"鸿蒙OS开发文档"的目录
鸿蒙OS开发文档 鸿蒙OS Ability Form
基本概念
Ability Form，即表单，是 Page 形态的 Ability 的一种界面展示形式，用于嵌入到其他应用中作为其界面的一部分显示，并支持基础的交互功能。表单使用方作为表单展示的宿主负责显示表单，表单使用方的典型应用就是桌面。下图展示一种音乐播放应用 Page 的完整显示及其微缩展示效果。
图1 Page 及其表单 
表单提供方
表单提供方是一个 Page 形态的 Ability，需要实现 onCreateForm() 方法，并返回一个 AbilityForm 对象。创建 AbilityForm 对象时需要指定表单布局文件。
- 为表单定义布局文件。创建布局文件form_layout.xml：
<?xml version="1.0" encoding="utf-8"?>
<DirectionLayout xmlns:ohos="http://schemas.huawei.com/res/ohos"
ohos:width="match_parent"
ohos:height="match_parent"
ohos:orientation="horizontal">
<Text
ohos:id="$+id:text01"
ohos:width="match_content"
ohos:height="match_content"
ohos:text="Counter"
ohos:text_color="#FF555555"
ohos:text_size="20fp"/>
<Text
ohos:id="$+id:text02"
ohos:width="match_content"
ohos:height="match_content"
ohos:text_color="#FF0000FF"
ohos:text_size="20fp"/>
</DirectionLayout>
- 实现 onCreateForm() 方法，并为表单视图控件注册回调。
public class FormAbility extends Ability {
private static AbilityForm abilityForm;
private static int clickTimes = 0;
...
@Override
public AbilityForm onCreateForm() {
abilityForm = new AbilityForm(ResourceTable.Layout_form_layout, this);
abilityForm.setText(ResourceTable.Id_text02, generateFormText());
abilityForm.registerViewListener(ResourceTable.Id_text02, new OnClickListener() {
@Override
public void onClick(int viewId, AbilityForm form, ViewsStatus viewsStatus) {
clickTimes++;
form.setText(viewId, generateFormText());
if (FormSlice.text != null) {
FormSlice.text.setText("Client.Counter: " + clickTimes);
}
}
});
return abilityForm;
}
private static String generateFormText() {
return "total: " + clickTimes;
}
} - 在 FormSlice 实现 text，用于展示 Form 点击效果（用例展示效果，非实现 Form 必须步骤）。
public class FormSlice extends AbilitySlice {
public static Text text;
@Override
public void onStart(Intent intent) {
super.onStart(intent);
PositionLayout positionLayout = new PositionLayout(this);
ShapeElement background = new ShapeElement();
background.setShape(ShapeElement.RECTANGLE);
background.setRgbColor(new RgbColor(0xFFFFFFFF));
positionLayout.setBackground(background);
text = new Text(this);
text.setTextSize(30);
text.setTop(400);
text.setLeft(200);
text.setText(assembleText(FormAbility.getClickTimes()));
positionLayout.addComponent(text);
super.setUIContent(positionLayout);
}
...
} - 表单提供方在配置文件中声明，将 form-enabled 设置为 true ，并提供表单尺寸信息。
{
"module": {
...
"abilities": [
{
...
"form-enabled": true,
"form": {
"default-height": 200,
"default-width": 300,
"min-height": 60,
"min-width": 80
},
...
}
]
...
}
...
} 说明
由于当前暂未支持 Form 缩放，即无法调整其显示尺寸，因此 min-height 和 min-width 字段暂无实际用途，可以省略。
表单使用方
表单使用方通常是桌面类应用。以下示例展示如何获取并展示表单。
- 获取表单需要具有 ohos.permission.REQUIRE_FORM 权限，注意该权限仅限系统应用获取。在配置文件中声明需要此权限。
"reqPermissions": [
{
"name": "ohos.permission.REQUIRE_FORM"
}
]
- 调用 AbilitySlice 类的 acquireAbilityFormAsync() 方法异步获取表单，该方法需要通过 Intent 指定获取的目标表单，并提供一个回调用于接收表单。注意，获取到 AbilityForm 实例并未立即显示到当前页面布局中，开发者需要继续后续步骤把表单添加到视图中才会显示。
private void acquireForm() throws RemoteException {
Intent intent = new Intent();
Operation operation = new Intent.OperationBuilder()
.withDeviceId("")
.withBundleName("ohos.formsupplier.ability")
.withAbilityName("ohos.formsupplier.ability.FormAbility")
.build();
intent.setOperation(operation);
// Get form size.
formAbilityInfo = getBundleManager().queryAbilityByIntent(intent,IBundleManager.GET_ABILITY_INFO_WITH_PERMISSION,userId).get(0);
this.acquireAbilityFormAsync(intent, new AbilityForm.OnAcquiredCallback() {
@Override
public void onAcquired(AbilityForm abilityForm) {
// store as a class field
form = abilityForm;
}
@Override
public void onDestroyed(AbilityForm abilityForm) {
form = null;
}
});
} - 创建布局，作为表单的视图容器。
private PositionLayout createFormHostLayout() {
PositionLayout formLayout = ...;
...
// set size same with default of form
formLayout.setHeight(formAbilityInfo.getDefaultFormHeight());
formLayout.setWidth(formAbilityInfo.getDefaultFormWidth());
...
return formLayout;
} - 将表单的视图容器添加到当前视图中，以便显示表单。
private void showForm() {
PositionLayout hostLayout = createFormHostLayout();
// attach form to host layout
hostLayout.addComponent(form.getView());
// attach host layout to root layout
rootLayout.addComponent(hostLayout);
} 如果开发者需要移除表单，调用 AbilitySlice 类的 releaseAbilityForm() 方法，并以此前获取的 AbilityFor 对象作为参数。