عنوان URL

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

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

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

ESMCJS

import url from 'node:url'

const url = require('node:url')

سلاسل URL وكائنات URL

سلسلة URL هي سلسلة مُهيكلة تحتوي على العديد من المكونات ذات المعنى. عند تحليلها، يتم إرجاع كائن URL يحتوي على خصائص لكل من هذه المكونات.

توفر وحدة node:url واجهتين برمجيتين للعمل مع عناوين URL: واجهة برمجية قديمة خاصة بـ Node.js، وواجهة برمجية أحدث تُنفذ نفس معيار WHATWG URL الذي تستخدمه متصفحات الويب.

يوضح ما يلي مقارنة بين واجهات برمجة التطبيقات WHATWG والقديمة. أعلى عنوان URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash'، يتم عرض خصائص الكائن الذي تُرجعه دالة url.parse() القديمة. وفي الأسفل خصائص كائن WHATWG URL.

تتضمن خاصية origin لـ WHATWG URL الخاصية protocol و host، ولكن ليس username أو password.

text

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│          │  │          │          │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(يجب تجاهل جميع المسافات في سطر "". إنها فقط لتنسيق.)

تحليل سلسلة URL باستخدام واجهة برمجة التطبيقات WHATWG:

const myURL = new URL('https://user::8080/p/a/t/h?query=string#hash')

تحليل سلسلة URL باستخدام واجهة برمجة التطبيقات القديمة:

ESMCJS

import url from 'node:url'
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

const url = require('node:url')
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

إنشاء عنوان URL من الأجزاء المكونة والحصول على السلسلة المُنشأة

من الممكن إنشاء عنوان URL من WHATWG من الأجزاء المكونة باستخدام مُعيّنات الخاصية أو سلسلة قالب حرفية:

const myURL = new URL('https://example.org')
myURL.pathname = '/a/b/c'
myURL.search = '?d=e'
myURL.hash = '#fgh'

const pathname = '/a/b/c'
const search = '?d=e'
const hash = '#fgh'
const myURL = new URL(`https://example.org${pathname}${search}${hash}`)

للحصول على سلسلة عنوان URL المُنشأة، استخدم مُحسِّن خاصية href:

console.log(myURL.href)

واجهة برمجة تطبيقات WHATWG URL

فئة: `URL`

[History]

الإصدار	التغييرات
v10.0.0	أصبحت الفئة متاحة الآن على الكائن العام.
v7.0.0, v6.13.0	تمت الإضافة في: v7.0.0, v6.13.0

فئة URL متوافقة مع المتصفح، مُنفذة باتباع معيار WHATWG URL. يمكن العثور على أمثلة على عناوين URL المُحللة في المعيار نفسه. تتوفر فئة URL أيضًا على الكائن العام.

وفقًا لاتفاقيات المتصفح، يتم تنفيذ جميع خصائص كائنات URL كمُحصلات ومُعيّنات على النموذج الأولي للفئة، بدلاً من خصائص البيانات على الكائن نفسه. وبالتالي، على عكس كائنات urlObject القديمة، فإن استخدام كلمة delete على أي خصائص لكائنات URL (مثل delete myURL.protocol, delete myURL.pathname, إلخ) ليس له أي تأثير، ولكن سيظلّ يُرجع true.

`new URL(input[, base])`

[History]

الإصدار	التغييرات
v20.0.0, v18.17.0	تم إزالة شرط ICU.

input <string> عنوان URL المدخل المطلق أو النسبي الذي يجب تحليله. إذا كان input نسبيًا، فيجب وجود base. إذا كان input مطلقًا، يتم تجاهل base. إذا لم يكن input سلسلة، يتم تحويله إلى سلسلة أولاً.
base <string> عنوان URL الأساسي للحل ضده إذا لم يكن input مطلقًا. إذا لم يكن base سلسلة، يتم تحويله إلى سلسلة أولاً.

يُنشئ كائن URL جديدًا من خلال تحليل input بالنسبة إلى base. إذا تم تمرير base كسلسلة، فسيتم تحليله بما يعادل new URL(base).

const myURL = new URL('/foo', 'https://example.org/')
// https://example.org/foo

يُمكن الوصول إلى مُنشئ URL كخاصية على الكائن العام. كما يمكن استيراده من وحدة url المُدمجة:

ESMCJS

import { URL } from 'node:url'
console.log(URL === globalThis.URL) // يطبع 'true'.

console.log(URL === require('node:url').URL) // يطبع 'true'.

سيتم طرح TypeError إذا لم تكن input أو base عناوين URL صالحة. لاحظ أنه سيتم بذل جهد لتحويل القيم المعطاة إلى سلاسل. على سبيل المثال:

const myURL = new URL({ toString: () => 'https://example.org/' })
// https://example.org/

سيتم تحويل الأحرف اليونيكود التي تظهر ضمن اسم المضيف لـ input تلقائيًا إلى ASCII باستخدام خوارزمية Punycode.

const myURL = new URL('https://測試')
// https://xn--g6w251d/

في الحالات التي لا يُعرف مسبقًا ما إذا كان input عنوان URL مطلقًا وتم توفير base، يُنصح بالتحقق من أن origin لكائن URL هو ما هو متوقع.

let myURL = new URL('http://Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/')
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/')
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/')
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/')
// foo:Example.com/

`url.hash`

<string>

يحصل على جزء المُقطَع من عنوان URL ويُعيّنه.

const myURL = new URL('https://example.org/foo#bar')
console.log(myURL.hash)
// يُطبع #bar

myURL.hash = 'baz'
console.log(myURL.href)
// يُطبع https://example.org/foo#baz

يتم ترميز الأحرف غير الصالحة في عنوان URL المُضمنة في القيمة المُعيّنة لخاصية hash باستخدام الترميز النسبي. وقد يختلف اختيار الأحرف التي يجب ترميزها نسبيًا إلى حد ما عما تنتجه طرق url.parse() وurl.format().

`url.host`

<string>

يحصل على جزء المُضيف من عنوان URL ويُعيّنه.

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.host)
// يُطبع example.org:81

myURL.host = 'example.com:82'
console.log(myURL.href)
// يُطبع https://example.com:82/foo

يتم تجاهل قيم المُضيف غير الصالحة المُعيّنة لخاصية host.

`url.hostname`

<string>

يحصل على جزء اسم المُضيف من عنوان URL ويُعيّنه. يكمن الاختلاف الرئيسي بين url.host وurl.hostname في أن url.hostname لا يتضمن المنفذ.

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.hostname)
// يُطبع example.org

// لا يُغيّر تعيين اسم المُضيف المنفذ
myURL.hostname = 'example.com'
console.log(myURL.href)
// يُطبع https://example.com:81/foo

// استخدم myURL.host لتغيير اسم المُضيف والمنفذ
myURL.host = 'example.org:82'
console.log(myURL.href)
// يُطبع https://example.org:82/foo

يتم تجاهل قيم اسم المُضيف غير الصالحة المُعيّنة لخاصية hostname.

`url.href`

<string>

يحصل على عنوان URL المُسلسل ويُعيّنه.

const myURL = new URL('https://example.org/foo')
console.log(myURL.href)
// يُطبع https://example.org/foo

myURL.href = 'https://example.com/bar'
console.log(myURL.href)
// يُطبع https://example.com/bar

يُعادل الحصول على قيمة خاصية href استدعاء url.toString().

يُعادل تعيين قيمة هذه الخاصية إلى قيمة جديدة إنشاء كائن URL جديد باستخدام new URL(value). سيتم تعديل كل من خصائص كائن URL.

