[文章]基于HarmonyOS Java UI使用元数据绑定框架实现UI和数据源的绑定

1. 介绍      
元数据绑定框架是基于HarmonyOS SDK开发的一套提供UI和数据源绑定能力的框架。通过使用元数据绑定框架，HarmonyOS应用开发者无需开发繁琐重复的代码即可实现绑定UI和数据源。

在本篇Codelab中，您将学会使用元数据绑定框架提供的接口，通过简单少量的代码实现UI和数据源绑定。我们提供了绑定简单UI组件、绑定UI容器组件、绑定自定义UI组件和绑定自定义数据源四种场景的实现。


2. 搭建HarmonyOS环境      

• 安装DevEco Studio，详情请参考下载和安装软件。
• 设置DevEco Studio开发环境，DevEco Studio开发环境依赖于网络环境，需要连接上网络才能确保工具的正常使用，可以根据如下两种情况来配置开发环境：
  
  • 如果可以直接访问Internet，只需进行下载HarmonyOS SDK操作。
  • 如果网络不能直接访问Internet，需要通过代理服务器才可以访问，请参考配置开发环境。
    
• 开发者可以参考以下链接，完成设备调试的相关配置：
  
  • 使用真机进行调试
  • 使用模拟器进行调试
    
    
  
  

您可以利用如下设备完成Codelab：

• 开启了开发者模式的HarmonyOS真机或DevEco Studio自带模拟器。
  
  
  说明
  本篇文章使用的DevEco Studio版本为DevEco Studio 2.1 Beta4，使用的SDK版本为API Version 5。
  
  

3. 代码结构解读      

• alarm/simple_ui：该路径下是实现简单UI绑定场景的代码。
• alarm/list_ui：该路径下是实现UI容器组件绑定场景的代码。
• custom_data_source：该目录下是实现绑定自定义数据源场景的代码。
• custom_ui：该目录下是实现绑定自定义UI组件场景的代码。
• MyApplication和MainAbility：项目应用程序的入口，在MyApplication中初始化元数据绑定框架。
• MainAbilitySlice：显示了四个按钮，分别是四个例子的入口。
• resources/base/layout：该路径下是各个界面的布局文件。
• resources/rawfile/jsonschema：该路径下是各个元数据的Json Schema文件。
  

4. 引入元数据绑定框架      在项目中引入元数据绑定框架使用元数据绑定框架并初始化
5. 实现简单UI组件的绑定      定义元数据结构

在alarm_schema.json中定义元数据的结构：

1. {
   
2.   "id": "com.example.meta-data.alarm",
   
3.   "title": "alarm schema",
   
4.   "$schema": "http://json-schema.org/draft-04/schema#",
   
5.   "description": "alarm description",   
   
6.   "type": "object",   
   
7.   "properties": {
   
8.     "id": {
   
9.       "type": "integer"     
   
10.     },     
    
11.     "hour": {
    
12.       "type": "integer"     
    
13.     },     
    
14.     "minutes": {
    
15.       "type": "integer"     
    
16.     },     
    
17.     "daysofweek": {
    
18.       "type": "integer"     
    
19.     },     
    
20.     "enabled": {
    
21.       "type": "integer"     
    
22.     },     
    
23.     "message": {
    
24.       "type": "string"     
    
25.     }   
    
26.   }
    
27. }

复制代码

元数据包括id、小时、分钟、星期几、是否开启和闹钟信息。其中星期几用七位的二进制整数表示，将整数转换为二进制后，第n位如果是1表示在星期n开启，否则为在星期n关闭。

说明
Json Schema定义了一套词汇和规则，这套词汇和规则用来定义Json元数据。关于Json Schema的定义请参考Json Schema官网。Json Schema文件一般由数据源一方提供。需要将得到的元数据Json文件放到resource/rawfile.jsonschema路径下。

在布局文件中使用元数据

来看一下要实现的界面效果：

创建布局文件single_alarm.xml，在xml布局文件中的最外层UI组件的定义中加入元数据绑定框架的命名空间：

1. xmlns:metaDataBinding="http://schemas.huawei.com/res/metaDatabinding"

复制代码

创建元数据实体：

1. <request-meta-data
   
2.     name="ClockMetaData"
   
3.     schema="com.example.meta-data.alarm"
   
