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