chrome.devtools.panels

refresh date: 2026-09-25 robots: noindex

شرح

از میانای برنامه‌سازی کاربردی chrome.devtools.panels برای ادغام افزونه‌تان در میانای کاربر پنجره «ابزارهای توسعه‌دهندگان» استفاده کنید: پانل‌های خودتان را ایجاد کنید، به پانل‌های موجود دسترسی پیدا کنید، و نوارهای کناری اضافه کنید.

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، کلیدهای زیر باید در مانیفست اعلام شوند.

"devtools_page"

برای آشنایی کلی با نحوه استفاده از میاناهای برنامه‌سازی کاربردی «ابزارهای توسعه‌دهندگان»، به خلاصه میاناهای برنامه‌سازی کاربردی DevTools مراجعه کنید.

نمای کلی

هر پانل افزونه و نوار کناری به‌عنوان یک صفحه 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 قرار دارد و عنوان آن Font Properties است به پانل Elements اضافه می‌کند، سپس ارتفاع آن را روی 8ex تنظیم می‌کند:

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

این نماگرفت تأثیری را که مثال‌های بالا بر پنجره «ابزارهای توسعه‌دهندگان» می‌گذارند نشان می‌دهد:

پانل نماد افزونه در نوارابزار DevTools

برای امتحان کردن این API، نمونه API پانل‌های devtools را از مخزن chrome-extension-samples نصب کنید.

انواع

Button

دکمه‌ای که افزونه ایجاد کرده است.

مشخصات

  • onClicked

    Event<functionvoidvoid>

    وقتی روی دکمه کلیک می‌شود، فعال می‌شود.

    تابع onClicked.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      () => void

  • به‌روز کردن

    باطل کردن

    مشخصه‌های دکمه را به‌روز می‌کند. اگر برخی‌از آرگومان‌ها حذف شده باشند یا null باشند، مشخصه‌های مربوطه به‌روز نمی‌شوند.

    تابع update به‌صورت زیر است: 

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

    • iconPath

      رشته اختیاری

      مسیر نماد جدید دکمه.

    • tooltipText

      رشته اختیاری

      نوشتاری که وقتی کاربر موشواره را روی دکمه نگه می‌دارد، به‌عنوان نکته‌ابزار نشان داده می‌شود.

    • غیرفعال

      بولی اختیاری

      آیا دکمه غیرفعال است.

ElementsPanel

پانل «عناصر» را نشان می‌دهد.

مشخصات

  • onSelectionChanged

    Event<functionvoidvoid>

    وقتی شیئی در پانل انتخاب شود، فعال می‌شود.

    تابع onSelectionChanged.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      () => void

  • createSidebarPane

    باطل کردن

    قول

    قاب جدیدی در نوار کناری پانل ایجاد می‌کند.

    تابع createSidebarPane به‌صورت زیر است: 

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

    • عنوان

      رشته

      نوشتاری که در زیرنویس نوار کناری نمایش داده می‌شود.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      (result: ExtensionSidebarPane) => void

      • یک شیء ExtensionSidebarPane برای قاب نوار کناری ایجادشده.

    • returns

      Promise<ExtensionSidebarPane>

      Chrome نسخه ۱۵۲ و بالاتر

      وقتی نوار کناری ایجاد می‌شود، یک فراخوانی برگشتی فراخوانده می‌شود.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

ExtensionPanel

نشان‌دهنده پانلی است که توسط افزونه ایجاد شده است.