4.     uri="dataability:///com.huawei.metadatabindingdemo.db.AlarmsDataAbility"/>

复制代码

说明
元数据实体包含两类，和；前者表示需要主动请求数据源的数据进行绑定，后者表示将一个元数据和UI进行绑定，不需要在绑定的开始向数据源请求数据。name表示元数据的名称，schema表示元数据的id（与Json Schema文件中的id一致），uri表示取得元数据的数据源的地址。

在组件中使用元数据：

1. <TimePicker
   
2.     ohos:id="$+id:time_picker"     
   
3.     ...
   
4.     metaDataBinding:hour="@={ClockMetaData.hour}"
   
5.     metaDataBinding:minute="@={ClockMetaData.minutes}"/>
   
6. <TextField
   
7.     ohos:id="$+id:clock_name_text"
   
8.     ...
   
9.     metaDataBinding:text="@={ClockMetaData.message}"/>
   
10. <Text
    
11.     ohos:id="$+id:show_alarm_name"
    
12.     ohos:align_parent_left="true"
    
13.     ...
    
14.     metaDataBinding:text="@{ClockMetaData.message}"/>
    
15. <Text
    
16.     ohos:id="$+id:show_alarm_time"
    
17.     ohos:align_parent_right="true"
    
18.     ...
    
19.     metaDataBinding:text="@{ClockMetaData.hour} + ':' + @{ClockMetaData.minutes}"/>

复制代码

在代码中进行绑定

在alarm/simple_ui/SingleAlarmSlice.java中的onStart方法中请求绑定：

1. // 创建元数据请求对象
   
2. MetaDataRequestInfo request = new MetaDataRequestInfo.Builder()
   
3.         .setMetaDataClass("ClockMetaData", ClockRowMetaData.class)
   
4.         .setSyncRequest("ClockMetaData", true)
   
5.         .build();
   
6. MetaDataBinding binding;
   
7. Component mainComponent;
   
8. try {
   
9.     // 请求绑定
   
10.     binding = SinglealarmMetaDataBinding.requestBinding(this, request, null);
    
11.     // 获得绑定的界面组件
    
12.     mainComponent = binding.getLayoutComponent();
    
13. } catch (DataSourceConnectionException e) {
    
14.     mainComponent = LayoutScatter.getInstance(this)
    
15.             .parse(ResourceTable.Layout_default_error, null, false);
    
16. }
    
17. setUIContent((ComponentContainer) mainComponent);

复制代码

说明
"ClockMetaData"是元数据的名字，对应xml布局文件中元数据的name。ClockRowMetaData类继承自MetaData类，我们可以在其中创建一些操作元数据内容的方法，例如将元数据内容转换成json字符串等。如果没有自定义的方法，则不需要创建继承自MetaData的类。

这样就完成了数据源和简单UI之间的绑定。运行之后效果如下：

   
6. 实现UI容器组件的绑定      创建布局文件

创建一个布局文件alarm_list_slice.xml，内容如下：

1. <?xml version="1.0" encoding="utf-8"?>
   
2. <DirectionalLayout
   
3.     xmlns:ohos="http://schemas.huawei.com/res/ohos"
   
4.     ohos:height="match_parent"
   
5.     ohos:width="match_parent"
   
6.     ohos:background_element="$color:colorAppBackground"
   
7.     ohos:orientation="vertical">
   
8.     <request-meta-data
   
9.         class="com.huawei.metadatabindingdemo.alarm.metadata.ClockRowMetaData"
   
10.         name="ClockMetaData"
    
11.         schema="com.example.meta-data.alarm"/>
    
12.     <!-- title -->
    
13.     <DependentLayout...>
    
14.     <!-- list -->
    
15.     <ListContainer
    
16.         ohos:id="$+id:list_view"
    
17.         ...
    
18.         ohos:top_padding="18vp"/>
    
19. </DirectionalLayout>

复制代码

获取数据源中的元数据

在AlarmListSlice类中请求数据源绑定。

1. MetaDataRequestInfo request = new MetaDataRequestInfo.Builder()
   
2.     .setRequestSource("ClockMetaData",
   
3.         "dataability:///com.huawei.metadatabindingdemo.db.AlarmsDataAbility")
   
4.     .setSyncRequest("ClockMetaData", false)
   
5.     .build();
   
