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<string, string> | string | URLParams) 21 22URLParams的构造函数。 23 24**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 25 26**系统能力:** SystemCapability.Utils.Lang 27 28**参数:** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | -------- | -------- | -------- | 32| init | string[][] \| Record<string, string> \| string \| URLParams | 否 | 入参对象。<br/>- string[][]:字符串二维数组<br/>- Record<string, string>:对象列表<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<[string, string]> | 返回一个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<string> 378 379返回一个所有键值对的name的ES6迭代器。 380 381**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 382 383**系统能力:** SystemCapability.Utils.Lang 384 385**返回值:** 386 387| 类型 | 说明 | 388| -------- | -------- | 389| IterableIterator<string> | 返回一个所有键值对的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<string> 405 406返回一个所有键值对的value的ES6迭代器。 407 408**原子化服务API**:从API version 11 开始,该接口支持在原子化服务中使用。 409 410**系统能力:** SystemCapability.Utils.Lang 411 412**返回值:** 413 414| 类型 | 说明 | 415| -------- | -------- | 416| IterableIterator<string> | 返回一个所有键值对的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<[string, string]> 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<[string, string]> | 返回一个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<string, string> | 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<string, string> \| string \| URLSearchParams | 否 | 入参对象。<br/>- string[][]:字符串二维数组<br/>- Record<string, string>:对象列表<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<[string, string]> | 返回一个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<string> 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<string> | 返回一个所有键值对的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<string> 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<string> | 返回一个所有键值对的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<[string, string]> 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<[string, string]> | 返回一个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-->