chrome.action

الوصف

مدى التوفّر

البيان

لاستخدام واجهة برمجة التطبيقات chrome.action، حدِّد "manifest_version" بالقيمة 3 وأدرِج المفتاح "action" في ملف البيان.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

المفتاح "action" (مع العناصر التابعة له) اختياري. وعندما لا يتم تضمينها، تظل الإضافة معروضة في شريط الأدوات لتوفير إمكانية الوصول إلى قائمة الإضافة. لهذا السبب، ننصحك دائمًا بتضمين المفتاحين "action" و"default_icon" على الأقل.

المفاهيم والاستخدام

أجزاء واجهة المستخدم

رمز

الرمز هو الصورة الرئيسية على شريط أدوات الإضافة، ويتم ضبطه باستخدام المفتاح "default_icon" في المفتاح "action" في ملف البيان. يجب أن يكون عرض الرموز وارتفاعها 16 بكسل مستقل عن الجهاز (DIP).

المفتاح "default_icon" هو قاموس للأحجام ومسارات الصور. يستخدم Chrome هذه الرموز لاختيار مقياس الصورة المطلوب استخدامه. في حال عدم العثور على نتيجة مطابقة تمامًا، يختار Chrome أقرب نتيجة متاحة ويغيّر حجمها لتناسب الصورة، ما قد يؤثر في جودة الصورة.

وبما أنّ الأجهزة التي تتضمّن عوامل قياس أقل شيوعًا، مثل 1.5x أو 1.2x، أصبحت أكثر شيوعًا، ننصحك بتوفير أحجام متعددة للرموز. ويضمن ذلك أيضًا توافق الإضافة مع أي تغييرات مستقبلية محتملة في حجم عرض الرموز. ومع ذلك، إذا كنت ستوفّر حجمًا واحدًا فقط، يمكن أيضًا ضبط المفتاح "default_icon" على سلسلة تتضمّن مسارًا إلى رمز واحد بدلاً من قاموس.

يمكنك أيضًا طلب action.setIcon() لضبط رمز الإضافة آليًا من خلال تحديد مسار صورة مختلف أو توفير رمز تم إنشاؤه ديناميكيًا باستخدام عنصر لوحة الرسم HTML، أو، في حال الضبط من عامل خدمة إضافة، باستخدام واجهة برمجة التطبيقات لوحة الرسم خارج الشاشة.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

بالنسبة إلى الإضافات المعبّأة (التي يتم تثبيتها من ملف crx.)، يمكن أن تكون الصور بأغلب التنسيقات التي يمكن لمحرك العرض Blink عرضها، بما في ذلك PNG وJPEG وBMP وICO وغيرها. تنسيق SVG غير متوافق. يجب أن تستخدم الإضافات غير المضغوطة صور PNG.

تلميح (عنوان)

يظهر التلميح أو العنوان عندما يضع المستخدم مؤشر الماوس فوق رمز الإضافة في شريط الأدوات. ويتم تضمينها أيضًا في النص المتاح الذي تقرأه برامج قراءة الشاشة عندما يتم التركيز على الزر.

يتم ضبط تلميح الأدوات التلقائي باستخدام الحقل "default_title" لمفتاح "action" في manifest.json. يمكنك أيضًا ضبطه آليًا من خلال استدعاء action.setTitle().

الشارة

يمكن أن تعرض الإجراءات اختياريًا "شارة"، وهي عبارة عن نص صغير مكوّن من طبقات فوق الرمز. يتيح لك ذلك تعديل الإجراء لعرض قدر صغير من المعلومات حول حالة الإضافة، مثل عدّاد. تحتوي الشارة على مكوّن نصي ولون خلفية. بما أنّ المساحة محدودة، ننصح بأن يتألف نص الشارة من أربعة أحرف أو أقل.

لإنشاء شارة، اضبطها برمجيًا من خلال استدعاء action.setBadgeBackgroundColor() وaction.setBadgeText(). لا يتوفّر إعداد تلقائي للشارة في البيان. يمكن أن تكون قيم ألوان الشارات مصفوفة من أربعة أعداد صحيحة تتراوح بين 0 و255 تشكّل لون RGBA للشارة، أو سلسلة تتضمّن قيمة لون CSS.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

