الوصف
استخدِم واجهة برمجة تطبيقات الأوامر لإضافة اختصارات لوحة المفاتيح التي تؤدي إلى تنفيذ الإجراءات في إضافتك، مثل إجراء لفتح إجراء المتصفّح أو إرسال أمر إلى الإضافة.
البيان
يجب الإعلان عن المفاتيح التالية في ملف البيان كي تتمكّن من استخدام واجهة برمجة التطبيقات هذه.
"commands"المفاهيم والاستخدام
تسمح واجهة برمجة التطبيقات Commands لمطوّري الإضافات بتحديد أوامر محدّدة وربطها بمجموعة مفاتيح تلقائية. يجب الإشارة إلى كل أمر تقبله الإضافة كسمات لكائن "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-work.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
أوامر الإجراءات
إنّ الأوامر _execute_action (الإصدار 3 من ملف البيان) و_execute_browser_action (الإصدار 2 من ملف البيان)
و_execute_page_action (الإصدار 2 من ملف البيان) محجوزة لإجراء تشغيل الإجراء أو إجراء المتصفّح أو إجراء الصفحة على التوالي. ولا توجّه هذه الأوامر أحداث
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-work.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-work.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-work.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.
}
});
}
الأنواع
Command
أماكن إقامة
-
الوصف
سلسلة اختيارية
وصف طلب الإضافة
-
اسم
سلسلة اختيارية
اسم أمر الإضافة
-
اختصار
سلسلة اختيارية
الاختصار نشط لهذا الأمر، أو فارغ إذا لم يكن نشطًا.
الطُرق
getAll()
chrome.commands.getAll(
callback?: function,
)
عرض جميع أوامر الإضافات المسجَّلة لهذه الإضافة واختصارها (إذا كان نشطًا). قبل استخدام Chrome 110، لم يكن هذا الأمر يؤدي إلى عرض الخطأ _execute_action.
المَعلمات
المرتجعات
-
الوعد<Command[]>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.