نظام الملفات

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

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

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

تتيح وحدة node:fs التفاعل مع نظام الملفات بطريقة مُحاكاة لوظائف POSIX القياسية.

لاستخدام واجهات برمجة التطبيقات القائمة على الوعود:

ESM

import * as fs from 'node:fs/promises'

CJS

const fs = require('node:fs/promises')

لاستخدام واجهات برمجة التطبيقات المتزامنة وذات الاستدعاء العكسي:

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

جميع عمليات نظام الملفات لها أشكال متزامنة، وذات استدعاء عكسي، وقائمة على الوعود، وهي قابلة للوصول باستخدام كل من بناء جملة CommonJS و ES6 Modules (ESM).

مثال على الوعود

ترجع العمليات القائمة على الوعود وعدًا يتم إنجازه عند اكتمال العملية غير المتزامنة.

ESM

import { unlink } from 'node:fs/promises'

try {
  await unlink('/tmp/hello')
  console.log('تم حذف /tmp/hello بنجاح')
} catch (error) {
  console.error('حدث خطأ:', error.message)
}

CJS

const { unlink } = require('node:fs/promises')

;(async function (path) {
  try {
    await unlink(path)
    console.log(`تم حذف ${path} بنجاح`)
  } catch (error) {
    console.error('حدث خطأ:', error.message)
  }
})('/tmp/hello')

مثال على الاستدعاء العكسي

يأخذ نموذج الاستدعاء العكسي دالة استدعاء إكمال كحجته الأخيرة ويثير العملية بشكل غير متزامن. تعتمد الوسائط المُمررة إلى دالة استدعاء الإكمال على الأسلوب، ولكن الحجة الأولى مُخصصة دائمًا لاستثناء. إذا اكتملت العملية بنجاح، فإن الحجة الأولى هي null أو undefined.

ESM

import { unlink } from 'node:fs'

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('تم حذف /tmp/hello بنجاح')
})

CJS

const { unlink } = require('node:fs')

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('تم حذف /tmp/hello بنجاح')
})

تُعدّ إصدارات واجهات برمجة التطبيقات لوحدة node:fs القائمة على الاستدعاء العكسي أفضل من استخدام واجهات برمجة التطبيقات القائمة على الوعود عندما يكون الأداء الأقصى (من حيث وقت التنفيذ وتخصيص الذاكرة) مطلوبًا.

مثال متزامن

تسدد واجهات برمجة التطبيقات المتزامنة حلقة أحداث Node.js و تنفيذ JavaScript الإضافي حتى اكتمال العملية. يتم طرح الاستثناءات على الفور ويمكن التعامل معها باستخدام try…catch، أو السماح لها بالانتشار لأعلى.

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('تم حذف /tmp/hello بنجاح')
} catch (err) {
  // التعامل مع الخطأ
}

CJS

const { unlinkSync } = require('node:fs')

try {
  unlinkSync('/tmp/hello')
  console.log('تم حذف /tmp/hello بنجاح')
} catch (err) {
  // التعامل مع الخطأ
}

واجهة برمجة التطبيقات للوعود

[السجل]

الإصدار	التغييرات
v14.0.0	تم عرضه كـ require('fs/promises').
v11.14.0, v10.17.0	لم تعد هذه الواجهة قيد التجربة.
v10.1.0	يمكن الوصول إلى هذه الواجهة عبر require('fs').promises فقط.
v10.0.0	تمت الإضافة في: v10.0.0

توفر واجهة برمجة التطبيقات fs/promises طرقًا غير متزامنة لنظام الملفات تُرجع الوعود.

تستخدم واجهات برمجة التطبيقات القائمة على الوعود مجموعة مؤشرات الترابط الأساسية في Node.js لأداء عمليات نظام الملفات خارج مؤشر ترابط حلقة الأحداث. هذه العمليات ليست متزامنة أو آمنة للخيوط. يجب توخي الحذر عند إجراء تعديلات متزامنة متعددة على نفس الملف، وإلا فقد يحدث تلف في البيانات.

الصنف: FileHandle

تمت الإضافة في: v10.0.0

كائن <FileHandle> هو كائن مُغلف لوصف ملف رقمي.

يتم إنشاء مثيلات كائن <FileHandle> بواسطة طريقة fsPromises.open().

جميع كائنات <FileHandle> هي <EventEmitter>.

إذا لم يتم إغلاق <FileHandle> باستخدام طريقة filehandle.close()، فإنه سيحاول إغلاق وصف الملف تلقائيًا وسيصدر تحذيرًا للعملية، مما يساعد على منع تسرب الذاكرة. يرجى عدم الاعتماد على هذا السلوك لأنه قد يكون غير موثوق به وقد لا يتم إغلاق الملف. بدلاً من ذلك، قم دائمًا بإغلاق <FileHandle> بشكل صريح. قد تُغيّر Node.js هذا السلوك في المستقبل.

الحدث: 'close'

مضاف في: v15.4.0

يتم إرسال حدث 'close' عندما يتم إغلاق مُعالِج الملفات <FileHandle> ولا يمكن استخدامه بعد الآن.

filehandle.appendFile(data[, options])

[السجل]

الإصدار	التغييرات
v21.1.0, v20.10.0	أصبح خيار flush مدعومًا الآن.
v15.14.0, v14.18.0	تدعم وسيطة data الآن AsyncIterable, Iterable, و Stream.
v14.0.0	لن تقوم وسيطة data بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v10.0.0	مضاف في: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> افتراضي: 'utf8'
  • flush <boolean> إذا كان true، فسيتم إفراغ مُوصِف الملف الأساسي قبل إغلاقه. افتراضي: false.

• القيمة المُرجعة: <Promise> يتم الوفاء به مع undefined عند النجاح.

مُرادِف لـ filehandle.writeFile().

عند التعامل مع مُعالِجات الملفات، لا يمكن تغيير الوضع عما تم تعيينه به باستخدام fsPromises.open(). لذلك، هذا يُعادل filehandle.writeFile().

filehandle.chmod(mode)

أضيف في: v10.0.0

• mode <integer> قناع بت وضع الملف.
• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يعدل الأذونات على الملف. انظر chmod(2).

filehandle.chown(uid, gid)

أضيف في: v10.0.0

• uid <integer> معرف مستخدم مالك الملف الجديد.
• gid <integer> معرف مجموعة مجموعة الملف الجديد.
• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يغير ملكية الملف. عبارة عن ملفوفة لـ chown(2).

filehandle.close()

أضيف في: v10.0.0

• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يغلق مقبض الملف بعد انتظار أي عملية معلقة على المقبض حتى تكتمل.

import { open } from 'node:fs/promises'

let filehandle
try {
  filehandle = await open('thefile.txt', 'r')
} finally {
  await filehandle?.close()
}

filehandle.createReadStream([options])

أضيف في: v16.11.0

• options <Object>

  • encoding <string> الافتراضي: null
  • autoClose <boolean> الافتراضي: true
  • emitClose <boolean> الافتراضي: true
  • start <integer>
  • end <integer> الافتراضي: Infinity
  • highWaterMark <integer> الافتراضي: 64 * 1024
  • signal <AbortSignal> | <undefined> الافتراضي: undefined

• الإرجاع: <fs.ReadStream>

يمكن أن تتضمن options قيم start و end لقراءة مجموعة من البايتات من الملف بدلاً من الملف بالكامل. كل من start و end شاملة وتبدأ العد من 0، والقيم المسموح بها هي في نطاق [0، Number.MAX_SAFE_INTEGER]. إذا تم حذف start أو undefined، فإن filehandle.createReadStream() يقرأ بشكل متسلسل من موضع الملف الحالي. يمكن أن يكون encoding أيًا من تلك التي يقبلها <Buffer>.

إذا كان FileHandle يشير إلى جهاز حرفي يدعم فقط القراءات المنظمة (مثل لوحة المفاتيح أو بطاقة الصوت)، فإن عمليات القراءة لا تنتهي حتى تتوفر البيانات. هذا يمكن أن يمنع العملية من الخروج وتغلق الدفق بشكل طبيعي.

بشكل افتراضي، سيصدر الدفق حدث 'close' بعد تدميره. قم بتعيين خيار emitClose إلى false لتغيير هذا السلوك.

import { open } from 'node:fs/promises'

const fd = await open('/dev/input/event0')
// إنشاء دفق من بعض الأجهزة الحرفية.
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // قد لا يغلق هذا الدفق.
  // وضع علامة اصطناعية لنهاية الدفق، كما لو أن المورد الأساسي قد
  // أشار إلى نهاية الملف بنفسه، يسمح للدفق بالإغلاق.
  // هذا لا يلغي عمليات القراءة المعلقة، وإذا كانت هناك مثل هذه العملية،
  // فقد لا تتمكن العملية من الخروج بنجاح
  // حتى تنتهي.
  stream.push(null)
  stream.read(0)
}, 100)

إذا كان autoClose خاطئًا، فلن يتم إغلاق مُعرّف الملف، حتى لو كان هناك خطأ. تقع على عاتق التطبيق مسؤولية إغلاقه والتأكد من عدم وجود تسرب لمعرفات الملفات. إذا تم تعيين autoClose على true (السلوك الافتراضي)، عند حدوث 'error' أو 'end' سيتم إغلاق مُعرّف الملف تلقائيًا.

مثال لقراءة آخر 10 بايتات من ملف طوله 100 بايت:

import { open } from 'node:fs/promises'

const fd = await open('sample.txt')
fd.createReadStream({ start: 90, end: 99 })

filehandle.createWriteStream([options])

[History]

الإصدار	التغييرات
v21.0.0، v20.10.0	أصبح خيار flush مدعومًا الآن.
v16.11.0	تمت الإضافة في: v16.11.0

• options <Object>

  • encoding <string> الافتراضي: 'utf8'
  • autoClose <boolean> الافتراضي: true
  • emitClose <boolean> الافتراضي: true
  • start <integer>
  • highWaterMark <number> الافتراضي: 16384
  • flush <boolean> إذا كان true، فسيتم مسح مُوصِف الملف الأساسي قبل إغلاقه. الافتراضي: false.

• الإرجاع: <fs.WriteStream>

قد يتضمن options أيضًا خيار start للسماح بكتابة البيانات في مكان ما بعد بداية الملف، والقيم المسموح بها هي في نطاق [0، Number.MAX_SAFE_INTEGER]. قد يتطلب تعديل ملف بدلاً من استبداله تعيين خيار flags open إلى r+ بدلاً من الافتراضي r. يمكن أن يكون encoding أيًا من تلك التي تقبلها <Buffer>.

إذا تم تعيين autoClose على true (السلوك الافتراضي) على 'error' أو 'finish'، فسيتم إغلاق مُوصِف الملف تلقائيًا. إذا كان autoClose false، فلن يتم إغلاق مُوصِف الملف، حتى لو حدث خطأ. تقع على عاتق التطبيق مسؤولية إغلاقه والتأكد من عدم وجود تسريب لموصِف الملف.

بشكل افتراضي، سيصدر الدفق حدث 'close' بعد تدميره. قم بتعيين خيار emitClose إلى false لتغيير هذا السلوك.

filehandle.datasync()

مضاف في: v10.0.0

• مُخرجات: <Promise> ينجز بـ undefined عند النجاح.

يُجبر جميع عمليات الإدخال/الإخراج المُصطفة حاليًا المرتبطة بالملف على حالة إكمال الإدخال/الإخراج المُزامن لنظام التشغيل. يرجى الرجوع إلى وثائق POSIX fdatasync(2) للحصول على التفاصيل.

على عكس filehandle.sync، لا تُفرغ هذه الطريقة البيانات الوصفية المُعدلة.

filehandle.fd

مضاف في: v10.0.0

• <number> مُعرّف الملف العددي الذي تديره كائن <FileHandle>.

filehandle.read(buffer, offset, length, position)

[السجل]

الإصدار	التغييرات
v21.0.0	يقبل قيم bigint كـ position.
v10.0.0	مضاف في: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> مُخزن مؤقت سيتم ملؤه ببيانات الملف المُقروءة.
• offset <integer> الموقع في المخزن المؤقت الذي يجب البدء بملئه منه. افتراضيًا: 0
• length <integer> عدد البايتات التي سيتم قراءتها. افتراضيًا: buffer.byteLength - offset
• position <integer> | <bigint> | <null> الموقع الذي يجب البدء بقراءة البيانات منه من الملف. إذا كان null أو -1، فسيتم قراءة البيانات من موقع الملف الحالي، وسيتم تحديث الموقع. إذا كان position عددًا صحيحًا غير سالب، فسيظل موقع الملف الحالي دون تغيير. افتراضيًا: null
• مُخرجات: <Promise> ينجز عند النجاح بكائن به خاصيتان:
  • bytesRead <integer> عدد البايتات المُقروءة
  • buffer <Buffer> | <TypedArray> | <DataView> مرجع لحجة buffer المُمررة.

يقرأ البيانات من الملف ويُخزنها في المخزن المؤقت المُعطى.

إذا لم يتم تعديل الملف بشكل مُتزامن، فسيتم الوصول إلى نهاية الملف عندما يكون عدد البايتات المُقروءة صفرًا.

filehandle.read([options])

[السجل]

الإصدار	التغييرات
v21.0.0	يقبل قيم bigint كـ position.
v13.11.0, v12.17.0	تمت الإضافة في: v13.11.0, v12.17.0

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> عازلة سيتم ملؤها ببيانات الملف المقروءة. الافتراضي: Buffer.alloc(16384)
  • offset <integer> الموقع في العازلة الذي يبدأ منه الملء. الافتراضي: 0
  • length <integer> عدد البايتات التي سيتم قراءتها. الافتراضي: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> الموقع الذي يبدأ منه قراءة البيانات من الملف. إذا كان null أو -1، فسيتم قراءة البيانات من موضع الملف الحالي، وسيتم تحديث الموضع. إذا كان position عددًا صحيحًا غير سالب، فسيظل موضع الملف الحالي دون تغيير. الافتراضي: null

• الإرجاع: <Promise> يتم الوفاء به عند النجاح مع كائن يحتوي على خاصيتين:

  • bytesRead <integer> عدد البايتات المقروءة
  • buffer <Buffer> | <TypedArray> | <DataView> مرجع للحجة buffer المُمرّرة.

يقرأ البيانات من الملف ويخزنها في العازلة المعطاة.

إذا لم يتم تعديل الملف بشكل متزامن، فسيتم الوصول إلى نهاية الملف عندما يكون عدد البايتات المقروءة صفرًا.

filehandle.read(buffer[, options])

[السجل]

الإصدار	التغييرات
v21.0.0	يقبل قيم bigint كـ position.
v18.2.0, v16.17.0	تمت الإضافة في: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> مخزن مؤقت سيتم ملؤه ببيانات الملف المقروءة.

• options <Object>

  • offset <integer> الموقع في المخزن المؤقت الذي يبدأ منه الملء. الافتراضي: 0
  • length <integer> عدد البايتات التي سيتم قراءتها. الافتراضي: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> الموقع الذي يبدأ منه قراءة البيانات من الملف. إذا كان null أو -1، فسيتم قراءة البيانات من موضع الملف الحالي، وسيتم تحديث الموضع. إذا كان position عددًا صحيحًا غير سالب، فسيظل موضع الملف الحالي دون تغيير. الافتراضي: null

• الإرجاع: <Promise> يتم الوفاء به عند النجاح باستخدام كائن يحتوي على خاصيتين:

  • bytesRead <integer> عدد البايتات المقروءة
  • buffer <Buffer> | <TypedArray> | <DataView> مرجع للحجة buffer المُمرّرة.

يقرأ البيانات من الملف ويخزنها في المخزن المؤقت المعطى.

إذا لم يتم تعديل الملف بشكل متزامن، فسيتم الوصول إلى نهاية الملف عندما يكون عدد البايتات المقروءة صفرًا.

filehandle.readableWebStream([options])

[السجل]

الإصدار	التغييرات
v20.0.0, v18.17.0	تمت إضافة خيار لإنشاء دفق "بايت".
v17.0.0	تمت الإضافة في: v17.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• options <Object>

  • type <string> | <undefined> ما إذا كان سيتم فتح دفق عادي أو دفق 'bytes' . الافتراضي: undefined

• المُرجَع: <ReadableStream>

يرجع ReadableStream الذي يمكن استخدامه لقراءة بيانات الملفات.

سيتم إرسال خطأ إذا تم استدعاء هذه الطريقة أكثر من مرة أو تم استدعاؤها بعد إغلاق أو إغلاق FileHandle.

ESM

import { open } from 'node:fs/promises'

const file = await open('./some/file/to/read')

for await (const chunk of file.readableWebStream()) console.log(chunk)

await file.close()

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const chunk of file.readableWebStream()) console.log(chunk)

  await file.close()
})()

في حين أن ReadableStream سيقوم بقراءة الملف حتى اكتماله، إلا أنه لن يغلق FileHandle تلقائيًا. يجب على رمز المستخدم الاستمرار في استدعاء طريقة fileHandle.close().

filehandle.readFile(options)

تمت الإضافة في: v10.0.0

• options <Object> | <string>

  • encoding <string> | <null> الافتراضي: null
  • signal <AbortSignal> يسمح بإلغاء عملية readFile قيد التنفيذ

• المُرجَع: <Promise> يتم الوفاء به عند القراءة الناجحة مع محتويات الملف. إذا لم يتم تحديد ترميز (باستخدام options.encoding)، فسيتم إرجاع البيانات ككائن <Buffer>. خلاف ذلك، ستكون البيانات سلسلة.

يقوم بقراءة محتويات الملف بالكامل بشكل غير متزامن.

إذا كانت options سلسلة، فإنها تحدد encoding.

يجب أن يدعم <FileHandle> القراءة.

إذا تم إجراء مكالمة واحدة أو أكثر من مكالمات filehandle.read() على مقبض ملف، ثم تم إجراء مكالمة filehandle.readFile()، فسيتم قراءة البيانات من الموقع الحالي حتى نهاية الملف. لا تقرأ دائمًا من بداية الملف.

filehandle.readLines([options])

مضاف في: v18.11.0

• options <Object>

  • encoding <string> افتراضي: null
  • autoClose <boolean> افتراضي: true
  • emitClose <boolean> افتراضي: true
  • start <integer>
  • end <integer> افتراضي: Infinity
  • highWaterMark <integer> افتراضي: 64 * 1024

• قيمة مُعادة: <readline.InterfaceConstructor>

طريقة مُيسّرة لإنشاء واجهة readline والتدفق عبر الملف. راجع filehandle.createReadStream() للاطلاع على الخيارات.

ESM

import { open } from 'node:fs/promises'

const file = await open('./some/file/to/read')

for await (const line of file.readLines()) {
  console.log(line)
}

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const line of file.readLines()) {
    console.log(line)
  }
})()

filehandle.readv(buffers[, position])

مضاف في: v13.13.0، v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> الإزاحة من بداية الملف حيث يجب قراءة البيانات منه. إذا لم يكن position رقمًا، فسيتم قراءة البيانات من الموقع الحالي. افتراضي: null
• قيمة مُعادة: <Promise> تُفي بالوعد عند النجاح، كائن يحتوي على خاصيتين:
  • bytesRead <integer> عدد البايتات المُقروءة
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> خاصية تحتوي على مرجع لإدخال buffers.

قراءة من ملف والكتابة في مصفوفة من <ArrayBufferView>s

filehandle.stat([options])

[التاريخ]

الإصدار	التغييرات
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة من نوع bigint.
v10.0.0	تمت الإضافة في: v10.0.0

• options <Object>

  • bigint <boolean> ما إذا كان يجب أن تكون القيم العددية في كائن <fs.Stats> المُرتجع من نوع bigint. الافتراضي: false.

• الإرجاع: <Promise> يتم الوفاء بـ <fs.Stats> للملف.

filehandle.sync()

تمت الإضافة في: v10.0.0

• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

طلب إفراغ جميع البيانات الخاصة بوصف الملف المفتوح إلى جهاز التخزين. التنفيذ المحدد يعتمد على نظام التشغيل والجهاز. يرجى الرجوع إلى وثائق POSIX fsync(2) لمزيد من التفاصيل.

filehandle.truncate(len)

تمت الإضافة في: v10.0.0

• len <integer> الافتراضي: 0
• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يقصّر الملف.

إذا كان الملف أكبر من len بايت، فسيتم الاحتفاظ فقط بأول len بايت في الملف.

يوضح المثال التالي الاحتفاظ بأول أربعة بايت فقط من الملف:

import { open } from 'node:fs/promises'

let filehandle = null
try {
  filehandle = await open('temp.txt', 'r+')
  await filehandle.truncate(4)
} finally {
  await filehandle?.close()
}

إذا كان الملف أقصر من len بايت سابقًا، فسيتم توسيعه، ويتم ملء الجزء الموسع ببايت فارغة ('\0'):

إذا كانت قيمة len سالبة، فسيتم استخدام 0.

filehandle.utimes(atime, mtime)

مضاف في: v10.0.0

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• القيمة المُرجعه: <Promise>

يُغيّر طوابع زمن نظام الملفات للكائن المُشار إليه بواسطة <FileHandle> ، ثم يُوفي الوعد بدون أي وسيطات عند النجاح.

filehandle.write(buffer, offset[, length[, position]])

[السجل]

الإصدار	التغييرات
v14.0.0	لن تُجبر وسيطة buffer المدخلات غير المدعومة على أن تكون مخازن مؤقتة بعد الآن.
v10.0.0	مضاف في: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> موضع البدء من داخل buffer حيث تبدأ البيانات التي سيتم كتابتها.
• length <integer> عدد البايتات من buffer التي سيتم كتابتها. الافتراضي: buffer.byteLength - offset
• position <integer> | <null> الإزاحة من بداية الملف حيث يجب كتابة البيانات من buffer. إذا لم يكن position رقمًا، فسيتم كتابة البيانات في الموضع الحالي. راجع وثائق POSIX pwrite(2) لمزيد من التفاصيل. الافتراضي: null
• القيمة المُرجعه: <Promise>

اكتب buffer إلى الملف.

يتم الوفاء بالوعد بكائن يحتوي على خاصيتين:

• bytesWritten <integer> عدد البايتات المكتوبة
• buffer <Buffer> | <TypedArray> | <DataView> مرجع لـ buffer المكتوب.

من غير الآمن استخدام filehandle.write() عدة مرات على نفس الملف دون انتظار إتمام الوعد (أو رفضه). في هذا السيناريو، استخدم filehandle.createWriteStream().

في لينكس، لا تعمل عمليات الكتابة الموضعية عندما يتم فتح الملف في وضع الإضافة. يتجاهل نواة النظام وسيطة الموضع ويضيف البيانات دائمًا إلى نهاية الملف.

filehandle.write(buffer[, options])

مضاف في: v18.3.0، v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> افتراضي: 0
  • length <integer> افتراضي: buffer.byteLength - offset
  • position <integer> افتراضي: null

• قيمة مُرجعة: <Promise>

يكتب buffer إلى الملف.

بالمثل، فإن دالة filehandle.write أعلاه تأخذ كائن options اختياريًا. إذا لم يتم تحديد كائن options، فسيتم استخدام القيم الافتراضية المذكورة أعلاه.

filehandle.write(string[, position[, encoding]])

[السجل]

الإصدار	التغييرات
v14.0.0	لن تقوم وسيطة string بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v10.0.0	مضاف في: v10.0.0

• string <string>
• position <integer> | <null> الإزاحة من بداية الملف حيث يجب كتابة البيانات من string. إذا لم يكن position رقمًا، فسيتم كتابة البيانات في الموضع الحالي. راجع وثائق POSIX pwrite(2) لمزيد من التفاصيل. افتراضي: null
• encoding <string> ترميز السلسلة المتوقع. افتراضي: 'utf8'
• قيمة مُرجعة: <Promise>

يكتب string إلى الملف. إذا لم يكن string سلسلة نصية، فسيتم رفض الوعد بخطأ.

يتم تحقيق الوعد بكائن يحتوي على خاصيتين:

• bytesWritten <integer> عدد البايت المكتوبة
• buffer <string> مرجع إلى string المكتوبة.

من غير الآمن استخدام filehandle.write() عدة مرات على نفس الملف دون انتظار تحقيق الوعد (أو رفضه). في هذا السيناريو، استخدم filehandle.createWriteStream().

على لينكس، لا تعمل عمليات الكتابة الموضعية عندما يتم فتح الملف في وضع الإضافة. يتجاهل نواة النظام وسيطة الموضع ويضيف البيانات دائمًا إلى نهاية الملف.

filehandle.writeFile(data, options)

[السجل]

الإصدار	التغييرات
v15.14.0، v14.18.0	تدعم وسيطة data الآن AsyncIterable و Iterable و Stream.
v14.0.0	لم تعد وسيطة data تُجبر المدخلات غير المدعومة على أن تكون سلاسل نصية.
v10.0.0	تمت الإضافة في: v10.0.0

• data <سلسلة> | <عازل> | <TypedArray> | <DataView> | <AsyncIterable> | <قابلة للتكرار> | <دفق>

• options <كائن> | <سلسلة>

  • encoding <سلسلة> | <لا شيء> ترميز الأحرف المتوقع عندما تكون data سلسلة نصية. افتراضيًا: 'utf8'

• القيمة المُرجعة: <وعد>

يكتب البيانات في ملف بشكل غير متزامن، ويستبدل الملف إذا كان موجودًا بالفعل. يمكن أن تكون data سلسلة نصية، أو عازل، أو <AsyncIterable> ، أو كائن <قابلة للتكرار>. يتم تحقيق الوعد بدون وسيطات عند النجاح.

إذا كانت options سلسلة نصية، فإنها تحدد encoding.

يجب أن يدعم <FileHandle> الكتابة.

من غير الآمن استخدام filehandle.writeFile() عدة مرات على نفس الملف دون انتظار تحقيق الوعد (أو رفضه).

إذا تم إجراء مكالمة واحدة أو أكثر من filehandle.write() على مُعامِل ملف، ثم تم إجراء مكالمة filehandle.writeFile()، فسيتم كتابة البيانات من الموضع الحالي حتى نهاية الملف. لا تكتب دائمًا من بداية الملف.

filehandle.writev(buffers[, position])

مضاف في: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> الإزاحة من بداية الملف حيث يجب كتابة البيانات من buffers. إذا لم يكن position رقمًا، فسيتم كتابة البيانات في الموقع الحالي. افتراضيًا: null
• القيمة المُرجعة: <Promise>

كتابة مصفوفة من <ArrayBufferView>s إلى الملف.

يتم تحقيق الوعد بكائن يحتوي على خاصيتين:

• bytesWritten <integer> عدد البايتات المكتوبة
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> مرجع لإدخال buffers.

من غير الآمن استدعاء writev() عدة مرات على نفس الملف دون انتظار تحقيق الوعد (أو رفضه).

في Linux، لا تعمل عمليات الكتابة الموضعية عندما يتم فتح الملف في وضع الإضافة. يتجاهل kernel وسيطة الموقع ويضيف دائمًا البيانات إلى نهاية الملف.

filehandle[Symbol.asyncDispose]()

مضاف في: v20.4.0، v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1 - تجريبي

اسم آخر لـ filehandle.close().

fsPromises.access(path[, mode])

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> افتراضي: fs.constants.F_OK
• القيمة المُرجعة: <Promise> يتم الوفاء بها مع undefined عند النجاح.

يختبر أذونات المستخدم للملف أو الدليل المحدد بواسطة path. حجة mode هي عدد صحيح اختياري يحدد عمليات فحص إمكانية الوصول التي سيتم تنفيذها. يجب أن يكون mode إما قيمة fs.constants.F_OK أو قناع يتكون من OR المنطقي لأي من fs.constants.R_OK، fs.constants.W_OK، و fs.constants.X_OK (مثل fs.constants.W_OK | fs.constants.R_OK). تحقق من ثوابت وصول الملف للحصول على القيم الممكنة لـ mode.

إذا نجح فحص إمكانية الوصول، فسيتم الوفاء بالوعد بدون قيمة. إذا فشل أي من عمليات فحص إمكانية الوصول، فسيتم رفض الوعد باستخدام كائن <Error>. يوضح المثال التالي ما إذا كان يمكن قراءة ملف /etc/passwd وكتابته بواسطة العملية الحالية.

import { access, constants } from 'node:fs/promises'

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK)
  console.log('يمكن الوصول')
} catch {
  console.error('لا يمكن الوصول')
}

لا يُنصح باستخدام fsPromises.access() للتحقق من إمكانية الوصول إلى ملف قبل استدعاء fsPromises.open(). يؤدي القيام بذلك إلى إدخال حالة سباق، حيث قد تغير العمليات الأخرى حالة الملف بين الاستدعاءين. بدلاً من ذلك، يجب أن يفتح/يقرأ/يكتب المستخدم الملف مباشرةً ويتعامل مع الخطأ الذي تم إثارة إذا لم يكن الملف قابلًا للوصول.

fsPromises.appendFile(path, data[, options])

[السجل]

