الوحدة Console‎ في Node.js

الاستقرار: 2-مستقر

توِّفر الوحدة console طرفيَّة بسيطة لتنقيح الأخطاء تشبه طرفيَّة JavaScript التي توفِّرها متصفحات الويب.

تنتج الوحدة عنصرين محدَّدين هما:

• الصنف Console مع توابعه مثل التوابع console.log()‎، و console.error()‎، و console.warn()‎ التي يمكن استعمالها للكتابة على أي مجرى من مجاري Node.js.
• نسخة الكائن console العامَّة المضبوطة للكتابة على المجرى process.stdout والمجرى process.stderr، ويمكن استعمالها دون استدعاء require('console')‎.

تحذير: لا تكون توابع الكائن console العام متزامنةً دومًا مثل واجهات المتصفح البرمجيَّة التي تشبهها، ولا غير متزامنةٍ دومًا مثل مجاري Node.js الأخرى. ارجع إلى القسم «ملاحظةٌ حول عمليَّة الإدخال والإخراج (I/O)»  للمزيد من المعلومات.

يشرح المثال التالي كيفيَّة استعمال الكائن console العام:

console.log('hello world');
// hello world :سيُطبع على مجرى الخرج القياسي
console.log('hello %s', 'world');
// hello world :سيُطبع على مجرى الخرج القياسي
console.error(new Error('Whoops, something bad happened'));
// [Error: Whoops, something bad happened] :سيُطبع على مجرى الخطأ القياسي

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Danger Will Robinson! Danger! :سيُطبع على مجرى الخطأ القياسي

بينما يشرح المثال التالي كيفيَّة استعمال الصنف Console:

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// hello world :out سيُطبع على المجرى
myConsole.log('hello %s', 'world');
// hello world :out سيُطبع على المجرى
myConsole.error(new Error('Whoops, something bad happened'));
// [Error: Whoops, something bad happened] :err سيُطبع على المجرى

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Danger Will Robinson! Danger! :err سيُطبع على المجرى

الصنف Console

سجل التغييرات

الإصدار	التغييرات
v8.0.0	ستتجاهل الأخطاء التي تحدث أثناء الكتابة على إحدى المجاري الضمنيَّة الآن بشكل افتراضي.

يمكن استعمال الصنف Console لإنشاء مسجِّل (logger) بسيط مع مجاري خرج قابلة للضبط ويمكن الوصول إليها باستعمال require('console')‎ أو console.Console (أو أي نظير مفكك [destructured counterpart] لهما).

const { Console } = require('console');
const { Console } = console;

new Console(options)‎

سجل التغييرات

الإصدار	التغييرات
v10.0.0	أصبح الكائن Console الباني الآن يدعم الوسيط options والذي أضيف إليه الخيار colorMode.
v8.0.0	أضيف الخيار ignoreErrors إلى الوسيط options.

• options: ‏<Object> كائن يدعم الخيارات التالية:
  • stdout: ‏<stream.Writable>
  • stderr: ‏<stream.Writable>
  • ignoreErrors: ‏<boolean> تحديد إن أريد تجاهل الأخطاء عند الكتابة على مجاري مُضمَّنة أم لا. القيمة الافتراضيَّة هي: true.
  • colorMode: ‏<boolean> | ‏<string> ضبط دعم اللون لنسخة Console. عندما يُضبَط هذا الخيار إلى القيمة true، ستُفعَّل الألوان أثناء فحص القيم. أما عند ضبطه إلى القيمة 'auto'، سيعتمد دعم اللون على قيمة الخاصِّيَّة isTTY والقيمة التي تعيدها الدالة getColorDepth()‎ عند استدعائها مع المجرى المقابل. القيمة الافتراضيَّة هي: 'auto'.

تنشئ هذه الدالة نسخة Console جديدة مع نسخة واحدة أو نسختين من مجرى يمكن الكتابة عليه. يعدُّ المجرى stdout (مجرى الخرج القياسي) مجرًى قابلًا للكتابة يستعمل لطباعة المخرجات الاعتياديَّة (معلومات وسجلات ...إلخ.). أما المجرى stderr (مجرى الخطأ القياسي)، فيُستعمَل لطباعة المخرجات المتعلقة بالتحذيرات والأخطاء. إن لم يكن المجرى stderr متاحًا، فيُستعمَل حيئنذٍ المجرى stdout عوضًا عنه.

