chrome.devtools.panels

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات 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

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثالاً على واجهة برمجة التطبيقات الخاصة بلوحات أدوات المطوّرين من مستودع 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>

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

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

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

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

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

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

  • setHeight

    باطل

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

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

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

    • الارتفاع

      سلسلة

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

  • setObject

    باطل

    وعد

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

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

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

    • jsonObject

      سلسلة

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

    • rootTitle

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

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

    • callback

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

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

      () => void

    • returns

      Promise<void>

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

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

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

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

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

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

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

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

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

openResource()

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

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

المعلمات

  • url

    سلسلة

    عنوان URL للمرجع الذي سيتم فتحه

  • lineNumber

    الرقم

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

  • columnNumber

    number اختياري

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

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

    • مظهر

      المظهر

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