وحدة التحكم

[مستقر: 2 - مستقر]

رمز المصدر: lib/console.js

توفر وحدة node:console وحدة تحكم تصحيح أخطاء بسيطة تشبه آلية وحدة تحكم JavaScript التي توفرها متصفحات الويب.

تصدر الوحدة مكونين محددين:

فئة Console مع طرق مثل console.log(), console.error(), و console.warn() التي يمكن استخدامها للكتابة إلى أي دفق Node.js.
مثيل عالمي console مُهيأ للكتابة إلى process.stdout و process.stderr. يمكن استخدام وحدة التحكم العالمية console دون استدعاء require('node:console').

تحذير: طرق كائن وحدة التحكم العالمية ليست متزامنة باستمرار مثل واجهات برمجة التطبيقات المتصفح التي تشبهها، كما أنها ليست غير متزامنة باستمرار مثل جميع دفقات Node.js الأخرى. يجب على البرامج التي ترغب في الاعتماد على السلوك المتزامن/غير المتزامن لوظائف وحدة التحكم أولاً معرفة طبيعة دفق وحدة التحكم الأساسي. وذلك لأن الدفق يعتمد على النظام الأساسي الأساسي وتكوين الدفق القياسي للعملية الحالية. راجع ملاحظة حول مدخلات/مخرجات العملية لمزيد من المعلومات.

مثال باستخدام وحدة التحكم العالمية console:

console.log('hello world')
// يُطبع: hello world، إلى stdout
console.log('hello %s', 'world')
// يُطبع: hello world، إلى stdout
console.error(new Error('Whoops, something bad happened'))
// يُطبع رسالة الخطأ ومسار المكدس إلى stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson'
console.warn(`Danger ${name}! Danger!`)
// يُطبع: Danger Will Robinson! Danger!، إلى stderr

مثال باستخدام فئة 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 لإنشاء مسجل بسيط مع تدفقات إخراج قابلة للتكوين، ويمكن الوصول إليه باستخدام require('node:console').Console أو console.Console (أو نظرائهم المفككين):

ESMCJS

import { Console } from 'node:console'

const { Console } = require('node:console')

const { Console } = console

`Console(stdout[, stderr][, ignoreErrors]) الجديد`

`Console(options) الجديد`

[السجل]

الإصدار	التغييرات
v14.2.0، v12.17.0	تم تقديم خيار `groupIndentation`.
v11.7.0	تم تقديم خيار `inspectOptions`.
v10.0.0	يدعم مُنشئ `Console` الآن وسيطة `options`، وتم تقديم خيار `colorMode`.
v8.0.0	تم تقديم خيار `ignoreErrors`.

options <Object>
- stdout <stream.Writable>
- stderr <stream.Writable>
- ignoreErrors <boolean> تجاهل الأخطاء عند الكتابة إلى التدفقات الأساسية. الافتراضي: true.
- colorMode <boolean> | <string> ضبط دعم الألوان لهذه مثيل Console. يؤدي الضبط على true إلى تمكين التلوين أثناء فحص القيم. يؤدي الضبط على false إلى تعطيل التلوين أثناء فحص القيم. يؤدي الضبط على 'auto' إلى جعل دعم الألوان يعتمد على قيمة خاصية isTTY والقيمة التي تم إرجاعها بواسطة getColorDepth() على التدفق المعني. لا يمكن استخدام هذا الخيار، إذا تم تعيين inspectOptions.colors أيضًا. الافتراضي: 'auto'.
- inspectOptions <Object> يحدد الخيارات التي يتم تمريرها إلى util.inspect().
- groupIndentation <number> ضبط مسافة بادئة المجموعة. الافتراضي: 2.

ينشئ Console جديدًا بمثيل أو مثيلين من تدفقات الكتابة. stdout هو تدفق كتابة لطباعة إخراج السجل أو المعلومات. يتم استخدام stderr لإخراج التحذيرات أو الأخطاء. إذا لم يتم توفير stderr، فسيتم استخدام stdout لـ stderr.

ESMCJS

import { createWriteStream } from 'node:fs'
import { Console } from 'node:console'
// بدلاً من ذلك
// const { Console } = console;

const output = createWriteStream('./stdout.log')
const errorOutput = createWriteStream('./stderr.log')
// مسجل بسيط مخصص
const logger = new Console({ stdout: output, stderr: errorOutput })
// استخدامه مثل وحدة التحكم
const count = 5
logger.log('count: %d', count)
// في stdout.log: count 5

const fs = require('node:fs')
const { Console } = require('node:console')
// بدلاً من ذلك
// const { Console } = console;

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)
// في stdout.log: count 5

وحدة التحكم العالمية console هي Console خاصة يتم إرسال إخراجها إلى process.stdout و process.stderr. وهي تعادل الاتصال بما يلي:

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

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

[السجل]

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

value <أي> القيمة التي يتم اختبار صحتها.
...message <أي> تُستخدم جميع الوسائط بخلاف value كرسالة خطأ.