const output = fs.createWriteStream('./stdout.log');
const errorOutput = fs.createWriteStream('./stderr.log');
// تخصيص مسجل بسيط
const logger = new Console({ stdout: output, stderr: errorOutput });
// استعماله كطرفية
const count = 5;
logger.log('count: %d', count);
// count 5 :stdout.log سيُطبع على المجرى

الكائن console العام هو حالة خاصَّة من Console، إذ تُرسَل المخرجات إلى process.stdout و process.stderr. هذا مكافئ للاستدعاء التالي:

new Console({ stdout: process.stdout, stderr: process.stderr });

console.assert(value[, ...message])‎

سجل التغييرات

الإصدار	التغييرات
v10.0.0	أصبح تنفيذ هذا التابع متوافقًا مع التنسيق spec ولن يعد يرمي أي شيء بعد الآن.
v0.1.101	أضيف هذا التابع.

• value: ‏<any> القيمة المراد فحصها للتحقُّق من كونها قيمة صحيحة (truthy).
• ‎...message: ‏<any> جميع الوسائط التي تعطى بعد الوسيط value تستعمل بوصفها رسالة خطأ.

يجري هذا التابع اختبار توكيد بسيط للتأكد إن كانت القيمة value المعطاة قيمةً صحيحة أم لا. إن لم تكن، فسيُرمَى الخطأ «Assertion failed». إن أعطيت أيَّة وسائط غير الوسيط value، فستُعدُّ رسالة خطأٍ وستُنسَّق باستعمال التابع util.format()‎ عبر تمرير جميع تلك الوسائط إليها. تستعمل المخرجات كرسالة خطأ أيضًا.

console.assert(true, 'does nothing');
// OK
console.assert(false, 'Whoops %s work', 'didn\'t');
// Assertion failed: Whoops didn't work

انتبه إلى أنَّ استدعاء console.assert()‎ مع قيمة خطأ (falsy value) سيتسبَّب في طباعة محتوى الوسيط ‎...message في الطرفيَّة دون مقاطعة تنفيذ العمليات اللاحقة في الشيفرة.

console.clear()‎

أضيف في الإصدار v8.3.0.

عندما يكون مجرى الخرج القياسي (stdout) هو TTY، فإنَّ استدعاء console.clear()‎ سيؤدي إلى مسح TTY. أمَّا إن لم يكن مجرى الخرج القياسي TTY، فإنَّ هذا التابع لا يستطيع فعل أي شيء.

تختلف آلية تنفيذ التابع console.clear()‎ باختلاف نظام التشغيل والطرفيَّة المستعملين. ففي أغلب أنظمة تشغيل لينكس، يعمل التابع console.clear()‎ بطريقة مشابهة لعمل الأمر clear في سطر الأوامر. أمَّا في ويندوز، فيعمل التابع console.clear()‎ على مسح المخرجات فقط من إطار عرض (viewport) الطرفية الحالي الذي يخص ملف Node.js التنفيذي.

console.count([label])‎

أضيف في الإصدار v8.3.0.

• label: ‏<string> العنوان المراد عدُّ المرَّات التي استدعي هذا التابع معه. القيمة الافتراضية هي: 'default'.

يعدُّ هذا التابع كم مرَّةً استُدعي مع الوسيط label المعطى ثمَّ يُظهِر النتيجة عبر مجرى الخرج القياسي.

> console.count()
default: 1
undefined
> console.count('default')
default: 2
undefined
> console.count('abc')
abc: 1
undefined
> console.count('xyz')
xyz: 1
undefined
> console.count('abc')
abc: 2
undefined
> console.count()
default: 3
undefined
>

console.countReset([label])‎

أضيف في الإصدار v8.3.0.

• label: ‏<string> العنوان المراد تصفير العداد الذي يعدُّ المرات التي استدعي التابع console.count()‎ معه. القيمة الافتراضية هي: 'default'.

يصفِّر هذا التابع العداد الداخلي الخاص بالوسيط label المعطى والذي يعدُّ المرات التي استدعي التابع console.count()‎ معه.

> console.count('abc');
abc: 1
undefined
> console.countReset('abc');
undefined
> console.count('abc');
abc: 1
undefined
>

console.debug(data[, ...args])‎

سجل التغييرات

الإصدار	التغييرات
v9.3.0	أصبح هذا التابع اسمًا بديلًا للتابع console.log()‎.
v8.0.0	أضيف هذا التابع.

• data: ‏<any>
• ‎...args: ‏<any>

