ProxyConfig是ArkWeb框架中用于配置网络代理规则的类,配合ProxyController实现对应用中所有Web组件网络请求的代理控制。通过ProxyConfig,开发者可以灵活定义多种代理规则:指定特定URL使用特定代理服务器、指定某些URL直连服务器、定义绕过代理的规则等。
本模块首批接口从API version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
本Class首批接口从API version 15开始支持。
示例效果请以真机运行为准。
insertProxyRule(proxyRule: string, schemeFilter?: ProxySchemeFilter): void
插入一条代理规则,与schemeFilter匹配的URL都会使用指定代理。如果未指定schemeFilter参数,将使用默认值MATCH_ALL_SCHEMES,所有URL都将使用指定代理。
代理格式为[scheme://]host[:port]。
scheme是可选的,必须是HTTP、HTTPS或SOCKS。scheme默认值为HTTP。
host是带括号的IPv6字面量、IPv4字面量或由点分隔的一个或多个标签。
端口号是可选的,默认HTTP为80、HTTPS为443、SOCKS为1080。
例如:
系统能力: SystemCapability.Web.Webview.Core
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| proxyRule | string | 是 | URL要使用的代理。 |
| schemeFilter | ProxySchemeFilter | 否 | 与schemeFilter匹配的URL会使用代理。 默认值:MATCH_ALL_SCHEMES。 传入undefined或null会抛出异常错误码401。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例:
完整示例代码参考removeProxyOverride。
insertDirectRule(schemeFilter?: ProxySchemeFilter): void
插入一条直连规则,指明符合schemeFilter条件的URL将直接连接到服务器。
系统能力: SystemCapability.Web.Webview.Core
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| schemeFilter | ProxySchemeFilter | 否 | 与schemeFilter匹配的URL会直接与服务器相连。 默认值:MATCH_ALL_SCHEMES。 传入undefined或null会抛出异常错误码401。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例:
完整示例代码参考removeProxyOverride。
insertBypassRule(bypassRule: string): void
插入一条bypass规则,指明哪些URL应该绕过代理并直接连接到服务器。当enableReverseBypass设置为true时,与bypassRule匹配的URL会使用代理而非绕过代理。
系统能力: SystemCapability.Web.Webview.Core
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bypassRule | string | 是 | bypass规则字符串,用于指定绕过代理的URL匹配规则,支持主机名或域名格式(如"example.com"匹配该域名及其子域名)。与bypassRule匹配的URL会绕过代理。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例:
完整示例代码参考removeProxyOverride。
bypassHostnamesWithoutPeriod(): void
没有点字符的域名将绕过代理并直接连接到服务器。
系统能力: SystemCapability.Web.Webview.Core
示例:
完整示例代码参考removeProxyOverride。
clearImplicitRules(): void
默认情况下,如果某些主机名是本地IP地址或localhost地址,它们会绕过代理。调用此函数以覆盖默认行为,并强制将localhost或本地IP地址通过代理发送。
系统能力: SystemCapability.Web.Webview.Core
示例:
完整示例代码参考removeProxyOverride。
enableReverseBypass(reverse: boolean): void
反转bypass规则。
系统能力: SystemCapability.Web.Webview.Core
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reverse | boolean | 是 | 参数值默认是false,表示与insertBypassRule中的bypassRule匹配的URL会绕过代理,参数值为true时,表示与insertBypassRule中的bypassRule匹配的URL会使用代理。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例:
完整示例代码参考removeProxyOverride。
getBypassRules(): Array<string>
获取不使用代理的URL列表。
系统能力: SystemCapability.Web.Webview.Core
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 不使用代理的URL列表。 |
示例:
完整示例代码参考removeProxyOverride。
getProxyRules(): Array<ProxyRule>
获取代理规则。
系统能力: SystemCapability.Web.Webview.Core
返回值:
| 类型 | 说明 |
|---|---|
| Array<ProxyRule> | 代理规则,每个ProxyRule对象表示一条已配置的代理规则。 |
示例:
完整示例代码参考removeProxyOverride。
isReverseBypassEnabled(): boolean
获取enableReverseBypass的参数值,详见enableReverseBypass。
系统能力: SystemCapability.Web.Webview.Core
返回值:
| 类型 | 说明 |
|---|---|
| boolean | enableReverseBypass的参数值。参数值为false,表示与insertBypassRule中的bypassRule匹配的URL会绕过代理,参数值为true时,表示与insertBypassRule中的bypassRule匹配的URL会使用代理。 |
示例:
完整示例代码参考removeProxyOverride。