HarmonyOS 应用开发之ArkData标准化数据定义(1)

标准化数据类型包含了标准化数据类型的标识ID、归属类型关系、简要描述等信息，每个类型定义具体包含以下内容：

• typeId： 定义标准化数据类型的ID，该ID具有唯一性。
• belongingToTypes： 定义标准化数据类型的归属关系，即该标准化数据类型归属于哪个更高层级的类型，允许存在一个标准化数据类型归属于多个类型的情况。
• description： 标准化数据类型的简要说明。
• referenceURL： 标准化数据类型的参考链接URL，用于描述类型的详细信息。
• iconFile： 标准化数据类型的默认图标文件路径，可能为空字符串（即没有默认图标），应用可以自行决定是否使用该默认图标。

预置数据类型

基于常用的数据类型，预先定义了一部分标准数据类型描述符，即预置数据类型。如用于描述音频文件的“general.audio”，描述视频文件的“general.video”。

应用自定义数据类型

由于预置标准数据类型无法穷举所有数据类型，在业务跨应用、跨设备交互过程中，会涉及到一些应用独有的数据类型，因此支持应用声明自定义数据类型。

应用自定义的数据类型可继承已有的标准类型，例如业务自定义的图片类型可以使用“com.company.x-image”作为自定义数据类型的标识。

业务可以将自定义数据类型注册到系统中，这样其他业务可以在需要时引用，进而实现生态内各应用自定义数据类型的共享与统一。

工作原理

基于标准类型的层级结构，业务声明自己支持的数据类型标识符时，需要声明该类型标识符的层级逻辑，例如业务自定义图片类型UTD标识符“com.company.x-image”，并归属到general.image类中。UTD会检验自定义类型标识符，确保归属关系中不出现环状结构。

应用安装时，UTD会读取应用中自定义的数据类型进行安装，校验自定义类型数据符合约束条件后，应用自定义数据类型将被安装到设备中。应用启动
后能正常读取到应用自定义的数据类型。如果引用其他应用定义的自定义数据类型，需要在应用开发时一并写入自定义数据类型配置文件中。

约束限制

针对自定义的类型描述各字段，有以下相关要求和限制：

• typeId： 定义标准化数据类型的ID，该ID具有唯一性，由应用bundleName + 具体类型名组成，不可缺省，允许包含数字、大小写字母、-和.。
• belongingToTypes： 定义标准化数据类型的归属关系，即该标准化数据类型归属于哪个更高层级的类型，所属类型可以为多个，但是必须为已存在的数据
  类型（标准化数据类型预置类型或其他新增自定义数据类型），不能为应用自定义类型本身，不能为空，且与现有标准化数据类型、其他新增自定义数据类型不能形成环行依赖结构。
• FilenameExtensions： 应用自定义标准化数据类型所关联的文件后缀。可以缺省；可以为多个，每个后缀为以.开头且长度不超过127的字符串。
• mimeTypes： 应用自定义标准化数据类型所关联的web消息数据类型。可以缺省；可以为多个，每个类型为长度不超过127的字符串。
• description： 应用自定义标准化数据类型的简要说明。可以缺省；填写时，长度为不超过255的字符串。
• referenceURL： 应用自定义标准化数据类型的参考链接URL，用于描述类型的详细信息。可以缺省；填写时，长度为不超过255的字符串。

开发步骤

下面以新增媒体类文件类型场景为例，说明如何自定义UTD标准化数据类型。

1. 当前应用在entry\src\main\resources\rawfile\arkdata\utd\目录下新增utd.json5文件。
2. 在当前应用的utd.json5配置文件内新增所需的自定义数据类型。

