chrome.action

الوصف

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

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

مدى التوفّر

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

البيان

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

"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 العنصر، أو خارج الشاشة في حال ضبطه من مشغّل خدمات الإضافات 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) إلى إضافتك. لا يؤثر ذلك في وجود الإجراء في شريط الأدوات.

أمثلة

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

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

أماكن إقامة

  • windowId

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

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

TabDetails

أماكن إقامة

  • tabId

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

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

UserSettings

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

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

أماكن إقامة

  • isOnToolbar

    منطقي

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

UserSettingsChange

في انتظار المراجعة

أماكن إقامة

  • isOnToolbar

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

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

الطُرق

disable()

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

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

المعلمات

  • tabId

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

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

enable()

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

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

المعلمات

  • tabId

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

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

  • رد الاتصال

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

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

    () => 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()

وعود الإصدار 110 من Chrome والإصدارات الأحدث 
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()

وعود الإصدار 91 من Chrome أو الإصدارات الأحدث 
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()

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

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

المعلمات

  • الخيارات

    OpenPopupOptions اختياري

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

  • رد الاتصال

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

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

    () => 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

المرتجعات

  • وعود <باطلة>

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

setBadgeText()

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

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

المعلمات

  • التفاصيل

    كائن

    • tabId

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

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

    • text

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

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

setBadgeTextColor()

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

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

المعلمات

  • التفاصيل

    كائن

    • اللون

      string | ColorArray

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

    • tabId

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

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

setIcon()

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

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

المعلمات

  • التفاصيل

    كائن

    • بيانات الصورة

      ImageData | الكائن اختياري

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

    • المسار

      string | الكائن اختياري

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

    • tabId

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

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

setPopup()

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

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

المعلمات

  • التفاصيل

    كائن

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

      سلسلة

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

    • tabId

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

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

setTitle()

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

لضبط عنوان الإجراء. يظهر ذلك في التلميح.

المعلمات

  • التفاصيل

    كائن

    • tabId

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

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

    • title

      سلسلة

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

فعاليات

onClicked

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (tab: tabs.Tab) => void

onUserSettingsChanged

في انتظار المراجعة
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

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

المعلمات