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

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

أماكن إقامة

  • tabId

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

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

الطُرق

getPopup()

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

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

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

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

getTitle()

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

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

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

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

hide()

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

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

المعلمات

  • tabId

    الرقم

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

  • رد الاتصال

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

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

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

    () => void

المرتجعات

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

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

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

setIcon()

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

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

المعلمات

  • التفاصيل

    كائن

    • iconIndex

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

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

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

      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

المرتجعات

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

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

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

setPopup()

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

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

المعلمات

  • التفاصيل

    كائن

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

      سلسلة

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

    • tabId

      الرقم

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

  • رد الاتصال

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

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

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

    () => void

المرتجعات

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

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

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

setTitle()

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

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

المعلمات

  • التفاصيل

    كائن

    • tabId

      الرقم

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

    • title

      سلسلة

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

  • رد الاتصال

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

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

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

    () => void

المرتجعات

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

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

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

show()

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

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

المعلمات

  • tabId

    الرقم

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

  • رد الاتصال

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

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

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

    () => void

المرتجعات

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

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

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

فعاليات

onClicked

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (tab: tabs.Tab) => void