نظام الملفات

[مستقر: 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 (ESM).

مثال الوعد

تُرجع العمليات المستندة إلى الوعد وعدًا يتم تنفيذه عند اكتمال العملية غير المتزامنة.

ESM

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

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}

CJS

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

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');

مثال معاودة الاتصال

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

ESM

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

CJS

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

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /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) {
  // معالجة الخطأ
}

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

[التاريخ]

الإصدار	التغييرات
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>s.

إذا لم يتم إغلاق <FileHandle> باستخدام طريقة filehandle.close()، فسوف يحاول إغلاق واصف الملف تلقائيًا وإصدار تحذير العملية، مما يساعد على منع تسرب الذاكرة. يرجى عدم الاعتماد على هذا السلوك لأنه قد يكون غير موثوق به وقد لا يتم إغلاق الملف. بدلاً من ذلك، قم دائمًا بإغلاق <FileHandle>s بشكل صريح. قد يغير 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');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  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])

[السجل]

الإصدار	التغييرات
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 عند النجاح.

يجبر جميع عمليات الإدخال/الإخراج (I/O) المنتظرة حاليًا المرتبطة بالملف على حالة إكمال الإدخال/الإخراج المتزامنة لنظام التشغيل. راجع وثائق 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])

[السجل]

الإصدار	التغييرات
الإصدار 21.0.0	يقبل قيم bigint كـ position.
الإصداران 13.11.0، 12.17.0	تمت إضافته في: الإصدار 13.11.0، 12.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	تمت إضافة خيار لإنشاء تدفق 'bytes'.
الإصدار v17.0.0	تمت الإضافة في: الإصدار v17.0.0

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

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

• options <الكائن>

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

• إرجاع: <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 <الكائن> | <سلسلة>

  • encoding <سلسلة> | <فارغ> الافتراضي: فارغ
  • 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 <الكائن>

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

• الإرجاع: <وعد> يتم تنفيذه باستخدام <fs.Stats> للملف.

filehandle.sync()

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

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

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

filehandle.truncate(len)

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

• len <عدد صحيح> الافتراضي: 0
• الإرجاع: <وعد> يتم تنفيذه مع 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().

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

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 عبارة عن number، فسيتم كتابة البيانات في الموضع الحالي. راجع وثائق POSIX pwrite(2) لمزيد من التفاصيل. الافتراضي: null
• encoding <string> ترميز السلسلة النصية المتوقع. الافتراضي: 'utf8'
• الإرجاع: <Promise>

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

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

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

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

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

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 <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

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

• الإرجاع: <Promise>

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

إذا كانت 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، الكتابات الموضعية لا تعمل عند فتح الملف في وضع الإلحاق. تتجاهل النواة وسيطة الموضع وتلحق دائمًا البيانات بنهاية الملف.

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])

[History]

Version	Changes
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> مسار الوجهة المراد النسخ إليها.

  • Returns: <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

• Returns: <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 <سلسلة نصية> | <سلسلة نصية[]>

• options <كائن>

  • cwd <سلسلة نصية> دليل العمل الحالي. الافتراضي: process.cwd()
  • exclude <دالة> دالة لتصفية الملفات/المجلدات. تُرجع true لاستبعاد العنصر، و false لتضمينه. الافتراضي: undefined.
  • withFileTypes <منطقي> 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 <سلسلة نصية> | <Buffer> | <URL>
• mode <عدد صحيح>
• الإرجاع: <Promise> يفي بـ undefined عند النجاح.

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

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

fsPromises.lchown(path, uid, gid)

[السجل]

الإصدار	التغييرات
v10.6.0	لم تعد واجهة برمجة التطبيقات هذه مهملة.
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> لمسار الارتباط الرمزي المحدد path.

يعادل 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.

• Returns: <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])

[السجل]

الإصدار	التغييرات
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. يمكن لبعض الأنظمة الأساسية، ولا سيما BSDs، إرجاع أكثر من ستة أحرف عشوائية، واستبدال الأحرف 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])

[السجل]

الإصدار	التغييرات
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) لمزيد من التفاصيل.

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

fsPromises.opendir(path[, options])

[السجل]

الإصدار	التغييرات
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])

[التاريخ]

الإصدار	التغييرات
الإصدار 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> انظر دعم flags نظام الملفات. الافتراضي: 'r'.
  • signal <AbortSignal> يسمح بإلغاء readFile قيد التقدم

• الإرجاع: <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 });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an 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)

تمت الإضافة في: الإصدار 10.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	تمت الإضافة في: الإصدار 10.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.

للحصول على سلوك مشابه لأمر Unix 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 هذه القواعد:

• يمكن أن تكون القيم إما أرقامًا تمثل وقت Unix epoch، أو Dates، أو سلسلة رقمية مثل '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])

[السجل]

الإصدار	التغييرات
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 });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
}

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

fsPromises.constants

أُضيف في: v18.4.0, v16.17.0

• <Object>

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

واجهة برمجة تطبيقات الاستدعاء (Callback API)

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

