chrome.action

الوصف

استخدِم واجهة برمجة التطبيقات chrome.action للتحكّم في رمز الإضافة في شريط أدوات Google Chrome.

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

مدى التوفّر

Chrome 88 والإصدارات الأحدث MV3 والإصدارات الأحدث

البيان

يجب الإعلان عن المفاتيح التالية في ملف البيان كي تتمكّن من استخدام واجهة برمجة التطبيقات هذه.

"action"

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

ملاحظة: لكل إضافة رمز في شريط أدوات Chrome، حتى إذا لم تتم إضافة مفتاح "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 وحدة بكسل مستقلة عن الجهاز (DIPs).

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

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

يمكنك أيضًا طلب 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}, () => { /* ... */ });

ملاحظة: تهدف action.setIcon() API إلى ضبط صورة ثابتة. لا تستخدم صورًا متحركة لرموزك.

بالنسبة إلى الإضافات المجمّعة (المثبَّتة من ملف .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().

ملاحظة: لن يتم إرسال الحدث action.onClicked إذا حدَّد إجراء الإضافة نافذة منبثقة لعرضها عند النقر على علامة التبويب الحالية.

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

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

يمكن أن تكون لإجراءات الإضافة حالات مختلفة لكل علامة تبويب. لضبط قيمة لعلامة تبويب فردية، استخدِم السمة 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-pattern.

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

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

// 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);
  });
});

الأنواع

OpenPopupOptions

Chrome 99 والإصدارات الأحدث

أماكن إقامة

• windowId

  الرقم اختياري

  رقم تعريف النافذة المنبثقة لفتح نافذة الإجراء المنبثقة. يتم ضبط الإعدادات التلقائية على النافذة النشطة حاليًا في حال عدم تحديدها.

TabDetails

أماكن إقامة

• tabId

  الرقم اختياري

  رقم تعريف علامة التبويب المطلوب الاستعلام عنها إذا لم يتم تحديد أي علامة تبويب، يتم عرض الحالة غير الخاصة بعلامة التبويب.

UserSettings

Chrome 91 والإصدارات الأحدث

مجموعة الإعدادات التي يحدِّدها المستخدم والمرتبطة بإجراء الإضافة.

أماكن إقامة

• isOnToolbar

  boolean

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

الطُرق

disable()

وعد

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

لإيقاف الإجراء في علامة تبويب

المَعلمات

• tabId

  الرقم اختياري

  رقم تعريف علامة التبويب التي تريد تعديل الإجراء لها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

enable()

وعد

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

لتفعيل الإجراء في علامة تبويب ويتم تفعيل الإجراءات تلقائيًا.

المَعلمات

• tabId

  الرقم اختياري

  رقم تعريف علامة التبويب التي تريد تعديل الإجراء لها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getBadgeBackgroundColor()

وعد

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

الحصول على لون خلفية الإجراء.

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: ColorArray)=>void

  • نتيجة

    ColorArray

المرتجعات

• Promise<browserAction.ColorArray>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getBadgeText()

وعد

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

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

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: string)=>void

  • نتيجة

    سلسلة

المرتجعات

• وعد<string>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getBadgeTextColor()

الوعد الإصدار 110 من Chrome أو الإصدارات الأحدث

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

الحصول على لون نص الإجراء.

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: ColorArray)=>void

  • نتيجة

    ColorArray

المرتجعات

• Promise<browserAction.ColorArray>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getPopup()

وعد

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

يؤدي إلى تعيين مستند html كنافذة منبثقة لهذا الإجراء.

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: string)=>void

  • نتيجة

    سلسلة

المرتجعات

• وعد<string>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getTitle()

وعد

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

يحصل على عنوان الإجراء.

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (result: string)=>void

  • نتيجة

    سلسلة

المرتجعات

• وعد<string>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getUserSettings()

البيانات المضمونة Chrome 91 والإصدارات الأحدث

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

تعرض الإعدادات التي حدّدها المستخدم والمتعلّقة بإجراء إحدى الإضافات.

المَعلمات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (userSettings: UserSettings)=>void

  • userSettings

    UserSettings

المرتجعات

• Promise<UserSettings>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

isEnabled()

الوعد الإصدار 110 من Chrome أو الإصدارات الأحدث

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

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

المَعلمات

• tabId

  الرقم اختياري

  رقم تعريف علامة التبويب التي تريد التحقّق من حالة تفعيلها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  (isEnabled: boolean)=>void

  • isEnabled

    boolean

    True إذا كان إجراء الإضافة مفعَّلاً.

المرتجعات

• Promise<boolean>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

openPopup()

الوعد الإصدار 118 من Chrome أو الإصدارات الأحدث مطلوب سياسة

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

يفتح النافذة المنبثقة للإضافة.

