鴻蒙OS Ability Form

基本概念

Ability Form，即表單，是 Page 形態(tài)的 Ability 的一種界面展示形式，用于嵌入到其他應(yīng)用中作為其界面的一部分顯示，并支持基礎(chǔ)的交互功能。表單使用方作為表單展示的宿主負責(zé)顯示表單，表單使用方的典型應(yīng)用就是桌面。下圖展示一種音樂播放應(yīng)用 Page 的完整顯示及其微縮展示效果。

圖1 Page 及其表單

表單提供方

表單提供方是一個 Page 形態(tài)的 Ability，需要實現(xiàn) onCreateForm() 方法，并返回一個 AbilityForm 對象。創(chuàng)建 AbilityForm 對象時需要指定表單布局文件。

1. 為表單定義布局文件。創(chuàng)建布局文件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. 實現(xiàn) onCreateForm() 方法，并為表單視圖控件注冊回調(diào)。

   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 實現(xiàn) text，用于展示 Form 點擊效果（用例展示效果，非實現(xiàn) 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 設(shè)置為 true ，并提供表單尺寸信息。

   {
       "module": {
           ...
           "abilities": [
               {
                   ...
                   "form-enabled": true,
                   "form": {
                       "default-height": 200,
                       "default-width": 300,
                       "min-height": 60,
                       "min-width": 80                    
                   },
                   ...
               }
           ]
           ...
       }
       ...
   }

說明

由于當(dāng)前暫未支持 Form 縮放，即無法調(diào)整其顯示尺寸，因此 min-height 和 min-width 字段暫無實際用途，可以省略。

表單使用方

表單使用方通常是桌面類應(yīng)用。以下示例展示如何獲取并展示表單。

1. 獲取表單需要具有 ohos.permission.REQUIRE_FORM 權(quán)限，注意該權(quán)限僅限系統(tǒng)應(yīng)用獲取。在配置文件中聲明需要此權(quán)限。

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

1. 調(diào)用 AbilitySlice 類的 acquireAbilityFormAsync() 方法異步獲取表單，該方法需要通過 Intent 指定獲取的目標(biāo)表單，并提供一個回調(diào)用于接收表單。注意，獲取到 AbilityForm 實例并未立即顯示到當(dāng)前頁面布局中，開發(fā)者需要繼續(xù)后續(xù)步驟把表單添加到視圖中才會顯示。

       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. 創(chuàng)建布局，作為表單的視圖容器。

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

1. 將表單的視圖容器添加到當(dāng)前視圖中，以便顯示表單。

       private void showForm() {
           PositionLayout hostLayout = createFormHostLayout();
           
           // attach form to host layout
           hostLayout.addComponent(form.getView());
    
           // attach host layout to root layout
           rootLayout.addComponent(hostLayout);
       }

如果開發(fā)者需要移除表單，調(diào)用 AbilitySlice 類的 releaseAbilityForm() 方法，并以此前獲取的 AbilityFor 對象作為參數(shù)。