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 تريده، وسيتم تغيير حجمها تلقائيًا ليلائم محتواها. يجب أن يتراوح حجم النافذة المنبثقة بين 25×25 و800×600 بكسل.

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

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

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

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

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

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

وفي حال عدم تضمين السمة tabId، يتم التعامل مع الإعداد كإعداد عام. وتحظى الإعدادات الخاصة بعلامة التبويب بالأولوية على الإعدادات العامة.

حالة التفعيل

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

أمثلة

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

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

من الشائع أن تعرض الإضافة نافذة منبثقة عندما ينقر المستخدم على إجراء الإضافة. لتنفيذ ذلك في إضافتك، يُرجى الإفصاح عن النافذة المنبثقة في 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,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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