鸿蒙NEXT开发实战往期必看文章:

一分钟了解”纯血版!鸿蒙HarmonyOS Next应用开发!

“非常详细的” 鸿蒙HarmonyOS Next应用开发学习路线!(从零基础入门到精通)

HarmonyOS NEXT应用开发案例实践总结合(持续更新......)

HarmonyOS NEXT应用开发性能优化实践总结(持续更新......)


本模块提供URI字符串解析的相关功能。URI遵循RFC3986规范标准,该标准定义了如何编码和解析用于定位网络资源的标识符,对于非标准场景解析不支持。

说明:

本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

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

URI

构造URI对象,提供判断对象相等、规范路径等方法。

属性

系统能力: SystemCapability.Utils.Lang

名称 类型 可读 可写 说明
scheme string 获取URI的协议部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
userInfo string 获取URI的用户信息部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
host string 获取URI的主机名部分(不带端口),若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
port string 获取URI的端口部分。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
path string 获取URI的路径部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
query string 获取URI的查询部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
fragment string 获取URI的片段部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
authority string 获取此URI的解码权限组件部分,若无此部分则返回null对象。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
ssp string 获取URI的解码方案特定部分,方案特定部分是URI的一部分,它包含了特定于协议或方案的信息。
原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。
encodedUserInfo12+ string 获取URI的编码用户信息部分,若无此部分则返回null对象。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。
encodedPath12+ string 获取URI的编码路径部分,若无此部分则返回null对象。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。
encodedQuery12+ string 获取URI的编码查询部分,若无此部分则返回null对象。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。
encodedFragment12+ string 获取URI的编码片段部分,若无此部分则返回null对象。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。
encodedAuthority12+ string 获取URI的编码权限组件部分,若无此部分则返回null对象。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。
encodedSSP12+ string 获取URI的编码方案特定部分。
原子化服务API: 从API version 12 开始,该接口支持在原子化服务中使用。

命名规则

命名形式:

标准uri定义主要由以下三个部分组成: [scheme:]scheme-specific-part[#fragment]。

将URI格式细化一些则可分为: [scheme:][//authority][path][?query][#fragment]。

将URI格式进一步细化可分为: [scheme:][//[user-info@]host[:port]][path][?query][#fragment]。

  • scheme: 协议名,与scheme-specific-part以:进行分隔,包含scheme部分的URI为绝对URI,不包含scheme部分的URI为相对URI,根据需要填写。例如http、https、ftp、datashare等。
  • scheme-specific-part: URI的特定解码方案特定部分,位于[scheme:]和[#fragment]之间由[//][authority][path][?query]组成,此部分以/开头的为分层URI,不以/开头的为不透明URI,根据需要填写。
    • authority: URI的解码权限组件部分。由[userinfo@]host[:port]组成,根据需要填写。
      • userinfo: 用户信息,与host通过@进行分隔,根据需要填写。
      • host: 服务器的主机名部分,当authority存在时,此项必填。
      • port: 服务器端口,默认值为-1。根据需要填写。
    • path: 路径信息,位于host与query之间以 / 进行分割,根据需要填写。
    • query: 查询部分,位于path和fragment之间,以 ? 开头的键值对格式,以&分割键值对,以=分割键值,根据需要填写。
  • fragment: 片段部分,以#与scheme-specific-part进行分隔,根据需要填写。

URI示例:

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
ts

constructor

constructor(uri: string)

constructor是URI的构造函数。

原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
uri string 入参对象。

错误码:

以下错误码的详细介绍请参见通用错误码语言基础类库错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200002 Invalid uri string.

示例:

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

toString

toString(): string

将URI转化为编码后的字符串。

系统能力: SystemCapability.Utils.Lang

原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。

返回值:

类型 说明
string 返回URI的字符串序列化。

示例:

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
ts

equalsTo9+

equalsTo(other: URI): boolean

判断此URI是否与其他URI对象相等。

原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
other URI 需要比较的URI对象。

返回值:

类型 说明
boolean 返回true表示相等,否则返回false。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

checkIsAbsolute

checkIsAbsolute(): boolean

判断此URI是否为绝对URI(是否定义了scheme组件)。

原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
boolean 如果是绝对URI返回true,否则返回false。

示例:

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
ts

normalize

normalize(): URI

规范化此URI的路径。

原子化服务API: 从API version 11 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
URI 返回一个path被规范化后的URI对象。

示例:

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
let uriInstance1 = uriInstance.normalize();
console.info(uriInstance1.path); // /path/path2/path3
ts

checkRelative12+

checkRelative(): boolean

判断此URI是否为相对URI,相对URI指的是不包含协议(scheme)部分的URI。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
boolean 如果是相对URI返回true,否则返回false。

示例:

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
ts

checkOpaque12+

checkOpaque(): boolean

判断此URI是否为不透明URI,方案特定部分不以“/”开头的URI为不透明的URI。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
boolean 如果是不透明的URI返回true,否则返回false。

示例:

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
ts

checkHierarchical12+

checkHierarchical(): boolean

判断此URI是否为分层URI,方案特定部分以“/”开头的URI为分层的URI。相对URI也是分层的。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
boolean 如果是分层的URI返回true,否则返回false。

示例:

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
ts

getQueryValue12+

getQueryValue(key:string): string

根据给定的查询关键词,从URI查询参数部分中提取出该关键词对应的第一个值,若查询参数中存在已编码过的内容,需将对应Key进行解码后获取Value。

查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
key string 此URI查询参数的名称。

返回值:

类型 说明
string 返回第一个此URI查询参数的值,若未找到对应值则返回null对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

addQueryValue12+

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

在当前URI的基础上添加查询参数,并创建一个新的URI,同时保持原有URI对象不变。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
key string 需要增添查询参数的名称。
value string 需要增添查询参数的值。

返回值:

类型 说明
URI 返回添加查询部分后的URI对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

addSegment12+

addSegment(pathSegment:string): URI

对给定的字段进行编码并将其追加到当前URI的path字段中,并创建一个新的URI返回,同时保持原有URI对象不变。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
pathSegment string 需要追加到路径部分的字段。

返回值:

类型 说明
URI 返回已追加字段的URI对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

addEncodedSegment12+

addEncodedSegment(pathSegment:string): URI

通过将已编码的字段追加到当前URI的path字段中,并创建一个新的URI返回,同时保持原有URI对象不变。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
pathSegment string 需要追加到路径部分的编码字段。

返回值:

类型 说明
URI 返回已追加字段的URI对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

getQueryNames12+

getQueryNames(): string[]

获取URI查询部分中所有不重复的键。查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
string[] 返回此URI查询部分中所有不重复键。

示例:

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
ts

getQueryValues12+

getQueryValues(key:string): string[]

获取此URI中查询参数的所有指定键对应值的集合。若查询参数中存在已编码过的内容,需将对应Key进行解码后获取Value。

查询参数是出现在问号“?”之后的部分,它们由键值对组成,键和值之间用等号“=”连接,键值对之间使用与号“&”分隔。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
key string 指定键的名称。

返回值:

类型 说明
string[] 返回此URI中查询参数内所有指定键对应值的集合,若没有找到则返回一个空字符串数组[]。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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"))); // []
ts

getBooleanQueryValue12+

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

从URI查询参数中获取布尔类型的参数值。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
key string 要获取的查询参数的名称。
defaultValue boolean 返回的默认值。

返回值:

类型 说明
boolean 如果指定的查询参数不存在,则返回默认值;查询参数对应第一个值为“false”或者“0”返回false,否则返回true。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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
ts

clearQuery12+

clearQuery(): URI

清除URI路径查询部分,并创建一个新的URI,同时保持原有URI对象不变。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
URI 返回一个已被清除查询部分的URI对象。

示例:

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

getLastSegment12+

getLastSegment(): string

获取此URI路径的最后一个段。每个段代表路径中的一个部分,通常通过“/”来进行分隔。对于以斜杠结尾的或者没有路径的不代表段。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
string 返回此URI路径中的最后一个段。

示例:

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

getSegment12+

getSegment(): string[]

获取此URI路径中的所有段。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

返回值:

类型 说明
string[] 返回此URI路径中的所有段。

示例:

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

createFromParts12+

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

根据提供的协议、方案特定部分以及片段部分创建一个新的URI。

原子化服务API:从API version 12 开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
scheme string 此URI协议部分。
ssp string 此URI的方案特定部分。
fragment string 此URI的片段部分。片段部分是URI中的一个特定部分,即“#”符号后面的部分。

返回值:

类型 说明
URI 返回创建的URI对象。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例:

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

equals(deprecated)

equals(other: URI): boolean

判断此URI是否与其他URI对象相等。

说明:

从API version 8开始支持,从API version 9开始废弃,建议使用equalsTo9+替代。

系统能力: SystemCapability.Utils.Lang

参数:

参数名 类型 必填 说明
other URI 需要比较的URI对象。

返回值:

类型 说明
boolean 返回true表示相等,否则返回false。

示例:

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

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