iDoc.dev

العربية

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
Русский

العربية

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
Русский

الوضع الداكن

عنوان URL ​

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

مستقر: 2 الاستقرار: 2 - مستقر

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

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

js
import url from 'node:url';
js
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() القديمة. يوجد أدناه خصائص كائن URL الخاص بـ WHATWG.

تتضمن خاصية 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 │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(يجب تجاهل جميع المسافات في سطر "". إنها فقط للتنسيق.)

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

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

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

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

بناء عنوان URL من الأجزاء المكونة والحصول على السلسلة التي تم إنشاؤها ​

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

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

للحصول على سلسلة عنوان URL التي تم إنشاؤها، استخدم أداة الوصول إلى الخاصية href:

js
console.log(myURL.href);

واجهة برمجة تطبيقات عنوان URL المتوافق مع معيار WHATWG ​

الصنف: URL ​

[السجل]

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

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

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

new URL(input[, base]) ​

[السجل]

الإصدارالتغييرات
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).

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

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

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

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

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

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

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

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

js
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 ​

يحصل ويضبط الجزء المجزأ من عنوان URL.

js
const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz

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

url.host ​

يحصل ويضبط جزء المضيف من عنوان URL.

js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo

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

url.hostname ​

يحصل ويضبط جزء اسم المضيف من عنوان URL. الفرق الرئيسي بين url.host و url.hostname هو أن url.hostname لا تتضمن المنفذ.

js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo

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

url.href ​

يحصل ويضبط عنوان URL المتسلسل.

js
const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar

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

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

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

url.origin ​

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

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

يحصل على التسلسل للقراءة فقط لأصل عنوان URL.

js
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// يطبع https://example.org
js
const idnURL = new URL('https://اختبار');
console.log(idnURL.origin);
// يطبع https://xn--g6w251d

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

url.password ​

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

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

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

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

url.pathname ​

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

js
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 ​

[تاريخ]

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

يحصل ويضبط جزء المنفذ من عنوان URL.

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

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

البروتوكولالمنفذ
"ftp"21
"file"
"http"80
"https"443
"ws"80
"wss"443
عند تعيين قيمة للمنفذ، سيتم أولاً تحويل القيمة إلى سلسلة باستخدام .toString().

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

js
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، على افتراض أنها صالحة:

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

url.protocol ​

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

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

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

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

المخططات الخاصة ​

[السجل]

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

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

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

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

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

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

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

js
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 ​

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

js
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 الذي يمثل معلمات الاستعلام الخاصة بعنوان URL. هذه الخاصية للقراءة فقط ولكن يمكن استخدام كائن URLSearchParams الذي توفره لتغيير مثيل URL؛ لاستبدال كامل معلمات الاستعلام الخاصة بعنوان URL، استخدم أداة تعيين url.search. راجع وثائق URLSearchParams للحصول على التفاصيل.

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

js
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 ​

يحصل ويعيّن جزء اسم المستخدم في عنوان URL.

js
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() ​

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

url.toJSON() ​

أضيف في: الإصدار 7.7.0، الإصدار 6.13.0

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

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

js
const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"]

URL.createObjectURL(blob) ​

أضيف في: الإصدار 16.7.0

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

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

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

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

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

// later...

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

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

يتم تسجيل كائنات Blob داخل سلسلة العمليات الحالية. في حالة استخدام سلاسل عمليات Worker، لن تكون كائنات Blob المسجلة داخل Worker واحد متاحة لعمال آخرين أو لسلسلة العمليات الرئيسية.

URL.revokeObjectURL(id) ​

أضيف في: الإصدار 16.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 سلسلة، فسيتم تحويله إلى سلسلة أولاً.
  • Returns: <boolean>

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

js
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 سلسلة، فسيتم تحويله إلى سلسلة أولاً.
  • Returns: <URL> | <null>

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

الفئة: URLSearchParams ​

[السجل]

الإصدارالتغييرات
الإصدار 10.0.0الفئة متاحة الآن على الكائن العام.
الإصدار 7.5.0, 6.13.0تمت الإضافة في: الإصدار 7.5.0, 6.13.0

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

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

js
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 جديد. يتم تجاهل '?' بادئة، إذا كانت موجودة.

js
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()، والتي ببساطة تجمع جميع عناصر المصفوفة بفواصل.

js
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 عبارة عن Array أو أي كائن قابل للتكرار. هذا يعني أن iterable يمكن أن يكون URLSearchParams آخر، وفي هذه الحالة سيقوم المنشئ ببساطة بإنشاء نسخة من URLSearchParams المقدمة. عناصر iterable هي أزواج المفاتيح والقيم، ويمكن أن تكون هي نفسها أي كائن قابل للتكرار.

يُسمح بالمفاتيح المكررة.

js
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) ​

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

urlSearchParams.delete(name[, value]) ​

[السجل]