الإصدار	التغييرات
v21.1.0, v20.10.0	خيار flush مدعوم الآن.
v10.0.0	مضاف في: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> اسم الملف أو <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> افتراضي: 'utf8'
  • mode <integer> افتراضي: 0o666
  • flag <string> انظر دعم علامات نظام الملفات. افتراضي: 'a'.
  • flush <boolean> إذا كانت true، فسيتم مسح واصف الملف الأساسي قبل إغلاقه. افتراضي: false.

• القيمة المُرجعة: <Promise> يتم الوفاء بها مع undefined عند النجاح.

يضيف بشكل غير متزامن البيانات إلى ملف، وإنشاء الملف إذا لم يكن موجودًا بالفعل. يمكن أن يكون data سلسلة أو <Buffer>.

إذا كان options سلسلة، فإنه يحدد encoding.

يؤثر خيار mode فقط على الملف الذي تم إنشاؤه حديثًا. راجع fs.open() لمزيد من التفاصيل.

يمكن تحديد path كـ <FileHandle> تم فتحه للإضافة (باستخدام fsPromises.open()).

fsPromises.chmod(path, mode)

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• القيمة المُرجعة: <Promise> تكتمل بـ undefined عند النجاح.

يُغيّر أذونات الملف.

fsPromises.chown(path, uid, gid)

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• القيمة المُرجعة: <Promise> تكتمل بـ undefined عند النجاح.

يُغيّر ملكية الملف.

fsPromises.copyFile(src, dest[, mode])

[السجل]

الإصدار	التغييرات
v14.0.0	تم تغيير وسيطة flags إلى mode وفرض التحقق من نوع أكثر صرامة.
v10.0.0	مضاف في: v10.0.0

• src <string> | <Buffer> | <URL> اسم الملف المصدر المراد نسخه

• dest <string> | <Buffer> | <URL> اسم ملف الوجهة لعملية النسخ

• mode <integer> مُعدِّلات اختيارية تحدد سلوك عملية النسخ. من الممكن إنشاء قناع يتكون من OR المنطقي بتي لواحد أو أكثر من القيم (مثل fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) الافتراضي: 0.

  • fs.constants.COPYFILE_EXCL: ستفشل عملية النسخ إذا كان dest موجودًا بالفعل.
  • fs.constants.COPYFILE_FICLONE: ستحاول عملية النسخ إنشاء مرجع ارتباط نسخ عند الكتابة. إذا لم يدعم النظام الأساسي النسخ عند الكتابة، فسيتم استخدام آلية نسخ احتياطية.
  • fs.constants.COPYFILE_FICLONE_FORCE: ستحاول عملية النسخ إنشاء مرجع ارتباط نسخ عند الكتابة. إذا لم يدعم النظام الأساسي النسخ عند الكتابة، فستفشل العملية.

• القيمة المُرجعة: <Promise> تكتمل بـ undefined عند النجاح.

ينسخ src إلى dest بشكل غير متزامن. بشكل افتراضي، يتم الكتابة فوق dest إذا كان موجودًا بالفعل.

لا تُعطى أي ضمانات حول ذرية عملية النسخ. إذا حدث خطأ بعد فتح ملف الوجهة للكتابة، فسيتم إجراء محاولة لإزالة الوجهة.

import { copyFile, constants } from 'node:fs/promises'

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('تم نسخ source.txt إلى destination.txt')
} catch {
  console.error('تعذّر نسخ الملف')
}

// باستخدام COPYFILE_EXCL، ستفشل العملية إذا كان destination.txt موجودًا.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('تم نسخ source.txt إلى destination.txt')
} catch {
  console.error('تعذّر نسخ الملف')
}

fsPromises.cp(src, dest[, options])

[السجل]

الإصدار	التغييرات
v22.3.0	لم يعد هذا البرنامج واجهة تجريبية.
v20.1.0، v18.17.0	قبول خيار mode إضافي لتحديد سلوك النسخ كوسيط mode لـ fs.copyFile().
v17.6.0، v16.15.0	يقبل خيار verbatimSymlinks إضافي لتحديد ما إذا كان سيتم إجراء حل المسار للروابط الرمزية.
v16.7.0	تمت الإضافة في: v16.7.0

• src <string> | <URL> مسار المصدر المراد نسخه.

• dest <string> | <URL> مسار الوجهة المراد النسخ إليه.

• options <Object>

  • dereference <boolean> إلغاء مرجع الروابط الرمزية. الافتراضي: false.

  • errorOnExist <boolean> عندما يكون force هو false، وإذا وجدت الوجهة، يتم إخراج خطأ. الافتراضي: false.

  • filter <Function> دالة لتصفية الملفات/الدلائل المنسوخة. إرجاع true لنسخ العنصر، false لتجاهله. عند تجاهل دليل، سيتم تخطي جميع محتوياته أيضًا. يمكن أيضًا إرجاع Promise يحقق true أو false الافتراضي: undefined.

  • src <string> مسار المصدر المراد نسخه.

  • dest <string> مسار الوجهة المراد النسخ إليه.

  • الإرجاع: <boolean> | <Promise> قيمة يمكن تحويلها إلى boolean أو Promise الذي يُحقق قيمة كهذه.

  • force <boolean> الكتابة فوق الملف أو الدليل الموجود. ستتجاهل عملية النسخ الأخطاء إذا قمت بتعيين هذا إلى false ووجود الوجهة. استخدم خيار errorOnExist لتغيير هذا السلوك. الافتراضي: true.

  • mode <integer> مُعدِّلات لعملية النسخ. الافتراضي: 0. راجع علم mode الخاص بـ fsPromises.copyFile().

  • preserveTimestamps <boolean> عندما يكون true سيتم حفظ طوابع الوقت من src. الافتراضي: false.

  • recursive <boolean> نسخ الدلائل بشكل متكرر الافتراضي: false

  • verbatimSymlinks <boolean> عندما يكون true، سيتم تخطي حل المسار للروابط الرمزية. الافتراضي: false

• الإرجاع: <Promise> يُحقق undefined عند النجاح.

يقوم بنسخ بنية الدليل بأكملها بشكل غير متزامن من src إلى dest، بما في ذلك الدلائل الفرعية والملفات.

عند نسخ دليل إلى دليل آخر، لا يتم دعم الكائنات العامة ويكون السلوك مشابهًا لـ cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

[السجل]

الإصدار	التغييرات
v22.2.0	إضافة دعم لـ withFileTypes كخيار.
v22.0.0	تمت الإضافة في: v22.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> الدليل الحالي للعمل. الافتراضي: process.cwd()
  • exclude <Function> دالة لتصفية الملفات/الدلائل. قم بإرجاع true لاستبعاد العنصر، false لإدراجه. الافتراضي: undefined.
  • withFileTypes <boolean> true إذا كان يجب أن يُرجع glob المسارات كـ Dirents، false خلاف ذلك. الافتراضي: false.

• القيمة المرجعة: <AsyncIterator> مُكرر غير متزامن يُنتج مسارات الملفات التي تتطابق مع النمط.

ESM

import { glob } from 'node:fs/promises'

for await (const entry of glob('**/*.js')) console.log(entry)

CJS

const { glob } = require('node:fs/promises')

;(async () => {
  for await (const entry of glob('**/*.js')) console.log(entry)
})()

fsPromises.lchmod(path, mode)

مُهمل منذ: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer>
• القيمة المرجعة: <Promise> يتم الوفاء به مع undefined عند النجاح.

يُغيّر الأذونات على رابط رمزي.

تم تنفيذ هذه الطريقة فقط على macOS.

fsPromises.lchown(path, uid, gid)

[History]

الإصدار	التغييرات
v10.6.0	لم يعد هذا API قديمًا.
v10.0.0	تمت الإضافة في: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يغير ملكية رابط رمزي.

fsPromises.lutimes(path, atime, mtime)

تمت الإضافة في: v14.5.0، v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• الإرجاع: <Promise> يتم الوفاء بـ undefined عند النجاح.

يغير أوقات الوصول والتعديل للملف بنفس طريقة fsPromises.utimes()، مع اختلاف أنه إذا كان المسار يشير إلى رابط رمزي، فلن يتم إلغاء مرجع الرابط: بدلاً من ذلك، سيتم تغيير طوابع الوقت للرابط الرمزي نفسه.

fsPromises.link(existingPath, newPath)

مضاف في: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• قيمة مُرجعة: <Promise> يتم الوفاء بـ undefined عند النجاح.

يُنشئ رابطًا جديدًا من existingPath إلى newPath. راجع وثائق POSIX link(2) لمزيد من التفاصيل.

fsPromises.lstat(path[, options])

[السجل]

الإصدار	التغييرات
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرجعة من نوع bigint.
v10.0.0	مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كان يجب أن تكون القيم العددية في كائن <fs.Stats> المُرجّع من نوع bigint. افتراضيًا: false.

• قيمة مُرجعة: <Promise> يتم الوفاء بـ كائن <fs.Stats> لمسار الرابط الرمزي المعطى.

ما يعادل fsPromises.stat() إلا إذا كان path يشير إلى رابط رمزي، وفي هذه الحالة يتم فحص الرابط نفسه، وليس الملف الذي يشير إليه. راجع وثيقة POSIX lstat(2) لمزيد من التفاصيل.

fsPromises.mkdir(path[, options])

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> الافتراضي: false
  • mode <string> | <integer> غير مدعوم على Windows. الافتراضي: 0o777.

• مُخرجات: <Promise> عند النجاح، يتم الوفاء بـ undefined إذا كان recursive يساوي false، أو مسار الدليل الأول الذي تم إنشاؤه إذا كان recursive يساوي true.

يقوم بإنشاء دليل بشكل غير متزامن.

يمكن أن تكون وسيطة options الاختيارية عددًا صحيحًا يحدد mode (أذونات وبتات لاصقة)، أو كائنًا يحتوي على خاصية mode وخاصية recursive تشير إلى ما إذا كان يجب إنشاء أدلة رئيسية. يؤدي استدعاء fsPromises.mkdir() عندما يكون path دليلًا موجودًا إلى الرفض فقط عندما يكون recursive خاطئًا.

ESM

import { mkdir } from 'node:fs/promises'

try {
  const projectFolder = new URL('./test/project/', import.meta.url)
  const createDir = await mkdir(projectFolder, { recursive: true })

  console.log(`created ${createDir}`)
} catch (err) {
  console.error(err.message)
}

CJS

const { mkdir } = require('node:fs/promises')
const { join } = require('node:path')

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project')
  const dirCreation = await mkdir(projectFolder, { recursive: true })

  console.log(dirCreation)
  return dirCreation
}

makeDirectory().catch(console.error)

fsPromises.mkdtemp(prefix[, options])

[History]

الإصدار	التغييرات
v20.6.0، v18.19.0	الآن، تقبل معلمة prefix المخازن المؤقتة وعنوان URL.
v16.5.0، v14.18.0	الآن، تقبل معلمة prefix سلسلة فارغة.
v10.0.0	تمت الإضافة في: v10.0.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• القيمة المُرجعة: <Promise> يتم الوفاء بوعد بسلسلة تحتوي على مسار نظام الملفات للدرج المؤقت الذي تم إنشاؤه حديثًا.

يُنشئ دليلاً مؤقتاً فريداً. يتم إنشاء اسم دليل فريد عن طريق إضافة ستة أحرف عشوائية إلى نهاية بادئة prefix المُقدمة. نظرًا لعدم تناسق المنصات، تجنب أحرف X النهائية في prefix. قد تُعيد بعض المنصات، ولا سيما أنظمة تشغيل BSD، أكثر من ستة أحرف عشوائية، وتستبدل أحرف X النهائية في prefix بأحرف عشوائية.

يمكن أن تكون وسيطة options الاختيارية سلسلة تُحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تُحدد ترميز الأحرف المُستخدم.

import { mkdtemp } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

try {
  await mkdtemp(join(tmpdir(), 'foo-'))
} catch (err) {
  console.error(err)
}

ستقوم طريقة fsPromises.mkdtemp() بإضافة الأحرف الستة المُختارة عشوائيًا مباشرةً إلى سلسلة prefix. على سبيل المثال، بالنظر إلى دليل /tmp، إذا كانت النية هي إنشاء دليل مؤقت ضمن /tmp، فيجب أن تنتهي prefix بفاصل مسار محدد بنظام التشغيل (require('node:path').sep).

fsPromises.open(path, flags[, mode])

[History]

الإصدار	التغييرات
v11.1.0	أصبحت وسيطة flags اختيارية الآن، وافتراضيًا هي 'r'.
v10.0.0	تمت الإضافة في: v10.0.0

• path <string> | <Buffer> | <URL>
• flags <string> | <number> انظر دعم علامات نظام الملفات. الافتراضي: 'r'.
• mode <string> | <integer> يحدد وضع الملف (أذونات والبتات اللاصقة) إذا تم إنشاء الملف. الافتراضي: 0o666 (قابل للقراءة والكتابة)
• القيمة المُرجعة: <Promise> تُفي بوعد بـ <FileHandle> كائن.

يفتح <FileHandle>.

يرجى الرجوع إلى وثائق POSIX open(2) لمزيد من التفاصيل.

بعض الأحرف (\< \> : " / \ | ? *) محجوزة في نظام ويندوز كما هو موثق في تسمية الملفات والمسارات ومساحات الأسماء. في NTFS، إذا كان اسم الملف يحتوي على نقطتين، فسوف يفتح Node.js دفق نظام ملفات، كما هو موضح في صفحة MSDN هذه.

fsPromises.opendir(path[, options])

[History]

الإصدار	التغييرات
v20.1.0، v18.17.0	تمت إضافة خيار recursive.
v13.1.0، v12.16.0	تم تقديم خيار bufferSize.
v12.12.0	تمت الإضافة في: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> الافتراضي: 'utf8'
  • bufferSize <number> عدد إدخالات الدليل التي يتم تخزينها مؤقتًا داخليًا عند القراءة من الدليل. تؤدي القيم الأعلى إلى أداء أفضل ولكن استخدام ذاكرة أعلى. الافتراضي: 32
  • recursive <boolean> Dir المُحلل سيكون <AsyncIterable> يحتوي على جميع الملفات والدلائل الفرعية. الافتراضي: false

• القيمة المُرجعة: <Promise> تُفي بوعد بـ <fs.Dir>.

افتح دليلًا بشكل غير متزامن للمسح التكراري. راجع وثائق POSIX opendir(3) لمزيد من التفاصيل.

يُنشئ <fs.Dir>، والذي يحتوي على جميع الوظائف الإضافية للقراءة من الدليل وتنظيفه.

يحدد خيار encoding ترميز path أثناء فتح الدليل وعمليات القراءة اللاحقة.

مثال باستخدام التكرار غير المتزامن:

import { opendir } from 'node:fs/promises'

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

عند استخدام مُكرر غير متزامن، سيتم إغلاق كائن <fs.Dir> تلقائيًا بعد خروج المُكرر.

fsPromises.readdir(path[, options])

[History]

الإصدار	التغييرات
v20.1.0, v18.17.0	تمت إضافة خيار recursive.
v10.11.0	تمت إضافة خيار جديد withFileTypes.
v10.0.0	تمت الإضافة في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'
  • withFileTypes <boolean> الافتراضي: false
  • recursive <boolean> إذا كان true، يقرأ محتويات الدليل بشكل متكرر. في الوضع المتكرر، سيسرد جميع الملفات والملفات الفرعية والدلائل. الافتراضي: false.

• الإرجاع: <Promise> يتم الوفاء بمصفوفة من أسماء الملفات الموجودة في الدليل باستثناء '.' و '..'.

يقرأ محتويات الدليل.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي سيتم استخدامه لأسماء الملفات. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير أسماء الملفات التي تم إرجاعها كأشياء <Buffer>.

إذا تم تعيين options.withFileTypes على true، فستحتوي المصفوفة التي تم إرجاعها على كائنات <fs.Dirent>.

import { readdir } from 'node:fs/promises'

try {
  const files = await readdir(path)
  for (const file of files) console.log(file)
} catch (err) {
  console.error(err)
}

fsPromises.readFile(path[, options])

[السجل]

الإصدار	التغييرات
v15.2.0، v14.17.0	قد تتضمن وسيطة الخيارات إشارة AbortSignal لإلغاء طلب readFile جارٍ.
v10.0.0	تمت الإضافة في: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> اسم الملف أو FileHandle

• options <Object> | <string>

  • encoding <string> | <null> الافتراضي: null
  • flag <string> انظر دعم علامات نظام الملفات. الافتراضي: 'r'
  • signal <AbortSignal> يسمح بإلغاء عملية قراءة الملف الجارية

• القيمة المُرجعة: <Promise> يتم الوفاء بها بمحتويات الملف.

يقوم بقراءة محتويات الملف بالكامل بشكل غير متزامن.

إذا لم يتم تحديد ترميز (باستخدام options.encoding)، يتم إرجاع البيانات ككائن <Buffer>. خلاف ذلك، ستكون البيانات سلسلة.

إذا كانت options سلسلة، فإنها تحدد الترميز.

عندما يكون path دليلًا، يكون سلوك fsPromises.readFile() محددًا بنظام التشغيل. على macOS وLinux وWindows، سيتم رفض الوعد بخطأ. على FreeBSD، سيتم إرجاع تمثيل لمحتويات الدليل.

مثال لقراءة ملف package.json الموجود في نفس دليل تشغيل التعليمات البرمجية:

ESM

import { readFile } from 'node:fs/promises'
try {
  const filePath = new URL('./package.json', import.meta.url)
  const contents = await readFile(filePath, { encoding: 'utf8' })
  console.log(contents)
} catch (err) {
  console.error(err.message)
}

CJS

const { readFile } = require('node:fs/promises')
const { resolve } = require('node:path')
async function logFile() {
  try {
    const filePath = resolve('./package.json')
    const contents = await readFile(filePath, { encoding: 'utf8' })
    console.log(contents)
  } catch (err) {
    console.error(err.message)
  }
}
logFile()

من الممكن إلغاء عملية readFile الجارية باستخدام <AbortSignal>. إذا تم إلغاء طلب، فسيتم رفض الوعد المُرجع بخطأ AbortError:

import { readFile } from 'node:fs/promises'

try {
  const controller = new AbortController()
  const { signal } = controller
  const promise = readFile(fileName, { signal })

  // إلغاء الطلب قبل استقرار الوعد.
  controller.abort()

  await promise
} catch (err) {
  // عندما يتم إلغاء طلب - err هو AbortError
  console.error(err)
}

إن إلغاء الطلب الجاري لا يلغي طلبات نظام التشغيل الفردية، بل التخزين المؤقت الداخلي الذي يقوم به fs.readFile.

يجب أن يدعم أي <FileHandle> محدد القراءة.

fsPromises.readlink(path[, options])

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• المُرجّع: <Promise> يتم الوفاء بـ linkString عند النجاح.

يقرأ محتويات الرابط الرمزي المشار إليه بواسطة path. راجع وثائق POSIX readlink(2) لمزيد من التفاصيل. يتم الوفاء بالوعد مع linkString عند النجاح.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي يجب استخدامه لمسار الرابط المُرجّع. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير مسار الرابط المُرجّع ككائن <Buffer>.

fsPromises.realpath(path[, options])

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• المُرجّع: <Promise> يتم الوفاء بالمسار المُحلل عند النجاح.

يحدد الموقع الفعلي لـ path باستخدام نفس دلالات دالة fs.realpath.native() .

يتم دعم المسارات التي يمكن تحويلها إلى سلاسل UTF8 فقط.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي يجب استخدامه للمسار. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير المسار المُرجّع ككائن <Buffer>.

في Linux، عندما يتم ربط Node.js بـ musl libc، يجب تثبيت نظام ملفات procfs على /proc لكي تعمل هذه الوظيفة. لا يحتوي Glibc على هذا القيد.

fsPromises.rename(oldPath, newPath)

مضاف في: v10.0.0

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• مُخرجات: <Promise> يتم الوفاء بـ undefined عند النجاح.

يعيد تسمية oldPath إلى newPath.

fsPromises.rmdir(path[, options])

[السجل]

الإصدار	التغييرات
v16.0.0	لم يعد يُسمح باستخدام fsPromises.rmdir(path, { recursive: true }) على path وهو ملف، وينتج عنه خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.
v16.0.0	لم يعد يُسمح باستخدام fsPromises.rmdir(path, { recursive: true }) على path غير موجود، وينتج عنه خطأ ENOENT.
v16.0.0	خيار recursive مُهمل، واستخدامه يُنشط تحذيرًا بالإهمال.
v14.14.0	خيار recursive مُهمل، استخدم fsPromises.rm بدلاً منه.
v13.3.0, v12.16.0	تم إعادة تسمية خيار maxBusyTries إلى maxRetries، وافتراضه هو 0. تم إزالة خيار emfileWait، وتستخدم أخطاء EMFILE نفس منطق إعادة المحاولة مثل الأخطاء الأخرى. تم دعم خيار retryDelay الآن. يتم إعادة محاولة أخطاء ENFILE الآن.
v12.10.0	تم دعم خيارات recursive و maxBusyTries و emfileWait الآن.
v10.0.0	مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> إذا تم مواجهة خطأ EBUSY أو EMFILE أو ENFILE أو ENOTEMPTY أو EPERM، فإن Node.js يعيد محاولة العملية مع انتظار تأخير خطي يبلغ retryDelay ميلي ثانية أطول في كل محاولة. يمثل هذا الخيار عدد المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive هو true. الافتراضي: 0.
  • recursive <boolean> إذا كان true، فقم بإزالة الدليل بشكل متكرر. في الوضع المتكرر، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false. مُهمل.
  • retryDelay <integer> مقدار الوقت بالميلي ثانية الذي يجب الانتظار خلاله بين المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive هو true. الافتراضي: 100.

• مُخرجات: <Promise> يتم الوفاء بـ undefined عند النجاح.

يزيل الدليل المحدد بواسطة path.

يؤدي استخدام fsPromises.rmdir() على ملف (وليس دليل) إلى رفض الوعد مع خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.

للحصول على سلوك مشابه لأمر rm -rf في يونكس، استخدم fsPromises.rm() مع الخيارات { recursive: true, force: true }.

fsPromises.rm(path[, options])

مُضافة في: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> عندما تكون true، سيتم تجاهل الاستثناءات إذا لم يكن path موجودًا. الافتراضي: false.
  • maxRetries <integer> إذا تم مواجهة خطأ EBUSY، EMFILE، ENFILE، ENOTEMPTY، أو EPERM، فسوف تعيد Node.js محاولة العملية مع انتظار تأخير خطي قدره retryDelay ميلي ثانية أطول في كل محاولة. يمثل هذا الخيار عدد المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive يساوي true. الافتراضي: 0.
  • recursive <boolean> إذا كانت true، قم بإجراء إزالة مُجلد مُتكررة. في وضع المُتكرر، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false.
  • retryDelay <integer> مقدار الوقت بالميلي ثانية الذي يجب الانتظار قبل إعادة المحاولة. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive يساوي true. الافتراضي: 100.

• المُخرجات: <Promise> يتم الوفاء بـ undefined عند النجاح.

يزيل الملفات والمجلدات (على غرار أداة POSIX القياسية rm).

fsPromises.stat(path[, options])

[السجل]

الإصدار	التغييرات
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرجعّة من نوع bigint.
v10.0.0	مُضافة في: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كانت القيم العددية في كائن <fs.Stats> المُرجع يجب أن تكون bigint. الافتراضي: false.

• المُخرجات: <Promise> يتم الوفاء بـ كائن <fs.Stats> للمسار المُعطى path.

fsPromises.statfs(path[, options])

مضاف في: v19.6.0، v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> هل يجب أن تكون القيم العددية في الكائن المُرجع <fs.StatFs> من نوع bigint. الافتراضي: false.

• المُرجَع: <Promise> يُفي بوعده مع كائن <fs.StatFs> للمسار المُعطى path.

fsPromises.symlink(target, path[, type])

[السجل]

الإصدار	التغييرات
v19.0.0	إذا كانت وسيطة type هي null أو مُهملة، فسوف يقوم Node.js باكتشاف نوع target تلقائيًا ويختار dir أو file تلقائيًا.
v10.0.0	مضاف في: v10.0.0

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> الافتراضي: null
• المُرجَع: <Promise> يُفي بوعده مع undefined عند النجاح.

يُنشئ رابطًا رمزيًا.

تُستخدم وسيطة type فقط على أنظمة التشغيل Windows ويمكن أن تكون أحدها 'dir'، 'file'، أو 'junction'. إذا كانت وسيطة type هي null، فسوف يقوم Node.js باكتشاف نوع target تلقائيًا ويستخدم 'file' أو 'dir'. إذا لم يكن target موجودًا، فسيتم استخدام 'file'. تتطلب نقاط الوصل في Windows أن يكون مسار الوجهة مسارًا مطلقًا. عند استخدام 'junction'، سيتم تطبيع وسيطة target تلقائيًا إلى مسار مطلق. لا يمكن لنقاط الوصل على وحدات تخزين NTFS أن تشير إلا إلى الدلائل.

fsPromises.truncate(path[, len])

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> افتراضيًا: 0
• القيمة المُرجعة: <Promise> يتم الوفاء به مع undefined عند النجاح.

يقصر (يقصّر أو يمد طول) محتوى path إلى len بايت.

fsPromises.unlink(path)

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• القيمة المُرجعة: <Promise> يتم الوفاء به مع undefined عند النجاح.

إذا كان path يشير إلى رابط رمزي، فسيتم إزالة الرابط دون التأثير على الملف أو الدليل الذي يشير إليه هذا الرابط. إذا كان path يشير إلى مسار ملف ليس رابطًا رمزيًا، فسيتم حذف الملف. راجع وثائق POSIX unlink(2) لمزيد من التفاصيل.

fsPromises.utimes(path, atime, mtime)

مضاف في: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• القيمة المُرجعة: <Promise> يتم الوفاء به مع undefined عند النجاح.

يُغيّر طوابع زمن نظام الملفات للكائن الذي يشير إليه path.

تتبع وسيطات atime و mtime هذه القواعد:

• يمكن أن تكون القيم أعدادًا تمثل وقت يونكس الإيبوك، أو Date، أو سلسلة رقمية مثل '123456789.0'.
• إذا تعذر تحويل القيمة إلى رقم، أو كانت NaN، أو Infinity، أو -Infinity، فسيتم طرح Error.

fsPromises.watch(filename[, options])

مضاف في: v15.9.0، v14.18.0

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> يشير إلى ما إذا كان يجب على العملية الاستمرار في التشغيل طالما يتم مراقبة الملفات. الافتراضي: true.
  • recursive <boolean> يشير إلى ما إذا كان يجب مراقبة جميع المجلدات الفرعية، أو المجلد الحالي فقط. ينطبق هذا عند تحديد مجلد، وفقط على الأنظمة الأساسية المدعومة (انظر تحذيرات). الافتراضي: false.
  • encoding <string> يحدد ترميز الأحرف الذي سيتم استخدامه لاسم الملف الذي تم تمريره إلى المُستمع. الافتراضي: 'utf8'.
  • signal <AbortSignal> إشارة <AbortSignal> تُستخدم للإشارة إلى متى يجب إيقاف مراقب الملفات.

• قيمة مُرجعة: <AsyncIterator> من الكائنات ذات الخصائص:

  • eventType <string> نوع التغيير
  • filename <string> | <Buffer> | <null> اسم الملف الذي تم تغييره.

يرجع مُكررًا غير متزامن يراقب التغييرات على filename، حيث filename هو ملف أو مجلد.

const { watch } = require('node:fs/promises')

const ac = new AbortController()
const { signal } = ac
setTimeout(() => ac.abort(), 10000)

;(async () => {
  try {
    const watcher = watch(__filename, { signal })
    for await (const event of watcher) console.log(event)
  } catch (err) {
    if (err.name === 'AbortError') return
    throw err
  }
})()

على معظم الأنظمة الأساسية، يتم إصدار 'rename' كلما ظهر اسم ملف أو اختفى في المجلد.

تنطبق جميع التحذيرات الخاصة بـ fs.watch() على fsPromises.watch() أيضًا.

fsPromises.writeFile(file, data[, options])

[History]

الإصدار	التغييرات
v21.0.0، v20.10.0	أصبح خيار flush مدعومًا الآن.
v15.14.0، v14.18.0	تدعم وسيطة data الآن AsyncIterable و Iterable و Stream.
v15.2.0، v14.17.0	قد تتضمن وسيطة الخيارات AbortSignal لإلغاء طلب writeFile جارٍ.
v14.0.0	لن تقوم وسيطة data بتحويل الإدخال غير المدعوم إلى سلاسل نصية بعد الآن.
v10.0.0	تمت الإضافة في: v10.0.0

• file <string> | <Buffer> | <URL> | <FileHandle> اسم الملف أو FileHandle

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> افتراضي: 'utf8'
  • mode <integer> افتراضي: 0o666
  • flag <string> انظر دعم علميات نظام الملفات. افتراضي: 'w'.
  • flush <boolean> إذا تم كتابة جميع البيانات بنجاح في الملف، و flush هو true، يتم استخدام filehandle.sync() لمسح البيانات. افتراضي: false.
  • signal <AbortSignal> يسمح بإلغاء عملية writeFile جارية

• الإرجاع: <Promise> يتم الوفاء به مع undefined عند النجاح.

يكتب البيانات بشكل غير متزامن إلى ملف، ويستبدل الملف إذا كان موجودًا بالفعل. يمكن أن يكون data سلسلة، أو مخزن مؤقت، أو كائن <AsyncIterable>، أو كائن <Iterable>.

يتم تجاهل خيار encoding إذا كان data مخزنًا مؤقتًا.

إذا كان options سلسلة، فإنه يحدد الترميز.

يؤثر خيار mode فقط على الملف الذي تم إنشاؤه حديثًا. راجع fs.open() لمزيد من التفاصيل.

يجب أن يدعم أي <FileHandle> محدد الكتابة.

من غير الآمن استخدام fsPromises.writeFile() عدة مرات على نفس الملف دون انتظار استقرار الوعد.

على غرار fsPromises.readFile - fsPromises.writeFile هي طريقة ملائمة تقوم بعدة مكالمات write داخليًا لكتابة المخزن المؤقت الذي تم تمريره إليه. بالنسبة للرمز الحساس للأداء، ضع في اعتبارك استخدام fs.createWriteStream() أو filehandle.createWriteStream().

من الممكن استخدام <AbortSignal> لإلغاء fsPromises.writeFile(). الإلغاء هو "أفضل جهد"، ومن المحتمل أن يتم كتابة بعض البيانات.

import { writeFile } from 'node:fs/promises'
import { Buffer } from 'node:buffer'

try {
  const controller = new AbortController()
  const { signal } = controller
  const data = new Uint8Array(Buffer.from('Hello Node.js'))
  const promise = writeFile('message.txt', data, { signal })

  // إلغاء الطلب قبل استقرار الوعد.
  controller.abort()

  await promise
} catch (err) {
  // عندما يتم إلغاء طلب - err هو AbortError
  console.error(err)
}

إلغاء الطلب الجاري لا يلغي طلبات نظام التشغيل الفردية، بل التخزين المؤقت الداخلي الذي يقوم به fs.writeFile.

fsPromises.constants

أضيف في: v18.4.0، v16.17.0

• <Object>

يرجع كائنًا يحتوي على ثوابت شائعة الاستخدام لعمليات نظام الملفات. الكائن هو نفسه fs.constants. راجع ثوابت نظام الملفات لمزيد من التفاصيل.

واجهة برمجة التطبيقات القائمة على المُنعطف

تقوم واجهات برمجة التطبيقات القائمة على المُنعطف بتنفيذ جميع العمليات بشكل غير متزامن، دون حظر حلقة الحدث، ثم تقوم باستدعاء دالة المُنعطف عند الإكمال أو حدوث خطأ.

تستخدم واجهات برمجة التطبيقات القائمة على المُنعطف مجموعة مؤشرات الترابط الأساسية في Node.js لأداء عمليات نظام الملفات خارج مؤشر ترابط حلقة الحدث. هذه العمليات ليست مُزامنة أو آمنة للخيوط. يجب توخي الحذر عند إجراء تعديلات متزامنة متعددة على نفس الملف، وإلا فقد يحدث تلف في البيانات.

fs.access(path[, mode], callback)

[السجل]

الإصدار	التغييرات
v20.8.0	الثوابت fs.F_OK، fs.R_OK، fs.W_OK و fs.X_OK التي كانت موجودة مباشرةً على fs قد تم إهمالها.
v18.0.0	تمرير مُنعطف غير صحيح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v7.6.0	يمكن أن تكون وسيطة path كائنًا من نوع URL WHATWG باستخدام بروتوكول file:
v6.3.0	تم نقل الثوابت مثل fs.R_OK، إلخ، الموجودة مباشرةً على fs إلى fs.constants كإهمال جزئي. وبالتالي، بالنسبة لـ Node.js < v6.3.0 استخدم fs للوصول إلى تلك الثوابت، أو قم بشيء مثل `(fs.constants
v0.11.15	تمت الإضافة في: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> الافتراضي: fs.constants.F_OK
• callback <Function>
  • err <Error>

يختبر أذونات المستخدم للملف أو الدليل المحدد بواسطة path. وسيطة mode هي عدد صحيح اختياري يُحدد عمليات فحص إمكانية الوصول التي سيتم تنفيذها. يجب أن تكون mode إما قيمة fs.constants.F_OK أو قناع يتكون من OR المنطقي لأي من fs.constants.R_OK، fs.constants.W_OK، و fs.constants.X_OK (مثلًا fs.constants.W_OK | fs.constants.R_OK). تحقق من ثوابت وصول الملف للحصول على القيم الممكنة لـ mode.

الوسيطة الأخيرة، callback، هي دالة مُنعطف يتم استدعاؤها مع وسيطة خطأ محتملة. إذا فشلت أي من عمليات فحص إمكانية الوصول، فستكون وسيطة الخطأ كائنًا من نوع Error. تُوضح الأمثلة التالية ما إذا كان package.json موجودًا، وما إذا كان قابلًا للقراءة أو الكتابة.

import { access, constants } from 'node:fs'

const file = 'package.json'

// تحقق ما إذا كان الملف موجودًا في الدليل الحالي.
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`)
})