هذا التابع هو اسم بديل للتابع console.log()‎.

console.dir(obj[, options])‎

أضيف في الإصدار v.0.1.101.

• obj: ‏<any>
• options: ‏<Object> كائنٌ يمكن أن يحتوي على الخيارات التالية:
  • showHidden: ‏<boolean> إن كانت هذه القيمة المنطقيَّة true، فستُظهَر الخاصِّيَّات الرمزية التي تكون من النوع Symbol وغير القابلة للإحصاء (non-enumerable) أيضًا. القيمة الافتراضية هي: false.
  • depth: ‏<number> يحدِّد هذا الخيار عدد مرات تكرار (recurse) التابع util.inspect()‎ أثناء تنسيق الكائن. هذا مفيد لفحص عدد كبير من الكائنات المعقَّدة. إن أردت تكرار التابع إلى أجل غير مسمى، فاضبط هذا الخيار إلى القيمة null. القيمة الافتراضيَّة هي: 2.
  • colors: ‏<boolean> إن كانت هذه القيمة المنطقية true، فستُنسَّق المخرجات تبعًا لألوان شيفرات ANSI. أضف إلى ذلك أنَّ الألوان قابلةٌ للتخصيص؛ ارجع إلى قسم «تخصيص ألوان util.inspect()‎». القيمة الافتراضية هي: false.

يستدعي هذا التابعُ التابعَ util.inspect()‎ مع الوسيط obj ثمَّ يطبع السلسلة النصية الناتجة عبر مجرى الخرج القياسي. يتجنَّب هذا التابع أيًّا من الدوال inspet()‎ المخصَّصة المُعرَّفة مع الوسيط obj.

console.dirxml(...data)‎

سجل التغييرات

الإصدار	التغييرات
v9.3.0	أصبح هذا التابع يستدعي التابع console.log()‎ مع وسائطه المعطاة.
v8.0.0	أضيف هذا التابع.

• ‎...data: ‏<any>

يستدعي هذا التابعُ التابعَ console.log()‎ مع تمرير الوسائط المعطاة إليه. انتبه رجاءً إلى أنَّ هذا التابع لا يُنتِج أي تنسيق يخص XML.

console.error([data][, ...args])‎

أضيف في الإصدار v.0.1.100.

• data ‏<any>
• ‎...args:‏ <any>

يُستعمَل هذا التابع للطباعة على مجرى الخطأ القياسي (stderr) مع إضافة محرف سطر جديد في النهاية. يمكن تمرير عدة وسائط إلى هذا التابع، إذ يمثِّل الوسيط الأول الرسالة الأساسيَّة وتمثِّل بقية الوسائط الإضافيَّة قيم الاستبدال (substitution values) وهذا مشابه للدالة printf(3)‎ (جميع الوسائط تمرر إلى التابع util.format()‎).

const code = 5;
console.error('error #%d', code);
// error #5 :سيُطبع على مجرى الخطأ القياسي
console.error('error', code);
// error 5 :سيُطبع على مجرى الخطأ القياسي

إن لم يُعثَر على عناصر تنسيقٍ (مثل ‎%d) في السلسلة النصيَّة الأولى، فسيُسدعى حينئذٍ التابع util.inspect()‎ مع كل وسيط وستكون قيم السلسلة النصية الناتجة مضافةً إلى بعضها. ارجع إلى التابع util.format()‎ للمزيد من المعلومات.

console.group([...label])‎

أضيف في الإصدار v8.5.0.

• ‎...label:‏ <any>

يزيد هذا التابع المسافات الفارغة للأسطر اللاحقة بمقدار مسافتين فارغتين.

إن مُرِّر إلى هذا التابع وسيط واحد أو أكثر، فستُطبع هذه الوسائط أولًا دون زيادة في المسافات.

console.groupCollapsed()‎

أضيف في الإصدار v8.5.0.

هذا التابع هو اسم بديل للتابع console.group()‎.

console.groupEnd()‎

أضيف في الإصدار v8.5.0.

يقلِّل هذا التابع المسافات الفارغة للأسطر اللاحقة بمقدار مسافتين فارغتين، إذ هو عكس التابع console.group()‎.

console.info([data][, ...args])‎

أضيف في الإصدار v0.1.100.

• data:‏ <any>
• ‎...args:‏ <any>

هذا التابع هو اسم بديل للتابع console.log()‎.

console.log([data][, ...args])‎

