chrome.devtools.panels

الوصف

استخدِم واجهة برمجة التطبيقات chrome.devtools.panels لدمج الإضافة في واجهة مستخدم نافذة "أدوات المطوّرين": يمكنك إنشاء لوحاتك الخاصة والوصول إلى اللوحات الحالية وإضافة أشرطة جانبية.

البيان

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

"devtools_page"

اطّلِع على ملخّص واجهات برمجة التطبيقات في "أدوات المطوّرين" للحصول على مقدّمة عامة حول استخدام واجهات برمجة التطبيقات في "أدوات المطوّرين".

نظرة عامة

يتم عرض كل لوحة إضافية وشريط جانبي كصفحة HTML منفصلة. يمكن لجميع صفحات الإضافة المعروضة في نافذة "أدوات المطوّرين" الوصول إلى جميع الوحدات في واجهة برمجة التطبيقات chrome.devtools، بالإضافة إلى واجهة برمجة التطبيقات chrome.extension. لا تتوفّر واجهات برمجة التطبيقات الأخرى للإضافات للصفحات ضمن نافذة "أدوات المطوّرين"، ولكن يمكنك استدعاؤها من خلال إرسال طلب إلى صفحة الخلفية الخاصة بإضافتك، تمامًا كما يتم ذلك في برامج النصوص الخاصة بالمحتوى.

يمكنك استخدام طريقة devtools.panels.setOpenResourceHandler لتثبيت دالّة رد الاتصال التي تعالج طلبات المستخدمين بفتح مورد (عادةً، نقرة على رابط مورد في نافذة "أدوات المطوّرين"). يتم استدعاء معالج واحد على الأكثر من المعالجات المثبَّتة، ويمكن للمستخدمين تحديد (باستخدام مربّع الحوار "إعدادات أدوات المطوّرين") إما السلوك التلقائي أو إضافة للتعامل مع طلبات فتح الموارد. إذا طلبت إحدى الإضافات setOpenResourceHandler() عدة مرات، سيتم الاحتفاظ بالمعالج الأخير فقط.

أمثلة

يضيف الرمز التالي لوحة مضمّنة في Panel.html، ويمثّلها FontPicker.png على شريط أدوات "أدوات المطوّرين"، ويُطلق عليها اسم أداة اختيار الخط:

chrome.devtools.panels.create("Font Picker",
                              "FontPicker.png",
                              "Panel.html",
                              function(panel) { ... });

يضيف الرمز التالي لوحة شريط جانبي مضمّنة في Sidebar.html بعنوان خصائص الخط إلى "لوحة العناصر"، ثم يضبط ارتفاعها على 8ex:

chrome.devtools.panels.elements.createSidebarPane("Font Properties",
  function(sidebar) {
    sidebar.setPage("Sidebar.html");
    sidebar.setHeight("8ex");
  }
);

توضّح لقطة الشاشة هذه التأثير الذي ستحدثه الأمثلة أعلاه في نافذة "أدوات المطوّرين":

لوحة رمز الإضافة في شريط أدوات DevTools

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال devtools panels API من مستودع chrome-extension-samples.

الأنواع

Button

زر أنشأته الإضافة

الخصائص

  • onClicked

    Event<functionvoidvoid>

    يتم تنشيط هذا الحدث عند النقر على الزر.

    تبدو الدالة onClicked.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      () => void

  • تحديث

    فارغ

    تعدّل هذه الطريقة سمات الزر. في حال حذف بعض الوسيطات أو كانت قيمتها null، لن يتم تعديل السمات المقابلة.

    تبدو الدالة update على النحو التالي: 

    (iconPath?: string, tooltipText?: string, disabled?: boolean) => {...}

    • iconPath

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

      مسار الرمز الجديد للزر

    • tooltipText

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

      النص المعروض كتلميح أداة عندما يمرّر المستخدم مؤشر الماوس فوق الزر.

    • غير مفعّلة

      boolean اختياري

      تحديد ما إذا كان الزر غير مفعَّل.

ElementsPanel

تمثّل لوحة "العناصر".

الخصائص

  • onSelectionChanged

    Event<functionvoidvoid>

    يتم تنشيط هذا الحدث عند اختيار عنصر في اللوحة.

    تبدو الدالة onSelectionChanged.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      () => void

  • createSidebarPane

    فارغ

    وعد

    تنشئ هذه السمة لوحة داخل الشريط الجانبي للوحة.

    تبدو الدالة createSidebarPane على النحو التالي: 

    (title: string, callback?: function) => {...}

    • title

      سلسلة

      النص الذي يتم عرضه في عنوان الشريط الجانبي

    • callback

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

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

      (result: ExtensionSidebarPane) => void

      • عنصر ExtensionSidebarPane للوحة الشريط الجانبي التي تم إنشاؤها

    • returns

      Promise<ExtensionSidebarPane>

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

      دالة ردّ اتصال يتم استدعاؤها عند إنشاء الشريط الجانبي.

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

