1# 系统能力SystemCapability使用指南 2 3## 概述 4 5### 系统能力与 API 6 7SysCap，全称SystemCapability，即系统能力，指操作系统中每一个相对独立的特性，如蓝牙，WIFI，NFC，摄像头等，都是系统能力之一。每个系统能力对应多个API，随着目标设备是否支持该系统能力共同存在或消失，也会随着DevEco Studio一起提供给开发者做联想。 8 9 10 11<!--Del-->开发者可以在[SysCap列表](phone-syscap-list.md)中查询OpenHarmony的能力集。<!--DelEnd--> 12 13### 支持能力集，联想能力集与要求能力集 14 15支持能力集，联想能力集与要求能力集都是系统能力的集合。 16 17支持能力集描述的是设备能力，要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集，则应用A可分发到设备N上安装运行，否则不能分发。 18 19联想能力集是该应用开发时，DevEco Studio可联想的API所在的系统能力集合。 20 21 22 23### 设备与支持能力集 24 25每个设备根据其硬件能力，对应不同的支持能力集。 26 27SDK将设备分为两组，典型设备和自定义设备，典型设备的支持能力集由OpenHarmony来定义，自定义设备由设备厂商给出。 28 29 30 31### 设备与SDK能力的对应 32 33SDK向DevEco Studio提供全量API，DevEco Studio识别开发者项目中选择的设备形态，找到该设备的支持能力集，筛选支持能力集包含的API并提供API联想。 34 35 36 37## SysCap开发指导 38 39<!--Del--> 40### PCID获取 41 42PCID，全称Product Compatibility ID，包含当前设备支持的SysCap信息。获取所有设备PCID的认证中心正在建设中，目前需要找对应设备的厂商获取该设备的PCID。 43 44### PCID导入 45 46DevEco Studio工程支持PCID的导入。导入的PCID文件解码后输出的SysCap会被写入syscap.json文件中。 47 48在工程目录右键后选择Import Product Compatibility ID，即可上传PCID文件并导入至syscap.json中。 49 50 51 52### 配置联想能力集和要求能力集 53 54DevEco Studio会根据创建的工程所支持的设置自动配置联想能力集和要求能力集，开发者也可以自行修改。 55对于联想能力集，开发者通过添加更多的系统能力，在DevEco Studio中可以使用更多的API，但要注意这些API可能在设备上不支持，使用前需要判断。 56对于要求能力集，开发者修改时要十分慎重，修改不当会导致应用无法分发到目标设备上。 57 58```json 59// syscap.json 60{ 61 "devices": { 62 "general": [ // 每一个典型设备对应一个syscap支持能力集，可配置多个典型设备 63 "default", 64 "car" 65 ], 66 "custom": [ // 厂家自定义设备 67 { 68 "某自定义设备": [ 69 "SystemCapability.Communication.SoftBus.Core" 70 ] 71 } 72 ] 73 }, 74 "development": { // addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集 75 "addedSysCaps": [ 76 "SystemCapability.Location.Location.Lite" 77 ] 78 }, 79 "production": { // 用于生成rpcid，慎重添加，可能导致应用无法分发到目标设备上 80 "addedSysCaps": [], // devices中配置的各设备支持的syscap集合的交集，添加addedSysCaps集合再除去removedSysCaps集合，共同构成要求能力集 81 "removedSysCaps": [] // 当该要求能力集为某设备的子集时，应用才可被分发到该设备上 82 } 83} 84``` 85<!--DelEnd--> 86 87<!--RP1--><!--RP1End--> 88 89### 单设备应用开发 90 91默认应用的联想能力集，要求系统能力集和设备的支持系统能力集相等，开发者修改要求能力集需要慎重。 92 93 94 95### 跨设备应用开发 96 97默认应用的联想能力集是多个设备支持能力集的并集，要求能力集则是交集。 98 99 100 101### 判断 API 是否可以使用 102 103当前提供了ArkTS API和Native API用于帮助判断某个API是否可以使用。 104 105- ArkTS API 106 107 - 方法1：OpenHarmony定义了API canIUse帮助开发者来判断该设备是否支持某个特定的syscap。 108 109 ```ts 110 if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { 111 console.log("该设备支持SystemCapability.ArkUI.ArkUI.Full"); 112 } else { 113 console.log("该设备不支持SystemCapability.ArkUI.ArkUI.Full"); 114 } 115 ``` 116 117 - 方法2：开发者可通过import的方式将模块导入，若当前设备不支持该模块，import的结果为undefined，开发者在使用其API时，需要判断其是否存在。 118 119 ```ts 120 import geolocationManager from '@ohos.geoLocationManager'; 121 122 try { 123 geolocationManager.getCurrentLocation((location) => { 124 console.log('current location: ' + JSON.stringify(location)); 125 }); 126 } catch(err) { 127 console.error('该设备不支持位置信息' + err); 128 } 129 ``` 130- Native API 131 132 ```c 133 #include <stdio.h> 134 #include <stdlib.h> 135 #include "syscap_ndk.h" 136 137 char syscap[] = "SystemCapability.ArkUI.ArkUI.Full"; 138 bool result = canIUse(syscap); 139 if (result) { 140 printf("SysCap: %s is supported!\n", syscap); 141 } else { 142 printf("SysCap: %s is not supported!\n", syscap); 143 } 144 ``` 145 146除此之外，开发者可以通过API参考文档查询API接口所属的SysCap。 147 148### 不同设备相同能力的差异检查 149 150即使是相同的系统能力，在不同的设备下，也会有能力的差异。比如同是摄像头的能力，平板设备优于智能穿戴设备。 151 152以下示例通过人脸识别功能进行举例： 153 154```ts 155import userAuth from '@ohos.userIAM.userAuth'; 156 157const authParam : userAuth.AuthParam = { 158 challenge: new Uint8Array(), 159 authType: [userAuth.UserAuthType.PIN], 160 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 161}; 162const widgetParam :userAuth.WidgetParam = { 163 title: '请输入密码', 164}; 165 166// 在使用接口时可通过try...catch捕获异常。如果接口的SysCap不支持当前设备，将返回801错误码。 167try { 168 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 169 userAuthInstance.start(); 170 console.log('设备认证成功'); 171} catch (error) { 172 console.error('auth catch error: ' + JSON.stringify(error)); 173} 174``` 175 176### 设备间的SysCap差异如何产生的 177 178设备的SysCap因产品解决方案厂商拼装的部件组合不同而不同，整体流程如下图： 179 180 181 1821. 一套操作系统源码由可选和必选部件集组成，不同的部件为对外体现的系统能力不同，即部件与 SysCap 之间映射关系。 183 1842. 发布归一化的SDK，API与SysCap之间存在映射关系。 185 1863. 产品解决方案厂商按硬件能力和产品诉求，可按需拼装部件。 187 1884. 产品配置的部件可以是系统部件，也可以是三方开发的私有部件，由于部件与SysCap间存在映射，所有拼装后即可得到该产品的SysCap集合。 189 1905. SysCap集编码生成 PCID (Product Compatibility ID， 产品兼容性标识)，应用开发者可将PCID导入IDE解码成SysCap，开发时对设备的SysCap差异做兼容性处理。 191 1926. 部署到设备上的系统参数中包含了SysCap集，系统提供了native的接口和应用接口，可供系统内的部件和应用查询某个SysCap是否存在。 193 1947. 应用开发过程中，应用必要的SysCap将被编码成RPCID（Required Product Compatibility ID），并写入应用安装包中。应用安装时，包管理器将解码RPCID得到应用需要的 SysCap，与设备当前具备的SysCap比较，若应用要求的SysCap都被满足，则安装成功。 195 1968. 应用运行时，可通过canIUse接口查询设备的SysCap，保证在不同设备上的兼容性。 197
