Node.js/path

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

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

const path = require('path');

ويندوز في مقابل POSIX

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

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

في POSIX:

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

في ويندوز:

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

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

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

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

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

ملاحظة: يتبع 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 في يونكس. تُتجاهل فواصل المجلدات الملحقة، انظر 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.

• من النوع <string>.

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

• ; لنظام التشغيل ويندوز.
• : لنظام التشغيل 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']

في ويندوز:

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 في يونكس. تُتجاهل فواصل المجلدات الملحقة، انظر 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.

• pathObject من النوع <Object>.
  • dir من النوع <string>.
  • root من النوع <string>.
  • base من النوع <string>.
  • name من النوع <string>.
  • ext من النوع <string>.
• القيمة المُعادة: من النوع <string>.

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

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

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

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

// إذا توفَّر `dir` و` root` و` base` ،
// سيُعاد `${dir}${path.sep}${base}`
// ويُتجاهل `root`.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt'
});
// يُعيد: '/home/user/dir/file.txt'

// يُستخدم `root` إذا لم يُحدد `dir`.
// إذا توفَّر `root` أو كان `dir` يساوي `root`
// لن يُتضمَّن فاصل النظام الأساسي. ويُتجاهل `ext`.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored'
});
// يُعيد: '/file.txt'

// يُستخدم `name` + `ext` إذا لم يُحدد `base`.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt'
});
// يُعيد: '/file.txt'

في ويندوز:

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

في ويندوز:

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 وأيًا من \ أو / في ويندوز)، فستُستبدل بمثيل مُفرد من أحرف فواصل المقاطع الخاصة بمنصة التشغيل ( / في POSIX و \ في ويندوز). ويُحتفَظ بالفواصل اللاحقة.

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

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

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

وفي ويندوز:

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

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

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.

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

• dir من النوع <string>.
• root من النوع <string>.
• base من النوع <string>.
• name من النوع <string>.
• ext من النوع <string>.

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

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

وفي ويندوز:

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.

• من النوع <Object>.

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

path.relative(from, to)‎

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

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

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

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

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

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

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

في ويندوز:

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.

• من النوع <string>.

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

• \ في Windows
• / في POSIX

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

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

على ويندوز:

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

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

path.toNamespacedPath(path)‎

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

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

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

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

path.win32

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

• من النوع <Object>.

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

مصادر

• صفحة المسار (Path) في توثيق Node.js الرسمي.