وحدة المسار (Path) في Node.js

من موسوعة حسوب

مؤشر الاستقرار: 2 - مستقر.

توفر وحدة المسار path أدوات للعمل مع مسارات الملفات والمجلدات. ويمكن الوصول إليها باستخدام:

const path = require('path');

Windows في مقابل POSIX

يختلف التشغيل الإفتراضي لوحدة path استناداً إلى نظام التشغيل الذي يعمل عليه أحد تطبيقات Node.js. على وجه التحديد، عند تشغيل نظام تشغيل Windows، ستفترض وحدة path استخدام نمط Windows للمسارات.

على سبيل المثال، استخدام الدالة path.basename()‎ مع مسار Windows للملف C:\temp\myfile.html، وسيُسفر ذلك عن نتائج مختلفة عند تشغيله على POSIX عمّا هو الحال عند تشغيله على Windows:

في POSIX:

path.basename('C:\\temp\\myfile.html');
// إعادة: 'C:\\temp\\myfile.html'

في Windows:

path.basename('C:\\temp\\myfile.html');
// إعادة: 'myfile.html'

يُستخدم path.win32 لتحقيق نتائج متسقة عند العمل مع مسارات ملفات Windows على أي نظام تشغيل: على POSIX و Windows:

path.win32.basename('C:\\temp\\myfile.html');
// إعادة: 'myfile.html'

يُستخدم path.posix لتحقيق نتائج متسقة عند العمل مع مسارات ملفات POSIX على أي نظام التشغيل:

path.posix.basename('/tmp/myfile.html');
// إعادة: 'myfile.html'

على POSIX و Windows:

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

path.basename(path[, ext])‎

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

الإصدار التغييرات
v6.0.0 تمرير قيمة ليست سلسلة نصية كوسيط المسار path سيُطرح الآن.
v0.1.25 أُضيف مع الإصدار: v0.1.25.
  • path من النوع <string>.
  • ext من النوع <string> امتداد اختياري لاسم الملف.
  • القيمة المُعادة: من النوع <string>.

تُعيد توابع path.basename()‎ الجزء الأخير من path، كما هو الحال مع أمر basename في Unix. تُتجاهل فواصل المجلدات الملحقة، انظر path.sep.

path.basename('/foo/bar/baz/asdf/quux.html');
// إعادة: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// إعادة: 'quux'

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية أو إذا توفر ext و كان ليس سلسلة نصية.

path.delimiter

أُضيف مع الإصدار: v0.9.3.

توفير مُحدِّد مسار محدد بحسب المنصة:

  • ; لنظام التشغيل Windows.
  • : لنظام التشغيل POSIX.

على سبيل المثال، في POSIX:

console.log(process.env.PATH);
// طباعة: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// إعادة: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']

في Windows:

console.log(process.env.PATH);
// طباعة: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// إعادة ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']

path.dirname(path)‎

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

الإصدار التغييرات
v6.0.0 تمرير قيمة ليست سلسلة نصية كوسيط المسار path سيُطرح الآن.
v0.1.25 أُضيف مع الإصدار: v0.1.25.
  • path من النوع <string>.
  • القيمة المُعادة: من النوع <string>.

يُعيد التابع path.dirname()‎ اسم المجلد للمسار path، كما هو الحال مع أمر dirname في Unix. تُتجاهل فواصل المجلدات الملحقة، انظر path.sep.

path.dirname('/foo/bar/baz/asdf/quux');
// إعادة
: '/foo/bar/baz/asdf'

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية.

path.extname(path)‎

  • path من النوع <string>.
  • القيمة المُعادة: من النوع <string>.

يُعيد التابع path.extname()‎ امتداد path، من آخر تواجد لعلامة النقطة '.' إلى نهاية السلسلة النصية في الجزء الأخير من path. تُعاد سلسلة نصية فارغة إذا لم يكن هناك نقطة '.' في الجزء الأخير من المسار path، أو إذا كان الحرف الأول من basename من المسار path هو النقطة '.' (راجع path.basename()‎).

path.extname('index.html');
// إعادة: '.html'

path.extname('index.coffee.md');
// إعادة: '.md'

path.extname('index.');
// إعادة: '.'

path.extname('index');
// إعادة: ''

path.extname('.index');
// إعادة: ''

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية.

path.format(pathObject)‎

أُضيف مع الإصدار: v0.11.15.

يُعيد التابع path.format()‎ سلسلة مسار من كائنٍ ما. وهو يعمل بعكس path.parse()‎.