تستخدم واجهات برمجة تطبيقات الاستدعاء مجموعة مؤشرات ترابط 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 كائن WHATWG URL باستخدام بروتوكول 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 ? 'غير موجود' : 'موجود'}`);
});

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

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

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

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

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

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

access('myfile', (err) => {
  if (!err) {
    console.error('myfile موجود بالفعل');
    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 موجود بالفعل');
      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 غير موجود');
      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 غير موجود');
      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> انظر دعم أعلام نظام الملفات. الافتراضي: '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('The "data to append" was appended to file!');
});

إذا كان 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 كائن URL من نوع WHATWG باستخدام بروتوكول file:.
v7.0.0	لم يعد المعامل callback اختياريًا. عدم تمريره سيؤدي إلى إصدار تحذير إهمال مع المعرّف DEP0013.
v0.1.30	تمت إضافته في: v0.1.30

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

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

راجع وثائق 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)

[السجل]

الإصدار	التغييرات
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])

[السجل]

الإصدار	التغييرات
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)

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

الإصدار	التغييرات
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: ستحاول عملية النسخ إنشاء إعادة ربط نسخ عند الكتابة. إذا كانت المنصة لا تدعم النسخ عند الكتابة، فسيتم استخدام آلية نسخ احتياطية.
• fs.constants.COPYFILE_FICLONE_FORCE: ستحاول عملية النسخ إنشاء إعادة ربط نسخ عند الكتابة. إذا كانت المنصة لا تدعم النسخ عند الكتابة، فسوف تفشل العملية.

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	هذا الـ API لم يعد تجريبيًا.
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> الكتابة فوق ملف أو مجلد موجود. ستتجاهل عملية النسخ الأخطاء إذا قمت بتعيين هذا إلى خطأ وكانت الوجهة موجودة. استخدم خيار 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])

[السجل]

الإصدار	التغييرات
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 كائن WHATWG URL باستخدام بروتوكول file:.
v7.0.0	لن يتم تعديل كائن options الذي تم تمريره أبدًا.
v2.3.0	يمكن أن يكون كائن options الذي تم تمريره عبارة عن سلسلة الآن.
v0.1.31	تمت إضافته في: v0.1.31

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

• options <string> | <Object>

  • flags <string> انظر دعم علامات نظام الملفات. الافتراضي: '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

• Returns: <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 حاصراً; يجب تمرير fds غير الحاصرة إلى <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 <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> انظر دعم أعلام نظام الملفات. الافتراضي: 'w'.
  • encoding <string> الافتراضي: 'utf8'
  • fd <integer> | <FileHandle> الافتراضي: null
  • mode <integer> الافتراضي: 0o666
  • autoClose <boolean> الافتراضي: true
  • emitClose <boolean> الافتراضي: true
  • start <integer>
  • fs <Object> | <null> الافتراضي: null
  • signal <AbortSignal> | <null> الافتراضي: null
  • highWaterMark <number> الافتراضي: 16384
  • flush <boolean> إذا كانت true، فسيتم تفريغ واصف الملف الأساسي قبل إغلاقه. الافتراضي: false.

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

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

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

بشكل افتراضي، سيصدر الدفق حدث '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 كائن URL من WHATWG باستخدام بروتوكول file:.
الإصدار v1.0.0	تم الإلغاء منذ: الإصدار v1.0.0
الإصدار v0.0.2	تمت الإضافة في: الإصدار v0.0.2

[مستقر: 0 - تم الإلغاء]

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

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

اختبر ما إذا كان العنصر في 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(). القيام بذلك يقدم حالة تسابق، حيث قد تغير العمليات الأخرى حالة الملف بين الاستدعاءين. بدلاً من ذلك، يجب على كود المستخدم فتح/قراءة/كتابة الملف مباشرة والتعامل مع الخطأ الذي يثار إذا كان الملف غير موجود.

write (غير موصى به)

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;
        });
      }
    });
  }
});

write (موصى به)

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;
    });
  }
});

read (غير موصى به)

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');
  }
});

read (موصى به)

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)

[السجل]

الإصدار	التغييرات
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 <عدد صحيح>
• mode <سلسلة> | <عدد صحيح>
• callback <دالة>
  • err <خطأ>

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

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

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

[السجل]

الإصدار	التغييرات
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 <عدد صحيح>
• uid <عدد صحيح>
• gid <عدد صحيح>
• callback <دالة>
  • err <خطأ>

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

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

fs.fdatasync(fd, callback)

[السجل]

الإصدار	التغييرات
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 <عدد صحيح>
• callback <دالة>
  • err <خطأ>

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

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

[السجل]

الإصدار	التغييرات
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 <عدد صحيح>

• options <كائن>

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

• callback <دالة>

  • err <خطأ>
  • stats <fs.Stats>

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

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

fs.fsync(fd, callback)

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

الإصدار	التغييرات
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 <عدد صحيح>
• callback <دالة>
  • err <خطأ>

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

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

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

الإصدار	التغييرات
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 <عدد صحيح>
• len <عدد صحيح> افتراضي: 0
• callback <دالة>
  • err <خطأ>

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

راجع وثائق 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)

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

الإصدار	التغييرات
الإصدار 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)

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

الإصدار	التغييرات
الإصدار 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)

[السجل]

الإصدار	التغييرات
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)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير رد نداء غير صالح إلى وسيطة callback يؤدي الآن إلى إطلاق ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v10.0.0	لم يعد المعامل callback اختياريًا. عدم تمريره سيؤدي إلى إطلاق TypeError في وقت التشغيل.
v7.6.0	يمكن أن تكون المعلمات existingPath و newPath كائنات URL لـ WHATWG باستخدام بروتوكول 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)

[السجل]

الإصدار	التغييرات
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)

[السجل]

الإصدار	التغييرات
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 كائن WHATWG URL باستخدام بروتوكول 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)

[التاريخ]

الإصدار	التغييرات
الإصدار 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>

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

يتم إنشاء ستة أحرف عشوائية لإضافتها خلف prefix مطلوب لإنشاء دليل مؤقت فريد. نظرًا للاختلافات في الأنظمة الأساسية، تجنب الأحرف 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);
  // Prints: /tmp/foo-itXde2 or 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)

[السجل]

الإصدار	التغييرات
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 كائن WHATWG URL باستخدام بروتوكول file:.
v0.0.2	تمت الإضافة في: v0.0.2

• path <string> | <Buffer> | <URL>
• flags <string> | <number> انظر دعم flags لنظام الملفات. الافتراضي: '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).

• Returns: <Promise> يتحقق مع <Blob> عند النجاح.

يُرجع <Blob> تكون بياناته مدعومة بالملف المحدد.

يجب عدم تعديل الملف بعد إنشاء <Blob>. أي تعديلات ستتسبب في فشل قراءة بيانات <Blob> مع ظهور خطأ DOMException. يتم إجراء عمليات stat متزامنة على الملف عند إنشاء 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 <Buffer> | <TypedArray> | <DataView> المخزن المؤقت الذي ستُكتب البيانات إليه.
• offset <عدد صحيح> الموضع في buffer لكتابة البيانات إليه.
• length <عدد صحيح> عدد البايتات المراد قراءتها.
• position <عدد صحيح> | <bigint> | <null> يحدد مكان البدء في القراءة من الملف. إذا كان position هو null أو -1، فستُقرأ البيانات من موضع الملف الحالي، وسيُحدَّث موضع الملف. إذا كان position عددًا صحيحًا غير سالب، فسيظل موضع الملف دون تغيير.
• callback <الدالة>
  • err <خطأ>
  • bytesRead <عدد صحيح>
  • buffer <Buffer>

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

تتلقى دالة رد النداء ثلاثة وسائط، (err, bytesRead, buffer).

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

إذا استُدعي هذا الأسلوب كإصدار util.promisify()ed الخاص به، فإنه يُرجع وعدًا بـ Object مع خصائص bytesRead و buffer.

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

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

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

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

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

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

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

الإصدار	التغييرات
الإصدار 13.11.0، الإصدار 12.17.0	يمكن تمرير كائن الخيارات لجعل المخزن المؤقت والإزاحة والطول والموضع اختياريين.
الإصدار 13.11.0، الإصدار 12.17.0	تمت الإضافة في: الإصدار 13.11.0، الإصدار 12.17.0

• fd <عدد صحيح>

• options <كائن>

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

• callback <دالة>

  • err <خطأ>
  • bytesRead <عدد صحيح>
  • 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 كائن WHATWG URL باستخدام بروتوكول 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	قد تتضمن وسيطة options كائن 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 <string> | <Buffer> | <URL> | <integer> اسم الملف أو واصف الملف

• options <Object> | <string>

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

• callback <Function>

  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

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

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: illegal operation on a directory, read <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) => {
  // ...
});
// When you want to abort the request
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 كائن WHATWG URL باستخدام بروتوكول file:.
v7.0.0	لم تعد معلمة callback اختيارية. سيؤدي عدم تمريرها إلى إصدار تحذير إهمال مع المعرف DEP0013.
v0.1.31	تمت الإضافة في: v0.1.31

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

• options <string> | <Object>

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

• callback <Function>

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

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

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

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

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

[السجل]

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

• fd <عدد صحيح>
• buffers <ArrayBufferView[]>
• position <عدد صحيح> | <null> الافتراضي: null
• callback <دالة>
  • err <خطأ>
  • bytesRead <عدد صحيح>
  • buffers <ArrayBufferView[]>

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

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

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

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

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

[السجل]

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

• path <سلسلة> | <Buffer> | <URL>

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

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

• callback <دالة>

  • err <خطأ>
  • resolvedPath <سلسلة> | <Buffer>

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

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

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

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

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

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

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

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

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

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

الإصدار	التغييرات
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)

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

الإصدار	التغييرات
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)

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

الإصدار	التغييرات
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 كائن URL WHATWG باستخدام بروتوكول 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.

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

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

[سجل التعديلات]

الإصدار	التغييرات
الإصدار v17.3.0, v16.14.0	يمكن أن يكون المعامل path كائن URL من نوع WHATWG باستخدام البروتوكول 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)

[السجل]

الإصدار	التغييرات
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.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)

[السجل]

الإصدار	التغييرات
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)

[السجل]

الإصدار	التغييرات
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 تم اقتطاعه');
});

CJS

const { truncate } = require('node:fs');
// بافتراض أن 'path/file.txt' هو ملف عادي.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt تم اقتطاعه');
});

تمرير واصف ملف مهمل وقد يؤدي إلى إطلاق خطأ في المستقبل.

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

fs.unlink(path, 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.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');
});

لن يعمل 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)

[السجل]

الإصدار	التغييرات
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 كائن WHATWG URL باستخدام بروتوكول 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 هذه القواعد:

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

fs.watch(filename[, options][, listener])

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

الإصدار	التغييرات
v19.1.0	تمت إضافة دعم تكراري لنظام التشغيل Linux و AIX و IBMi.
v15.9.0, v14.17.0	تمت إضافة دعم لإغلاق المراقب باستخدام AbortSignal.
v7.6.0	يمكن أن يكون المعامل filename كائن WHATWG URL باستخدام بروتوكول 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>

• Returns: <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()، الذي يستخدم استطلاع الرأي stat، ولكن هذه الطريقة أبطأ وأقل موثوقية.

Inodes

في أنظمة Linux و macOS، تحل fs.watch() المسار إلى inode وتراقب inode. إذا تم حذف المسار الذي تتم مراقبته وإعادة إنشائه، فسيتم تعيين inode جديد له. ستصدر المراقبة حدثًا للحذف ولكنها ستستمر في مراقبة inode الأصلي. لن يتم إصدار أحداث لـ inode الجديد. هذا هو السلوك المتوقع.

تحتفظ ملفات AIX بنفس inode طوال فترة بقاء الملف. سيؤدي حفظ وإغلاق ملف تتم مراقبته على AIX إلى ظهور إشعارين (أحدهما لإضافة محتوى جديد، والآخر للاقتطاع).

وسيط اسم الملف

توفير وسيط filename في الاستدعاء مدعوم فقط على Linux و macOS و Windows و AIX. حتى على المنصات المدعومة، ليس من المضمون دائمًا توفير filename. لذلك، لا تفترض أنه يتم توفير وسيط filename دائمًا في الاستدعاء، واحتفظ ببعض المنطق الاحتياطي إذا كان null.

import { watch } from 'node:fs';
watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`);
  if (filename) {
    console.log(`filename provided: ${filename}`);
  } else {
    console.log('filename not provided');
  }
});

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(`the current mtime is: ${curr.mtime}`);
  console.log(`the previous mtime was: ${prev.mtime}`);
});