// تحقق ما إذا كان الملف قابلًا للقراءة.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`)
})

// تحقق ما إذا كان الملف قابلًا للكتابة.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`)
})

// تحقق ما إذا كان الملف قابلًا للقراءة والكتابة.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`)
})

لا تستخدم fs.access() للتحقق من إمكانية الوصول إلى ملف قبل استدعاء fs.open()، fs.readFile()، أو fs.writeFile(). يؤدي القيام بذلك إلى إدخال حالة سباق، نظرًا لأن العمليات الأخرى قد تغير حالة الملف بين هاتين الدعوتين. بدلاً من ذلك، يجب على رمز المستخدم فتح/قراءة/كتابة الملف مباشرةً ومعالجة الخطأ الذي تم إثارة إذا لم يكن الملف قابلًا للوصول.

الكتابة (غير مُوصى بها)

import { access, open, close } from 'node:fs'

access('myfile', err => {
  if (!err) {
    console.error('myfile already exists')
    return
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err

    try {
      writeMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

الكتابة (مُوصى بها)

import { open, close } from 'node:fs'

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

القراءة (غير مُوصى بها)

import { access, open, close } from 'node:fs'
access('myfile', err => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist')
      return
    }

    throw err
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err

    try {
      readMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

القراءة (مُوصى بها)

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

الأمثلة "غير المُوصى بها" أعلاه تتحقق من إمكانية الوصول ثم تستخدم الملف؛ الأمثلة "المُوصى بها" أفضل لأنها تستخدم الملف مباشرةً وتعالج الخطأ، إن وجد.

بشكل عام، تحقق من إمكانية الوصول إلى ملف فقط إذا لم يتم استخدام الملف مباشرةً، على سبيل المثال عندما تكون إمكانية الوصول إليه إشارة من عملية أخرى.

في نظام التشغيل Windows، قد تحد سياسات التحكم في الوصول (ACLs) على دليل ما من الوصول إلى ملف أو دليل. ومع ذلك، لا تتحقق دالة fs.access() من ACL وبالتالي قد تُبلغ بأن المسار قابل للوصول حتى إذا كان ACL يمنع المستخدم من القراءة أو الكتابة إليه.

fs.appendFile(path, data[, options], callback)

[السجل]

الإصدار	التغييرات
v21.1.0, v20.10.0	أصبح خيار flush مدعومًا الآن.
v18.0.0	يؤدي تمرير مُدعَى مُراجِع غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إصدار تحذير من إلغاء الاستخدام برقم التعريف DEP0013.
v7.0.0	لن يتم تعديل كائن options المُمرر أبدًا.
v5.0.0	يمكن أن تكون وسيطة file مُوصِف ملف الآن.
v0.6.7	تمت الإضافة في: v0.6.7

• path <string> | <Buffer> | <URL> | <number> اسم الملف أو مُوصِف الملف

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> افتراضي: 'utf8'
  • mode <integer> افتراضي: 0o666
  • flag <string> انظر دعم علميات نظام الملفات flags. افتراضي: 'a'.
  • flush <boolean> إذا كان true، فسيتم إفراغ مُوصِف الملف الأساسي قبل إغلاقه. افتراضي: false.

• callback <Function>

  • err <Error>

إضافة بيانات بشكل غير متزامن إلى ملف، وإنشاء الملف إذا لم يكن موجودًا بعد. يمكن أن يكون data سلسلة أو <Buffer>.

يؤثر خيار mode فقط على الملف المُنشأ حديثًا. انظر fs.open() لمزيد من التفاصيل.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', err => {
  if (err) throw err
  console.log('تمت إضافة "data to append" إلى الملف!')
})

إذا كان options سلسلة، فسوف يحدد الترميز:

import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', 'utf8', callback)

يمكن تحديد path كمُوصِف ملف رقمي تم فتحه للإضافة (باستخدام fs.open() أو fs.openSync()). لن يتم إغلاق مُوصِف الملف تلقائيًا.

import { open, close, appendFile } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err

  try {
    appendFile(fd, 'data to append', 'utf8', err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

fs.chmod(path, mode, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير دالة مُراجعة غير صالحة إلى وسيطة callback الآن إلى إخراج ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إخراج TypeError أثناء وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن WHATWG URL باستخدام بروتوكول file:
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إصدار تحذير انتهاء الاستخدام برقم DEP0013.
v0.1.30	تمت الإضافة في: v0.1.30

• path <سلسلة> | <عازلة> | <عنوان URL>
• mode <سلسلة> | <عدد صحيح>
• callback <دالة>
  • err <خطأ>

يُغيّر بشكل غير متزامن أذونات ملف. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى دالة المُراجعة لإتمام العملية.

راجع وثائق POSIX chmod(2) لمزيد من التفاصيل.

import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('تم تغيير أذونات الملف "my_file.txt"!')
})

أوضاع الملف

تُعد وسيطة mode المستخدمة في كل من طريقتي fs.chmod() و fs.chmodSync() قناع بت رقمي تم إنشاؤه باستخدام OR المنطقي للثوابت التالية:

الثابت	ثماني	الوصف
fs.constants.S_IRUSR	0o400	القراءة من قِبل المالك
fs.constants.S_IWUSR	0o200	الكتابة من قِبل المالك
fs.constants.S_IXUSR	0o100	التنفيذ/البحث من قِبل المالك
fs.constants.S_IRGRP	0o40	القراءة من قِبل المجموعة
fs.constants.S_IWGRP	0o20	الكتابة من قِبل المجموعة
fs.constants.S_IXGRP	0o10	التنفيذ/البحث من قِبل المجموعة
fs.constants.S_IROTH	0o4	القراءة من قِبل الآخرين
fs.constants.S_IWOTH	0o2	الكتابة من قِبل الآخرين
fs.constants.S_IXOTH	0o1	التنفيذ/البحث من قِبل الآخرين

تُعد طريقة أسهل لإنشاء mode هي استخدام تسلسل من ثلاثة أرقام ثمانية (مثل 765). يحدد الرقم الأيسر (7 في المثال)، أذونات مالك الملف. يحدد الرقم الأوسط (6 في المثال)، أذونات المجموعة. يحدد الرقم الأيمن (5 في المثال)، أذونات الآخرين.

الرقم	الوصف
7	القراءة والكتابة والتنفيذ
6	القراءة والكتابة
5	القراءة والتنفيذ
4	القراءة فقط
3	الكتابة والتنفيذ
2	الكتابة فقط
1	التنفيذ فقط
0	لا يوجد إذن

على سبيل المثال، تعني القيمة الثمانية 0o765:

• يجوز للمالك القراءة والكتابة والتنفيذ في الملف.
• يجوز للمجموعة القراءة والكتابة في الملف.
• يجوز للآخرين القراءة والتنفيذ في الملف.

عند استخدام الأعداد الخام حيثما يتوقع أوضاع الملفات، قد تؤدي أي قيمة أكبر من 0o777 إلى سلوكيات خاصة بالمنصة غير مدعومة للعمل بشكل متسق. لذلك، لا يتم عرض ثوابت مثل S_ISVTX، S_ISGID، أو S_ISUID في fs.constants.

تحذيرات: في نظام Windows، لا يمكن تغيير سوى إذن الكتابة، ولا يتم تطبيق التمييز بين أذونات المجموعة أو المالك أو الآخرين.

fs.chown(path, uid, gid, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُستدعي غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير إهمال مع معرف DEP0013.
v0.1.97	تمت الإضافة في: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

يُغيّر بشكل غير متزامن مالك ومجموعة ملف. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُستدعي الإكمال.

راجع وثائق POSIX chown(2) لمزيد من التفاصيل.

fs.close(fd[, callback])

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُستدعي غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.9.0, v14.17.0	يتم الآن استخدام مُستدعي افتراضي إذا لم يتم توفيره.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير إهمال مع معرف DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• fd <integer>
• callback <Function>
  • err <Error>

يُغلق مُوصِف الملف. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُستدعي الإكمال.

قد يؤدي استدعاء fs.close() على أي مُوصِف ملف (fd) قيد الاستخدام حاليًا من خلال أي عملية fs أخرى إلى سلوك غير مُعرّف.

راجع وثائق POSIX close(2) لمزيد من التفاصيل.

fs.copyFile(src, dest[, mode], callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُعامل استدعاء غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v14.0.0	تم تغيير وسيطة flags إلى mode وفرض التحقق من نوع أكثر صرامة.
v8.5.0	تمت الإضافة في: v8.5.0

• src <string> | <Buffer> | <URL> اسم الملف المصدر المراد نسخه
• dest <string> | <Buffer> | <URL> اسم ملف الوجهة لعملية النسخ
• mode <integer> مُعدِّلات لعملية النسخ. الافتراضي: 0.
• callback <Function>
  • err <Error>

يقوم بنسخ src إلى dest بشكل غير متزامن. بشكل افتراضي، يتم الكتابة فوق dest إذا كان موجودًا بالفعل. لا تُعطى أي وسيطات أخرى بخلاف استثناء محتمل إلى دالة الاستدعاء. لا تقدم Node.js أي ضمانات حول ذرية عملية النسخ. إذا حدث خطأ بعد فتح ملف الوجهة للكتابة، ستحاول Node.js إزالة الوجهة.

mode هو عدد صحيح اختياري يُحدد سلوك عملية النسخ. من الممكن إنشاء قناع يتكون من OR المنطقي لواحد أو أكثر من القيم (على سبيل المثال، fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: ستفشل عملية النسخ إذا كان dest موجودًا بالفعل.
• fs.constants.COPYFILE_FICLONE: ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم يدعم النظام الأساسي copy-on-write، فسيتم استخدام آلية نسخ بديلة.
• fs.constants.COPYFILE_FICLONE_FORCE: ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم يدعم النظام الأساسي copy-on-write، فستفشل العملية.

import { copyFile, constants } from 'node:fs'

function callback(err) {
  if (err) throw err
  console.log('تم نسخ source.txt إلى destination.txt')
}

// سيتم إنشاء destination.txt أو الكتابة فوقه بشكل افتراضي.
copyFile('source.txt', 'destination.txt', callback)

// باستخدام COPYFILE_EXCL، ستفشل العملية إذا كان destination.txt موجودًا.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

fs.cp(src, dest[, options], callback)

[السجل]

الإصدار	التغييرات
v22.3.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v20.1.0, v18.17.0	قبول خيار mode إضافي لتحديد سلوك النسخ كوسيطة mode لـ fs.copyFile().
v18.0.0	يؤدي تمرير مُعالِج استدعاء غير صالح إلى وسيطة callback الآن إلى إخراج ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v17.6.0, v16.15.0	يقبل خيار verbatimSymlinks إضافي لتحديد ما إذا كان سيتم إجراء حل المسار للروابط الرمزية.
v16.7.0	تمت الإضافة في: v16.7.0

• src <string> | <URL> مسار المصدر المراد نسخه.

• dest <string> | <URL> مسار الوجهة المراد النسخ إليه.

• options <Object>

  • dereference <boolean> إلغاء مرجع الروابط الرمزية. الافتراضي: false.

  • errorOnExist <boolean> عندما يكون force مساويًا لـ false، وإذا وجدت الوجهة، فقم بإخراج خطأ. الافتراضي: false.

  • filter <Function> دالة لتصفية الملفات/الدلائل المُنسوخة. قم بإرجاع true لنسخ العنصر، و false لتجاهله. عند تجاهل دليل، سيتم تخطي جميع محتوياته أيضًا. يمكن أيضًا إرجاع Promise يحقق true أو false. الافتراضي: undefined.

  • src <string> مسار المصدر المراد نسخه.

  • dest <string> مسار الوجهة المراد النسخ إليه.

  • الإرجاع: <boolean> | <Promise> قيمة قابلة للتحويل إلى boolean أو Promise الذي يحقق مثل هذه القيمة.

  • force <boolean> الكتابة فوق الملف أو الدليل الموجود. ستتجاهل عملية النسخ الأخطاء إذا قمت بتعيين هذا إلى false وتوجد الوجهة. استخدم خيار errorOnExist لتغيير هذا السلوك. الافتراضي: true.

  • mode <integer> مُعدِّلات لعملية النسخ. الافتراضي: 0. انظر علم mode لـ fs.copyFile().

  • preserveTimestamps <boolean> عندما يكون true سيتم الحفاظ على طوابع الوقت من src. الافتراضي: false.

  • recursive <boolean> نسخ الدلائل بشكل متكرر الافتراضي: false

  • verbatimSymlinks <boolean> عندما يكون true، سيتم تخطي حل المسار للروابط الرمزية. الافتراضي: false

• callback <Function>

  • err <Error>

ينسخ بشكل غير متزامن هيكل الدليل بالكامل من src إلى dest، بما في ذلك الدلائل الفرعية والملفات.

عند نسخ دليل إلى دليل آخر، لا يتم دعم التعبيرات العامة ويكون السلوك مشابهًا لـ cp dir1/ dir2/.

fs.createReadStream(path[, options])

[History]

الإصدار	التغييرات
v16.10.0	خيار fs لا يحتاج إلى طريقة open إذا تم توفير fd.
v16.10.0	خيار fs لا يحتاج إلى طريقة close إذا كانت autoClose هي false.
v15.5.0	إضافة دعم لـ AbortSignal.
v15.4.0	خيار fd يقبل وسيطات FileHandle.
v14.0.0	تغيير قيمة emitClose الافتراضية إلى true.
v13.6.0, v12.17.0	تسمح خيارات fs بتجاوز تنفيذ fs المستخدم.
v12.10.0	تمكين خيار emitClose.
v11.0.0	فرض قيود جديدة على start و end، ورمي أخطاء أكثر ملاءمة في الحالات التي لا يمكننا فيها التعامل بشكل معقول مع قيم الإدخال.
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:.
v7.0.0	لن يتم تعديل كائن options المُمرر أبدًا.
v2.3.0	يمكن أن يكون كائن options المُمرر سلسلة الآن.
v0.1.31	تمت الإضافة في: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> انظر دعم نظام الملفات flags. الافتراضي: 'r'.
  • encoding <string> الافتراضي: null
  • fd <integer> | <FileHandle> الافتراضي: null
  • mode <integer> الافتراضي: 0o666
  • autoClose <boolean> الافتراضي: true
  • emitClose <boolean> الافتراضي: true
  • start <integer>
  • end <integer> الافتراضي: Infinity
  • highWaterMark <integer> الافتراضي: 64 * 1024
  • fs <Object> | <null> الافتراضي: null
  • signal <AbortSignal> | <null> الافتراضي: null

• الإرجاع: <fs.ReadStream>

يمكن أن يتضمن options قيم start و end لقراءة نطاق من البايتات من الملف بدلاً من الملف بالكامل. كل من start و end شاملان ويبدأ العد من 0، والقيم المسموح بها في نطاق [0، Number.MAX_SAFE_INTEGER]. إذا تم تحديد fd وتم حذف start أو تعيينه إلى undefined، فإن fs.createReadStream() يقرأ بشكل تسلسلي من موضع الملف الحالي. يمكن أن يكون encoding أيًا من تلك التي يقبلها <Buffer>.

إذا تم تحديد fd، فإن ReadStream سيتجاهل وسيطة path وسوف يستخدم مُعرّف الملف المحدد. وهذا يعني أنه لن يتم إصدار حدث 'open'. يجب أن يكون fd مُحجّمًا؛ يجب تمرير مُعرّفات fd غير المُحجّمة إلى <net.Socket>.

إذا كان fd يشير إلى جهاز حرفي يدعم فقط القراءات المُحجّمة (مثل لوحة المفاتيح أو بطاقة الصوت)، فإن عمليات القراءة لا تنتهي حتى تتوفر البيانات. هذا يمكن أن يمنع العملية من الخروج وتغلق الدفق بشكل طبيعي.

بشكل افتراضي، سيصدر الدفق حدث 'close' بعد تدميره. قم بتعيين خيار emitClose إلى false لتغيير هذا السلوك.

من خلال توفير خيار fs، من الممكن تجاوز تنفيذات fs المقابلة لـ open و read و close. عند توفير خيار fs، يلزم تجاوز لـ read. إذا لم يتم توفير fd، فيلزم أيضًا تجاوز لـ open. إذا كانت autoClose هي true، فيلزم أيضًا تجاوز لـ close.

import { createReadStream } from 'node:fs'

// إنشاء دفق من جهاز حرفي ما.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // قد لا يغلق هذا الدفق.
  // وضع علامة اصطناعية على نهاية الدفق، كما لو أن المورد الأساسي
  // أشار إلى نهاية الملف بنفسه، يسمح للدفق بالإغلاق.
  // هذا لا يلغي عمليات القراءة المعلقة، وإذا كانت هناك مثل هذه
  // العملية، فقد لا تتمكن العملية من الخروج بنجاح
  // حتى تنتهي.
  stream.push(null)
  stream.read(0)
}, 100)

إذا كانت autoClose خاطئة، فلن يتم إغلاق مُعرّف الملف، حتى لو حدث خطأ. تقع على عاتق التطبيق مسؤولية إغلاقه والتأكد من عدم وجود تسرب لمُعرّف الملف. إذا تم تعيين autoClose على true (السلوك الافتراضي)، فسيتم إغلاق مُعرّف الملف تلقائيًا عند حدوث 'error' أو 'end'.

يُعيّن mode وضع الملف (أذونات وبتات لاصقة)، ولكن فقط إذا تم إنشاء الملف.

مثال لقراءة آخر 10 بايتات من ملف طوله 100 بايت:

import { createReadStream } from 'node:fs'

createReadStream('sample.txt', { start: 90, end: 99 })

إذا كانت options سلسلة، فإنها تحدد الترميز.

fs.createWriteStream(path[, options])

[السجل]

الإصدار	التغييرات
v21.0.0, v20.10.0	أصبح خيار flush مدعومًا الآن.
v16.10.0	لم يعد خيار fs يحتاج إلى طريقة open إذا تم توفير fd.
v16.10.0	لم يعد خيار fs يحتاج إلى طريقة close إذا كانت قيمة autoClose هي false.
v15.5.0	إضافة دعم لـ AbortSignal.
v15.4.0	يقبل خيار fd وسيطات FileHandle.
v14.0.0	تغيير قيمة emitClose الافتراضية إلى true.
v13.6.0, v12.17.0	تسمح خيارات fs بتجاوز تنفيذ fs المستخدم.
v12.10.0	تمكين خيار emitClose.
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:.
v7.0.0	لن يتم تعديل كائن options المُمرر أبدًا.
v5.5.0	أصبح خيار autoClose مدعومًا الآن.
v2.3.0	يمكن أن يكون كائن options المُمرر سلسلة الآن.
v0.1.31	تمت الإضافة في: v0.1.31

• path <سلسلة> | <مخزن مؤقت> | <عنوان URL>

• options <سلسلة> | <كائن>

  • flags <سلسلة> انظر دعم أعلام نظام الملفات. الافتراضي: 'w'.
  • encoding <سلسلة> الافتراضي: 'utf8'
  • fd <عدد صحيح> | <FileHandle> الافتراضي: null
  • mode <عدد صحيح> الافتراضي: 0o666
  • autoClose <قيمة منطقية> الافتراضي: true
  • emitClose <قيمة منطقية> الافتراضي: true
  • start <عدد صحيح>
  • fs <كائن> | <لا شيء> الافتراضي: null
  • signal <AbortSignal> | <لا شيء> الافتراضي: null
  • highWaterMark <رقم> الافتراضي: 16384
  • flush <قيمة منطقية> إذا كانت true، فسيتم إفراغ مُعرّف الملف الأساسي قبل إغلاقه. الافتراضي: false.

• القيمة المُرجعة: <fs.WriteStream>

قد يتضمن options أيضًا خيار start للسماح بكتابة البيانات في مكان ما بعد بداية الملف، والقيم المسموح بها تتراوح بين [0، Number.MAX_SAFE_INTEGER]. قد يتطلب تعديل ملف بدلاً من استبداله تعيين خيار flags إلى r+ بدلاً من الافتراضي w. يمكن أن يكون encoding أيًا من تلك التي يقبلها <مخزن مؤقت>.

إذا تم تعيين autoClose على true (السلوك الافتراضي) على 'error' أو 'finish'، فسيتم إغلاق مُعرّف الملف تلقائيًا. إذا كانت قيمة autoClose هي false، فلن يتم إغلاق مُعرّف الملف، حتى لو حدث خطأ. تقع على عاتق التطبيق مسؤولية إغلاقه والتأكد من عدم وجود تسريب مُعرّفات ملفات.

بشكل افتراضي، سيصدر الدفق حدث 'close' بعد تدميره. قم بتعيين خيار emitClose إلى false لتغيير هذا السلوك.

من خلال توفير خيار fs، من الممكن تجاوز عمليات تنفيذ fs المقابلة لـ open، و write، و writev، و close. يمكن أن يؤدي تجاوز write() بدون writev() إلى تقليل الأداء حيث سيتم تعطيل بعض عمليات التحسين (_writev()). عند توفير خيار fs، يلزم وجود تجاوزات على الأقل لواحد من write و writev. إذا لم يتم توفير خيار fd، يلزم أيضًا تجاوز لـ open. إذا كانت قيمة autoClose هي true، يلزم أيضًا تجاوز لـ close.

مثل <fs.ReadStream>، إذا تم تحديد fd، فسيتجاهل <fs.WriteStream> وسيط path وسيستخدم مُعرّف الملف المحدد. هذا يعني أنه لن يتم إصدار حدث 'open'. يجب أن يكون fd مُحجِمًا؛ يجب تمرير fd غير المحجِم إلى <net.Socket>.

إذا كانت options سلسلة، فإنها تحدد الترميز.

fs.exists(path, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُعامل استدعاء غير صحيح إلى وسيطة callback يُطرح الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v7.6.0	يمكن أن تكون وسيطة path كائن WHATWG URL باستخدام بروتوكول file: .
v1.0.0	مُهمل منذ: v1.0.0
v0.0.2	مُضاف في: v0.0.2

[مستقر: 0 - مُهمل]

مستقر: 0 الثبات: 0 - مُهمل: استخدم fs.stat() أو fs.access() بدلاً من ذلك.

• path <سلسلة> | <مُخزن مؤقت> | <عنوان ويب>
• callback <دالة>
  • exists <قيمة منطقية>

اختبر ما إذا كان العنصر الموجود في path المعطى موجودًا أم لا من خلال التحقق من نظام الملفات. ثم قم باستدعاء وسيطة callback بقيمة true أو false:

import { exists } from 'node:fs'

exists('/etc/passwd', e => {
  console.log(e ? 'it exists' : 'no passwd!')
})

لا تتوافق معلمات مُعامل الاستدعاء هذا مع معلمات مُعاملات الاستدعاء الأخرى في Node.js. عادةً، تكون المعلمة الأولى لمُعامل استدعاء Node.js هي معلمة err، تليها اختياريًا معلمات أخرى. يحتوي مُعامل استدعاء fs.exists() على معلمة منطقية واحدة فقط. هذا هو أحد الأسباب التي يُنصح بها fs.access() بدلاً من fs.exists().

إذا كان path رابطًا رمزيًا، فسيتم اتباعه. وبالتالي، إذا كان path موجودًا ولكنه يشير إلى عنصر غير موجود، فسيستلم مُعامل الاستدعاء القيمة false.

لا يُنصح باستخدام fs.exists() للتحقق من وجود ملف قبل استدعاء fs.open()، أو fs.readFile()، أو fs.writeFile(). يؤدي القيام بذلك إلى إدخال حالة سباق، حيث قد تغير العمليات الأخرى حالة الملف بين هاتين الدعوتين. بدلاً من ذلك، يجب أن يفتح/يقرأ/يكتب المستخدم الملف مباشرةً ويتعامل مع الخطأ الذي يُثار إذا لم يكن الملف موجودًا.

الكتابة (غير مُنصح بها)

import { exists, open, close } from 'node:fs'

exists('myfile', e => {
  if (e) {
    console.error('myfile already exists')
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err

      try {
        writeMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  }
})

الكتابة (مُنصح بها)

import { open, close } from 'node:fs'
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

القراءة (غير مُنصح بها)

import { open, close, exists } from 'node:fs'

exists('myfile', e => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err

      try {
        readMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  } else {
    console.error('myfile does not exist')
  }
})

القراءة (مُنصح بها)

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

أمثلة "غير مُنصح بها" أعلاه تتحقق من الوجود ثم تستخدم الملف ؛ الأمثلة "المُنصح بها" أفضل لأنها تستخدم الملف مباشرةً وتتعامل مع الخطأ، إن وجد.

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

fs.fchmod(fd, mode, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُراجع مُعطّل إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال تحذير إهمال باستخدام معرف DEP0013.
v0.4.7	تمت الإضافة في: v0.4.7

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

يُعيّن الأذونات على الملف. لا تُعطى أي وسيطات أخرى غير استثناء محتمل إلى مُراجع الإكمال.

انظر وثائق POSIX fchmod(2) لمزيد من التفاصيل.

fs.fchown(fd, uid, gid, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُراجع مُعطّل إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال تحذير إهمال باستخدام معرف DEP0013.
v0.4.7	تمت الإضافة في: v0.4.7

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

يُعيّن مالك الملف. لا تُعطى أي وسيطات أخرى غير استثناء محتمل إلى مُراجع الإكمال.

انظر وثائق POSIX fchown(2) لمزيد من التفاصيل.

fs.fdatasync(fd, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صحيح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير إهمال مع معرف DEP0013.
v0.1.96	تمت الإضافة في: v0.1.96

• fd <integer>
• callback <Function>
  • err <Error>

يجبر جميع عمليات الإدخال/الإخراج المُصطفة حاليًا المرتبطة بالملف على حالة إكمال الإدخال/الإخراج المُزامن لنظام التشغيل. يرجى الرجوع إلى وثائق POSIX fdatasync(2) للحصول على التفاصيل. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُعامل استدعاء الإكمال.

fs.fstat(fd[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صحيح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة من نوع bigint.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير إهمال مع معرف DEP0013.
v0.1.95	تمت الإضافة في: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> ما إذا كان يجب أن تكون القيم العددية في كائن <fs.Stats> المُرتجع من نوع bigint. الافتراضي: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

يستدعي مُعامل الاستدعاء مع <fs.Stats> لوصف الملف.

راجع وثائق POSIX fstat(2) لمزيد من التفاصيل.

fs.fsync(fd, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعًى غير صالح إلى وسيطة callback الآن إلى إطلاق ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إطلاق TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير مُهمل مع معرف DEP0013.
v0.1.96	تمت الإضافة في: v0.1.96

• fd <integer>
• callback <Function>
  • err <Error>

طلب إفراغ جميع البيانات الخاصة بوصف الملف المفتوح إلى جهاز التخزين. يكون التنفيذ المحدد خاصًا بنظام التشغيل والجهاز. ارجع إلى وثائق POSIX fsync(2) لمزيد من التفاصيل. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُدعَى الإكمال.

fs.ftruncate(fd[, len], callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعًى غير صالح إلى وسيطة callback الآن إلى إطلاق ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إطلاق TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير مُهمل مع معرف DEP0013.
v0.8.6	تمت الإضافة في: v0.8.6

• fd <integer>
• len <integer> الافتراضي: 0
• callback <Function>
  • err <Error>

يقصر وصف الملف. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُدعَى الإكمال.

راجع وثائق POSIX ftruncate(2) لمزيد من التفاصيل.

إذا كان الملف المشار إليه بواسطة وصف الملف أكبر من len بايت، فلن يتم الاحتفاظ إلا بأول len بايت في الملف.

على سبيل المثال، يحتفظ البرنامج التالي بأول أربعة بايت فقط من الملف:

import { open, close, ftruncate } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err

  try {
    ftruncate(fd, 4, err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    if (err) throw err
  }
})

إذا كان الملف أقصر من len بايت سابقًا، فسيتم توسيعه، ويتم ملء الجزء الموسع ببايت فارغة ('\0'):

إذا كانت قيمة len سالبة، فسيتم استخدام 0.

fs.futimes(fd, atime, mtime, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُنادٍ غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُلقي خطأ TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بالإهمال برقم التعريف DEP0013.
v4.1.0	أصبحت السلاسل العددية و NaN و Infinity مواصفات وقت مسموح بها الآن.
v0.4.2	تمت الإضافة في: v0.4.2

• fd <عدد صحيح>
• atime <عدد> | <سلسلة> | <تاريخ>
• mtime <عدد> | <سلسلة> | <تاريخ>
• callback <دالة>
  • err <خطأ>

تغيير طوابع زمن نظام الملفات للكائن المشار إليه بواسطة مُعرّف الملف المُقدم. انظر fs.utimes().

fs.glob(pattern[, options], callback)

[السجل]

الإصدار	التغييرات
v22.2.0	إضافة دعم لـ withFileTypes كخيار.
v22.0.0	تمت الإضافة في: v22.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• pattern <سلسلة> | <مصفوفة سلاسل>

• options <كائن>

  • cwd <سلسلة> دليل العمل الحالي. الافتراضي: process.cwd()
  • exclude <دالة> دالة لتصفية الملفات/الدلائل. قم بإرجاع true لاستبعاد العنصر، و false لإدراجه. الافتراضي: undefined.
  • withFileTypes <قيمة منطقية> true إذا كان يجب أن تُرجع الدالة glob المسارات كـ Dirents، false بخلاف ذلك. الافتراضي: false.

• callback <دالة>

  • err <خطأ>

• يسترد الملفات المطابقة للنمط المحدد.

ESM

import { glob } from 'node:fs'

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

CJS

const { glob } = require('node:fs')

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

fs.lchmod(path, mode, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير دالة استدعاء غير صالحة إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.0.0	قد يكون الخطأ المُرجع هو AggregateError إذا تم إرجاع أكثر من خطأ واحد.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إرسال TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير من انتهاء الصلاحية برقم تعريف DEP0013.
v0.4.7	مُحذّر منذ: v0.4.7

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

يُغيّر الأذونات على رابط رمزي. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى دالة الاستدعاء لإتمام العملية.

هذه الطريقة مُطبقة فقط على macOS.

راجع وثائق POSIX lchmod(2) لمزيد من التفاصيل.

fs.lchown(path, uid, gid, callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير دالة استدعاء غير صالحة إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.6.0	لم يعد هذا الـ API مُحذّراً.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إرسال TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير من انتهاء الصلاحية برقم تعريف DEP0013.
v0.4.7	تحذير وثائق فقط.

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

تعيين مالك الرابط الرمزي. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى دالة الاستدعاء لإتمام العملية.

راجع وثائق POSIX lchown(2) لمزيد من التفاصيل.

fs.lutimes(path, atime, mtime, callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُنادٍ غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v14.5.0, v12.19.0	تمت الإضافة في: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

يُغيّر أوقات الوصول والتعديل للملف بنفس طريقة fs.utimes()، مع اختلاف أن المسار يشير إلى ارتباط رمزي، ثم لا يتم إلغاء مرجع الارتباط: بدلاً من ذلك، يتم تغيير طوابع الوقت لارتباط الرمزي نفسه.

لا تُعطى أي وسيطات أخرى غير استثناء محتمل إلى مُنادٍ إكمال.

fs.link(existingPath, newPath, callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُنادٍ غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إلقاء TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطتا existingPath و newPath كائنات WHATWG URL باستخدام بروتوكول file: . الدعم لا يزال تجريبيًا حاليًا.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إصدار تحذير من إهمال باستخدام المعرف DEP0013.
v0.1.31	تمت الإضافة في: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

يُنشئ ارتباطًا جديدًا من existingPath إلى newPath. راجع وثائق POSIX link(2) لمزيد من التفاصيل. لا تُعطى أي وسيطات أخرى غير استثناء محتمل إلى مُنادٍ إكمال.

fs.lstat(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة من نوع bigint.
v10.0.0	لم يعد مُعامل callback اختياريًا. لن يؤدي عدم تمريره إلا إلى طرح TypeError أثناء وقت التشغيل.
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file:.
v7.0.0	لم يعد مُعامل callback اختياريًا. لن يؤدي عدم تمريره إلا إلى إصدار تحذير بإلغاء الاستخدام برقم تعريف DEP0013.
v0.1.30	تمت الإضافة في: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كان يجب أن تكون القيم العددية في كائن <fs.Stats> المُرتجع من نوع bigint. الافتراضي: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

يسترد <fs.Stats> للارتباط الرمزي المُشار إليه بواسطة المسار. يحصل مُعامل الاستدعاء على وسيطين (err, stats) حيث أن stats هو كائن <fs.Stats>. lstat() مطابق لـ stat()، إلا أنه إذا كان path رابطًا رمزيًا، فسيتم فحص الرابط نفسه، وليس الملف الذي يشير إليه.

راجع وثائق POSIX lstat(2) لمزيد من التفاصيل.

fs.mkdir(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُعاودة اتصال غير صالحة إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v13.11.0، v12.17.0	في الوضع recursive، تتلقى مُعاودة الاتصال الآن مسار الدليل المُنشأ أولاً كوسيط.
v10.12.0	يمكن أن يكون الوسيط الثاني الآن كائن options مع خصائص recursive و mode.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إلقاء TypeError وقت التشغيل.
v7.6.0	يمكن أن يكون وسيط path كائن URL من WHATWG باستخدام بروتوكول file:.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إصدار تحذير من إلغاء الاستخدام مع معرف DEP0013.
v0.1.8	تمت الإضافة في: v0.1.8

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> الافتراضي: false
  • mode <string> | <integer> غير مدعوم على Windows. الافتراضي: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> موجود فقط إذا تم إنشاء دليل مع تعيين recursive إلى true.

يُنشئ دليلًا بشكل غير متزامن.

يتم إعطاء مُعاودة الاتصال استثناءً ممكنًا، وإذا كان recursive هو true، فإن مسار الدليل الأول المُنشأ، (err[, path]). يمكن أن يكون path لا يزال undefined عندما يكون recursive هو true، إذا لم يتم إنشاء أي دليل (على سبيل المثال، إذا تم إنشاؤه مسبقًا).

يمكن أن تكون وسيطة options الاختيارية عددًا صحيحًا يُحدد mode (أذونات الوصول وبتات اللصق)، أو كائنًا يحتوي على خاصية mode وخاصية recursive تشير إلى ما إذا كان يجب إنشاء أدلة الأصول. يؤدي استدعاء fs.mkdir() عندما يكون path دليلًا موجودًا إلى حدوث خطأ فقط عندما يكون recursive خاطئًا. إذا كان recursive خاطئًا وكان الدليل موجودًا، فسيحدث خطأ EEXIST.

import { mkdir } from 'node:fs'

// إنشاء ./tmp/a/apple، بغض النظر عما إذا كان ./tmp و ./tmp/a موجودين.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

على Windows، سيؤدي استخدام fs.mkdir() في الدليل الجذر حتى مع التكرار إلى حدوث خطأ:

import { mkdir } from 'node:fs'

mkdir('/', { recursive: true }, err => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
})

راجع وثائق POSIX mkdir(2) لمزيد من التفاصيل.

fs.mkdtemp(prefix[, options], callback)

[History]

الإصدار	التغييرات
v20.6.0، v18.19.0	الآن، تقبل معلمة prefix المخزّنات المؤقتة وعنوان URL.
v18.0.0	يؤدي تمرير دالة مُراجعة غير صالحة إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.5.0، v14.18.0	الآن، تقبل معلمة prefix سلسلة فارغة.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إرسال تحذير انتهاء الاستخدام برقم تعريف DEP0013.
v6.2.1	أصبحت وسيطة callback اختيارية الآن.
v5.10.0	تمت الإضافة في: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• callback <Function>

  • err <Error>
  • directory <string>

إنشاء دليل مؤقت فريد.

يُنشئ ستة أحرف عشوائية لإضافتها خلف بادئة مطلوبة لإنشاء دليل مؤقت فريد. نظرًا لتناقضات النظام الأساسي، تجنّب أحرف X النهائية في prefix. قد تُعيد بعض الأنظمة الأساسية، ولا سيما أنظمة BSD، أكثر من ستة أحرف عشوائية، واستبدال أحرف X النهائية في prefix بأحرف عشوائية.

يتم تمرير مسار الدليل المُنشأ كسلسلة إلى الوسيط الثاني للدالة المُراجعة.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف المُراد استخدامه.

import { mkdtemp } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err
  console.log(directory)
  // يُطبع: /tmp/foo-itXde2 أو C:\Users\...\AppData\Local\Temp\foo-itXde2
})

ستقوم طريقة fs.mkdtemp() بإضافة الأحرف الستة المُحددة عشوائيًا مباشرةً إلى سلسلة prefix. على سبيل المثال، بالنظر إلى دليل /tmp، إذا كان الهدف هو إنشاء دليل مؤقت ضمن /tmp، فيجب أن تنتهي prefix بفاصل مسار محدد بنظام التشغيل (require('node:path').sep).

import { tmpdir } from 'node:os'
import { mkdtemp } from 'node:fs'

// الدليل الرئيسي للدليل المؤقت الجديد
const tmpDir = tmpdir()

// هذه الطريقة *غير صحيحة*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // سيُطبع شيء مشابه لـ `/tmpabc123`.
  // يتم إنشاء دليل مؤقت جديد في جذر نظام الملفات
  // بدلاً من *داخل* دليل /tmp.
})

// هذه الطريقة *صحيحة*:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // سيُطبع شيء مشابه لـ `/tmp/abc123`.
  // يتم إنشاء دليل مؤقت جديد داخل
  // دليل /tmp.
})

fs.open(path[, flags[, mode]], callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير دالة استدعاء غير صالحة إلى وسيطة callback يؤدي الآن إلى إلقاء ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v11.1.0	أصبحت وسيطة flags اختيارية الآن، وافتراضياً تساوي 'r'.
v9.9.0	يتم دعم علميّ as و as+ الآن.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v0.0.2	تمت الإضافة في: v0.0.2

• path <string> | <Buffer> | <URL>
• flags <string> | <number> انظر دعم أعلام نظام الملفات. الافتراضي: 'r'.
• mode <string> | <integer> الافتراضي: 0o666 (قابل للقراءة والكتابة)
• callback <Function>
  • err <Error>
  • fd <integer>

فتح ملف غير متزامن. راجع وثائق POSIX open(2) لمزيد من التفاصيل.

يحدد mode وضع الملف (الأذونات وبتات اللصق)، ولكن فقط إذا تم إنشاء الملف. في نظام Windows، لا يمكن التلاعب إلا بأذونات الكتابة؛ راجع fs.chmod().

تحصل دالة الاستدعاء على وسيطين (err, fd).

بعض الأحرف (\< \> : " / \ | ? *) محجوزة في نظام Windows كما هو موثق في تسمية الملفات والمسارات ومساحات الأسماء. في نظام NTFS، إذا كان اسم الملف يحتوي على نقطتين، فسيفتح Node.js دفق نظام ملفات، كما هو موضح في صفحة MSDN هذه.

تُظهر الوظائف القائمة على fs.open() هذا السلوك أيضًا: fs.writeFile()، fs.readFile()، إلخ.

fs.openAsBlob(path[, options])

تم الإضافة في: v19.8.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• path <string> | <Buffer> | <URL>

• options <Object>

  • type <string> نوع MIME اختياري للـ blob.

• الإرجاع: <Promise> يُفي بـ <Blob> عند النجاح.

يُعيد <Blob> تعتمد بياناتها على الملف المعطى.

يجب عدم تعديل الملف بعد إنشاء <Blob>. ستؤدي أي تعديلات إلى فشل قراءة بيانات <Blob> مع خطأ DOMException. عمليات الحالة المتزامنة على الملف عند إنشاء Blob، وقبل كل قراءة من أجل اكتشاف ما إذا تم تعديل بيانات الملف على القرص.

ESM

import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()

CJS

const { openAsBlob } = require('node:fs')

;(async () => {
  const blob = await openAsBlob('the.file.txt')
  const ab = await blob.arrayBuffer()
  blob.stream()
})()

fs.opendir(path[, options], callback)

[السجل]

الإصدار	التغييرات
v20.1.0, v18.17.0	تمت إضافة خيار recursive.
v18.0.0	تمرير مُدعمة غير صالحة إلى وسيطة callback الآن يُلقي ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v13.1.0, v12.16.0	تم تقديم خيار bufferSize.
v12.12.0	تمت الإضافة في: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> الافتراضي: 'utf8'
  • bufferSize <number> عدد إدخالات الدليل التي يتم تخزينها مؤقتًا داخليًا عند القراءة من الدليل. تؤدي القيم الأعلى إلى أداء أفضل ولكن استخدامًا أعلى للذاكرة. الافتراضي: 32
  • recursive <boolean> الافتراضي: false

• callback <Function>

  • err <Error>
  • dir <fs.Dir>

فتح دليل بشكل غير متزامن. راجع وثائق POSIX opendir(3) لمزيد من التفاصيل.

يُنشئ <fs.Dir>، والذي يحتوي على جميع الوظائف الأخرى للقراءة من الدليل وتنظيفه.

يحدد خيار encoding ترميز path أثناء فتح الدليل وعمليات القراءة اللاحقة.

fs.read(fd, buffer, offset, length, position, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُدعًى غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.10.0	يمكن أن تكون وسيطة buffer الآن أي TypedArray، أو DataView.
v7.4.0	يمكن أن تكون وسيطة buffer الآن Uint8Array.
v6.0.0	يمكن أن تكون وسيطة length الآن 0.
v0.0.2	تمت الإضافة في: v0.0.2

• fd <عدد صحيح>
• buffer <عازلة> | <TypedArray> | <DataView> العازلة التي سيتم كتابة البيانات فيها.
• offset <عدد صحيح> الموضع في buffer لكتابة البيانات فيه.
• length <عدد صحيح> عدد البايتات التي سيتم قراءتها.
• position <عدد صحيح> | <عدد صحيح كبير> | <لا شيء> يحدد مكان البدء في القراءة من الملف. إذا كان position يساوي null أو -1، فسيتم قراءة البيانات من موضع الملف الحالي، وسيتم تحديث موضع الملف. إذا كان position عددًا صحيحًا غير سالب، فلن يتغير موضع الملف.
• callback <دالة>
  • err <خطأ>
  • bytesRead <عدد صحيح>
  • buffer <عازلة>

قراءة البيانات من الملف المحدد بواسطة fd.

يتم إعطاء المُدعًى ثلاثة وسيطات، (err, bytesRead, buffer).

إذا لم يتم تعديل الملف بالتزامن، فسيتم الوصول إلى نهاية الملف عندما يكون عدد البايتات المقروءة صفرًا.

إذا تم استدعاء هذه الطريقة كنسختها المُعدة بواسطة util.promisify()، فإنها تُرجع وعدًا لكائن يحتوي على خصائص bytesRead و buffer.

تقوم طريقة fs.read() بقراءة البيانات من الملف المحدد بواسطة مُحدد الملف (fd). تشير وسيطة length إلى الحد الأقصى لعدد البايتات التي ستحاول Node.js قراءتها من نواة النظام. ومع ذلك، فإن العدد الفعلي للبايتات المقروءة (bytesRead) يمكن أن يكون أقل من length المحدد لأسباب مختلفة.

على سبيل المثال:

• إذا كان الملف أقصر من length المحدد، فسيتم تعيين bytesRead إلى العدد الفعلي للبايتات المقروءة.
• إذا واجه الملف نهاية الملف (EOF) قبل ملء العازلة، فستقوم Node.js بقراءة جميع البايتات المتاحة حتى يتم الوصول إلى نهاية الملف، وسيشير مُعامل bytesRead في المُدعًى إلى العدد الفعلي للبايتات المقروءة، والذي قد يكون أقل من length المحدد.
• إذا كان الملف موجودًا على نظام ملفات شبكي بطيء أو واجه أي مشكلة أخرى أثناء القراءة، فقد يكون bytesRead أقل من length المحدد.

لذلك، عند استخدام fs.read()، من المهم التحقق من قيمة bytesRead لتحديد عدد البايتات التي تم قراءتها بالفعل من الملف. بناءً على منطق تطبيقك، قد تحتاج إلى معالجة الحالات التي يكون فيها bytesRead أقل من length المحدد، مثل لفّ مكالمة القراءة في حلقة إذا كنت تحتاج إلى الحد الأدنى من البايتات.

هذا السلوك مشابه لوظيفة POSIX preadv2.

fs.read(fd[, options], callback)

[History]

الإصدار	التغييرات
v13.11.0, v12.17.0	يمكن تمرير كائن الخيارات لجعل العناصر buffer، offset، length، و position اختيارية.
v13.11.0, v12.17.0	تمت الإضافة في: v13.11.0, v12.17.0

• fd <integer>

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> الافتراضي: Buffer.alloc(16384)
  • offset <integer> الافتراضي: 0
  • length <integer> الافتراضي: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> الافتراضي: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

يشبه وظيفة fs.read() ، يأخذ هذا الإصدار كائن options اختياريًا. إذا لم يتم تحديد كائن options، فسيتم تعيين القيم الافتراضية أعلاه.

fs.read(fd, buffer[, options], callback)

مُضافة في: v18.2.0، v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView> المخزن المؤقت الذي سيتم كتابة البيانات فيه.

• options <Object>

  • offset <integer> افتراضيًا: 0
  • length <integer> افتراضيًا: buffer.byteLength - offset
  • position <integer> | <bigint> افتراضيًا: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

يشبه دالة fs.read() هذه النسخة، تأخذ كائن options اختياري. إذا لم يتم تحديد كائن options، فسيتم تعيين القيم الافتراضية أعلاه.

fs.readdir(path[, options], callback)

[السجل]

الإصدار	التغييرات
v20.1.0، v18.17.0	تمت إضافة خيار recursive.
v18.0.0	يؤدي تمرير مُسْتَدْعَى غير صالح إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.10.0	تمت إضافة خيار جديد withFileTypes.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إرسال TypeError في وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إرسال تحذير بالإهمال برقم التعريف DEP0013.
v6.0.0	تمت إضافة وسيطة options.
v0.1.8	مُضافة في: v0.1.8

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> افتراضيًا: 'utf8'
  • withFileTypes <boolean> افتراضيًا: false
  • recursive <boolean> إذا كان true، يقرأ محتويات الدليل بشكل متكرر. في الوضع المتكرر، سيقوم بإدراج جميع الملفات والملفات الفرعية والدلائل. افتراضيًا: false.

• callback <Function>

  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

يقرأ محتويات الدليل. يحصل المُسْتَدْعَى على وسيطين (err, files) حيث أن files عبارة عن مصفوفة من أسماء الملفات في الدليل باستثناء '.' و '..'.

راجع وثائق POSIX readdir(3) لمزيد من التفاصيل.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف المُستخدم لأسماء الملفات المُمررة إلى المُسْتَدْعَى. إذا تم تعيين encoding على 'buffer'، فستتم تمرير أسماء الملفات المُرجعّة كأشياء <Buffer>.

إذا تم تعيين options.withFileTypes على true، فستحتوي مصفوفة files على كائنات <fs.Dirent>.

fs.readFile(path[, options], callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُنادٍ غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.0.0	قد يكون الخطأ المُرتدّ AggregateError إذا تم إرجاع أكثر من خطأ واحد.
v15.2.0، v14.17.0	قد تتضمن وسيطة الخيارات AbortSignal لإلغاء طلب readFile قيد التنفيذ.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُلقي TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بالإهمال برقم تعريف DEP0013.
v5.1.0	سيتم دائمًا استدعاء callback مع null كوسيطه error في حالة النجاح.
v5.0.0	يمكن أن تكون وسيطة path مُعرّف ملف الآن.
v0.1.29	تمت الإضافة في: v0.1.29

• path <سلسلة> | <عازلة> | <عنوان URL> | <عدد صحيح> اسم الملف أو مُعرّف الملف

• options <كائن> | <سلسلة>

  • encoding <سلسلة> | <لاشيء> الافتراضي: null
  • flag <سلسلة> انظر دعم علامات نظام الملفات. الافتراضي: 'r'.
  • signal <AbortSignal> يسمح بإلغاء readFile قيد التنفيذ

• callback <دالة>

  • err <خطأ> | <AggregateError>
  • data <سلسلة> | <عازلة>

يقوم بقراءة محتويات الملف بالكامل بشكل غير متزامن.

import { readFile } from 'node:fs'

readFile('/etc/passwd', (err, data) => {
  if (err) throw err
  console.log(data)
})

يتم تمرير المُنادى إلى وسيطين (err, data)، حيث أن data هي محتويات الملف.

إذا لم يتم تحديد ترميز، فسيتم إرجاع العازلة الخام.

إذا كانت options سلسلة، فستحدد الترميز:

import { readFile } from 'node:fs'

readFile('/etc/passwd', 'utf8', callback)

عندما يكون المسار هو دليل، فإن سلوك fs.readFile() و fs.readFileSync() يعتمد على النظام الأساسي. على macOS و Linux و Windows، سيتم إرجاع خطأ. على FreeBSD، سيتم إرجاع تمثيل لمحتويات الدليل.

import { readFile } from 'node:fs'

// macOS و Linux و Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: عملية غير قانونية على دليل، قراءة <directory>]
})

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null، <data>
})

من الممكن إلغاء طلب قيد التنفيذ باستخدام AbortSignal. إذا تم إلغاء طلب، يتم استدعاء المُنادى مع AbortError:

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// عندما تريد إلغاء الطلب
controller.abort()

تُخزّن دالة fs.readFile() الملف بالكامل. لتقليل تكاليف الذاكرة، عند الإمكان، فضّل البث عبر fs.createReadStream().

إن إلغاء طلب قيد التنفيذ لا يُلغي طلبات نظام التشغيل الفردية، بل التخزين المؤقت الداخلي الذي يقوم به fs.readFile.

مُوصِفات الملفات

اعتبارات الأداء

تقوم طريقة fs.readFile() بقراءة محتويات الملف بشكل غير متزامن في الذاكرة جزءًا تلو الآخر، مما يسمح لحلقة الحدث بالتبديل بين كل جزء. يسمح هذا لعملية القراءة بأن يكون لها تأثير أقل على الأنشطة الأخرى التي قد تستخدم تجمع خيوط libuv الأساسي، ولكن هذا يعني أنه سيستغرق وقتًا أطول لقراءة ملف كامل في الذاكرة.

يمكن أن تختلف تكلفة القراءة الإضافية اختلافًا كبيرًا على أنظمة مختلفة وتعتمد على نوع الملف الذي يتم قراءته. إذا لم يكن نوع الملف ملفًا عاديًا (أنبوب على سبيل المثال) ولم تتمكن Node.js من تحديد حجم ملف فعلي، فستقوم كل عملية قراءة بتحميل 64 كيلوبايت من البيانات. بالنسبة للملفات العادية، ستقوم كل قراءة بمعالجة 512 كيلوبايت من البيانات.

بالنسبة للتطبيقات التي تتطلب قراءة محتويات الملف بأسرع وقت ممكن، من الأفضل استخدام fs.read() مباشرة ولتقوم شفرة التطبيق بإدارة قراءة محتويات الملف بالكامل بنفسها.

تقدم مشكلة Node.js على GitHub رقم #25741 مزيدًا من المعلومات وتحليلًا مفصلًا لأداء fs.readFile() لأحجام ملفات متعددة في إصدارات Node.js المختلفة.

fs.readlink(path[, options], callback)

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُنعطف غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى طرح TypeError في وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلى إصدار تحذير من إلغاء الاستخدام برقم معرف DEP0013.
v0.1.31	تمت الإضافة في: v0.1.31

• path <سلسلة> | <مُخزن مؤقت> | <عنوان URL>

• options <سلسلة> | <كائن>

  • encoding <سلسلة> افتراضي: 'utf8'

• callback <دالة>

  • err <خطأ>
  • linkString <سلسلة> | <مُخزن مؤقت>

يقرأ محتويات الرابط الرمزي المشار إليه بواسطة path. يحصل المُنعطف على وسيطين (err, linkString).

راجع وثائق POSIX readlink(2) لمزيد من التفاصيل.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي يجب استخدامه لمسار الرابط الممرر إلى المُنعطف. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير مسار الرابط المُرجع ككائن <مُخزن مؤقت>.

fs.readv(fd, buffers[, position], callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُعامل استدعاء غير صالح إلى وسيطة callback يُطلق الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v13.13.0, v12.17.0	تمت الإضافة في: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> الافتراضي: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

القراءة من ملف محدد بواسطة fd والكتابة في مصفوفة من ArrayBufferView باستخدام readv().

position هو الإزاحة من بداية الملف الذي يجب قراءة البيانات منه. إذا كان typeof position !== 'number', فسيتم قراءة البيانات من الموضع الحالي.

سيتم إعطاء مُعامل الاستدعاء ثلاث وسيطات: err, bytesRead, و buffers. bytesRead هو عدد البايتات التي تم قراءتها من الملف.

إذا تم استدعاء هذه الطريقة كنسختها المُعدة بواسطة util.promisify()، فإنها تُرجع وعدًا لكائن يحتوي على خصائص bytesRead و buffers.

fs.realpath(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُعامل استدعاء غير صالح إلى وسيطة callback يُطلق الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُطلق خطأ TypeError وقت التشغيل.
v8.0.0	تمت إضافة دعم حل أنبوب/مقبس.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بالإهمال برقم تعريف DEP0013.
v6.4.0	تعمل الآن مكالمة realpath مرة أخرى لحالات الحافة المختلفة على Windows.
v6.0.0	تمت إزالة وسيطة cache.
v0.1.31	تمت الإضافة في: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

يحسب بشكل غير متزامن اسم المسار القانوني عن طريق حل ., .., والروابط الرمزية.

اسم المسار القانوني ليس بالضرورة فريدًا. يمكن للروابط الثابتة وتركيبات الربط عرض كيان نظام ملفات من خلال العديد من أسماء المسارات.

تتصرف هذه الدالة مثل realpath(3)، مع بعض الاستثناءات:

يحصل callback على وسيطتين (err, resolvedPath). قد يستخدم process.cwd لحل المسارات النسبية.

يتم دعم المسارات التي يمكن تحويلها إلى سلاسل UTF8 فقط.

يمكن أن تكون وسيطة options الاختيارية سلسلة تُحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تُحدد ترميز الأحرف الذي يجب استخدامه للمسار الممرر إلى مُعامل الاستدعاء. إذا تم تعيين encoding على 'buffer', فسيتم تمرير المسار المُرجَع ككائن <Buffer>.

إذا تم حل path إلى مقبس أو أنبوب، فستعيد الدالة اسمًا يعتمد على النظام لذلك الكائن.

يؤدي المسار الذي لا يوجد إلى خطأ ENOENT. error.path هو المسار المطلق للملف.

fs.realpath.native(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى خاطئ إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v9.2.0	تمت الإضافة في: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

بشكل غير متزامن realpath(3).

يحصل callback على وسيطين (err, resolvedPath).

يتم دعم المسارات التي يمكن تحويلها إلى سلاسل UTF8 فقط.

يمكن أن تكون وسيطة options الاختيارية سلسلة محددة ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف المُستخدم للمسار المُمرر إلى المُدعًى. إذا تم تعيين encoding إلى 'buffer'، فسيتم تمرير المسار المُرجَع ككائن <Buffer>.

على نظام Linux، عندما يتم ربط Node.js بـ musl libc، يجب تركيب نظام ملفات procfs على /proc لكي تعمل هذه الوظيفة. لا يحتوي Glibc على هذا التقييد.

fs.rename(oldPath, newPath, callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى خاطئ إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إلقاء TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطتا oldPath و newPath كائنات WHATWG URL باستخدام بروتوكول file: . الدعم لا يزال تجريبيًا حاليًا.
v7.0.0	لم تعد وسيطة callback اختيارية. لن يؤدي عدم تمريرها إلا إلى إصدار تحذير من إلغاء الاستخدام باستخدام معرف DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

قم بإعادة تسمية الملف بشكل غير متزامن في oldPath إلى اسم المسار المُقدم كـ newPath. في حالة وجود newPath بالفعل، سيتم الكتابة فوقه. إذا كان هناك دليل في newPath، فسيتم إثارة خطأ بدلاً من ذلك. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُدعًى الإكمال.

انظر أيضًا: rename(2).

import { rename } from 'node:fs'

rename('oldFile.txt', 'newFile.txt', err => {
  if (err) throw err
  console.log('Rename complete!')
})

fs.rmdir(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.0.0	لم يعد يُسمح باستخدام fs.rmdir(path, { recursive: true }) على مسار path وهو ملف، وينتج عنه خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.
v16.0.0	لم يعد يُسمح باستخدام fs.rmdir(path, { recursive: true }) على مسار path غير موجود، وينتج عنه خطأ ENOENT.
v16.0.0	خيار recursive مُهمل، واستخدامه يُنشِط تحذيرًا بالإهمال.
v14.14.0	خيار recursive مُهمل، استخدم fs.rm بدلاً منه.
v13.3.0، v12.16.0	تم تغيير اسم خيار maxBusyTries إلى maxRetries، وافتراضيته هو 0. تم إزالة خيار emfileWait، وتستخدم أخطاء EMFILE نفس منطق إعادة المحاولة مثل الأخطاء الأخرى. تم دعم خيار retryDelay الآن. يتم إعادة محاولة أخطاء ENFILE الآن.
v12.10.0	تم دعم خيارات recursive وmaxBusyTries وemfileWait الآن.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُطرح خطأ TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون معلمات path كائن WHATWG URL باستخدام بروتوكول file:.
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بالإهمال برقم DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> إذا تم مواجهة خطأ EBUSY أو EMFILE أو ENFILE أو ENOTEMPTY أو EPERM، فإن Node.js يُعيد محاولة العملية مع انتظار تأخير خطي يبلغ retryDelay ميلي ثانية أطول في كل محاولة. يمثل هذا الخيار عدد المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 0.
  • recursive <boolean> إذا كان true، فقم بإزالة الدليل بشكل متكرر. في الوضع المتكرر، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false. مُهمل.
  • retryDelay <integer> مقدار الوقت بالميلي ثانية الذي يجب الانتظار بين المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 100.

• callback <Function>

  • err <Error>

غير متزامن rmdir(2). لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُعامل استدعاء الإكمال.

يؤدي استخدام fs.rmdir() على ملف (وليس دليل) إلى خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.

لحصول على سلوك مشابه لأمر rm -rf في يونكس، استخدم fs.rm() مع الخيارات { recursive: true, force: true }.

fs.rm(path[, options], callback)

[History]

الإصدار	التغييرات
v17.3.0, v16.14.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file:
v14.14.0	تمت الإضافة في: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> عندما تكون true، سيتم تجاهل الاستثناءات إذا لم يكن path موجودًا. الافتراضي: false.
  • maxRetries <integer> إذا تم مواجهة خطأ EBUSY، أو EMFILE، أو ENFILE، أو ENOTEMPTY، أو EPERM، فستعيد Node.js محاولة العملية مع انتظار تأخير خطي يبلغ retryDelay ميلي ثانية أطول في كل محاولة. يمثل هذا الخيار عدد المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 0.
  • recursive <boolean> إذا كانت true، قم بإجراء إزالة متكررة. في وضع التكرار، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false.
  • retryDelay <integer> مقدار الوقت بالميلي ثانية الذي يجب الانتظار خلاله بين المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 100.

• callback <Function>

  • err <Error>

يزيل الملفات والمجلدات بشكل غير متزامن (بناءً على أداة POSIX القياسية rm). لا تُعطى أي حجج أخرى غير استثناء محتمل إلى دالة الاستدعاء النهائية.

fs.stat(path[, options], callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير دالة استدعاء غير صالحة إلى وسيطة callback يُحدث الآن خطأ ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة من نوع bigint.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُحدث خطأ من نوع TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file:.
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بالإهمال برقم تعريف DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كان يجب أن تكون القيم العددية في كائن <fs.Stats> المُرتجع من نوع bigint. الافتراضي: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

دالة غير متزامنة stat(2). تحصل دالة الاستدعاء على وسيطتين (err, stats) حيث أن stats هو كائن <fs.Stats>.

في حالة حدوث خطأ، سيكون err.code أحد أخطاء النظام الشائعة.

تتبع fs.stat() الروابط الرمزية. استخدم fs.lstat() لعرض الروابط نفسها.

لا يُنصح باستخدام fs.stat() للتحقق من وجود ملف قبل استدعاء fs.open(), fs.readFile(), أو fs.writeFile(). بدلاً من ذلك، يجب أن يفتح/يقرأ/يكتب المستخدم الملف مباشرةً ويتعامل مع الخطأ الذي يُثار إذا لم يكن الملف متوفرًا.

للتحقق مما إذا كان الملف موجودًا بدون معالجته لاحقًا، يُنصح باستخدام fs.access().

على سبيل المثال، بالنظر إلى بنية الدليل التالية:

- txtDir
-- file.txt
- app.js

سيقوم البرنامج التالي بالتحقق من إحصائيات المسارات المعطاة:

import { stat } from 'node:fs'

const pathsToCheck = ['./txtDir', './txtDir/file.txt']

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory())
    console.log(stats)
  })
}

ستشبه المخرجات الناتجة ما يلي:

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
}

fs.statfs(path[, options], callback)

مُضافة في: v19.6.0، v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> هل يجب أن تكون القيم العددية في كائن <fs.StatFs> المُرجع من نوع bigint. الافتراضي: false.

• callback <Function>

  • err <Error>
  • stats <fs.StatFs>

نسخة غير متزامنة من statfs(2). تُرجع معلومات حول نظام الملفات المُركّبة الذي يحتوي على path. يحصل مُستدعي الوظيفة على حُجّتين (err, stats) حيث أن stats هو كائن <fs.StatFs>.

في حالة حدوث خطأ، سيكون err.code أحد أخطاء النظام الشائعة.

fs.symlink(target, path[, type], callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُستدعي وظيفة غير صالح إلى وسيطة callback يُلقِي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v12.0.0	إذا تم ترك وسيطة type غير مُعرّفة، فسوف يقوم Node باكتشاف نوع target تلقائيًا ويختار dir أو file تلقائيًا.
v7.6.0	يمكن أن تكون الوسيطتان target و path كائنات WHATWG URL باستخدام بروتوكول file: . الدعم لا يزال تجريبيًا حاليًا.
v0.1.31	مُضافة في: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> الافتراضي: null
• callback <Function>
  • err <Error>

يُنشئ الرابط المسمى path الذي يشير إلى target. لا تُعطى أي وسيطات أخرى بخلاف استثناء محتمل إلى مُستدعي وظيفة الإكمال.

راجع وثائق POSIX symlink(2) لمزيد من التفاصيل.

تتوفر وسيطة type فقط على Windows ويتم تجاهلها على الأنظمة الأساسية الأخرى. يمكن تعيينها إلى 'dir'، 'file'، أو 'junction'. إذا كانت وسيطة type هي null، فسيقوم Node.js باكتشاف نوع target تلقائيًا واستخدام 'file' أو 'dir'. إذا لم يكن target موجودًا، فسيتم استخدام 'file'. تتطلب نقاط الوصل في Windows أن يكون مسار الوجهة مسارًا مطلقًا. عند استخدام 'junction'، سيتم تطبيع وسيطة target تلقائيًا إلى مسار مطلق. لا يمكن لنقاط الوصل على مجلدات NTFS إلا أن تشير إلى الدلائل.

الأهداف النسبية هي نسبية إلى الدليل الرئيسي للرابط.

import { symlink } from 'node:fs'

symlink('./mew', './mewtwo', callback)

يُنشئ المثال أعلاه رابطًا رمزيًا mewtwo يشير إلى mew في نفس الدليل:

$ tree .
.
├── mew
└── mewtwo -> ./mew

fs.truncate(path[, len], callback)

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُرجِع غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.0.0	قد يكون الخطأ المُرجع هو AggregateError إذا تم إرجاع أكثر من خطأ واحد.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى طرح TypeError وقت التشغيل.
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إصدار تحذير من إهمال باستخدام معرف DEP0013.
v0.8.6	تمت الإضافة في: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> الافتراضي: 0
• callback <Function>
  • err <Error> | <AggregateError>

يقصّر الملف. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُرجِع الإكمال. يمكن أيضًا تمرير مُوصِف ملف كأول وسيطة. في هذه الحالة، يتم استدعاء fs.ftruncate().

ESM

import { truncate } from 'node:fs'
// بافتراض أن 'path/file.txt' هو ملف عادي.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})

CJS

const { truncate } = require('node:fs')
// بافتراض أن 'path/file.txt' هو ملف عادي.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})

يُنصح بعدم تمرير مُوصِف ملف وقد يؤدي ذلك إلى طرح خطأ في المستقبل.

راجع وثائق POSIX truncate(2) لمزيد من التفاصيل.

fs.unlink(path, callback)

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُدعًى غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُلقي خطأ TypeError وقت التشغيل.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا بإلغاء الاستخدام برقم تعريف DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• path <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

يزيل ملفًا أو رابطًا رمزيًا بشكل غير متزامن. لا تُعطى أي وسيطات بخلاف استثناء محتمل إلى مُدعًى الإكمال.

import { unlink } from 'node:fs'
// بافتراض أن 'path/file.txt' هو ملف عادي.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was deleted')
})

لن تعمل fs.unlink() على دليل، فارغًا أو غير ذلك. لإزالة دليل، استخدم fs.rmdir().

راجع وثائق POSIX unlink(2) لمزيد من التفاصيل.

fs.unwatchFile(filename[, listener])

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

• filename <string> | <Buffer> | <URL>
• listener <Function> اختياري، مُستمع تم إرفاقه مسبقًا باستخدام fs.watchFile()

إيقاف مراقبة التغييرات على filename. إذا تم تحديد listener، فسيتم إزالة هذا المُستمع فقط. خلاف ذلك، سيتم إزالة جميع المُستمعين، مما يؤدي إلى إيقاف مراقبة filename بشكل فعال.

إن استدعاء fs.unwatchFile() باسم ملف لا يتم مراقبته هو عملية لا شيء، وليس خطأ.

استخدام fs.watch() أكثر كفاءة من fs.watchFile() و fs.unwatchFile(). يجب استخدام fs.watch() بدلاً من fs.watchFile() و fs.unwatchFile() عند الإمكان.

fs.utimes(path, atime, mtime, callback)

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إلقاء TypeError وقت التشغيل.
v8.0.0	لم تعد NaN و Infinity و -Infinity مُحددات أوقات صالحة.
v7.6.0	يمكن أن تكون وسيطة path كائن URL من WHATWG باستخدام بروتوكول file: .
v7.0.0	لم تعد وسيطة callback اختيارية. سيؤدي عدم تمريرها إلى إصدار تحذير مُهمل باستخدام معرف DEP0013.
v4.1.0	أصبحت سلاسل الأرقام، و NaN، و Infinity مُحددات أوقات مسموح بها الآن.
v0.4.2	تمت الإضافة في: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

تغيير طوابع زمن نظام الملفات للكائن المُشار إليه بواسطة path.

تتبع وسيطتا atime و mtime القواعد التالية:

• يمكن أن تكون القيم أرقامًا تُمثل وقت حقبة يونكس بالثواني، أو Date، أو سلسلة رقمية مثل '123456789.0'.
• إذا تعذر تحويل القيمة إلى رقم، أو كانت NaN أو Infinity أو -Infinity، فسيتم إلقاء Error.

fs.watch(filename[, options][, listener])

[History]

الإصدار	التغييرات
v19.1.0	تمت إضافة دعم متكرر لنظامي Linux و AIX و IBMi.
v15.9.0، v14.17.0	تمت إضافة دعم لإغلاق مراقب الملفات باستخدام AbortSignal.
v7.6.0	يمكن أن يكون معامل filename كائن URL من WHATWG باستخدام بروتوكول file:.
v7.0.0	لن يتم تعديل كائن options المُمرر أبدًا.
v0.5.10	تمت الإضافة في: v0.5.10

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> يشير إلى ما إذا كان يجب على العملية الاستمرار في التشغيل طالما يتم مراقبة الملفات. الافتراضي: true.
  • recursive <boolean> يشير إلى ما إذا كان يجب مراقبة جميع الدلائل الفرعية، أم الدليل الحالي فقط. ينطبق هذا عند تحديد دليل، وعلى الأنظمة الأساسية المدعومة فقط (انظر التحذيرات). الافتراضي: false.
  • encoding <string> يحدد ترميز الأحرف الذي سيتم استخدامه لاسم الملف المُمرر إلى المُستمع. الافتراضي: 'utf8'.
  • signal <AbortSignal> يسمح بإغلاق مراقب الملفات باستخدام AbortSignal.

• listener <Function> | <undefined> الافتراضي: undefined

  • eventType <string>
  • filename <string> | <Buffer> | <null>

• الإرجاع: <fs.FSWatcher>

مراقبة التغييرات على filename، حيث filename إما ملف أو دليل.

الحجة الثانية اختيارية. إذا تم توفير options كسلسلة، فإنها تحدد encoding. خلافًا لذلك، يجب تمرير options ككائن.

يحصل مُستمع المُراجعة على حُجتين (eventType, filename). eventType هو إما 'rename' أو 'change'، و filename هو اسم الملف الذي أثار الحدث.

على معظم الأنظمة الأساسية، يتم إصدار 'rename' كلما ظهر اسم ملف أو اختفى في الدليل.

يتم إرفاق مُستمع المُراجعة بحدث 'change' الذي أصدره <fs.FSWatcher>، لكنه ليس هو نفس قيمة 'change' لـ eventType.

إذا تم تمرير signal، فإن إلغاء AbortController المقابل سيؤدي إلى إغلاق <fs.FSWatcher> المُرجع.

التحذيرات

إن واجهة برمجة التطبيقات fs.watch ليست متسقة بنسبة 100٪ عبر الأنظمة الأساسية، وهي غير متوفرة في بعض الحالات.

في نظام التشغيل Windows، لن يتم إصدار أي أحداث إذا تم نقل الدليل الذي يتم مراقبته أو إعادة تسميته. يتم الإبلاغ عن خطأ EPERM عند حذف الدليل الذي يتم مراقبته.

التوافر

تعتمد هذه الميزة على نظام التشغيل الأساسي الذي يوفر طريقة للإشعار بتغييرات نظام الملفات.

• في أنظمة Linux، يستخدم هذا inotify(7).
• في أنظمة BSD، يستخدم هذا kqueue(2).
• في نظام macOS، يستخدم هذا kqueue(2) للملفات وFSEvents للدلائل.
• في أنظمة SunOS (بما في ذلك Solaris و SmartOS)، يستخدم هذا event ports.
• في أنظمة Windows، تعتمد هذه الميزة على ReadDirectoryChangesW.
• في أنظمة AIX، تعتمد هذه الميزة على AHAFS, والتي يجب تمكينها.
• في أنظمة IBM i، لا يتم دعم هذه الميزة.

إذا لم تكن الوظائف الأساسية متاحة لسبب ما، فلن تتمكن fs.watch() من العمل وقد تطرح استثناءً. على سبيل المثال، قد تكون مراقبة الملفات أو الدلائل غير موثوقة، وفي بعض الحالات مستحيلة، على أنظمة ملفات الشبكة (NFS، SMB، إلخ) أو أنظمة ملفات المضيف عند استخدام برامج افتراضية مثل Vagrant أو Docker.

لا يزال من الممكن استخدام fs.watchFile()، الذي يستخدم استطلاع الحالة، ولكن هذه الطريقة أبطأ وأقل موثوقية.

عقد البيانات (Inodes)

في أنظمة Linux و macOS، تحل fs.watch() مسار عقد البيانات وتراقب عقد البيانات. إذا تم حذف المسار الذي يتم مراقبته وإعادة إنشائه، فسيتم تعيين عقد بيانات جديد له. ستصدر المراقبة حدثًا للحذف ولكنها ستستمر في مراقبة عقد البيانات الأصلي. لن يتم إصدار أحداث لعقد البيانات الجديدة. هذا سلوك متوقع.

تحتفظ ملفات AIX بنفس عقد البيانات طوال عمر الملف. سيؤدي حفظ وإغلاق ملف مراقب على AIX إلى إشعارين (واحد لإضافة محتوى جديد، وواحد لاقتطاع).

وسيطة اسم الملف

يُدعم توفير وسيطة filename في وظيفة المُعالجة المُستدعاة فقط على أنظمة Linux وmacOS وWindows وAIX. حتى على الأنظمة الأساسية المدعومة، لا يُضمن دائمًا توفير filename. لذلك، لا تفترض أن وسيطة filename مُقدمة دائمًا في وظيفة المُعالجة المُستدعاة، واجعل لديك منطق احتياطي إذا كانت null.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`نوع الحدث هو: ${eventType}`)
  if (filename) {
    console.log(`اسم الملف المُقدم: ${filename}`)
  } else {
    console.log('اسم الملف غير مُقدم')
  }
})

fs.watchFile(filename[, options], listener)

[السجل]

الإصدار	التغييرات
v10.5.0	الآن يُدعم خيار bigint.
v7.6.0	يمكن أن تكون وسيطة filename كائن WHATWG URL باستخدام بروتوكول file:
v0.1.31	تمت الإضافة في: v0.1.31

• filename <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> افتراضيًا: false
  • persistent <boolean> افتراضيًا: true
  • interval <integer> افتراضيًا: 5007

• listener <Function>

  • current <fs.Stats>
  • previous <fs.Stats>

• القيمة المُرجعة: <fs.StatWatcher>

راقب التغييرات على filename. سيتم استدعاء وظيفة المُعالجة المُستدعاة listener في كل مرة يتم الوصول إلى الملف فيها.

يمكن حذف وسيطة options. إذا تم تقديمها، فيجب أن تكون كائنًا. قد يحتوي كائن options على قيمة منطقية تُسمى persistent تشير إلى ما إذا كان يجب على العملية الاستمرار في التشغيل طالما يتم مراقبة الملفات. قد يُحدد كائن options خاصية interval التي تشير إلى عدد مرات استطلاع الهدف بالمللي ثانية.

يحصل listener على حُجتين: كائن الحالة الحالي وكائن الحالة السابق:

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`وقت التعديل الأخير الحالي هو: ${curr.mtime}`)
  console.log(`وقت التعديل الأخير السابق كان: ${prev.mtime}`)
})

هذه كائنات الحالة هي مثيلات من fs.Stat. إذا كان خيار bigint يساوي true، فسيتم تحديد القيم العددية في هذه الكائنات على أنها BigInt.

للتبليغ عندما تم تعديل الملف، وليس فقط الوصول إليه، من الضروري مقارنة curr.mtimeMs و prev.mtimeMs.

عندما تؤدي عملية fs.watchFile إلى حدوث خطأ ENOENT، ستقوم باستدعاء وظيفة المُعالجة المُستدعاة مرة واحدة، مع تعيين جميع الحقول على الصفر (أو، بالنسبة للتاريخ، حقبة يونكس). إذا تم إنشاء الملف لاحقًا، فسيتم استدعاء وظيفة المُعالجة المُستدعاة مرة أخرى، مع أحدث كائنات الحالة. هذا تغيير في الوظائف منذ الإصدار v0.10.

استخدام fs.watch() أكثر كفاءة من fs.watchFile و fs.unwatchFile. يجب استخدام fs.watch بدلاً من fs.watchFile و fs.unwatchFile كلما أمكن ذلك.

عندما يختفي ملف يُراقب بواسطة fs.watchFile() ويظهر مرة أخرى، فإن محتويات previous في حدث وظيفة المُعالجة المُستدعاة الثاني (إعادة ظهور الملف) ستكون هي نفسها محتويات previous في حدث وظيفة المُعالجة المُستدعاة الأول (اختفائه).

يحدث هذا عندما:

• يتم حذف الملف، متبوعًا باستعادة
• يتم إعادة تسمية الملف ثم إعادة تسميته مرة ثانية إلى اسمه الأصلي

fs.write(fd, buffer, offset[, length[, position]], callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير دالة استدعاء غير صالحة إلى وسيطة callback يؤدي الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v14.0.0	لن تقوم وسيطة buffer بتحويل الإدخال غير المدعوم إلى سلاسل نصية بعد الآن.
v10.10.0	يمكن أن تكون وسيطة buffer الآن أي TypedArray أو DataView.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيؤدي إلى طرح TypeError وقت التشغيل.
v7.4.0	يمكن أن تكون وسيطة buffer الآن Uint8Array.
v7.2.0	أصبحت وسيطتا offset و length اختياريتين الآن.
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيؤدي إلى إصدار تحذير من إلغاء الاستخدام مع المعرف DEP0013.
v0.0.2	تمت الإضافة في: v0.0.2

• fd <عدد صحيح>
• buffer <عازلة> | <TypedArray> | <DataView>
• offset <عدد صحيح> الافتراضي: 0
• length <عدد صحيح> الافتراضي: buffer.byteLength - offset
• position <عدد صحيح> | <لا شيء> الافتراضي: null
• callback <دالة>
  • err <خطأ>
  • bytesWritten <عدد صحيح>
  • buffer <عازلة> | <TypedArray> | <DataView>

كتابة buffer إلى الملف المحدد بواسطة fd.

يحدد offset جزء العازلة المراد كتابته، و length هو عدد صحيح يحدد عدد البايتات المراد كتابتها.

يشير position إلى الإزاحة من بداية الملف حيث يجب كتابة هذه البيانات. إذا كان typeof position !== 'number'، فسيتم كتابة البيانات في الموقع الحالي. انظر pwrite(2).

ستحصل دالة الاستدعاء على ثلاث وسيطات (err, bytesWritten, buffer) حيث يحدد bytesWritten عدد البايتات التي تم كتابتها من buffer.

إذا تم استدعاء هذه الطريقة كنسخة util.promisify() لها، فإنها تُرجع وعدًا لكائن يحتوي على خصائص bytesWritten و buffer.

من غير الآمن استخدام fs.write() عدة مرات على نفس الملف دون انتظار دالة الاستدعاء. لهذا السيناريو، يُوصى باستخدام fs.createWriteStream().

في لينكس، لا تعمل عمليات الكتابة الموضعية عندما يتم فتح الملف في وضع الإضافة. يتجاهل نواة النظام وسيطة الموقع ويضيف البيانات دائمًا إلى نهاية الملف.

fs.write(fd, buffer[, options], callback)

مضاف في: v18.3.0، v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> افتراضي: 0
  • length <integer> افتراضي: buffer.byteLength - offset
  • position <integer> افتراضي: null

• callback <Function>

  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

كتابة buffer إلى الملف المحدد بواسطة fd.

على غرار دالة fs.write أعلاه، يأخذ هذا الإصدار كائن options اختياريًا. إذا لم يتم تحديد كائن options، فسيتم تعيين القيم الافتراضية أعلاه.

fs.write(fd, string[, position[, encoding]], callback)

[السجل]

الإصدار	التغييرات
v19.0.0	لم يعد يُدعم تمرير كائن يحتوي على دالة toString خاصة به إلى معامل string.
v17.8.0	تم إهمال تمرير كائن يحتوي على دالة toString خاصة به إلى معامل string.
v14.12.0	سيقوم معامل string بتحويل كائن يحتوي على دالة toString صريحة إلى سلسلة نصية.
v14.0.0	لن يقوم معامل string بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v10.0.0	لم يعد معامل callback اختياريًا. لن يؤدي عدم تمريره إلا إلى طرح خطأ TypeError وقت التشغيل.
v7.2.0	أصبح معامل position اختياريًا الآن.
v7.0.0	لم يعد معامل callback اختياريًا. لن يؤدي عدم تمريره إلا إلى إصدار تحذير بإهمال برقم معرف DEP0013.
v0.11.5	مضاف في: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> افتراضي: null
• encoding <string> افتراضي: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

كتابة string إلى الملف المحدد بواسطة fd. إذا لم يكن string سلسلة نصية، فسيتم طرح استثناء.

يشير position إلى الإزاحة من بداية الملف حيث يجب كتابة هذه البيانات. إذا كان typeof position !== 'number'، فسيتم كتابة البيانات في الموضع الحالي. انظر pwrite(2).

encoding هو ترميز السلسلة المتوقع.

سيستقبل callback الوسائط (err, written, string) حيث يحدد written عدد البايتات التي تتطلبها السلسلة الممررة للكتابة. عدد البايتات المكتوبة ليس بالضرورة هو نفسه عدد أحرف السلسلة المكتوبة. انظر Buffer.byteLength.

من غير الآمن استخدام fs.write() عدة مرات على نفس الملف دون انتظار callback. لهذه الحالة، يُوصى باستخدام fs.createWriteStream().

في Linux، لا تعمل كتابات المواضع عندما يتم فتح الملف في وضع الإضافة. يتجاهل kernel وسيطة الموضع ويضيف البيانات دائمًا إلى نهاية الملف.

في Windows، إذا كان مُعرّف الملف متصلاً بالوحدة الطرفية (مثل fd == 1 أو stdout)، فلن يتم عرض سلسلة نصية تحتوي على أحرف غير ASCII بشكل صحيح بشكل افتراضي، بغض النظر عن الترميز المستخدم. من الممكن تكوين وحدة التحكم لعرض UTF-8 بشكل صحيح عن طريق تغيير صفحة الرموز النشطة باستخدام أمر chcp 65001. راجع وثائق chcp لمزيد من التفاصيل.

fs.writeFile(file, data[, options], callback)

[السجل]

الإصدار	التغييرات
v21.0.0، v20.10.0	أصبح خيار flush مدعومًا الآن.
v19.0.0	لم يعد يُسمح بمرور كائن يحتوي على دالة toString خاصة به إلى معامل string.
v18.0.0	يُلقي تمرير مُرجِع غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v17.8.0	أصبح تمرير كائن يحتوي على دالة toString خاصة به إلى معامل string مُحذَّرًا منه.
v16.0.0	قد يكون الخطأ المُرجع AggregateError إذا تم إرجاع أكثر من خطأ واحد.
v15.2.0، v14.17.0	قد تتضمن وسيطة الخيارات إشارة AbortSignal لإلغاء طلب writeFile جارٍ.
v14.12.0	ستقوم وسيطة data بتحويل كائن إلى سلسلة نصية باستخدام دالة toString صريحة.
v14.0.0	لن تقوم وسيطة data بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v10.10.0	يمكن أن تكون وسيطة data الآن أي TypedArray أو DataView.
v10.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيؤدي إلى إلقاء TypeError وقت التشغيل.
v7.4.0	يمكن أن تكون وسيطة data الآن Uint8Array.
v7.0.0	لم تعد وسيطة callback اختيارية. عدم تمريرها سيُصدر تحذيرًا من إلغاء الاستخدام برقم DEP0013.
v5.0.0	يمكن أن يكون معامل file الآن مُوصِف ملف.
v0.1.29	تمت الإضافة في: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> اسم الملف أو مُوصِف الملف

• data <string> | <Buffer> | <TypedArray> | <DataView>

• options <Object> | <string>

  • encoding <string> | <null> الافتراضي: 'utf8'
  • mode <integer> الافتراضي: 0o666
  • flag <string> انظر دعم أعلام نظام الملفات. الافتراضي: 'w'.
  • flush <boolean> إذا تم كتابة جميع البيانات بنجاح في الملف، و flush يساوي true، فسيتم استخدام fs.fsync() لتنظيف البيانات. الافتراضي: false.
  • signal <AbortSignal> يسمح بإلغاء عملية writeFile الجارية

• callback <Function>

  • err <Error> | <AggregateError>

عندما يكون file اسم ملف، فإنه يكتب البيانات بشكل غير متزامن إلى الملف، ويستبدل الملف إذا كان موجودًا بالفعل. يمكن أن يكون data سلسلة نصية أو مُخزن مؤقت.

عندما يكون file مُوصِف ملف، يكون السلوك مشابهًا لاستدعاء fs.write() مباشرةً (وهو ما يُوصى به). انظر الملاحظات أدناه حول استخدام مُوصِف ملف.

يتم تجاهل خيار encoding إذا كان data مُخزنًا مؤقتًا.

يؤثر خيار mode فقط على الملف المُنشأ حديثًا. انظر fs.open() لمزيد من التفاصيل.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, err => {
  if (err) throw err
  console.log('تم حفظ الملف!')
})

إذا كان options سلسلة نصية، فإنه يحدد ترميز:

import { writeFile } from 'node:fs'

writeFile('message.txt', 'Hello Node.js', 'utf8', callback)

من غير الآمن استخدام fs.writeFile() عدة مرات على نفس الملف دون انتظار المُرجِع. لهذه الحالة، يُوصى باستخدام fs.createWriteStream().

على غرار fs.readFile - fs.writeFile هي طريقة مُيسّرة تُجري عدة مكالمات write داخليًا لكتابة المخزن المؤقت المُمرَّر إليه. بالنسبة للكود الحساس للأداء، ضع في اعتبارك استخدام fs.createWriteStream().

من الممكن استخدام <AbortSignal> لإلغاء fs.writeFile(). الإلغاء هو "أفضل جهد"، ومن المحتمل أن يتم كتابة بعض البيانات.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, { signal }, err => {
  // عندما يتم إلغاء طلب - يتم استدعاء المُرجِع مع AbortError
})
// عندما يجب إلغاء الطلب
controller.abort()

إلغاء الطلب الجاري لا يلغي طلبات نظام التشغيل الفردية، بل التخزين المؤقت الداخلي الذي يقوم به fs.writeFile.

استخدام fs.writeFile() مع مُوصِفات الملفات

عندما يكون file مُوصِف ملف، يكون السلوك مُتماثلاً تقريبًا مع استدعاء fs.write() مباشرةً كما يلي:

import { write } from 'node:fs'
import { Buffer } from 'node:buffer'

write(fd, Buffer.from(data, options.encoding), callback)

يختلف الأمر عن استدعاء fs.write() مباشرةً في أن fs.write() قد لا يكتب سوى جزء من المخزن المؤقت في ظل بعض الظروف غير العادية، وقد يحتاج إلى إعادة المحاولة لكتابة البيانات المتبقية، بينما تُعيد fs.writeFile() المحاولة حتى يتم كتابة البيانات بالكامل (أو حدوث خطأ).

تُعدّ آثار هذا الأمر مصدرًا شائعًا للارتباك. في حالة مُوصِف الملف، لا يتم استبدال الملف! لا يتم بالضرورة كتابة البيانات في بداية الملف، وقد تبقى بيانات الملف الأصلية قبل البيانات المكتوبة حديثًا و/أو بعدها.

على سبيل المثال، إذا تم استدعاء fs.writeFile() مرتين متتاليتين، أولاً لكتابة السلسلة 'Hello'، ثم لكتابة السلسلة ', World'، فسيتضمن الملف 'Hello, World'، وقد يتضمن بعض بيانات الملف الأصلية (حسب حجم الملف الأصلي، وموضع مُوصِف الملف). إذا تم استخدام اسم ملف بدلاً من مُوصِف، فمن المؤكد أن الملف سيحتوي فقط على ', World'.

fs.writev(fd, buffers[, position], callback)

[التاريخ]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُنعكس غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v12.9.0	تمت الإضافة في: v12.9.0

• fd <عدد صحيح>
• buffers <ArrayBufferView[]>
• position <عدد صحيح> | <لا شيء> الافتراضي: null
• callback <دالة>
  • err <خطأ>
  • bytesWritten <عدد صحيح>
  • buffers <ArrayBufferView[]>

اكتب مصفوفة من ArrayBufferViews إلى الملف الذي تحدده fd باستخدام writev().

position هو الإزاحة من بداية الملف حيث يجب كتابة هذه البيانات. إذا كان typeof position !== 'number'، فسيتم كتابة البيانات في الموضع الحالي.

سيتم إعطاء المُنعكس ثلاث وسيطات: err، و bytesWritten، و buffers. bytesWritten هو عدد البايتات التي تم كتابتها من buffers.

إذا تم استخدام هذه الطريقة مع util.promisify()، فإنها تُعيد وعدًا لكائن يحتوي على خصائص bytesWritten و buffers.

من غير الآمن استخدام fs.writev() عدة مرات على نفس الملف دون انتظار المُنعكس. في هذا السيناريو، استخدم fs.createWriteStream().

في نظام لينكس، لا تعمل كتابات المواضع عندما يتم فتح الملف في وضع الإضافة. يتجاهل kernel وسيطة الموضع ويضيف البيانات دائمًا إلى نهاية الملف.

واجهة برمجة التطبيقات المتزامنة

تقوم واجهات برمجة التطبيقات المتزامنة بجميع العمليات بشكل متزامن، مما يحجب حلقة الحدث حتى اكتمال العملية أو فشلها.

fs.accessSync(path[, mode])

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:
v0.11.15	تمت الإضافة في: v0.11.15

• path <سلسلة> | <مُخزن مؤقت> | <URL>
• mode <عدد صحيح> افتراضيًا: fs.constants.F_OK

يختبر بشكل متزامن أذونات المستخدم للملف أو الدليل المحدد بواسطة path. مُعامل mode هو عدد صحيح اختياري يحدد عمليات فحص إمكانية الوصول التي سيتم إجراؤها. يجب أن يكون mode إما قيمة fs.constants.F_OK أو قناع يتكون من OR المنطقي لأي من fs.constants.R_OK، fs.constants.W_OK، و fs.constants.X_OK (مثل fs.constants.W_OK | fs.constants.R_OK). تحقق من ثوابت وصول الملف للحصول على القيم الممكنة لـ mode.

إذا فشلت أي من عمليات فحص إمكانية الوصول، فسيتم طرح Error. خلاف ذلك، ستعيد الطريقة undefined.

import { accessSync, constants } from 'node:fs'

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('يمكن القراءة/الكتابة')
} catch (err) {
  console.error('لا يوجد وصول!')
}

fs.appendFileSync(path, data[, options])

[السجل]

الإصدار	التغييرات
v21.1.0, v20.10.0	خيار flush مدعوم الآن.
v7.0.0	لن يتم تعديل كائن options المُمرر أبدًا.
v5.0.0	يمكن أن يكون مُعامل file مُوصف ملف الآن.
v0.6.7	تمت الإضافة في: v0.6.7

• path <سلسلة> | <مُخزن مؤقت> | <URL> | <عدد> اسم الملف أو مُوصف الملف
• data <سلسلة> | <مُخزن مؤقت>
• options <كائن> | <سلسلة>
  • encoding <سلسلة> | <لا شيء> افتراضيًا: 'utf8'
  • mode <عدد صحيح> افتراضيًا: 0o666
  • flag <سلسلة> انظر دعم مُوصّفات نظام الملفات. افتراضيًا: 'a'.
  • flush <قيمة منطقية> إذا كانت true، فسيتم مسح مُوصف الملف الأساسي قبل إغلاقه. افتراضيًا: false.

إضافة بيانات بشكل متزامن إلى ملف، وإنشاء الملف إذا لم يكن موجودًا بعد. يمكن أن يكون data سلسلة أو <مُخزن مؤقت>.

يؤثر خيار mode فقط على الملف المُنشأ حديثًا. راجع fs.open() لمزيد من التفاصيل.

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'data to append')
  console.log('تمت إضافة "data to append" إلى الملف!')
} catch (err) {
  /* تعامل مع الخطأ */
}

إذا كان options سلسلة، فإنه يحدد الترميز:

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'data to append', 'utf8')

يمكن تحديد path كمُوصف ملف رقمي تم فتحه للإضافة (باستخدام fs.open() أو fs.openSync()). لن يتم إغلاق مُوصف الملف تلقائيًا.

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'data to append', 'utf8')
} catch (err) {
  /* تعامل مع الخطأ */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[History]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file: .
v0.6.7	تمت الإضافة في: v0.6.7

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.chmod().

راجع وثائق POSIX chmod(2) لمزيد من التفاصيل.

fs.chownSync(path, uid, gid)

[History]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file: .
v0.1.97	تمت الإضافة في: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

يُغيّر بشكل متزامن مالك ومجموعة ملف. يُعيد undefined. هذا هو الإصدار المتزامن من fs.chown().

راجع وثائق POSIX chown(2) لمزيد من التفاصيل.

fs.closeSync(fd)

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

• fd <integer>

يُغلق مُعرّف الملف. يُعيد undefined.

قد يؤدي استدعاء fs.closeSync() على أي مُعرّف ملف (fd) قيد الاستخدام حاليًا من خلال أي عملية fs أخرى إلى سلوك غير مُعرّف.

راجع وثائق POSIX close(2) لمزيد من التفاصيل.

fs.copyFileSync(src, dest[, mode])

[History]

الإصدار	التغييرات
v14.0.0	تم تغيير وسيطة flags إلى mode وفرض التحقق من نوع أكثر صرامة.
v8.5.0	تمت الإضافة في: v8.5.0

• src <string> | <Buffer> | <URL> اسم الملف المصدر المراد نسخه
• dest <string> | <Buffer> | <URL> اسم ملف الوجهة لعملية النسخ
• mode <integer> مُعدِّلات لعملية النسخ. الافتراضي: 0.

يقوم بنسخ src إلى dest بشكل متزامن. بشكل افتراضي، يتم الكتابة فوق dest إذا كان موجودًا بالفعل. يُرجع undefined. لا تقدم Node.js أي ضمانات حول ذرية عملية النسخ. إذا حدث خطأ بعد فتح ملف الوجهة للكتابة، فستحاول Node.js إزالة الوجهة.

mode هو عدد صحيح اختياري يحدد سلوك عملية النسخ. من الممكن إنشاء قناع يتكون من OR المنطقي لواحد أو أكثر من القيم (مثل fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: ستفشل عملية النسخ إذا كان dest موجودًا بالفعل.
• fs.constants.COPYFILE_FICLONE: ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم يدعم النظام الأساسي copy-on-write، فسيتم استخدام آلية نسخ بديلة.
• fs.constants.COPYFILE_FICLONE_FORCE: ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم يدعم النظام الأساسي copy-on-write، فستفشل العملية.

import { copyFileSync, constants } from 'node:fs'

// سيتم إنشاء أو الكتابة فوق destination.txt بشكل افتراضي.
copyFileSync('source.txt', 'destination.txt')
console.log('تم نسخ source.txt إلى destination.txt')

// باستخدام COPYFILE_EXCL، ستفشل العملية إذا كان destination.txt موجودًا.
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[History]

الإصدار	التغييرات
v22.3.0	لم يعد هذا الواجهة البرمجية تجريبيًا.
v20.1.0, v18.17.0	قبول خيار mode إضافي لتحديد سلوك النسخ كوسيط mode لـ fs.copyFile().
v17.6.0, v16.15.0	يقبل خيار verbatimSymlinks إضافي لتحديد ما إذا كان سيتم إجراء حل المسار للروابط الرمزية.
v16.7.0	تمت الإضافة في: v16.7.0

• src <string> | <URL> مسار المصدر المراد نسخه.

• dest <string> | <URL> مسار الوجهة المراد النسخ إليه.

• options <Object>

  • dereference <boolean> إلغاء مرجع الروابط الرمزية. الافتراضي: false.

  • errorOnExist <boolean> عندما يكون force false، وإذا كانت الوجهة موجودة، يتم إرجاع خطأ. الافتراضي: false.

  • filter <Function> دالة لتصفية الملفات/الدلائل المنسوخة. أرجع true لنسخ العنصر، false لتجاهله. عند تجاهل دليل، سيتم تخطي جميع محتوياته أيضًا. الافتراضي: undefined

  • src <string> مسار المصدر المراد نسخه.

  • dest <string> مسار الوجهة المراد النسخ إليه.

  • الإرجاع: <boolean> أي قيمة غير Promise قابلة للتحويل إلى boolean.

  • force <boolean> الكتابة فوق الملف أو الدليل الموجود. ستتجاهل عملية النسخ الأخطاء إذا قمت بتعيين هذا إلى false وتوجد الوجهة. استخدم خيار errorOnExist لتغيير هذا السلوك. الافتراضي: true.

  • mode <integer> مُعدِّلات لعملية النسخ. الافتراضي: 0. انظر علم mode الخاص بـ fs.copyFileSync().

  • preserveTimestamps <boolean> عندما يكون true سيتم الاحتفاظ بعلامات الوقت من src. الافتراضي: false.

  • recursive <boolean> نسخ الدلائل بشكل متكرر الافتراضي: false

  • verbatimSymlinks <boolean> عندما يكون true، سيتم تخطي حل المسار للروابط الرمزية. الافتراضي: false

ينسخ بنفس الطريقة هيكل الدليل بالكامل من src إلى dest، بما في ذلك الدلائل الفرعية والملفات.

عند نسخ دليل إلى دليل آخر، لا يتم دعم globs ويكون السلوك مشابهًا لـ cp dir1/ dir2/.

fs.existsSync(path)

[History]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:
v0.1.21	تمت الإضافة في: v0.1.21

• path <string> | <Buffer> | <URL>
• القيمة المُرجعة: <boolean>

ترجع true إذا كان المسار موجودًا، و false بخلاف ذلك.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.exists().

تم إهمال fs.exists()، ولكن لم يتم إهمال fs.existsSync(). يأخذ مُعامل callback في fs.exists() معاملات غير متناسقة مع مُعاملات الاستدعاء الأخرى في Node.js. لا يستخدم fs.existsSync() مُعامل استدعاء.

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('The path exists.')

fs.fchmodSync(fd, mode)

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

• fd <integer>
• mode <string> | <integer>

يُعيّن الأذونات على الملف. تُرجع undefined.

راجع وثائق POSIX fchmod(2) لمزيد من التفاصيل.

fs.fchownSync(fd, uid, gid)

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

• fd <integer>
• uid <integer> معرف مستخدم المالك الجديد للملف.
• gid <integer> معرف مجموعة المالك الجديد للملف.

يُعيّن مالك الملف. تُرجع undefined.

راجع وثائق POSIX fchown(2) لمزيد من التفاصيل.

fs.fdatasyncSync(fd)

مضاف في: v0.1.96

• fd <integer>

يُجبر جميع عمليات الإدخال/الإخراج المُصطفة حاليًا المُرتبطة بالملف على حالة إكمال الإدخال/الإخراج المُزامنة لنظام التشغيل. يرجى الرجوع إلى وثائق POSIX fdatasync(2) للحصول على التفاصيل. يعيد undefined.

fs.fstatSync(fd[, options])

[السجل]

الإصدار	التغييرات
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة من نوع bigint.
v0.1.95	مضاف في: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> ما إذا كانت القيم العددية في كائن <fs.Stats> المُرتجع يجب أن تكون من نوع bigint. الافتراضي: false.

• المُرتجع: <fs.Stats>

يسترد <fs.Stats> لوصف الملف.

راجع وثائق POSIX fstat(2) لمزيد من التفاصيل.

fs.fsyncSync(fd)

مضاف في: v0.1.96

• fd <integer>

يطلب إرسال جميع البيانات لوصف الملف المفتوح إلى جهاز التخزين. التنفيذ المحدد يعتمد على نظام التشغيل والجهاز. يرجى الرجوع إلى وثائق POSIX fsync(2) لمزيد من التفاصيل. يعيد undefined.

fs.ftruncateSync(fd[, len])

مضاف في: v0.8.6

• fd <integer>
• len <integer> الافتراضي: 0

يقص وصف الملف. يعيد undefined.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[History]

الإصدار	التغييرات
v4.1.0	أصبح من الممكن الآن استخدام سلاسل الأرقام و NaN و Infinity كمحددات للوقت.
v0.4.2	تمت الإضافة في: v0.4.2

• fd <عدد صحيح>
• atime <رقم> | <سلسلة> | <تاريخ>
• mtime <رقم> | <سلسلة> | <تاريخ>

نسخة متزامنة من fs.futimes(). تُرجع undefined.

fs.globSync(pattern[, options])

[History]

الإصدار	التغييرات
v22.2.0	إضافة دعم لـ withFileTypes كخيار.
v22.0.0	تمت الإضافة في: v22.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• pattern <سلسلة> | <مصفوفة من السلاسل>

• options <كائن>

  • cwd <سلسلة> دليل العمل الحالي. الافتراضي: process.cwd()
  • exclude <دالة> دالة لتصفية الملفات/الدلائل. أرجع true لاستبعاد العنصر، false لإدراجه. الافتراضي: undefined.
  • withFileTypes <قيمة منطقية> true إذا كان يجب أن تُرجع glob المسارات كـ Dirents، false خلاف ذلك. الافتراضي: false.

• المُرجَع: <مصفوفة من السلاسل> مسارات الملفات التي تطابق النمط.

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

const { globSync } = require('node:fs')

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

مسحوب منذ الإصدار: v0.4.7

• path <string> | <Buffer> | <URL>
• mode <integer>

يُغيّر أذونات الرابط الرمزي. يُعيد undefined.

هذه الطريقة مُنفّذة فقط على نظام macOS.

راجع وثائق POSIX lchmod(2) لمزيد من التفاصيل.

fs.lchownSync(path, uid, gid)

[السجل]

الإصدار	التغييرات
v10.6.0	لم يعد هذا API مسحوباً.
v0.4.7	إزالة من الوثائق فقط.

• path <string> | <Buffer> | <URL>
• uid <integer> معرف مستخدم المالك الجديد للملف.
• gid <integer> معرف مجموعة المالك الجديد للملف.

يُعيّن المالك للمسار. يُعيد undefined.

راجع وثائق POSIX lchown(2) لمزيد من التفاصيل.

fs.lutimesSync(path, atime, mtime)

مُضاف في: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

يُغيّر طوابع زمن نظام الملفات للرابط الرمزي المُشار إليه بواسطة path. يُعيد undefined، أو يُلقي استثناءً عندما تكون المعلمات غير صحيحة أو تفشل العملية. هذا هو الإصدار المتزامن من fs.lutimes().

fs.linkSync(existingPath, newPath)

[History]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون параметра existingPath و newPath كائنات WHATWG URL باستخدام بروتوكول file:، والدعم لا يزال تجريبيًا حاليًا.
v0.1.31	تمت الإضافة في: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

يقوم بإنشاء رابط جديد من existingPath إلى newPath. راجع وثائق POSIX link(2) لمزيد من التفاصيل. يُرجع undefined.

fs.lstatSync(path[, options])

[History]

الإصدار	التغييرات
v15.3.0، v14.17.0	يقبل خيار throwIfNoEntry لتحديد ما إذا كان يجب إرسال استثناء إذا لم يكن الإدخال موجودًا.
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كانت القيم العددية المُرجعَة يجب أن تكون bigint.
v7.6.0	يمكن أن يكون параметر path كائن WHATWG URL باستخدام بروتوكول file:.
v0.1.30	تمت الإضافة في: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كانت القيم العددية في كائن <fs.Stats> المُرجع يجب أن تكون bigint. الافتراضي: false.
  • throwIfNoEntry <boolean> ما إذا كان سيتم إرسال استثناء إذا لم يكن هناك إدخال في نظام الملفات، بدلاً من إرجاع undefined. الافتراضي: true.

• يُرجع: <fs.Stats>

يسترد <fs.Stats> للارتباط الرمزي المشار إليه بواسطة path.

راجع وثائق POSIX lstat(2) لمزيد من التفاصيل.

fs.mkdirSync(path[, options])

[History]

الإصدار	التغييرات
v13.11.0, v12.17.0	في وضع recursive، يتم إرجاع المسار الذي تم إنشاؤه أولاً الآن.
v10.12.0	يمكن أن يكون الوسيط الثاني الآن كائن options مع خصائص recursive و mode.
v7.6.0	يمكن أن يكون معامل path كائن URL من WHATWG باستخدام بروتوكول file:
v0.1.21	تمت الإضافة في: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> الافتراضي: false
  • mode <string> | <integer> غير مدعوم على Windows. الافتراضي: 0o777.

• الإرجاع: <string> | <undefined>

يقوم بإنشاء دليل بشكل متزامن. يعيد undefined، أو إذا كانت recursive هي true، فإن أول مسار دليل تم إنشاؤه. هذا هو الإصدار المتزامن من fs.mkdir().

راجع وثائق POSIX mkdir(2) لمزيد من التفاصيل.

fs.mkdtempSync(prefix[, options])

[History]

الإصدار	التغييرات
v20.6.0, v18.19.0	معامل prefix يقبل الآن العروض والـ URL.
v16.5.0, v14.18.0	معامل prefix يقبل الآن سلسلة فارغة.
v5.10.0	تمت الإضافة في: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• الإرجاع: <string>

يعيد مسار الدليل الذي تم إنشاؤه.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.mkdtemp().

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف المراد استخدامه.

fs.opendirSync(path[, options])

[History]

الإصدار	التغييرات
v20.1.0, v18.17.0	تمت إضافة خيار recursive.
v13.1.0, v12.16.0	تم تقديم خيار bufferSize.
v12.12.0	تمت الإضافة في: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> الافتراضي: 'utf8'
  • bufferSize <number> عدد مداخل الدليل التي يتم تخزينها مؤقتًا داخليًا عند القراءة من الدليل. تؤدي القيم الأعلى إلى أداء أفضل ولكن استخدام ذاكرة أعلى. الافتراضي: 32
  • recursive <boolean> الافتراضي: false

• الإرجاع: <fs.Dir>

فتح دليل بشكل متزامن. انظر opendir(3).

يُنشئ <fs.Dir>، والذي يحتوي على جميع الوظائف الأخرى للقراءة من الدليل وتنظيفه.

يحدد خيار encoding ترميز path أثناء فتح الدليل وعمليات القراءة اللاحقة.

fs.openSync(path[, flags[, mode]])

[History]

الإصدار	التغييرات
v11.1.0	أصبحت وسيطة flags اختيارية الآن وتُعيّن افتراضيًا على 'r'.
v9.9.0	يتم دعم علمي as و as+ الآن.
v7.6.0	يمكن أن يكون مُعامل path كائن URL WHATWG باستخدام بروتوكول file:.
v0.1.21	تمت الإضافة في: v0.1.21

• path <string> | <Buffer> | <URL>
• flags <string> | <number> الافتراضي: 'r'. انظر دعم أعلام نظام الملفات.
• mode <string> | <integer> الافتراضي: 0o666
• الإرجاع: <number>

يُرجع عددًا صحيحًا يمثل مُعرّف الملف.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج النصي: fs.open().

fs.readdirSync(path[, options])

[السجل]

الإصدار	التغييرات
v20.1.0, v18.17.0	تمت إضافة خيار recursive.
v10.10.0	تمت إضافة خيار جديد withFileTypes.
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file: .
v0.1.21	تمت الإضافة في: v0.1.21

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'
  • withFileTypes <boolean> الافتراضي: false
  • recursive <boolean> إذا كان true، يقرأ محتويات الدليل بشكل متكرر. في الوضع المتكرر، سيقوم بإدراج جميع الملفات والملفات الفرعية والدلائل. الافتراضي: false.

• القيمة المُرجعه: <string[]> | <Buffer[]> | <fs.Dirent[]>

يقوم بقراءة محتويات الدليل.

راجع وثائق POSIX readdir(3) لمزيد من التفاصيل.

يمكن أن يكون وسيط options الاختياري سلسلة نصية تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي سيتم استخدامه لأسماء الملفات المُرجعه. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير أسماء الملفات المُرجعه كأجسام <Buffer>.

إذا تم تعيين options.withFileTypes على true، فستحتوي النتيجة على أجسام <fs.Dirent>.

fs.readFileSync(path[, options])

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file: .
v5.0.0	يمكن أن يكون مُعامل path الآن مُوصِف ملف.
v0.1.8	تمت الإضافة في: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> اسم الملف أو مُوصِف الملف

• options <Object> | <string>

  • encoding <string> | <null> افتراضي: null
  • flag <string> انظر دعم مُعلمات نظام الملفات. افتراضي: 'r'.

• المُخرجات: <string> | <Buffer>

يُعيد محتويات path.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.readFile().

إذا تم تحديد خيار encoding، فإن هذه الوظيفة تُعيد سلسلة. خلاف ذلك، فإنها تُعيد مُخزن مؤقت.

على غرار fs.readFile()، عندما يكون المسار عبارة عن مُجلد، فإن سلوك fs.readFileSync() يعتمد على النظام الأساسي.

import { readFileSync } from 'node:fs'

// macOS و Linux و Windows
readFileSync('<directory>')
// => [Error: EISDIR: عملية غير قانونية على مُجلد، قراءة <directory>]

// FreeBSD
readFileSync('<directory>') // => <data>

fs.readlinkSync(path[, options])

[History]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path مُثالاً من كائن WHATWG URL باستخدام بروتوكول file:
v0.1.31	تمت الإضافة في: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• القيمة المُرجعة: <string> | <Buffer>

يُرجِع القيمة السلسلية للرابط الرمزي.

للمزيد من التفاصيل، انظر وثائق POSIX readlink(2).

يمكن أن يكون المُعامل الاختياري options سلسلة تُحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تُحدد ترميز الأحرف المُستخدم لمسار الرابط المُرجَع. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير مسار الرابط المُرجَع ككائن <Buffer>.

fs.readSync(fd, buffer, offset, length[, position])

[History]

الإصدار	التغييرات
v10.10.0	يمكن أن يكون مُعامل buffer الآن أي TypedArray أو DataView.
v6.0.0	يمكن أن يكون مُعامل length الآن 0.
v0.1.21	تمت الإضافة في: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> الافتراضي: null
• القيمة المُرجعة: <number>

يُرجِع عدد bytesRead.

للحصول على معلومات مُفصّلة، انظر وثائق الإصدار اللا مُزامن من هذا الـ API: fs.read().

fs.readSync(fd, buffer[, options])

[History]

الإصدار	التغييرات
v13.13.0, v12.17.0	يمكن تمرير كائن الخيارات لجعل الإزاحة والطول والموضع اختياريين.
v13.13.0, v12.17.0	تمت الإضافة في: v13.13.0, v12.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> الافتراضي: 0
  • length <integer> الافتراضي: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> الافتراضي: null

• الإرجاع: <number>

يرجع عدد bytesRead.

على غرار دالة fs.readSync المذكورة أعلاه، يأخذ هذا الإصدار كائن options اختياريًا. إذا لم يتم تحديد كائن options، فسيتم تعيينه افتراضيًا بالقيم المذكورة أعلاه.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.read().

fs.readvSync(fd, buffers[, position])

تمت الإضافة في: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> الافتراضي: null
• الإرجاع: <number> عدد البايتات المقروءة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.readv().

fs.realpathSync(path[, options])

[السجل]

الإصدار	التغييرات
v8.0.0	تمت إضافة دعم حل الأنابيب/المقابس.
v7.6.0	يمكن أن تكون معلمة path كائن WHATWG URL باستخدام بروتوكول file: .
v6.4.0	تعمل الآن استدعاء realpathSync مرة أخرى لحالات الحافة المختلفة على Windows.
v6.0.0	تمت إزالة معلمة cache.
v0.1.31	تمت الإضافة في: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• القيمة المُرجعة: <string> | <Buffer>

يرجع اسم المسار المُحلل.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا API: fs.realpath().

fs.realpathSync.native(path[, options])

تمت الإضافة في: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> الافتراضي: 'utf8'

• القيمة المُرجعة: <string> | <Buffer>

realpath(3) متزامن.

يتم دعم المسارات التي يمكن تحويلها إلى سلاسل UTF8 فقط.

يمكن أن تكون وسيطة options الاختيارية سلسلة تحدد ترميزًا، أو كائنًا يحتوي على خاصية encoding تحدد ترميز الأحرف الذي سيتم استخدامه للمسار المُرجَع. إذا تم تعيين encoding على 'buffer'، فسيتم تمرير المسار المُرجَع ككائن <Buffer>.

على Linux، عندما يتم ربط Node.js بـ musl libc، يجب تركيب نظام ملفات procfs على /proc لكي تعمل هذه الدالة. لا يحتوي Glibc على هذا التقييد.

fs.renameSync(oldPath, newPath)

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون параметران oldPath و newPath كائنات WHATWG URL باستخدام بروتوكول file:، والدعم لا يزال تجريبيًا حاليًا.
v0.1.21	تمت الإضافة في: v0.1.21

• oldPath <سلسلة> | <مُخزن مؤقت> | <عنوان URL>
• newPath <سلسلة> | <مُخزن مؤقت> | <عنوان URL>

يعيد تسمية الملف من oldPath إلى newPath. يعيد undefined.

راجع وثائق POSIX rename(2) لمزيد من التفاصيل.

fs.rmdirSync(path[, options])

[السجل]

الإصدار	التغييرات
v16.0.0	لم يعد يُسمح باستخدام fs.rmdirSync(path, { recursive: true }) على path وهو ملف، ونتيجة لذلك يُرجع خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.
v16.0.0	لم يعد يُسمح باستخدام fs.rmdirSync(path, { recursive: true }) على path غير موجود، ونتيجة لذلك يُرجع خطأ ENOENT.
v16.0.0	خيار recursive مُهمل، واستخدامه يُنشئ تحذيرًا بالإهمال.
v14.14.0	خيار recursive مُهمل، استخدم fs.rmSync بدلاً منه.
v13.3.0, v12.16.0	تم تغيير اسم خيار maxBusyTries إلى maxRetries، وافتراضه هو 0. تمت إزالة خيار emfileWait، وتستخدم أخطاء EMFILE نفس منطق إعادة المحاولة مثل الأخطاء الأخرى. تم دعم خيار retryDelay الآن. يتم إعادة محاولة أخطاء ENFILE الآن.
v12.10.0	تم دعم خيارات recursive و maxBusyTries و emfileWait الآن.
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file:.
v0.1.21	تمت الإضافة في: v0.1.21

• path <سلسلة> | <مُخزن مؤقت> | <عنوان URL>
• options <كائن>
  • maxRetries <عدد صحيح> إذا تم مواجهة خطأ EBUSY أو EMFILE أو ENFILE أو ENOTEMPTY أو EPERM، فإن Node.js يُعيد محاولة العملية مع انتظار مُؤجل خطي لـ retryDelay مللي ثانية أطول في كل محاولة. يُمثل هذا الخيار عدد مرات إعادة المحاولة. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 0.
  • recursive <قيمة منطقية> إذا كانت true، فقم بإجراء إزالة مُجلد مُتكررة. في الوضع المُتكرر، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false. مُهمل.
  • retryDelay <عدد صحيح> مقدار الوقت بالمللي ثانية الذي يجب الانتظار بين المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive مساويًا لـ true. الافتراضي: 100.

rmdir(2) متزامن. يعيد undefined.

يؤدي استخدام fs.rmdirSync() على ملف (ليس مُجلدًا) إلى خطأ ENOENT على Windows وخطأ ENOTDIR على POSIX.

لحصول على سلوك مشابه لأمر rm -rf في يونكس، استخدم fs.rmSync() مع الخيارات { recursive: true, force: true }.

fs.rmSync(path[, options])

[History]

الإصدار	التغييرات
v17.3.0, v16.14.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file:
v14.14.0	تمت الإضافة في: v14.14.0

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> عندما تكون true، سيتم تجاهل الاستثناءات إذا لم يكن path موجودًا. الافتراضي: false.
  • maxRetries <integer> إذا تم مواجهة خطأ EBUSY، EMFILE، ENFILE، ENOTEMPTY، أو EPERM، فستعيد Node.js محاولة العملية مع انتظار تأخير خطي بقيمة retryDelay مللي ثانية أطول في كل محاولة. يمثل هذا الخيار عدد المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive هو true. الافتراضي: 0.
  • recursive <boolean> إذا كانت true، فقم بإزالة الدليل بشكل متكرر. في وضع التكرار، يتم إعادة محاولة العمليات عند الفشل. الافتراضي: false.
  • retryDelay <integer> مقدار الوقت بالميلي ثانية الذي يجب الانتظار بين المحاولات. يتم تجاهل هذا الخيار إذا لم يكن خيار recursive هو true. الافتراضي: 100.

يزيل الملفات والدلائل بشكل متزامن (على غرار أداة POSIX القياسية rm). يُرجع undefined.

fs.statSync(path[, options])

[History]

الإصدار	التغييرات
v15.3.0, v14.17.0	يقبل خيار throwIfNoEntry لتحديد ما إذا كان يجب إلقاء استثناء إذا لم يكن الإدخال موجودًا.
v10.5.0	يقبل كائن options إضافيًا لتحديد ما إذا كان يجب أن تكون القيم العددية المُرتجعة هي bigint.
v7.6.0	يمكن أن يكون مُعامل path كائن WHATWG URL باستخدام بروتوكول file:
v0.1.21	تمت الإضافة في: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> ما إذا كانت القيم العددية في كائن <fs.Stats> المُرتجعة يجب أن تكون bigint. الافتراضي: false.
  • throwIfNoEntry <boolean> ما إذا كان سيتم إلقاء استثناء إذا لم يكن هناك إدخال في نظام الملفات، بدلاً من إرجاع undefined. الافتراضي: true.

• المُرتجع: <fs.Stats>

يسترد <fs.Stats> للمسار.

fs.statfsSync(path[, options])

مضاف في: v19.6.0، v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> هل يجب أن تكون القيم العددية في كائن <fs.StatFs> المُرجَع bigint. افتراضيًا: false.

• مُرجَع: <fs.StatFs>

statfs(2) متزامن. يُرجِع معلومات حول نظام الملفات المُركّب الذي يحتوي على path.

في حالة حدوث خطأ، سيكون err.code أحد أخطاء النظام الشائعة.

fs.symlinkSync(target, path[, type])

[السجل]

الإصدار	التغييرات
v12.0.0	إذا تم ترك وسيطة type غير مُعرّفة، فسوف تكتشف Node نوع target تلقائيًا وتختار dir أو file تلقائيًا.
v7.6.0	يمكن أن تكون معاملتا target و path كائنات WHATWG URL باستخدام بروتوكول file: . الدعم لا يزال تجريبيًا حاليًا.
v0.1.31	مضاف في: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> افتراضيًا: null

يُرجِع undefined.

للحصول على معلومات مُفصّلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.symlink().

fs.truncateSync(path[, len])

مضاف في: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> افتراضي: 0

يقوم بقص الملف. يُرجع undefined. يمكن أيضًا تمرير مُعرّف ملف كمُعامل أول. في هذه الحالة، يتم استدعاء fs.ftruncateSync().

إن تمرير مُعرّف الملف قديم وقد يؤدي إلى ظهور خطأ في المستقبل.

fs.unlinkSync(path)

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:
v0.1.21	مضاف في: v0.1.21

• path <string> | <Buffer> | <URL>

unlink(2) متزامن. يُرجع undefined.

fs.utimesSync(path, atime, mtime)

[السجل]

الإصدار	التغييرات
v8.0.0	لم تعد NaN و Infinity و -Infinity مُحددات أوقات صالحة.
v7.6.0	يمكن أن يكون مُعامل path كائن URL من WHATWG باستخدام بروتوكول file:
v4.1.0	أصبحت السلاسل الرقمية و NaN و Infinity مُحددات أوقات مُسموح بها الآن.
v0.4.2	مضاف في: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

يُرجع undefined.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.utimes().

fs.writeFileSync(file, data[, options])

[السجل]

الإصدار	التغييرات
v21.0.0، v20.10.0	أصبح خيار flush مدعومًا الآن.
v19.0.0	لم يعد يُسمح بمرور كائن يحتوي على دالة toString خاصة به إلى معامل data.
v17.8.0	أصبح تمرير كائن يحتوي على دالة toString خاصة به إلى معامل data قديمًا.
v14.12.0	سيقوم معامل data بتحويل كائن يحتوي على دالة toString صريحة إلى سلسلة نصية.
v14.0.0	لن يقوم معامل data بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v10.10.0	يمكن أن يكون معامل data الآن أي TypedArray أو DataView.
v7.4.0	يمكن أن يكون معامل data الآن Uint8Array.
v5.0.0	يمكن أن يكون معامل file الآن مُعرّف ملف.
v0.1.29	تمت الإضافة في: v0.1.29

• file <سلسلة> | <مخزن مؤقت> | <عنوان URL> | <عدد صحيح> اسم الملف أو مُعرّف الملف
• data <سلسلة> | <مخزن مؤقت> | <TypedArray> | <DataView>
• options <كائن> | <سلسلة>
  • encoding <سلسلة> | <لا شيء> الافتراضي: 'utf8'
  • mode <عدد صحيح> الافتراضي: 0o666
  • flag <سلسلة> انظر دعم علامات نظام الملفات. الافتراضي: 'w'.
  • flush <قيمة منطقية> إذا تم كتابة جميع البيانات بنجاح في الملف، و flush هي true، فسيتم استخدام fs.fsyncSync() لتنظيف البيانات.

يُرجع undefined.

يؤثر خيار mode فقط على الملف المُنشأ حديثًا. راجع fs.open() لمزيد من التفاصيل.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.writeFile().

fs.writeSync(fd, buffer, offset[, length[, position]])

[السجل]

الإصدار	التغييرات
v14.0.0	لن تقوم معلمة buffer بتحويل الإدخال غير المدعوم إلى سلاسل نصية بعد الآن.
v10.10.0	يمكن أن تكون معلمة buffer الآن أي TypedArray أو DataView.
v7.4.0	يمكن أن تكون معلمة buffer الآن Uint8Array.
v7.2.0	أصبحت معلمات offset و length اختيارية الآن.
v0.1.21	تمت الإضافة في: v0.1.21

• fd <عدد صحيح>
• buffer <وسيط> | <TypedArray> | <DataView>
• offset <عدد صحيح> افتراضي: 0
• length <عدد صحيح> افتراضي: buffer.byteLength - offset
• position <عدد صحيح> | <لا شيء> افتراضي: null
• القيمة المرجعة: <عدد> عدد البايت المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

تمت الإضافة في: v18.3.0، v16.17.0

• fd <عدد صحيح>

• buffer <وسيط> | <TypedArray> | <DataView>

• options <كائن>

  • offset <عدد صحيح> افتراضي: 0
  • length <عدد صحيح> افتراضي: buffer.byteLength - offset
  • position <عدد صحيح> افتراضي: null

• القيمة المرجعة: <عدد> عدد البايت المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا البرنامج: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[History]

الإصدار	التغييرات
v14.0.0	لن تقوم معلمة string بتحويل المدخلات غير المدعومة إلى سلاسل نصية بعد الآن.
v7.2.0	أصبحت معلمة position اختيارية الآن.
v0.11.5	تمت الإضافة في: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> الافتراضي: null
• encoding <string> الافتراضي: 'utf8'
• القيمة المُرجعة: <number> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

تمت الإضافة في: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> الافتراضي: null
• القيمة المُرجعة: <number> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من هذا الـ API: fs.writev().

الكائنات الشائعة

تُشارك الكائنات الشائعة بواسطة جميع أنواع واجهة برمجة تطبيقات نظام الملفات (الوعود، وظيفة الاستدعاء، والمتزامنة).

الصف: fs.Dir

مضاف في: v12.12.0

صف يمثل دفق دليل.

تم إنشاؤه بواسطة fs.opendir()، fs.opendirSync()، أو fsPromises.opendir().

import { opendir } from 'node:fs/promises'

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

عند استخدام مُكرر async، سيتم إغلاق كائن <fs.Dir> تلقائيًا بعد خروج المُكرر.

dir.close()

مضاف في: v12.12.0

• قيمة مُعادة: <Promise>

يغلق بشكل غير متزامن مُقبض مورد الدليل الأساسي. ستؤدي القراءات اللاحقة إلى أخطاء.

يتم إرجاع وعد سيتم الوفاء به بعد إغلاق المورد.

dir.close(callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُدعوى غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v12.12.0	مضاف في: v12.12.0

• callback <Function>
  • err <Error>

يغلق بشكل غير متزامن مُقبض مورد الدليل الأساسي. ستؤدي القراءات اللاحقة إلى أخطاء.

سيتم استدعاء callback بعد إغلاق مُقبض المورد.

dir.closeSync()

مضاف في: v12.12.0

يغلق بشكل متزامن مُقبض مورد الدليل الأساسي. ستؤدي القراءات اللاحقة إلى أخطاء.

dir.path

مضاف في: v12.12.0

• <string>

مسار القراءة فقط لهذا الدليل كما تم توفيره إلى fs.opendir()، fs.opendirSync()، أو fsPromises.opendir().

dir.read()

أضيف في: v12.12.0

• القيمة المُرجعَة: <Promise> يتم الوفاء بوعد بـ <fs.Dirent> | <null>

قراءة الإدخال التالي للمجلد بشكل غير متزامن عبر readdir(3) كـ <fs.Dirent>.

يتم إرجاع وعد سيتم الوفاء به باستخدام <fs.Dirent> ، أو null إذا لم تكن هناك المزيد من إدخالات الدليل للقراءة.

لا يتم ترتيب إدخالات الدليل التي تُرجعها هذه الدالة بترتيب معين كما هو موضح في آليات دليل النظام الأساسي. قد لا يتم تضمين الإدخالات التي تمت إضافتها أو إزالتها أثناء التكرار في نتائج التكرار.

dir.read(callback)

أضيف في: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

قراءة الإدخال التالي للمجلد بشكل غير متزامن عبر readdir(3) كـ <fs.Dirent>.

بعد اكتمال القراءة ، سيتم استدعاء callback باستخدام <fs.Dirent> ، أو null إذا لم تكن هناك المزيد من إدخالات الدليل للقراءة.

لا يتم ترتيب إدخالات الدليل التي تُرجعها هذه الدالة بترتيب معين كما هو موضح في آليات دليل النظام الأساسي. قد لا يتم تضمين الإدخالات التي تمت إضافتها أو إزالتها أثناء التكرار في نتائج التكرار.

dir.readSync()

أضيف في: v12.12.0

• القيمة المُرجعَة: <fs.Dirent> | <null>

قراءة الإدخال التالي للمجلد بشكل متزامن كـ <fs.Dirent>. راجع وثائق POSIX readdir(3) لمزيد من التفاصيل.

إذا لم تكن هناك المزيد من إدخالات الدليل للقراءة ، فسيتم إرجاع null.

لا يتم ترتيب إدخالات الدليل التي تُرجعها هذه الدالة بترتيب معين كما هو موضح في آليات دليل النظام الأساسي. قد لا يتم تضمين الإدخالات التي تمت إضافتها أو إزالتها أثناء التكرار في نتائج التكرار.

dir[Symbol.asyncIterator]()

مضاف في: v12.12.0

• قيمة الإرجاع: <AsyncIterator> مُكرر غير متزامن لـ <fs.Dirent>

يُكرر بشكل غير متزامن على الدليل حتى يتم قراءة جميع الإدخالات. يرجى الرجوع إلى وثائق POSIX readdir(3) لمزيد من التفاصيل.

الإدخالات التي يُرجعها المُكرر غير المتزامن هي دائمًا <fs.Dirent>. يتم التعامل مع حالة null من dir.read() داخليًا.

راجع <fs.Dir> للحصول على مثال.

لا يوجد ترتيب معين لإدخالات الدليل التي يُرجعها هذا المُكرر، كما هو مُقدم من آليات الدليل الأساسية لنظام التشغيل. قد لا يتم تضمين الإدخالات التي تمت إضافتها أو إزالتها أثناء التكرار على الدليل في نتائج التكرار.

الصنف: fs.Dirent

مضاف في: v10.10.0

تمثيل لإدخال دليل، والذي يمكن أن يكون ملفًا أو دليلًا فرعيًا داخل الدليل، كما هو مُرجع من خلال القراءة من <fs.Dir>. إدخال الدليل هو مزيج من أزواج اسم الملف ونوع الملف.

بالإضافة إلى ذلك، عندما يتم استدعاء fs.readdir() أو fs.readdirSync() مع تعيين خيار withFileTypes إلى true، يتم تعبئة المصفوفة الناتجة بـ <fs.Dirent> كائنات، بدلاً من سلاسل أو <Buffer>s.

dirent.isBlockDevice()

مضاف في: v10.10.0

• قيمة الإرجاع: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف جهاز كتلة.

dirent.isCharacterDevice()

مضاف في: v10.10.0

• قيمة الإرجاع: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف جهاز حرف.

dirent.isDirectory()

أضيف في: v10.10.0

• مُخرجات: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف مُجلدًا في نظام الملفات.

dirent.isFIFO()

أضيف في: v10.10.0

• مُخرجات: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف أنبوب FIFO (أولاً في أولاً خارجاً).

dirent.isFile()

أضيف في: v10.10.0

• مُخرجات: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف ملفًا عاديًا.

dirent.isSocket()

أضيف في: v10.10.0

• مُخرجات: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف مقبسًا.

dirent.isSymbolicLink()

أضيف في: v10.10.0

• مُخرجات: <boolean>

يُرجع true إذا كان كائن <fs.Dirent> يصف رابطًا رمزيًا.

dirent.name

أضيف في: v10.10.0

• <string> | <Buffer>

اسم الملف الذي يشير إليه كائن <fs.Dirent> هذا. يتم تحديد نوع هذه القيمة بواسطة options.encoding المُمرر إلى fs.readdir() أو fs.readdirSync().

dirent.parentPath

أضيف في: v21.4.0, v20.12.0, v18.20.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

• <string>

المسار إلى المجلد الرئيسي للملف الذي يشير إليه كائن <fs.Dirent> هذا.

dirent.path

[السجل]

الإصدار	التغييرات
v23.2.0	لم تعد الخاصية للقراءة فقط.
v23.0.0	يؤدي الوصول إلى هذه الخاصية إلى إصدار تحذير. أصبحت الآن للقراءة فقط.
v21.5.0، v20.12.0، v18.20.0	مُحذّر منذ: v21.5.0، v20.12.0، v18.20.0
v20.1.0، v18.17.0	تمت الإضافة في: v20.1.0، v18.17.0

[مستقر: 0 - مُحذّر]

مستقر: 0 ثبات: 0 - مُحذّر: استخدم dirent.parentPath بدلاً من ذلك.

• <string>

مُرادف لـ dirent.parentPath.

الفئة: fs.FSWatcher

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

• يمتد من <EventEmitter>

ستعيد المكالمة الناجحة لطريقة fs.watch() كائن <fs.FSWatcher> جديدًا.

جميع كائنات <fs.FSWatcher> تُصدر حدث 'change' كلما تم تعديل ملف محدد يتم مراقبته.

الحدث: 'change'

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

• eventType <string> نوع حدث التغيير الذي حدث
• filename <string> | <Buffer> اسم الملف الذي تغير (إن وجد/متاح)

يُصدر عندما يتغير شيء ما في دليل أو ملف مراقب. راجع المزيد من التفاصيل في fs.watch().

قد لا يتم توفير وسيطة filename اعتمادًا على دعم نظام التشغيل. إذا تم توفير filename، فسيتم توفيره كـ <Buffer> إذا تم استدعاء fs.watch() مع خيار encoding الخاص به مُعيّنًا على 'buffer'، خلاف ذلك سيكون filename سلسلة نصية بتشفير UTF-8.

import { watch } from 'node:fs'
// مثال عند التعامل معه من خلال مُستمع fs.watch()
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // يُطبع: <Buffer ...>
  }
})