6. Component mainComponent;
   
7. try {
   
8.     binding = AlarmlistsliceMetaDataBinding.requestBinding(this, request, this);
   
9.     mainComponent = binding.getLayoutComponent();
   
10. } catch (DataSourceConnectionException e) {
    
11.     mainComponent = LayoutScatter.getInstance(this)
    
12.         .parse(ResourceTable.Layout_default_error, null, false);
    
13. }
    
14. setUIContent((ComponentContainer) mainComponent);

复制代码

这里设置同步请求为false，表示请求是异步的。在requestBinding方法中dataCallback参数传入this，因为AlarmListSlice类实现了IMetaDataObserver接口。

说明
setSyncRequest传入false表示是异步的请求，IMetaDataObserver.onDataLoad方法会异步执行；如果传入true，则是同步的，IMetaDataObserver.onDataLoad方法执行之后requestBinding方法才会返回。

两个回调函数实现如下：

1. @Override
   
2. public void onDataLoad(List<MetaData> metaDatas, MetaDataRequestInfo.RequestItem requestItem) {
   
3.     if (metaDatas == null || requestItem == null) { return;}
   
4.     if (listContainer != null) {
   
5.         itemProvider.initData(createAlarms(this, metaDatas));
   
6.         listContainer.setItemProvider(itemProvider);
   
7.     }
   
8. }
   
9. @Override
   
10. public void onDataChange(List<MetaData> addedMetaData, List<MetaData> updatedMetaData,
    
11.     List<MetaData> deletedMetaData, MetaDataRequestInfo.RequestItem requestItem) {
    
12.     if (addedMetaData == null) { return;}
    
13.     itemProvider.addItems(createAlarms(this, addedMetaData));
    
14. }
    
15. private List<AlarmRow> createAlarms(AbilitySlice context, List<MetaData> dataList) {
    
16.     List<AlarmRow> list = new ArrayList<>();
    
17.     for (MetaData metaData : dataList) {
    
18.         AlarmRow item = new AlarmRow(context, metaData);
    
19.         list.add(item);
    
20.     }
    
21.     return list;
    
22. }

复制代码

将列表条目与元数据进行绑定

列表条目的展示效果：

为列表条目创建布局文件alarm_row.xml：

1. <?xml version="1.0" encoding="utf-8"?><DependentLayout
   
2.     xmlns:ohos="http://schemas.huawei.com/res/ohos"
   
3.     xmlns:metaDataBinding="http://schemas.huawei.com/res/metaDatabinding"
   
4.     ...
   
5.     ohos:orientation="vertical">
   
6.     <using-meta-data
   
7.         class="com.huawei.metadatabindingdemo.alarm.metadata.ClockRowMetaData"
   
8.         name="ClockMetaData"
   
9.         schema="com.example.meta-data.alarm"/>
   
10.     <DependentLayout
    
11.         ohos:id="$+id:double_line_text_area"...>
    
12.         <Text
    
13.             ohos:id="$+id:timezone"
    
14.             ...
    
15.             metaDataBinding:text="*{ClockMetaData.getTimeZone(@{ClockMetaData.hour})}"/>
    
16.         <Text
    
17.             ohos:id="$+id:time"
    
18.             ...
    
19.             metaDataBinding:text="@{ClockMetaData.hour} + ':' + @{ClockMetaData.minutes}"/>
    
20.         <Text
    
21.             ohos:id="$+id:message"
    
22.             ...
    
23.             metaDataBinding:text="*{ClockMetaData.toMessage(@{ClockMetaData.message},@{ClockMetaData.daysofweek})}"/>
    
24.     </DependentLayout>
    
25.     <DependentLayout
    
26.         ohos:id="$+id:double_line_switch_hot_area"...>
    
27.         <Image
    
28.             ohos:id="$+id:switch_enable_button"
    
29.             ...
    
30.             metaDataBinding:image_src="@{ClockMetaData.enabled} == 1 ? ${Media_icon_switch_enabled} : ${Media_icon_switch_disabled}"
    
31.             metaDataBinding:onClick="#{ClockMetaData.enabled = (@{ClockMetaData.enabled} == 1 ? 0 : 1)}"/>
    
32.     </DependentLayout>
    
33. </DependentLayout>

复制代码

