chrome.debugger

refresh date: 2026-09-25 robots: noindex

شرح

chrome.debugger API به‌عنوان انتقال جایگزین برای پروتکل اشکال‌زدایی از راه دور Chrome عمل می‌کند. از chrome.debugger برای پیوست کردن به یک یا چند برگه برای ابزارسازی تعامل شبکه، اشکال‌زدایی جاوا اسکریپت، تغییر DOM و CSS، و موارد دیگر استفاده کنید. از ویژگی Debuggee tabId برای هدف‌یابی برگه‌ها با sendCommand و مسیریابی رویدادها با tabId از فراخوانی‌های برگشتی onEvent استفاده کنید.

اجازه‌ها

debugger

این اجازه هشداری را فعال می‌کند.

یادداشت امنیتی

به‌دلایل امنیتی، chrome.debugger API دسترسی به همه دامنه‌های پروتکل Chrome DevTools را فراهم نمی‌کند. دامنه‌های دردسترس عبارت‌اند از: دسترس‌پذیری، بازرسی‌ها، CacheStorage، کنسول، CSS، پایگاه داده، اشکال‌زدا، DOM، DOMDebugger، DOMSnapshot، شبیه‌سازی، Fetch، IO، ورودی، بازرس، گزارش، شبکه، هم‌پوشانی، صفحه، عملکرد، زمان اجرا، فضای ذخیره‌سازی، هدف، ردیابی، WebAudio، و WebAuthn.

مانیفست

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

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

مثال‌ها

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

انواع

Debuggee

شناسه اشکال‌زدایی. باید tabId،‏ extensionId، یا targetId مشخص شود

مشخصات

• extensionId

  رشته اختیاری

  شناسه افزونه‌ای که می‌خواهید اشکال‌زدایی کنید. پیوست کردن به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از کلید خط فرمان --silent-debugger-extension-api استفاده شود.

• tabId

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

  شناسه برگه‌ای که می‌خواهید اشکال‌زدایی کنید.

• targetId

  رشته اختیاری

  شناسه مبهم هدف اشکال‌زدایی.

DebuggerSession

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

شناسه جلسه اشکال‌زدا. یکی‌از tabId،‏ extensionId، یا targetId باید مشخص شود. علاوه‌براین، sessionId اختیاری می‌تواند ارائه شود. اگر sessionId برای آرگومان‌های ارسال‌شده از onEvent مشخص شده باشد، به این معنی است که رویداد از یک جلسه پروتکل فرزند در جلسه اشکال‌زدایی ریشه می‌آید. اگر sessionId هنگام ارسال به sendCommand مشخص شده باشد، یک جلسه پروتکل فرزند را در جلسه اشکال‌زدایی ریشه هدف قرار می‌دهد.

مشخصات

• extensionId

  رشته اختیاری

  شناسه افزونه‌ای که می‌خواهید اشکال‌زدایی کنید. پیوست کردن به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از کلید خط فرمان --silent-debugger-extension-api استفاده شود.

• sessionId

  رشته اختیاری

  شناسه مبهم جلسه پروتکل Chrome DevTools. جلسه فرزند را در جلسه ریشه که با tabId،‏ extensionId، یا targetId شناسایی شده است شناسایی می‌کند.

• tabId

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

  شناسه برگه‌ای که می‌خواهید اشکال‌زدایی کنید.

• targetId

  رشته اختیاری

  شناسه مبهم هدف اشکال‌زدایی.

DetachReason

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

دلیل قطع اتصال.

شمارشی

"target_closed"

"canceled_by_user"

TargetInfo

اطلاعات هدف اشکال‌زدایی

مشخصات

• پیوست‌شده

  بولی

  اگر اشکال‌زدا ازقبل پیوست شده باشد، درست است.

• extensionId

  رشته اختیاری

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

• faviconUrl

  رشته اختیاری

  نشانی وب نماد وب‌سایت هدف.

• id

  رشته

  شناسه هدف.

• tabId

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

  شناسه برگه، اگر نوع == «صفحه» باشد تعریف می‌شود.

• عنوان

  رشته

  عنوان صفحه هدف.

• نوع

  TargetInfoType

  نوع هدف.

• نشانی وب

  رشته

  نشانی وب هدف.

TargetInfoType

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

نوع هدف.

شمارشی

«صفحه»

"background_page"

«worker»

«دیگر»

روش‌ها

attach()

قول

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
): Promise<void>

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

پارامترها

• هدف

  Debuggee

  هدف اشکال‌زدایی که می‌خواهید به آن متصل شوید.

• requiredVersion

  رشته

  نسخه پروتکل اشکال‌زدایی الزامی («0.1»). فقط می‌توان به اشکال‌زدایی با نسخه اصلی منطبق و نسخه فرعی بزرگ‌تر یا مساوی متصل شد. فهرست نسخه‌های پروتکل را می‌توانید در اینجا دریافت کنید.

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

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

detach()

قول

chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
): Promise<void>

اشکال‌زدا را از هدف موردنظر جدا می‌کند.

پارامترها

• هدف

  Debuggee

  هدف اشکال‌زدایی که می‌خواهید از آن جدا شوید.

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

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

getTargets()

قول

chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

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

پارامترها

• تماس برگشتی

  تابع اختیاری

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

  (result: TargetInfo[]) => void

  • نتیجه

    TargetInfo[]

    آرایه‌ای از اشیاء TargetInfo که با اهداف اشکال‌زدایی دردسترس مطابقت دارد.

بازگشتی‌ها

• Promise<TargetInfo[]>

  Chrome نسخه ۹۶ به بالا

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

sendCommand()

قول

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
): Promise<object | undefined>

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

پارامترها

• هدف

  DebuggerSession

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

• روش

  رشته

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

• commandParams

  شیء اختیاری

  شیء JSON با پارامترهای درخواست. این شیء باید با طرح پارامترهای اشکال‌زدایی از راه دور برای روش ارائه‌شده مطابقت داشته باشد.

• تماس برگشتی

  تابع اختیاری

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

  (result?: object) => void

  • نتیجه

    شیء اختیاری

    شیء JSON با پاسخ. ساختار پاسخ بسته به نام روش متفاوت است و با مشخصه «returns» شرح فرمان در پروتکل اشکال‌زدایی ازراه‌دور تعریف می‌شود.

بازگشتی‌ها

• Promise<object | undefined>

  Chrome نسخه ۹۶ به بالا

  متن پاسخ. اگر هنگام پست کردن پیام خطایی رخ دهد، promise رد خواهد شد.

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

رویدادها

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

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

پارامترها

• تماس برگشتی

  عملکرد

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

  (source: Debuggee, reason: DetachReason) => void

  • منبع

    Debuggee

  • دلیل

    DetachReason

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

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

پارامترها

• تماس برگشتی

  عملکرد

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

  (source: DebuggerSession, method: string, params?: object) => void

  • منبع

    DebuggerSession

  • روش

    رشته

  • پارامترها

    شیء اختیاری