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 | 是 | 入参对象。 | 542| base | string \| URL | 否 | 入参字符串或者对象。<br/>- string：字符串<br/>- URL：字符串或对象<br/>- 默认值是空字符串或空对象。 | 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 | 是 | 入参对象。 | 586| base | string \| URL | 否 | 入参字符串或者对象。<br/>- string：字符串<br/>- URL：字符串或对象<br/>- 默认值是空字符串或空对象。 | 587 588**错误码：** 589 590以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 591 592| 错误码ID | 错误信息 | 593| -------- | -------- | 594| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 595| 10200002 | Invalid url string. | 596 597**示例：** 598 599```ts 600let mm = 'https://username:password@host:8080'; 601let urlObject = url.URL.parseURL(mm); 602let result = urlObject.toString(); // Output 'https://username:password@host:8080/' 603``` 604 605### toString 606 607toString(): string 608 609将解析过后的URL转化为字符串。 610 611**原子化服务API**：从API version 11 开始，该接口支持在原子化服务中使用。 612 613**系统能力：** SystemCapability.Utils.Lang 614 615**返回值：** 616 617| 类型 | 说明 | 618| -------- | -------- | 619| string | 用于返回网址的字符串序列化。 | 620 621**示例：** 622 623```ts 624const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 625let result = urlObject.toString(); // Output 'https://username:password@host:8080/directory/file?query=pppppp#qwer=da' 626``` 627 628### toJSON 629 630toJSON(): string 631 632将解析过后的URL转化为JSON字符串。 633 634**原子化服务API**：从API version 11 开始，该接口支持在原子化服务中使用。 635 636**系统能力：** SystemCapability.Utils.Lang 637 638**返回值：** 639 640| 类型 | 说明 | 641| -------- | -------- | 642| string | 用于返回网址的字符串序列化。 | 643 644**示例：** 645```ts 646const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 647let result = urlObject.toJSON(); 648``` 649 650## URLSearchParams<sup>(deprecated)</sup> 651 652URLSearchParams接口定义了一些处理URL查询字符串的实用方法，从API version 9开始废弃，建议使用[URLParams](#urlparams9)。 653 654### constructor<sup>(deprecated)</sup> 655 656constructor(init?: string[][] | Record<string, string> | string | URLSearchParams) 657 658URLSearchParams的构造函数。 659 660> **说明：** 661> 662> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.constructor<sup>9+</sup>](#constructor9)替代。 663 664**系统能力：** SystemCapability.Utils.Lang 665 666**参数：** 667 668| 参数名 | 类型 | 必填 | 说明 | 669| -------- | -------- | -------- | -------- | 670| init | string[][] \| Record<string, string> \| string \| URLSearchParams | 否 | 入参对象。<br/>- string[][]：字符串二维数组<br/>- Record<string, string>：对象列表<br/>- string：字符串<br/>- URLSearchParams：对象<br/>- 默认值：null。 | 671 672**示例：** 673 674```ts 675let objectParams = new url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]); 676let objectParams1 = new url.URLSearchParams({"fod" : '1' , "bard" : '2'}); 677let objectParams2 = new url.URLSearchParams('?fod=1&bard=2'); 678let urlObject = new url.URL('https://developer.mozilla.org/?fod=1&bard=2'); 679let params = new url.URLSearchParams(urlObject.search); 680``` 681 682### append<sup>(deprecated)</sup> 683 684append(name: string, value: string): void 685 686将新的键值对插入到查询字符串。 687 688> **说明：** 689> 690> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.append<sup>9+</sup>](#append9)替代。 691 692**系统能力：** SystemCapability.Utils.Lang 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| -------- | -------- | -------- | -------- | 698| name | string | 是 | 需要插入搜索参数的键名。 | 699| value | string | 是 | 需要插入搜索参数的值。 | 700 701**示例：** 702 703```ts 704let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 705let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 706paramsObject.append('fod', '3'); 707``` 708 709### delete<sup>(deprecated)</sup> 710 711delete(name: string): void 712 713删除指定名称的键值对。 714 715> **说明：** 716> 717> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.delete<sup>9+</sup>](#delete9)替代。 718 719**系统能力：** SystemCapability.Utils.Lang 720 721**参数：** 722 723| 参数名 | 类型 | 必填 | 说明 | 724| -------- | -------- | -------- | -------- | 725| name | string | 是 | 需要删除的键值名称。 | 726 727**示例：** 728 729```ts 730let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 731let paramsobject = new url.URLSearchParams(urlObject.search.slice(1)); 732paramsobject.delete('fod'); 733``` 734 735### getAll<sup>(deprecated)</sup> 736 737getAll(name: string): string[] 738 739获取指定名称的所有键值对。 740 741> **说明：** 742> 743> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.getAll<sup>9+</sup>](#getall9)替代。 744 745**系统能力：** SystemCapability.Utils.Lang 746 747**参数：** 748 749| 参数名 | 类型 | 必填 | 说明 | 750| -------- | -------- | -------- | -------- | 751| name | string | 是 | 指定的键值名称。 | 752 753**返回值：** 754 755| 类型 | 说明 | 756| -------- | -------- | 757| string[] | 返回指定名称的所有键值对。 | 758 759**示例：** 760 761```ts 762let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 763let params = new url.URLSearchParams(urlObject.search.slice(1)); 764params.append('fod', '3'); // Add a second value for the fod parameter. 765console.log(params.getAll('fod').toString()) // Output ["1","3"]. 766``` 767 768### entries<sup>(deprecated)</sup> 769 770entries(): IterableIterator<[string, string]> 771 772返回一个ES6的迭代器，迭代器的每一项都是一个 JavaScript Array。Array的第一项是name，Array的第二项是value。 773 774> **说明：** 775> 776> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.entries<sup>9+</sup>](#entries9)替代。 777 778**系统能力：** SystemCapability.Utils.Lang 779 780**返回值：** 781 782| 类型 | 说明 | 783| -------- | -------- | 784| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 785 786**示例：** 787 788```ts 789let searchParamsObject = new url.URLSearchParams("keyName1=valueName1&keyName2=valueName2"); 790let iter: Iterable<Object[]> = searchParamsObject.entries(); 791let pairs = Array.from(iter); 792for (let pair of pairs) { // Show keyName/valueName pairs 793 console.log(pair[0]+ ', '+ pair[1]); 794} 795``` 796 797 798### forEach<sup>(deprecated)</sup> 799 800forEach(callbackFn: (value: string, key: string, searchParams: URLSearchParams) => void, thisArg?: Object): void 801 802通过回调函数来遍历URLSearchParams实例对象上的键值对。 803 804> **说明：** 805> 806> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.forEach<sup>9+</sup>](#foreach9)替代。 807 808**系统能力：** SystemCapability.Utils.Lang 809 810**参数：** 811 812| 参数名 | 类型 | 必填 | 说明 | 813| -------- | -------- | -------- | -------- | 814| callbackFn | function | 是 | 回调函数。 | 815| thisArg | Object | 否 | callbackFn被调用时用作this值，默认值是本对象。 | 816 817**表1** callbackFn的参数说明 818 819| 参数名 | 类型 | 必填 | 说明 | 820| -------- | -------- | -------- | -------- | 821| value | string | 是 | 当前遍历到的键值。 | 822| key | string | 是 | 当前遍历到的键名。 | 823| searchParams | [URLSearchParams](#urlsearchparamsdeprecated) | 是 | 当前调用forEach方法的实例对象。 | 824 825**示例：** 826 827```ts 828const myURLObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 829myURLObject.searchParams.forEach((value, name, searchParams) => { 830 console.log(name, value, myURLObject.searchParams === searchParams); 831}); 832``` 833 834 835### get<sup>(deprecated)</sup> 836 837get(name: string): string | null 838 839获取指定名称对应的第一个值。 840 841> **说明：** 842> 843> 若查找一个不存在的键值对名称时返回值为undefined，从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.get<sup>9+</sup>](#get9)替代。 844 845 846**系统能力：** SystemCapability.Utils.Lang 847 848**参数：** 849 850| 参数名 | 类型 | 必填 | 说明 | 851| -------- | -------- | -------- | -------- | 852| name | string | 是 | 指定键值对的名称。 | 853 854**返回值：** 855 856| 类型 | 说明 | 857| -------- | -------- | 858| string | 返回第一个值。 | 859| null | 如果没找到，返回 null。 | 860 861**示例：** 862 863```ts 864let paramsObject = new url.URLSearchParams('name=Jonathan&age=18'); 865let name = paramsObject.get("name"); // is the string "Jonathan" 866let age = paramsObject.get("age"); // is the string '18' 867let getObj = paramsObject.get("abc"); // undefined 868``` 869 870 871### has<sup>(deprecated)</sup> 872 873has(name: string): boolean 874 875判断一个指定的键名对应的值是否存在。 876 877> **说明：** 878> 879> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.has<sup>9+</sup>](#has9)替代。 880 881**系统能力：** SystemCapability.Utils.Lang 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| -------- | -------- | -------- | -------- | 887| name | string | 是 | 要查找的参数的键名。 | 888 889**返回值：** 890 891| 类型 | 说明 | 892| -------- | -------- | 893| boolean | 是否存在相对应的key值，存在返回true，否则返回false。 | 894 895**示例：** 896 897```ts 898let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 899let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 900paramsObject.has('bard') === true; 901``` 902 903 904### set<sup>(deprecated)</sup> 905 906set(name: string, value: string): void 907 908将与name关联的URLSearchParams对象中的值设置为value。如果存在名称为name的键值对，请将第一个键值对的值设置为value并删除所有其他值。如果不是，则将键值对附加到查询字符串。 909 910> **说明：** 911> 912> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.set<sup>9+</sup>](#set9)替代。 913 914**系统能力：** SystemCapability.Utils.Lang 915 916**参数：** 917 918| 参数名 | 类型 | 必填 | 说明 | 919| -------- | -------- | -------- | -------- | 920| name | string | 是 | 将要设置的参数的键值名。 | 921| value | string | 是 | 所要设置的参数值。 | 922 923**示例：** 924 925```ts 926let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 927let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 928paramsObject.set('baz', '3'); // Add a third parameter. 929``` 930 931 932### sort<sup>(deprecated)</sup> 933 934sort(): void 935 936对包含在此对象中的所有键值对进行排序，并返回undefined。排序顺序是根据键的Unicode代码点。该方法使用稳定的排序算法 （即，将保留具有相等键的键值对之间的相对顺序）。 937 938> **说明：** 939> 940> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.sort<sup>9+</sup>](#sort9)替代。 941 942**系统能力：** SystemCapability.Utils.Lang 943 944**示例：** 945 946```ts 947let searchParamsObject = new url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object 948searchParamsObject.sort(); // Sort the key/value pairs 949console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2 950``` 951 952 953### keys<sup>(deprecated)</sup> 954 955keys(): IterableIterator<string> 956 957返回一个所有键值对的name的ES6迭代器。 958 959> **说明：** 960> 961> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.keys<sup>9+</sup>](#keys9)替代。 962 963**系统能力：** SystemCapability.Utils.Lang 964 965**返回值：** 966 967| 类型 | 说明 | 968| -------- | -------- | 969| IterableIterator<string> | 返回一个所有键值对的name的ES6迭代器。 | 970 971**示例：** 972 973```ts 974let searchParamsObject = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing 975let keys = Array.from(searchParamsObject.keys()); 976for (let key of keys) { // Output key-value pairs 977 console.log(key); 978} 979``` 980 981 982### values<sup>(deprecated)</sup> 983 984values(): IterableIterator<string> 985 986返回一个所有键值对的value的ES6迭代器。 987 988> **说明：** 989> 990> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.values<sup>9+</sup>](#values9)替代。 991 992**系统能力：** SystemCapability.Utils.Lang 993 994**返回值：** 995 996| 类型 | 说明 | 997| -------- | -------- | 998| IterableIterator<string> | 返回一个所有键值对的value的ES6迭代器。 | 999 1000**示例：** 1001 1002```ts 1003let searchParams = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing 1004let values = Array.from(searchParams.values()); 1005for (let value of values) { 1006 console.log(value); 1007} 1008``` 1009 1010 1011### [Symbol.iterator]<sup>(deprecated)</sup> 1012 1013[Symbol.iterator]\(): IterableIterator<[string, string]> 1014 1015返回一个ES6的迭代器，迭代器的每一项都是一个 JavaScript Array。Array的第一项是name，Array的第二项是value。 1016 1017> **说明：** 1018> 1019> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.[Symbol.iterator]<sup>9+</sup>](#symboliterator9)替代。 1020 1021**系统能力：** SystemCapability.Utils.Lang 1022 1023**返回值：** 1024 1025| 类型 | 说明 | 1026| -------- | -------- | 1027| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 1028 1029**示例：** 1030 1031```ts 1032const paramsObject = new url.URLSearchParams('fod=bay&edg=bap'); 1033let iter: Iterable<Object[]> = paramsObject[Symbol.iterator](); 1034let pairs = Array.from(iter); 1035for (let pair of pairs) { 1036 console.log(pair[0] + ', ' + pair[1]); 1037} 1038``` 1039 1040### toString<sup>(deprecated)</sup> 1041 1042toString(): string 1043 1044返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 1045 1046> **说明：** 1047> 1048> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.toString<sup>9+</sup>](#tostring9)替代。 1049 1050**系统能力：** SystemCapability.Utils.Lang 1051 1052**返回值：** 1053 1054| 类型 | 说明 | 1055| -------- | -------- | 1056| string | 返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 | 1057 1058**示例：** 1059 1060```ts 1061let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 1062let params = new url.URLSearchParams(urlObject.search.slice(1)); 1063params.append('fod', '3'); 1064console.log(params.toString()); // Output 'fod=1&bard=2&fod=3' 1065``` 1066<!--no_check-->