إذا كانت القيمة المُعيّنة لخاصية href ليست عنوان URL صالحًا، فسيتم طرح TypeError.

`url.origin`

[History]

الإصدار	التغييرات
v15.0.0	لم يعد نظام "gopher" خاصًا، و`url.origin` يعيد الآن `'null'` له.

<string>

يحصل على تسلسل مُقرأ فقط لمنشأ عنوان URL.

const myURL = new URL('https://example.org/foo/bar?baz')
console.log(myURL.origin)
// يطبع https://example.org

const idnURL = new URL('https://測試')
console.log(idnURL.origin)
// يطبع https://xn--g6w251d

console.log(idnURL.hostname)
// يطبع xn--g6w251d

`url.password`

<string>

يحصل على جزء كلمة المرور من عنوان URL ويضبطه.

const myURL = new URL('https://abc:xyz')
console.log(myURL.password)
// يطبع xyz

myURL.password = '123'
console.log(myURL.href)
// يطبع https://abc:123@/

يتم ترميز النسبة المئوية لرموز عنوان URL غير الصالحة المضمنة في القيمة المُعيّنة لخاصية password. قد يختلف اختيار الرموز التي سيتم ترميز النسبة المئوية لها إلى حد ما عما تنتجه طرق url.parse() وurl.format().

`url.pathname`

<string>

يحصل على جزء المسار من عنوان URL ويضبطه.

const myURL = new URL('https://example.org/abc/xyz?123')
console.log(myURL.pathname)
// يطبع /abc/xyz

myURL.pathname = '/abcdef'
console.log(myURL.href)
// يطبع https://example.org/abcdef?123

يتم ترميز النسبة المئوية لرموز عنوان URL غير الصالحة المضمنة في القيمة المُعيّنة لخاصية pathname. قد يختلف اختيار الرموز التي سيتم ترميز النسبة المئوية لها إلى حد ما عما تنتجه طرق url.parse() وurl.format().

`url.port`

[History]

الإصدار	التغييرات
v15.0.0	لم يعد مخطط "gopher" خاصًا.

<string>

يحصل على ويُعيّن جزء المنفذ من عنوان URL.

قد تكون قيمة المنفذ رقمًا أو سلسلة تحتوي على رقم في النطاق 0 إلى 65535 (ضمنيًا). سيؤدي تعيين القيمة إلى منفذ افتراضي لأشياء URL التي تم إعطاؤها protocol إلى جعل قيمة port سلسلة فارغة ('').

يمكن أن تكون قيمة المنفذ سلسلة فارغة، وفي هذه الحالة يعتمد المنفذ على البروتوكول/المخطط:

البروتوكول	المنفذ
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443

عند تعيين قيمة للمنفذ، سيتم تحويل القيمة أولاً إلى سلسلة باستخدام .toString().

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

const myURL = new URL('https://example.org:8888')
console.log(myURL.port)
// يطبع 8888

// يتم تحويل المنافذ الافتراضية تلقائيًا إلى سلسلة فارغة
// (المنفذ الافتراضي لبروتوكول HTTPS هو 443)
myURL.port = '443'
console.log(myURL.port)
// يطبع سلسلة فارغة
console.log(myURL.href)
// يطبع https://example.org/

myURL.port = 1234
console.log(myURL.port)
// يطبع 1234
console.log(myURL.href)
// يطبع https://example.org:1234/

// يتم تجاهل سلاسل المنافذ غير الصالحة تمامًا
myURL.port = 'abcd'
console.log(myURL.port)
// يطبع 1234

// يتم التعامل مع الأرقام الرئيسية كرقم منفذ
myURL.port = '5678abcd'
console.log(myURL.port)
// يطبع 5678

// يتم اقتطاع الأعداد غير الصحيحة
myURL.port = 1234.5678
console.log(myURL.port)
// يطبع 1234

// سيتم تجاهل الأرقام خارج النطاق التي لا تُمثَّل في تدوين علمي.
myURL.port = 1e10 // 10000000000، سيتم فحص النطاق كما هو موضح أدناه
console.log(myURL.port)
// يطبع 1234

الأرقام التي تحتوي على نقطة عشرية، مثل الأعداد العائمة أو الأعداد في التدوين العلمي، ليست استثناءً لهذه القاعدة. سيتم تعيين الأرقام الرئيسية حتى النقطة العشرية كمنفذ لـ URL، بافتراض أنها صالحة:

myURL.port = 4.567e21
console.log(myURL.port)
// يطبع 4 (لأنه الرقم الرئيسي في السلسلة '4.567e21')

`url.protocol`

<string>

يحصل على ويُعيّن جزء بروتوكول عنوان URL.

const myURL = new URL('https://example.org')
console.log(myURL.protocol)
// يطبع https:

myURL.protocol = 'ftp'
console.log(myURL.href)
// يطبع ftp://example.org/

يتم تجاهل قيم بروتوكول عنوان URL غير الصالحة المعينة لخاصية protocol.

مخططات خاصة

[History]

الإصدار	التغييرات
v15.0.0	لم يعد المخطط "gopher" خاصًا.

يُعتبر معيار WHATWG URL عددًا قليلاً من مخططات بروتوكول عنوان URL خاصة من حيث كيفية تحليلها وتسلسلها. عندما يتم تحليل عنوان URL باستخدام أحد هذه البروتوكولات الخاصة، قد يتم تغيير خاصية url.protocol إلى بروتوكول خاص آخر، ولكن لا يمكن تغييرها إلى بروتوكول غير خاص، والعكس صحيح.

على سبيل المثال، يعمل التغيير من http إلى https:

const u = new URL('http://example.org')
u.protocol = 'https'
console.log(u.href)
// https://example.org/

ومع ذلك، فإن التغيير من http إلى بروتوكول افتراضي fish لا يعمل لأن البروتوكول الجديد ليس خاصًا.

const u = new URL('http://example.org')
u.protocol = 'fish'
console.log(u.href)
// http://example.org/

وبالمثل، لا يُسمح أيضًا بتغيير البروتوكول من بروتوكول غير خاص إلى بروتوكول خاص:

const u = new URL('fish://example.org')
u.protocol = 'http'
console.log(u.href)
// fish://example.org

وفقًا لمعيار WHATWG URL، فإن مخططات البروتوكول الخاصة هي ftp، وfile، وhttp، وhttps، وws، وwss.

`url.search`

<string>

يحصل على ويُعيّن الجزء المُسلسل للاستعلام من عنوان URL.

const myURL = new URL('https://example.org/abc?123')
console.log(myURL.search)
// يطبع ?123

myURL.search = 'abc=xyz'
console.log(myURL.href)
// يطبع https://example.org/abc?abc=xyz

أي أحرف عنوان URL غير صالحة تظهر في القيمة المعينة لخاصية search سيتم ترميزها بنسبة مئوية. قد يختلف اختيار الأحرف التي يجب ترميزها بنسبة مئوية إلى حد ما عما تنتجه طرق url.parse() وurl.format().

`url.searchParams`

<URLSearchParams>

يحصل على كائن URLSearchParams الذي يمثل معلمات الاستعلام لعنوان URL. هذه الخاصية للقراءة فقط، ولكن يمكن استخدام كائن URLSearchParams الذي يوفره لتغيير مثيل URL؛ لاستبدال معلمات استعلام URL بالكامل، استخدم مُعيّن url.search. راجع وثائق URLSearchParams للحصول على التفاصيل.

