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

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

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