نافذة منبثقة

يظهر نافذة منبثقة خاصة بأحد الإجراءات عندما ينقر المستخدم على زر الإجراء الخاص بالإضافة في شريط الأدوات. يمكن أن يحتوي العنصر المنبثق على أي محتوى HTML تريده، وسيتم تغيير حجمه تلقائيًا ليتناسب مع محتواه. يجب أن يتراوح حجم النافذة المنبثقة بين 25x25 و800x600 بكسل.

يتم ضبط النافذة المنبثقة في البداية من خلال السمة "default_popup" في المفتاح "action" في ملف manifest.json. في حال توفّرها، يجب أن تشير هذه السمة إلى مسار نسبي ضمن دليل الإضافة. يمكن أيضًا تعديلها بشكل ديناميكي للإشارة إلى مسار نسبي مختلف باستخدام الطريقة action.setPopup().

حالات الاستخدام

الحالة لكل علامة تبويب

يمكن أن تتضمّن إجراءات الإضافة حالات مختلفة لكل علامة تبويب. لضبط قيمة لعلامة تبويب فردية، استخدِم السمة tabId في طرق إعداد واجهة برمجة التطبيقات action. على سبيل المثال، لضبط نص الشارة لعلامة تبويب معيّنة، يمكنك تنفيذ ما يلي:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

في حال عدم تضمين السمة tabId، يتم التعامل مع الإعداد على أنّه إعداد عام. تُعطى إعدادات علامة التبويب الأولوية على الإعدادات العامة.

الحالة "مفعَّل"

تكون إجراءات شريط الأدوات مفعَّلة (يمكن النقر عليها) تلقائيًا في كل علامة تبويب. يمكنك تغيير هذه القيمة التلقائية من خلال ضبط السمة default_state في المفتاح action في ملف البيان. إذا تم ضبط قيمة default_state على "disabled"، سيتم إيقاف الإجراء تلقائيًا ويجب تفعيله برمجيًا ليكون قابلاً للنقر. إذا تم ضبط default_state على "enabled" (الإعداد التلقائي)، سيتم تفعيل الإجراء ويمكن النقر عليه تلقائيًا.

يمكنك التحكّم في الحالة آليًا باستخدام الطريقتَين action.enable() وaction.disable(). يؤثر ذلك فقط في ما إذا كان سيتم إرسال النافذة المنبثقة (إن وُجدت) أو حدث action.onClicked إلى الإضافة، ولا يؤثر في ظهور الإجراء في شريط الأدوات.

أمثلة

توضّح الأمثلة التالية بعض الطرق الشائعة لاستخدام الإجراءات في الإضافات. لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال Action API من مستودع chrome-extension-samples.

عرض نافذة منبثقة

من الشائع أن تعرض إضافة نافذة منبثقة عندما ينقر المستخدم على إجراء الإضافة. لتنفيذ ذلك في إضافتك، عليك تعريف النافذة المنبثقة في manifest.json وتحديد المحتوى الذي سيعرضه Chrome في النافذة المنبثقة.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

إدخال نص برمجي للمحتوى عند النقر

من الأنماط الشائعة للإضافات عرض ميزتها الأساسية باستخدام إجراء الإضافة. يوضّح المثال التالي هذا النمط. عندما ينقر المستخدم على الإجراء، تُدرِج الإضافة نصًا برمجيًا للمحتوى في الصفحة الحالية. بعد ذلك، يعرض النص البرمجي للمحتوى تنبيهًا للتحقّق من أنّ كل شيء يعمل على النحو المتوقّع.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

محاكاة الإجراءات باستخدام declarativeContent

يوضّح هذا المثال كيف يمكن لمنطق الخلفية لإحدى الإضافات (أ) إيقاف إجراء تلقائيًا و (ب) استخدام declarativeContent لتفعيل الإجراء على مواقع إلكترونية معيّنة.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

chrome.action.onClicked.addListener(
  callback: function,
)

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)