عند توفير خصائص pathObject تذكر أن هناك عدة تركيبات منها بحيث يكون هناك أولوية لخاصية ما على الأخرى:

  • يُتجاهل pathObject.root إذا توفَّر pathObject.dir.
  • يُتجاهل كلٌ من pathObject.ext و pathObject.name في حالة وجود pathObject.base.

على سبيل المثال، في POSIX:

// If `dir`, `root` and `base` are provided,
// `${dir}${path.sep}${base}`
// will be returned. `root` is ignored.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt'
});
// Returns: '/home/user/dir/file.txt'

// `root` will be used if `dir` is not specified.
// If only `root` is provided or `dir` is equal to `root` then the
// platform separator will not be included. `ext` will be ignored.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored'
});
// Returns: '/file.txt'

// `name` + `ext` will be used if `base` is not specified.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt'
});
// Returns: '/file.txt'

في Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt'
});
// إعادة: 'C:\\path\\dir\\file.txt'

path.isAbsolute(path)‎

أُضيف مع الإصدار: v0.11.2.

  • path من النوع <string>.
  • القيمة المُعادة: من النوع <boolean>.

يُحدد التابع path.isAbsolute()‎ ما إذا كان المسار path مساراً مطلقا.

إذا كان path سلسلة نصية ذات طول صفري، ستُعاد القيمة false.

على سبيل المثال، في POSIX:

path.isAbsolute('/foo/bar'); // true
path.isAbsolute('/baz/..');  // true
path.isAbsolute('qux/');     // false
path.isAbsolute('.');        // false

في Windows:

path.isAbsolute('//server');    // true
path.isAbsolute('\\\\server');  // true
path.isAbsolute('C:/foo/..');   // true
path.isAbsolute('C:\\foo\\..'); // true
path.isAbsolute('bar\\baz');    // false
path.isAbsolute('bar/baz');     // false
path.isAbsolute('.');           // false

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية.

path.join([...paths])‎

أُضيف مع الإصدار: v0.1.16.

  • ‎...paths من النوع <string> وهو تسلسل مقاطع المسار.
  • القيمة المُعادة: من النوع <string>.

يضم التابع path.join()‎ جميع مقاطع المسار path المعطى معا باستخدام المُحدِّد الفاصل الخاص بمنصة التشغيل، ثم يضبط المسار الناتج.

تُتجاهل مقاطع المسار path ذات الطول الصفري. إذا كانت سلسلة المسار المنضمة ذات طول صفري، ستُعاد علامة '.'، ممثلةً مجلد العمل الحالي.

path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// إعادة: '/foo/bar/baz/asdf'

path.join('foo', {}, 'bar');
// طرح 'TypeError: Path must be a string. Received {}'

يُطرح TypeError إذا كان أي من مقاطع المسار ليس سلسلة نصية.

path.normalize(path)‎

أُضيف مع الإصدار: v0.1.23.

  • path من النوع <string>.
  • القيمة المُعادة: من النوع <string>.

يضبط التابع path.normalize()‎ المسار path المُعطى، مع حل كل من المقاطع '..' و '.'.

عند العثور على أحرف الفواصل لمقاطع المسار المتعددة المتتالية، (على سبيل المثال / في POSIX وأيًا من \ أو / في Windows)، فستُستبدل بمثيل مُفرد من أحرف فواصل المقاطع الخاصة بمنصة التشغيل ( / في POSIX و \ في Windows). ويُحتفَظ بالفواصل اللاحقة.

إذا كانت سلسلة المسار path ذات طول صفري، ستُعاد علامة '.'، ممثلةً مجلد العمل الحالي.

على سبيل المثال، في POSIX:

path.normalize('/foo/bar//baz/asdf/quux/..');
// إعادة: '/foo/bar/baz/asdf'

وفي Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// إعادة: 'C:\\temp\\foo\\'

ولما كان Windows يتعرف على فواصل المسار المتعددة، ستُستبدل كلٌ من الفاصلين بمثيلات من فاصل Windows المفضل (\):

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// إعادة: 'C:\\temp\\foo\\bar'

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية.

path.parse(path)‎

أُضيف مع الإصدار: v0.11.15.

  • path من النوع <string>.
  • القيمة المُعادة: من النوع <Object>.

يُعيد التابع path.parse()‎ كائنًا تمثل خصائصه عناصر هامة من المسار path. تُتجاهل فواصل المجلدات الملحقة، انظر path.sep.

سوف يكون للكائن المُعاد الخصائص التالية:

على سبيل المثال، في POSIX:

path.parse('/home/user/dir/file.txt');
// إعادة:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

