1# @ohos.url (URL字符串解析)
2
3URL代表着是统一资源定位符,本模块提供了常用的工具函数,实现了解析URL字符串和构造[URL](#url)对象等功能。
4
5> **说明:**
6>
7> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { url } from '@kit.ArkTS';
13```
14## URLParams<sup>9+</sup>
15
16URLParams接口定义了一些处理URL查询字符串的实用方法。
17
18### constructor<sup>9+</sup>
19
20constructor(init?: string[][] | Record&lt;string, string&gt; | string | URLParams)
21
22URLParams的构造函数。
23
24**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
25
26**系统能力:** SystemCapability.Utils.Lang
27
28**参数:**
29
30| 参数名 | 类型 | 必填 | 说明 |
31| -------- | -------- | -------- | -------- |
32| init | string[][] \| Record&lt;string, string&gt; \| string \| URLParams | 否 | 入参对象。<br/>- string[][]:字符串二维数组<br/>- Record&lt;string, string&gt;:对象列表<br/>- string:字符串<br/>- URLParams:对象<br/>- 默认值:null。 |
33
34**错误码:**
35
36以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
37
38| 错误码ID | 错误信息 |
39| -------- | -------- |
40| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
41
42**示例:**
43
44```ts
45// 通过string[][]方式构造URLParams对象:
46let objectParams = new url.URLParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
47// 通过Record<string, string>方式构造URLParams对象:
48let objectParams1 = new url.URLParams({"fod" : '1' , "bard" : '2'});
49// 通过string方式构造URLParams对象:
50let objectParams2 = new url.URLParams('?fod=1&bard=2');
51// 通过url对象的search属性构造URLParams对象:
52let urlObject = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2');
53let objectParams3 = new url.URLParams(urlObject.search);
54// 通过url对象的params属性获取URLParams对象:
55let urlObject1 = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2');
56let objectParams4 = urlObject1.params;
57```
58
59
60### append<sup>9+</sup>
61
62append(name: string, value: string): void
63
64将新的键值对插入到查询字符串。
65
66**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
67
68**系统能力:** SystemCapability.Utils.Lang
69
70**参数:**
71
72| 参数名 | 类型 | 必填 | 说明 |
73| -------- | -------- | -------- | -------- |
74| name | string | 是 | 需要插入搜索参数的键名。 |
75| value | string | 是 | 需要插入搜索参数的值。 |
76
77**错误码:**
78
79以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
80
81| 错误码ID | 错误信息 |
82| -------- | -------- |
83| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
84
85**示例:**
86
87```ts
88let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
89let paramsObject = new url.URLParams(urlObject.search.slice(1));
90paramsObject.append('fod', '3');
91```
92
93
94### delete<sup>9+</sup>
95
96delete(name: string): void
97
98删除指定名称的键值对。
99
100**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
101
102**系统能力:** SystemCapability.Utils.Lang
103
104**参数:**
105
106| 参数名 | 类型 | 必填 | 说明 |
107| -------- | -------- | -------- | -------- |
108| name | string | 是 | 需要删除的键值名称。 |
109
110**错误码:**
111
112以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
113
114| 错误码ID | 错误信息 |
115| -------- | -------- |
116| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
117
118**示例:**
119
120```ts
121let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
122let paramsObject = new url.URLParams(urlObject.search.slice(1));
123paramsObject.delete('fod');
124```
125
126
127### getAll<sup>9+</sup>
128
129getAll(name: string): string[]
130
131获取指定名称的所有键对应值的集合。
132
133**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
134
135**系统能力:** SystemCapability.Utils.Lang
136
137**参数:**
138
139| 参数名 | 类型 | 必填 | 说明 |
140| -------- | -------- | -------- | -------- |
141| name | string | 是 | 指定的键值名称。 |
142
143**返回值:**
144
145| 类型 | 说明 |
146| -------- | -------- |
147| string[] | 返回指定名称的所有键对应值的集合。 |
148
149**错误码:**
150
151以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
152
153| 错误码ID | 错误信息 |
154| -------- | -------- |
155| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
156
157**示例:**
158
159```ts
160let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
161let params = new url.URLParams(urlObject.search.slice(1));
162params.append('fod', '3'); // Add a second value for the fod parameter.
163console.log(params.getAll('fod').toString()) // Output ["1","3"].
164```
165
166
167### entries<sup>9+</sup>
168
169entries(): IterableIterator<[string, string]>
170
171返回一个ES6的迭代器,迭代器的每一项都是一个 JavaScript Array。Array的第一项是name,Array的第二项是value。
172
173**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
174
175**系统能力:** SystemCapability.Utils.Lang
176
177**返回值:**
178
179| 类型 | 说明 |
180| -------- | -------- |
181| IterableIterator&lt;[string, string]&gt; | 返回一个ES6的迭代器。 |
182
183**示例:**
184
185```ts
186let searchParamsObject = new url.URLParams("keyName1=valueName1&keyName2=valueName2");
187let pair:Iterable<Object[]> = searchParamsObject.entries();
188let arrayValue = Array.from(pair);
189for (let pair of arrayValue) { // Show keyName/valueName pairs
190  console.log(pair[0]+ ', '+ pair[1]);
191}
192```
193
194
195### forEach<sup>9+</sup>
196
197forEach(callbackFn: (value: string, key: string, searchParams: URLParams) => void, thisArg?: Object): void
198
199通过回调函数来遍历URLSearchParams实例对象上的键值对。
200
201**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
202
203**系统能力:** SystemCapability.Utils.Lang
204
205**参数:**
206
207| 参数名 | 类型 | 必填 | 说明 |
208| -------- | -------- | -------- | -------- |
209| callbackFn | function | 是 | 回调函数。 |
210| thisArg | Object | 否 | callbackFn被调用时用作this值,默认值是本对象。 |
211
212**表1** callbackFn的参数说明
213
214| 参数名 | 类型 | 必填 | 说明 |
215| -------- | -------- | -------- | -------- |
216| value | string | 是 | 当前遍历到的键值。 |
217| key | string | 是 | 当前遍历到的键名。 |
218| searchParams | [URLParams](#urlparams9) | 是 | 当前调用forEach方法的实例对象。 |
219
220**错误码:**
221
222以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
223
224| 错误码ID | 错误信息 |
225| -------- | -------- |
226| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
227
228**示例:**
229
230```ts
231const myURLObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
232myURLObject.params.forEach((value, name, searchParams) => {
233    console.log(name, value, myURLObject.params === searchParams);
234});
235```
236
237
238### get<sup>9+</sup>
239
240get(name: string): string | null
241
242获取指定名称对应的第一个值。
243
244> **说明:**
245>
246> 若查找一个不存在的键值对名称时返回值为undefined。
247
248**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
249
250**系统能力:** SystemCapability.Utils.Lang
251
252**参数:**
253
254| 参数名 | 类型 | 必填 | 说明 |
255| -------- | -------- | -------- | -------- |
256| name | string | 是 | 指定键值对的名称。 |
257
258**返回值:**
259
260| 类型 | 说明 |
261| -------- | -------- |
262| string | 返回第一个值。 |
263| null | 如果没找到,返回 null。 |
264
265**错误码:**
266
267以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
268
269| 错误码ID | 错误信息 |
270| -------- | -------- |
271| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
272
273**示例:**
274
275```ts
276let paramsObject = new url.URLParams('name=Jonathan&age=18');
277let name = paramsObject.get("name"); // is the string "Jonathan"
278let age = paramsObject.get("age"); // is the string "18"
279let getObj = paramsObject.get("abc"); // undefined
280```
281
282
283### has<sup>9+</sup>
284
285has(name: string): boolean
286
287判断一个指定的键名对应的值是否存在。
288
289**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
290
291**系统能力:** SystemCapability.Utils.Lang
292
293**参数:**
294
295| 参数名 | 类型 | 必填 | 说明 |
296| -------- | -------- | -------- | -------- |
297| name | string | 是 | 要查找的参数的键名。 |
298
299**返回值:**
300
301| 类型 | 说明 |
302| -------- | -------- |
303| boolean | 是否存在相对应的key值,存在返回true,否则返回false。 |
304
305**错误码:**
306
307以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
308
309| 错误码ID | 错误信息 |
310| -------- | -------- |
311| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
312
313**示例:**
314
315```ts
316let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
317let paramsObject = new url.URLParams(urlObject.search.slice(1));
318let result = paramsObject.has('bard');
319```
320
321
322### set<sup>9+</sup>
323
324set(name: string, value: string): void
325
326将与name关联的URLSearchParams对象中的值设置为value。如果存在名称为name的键值对,请将第一个键值对的值设置为value并删除所有其他值。如果不是,则将键值对附加到查询字符串。
327
328**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
329
330**系统能力:** SystemCapability.Utils.Lang
331
332**参数:**
333
334| 参数名 | 类型 | 必填 | 说明 |
335| -------- | -------- | -------- | -------- |
336| name | string | 是 | 将要设置的参数的键值名。 |
337| value | string | 是 | 所要设置的参数值。 |
338
339**错误码:**
340
341以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
342
343| 错误码ID | 错误信息 |
344| -------- | -------- |
345| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
346
347**示例:**
348
349```ts
350let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
351let paramsObject = new url.URLParams(urlObject.search.slice(1));
352paramsObject.set('baz', '3'); // Add a third parameter.
353```
354
355
356### sort<sup>9+</sup>
357
358sort(): void
359
360对包含在此对象中的所有键值对进行排序,并返回undefined。排序顺序是根据键的Unicode代码点。该方法使用稳定的排序算法 (即,将保留具有相等键的键值对之间的相对顺序)。
361
362**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
363
364**系统能力:** SystemCapability.Utils.Lang
365
366**示例:**
367
368```ts
369let searchParamsObject = new url.URLParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
370searchParamsObject.sort(); // Sort the key/value pairs
371console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2
372```
373
374
375### keys<sup>9+</sup>
376
377keys(): IterableIterator&lt;string&gt;
378
379返回一个所有键值对的name的ES6迭代器。
380
381**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
382
383**系统能力:** SystemCapability.Utils.Lang
384
385**返回值:**
386
387| 类型 | 说明 |
388| -------- | -------- |
389| IterableIterator&lt;string&gt; | 返回一个所有键值对的name的ES6迭代器。 |
390
391**示例:**
392
393```ts
394let searchParamsObject = new url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
395let keys = Array.from(searchParamsObject.keys());
396for (let key of keys) { // Output key-value pairs
397  console.log(key);
398}
399```
400
401
402### values<sup>9+</sup>
403
404values(): IterableIterator&lt;string&gt;
405
406返回一个所有键值对的value的ES6迭代器。
407
408**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
409
410**系统能力:** SystemCapability.Utils.Lang
411
412**返回值:**
413
414| 类型 | 说明 |
415| -------- | -------- |
416| IterableIterator&lt;string&gt; | 返回一个所有键值对的value的ES6迭代器。 |
417
418**示例:**
419
420```ts
421let searchParams = new url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
422let values = Array.from(searchParams.values());
423for (let value of values) {
424  console.log(value);
425}
426```
427
428
429### [Symbol.iterator]<sup>9+</sup>
430
431[Symbol.iterator]\(): IterableIterator&lt;[string, string]&gt;
432
433返回一个ES6的迭代器,迭代器的每一项都是一个 JavaScript Array。Array的第一项是name,Array的第二项是value。
434
435**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
436
437**系统能力:** SystemCapability.Utils.Lang
438
439**返回值:**
440
441| 类型 | 说明 |
442| -------- | -------- |
443| IterableIterator&lt;[string, string]&gt; | 返回一个ES6的迭代器。 |
444
445**示例:**
446
447```ts
448const paramsObject = new url.URLParams('fod=bay&edg=bap');
449let iter: Iterable<Object[]> = paramsObject[Symbol.iterator]();
450let pairs = Array.from(iter);
451for (let pair of pairs) {
452  console.log(pair[0] + ', ' + pair[1]);
453}
454```
455
456
457### toString<sup>9+</sup>
458
459toString(): string
460
461返回序列化为字符串的搜索参数,必要时对字符进行百分比编码。
462
463**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
464
465**系统能力:** SystemCapability.Utils.Lang
466
467**返回值:**
468
469| 类型 | 说明 |
470| -------- | -------- |
471| string | 返回序列化为字符串的搜索参数,必要时对字符进行百分比编码。 |
472
473**示例:**
474
475```ts
476let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
477let params = new url.URLParams(urlObject.search.slice(1));
478params.append('fod', '3');
479console.log(params.toString()); // Output 'fod=1&bard=2&fod=3'
480```
481
482## URL
483
484用于解析、构造、规范、编码对应的URL字符串。
485
486### 属性
487
488**系统能力:** SystemCapability.Utils.Lang
489
490| 名称 | 类型 | 可读 | 可写 | 说明 |
491| -------- | -------- | -------- | -------- | -------- |
492| hash | string | 是 | 是 | 获取和设置URL的片段部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
493| host | string | 是 | 是 | 获取和设置URL的主机部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
494| hostname | string | 是 | 是 | 获取和设置URL的主机名部分,不带端口。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
495| href | string | 是 | 是 | 获取和设置序列化的URL。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
496| origin | string | 是 | 否 | 获取URL源的只读序列化。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
497| password | string | 是 | 是 | 获取和设置URL的密码部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
498| pathname | string | 是 | 是 | 获取和设置URL的路径部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
499| port | string | 是 | 是 | 获取和设置URL的端口部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
500| protocol | string | 是 | 是 | 获取和设置URL的协议部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
501| search | string | 是 | 是 | 获取和设置URL的序列化查询部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
502| searchParams<sup>(deprecated)</sup> | [URLSearchParams](#urlsearchparamsdeprecated) | 是 | 否 | 获取URLSearchParams表示URL查询参数的对象。<br/>- **说明:** 此属性从API version 7开始支持,从API version 9开始被废弃。建议使用params<sup>9+</sup>替代。 |
503| params<sup>9+</sup> | [URLParams](#urlparams9) | 是 | 否 | 获取URLParams表示URL查询参数的对象。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
504| username | string | 是 | 是 | 获取和设置URL的用户名部分。**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 |
505
506**示例:**
507
508```ts
509let that = url.URL.parseURL('http://username:password@host:8080/directory/file?foo=1&bar=2#fragment');
510console.log("hash " + that.hash) // hash #fragment
511console.log("host " + that.host) // host host:8080
512console.log("hostname " + that.hostname) // hostname host
513console.log("href " + that.href) // href http://username:password@host:8080/directory/file?foo=1&bar=2#fragment
514console.log("origin " + that.origin) // origin http://host:8080
515console.log("password " + that.password) // password password
516console.log("pathname " + that.pathname) // pathname /directory/file
517console.log("port " + that.port) // port 8080
518console.log("protocol " + that.protocol) // protocol http:
519console.log("search " + that.search) // search ?foo=1&bar=2
520console.log("username " + that.username) // username username
521// that.params 返回值为URLParams对象
522console.log("params: foo " + that.params.get("foo")) // params: foo 1
523```
524
525### constructor<sup>(deprecated)</sup>
526
527> **说明:**
528>
529> 从API version 7开始支持,从API version 9开始废弃,建议使用[parseURL<sup>9+</sup>](#parseurl9)替代。
530
531constructor(url: string, base?: string | URL)
532
533URL的构造函数。
534
535**系统能力:** SystemCapability.Utils.Lang
536
537**参数:**
538
539| 参数名 | 类型 | 必填 | 说明 |
540| -------- | -------- | -------- | -------- |
541| url | string | 是 | 一个表示绝对URL或相对URL的字符串。 <br/>如果 url 是相对URL,则需要指定 base,用于解析最终的URL。 <br/>如果 url 是绝对URL,则给定的 base 将不会生效。 |
542| base | string \| URL | 否 | 入参字符串或者对象,默认值是undefined。<br/>- string:字符串<br/>- URL:URL对象<br/>- 在url是相对URL时使用。 |
543
544**示例:**
545
546```ts
547let mm = 'https://username:password@host:8080';
548let a = new url.URL("/", mm); // Output 'https://username:password@host:8080/';
549let b = new url.URL(mm); // Output 'https://username:password@host:8080/';
550new url.URL('path/path1', b); // Output 'https://username:password@host:8080/path/path1';
551let c = new url.URL('/path/path1', b);  // Output 'https://username:password@host:8080/path/path1';
552new url.URL('/path/path1', c); // Output 'https://username:password@host:8080/path/path1';
553new url.URL('/path/path1', a); // Output 'https://username:password@host:8080/path/path1';
554new url.URL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output https://www.exampleUrl/path/path1
555new url.URL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL
556new url.URL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL
557new url.URL('https://www.example.com', ); // Output https://www.example.com/
558new url.URL('https://www.example.com', b); // Output https://www.example.com/
559```
560
561### constructor<sup>9+</sup>
562
563constructor()
564
565URL的无参构造函数。parseURL调用后返回一个URL对象,不单独使用。
566
567**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
568
569**系统能力:** SystemCapability.Utils.Lang
570
571### parseURL<sup>9+</sup>
572
573static parseURL(url: string, base?: string | URL): URL
574
575URL静态成员函数。
576
577**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
578
579**系统能力:** SystemCapability.Utils.Lang
580
581**参数:**
582
583| 参数名 | 类型 | 必填 | 说明 |
584| -------- | -------- | -------- | -------- |
585| url | string | 是 | 一个表示绝对URL或相对URL的字符串。 <br/>如果 url 是相对URL,则需要指定 base,用于解析最终的URL。 <br/>如果 url 是绝对URL,则给定的 base 将不会生效。 |
586| base | string \| URL | 否 | 入参字符串或者对象,默认值是undefined。<br/>- string:字符串<br/>- URL:URL对象<br/>- 在url是相对URL时使用。 |
587
588> **说明:**
589>
590> 当入参url是相对URL时,调用该接口解析后的URL并不是简单地将入参url和base直接拼接。url内容为相对路径格式时,会相对于base的当前目录进行解析,包括base中path字段最后一个斜杠前的所有路径片段,但不包括其后的部分(参照示例中url1)。url内容为指向根目录的格式时,会相对于 base 的原始地址(origin)进行解析(参照示例中url2)。
591
592**错误码:**
593
594以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。
595
596| 错误码ID | 错误信息 |
597| -------- | -------- |
598| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
599| 10200002 | Invalid url string. |
600
601**示例:**
602
603```ts
604let mm = 'https://username:password@host:8080/test/test1/test3';
605let urlObject = url.URL.parseURL(mm);
606let result = urlObject.toString(); // Output 'https://username:password@host:8080/test/test1/test3'
607// url内容为相对路径格式时,此时base参数的path为test/test1,解析后的URL的path为/test/path2/path3
608let url1 = url.URL.parseURL('path2/path3', 'https://www.huawei.com/test/test1'); // Output 'https://www.huawei.com/test/path2/path3'
609// url内容为指向根目录的格式时,此时base参数的path为/test/test1/test3,解析后的URL的path为/path1/path2
610let url2 = url.URL.parseURL('/path1/path2', urlObject); // Output 'https://username:password@host:8080/path1/path2'
611url.URL.parseURL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output 'https://www.exampleUrl/path/path1'
612url.URL.parseURL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL
613url.URL.parseURL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL
614url.URL.parseURL('https://www.example.com', ); // Output 'https://www.example.com/'
615url.URL.parseURL('https://www.example.com', urlObject); // Output 'https://www.example.com/'
616```
617
618### toString
619
620toString(): string
621
622将解析过后的URL转化为字符串。
623
624**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
625
626**系统能力:** SystemCapability.Utils.Lang
627
628**返回值:**
629
630| 类型 | 说明 |
631| -------- | -------- |
632| string | 用于返回网址的字符串序列化。 |
633
634**示例:**
635
636```ts
637const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
638let result = urlObject.toString(); // Output 'https://username:password@host:8080/directory/file?query=pppppp#qwer=da'
639```
640
641### toJSON
642
643toJSON(): string
644
645将解析过后的URL转化为JSON字符串。
646
647**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。
648
649**系统能力:** SystemCapability.Utils.Lang
650
651**返回值:**
652
653| 类型 | 说明 |
654| -------- | -------- |
655| string | 用于返回网址的字符串序列化。 |
656
657**示例:**
658```ts
659const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
660let result = urlObject.toJSON();
661```
662
663## URLSearchParams<sup>(deprecated)</sup>
664
665URLSearchParams接口定义了一些处理URL查询字符串的实用方法,从API version 9开始废弃,建议使用[URLParams](#urlparams9)。
666
667### constructor<sup>(deprecated)</sup>
668
669constructor(init?: string[][] | Record&lt;string, string&gt; | string | URLSearchParams)
670
671URLSearchParams的构造函数。
672
673> **说明:**
674>
675> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.constructor<sup>9+</sup>](#constructor9)替代。
676
677**系统能力:** SystemCapability.Utils.Lang
678
679**参数:**
680
681| 参数名 | 类型 | 必填 | 说明 |
682| -------- | -------- | -------- | -------- |
683| init | string[][] \| Record&lt;string, string&gt; \| string \| URLSearchParams | 否 | 入参对象。<br/>- string[][]:字符串二维数组<br/>- Record&lt;string, string&gt;:对象列表<br/>- string:字符串<br/>- URLSearchParams:对象<br/>- 默认值:null。 |
684
685**示例:**
686
687```ts
688let objectParams = new url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
689let objectParams1 = new url.URLSearchParams({"fod" : '1' , "bard" : '2'});
690let objectParams2 = new url.URLSearchParams('?fod=1&bard=2');
691let urlObject = new url.URL('https://developer.mozilla.org/?fod=1&bard=2');
692let params = new url.URLSearchParams(urlObject.search);
693```
694
695### append<sup>(deprecated)</sup>
696
697append(name: string, value: string): void
698
699将新的键值对插入到查询字符串。
700
701> **说明:**
702>
703> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.append<sup>9+</sup>](#append9)替代。
704
705**系统能力:** SystemCapability.Utils.Lang
706
707**参数:**
708
709| 参数名 | 类型 | 必填 | 说明 |
710| -------- | -------- | -------- | -------- |
711| name | string | 是 | 需要插入搜索参数的键名。 |
712| value | string | 是 | 需要插入搜索参数的值。 |
713
714**示例:**
715
716```ts
717let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
718let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
719paramsObject.append('fod', '3');
720```
721
722### delete<sup>(deprecated)</sup>
723
724delete(name: string): void
725
726删除指定名称的键值对。
727
728> **说明:**
729>
730> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.delete<sup>9+</sup>](#delete9)替代。
731
732**系统能力:** SystemCapability.Utils.Lang
733
734**参数:**
735
736| 参数名 | 类型 | 必填 | 说明 |
737| -------- | -------- | -------- | -------- |
738| name | string | 是 | 需要删除的键值名称。 |
739
740**示例:**
741
742```ts
743let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
744let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
745paramsObject.delete('fod');
746```
747
748### getAll<sup>(deprecated)</sup>
749
750getAll(name: string): string[]
751
752获取指定名称的所有键值对。
753
754> **说明:**
755>
756> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.getAll<sup>9+</sup>](#getall9)替代。
757
758**系统能力:** SystemCapability.Utils.Lang
759
760**参数:**
761
762| 参数名 | 类型 | 必填 | 说明 |
763| -------- | -------- | -------- | -------- |
764| name | string | 是 | 指定的键值名称。 |
765
766**返回值:**
767
768| 类型 | 说明 |
769| -------- | -------- |
770| string[] | 返回指定名称的所有键值对。 |
771
772**示例:**
773
774```ts
775let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
776let params = new url.URLSearchParams(urlObject.search.slice(1));
777params.append('fod', '3'); // Add a second value for the fod parameter.
778console.log(params.getAll('fod').toString()) // Output ["1","3"].
779```
780
781### entries<sup>(deprecated)</sup>
782
783entries(): IterableIterator<[string, string]>
784
785返回一个ES6的迭代器,迭代器的每一项都是一个 JavaScript Array。Array的第一项是name,Array的第二项是value。
786
787> **说明:**
788>
789> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.entries<sup>9+</sup>](#entries9)替代。
790
791**系统能力:** SystemCapability.Utils.Lang
792
793**返回值:**
794
795| 类型 | 说明 |
796| -------- | -------- |
797| IterableIterator&lt;[string, string]&gt; | 返回一个ES6的迭代器。 |
798
799**示例:**
800
801```ts
802let searchParamsObject = new url.URLSearchParams("keyName1=valueName1&keyName2=valueName2");
803let iter: Iterable<Object[]> = searchParamsObject.entries();
804let pairs = Array.from(iter);
805for (let pair of pairs) { // Show keyName/valueName pairs
806  console.log(pair[0]+ ', '+ pair[1]);
807}
808```
809
810
811### forEach<sup>(deprecated)</sup>
812
813forEach(callbackFn: (value: string, key: string, searchParams: URLSearchParams) => void, thisArg?: Object): void
814
815通过回调函数来遍历URLSearchParams实例对象上的键值对。
816
817> **说明:**
818>
819> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.forEach<sup>9+</sup>](#foreach9)替代。
820
821**系统能力:** SystemCapability.Utils.Lang
822
823**参数:**
824
825| 参数名 | 类型 | 必填 | 说明 |
826| -------- | -------- | -------- | -------- |
827| callbackFn | function | 是 | 回调函数。 |
828| thisArg | Object | 否 | callbackFn被调用时用作this值,默认值是本对象。 |
829
830**表1** callbackFn的参数说明
831
832| 参数名 | 类型 | 必填 | 说明 |
833| -------- | -------- | -------- | -------- |
834| value | string | 是 | 当前遍历到的键值。 |
835| key | string | 是 | 当前遍历到的键名。 |
836| searchParams | [URLSearchParams](#urlsearchparamsdeprecated) | 是 | 当前调用forEach方法的实例对象。 |
837
838**示例:**
839
840```ts
841const myURLObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
842myURLObject.searchParams.forEach((value, name, searchParams) => {
843    console.log(name, value, myURLObject.searchParams === searchParams);
844});
845```
846
847
848### get<sup>(deprecated)</sup>
849
850get(name: string): string | null
851
852获取指定名称对应的第一个值。
853
854> **说明:**
855>
856> 若查找一个不存在的键值对名称时返回值为undefined,从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.get<sup>9+</sup>](#get9)替代。
857
858
859**系统能力:** SystemCapability.Utils.Lang
860
861**参数:**
862
863| 参数名 | 类型 | 必填 | 说明 |
864| -------- | -------- | -------- | -------- |
865| name | string | 是 | 指定键值对的名称。 |
866
867**返回值:**
868
869| 类型 | 说明 |
870| -------- | -------- |
871| string | 返回第一个值。 |
872| null | 如果没找到,返回 null。 |
873
874**示例:**
875
876```ts
877let paramsObject = new url.URLSearchParams('name=Jonathan&age=18');
878let name = paramsObject.get("name"); // is the string "Jonathan"
879let age = paramsObject.get("age"); // is the string '18'
880let getObj = paramsObject.get("abc"); // undefined
881```
882
883
884### has<sup>(deprecated)</sup>
885
886has(name: string): boolean
887
888判断一个指定的键名对应的值是否存在。
889
890> **说明:**
891>
892> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.has<sup>9+</sup>](#has9)替代。
893
894**系统能力:** SystemCapability.Utils.Lang
895
896**参数:**
897
898| 参数名 | 类型 | 必填 | 说明 |
899| -------- | -------- | -------- | -------- |
900| name | string | 是 | 要查找的参数的键名。 |
901
902**返回值:**
903
904| 类型 | 说明 |
905| -------- | -------- |
906| boolean | 是否存在相对应的key值,存在返回true,否则返回false。 |
907
908**示例:**
909
910```ts
911let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
912let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
913paramsObject.has('bard') === true;
914```
915
916
917### set<sup>(deprecated)</sup>
918
919set(name: string, value: string): void
920
921将与name关联的URLSearchParams对象中的值设置为value。如果存在名称为name的键值对,请将第一个键值对的值设置为value并删除所有其他值。如果不是,则将键值对附加到查询字符串。
922
923> **说明:**
924>
925> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.set<sup>9+</sup>](#set9)替代。
926
927**系统能力:** SystemCapability.Utils.Lang
928
929**参数:**
930
931| 参数名 | 类型 | 必填 | 说明 |
932| -------- | -------- | -------- | -------- |
933| name | string | 是 | 将要设置的参数的键值名。 |
934| value | string | 是 | 所要设置的参数值。 |
935
936**示例:**
937
938```ts
939let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
940let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
941paramsObject.set('baz', '3'); // Add a third parameter.
942```
943
944
945### sort<sup>(deprecated)</sup>
946
947sort(): void
948
949对包含在此对象中的所有键值对进行排序,并返回undefined。排序顺序是根据键的Unicode代码点。该方法使用稳定的排序算法 (即,将保留具有相等键的键值对之间的相对顺序)。
950
951> **说明:**
952>
953> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.sort<sup>9+</sup>](#sort9)替代。
954
955**系统能力:** SystemCapability.Utils.Lang
956
957**示例:**
958
959```ts
960let searchParamsObject = new url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
961searchParamsObject.sort(); // Sort the key/value pairs
962console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2
963```
964
965
966### keys<sup>(deprecated)</sup>
967
968keys(): IterableIterator&lt;string&gt;
969
970返回一个所有键值对的name的ES6迭代器。
971
972> **说明:**
973>
974> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.keys<sup>9+</sup>](#keys9)替代。
975
976**系统能力:** SystemCapability.Utils.Lang
977
978**返回值:**
979
980| 类型 | 说明 |
981| -------- | -------- |
982| IterableIterator&lt;string&gt; | 返回一个所有键值对的name的ES6迭代器。 |
983
984**示例:**
985
986```ts
987let searchParamsObject = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
988let keys = Array.from(searchParamsObject.keys());
989for (let key of keys) { // Output key-value pairs
990  console.log(key);
991}
992```
993
994
995### values<sup>(deprecated)</sup>
996
997values(): IterableIterator&lt;string&gt;
998
999返回一个所有键值对的value的ES6迭代器。
1000
1001> **说明:**
1002>
1003> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.values<sup>9+</sup>](#values9)替代。
1004
1005**系统能力:** SystemCapability.Utils.Lang
1006
1007**返回值:**
1008
1009| 类型 | 说明 |
1010| -------- | -------- |
1011| IterableIterator&lt;string&gt; | 返回一个所有键值对的value的ES6迭代器。 |
1012
1013**示例:**
1014
1015```ts
1016let searchParams = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
1017let values = Array.from(searchParams.values());
1018for (let value of values) {
1019  console.log(value);
1020}
1021```
1022
1023
1024### [Symbol.iterator]<sup>(deprecated)</sup>
1025
1026[Symbol.iterator]\(): IterableIterator&lt;[string, string]&gt;
1027
1028返回一个ES6的迭代器,迭代器的每一项都是一个 JavaScript Array。Array的第一项是name,Array的第二项是value。
1029
1030> **说明:**
1031>
1032> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.[Symbol.iterator]<sup>9+</sup>](#symboliterator9)替代。
1033
1034**系统能力:** SystemCapability.Utils.Lang
1035
1036**返回值:**
1037
1038| 类型 | 说明 |
1039| -------- | -------- |
1040| IterableIterator&lt;[string, string]&gt; | 返回一个ES6的迭代器。 |
1041
1042**示例:**
1043
1044```ts
1045const paramsObject = new url.URLSearchParams('fod=bay&edg=bap');
1046let iter: Iterable<Object[]> = paramsObject[Symbol.iterator]();
1047let pairs = Array.from(iter);
1048for (let pair of pairs) {
1049  console.log(pair[0] + ', ' + pair[1]);
1050}
1051```
1052
1053### toString<sup>(deprecated)</sup>
1054
1055toString(): string
1056
1057返回序列化为字符串的搜索参数,必要时对字符进行百分比编码。
1058
1059> **说明:**
1060>
1061> 从API version 7开始支持,从API version 9开始废弃,建议使用[URLParams.toString<sup>9+</sup>](#tostring9)替代。
1062
1063**系统能力:** SystemCapability.Utils.Lang
1064
1065**返回值:**
1066
1067| 类型 | 说明 |
1068| -------- | -------- |
1069| string | 返回序列化为字符串的搜索参数,必要时对字符进行百分比编码。 |
1070
1071**示例:**
1072
1073```ts
1074let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
1075let params = new url.URLSearchParams(urlObject.search.slice(1));
1076params.append('fod', '3');
1077console.log(params.toString()); // Output 'fod=1&bard=2&fod=3'
1078```
1079<!--no_check-->