chrome.action

الوصف

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

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

مدى التوفّر

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

البيان

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

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

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
  () => { /* ... */ },
);

تظهر نافذة منبثقة للإجراء عندما ينقر المستخدم على زر الإجراء الخاص باإضافة في toolbar. ويمكن أن تحتوي النافذة المنبثقة على أي محتوى 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-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

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

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

أماكن إقامة

  • 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

المرتجعات

  • Promise&lt;browserAction.ColorArray&gt;

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

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

isEnabled()

التوقعات Chrome 110 والأحدث 
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 من Chrome والإصدار 126، لا يتوفّر هذا الخيار إلا للإضافات المثبَّتة من خلال السياسة.

المعلمات

  • الخيارات

    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

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

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

    • نص

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

      يمكن تمرير أي عدد من الأحرف، ولكن لا يمكن تضمين سوى أربعة أحرف فقط في المساحة. في حال إدخال سلسلة فارغة ('')، يتم محو نص الشارة. إذا تم تحديد 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 -> relative image path} يشير إلى الرمز المطلوب ضبطه. إذا تم تحديد الرمز كقاموس، يتم اختيار الصورة الفعلية المراد استخدامها بناءً على كثافة وحدات البكسل للشاشة. إذا كان عدد وحدات البكسل في الصورة التي تتناسب مع وحدة مساحة شاشة واحدة يساوي 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

onUserSettingsChanged

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

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

المعلمات