أضيف في الإصدار v0.1.100.

• data:‏ <any>
• ‎...args:‏ <any>

يستعمل هذا التابع للطباعة على مجرى الخرج القياسي (stdout) مع إضافة محرف سطر جديد في النهاية. يمكن تمرير عدَّة وسائط إلى هذا التابع، إذ يمثِّل الوسيط الأول الرسالة الأساسية وتمثِّل بقيَّة الوسائط الإضافية قيم الاستبدال (substitution values) وهذا مشابه للدالة printf(3)‎ (جميع الوسائط تمرر إلى التابع util.format()‎).

const count = 5;
console.log('count: %d', count);
// count: 5 :سيُطبع على مجرى الخرج القياسي
console.log('count:', count);
// count: 5 :سيُطبع على مجرى الخرج القياسي

انظر أيضًا التابع util.format()‎ للمزيد من المعلومات.

console.table(tabularData[, properties])‎

أضيف في الإصدار v10.0.0.

• tabularData:‏ <any>
• properties:‏ <string[]‎> خاصِّيَّات بديلة تستعمل في إنشاء الجدول.

يحاول هذا التابع إنشاء جدول أعمدته هي خاصِّيَّات الوسيط tabularData (أو الوسيط properties إن أعطي) وأسطره هي قيم الوسيط tabularData. إن لم يكن بالإمكان تحليل الوسيط ووضعه في جدول، فسيُطبع هذا الوسيط على مجرى الخرج القياسي فقط.

// لا يمكن تحليل ووضع البيانات التالية في جدول
console.table(Symbol());
// Symbol()

console.table(undefined);
// undefined

console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }]);
// ┌─────────┬─────┬─────┐
// │ (index) │  a  │  b  │
// ├─────────┼─────┼─────┤
// │    0    │  1  │ 'Y' │
// │    1    │ 'Z' │  2  │
// └─────────┴─────┴─────┘

console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']);
// ┌─────────┬─────┐
// │ (index) │  a  │
// ├─────────┼─────┤
// │    0    │  1  │
// │    1    │ 'Z' │
// └─────────┴─────┘

console.time([label])‎

أضيف في الإصدار v0.1.104.

• label: ‏<string> معرِّف المؤقِّت المراد بدء استعماله. القيمة الافتراضية هي: 'default'.

يُستعمَل هذا التابع مؤقتًّا لحساب زمن عملية معيَّنة. يخصَّص لكل مؤقِّت معرِّف فريد يدعى label، لذا استعمل المُعرِّف label نفسه عند استدعاء التابع console.timeEnd()‎ لإيقاف المؤقِّت وإظهار الوقت المستغرق بواحدة الميلي ثانية عبر مجرى الخرج القياسي. أضف إلى ذلك أنَّ دقة زمن المؤقت تصل إلى أجزاءٍ من الميلي ثانية.

console.timeEnd([label])‎

سجل التغييرات

الإصدار	التغييرات
v6.0.0	لم يعد هذا التابع يدعم استدعاءه عدة مرات دون تعيينه إلى استدعاءات سابقة فردية للتابع console.time()‎.
v0.1.104	أضيف هذا التابع.

• label:‏ <string> معرِّف المؤقِّت المراد إيقافه. القيمة الافتراضية هي: 'default'.

يوقف هذا التابع المؤقِّت الذي بدء عمله مسبقًا عند استدعاء التابع console.time()‎ ثمَّ يطبع الفترة الزمنيَّة على مجرى الخرج القياسي.

console.time('100-elements');
for (let i = 0; i < 100; i++) {}
console.timeEnd('100-elements');
// 100-elements: 225.438ms

console.timeLog([label][, ...data])‎

أضيف في الإصدار v10.7.0.

• label:‏ <string> مُعرِّف المؤقِّت المراد معرفة الوقت المنقضي الذي وصل إليه. القيمة الافتراضية هي: 'default'.
• ‎...data: ‏<any>

يطبع هذا التابع الوقت المنقضي للمؤقِّت label الذي شُغِّل مسبقًا عند استدعاء التابع console.time()‎ عبر مجرى الخرج القياسي. إن أعطي الوسيط ‎...data، فسيُضَاف محتواه إلى الوقت الناتج.

console.time('process');
const value = expensiveProcess1(); // 42
console.timeLog('process', value);
// "process: 365.227ms 42" :سيُطبع
doExpensiveProcess2(value);
console.timeEnd('process');