استخدم الحذر عند استخدام .searchParams لتعديل URL لأنه، وفقًا لمواصفات WHATWG، يستخدم كائن URLSearchParams قواعد مختلفة لتحديد الأحرف التي يجب ترميزها بنسبة مئوية. على سبيل المثال، لن يقوم كائن URL بترميز حرف التيلدا ASCII (~) بنسبة مئوية، بينما سيقوم URLSearchParams دائمًا بترميزه:

const myURL = new URL('https://example.org/abc?foo=~bar')

console.log(myURL.search) // يطبع ?foo=~bar

// تعديل URL عبر searchParams...
myURL.searchParams.sort()

console.log(myURL.search) // يطبع ?foo=%7Ebar

`url.username`

<string>

يحصل على جزء اسم المستخدم من عنوان URL ويضبطه.

const myURL = new URL('https://abc:')
console.log(myURL.username)
// يطبع abc

myURL.username = '123'
console.log(myURL.href)
// يطبع https://123:/

سيتم ترميز أي أحرف URL غير صالحة تظهر في القيمة المُعيّنة لخاصية username بنسبة مئوية. قد يختلف اختيار الأحرف التي يجب ترميزها بنسبة مئوية إلى حد ما عما تنتجه طرق url.parse() و url.format().

`url.toString()`

الإرجاع: <string>

ترجع طريقة toString() على كائن URL عنوان URL المُسلسل. القيمة المُرجعة تعادل قيمة url.href و url.toJSON().

`url.toJSON()`

أضيف في: v7.7.0، v6.13.0

المُرجَع: <string>

ترجع طريقة toJSON() في كائن URL عنوان URL مُسلسل. القيمة المُرجعة تُعادل قيمة url.href و url.toString().

تُستدعى هذه الطريقة تلقائيًا عندما يتم تسلسل كائن URL باستخدام JSON.stringify().

const myURLs = [new URL('https://www.example.com'), new URL('https://test.example.org')]
console.log(JSON.stringify(myURLs))
// يُطبع ["https://www.example.com/","https://test.example.org/"]

`URL.createObjectURL(blob)`

أضيف في: v16.7.0

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

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

blob <Blob>
المُرجَع: <string>

يُنشئ سلسلة عنوان URL من نوع 'blob:nodedata:...' تمثل كائن <Blob> المُعطى، ويمكن استخدامها لاسترداد Blob لاحقًا.

const { Blob, resolveObjectURL } = require('node:buffer')

const blob = new Blob(['hello'])
const id = URL.createObjectURL(blob)

// لاحقًا...

const otherBlob = resolveObjectURL(id)
console.log(otherBlob.size)

سيتم الاحتفاظ بالبيانات المخزنة بواسطة <Blob> المُسجل في الذاكرة حتى يتم استدعاء URL.revokeObjectURL() لإزالتها.

يتم تسجيل كائنات Blob ضمن مؤشر الترابط الحالي. في حالة استخدام مؤشرات ترابط عامل، لن تكون كائنات Blob المُسجلة ضمن عامل واحد متاحة للعاملين الآخرين أو المؤشر الرئيسي.

`URL.revokeObjectURL(id)`

أضيف في: v16.7.0

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

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

id <string> سلسلة عنوان URL من نوع 'blob:nodedata:... مُرجعة من مكالمة سابقة لـ URL.createObjectURL().

يزيل <Blob> المُخزّن المُحدد بواسطة المعرف المُعطى. ستفشل محاولة إلغاء معرف غير مسجل بصمت.

`URL.canParse(input[, base])`

مُضاف في: v19.9.0، v18.17.0

input <string> عنوان URL المدخل المطلق أو النسبي للتحليل. إذا كان input نسبيًا، فيجب استخدام base. إذا كان input مطلقًا، يتم تجاهل base. إذا لم يكن input سلسلة نصية، فسيتم تحويله إلى سلسلة نصية أولاً.
base <string> عنوان URL الأساسي للتحليل ضده إذا لم يكن input مطلقًا. إذا لم يكن base سلسلة نصية، فسيتم تحويله إلى سلسلة نصية أولاً.
القيمة المُرجعة: <boolean>

يتحقق مما إذا كان بإمكان تحليل input بالنسبة إلى base إلى URL.

const isValid = URL.canParse('/foo', 'https://example.org/') // true

const isNotValid = URL.canParse('/foo') // false

`URL.parse(input[, base])`

مُضاف في: v22.1.0

input <string> عنوان URL المدخل المطلق أو النسبي للتحليل. إذا كان input نسبيًا، فيجب استخدام base. إذا كان input مطلقًا، يتم تجاهل base. إذا لم يكن input سلسلة نصية، فسيتم تحويله إلى سلسلة نصية أولاً.
base <string> عنوان URL الأساسي للتحليل ضده إذا لم يكن input مطلقًا. إذا لم يكن base سلسلة نصية، فسيتم تحويله إلى سلسلة نصية أولاً.
القيمة المُرجعة: <URL> | <null>

يحلل سلسلة نصية كـ URL. إذا تم توفير base، فسيتم استخدامه كعنوان URL الأساسي لغرض حل عناوين URL input غير المطلقة. يُرجع null إذا لم يكن input صالحًا.

الصنف: `URLSearchParams`

[السجل]

الإصدار	التغييرات
v10.0.0	أصبح هذا الصنف متاحًا الآن على الكائن العام.
v7.5.0, v6.13.0	تمت الإضافة في: v7.5.0, v6.13.0

يوفر واجهة برمجة التطبيقات URLSearchParams إمكانية القراءة والكتابة لاستعلام URL. يمكن أيضًا استخدام فئة URLSearchParams بشكل مستقل باستخدام أحد مُنشئي الأربعة التالية. تتوفر فئة URLSearchParams أيضًا على الكائن العام.

تتمتع واجهة URLSearchParams من WHATWG ووحدة querystring بغرض مشابه، لكن غرض وحدة querystring أكثر عمومية، حيث تسمح بتخصيص أحرف الفاصلة (& و =). من ناحية أخرى، تم تصميم واجهة برمجة التطبيقات هذه خصيصًا لسلاسل استعلامات URL.

const myURL = new URL('https://example.org/?abc=123')
console.log(myURL.searchParams.get('abc'))
// يطبع 123

myURL.searchParams.append('abc', 'xyz')
console.log(myURL.href)
// يطبع https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc')
myURL.searchParams.set('a', 'b')
console.log(myURL.href)
// يطبع https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams)
// ما سبق يعادل
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c')
console.log(myURL.href)
// يطبع https://example.org/?a=b
console.log(newSearchParams.toString())
// يطبع a=b&a=c

// يتم استدعاء newSearchParams.toString() ضمنيًا
myURL.search = newSearchParams
console.log(myURL.href)
// يطبع https://example.org/?a=b&a=c
newSearchParams.delete('a')
console.log(myURL.href)
// يطبع https://example.org/?a=b&a=c

`new URLSearchParams()`

إنشاء كائن URLSearchParams فارغ جديد.

`new URLSearchParams(string)`

string <string> سلسلة استعلام

تحليل string كسلسلة استعلام، واستخدامه لإنشاء كائن URLSearchParams جديد. يتم تجاهل علامة '?' الرائدة، إذا كانت موجودة.

let params

params = new URLSearchParams('user=abc&query=xyz')
console.log(params.get('user'))
// يطبع 'abc'
console.log(params.toString())
// يطبع 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz')
console.log(params.toString())
// يطبع 'user=abc&query=xyz'

`new URLSearchParams(obj)`

أضيف في: v7.10.0، v6.13.0

obj <Object> كائن يمثل مجموعة من أزواج المفتاح-القيمة