这里用到了多种引用元数据的表达式，具体的用法如下：

标识符	意义	示例
@	取得原数据属性的值赋值到UI属性的单项绑定	metaDataBinding:text="@{ClockMetaData.message}"
@=	元数据属性的值和UI属性双向绑定	metaDataBinding:text="@={ClockMetaData.message}"
*	绑定自定义函数	metaDataBinding:text="*{ClockMetaData.getTimeZone(@{ClockMetaData.hour})}"
$	绑定资源文件	metaDataBinding:image_src="@{ClockMetaData.enabled} == 1 ? ${Media_icon_switch_enabled} : ${Media_icon_switch_disabled}"
#	点击事件触发给元数据赋值	metaDataBinding:onClick="#{ClockMetaData.enabled = (@{ClockMetaData.enabled} == 1 ? 0 : 1)}"

创建AlarmRow类表示列表的一个条目。它持有一个元数据对象，提供了获取UI组件，绑定UI组件和响应点击事件三个方法：

1. public class AlarmRow {
   
2.     private final AbilitySlice context;
   
3.     private final ClockRowMetaData clockMeta;
   
4.     public AlarmRow(AbilitySlice context, MetaData clockMeta) {
   
5.         this.context = context;
   
6.         this.clockMeta = (ClockRowMetaData) clockMeta;
   
7.     }
   
8.     public Component createComponent() {
   
9.         AlarmrowMetaDataBinding metaBinding = AlarmrowMetaDataBinding.createBinding(context, clockMeta);
   
10.         Component comp = metaBinding.getLayoutComponent();
    
11.         comp.setTag(metaBinding);
    
12.         return comp;
    
13.     }
    
14.     public void bindComponent(Component component) {
    
15.         AlarmrowMetaDataBinding metaBinding = (AlarmrowMetaDataBinding) component.getTag();
    
16.         metaBinding.reBinding(component, clockMeta);
    
17.     }
    
18.     public void onClick() {
    
19.         context.present(new AlarmEditSlice(clockMeta), new Intent());
    
20.     }
    
21. }

复制代码

创建AlarmListProvider类，重写getComponent方法，将列表条目组件和元数据进行绑定：

1. public Component getComponent(int position, Component component, ComponentContainer componentContainer) {
   
2.     AlarmRow alarm = alarmList.get(alarmIndex);
   
3.     if (component == null) {
   
4.         Component newComponent = alarm.createComponent();
   
5.         return newComponent;
   
6.     } else {
   
7.         alarm.bindComponent(component);
   
8.         return component;
   
9.     }
   
10. }

复制代码

在AlarmEditSlice类中将传入的元数据和现在的界面进行绑定；并监听"返回"按钮和"保存"按钮的点击事件。当点击"返回"按钮的时候使用元数据的rollback方法进行操作回滚， 点击"保存"按钮的时候进行提交和备份：

1. metaBinding = AlarmdetailMetaDataBinding.createBinding(this, clockMeta);
   
2. Component comp = metaBinding.getLayoutComponent();
   
3. DependentLayout dependentLayout = (DependentLayout) comp.findComponentById(ResourceTable
   
4.         .Id_title_area_back_icon_hot_area);
   
5. dependentLayout.setClickedListener(component -> {
   
6.     clockMeta.rollback();
   
7.     this.terminate();
   
8. });
   
9. comp.findComponentById(ResourceTable.Id_save).setClickedListener(component -> {
   
10.     clockMeta.commit();
    
11.     clockMeta.stash();
    
12.     this.terminate();
    
13. });

复制代码

添加一条记录

给界面右上方的'+‘号按钮添加点击事件监听，点击后会添加一条数据，该数据会保存在列表和数据源中。添加的数据默认表示将闹铃设置为开启，设定在周三和周四的12时12分。添加记录的代码如下：

1. public static void insertAnAlarm(MetaDataBinding binding) {
   
2.     MetaDataRequestInfo.RequestItem requestItem = binding.getRequestInfo().getRequestItem("ClockMetaData");
   
3.     MetaData metaData = AlarmlistsliceMetaDataBinding.createMetaData(requestItem);
   
4.     metaData.put(COL_HOUR, DEFAULT_HOUR);
   
5.     metaData.put(COL_MINUTE, DEFAULT_MINUTES);
   
6.     metaData.put(COL_DAYS, DEFAULT_DAYS_OF_WEEK);
   
7.     metaData.put(COL_ENABLE, DEFAULT_ENABLE);
   
8.     metaData.put("message", "count" + count);
   
9.     binding.addMetaData(metaData, requestItem);
   
10.     count++;
    
11. }

