企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本文围绕仓颉语言在 OpenHarmony 应用开发中的 SysCap（SystemCapability，系统能力）机制展开，以 ArkUI-CJ API 参考中的canIUse(String)接口为主体，结合能力列表、编译期标签化管控（@IfAvailable）与运行期差异检查等资料，说明如何在一套代码中适配不同系统能力集的设备。读完本文后，你将能够准确判断某个 OpenHarmony 接口在当前设备上是否可用，并掌握“运行期 canIUse 查询 + 编译期 syscap 检查 + 异常兜底”的完整兼容性处理方案。

什么是系统能力（SysCap）

系统能力（SystemCapability，简称 SysCap）指操作系统中每一个相对独立的特性，例如蓝牙、WIFI、NFC、摄像头等，都属于系统能力之一。其核心特征包括：

• 不同设备对应不同的系统能力集：设备根据其硬件能力拼装出各自的 SysCap 集合；
• 每个系统能力对应一个或多个 API：API 与 SysCap 之间存在映射关系；
• SysCap 随设备能力共同存在或消失：开发者可据此判断是否可以使用某个接口。

在仓颉 API 参考文档中，每个接口的描述里都会标注其所需的系统能力，例如：

**系统能力：** SystemCapability.xxx.xxx

同时，文档会在接口描述中标明“起始版本”，如canIUse接口起始版本为 22。字段含义可参考 API 参考开发说明：起始版本号表示接口开始支持的版本，系统能力字段则指明使用该接口所需的 SysCap。

canIUse 接口 API 参考

canIUse是 SysCap 模块提供的核心查询接口，其定义如下（参见 SysCap（系统能力）API 参考）：

public func canIUse(syscap: String): Bool

• 功能：查询系统是否具备某个系统能力。
• 系统能力：SystemCapability.ArkUI.ArkUI.Full
• 起始版本：22

参数说明：

返回值说明：

需要特别说明的前提是：canIUse本身的系统能力要求为SystemCapability.ArkUI.ArkUI.Full，且起始版本为 22。也就是说，只有运行在具备完整 ArkUI 能力、版本不低于 22 的环境上，才能调用该接口进行能力查询。这也是跨端开发中“用能力查询能力”的典型边界条件。

使用示例：判断 API 是否可以使用

系统提供了仓颉 API 用于判断某个接口是否可以使用。以下示例在运行期查询设备是否具备 ArkUI 完整能力（示例源自 系统能力 SystemCapability 使用指南）：

import ohos.base.canIUse if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { Hilog.info(0, "SysCap", "支持系统能力SystemCapability.ArkUI.ArkUI.Full") } else { Hilog.info(0, "SysCap", "不支持系统能力SystemCapability.ArkUI.ArkUI.Full") }

从示例可见，实际开发中的推荐流程是：

1. 查阅目标接口的 API 参考文档，确认其标注的“系统能力”与“起始版本”；
2. 在调用该接口之前，先用canIUse("对应的SysCap名称")进行运行期查询；
3. 查询结果为true时正常调用；为false时走降级逻辑（禁用该功能或提供替代交互）。

能力列表：查询目标设备支持的能力集

SysCap 名称是一个层级化的字符串，例如SystemCapability.Communication.WiFi.STA、SystemCapability.Location.Location.Geocoder。要确定某能力是否被某类设备支持，可以直接查阅仓库中的能力列表：

• Phone 设备最小系统能力集：当前版本 Phone 设备类型支持的最小系统能力集，涵盖SystemCapability.ArkUI.ArkUI.Full、SystemCapability.Base、SystemCapability.Communication.WiFi.Core、SystemCapability.Location.Location.Core等条目；
• Tablet 设备最小系统能力集：当前版本 Tablet 设备类型对应的能力集。

Phone 列表文档中明确了该列表的使用语义：

该列表枚举当前版本 Phone 设备类型支持的最小系统能力集，开发者可以在 sdk 中通过 default.json 文件查询。开发者使用该列表中的系统能力集对应的 API 开发当前版本 Phone 应用时，可直接调用，无需在使用前进行 canIUse() 隔离判断。

这给出了一条重要的实践规则：若目标能力出现在目标设备类型的最小能力集列表中，开发该设备类型的版本时可以直接调用对应 API；只有跨设备类型、或能力不在最小集内时，才必须通过canIUse做运行期隔离。

编译期配合：@IfAvailable 的 syscap 检查

canIUse解决的是运行期问题；仓颉语言还通过@IfAvailable宏表达式在编译期提供 syscap 维度的标签化管控，两者互补（详见 API 标签化管控）。

@IfAvailable的语法为：

@IfAvailable(<label>: <value>, <lambda1>, <lambda2>)

当<label>指定为syscap时，该检查生效。DevEco Studio 默认读取所有设备支持的 SystemCapability 用于检查，检查规则为：

• 调用的 API 满足交集（所有设备同时拥有的能力集合）时，不报错；
• 不满足交集、但满足并集（至少有一个设备拥有的能力集合）时，编译告警；
• 既不满足交集也不满足并集时，编译报错。