إنشاء كائن URLSearchParams جديد باستخدام خريطة هاش الاستعلام. يتم دائمًا تحويل مفتاح وقيمة كل خاصية من obj إلى سلاسل نصية.

على عكس وحدة querystring، لا يُسمح بوجود مفاتيح مكررة في شكل قيم مصفوفة. يتم تحويل المصفوفات إلى سلاسل نصية باستخدام array.toString()، والذي يقوم ببساطة بدمج جميع عناصر المصفوفة بفاصلات.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
})
console.log(params.getAll('query'))
// يطبع [ 'first,second' ]
console.log(params.toString())
// يطبع 'user=abc&query=first%2Csecond'

`new URLSearchParams(iterable)`

أضيف في: v7.10.0، v6.13.0

iterable <Iterable> كائن قابل للتكرار تكون عناصره أزواج مفتاح-قيمة

إنشاء كائن URLSearchParams جديد باستخدام خريطة قابلة للتكرار بطريقة مشابهة لمعامل إنشاء Map. يمكن أن يكون iterable مصفوفة أو أي كائن قابل للتكرار. هذا يعني أن iterable يمكن أن يكون URLSearchParams آخر، وفي هذه الحالة، سيقوم المُنشئ بإنشاء نسخة طبق الأصل من URLSearchParams المُقدّم. عناصر iterable هي أزواج مفتاح-قيمة، ويمكن أن تكون نفسها أي كائن قابل للتكرار.

يُسمح بوجود مفاتيح مكررة.

let params

// باستخدام مصفوفة
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// يطبع 'user=abc&query=first&query=second'

// باستخدام كائن Map
const map = new Map()
map.set('user', 'abc')
map.set('query', 'xyz')
params = new URLSearchParams(map)
console.log(params.toString())
// يطبع 'user=abc&query=xyz'

// باستخدام دالة مُولدة
function* getQueryPairs() {
  yield ['user', 'abc']
  yield ['query', 'first']
  yield ['query', 'second']
}
params = new URLSearchParams(getQueryPairs())
console.log(params.toString())
// يطبع 'user=abc&query=first&query=second'

// يجب أن يحتوي كل زوج مفتاح-قيمة على عنصرين بالضبط
new URLSearchParams([['user', 'abc', 'error']])
// يطرح TypeError [ERR_INVALID_TUPLE]:
//        يجب أن يكون كل زوج استعلام عبارة عن مجموعة قابلة للتكرار [الاسم، القيمة]

`urlSearchParams.append(name, value)`

name <string>
value <string>

إضافة زوج جديد من اسم وقيمة إلى سلسلة الاستعلام.

`urlSearchParams.delete(name[, value])`

[History]

الإصدار	التغييرات
v20.2.0, v18.18.0	إضافة دعم للحجة `value` الاختيارية.

name <string>
value <string>

إذا تم توفير value، فسيتم إزالة جميع أزواج اسم/قيمة حيث يكون الاسم هو name والقيمة هي value.

إذا لم يتم توفير value، فسيتم إزالة جميع أزواج اسم/قيمة التي يكون اسمها هو name.

`urlSearchParams.entries()`

القيمة المرجعة: <Iterator>

يرجع مُكرر ES6 لكل من أزواج الاسم/القيمة في الاستعلام. كل عنصر من عناصر المُكرر هو مصفوفة جافا سكريبت. العنصر الأول من المصفوفة هو name، والعنصر الثاني من المصفوفة هو value.

مرادف لـ urlSearchParams[@@iterator]().