الإصدارالتغييرات
v20.2.0, v18.18.0إضافة دعم لوسيطة value اختيارية.

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

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

urlSearchParams.entries() ​

يُرجع ES6 Iterator على كل زوج من أزواج الاسم-القيمة في الاستعلام. كل عنصر من عناصر التكرار هو Array JavaScript. العنصر الأول من Array هو name، والعنصر الثاني من Array هو value.

اسم بديل لـ urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg]) ​

[السجل]

الإصدارالتغييرات
v18.0.0تمرير رد اتصال غير صالح إلى وسيطة fn يطرح الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
  • fn <Function> يتم استدعاؤه لكل زوج اسم-قيمة في الاستعلام
  • thisArg <Object> لاستخدامه كقيمة this عند استدعاء fn

يتكرر على كل زوج اسم-قيمة في الاستعلام ويستدعي الدالة المحددة.

js
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. إذا لم تكن هناك أزواج كهذه، يتم إرجاع مصفوفة فارغة.

urlSearchParams.has(name[, value]) ​

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

الإصدارالتغييرات
v20.2.0, v18.18.0إضافة دعم الوسيطة الاختيارية value.

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

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

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

urlSearchParams.keys() ​

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

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

urlSearchParams.set(name, value) ​

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

js
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

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

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

js
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() ​

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

urlSearchParams.values() ​

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

urlSearchParams[Symbol.iterator]() ​

يُرجع Iterator ES6 على كل من أزواج الاسم-القيمة في سلسلة الاستعلام. كل عنصر من عناصر المُكرِّر هو Array JavaScript. العنصر الأول من Array هو name، والعنصر الثاني من Array هو value.

اسم بديل لـ urlSearchParams.entries().

js
const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz

url.domainToASCII(domain) ​

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

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

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

إنه ينفذ العملية العكسية لـ url.domainToUnicode().

js
import url from 'node:url';

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string
js
const url = require('node:url');

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

url.domainToUnicode(domain) ​

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

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

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

إنه ينفذ العملية العكسية لـ url.domainToASCII().

js
import url from 'node:url';

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string
js
const url = require('node:url');

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

url.fileURLToPath(url[, options]) ​

[السجل]

الإصدارالتغييرات
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 خاص بالنظام الأساسي تم حله بالكامل.

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

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

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

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

js
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'
js
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]) ​

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

الإصدارالتغييرات
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 للملف.

js
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)
js
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) ​

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

الإصدارالتغييرات
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' لحساب رأس التفويض.

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

js
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'
}
*/
js
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 - قديم: استخدم واجهة برمجة تطبيقات عنوان URL الخاصة بـ WHATWG بدلاً من ذلك.

urlObject القديم ​

[التاريخ]

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

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

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

يتم إنشاء وإرجاع 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تم إلغاء الإيقاف. تم تغيير الحالة إلى "Legacy".
v11.0.0واجهة برمجة تطبيقات URL القديمة مهملة. استخدم واجهة برمجة تطبيقات WHATWG URL.
v7.0.0ستستخدم عناوين URL التي تحتوي على مخطط file: دائمًا العدد الصحيح من الشرطات المائلة بغض النظر عن خيار slashes. يتم الآن أيضًا احترام خيار slashes الخاطئ بدون بروتوكول في جميع الأوقات.
v0.1.25تمت الإضافة في: v0.1.25

[مستقر: 3 - Legacy]

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

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

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

js
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 عبارة عن Object، فسيتم إلحاق السلسلة الحرفية ? بـ 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 <string> سلسلة URL المراد تحليلها.
  • parseQueryString <boolean> إذا كانت true، فسيتم دائمًا تعيين خاصية query لكائن مُرجع بواسطة طريقة parse() الخاصة بوحدة querystring. إذا كانت false، فستكون خاصية query في كائن عنوان URL المُرجع عبارة عن سلسلة غير مُحللة وغير مفككة. افتراضي: false.
  • slashesDenoteHost <boolean> إذا كانت true، فسيتم تفسير الرمز المميز الأول بعد السلسلة الحرفية // والتي تسبق / التالية على أنه host. على سبيل المثال، بالنظر إلى //foo/bar، ستكون النتيجة {host: 'foo', pathname: '/bar'} بدلاً من {pathname: '//foo/bar'}. افتراضي: false.

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

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

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

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

url.resolve(from, to) ​

[السجل]

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

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

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

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

تقوم طريقة url.resolve() بحل عنوان URL هدف بالنسبة إلى عنوان URL أساسي بطريقة مشابهة لتلك التي يستخدمها مستعرض الويب لحل علامة ارتساء.

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

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

js
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.

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

ضمن واجهة برمجة التطبيقات القديمة، سيتم تلقائيًا تضمين المسافات (' ') والأحرف التالية في خصائص كائنات 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 وأحرف مشفرة بنسبة مئوية:

js
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