الحدث: 'close'

مضاف في: v10.0.0

يتم إصداره عندما يتوقف المُراقب عن مراقبة التغييرات. لم يعد كائن <fs.FSWatcher> المُغلق قابلاً للاستخدام في مُعالِج الحدث.

الحدث: 'error'

مضاف في: v0.5.8

• error <Error>

يتم إصداره عندما يحدث خطأ أثناء مراقبة الملف. لم يعد كائن <fs.FSWatcher> الذي حدث به الخطأ قابلاً للاستخدام في مُعالِج الحدث.

watcher.close()

مضاف في: v0.5.8

إيقاف مراقبة التغييرات على <fs.FSWatcher> المُعطى. بعد التوقف، لم يعد كائن <fs.FSWatcher> قابلاً للاستخدام.

watcher.ref()

مضاف في: v14.3.0, v12.20.0

• الإرجاع: <fs.FSWatcher>

عند استدعائه، يطلب من حلقة أحداث Node.js عدم الخروج طالما أن <fs.FSWatcher> نشط. لن يكون لاستدعاء watcher.ref() عدة مرات أي تأثير.

بشكل افتراضي، يتم "إسناد" جميع كائنات <fs.FSWatcher>، مما يجعل من غير الضروري عادةً استدعاء watcher.ref() إلا إذا تم استدعاء watcher.unref() مسبقًا.

