1# 系统能力SystemCapability使用指南 2 3## 概述 4 5### 系统能力与 API 6 7SysCap,全称SystemCapability,即系统能力,指操作系统中每一个相对独立的特性,如蓝牙,WIFI,NFC,摄像头等,都是系统能力之一。每个系统能力对应多个API,随着目标设备是否支持该系统能力共同存在或消失,也会随着DevEco Studio一起提供给开发者做联想。 8 9![image-20220326064841782](figures/image-20220326064841782.png) 10 11开发者可以在[SysCap列表](syscap-list.md)中查询OpenHarmony的能力集。 12 13### 支持能力集,联想能力集与要求能力集 14 15支持能力集,联想能力集与要求能力集都是系统能力的集合。 16支持能力集描述的是设备能力,要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集,则应用A可分发到设备N上安装运行,否则不能分发。 17联想能力集是该应用开发时,DevEco Studio可联想的API所在的系统能力集合。 18 19![image-20220326064913834](figures/image-20220326064913834.png) 20 21### 设备与支持能力集 22 23每个设备根据其硬件能力,对应不同的支持能力集。 24SDK将设备分为两组,典型设备和自定义设备,典型设备的支持能力集由OpenHarmony来定义,自定义设备由设备厂商给出。 25 26![image-20220326064955505](figures/image-20220326064955505.png) 27 28### 设备与SDK能力的对应 29 30SDK向DevEco Studio提供全量API,DevEco Studio识别开发者项目中选择的设备形态,找到该设备的支持能力集,筛选支持能力集包含的API并提供API联想。 31 32![image-20220326065043006](figures/image-20220326065043006.png) 33 34## SysCap开发指导 35 36### PCID获取 37 38PCID,全称Product Compatibility ID,包含当前设备支持的SysCap信息。获取所有设备PCID的认证中心正在建设中,目前需要找对应设备的厂商获取该设备的PCID。 39 40### PCID导入 41 42DevEco Studio工程支持PCID的导入。导入的PCID文件解码后输出的SysCap会被写入syscap.json文件中。 43 44在工程目录右键后选择Import Product Compatibility ID,即可上传PCID文件并导入至syscap.json中。 45 46![20220329-103626](figures/20220329-103626.gif) 47 48### 配置联想能力集和要求能力集 49 50DevEco Studio会根据创建的工程所支持的设置自动配置联想能力集和要求能力集,开发者也可以自行修改。 51对于联想能力集,开发者通过添加更多的系统能力,在DevEco Studio中可以使用更多的API,但要注意这些API可能在设备上不支持,使用前需要判断。 52对于要求能力集,开发者修改时要十分慎重,修改不当会导致应用无法分发到目标设备上。 53 54```json 55// syscap.json 56{ 57 "devices": { 58 "general": [ // 每一个典型设备对应一个syscap支持能力集,可配置多个典型设备 59 "default", 60 "car" 61 ], 62 "custom": [ // 厂家自定义设备 63 { 64 "某自定义设备": [ 65 "SystemCapability.Communication.SoftBus.Core" 66 ] 67 } 68 ] 69 }, 70 "development": { // addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集 71 "addedSysCaps": [ 72 "SystemCapability.Location.Location.Lite" 73 ] 74 }, 75 "production": { // 用于生成rpcid,慎重添加,可能导致应用无法分发到目标设备上 76 "addedSysCaps": [], // devices中配置的各设备支持的syscap集合的交集,添加addedSysCaps集合再除去removedSysCaps集合,共同构成要求能力集 77 "removedSysCaps": [] // 当该要求能力集为某设备的子集时,应用才可被分发到该设备上 78 } 79} 80``` 81 82### 单设备应用开发 83 84默认应用的联想能力集,要求系统能力集和设备的支持系统能力集相等,开发者修改要求能力集需要慎重。 85 86![image-20220326065124911](figures/image-20220326065124911.png) 87 88### 跨设备应用开发 89 90默认应用的联想能力集是多个设备支持能力集的并集,要求能力集则是交集。 91 92![image-20220326065201867](figures/image-20220326065201867.png) 93 94### 判断 API 是否可以使用 95 96- 方法1:OpenHarmony定义了API canIUse帮助开发者来判断该设备是否支持某个特定的syscap。 97 98 ``` 99 if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { 100 console.log("该设备支持SystemCapability.ArkUI.ArkUI.Full"); 101 } else { 102 console.log("该设备不支持SystemCapability.ArkUI.ArkUI.Full"); 103 } 104 ``` 105 106- 方法2:开发者可通过import的方式将模块导入,若当前设备不支持该模块,import的结果为undefined,开发者在使用其API时,需要判断其是否存在。 107 108 ```ts 109 import geolocation from '@ohos.geolocation'; 110 111 if (geolocation) { 112 geolocation.getCurrentLocation((location) => { 113 console.log(location.latitude, location.longitude); 114 }); 115 } else { 116 console.log('该设备不支持位置信息'); 117 } 118 ``` 119除此之外,开发者可以通过API参考文档查询API接口所属的SysCap。 120 121### 不同设备相同能力的差异检查 122 123即使是相同的系统能力,在不同的设备下,也会有能力的差异。比如同是摄像头的能力,平板设备优于智能穿戴设备。 124 125``` 126import userAuth from '@ohos.userIAM.userAuth'; 127 128const authenticator = userAuth.getAuthenticator(); 129const result = authenticator.checkAbility('FACE_ONLY', 'S1'); 130 131if (result == authenticator.CheckAvailabilityResult.AUTH_NOT_SUPPORT) { 132 console.log('该设备不支持人脸识别'); 133} 134//强行调用不支持的 API 会返回错误信息,但不会出现语法错误。 135authenticator.execute('FACE_ONLY', 'S1', (err, result) => { 136 if (err) { 137 console.log(err.message); 138 return; 139 } 140}) 141``` 142 143### 设备间的SysCap差异如何产生的 144 145设备的SysCap因产品解决方案厂商拼装的部件组合不同而不同,整体流程如下图: 146 147![image-20220326072448840](figures/image-20220326072448840.png) 148 1491. 一套 OpenHarmony 源码由可选和必选部件集组成,不同的部件为对外体现的系统能力不同,即部件与 SysCap 之间映射关系。 150 1512. 发布归一化的SDK,API与SysCap之间存在映射关系。 152 1533. 产品解决方案厂商按硬件能力和产品诉求,可按需拼装部件。 154 1554. 产品配置的部件可以是OpenHarmony的部件,也可以是三方开发的私有部件,由于部件与SysCap间存在映射,所有拼装后即可得到该产品的SysCap集合。 156 1575. SysCap集编码生成 PCID (Product Compatibility ID, 产品兼容性标识),应用开发者可将PCID导入IDE解码成SysCap,开发时对设备的SysCap差异做兼容性处理。 158 1596. 部署到设备上的系统参数中包含了SysCap集,系统提供了native的接口和应用接口,可供系统内的部件和应用查询某个SysCap是否存在。 160 1617. 应用开发过程中,应用必要的SysCap将被编码成RPCID(Required Product Compatibility ID),并写入应用安装包中。应用安装时,包管理器将解码RPCID得到应用需要的 SysCap,与设备当前具备的SysCap比较,若应用要求的SysCap都被满足,则安装成功。 162 1638. 应用运行时,可通过canIUse接口查询设备的SysCap,保证在不同设备上的兼容性。 164