chrome.action

الوصف

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

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، يتم التعامل مع الإعداد على أنّه إعداد عام. تُعطى الإعدادات الخاصة بالعلامة تبويب الأولوية على الإعدادات العامة.

الحالة مفعَّلة

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

يمكنك التحكّم في الحالة آليًا باستخدام الطريقتَين 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

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

المرتجعات

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

getBadgeText()

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

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

المعلمات

  • التفاصيل

    TabDetails

  • ردّ الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • Promise<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

    • نتيجة

      سلسلة

المرتجعات

  • Promise<string>

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

getTitle()

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

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

المعلمات

  • التفاصيل

    TabDetails

  • ردّ الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • Promise<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<boolean>

    تتوفّر الوعود في الإصدار 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 | object optional

      إما عنصر 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,
)

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

المعلمات