ExtensionPanel

تمثّل هذه السمة لوحة أنشأتها إحدى الإضافات.

الخصائص

  • onHidden

    Event<functionvoidvoid>

    يتم تنشيط هذا الحدث عندما يخرج المستخدم من اللوحة.

    تبدو الدالة onHidden.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      () => void

  • onSearch

    Event<functionvoidvoid>

    يتم تنشيطه عند اتّخاذ إجراء بحث (بدء بحث جديد أو التنقّل بين نتائج البحث أو إلغاء البحث).

    تبدو الدالة onSearch.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      (action: string, queryString?: string) => void

      • إجراء

        سلسلة

      • queryString

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

  • onShown

    Event<functionvoidvoid>

    يتم تنشيطه عندما ينتقل المستخدم إلى اللوحة.

    تبدو الدالة onShown.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      (window: Window) => void

      • نافذة

        نافذة

  • createStatusBarButton

    إلغاء

    تُستخدَم لإلحاق زر بشريط الحالة في اللوحة.

    تبدو الدالة createStatusBarButton على النحو التالي: 

    (iconPath: string, tooltipText: string, disabled: boolean) => {...}

    • iconPath

      سلسلة

      مسار رمز الزر يجب أن يحتوي الملف على صورة بحجم 64×24 بكسل تتألف من رمزَين بحجم 32×24 بكسل. يُستخدم الرمز الأيسر عندما يكون الزر غير نشط، ويظهر الرمز الأيمن عند الضغط على الزر.

    • tooltipText

      سلسلة

      النص المعروض كتلميح أداة عندما يمرّر المستخدم مؤشر الماوس فوق الزر.

    • غير مفعّلة

      قيمة منطقية

      تحديد ما إذا كان الزر غير مفعَّل.

  • إظهار

    فارغ

    ‫Chrome 140 أو إصدار أحدث

    تعرض هذه السمة اللوحة من خلال تفعيل علامة التبويب المقابلة.

    تبدو الدالة show على النحو التالي: 

    () => {...}

ExtensionSidebarPane

شريط جانبي تم إنشاؤه بواسطة الإضافة

الخصائص

  • onHidden

    Event<functionvoidvoid>

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

    تبدو الدالة onHidden.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      () => void

  • onShown

    Event<functionvoidvoid>

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

    تبدو الدالة onShown.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      (window: Window) => void

      • نافذة

        نافذة

  • setExpression

    فارغ

    وعد

    تضبط هذه السمة تعبيرًا يتم تقييمه داخل الصفحة التي تم فحصها. يتم عرض النتيجة في جزء الشريط الجانبي.

    تبدو الدالة setExpression على النحو التالي: 

    (expression: string, rootTitle?: string, callback?: function) => {...}

    • تعبير

      سلسلة

      تعبير سيتم تقييمه في سياق الصفحة التي تم فحصها. يتم عرض كائنات JavaScript وعُقد DOM في شجرة قابلة للتوسيع تشبه وحدة التحكّم/المراقبة.

    • rootTitle

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

      عنوان اختياري لجذر شجرة التعبير

    • callback

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

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

      () => void

    • returns

      Promise<void>

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

      يتم استدعاء دالة رد الاتصال بعد تعديل لوحة الشريط الجانبي بنتائج تقييم التعبير.

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

  • setHeight

    فارغ

    تضبط هذه السمة ارتفاع الشريط الجانبي.

    تبدو الدالة setHeight على النحو التالي: 

    (height: string) => {...}

    • الطول

      سلسلة

      مواصفات الحجم المشابهة لـ CSS، مثل '100px' أو '12ex'

  • setObject

    فارغ

    وعد

    تضبط هذه السمة عنصرًا متوافقًا مع JSON ليتم عرضه في لوحة الشريط الجانبي.

    تبدو الدالة setObject على النحو التالي: 

    (jsonObject: string, rootTitle?: string, callback?: function) => {...}

    • jsonObject

      سلسلة

      تمثّل هذه السمة عنصرًا سيتم عرضه في سياق الصفحة التي يتم فحصها. يتم تقييمها في سياق المتصل (عميل واجهة برمجة التطبيقات).

    • rootTitle

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

      عنوان اختياري لجذر شجرة التعبير

    • callback

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

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

      () => void

    • returns

      Promise<void>

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

      دالة ردّ نداء يتم استدعاؤها بعد تعديل الشريط الجانبي باستخدام العنصر.

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

  • setPage

    فارغ

    تضبط هذه السمة صفحة HTML ليتم عرضها في لوحة الشريط الجانبي.

    تبدو الدالة setPage على النحو التالي: 

    (path: string) => {...}

    • المسار

      سلسلة

      المسار النسبي لصفحة إضافة سيتم عرضها في الشريط الجانبي.

