المسار

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

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

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

CJSESM

const path = require('node:path')

import path from 'node:path'

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

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

لذلك، قد يُعطي استخدام path.basename() نتائج مختلفة على 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'

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

على POSIX وويندوز:

path.posix.basename('/tmp/myfile.html')
// تُرجع: 'myfile.html'

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

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

[السجل]

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

path <سلسلة>
suffix <سلسلة> بادئة اختيارية لإزالتها
المُرجع: <سلسلة>

ترجع طريقة path.basename() الجزء الأخير من path، مشابهًا لأمر basename في يونكس. يتم تجاهل فاصلات المجلدات النهائية.

path.basename('/foo/bar/baz/asdf/quux.html')
// تُرجع: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html')
// تُرجع: 'quux'

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

path.win32.basename('C:\\foo.html', '.html')
// تُرجع: 'foo'

path.win32.basename('C:\\foo.HTML', '.html')
// تُرجع: 'foo.HTML'

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

`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.16	مضاف في: v0.1.16

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

[السجل]

الإصدار	التغييرات
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 <كائن> أي كائن جافا سكريبت يحتوي على الخصائص التالية:
- dir <سلسلة>
- root <سلسلة>
- base <سلسلة>
- name <سلسلة>
- ext <سلسلة>
قيمة الإرجاع: <سلسلة>

ترجع طريقة 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'

على نظام ويندوز:

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

`path.matchesGlob(path, pattern)`

أضيف في: v22.5.0، v20.17.0

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

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

path <string> المسار الذي يجب مطابقته باستخدام glob.
pattern <string> تعبير glob للتحقق من المسار ضده.
القيمة المرجعة: <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)`

أضيف في: 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، لا تلتزم أنواع التطبيع التي تقوم بها هذه الدالة بدقة بمواصفات 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`

[History]

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

<Object>

توفر خاصية path.posix الوصول إلى تنفيذات محددة لنظام POSIX لأساليب path.

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

`path.relative(from, to)`

[History]

الإصدار	التغييرات
v6.8.0	في ويندوز، يتم تضمين الشرطة المائلة الأمامية لمسارات 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 لأن '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']

على Windows:

'foo\\bar\\baz'.split(path.sep)
// يعيد: ['foo', 'bar', 'baz']

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

`path.toNamespacedPath(path)`

مضاف في: v9.0.0

path <string>
يعيد: <string>

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

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

`path.win32`

[السجل]

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

<Object>

توفر خاصية path.win32 الوصول إلى تنفيذات مُحددة بنظام Windows لأساليب path.

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

المسار ​

ويندوز مقابل 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 ​

المسار

ويندوز مقابل 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`