chrome.commands

الوصف

البيان

المفاهيم وطريقة الاستخدام

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

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

suggested_key

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

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

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

اطّلِع على متطلبات مجموعات المفاتيح للحصول على تفاصيل إضافية.

description

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

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

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

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

مفاتيح الأبجدية

A … Z

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

0 … 9

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

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

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

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

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

‫Ctrl وAlt وShift وMacCtrl (نظام التشغيل macOS فقط) وCommand (نظام التشغيل macOS فقط) وSearch (نظام التشغيل ChromeOS فقط)

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

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

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

  • في العديد من لوحات مفاتيح نظام التشغيل macOS، يشير الرمز Alt إلى مفتاح Option.

  • على نظام التشغيل macOS، يمكن أيضًا استخدام Command أو MacCtrl بدلاً من Ctrl أو Alt (راجِع نقطة التعداد التالية).

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

  • يمكن أيضًا استخدام Command في الاختصار "mac" للإشارة صراحةً إلى مفتاح 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((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.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
)

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