chrome.pageAction

الوصف

يمكنك استخدام chrome.pageAction API لوضع الرموز في شريط أدوات 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

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

أماكن إقامة

  • tabId

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

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

الطُرق

getPopup()

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

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

المَعلمات

  • التفاصيل

    TabDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (result: string)=>void

    • نتيجة

      سلسلة

المرتجعات

  • وعد<string>

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

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

getTitle()

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

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

المَعلمات

  • التفاصيل

    TabDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (result: string)=>void

    • نتيجة

      سلسلة

المرتجعات

  • وعد<string>

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

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

hide()

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

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

المَعلمات

  • tabId

    الرقم

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

setIcon()

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

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

المَعلمات

  • التفاصيل

    كائن

    • iconIndex

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

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

    • imageData

      ImageData|Object اختياري

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

    • المسار

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

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

    • tabId

      الرقم

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

setPopup()

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

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

المَعلمات

  • التفاصيل

    كائن

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

      سلسلة

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

    • tabId

      الرقم

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

setTitle()

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

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

المَعلمات

  • التفاصيل

    كائن

    • tabId

      الرقم

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

    • title

      سلسلة

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

show()

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

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

المَعلمات

  • tabId

    الرقم

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

فعاليات

onClicked

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (tab: tabs.Tab)=>void