@ohos.url (URL String Parsing)
NOTE
The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import Url from '@ohos.url'
URLParams9+
constructor9+
constructor(init?: string[][] | Record<string, string> | string | URLSearchParams)
A constructor used to create a URLParams instance.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
init | string[][] | Record<string, string> | string | URLSearchParams | No | Input parameter objects, which include the following: - string[][]: two-dimensional string array - Record<string, string>: list of objects - string: string - URLSearchParams: object |
Example
let objectParams = new Url.URLParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
let objectParams1 = new Url.URLParams({"fod" : '1' , "bard" : '2'});
let objectParams2 = new Url.URLParams('?fod=1&bard=2');
let urlObject = Url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2');
let params = new Url.URLParams(urlObject.search);
append9+
append(name: string, value: string): void
Appends a key-value pair into the query string.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the key-value pair to append. |
value | string | Yes | Value of the key-value pair to append. |
Example
let urlObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLParams(urlObject.search.slice(1));
paramsObject.append('fod', '3');
delete9+
delete(name: string): void
Deletes key-value pairs of the specified key.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the key-value pairs to delete. |
Example
let urlObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLParams(urlObject.search.slice(1));
paramsObject.delete('fod');
getAll9+
getAll(name: string): string[]
Obtains all the values based on the specified key.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Target key. |
Return value
Type | Description |
---|---|
string[] | All the values obtained. |
Example
let urlObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let params = new Url.URLParams(urlObject.search.slice(1));
params.append('fod', '3'); // Add a second value for the fod parameter.
console.log(params.getAll('fod').toString()) // Output ["1","3"].
entries9+
entries(): IterableIterator<[string, string]>
Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<[string, string]> | ES6 iterator. |
Example
let searchParamsObject = new Url.URLParams("keyName1=valueName1&keyName2=valueName2");
for (var pair of searchParamsObject.entries()) { // Show keyName/valueName pairs
console.log(pair[0]+ ', '+ pair[1]);
}
forEach9+
forEach(callbackFn: (value: string, key: string, searchParams: this) => void, thisArg?: Object): void
Traverses the key-value pairs in the URLSearchParams instance by using a callback.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callbackFn | function | Yes | Callback invoked to traverse the key-value pairs in the URLSearchParams instance. |
thisArg | Object | No | Value of this to use when callbackFn is invoked. |
Table 1 callbackFn parameter description
Name | Type | Mandatory | Description |
---|---|---|---|
value | string | Yes | Value that is currently traversed. |
key | string | Yes | Key that is currently traversed. |
searchParams | Object | Yes | Instance that invokes the forEach method. |
Example
const myURLObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
myURLObject.params.forEach((value, name, searchParams) => {
console.log(name, value, myURLObject.params === searchParams);
});
get9+
get(name: string): string | null
Obtains the value of the first key-value pair based on the specified key.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key specified to obtain the value. |
Return value
Type | Description |
---|---|
string | Returns the value of the first key-value pair if obtained. |
null | Returns null if no value is obtained. |
Example
let paramsObject = new Url.URLParams('name=Jonathan&age=18');
let name = paramsObject.get("name"); // is the string "Jonathan"
let age = parseInt(paramsObject.get("age"), 10); // is the number 18
has9+
has(name: string): boolean
Checks whether a key has a value.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key specified to search for its value. |
Return value
Type | Description |
---|---|
boolean | Returns true if the value exists; returns false otherwise. |
Example
let urlObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLParams(urlObject.search.slice(1));
let result = paramsObject.has('bard');
set9+
set(name: string, value: string): void
Sets the value for a key. If key-value pairs matching the specified key exist, the value of the first key-value pair will be set to the specified value and other key-value pairs will be deleted. Otherwise, the key-value pair will be appended to the query string.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the value to set. |
value | string | Yes | Value to set. |
Example
let urlObject = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLParams(urlObject.search.slice(1));
paramsObject.set('baz', '3'); // Add a third parameter.
sort9+
sort(): void
Sorts all key-value pairs contained in this object based on the Unicode code points of the keys and returns undefined. This method uses a stable sorting algorithm, that is, the relative order between key-value pairs with equal keys is retained.
System capability: SystemCapability.Utils.Lang
Example
let searchParamsObject = new Url.URLParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
searchParamsObject.sort(); // Sort the key/value pairs
console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=2&c=3&d=4
keys9+
keys(): IterableIterator<string>
Obtains an ES6 iterator that contains the keys of all the key-value pairs.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<string> | ES6 iterator that contains the keys of all the key-value pairs. |
Example
let searchParamsObject = new Url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
for (var key of searchParamsObject .keys()) { // Output key-value pairs
console.log(key);
}
values9+
values(): IterableIterator<string>
Obtains an ES6 iterator that contains the values of all the key-value pairs.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<string> | ES6 iterator that contains the values of all the key-value pairs. |
Example
let searchParams = new Url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
for (var value of searchParams.values()) {
console.log(value);
}
[Symbol.iterator]9+
[Symbol.iterator](): IterableIterator<[string, string]>
Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<[string, string]> | ES6 iterator. |
Example
const paramsObject = new Url.URLParams('fod=bay&edg=bap');
for (const [name, value] of paramsObject[Symbol.iterator]()) {
console.log(name, value);
}
tostring9+
toString(): string
Obtains search parameters that are serialized as a string and, if necessary, percent-encodes the characters in the string.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
string | String of serialized search parameters, which is percent-encoded if necessary. |
Example
let url = Url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
let params = new Url.URLParams(url.search.slice(1));
params.append('fod', '3');
console.log(params.toString());
URL
Attributes
System capability: SystemCapability.Utils.Lang
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
hash | string | Yes | Yes | String that contains a harsh mark (#) followed by the fragment identifier of a URL. |
host | string | Yes | Yes | Host information in a URL. |
hostname | string | Yes | Yes | Hostname (without the port) in a URL. |
href | string | Yes | Yes | String that contains the whole URL. |
origin | string | Yes | No | Read-only string that contains the Unicode serialization of the origin of the represented URL. |
password | string | Yes | Yes | Password in a URL. |
pathname | string | Yes | Yes | Path in a URL. |
port | string | Yes | Yes | Port in a URL. |
protocol | string | Yes | Yes | Protocol in a URL. |
search | string | Yes | Yes | Serialized query string in a URL. |
searchParams(deprecated) | URLSearchParams | Yes | No | URLSearchParams object allowing access to the query parameters in a URL. - NOTE: This attribute is supported since API version 7 and is deprecated since API version 9. You are advised to use params9+ instead. |
params9+ | URLParams | Yes | No | URLParams object allowing access to the query parameters in a URL. |
username | string | Yes | Yes | Username in a URL. |
constructor(deprecated)
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use parseURL9+ instead.
constructor(url: string, base?: string | URL)
Creates a URL.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
url | string | Yes | Input object. |
base | string | URL | No | Input parameter, which can be any of the following: - string: string - URL: string or object |
Example
let mm = 'https://username:password@host:8080';
let a = new Url.URL("/", mm); // Output 'https://username:password@host:8080/';
let b = new Url.URL(mm); // Output 'https://username:password@host:8080/';
new Url.URL('path/path1', b); // Output 'https://username:password@host:8080/path/path1';
let c = new Url.URL('/path/path1', b); // Output 'https://username:password@host:8080/path/path1';
new Url.URL('/path/path1', c); // Output 'https://username:password@host:8080/path/path1';
new Url.URL('/path/path1', a); // Output 'https://username:password@host:8080/path/path1';
new Url.URL('/path/path1', "https://www.exampleUrl/fr-FR/toto"); // Output https://www.exampleUrl/path/path1
new Url.URL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL
new Url.URL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL
new Url.URL('https://www.example.com', ); // Output https://www.example.com/
new Url.URL('https://www.example.com', b); // Output https://www.example.com/
constructor9+
constructor()
A no-argument constructor used to create a URL. It returns a URL object after parseURL is called. It is not used independently.
System capability: SystemCapability.Utils.Lang
parseURL9+
static parseURL(url : string, base?: string | URL): URL
Parses a URL.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
url | string | Yes | Input object. |
base | string | URL | No | Input parameter, which can be any of the following: - string: string - URL: string or object |
Error codes
For details about the error codes, see Utils Error Codes.
ID | Error Message |
---|---|
10200002 | Invalid url string. |
Example
let mm = 'https://username:password@host:8080';
let url = Url.URL.parseURL(mm);
let result = url.toString(); // Output 'https://username:password@host:8080/'
tostring
toString(): string
Converts the parsed URL into a string.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
string | Website address in a serialized string. |
Example
const url = Url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
let result = url.toString();
toJSON
toJSON(): string
Converts the parsed URL into a JSON string.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
string | Website address in a serialized string. |
Example
const url = Url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
let result = url.toJSON();
URLSearchParams(deprecated)
constructor(deprecated)
constructor(init?: string[][] | Record<string, string> | string | URLSearchParams)
A constructor used to create a URLSearchParams instance.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.constructor9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
init | string[][] | Record<string, string> | string | URLSearchParams | No | Input parameter objects, which include the following: - string[][]: two-dimensional string array - Record<string, string>: list of objects - string: string - URLSearchParams: object |
Example
let objectParams = new Url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
let objectParams1 = new Url.URLSearchParams({"fod" : '1' , "bard" : '2'});
let objectParams2 = new Url.URLSearchParams('?fod=1&bard=2');
let urlObject = new Url.URL('https://developer.mozilla.org/?fod=1&bard=2');
let params = new Url.URLSearchParams(urlObject.search);
append(deprecated)
append(name: string, value: string): void
Appends a key-value pair into the query string.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.append9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the key-value pair to append. |
value | string | Yes | Value of the key-value pair to append. |
Example
let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1));
paramsObject.append('fod', '3');
delete(deprecated)
delete(name: string): void
Deletes key-value pairs of the specified key.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.delete9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the key-value pairs to delete. |
Example
let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsobject = new Url.URLSearchParams(urlObject.search.slice(1));
paramsobject.delete('fod');
getAll(deprecated)
getAll(name: string): string[]
Obtains all the key-value pairs based on the specified key.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.getAll9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Target key. |
Return value
Type | Description |
---|---|
string[] | All key-value pairs matching the specified key. |
Example
let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let params = new Url.URLSearchParams(urlObject.search.slice(1));
params.append('fod', '3'); // Add a second value for the fod parameter.
console.log(params.getAll('fod').toString()) // Output ["1","3"].
entries(deprecated)
entries(): IterableIterator<[string, string]>
Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.entries9+ instead.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<[string, string]> | ES6 iterator. |
Example
let searchParamsObject = new Url.URLSearchParams("keyName1=valueName1&keyName2=valueName2");
for (var pair of searchParamsObject.entries()) { // Show keyName/valueName pairs
console.log(pair[0]+ ', '+ pair[1]);
}
forEach(deprecated)
forEach(callbackFn: (value: string, key: string, searchParams: this) => void, thisArg?: Object): void
Traverses the key-value pairs in the URLSearchParams instance by using a callback.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.forEach9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callbackFn | function | Yes | Callback invoked to traverse the key-value pairs in the URLSearchParams instance. |
thisArg | Object | No | Value of this to use when callbackFn is invoked. |
Table 1 callbackFn parameter description
Name | Type | Mandatory | Description |
---|---|---|---|
value | string | Yes | Value that is currently traversed. |
key | string | Yes | Key that is currently traversed. |
searchParams | Object | Yes | Instance that invokes the forEach method. |
Example
const myURLObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
myURLObject.searchParams.forEach((value, name, searchParams) => {
console.log(name, value, myURLObject.searchParams === searchParams);
});
get(deprecated)
get(name: string): string | null
Obtains the value of the first key-value pair based on the specified key.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.get9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key specified to obtain the value. |
Return value
Type | Description |
---|---|
string | Returns the value of the first key-value pair if obtained. |
null | Returns null if no value is obtained. |
Example
let paramsObject = new Url.URLSearchParams('name=Jonathan&age=18');
let name = paramsObject.get("name"); // is the string "Jonathan"
let age = parseInt(paramsObject.get("age"), 10); // is the number 18
has(deprecated)
has(name: string): boolean
Checks whether a key has a value.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.has9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key specified to search for its value. |
Return value
Type | Description |
---|---|
boolean | Returns true if the value exists; returns false otherwise. |
Example
let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1));
paramsObject.has('bard') === true;
set(deprecated)
set(name: string, value: string): void
Sets the value for a key. If key-value pairs matching the specified key exist, the value of the first key-value pair will be set to the specified value and other key-value pairs will be deleted. Otherwise, the key-value pair will be appended to the query string.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.set9+ instead.
System capability: SystemCapability.Utils.Lang
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Key of the value to set. |
value | string | Yes | Value to set. |
Example
let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1));
paramsObject.set('baz', '3'); // Add a third parameter.
sort(deprecated)
sort(): void
Sorts all key-value pairs contained in this object based on the Unicode code points of the keys and returns undefined. This method uses a stable sorting algorithm, that is, the relative order between key-value pairs with equal keys is retained.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.sort9+ instead.
System capability: SystemCapability.Utils.Lang
Example
let searchParamsObject = new Url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
searchParamsObject.sort(); // Sort the key/value pairs
console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=2&c=3&d=4
keys(deprecated)
keys(): IterableIterator<string>
Obtains an ES6 iterator that contains the keys of all the key-value pairs.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.keys9+ instead.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<string> | ES6 iterator that contains the keys of all the key-value pairs. |
Example
let searchParamsObject = new Url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
for (var key of searchParamsObject .keys()) { // Output key-value pairs
console.log(key);
}
values(deprecated)
values(): IterableIterator<string>
Obtains an ES6 iterator that contains the values of all the key-value pairs.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.values9+ instead.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<string> | ES6 iterator that contains the values of all the key-value pairs. |
Example
let searchParams = new Url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
for (var value of searchParams.values()) {
console.log(value);
}
[Symbol.iterator](deprecated)
[Symbol.iterator](): IterableIterator<[string, string]>
Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.[Symbol.iterator]9+ instead.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
IterableIterator<[string, string]> | ES6 iterator. |
Example
const paramsObject = new Url.URLSearchParams('fod=bay&edg=bap');
for (const [name, value] of paramsObject) {
console.log(name, value);
}
tostring(deprecated)
toString(): string
Obtains search parameters that are serialized as a string and, if necessary, percent-encodes the characters in the string.
NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use URLParams.tostring9+ instead.
System capability: SystemCapability.Utils.Lang
Return value
Type | Description |
---|---|
string | String of serialized search parameters, which is percent-encoded if necessary. |
Example
let url = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2');
let params = new Url.URLSearchParams(url.search.slice(1));
params.append('fod', '3');
console.log(params.toString());