يكتب console.assert() رسالة إذا كانت value خاطئة أو تم حذفها. إنها تكتب رسالة فقط ولا تؤثر على التنفيذ بخلاف ذلك. يبدأ الإخراج دائمًا بـ "Assertion failed". إذا تم توفيره، يتم تنسيق message باستخدام util.format().

إذا كانت value صحيحة، فلن يحدث شيء.

console.assert(true, 'does nothing')

console.assert(false, 'Whoops %s work', "didn't")
// Assertion failed: Whoops didn't work

console.assert()
// Assertion failed

`console.clear()`

تمت الإضافة في: v8.3.0

عندما يكون stdout عبارة عن TTY، فإن استدعاء console.clear() سيحاول مسح TTY. عندما لا يكون stdout عبارة عن TTY، فإن هذه الطريقة لا تفعل شيئًا.

يمكن أن تختلف عملية console.clear() المحددة عبر أنظمة التشغيل وأنواع المحطات. بالنسبة لمعظم أنظمة تشغيل Linux، تعمل console.clear() بشكل مشابه لأمر clear في shell. على نظام Windows، ستمسح console.clear() فقط الإخراج في نافذة عرض المحطة الحالية لملف Node.js الثنائي.

`console.count([label])`

تمت الإضافة في: v8.3.0

label <سلسلة> تسمية العرض للعداد. الافتراضي: 'default'.

يحافظ على عداد داخلي خاص بـ label ويُخرج إلى stdout عدد مرات استدعاء console.count() باستخدام 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> تسمية العرض للعداد. الافتراضي: 'default'.

يعيد تعيين العداد الداخلي المحدد لـ label.

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

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

[History]

الإصدار	التغييرات
v8.10.0	أصبحت `console.debug` الآن اسمًا مستعارًا لـ `console.log`.
v8.0.0	مضاف في: v8.0.0

data <any>
...args <any>

دالة console.debug() هي اسم مستعار لـ console.log().

`console.dir(obj[, options])`

مضاف في: v0.1.101

obj <any>
options <Object>
- showHidden <boolean> إذا كانت true، فسيتم عرض خصائص الكائن غير القابلة للعد ورمزية أيضًا. الافتراضي: false.
- depth <number> يخبر util.inspect() عدد مرات التكرار أثناء تنسيق الكائن. هذا مفيد لفحص الكائنات الكبيرة والمعقدة. لجعله يتكرر إلى أجل غير مسمى، مرر null. الافتراضي: 2.
- colors <boolean> إذا كانت true، فسيتم تصميم الإخراج باستخدام رموز ألوان ANSI. الألوان قابلة للتخصيص؛ راجع تخصيص ألوان util.inspect(). الافتراضي: false.

يستخدم util.inspect() على obj ويطبع السلسلة الناتجة إلى stdout. تتجاوز هذه الدالة أي دالة inspect() مخصصة مُعرّفة على obj.

`console.dirxml(...data)`

[History]

الإصدار	التغييرات
v9.3.0	أصبحت `console.dirxml` الآن تستدعي `console.log` للحجج الخاصة بها.
v8.0.0	تمت الإضافة في: v8.0.0

...data <أي>

تستدعي هذه الطريقة console.log() مع تمرير الحجج المُستقبَلة إليها. لا تُنتج هذه الطريقة أي تنسيق XML.

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

تمت الإضافة في: v0.1.100

data <أي>
...args <أي>

يطبع إلى stderr مع سطر جديد. يمكن تمرير حجج متعددة، حيث يتم استخدام الحجة الأولى كرسالة أساسية ويتم استخدام جميع الحجج الإضافية كقيم بديلة مشابهة لـ printf(3) (يتم تمرير جميع الحجج إلى util.format()).

const code = 5
console.error('error #%d', code)
// يطبع: error #5، إلى stderr
console.error('error', code)
// يطبع: error 5، إلى stderr

إذا لم يتم العثور على عناصر التنسيق (مثل %d) في السلسلة الأولى، فسيتم استدعاء util.inspect() على كل حجة، ويتم دمج قيم السلاسل الناتجة. راجع util.format() لمزيد من المعلومات.

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

تمت الإضافة في: v8.5.0

...label <أي>

يزيد من مسافة البادئة للأسطر اللاحقة بمسافات لطول groupIndentation.

إذا تم توفير واحد أو أكثر من label، فسيتم طباعتها أولاً بدون مسافة بادئة إضافية.

`console.groupCollapsed()`

تمت الإضافة في: v8.5.0

اسم مستعار لـ console.group().

`console.groupEnd()`

تمت الإضافة في: v8.5.0

يقلل من مسافة البادئة للأسطر اللاحقة بمسافات لطول groupIndentation.

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

مضاف في: v0.1.100

data <أي>
...args <أي>

دالة console.info() هي اسم آخر للدالة console.log().

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

مضاف في: v0.1.100

data <أي>
...args <أي>

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

const count = 5
console.log('count: %d', count)
// يطبع: count: 5، إلى stdout
console.log('count:', count)
// يطبع: count: 5، إلى stdout

