1# UserAgent开发指导 2<!--RP1--> 3UserAgent（简称UA）是一个特殊的字符串，它包含了设备类型、操作系统及版本等关键信息。如果页面无法正确识别UA，可能会导致一系列异常情况，例如页面布局错误、渲染问题以及逻辑错误等。 4 5## 默认UserAgent结构 6 7- 默认UserAgent定义 8 9 ```ts 10 Mozilla/5.0 ({DeviceType}; {OSName} {OSVersion}; {DistributionOSName} {DistributionOSVersion}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{ChromeCompatibleVersion}.0.0.0 Safari/537.36 ArkWeb/{ArkWeb VersionCode} {DeviceCompat} {扩展区} 11 ``` 12 13- 举例说明 14 15 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 16 17- 字段说明 18 19 | 字段 | 含义 | 20 | --------------------- | ------------------------------------------------------------ | 21 | DeviceType | 当前的设备类型。<br>取值范围：<br>- Phone：手机<br>- Tablet：平板设备<br>- PC：2in1设备 | 22 | OSName | 基础操作系统名称。<br>默认取值：OpenHarmony | 23 | OSVersion | 基础操作系统版本，两位数字，M.S。<br>通过系统参数const.ohos.fullname解析版本号得到，取版本号部分M.S前两位。<br>默认取值：例如5.0 | 24 | DistributionOSName | 发行版操作系统名称。 | 25 | DistributionOSVersion | 发行版操作系统版本，两位数字，M.S。<br>通过系统参数const.product.os.dist.apiname解析版本号得到，如果该参数值为空，通过系统参数const.product.os.dist.version解析版本号得到，取M.S前两位。<br>默认取值：例如 5.0 | 26 | ChromeCompatibleVersion | 兼容Chrome主版本的版本号，从114版本开始演进。<br>默认取值：114 | 27 | ArkWeb | OpenHarmony版本Web内核名称。<br>默认取值：ArkWeb | 28 | ArkWeb VersionCode | ArkWeb版本号，格式a.b.c.d。<br>默认取值：例如4.1.6.1 | 29 | DeviceCompat | 前向兼容字段。<br>默认取值：Mobile | 30 | 扩展区 | 三方应用可以扩展的字段。<br>三方应用使用ArkWeb组件时，可以做UA扩展，例如加入APP相关信息标识。 | 31 32> **说明：** 33> 34> - 当前通过UserAgent中是否含有"Mobile"字段来判断是否开启前端HTML页面中meta标签的viewport属性。当UserAgent中不含有"Mobile"字段时，meta标签中viewport属性默认关闭，此时可通过显性设置[metaViewport](../reference/apis-arkweb/ts-basic-components-web.md#metaviewport12)属性为true来覆盖关闭状态。 35> 36> - 建议通过OpenHarmony关键字识别是否是OpenHarmony设备，同时可以通过DeviceType识别设备类型用于不同设备上的页面显示（ArkWeb关键字表示设备使用的web内核，OpenHarmony关键字表示设备使用的操作系统，因此推荐通过OpenHarmony关键字识别是否是OpenHarmony设备）。 37 38## 自定义UserAgent结构 39 40在下面的示例中，通过[getUserAgent()](../reference/apis-arkweb/js-apis-webview.md#getuseragent)接口获取当前默认用户代理，支持开发者基于默认的UserAgent去定制UserAgent。 41 42```ts 43// xxx.ets 44import { webview } from '@kit.ArkWeb'; 45import { BusinessError } from '@kit.BasicServicesKit'; 46 47@Entry 48@Component 49struct WebComponent { 50 controller: webview.WebviewController = new webview.WebviewController(); 51 52 build() { 53 Column() { 54 Button('getUserAgent') 55 .onClick(() => { 56 try { 57 let userAgent = this.controller.getUserAgent(); 58 console.log("userAgent: " + userAgent); 59 } catch (error) { 60 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 61 } 62 }) 63 Web({ src: 'www.example.com', controller: this.controller }) 64 } 65 } 66} 67``` 68 69以下示例通过[setCustomUserAgent()](../reference/apis-arkweb/js-apis-webview.md#setcustomuseragent10)接口设置自定义用户代理，会覆盖系统的用户代理。建议将扩展字段追加在默认用户代理的末尾。 70 71当Web组件src设置了url时，建议在onControllerAttached回调事件中设置UserAgent，设置方式请参考示例。不建议将UserAgent设置在onLoadIntercept回调事件中，会概率性出现设置失败。如果未在onControllerAttached回调事件中设置UserAgent。再调用setCustomUserAgent方法时，可能会出现加载的页面与实际设置UserAgent不符的异常现象。 72 73当Web组件src设置为空字符串时，建议先调用setCustomUserAgent方法设置UserAgent，再通过loadUrl加载具体页面。 74 75```ts 76// xxx.ets 77import { webview } from '@kit.ArkWeb'; 78import { BusinessError } from '@kit.BasicServicesKit'; 79 80@Entry 81@Component 82struct WebComponent { 83 controller: webview.WebviewController = new webview.WebviewController(); 84 // 三方应用相关信息标识 85 @State customUserAgent: string = ' DemoApp'; 86 87 build() { 88 Column() { 89 Web({ src: 'www.example.com', controller: this.controller }) 90 .onControllerAttached(() => { 91 console.log("onControllerAttached"); 92 try { 93 let userAgent = this.controller.getUserAgent() + this.customUserAgent; 94 this.controller.setCustomUserAgent(userAgent); 95 } catch (error) { 96 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 97 } 98 }) 99 } 100 } 101} 102``` 103 104在下面的示例中，通过[getCustomUserAgent()](../reference/apis-arkweb/js-apis-webview.md#getcustomuseragent10)接口获取自定义用户代理。 105 106```ts 107// xxx.ets 108import { webview } from '@kit.ArkWeb'; 109import { BusinessError } from '@kit.BasicServicesKit'; 110 111@Entry 112@Component 113struct WebComponent { 114 controller: webview.WebviewController = new webview.WebviewController(); 115 @State userAgent: string = ''; 116 117 build() { 118 Column() { 119 Button('getCustomUserAgent') 120 .onClick(() => { 121 try { 122 this.userAgent = this.controller.getCustomUserAgent(); 123 console.log("userAgent: " + this.userAgent); 124 } catch (error) { 125 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 126 } 127 }) 128 Web({ src: 'www.example.com', controller: this.controller }) 129 } 130 } 131} 132``` 133 134## 常见问题 135 136### 如何通过UserAgent来识别OpenHarmony操作系统中不同设备 137 138OpenHarmony设备的识别主要通过UserAgent中的系统、系统版本和设备类型三个维度来判断。建议同时检查系统、系统版本和设备类型，以确保更准确的设备识别。 139 1401. 系统识别 141 142 通过UserAgent中的{OSName}字段识别OpenHarmony系统。 143 144 ```ts 145 const isOpenHarmony = () => /OpenHarmony/i.test(navigator.userAgent); 146 ``` 147 1482. 系统版本识别 149 150 通过UserAgent中的{OSName}和{OSVersion}字段识别OpenHarmony系统及系统版本。格式为：OpenHarmony + 版本号。 151 152 ```ts 153 const matches = navigator.userAgent.match(/OpenHarmony (\d+\.?\d*)/); 154 matches?.length && Number(matches[1]) >= 5; 155 ``` 156 1573. 设备类型识别 158 159 通过DeviceType字段来识别不同设备类型。 160 161 ```ts 162 // 检测是否为手机设备 163 const isPhone = () => /Phone/i.test(navigator.userAgent); 164 165 // 检测是否为平板设备 166 const isTablet = () => /Tablet/i.test(navigator.userAgent); 167 168 // 检测是否为2in1设备 169 const is2in1 = () => /PC/i.test(navigator.userAgent); 170 ``` 171 172### 如何模拟OpenHarmony操作系统的UserAgent进行前端调试 173 174在Windows/Mac/Linux等操作系统中，可以通过Chrome/Edge/Firefox等浏览器DevTools提供的UserAgent复写能力，模拟OpenHarmony UserAgent。 175<!--RP1End-->