文档中给出的示例：假设设备 1 的 syscap 为["SystemCapability.A", "SystemCapability.B"]，设备 2 的 syscap 为["SystemCapability.B", "SystemCapability.C"]，则：

import ohos.sample.* func demo() { @IfAvaliable(syscap: "SystemCapability.D", { => // 此作用域最高允许使用 ["SystemCapability.A", "SystemCapability.B", "SystemCapability.C", "SystemCapability.D"]，其中： // ["SystemCapability.B", "SystemCapability.D"] 不告警； // ["SystemCapability.A", "SystemCapability.C"] 告警； // 非 ["SystemCapability.A", "SystemCapability.B", "SystemCapability.C", "SystemCapability.D"] 报错 f1(); // warning f2(); // ok f3(); // warning f4(); // ok }, { => // 此作用域最高允许使用 ["A", "B", "C"]，其中： // ["B"] 不告警； // ["A", "C"] 告警； // 非 ["A", "B", "C"] 报错 f1(); // warning f2(); // ok f3(); // warning f4(); // error }) }

可以看到，@IfAvailable(syscap: ...)的第一个分支可以“为交集与并集增加能力”——即在其中调用syscap: <value>指定的能力 API 是合法的，而第二个分支不允许。因此，从源码结构看，@IfAvailable与canIUse的分工可以概括为：

• 编译期（@IfAvailable + syscap 注解）：保证“任何设备都不支持的能力”根本无法编译通过，并对“部分设备支持”的能力给出告警，提示开发者补上运行期判断；
• 运行期（canIUse）：在真实设备上动态确认能力是否存在，再决定走哪个功能分支。

不同设备相同能力的差异检查：异常兜底

即使canIUse返回true，相同系统能力在不同设备上的能力深度也可能不同——例如同是摄像头能力，平板设备优于智能穿戴设备。因此，对于接口调用本身还建议用try..catch捕获异常作为最后一道防线。以获取蓝牙已连接设备为例（示例源自 系统能力 SystemCapability 使用指南）：

import kit.ConnectivityKit.* import kit.PerformanceAnalysisKit.Hilog import ohos.business_exception.BusinessException // 在使用接口时可通过try..catch捕获异常。如果接口的SysCap不支持当前设备，将返回801错误码。 try { let hdfProfile = createHfpAgProfile() let retArray = hdfProfile.getConnectedDevices() } catch (e: BusinessException) { Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}") }

关键事实是：当接口的 SysCap 不支持当前设备时，调用将返回 801 错误码。这意味着三层防护缺一不可——能力清单用于开发前评估，canIUse用于调用前隔离，try..catch捕获 801 错误码用于运行期兜底。

系统能力集是如何产生与校验的（背景流程）

为理解canIUse在整个体系中处于什么位置，可以简要梳理 系统能力 SystemCapability 使用指南 中描述的完整链路：

1. 一套操作系统源码由可选和必选部件集组成，部件与 SysCap 之间存在映射关系；
2. 发布归一化的 SDK，API 与 SysCap 之间存在映射关系；
3. 产品解决方案厂商按硬件能力和产品诉求按需拼装部件；
4. 部件可以是系统部件，也可以是三方开发的私有部件，拼装后即可得到该产品的 SysCap 集合；
5. SysCap 集编码生成 PCID（Product Compatibility ID，产品兼容性标识），开发者可将 PCID 导入 DevEco Studio 解码成 SysCap，开发时对设备差异做兼容性处理；
6. 部署到设备上的系统参数中包含 SysCap 集，系统提供 native 接口和应用接口，可供查询某个 SysCap 是否存在；
7. 应用开发过程中，应用必要的 SysCap 将被编码成 RPCID（Required Product Compatibility ID），写入应用安装包；应用安装时，包管理器解码 RPCID 得到应用需要的 SysCap，与设备当前具备的 SysCap 比较，全部满足则安装成功；
8. 应用运行时，可通过 canIUse 接口查询设备的 SysCap，保证在不同设备上的兼容性——这正是本文主体接口所处的环节。

其中，DevEco Studio 工程支持 PCID 导入：在工程目录右键选择 Import Product Compatibility ID，即可上传 PCID 文件并导入至 syscap.json。导入后，syscap.json 中的devices、development.addedSysCaps、production.addedSysCaps/production.removedSysCaps等配置共同决定了工程的“联想能力集”与“要求能力集”；修改要求能力集需谨慎，修改不当会导致应用无法分发到目标设备上。

小结与工程建议

围绕canIUse接口的完整实践路径可以归纳为：

相关文档索引：

• SysCap（系统能力）API 参考：canIUse接口的签名、参数、返回值与版本信息；
• 系统能力 SystemCapability 使用指南：SysCap 概念、PCID 导入、能力集配置与开发指导；
• API 标签化管控：@IfAvailable宏表达式的 level 与 syscap 检查规则；
• API 参考开发说明：版本说明、系统能力字段与仓颉示例代码使用说明。

• 文档
• 知识库
• 教程
• OpenHarmony