تعد كائنات الحالة هذه مثيلات لـ fs.Stat. إذا كان خيار bigint هو true، فسيتم تحديد القيم الرقمية في هذه الكائنات على أنها BigInts.

لكي يتم إعلامك عندما تم تعديل الملف، وليس مجرد الوصول إليه، من الضروري مقارنة curr.mtimeMs و prev.mtimeMs.

عندما تؤدي عملية fs.watchFile إلى خطأ ENOENT، فسيتم استدعاء المستمع مرة واحدة، مع تصفير جميع الحقول (أو، بالنسبة للتواريخ، Epoch Unix). إذا تم إنشاء الملف لاحقًا، فسيتم استدعاء المستمع مرة أخرى، مع أحدث كائنات الحالة. هذا تغيير في الوظائف منذ الإصدار 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 <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> افتراضي: 0
• length <integer> افتراضي: buffer.byteLength - offset
• position <integer> | <null> افتراضي: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

اكتب buffer إلى الملف المحدد بواسطة fd.

يحدد offset جزءًا من المخزن المؤقت المراد كتابته، و length هو عدد صحيح يحدد عدد البايتات المراد كتابتها.

يشير position إلى الإزاحة من بداية الملف حيث يجب كتابة هذه البيانات. إذا كان typeof position !== 'number'، فسيتم كتابة البيانات في الموضع الحالي. راجع pwrite(2).

