chrome.debugger

توضیحات

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

مجوزها

debugger

این مجوز باعث ایجاد هشدار می‌شود .

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

به دلایل امنیتی، API chrome.debugger دسترسی به همه دامنه‌های پروتکل Chrome DevTools را فراهم نمی‌کند. دامنه‌های موجود عبارتند از: Accessibility ، Audits ، CacheStorage ، Console ، CSS ، Database ، Debugger ، DOM ، DOMDebugger ، DOMSnapshot ، Emulation ، Fetch ، IO ، Input ، Inspector ، Log ، Network ، Overlay ، Page ، Performance ، Profiler ، Runtime ، Storage ، Target ، Tracing ، WebAudio و WebAuthn .

مانیفست

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

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

مثال‌ها

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

انواع

Debuggee

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

خواص

• شناسه افزونه

  رشته اختیاری

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

• شناسه برگه

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

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DebuggerSession

کروم ۱۲۵+

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

خواص

• شناسه افزونه

  رشته اختیاری

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

• شناسه جلسه

  رشته اختیاری

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

• شناسه برگه

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

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DetachReason

کروم ۴۴+

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

شمارشی

"هدف_بسته"

"لغو_توسط_کاربر"

TargetInfo

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

خواص

• پیوست

  بولی

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

• شناسه افزونه

  رشته اختیاری

  شناسه افزونه، که در صورت نوع = 'background_page' تعریف می‌شود.

• آدرس فاویکون

  رشته اختیاری

  آدرس فاویکون هدف.

• شناسه

  رشته

  شناسه هدف.

• شناسه برگه

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

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

• عنوان

  رشته

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

• نوع

  نوع اطلاعات هدف

  نوع هدف.

• آدرس اینترنتی

  رشته

  آدرس اینترنتی هدف.

TargetInfoType

کروم ۴۴+

نوع هدف.

شمارشی

«صفحه»

"صفحه_پس_زمینه"

"کارگر"

«دیگر»

روش‌ها

attach()

وعده

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

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

پارامترها

• هدف

  دیباگی

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

• نسخه مورد نیاز

  رشته

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  () => void

بازگشت‌ها

• قول<void>

  کروم ۹۶+

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

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

detach()

وعده

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

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

پارامترها

• هدف

  دیباگی

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  () => void

بازگشت‌ها

• قول<void>

  کروم ۹۶+

  زمانی که عملیات detach با موفقیت یا شکست مواجه شود، برطرف می‌شود. promise بدون هیچ مقداری برطرف می‌شود. اگر detach با شکست مواجه شود، promise رد خواهد شد.

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getTargets()

وعده

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

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (result: TargetInfo[]) => void

  • نتیجه

    اطلاعات هدف []

    آرایه‌ای از اشیاء TargetInfo مربوط به اهداف اشکال‌زدایی موجود.

بازگشت‌ها

• قول< TargetInfo []>

  کروم ۹۶+

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

sendCommand()

وعده

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

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

پارامترها

• هدف

  جلسه اشکال‌زدایی

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

• روش

  رشته

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

• پارامترهای فرمان

  شیء اختیاری

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (result?: object) => void

  • نتیجه

    شیء اختیاری

    شیء JSON با پاسخ. ساختار پاسخ بسته به نام متد متفاوت است و توسط ویژگی 'returns' از توضیحات دستور در پروتکل اشکال‌زدایی از راه دور تعریف می‌شود.

بازگشت‌ها

• قول <object | undefined>

  کروم ۹۶+

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

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onDetach

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

زمانی اجرا می‌شود که مرورگر، جلسه اشکال‌زدایی (debugging session) مربوط به تب را خاتمه می‌دهد. این اتفاق زمانی می‌افتد که یا تب بسته می‌شود یا Chrome DevTools برای تب پیوست شده فراخوانی می‌شود.

پارامترها

• تماس برگشتی

  تابع

  پارامتر callback به شکل زیر است:

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

  • منبع

    دیباگی

  • دلیل

    دلیل جدا کردن

onEvent

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

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

پارامترها

• تماس برگشتی

  تابع

  پارامتر callback به شکل زیر است:

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

  • منبع

    جلسه اشکال‌زدایی

  • روش

    رشته

  • پارامترها

    شیء اختیاری