`urlSearchParams.forEach(fn[, thisArg])`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُنعطف غير صالح إلى وسيطة `fn` الآن إلى طرح `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.

fn <Function> يتم استدعاء هذه الدالة لكل زوج من اسم وقيمة في الاستعلام.
thisArg <Object> لاستخدامه كقيمة this عندما يتم استدعاء fn.

يُكرر فوق كل زوج اسم/قيمة في الاستعلام ويستدعي الدالة المعطاة.

const myURL = new URL('https://example.org/?a=b&c=d')
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams)
})
// يُطبع:
//   a b true
//   c d true

`urlSearchParams.get(name)`

name <string>
قيمة الإرجاع: <string> | <null> سلسلة نصية أو null إذا لم يكن هناك زوج اسم-قيمة باسم name المعطى.

يرجع قيمة أول زوج اسم-قيمة يكون اسمه name. إذا لم تكن هناك أزواج من هذا القبيل، يتم إرجاع null.

`urlSearchParams.getAll(name)`

name <string>
قيمة الإرجاع: <string[]>

يرجع قيم جميع أزواج اسم-قيمة يكون اسمها name. إذا لم تكن هناك أزواج من هذا القبيل، يتم إرجاع مصفوفة فارغة.

`urlSearchParams.has(name[, value])`

[السجل]

الإصدار	التغييرات
v20.2.0, v18.18.0	إضافة دعم للحجة `value` الاختيارية.

name <string>
value <string>
قيمة الإرجاع: <boolean>

يتحقق مما إذا كان كائن URLSearchParams يحتوي على زوج(أزواج) مفتاح-قيمة بناءً على name وحجة value الاختيارية.

إذا تم توفير value، يتم إرجاع true عندما يوجد زوج اسم-قيمة بنفس name و value.

إذا لم يتم توفير value، يتم إرجاع true إذا كان هناك زوج اسم-قيمة واحد على الأقل يكون اسمه name.

`urlSearchParams.keys()`

قيمة الإرجاع: <Iterator>

يرجع مُكرر ES6 على أسماء كل زوج اسم-قيمة.

const params = new URLSearchParams('foo=bar&foo=baz')
for (const name of params.keys()) {
  console.log(name)
}
// يطبع:
//   foo
//   foo

`urlSearchParams.set(name, value)`

name <string>
value <string>

يُعيّن القيمة في كائن URLSearchParams المرتبط بـ name إلى value. إذا كانت هناك أي أزواج اسم-قيمة موجودة مسبقًا أسماؤها هي name، فعيّن قيمة الزوج الأول من هذا النوع إلى value وأزل جميع الأزواج الأخرى. وإلا، أضف زوج الاسم والقيمة إلى سلسلة الاستعلام.

const params = new URLSearchParams()
params.append('foo', 'bar')
params.append('foo', 'baz')
params.append('abc', 'def')
console.log(params.toString())
// Prints foo=bar&foo=baz&abc=def

params.set('foo', 'def')
params.set('xyz', 'opq')
console.log(params.toString())
// Prints foo=def&abc=def&xyz=opq

`urlSearchParams.size`

مضاف في: v19.8.0، v18.16.0

العدد الإجمالي لإدخالات المعلمة.

`urlSearchParams.sort()`

مضاف في: v7.7.0، v6.13.0

رتّب جميع أزواج الاسم والقيمة الموجودة في المكان بواسطة أسمائها. يتم الترتيب باستخدام خوارزمية فرز مستقرة، لذلك يتم الحفاظ على الترتيب النسبي بين أزواج الاسم والقيمة التي لها نفس الاسم.

يمكن استخدام هذه الطريقة، على وجه الخصوص، لزيادة عمليات الوصول إلى ذاكرة التخزين المؤقت.

const params = new URLSearchParams('query[]=abc&type=search&query[]=123')
params.sort()
console.log(params.toString())
// Prints query%5B%5D=abc&query%5B%5D=123&type=search

`urlSearchParams.toString()`

الإرجاع: <string>

يرجع معلمات البحث المُسلسلة كسلسلة، مع ترميز الأحرف بنسبة مئوية عند الضرورة.

`urlSearchParams.values()`

الإرجاع: <Iterator>

يرجع مُكرّر ES6 على قيم كل زوج اسم-قيمة.

`urlSearchParams[Symbol.iterator]()`

مُرجِع: <Iterator>

يُرجِع مُكرِّر ES6 لكل زوج من اسم القيمة في سلسلة الاستعلام. كل عنصر من المُكرِّر هو مصفوفة جافا سكريبت. العنصر الأول من المصفوفة هو الاسم، والعنصر الثاني من المصفوفة هو القيمة.

مُرادف لـ urlSearchParams.entries().

const params = new URLSearchParams('foo=bar&xyz=baz')
for (const [name, value] of params) {
  console.log(name, value)
}
// يُطبع:
//   foo bar
//   xyz baz

`url.domainToASCII(domain)`

[History]

الإصدار	التغييرات
v20.0.0, v18.17.0	تم إزالة متطلبات ICU.
v7.4.0, v6.13.0	تمت الإضافة في: v7.4.0, v6.13.0

domain <string>
مُرجِع: <string>

يُرجِع تسلسل ASCII لـ Punycode لـ domain. إذا كان domain مجالًا غير صالح، فسيتم إرجاع سلسلة فارغة.

يقوم بعملية عكسية لـ url.domainToUnicode().

ESMCJS

import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// يُطبع xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// يُطبع xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// يُطبع سلسلة فارغة

const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// يُطبع xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// يُطبع xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// يُطبع سلسلة فارغة

`url.domainToUnicode(domain)`

[History]

الإصدار	التغييرات
v20.0.0, v18.17.0	تم إزالة متطلبات ICU.
v7.4.0, v6.13.0	تمت الإضافة في: v7.4.0, v6.13.0

domain <string>
مُرجِع: <string>

يُرجِع تسلسل Unicode لـ domain. إذا كان domain مجالًا غير صالح، فسيتم إرجاع سلسلة فارغة.

يقوم بعملية عكسية لـ url.domainToASCII().

ESMCJS

import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// يُطبع español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// يُطبع 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// يُطبع سلسلة فارغة

const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// يُطبع español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// يُطبع 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// يُطبع سلسلة فارغة

`url.fileURLToPath(url[, options])`

[History]

الإصدار	التغييرات
v22.1.0, v20.13.0	يمكن الآن استخدام وسيطة `options` لتحديد كيفية تحليل وسيطة `path`.
v10.12.0	تمت الإضافة في: v10.12.0

url <URL> | <string> سلسلة عنوان URL للملف أو كائن URL لتحويله إلى مسار.
options <Object>
- windows <boolean> | <undefined> true إذا كان يجب إرجاع path كمسار ملف Windows، false لـ posix، و undefined لافتراضي النظام. الافتراضي: undefined.
الإرجاع: <string> مسار ملف Node.js محدد بالكامل حسب النظام الأساسي.

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

ESMCJS

import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // غير صحيح: /C:/path/
fileURLToPath('file:///C:/path/') // صحيح:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // غير صحيح: /foo.txt
fileURLToPath('file://nas/foo.txt') // صحيح:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // غير صحيح: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // صحيح:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // غير صحيح: /hello%20world
fileURLToPath('file:///hello world') // صحيح:   /hello world (POSIX)

const { fileURLToPath } = require('node:url')
new URL('file:///C:/path/').pathname // غير صحيح: /C:/path/
fileURLToPath('file:///C:/path/') // صحيح:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // غير صحيح: /foo.txt
fileURLToPath('file://nas/foo.txt') // صحيح:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // غير صحيح: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // صحيح:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // غير صحيح: /hello%20world
fileURLToPath('file:///hello world') // صحيح:   /hello world (POSIX)

`url.format(URL[, options])`

أضيف في: v7.6.0

URL <URL> كائن WHATWG URL
options <Object>
- auth <boolean> true إذا كان سلسلة عنوان URL المُسلسلة يجب أن تتضمن اسم المستخدم وكلمة المرور، false خلاف ذلك. الافتراضي: true.
- fragment <boolean> true إذا كان سلسلة عنوان URL المُسلسلة يجب أن تتضمن الجزء المُجزأ، false خلاف ذلك. الافتراضي: true.
- search <boolean> true إذا كان سلسلة عنوان URL المُسلسلة يجب أن تتضمن استعلام البحث، false خلاف ذلك. الافتراضي: true.
- unicode <boolean> true إذا كانت أحرف Unicode التي تظهر في مُكون المضيف لسلسلة عنوان URL يجب أن تُشفر مباشرةً بدلاً من أن تُشفر باستخدام Punycode. الافتراضي: false.
الإرجاع: <string>

يُرجع تسلسلاً قابلاً للتخصيص لتمثيل سلسلة String لعنوان URL لكائن WHATWG URL.

يحتوي كائن URL على كل من طريقة toString() وخاصية href اللتان تُعيدان تسلسلات سلسلة لعنوان URL. ومع ذلك، هذه ليست قابلة للتخصيص بأي شكل من الأشكال. تسمح طريقة url.format(URL[, options]) بالتخصيص الأساسي للمخرجات.

ESMCJS

import url from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// Prints 'https://測試/?abc'

const url = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// Prints 'https://測試/?abc'

`url.pathToFileURL(path[, options])`

[History]

الإصدار	التغييرات
v22.1.0, v20.13.0	يمكن الآن استخدام وسيطة `options` لتحديد كيفية إرجاع قيمة `path`.
v10.12.0	تمت الإضافة في: v10.12.0

path <string> المسار الذي سيتم تحويله إلى عنوان URL للملف.
options <Object>
- windows <boolean> | <undefined> true إذا كان يجب التعامل مع path كمسار ملفات Windows، وfalse لـ posix، وundefined لافتراضي النظام. الافتراضي: undefined.
الإرجاع: <URL> كائن عنوان URL الخاص بالملف.

تضمن هذه الدالة حل path بشكل مطلق، وتشفير أحرف التحكم في عنوان URL بشكل صحيح عند التحويل إلى عنوان URL الخاص بالملف.

ESMCJS

import { pathToFileURL } from 'node:url'

new URL('/foo#1', 'file:') // غير صحيح: file:///foo#1
pathToFileURL('/foo#1') // صحيح:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // غير صحيح: file:///some/path%.c
pathToFileURL('/some/path%.c') // صحيح:   file:///some/path%25.c (POSIX)

const { pathToFileURL } = require('node:url')
new URL(__filename) // غير صحيح: يرمي خطأ (POSIX)
new URL(__filename) // غير صحيح: C:\... (Windows)
pathToFileURL(__filename) // صحيح:   file:///... (POSIX)
pathToFileURL(__filename) // صحيح:   file:///C:/... (Windows)

new URL('/foo#1', 'file:') // غير صحيح: file:///foo#1
pathToFileURL('/foo#1') // صحيح:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // غير صحيح: file:///some/path%.c
pathToFileURL('/some/path%.c') // صحيح:   file:///some/path%25.c (POSIX)

`url.urlToHttpOptions(url)`

[History]

الإصدار	التغييرات
v19.9.0, v18.17.0	سيحتوي الكائن المُرجَع أيضًا على جميع خصائص `url` الخاصة القابلة للعد.
v15.7.0, v14.18.0	تمت الإضافة في: v15.7.0, v14.18.0

url <URL> كائن WHATWG URL لتحويله إلى كائن خيارات.
القيمة المُرجعة: <Object> كائن الخيارات
- protocol <string> بروتوكول للاستخدام.
- hostname <string> اسم نطاق أو عنوان IP للخادم لإرسال الطلب إليه.
- hash <string> جزء التجزئة من عنوان URL.
- search <string> الجزء المُسلسل من الاستعلام لعنوان URL.
- pathname <string> جزء المسار من عنوان URL.
- path <string> مسار الطلب. يجب أن يتضمن سلسلة الاستعلام إن وجدت. مثال: '/index.html?page=12'. يتم طرح استثناء عندما يحتوي مسار الطلب على أحرف غير قانونية. حاليًا، يتم رفض المسافات فقط، ولكن قد يتغير ذلك في المستقبل.
- href <string> عنوان URL المُسلسل.
- port <number> منفذ الخادم البعيد.
- auth <string> المصادقة الأساسية أي 'user:password' لحساب رأس Authorization.

هذه الدالة المساعدة تحوّل كائن URL إلى كائن خيارات عادي كما هو متوقع من واجهات برمجة التطبيقات http.request() و https.request().

ESMCJS

import { urlToHttpOptions } from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

const { urlToHttpOptions } = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

واجهة برمجة التطبيقات لـ URL القديمة

[السجل]

الإصدار	التغييرات
v15.13.0، v14.17.0	تم إلغاء إزالة الإصدار. تم تغيير الحالة إلى "قديم".
v11.0.0	تم إزالة هذه واجهة برمجة التطبيقات.

[مستقر: 3 - قديم]

مستقر: 3 الاستقرار: 3 - قديم: استخدم واجهة برمجة تطبيقات WHATWG URL بدلاً من ذلك.

`urlObject` القديمة

[السجل]

الإصدار	التغييرات
v15.13.0، v14.17.0	تم إلغاء إزالة الإصدار. تم تغيير الحالة إلى "قديم".
v11.0.0	تم إزالة واجهة برمجة التطبيقات URL القديمة. استخدم واجهة برمجة تطبيقات WHATWG URL.

[مستقر: 3 - قديم]

مستقر: 3 الاستقرار: 3 - قديم: استخدم واجهة برمجة تطبيقات WHATWG URL بدلاً من ذلك.

يتم إنشاء urlObject القديمة (require('node:url').Url أو import { Url } from 'node:url') وإرجاعها بواسطة دالة url.parse().

`urlObject.auth`

خاصية auth هي جزء اسم المستخدم وكلمة المرور من عنوان URL، ويشار إليها أيضًا باسم معلومات المستخدم. تتبع هذه المجموعة الفرعية من السلسلة protocol والشرطتين المائلتين (إذا وجدتا) وتسبق مكون host، مفصولة بـ @. السلسلة هي إما اسم المستخدم، أو هي اسم المستخدم وكلمة المرور مفصولة بـ :.

مثال: 'user:pass'.

`urlObject.hash`

خاصية hash هي جزء معرف جزء من عنوان URL بما في ذلك حرف # الرئيسي.

مثال: '#hash'.

`urlObject.host`

خاصية host هي جزء المضيف الكامل بحروف صغيرة من عنوان URL، بما في ذلك port إذا تم تحديده.

مثال: 'sub.example.com:8080'.

`urlObject.hostname`

خاصية hostname هي اسم المضيف بحروف صغيرة من مكون host بدون تضمين port.

مثال: 'sub.example.com'.

`urlObject.href`

خاصية href هي سلسلة عنوان URL الكاملة التي تم تحليلها مع تحويل كل من مكوني protocol و host إلى أحرف صغيرة.

مثال: 'http://user:[email protected]:8080/p/a/t/h?query=string#hash'.

`urlObject.path`

خاصية path هي سلسلة من مكونات pathname و search.

مثال: '/p/a/t/h?query=string'.

لا يتم فك تشفير path.

`urlObject.pathname`

تتكون خاصية pathname من قسم المسار بالكامل لعنوان URL. هذا هو كل ما يلي host (بما في ذلك port) وقبل بداية مكونات query أو hash, مفصولة إما بعلامة استفهام ASCII (?) أو علامة التصنيف (#).

مثال: '/p/a/t/h'.

لا يتم فك تشفير سلسلة المسار.

`urlObject.port`

خاصية port هي جزء المنفذ العددي من مكون host.

مثال: '8080'.

`urlObject.protocol`

خاصية protocol تحدد مخطط بروتوكول عنوان URL بحروف صغيرة.

مثال: 'http:'.

`urlObject.query`

خاصية query هي إما سلسلة الاستعلام بدون علامة استفهام ASCII الرائدة (?), أو كائن تم إرجاعه بواسطة طريقة parse() لوحدة querystring. يتم تحديد ما إذا كانت خاصية query سلسلة أو كائنًا بواسطة وسيطة parseQueryString التي تم تمريرها إلى url.parse().

مثال: 'query=string' أو {'query': 'string'}.

إذا تم إرجاعها كسلسلة، فلن يتم فك تشفير سلسلة الاستعلام. إذا تم إرجاعها ككائن، فسيتم فك تشفير المفاتيح والقيم على حد سواء.

`urlObject.search`

تتكون خاصية search من جزء "سلسلة الاستعلام" بالكامل لعنوان URL، بما في ذلك حرف علامة الاستفهام ASCII الرائدة (?).

مثال: '?query=string'.

لا يتم فك تشفير سلسلة الاستعلام.

`urlObject.slashes`

خاصية slashes هي قيمة من نوع boolean بقيمة true إذا كانت هناك حاجة إلى حرفي شرطة مائلة للأمام ASCII (/) بعد النقطتين في protocol.

`url.format(urlObject)`

[السجل]

الإصدار	التغييرات
v17.0.0	يلقي الآن باستثناء `ERR_INVALID_URL` عندما يؤدي تحويل Punycode لاسم المضيف إلى تغييرات يمكن أن تتسبب في إعادة تحليل عنوان URL بشكل مختلف.
v15.13.0, v14.17.0	تم إلغاء الإنهاء. تم تغيير الحالة إلى "إرث".
v11.0.0	تم إهمال واجهة برمجة تطبيقات URL القديمة. استخدم واجهة برمجة تطبيقات URL WHATWG.
v7.0.0	ستستخدم عناوين URL التي تحتوي على مخطط `file:` دائمًا عددًا صحيحًا من الشرطة المائلة بغض النظر عن خيار `slashes`. يتم احترام خيار `slashes` الكاذب بدون بروتوكول في جميع الأوقات.
v0.1.25	تمت الإضافة في: v0.1.25

[مستقر: 3 - إرث]

مستقر: 3 الثبات: 3 - إرث: استخدم واجهة برمجة تطبيقات URL WHATWG بدلاً من ذلك.

urlObject <Object> | <string> كائن URL (كما تم إرجاعه بواسطة url.parse() أو تم إنشاؤه بطريقة أخرى). إذا كانت سلسلة، فسيتم تحويلها إلى كائن عن طريق تمريرها إلى url.parse().

ترجع طريقة url.format() سلسلة عنوان URL تم تنسيقها مشتقة من urlObject.

const url = require('node:url')
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json',
  },
})

// => 'https://example.com/some/path?page=1&format=json'

إذا لم يكن urlObject كائنًا أو سلسلة، فسوف تلقي url.format() بـ TypeError.

عملية التنسيق تعمل على النحو التالي:

يتم إنشاء سلسلة فارغة جديدة result.
إذا كانت urlObject.protocol سلسلة، فسيتم إلحاقها كما هي إلى result.
خلاف ذلك، إذا لم تكن urlObject.protocol undefined ولم تكن سلسلة، فسيتم إلقاء Error.
بالنسبة لجميع القيم السلسلية لـ urlObject.protocol التي لا تنتهي بحرف نقطتين ASCII (:)، سيتم إلحاق السلسلة الحرفية : إلى result.
إذا كان أي من الشرطين التاليين صحيحًا، فسيتم إلحاق السلسلة الحرفية // إلى result:
- خاصية urlObject.slashes صحيحة؛
- تبدأ urlObject.protocol بـ http، أو https، أو ftp، أو gopher، أو file؛
إذا كانت قيمة خاصية urlObject.auth صحيحة، وإما urlObject.host أو urlObject.hostname ليست undefined، فسيتم إجبار قيمة urlObject.auth على سلسلة وإلحاقها بـ result متبوعة بالسلسلة الحرفية @.
إذا كانت خاصية urlObject.host هي undefined، فإنه:
- إذا كان urlObject.hostname سلسلة، فسيتم إلحاقها بـ result.
- خلاف ذلك، إذا لم تكن urlObject.hostname undefined ولم تكن سلسلة، فسيتم إلقاء Error.
- إذا كانت قيمة خاصية urlObject.port صحيحة، و urlObject.hostname ليست undefined:
- سيتم إلحاق السلسلة الحرفية : بـ result، و
- سيتم إجبار قيمة urlObject.port على سلسلة وإلحاقها بـ result.
خلاف ذلك، إذا كانت قيمة خاصية urlObject.host صحيحة، فسيتم إجبار قيمة urlObject.host على سلسلة وإلحاقها بـ result.
إذا كانت خاصية urlObject.pathname سلسلة وليست سلسلة فارغة:
- إذا كانت urlObject.pathname لا تبدأ بشرطة مائلة للأمام ASCII (/), فسيتم إلحاق السلسلة الحرفية '/' بـ result.
- سيتم إلحاق قيمة urlObject.pathname بـ result.
خلاف ذلك، إذا لم تكن urlObject.pathname undefined ولم تكن سلسلة، فسيتم إلقاء Error.
إذا كانت خاصية urlObject.search هي undefined وإذا كانت خاصية urlObject.query كائنًا، فسيتم إلحاق السلسلة الحرفية ? بـ result متبوعة بمخرجات استدعاء طريقة stringify() لوحدة querystring بتمرير قيمة urlObject.query.
خلاف ذلك، إذا كانت urlObject.search سلسلة:
- إذا كانت قيمة urlObject.search لا تبدأ بحرف علامة الاستفهام ASCII (?)، فسيتم إلحاق السلسلة الحرفية ? بـ result.
- سيتم إلحاق قيمة urlObject.search بـ result.
خلاف ذلك، إذا لم تكن urlObject.search undefined ولم تكن سلسلة، فسيتم إلقاء Error.
إذا كانت خاصية urlObject.hash سلسلة:
- إذا كانت قيمة urlObject.hash لا تبدأ بعلامة التصنيف ASCII (#)، فسيتم إلحاق السلسلة الحرفية # بـ result.
- سيتم إلحاق قيمة urlObject.hash بـ result.
خلاف ذلك، إذا لم تكن خاصية urlObject.hash undefined ولم تكن سلسلة، فسيتم إلقاء Error.
يتم إرجاع result.

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

[السجل]

الإصدار	التغييرات
v19.0.0، v18.13.0	إهمال في الوثائق فقط.
v15.13.0، v14.17.0	تم إلغاء الإهمال. تغيرت الحالة إلى "قديم".
v11.14.0	خاصية `pathname` في كائن URL المُرجَع هي الآن `/` عندما لا يوجد مسار ومخطط البروتوكول هو `ws:` أو `wss:`.
v11.0.0	تم إهمال واجهة برمجة التطبيقات القديمة لـ URL. استخدم واجهة برمجة تطبيقات WHATWG URL.
v9.0.0	خاصية `search` في كائن URL المُرجَع هي الآن `null` عندما لا يوجد سلسلة استعلام.
v0.1.25	تمت الإضافة في: v0.1.25

[مستقر: 0 - مُهمَل]

مستقر: 0 الثبات: 0 - مُهمَل: استخدم واجهة برمجة تطبيقات WHATWG URL بدلاً من ذلك.

urlString <سلسلة> سلسلة URL المراد تحليلها.
parseQueryString <منطقية> إذا كانت true، فسيتم دائمًا تعيين خاصية query إلى كائن مُرجَع بواسطة طريقة parse() من وحدة querystring. إذا كانت false، فستكون خاصية query في كائن URL المُرجَع سلسلة غير مُحللة وغير مُشفّرة. افتراضي: false.
slashesDenoteHost <منطقية> إذا كانت true، فسيتم تفسير الرمز الأول بعد السلسلة الحرفية // وقبل / التالية على أنه host. على سبيل المثال، بالنظر إلى //foo/bar، ستكون النتيجة {host: 'foo', pathname: '/bar'} بدلاً من {pathname: '//foo/bar'}. افتراضي: false.

تأخذ طريقة url.parse() سلسلة URL، وتحليلها، وتُرجِع كائن URL.

يتم إرسال TypeError إذا لم تكن urlString سلسلة.

يتم إرسال URIError إذا كانت خاصية auth موجودة ولكن لا يمكن فك تشفيرها.

تستخدم url.parse() خوارزمية مُتساهلة وغير قياسية لتحليل سلاسل URL. وهي عرضة لمشاكل أمنية مثل انتحال اسم المضيف والمعالجة غير الصحيحة لأسماء المستخدمين وكلمات المرور. لا تستخدمها مع الإدخال غير الموثوق. لا يتم إصدار CVEs لثغرات أمان url.parse(). استخدم واجهة برمجة تطبيقات WHATWG URL بدلاً من ذلك.

`url.resolve(from, to)`

[السجل]

الإصدار	التغييرات
v15.13.0، v14.17.0	تم إلغاء إبطال الاستخدام. تم تغيير الحالة إلى "قديم".
v11.0.0	تم إبطال استخدام واجهة برمجة التطبيقات القديمة لـ URL. استخدم واجهة برمجة تطبيقات WHATWG URL.
v6.6.0	يتم الآن الاحتفاظ بحقول `auth` سليمة عندما يشير `from` و `to` إلى نفس المضيف.
v6.0.0	يتم الآن مسح حقول `auth` إذا كانت المعلمة `to` تحتوي على اسم مضيف.
v6.5.0، v4.6.2	يتم الآن نسخ حقل `port` بشكل صحيح.
0.1.25	تمت الإضافة في: v0.1.25

[مستقر: 3 - قديم]

مستقر: 3 ثبات: 3 - قديم: استخدم واجهة برمجة تطبيقات WHATWG URL بدلاً من ذلك.

from <سلسلة> عنوان URL الأساسي الذي يجب استخدامه إذا كان to عنوان URL نسبيًا.
to <سلسلة> عنوان URL الهدف الذي يجب حله.

تقوم طريقة url.resolve() بحل عنوان URL الهدف بالنسبة لعنوان URL الأساسي بطريقة مشابهة لطريقة حل علامة الربط التشعبي في متصفح الويب.

const url = require('node:url')
url.resolve('/one/two/three', 'four') // '/one/two/four'
url.resolve('http://example.com/', '/one') // 'http://example.com/one'
url.resolve('http://example.com/one', '/two') // 'http://example.com/two'

لتحقيق نفس النتيجة باستخدام واجهة برمجة تطبيقات WHATWG URL:

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'))
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` هو عنوان URL نسبي.
    const { pathname, search, hash } = resolvedUrl
    return pathname + search + hash
  }
  return resolvedUrl.toString()
}

