回复
OpenHarmony应用开发- API参考
素年锦时静待君丶
发布于 2023-4-13 19:20
浏览
0收藏
版本：v3.2 Release
系统能力SystemCapability使用指南
概述
系统能力与 API
SysCap，全称SystemCapability，即系统能力，指操作系统中每一个相对独立的特性，如蓝牙，WIFI，NFC，摄像头等，都是系统能力之一。每个系统能力对应多个API，随着目标设备是否支持该系统能力共同存在或消失，也会随着DevEco Studio一起提供给开发者做联想。
开发者可以在SysCap列表中查询OpenHarmony的能力集。
支持能力集，联想能力集与要求能力集
支持能力集，联想能力集与要求能力集都是系统能力的集合。 支持能力集描述的是设备能力，要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集，则应用A可分发到设备N上安装运行，否则不能分发。 联想能力集是该应用开发时，DevEco Studio可联想的API所在的系统能力集合。
设备与支持能力集
每个设备根据其硬件能力，对应不同的支持能力集。 SDK将设备分为两组，典型设备和自定义设备，典型设备的支持能力集由OpenHarmony来定义，自定义设备由设备厂商给出。
设备与SDK能力的对应
SDK向DevEco Studio提供全量API，DevEco Studio识别开发者项目中选择的设备形态，找到该设备的支持能力集，筛选支持能力集包含的API并提供API联想。
SysCap开发指导
PCID获取
PCID，全称Product Compatibility ID，包含当前设备支持的SysCap信息。获取所有设备PCID的认证中心正在建设中，目前需要找对应设备的厂商获取该设备的PCID。
PCID导入
DevEco Studio工程支持PCID的导入。导入的PCID文件解码后输出的SysCap会被写入syscap.json文件中。
在工程目录右键后选择Import Product Compatibility ID，即可上传PCID文件并导入至syscap.json中。
配置联想能力集和要求能力集
DevEco Studio会根据创建的工程所支持的设置自动配置联想能力集和要求能力集，开发者也可以自行修改。 对于联想能力集，开发者通过添加更多的系统能力，在DevEco Studio中可以使用更多的API，但要注意这些API可能在设备上不支持，使用前需要判断。 对于要求能力集，开发者修改时要十分慎重，修改不当会导致应用无法分发到目标设备上。
// syscap.json
{
"devices": {
"general": [ // 每一个典型设备对应一个syscap支持能力集，可配置多个典型设备"default",
"car"
],
"custom": [ // 厂家自定义设备
{
"某自定义设备": [
"SystemCapability.Communication.SoftBus.Core"
]
}
]
},
"development": { // addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集
"addedSysCaps": [
"SystemCapability.Location.Location.Lite"
]
},
"production": { // 用于生成rpcid，慎重添加，可能导致应用无法分发到目标设备上
"addedSysCaps": [], // devices中配置的各设备支持的syscap集合的交集，添加addedSysCaps集合再除去removedSysCaps集合，共同构成要求能力集
"removedSysCaps": [] // 当该要求能力集为某设备的子集时，应用才可被分发到该设备上
}
}单设备应用开发
默认应用的联想能力集，要求系统能力集和设备的支持系统能力集相等，开发者修改要求能力集需要慎重。
跨设备应用开发
默认应用的联想能力集是多个设备支持能力集的并集，要求能力集则是交集。
判断 API 是否可以使用
- 方法1：OpenHarmony定义了API canIUse帮助开发者来判断该设备是否支持某个特定的syscap。
if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) {
console.log("该设备支持SystemCapability.ArkUI.ArkUI.Full");
} else {
console.log("该设备不支持SystemCapability.ArkUI.ArkUI.Full");
}- 方法2：开发者可通过import的方式将模块导入，若当前设备不支持该模块，import的结果为undefined，开发者在使用其API时，需要判断其是否存在。
import geolocation from '@ohos.geolocation';
if (geolocation) {
geolocation.getCurrentLocation((location) => {
console.log(location.latitude, location.longitude);
});
} else {
console.log('该设备不支持位置信息')；
}除此之外，开发者可以通过API参考文档查询API接口所属的SysCap。
不同设备相同能力的差异检查
即使是相同的系统能力，在不同的设备下，也会有能力的差异。比如同是摄像头的能力，平板设备优于智能穿戴设备。
import userAuth from '@ohos.userIAM.userAuth';
const authenticator = userAuth.getAuthenticator();
const result = authenticator.checkAbility('FACE_ONLY', 'S1');
if (result == authenticator.CheckAvailabilityResult.AUTH_NOT_SUPPORT) {
console.log('该设备不支持人脸识别');
}
//强行调用不支持的 API 会返回错误信息，但不会出现语法错误。
authenticator.execute('FACE_ONLY', 'S1', (err, result) => {
if (err) {
console.log(err.message);
return;
}
})设备间的SysCap差异如何产生的
设备的SysCap因产品解决方案厂商拼装的部件组合不同而不同，整体流程如下图：
- 一套 OpenHarmony 源码由可选和必选部件集组成，不同的部件为对外体现的系统能力不同，即部件与 SysCap 之间映射关系。
- 发布归一化的SDK，API与SysCap之间存在映射关系。
- 产品解决方案厂商按硬件能力和产品诉求，可按需拼装部件。
- 产品配置的部件可以是OpenHarmony的部件，也可以是三方开发的私有部件，由于部件与SysCap间存在映射，所有拼装后即可得到该产品的SysCap集合。
- SysCap集编码生成 PCID (Product Compatibility ID， 产品兼容性标识)，应用开发者可将PCID导入IDE解码成SysCap，开发时对设备的SysCap差异做兼容性处理。
- 部署到设备上的系统参数中包含了SysCap集，系统提供了native的接口和应用接口，可供系统内的部件和应用查询某个SysCap是否存在。
- 应用开发过程中，应用必要的SysCap将被编码成RPCID（Required Product Compatibility ID），并写入应用安装包中。应用安装时，包管理器将解码RPCID得到应用需要的 SysCap，与设备当前具备的SysCap比较，若应用要求的SysCap都被满足，则安装成功。
- 应用运行时，可通过canIUse接口查询设备的SysCap，保证在不同设备上的兼容性。
组件参考（基于ArkTS的声明式开发范式）
组件导读
行列与分栏
- Column沿垂直方向布局的容器组件。
- ColumnSplit垂直方向分隔布局容器组件，将子组件纵向布局，并在每个子组件之间插入一根横向的分割线。
- Row沿水平方向布局的容器组件。
- RowSplit水平方向分隔布局容器组件，将子组件横向布局，并在每个子组件之间插入一根纵向的分割线。
- SideBarContainer提供侧边栏可以显示和隐藏的侧边栏容器组件，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。
堆叠Flex与栅格
- Stack堆叠容器组件，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。
- Flex以弹性方式布局子组件的容器组件。
- GridContainer纵向排布栅格布局容器组件，仅在栅格布局场景中使用。
- GridRow栅格容器组件，仅可以和栅格子组件(GridCol)在栅格布局场景中使用。
- GridCol栅格子组件，必须作为栅格容器组件(GridRow)的子组件使用。
- RelativeContainer相对布局组件，用于复杂场景中元素对齐的布局。
列表与宫格
- List列表包含一系列相同宽度的列表项，适合连续、多行呈现同类数据，例如图片和文本。
- ListItem用来展示具体列表项，必须配合List来使用。
- ListItemGroup用来展示分组列表项的组件，必须配合List组件来使用。
- Grid网格容器组件，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。
- GridItem网格容器中单项内容容器。
滚动与滑动
导航
- Navigator路由容器组件，提供路由跳转能力。
- Navigation一般作为Page页面的根容器，通过属性设置来展示页面的标题栏、工具栏、导航栏等。
- NavRouter导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。
- NavDestination作为NavRouter组件的子组件，用于显示导航内容区。
- Stepper步骤导航器组件，适用于引导用户按照步骤完成任务的导航场景。
- StepperItemStepper组件的子组件。
- Tabs通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。
- TabContent仅在Tabs组件中使用，对应一个切换页签的内容视图。
按钮与选择
- Button按钮组件，可快速创建不同样式的按钮。
- Toggle组件提供勾选框样式、状态按钮样式及开关样式。
- Checkbox提供多选框组件，通常用于某选项的打开或关闭。
- CheckboxGroup多选框群组，用于控制多选框全选或者不全选状态。
- DatePicker选择日期的滑动选择器组件。
- TextPicker滑动选择文本内容的组件。
- TimePicker滑动选择时间的组件。
- Radio单选框，提供相应的用户交互选择项。
- Rating提供在给定范围内选择评分的组件。
- Select提供下拉选择菜单，可以让用户在多个选项之间选择。
- Slider滑动条组件，通常用于快速调节设置值，如音量调节、亮度调节等应用场景。
- Counter计数器组件，提供相应的增加或者减少的计数操作。
文本与输入
- Text显示一段文本的组件。
- Span作为Text组件的子组件，用于显示行内文本片段的组件。
- Search搜索框组件，适用于浏览器的搜索内容输入框等应用场景。
- TextArea多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。
- TextInput单行文本输入框组件。
- PatternLock图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。
- RichText富文本组件，解析并显示HTML格式文本。
图片视频与媒体
- Image图片组件，支持本地图片和网络图片的渲染展示。
- ImageAnimator提供逐帧播放图片能力的帧动画组件，可以配置需要播放的图片列表，每张图片可以配置时长。
- Video用于播放视频文件并控制其播放状态的组件。
- PluginComponent提供外部应用组件嵌入式显示功能，即外部应用提供的UI可在本应用内显示。
- XComponent用于EGL/OpenGLES和媒体数据写入。
信息展示
- DataPanel数据面板组件，用于将多个数据占比情况使用占比图进行展示。
- Gauge数据量规图表组件，用于将数据展示为环形图表。
- LoadingProgress用于显示加载动效的组件。
- Marquee跑马灯组件，用于滚动展示一段单行文本，仅当文本内容宽度超过跑马灯组件宽度时滚动。
- Progress进度条组件，用于显示内容加载或操作处理等进度。
- QRCode用于显示单个二维码的组件。
- TextClock通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。
- TextTimer通过文本显示计时信息并控制其计时器状态的组件。
空白与分隔
画布与图形绘制
- Canvas提供画布组件，用于自定义绘制图形。
- Circle用于绘制圆形的组件。
- Ellipse椭圆绘制组件。
- Line直线绘制组件。
- Polyline折线绘制组件。
- Polygon多边形绘制组件。
- Path路径绘制组件，根据绘制路径生成封闭的自定义形状。
- Rect矩形绘制组件。
- Shape作为绘制组件的父组件，实现类似SVG的效果，父组件中会描述所有绘制组件均支持的通用属性。
网络
- Web提供具有网页显示能力的Web组件。
其他
- ScrollBar滚动条组件，用于配合可滚动组件使用，如List、Grid、Scroll等。
- Badge可以附加在单个组件上用于信息标记的容器组件。
- AlphabetIndexer可以与容器组件联动用于按逻辑结构快速定位容器显示区域的索引条组件。
- Panel可滑动面板，提供一种轻量的内容展示窗口，方便在不同尺寸中切换。
- Refresh可以进行页面下拉操作并显示刷新动效的容器组件。
- AbilityComponent独立显示Ability的容器组件。
- RemoteWindow远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。
- Formcomponent提供卡片组件，实现卡片的显示功能。
- Menu以垂直列表形式显示的菜单。
- MenuItem用来展示菜单Menu中具体的item菜单项。
- MenuItemGroup用来展示菜单MenuItem的分组。
标签
已于2023-4-13 19:20:38修改
赞
收藏
回复
相关推荐