،

توضیحات

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

مجوزها

debugger

این مجوز باعث ایجاد هشدار می‌شود .

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

به دلایل امنیتی، API chrome.debugger دسترسی به همه دامنه‌های پروتکل Chrome DevTools را فراهم نمی‌کند. دامنه‌های موجود عبارتند از: Accessibility ، Audits ، CacheStorage ، Console ، CSS ، Database ، Debugger ، DOM ، DOMDebugger ، DOMSnapshot ، Emulation ، Fetch ، IO ، Input ، Inspector ، Log ، Network ، Overlay ، Page ، Performance ، Profiler ، Runtime ، Storage ، Target ، Tracing ، WebAudio و WebAuthn .

مانیفست

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

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

مثال‌ها

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

انواع

Debuggee

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

خواص

• شناسه افزونه

  رشته اختیاری

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

• شناسه برگه

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

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DebuggerSession

کروم ۱۲۵+

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

خواص

• شناسه افزونه

  رشته اختیاری

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

• شناسه جلسه

  رشته اختیاری

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

• شناسه برگه

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

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DetachReason

کروم ۴۴+

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

شمارشی

"هدف_بسته"

"لغو_توسط_کاربر"

TargetInfo

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

خواص

• پیوست

  بولی

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

• شناسه افزونه

  رشته اختیاری

  شناسه افزونه، که در صورت نوع = 'background_page' تعریف می‌شود.

• آدرس فاویکون

  رشته اختیاری

  آدرس فاویکون هدف.

• شناسه

  رشته

  شناسه هدف.

• شناسه برگه

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

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

• عنوان

  رشته

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

• نوع

  نوع اطلاعات هدف

  نوع هدف.

• آدرس اینترنتی

  رشته

  آدرس اینترنتی هدف.

TargetInfoType

کروم ۴۴+

نوع هدف.

شمارشی

«صفحه»

"صفحه_پس_زمینه"

"کارگر"

«دیگر»

روش‌ها

attach()

وعده

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

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

پارامترها

• هدف

  دیباگی

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

• نسخه مورد نیاز

  رشته

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  () => void

بازگشت‌ها

• قول<void>

  کروم ۹۶+

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

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

detach()

وعده

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

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

پارامترها

• هدف

  دیباگی

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  () => void

بازگشت‌ها

• قول<void>

  کروم ۹۶+

  زمانی که عملیات detach با موفقیت یا شکست مواجه شود، برطرف می‌شود. promise بدون هیچ مقداری برطرف می‌شود. اگر detach با شکست مواجه شود، promise رد خواهد شد.

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getTargets()

وعده

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

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (result: TargetInfo[]) => void

  • نتیجه

    اطلاعات هدف []

    آرایه‌ای از اشیاء TargetInfo مربوط به اهداف اشکال‌زدایی موجود.

بازگشت‌ها

• قول< TargetInfo []>

  کروم ۹۶+

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

sendCommand()

وعده

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

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

پارامترها

• هدف

  جلسه اشکال‌زدایی

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

• روش

  رشته

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

• پارامترهای فرمان

  شیء اختیاری

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (result?: object) => void

  • نتیجه

    شیء اختیاری

    شیء JSON با پاسخ. ساختار پاسخ بسته به نام متد متفاوت است و توسط ویژگی 'returns' از توضیحات دستور در پروتکل اشکال‌زدایی از راه دور تعریف می‌شود.

بازگشت‌ها

• قول <object | undefined>

  کروم ۹۶+

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

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onDetach

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

زمانی اجرا می‌شود که مرورگر، جلسه اشکال‌زدایی (debugging session) مربوط به تب را خاتمه می‌دهد. این اتفاق زمانی می‌افتد که یا تب بسته می‌شود یا Chrome DevTools برای تب پیوست شده فراخوانی می‌شود.

پارامترها

• تماس برگشتی

  تابع

  پارامتر callback به شکل زیر است:

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

  • منبع

    دیباگی

  • دلیل

    دلیل جدا کردن

onEvent

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

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

پارامترها

• تماس برگشتی

  تابع

  پارامتر callback به شکل زیر است:

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

  • منبع

    جلسه اشکال‌زدایی

  • روش

    رشته

  • پارامترها

    شیء اختیاری