复制代码

说明
这里使用了MetaDataBinding的addMetaData方法添加元数据对象，您可以尝试使用deleteMetaData方法实现删除操作。

效果如下：

   
7. 绑定自定义UI组件      目前元数据绑定框架支持绑定的组件和属性如下：

组件	属性
所有组件	alpha，enabled，focusable，visibility，onClick
Button	text，text_color，text_size
Checkbox	checked
Image	image_src
ProgressBar	progress
RadioContainer	marked
Slider	progress,
Switch	checked
TabList	orientation
TextField	hint
Text	text, text_color, text_size
TimePicker	hour, minute, second

针对自定义UI组件，元数据绑定框架提供了BindingComponent注解、BindingTag注解和Operator接口。

在custom_ui目录下，创建一个正方形的组件，将它的颜色和数据源进行绑定，还有一个自定义的RadioButton组件，它的颜色也和该数据源进行绑定。
关于正方形组件的绘制代码我们不再赘述，请查看源码。
正方形组件提供了一个设置颜色的方法：

1. public void setColor(boolean isGreen) {
   
2.     this.isGreen = isGreen;
   
3.     if (isGreen) {
   
4.         rectPaint.setColor(Color.GREEN);
   
5.     } else {
   
6.         rectPaint.setColor(Color.YELLOW);
   
7.     }
   
8.     invalidate();
   
9. }

复制代码

RadioButton组件继承RadioButton类，重写构造方法，其余什么都不做。
使用一个Switch组件和元数据的bool_attr元素进行双向绑定，意图通过Switch控件来给元数据赋值。元数据的Json Schema文件是custom_schema.json。
布局文件custom_operator.xml如下：

1. <?xml version="1.0" encoding="utf-8"?>
   
2. <DirectionalLayout
   
3.     xmlns:ohos="http://schemas.huawei.com/res/ohos"
   
4.     xmlns:metaDataBinding="http://schemas.huawei.com/res/metaDatabinding"
   
5.     ...
   
6.     >
   
7.     <using-meta-data
   
8.         class="com.huawei.metadatabindingdemo.custom_ui.metadata.CustomMetaData"
   
9.         name="MetaData"
   
10.         schema="com.example.meta-data.custom"/>
    
11.     <Switch
    
12.         ohos:id="$+id:switch_color"
    
13.         ...
    
14.         metaDataBinding:checked="@={MetaData.bool_attr}"/>
    
15.     <com.hauwei.metadatabindingdemo.custom_ui.component.MyRadioButton
    
16.         ohos:id="$+id:test_my_radiobt"
    
17.         ...
    
18.         metaDataBinding:text_color_off2="*{MetaData.getColorOff(@{MetaData.bool_attr})}"
    
19.         metaDataBinding:text_color_on2="*{MetaData.getColorOn(@{MetaData.bool_attr})}"/>
    
20.     <com.huawei.metadatabindingdemo.custom_ui.component.MySquare
    
21.         ohos:id="$+id:test_my_comp"
    
22.         ...
    
23.         metaDataBinding:enabled2="@{MetaData.bool_attr}"/>
    
24. </DirectionalLayout>

复制代码

在CustomOperatorSlice中创建一个元数据对象，然后将元数据对象和UI进行绑定。

1. metaData = new CustomMetaData();
   
2. metaData.setPrimaryKey("id");
   
3. metaData.setName("MetaData");
   
4. metaData.put("bool_attr", false);
   
5. MetaDataBinding binding;
   
6. binding = CustomoperatorMetaDataBinding.createBinding(this, metaData);
   
7. Component mainComponent;
   
8. mainComponent = binding.getLayoutComponent();
   
9. setUIContent((ComponentContainer) mainComponent);

复制代码

适配正方形组件：

1. @BindingComponent(component ="com.huawei.metadatabindingdemo.custom_ui.component.MySquare")
   