مشخصات

  • onHidden

    Event<functionvoidvoid>

    وقتی کاربر از پانل خارج می‌شود، فعال می‌شود.

    تابع onHidden.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      () => void

  • onSearch

    Event<functionvoidvoid>

    هنگام کنش جستجو (شروع جستجوی جدید، پیمایش نتیجه جستجو، یا لغو جستجو) فعال می‌شود.

    تابع onSearch.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

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

      • کنش

        رشته

      • queryString

        رشته اختیاری

  • onShown

    Event<functionvoidvoid>

    وقتی کاربر به پانل می‌رود، فعال می‌شود.

    تابع onShown.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      (window: Window) => void

      • پنجره

        پنجره

  • createStatusBarButton

    باطل کردن

    دکمه‌ای به نوار وضعیت پانل اضافه می‌کند.

    تابع createStatusBarButton به‌صورت زیر است: 

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

    • iconPath

      رشته

      مسیر نماد دکمه. فایل باید حاوی تصویری با ابعاد ۶۴×۲۴ پیکسل باشد که از دو نماد ۳۲×۲۴ تشکیل شده است. نماد سمت چپ زمانی استفاده می‌شود که دکمه غیرفعال باشد؛ نماد سمت راست زمانی نمایش داده می‌شود که دکمه فشار داده شود.

    • tooltipText

      رشته

      نوشتاری که وقتی کاربر موشواره را روی دکمه نگه می‌دارد، به‌عنوان نکته‌ابزار نشان داده می‌شود.

    • غیرفعال

      بولی

      آیا دکمه غیرفعال است.

  • نمایش

    باطل کردن

    Chrome نسخه ۱۴۰ به بالا

    پانل را با فعال کردن زبانه مربوطه نشان می‌دهد.

    تابع show به‌صورت زیر است: 

    () => {...}

ExtensionSidebarPane

نوار کناری ایجادشده توسط افزونه.

مشخصات

  • onHidden

    Event<functionvoidvoid>

    وقتی پانل نوار کناری درنتیجه تغییر دادن پانل میزبان پانل نوار کناری توسط کاربر پنهان می‌شود، فعال می‌شود.

    تابع onHidden.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      () => void

  • onShown

    Event<functionvoidvoid>

    وقتی قاب نوار کناری درنتیجه جابه‌جایی کاربر به پانلی که میزبان آن است نمایان می‌شود، فعال می‌شود.

    تابع onShown.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      (window: Window) => void

      • پنجره

        پنجره

  • setExpression

    باطل کردن

    قول

    عبارتی را تنظیم می‌کند که در صفحه بازرسی‌شده ارزیابی می‌شود. نتیجه در قاب نوار کناری نمایش داده می‌شود.

    تابع setExpression به‌صورت زیر است: 

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

    • عبارت

      رشته

      عبارتی که باید در بافتار صفحه بازرسی‌شده ارزیابی شود. اهداف جاوا اسکریپت و گره‌های DOM در درختی قابل‌گسترش مشابه کنسول/ساعت نمایش داده می‌شوند.

    • rootTitle

      رشته اختیاری

      عنوان اختیاری برای ریشه درخت عبارت.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      () => void

    • returns

      Promise<void>

      Chrome نسخه ۱۵۲ و بالاتر

      فراخوانی برگشتی که پس‌از به‌روزرسانی قاب نوار کناری با نتایج ارزیابی عبارت فراخوانی می‌شود.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

  • setHeight

    باطل کردن

    ارتفاع نوار کناری را تنظیم می‌کند.

    تابع setHeight به‌صورت زیر است: 

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

    • ارتفاع

      رشته

      مشخصات اندازه شبیه CSS، مانند '100px' یا '12ex'.

  • setObject

    باطل کردن

    قول

    شیء سازگار با JSON را برای نمایش در قاب نوار کناری تنظیم می‌کند.

    تابع setObject به‌صورت زیر است: 

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

    • jsonObject

      رشته

      شیئی که باید در بافتار صفحه بازرسی‌شده نمایش داده شود. در بافت فراخواننده (کارخواه میانای برنامه‌سازی کاربردی) ارزیابی می‌شود.

    • rootTitle

      رشته اختیاری

      عنوان اختیاری برای ریشه درخت عبارت.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      () => void

    • returns

      Promise<void>

      Chrome نسخه ۱۵۲ و بالاتر

      فراخوانی‌ای که پس‌از به‌روزرسانی نوار کناری با شیء فراخوانده می‌شود.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

  • setPage

    باطل کردن

    صفحه HTML را برای نمایش در قاب نوار کناری تنظیم می‌کند.

    تابع setPage به‌صورت زیر است: 

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

    • مسیر

      رشته

      مسیر نسبی صفحه افزونه برای نمایش در نوار کناری.

SourcesPanel

پانل «منابع» را نشان می‌دهد.