watcher.unref()

مضاف في: v14.3.0, v12.20.0

• الإرجاع: <fs.FSWatcher>

عند استدعائه، لن يتطلب كائن <fs.FSWatcher> النشط بقاء حلقة أحداث Node.js نشطة. إذا لم تكن هناك أنشطة أخرى تحافظ على تشغيل حلقة الأحداث، فقد يخرج البرنامج قبل استدعاء دالة الاستدعاء لكائن <fs.FSWatcher>. لن يكون لاستدعاء watcher.unref() عدة مرات أي تأثير.

الفئة: fs.StatWatcher

مضاف في: v14.3.0, v12.20.0

• يمتد من <EventEmitter>

ستعيد المكالمة الناجحة لطريقة fs.watchFile() كائن <fs.StatWatcher> جديدًا.

watcher.ref()

مضاف في: v14.3.0, v12.20.0

• الإرجاع: <fs.StatWatcher>

عند استدعائه، يطلب من حلقة أحداث Node.js عدم الخروج طالما أن <fs.StatWatcher> نشط. لن يكون لاستدعاء watcher.ref() عدة مرات أي تأثير.

بشكل افتراضي، يتم "إسناد" جميع كائنات <fs.StatWatcher>، مما يجعل من غير الضروري عادةً استدعاء watcher.ref() إلا إذا تم استدعاء watcher.unref() مسبقًا.