2. public class Custom1Operator {
   
3.     @BindingTag(attr = "enabled2", type = "java.lang.Boolean")
   
4.     public static Operator<Boolean> SetColorOperator = new Operator<Boolean>() {
   
5.         @Override
   
6.         public void operate(Component component, Boolean value) {
   
7.             ((MySquare) component).setColor(value);
   
8.         }
   
9.     };
   
10. }

复制代码

适配自定义RadioButton组件：

1. @BindingComponent(component ="com.huawei.metadatabindingdemo.custom_ui.component.MyRadioButton")
   
2. public class Custom2Operator {
   
3.     @BindingTag(attr = "text_color_on2", type = "ohos.agp.utils.Color")
   
4.     public static Operator<Color> SetOnColor = new Operator<Color>() {
   
5.         @Override
   
6.         public void operate(Component component, Color value) {
   
7.             ((MyRadioButton)component).setTextColorOn(value);
   
8.         }
   
9.     };
   
10.     @BindingTag(attr = "text_color_off2", type = "ohos.agp.utils.Color")
    
11.     public static Operator<Color> SetOffColor = new Operator<Color>() {
    
12.         @Override
    
13.         public void operate(Component component, Color value) {
    
14.             ((MyRadioButton)component).setTextColorOff(value);
    
15.         }
    
16.     };
    
17. }

复制代码

现在元数据绑定框架可以识别自定义的两个组件了。

   
8. 绑定自定义数据源      元数据绑定框架对自定义数据源的支持是通过两个接口，CustomDao.ICustomMetaDataHandler和SimpleDao.ISimpleMetaDataHandler来实现的。由于ICustomMetaDataHandler接口支持多个元数据的获取，所以这里使用它来实现一个列表容器。布局文件不再赘述。数据源复用了闹钟列表的数据库，在数据库中添加了一个新的表，具体实现请阅读custom_data_source路径下的源码。这里只展示CustomDao.ICustomMetaDataHandler的接口实现：

1. public class MyDataHandler implements CustomDao.ICustomMetaDataHandler {
   
2.     private DataAbilityHelper mDbHelper = null;
   
3.     private MetaDataRequestInfo.RequestItem mReqItem = null;
   
4.     @Override
   
5.     public boolean onConnect(CustomDao dao) {
   
6.         Context mCtx = MetaDataFramework.appContext;
   
7.         this.mDbHelper = DataAbilityHelper.creator(mCtx);
   
8.         this.mReqItem = dao.getRequestItem();
   
9.         return true;
   
10.     }
    
11.     @Override
    
12.     public List<MetaData> onQuery(CustomDao dao, boolean isSync, String[] properties, PacMap predicates) {
    
13.         ArrayList<MetaData> list = new ArrayList<>();
    
14.         try {ResultSet resultSet = mDbHelper.query(NotesDataAbility.NOTE_URI, null, null);
    
15.             if (resultSet != null) {
    
16.                 boolean hasData = resultSet.goToFirstRow();
    
17.                 if (!hasData) {
    
18.                     return list;
    
19.                 }
    
20.                 do {
    
21.                     list.add(getQueryResults(resultSet)); // ResultSet to MetaData
    
22.                 }while (resultSet.goToNextRow());
    
23.             }
    
24.         } catch (DataAbilityRemoteException e) {
    
25.             MyLog.error("ohosTest: SimpleHandler onQuery error");
    
26.         }
    
27.         return list;
    
28.     }
    
29.     @Override
    
30.     public void onAdd(MetaData metaData) {}
    
31.     @Override
    
32.     public void onDelete(MetaData metaData) {}
    
33.     @Override
    
34.     public void onChange(MetaData metaData, String key, Object value) {}
    
35.     @Override
    
36.     public void onFlush(MetaData metaData) {}
    
37.     @Override
    
38.     public void onDisconnect(CustomDao dao) {}
    
39. }

复制代码

CustomDao.ICustomMetaDataHandler接口提供了连接、断连和增删改查元数据的操作。只需要实现这几个接口，在其中实现对数据源的操作，这样元数据绑定框架就会将数据源和UI绑定。

   
9. 恭喜你      

• 将元数据绑定框架引入工程和初始化。
• 将简单UI组件和数据源绑定。
• 将UI容器组件和数据源绑定。
• 将自定义UI组件和数据源绑定。
• 将UI组件和自定义数据源绑定。
  

10. 参考