• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# User-Agent开发指导
2<!--Kit: ArkWeb-->
3<!--Subsystem: Web-->
4<!--Owner: @aohui-->
5<!--Designer: @yaomingliu-->
6<!--Tester: @ghiker-->
7<!--Adviser: @HelloCrease-->
8<!--RP1-->
9User-Agent（简称UA）是一个特殊的字符串，包含设备类型、操作系统及版本等关键信息。在Web开发中，这个字符串使服务器能够识别请求的来源设备及其特性，从而根据这些信息提供定制化的内容和服务。如果页面无法正确识别UA，可能会导致多种异常情况。例如，为移动设备优化的页面布局可能会在桌面设备上显示错乱，反之亦然。此外，某些特定的浏览器功能或CSS样式可能仅在特定的浏览器版本中受支持，如果页面无法根据UA字符串做出正确的判断，就可能导致渲染问题或逻辑错误。
10
11## 默认User-Agent结构
12
13- 默认User-Agent定义
14
15  ```ts
16  Mozilla/5.0 ({DeviceType}; {OSName} {OSVersion}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{ChromeCompatibleVersion}.0.0.0 Safari/537.36  ArkWeb/{ArkWeb VersionCode} {DeviceCompat} {扩展区}
17  ```
18
19- 举例说明
20
21  ```ts
22  Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36  ArkWeb/4.1.6.1 Mobile
23  ```
24
25- 字段说明
26
27  | 字段                  | 含义                                                         |
28  | --------------------- | ------------------------------------------------------------ |
29  | DeviceType            | 当前的设备类型。<br>取值范围：<br>- Phone：手机<br>- Tablet：平板设备<br>-  PC：2in1设备 |
30  | OSName                | 基础操作系统名称。<br>默认取值：OpenHarmony                  |
31  | OSVersion             | 基础操作系统版本，两位数字，M.S。<br>通过系统参数const.ohos.fullname解析版本号得到，取版本号部分M.S前两位。<br>默认取值：例如5.0       |
32  | ChromeCompatibleVersion | 兼容Chrome主版本的版本号，从114版本开始演进。<br>默认取值：114            |
33  | ArkWeb                | OpenHarmony版本Web内核名称。<br>默认取值：ArkWeb             |
34  | ArkWeb VersionCode    | ArkWeb版本号，格式a.b.c.d。<br>默认取值：例如4.1.6.1         |
35  | DeviceCompat          | 前向兼容字段。<br>默认取值：Mobile                          |
36  | 扩展区                | 三方应用可以扩展的字段。<br>三方应用使用ArkWeb组件时，可以做UA扩展，例如加入APP相关信息标识。 |
37
38> **说明：**
39>
40> - 当前默认User-Agent的ArkWeb字段前有两个空格。
41>
42> - 当前通过User-Agent中是否含有"Mobile"字段来判断是否开启前端HTML页面中meta标签的viewport属性。当User-Agent中不含有"Mobile"字段时，meta标签中viewport属性默认关闭，此时可通过显性设置[metaViewport](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#metaviewport12)属性为true来覆盖关闭状态。
43>
44> - 建议通过OpenHarmony关键字识别是否是OpenHarmony设备，同时可以通过DeviceType识别设备类型用于不同设备上的页面显示（ArkWeb关键字表示设备使用的web内核，OpenHarmony关键字表示设备使用的操作系统，因此推荐通过OpenHarmony关键字识别是否是OpenHarmony设备）。
45>
46> - {DistributionOSName}和{DistributionOSVersion}字段在API version 15之前的版本中未启用，从API version 15版本开始不在默认User-Agent中体现。
47
48## 自定义User-Agent结构
49
50在下面的示例中，通过调用[getUserAgent()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#getuseragent)接口获取当前默认的用户代理（User-Agent）字符串。这一接口提供的默认User-Agent信息为开发者提供了基础，使开发者能够基于这个默认信息进行定制或扩展。
51
52```ts
53// xxx.ets
54import { webview } from '@kit.ArkWeb';
55import { BusinessError } from '@kit.BasicServicesKit';
56
57@Entry
58@Component
59struct WebComponent {
60  controller: webview.WebviewController = new webview.WebviewController();
61
62  build() {
63    Column() {
64      Button('getUserAgent')
65        .onClick(() => {
66          try {
67            let userAgent = this.controller.getUserAgent();
68            console.log("userAgent: " + userAgent);
69          } catch (error) {
70            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
71          }
72        })
73      Web({ src: 'www.example.com', controller: this.controller })
74    }
75  }
76}
77```
78
79以下示例通过[setCustomUserAgent()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setcustomuseragent10)接口设置自定义用户代理，但请注意，此操作会覆盖系统的用户代理。因此，我们建议将扩展字段追加在默认用户代理的末尾，比如三方应用程序的开发场景，可以在系统默认用户代理字符串的末尾追加特定的APP标识，这样既能保留原有用户代理信息，又能增加自定义的应用识别信息。
80
81当Web组件src设置了url时，建议在onControllerAttached回调事件中设置User-Agent，设置方式请参考示例。不建议将User-Agent设置在onLoadIntercept回调事件中，会概率性出现设置失败。如果未在onControllerAttached回调事件中设置User-Agent。再调用setCustomUserAgent方法时，可能会出现加载的页面与实际设置User-Agent不符的异常现象。
82
83当Web组件src设置为空字符串时，建议先调用setCustomUserAgent方法设置User-Agent，再通过loadUrl加载具体页面。
84
85```ts
86// xxx.ets
87import { webview } from '@kit.ArkWeb';
88import { BusinessError } from '@kit.BasicServicesKit';
89
90@Entry
91@Component
92struct WebComponent {
93  controller: webview.WebviewController = new webview.WebviewController();
94  // 三方应用相关信息标识
95  @State customUserAgent: string = ' DemoApp';
96
97  build() {
98    Column() {
99      Web({ src: 'www.example.com', controller: this.controller })
100      .onControllerAttached(() => {
101        console.log("onControllerAttached");
102        try {
103          let userAgent = this.controller.getUserAgent() + this.customUserAgent;
104          this.controller.setCustomUserAgent(userAgent);
105        } catch (error) {
106          console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
107        }
108      })
109    }
110  }
111}
112```
113
114从API version 20开始，可通过[setAppCustomUserAgent()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setappcustomuseragent20)接口设置应用级自定义用户代理，或者通过[setUserAgentForHosts()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setuseragentforhosts20)对特定网站设置应用级自定义用户代理，覆盖系统的用户代理，应用内所有Web组件生效。
115
116建议在Web组件创建前先调用静态接口[getDefaultUserAgent](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#getdefaultuseragent14)获取默认的用户代理（User-Agent）字符串，然后调用setAppCustomUserAgent，setUserAgentForHosts方法设置User-Agent，再创建指定src的Web组件或通过loadUrl加载具体页面。
117
118```ts
119// xxx.ets
120import { webview } from '@kit.ArkWeb';
121import { BusinessError } from '@kit.BasicServicesKit';
122
123@Entry
124@Component
125struct WebComponent {
126  controller: webview.WebviewController = new webview.WebviewController();
127
128  aboutToAppear(): void {
129    try {
130      webview.WebviewController.initializeWebEngine();
131      let defaultUserAgent = webview.WebviewController.getDefaultUserAgent();
132      let appUA = defaultUserAgent + " appUA";
133      webview.WebviewController.setAppCustomUserAgent(appUA);
134      webview.WebviewController.setUserAgentForHosts(
135        appUA,
136        [
137          "www.example.com",
138          "www.baidu.com"
139        ]
140      );
141    } catch (error) {
142      console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
143    }
144  }
145
146  build() {
147    Column() {
148      Web({ src: 'www.example.com', controller: this.controller })
149    }
150  }
151}
152```
153
154在下面的示例中，通过[getCustomUserAgent()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#getcustomuseragent10)接口获取自定义用户代理。
155
156```ts
157// xxx.ets
158import { webview } from '@kit.ArkWeb';
159import { BusinessError } from '@kit.BasicServicesKit';
160
161@Entry
162@Component
163struct WebComponent {
164  controller: webview.WebviewController = new webview.WebviewController();
165  @State userAgent: string = '';
166
167  build() {
168    Column() {
169      Button('getCustomUserAgent')
170        .onClick(() => {
171          try {
172            this.userAgent = this.controller.getCustomUserAgent();
173            console.log("userAgent: " + this.userAgent);
174          } catch (error) {
175            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
176          }
177        })
178      Web({ src: 'www.example.com', controller: this.controller })
179    }
180  }
181}
182```
183
184## 相关User-Agent接口优先级
185
186| 接口名称 | 优先级 | 说明 |
187| -------- | -------- | -------- |
188| setCustomUserAgent | 最高 | 对调用的Web组件生效。|
189| setUserAgentForHosts | 低于setCustomUserAgent | 对应用中所有Web组件访问指定网站生效。|
190| setAppCustomUserAgent | 低于setUserAgentForHosts | 对应用中所有Web组件生效。 |
191|  ArkWeb默认UA | 最低 | 对应用中所有Web组件生效，只读，通过getDefaultUserAgent获取。|
192
193## 常见问题
194
195### 如何通过User-Agent来识别OpenHarmony操作系统中不同设备
196
197OpenHarmony设备的识别主要通过User-Agent中的系统、系统版本和设备类型三个维度来判断。建议同时检查系统、系统版本和设备类型，以确保更准确的设备识别。
198
1991. 系统识别
200
201   通过User-Agent中的{OSName}字段识别OpenHarmony系统。
202
203   ```ts
204   const isOpenHarmony = () => /OpenHarmony/i.test(navigator.userAgent);
205   ```
206
2072. 系统版本识别
208
209   通过User-Agent中的{OSName}和{OSVersion}字段识别OpenHarmony系统及系统版本。格式为：OpenHarmony + 版本号。
210
211   ```ts
212   const matches = navigator.userAgent.match(/OpenHarmony (\d+\.?\d*)/);
213   matches?.length && Number(matches[1]) > 0;
214   ```
215
2163. 设备类型识别
217
218    通过deviceType字段来识别不同设备类型。
219
220   ```ts
221   // 检测是否为手机设备
222   const isPhone = () => /Phone/i.test(navigator.userAgent);
223
224   // 检测是否为平板设备
225   const isTablet = () => /Tablet/i.test(navigator.userAgent);
226
227   // 检测是否为2in1设备
228   const is2in1 = () => /PC/i.test(navigator.userAgent);
229   ```
230
231### 如何模拟OpenHarmony操作系统的User-Agent进行前端调试
232
233在Windows/Mac/Linux等操作系统中，可以通过Chrome/Edge/Firefox等浏览器DevTools提供的User-Agent复写能力，模拟OpenHarmony User-Agent。
234
235### 如何在OpenHarmony中自定义User-Agent以实现H5兼容性
236
237OpenHarmony提供[setCustomUserAgent](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setcustomuseragent10)接口以支持User-Agent的自定义设置。为适配移动端H5页面通常依赖的UA标识检测（如Mobile、Android等），并确保不覆盖系统默认UA信息，推荐按如下方式操作：首先通过[setCustomUserAgent()](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setcustomuseragent10)接口获取系统默认User-Agent字符串，随后将H5兼容所需的自定义标识字段追加至该字符串末尾，最后调用setCustomUserAgent接口设置修改后的完整UA字符串。
238<!--RP1End-->