المَعلمات

• الخيارات

  OpenPopupOptions اختياري

  تحدِّد هذه السياسة خيارات فتح النافذة المنبثقة.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setBadgeBackgroundColor()

وعد

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

لضبط لون الخلفية للشارة.

المَعلمات

• التفاصيل

  كائن

  • اللون

    سلسلة|ColorArray

    مصفوفة من أربعة أعداد صحيحة في النطاق [0,255] تشكل لون RGBA للشارة. على سبيل المثال، اللون الأحمر المعتم هو [255, 0, 0, 255]. ويمكن أيضًا أن يكون سلسلة ذات قيمة CSS، ويكون اللون الأحمر غير الشفاف #FF0000 أو #F00.

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setBadgeText()

وعد

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

يضبط نص الشارة للإجراء. يتم عرض الشارة أعلى الرمز.

المَعلمات

• التفاصيل

  كائن

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

  • text

    سلسلة اختيارية

    يمكن تمرير أي عدد من الأحرف، ولكن يمكن إدخال أربعة أحرف فقط في الفراغ. في حال تمرير سلسلة فارغة ('')، سيتم محو نص الشارة. إذا تم تحديد tabId وكان text فارغًا، سيتم محو نص علامة التبويب المحدّدة وسيتم ضبطه تلقائيًا على نص الشارة العامة.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setBadgeTextColor()

الوعد الإصدار 110 من Chrome أو الإصدارات الأحدث

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

لضبط لون النص للشارة.

المَعلمات

• التفاصيل

  كائن

  • اللون

    سلسلة|ColorArray

    مصفوفة من أربعة أعداد صحيحة في النطاق [0,255] تشكل لون RGBA للشارة. على سبيل المثال، اللون الأحمر المعتم هو [255, 0, 0, 255]. ويمكن أيضًا أن يكون سلسلة ذات قيمة CSS، ويكون اللون الأحمر غير الشفاف #FF0000 أو #F00. في حال عدم ضبط هذه القيمة، سيتم تلقائيًا اختيار لون متباين مع لون خلفية الشارة ليكون النص مرئيًا. لن يتم ضبط الألوان التي تحتوي على قيم ألفا مكافئة لـ 0 وستعرض خطأ.

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setIcon()

وعد

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

لضبط الرمز للإجراء. يمكن تحديد الرمز إما كمسار إلى ملف صورة أو كبيانات البكسل من عنصر لوحة رسم، أو كقاموس لأي منهما. يجب تحديد خاصية path أو imageData.

المَعلمات

• التفاصيل

  كائن

  • imageData

    ImageData|Object اختياري

    إما كائن ImageData أو القاموس {size -> ImageData} الذي يمثل الرمز المراد تعيينه. إذا تم تحديد الرمز كقاموس، سيتم اختيار الصورة الفعلية التي سيتم استخدامها بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة الشاشة الواحدة يساوي scale، سيتم اختيار صورة بحجم scale * n، حيث يكون n هو حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّ 'details.imageData = foo' تساوي 'details.imageData = {'16': foo}'

  • المسار

    سلسلة|object اختيارية

    إما مسار صورة نسبي أو قاموس {size -> رباعي صورة نسبية} يشير إلى الرمز المراد تعيينه. إذا تم تحديد الرمز كقاموس، سيتم اختيار الصورة الفعلية التي سيتم استخدامها بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة الشاشة الواحدة يساوي scale، سيتم اختيار صورة بحجم scale * n، حيث يكون n هو حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. تجدر الإشارة إلى أن 'details.path = foo' تساوي 'details.path = {'16': foo}'

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  Chrome 96 والإصدارات الأحدث

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setPopup()

وعد

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

لضبط مستند HTML ليتم فتحه كنافذة منبثقة عندما ينقر المستخدم على رمز الإجراء.

المَعلمات

• التفاصيل

  كائن

  • نافذة منبثقة

    سلسلة

    المسار النسبي لملف HTML المطلوب عرضه في نافذة منبثقة. في حال ضبطها على السلسلة الفارغة ('')، لن تظهر أي نافذة منبثقة.

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

setTitle()

وعد

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

تحدّد عنوان الإجراء. سيظهر ذلك في التلميح.

المَعلمات

• التفاصيل

  كائن

  • tabId

    الرقم اختياري

    لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.

  • title

    سلسلة

    السلسلة التي يجب أن يعرضها الإجراء عند تمرير الماوس فوقها.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

فعاليات

onClicked

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

يتم تنشيطها عند النقر على رمز إجراء. ولن يتمّ تنشيط هذا الحدث إذا كان الإجراء يحتوي على نافذة منبثقة.

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (tab: tabs.Tab)=>void

  • ‏

    tabs.Tab