@ohos.uri (URI String Parsing)

The uri module provides APIs for parsing URI strings that comply with the RFC3986 standard. This standard defines how to encode and parse the identifiers used to locate network resources. The module does not support parsing of URIs in non-standard scenarios.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { uri } from '@kit.ArkTS';

URI

Implements a URI, which provides APIs for determining whether objects are equal as well as standard paths.

Attributes

System capability: SystemCapability.Utils.Lang

Naming Rules

Naming format:

A standard URI mainly consists of three parts, as follows:

[scheme:]scheme-specific-part[#fragment]

The generic URI syntax consists of a hierarchical sequence of components, as follows:

[scheme:][//authority][path][?query][#fragment]

It can be further divided into the following parts:

[scheme:][//[user-info@]host[:port]][path][?query][#fragment]

• scheme: scheme name, which is separated from scheme-specific-part by a colon (:). The URI that contains the scheme component is an absolute URI, and the URI that does not contain the scheme component is a relative URI. Set this part as required. Example values: http, https, ftp, and datashare.
• scheme-specific-part: specific part of the URI decoding scheme. It is located between [scheme:] and [#fragment] and consists of [//][authority][path][?query]. The URI that starts with a slash (/) is a hierarchical URI, and the URI that does not start with a slash (/) is an opaque URI. Set this part as required.
  • authority: decoding authority component of the URI. The value consists of [userinfo@]host[:port]. Set this part as required.
    • userinfo: user information, which is separated from host by an at sign (@). Set this part as required.
    • host: host name of the server. This parameter is mandatory when authority exists.
    • port: port number of the server. The default value is -1. Set this part as required.
  • path: path information, which is located between host and query and separated by a slash (/). Set this part as required.
  • query: query component, which is located between path and fragment, indicated by the first question mark (?) character, and is in the format of key-value pairs. Multiple key-value pairs are separated by the at sign (&), and the key and value in a pair is separated by the equal sign (=). Set this part as required.
• fragment: fragment component, which is separated from scheme-specific-part by the pound key (#). Set this part as required.

Example URIs

const uriObj1 = new uri.URI("ftp://ftp.aaa.bbb.ccc/dddd/eee.txt");
console.info(uriObj1.host) // ftp.aaa.bbb.ccc
console.info(uriObj1.fragment) // null
console.info(uriObj1.path) // /dddd/eee.txt
console.info(uriObj1.scheme) // ftp
console.info(uriObj1.userInfo) // null
console.info(uriObj1.port) // -1
console.info(uriObj1.query) // null

const uriObj2 = new uri.URI("gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles#fragment");
console.info(uriObj2.host) // spinaltap.micro.umn.edu
console.info(uriObj2.fragment) // fragment
console.info(uriObj2.path) // /00/Weather/California/Los Angeles
console.info(uriObj2.scheme) // gopher
console.info(uriObj2.userInfo) // null
console.info(uriObj2.port) //-1
console.info(uriObj2.query) // null

const uriObj3 = new uri.URI("datashare:///com.samples.datasharetest.DataShare/DB00/TBL00");
console.info(uriObj3.host) // null
console.info(uriObj3.fragment) // null
console.info(uriObj3.path) // /com.samples.datasharetest.DataShare/DB00/TBL00
console.info(uriObj3.scheme) // datashare
console.info(uriObj3.userInfo) // null
console.info(uriObj3.port) // -1
console.info(uriObj3.query) // null

const uriObj4 = new uri.URI("https://username:password@host:8080/directory/file?foo=1&bar=2#fragment");
console.info(uriObj4.host) // host
console.info(uriObj4.fragment) // fragment
console.info(uriObj4.path) // /directory/file
console.info(uriObj4.scheme) // https
console.info(uriObj4.userInfo) // username:password
console.info(uriObj4.port) // 8080
console.info(uriObj4.query) // foo=1&bar=2

const uriObj5 = new uri.URI("dataability:///com.example.DataAbility");
console.info(uriObj5.host) // null
console.info(uriObj5.fragment) // null
console.info(uriObj5.path) // /com.example.DataAbility:
console.info(uriObj5.scheme) // dataability
console.info(uriObj5.userInfo) // null
console.info(uriObj5.port) // -1
console.info(uriObj5.query) // null

const uriObj6 = new uri.URI("https://username:my+name@host:8080/directory/my+file?foo=1&bar=2#fragment");
console.info(uriObj6.encodedUserInfo) // username:my+name
console.info(uriObj6.encodedPath) // /directory/my+file
console.info(uriObj6.encodedQuery) // foo=1&bar=2
console.info(uriObj6.encodedFragment) // fragment
console.info(uriObj6.encodedAuthority) // username:my+name@host:8080
console.info(uriObj6.encodedSSP) // //username:my+name@host:8080/directory/my+file?foo=1&bar=2

let uriObj7 = new uri.URI("www.abc.com:8080/directory/file?ab=pppppp#qwer=da");
console.log(uriObj7.scheme) // www.abc.com
console.log(uriObj7.host) // null
console.log(uriObj7.port) // -1
console.log(uriObj7.path) // null
console.log(uriObj7.query) // null
console.log(uriObj7.authority) // null
console.log(uriObj7.fragment) // qwer=da
console.log(uriObj7.ssp) // 8080/directory/file?ab=pppppp
console.log("result:", uriObj7.checkIsAbsolute()) // result: true

constructor

constructor(uri: string)

A constructor used to create a URI instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Universal Error Codes and Utils Error Codes.

Example

let mm = 'https://username:password@host:8080/directory/file?foo=1&bar=2#fragment';
new uri.URI(mm);

new uri.URI('https://username:password@host:8080');

toString

toString(): string

Converts this URI into an encoded string.

System capability: SystemCapability.Utils.Lang

Atomic service API: This API can be used in atomic services since API version 11.

Return value

Example

const result = new uri.URI('https://username:password@host:8080/directory/file?ab=pppppp#qwer da');
let result1 = result.toString(); // https://username:password@host:8080/directory/file?ab=pppppp#qwer%20da

equalsTo⁹⁺

equalsTo(other: URI): boolean

Checks whether this URI is the same as another URI object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
const uriInstance1 = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
let result = uriInstance.equalsTo(uriInstance1); // true

checkIsAbsolute

checkIsAbsolute(): boolean

Checks whether this URI is an absolute URI (whether the scheme component is defined).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI('https://username:password@www.qwer.com:8080?query=pppppp');
console.info(`${uriInstance.checkIsAbsolute()}`); // true
const uriInstance1 = new uri.URI('xxx.com/suppliers.htm');
console.info(`${uriInstance1.checkIsAbsolute()}`); // false

normalize

normalize(): URI

Normalizes the path of this URI.

NOTE

If the URI is opaque or its path is already in normalized, the URI is directly returned. Otherwise, a new URI is created. The new URI is similar to the current URI. The only difference relies on its path, which is determined by normalizing the path of the current URI according to the following guidelines:

• All . (dot) segments are removed.

• For any .. (double-dot) segment that is immediately preceded by a segment that is not .., both segments are removed. This process is iterated until no further removals can be made.

If normalization results in a path starting with a .. (double-dot) segment, it indicates that there were insufficient preceding non-.. segments for removal. As a result, the path will start with a .. segment.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI('https://username:password@www.qwer.com:8080/path/path1/../path2/./path3?query=pppppp');
console.info(uriInstance.path); // /path/path1/../path2/./path3
// Following path normalization, all . (dot) segments are removed. If a .. (double-dot) segment is immediately preceded by a segment that is not .., both segments are removed.
let uriInstance1 = uriInstance.normalize();
console.info(uriInstance1.path); // /path/path2/path3
let uri1 = new uri.URI('http://www.test.com/../../patch/path1/../path2/path3/./path4/../');
console.log(uri1.path); // /../../patch/path1/../path2/path3/./path4/../
// If normalization result in a path starting with a .. (double-dot) segment, it indicates that there were insufficient preceding non-.. segments for removal. As a result, the path will start with a .. segment.
let uri2 = uri1.normalize();
console.log(uri2.path); // /../../patch/path2/path3

checkRelative¹²⁺

checkRelative(): boolean

Checks whether this URI is a relative URI. A relative URI does not contain the scheme component.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("https://username:password@www.qwer.com:8080?query=p");
console.info(`${uriInstance.checkRelative()}`); // false
const uriInstance1 = new uri.URI("/images/pic.jpg");
console.info(`${uriInstance1.checkRelative()}`); // true

checkOpaque¹²⁺

checkOpaque(): boolean

Checks whether this URI is an opaque URI. The URI that does not start with a slash (/) is an opaque URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("http://www.test.com/images/pic.jpg");
console.info(`${uriInstance.checkOpaque()}`); // false
const uriInstance1 = new uri.URI("mailto:user@example.com");
console.info(`${uriInstance1.checkOpaque()}`); // true

checkHierarchical¹²⁺

checkHierarchical(): boolean

Checks whether this URI is a hierarchical URI. The URI that starts with a slash (/) in scheme-specific-part is a hierarchical URI. Relative URIs are also hierarchical.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("http://www.test.com/images/pic.jpg");
console.info(`${uriInstance.checkHierarchical()}`); // true
const uriInstance1 = new uri.URI("mailto:user@example.com");
console.info(`${uriInstance1.checkHierarchical()}`); // false

getQueryValue¹²⁺

getQueryValue(key:string): string

Obtains the first value of a given key from the query component of this URI. If the query component contains encoded content, this API decodes the key before obtaining the value.

The query component follows the question mark (?) and consists of key-value pairs, separated by the at sign (&). In each key-value pair, the equal sign (=) is used to connect the key and value.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("https://www.com?param1=value1&param2=value2");
console.info(uriInstance.getQueryValue("param1")); // value1
let uriInstance1 = new uri.URI('https://www.zyy.ss?sa%3D=po%7E');
console.info(uriInstance1.getQueryValue('sa=')) // po~
console.info(uriInstance1.getQueryValue('abc')) // null

addQueryValue¹²⁺

addQueryValue(key:string, value:string): URI

Adds a query parameter to this URI to create a new URI, while keeping the existing URI unchanged.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("https://www.test.com");
const newRoute = uriInstance.addQueryValue("param1", "hello world");
console.info(newRoute.toString()); // https://www.test.com?param1=hello%20world

addSegment¹²⁺

addSegment(pathSegment:string): URI

Encodes a given field, appends it to the path component of this URI to create a new URI, and returns the new URI, while keeping the existing URI unchanged.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("http://www.test.com");
const newRoute = uriInstance.addSegment("my image.jpg");
console.info(newRoute.toString()); // http://www.test.com/my%20image.jpg

addEncodedSegment¹²⁺

addEncodedSegment(pathSegment:string): URI

Appends an encoded field to the path component of this URI to create a new URI and returns the new URI, while keeping the existing URI unchanged.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("http://www.test.com");
const newRoute = uriInstance.addEncodedSegment("my%20image.jpg");
console.info(newRoute.toString()); // http://www.test.com/my%20image.jpg

getQueryNames¹²⁺

getQueryNames(): string[]

Obtains all non-repeated keys in the query component of this URI. The query component follows the question mark (?) and consists of key-value pairs, separated by the at sign (&). In each key-value pair, the equal sign (=) is used to connect the key and value.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("https://www.test.com?param1=value1&param2=value2");
const paramNames = uriInstance.getQueryNames();
console.info(Array.from(paramNames).toString()); // param1,param2

getQueryValues¹²⁺

getQueryValues(key:string): string[]

Obtains the values of a given key from the query component of this URI. If the query component contains encoded content, this API decodes the keys before obtaining the values.

The query component follows the question mark (?) and consists of key-value pairs, separated by the at sign (&). In each key-value pair, the equal sign (=) is used to connect the key and value.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("https://www.test.com/search?query=name&query=my");
console.info(uriInstance.getQueryValues("query").toString()); // name,my
console.info(JSON.stringify(uriInstance.getQueryValues("abc"))); // []

getBooleanQueryValue¹²⁺

getBooleanQueryValue(key:string,defaultValue:boolean): boolean

Obtains the value of the Boolean type of a query parameter in this URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = new uri.URI("https://www.test.com/search?active=true");
console.info(`${uriInstance.getBooleanQueryValue("active", false)}`); // true
const uriInstance1 = new uri.URI("https://www.test.com/search");
console.info(`${uriInstance1.getBooleanQueryValue("active", false)}`); // false
const uriInstance2 = new uri.URI("https://www.test.com/search?active=aa&active=false");
console.info(`${uriInstance2.getBooleanQueryValue("active", false)}`); // true
const uriInstance3 = new uri.URI("https://www.test.com/search?active=0");
console.info(`${uriInstance3.getBooleanQueryValue("active", true)}`); // false
const uriInstance4 = new uri.URI("https://www.test.com/search");
console.info(`${uriInstance4.getBooleanQueryValue("active", true)}`); // true

clearQuery¹²⁺

clearQuery(): URI

Clears the query component of this URI to create a new URI, while keeping the existing URI object unchanged.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("https://www.test.com?param1=value1");
console.info(uriInstance.clearQuery().toString()); // https://www.test.com

getLastSegment¹²⁺

getLastSegment(): string

Obtains the last segment of this URI. A path includes multiple segments, separated by slashes (/). The part that ends with a slash is not a segment.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("content://com.test.provider/files/image.jpg");
console.info(uriInstance.getLastSegment()); // image.jpg

getSegment¹²⁺

getSegment(): string[]

Obtains all segments of this URI.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Return value

Example

const uriInstance = new uri.URI("http://www.test.com/path/to/image.jpg");
console.info(uriInstance.getSegment().toString()); // path,to,image.jpg

createFromParts¹²⁺

createFromParts(scheme: string, ssp: string, fragment: string): URI

Creates a URI based on the provided scheme, scheme-specific-part, and fragment components.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

const uriInstance = uri.URI.createFromParts("mailto", "no body", "top");
console.info(uriInstance.toString()); // mailto:no%20body#top

equals^(deprecated)

equals(other: URI): boolean

Checks whether this URI is the same as another URI object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use equalsTo⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Example

const uriInstance = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
const uriInstance1 = new uri.URI('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
uriInstance.equals(uriInstance1); // true

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS

harmony 鸿蒙Compilation Toolchain Error Codes

harmony 鸿蒙TypeScript Compiler Error Codes

harmony 鸿蒙Utils Error Codes

harmony 鸿蒙js-apis-arkts-collections

harmony 鸿蒙@arkts.math.Decimal (High-Precision Math Library Decimal)

harmony 鸿蒙@arkts.lang (ArkTS Base Capability)

harmony 鸿蒙@arkts.utils (ArkTS Utils)

harmony 鸿蒙@ohos.util.ArrayList (Linear Container ArrayList)

harmony 鸿蒙@ohos.buffer (Buffer)