resolve('/one/two/three', 'four') // '/one/two/four'
resolve('http://example.com/', '/one') // 'http://example.com/one'
resolve('http://example.com/one', '/two') // 'http://example.com/two'

ترميز النسبة المئوية في عناوين URL

يُسمح لعناوين URL فقط باحتواء نطاق معين من الأحرف. يجب ترميز أي حرف يقع خارج هذا النطاق. تعتمد كيفية ترميز هذه الأحرف، والأحرف التي يجب ترميزها، كليًا على مكان وجود الحرف داخل بنية عنوان URL.

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

ضمن واجهة برمجة التطبيقات القديمة، سيتم إفلات المسافات (' ') والرموز التالية تلقائيًا في خصائص كائنات عنوان URL:

text

< > " ` \r \n \t { } | \ ^ '

على سبيل المثال، يتم ترميز رمز مسافة ASCII (' ') كـ %20. ويتم ترميز رمز الشرطة المائلة الأمامية ASCII (/) كـ %3C.

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

يستخدم معيار WHATWG لعنوان URL نهجًا أكثر انتقائية ودقة في اختيار الرموز المشفرة من ذلك المستخدم في واجهة برمجة التطبيقات القديمة.

تُعرّف خوارزمية WHATWG أربع "مجموعات ترميز بنسبة مئوية" تصف نطاقات الرموز التي يجب ترميزها بنسبة مئوية:

