diff --git a/zh-cn/application-dev/database/unified-data-channels.md b/zh-cn/application-dev/database/unified-data-channels.md index 7c63b2ce1cd8ff22d23728cf81f7988c8a90629a..37fa089928a97950df4af042708152e949171c3b 100644 --- a/zh-cn/application-dev/database/unified-data-channels.md +++ b/zh-cn/application-dev/database/unified-data-channels.md @@ -3,102 +3,128 @@ ## 场景介绍 -为了构建OpenHarmony数据跨应用/设备交互的标准定义，降低应用/业务数据交互成本，促进数据生态建设，UDMF提供了标准化的数据定义，统一定义了多种常用的数据类型。应用可以使用统一数据管理框架提供的接口创建和使用这些标准化数据类型。 +UDMF定义了安全、标准化的数据接入与读取通路，为各种业务场景（如跨应用跨设备数据拖拽）提供了跨应用、跨设备的数据接入与读取通路，降低业务跨应用、跨设备数据交互的成本。 ## 接口说明 -以下是键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[分布式键值数据库](../reference/apis/js-apis-distributedKVStore.md)。 +以下是UDMF标准化数据通路的相关接口，均为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[统一数据管理框架](../reference/apis/js-apis-data-udmf.md)。 -| 接口名称 | 描述 | -| -------- | -------- | -| createKVManager(config: KVManagerConfig): KVManager | 创建一个KVManager对象实例，用于管理数据库对象。 | -| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | 指定Options和storeId，创建并得到指定类型的KVStore数据库。 | -| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | 添加指定类型的键值对到数据库。 | -| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | 获取指定键的值。 | -| delete(key: string, callback: AsyncCallback<void>): void | 从数据库中删除指定键值的数据。 | +| 接口名称 | 描述 | +|----------------------------------------------------------------------------------------|---------------------------------------------| +| insertData(options: Options, data: UnifiedData, callback: AsyncCallback): void | 将数据写入UDMF的公共存储中，并生成数据的唯一标识符，使用callback异步回调。 | +| updateData(options: Options, data: UnifiedData, callback: AsyncCallback): void | 更新已写入UDMF的公共存储的数据，使用callback异步回调。 | +| queryData(options: Options, callback: AsyncCallback>): void | 查询UDMF公共存储的数据，使用callback异步回调。 | +| deleteData(options: Options, callback: AsyncCallback>): void | 删除UDMF公共存储的数据，返回删除的数据集，使用callback异步回调。 | ## 开发步骤 -以一次创建数据（包含图片、纯文本、二进制图片三条数据记录）为例，说明开发步骤。 +以一次统一数据对象的插入、更新、查询和删除为例，说明开发步骤，示例代码均采用Callback形式，Promise形式请见。 1. 导入`@ohos.data.UDMF`模块 ```js import UDMF from '@ohos.data.UDMF'; ``` -2. 创建图片数据记录，并初始化得到带有该数据记录的UnifiedData对象 - - （1）创建图片数据记录 - - ```js - let image = new UDMF.Image(); - ``` - - （2）修改对象属性 - - ```js - // Image对象包含一个属性imageUri - image.imageUri = '...'; - ``` - - （3）访问对象属性 +2. 创建一个统一数据对象并插入到UDMF的公共存储中。 ```js - console.info(`imageUri = ${image.imageUri}`); - ``` - - （4）创建一个统一数据对象实例 - - ```js - let unifiedData = new UDMF.UnifiedData(image); + let plainText = new UDMF.PlainText(); + plainText.textContent = 'hello world!'; + let unifiedData = new UDMF.UnifiedData(plainText); + + let options = { + intention: UDMF.Intention.SUPER_HUB + } + try { + UDMF.insertData(options, unifiedData, (err, data) => { + if (err === undefined) { + console.info(`Succeeded in inserting data. key = ${data}`); + } else { + console.error(`Failed to insert data. code is ${err.code},message is ${err.message} `); + } + }); + } catch(e) { + console.error(`Insert data throws an exception. code is ${e.code},message is ${e.message} `); + } ``` -3. 创建纯文本数据类型记录，将其添加到刚才创建的UnifiedData对象 +3. 更新上一步骤插入的统一数据对象。 ```js let plainText = new UDMF.PlainText(); - plainText.textContent = 'this is textContent of plainText'; - plainText.abstract = 'abstract of plainText'; - plainText.details = { - plainKey1: 'plainValue1', - plainKey2: 'plainValue2', + plainText.textContent = 'hello world!'; + let unifiedData = new UDMF.UnifiedData(plainText); + + let options = { + key: 'udmf://SuperHub/com.ohos.test/0123456789' }; - unifiedData.addRecord(plainText); - ``` -4. 创建二进制图片数据类型记录，将其添加到UnifiedData对象 - - ```js - let sdPixelMap = new UDMF.SystemDefinedPixelMap(); - sdPixelMap.rawData = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); - unifiedData.addRecord(sdPixelMap); + + try { + UDMF.updateData(options, unifiedData, (err) => { + if (err === undefined) { + console.info('Succeeded in updating data.'); + } else { + console.error('Failed to update data. code is ${err.code},message is ${err.message} `); + } + }); + } catch(e) { + console.error(`Update data throws an exception. code is ${e.code},message is ${e.message} `); + } ``` -5. 记录添加完成后，可获取当前UnifiedData对象内的所有数据记录 +4. 查询存储在UDMF公共存储中的统一数据对象。 ```js - let records = unifiedData.getRecords(); + let options = { + intention: UDMF.Intention.SUPER_HUB + }; + + try { + UDMF.queryData(options, (err, data) => { + if (err === undefined) { + console.info(`Succeeded in querying data. size = ${data.length}`); + for (let i = 0; i < data.length; i++) { + let records = data[i].getRecords(); + for (let j = 0; j < records.length; j++) { + if (records[j].getType() === UDMF.UnifiedDataType.PLAIN_TEXT) { + let text = (records[j]); + console.info(`${i + 1}.${text.textContent}`); + } + } + } + } else { + console.error(`Failed to query data. code is ${err.code},message is ${err.message} `); + } + }); + } catch(e) { + console.error(`Query data throws an exception. code is ${e.code},message is ${e.message} `); + } ``` -6. 遍历每条记录，判断该记录的数据类型，转换为子类对象，得到原数据记录 +5. 删除存储在UDMF公共存储中的统一数据对象。 ```js - for (let i = 0; i < records.length; i ++) { - // 读取该数据记录的类型 - let type = records[i].getType(); - switch (type) { - case UDMF.UnifiedDataType.IMAGE: - // 转换得到原图片数据记录 - let image = (records[i]); - break; - case UDMF.UnifiedDataType.PLAIN_TEXT: - // 转换得到原文本数据记录 - let plainText = (records[i]); - break; - case UDMF.UnifiedDataType.SYSTEM_DEFINED_PIXEL_MAP: - // 转换得到原二进制图片数据记录 - let sdPixelMap = (records[i]); - break; - default: - break; - } + let options = { + intention: UDMF.Intention.SUPER_HUB + }; + + try { + UDMF.deleteData(options, (err, data) => { + if (err === undefined) { + console.info(`Succeeded in deleting data. size = ${data.length}`); + for (let i = 0; i < data.length; i++) { + let records = data[i].getRecords(); + for (let j = 0; j < records.length; j++) { + if (records[j].getType() === UDMF.UnifiedDataType.PLAIN_TEXT) { + let text = (records[j]); + console.info(`${i + 1}.${text.textContent}`); + } + } + } + } else { + console.error(`Failed to delete data. code is ${err.code},message is ${err.message} `); + } + }); + } catch(e) { + console.error(`Delete data throws an exception. code is ${e.code},message is ${e.message} `); } ``` diff --git a/zh-cn/application-dev/database/unified-data-definition.md b/zh-cn/application-dev/database/unified-data-definition.md index 452219ac3e38c4613eaaeed3144d8bb10525fbfd..b4ee4433152f22389c5a58928dd67dc531619ca8 100644 --- a/zh-cn/application-dev/database/unified-data-definition.md +++ b/zh-cn/application-dev/database/unified-data-definition.md @@ -3,25 +3,34 @@ ## 场景介绍 -为了构建OpenHarmony数据跨应用/设备交互的标准定义，降低应用/业务数据交互成本，促进数据生态建设，UDMF提供了标准化的数据定义，统一定义了多种常用的数据类型。应用可以使用统一数据管理框架提供的接口创建和使用这些标准化数据类型。 +为了构建OpenHarmony数据跨应用、跨设备交互的标准定义，降低应用/业务数据交互成本，促进数据生态建设，UDMF提供了标准化的数据定义，统一定义了多种常用的数据类型。应用可以使用统一数据管理框架提供的接口创建和使用这些标准化数据类型。 ## 约束限制 - UDMF中每条数据记录大小不超过2MB。 -- UDMF支持批量数据记录的分组管理，每个分组最多支持512条数据，整体大小不超过4MB。 +- UDMF支持批量数据记录的分组管理，每个分组整体大小不超过4MB。 + ## 接口说明 -以下是键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[分布式键值数据库](../reference/apis/js-apis-distributedKVStore.md)。 +UDMF支持的标准化数据类型列表，请见接口参考中的[UnifiedDataType](../reference/apis/js-apis-data-udmf.md#UnifiedDataType)。 + +UDMF标准化数据类型均为数据记录[UnifiedRecord](../reference/apis/js-apis-data-udmf.md#UnifiedRecord)的子类，如下表所示， +通过基类的getType方法可以获取具体的数据类型。 + +| 接口名称 | 描述 | +|-------------------|-----------------------------------------------------------------------------------------------| +| getType(): string | 获取当前数据记录对应的具体数据类型，见[UnifiedDataType](../reference/apis/js-apis-data-udmf.md#UnifiedDataType)。 | + +UDMF支持批量数据记录的分组管理，通过统一数据对象[UnifiedData](../reference/apis/js-apis-data-udmf.md#UnifiedData)封装一组数据记录， +UnifiedData的接口如下表所示。 -| 接口名称 | 描述 | -| -------- | -------- | -| createKVManager(config: KVManagerConfig): KVManager | 创建一个KVManager对象实例，用于管理数据库对象。 | -| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | 指定Options和storeId，创建并得到指定类型的KVStore数据库。 | -| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | 添加指定类型的键值对到数据库。 | -| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | 获取指定键的值。 | -| delete(key: string, callback: AsyncCallback<void>): void | 从数据库中删除指定键值的数据。 | +| 接口名称 | 描述 | +|----------------------------------------|--------------------------------------------------------------------------| +| constructor(record: UnifiedRecord) | 用于创建带有一条数据记录的统一数据对象。 | +| addRecord(record: UnifiedRecord): void | 在当前统一数据对象中添加一条数据记录。 | +| getRecords(): Array | 将当前统一数据对象中的所有数据记录取出，通过本接口取出的数据为UnifiedRecord类型，需通过getType获取数据类型后转为子类再使用。 | ## 开发步骤