watcher.unref()

مضاف في: v14.3.0، v12.20.0

• مُخرجات: <fs.StatWatcher>

عند النداء، لن يتطلب كائن <fs.StatWatcher> النشط بقاء حلقة أحداث Node.js نشطة. إذا لم يكن هناك نشاط آخر يبقي حلقة الحدث قيد التشغيل، فقد تخرج العملية قبل استدعاء مُستدعي كائن <fs.StatWatcher>. لن يكون لاستدعاء watcher.unref() عدة مرات أي تأثير.

الفئة: fs.ReadStream

مضاف في: v0.1.93

• امتداد: <stream.Readable>

يتم إنشاء مثيلات <fs.ReadStream> وإرجاعها باستخدام دالة fs.createReadStream().

الحدث: 'close'

مضاف في: v0.1.93

يُصدر عندما يتم إغلاق مُصفف الوصف الخاص بالملف الأساسي لـ <fs.ReadStream>.

الحدث: 'open'

مضاف في: v0.1.93

• fd <integer> مُصفف وصف ملف عدد صحيح يُستخدم بواسطة <fs.ReadStream>.

يُصدر عندما يتم فتح مُصفف وصف الملف الخاص بـ <fs.ReadStream>.

الحدث: 'ready'

مضاف في: v9.11.0

