chrome.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 ( Option در macOS)، Shift ، MacCtrl (فقط macOS)، Command (فقط macOS)، Search (فقط ChromeOS)

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

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

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

• در macOS Ctrl به طور خودکار به 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`);
});

دستور عمل

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

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(
  callback?: function,
)

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