browser.commands

شرح

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

مانیفست

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

"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)، Option (فقط macOS)، Command (فقط macOS)، Search (فقط ChromeOS)

الزامات ترکیب کلید

  • میان‌برهای فرمان افزونه باید شامل Ctrl یا Alt باشد.

    • اصلاح‌گرها نمی‌توانند در ترکیب با «کلیدهای رسانه» استفاده شوند.

    • در بسیاری‌از صفحه‌کلیدهای macOS،‏ Alt به کلید Option اشاره دارد.

    • در macOS، از Command یا MacCtrl نیز می‌توان به‌جای Ctrl استفاده کرد، و از کلید Option می‌توان به‌جای Alt استفاده کرد (مورد بعدی را ببینید).

  • در macOS،‏ Ctrl به‌طور خودکار به Command تبدیل می‌شود.

    • Command را می‌توان در میان‌بر "mac" نیز استفاده کرد تا به‌طور صریح به کلید 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:

browser.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 نسخه ۳۵، توسعه‌دهندگان افزونه می‌توانند به‌صورت اختیاری فرمانی را به‌عنوان «سراسری» علامت‌گذاری کنند. فرمان‌های سراسری وقتی 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:

browser.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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

درستی‌سنجی فرمان‌های ثبت‌شده

اگر افزونه‌ای تلاش کند میان‌بری را ثبت کند که قبلاً توسط افزونه دیگری استفاده شده است، میان‌بر افزونه دوم طبق انتظار ثبت نخواهد شد. با پیش‌بینی این احتمال و بررسی تداخل‌ها در زمان نصب، می‌توانید تجربه کاربر نهایی را بهبود ببخشید.

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

browser.commands.getAll(): Promise<Command[]>

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

بازگشتی‌ها

  • Promise<Command[]>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

    با فهرستی از فرمان‌های ثبت‌شده حل‌وفصل می‌شود.

رویدادها

onCommand

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • فرمان

      رشته

    • جهش

      tabs.Tab اختیاری