refresh date: 2026-09-25 robots: noindex
شرح
از commands API برای افزودن میان‌برهای صفحه‌کلید استفاده کنید که کنش‌ها را در افزونه شما راه‌اندازی می‌کنند، برای مثال، کنشی برای باز کردن کنش مرورگر یا ارسال فرمان به افزونه.
مانیفست
کاربرد
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، هنگام تعریف میان‌بر
"mac"،Ctrlرا باMacCtrlجایگزین کنید.استفاده از
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 در جاوا اسکریپت بالاپر گوش دهید.
حوزه
به‌طور پیش‌فرض، فرمان‌ها به مرورگر 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((reason) => {
if (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
مشخصات
-
description
رشته اختیاری
شرح «فرمان افزونه»
-
نام
رشته اختیاری
نام «فرمان افزونه»
-
میان‌بر
رشته اختیاری
میان‌بر فعال برای این فرمان، یا اگر فعال نباشد، خالی است.
روش‌ها
getAll()
chrome.commands.getAll(
callback?: function,
): Promise<Command[]>
همه فرمان‌های افزونه ثبت‌شده برای این افزونه و میان‌بر آن‌ها (درصورت فعال بودن) را برمی‌گرداند. قبل‌از Chrome 110، این فرمان _execute_action را برنمی‌گرداند.
پارامترها
بازگشتی‌ها
-
Promise<Command[]>
Chrome نسخه ۹۶ به بالابا فهرستی از فرمان‌های ثبت‌شده حل‌وفصل می‌شود.
Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.