SourcesPanel

تمثّل لوحة "المصادر".

الخصائص

  • onSelectionChanged

    Event<functionvoidvoid>

    يتم تنشيط هذا الحدث عند اختيار عنصر في اللوحة.

    تبدو الدالة onSelectionChanged.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      () => void

  • createSidebarPane

    فارغ

    وعد

    تنشئ هذه السمة لوحة داخل الشريط الجانبي للوحة.

    تبدو الدالة createSidebarPane على النحو التالي: 

    (title: string, callback?: function) => {...}

    • title

      سلسلة

      النص الذي يتم عرضه في عنوان الشريط الجانبي

    • callback

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

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

      (result: ExtensionSidebarPane) => void

      • عنصر ExtensionSidebarPane للوحة الشريط الجانبي التي تم إنشاؤها

    • returns

      Promise<ExtensionSidebarPane>

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

      دالة ردّ اتصال يتم استدعاؤها عند إنشاء الشريط الجانبي.

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

Theme

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

المظهر المستخدَم في "أدوات مطوّري البرامج"

تعداد

"default"
مظهر "أدوات مطوّري البرامج" التلقائي ويكون هذا المظهر فاتحًا دائمًا.

"dark"
المظهر الداكن

الخصائص

elements

لوحة "العناصر"

النوع

ElementsPanel

sources

لوحة "المصادر"

النوع

SourcesPanel

themeName

Chrome 59+

اسم نسق الألوان الذي تم ضبطه في إعدادات "أدوات مطوري البرامج" الخاصة بالمستخدم. القيم المحتمَلة: default (القيمة التلقائية) وdark.

النوع

سلسلة

الطُرق

create()

وعد 
chrome.devtools.panels.create(
  title: string,
  iconPath: string,
  pagePath: string,
  callback?: function,
): Promise<ExtensionPanel>

تنشئ هذه الطريقة لوحة إضافة.

المعلمات

  • title

    سلسلة

    العنوان الذي يظهر بجانب رمز الإضافة في شريط أدوات "أدوات المطوّرين"

  • iconPath

    سلسلة

    مسار رمز اللوحة بالنسبة إلى دليل الإضافة

  • pagePath

    سلسلة

    مسار صفحة HTML للوحة بالنسبة إلى دليل الإضافة

  • callback

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

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

    (panel: ExtensionPanel) => void

    • لوحة

      ExtensionPanel

      عنصر ExtensionPanel يمثّل اللوحة التي تم إنشاؤها.

المرتجعات

  • Promise<ExtensionPanel>

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

    دالة يتم استدعاؤها عند إنشاء اللوحة.

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

openResource()

وعد 
chrome.devtools.panels.openResource(
  url: string,
  lineNumber: number,
  columnNumber?: number,
  callback?: function,
): Promise<void>

يطلب من "أدوات مطوري البرامج" فتح عنوان URL في إحدى لوحات "أدوات مطوري البرامج".

المعلمات

  • url

    سلسلة

    عنوان URL للمرجع المطلوب فتحه

  • lineNumber

    الرقم

    تحدّد هذه السمة رقم السطر الذي سيتم الانتقال إليه عند تحميل المرجع.

  • columnNumber

    number اختياري

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

    تحدّد هذه السمة رقم العمود الذي سيتم الانتقال إليه عند تحميل المرجع.

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    دالة يتم استدعاؤها عند تحميل المورد بنجاح.

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

setOpenResourceHandler()

chrome.devtools.panels.setOpenResourceHandler(
  callback?: function,
): void

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

المعلمات

  • callback

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

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

    (resource: Resource, lineNumber: number) => void

    • المصدر

      المرجع

      عنصر devtools.inspectedWindow.Resource للمرجع الذي تم النقر عليه.

    • lineNumber

      الرقم

      تحدّد هذه السمة رقم السطر داخل المرجع الذي تم النقر عليه.

setThemeChangeHandler()

الإصدار 99 من Chrome والإصدارات الأحدث 
chrome.devtools.panels.setThemeChangeHandler(
  callback?: function,
): void

تحدّد هذه السمة الدالة التي سيتم استدعاؤها عند تغيير المظهر الحالي في "أدوات مطوّري البرامج". لإلغاء ضبط المعالج، يمكنك إما استدعاء الطريقة بدون مَعلمات أو تمرير null كمَعلمة.

المعلمات

  • callback

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

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

    (theme: Theme) => void

    • مظهر

      المظهر

      المظهر الحالي في "أدوات مطوّري البرامج"