يُصدر عندما يكون <fs.ReadStream> جاهزًا للاستخدام.

يتم تشغيله مباشرة بعد 'open'.

readStream.bytesRead

مضاف في: v6.4.0

• <number>

عدد البايتات التي تم قراءتها حتى الآن.

readStream.path

مضاف في: v0.1.93

• <string> | <Buffer>

مسار الملف الذي يقرأ منه التدفق كما هو محدد في الوسيطة الأولى لـ fs.createReadStream(). إذا تم تمرير path كسلسلة، فسيكون readStream.path سلسلة. إذا تم تمرير path كـ <Buffer>، فسيكون readStream.path <Buffer>. إذا تم تحديد fd، فسيكون readStream.path undefined.

readStream.pending

مُضاف في: v11.2.0، v10.16.0

• <boolean>

هذه الخاصية تساوي true إذا لم يتم فتح الملف الأساسي بعد، أي قبل إصدار حدث 'ready'.

Class: fs.Stats

[History]

الإصدار	التغييرات
v22.0.0، v20.13.0	مُنشئ عام مُهمل.
v8.1.0	أضيف الأوقات كأرقام.
v0.1.21	مُضاف في: v0.1.21

يوفر كائن <fs.Stats> معلومات حول ملف.

الكائنات المُرتجعة من fs.stat()، fs.lstat()، fs.fstat()، ونظيراتها المتزامنة من هذا النوع. إذا كانت bigint في options المُمررة إلى هذه الطرق تساوي true، فسيكون القيم العددية من نوع bigint بدلاً من number، وسيحتوي الكائن على خصائص إضافية بدقة نانوثانية مُلحقة بـ Ns. لا يجب إنشاء كائنات Stat مباشرةً باستخدام الكلمة المفتاحية new.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

نسخة bigint:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف جهاز كتلة.

stats.isCharacterDevice()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف جهاز حرف.

stats.isDirectory()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف دليل نظام ملفات.

إذا تم الحصول على كائن <fs.Stats> من خلال استدعاء fs.lstat() على رابط رمزي يحل إلى دليل، فإن هذه الطريقة سترجع false. هذا لأن fs.lstat() ترجع معلومات حول الرابط الرمزي نفسه وليس المسار الذي يحله.

stats.isFIFO()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف أنبوب FIFO (الأولوية للأول).

stats.isFile()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف ملفًا عاديًا.

stats.isSocket()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف مقبسًا.

stats.isSymbolicLink()

أضيف في: v0.1.10

• الإرجاع: <boolean>

يرجع true إذا كان كائن <fs.Stats> يصف رابطًا رمزيًا.

هذه الطريقة صالحة فقط عند استخدام fs.lstat().

stats.dev

• <number> | <bigint>

معرّف رقمي للجهاز الذي يحتوي على الملف.

stats.ino

• <number> | <bigint>

رقم "Inode" الخاص بنظام الملفات للملف.

stats.mode

• <number> | <bigint>

حقل بتّي يصف نوع الملف ووضعه.

stats.nlink

• <number> | <bigint>

عدد الوصلات الثابتة الموجودة للملف.

stats.uid

• <number> | <bigint>

معرّف المستخدم الرقمي للمستخدم الذي يملك الملف (POSIX).

stats.gid

• <number> | <bigint>

معرّف المجموعة الرقمي للمجموعة التي تملك الملف (POSIX).

stats.rdev

• <number> | <bigint>

معرّف جهاز رقمي إذا كان الملف يمثل جهازًا.

stats.size

• <number> | <bigint>

حجم الملف بالبايت.

إذا لم يدعم نظام الملفات الأساسي الحصول على حجم الملف، فسيكون هذا 0.

stats.blksize

• <number> | <bigint>

حجم كتلة نظام الملفات لعمليات الإدخال/الإخراج.

stats.blocks

• <number> | <bigint>

عدد الكتل المخصصة لهذا الملف.

stats.atimeMs

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

• <number> | <bigint>

الزمن الذي يدل على آخر مرة تم الوصول فيها إلى هذا الملف، معبراً عنه بالميلي ثانية منذ عصر يونكس.

stats.mtimeMs

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

• <number> | <bigint>

الزمن الذي يدل على آخر مرة تم تعديل هذا الملف فيها، معبراً عنه بالميلي ثانية منذ عصر يونكس.

stats.ctimeMs

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

• <number> | <bigint>

الزمن الذي يدل على آخر مرة تم تغيير حالة الملف فيها، معبراً عنه بالميلي ثانية منذ عصر يونكس.

stats.birthtimeMs

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