سيتم إعطاء رد النداء ثلاث وسيطات (err, bytesWritten, buffer) حيث تحدد bytesWritten عدد البايتات التي تمت كتابتها من buffer.

إذا تم استدعاء هذه الطريقة كإصدار util.promisify()ed الخاص بها، فستعيد وعدًا بـ Object مع خصائص bytesWritten و buffer.

من غير الآمن استخدام fs.write() عدة مرات في نفس الملف دون انتظار رد النداء. لهذا السيناريو، يوصى باستخدام fs.createWriteStream().

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

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 هو ترميز السلسلة المتوقع.

سيتلقى الاستدعاء الوسيطات (err, written, string) حيث تحدد written عدد البايتات التي تطلبتها السلسلة التي تم تمريرها للكتابة. البايتات المكتوبة ليست بالضرورة هي نفسها الأحرف المكتوبة في السلسلة. راجع Buffer.byteLength.

من غير الآمن استخدام fs.write() عدة مرات على نفس الملف دون انتظار الاستدعاء. لهذا السيناريو، يوصى باستخدام fs.createWriteStream().

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

في نظام 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> انظر دعم نظام الملفات flags. الافتراضي: '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('The file has been saved!');
});

إذا كانت 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> الافتراضي: null
• callback <Function>
  • err <Error>
  • bytesWritten <عدد صحيح>
  • buffers <ArrayBufferView[]>

اكتب مجموعة من ArrayBufferView إلى الملف المحدد بواسطة fd باستخدام writev().

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

سيتم إعطاء رد الاتصال ثلاث وسائط: err و bytesWritten و buffers. bytesWritten هو عدد البايتات التي تمت كتابتها من buffers.

إذا كانت هذه الطريقة util.promisify()ed، فإنها تُرجع وعدًا لـ Object مع خصائص bytesWritten و buffers.

من غير الآمن استخدام fs.writev() عدة مرات على نفس الملف دون انتظار رد الاتصال. لهذا السيناريو، استخدم fs.createWriteStream().

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

واجهة برمجة التطبيقات المتزامنة

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

fs.accessSync(path[, mode])

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

