chrome.commands

توضیحات

از دستورات API برای افزودن میانبرهای صفحه کلیدی استفاده کنید که اقداماتی را در برنامه افزودنی شما فعال می کند، به عنوان مثال، اقدامی برای باز کردن عملکرد مرورگر یا ارسال فرمان به برنامه افزودنی.

آشکار

برای استفاده از این API باید کلیدهای زیر در مانیفست اعلان شوند.

"commands"

مفاهیم و کاربرد

Commands API به توسعه دهندگان برنامه افزودنی اجازه می دهد تا دستورات خاصی را تعریف کرده و آنها را به یک کلید ترکیبی پیش فرض متصل کنند. هر دستوری که یک برنامه افزودنی می پذیرد باید به عنوان ویژگی های شیء "commands" در مانیفست برنامه افزودنی اعلان شود.

کلید ویژگی به عنوان نام فرمان استفاده می شود. اشیاء فرمان می توانند دو ویژگی داشته باشند.

suggested_key

یک ویژگی اختیاری که میانبرهای پیش فرض صفحه کلید را برای دستور اعلام می کند. در صورت حذف، دستور unbound خواهد شد. این ویژگی می تواند یک رشته یا یک مقدار شی را بگیرد.

  • یک مقدار رشته، میانبر پیش فرض صفحه کلید را مشخص می کند که باید در همه پلتفرم ها استفاده شود.

  • یک مقدار شیء به توسعه دهنده برنامه افزودنی اجازه می دهد تا میانبر صفحه کلید را برای هر پلتفرم سفارشی کند. هنگام ارائه میانبرهای مخصوص پلتفرم، ویژگی های آبجکت معتبر default ، chromeos ، linux ، mac و windows است.

برای جزئیات بیشتر به الزامات ترکیب کلید مراجعه کنید.

description

رشته ای که برای ارائه توضیحات کوتاهی از هدف دستور به کاربر استفاده می شود. این رشته در رابط کاربری مدیریت میانبر صفحه کلید افزونه ظاهر می شود. توضیحات برای دستورات استاندارد مورد نیاز است، اما برای دستورات Action نادیده گرفته می شود.

یک برنامه افزودنی می تواند دستورات زیادی داشته باشد، اما ممکن است حداکثر چهار میانبر صفحه کلید پیشنهادی را مشخص کند. کاربر می تواند به صورت دستی میانبرهای بیشتری را از گفتگوی 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، هنگام تعریف میانبر "mac" Ctrl با MacCtrl جایگزین کنید.

    • استفاده از MacCtrl در ترکیب برای پلتفرم دیگر باعث خطای اعتبارسنجی می شود و از نصب افزونه جلوگیری می کند.

  • Shift یک اصلاح کننده اختیاری در همه پلتفرم ها است.

  • Search یک اصلاح کننده اختیاری است که منحصر به سیستم عامل Chrome است.

  • برخی از میانبرهای سیستم عامل و 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 35، توسعه دهندگان برنامه افزودنی می توانند به صورت اختیاری یک فرمان را به عنوان "جهانی" علامت گذاری کنند. زمانی که کروم فوکوس ندارد ، دستورات جهانی نیز کار می کنند.

پیشنهادات میانبر صفحه کلید برای دستورات جهانی به 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.
    }
  });
}

انواع

Command

خواص

  • توضیحات

    رشته اختیاری

    توضیحات دستور Extension

  • نام

    رشته اختیاری

    نام Extension Command

  • میانبر

    رشته اختیاری

    میانبر برای این دستور فعال است یا اگر فعال نباشد خالی است.

روش ها

getAll()

قول بده
chrome.commands.getAll(
  callback?: function,
)

تمام دستورات برنامه افزودنی ثبت شده را برای این برنامه افزودنی و میانبر آنها (در صورت فعال بودن) برمی گرداند. قبل از Chrome 110، این دستور _execute_action برنمی‌گرداند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (commands: Command[]) => void

برمی گرداند

  • Promise< فرمان []>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onCommand

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

هنگامی که یک فرمان ثبت شده با استفاده از میانبر صفحه کلید فعال می شود، فعال می شود.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (command: string, tab?: tabs.Tab) => void

    • فرمان

      رشته

    • زبانه

      Tabs.Tab اختیاری است