الفرق بين المراجعتين ل"Node.js/console"
جميل-بيلوني (نقاش | مساهمات) (إضافة محتويات الصفحة.) |
ط |
||
(مراجعة متوسطة واحدة بواسطة مستخدم واحد آخر غير معروضة) | |||
سطر 93: | سطر 93: | ||
|- | |- | ||
|v10.0.0 | |v10.0.0 | ||
− | |أصبح تنفيذ هذا التابع متوافقًا مع التنسيق <code>spec</code> | + | |أصبح تنفيذ هذا التابع متوافقًا مع التنسيق <code>spec</code> ولم يعد يرمي أي شيء بعد الآن. |
|- | |- | ||
|v0.1.101 | |v0.1.101 | ||
سطر 391: | سطر 391: | ||
== مصادر == | == مصادر == | ||
* [https://nodejs.org/dist/latest-v10.x/docs/api/console.html صفحة console في توثيق Node.js الرسمي.] | * [https://nodejs.org/dist/latest-v10.x/docs/api/console.html صفحة console في توثيق Node.js الرسمي.] | ||
− | [[تصنيف:Node.js]] | + | [[تصنيف:Node.js|{{SUBPAGENAME}}]] |
المراجعة الحالية بتاريخ 12:27، 9 فبراير 2019
الاستقرار: 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(stdout[, stderr][, ignoreErrors])
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()
.