وفي Windows:

path.parse('C:\\path\\dir\\file.txt');
// إعادة:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

يُطرح TypeError إذا كان المسار path ليس سلسلة نصية.

path.posix

أُضيف مع الإصدار: v0.11.15.

تُمكن الخاصية path.posix من الوصول إلى تطبيقات POSIX المُحدَدة لتوابع المسار path.

path.relative(from, to)‎

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

الإصدار التغييرات
v6.8.0 في Windows ، تُعاد الآن الشرطات الأمامية السابقة متضمَنة مع مسارات UNC.
v0.5.0 أُضيف مع الإصدار: v0.5.0

يُعيد التابع path.relative()‎ المسار النسبي من from حتي to بالنسبة لمجلد العمل الحالي. إذا كان from و to يؤديان إلى نفي المسار (بعد استدعاء path.resolve()‎ في كل منهما)، تُعاد سلسلة نصية ذات طول صفري.

إذا مُررِت سلسلة ذات طول صفري في from أو to، سيستخدم مُجلد العمل الحالي بدلاً من السلاسل النصية ذات الطول الصفري.

على سبيل المثال، في POSIX:

path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb');
// إعادة: '../../impl/bbb'

في Windows:

path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// إعادة: '..\\..\\impl\\bbb'

يُطرح TypeError إذا كان أي من from أو to ليس سلسلة نصية.

path.resolve([...paths])‎

أُضيف مع الإصدار: v0.3.4.

  • ‎...paths من النوع <string> وهو تسلسل من المسارات أو مقاطع المسار.
  • القيمة المُعادة: من النوع <string>.

يحل التابع path.resolve()‎ سلسلة من المسارات أو مقاطع المسار إلى مسارٍ مطلق.

يعالج تسلسل مسارات المُعطى من اليمين إلى اليسار، مع كل مسار path تالٍ سبق إرفاقه حتى يُنشأ مسار مطلق. على سبيل المثال، في ضوء تسلسل مقاطع المسار: ‎/foo, /bar, baz, استدعاء path.resolve('/foo', '/bar', 'baz')‎ سيُعيد ‎/bar/baz.

إذا لم ينشأ مسار مطلق بعد معالجة جميع مقاطع المسار المعطى path، يُستخدام مُجلد العمل الحالي.

المسار الناتج منضبط وتُزال الشرطات المائلة المذيِّلة ما لم يشير المسار إلى الدليل الجذر.

تُتجاهل مقاطع المسار path ذات الطول الصفري.

إذا لم تُمرر مقاطع المسار path، سيعيد path.resolve()‎ المسار المطلق لمجلد العمل الحالي.

path.resolve('/foo/bar', './baz');
// إعادة: '/foo/bar/baz'

path.resolve('/foo/bar', '/tmp/file/');
// إعادة: '/tmp/file'

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// إذا كان مجلد العمل الحالي هو /home/myself/node,
// سيُعاد '/home/myself/node/wwwroot/static_files/gif/image.gif'

يُطرح TypeError إذا كان أي من الوسائط ليس سلسلة نصية.

path.sep

أُضيف مع الإصدار: v0.7.9.

يوفر فاصل مقاطع المسار الخاص بمنصة التشغيل:

  • \ في Windows
  • / في POSIX

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

'foo/bar/baz'.split(path.sep);
// إعادة
: ['foo', 'bar', 'baz']

على Windows:

'foo\\bar\\baz'.split(path.sep);
// إعادة: ['foo', 'bar', 'baz']

في Windows، يقبل كل من الشرطة المائلة الأمامية (/) والشرطة المائلة الخلفية (\) كفاصل مقاطع المسار؛ ومع ذلك، يضيف تابع path فقط الشرطة المائلة الخلفية(\).

path.toNamespacedPath(path)‎

أُضيف مع الإصدار: v9.0.0.

  • path من النوع <string>.
  • القيمة المُعادة: من النوع <string>.

يعيد مسارًا مسبوقًا بمجال الأسماء ( namespace-prefixed path) يكافئ المسار المُعطى path، في أنظمة Windows فقط. إذا لم يكن المسار path سلسلة نصية، سيعيد المسار path دون تعديلات.

هذا التابع مفيد فقط في نظام Windows. في أنظمة posix، لا يعمل هذا التابع ويعيد دومًا المسار path دون تعديلات.

path.win32

أُضيف مع الإصدار: v0.11.15.

تُمكن الخاصية path.win32 من الوصول إلى تطبيقات Windows المُحدَدة لتوابع المسار path.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Node.js/path&oldid=13060»