مرجع API Console Utilities

کیس باسک
Kayce Basques
X GitHub
صوفیا املیانووا
Sofia Emelianova
GitHub

API کنسول یوتیلیتیز شامل مجموعه‌ای از توابع کاربردی برای انجام وظایف رایج است: انتخاب و بررسی عناصر DOM، پرس‌وجو از اشیاء، نمایش داده‌ها در قالب قابل خواندن، متوقف کردن و شروع پروفایلر، نظارت بر رویدادهای DOM و فراخوانی‌های تابع و موارد دیگر.

دنبال توابع console.log() ، console.error() و بقیه توابع console.* می‌گردید؟ به مرجع API کنسول مراجعه کنید.

دلار_

$_ ‎ مقدار آخرین عبارت ارزیابی شده را برمی‌گرداند.

در مثال زیر، یک عبارت ساده ( 2 + 2 ) ارزیابی می‌شود. سپس ویژگی $_ ارزیابی می‌شود که حاوی همان مقدار است:

‎$_‎ آخرین عبارتی است که ارزیابی شده است.

در مثال بعدی، عبارت ارزیابی‌شده در ابتدا شامل آرایه‌ای از نام‌ها است. با ارزیابی $_.length برای یافتن طول آرایه، مقدار ذخیره‌شده در $_ تغییر می‌کند تا به آخرین عبارت ارزیابی‌شده تبدیل شود، ۴:

‎$_‎ هنگام ارزیابی دستورات جدید تغییر می‌کند.

۰ تا ۴ دلار

دستورات $0 ، $1 ، $2 ، $3 و $4 به عنوان یک مرجع تاریخی به پنج عنصر DOM آخر بررسی شده در پنل Elements یا پنج شیء heap جاوا اسکریپت آخر انتخاب شده در پنل Profiles عمل می‌کنند. $0 عنصر یا شیء جاوا اسکریپتی که اخیراً انتخاب شده است را برمی‌گرداند، $1 دومین عنصر یا شیء جاوا اسکریپتی که اخیراً انتخاب شده است را برمی‌گرداند و به همین ترتیب ادامه می‌یابد.

در مثال زیر، یک عنصر img در پنل Elements انتخاب شده است. در کشوی Console ، $0 ارزیابی شده و همان عنصر را نمایش می‌دهد:

مثال ۰ دلار.

تصویر زیر عنصر دیگری را نشان می‌دهد که در همان صفحه انتخاب شده است. اکنون $0 به عنصری که اخیراً انتخاب شده اشاره دارد، در حالی که $1 عنصری را که قبلاً انتخاب شده است برمی‌گرداند:

مثال ۱ دلار.

$(انتخابگر [، startNode])

$(selector) ‎ ارجاع به اولین عنصر DOM با انتخابگر CSS مشخص شده را برمی‌گرداند. وقتی این تابع با یک آرگومان فراخوانی شود، میانبری برای تابع ‎document.querySelector() ‎ خواهد بود.

مثال زیر یک ارجاع به اولین عنصر <img> در سند برمی‌گرداند:

مثالی از ‎$('img').‎

روی نتیجه‌ی برگشتی کلیک راست کرده و گزینه‌ی «آشکارسازی در پنل عناصر» (Reveal in Elements Panel) را انتخاب کنید تا آن را در DOM پیدا کنید، یا برای نمایش آن در صفحه، به قسمت «مشاهده» (View) بروید .

مثال زیر یک ارجاع به عنصر انتخاب شده‌ی فعلی برمی‌گرداند و ویژگی src آن را نمایش می‌دهد:

مثال ‎$('img').src‎

این تابع همچنین از پارامتر دومی به startNode پشتیبانی می‌کند که یک «عنصر» یا گره را برای جستجوی عناصر مشخص می‌کند. مقدار پیش‌فرض این پارامتر document است.

مثال زیر یک ارجاع به اولین عنصر img که از نوادگان devsite-header-background است را برمی‌گرداند و ویژگی src آن را نمایش می‌دهد:

مثالی از ‎$('img', div).src.‎

$$(selector [, startNode])

$$(selector) آرایه‌ای از عناصر را برمی‌گرداند که با سلکتور CSS داده شده مطابقت دارند. این دستور معادل فراخوانی Array.from( document.querySelectorAll() ) است.

مثال زیر استفاده می‌کند $$() to create an array of all <img> elements in the current document and displays the value of each element's src property:

