المسار

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

شفرة المصدر: lib/path.js

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

CJSESM

const path = require('node:path');

import path from 'node:path';

Windows vs. POSIX

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

لذا، قد يؤدي استخدام path.basename() إلى نتائج مختلفة على POSIX و Windows:

على POSIX:

path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html'

على Windows:

path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'

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

على POSIX و Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'

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

على POSIX و Windows:

path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html'

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

`path.basename(path[, suffix])`

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

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

path <string>
suffix <string> لاحقة اختيارية للإزالة
الإرجاع: <string>

تُرجع الطريقة path.basename() الجزء الأخير من path، على غرار أمر Unix basename. يتم تجاهل فواصل دليل في النهاية.

path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Returns: 'quux'

على الرغم من أن نظام Windows عادةً ما يتعامل مع أسماء الملفات، بما في ذلك امتدادات الملفات، بطريقة غير حساسة لحالة الأحرف، إلا أن هذه الوظيفة لا تفعل ذلك. على سبيل المثال، يشير C:\\foo.html و C:\\foo.HTML إلى نفس الملف، ولكن basename يعامل الامتداد كسلسلة حساسة لحالة الأحرف:

path.win32.basename('C:\\foo.html', '.html');
// Returns: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Returns: 'foo.HTML'

يتم طرح TypeError إذا لم يكن path سلسلة نصية أو إذا تم إعطاء suffix ولم يكن سلسلة نصية.

`path.delimiter`

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

<string>

يوفر محدد المسار الخاص بالنظام الأساسي:

; لنظام التشغيل 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.16	أضيف في: الإصدار v0.1.16

path <string>
الإرجاع: <string>

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

path.dirname('/foo/bar/baz/asdf/quux');
// الإرجاع: '/foo/bar/baz/asdf'

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

`path.extname(path)`

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

الإصدار	التغييرات
v6.0.0	سيؤدي تمرير قيمة ليست سلسلة نصية كـ `path` إلى حدوث خطأ الآن.
v0.1.25	أضيف في: الإصدار v0.1.25

path <string>
الإرجاع: <string>

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

path.extname('index.html');
// الإرجاع: '.html'

path.extname('index.coffee.md');
// الإرجاع: '.md'

path.extname('index.');
// الإرجاع: '.'

path.extname('index');
// الإرجاع: ''

path.extname('.index');
// الإرجاع: ''

path.extname('.index.md');
// الإرجاع: '.md'

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

`path.format(pathObject)`

[التاريخ]

الإصدار	التغييرات
v19.0.0	ستتم إضافة النقطة إذا لم يتم تحديدها في `ext`.
v0.11.15	تمت الإضافة في: v0.11.15

pathObject <Object> أي كائن JavaScript يحتوي على الخصائص التالية:
- 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'

// ستتم إضافة النقطة إذا لم يتم تحديدها في `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
});
// الإرجاع: '/file.txt'

في نظام Windows:

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

`path.matchesGlob(path, pattern)`

أُضيف في: الإصدار 22.5.0، الإصدار 20.17.0

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

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

path <string> المسار المراد مطابقته مع النمط العام.
pattern <string> النمط العام المراد التحقق من المسار مقابله.
إرجاع: <boolean> ما إذا كان path متطابقًا مع pattern أم لا.

تحدد الطريقة path.matchesGlob() ما إذا كان path متطابقًا مع pattern.

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

path.matchesGlob('/foo/bar', '/foo/*'); // true
path.matchesGlob('/foo/bar*', 'foo/bird'); // false

يتم طرح TypeError إذا كان path أو pattern ليسا من نوع السلسلة.

`path.isAbsolute(path)`

أُضيف في: الإصدار 0.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])`

أُضيف في: الإصدار 0.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: يجب أن يكون المسار سلسلة. تم استقبال {}'

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

`path.normalize(path)`

أُضيف في: v0.1.23

path <string>
تُرجع: <string>

يقوم الأسلوب path.normalize() بتطبيع path المُعطى، وحل المقاطع '..' و '.'.

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

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

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

على سبيل المثال، على 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.

سيكون للكائن الذي تم إرجاعه الخصائص التالية:

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

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(يجب تجاهل جميع المسافات في السطر "". إنها مخصصة للتنسيق فقط.)

على Windows:

path.parse('C:\\path\\dir\\file.txt');
// تُرجع:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(يجب تجاهل جميع المسافات في السطر "". إنها مخصصة للتنسيق فقط.)

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

`path.posix`

[التاريخ]

الإصدار	التغييرات
v15.3.0	تم عرضه كـ `require('path/posix')`.
v0.11.15	تمت إضافته في: v0.11.15

<الكائن>

يوفر الخاصية path.posix الوصول إلى تطبيقات POSIX الخاصة بطرق path.

يمكن الوصول إلى واجهة برمجة التطبيقات عبر require('node:path').posix أو require('node:path/posix').

`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 <سلسلة نصية> تسلسل من المسارات أو أجزاء المسار
الإرجاع: <سلسلة نصية>

تقوم الطريقة path.resolve() بحل تسلسل من المسارات أو أجزاء المسار إلى مسار مطلق.

تتم معالجة التسلسل المحدد من المسارات من اليمين إلى اليسار، مع إضافة كل path لاحق حتى يتم إنشاء مسار مطلق. على سبيل المثال، بالنظر إلى تسلسل أجزاء المسار: /foo, /bar, baz، فإن استدعاء path.resolve('/foo', '/bar', 'baz') سيعيد /bar/baz لأن '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 <سلسلة نصية>
الإرجاع: <سلسلة نصية>

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

هذه الطريقة ذات مغزى فقط في أنظمة Windows. في أنظمة POSIX، تكون الطريقة غير فعالة وتُرجع دائمًا path دون تعديلات.

`path.win32`

[السجل]

الإصدار	التغييرات
v15.3.0	تم عرضه على أنه `require('path/win32')`.
v0.11.15	أُضيف في: v0.11.15

<كائن>

توفر الخاصية path.win32 الوصول إلى عمليات التنفيذ الخاصة بنظام Windows لطرق path.

يمكن الوصول إلى واجهة برمجة التطبيقات عبر require('node:path').win32 أو require('node:path/win32').

المسار ​

Windows vs. POSIX ​

path.basename(path[, suffix]) ​

path.delimiter ​

path.dirname(path) ​

path.extname(path) ​

path.format(pathObject) ​

path.matchesGlob(path, pattern) ​

path.isAbsolute(path) ​

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

path.normalize(path) ​

path.parse(path) ​

path.posix ​

path.relative(from, to) ​

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

path.sep ​

path.toNamespacedPath(path) ​

path.win32 ​

المسار

Windows vs. POSIX

`path.basename(path[, suffix])`

`path.delimiter`

`path.dirname(path)`

`path.extname(path)`

`path.format(pathObject)`

`path.matchesGlob(path, pattern)`

`path.isAbsolute(path)`

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

`path.normalize(path)`

`path.parse(path)`

`path.posix`

`path.relative(from, to)`

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

`path.sep`

`path.toNamespacedPath(path)`

`path.win32`