console.trace([message][, ...args])‎

أضيف في الإصدار 0.1.104.

• message: ‏<any>
• ‎...args:‏ <any>

يطبع هذا التابع على مجرى الخرج القياسي السلسلة النصية 'Trace: ‎' تليها قيمة المعامل message المنسَّقة باستعمال util.format()‎ وتعقبات المكدس (stack trace) حتى الموقع الحالي من الشيفرة.

console.trace('Show me');
// Prints: (stack trace will vary based on where trace is called)
//  Trace: Show me
//    at repl:2:9
//    at REPLServer.defaultEval (repl.js:248:27)
//    at bound (domain.js:287:14)
//    at REPLServer.runBound [as eval] (domain.js:300:12)
//    at REPLServer.<anonymous> (repl.js:412:12)
//    at emitOne (events.js:82:20)
//    at REPLServer.emit (events.js:169:7)
//    at REPLServer.Interface._onLine (readline.js:210:10)
//    at REPLServer.Interface._line (readline.js:549:8)
//    at REPLServer.Interface._ttyWrite (readline.js:826:14)

console.warn([data][, ...args])‎

أضيف في الإصدار v0.1.100.

• data:‏ <any>
• ‎...args:‏ <any>

هذا التابع هو اسمٌ بديلٌ للتابع console.error()‎.

توابع المراقب (inspector) فقط

يستطيع المراقب V8 مراقبة وعرض التوابع التالية في في الواجهة البرمجيَّة العامة (general API)، ولكن لا يمكن أن تَعرِض تلك التوابع أي شيء إلا إذا استعملت بالاقتران مع المراقب (الراية ‎--inspector).

console.markTimeline([label])‎

أضيف في الإصدار v8.0.0.

• label:‏ <string> القيمة الافتراضية هي: 'default'.

لا يُظهر هذا التابع أي شيء إلا إذا استُعمَل مع المراقب.

إن هذا التابع هو الشكل المهمل للتابع console.timeStamp()‎.

console.profile([label])‎

أضيف في الإصدار v8.0.0.

• label: ‏<string>

لا يُظهِر هذا التابع أي شيء إلا إذا استعمل مع المراقب.

يبدأ هذا التابع تسجيل أداء وحدة المعالجة المركزية CPU مع شيفرات JavaScript مع إمكانيَّة استعمال تسمية اختياريَّة، ويستمر حتى استدعاء التابع cosole.profileEnd()‎. يضاف بعدئذٍ الملف إلى لوحة سجل (Profile panel) المراقب.

console.profile('MyLabel');
// بعض الشيفرة
console.profileEnd('MyLabel');
// إلى لوحة ملفات المراقب 'MyLabel' إضافة الملف

console.profileEnd([label])‎

أضيف في الإصدار v8.0.0.

لا يُظهِر هذا التابع أي شيء إلا إذا استعمل مع المراقب.

يوقف هذا التابع جلسة تسجيل أداء وحدة المعالجة المركزية CPU مع شيفرات JavaScript التي بُدئَت من قبل ثمَّ يطبع التقرير في لوحة السجلات (Profiles panel) للمراقب. تفحَّص المثال الموجود في التابع console.profile()‎.

إن استُدعي هذا التابع دون تمرير تسمية label إليه، فسيُوقف التسجيل الأحدث.

console.timeStamp([label])‎

أضيف في الإصدار v8.0.0.

• label: ‏<string>

لا يُظهِر هذا التابع أي شيء إلا إذا استعمل مع المراقب.

يضيف هذا التابع حدثًا مع التسمية 'label' إلى اللوحة Timeline الخاصَّة بالمراقب.

console.timeline([label])‎

أضيف في الإصدار v8.0.0.

• label:‏ <string> معرِّف المؤقت المراد بدء استعماله. القيمة الافتراضية هي: 'default'.

لا يُظهِر هذا التابع أي شيء إلا إذا استُعمِل مع المراقب.

هذا التابع هو الشكل المهمل من التابع console.time()‎.

console.timelineEnd([label])‎

أضيف في الإصدار v8.0.0.

• label: ‏<string> مُعرِّف المؤقِّت المراد إيقافه. القيمة الافتراضية هي: 'default'.

لا يُظهِر هذا التابع أي شيء إلا إذا استعمل مع المراقب.

هذا التابع هو الشكل المهمل من التابع console.timelineEnd()‎.

مصادر

• صفحة console في توثيق Node.js الرسمي.