let images = $$( 'img' ); for ( let each of images ) {  console . log ( each . }​​

مثالی از استفاده از <!-- notranslate l10n-placeholder: l10n-placeholder3 -->()</code> برای ایجاد آرایه‌ای از تمام <code translate= عناصر <img> که در سند فعلی پس از گره انتخاب شده ظاهر می‌شوند:

let images = $$('img', document.querySelector('.devsite-header-background'));
for (let each of images) {
  console.log(each.src);
}

مثالی از استفاده از $() برای انتخاب تمام تصاویری که بعد از عنصر div انتخاب شده در سند ظاهر می‌شوند و نمایش منابع آنها.

$x(مسیر [، گره شروع])

$x(path) ‎ آرایه‌ای از عناصر DOM را که با عبارت XPath داده شده مطابقت دارند، برمی‌گرداند.

برای مثال، کد زیر تمام عناصر <p> موجود در صفحه را برمی‌گرداند:

$x("//p")

مثالی از استفاده از انتخابگر XPath.

مثال زیر تمام عناصر <p> که شامل عناصر <a> هستند را برمی‌گرداند:

$x("//p[a]")

مثالی از استفاده از یک انتخابگر XPath پیچیده‌تر.

مشابه سایر توابع انتخابگر، $x(path) ‎ یک پارامتر دوم اختیاری به نام startNode دارد که یک عنصر یا گره را برای جستجوی عناصر مشخص می‌کند.

مثالی از استفاده از انتخابگر XPath با startNode.

پاک کردن()

clear() تاریخچه‌ی کنسول را پاک می‌کند.

clear();

کپی (شیء)

copy(object) یک رشته از شیء مشخص شده را در کلیپ بورد کپی می‌کند.

copy($0);

اشکال‌زدایی (تابع)

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

debug(getData);

شکستن کد درون یک تابع با استفاده از debug().

برای متوقف کردن وقفه در تابع، از undebug(fn) استفاده کنید، یا از رابط کاربری برای غیرفعال کردن همه نقاط توقف استفاده کنید.

برای اطلاعات بیشتر در مورد نقاط شکست، به بخش «کد خود را با نقاط شکست متوقف کنید» مراجعه کنید.

دایرکتوری (شیء)

dir(object) فهرستی از تمام ویژگی‌های شیء مشخص‌شده را به سبک شیء نمایش می‌دهد. این متد، میانبری برای متد console.dir() از API کنسول است.

مثال زیر تفاوت بین ارزیابی مستقیم document.body در خط فرمان و استفاده از dir() برای نمایش همان عنصر را نشان می‌دهد: 

document.body;
dir(document.body);

ثبت سند document.body با و بدون تابع dir()‎

برای اطلاعات بیشتر، به ورودی console.dir() در Console API مراجعه کنید.

dirxml(شیء)

dirxml(object) یک نمایش XML از شیء مشخص شده را چاپ می‌کند، همانطور که در پنل Elements دیده می‌شود. این متد معادل متد console.dirxml() است.

بازرسی (شیء/تابع)

inspect(object/function) عنصر یا شیء مشخص شده را در پنل مناسب باز می‌کند و انتخاب می‌کند: یا پنل Elements برای عناصر DOM یا پنل Profiles برای اشیاء heap جاوا اسکریپت.

مثال زیر document.body را در پنل Elements باز می‌کند: 

inspect(document.body);

بررسی یک عنصر با استفاده از inspect().

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

getEventListeners(شیء)

getEventListeners(object) شنونده‌های رویداد ثبت‌شده روی شیء مشخص‌شده را برمی‌گرداند. مقدار بازگشتی، شیء‌ای است که شامل یک آرایه برای هر نوع رویداد ثبت‌شده (مثلاً click یا keydown ) است. اعضای هر آرایه، اشیایی هستند که شنونده ثبت‌شده برای هر نوع را توصیف می‌کنند. برای مثال، در زیر تمام شنونده‌های رویداد ثبت‌شده روی شیء document فهرست شده‌اند: 

getEventListeners(document);

خروجی استفاده از getEventListeners().

اگر بیش از یک شنونده روی شیء مشخص شده ثبت شده باشد، آرایه شامل یک عضو برای هر شنونده است. در مثال زیر، دو شنونده رویداد روی عنصر سند برای رویداد click ثبت شده‌اند:

شنوندگان متعدد.

می‌توانید هر یک از این اشیاء را بیشتر بسط دهید تا ویژگی‌های آنها را بررسی کنید:

نمای گسترده از شیء شنونده.

برای اطلاعات بیشتر، به بررسی ویژگی‌های شیء مراجعه کنید.

کلیدها (شیء)

keys(object) آرایه‌ای شامل نام ویژگی‌های متعلق به شیء مشخص شده را برمی‌گرداند. برای دریافت مقادیر مرتبط با همان ویژگی‌ها، values() استفاده کنید.

برای مثال، فرض کنید برنامه شما شیء زیر را تعریف کرده است: 

let player = {
    "name": "Parzival",
    "number": 1,
    "state": "ready",
    "easterEggs": 3
};

با فرض اینکه player در فضای نام سراسری تعریف شده باشد (برای سادگی)، تایپ keys(player) و values(player) در کنسول منجر به موارد زیر می‌شود:

مثالی از متدهای keys() و values()

مانیتور (تابع)

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

function sum(x, y) {
  return x + y;
}
monitor(sum);

مثالی از متد monitor().

برای متوقف کردن نظارت unmonitor(function) استفاده کنید.

monitorEvents(شیء [، رویدادها])

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

کد زیر تمام رویدادهای تغییر اندازه روی شیء پنجره را رصد می‌کند. 

monitorEvents(window, "resize");

نظارت بر رویدادهای تغییر اندازه پنجره.

کد زیر یک آرایه برای نظارت بر رویدادهای "تغییر اندازه" و "اسکرول" روی شیء پنجره تعریف می‌کند: 

monitorEvents(window, ["resize", &quot;scroll"])

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

نوع رویداد و رویدادهای نگاشت‌شده‌ی متناظر
موش "download"، "mouseup"، "click"، "dblclick"، "mousemove"، "mouseover"، "mouseout"، "چرخ ماوس"
کلید «کلید پایین»، «کلید بالا»، «فشردن کلید»، «ورودی متن»
لمس کردن «شروع لمسی»، «حرکت لمسی»، «پایان لمسی»، «لغو لمسی»
کنترل «تغییر اندازه»، «اسکرول»، «زوم»، «فوکوس»، «تاری»، «انتخاب»، «تغییر»، «ارسال»، «تنظیم مجدد»

برای مثال، در مثال زیر از نوع رویداد "key" برای تمام رویدادهای کلید مربوطه در یک فیلد متنی ورودی که در حال حاضر در پنل Elements انتخاب شده است، استفاده می‌شود. 

monitorEvents($0, "key");

در زیر نمونه خروجی پس از تایپ یک کاراکتر در فیلد متن را مشاهده می‌کنید:

نظارت بر رویدادهای کلیدی

برای متوقف کردن نظارت از unmonitorEvents(object[, events]) استفاده کنید.

profile([name]) و profileEnd([name])

profile() یک جلسه پروفایلینگ CPU جاوا اسکریپت را با یک نام اختیاری آغاز می‌کند. profileEnd() پروفایل را تکمیل کرده و نتایج را در مسیر Performance > Main نمایش می‌دهد.

برای شروع نمایه‌سازی: 

profile("Profile 1")

برای متوقف کردن پروفایلینگ و مشاهده نتایج در Performance > Main track: 

profileEnd("Profile 1")

نتیجه در مسیر Performance > Main track:

پروفایل ۱ در مسیر اصلی عملکرد.

پروفایل‌ها را می‌توان به صورت تو در تو نیز تعریف کرد. برای مثال، این روش به هر ترتیبی کار خواهد کرد: 

profile('A');
profile('B');
profileEnd('A&#39;);
profileEnd('B');

queryObjects(سازنده)

برای برگرداندن آرایه‌ای از اشیاء که با سازنده‌ی مشخص شده ایجاد شده‌اند، از کنسول queryObjects(Constructor) فراخوانی کنید. برای مثال:

  • queryObjects(Promise) . تمام نمونه‌های Promise را برمی‌گرداند.
  • queryObjects(HTMLElement) . تمام عناصر HTML را برمی‌گرداند.
  • queryObjects(foo) ، که در آن foo نام کلاس است. تمام اشیاء نمونه‌سازی شده از طریق new foo() را برمی‌گرداند.

دامنه‌ی queryObjects() زمینه‌ی اجرایی انتخاب‌شده‌ی فعلی در کنسول است.

جدول (داده‌ها [، ستون‌ها])

داده‌های شیء را با قالب‌بندی جدول، با ارسال یک شیء داده با عنوان‌های ستون اختیاری، ثبت کنید. این یک میانبر برای console.table() است.

برای مثال، برای نمایش لیستی از نام‌ها با استفاده از یک جدول در کنسول، باید به صورت زیر عمل کنید: 

let names = [
  { firstName: "John", lastName: "Smith" },
  { firstName: "Jane", lastName: "Doe" },
];
table(names);

مثالی از متد table().

رفع اشکال (تابع)

undebug(function) اشکال‌زدایی تابع مشخص‌شده را متوقف می‌کند، به‌طوری‌که وقتی تابع فراخوانی می‌شود، اشکال‌زدا دیگر فراخوانی نمی‌شود. این تابع همراه با debug(fn) استفاده می‌شود. 

undebug(getData);

غیر مانیتور (تابع)

unmonitor(function) نظارت بر تابع مشخص شده را متوقف می‌کند. این تابع به همراه monitor(fn) استفاده می‌شود. 

unmonitor(getData);

unmonitorEvents(شیء [، رویدادها])

unmonitorEvents(object[, events]) نظارت بر رویدادها را برای شیء و رویدادهای مشخص شده متوقف می‌کند. برای مثال، کد زیر تمام نظارت بر رویدادها را روی شیء window متوقف می‌کند: 

unmonitorEvents(window);

همچنین می‌توانید به صورت انتخابی، نظارت بر رویدادهای خاص روی یک شیء را متوقف کنید. برای مثال، کد زیر شروع به نظارت بر تمام رویدادهای ماوس روی عنصر انتخاب شده فعلی می‌کند و سپس نظارت بر رویدادهای "mousemove" را متوقف می‌کند (شاید برای کاهش نویز در خروجی کنسول): 

monitorEvents($0, "mouse");
unmonitorEvents($0, &quot;mousemove");

مقادیر (شیء)

values(object) آرایه‌ای شامل مقادیر تمام ویژگی‌های متعلق به شیء مشخص شده را برمی‌گرداند. 

let player = {
    "name": "Parzival",
    "number": 1,
    "state": "ready",
    "easterEggs": 3
};

values(player);

نتیجه مقادیر (بازیکن).