{
     "UniformDataTypeDeclarations": [
         {
             "typeId": "com.example.myFirstHap.image",
             "belongingToTypes": ["general.image"],
             "FilenameExtensions": [".myImage", ".khImage"],
             "mimeTypes": ["application/myImage", "application/khImage"],
             "description": "My Image.",
             "referenceURL": ""
         },
         {
             "typeId": "com.example.myFirstHap.audio",
             "belongingToTypes": ["general.audio"],
             "FilenameExtensions": [".myAudio", ".khAudio"],
             "mimeTypes": ["application/myAudio", "application/khAudio"],
             "description": "My audio.",
             "referenceURL": ""
         },
         {
             "typeId": "com.example.myFirstHap.video",
             "belongingToTypes": ["general.video"],
             "FilenameExtensions": [".myVideo", ".khVideo"],
             "mimeTypes": ["application/myVideo", "application/khVideo"],
             "description": "My video.",
             "referenceURL": ""
         }
     ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

3. 如果其他应用要直接使用当前应用内的自定义数据类型，需要在其应用的entry\src\main\resources\rawfile\arkdata\utd\目录下新增utd.json5文件。

然后在utd.json5配置文件中进行以下声明：

{
    "ReferenceUniformDataTypeDeclarations": [
         {
             "typeId": "com.example.myFirstHap.image",
             "belongingToTypes": ["general.image"],
             "FilenameExtensions": [".myImage", ".khImage"],
             "mimeTypes": ["application/myImage", "application/khImage"],
             "description": "My Image.",
             "referenceURL": ""
         }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13

4. 其他应用也可以在引用当前应用内的自定义数据类型之后，基于已引用的自定义数据类型进行自定义。utd.json5配置文件示例如下：

{
    "UniformDataTypeDeclarations": [
        {
            "typeId": "com.example.mySecondHap.image",
            "belongingToTypes": ["com.example.myFirstHap.image"],
            "FilenameExtensions": [".myImageEx", ".khImageEx"],
            "mimeTypes": ["application/my-ImageEx", "application/khImageEx"],
            "description": "My Image extension.",
            "referenceURL": ""
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13

接口说明

以下是UTD常用接口说明，对于预置数据类型和应用自定义数据类型同样适用，更多接口和详细说明。

开发步骤

下面以媒体类文件的归属类型查询场景为例，说明如何使用UTD。

1. 导入@ohos.data.uniformTypeDescriptor模块。
2. 可根据 “.mp3” 文件后缀查询对应UTD数据类型，并查询对应UTD数据类型的具体属性。
3. 可根据 “audio/mp3” MIMEType查询对应UTD数据类型，并查询对应UTD数据类型的具体属性。
4. 将上述步骤查询出来的数据类型进行比较，确认类型是否相等。
5. 根据上述步骤中查询到的标准数据类型“general.mp3”与表示音频数据的已知标准数据类型“general.audio”做比较查询，确认是否存在归属关系。

// 1.导入模块
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';

try {
  // 2.可根据 “.mp3” 文件后缀查询对应UTD数据类型，并查询对应UTD数据类型的具体属性
  let fileExtention = '.mp3';
  let typeId1 = uniformTypeDescriptor.getUniformDataTypeByFilenameExtension(fileExtention);
  let typeObj1 = uniformTypeDescriptor.getTypeDescriptor(typeId1);
  console.info('typeId:' + typeObj1.typeId);
  console.info('belongingToTypes:' + typeObj1.belongingToTypes);
  console.info('description:' + typeObj1.description);
  console.info('referenceURL:' + typeObj1.referenceURL);

  // 3.可根据 “audio/mp3” MIMEType查询对应UTD数据类型，并查询对应UTD数据类型的具体属性。
  let mineType = 'audio/mp3';
  let typeId2 = uniformTypeDescriptor.getUniformDataTypeByMIMEType(mineType);
  let typeObj2 = uniformTypeDescriptor.getTypeDescriptor(typeId2);
  console.info('typeId:' + typeObj2.typeId);
  console.info('belongingToTypes:' + typeObj2.belongingToTypes);
  console.info('description:' + typeObj2.description);
  console.info('referenceURL:' + typeObj2.referenceURL);

  // 4.将数据类型进行比较，确认是否同一种数据类型
  if (typeObj1 != null && typeObj2 != null) {
    let ret = typeObj1.equals(typeObj2);
    console.info('typeObj1 equals typeObj2, ret:' + ret);
  }

  // 5.将查询到的标准数据类型“general.mp3”与表示音频数据的已知标准数据类型“general.audio”做比较查询，确认是否存在归属关系。
  if (typeObj1 != null) {
    let ret = typeObj1.belongsTo('general.audio');
    console.info('belongsTo, ret:' + ret);
    let mediaTypeObj = uniformTypeDescriptor.getTypeDescriptor('general.media');
    ret = mediaTypeObj.isHigherLevelType('general.audio'); // 确认是否存在归属关系
    console.info('isHigherLevelType, ret:' + ret);
  }
} catch (err) {
  console.error('err message:' + err.message + ', err code:' + err.code);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

标准化数据结构

场景介绍

针对一些UTD标准化数据类型，为了方便业务使用，我们提供了标准化数据结构，例如OpenHarmony系统定义的桌面卡片类型（对应的标准化数据类型标识为为’openharmony.form’），我们明确定义了该数据结构对应的相关描述信息。

某些业务场景下应用可以直接使用我们具体定义的UTD标准化数据结构，例如跨应用拖拽场景。拖出方应用可以按照标准化数据结构将拖拽数据写入 拖拽事件 ，拖入方应用从拖拽事件中读取拖拽数据并按照标准化数据结构进行数据的解析。这使得不同应用间的数据交互遵从相同的标准定义，有效减少了跨应用数据交互的开发工作量。

当前支持的标准化数据结构

UDMF针对部分标准化数据类型定义的标准化数据结构如下所示：

约束限制

UDMF支持批量数据记录的分组管理，每个分组整体大小不超过200MB，其中PlainText、Hyperlink、HTML内单个属性值数据上限20M。

接口说明

UDMF提供了统一数据对象UnifiedData，用于封装一组数据记录UnifiedRecord。数据记录UnifiedRecord则是对UDMF支持的数据内容的抽象定义，例如一条文本记录、一条图片记录等。数据记录中的数据内容类型对应为各数据类型UniformDataType。

以下是标准化数据结构的常用接口说明，更多接口和具体说明，请见 标准化数据通路 和 标准化数据定义与描述 。

开发步骤

以使用标准化数据结构定义数据内容（包含图片、纯文本两条数据记录）为例，提供基本的开发步骤。

1. 导入@ohos.data.unifiedDataChannel和@ohos.data.uniformTypeDescriptor模块。

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';

1
2
3

2. 创建图片数据记录，并初始化得到带有该数据记录的UnifiedData对象。

   • 创建图片数据记录。

   let image = new unifiedDataChannel.Image();
   
   1
   2

   • 修改对象属性。

   // Image对象包含一个属性imageUri
   image.imageUri = '...';
   
   1
   2
   3

   • 访问对象属性。

   console.info(`imageUri = ${image.imageUri}`);
   
   1
   2

   • 创建一个统一数据对象实例。

   let unifiedData = new unifiedDataChannel.UnifiedData(image);
   
   1
   2

3. 创建纯文本数据类型记录，将其添加到刚才创建的UnifiedData对象。

let plainText = new unifiedDataChannel.PlainText();
plainText.textContent = 'this is textContent of plainText';
plainText.abstract = 'abstract of plainText';
plainText.details = {
  plainKey1: 'plainValue1',
  plainKey2: 'plainValue2',
};
unifiedData.addRecord(plainText);

1
2
3
4
5
6
7
8
9

4. 记录添加完成后，可获取当前UnifiedData对象内的所有数据记录。

let records = unifiedData.getRecords();

1
2

5. 遍历每条记录，判断该记录的数据类型，转换为子类对象，得到原数据记录。

for (let i = 0; i < records.length; i ++) {
  // 读取该数据记录的类型
  let type = records[i].getType();
  switch (type) {
    case uniformTypeDescriptor.UniformDataType.IMAGE:
      // 转换得到原图片数据记录
      let image = records[i] as unifiedDataChannel.Image;
      break;
    case uniformTypeDescriptor.UniformDataType.PLAIN\_TEXT:
      // 转换得到原文本数据记录
      let plainText = records[i] as unifiedDataChannel.PlainText;
      break;
    default:
      break;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开发技术，这边特意整理了《鸿蒙开发学习手册》（共计890页），希望对大家有所帮助：https://qr21.cn/FV7h05

《鸿蒙开发学习手册》：

如何快速入门：https://qr21.cn/FV7h05

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数HarmonyOS鸿蒙开发工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则几千的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年HarmonyOS鸿蒙开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上HarmonyOS鸿蒙开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新

如果你觉得这些内容对你有帮助，可以添加VX：vip204888 （备注鸿蒙获取）

一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

片转存中…(img-cIBTWgiM-1712843939577)]

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上HarmonyOS鸿蒙开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新

如果你觉得这些内容对你有帮助，可以添加VX：vip204888 （备注鸿蒙获取）
[外链图片转存中…(img-wirxkhxJ-1712843939578)]

一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！