chrome.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 استفاده کرد.

  • برای استفاده از کلید کنترل در macOS، هنگام تعریف میانبر "mac" به جای Ctrl از MacCtrl استفاده کنید.

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

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

• Search یک اصلاح‌کننده اختیاری است که منحصراً برای ChromeOS ارائه شده است.

• برخی از میانبرهای سیستم عامل و کروم (مثلاً مدیریت پنجره) همیشه نسبت به میانبرهای دستورات افزونه اولویت دارند و قابل لغو نیستند.

مدیریت رویدادهای فرمان

مانیفست.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 یک هندلر را به هر یک از دستورات تعریف شده در مانیفست متصل کنید. برای مثال:

سرویس-ورکر.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

دستورات عملی

دستورات _execute_action (Manifest V3)، _execute_browser_action (Manifest V2) و _execute_page_action (Manifest V2) به ترتیب برای اجرای action، browser action یا page action شما رزرو شده‌اند. این دستورات مانند دستورات استاندارد، رویدادهای command.onCommand را ارسال نمی‌کنند.

اگر نیاز دارید که بر اساس باز شدن پاپ‌آپ، اقدامی انجام دهید، می‌توانید رویداد DOMContentLoaded را در داخل جاوا اسکریپت پاپ‌آپ خود فعال کنید.

دامنه

به طور پیش‌فرض، دستورات در مرورگر کروم محدود می‌شوند. این بدان معناست که وقتی مرورگر فوکوس ندارد، میانبرهای دستورات غیرفعال هستند. از کروم ۳۵ به بعد، توسعه‌دهندگان افزونه‌ها می‌توانند به صورت اختیاری یک دستور را به عنوان "جهانی" علامت‌گذاری کنند. دستورات سراسری در حالی که کروم فوکوس ندارد نیز کار می‌کنند.

پیشنهادهای میانبر صفحه‌کلید برای دستورات سراسری به Ctrl+Shift+[0..9] محدود می‌شود. این یک اقدام حفاظتی برای به حداقل رساندن خطر نادیده گرفتن میانبرها در برنامه‌های دیگر است، زیرا اگر، برای مثال، Alt+P به عنوان سراسری مجاز باشد، ممکن است میانبر صفحه‌کلید برای باز کردن کادر محاوره‌ای چاپ در برنامه‌های دیگر کار نکند.

کاربران نهایی می‌توانند با استفاده از رابط کاربری موجود در chrome://extensions/shortcuts دستورات سراسری را به ترکیب کلیدهای دلخواه خود تغییر دهند.

مثال:

مانیفست.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

مثال‌ها

مثال‌های زیر، عملکرد اصلی API دستورات را انعطاف‌پذیرتر می‌کنند.

دستور پایه

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

مانیفست.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"
    }
  }
}

سرویس-ورکر.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

دستور عمل

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

مانیفست.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"
      }
    }
  }
}

سرویس-ورکر.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`);
});

تأیید دستورات ثبت‌شده

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

سرویس-ورکر.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(): Promise<Command[]>

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