chrome.commands

refresh date: 2026-09-25 robots: noindex

الوصف

البيان

الاستخدام

تتيح واجهة برمجة التطبيقات Commands API لمطوّري الإضافات تحديد أوامر معيّنة وربطها بمجموعة مفاتيح تلقائية. يجب الإفصاح عن كل أمر تقبله الإضافة كسمات للعنصر "commands" في بيان الإضافة.

يتم استخدام مفتاح السمة كاسم للأمر. يمكن أن تتضمّن عناصر الأوامر سمتَين.

suggested_key

سمة اختيارية تحدّد اختصارات لوحة المفاتيح التلقائية للأمر. في حال عدم توفّره، سيتم إلغاء ربط الأمر. يمكن أن تقبل هذه السمة قيمة سلسلة أو قيمة كائن.

• تحدّد قيمة السلسلة اختصار لوحة المفاتيح التلقائي الذي يجب استخدامه على جميع المنصات.

• تسمح قيمة العنصر لمطوّر الإضافة بتخصيص اختصار لوحة المفاتيح لكل نظام أساسي. عند تقديم اختصارات خاصة بمنصة معيّنة، تكون سمات العنصر الصالحة هي default وchromeos وlinux وmac وwindows.

يمكنك الاطّلاع على متطلبات تركيبة المفاتيح لمعرفة المزيد من التفاصيل.

description

سلسلة تُستخدَم لتزويد المستخدم بوصف موجز لغرض الأمر. تظهر هذه السلسلة في واجهة مستخدم إدارة اختصارات لوحة المفاتيح الخاصة بالإضافات. الوصف مطلوب للأوامر العادية، ولكن يتم تجاهله لأوامر الإجراءات.

يمكن أن تتضمّن الإضافة العديد من الأوامر، ولكن يمكنها تحديد أربعة اختصارات لوحة مفاتيح مقترَحة كحدّ أقصى. يمكن للمستخدم إضافة المزيد من الاختصارات يدويًا من مربّع الحوار chrome://extensions/shortcuts.

المفاتيح المتوافقة

يمكن استخدام المفاتيح التالية كاختصارات للأوامر. تكون تعريفات المفاتيح حسّاسة لحالة الأحرف. ستؤدي محاولة تحميل إضافة باستخدام مفتاح مكتوب بشكل غير صحيح إلى حدوث خطأ في تحليل ملف البيان أثناء عملية التثبيت.

مفاتيح الإصدار الأوّلي

‫

A … Z

المفاتيح الرقمية

‫

0 … 9

سلاسل المفاتيح العادية

عامة–Comma وPeriod وHome وEnd وPageUp وPageDown وSpace وInsert وDelete

مفاتيح الأسهم: Up وDown وLeft وRight

مفاتيح الوسائط: MediaNextTrack وMediaPlayPause وMediaPrevTrack وMediaStop

سلاسل مفاتيح التعديل

‫Ctrl وAlt (Option على أجهزة macOS) وShift وMacCtrl (على أجهزة macOS فقط) وCommand (على أجهزة macOS فقط) وSearch (على أجهزة ChromeOS فقط)

متطلبات تركيبة المفاتيح

• يجب أن تتضمّن اختصارات أوامر الإضافة Ctrl أو Alt.

  • لا يمكن استخدام المعدِّلات مع مفاتيح الوسائط.

• على macOS، يتم تحويل Ctrl تلقائيًا إلى Command.

  • لاستخدام مفتاح Control على أجهزة macOS، استبدِل Ctrl بـ MacCtrl عند تحديد الاختصار "mac".

  • سيؤدي استخدام MacCtrl في المجموعة لمنصة أخرى إلى حدوث خطأ في التحقّق من الصحة وسيمنع تثبيت الإضافة.

• Shift هو معدِّل اختياري على جميع المنصات.

• ‫Search هو معدِّل اختياري حصري لنظام التشغيل ChromeOS.

• تكون بعض اختصارات نظام التشغيل وChrome (مثل إدارة النوافذ) دائمًا لها الأولوية على اختصارات أوامر الإضافات ولا يمكن إلغاؤها.

التعامل مع أحداث الأوامر

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

في عامل الخدمة، يمكنك ربط معالج بكل الأوامر المحدّدة في البيان باستخدام onCommand.addListener. على سبيل المثال:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

أوامر الإجراءات

الأوامر _execute_action (الإصدار 3 من Manifest) و_execute_browser_action (الإصدار 2 من Manifest) و_execute_page_action (الإصدار 2 من Manifest) محجوزة لتنفيذ إجراءك أو إجراء المتصفّح أو إجراء الصفحة على التوالي. لا تُرسِل هذه الأوامر أحداث command.onCommand مثل الأوامر العادية.

إذا كنت بحاجة إلى اتّخاذ إجراء استنادًا إلى فتح النافذة المنبثقة، ننصحك بالاستماع إلى حدث DOMContentLoaded داخل JavaScript الخاص بالنافذة المنبثقة.

النطاق

تكون نطاقات الأوامر تلقائيًا هي متصفّح Chrome. هذا يعني أنّه عندما لا يكون المتصفّح في المقدّمة، تكون اختصارات الأوامر غير نشطة. اعتبارًا من الإصدار 35 من Chrome، يمكن لمطوّري الإضافات وضع علامة "عام" على أحد الأوامر بشكل اختياري. تعمل الأوامر العامة أيضًا عندما لا يكون Chrome في المقدّمة.

تقتصر اقتراحات اختصارات لوحة المفاتيح للأوامر العامة على Ctrl+Shift+[0..9]. هذا إجراء وقائي للحدّ من خطر إلغاء الاختصارات في التطبيقات الأخرى، لأنّه إذا تم السماح باستخدام Alt+P كاختصار عام، قد لا يعمل اختصار لوحة المفاتيح لفتح مربّع حوار الطباعة في التطبيقات الأخرى.

يمكن للمستخدمين النهائيين إعادة ربط الأوامر العامة بمجموعة المفاتيح المفضّلة لديهم باستخدام واجهة المستخدم المعروضة في chrome://extensions/shortcuts.

مثال:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

أمثلة

توضّح الأمثلة التالية الوظائف الأساسية لواجهة برمجة التطبيقات Commands API.

الطلب الأساسي

تسمح الأوامر للإضافات بربط منطق باختصارات لوحة المفاتيح التي يمكن للمستخدم استدعاؤها. في أبسط أشكاله، لا يتطلّب الأمر سوى تعريف الأمر في بيان الإضافة وتسجيل معالج الأحداث، كما هو موضّح في المثال التالي.

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

أمر الإجراء

كما هو موضّح في قسم الاستخدام، يمكنك أيضًا ربط أمر بإجراء أحد الإضافات. يُدرِج المثال التالي نصًا برمجيًا للمحتوى يعرض تنبيهًا على الصفحة الحالية عندما ينقر المستخدم على إجراء الإضافة أو يشغّل اختصار لوحة المفاتيح.

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

التحقّق من الأوامر المسجّلة

إذا حاولت إضافة تسجيل اختصار مستخدَم من قِبل إضافة أخرى، لن يتم تسجيل اختصار الإضافة الثانية على النحو المتوقّع. يمكنك تقديم تجربة أكثر فعالية للمستخدم النهائي من خلال توقّع هذه الإمكانية والتحقّق من حدوث تعارضات أثناء عملية التثبيت.

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (reason === chrome.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  chrome.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

chrome.commands.onCommand.addListener(
  callback: function,
)