1# @ohos.uri (URI字符串解析)
2
3本模块提供URI字符串解析的相关功能。URI遵循RFC3986规范标准,该标准定义了如何编码和解析用于定位网络资源的标识符,对于非标准场景解析不支持。
4
5> **说明:**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12```ts
13import { uri } from '@kit.ArkTS';
14```
15
16## URI
17
18构造URI对象,提供判断对象相等、规范路径等方法。
19
20### 属性
21
22**系统能力:** SystemCapability.Utils.Lang
23
24| 名称 | 类型 | 可读 | 可写 | 说明 |
25| -------- | -------- | -------- | -------- | -------- |
26| scheme | string | 是 | 否 | 获取URI的协议部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。|
27| userInfo | string | 是 | 否 | 获取URI的用户信息部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
28| host | string | 是 | 否 | 获取URI的主机名部分(不带端口),若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。|
29| port | string | 是 | 否 | 获取URI的端口部分。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
30| path | string | 是 | 否 | 获取URI的路径部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
31| query | string | 是 | 否 | 获取URI的查询部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
32| fragment | string | 是 | 否 | 获取URI的片段部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
33| authority | string | 是 | 否 | 获取此URI的解码权限组件部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
34| ssp | string | 是 | 否 | 获取URI的解码方案特定部分,方案特定部分是URI的一部分,它包含了特定于协议或方案的信息。<br/>**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。 |
35| encodedUserInfo<sup>12+</sup>  | string | 是   | 否   | 获取URI的编码用户信息部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。   |
36| encodedPath<sup>12+</sup>      | string | 是   | 否   | 获取URI的编码路径部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。       |
37| encodedQuery<sup>12+</sup>     | string | 是   | 否   | 获取URI的编码查询部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。      |
38| encodedFragment<sup>12+</sup>  | string | 是   | 否   | 获取URI的编码片段部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。      |
39| encodedAuthority<sup>12+</sup> | string | 是   | 否   | 获取URI的编码权限组件部分,若无此部分则返回null对象。 <br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。   |
40| encodedSSP<sup>12+</sup>       | string | 是   | 否   | 获取URI的编码方案特定部分。<br/>**原子化服务API:** 从API version 12 开始,该接口支持在原子化服务中使用。   |
41
42### 命名规则
43
44**命名形式:**
45
46标准uri定义主要由以下三个部分组成:
47[scheme:]scheme-specific-part[#fragment]。
48
49将URI格式细化一些则可分为:
50[scheme:][//authority][path][?query][#fragment]。
51
52将URI格式进一步细化可分为:
53[scheme:][//[user-info@]host[:port]][path][?query][#fragment]。
54
55- scheme: 协议名,与scheme-specific-part以:进行分隔,包含scheme部分的URI为绝对URI,不包含scheme部分的URI为相对URI,根据需要填写。例如http、https、ftp、datashare等。
56- scheme-specific-part: URI的特定解码方案特定部分,位于[scheme:]和[#fragment]之间由[//][authority][path][?query]组成,此部分以/开头的为分层URI,不以/开头的为不透明URI,根据需要填写。
57    - authority: URI的解码权限组件部分。由[userinfo@]host[:port]组成,根据需要填写。
58        - userinfo: 用户信息,与host通过@进行分隔,根据需要填写。
59        - host: 服务器的主机名部分,当authority存在时,此项必填。
60        - port: 服务器端口,默认值为-1。根据需要填写。
61    - path: 路径信息,位于host与query之间以 / 进行分割,根据需要填写。
62    - query: 查询部分,位于path和fragment之间,以 ? 开头的键值对格式,以&分割键值对,以=分割键值,根据需要填写。
63- fragment: 片段部分,以#与scheme-specific-part进行分隔,根据需要填写。
64
65**URI示例:**
66
67```ts
68const uriObj1 = new uri.URI("ftp://ftp.aaa.bbb.ccc/dddd/eee.txt");
69console.info(uriObj1.host) // ftp.aaa.bbb.ccc
70console.info(uriObj1.fragment) // null
71console.info(uriObj1.path) // /dddd/eee.txt
72console.info(uriObj1.scheme) // ftp
73console.info(uriObj1.userInfo) // null
74console.info(uriObj1.port) // -1
75console.info(uriObj1.query) // null
76
77const uriObj2 = new uri.URI("gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles#fragment");
78console.info(uriObj2.host) // spinaltap.micro.umn.edu
79console.info(uriObj2.fragment) // fragment
80console.info(uriObj2.path) // /00/Weather/California/Los Angeles
81console.info(uriObj2.scheme) // gopher
82console.info(uriObj2.userInfo) // null
83console.info(uriObj2.port) //-1
84console.info(uriObj2.query) // null
85
86const uriObj3 = new uri.URI("datashare:///com.samples.datasharetest.DataShare/DB00/TBL00");
87console.info(uriObj3.host) // null
88console.info(uriObj3.fragment) // null
89console.info(uriObj3.path) // /com.samples.datasharetest.DataShare/DB00/TBL00
90console.info(uriObj3.scheme) // datashare
91console.info(uriObj3.userInfo) // null
92console.info(uriObj3.port) // -1
93console.info(uriObj3.query) // null
94
95const uriObj4 = new uri.URI("https://username:password@host:8080/directory/file?foo=1&bar=2#fragment");
96console.info(uriObj4.host) // host
97console.info(uriObj4.fragment) // fragment
98console.info(uriObj4.path) // /directory/file
99console.info(uriObj4.scheme) // https
100console.info(uriObj4.userInfo) // username:password
101console.info(uriObj4.port) // 8080
102console.info(uriObj4.query) // foo=1&bar=2
103
104const uriObj5 = new uri.URI("dataability:///com.example.DataAbility");
105console.info(uriObj5.host) // null
106console.info(uriObj5.fragment) // null
107console.info(uriObj5.path) // /com.example.DataAbility:
108console.info(uriObj5.scheme) // dataability
109console.info(uriObj5.userInfo) // null
110console.info(uriObj5.port) // -1
111console.info(uriObj5.query) // null
112
113const uriObj6 = new uri.URI("https://username:my+name@host:8080/directory/my+file?foo=1&bar=2#fragment");
114console.info(uriObj6.encodedUserInfo) // username:my+name
115console.info(uriObj6.encodedPath) // /directory/my+file
116console.info(uriObj6.encodedQuery) // foo=1&bar=2
117console.info(uriObj6.encodedFragment) // fragment
118console.info(uriObj6.encodedAuthority) // username:my+name@host:8080
119console.info(uriObj6.encodedSSP) // //username:my+name@host:8080/directory/my+file?foo=1&bar=2
120
121let uriObj7 = new uri.URI("www.abc.com:8080/directory/file?ab=pppppp#qwer=da");
122console.log(uriObj7.scheme) // www.abc.com
123console.log(uriObj7.host) // null
124console.log(uriObj7.port) // -1
125console.log(uriObj7.path) // null
126console.log(uriObj7.query) // null
127console.log(uriObj7.authority) // null
128console.log(uriObj7.fragment) // qwer=da
129console.log(uriObj7.ssp) // 8080/directory/file?ab=pppppp
130console.log("result:", uriObj7.checkIsAbsolute()) // result: true
131```
132
133### constructor
134
135constructor(uri: string)
136
137constructor是URI的构造函数。
138
139**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。
140
141**系统能力:** SystemCapability.Utils.Lang
142
143**参数:**
144
145| 参数名 | 类型 | 必填 | 说明 |
146| -------- | -------- | -------- | -------- |
147| uri | string | 是 | 入参对象。 |
148
149**错误码:**
150
151以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.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| 10200002 | Invalid uri string. |
157
158**示例:**
159
160```ts
161let mm = 'https://username:password@host:8080/directory/file?foo=1&bar=2#fragment';
162new uri.URI(mm);
163```
164```ts
165new uri.URI('https://username:password@host:8080');
166```
167
168
169### toString
170
171toString(): string
172
173将URI转化为编码后的字符串。
174
175**系统能力:** SystemCapability.Utils.Lang
176
177**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。
178
179**返回值:**
180
181| 类型 | 说明 |
182| -------- | -------- |
183| string | 返回URI的字符串序列化。 |
184
185**示例:**
186
187```ts
188const result = new uri.URI('https://username:password@host:8080/directory/file?ab=pppppp#qwer da');
189let result1 = result.toString(); // https://username:password@host:8080/directory/file?ab=pppppp#qwer%20da
190```
191
192### equalsTo<sup>9+</sup>
193
194equalsTo(other: URI): boolean
195
196判断此URI是否与其他URI对象相等。
197
198**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。
199
200**系统能力:** SystemCapability.Utils.Lang
201
202**参数:**
203
204| 参数名 | 类型 | 必填 | 说明 |
205| -------- | -------- | -------- | -------- |
206| other | [URI](#uri) | 是 | 需要比较的URI对象。 |
207
208**返回值:**
209
210| 类型 | 说明 |
211| -------- | -------- |
212| boolean | 返回true表示相等,否则返回false。 |
213
214**错误码:**
215
216以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
217
218| 错误码ID | 错误信息 |
219| -------- | -------- |
220| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
221
222**示例:**
223
224```ts
225const uriInstance = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
226const uriInstance1 = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
227let result = uriInstance.equalsTo(uriInstance1); // true
228```
229
230### checkIsAbsolute
231
232checkIsAbsolute(): boolean
233
234判断此URI是否为绝对URI(是否定义了scheme组件)。
235
236**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。
237
238**系统能力:** SystemCapability.Utils.Lang
239
240**返回值:**
241
242| 类型 | 说明 |
243| -------- | -------- |
244| boolean | 如果是绝对URI返回true,否则返回false。|
245
246**示例:**
247
248```ts
249const uriInstance = new uri.URI('https://username:password@www.qwer.com:8080?query=pppppp');
250console.info(`${uriInstance.checkIsAbsolute()}`); // true
251const uriInstance1 = new uri.URI('xxx.com/suppliers.htm');
252console.info(`${uriInstance1.checkIsAbsolute()}`); // false
253```
254
255
256### normalize
257
258normalize(): URI
259
260规范化此URI的路径。
261
262> **说明:**
263>
264> 如果此URI是不透明的,或者其路径已经是规范形式,则返回该URI。否则将构造一个新的URI,该URI与当前URI相同,唯一的区别是其路径通过规范化当前URI的路径来计算,具体规则如下:
265>
266>  1.移除所有的 .(点)段。
267>
268>  2.如果 ..(双点)段前面有一个非 .. 段,则将这两个段一起移除。重复此步骤,直到不再适用为止。
269>
270>如果路径规范化后以 ..(双点)段开头,这表明之前没有足够的非 .. 段可以移除,因此路径将以 .. 段开始。
271
272
273**原子化服务API:** 从API version 11 开始,该接口支持在原子化服务中使用。
274
275**系统能力:** SystemCapability.Utils.Lang
276
277**返回值:**
278
279| 类型 | 说明 |
280| -------- | -------- |
281| [URI](#uri) | 返回一个path被规范化后的URI对象。 |
282
283**示例:**
284
285```ts
286const uriInstance = new uri.URI('https://username:password@www.qwer.com:8080/path/path1/../path2/./path3?query=pppppp');
287console.info(uriInstance.path); // /path/path1/../path2/./path3
288// 规范化path后,移除所有的.(点)段,如果 ..(双点)段前面有一个非 .. 段,则将这两个段一起移除。
289let uriInstance1 = uriInstance.normalize();
290console.info(uriInstance1.path); // /path/path2/path3
291let uri1 = new uri.URI('http://www.test.com/../../patch/path1/../path2/path3/./path4/../');
292console.log(uri1.path); // /../../patch/path1/../path2/path3/./path4/../
293// 如果路径规范化后以 ..(双点)段开头,这表明之前没有足够的非 .. 段可以移除,因此路径将以 .. 段开始。
294let uri2 = uri1.normalize();
295console.log(uri2.path); // /../../patch/path2/path3
296```
297
298### checkRelative<sup>12+</sup>
299
300checkRelative(): boolean
301
302判断此URI是否为相对URI,相对URI指的是不包含协议(scheme)部分的URI。
303
304**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
305
306**系统能力:** SystemCapability.Utils.Lang
307
308**返回值:**
309
310| 类型    | 说明                                       |
311| ------- | ------------------------------------------ |
312| boolean | 如果是相对URI返回true,否则返回false。 |
313
314**示例:**
315
316```ts
317const uriInstance = new uri.URI("https://username:password@www.qwer.com:8080?query=p");
318console.info(`${uriInstance.checkRelative()}`); // false
319const uriInstance1 = new uri.URI("/images/pic.jpg");
320console.info(`${uriInstance1.checkRelative()}`); // true
321```
322
323### checkOpaque<sup>12+</sup>
324
325checkOpaque(): boolean
326
327判断此URI是否为不透明URI,方案特定部分不以“/”开头的URI为不透明的URI。
328
329**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
330
331**系统能力:** SystemCapability.Utils.Lang
332
333**返回值:**
334
335| 类型    | 说明                                           |
336| ------- | ---------------------------------------------- |
337| boolean | 如果是不透明的URI返回true,否则返回false。 |
338
339**示例:**
340
341```ts
342const uriInstance = new uri.URI("http://www.test.com/images/pic.jpg");
343console.info(`${uriInstance.checkOpaque()}`); // false
344const uriInstance1 = new uri.URI("mailto:user@example.com");
345console.info(`${uriInstance1.checkOpaque()}`); // true
346```
347
348### checkHierarchical<sup>12+</sup>
349
350checkHierarchical(): boolean
351
352判断此URI是否为分层URI,方案特定部分以“/”开头的URI为分层的URI。相对URI也是分层的。
353
354**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
355
356**系统能力:** SystemCapability.Utils.Lang
357
358**返回值:**
359
360| 类型    | 说明                                         |
361| ------- | -------------------------------------------- |
362| boolean | 如果是分层的URI返回true,否则返回false。 |
363
364**示例:**
365
366```ts
367const uriInstance = new uri.URI("http://www.test.com/images/pic.jpg");
368console.info(`${uriInstance.checkHierarchical()}`); // true
369const uriInstance1 = new uri.URI("mailto:user@example.com");
370console.info(`${uriInstance1.checkHierarchical()}`); // false
371```
372
373### getQueryValue<sup>12+</sup>
374
375getQueryValue(key:string): string
376
377根据给定的查询关键词,从URI查询参数部分中提取出该关键词对应的第一个值,若查询参数中存在已编码过的内容,需将对应Key进行解码后获取Value。
378
379查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。
380
381**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
382
383**系统能力:** SystemCapability.Utils.Lang
384
385**参数:**
386
387| 参数名 | 类型   | 必填 | 说明                    |
388| ------ | ------ | ---- | ----------------------- |
389| key    | string | 是   | 此URI查询参数的名称。 |
390
391**返回值:**
392
393| 类型   | 说明                          |
394| ------ | ----------------------------- |
395| string | 返回第一个此URI查询参数的值,若未找到对应值则返回null对象。 |
396
397**错误码:**
398
399以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
400
401| 错误码ID | 错误信息 |
402| -------- | -------- |
403| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
404
405**示例:**
406
407```ts
408const uriInstance = new uri.URI("https://www.com?param1=value1&param2=value2");
409console.info(uriInstance.getQueryValue("param1")); // value1
410let uriInstance1 = new uri.URI('https://www.zyy.ss?sa%3D=po%7E');
411console.info(uriInstance1.getQueryValue('sa=')) // po~
412console.info(uriInstance1.getQueryValue('abc')) // null
413```
414
415### addQueryValue<sup>12+</sup>
416
417addQueryValue(key:string, value:string): URI
418
419在当前URI的基础上添加查询参数,并创建一个新的URI,同时保持原有URI对象不变。
420
421**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
422
423**系统能力:** SystemCapability.Utils.Lang
424
425**参数:**
426
427| 参数名 | 类型   | 必填 | 说明                     |
428| ------ | ------ | ---- | ------------------------ |
429| key    | string | 是   | 需要增添查询参数的名称。 |
430| value  | string | 是   | 需要增添查询参数的值。   |
431
432**返回值:**
433
434| 类型 | 说明                             |
435| ---- | -------------------------------- |
436| [URI](#uri)  | 返回添加查询部分后的URI对象。 |
437
438**错误码:**
439
440以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
441
442| 错误码ID | 错误信息 |
443| -------- | -------- |
444| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
445
446**示例:**
447
448```ts
449const uriInstance = new uri.URI("https://www.test.com");
450const newRoute = uriInstance.addQueryValue("param1", "hello world");
451console.info(newRoute.toString()); // https://www.test.com?param1=hello%20world
452```
453
454### addSegment<sup>12+</sup>
455
456addSegment(pathSegment:string): URI
457
458对给定的字段进行编码并将其追加到当前URI的path字段中,并创建一个新的URI返回,同时保持原有URI对象不变。
459
460**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
461
462**系统能力:** SystemCapability.Utils.Lang
463
464**参数:**
465
466| 参数名      | 类型   | 必填 | 说明               |
467| ----------- | ------ | ---- | ------------------ |
468| pathSegment | string | 是   | 需要追加到路径部分的字段。 |
469
470**返回值:**
471
472| 类型 | 说明                             |
473| ---- | -------------------------------- |
474| [URI](#uri)  | 返回已追加字段的URI对象。 |
475
476**错误码:**
477
478以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
479
480| 错误码ID | 错误信息 |
481| -------- | -------- |
482| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
483
484**示例:**
485
486```ts
487const uriInstance = new uri.URI("http://www.test.com");
488const newRoute = uriInstance.addSegment("my image.jpg");
489console.info(newRoute.toString()); // http://www.test.com/my%20image.jpg
490```
491
492### addEncodedSegment<sup>12+</sup>
493
494addEncodedSegment(pathSegment:string): URI
495
496通过将已编码的字段追加到当前URI的path字段中,并创建一个新的URI返回,同时保持原有URI对象不变。
497
498**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
499
500**系统能力:** SystemCapability.Utils.Lang
501
502**参数:**
503
504| 参数名      | 类型   | 必填 | 说明               |
505| ----------- | ------ | ---- | ------------------ |
506| pathSegment | string | 是   | 需要追加到路径部分的编码字段。 |
507
508**返回值:**
509
510| 类型 | 说明                             |
511| ---- | -------------------------------- |
512| [URI](#uri)  | 返回已追加字段的URI对象。 |
513
514**错误码:**
515
516以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
517
518| 错误码ID | 错误信息 |
519| -------- | -------- |
520| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
521
522**示例:**
523
524```ts
525const uriInstance = new uri.URI("http://www.test.com");
526const newRoute = uriInstance.addEncodedSegment("my%20image.jpg");
527console.info(newRoute.toString()); // http://www.test.com/my%20image.jpg
528```
529
530### getQueryNames<sup>12+</sup>
531
532getQueryNames(): string[]
533
534获取URI查询部分中所有不重复的键。查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。
535
536**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
537
538**系统能力:** SystemCapability.Utils.Lang
539
540**返回值:**
541
542| 类型        | 说明                                |
543| ----------- | ----------------------------------- |
544| string[] | 返回此URI查询部分中所有不重复键。 |
545
546**示例:**
547
548```ts
549const uriInstance = new uri.URI("https://www.test.com?param1=value1&param2=value2");
550const paramNames = uriInstance.getQueryNames();
551console.info(Array.from(paramNames).toString()); // param1,param2
552```
553
554### getQueryValues<sup>12+</sup>
555
556getQueryValues(key:string): string[]
557
558获取此URI中查询参数的所有指定键对应值的集合。若查询参数中存在已编码过的内容,需将对应Key进行解码后获取Value。
559
560查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。
561
562**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
563
564**系统能力:** SystemCapability.Utils.Lang
565
566**参数:**
567
568| 参数名 | 类型   | 必填 | 说明                    |
569| ------ | ------ | ---- | ----------------------- |
570| key    | string | 是   | 指定键的名称。 |
571
572**返回值:**
573
574| 类型     | 说明                                |
575| -------- | ----------------------------------- |
576| string[] | 返回此URI中查询参数内所有指定键对应值的集合,若没有找到则返回一个空字符串数组[]。 |
577
578**错误码:**
579
580以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
581
582| 错误码ID | 错误信息 |
583| -------- | -------- |
584| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
585
586**示例:**
587
588```ts
589const uriInstance = new uri.URI("https://www.test.com/search?query=name&query=my");
590console.info(uriInstance.getQueryValues("query").toString()); // name,my
591console.info(JSON.stringify(uriInstance.getQueryValues("abc"))); // []
592```
593
594### getBooleanQueryValue<sup>12+</sup>
595
596getBooleanQueryValue(key:string,defaultValue:boolean): boolean
597
598从URI查询参数中获取布尔类型的参数值。
599
600**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
601
602**系统能力:** SystemCapability.Utils.Lang
603
604**参数:**
605
606| 参数名       | 类型    | 必填 | 说明                                  |
607| ------------ | ------- | ---- | ------------------------------------- |
608| key          | string  | 是   | 要获取的查询参数的名称。               |
609| defaultValue | boolean | 是   | 返回的默认值。 |
610
611**返回值:**
612
613| 类型    | 说明                                                                   |
614| ------- | ---------------------------------------------------------------------- |
615| boolean | 如果指定的查询参数不存在,则返回默认值;查询参数对应第一个值为“false”或者“0”返回false,否则返回true。 |
616
617**错误码:**
618
619以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
620
621| 错误码ID | 错误信息 |
622| -------- | -------- |
623| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
624
625**示例:**
626
627```ts
628const uriInstance = new uri.URI("https://www.test.com/search?active=true");
629console.info(`${uriInstance.getBooleanQueryValue("active", false)}`); // true
630const uriInstance1 = new uri.URI("https://www.test.com/search");
631console.info(`${uriInstance1.getBooleanQueryValue("active", false)}`); // false
632const uriInstance2 = new uri.URI("https://www.test.com/search?active=aa&active=false");
633console.info(`${uriInstance2.getBooleanQueryValue("active", false)}`); // true
634const uriInstance3 = new uri.URI("https://www.test.com/search?active=0");
635console.info(`${uriInstance3.getBooleanQueryValue("active", true)}`); // false
636```
637
638### clearQuery<sup>12+</sup>
639
640clearQuery(): URI
641
642清除URI路径查询部分,并创建一个新的URI,同时保持原有URI对象不变。
643
644**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
645
646**系统能力:** SystemCapability.Utils.Lang
647
648**返回值:**
649
650| 类型 | 说明                                  |
651| ---- | ------------------------------------- |
652| [URI](#uri)  | 返回一个已被清除查询部分的URI对象。 |
653
654**示例:**
655
656```ts
657const uriInstance = new uri.URI("https://www.test.com?param1=value1");
658console.info(uriInstance.clearQuery().toString()); // https://www.test.com
659```
660
661### getLastSegment<sup>12+</sup>
662
663getLastSegment(): string
664
665获取此URI路径的最后一个段。每个段代表路径中的一个部分,通常通过“/”来进行分隔。对于以斜杠结尾的或者没有路径的不代表段。
666
667**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
668
669**系统能力:** SystemCapability.Utils.Lang
670
671**返回值:**
672
673| 类型 | 说明                          |
674| ---- | ----------------------------- |
675| string  | 返回此URI路径中的最后一个段。 |
676
677**示例:**
678
679```ts
680const uriInstance = new uri.URI("content://com.test.provider/files/image.jpg");
681console.info(uriInstance.getLastSegment()); // image.jpg
682```
683
684### getSegment<sup>12+</sup>
685
686getSegment(): string[]
687
688获取此URI路径中的所有段。
689
690**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
691
692**系统能力:** SystemCapability.Utils.Lang
693
694**返回值:**
695
696| 类型     | 说明                        |
697| -------- | --------------------------- |
698| string[] | 返回此URI路径中的所有段。 |
699
700**示例:**
701
702```ts
703const uriInstance = new uri.URI("http://www.test.com/path/to/image.jpg");
704console.info(uriInstance.getSegment().toString()); // path,to,image.jpg
705```
706
707### createFromParts<sup>12+</sup>
708
709createFromParts(scheme: string, ssp: string, fragment: string): URI
710
711根据提供的协议、方案特定部分以及片段部分创建一个新的URI。
712
713**原子化服务API**:从API version 12 开始,该接口支持在原子化服务中使用。
714
715**系统能力:** SystemCapability.Utils.Lang
716
717**参数:**
718
719| 参数名   | 类型   | 必填 | 说明                            |
720| -------- | ------ | ---- | ------------------------------- |
721| scheme   | string | 是   | 此URI协议部分。               |
722| ssp      | string | 是   | 此URI的方案特定部分。 |
723| fragment | string | 是   | 此URI的片段部分。片段部分是URI中的一个特定部分,即“#”符号后面的部分。             |
724
725**返回值:**
726
727| 类型 | 说明                                              |
728| ---- | ------------------------------------------------- |
729| [URI](#uri)  | 返回创建的URI对象。 |
730
731**错误码:**
732
733以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
734
735| 错误码ID | 错误信息 |
736| -------- | -------- |
737| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
738
739**示例:**
740
741```ts
742const uriInstance = uri.URI.createFromParts("mailto", "no body", "top");
743console.info(uriInstance.toString()); // mailto:no%20body#top
744```
745
746### equals<sup>(deprecated)</sup>
747
748equals(other: URI): boolean
749
750判断此URI是否与其他URI对象相等。
751
752> **说明:**
753>
754> 从API version 8开始支持,从API version 9开始废弃,建议使用[equalsTo<sup>9+</sup>](#equalsto9)替代。
755
756**系统能力:** SystemCapability.Utils.Lang
757
758**参数:**
759
760| 参数名 | 类型 | 必填 | 说明 |
761| -------- | -------- | -------- | -------- |
762| other | [URI](#uri) | 是 | 需要比较的URI对象。 |
763
764**返回值:**
765
766| 类型 | 说明 |
767| -------- | -------- |
768| boolean | 返回true表示相等,否则返回false。 |
769
770**示例:**
771
772```ts
773const uriInstance = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
774const uriInstance1 = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
775uriInstance.equals(uriInstance1); // true
776```