本文同步发表于 微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、User-Agent

User-Agent（UA） 是一个标识客户端设备、操作系统、浏览器等信息的字符串，服务器通过它来识别请求来源，从而提供定制化内容和服务。若页面无法正确识别 UA，可能导致：

• 移动端页面在桌面端显示错乱

• 特定浏览器功能或 CSS 样式因版本不支持而渲染错误或逻辑错误

二、默认 User-Agent 结构

2.1 结构模板

Mozilla/5.0 ({DeviceType}; {OSName} {OSVersion}) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/{ChromeCompatibleVersion}.0.0.0 Safari/537.36
ArkWeb/{ArkWeb VersionCode} {DeviceCompat} {扩展区}

2.2 示例

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

比如：需要识别 HarmonyOS 设备，可以从以下从三个维度识别：

//系统识别：检查 UA 是否包含 OpenHarmony
const isHarmonyOS = () => /OpenHarmony/i.test(navigator.userAgent);


//系统版本识别：通过正则匹配 OpenHarmony 和版本号
// 检测是否是HarmonyOS NEXT系统
const matches = navigator.userAgent.match(/OpenHarmony (\d+\.?\d*)/);
matches?.length && Number(matches[1]) >= 5;


//设备类型识别：通过 Phone、Tablet、PC 识别设备类型
const isPhone = () => /Phone/i.test(navigator.userAgent);
const isTablet = () => /Tablet/i.test(navigator.userAgent);
const is2in1 = () => /PC/i.test(navigator.userAgent);

2.3 字段说明

字段	含义	取值范围/默认值
DeviceType	设备类型	Phone、Tablet、PC（2in1设备）
OSName	操作系统名称	默认为 OpenHarmony
OSVersion	操作系统版本，格式 M.S	从系统参数 const.ohos.fullname 解析
ChromeCompatibleVersion	兼容 Chrome 主版本号	从 114 开始演进
ArkWeb	HarmonyOS Web 内核名称	默认为 ArkWeb
ArkWeb VersionCode	ArkWeb 版本号，格式 a.b.c.d	如 4.1.6.1
DeviceCompat	前向兼容字段	默认为 Mobile
扩展区	三方应用可扩展字段，用于标识 APP 信息	自定义字符串

三、说明

• ArkWeb 字段前有两个空格

• 通过 UA 中是否包含 "Mobile" 字段判断是否开启 <meta name="viewport">。

  • 若不含 "Mobile"，则默认关闭 viewport，可通过 metaViewport 属性显式开启

• 建议通过 OpenHarmony 关键字识别是否为 HarmonyOS 设备

• {DistributionOSName} 和 {DistributionOSVersion} 在 API 15 之前未启用，API 15 起不在默认 UA 中体现

• 若 UA 中同时包含 "HarmonyOS" 和其他系统名称，应将 HarmonyOS 处理逻辑放在其他系统之前

四、自定义 User-Agent

4.1 获取默认 UA

使用 getUserAgent() 获取当前默认 UA：

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Button('getUserAgent')
        .onClick(() => {
          try {
            let userAgent = this.controller.getUserAgent();
            console.log("userAgent: " + userAgent);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

4.2 设置自定义 UA（覆盖系统 UA）

使用 setCustomUserAgent()，建议在默认 UA 末尾追加扩展字段：

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  @State customUserAgent: string = ' DemoApp';

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onControllerAttached(() => {
          console.log("onControllerAttached");
          try {
            let userAgent = this.controller.getUserAgent() + this.customUserAgent;
            this.controller.setCustomUserAgent(userAgent);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
    }
  }
}

注意事项：

• 建议在 onControllerAttached 回调中设置

• 不建议在 onLoadIntercept 中设置，可能出现失败

• 若 src 为空字符串，应先调用 setCustomUserAgent，再 loadUrl

4.3 应用级自定义 UA（API 20+）

• setAppCustomUserAgent()：设置全局 UA

• setUserAgentForHosts()：为特定网站设置 UA

建议流程：

1. 调用 getDefaultUserAgent 获取默认 UA。

2. 调用 setAppCustomUserAgent 或 setUserAgentForHosts。

3. 创建 Web 组件或加载页面。

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear(): void {
    try {
      webview.WebviewController.initializeWebEngine();
      let defaultUserAgent = webview.WebviewController.getDefaultUserAgent();
      let appUA = defaultUserAgent + " appUA";
      webview.WebviewController.setAppCustomUserAgent(appUA);
      webview.WebviewController.setUserAgentForHosts(
        appUA,
        [
          "www.example.com",
          "www.baidu.com"
        ]
      );
    } catch (error) {
      console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
    }
  }

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

4.4 获取自定义 UA

使用 getCustomUserAgent() 获取已设置的自定义 UA：

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  @State userAgent: string = '';

  build() {
    Column() {
      Button('getCustomUserAgent')
        .onClick(() => {
          try {
            this.userAgent = this.controller.getCustomUserAgent();
            console.log("userAgent: " + this.userAgent);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

五、User-Agent 接口优先级

从高到低依次为：

1. setCustomUserAgent：对调用它的 Web 组件生效。

2. setUserAgentForHosts：对应用中所有 Web 组件访问指定网站生效。

3. setAppCustomUserAgent：对应用中所有 Web 组件生效。

4. ArkWeb 默认 UA：只读，通过 getDefaultUserAgent 获取。

总结

• UA 是识别客户端环境的关键字符串，HarmonyOS 中主要由 OpenHarmony 标识系统，ArkWeb 标识内核

• 支持通过多种接口自定义 UA，建议在默认 UA 基础上追加，避免覆盖系统关键信息

• 建议在合适的生命周期回调中设置 UA，避免加载异常

• 通过 UA 可识别设备类型、系统版本，支持多端适配与调试