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 فقط) و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 (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:

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,
)