الإصدار	التغييرات
v7.6.0	يمكن أن يكون المعامل path كائن URL من نوع WHATWG باستخدام بروتوكول file:.
v0.11.15	تمت إضافته في: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> الافتراضي: 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 <string> | <Buffer> | <URL> | <number> اسم الملف أو واصف الملف
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> الافتراضي: 'utf8'
  • mode <integer> الافتراضي: 0o666
  • flag <string> انظر [دعم علامات نظام الملفات`](/ar/api/fs#file-system-flags). الافتراضي: `'a'`.
  • flush <boolean> إذا كانت true، فسيتم تفريغ واصف الملف الأساسي قبل إغلاقه. الافتراضي: false.

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

يؤثر الخيار 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)

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون المعامل path كائن URL الخاص بـ WHATWG باستخدام البروتوكول file:.
v0.6.7	أُضيف في: v0.6.7

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

للحصول على معلومات مفصلة، راجع الوثائق الخاصة بالإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: fs.chmod().

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

fs.chownSync(path, uid, gid)

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون المعامل path كائن URL الخاص بـ WHATWG باستخدام البروتوكول 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])

[السجل]

الإصدار	التغييرات
الإصدار 14.0.0	تم تغيير وسيطة flags إلى mode وفرض التحقق الأكثر صرامة من النوع.
الإصدار 8.5.0	تمت الإضافة في: الإصدار 8.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: ستحاول عملية النسخ إنشاء إعادة ارتباط نسخ عند الكتابة. إذا كانت المنصة لا تدعم النسخ عند الكتابة، فسيتم استخدام آلية نسخ احتياطية.
• fs.constants.COPYFILE_FICLONE_FORCE: ستحاول عملية النسخ إنشاء إعادة ارتباط نسخ عند الكتابة. إذا كانت المنصة لا تدعم النسخ عند الكتابة، فسوف تفشل العملية.

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])

[السجل]

الإصدار	التغييرات
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> مسار الوجهة المراد النسخ إليه.

  • Returns: <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، بما في ذلك الدلائل الفرعية والملفات.

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

fs.existsSync(path)

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

الإصدار	التغييرات
v7.6.0	يمكن أن يكون المعامل path كائن URL الخاص بـ WHATWG باستخدام بروتوكول file:.
v0.1.21	أُضيف في: v0.1.21

• path <string> | <Buffer> | <URL>
• الإرجاع: <boolean>

إرجاع true إذا كان المسار موجودًا، وإلا false.

للحصول على معلومات مفصلة، راجع الوثائق الخاصة بالإصدار غير المتزامن من هذا API: fs.exists().

fs.exists() مهمل، لكن fs.existsSync() ليس كذلك. يقبل المعامل callback في fs.exists() معلمات غير متوافقة مع استدعاءات Node.js الأخرى. لا تستخدم fs.existsSync() استدعاءً.

import { existsSync } from 'node:fs';

if (existsSync('/etc/passwd'))
  console.log('المسار موجود.');

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 ‏<عدد صحيح>

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

‏fs.fstatSync(fd[, options])

[السجل]

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

• ‏fd ‏<عدد صحيح>

• ‏options ‏<كائن>

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

• تُرجع: ‏<fs.Stats>

تسترجع ‏<fs.Stats> لواصف الملف.

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

‏fs.fsyncSync(fd)

تمت إضافتها في: الإصدار v0.1.96

• ‏fd ‏<عدد صحيح>

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

‏fs.ftruncateSync(fd[, len])

تمت إضافتها في: الإصدار v0.8.6

• ‏fd ‏<عدد صحيح>
• ‏len ‏<عدد صحيح> ‏الافتراضي: ‏0

تقتطع واصف الملف. تُرجع غير مُعرَّفة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: ‏fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[سجل التعديلات]

الإصدار	التغييرات
v4.1.0	تم السماح الآن باستخدام السلاسل الرقمية و NaN و Infinity كمحددات للوقت.
v0.4.2	تمت الإضافة في: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

الإصدار المتزامن من fs.futimes(). تقوم بإرجاع undefined.

fs.globSync(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.

• تُرجع: <string[]> مسارات الملفات التي تطابق النمط.

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>

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

هذه الطريقة مُطبقة فقط على نظام التشغيل macOS.

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

fs.lchownSync(path, uid, gid)

[السجل]

الإصدار	التغييرات
v10.6.0	لم تعد واجهة برمجة التطبيقات هذه مهملة.
v0.4.7	الإهمال خاص بالتوثيق فقط.

• path <string> | <Buffer> | <URL>
• uid <integer> معرّف المستخدم لمالك الملف الجديد.
• gid <integer> معرّف المجموعة لمجموعة الملف الجديدة.

تعيين المالك للمسار. يُرجع غير معرّف.

راجع توثيق 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. يُرجع غير معرّف، أو يطرح استثناءً عندما تكون المعلمات غير صحيحة أو تفشل العملية. هذا هو الإصدار المتزامن من fs.lutimes().

fs.linkSync(existingPath, newPath)

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

الإصدار	التغييرات
v7.6.0	يمكن أن تكون المعلمات existingPath و newPath كائنات URL من WHATWG باستخدام بروتوكول 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])

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

الإصدار	التغييرات
v15.3.0, v14.17.0	يقبل خيار throwIfNoEntry لتحديد ما إذا كان سيتم طرح استثناء إذا لم يكن الإدخال موجودًا.
v10.5.0	يقبل كائن options إضافي لتحديد ما إذا كانت القيم الرقمية التي تم إرجاعها يجب أن تكون bigint.
v7.6.0	يمكن أن تكون المعلمة path كائن URL من WHATWG باستخدام بروتوكول 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])

[السجل]

الإصدار	التغييرات
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])

[السجل]

الإصدار	التغييرات
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])

[السجل]

الإصدار	التغييرات
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]])

[السجل]

الإصدار	التغييرات
v11.1.0	الوسيطة flags اختيارية الآن وتأخذ القيمة الافتراضية 'r'.
v9.9.0	يتم الآن دعم العلامات as و as+.
v7.6.0	يمكن أن يكون المعامل path كائن WHATWG URL باستخدام بروتوكول file:.
v0.1.21	تمت إضافته في: v0.1.21

• path <string> | <Buffer> | <URL>
• flags <string> | <number> الافتراضي: 'r'. انظر دعم flags نظام الملفات.
• 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.

• Returns: <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 كائن WHATWG URL باستخدام البروتوكول 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> انظر دعم نظام الملفات flags. الافتراضي: 'r'.

• Returns: <string> | <Buffer>

إرجاع محتويات path.

للحصول على معلومات مفصلة، راجع توثيق الإصدار غير المتزامن من هذا الـ API: fs.readFile().

إذا تم تحديد خيار encoding، فإن هذه الدالة ترجع سلسلة نصية. وإلا فإنها ترجع buffer.

على غرار fs.readFile()، عندما يكون المسار عبارة عن دليل، فإن سلوك fs.readFileSync() خاص بالنظام الأساسي.

import { readFileSync } from 'node:fs';

// macOS, Linux, و Windows
readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

//  FreeBSD
readFileSync('<directory>'); // => <data>

fs.readlinkSync(path[, options])

[السجل]

الإصدار	التغييرات
v7.6.0	يمكن أن يكون المعامل path كائن URL لـ WHATWG باستخدام بروتوكول 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])

[السجل]

الإصدار	التغييرات
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.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: fs.read().

fs.readSync(fd, buffer[, options])

[السجل]

الإصدار	التغييرات
v13.13.0, v12.17.0	يمكن تمرير كائن الخيارات لجعل الإزاحة والطول والموضع اختيارية.
v13.13.0, v12.17.0	تمت إضافتها في: v13.13.0, v12.17.0

• fd <عدد صحيح>

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

• options <كائن>

  • offset <عدد صحيح> الافتراضي: 0
  • length <عدد صحيح> الافتراضي: buffer.byteLength - offset
  • position <عدد صحيح> | <bigint> | <null> الافتراضي: null

• الإرجاع: <عدد>

إرجاع عدد bytesRead.

على غرار دالة fs.readSync المذكورة أعلاه، تأخذ هذه النسخة كائن options اختياري. إذا لم يتم تحديد كائن options، فسيتم الافتراض بالقيم المذكورة أعلاه.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن لواجهة برمجة التطبيقات هذه: fs.read().

fs.readvSync(fd, buffers[, position])

تمت إضافتها في: v13.13.0, v12.17.0

• fd <عدد صحيح>
• buffers <ArrayBufferView[]>
• position <عدد صحيح> | <null> الافتراضي: null
• الإرجاع: <عدد> عدد البايتات التي تمت قراءتها.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن لواجهة برمجة التطبيقات هذه: fs.readv().

fs.realpathSync(path[, options])

[التاريخ]

الإصدار	التغييرات
v8.0.0	تمت إضافة دعم تحليل الأنابيب/المقبس.
v7.6.0	يمكن أن يكون المعامل path كائن URL الخاص بـ WHATWG باستخدام بروتوكول 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>

إرجاع اسم المسار الذي تم تحليله.

للحصول على معلومات تفصيلية، راجع وثائق الإصدار غير المتزامن لواجهة برمجة التطبيقات هذه: 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 كائنات URL WHATWG باستخدام بروتوكول file:. الدعم حاليًا لا يزال تجريبيًا.
v0.1.21	تمت الإضافة في: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <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 كائن URL WHATWG باستخدام بروتوكول file:.
v0.1.21	تمت الإضافة في: v0.1.21

• 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.

rmdir(2) متزامن. يُرجع undefined.

يؤدي استخدام fs.rmdirSync() على ملف (وليس دليل) إلى حدوث خطأ ENOENT على نظام التشغيل Windows وخطأ ENOTDIR على نظام التشغيل POSIX.

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

fs.rmSync(path[, options])

[السجل]

الإصدار	التغييرات
v17.3.0, v16.14.0	يمكن أن يكون المعامل path كائن URL من WHATWG باستخدام بروتوكول 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.

يزيل الملفات والأدلة بشكل متزامن (على غرار أداة rm القياسية في نظام POSIX). يُرجع undefined.

fs.statSync(path[, options])

[السجل]

الإصدار	التغييرات
v15.3.0, v14.17.0	يقبل خيار throwIfNoEntry لتحديد ما إذا كان ينبغي إطلاق استثناء إذا لم يكن الإدخال موجودًا.
v10.5.0	يقبل كائن options إضافي لتحديد ما إذا كانت القيم الرقمية التي يتم إرجاعها يجب أن تكون bigint.
v7.6.0	يمكن أن يكون المعامل path كائن URL من WHATWG باستخدام بروتوكول 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.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: 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 كائن WHATWG URL باستخدام بروتوكول 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 كائن WHATWG URL باستخدام بروتوكول 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.

للحصول على معلومات مفصلة، راجع توثيق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: 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 <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.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 <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> الافتراضي: 0
• length <integer> الافتراضي: buffer.byteLength - offset
• position <integer> | <null> الافتراضي: null
• الإرجاع: <number> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

تمت الإضافة في: 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

• الإرجاع: <number> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق الإصدار غير المتزامن من واجهة برمجة التطبيقات هذه: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[التاريخ]

الإصدار	التغييرات
v14.0.0	لن يقوم المعامل string بعد الآن بإجبار الإدخال غير المدعوم إلى سلاسل نصية.
v7.2.0	المعامل position اختياري الآن.
v0.11.5	أُضيف في: v0.11.5

• fd <عدد صحيح>
• string <سلسلة نصية>
• position <عدد صحيح> | <فارغ> الافتراضي: null
• encoding <سلسلة نصية> الافتراضي: 'utf8'
• الإرجاع: <عدد> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق النسخة غير المتزامنة من هذا الـ API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

أُضيف في: v12.9.0

• fd <عدد صحيح>
• buffers <ArrayBufferView[]>
• position <عدد صحيح> | <فارغ> الافتراضي: null
• الإرجاع: <عدد> عدد البايتات المكتوبة.

للحصول على معلومات مفصلة، راجع وثائق النسخة غير المتزامنة من هذا الـ 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);
}

عند استخدام المكرر غير المتزامن، سيتم إغلاق كائن <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

[Stable: 1 - Experimental]

Stable: 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 بدلاً من ذلك.

• <سلسلة>

اسم مستعار لـ dirent.parentPath.

الصنف: fs.FSWatcher

تمت إضافته في: v0.5.8

• يمتد <EventEmitter>

ستعيد المكالمة الناجحة لطريقة fs.watch() كائن <fs.FSWatcher> جديد.

تصدر جميع كائنات <fs.FSWatcher> حدث 'change' كلما تم تعديل ملف معين تتم مراقبته.

الحدث: 'change'

تمت إضافته في: v0.5.8

• eventType <سلسلة> نوع حدث التغيير الذي حدث
• filename <سلسلة> | <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'.

الفئة: fs.Stats

[السجل]

الإصدار	التغييرات
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 التي تم تمريرها إلى هذه الطرق صحيحة، فستكون القيم الرقمية 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>

الطابع الزمني الذي يشير إلى آخر مرة تم فيها الوصول إلى هذا الملف معبرًا عنه بالملي ثانية منذ عصر POSIX.

stats.mtimeMs

أضيف في: v8.1.0

• <number> | <bigint>

الطابع الزمني الذي يشير إلى آخر مرة تم فيها تعديل هذا الملف معبرًا عنه بالملي ثانية منذ عصر POSIX.

stats.ctimeMs

أضيف في: v8.1.0

• <number> | <bigint>

الطابع الزمني الذي يشير إلى آخر مرة تم فيها تغيير حالة الملف معبرًا عنه بالملي ثانية منذ عصر POSIX.

stats.birthtimeMs

أضيف في: v8.1.0

• <number> | <bigint>

الطابع الزمني الذي يشير إلى وقت إنشاء هذا الملف معبرًا عنه بالملي ثانية منذ عصر POSIX.

stats.atimeNs

أضيف في: v12.10.0

• <bigint>

موجود فقط عند تمرير bigint: true إلى الطريقة التي تولد الكائن. الطابع الزمني الذي يشير إلى آخر مرة تم فيها الوصول إلى هذا الملف معبرًا عنه بالنانو ثانية منذ عصر POSIX.

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>

الطابع الزمني الذي يشير إلى وقت إنشاء هذا الملف.

قيم وقت الحالة (Stat time values)

الخصائص 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 "وقت التغيير": الوقت الذي تم فيه آخر تغيير لحالة الملف (تعديل بيانات inode). يتم تغييره بواسطة استدعاءات النظام chmod(2) و chown(2) و link(2) و mknod(2) و rename(2) و unlink(2) و utimes(2) و read(2) و write(2).
• birthtime "وقت الإنشاء": وقت إنشاء الملف. يتم تعيينه مرة واحدة عند إنشاء الملف. في أنظمة الملفات حيث يكون وقت الإنشاء غير متوفر، قد يحتوي هذا الحقل بدلاً من ذلك على ctime أو 1970-01-01T00:00Z (أي، الطابع الزمني لحقبة Unix 0). قد تكون هذه القيمة أكبر من atime أو mtime في هذه الحالة. في Darwin ومتغيرات FreeBSD الأخرى، يتم تعيينه أيضًا إذا تم تعيين atime صراحةً إلى قيمة سابقة لوقت birthtime الحالي باستخدام استدعاء النظام utimes(2).

قبل Node.js 0.12، كان ctime يحمل birthtime على أنظمة Windows. اعتبارًا من 0.12، ctime ليس "وقت الإنشاء"، ولم يكن كذلك أبدًا على أنظمة Unix.

الفئة: fs.StatFs

أُضيفت في: الإصدار 19.6.0، و 18.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

أُضيفت في: الإصدار 19.6.0، و 18.15.0

• <number> | <bigint>

كتل حرة متاحة للمستخدمين غير المتميزين.

statfs.bfree

أُضيفت في: الإصدار 19.6.0، و 18.15.0

• <number> | <bigint>

كتل حرة في نظام الملفات.

statfs.blocks

أُضيفت في: الإصدار 19.6.0، و 18.15.0

• <number> | <bigint>

إجمالي كتل البيانات في نظام الملفات.

statfs.bsize

أُضيفت في: الإصدار 19.6.0، و 18.15.0

• <number> | <bigint>

حجم كتلة النقل الأمثل.

statfs.ffree

أُضيفت في: الإصدار 19.6.0، و 18.15.0

• <number> | <bigint>

عقد الملفات الحرة في نظام الملفات.

statfs.files

أضيف في: الإصدار 19.6.0، الإصدار 18.15.0

• <number> | <bigint>

إجمالي عدد عقد الملفات في نظام الملفات.

statfs.type

أضيف في: الإصدار 19.6.0، الإصدار 18.15.0

• <number> | <bigint>

نوع نظام الملفات.

الصنف: fs.WriteStream

أضيف في: الإصدار 0.1.93

• يمتد <stream.Writable>

يتم إنشاء وإرجاع نسخ <fs.WriteStream> باستخدام الدالة fs.createWriteStream().

الحدث: 'close'

أضيف في: الإصدار 0.1.93

يصدر عندما يتم إغلاق واصف الملف الأساسي لـ <fs.WriteStream>.

الحدث: 'open'

أضيف في: الإصدار 0.1.93

• fd <integer> واصف ملف عدد صحيح تستخدمه <fs.WriteStream>.

يصدر عندما يتم فتح ملف <fs.WriteStream>.

الحدث: 'ready'

أضيف في: الإصدار 9.11.0

يصدر عندما يكون <fs.WriteStream> جاهزًا للاستخدام.

يطلق مباشرة بعد 'open'.

writeStream.bytesWritten

أضيف في: الإصدار 0.4.7

عدد البايتات التي تمت كتابتها حتى الآن. لا يتضمن البيانات التي لا تزال في قائمة الانتظار للكتابة.

writeStream.close([callback])

أضيف في: الإصدار 0.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	في حالة وجوده، ستحاول عملية النسخ إنشاء إعادة ارتباط نسخ عند الكتابة. إذا كانت المنصة الأساسية لا تدعم النسخ عند الكتابة، فسيتم استخدام آلية نسخ احتياطية.
COPYFILE_FICLONE_FORCE	في حالة وجوده، ستحاول عملية النسخ إنشاء إعادة ارتباط نسخ عند الكتابة. إذا كانت المنصة الأساسية لا تدعم النسخ عند الكتابة، فستفشل العملية مع وجود خطأ.
التعريفات متاحة أيضًا على نظام التشغيل 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/pipe.
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 فقط.

ملاحظات

ترتيب عمليات الاستدعاء والوعد

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

على سبيل المثال، ما يلي عرضة للخطأ لأن عملية 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');

أو، عند استخدام واجهات برمجة تطبيقات الاستدعاء، انقل استدعاء fs.stat() إلى الاستدعاء الخلفي لعملية 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: التي تحمل اسم مضيف إلى مسارات UNC، بينما يتم تحويل <URL> من النوع file: التي تحمل أحرف محركات أقراص إلى مسارات مطلقة محلية. ستؤدي <URL> من النوع file: التي لا تحمل اسم مضيف ولا حرف محرك أقراص إلى حدوث خطأ:

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> من النوع file: التي تحمل اسم مضيف غير مدعومة وستؤدي إلى حدوث خطأ:

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: التي تحتوي على أحرف شرطة مائلة مشفرة إلى حدوث خطأ على جميع الأنظمة الأساسية:

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: التي تحتوي على شرطة مائلة عكسية مشفرة إلى حدوث خطأ:

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');
  // Do something with the file
} finally {
  await fd?.close();
}

دلائل العمل لكل محرك أقراص على نظام Windows

في نظام Windows، يتبع Node.js مفهوم دليل العمل لكل محرك أقراص. يمكن ملاحظة هذا السلوك عند استخدام مسار محرك أقراص بدون شرطة مائلة عكسية. على سبيل المثال، يمكن أن تُرجع fs.readdirSync('C:\\') نتيجة مختلفة عن fs.readdirSync('C:'). لمزيد من المعلومات، راجع صفحة MSDN هذه.

واصفات الملفات

في أنظمة POSIX، يحتفظ kernel لكل عملية بجدول للملفات والموارد المفتوحة حاليًا. يتم تعيين مُعرّف رقمي بسيط لكل ملف مفتوح يسمى واصف الملف. على مستوى النظام، تستخدم جميع عمليات نظام الملفات واصفات الملفات هذه لتحديد وتتبع كل ملف محدد. تستخدم أنظمة 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;
      }

      // use 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();
  // use 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 and Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
});

// Windows and FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
});

على نظام التشغيل Windows، سيؤدي فتح ملف مخفي موجود باستخدام العلامة 'w' (سواء من خلال fs.open() أو fs.writeFile() أو fsPromises.open()) إلى الفشل مع EPERM. يمكن فتح الملفات المخفية الموجودة للكتابة باستخدام العلامة 'r+'.

يمكن استخدام استدعاء fs.ftruncate() أو filehandle.truncate() لإعادة تعيين محتويات الملف.