مرجع واجهة برمجة تطبيقات Console Utilities API

Kayce Basques
Kayce Basques
Sofia Emelianova
Sofia Emelianova

تحتوي واجهة Console Utilities API على مجموعة من الدوال المريحة لتنفيذ المهام الشائعة: اختيار عناصر DOM وفحصها، والاستعلام عن الكائنات، وعرض البيانات بتنسيق قابل للقراءة، وإيقاف المحلل وبدء تشغيله، ومراقبة أحداث DOM واستدعاءات الدوال، والمزيد.

هل تبحث عن console.log() وconsole.error() وبقية دوال console.*؟ يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات Console.

$_

تعرض الدالة $_ قيمة التعبير الذي تم تقييمه مؤخرًا.

في المثال التالي، يتم تقييم تعبير بسيط (2 + 2). بعد ذلك، يتم تقييم السمة $_ التي تحتوي على القيمة نفسها:

‫$_ هو التعبير الذي تم تقييمه مؤخرًا.

في المثال التالي، يحتوي التعبير الذي تم تقييمه في البداية على مصفوفة من الأسماء. عند تقييم $_.length للعثور على طول الصفيف، تتغيّر القيمة المخزّنة في $_ لتصبح آخر تعبير تم تقييمه، وهو 4:

يتغير $_ عند تقييم أوامر جديدة.

‫0 - 4 دولار أمريكي

تعمل الأوامر $0 و$1 و$2 و$3 و$4 كمرجع سابق لآخر خمسة عناصر في نموذج العناصر في المستند (بما في ذلك العناصر الزائفة مثل ::before أو ::after) التي تم فحصها ضمن لوحة العناصر أو آخر خمسة عناصر في الذاكرة المؤقتة في JavaScript تم اختيارها في لوحة "الملفات الشخصية". تعرض السمة $0 العنصر أو كائن JavaScript الذي تم اختياره مؤخرًا، بينما تعرض السمة $1 العنصر أو كائن JavaScript الذي تم اختياره قبل الأخير، وهكذا.

في المثال التالي، يتم اختيار عنصر img في لوحة العناصر. في لوحة وحدة التحكّم، تم تقييم $0 ويعرض العنصر نفسه:

مثال على 0 دولار أمريكي.

تعرض الصورة أدناه عنصرًا مختلفًا تم اختياره في الصفحة نفسها. يشير $0 الآن إلى العنصر المحدّد حديثًا، بينما يعرض $1 العنصر المحدّد سابقًا:

مثال على دولار أمريكي واحد

$(selector [, startNode])

تعرض الدالة $(selector) المرجع إلى عنصر DOM الأول الذي يتضمّن أداة اختيار لغة CSS المحدّدة. عند استدعاء هذه الدالة باستخدام وسيطة واحدة، تكون اختصارًا للدالة document.querySelector().

يعرض المثال التالي مرجعًا لأول عنصر <img> في المستند:

مثال على $('img').

انقر بزر الماوس الأيمن على النتيجة المعروضة واختَر إظهار في لوحة "العناصر" للعثور عليها في نموذج DOM، أو الانتقال إلى العرض لعرضها على الصفحة.

يعرض المثال التالي مرجعًا للعنصر المحدّد حاليًا ويعرض سمة 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.src);
}

عناصر مثال على استخدام<!-- 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(path [, startNode])

تعرض الدالة $x(path) مصفوفة من عناصر DOM التي تتطابق مع تعبير XPath المحدّد.

على سبيل المثال، يعرض ما يلي جميع عناصر <p> في الصفحة:

$x("//p")

مثال على استخدام أداة اختيار XPath

يعرض المثال التالي جميع عناصر <p> التي تحتوي على عناصر <a>:

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

مثال على استخدام أداة اختيار XPath أكثر تعقيدًا

على غرار دوال الاختيار الأخرى، تحتوي الدالة $x(path) على مَعلمة ثانية اختيارية، وهي startNode، تحدّد عنصرًا أو عقدة للبحث عن العناصر منها.

مثال على استخدام أداة اختيار XPath مع startNode

clear()‎

clear() يمحو سجلّ وحدة التحكّم.

clear();

copy(object)

ينسخ copy(object) تمثيل سلسلة للعنصر المحدّد إلى الحافظة.

copy($0);

debug(function)

عند استدعاء الدالة المحدّدة، يتم استدعاء مصحّح الأخطاء وإيقاف التنفيذ داخل الدالة في لوحة المصادر، ما يسمح بتتبُّع الرمز وتصحيح أخطائه.

debug(getData);

الكسر داخل دالة باستخدام debug().

استخدِم undebug(fn) لإيقاف الإيقاف المؤقت في الدالة، أو استخدِم واجهة المستخدم لإيقاف جميع نقاط الإيقاف.

