chrome.pageAction

refresh date: 2026-09-25 robots: noindex

الوصف

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

مدى التوفّر

≤ MV2

إليك بعض الأمثلة:

  • الاشتراك في خلاصة RSS لهذه الصفحة
  • إنشاء عرض شرائح من صور هذه الصفحة

يمثّل رمز RSS في لقطة الشاشة التالية إجراء صفحة يتيح لك الاشتراك في خلاصة RSS للصفحة الحالية.

تظهر الإجراءات المخفية على الصفحة باللون الرمادي. على سبيل المثال، خلاصة RSS أدناه غير متاحة، لأنّه لا يمكنك الاشتراك في خلاصة الصفحة الحالية:

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

البيان

سجِّل إجراء الصفحة في بيان الإضافة على النحو التالي:

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

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

لا يزال من الممكن استخدام البنية القديمة لتسجيل الرمز التلقائي:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

أجزاء واجهة المستخدم

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

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

نصائح

للحصول على أفضل تأثير مرئي، اتّبِع الإرشادات التالية:

  • استخدِم إجراءات الصفحة للميزات التي لا تنطبق إلا على عدد قليل من الصفحات.
  • لا تستخدِم إجراءات الصفحة للميزات التي تكون منطقية لمعظم الصفحات. استخدِم إجراءات المتصفح بدلاً من ذلك.
  • لا تحرِّك الرمز باستمرار. هذا مزعج فقط.

الأنواع

ImageDataType

بيانات البكسل لصورة يجب أن يكون كائن ImageData (على سبيل المثال، من عنصر canvas).

النوع

ImageData

TabDetails

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

الخصائص

  • tabId

    number اختياري

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

الطُرق

getPopup()

وعد 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

المعلمات

  • التفاصيل

    TabDetails

  • callback

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • Promise<string>

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

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

getTitle()

وعد 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

تعرض هذه السمة عنوان إجراء الصفحة.

المعلمات

  • التفاصيل

    TabDetails

  • callback

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • Promise<string>

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

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

hide()

وعد 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

يخفي هذا الخيار إجراء الصفحة. تظلّ إجراءات الصفحة المخفية ظاهرةً في شريط أدوات Chrome، ولكنها تظهر باللون الرمادي.

المعلمات

  • tabId

    الرقم

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

  • callback

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

setIcon()

وعد 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • iconIndex

      number اختياري

      تمّت إزالة هذا العمود. يتم تجاهل هذه الوسيطة.

    • imageData

      ImageData | object اختيارية

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

    • المسار

      string | object اختيارية

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

    • tabId

      الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

setPopup()

وعد 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

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

      سلسلة

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

    • tabId

      الرقم

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

  • callback

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

setTitle()

وعد 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • tabId

      الرقم

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

    • title

      سلسلة

      سلسلة التلميح

  • callback

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

show()

وعد 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

تعرِض هذه السمة الإجراء على الصفحة. يظهر إجراء الصفحة كلّما تم اختيار علامة التبويب.

المعلمات

  • tabId

    الرقم

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

  • callback

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

الفعاليات

onClicked

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

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

المعلمات

  • callback

    دالة

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

    (tab: tabs.Tab) => void