chrome.commands

الوصف

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

البيان

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

"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 فقط)

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

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

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

النطاق

يتم ضبط الأوامر تلقائيًا على متصفّح Chrome. وهذا يعني أنه عندما لا يكون التركيز في المتصفح، تكون اختصارات الأوامر غير نشطة. وبدءًا من Chrome 35، يمكن لمطوّري الإضافات وضع علامة "عالمي" على أحد الأوامر اختياريًا. تعمل الأوامر العامة أيضًا عندما لا يتم التركيز على 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((details) => {
  if (details.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

أماكن إقامة

  • الوصف

    سلسلة اختيارية

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

  • اسم

    سلسلة اختيارية

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

  • اختصار

    سلسلة اختيارية

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

الطُرق

getAll()

وعد بذلك 
chrome.commands.getAll(
  callback?: function,
)

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

المعلمات

  • رد الاتصال

    الدالة اختيارية

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

    (commands: Command[]) => void

المرتجعات

  • الوعد<Command[]>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال للتوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. ويحلّ الوعد بالنوع نفسه الذي يتم إرساله إلى معاودة الاتصال.

فعاليات

onCommand

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

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

المعلمات

  • رد الاتصال

    الوظيفة

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

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

    • Command

      سلسلة

    • ‏

      tabs.Tab اختيارية