鸿蒙OS Ability Form

基本概念

Ability Form，即表单，是 Page 形态的 Ability 的一种界面展示形式，用于嵌入到其他应用中作为其界面的一部分显示，并支持基础的交互功能。表单使用方作为表单展示的宿主负责显示表单，表单使用方的典型应用就是桌面。下图展示一种音乐播放应用 Page 的完整显示及其微缩展示效果。

图1 Page 及其表单

表单提供方

表单提供方是一个 Page 形态的 Ability，需要实现 onCreateForm() 方法，并返回一个 AbilityForm 对象。创建 AbilityForm 对象时需要指定表单布局文件。

1. 为表单定义布局文件。创建布局文件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>

1. 实现 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;
       }
   }

1. 在 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);
       }
       ...
   }

1. 表单提供方在配置文件中声明，将 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 字段暂无实际用途，可以省略。

表单使用方

表单使用方通常是桌面类应用。以下示例展示如何获取并展示表单。

1. 获取表单需要具有 ohos.permission.REQUIRE_FORM 权限，注意该权限仅限系统应用获取。在配置文件中声明需要此权限。

   "reqPermissions": [
       {
           "name": "ohos.permission.REQUIRE_FORM"
       }
   ]

1. 调用 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;
               }
           });
       }

1. 创建布局，作为表单的视图容器。

       private PositionLayout createFormHostLayout() {
           PositionLayout formLayout = ...;
    
           ...
           // set size same with default of form
           formLayout.setHeight(formAbilityInfo.getDefaultFormHeight());
           formLayout.setWidth(formAbilityInfo.getDefaultFormWidth());
           ...
    
           return formLayout;
       }

1. 将表单的视图容器添加到当前视图中，以便显示表单。

       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 对象作为参数。