chrome.action

الوصف

مدى التوفّر

البيان

لاستخدام واجهة برمجة التطبيقات chrome.action API، حدِّد "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 العنصر، أو خارج الشاشة في حال ضبطه من مشغّل خدمات الإضافات Candy API.

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) إلى إضافتك. لا يؤثر ذلك في وجود الإجراء في شريط الأدوات.

أمثلة

توضّح الأمثلة التالية بعض الطرق الشائعة لاستخدام الإجراءات في الإضافات. لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال 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,
  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,
)

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