browser.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 وShift وMacCtrl (نظام التشغيل macOS فقط) وOption (نظام التشغيل macOS فقط) وCommand (نظام التشغيل macOS فقط) وSearch (نظام التشغيل ChromeOS فقط)

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

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

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

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

    • على نظام التشغيل macOS، يمكن أيضًا استخدام Command أو MacCtrl بدلاً من Ctrl، ويمكن استخدام مفتاح Option بدلاً من 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:

browser.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.

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

browser.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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

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

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

service-worker.js:

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

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

browser.commands.getAll(): Promise<Command[]>

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

المرتجعات

  • Promise<Command[]>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الفعاليات

onCommand

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

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

المعلمات

  • callback

    دالة

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

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

    • أمر

      سلسلة

    • ‏:

      tabs.Tab اختياري