chrome.action

الوصف

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

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

مدى التوفّر

الإصدار 88 من Chrome والإصدارات الأحدث الإصدار 3 من MV والإصدارات الأحدث

البيان

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

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

الأنواع

OpenPopupOptions

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

أماكن إقامة

  • windowId

    رقم اختياري

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

TabDetails

أماكن إقامة

  • tabId

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

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

UserSettings

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

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

أماكن إقامة

  • isOnToolbar

    منطقي

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

UserSettingsChange

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

أماكن إقامة

  • isOnToolbar

    قيمة منطقية اختيارية

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

الطُرق

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

المرتجعات

  • Promise&lt;browserAction.ColorArray&gt;

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

getBadgeText()

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

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

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

getBadgeTextColor()

الوعد Chrome 110 والإصدارات الأحدث 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

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

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (result: ColorArray) => void

المرتجعات

  • تكون الوعود متاحة في الإصدار 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

المرتجعات

  • Promise&lt;UserSettings&gt;

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

isEnabled()

وعود الإصدار 110 من Chrome والإصدارات الأحدث 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

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

المعلمات

  • tabId

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

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (isEnabled: boolean) => void

    • isEnabled

      منطقي

      صحيح إذا كان إجراء الإضافة مفعّلاً.

المرتجعات

  • Promise&lt;boolean&gt;

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

openPopup()

الوعد Chrome 127 والإصدارات الأحدث 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

فتح النافذة المنبثقة للإضافة ولا تتوفّر هذه الميزة إلا للإضافات المثبَّتة من خلال السياسات بين الإصدار 118 و126 من Chrome.

المعلمات

  • الخيارات

    ‫OpenPopupOptions اختيارية

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

setBadgeBackgroundColor()

الوعد 
chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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

المعلمات

  • التفاصيل

    كائن

    • اللون

      string | 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

      رقم اختياري

      حصر التغيير عند اختيار علامة تبويب معيّنة تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

    • نص

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

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

setBadgeTextColor()

الوعد Chrome 110 والإصدارات الأحدث 
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 | الكائن اختياري

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

    • المسار

      سلسلة | عنصر اختياري

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

    • tabId

      رقم اختياري

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

    تكون الوعود متاحة في الإصدار 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>

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

الفعاليات

onClicked

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

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

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (tab: tabs.Tab) => void

onUserSettingsChanged

الإصدار 130 من Chrome أو الإصدارات الأحدث 
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

يتم الإطلاق عند تحديد المستخدم لإعدادات ذات صلة بتغيير إجراء الإضافة.

المعلمات