لمزيد من المعلومات حول نقاط الإيقاف، يُرجى الاطّلاع على إيقاف الرمز مؤقتًا باستخدام نقاط الإيقاف.

dir(object)

تعرض الدالة dir(object) قائمة بأسلوب الكائن لجميع سمات الكائن المحدّد. هذه الطريقة هي اختصار لطريقة console.dir() في Console API.

يوضّح المثال التالي الفرق بين تقييم document.body مباشرةً في سطر الأوامر واستخدام dir() لعرض العنصر نفسه:

document.body;
dir(document.body);

تسجيل document.body مع دالة dir()‎ وبدونها

لمزيد من المعلومات، يُرجى الاطّلاع على الإدخال console.dir() في Console API.

dirxml(object)‎

تطبع الدالة dirxml(object) تمثيلاً بتنسيق XML للعنصر المحدّد، كما يظهر في لوحة العناصر. هذه الطريقة مماثلة للطريقة console.dirxml().

inspect(object/function)

يفتح inspect(object/function) العنصر أو الكائن المحدّد ويختاره في اللوحة المناسبة: إما لوحة العناصر لعناصر DOM أو لوحة "الملفات الشخصية" لكائنات كومة JavaScript.

يفتح المثال التالي document.body في لوحة العناصر:

inspect(document.body);

فحص عنصر باستخدام inspect()‎

عند تمرير دالة لفحصها، تفتح الدالة المستند في لوحة المصادر لكي تتمكّن من فحصه.

getAccessibleName(node)

تعرض الدالة getAccessibleName(node) اسم العنصر الظاهر على واجهة المستخدم الذي تم تحديده لعقدة DOM المحدّدة. هذا هو الاسم الذي تعلنه التكنولوجيا المساعدة، مثل قارئات الشاشة، للعنصر. على سبيل المثال، افحص زرًا في لوحة العناصر، ثم شغِّل:

getAccessibleName($0);

getAccessibleRole(node)

تعرض الدالة getAccessibleRole(node) دور تسهيل الاستخدام المحسوب لعقدة DOM المحدّدة، مثل 'button' أو 'link' أو 'heading'. على سبيل المثال، افحص عنصرًا في لوحة العناصر، ثم شغِّل:

getAccessibleRole($0);

getEventListeners(object)

تعرض الدالة getEventListeners(object) متتبِّعات الأحداث المسجّلة في العنصر المحدّد. القيمة المعروضة هي كائن يحتوي على مصفوفة لكل نوع حدث مسجَّل (click أو keydown، على سبيل المثال). تتألف كل مصفوفة من عناصر تصف المستمع المسجَّل لكل نوع. على سبيل المثال، يسرد ما يلي جميع متتبِّعات الأحداث المسجَّلة في كائن المستند:

getEventListeners(document);

ناتج استخدام getEventListeners()‎

إذا تم تسجيل أكثر من مستمع واحد على الكائن المحدد، فستحتوي المصفوفة على عضو لكل مستمع. في المثال التالي، هناك متتبِّعان للأحداث مسجَّلان في عنصر المستند للحدث click:

مستمعون متعددون

يمكنك توسيع كل من هذه العناصر لاستكشاف خصائصها:

عرض موسّع لكائن المستمع

لمزيد من المعلومات، يُرجى الاطّلاع على فحص خصائص العناصر.

keys(object)

تعرض الدالة keys(object) مصفوفة تحتوي على أسماء السمات التي تنتمي إلى الكائن المحدّد. للحصول على القيم المرتبطة بالسمات نفسها، استخدِم values().

على سبيل المثال، لنفترض أنّ تطبيقك حدّد العنصر التالي:

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

بافتراض أنّه تم تحديد player في مساحة الاسم العامة (للتبسيط)، ستؤدي كتابة keys(player) وvalues(player) في وحدة التحكّم إلى ما يلي:

مثال على الطريقتين ()keys و()values.

monitor(function)

عند استدعاء الدالة المحدّدة، يتم تسجيل رسالة في وحدة التحكّم تشير إلى اسم الدالة مع الوسيطات التي تم تمريرها إلى الدالة عند استدعائها.

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

مثال على طريقة monitor()‎

استخدِم unmonitor(function) لإيقاف المراقبة.

monitorEvents(object [, events])

عند حدوث أحد الأحداث المحدّدة في الكائن المحدّد، يتم تسجيل كائن الحدث في وحدة التحكّم. يمكنك تحديد حدث واحد لمراقبته، أو مصفوفة من الأحداث، أو أحد "أنواع" الأحداث العامة المرتبطة بمجموعة محدّدة مسبقًا من الأحداث. يُرجى مراجعة الأمثلة أدناه.

يرصد الرمز التالي جميع أحداث تغيير الحجم في عنصر النافذة.

monitorEvents(window, "resize");

مراقبة أحداث تغيير حجم النافذة