• <number> | <bigint>

الزمن الذي يدل على وقت إنشاء هذا الملف، معبراً عنه بالميلي ثانية منذ عصر يونكس.

stats.atimeNs

تم الإضافة في: v12.10.0

• <bigint>

يظهر فقط عندما يتم تمرير bigint: true إلى الأسلوب الذي يولد الكائن. الزمن الذي يدل على آخر مرة تم الوصول فيها إلى هذا الملف، معبراً عنه بالنانو ثانية منذ عصر يونكس.

stats.mtimeNs

تم الإضافة في: v12.10.0

• <bigint>

لا تظهر إلا عند تمرير bigint: true إلى الأسلوب الذي يُنشئ الكائن. الوقت الذي يدل على آخر مرة تم تعديل هذا الملف فيها، معبر عنه بالنانوثانية منذ حقبة POSIX.

stats.ctimeNs

تم الإضافة في: v12.10.0

• <bigint>

لا تظهر إلا عند تمرير bigint: true إلى الأسلوب الذي يُنشئ الكائن. الوقت الذي يدل على آخر مرة تم تغيير حالة الملف فيها، معبر عنه بالنانوثانية منذ حقبة POSIX.

stats.birthtimeNs

تم الإضافة في: v12.10.0

• <bigint>

لا تظهر إلا عند تمرير bigint: true إلى الأسلوب الذي يُنشئ الكائن. الوقت الذي يدل على وقت إنشاء هذا الملف، معبر عنه بالنانوثانية منذ حقبة POSIX.

stats.atime

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

• <Date>

الوقت الذي يدل على آخر مرة تم الوصول إلى هذا الملف فيها.

stats.mtime

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

• <Date>

الوقت الذي يدل على آخر مرة تم تعديل هذا الملف فيها.

stats.ctime

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

• <Date>

الوقت الذي يدل على آخر مرة تم تغيير حالة الملف فيها.

stats.birthtime

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

• <Date>

الوقت الذي يدل على وقت إنشاء هذا الملف.

قيم وقت الحالة

الخصائص atimeMs, mtimeMs, ctimeMs, birthtimeMs هي قيم عددية تحمل الأوقات المقابلة بالميلي ثانية. دقة هذه القيم تعتمد على النظام الأساسي. عندما يتم تمرير bigint: true إلى الأسلوب الذي يُنشئ الكائن، ستكون الخصائص bigints، وإلا ستكون أعداد.

الخصائص atimeNs, mtimeNs, ctimeNs, birthtimeNs هي bigints تحمل الأوقات المقابلة بالنانوثانية. تظهر فقط عندما يتم تمرير bigint: true إلى الأسلوب الذي يُنشئ الكائن. دقة هذه القيم تعتمد على النظام الأساسي.

atime, mtime, ctime, و birthtime هي تمثيلات بديلة للأوقات المختلفة باستخدام كائن Date. قيم Date والعدد غير مرتبطة. لن ينعكس تعيين قيمة عددية جديدة، أو تغيير قيمة Date، في التمثيل البديل المقابل.

لأوقات في كائن الحالة المعاني التالية:

• atime "وقت الوصول": الوقت الذي تم فيه الوصول إلى بيانات الملف آخر مرة. تتغير بواسطة نداءات النظام mknod(2), utimes(2), و read(2).
• mtime "وقت التعديل": الوقت الذي تم فيه تعديل بيانات الملف آخر مرة. تتغير بواسطة نداءات النظام mknod(2), utimes(2), و write(2).
• ctime "وقت التغيير": الوقت الذي تم فيه تغيير حالة الملف آخر مرة (تعديل بيانات العقدة). تتغير بواسطة نداءات النظام chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), و write(2).
• birthtime "وقت الميلاد": وقت إنشاء الملف. يتم تعيينه مرة واحدة عند إنشاء الملف. في أنظمة الملفات التي لا يتوفر فيها birthtime، قد يحمل هذا الحقل بدلاً من ذلك إما ctime أو 1970-01-01T00:00Z (أي، طابع زمني لعصر يونكس 0). قد تكون هذه القيمة أكبر من atime أو mtime في هذه الحالة. على Darwin والمتغيرات الأخرى من FreeBSD، يتم تعيينها أيضًا إذا تم تعيين atime صراحةً إلى قيمة أقدم من birthtime الحالي باستخدام نداء النظام utimes(2).

قبل Node.js 0.12، كان ctime يحمل birthtime على أنظمة Windows. اعتبارًا من الإصدار 0.12، ctime ليس "وقت الإنشاء"، وعلى أنظمة Unix، لم يكن كذلك أبدًا.

صنف: fs.StatFs

مضاف في: v19.6.0، v18.15.0

يوفر معلومات حول نظام الملفات المُركّب.

الأشياء المُرتجعة من fs.statfs() ونظيرتها المُزامنة هي من هذا النوع. إذا كان bigint في options المُمرر إلى هذه الطرق يساوي true، فسيتم تمثيل القيم العددية كـ bigint بدلاً من number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

نسخة bigint:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

الكتل الحرة المتاحة للمستخدمين غير المُتمتّعين بامتيازات.

statfs.bfree

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

الكتل الحرة في نظام الملفات.

statfs.blocks

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

مجموع كتل البيانات في نظام الملفات.

statfs.bsize

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

حجم الكتلة الأمثل للنقل.

statfs.ffree

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

عقد الملفات الحرة في نظام الملفات.

statfs.files

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

مجموع عقد الملفات في نظام الملفات.

statfs.type

مضاف في: v19.6.0، v18.15.0

• <number> | <bigint>

نوع نظام الملفات.

Class: fs.WriteStream

مضاف في: v0.1.93

• يمتد من <stream.Writable>

يتم إنشاء مثيلات <fs.WriteStream> وإرجاعها باستخدام دالة fs.createWriteStream().

Event: 'close'

مضاف في: v0.1.93

يتم إصداره عندما يتم إغلاق مُوصِف الملف الأساسي لـ <fs.WriteStream>.

Event: 'open'

مضاف في: v0.1.93

• fd <integer> مُوصِف ملف عدد صحيح يُستخدم بواسطة <fs.WriteStream>.

يتم إصداره عند فتح ملف <fs.WriteStream>.

Event: 'ready'

مضاف في: v9.11.0

يتم إصداره عندما يكون <fs.WriteStream> جاهزًا للاستخدام.

يتم تشغيله مباشرة بعد 'open'.

writeStream.bytesWritten

مضاف في: v0.4.7

عدد البايتات المكتوبة حتى الآن. لا يشمل البيانات التي لا تزال مُنتظرة للكتابة.

writeStream.close([callback])

مضاف في: v0.9.4

• callback <Function>
  • err <Error>

يُغلق writeStream. يقبل اختياريًا دالة مُعاداة تُنفذ بمجرد إغلاق writeStream.

writeStream.path

مضاف في: v0.1.93

مسار الملف الذي يقوم التدفق بالكتابة إليه كما هو محدد في الوسيط الأول لـ fs.createWriteStream(). إذا تم تمرير path كسلسلة، فسيكون writeStream.path سلسلة. إذا تم تمرير path كـ <Buffer>، فسيكون writeStream.path <Buffer>.

writeStream.pending

مضاف في: v11.2.0

• <boolean>

هذه الخاصية تساوي true إذا لم يتم فتح الملف الأساسي بعد، أي قبل إصدار حدث 'ready'.

fs.constants

• <Object>

يرجع كائنًا يحتوي على ثوابت شائعة الاستخدام لعمليات نظام الملفات.

ثوابت FS

يتم تصدير الثوابت التالية بواسطة fs.constants و fsPromises.constants.

لن تكون جميع الثوابت متاحة على كل نظام تشغيل؛ هذا مهم بشكل خاص لنظام التشغيل Windows، حيث لا تتوفر العديد من التعريفات الخاصة بـ POSIX. للتطبيقات القابلة للنقل، يُنصح بالتحقق من وجودها قبل الاستخدام.

لاستخدام أكثر من ثابت واحد، استخدم عامل التشغيل المنطقي بت OR |.

مثال:

import { open, constants } from 'node:fs'

const { O_RDWR, O_CREAT, O_EXCL } = constants

open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
})

ثوابت وصول الملف

تهدف الثوابت التالية للاستخدام كمعامل mode الممرر إلى fsPromises.access()، fs.access()، و fs.accessSync().

الثابت	الوصف
F_OK	علم يشير إلى أن الملف مرئي لعملية الاتصال. هذا مفيد لتحديد ما إذا كان الملف موجودًا، لكنه لا يقول شيئًا عن أذونات rwx. الافتراضي إذا لم يتم تحديد أي وضع.
R_OK	علم يشير إلى إمكانية قراءة الملف بواسطة عملية الاتصال.
W_OK	علم يشير إلى إمكانية كتابة الملف بواسطة عملية الاتصال.
X_OK	علم يشير إلى إمكانية تنفيذ الملف بواسطة عملية الاتصال. هذا ليس له أي تأثير على Windows (سيتصرف مثل fs.constants.F_OK).

التعريفات متاحة أيضًا على Windows.

ثوابت نسخ الملفات

تهدف الثوابت التالية للاستخدام مع fs.copyFile().

الثابت	الوصف
COPYFILE_EXCL	إذا وجد، ستفشل عملية النسخ بخطأ إذا كان مسار الوجهة موجودًا بالفعل.
COPYFILE_FICLONE	إذا وجد، ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم تدعم المنصة الأساسية copy-on-write، فسيتم استخدام آلية نسخ احتياطية.
COPYFILE_FICLONE_FORCE	إذا وجد، ستحاول عملية النسخ إنشاء رابط مرجعي copy-on-write. إذا لم تدعم المنصة الأساسية copy-on-write، فستفشل العملية بخطأ.

التعاريف متاحة أيضًا على Windows.

ثوابت فتح الملفات

تهدف الثوابت التالية للاستخدام مع fs.open().

الثابت	الوصف
O_RDONLY	علم يشير إلى فتح ملف للقراءة فقط.
O_WRONLY	علم يشير إلى فتح ملف للكتابة فقط.
O_RDWR	علم يشير إلى فتح ملف للقراءة والكتابة.
O_CREAT	علم يشير إلى إنشاء الملف إذا لم يكن موجودًا بالفعل.
O_EXCL	علم يشير إلى أن فتح ملف يجب أن يفشل إذا تم تعيين علم O_CREAT والملف موجود بالفعل.
O_NOCTTY	علم يشير إلى أنه إذا حدد المسار جهاز طرفي، فإن فتح المسار لن يتسبب في أن يصبح هذا الطرفي طرفًا تحكميًا للعملية (إذا لم تكن العملية تمتلك بالفعل واحدًا).
O_TRUNC	علم يشير إلى أنه إذا كان الملف موجودًا وهو ملف عادي، وتم فتح الملف بنجاح للوصول إلى الكتابة، فسيتم اقتطاع طوله إلى صفر.
O_APPEND	علم يشير إلى أنه سيتم إضافة البيانات إلى نهاية الملف.
O_DIRECTORY	علم يشير إلى أن الفتح يجب أن يفشل إذا لم يكن المسار دليلًا.
O_NOATIME	علم يشير إلى أن عمليات القراءة على نظام الملفات لن تؤدي بعد الآن إلى تحديث معلومات atime المرتبطة بالملف. هذا العلم متاح على أنظمة تشغيل Linux فقط.
O_NOFOLLOW	علم يشير إلى أن الفتح يجب أن يفشل إذا كان المسار رابطًا رمزيًا.
O_SYNC	علم يشير إلى أن الملف مفتوح لإدخال/إخراج متزامن مع عمليات الكتابة التي تنتظر سلامة الملف.
O_DSYNC	علم يشير إلى أن الملف مفتوح لإدخال/إخراج متزامن مع عمليات الكتابة التي تنتظر سلامة البيانات.
O_SYMLINK	علم يشير إلى فتح الرابط الرمزي نفسه بدلاً من المورد الذي يشير إليه.
O_DIRECT	عند تعيينه، سيتم بذل محاولة لتقليل آثار التخزين المؤقت لإدخال/إخراج الملف.
O_NONBLOCK	علم يشير إلى فتح الملف في وضع غير مسدود عند إمكانية ذلك.
UV_FS_O_FILEMAP	عند تعيينه، يتم استخدام تعيين ملف ذاكرة للوصول إلى الملف. هذا العلم متاح على أنظمة تشغيل Windows فقط. على أنظمة التشغيل الأخرى، يتم تجاهل هذا العلم.

على Windows، تكون فقط O_APPEND، O_CREAT، O_EXCL، O_RDONLY، O_RDWR، O_TRUNC، O_WRONLY، و UV_FS_O_FILEMAP متاحة.

ثوابت نوع الملف

تهدف الثوابت التالية للاستخدام مع خاصية mode لكائن <fs.Stats> لتحديد نوع الملف.

الثابت	الوصف
S_IFMT	قناع بت يستخدم لاستخراج رمز نوع الملف.
S_IFREG	ثابت نوع الملف لملف عادي.
S_IFDIR	ثابت نوع الملف لدليل.
S_IFCHR	ثابت نوع الملف لملف جهاز موجه للشخصيات.
S_IFBLK	ثابت نوع الملف لملف جهاز موجه للكتل.
S_IFIFO	ثابت نوع الملف لـ FIFO/أنبوب.
S_IFLNK	ثابت نوع الملف لرابط رمزي.
S_IFSOCK	ثابت نوع الملف لمقبس.

في Windows، تتوفر فقط S_IFCHR، S_IFDIR، S_IFLNK، S_IFMT، و S_IFREG.

ثوابت وضع الملف

تهدف الثوابت التالية للاستخدام مع خاصية mode لكائن <fs.Stats> لتحديد أذونات الوصول إلى ملف.

الثابت	الوصف
S_IRWXU	وضع الملف الذي يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل المالك.
S_IRUSR	وضع الملف الذي يشير إلى قابلية القراءة من قبل المالك.
S_IWUSR	وضع الملف الذي يشير إلى قابلية الكتابة من قبل المالك.
S_IXUSR	وضع الملف الذي يشير إلى قابلية التنفيذ من قبل المالك.
S_IRWXG	وضع الملف الذي يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل المجموعة.
S_IRGRP	وضع الملف الذي يشير إلى قابلية القراءة من قبل المجموعة.
S_IWGRP	وضع الملف الذي يشير إلى قابلية الكتابة من قبل المجموعة.
S_IXGRP	وضع الملف الذي يشير إلى قابلية التنفيذ من قبل المجموعة.
S_IRWXO	وضع الملف الذي يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل الآخرين.
S_IROTH	وضع الملف الذي يشير إلى قابلية القراءة من قبل الآخرين.
S_IWOTH	وضع الملف الذي يشير إلى قابلية الكتابة من قبل الآخرين.
S_IXOTH	وضع الملف الذي يشير إلى قابلية التنفيذ من قبل الآخرين.

في Windows، تتوفر فقط S_IRUSR و S_IWUSR.

ملاحظات

ترتيب العمليات القائمة على الـ callback والوعود

بسبب تنفيذها بشكل غير متزامن بواسطة تجمع الخيوط الأساسي، لا يوجد ترتيب مضمون عند استخدام طرق الـ callback أو القائمة على الوعود.

على سبيل المثال، ما يلي عرضة للخطأ لأن عملية fs.stat() قد تكتمل قبل عملية fs.rename() :

const fs = require('node:fs')

fs.rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  console.log('renamed complete')
})
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err
  console.log(`stats: ${JSON.stringify(stats)}`)
})

من المهم ترتيب العمليات بشكل صحيح عن طريق انتظار نتائج واحدة قبل استدعاء الأخرى:

ESM

import { rename, stat } from 'node:fs/promises'

const oldPath = '/tmp/hello'
const newPath = '/tmp/world'

try {
  await rename(oldPath, newPath)
  const stats = await stat(newPath)
  console.log(`stats: ${JSON.stringify(stats)}`)
} catch (error) {
  console.error('there was an error:', error.message)
}

CJS

const { rename, stat } = require('node:fs/promises')

;(async function (oldPath, newPath) {
  try {
    await rename(oldPath, newPath)
    const stats = await stat(newPath)
    console.log(`stats: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello', '/tmp/world')

أو، عند استخدام واجهات برمجة تطبيقات الـ callback، انقل مكالمة fs.stat() إلى دالة الـ callback الخاصة بعملية fs.rename() :

ESM

import { rename, stat } from 'node:fs'

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

CJS

const { rename, stat } = require('node:fs/promises')

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

مسارات الملفات

تقبل معظم عمليات fs مسارات الملفات التي يمكن تحديدها في شكل سلسلة، أو <Buffer>، أو كائن <URL> باستخدام بروتوكول file: .

مسارات السلسلة

يتم تفسير مسارات السلسلة على أنها تسلسلات أحرف UTF-8 تحدد اسم الملف المطلق أو النسبي. سيتم حل المسارات النسبية بالنسبة إلى دليل العمل الحالي كما هو محدد من خلال استدعاء process.cwd() .

مثال باستخدام مسار مطلق على POSIX:

import { open } from 'node:fs/promises'

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // القيام بشيء ما مع الملف
} finally {
  await fd?.close()
}

مثال باستخدام مسار نسبي على POSIX (نسبي لـ process.cwd()):

import { open } from 'node:fs/promises'

let fd
try {
  fd = await open('file.txt', 'r')
  // القيام بشيء ما مع الملف
} finally {
  await fd?.close()
}

مسارات عنوان URL للملف

تمت الإضافة في: v7.6.0

بالنسبة لمعظم وظائف وحدة node:fs، يمكن تمرير وسيطة path أو filename ككائن <URL> باستخدام بروتوكول file: .

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

عناوين URL من نوع file: هي دائمًا مسارات مطلقة.

اعتبارات خاصة بالمنصة

على نظام التشغيل Windows، يتم تحويل عناوين URL من نوع file: <URL> التي تحتوي على اسم مضيف إلى مسارات UNC، بينما يتم تحويل عناوين URL من نوع file: <URL> التي تحتوي على أحرف محركات الأقراص إلى مسارات مطلقة محلية. ستؤدي عناوين URL من نوع file: <URL> التي لا تحتوي على اسم مضيف ولا حرف محرك أقراص إلى حدوث خطأ:

import { readFileSync } from 'node:fs'
// على نظام التشغيل Windows:

// - عناوين URL الخاصة بملفات WHATWG التي تحتوي على اسم مضيف يتم تحويلها إلى مسار UNC
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - عناوين URL الخاصة بملفات WHATWG التي تحتوي على أحرف محركات أقراص يتم تحويلها إلى مسار مطلق
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - يجب أن تحتوي عناوين URL الخاصة بملفات WHATWG التي لا تحتوي على اسم مضيف على أحرف محركات أقراص
readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'))
readFileSync(new URL('file:///c/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: يجب أن يكون مسار عنوان URL الخاص بالملف مطلقًا

يجب أن تستخدم عناوين URL من نوع file: <URL> التي تحتوي على أحرف محركات أقراص : كفاصل مباشرة بعد حرف محرك الأقراص. سيؤدي استخدام فاصل آخر إلى حدوث خطأ.

على جميع المنصات الأخرى، لا يتم دعم عناوين URL من نوع file: <URL> التي تحتوي على اسم مضيف وستؤدي إلى حدوث خطأ:

import { readFileSync } from 'node:fs'
// على منصات أخرى:

// - لا يتم دعم عناوين URL الخاصة بملفات WHATWG التي تحتوي على اسم مضيف
// file://hostname/p/a/t/h/file => throw!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: يجب أن يكون مطلقًا

// - يتم تحويل عناوين URL الخاصة بملفات WHATWG إلى مسار مطلق
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

سيؤدي عنوان URL من نوع file: <URL> يحتوي على أحرف مائلة مائلة مشفرة إلى حدوث خطأ على جميع المنصات:

import { readFileSync } from 'node:fs'

// على نظام التشغيل Windows
readFileSync(new URL('file:///C:/p/a/t/h/%2F'))
readFileSync(new URL('file:///C:/p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: يجب ألا يتضمن مسار عنوان URL الخاص بالملف أحرف \ أو / مشفرة */

// على POSIX
readFileSync(new URL('file:///p/a/t/h/%2F'))
readFileSync(new URL('file:///p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: يجب ألا يتضمن مسار عنوان URL الخاص بالملف أحرف / مشفرة */

على نظام التشغيل Windows، ستؤدي عناوين URL من نوع file: <URL> التي تحتوي على شرطة مائلة عكسية مشفرة إلى حدوث خطأ:

import { readFileSync } from 'node:fs'

// على نظام التشغيل Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: يجب ألا يتضمن مسار عنوان URL الخاص بالملف أحرف \ أو / مشفرة */

مسارات المخزن المؤقت

تُعد المسارات المحددة باستخدام <Buffer> مفيدة بشكل أساسي على أنظمة تشغيل POSIX معينة تعامل مسارات الملفات كمتواليات بايت معتمة. على هذه الأنظمة، من الممكن أن يحتوي مسار ملف واحد على متواليات فرعية تستخدم ترميزات أحرف متعددة. كما هو الحال مع مسارات السلاسل، قد تكون مسارات <Buffer> نسبية أو مطلقة:

مثال باستخدام مسار مطلق على POSIX:

import { open } from 'node:fs/promises'
import { Buffer } from 'node:buffer'

let fd
try {
  fd = await open(Buffer.from('/open/some/file.txt'), 'r')
  // قم بفعل شيء ما مع الملف
} finally {
  await fd?.close()
}

أدلة العمل لكل محرك أقراص على Windows

على Windows، يتبع Node.js مفهوم دليل العمل لكل محرك أقراص. يمكن ملاحظة هذا السلوك عند استخدام مسار محرك أقراص بدون شرطة مائلة عكسية. على سبيل المثال، قد يُعيد fs.readdirSync('C:\\') نتيجة مختلفة عن fs.readdirSync('C:'). لمزيد من المعلومات، راجع صفحة MSDN هذه.

مُعرّفات الملفات

على أنظمة POSIX، لكل عملية، تُحافظ النواة على جدول بالملفات والموارد المفتوحة حاليًا. يتم تعيين مُعرّف رقمي بسيط يسمى مُعرّف الملف لكل ملف مفتوح. على مستوى النظام، تستخدم جميع عمليات نظام الملفات هذه المُعرّفات لتحديد وتتبع كل ملف محدد. تستخدم أنظمة Windows آلية مختلفة ولكنها متشابهة من الناحية المفاهيمية لتتبع الموارد. لتبسيط الأمور على المستخدمين، يُخفي Node.js الاختلافات بين أنظمة التشغيل ويُعيّن لجميع الملفات المفتوحة مُعرّف ملف رقمي.

تقوم الطريقتان القائمتان على المُنعطف العكسي fs.open()، والطريقة المُزامنة fs.openSync() بفتح ملف وتخصيص مُعرّف ملف جديد. بمجرد التخصيص، يمكن استخدام مُعرّف الملف لقراءة البيانات من، أو كتابة البيانات إلى، أو طلب معلومات حول الملف.

تحد أنظمة التشغيل عدد مُعرّفات الملفات التي قد تكون مفتوحة في أي وقت مُحدد، لذلك من المهم إغلاق المُعرّف عند اكتمال العمليات. سيؤدي الفشل في القيام بذلك إلى حدوث تسرب للذاكرة سيؤدي في النهاية إلى تعطل التطبيق.

import { open, close, fstat } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err
  try {
    fstat(fd, (err, stat) => {
      if (err) {
        closeFd(fd)
        throw err
      }

      // استخدم stat

      closeFd(fd)
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

تستخدم واجهات برمجة التطبيقات القائمة على الوعود كائن <FileHandle> بدلاً من مُعرّف الملف الرقمي. يتم إدارة هذه الكائنات بشكل أفضل بواسطة النظام لضمان عدم تسرب الموارد. ومع ذلك، لا يزال من المطلوب إغلاقها عند اكتمال العمليات:

import { open } from 'node:fs/promises'

let file
try {
  file = await open('/open/some/file.txt', 'r')
  const stat = await file.stat()
  // استخدم stat
} finally {
  await file.close()
}

استخدام تجمع مؤشرات الترابط

تستخدم جميع واجهات برمجة التطبيقات القائمة على المُستدعيات والوعود لنظام الملفات (باستثناء fs.FSWatcher()) تجمع مؤشرات الترابط في libuv. قد يكون لهذا آثار سلبية ومفاجئة على الأداء بالنسبة لبعض التطبيقات. راجع وثائق UV_THREADPOOL_SIZE لمزيد من المعلومات.

علامات نظام الملفات

تتوفر علامات النظام التالية أينما كان خيار flag يأخذ سلسلة.

• 'a': فتح الملف للإضافة. يتم إنشاء الملف إذا لم يكن موجودًا.
• 'ax': مثل 'a' لكنه يفشل إذا كان المسار موجودًا.
• 'a+': فتح الملف للقراءة والإضافة. يتم إنشاء الملف إذا لم يكن موجودًا.
• 'ax+': مثل 'a+' لكنه يفشل إذا كان المسار موجودًا.
• 'as': فتح الملف للإضافة في الوضع المتزامن. يتم إنشاء الملف إذا لم يكن موجودًا.
• 'as+': فتح الملف للقراءة والإضافة في الوضع المتزامن. يتم إنشاء الملف إذا لم يكن موجودًا.
• 'r': فتح الملف للقراءة. يحدث استثناء إذا لم يكن الملف موجودًا.
• 'rs': فتح الملف للقراءة في الوضع المتزامن. يحدث استثناء إذا لم يكن الملف موجودًا.
• 'r+': فتح الملف للقراءة والكتابة. يحدث استثناء إذا لم يكن الملف موجودًا.
• 'rs+': فتح الملف للقراءة والكتابة في الوضع المتزامن. يُرشد نظام التشغيل على تجاوز ذاكرة التخزين المؤقت لنظام الملفات المحلي. هذا مفيد بشكل أساسي لفتح الملفات على وحدات التخزين NFS لأنه يسمح بتخطي ذاكرة التخزين المؤقت المحلية التي قد تكون قديمة. له تأثير حقيقي جدًا على أداء الإدخال/الإخراج، لذلك لا يُوصى باستخدام هذه العلامة إلا إذا لزم الأمر. هذا لا يحوّل fs.open() أو fsPromises.open() إلى مُكالمة حجب متزامنة. إذا رغبت في العملية المتزامنة، فيجب استخدام شيء مثل fs.openSync().
• 'w': فتح الملف للكتابة. يتم إنشاء الملف (إذا لم يكن موجودًا) أو اقتطاعه (إذا كان موجودًا).
• 'wx': مثل 'w' لكنه يفشل إذا كان المسار موجودًا.
• 'w+': فتح الملف للقراءة والكتابة. يتم إنشاء الملف (إذا لم يكن موجودًا) أو اقتطاعه (إذا كان موجودًا).
• 'wx+': مثل 'w+' لكنه يفشل إذا كان المسار موجودًا.

يمكن أن يكون flag أيضًا رقمًا كما هو موثق بواسطة open(2)؛ تتوفر الثوابت المستخدمة بشكل شائع من fs.constants. على نظام Windows، يتم ترجمة العلامات إلى ما يعادلها حيثما ينطبق ذلك، مثل O_WRONLY إلى FILE_GENERIC_WRITE، أو O_EXCL|O_CREAT إلى CREATE_NEW، كما تقبله CreateFileW.

تتسبب علامة الحصر 'x' (علامة O_EXCL في open(2)) في أن تُرجع العملية خطأً إذا كان المسار موجودًا بالفعل. على POSIX، إذا كان المسار عبارة عن ارتباط رمزي، فإن استخدام O_EXCL يُرجع خطأً حتى لو كان الرابط لمسار غير موجود. قد لا تعمل علامة الحصر مع أنظمة ملفات الشبكة.

على نظام Linux، لا تعمل عمليات الكتابة الموضعية عندما يتم فتح الملف في وضع الإضافة. يتجاهل kernel وسيطة الموقع ويضيف البيانات دائمًا إلى نهاية الملف.

قد يتطلب تعديل ملف بدلاً من استبداله تعيين خيار flag على 'r+' بدلاً من الافتراضي 'w'.

سلوك بعض العلامات محدد بنظام التشغيل. على هذا النحو، فإن فتح دليل على macOS وLinux باستخدام علامة 'a+'، كما في المثال أدناه، سيُرجع خطأً. على النقيض من ذلك، على Windows وFreeBSD، سيتم إرجاع مُعرّف ملف أو FileHandle.

// macOS وLinux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: عملية غير قانونية على دليل، فتح <directory>]
})

// Windows وFreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
})

على نظام Windows، سيؤدي فتح ملف مخفي موجود باستخدام علامة 'w' (إما من خلال fs.open()، أو fs.writeFile()، أو fsPromises.open()) إلى الفشل مع EPERM. يمكن فتح الملفات المخفية الموجودة للكتابة باستخدام علامة 'r+'.

يمكن استخدام مُكالمة إلى fs.ftruncate() أو filehandle.truncate() لإعادة تعيين محتويات الملف.