chrome.commands

refresh date: 2026-09-25 robots: noindex

الوصف

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

البيان

يجب الإعلان عن المفاتيح التالية في ملف البيان لاستخدام واجهة برمجة التطبيقات هذه.

"commands"

الاستخدام

تتيح واجهة برمجة التطبيقات 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 فقط)

ملاحظة: تمت إزالة Tab من قائمة المفاتيح المتوافقة في الإصدار 33 من Chrome لأسباب تتعلق بتسهيل الاستخدام.

متطلبات مجموعة المفاتيح

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

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

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

  • لاستخدام مفتاح Control على نظام التشغيل macOS، استبدِل Ctrl بـ MacCtrl عند تحديد اختصار "mac".

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

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

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

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

ملاحظة:لا يُسمح بمجموعات المفاتيح التي تتضمّن Ctrl+Alt لتجنُّب التعارض مع مفتاح AltGr.

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

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 (Manifest V3) و_execute_browser_action (Manifest V2) و_execute_page_action (Manifest V2) لتشغيل الإجراء أو إجراء المتصفّح أو إجراء الصفحة على التوالي. لا ترسل هذه الأوامر أحداث command.onCommand مثل الأوامر العادية.

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

النطاق

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

ملاحظة: لا يتوافق نظام التشغيل ChromeOS مع الأوامر العامة.

يقتصر عدد اقتراحات اختصارات لوحة المفاتيح للأوامر العامة على 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`);
});

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

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

ملاحظة: لن يظهر _execute_action في قائمة الأوامر التي يعرضها commands.getAll().

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.
    }
  });
}

الأنواع

Command

الخصائص

• الوصف

  string اختياري

  وصف أمر الإضافة

• الاسم

  string اختياري

  اسم أمر الإضافة

• اختصار

  string اختياري

  اختصار لوحة المفاتيح النشط لهذا الأمر، أو فارغ إذا لم يكن نشطًا.

الطُرق

getAll()

Promise

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

تعرض هذه الطريقة جميع أوامر الإضافة المسجّلة لهذه الإضافة واختصاراتها (إذا كانت نشطة). قبل الإصدار 110 من Chrome، لم يكن هذا الأمر يعرض _execute_action.

المعلمات

• callback

  function اختياري

  تظهر المَعلمة callback على النحو التالي:

  (commands: Command[]) => void

  • الأوامر

    Command[]

المرتجعات

• Promise<Command[]>

  الإصدار 96 من Chrome أو الإصدارات الأحدث

  يتم حلّها باستخدام قائمة بالأوامر المسجّلة.

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onCommand

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

يتم تفعيل هذا الحدث عند تفعيل أمر مسجَّل باستخدام اختصار لوحة مفاتيح.

المعلمات

• callback

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (command: string, tab?: tabs.Tab) => void

  • أمر

    سلسلة

  • ‏:

    tabs.Tab اختياري