يحدّد ما يلي مصفوفة لمراقبة كل من حدثَي "تغيير الحجم" و "التمرير" في عنصر النافذة:

monitorEvents(window, ["resize", "scroll"])

يمكنك أيضًا تحديد أحد "أنواع" الأحداث المتاحة، وهي سلاسل يتم ربطها بمجموعات محدّدة مسبقًا من الأحداث. يسرد الجدول أدناه أنواع الأحداث المتاحة وعمليات ربط الأحداث المرتبطة بها:

نوع الحدث والأحداث المرتبطة به
ماوس"mousedown", "mouseup", "click", "dblclick", "mousemove", "mouseover", "mouseout", "mousewheel"
مفتاح"keydown", "keyup", "keypress", "textInput"
لمس"touchstart" و"touchmove" و"touchend" و"touchcancel"
التحكم"resize", "scroll", "zoom", "focus", "blur", "select", "change", "submit", "reset"

على سبيل المثال، يستخدم ما يلي نوع الحدث "key" لجميع الأحداث الرئيسية المقابلة في حقل نص الإدخال المحدّد حاليًا في لوحة العناصر.

monitorEvents($0, "key");

في ما يلي نموذج للإخراج بعد كتابة أحرف في حقل النص:

مراقبة الأحداث الرئيسية

استخدِم unmonitorEvents(object[, events]) لإيقاف المراقبة.

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

profile() تبدأ جلسة تحليل وحدة المعالجة المركزية (CPU) في JavaScript باسم اختياري. profileEnd() عملية إنشاء الملف الشخصي، ويفتح لوحة الأداء تلقائيًا، ويعرض النتائج في المسار الرئيسي.

لبدء عملية تحليل الملف الشخصي:

profile("Profile 1")

لإيقاف عملية التحليل والاطّلاع على النتائج في مسار الأداء > الرئيسي:

profileEnd("Profile 1")

النتيجة في قناة الأداء > الرئيسية:

الملف الشخصي 1 في المسار الرئيسي للأداء

يمكن أيضًا دمج الملفات الشخصية. على سبيل المثال، سيعمل هذا بأي ترتيب:

profile('A');
profile('B');
profileEnd('A');
profileEnd('B');

queryObjects(Constructor)

يمكنك استدعاء queryObjects(Constructor) من وحدة التحكّم لعرض مصفوفة من العناصر التي تم إنشاؤها باستخدام الدالة الإنشائية المحدّدة. على سبيل المثال:

  • ‫queryObjects(Promise): تعرض جميع نُسخ Promise.
  • ‫queryObjects(HTMLElement): تعرض جميع عناصر HTML.
  • ‫queryObjects(foo)، حيث foo هو اسم الصف. تعرض هذه السمة جميع الكائنات التي تم إنشاء مثيل لها من خلال new foo().

نطاق queryObjects() هو سياق التنفيذ المحدّد حاليًا في وحدة التحكّم.

table(data [, columns])

تسجيل بيانات الكائن بتنسيق جدول من خلال تمرير كائن بيانات مع عناوين أعمدة اختيارية هذا اختصار لـ console.table().

على سبيل المثال، لعرض قائمة بالأسماء باستخدام جدول في وحدة التحكّم، يمكنك إجراء ما يلي:

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

مثال على طريقة table()‎

لنسخ جدول مسجَّل إلى الحافظة كجدول Markdown منسَّق أو بيانات CSV، انقر بزر الماوس الأيمن على الجدول في وحدة التحكّم واختَر خيار النسخ المناسب من قائمة السياق.

undebug(function)

توقف الدالة undebug(function) تصحيح أخطاء الدالة المحدّدة، وبالتالي لا يتم استدعاء مصحّح الأخطاء عند استدعاء الدالة. يتم استخدام هذه السياسة مع سياسة debug(fn).

undebug(getData);

unmonitor(function)

يوقف unmonitor(function) مراقبة الدالة المحدّدة. يتم استخدام هذه السياسة مع سياسة monitor(fn).

unmonitor(getData);

unmonitorEvents(object [, events])

يتوقف unmonitorEvents(object[, events]) عن مراقبة الأحداث للعنصر والأحداث المحدّدة. على سبيل المثال، يؤدي ما يلي إلى إيقاف جميع عمليات مراقبة الأحداث على كائن النافذة:

unmonitorEvents(window);

يمكنك أيضًا إيقاف مراقبة أحداث معيّنة على عنصر بشكل انتقائي. على سبيل المثال، يبدأ الرمز التالي في مراقبة جميع أحداث الماوس على العنصر المحدّد حاليًا، ثم يتوقف عن مراقبة أحداث "mousemove" (ربما لتقليل التشويش في مخرجات وحدة التحكم):

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

values(object)

تعرض الدالة values(object) مصفوفة تحتوي على قيم جميع السمات التي تنتمي إلى الكائن المحدّد.

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

values(player);

نتيجة القيم (اللاعب)