مشخصات

  • onSelectionChanged

    Event<functionvoidvoid>

    وقتی شیئی در پانل انتخاب شود، فعال می‌شود.

    تابع onSelectionChanged.addListener به‌صورت زیر است: 

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

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      () => void

  • createSidebarPane

    باطل کردن

    قول

    قاب جدیدی در نوار کناری پانل ایجاد می‌کند.

    تابع createSidebarPane به‌صورت زیر است: 

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

    • عنوان

      رشته

      نوشتاری که در زیرنویس نوار کناری نمایش داده می‌شود.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      (result: ExtensionSidebarPane) => void

      • یک شیء ExtensionSidebarPane برای قاب نوار کناری ایجادشده.

    • returns

      Promise<ExtensionSidebarPane>

      Chrome نسخه ۱۵۲ و بالاتر

      وقتی نوار کناری ایجاد می‌شود، یک فراخوانی برگشتی فراخوانده می‌شود.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

Theme

Chrome نسخه ۹۹ و بالاتر

زمینه مورداستفاده DevTools.

شمارشی

«پیش‌فرض»
زمینه پیش‌فرض DevTools. این همیشه زمینه روشن است.

«تیره»
زمینه تیره.

مشخصات

elements

پانل «عناصر».

نوع

ElementsPanel

sources

پانل منابع.

نوع

SourcesPanel

themeName

Chrome نسخه ۵۹ و بالاتر

نام زمینه رنگی تنظیم‌شده در تنظیمات DevTools کاربر. مقادیر ممکن: default (پیش‌فرض) و dark.

نوع

رشته

روش‌ها

create()

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

پانل افزونه ایجاد می‌کند.

پارامترها

  • عنوان

    رشته

    عنوانی که در کنار نماد افزونه در نوارابزار «ابزارهای توسعه‌دهندگان» نمایش داده می‌شود.

  • iconPath

    رشته

    مسیر نماد پانل نسبت‌به دایرکتوری افزونه.

  • pagePath

    رشته

    مسیر صفحه HTML پانل نسبت به دایرکتوری افزونه.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (panel: ExtensionPanel) => void

    • قاب کارت‌ها

      ExtensionPanel

      شیء ExtensionPanel که نشان‌دهنده پانل ایجادشده است.

بازگشتی‌ها

  • Promise<ExtensionPanel>

    Chrome نسخه ۱۵۲ و بالاتر

    تابعی که هنگام ایجاد پانل فراخوانی می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

openResource()

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

از DevTools درخواست می‌کند نشانی وب را در پانل «ابزارهای توسعه‌دهندگان» باز کند.

پارامترها

  • نشانی وب

    رشته

    نشانی وب منبعی که باید باز شود.

  • lineNumber

    شماره

    شماره خطی را که هنگام بار شدن منبع باید به آن پیمایش شود مشخص می‌کند.

  • columnNumber

    شماره اختیاری

    Chrome نسخه ۱۱۴ و بالاتر

    شماره ستونی را که هنگام بار شدن منبع باید به آن پیمایش شود مشخص می‌کند.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۵۲ و بالاتر

    تابعی که وقتی منبع باموفقیت بار شده است فراخوانی می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setOpenResourceHandler()

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

عملکردی را که باید هنگام کلیک کردن کاربر روی پیوند منبع در پنجره «ابزارهای توسعه‌دهنده» فراخوانی شود مشخص می‌کند. برای لغو تنظیم کنترل‌کننده، یا روش را بدون پارامتر فراخوانی کنید یا null را به‌عنوان پارامتر ارسال کنید.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

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

    • منبع

      منبع

      شیء devtools.inspectedWindow.Resource برای منبعی که روی آن کلیک شده است.

    • lineNumber

      شماره

      شماره خط را در منبعی که روی آن کلیک شده است مشخص می‌کند.

setThemeChangeHandler()

Chrome نسخه ۹۹ و بالاتر 
chrome.devtools.panels.setThemeChangeHandler(
  callback?: function,
): void

تابعی را که باید هنگام تغییر طرح زمینه فعلی در DevTools فراخوانی شود مشخص می‌کند. برای لغو تنظیم کنترل‌کننده، یا روش را بدون پارامتر فراخوانی کنید یا null را به‌عنوان پارامتر ارسال کنید.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (theme: Theme) => void

    • طرح زمینه

      زمینه

      زمینه کنونی در DevTools.