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

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(): Promise<Command[]>

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