مجموعة ترميز النسبة المئوية للتحكم في C0: تتضمن نقاط التعليمات البرمجية في النطاق U+0000 إلى U+001F (شامل) وجميع نقاط التعليمات البرمجية الأكبر من U+007E (~).
مجموعة ترميز النسبة المئوية للجزء: تتضمن مجموعة ترميز النسبة المئوية للتحكم في C0 ونقاط التعليمات البرمجية U+0020 SPACE، U+0022 (")، U+003C (<)، U+003E (>)، و U+0060 (`).
مجموعة ترميز النسبة المئوية للمسار: تتضمن مجموعة ترميز النسبة المئوية للتحكم في C0 ونقاط التعليمات البرمجية U+0020 SPACE، U+0022 (")، U+0023 (#)، U+003C (<)، U+003E (>)، U+003F (?)، U+0060 (`)، U+007B ({)، و U+007D (}).
مجموعة ترميز المستخدم: تتضمن مجموعة ترميز النسبة المئوية للمسار ونقاط التعليمات البرمجية U+002F (/)، U+003A (😃، U+003B (😉، U+003D (=)، U+0040 (@)، U+005B ([) إلى U+005E(^)، و U+007C (|).

تُستخدم مجموعة ترميز المستخدم حصريًا لأسماء المستخدمين وكلمات المرور المشفرة ضمن عنوان URL. وتُستخدم مجموعة ترميز النسبة المئوية للمسار لمسار معظم عناوين URL. وتُستخدم مجموعة ترميز النسبة المئوية للجزء لأجزاء عنوان URL. وتُستخدم مجموعة ترميز النسبة المئوية للتحكم في C0 للمضيف والمسار في ظل ظروف معينة محددة، بالإضافة إلى جميع الحالات الأخرى.

عندما تظهر رموز غير ASCII ضمن اسم مضيف، يتم ترميز اسم المضيف باستخدام خوارزمية Punycode. ومع ذلك، لاحظ أن اسم المضيف قد يحتوي على كل من الرموز المشفرة Punycode والرموز المشفرة بنسبة مئوية:

const myURL = new URL('https://%CF%80.example.com/foo')
console.log(myURL.href)
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin)
// Prints https://xn--1xa.example.com

عنوان URL ​

سلاسل URL وكائنات URL ​

إنشاء عنوان URL من الأجزاء المكونة والحصول على السلسلة المُنشأة ​

واجهة برمجة تطبيقات WHATWG URL ​

فئة: URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

مخططات خاصة ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

الصنف: URLSearchParams ​

new URLSearchParams() ​

new URLSearchParams(string) ​

new URLSearchParams(obj) ​

new URLSearchParams(iterable) ​

urlSearchParams.append(name, value) ​

urlSearchParams.delete(name[, value]) ​

urlSearchParams.entries() ​

urlSearchParams.forEach(fn[, thisArg]) ​

urlSearchParams.get(name) ​

urlSearchParams.getAll(name) ​

urlSearchParams.has(name[, value]) ​

urlSearchParams.keys() ​

urlSearchParams.set(name, value) ​

urlSearchParams.size ​

urlSearchParams.sort() ​

urlSearchParams.toString() ​

urlSearchParams.values() ​

urlSearchParams[Symbol.iterator]() ​

url.domainToASCII(domain) ​

url.domainToUnicode(domain) ​

url.fileURLToPath(url[, options]) ​

url.format(URL[, options]) ​

url.pathToFileURL(path[, options]) ​

url.urlToHttpOptions(url) ​

واجهة برمجة التطبيقات لـ URL القديمة ​

urlObject القديمة ​

urlObject.auth ​

urlObject.hash ​

urlObject.host ​

urlObject.hostname ​

urlObject.href ​

urlObject.path ​

urlObject.pathname ​

urlObject.port ​

urlObject.protocol ​

urlObject.query ​

urlObject.search ​

urlObject.slashes ​

url.format(urlObject) ​

url.parse(urlString[, parseQueryString[, slashesDenoteHost]]) ​

url.resolve(from, to) ​

ترميز النسبة المئوية في عناوين URL ​

واجهة برمجة التطبيقات القديمة (Legacy API) ​

واجهة برمجة التطبيقات WHATWG ​

عنوان URL

سلاسل URL وكائنات URL

إنشاء عنوان URL من الأجزاء المكونة والحصول على السلسلة المُنشأة

واجهة برمجة تطبيقات WHATWG URL

فئة: `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

مخططات خاصة

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

`URL.canParse(input[, base])`

`URL.parse(input[, base])`

الصنف: `URLSearchParams`

`new URLSearchParams()`

`new URLSearchParams(string)`

`new URLSearchParams(obj)`

`new URLSearchParams(iterable)`

`urlSearchParams.append(name, value)`

`urlSearchParams.delete(name[, value])`

`urlSearchParams.entries()`

`urlSearchParams.forEach(fn[, thisArg])`

`urlSearchParams.get(name)`

`urlSearchParams.getAll(name)`

`urlSearchParams.has(name[, value])`

`urlSearchParams.keys()`

`urlSearchParams.set(name, value)`

`urlSearchParams.size`

`urlSearchParams.sort()`

`urlSearchParams.toString()`

`urlSearchParams.values()`

`urlSearchParams[Symbol.iterator]()`

`url.domainToASCII(domain)`

`url.domainToUnicode(domain)`

`url.fileURLToPath(url[, options])`

`url.format(URL[, options])`

`url.pathToFileURL(path[, options])`

`url.urlToHttpOptions(url)`

واجهة برمجة التطبيقات لـ URL القديمة

`urlObject` القديمة

`urlObject.auth`

`urlObject.hash`

`urlObject.host`

`urlObject.hostname`

`urlObject.href`

`urlObject.path`

`urlObject.pathname`

`urlObject.port`

`urlObject.protocol`

`urlObject.query`

`urlObject.search`

`urlObject.slashes`

`url.format(urlObject)`

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

`url.resolve(from, to)`

ترميز النسبة المئوية في عناوين URL

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

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