راجع util.format() لمزيد من المعلومات.

`console.table(tabularData[, properties])`

مضاف في: v10.0.0

tabularData <أي>
properties <مصفوفة سلاسل> خصائص بديلة لإنشاء الجدول.

حاول إنشاء جدول باستخدام أعمدة خصائص 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() لإيقاف المؤقت وإخراج الوقت المنقضي بوحدات زمنية مناسبة إلى stdout. على سبيل المثال، إذا كان الوقت المنقضي هو 3869 مللي ثانية، فسيعرض console.timeEnd() "3.869s".

`console.timeEnd([label])`

[السجل]

الإصدار	التغييرات
v13.0.0	يتم عرض الوقت المنقضي بوحدة زمنية مناسبة.
v6.0.0	لم تعد هذه الطريقة تدعم المكالمات المتعددة التي لا تتوافق مع مكالمات `console.time()` الفردية؛ انظر أدناه للحصول على التفاصيل.
v0.1.104	مضاف في: v0.1.104

label <string> افتراضي: 'default'

يوقف مؤقتًا تم بدء تشغيله مسبقًا من خلال استدعاء console.time() ويطبع النتيجة إلى stdout:

console.time('bunch-of-stuff')
// قم ببعض الأشياء.
console.timeEnd('bunch-of-stuff')
// يطبع: bunch-of-stuff: 225.438ms

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

مضاف في: v10.7.0

label <string> افتراضي: 'default'
...data <any>

بالنسبة لمؤقت تم بدء تشغيله مسبقًا من خلال استدعاء console.time()، فإنه يطبع الوقت المنقضي وحجج data الأخرى إلى stdout:

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

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

مضاف في: v0.1.104

message <any>
...args <any>

يطبع إلى stderr السلسلة 'Trace: '، متبوعًا برسالة مُنسّقة util.format() ومسار المكدس إلى الموضع الحالي في التعليمات البرمجية.

console.trace('Show me')
// يطبع: (سيتغير مسار المكدس بناءً على مكان استدعاء التتبع)
//  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.warn() هي اسم آخر لدالة console.error().

طرق مُفتّشة فقط

الطرق التالية مُعرّفة بواسطة محرّك V8 في واجهة برمجة التطبيقات العامة، لكنها لا تُظهر أي شيء ما لم تُستخدم بالتزامن مع المُفتّش (--inspect flag).

`console.profile([label])`

مضاف في: v8.0.0

label <string>

لا تُظهر هذه الطريقة أي شيء ما لم تُستخدم في المُفتّش. تبدأ طريقة console.profile() ملف تعريف وحدة المعالجة المركزية لـ JavaScript مع تسمية اختيارية حتى يتم استدعاء console.profileEnd(). ثم يتم إضافة الملف الشخصي إلى لوحة الملف الشخصي في المُفتّش.

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

`console.profileEnd([label])`

مضاف في: v8.0.0

label <string>

لا تُظهر هذه الطريقة أي شيء ما لم تُستخدم في المُفتّش. تُوقف جلسة تحديد ملف تعريف وحدة المعالجة المركزية الحالية لـ JavaScript إذا تم بدء واحدة وتُطبع التقرير في لوحة الملفات الشخصية في المُفتّش. انظر console.profile() للحصول على مثال.

إذا تم استدعاء هذه الطريقة بدون تسمية، فسيتم إيقاف أحدث ملف تعريف تم بدؤه.

`console.timeStamp([label])`

مضاف في: v8.0.0

label <string>

لا تُظهر هذه الطريقة أي شيء ما لم تُستخدم في المُفتّش. تُضيف طريقة console.timeStamp() حدثًا مع التسمية 'label' إلى لوحة الجدول الزمني في المُفتّش.

وحدة التحكم ​

صنف: Console ​

Console(stdout[, stderr][, ignoreErrors]) الجديد ​

Console(options) الجديد ​

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

console.clear() ​

console.count([label]) ​

console.countReset([label]) ​

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

console.dir(obj[, options]) ​

console.dirxml(...data) ​

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

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

console.groupCollapsed() ​

console.groupEnd() ​

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

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

console.table(tabularData[, properties]) ​

console.time([label]) ​

console.timeEnd([label]) ​

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

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

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

طرق مُفتّشة فقط ​

console.profile([label]) ​

console.profileEnd([label]) ​

console.timeStamp([label]) ​

وحدة التحكم

صنف: `Console`

`Console(stdout[, stderr][, ignoreErrors]) الجديد`

`Console(options) الجديد`

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

`console.clear()`

`console.count([label])`

`console.countReset([label])`

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

`console.dir(obj[, options])`

`console.dirxml(...data)`

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

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

`console.groupCollapsed()`

`console.groupEnd()`

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

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

`console.table(tabularData[, properties])`

`console.time([label])`

`console.timeEnd([label])`

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

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

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

طرق مُفتّشة فقط

`console.profile([label])`

`console.profileEnd([label])`

`console.timeStamp([label])`