@ohos.data.unifiedDataChannel (标准化数据通路)

本模块为统一数据管理框架（Unified Data Management Framework,UDMF）的组成部分，针对多对多跨应用数据共享的不同业务场景提供了标准化的数据通路，提供了标准化的数据接入与读取接口。同时对文本、图片等数据类型提供了标准化定义，方便不同应用间进行数据交互，减少数据类型适配的工作量。

说明：

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

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

UnifiedData

表示UDMF统一数据对象，提供封装一组数据记录的方法。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

constructor

constructor(record: UnifiedRecord)

用于创建带有一条数据记录的统一数据对象。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

let text = new unifiedDataChannel.PlainText();
text.textContent = 'this is textContent of text';
let unifiedData = new unifiedDataChannel.UnifiedData(text);

addRecord

addRecord(record: UnifiedRecord): void

在当前统一数据对象中添加一条数据记录。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

let text1 = new unifiedDataChannel.PlainText();
text1.textContent = 'this is textContent of text1';
let unifiedData = new unifiedDataChannel.UnifiedData(text1);

let text2 = new unifiedDataChannel.PlainText();
text2.textContent = 'this is textContent of text2';
unifiedData.addRecord(text2);

getRecords

getRecords(): Array<UnifiedRecord>

将当前统一数据对象中的所有数据记录取出。通过本接口取出的数据为UnifiedRecord类型，需通过getType获取数据类型后转为子类再使用。

系统能力 ：SystemCapability.DistributedDataManager.UDMF.Core

返回值：

示例：

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

let text = new unifiedDataChannel.PlainText();
text.textContent = 'this is textContent of text';
let unifiedData = new unifiedDataChannel.UnifiedData(text);

let link = new unifiedDataChannel.Hyperlink();
link.url = 'www.XXX.com';
unifiedData.addRecord(link);

let records = unifiedData.getRecords();
for (let i = 0; i < records.length; i++) {
  let record = records[i];
  if (record.getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
    let plainText = record as unifiedDataChannel.PlainText;
    console.info(`textContent: ${plainText.textContent}`);
  } else if (record.getType() == uniformTypeDescriptor.UniformDataType.HYPERLINK) {
    let hyperlink = record as unifiedDataChannel.Hyperlink;
    console.info(`linkUrl: ${hyperlink.url}`);
  }
}

Summary

描述某一统一数据对象的数据摘要，包括所含数据类型及大小，当前暂不支持。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

UnifiedRecord

对UDMF支持的数据内容的抽象定义，称为数据记录。一个统一数据对象内包含一条或多条数据记录，例如一条文本记录、一条图片记录、一条HTML记录等。

UnifiedRecord是一个抽象父类，无法保存具体数据内容，应用在使用时，不能将其添加到统一数据对象中，而应该创建带有数据内容的具体子类，如Text、Image等。

getType

getType(): string

获取当前数据记录的类型。由于从统一数据对象中调用getRecords所取出的数据是UnifiedRecord对象，因此需要通过本接口查询此记录的具体类型，再将该UnifiedRecord对象转换为其子类，调用子类接口。

系统能力 ：SystemCapability.DistributedDataManager.UDMF.Core

返回值：

示例：

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

let text = new unifiedDataChannel.PlainText();
text.textContent = 'this is textContent of text';
let unifiedData = new unifiedDataChannel.UnifiedData(text);

let records = unifiedData.getRecords();
if (records[0].getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
  let plainText = records[0] as unifiedDataChannel.PlainText;
  console.info(`textContent: ${plainText.textContent}`);
}

Text

文本类型数据，是UnifiedRecord的子类，也是文本类型数据的基类，用于描述文本类数据，推荐开发者优先使用Text的子类描述数据，如PlainText、Hyperlink、HTML等具体子类。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let text = new unifiedDataChannel.Text();
text.details = {
  title: 'MyTitle',
  content: 'this is content',
};
let unifiedData = new unifiedDataChannel.UnifiedData(text);

PlainText

纯文本类型数据，是Text的子类，用于描述纯文本类数据。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let text = new unifiedDataChannel.PlainText();
text.textContent = 'this is textContent';
text.abstract = 'this is abstract';

Hyperlink

超链接类型数据，是Text的子类，用于描述超链接类型数据。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let link = new unifiedDataChannel.Hyperlink();
link.url = 'www.XXX.com';
link.description = 'this is description';

HTML

HTML类型数据，是Text的子类，用于描述超文本标记语言数据。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let html = new unifiedDataChannel.HTML();
html.htmlContent = '<div><p>标题</p></div>';
html.plainContent = 'this is plainContent';

File

File类型数据，是UnifiedRecord的子类，也是文件类型数据的基类，用于描述文件类型数据，推荐开发者优先使用File的子类描述数据，如Image、Video、Folder等具体子类。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let file = new unifiedDataChannel.File();
file.details = {
    name: 'test',
    type: 'txt',
};
file.uri = 'schema://com.samples.test/files/test.txt';

Image

图片类型数据，是File的子类，用于描述图片文件。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let image = new unifiedDataChannel.Image();
image.imageUri = 'schema://com.samples.test/files/test.jpg';

Video

视频类型数据，是File的子类，用于描述视频文件。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let video = new unifiedDataChannel.Video();
video.videoUri = 'schema://com.samples.test/files/test.mp4';

Audio

音频类型数据，是File的子类，用于描述音频文件。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let audio = new unifiedDataChannel.Audio();
audio.audioUri = 'schema://com.samples.test/files/test.mp3';

Folder

文件夹类型数据，是File的子类，用于描述文件夹。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let folder = new unifiedDataChannel.Folder();
folder.folderUri = 'schema://com.samples.test/files/folder/';

SystemDefinedRecord

SystemDefinedRecord是UnifiedRecord的子类，也是OpenHarmony系统特有数据类型的基类，用于描述仅在OpenHarmony系统范围内流通的特有数据类型，推荐开发者优先使用SystemDefinedRecord的子类描述数据，如SystemDefinedForm、SystemDefinedAppItem、SystemDefinedPixelMap等具体子类。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let sdr = new unifiedDataChannel.SystemDefinedRecord();
let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
sdr.details = {
    title: 'recordTitle',
    version: 1,
    content: u8Array,
};
let unifiedData = new unifiedDataChannel.UnifiedData(sdr);

SystemDefinedForm

系统定义的桌面卡片类型数据，是SystemDefinedRecord的子类。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let form = new unifiedDataChannel.SystemDefinedForm();
form.formId = 123456;
form.formName = 'MyFormName';
form.bundleName = 'MyBundleName';
form.abilityName = 'MyAbilityName';
form.module = 'MyModule';
let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
form.details = {
  formKey1: 123,
  formKey2: 'formValue',
  formKey3: u8Array,
};
let unifiedData = new unifiedDataChannel.UnifiedData(form);

SystemDefinedAppItem

系统定义的桌面图标类型数据，是SystemDefinedRecord的子类。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let appItem = new unifiedDataChannel.SystemDefinedAppItem();
appItem.appId = 'MyAppId';
appItem.appName = 'MyAppName';
appItem.appIconId = 'MyAppIconId';
appItem.appLabelId = 'MyAppLabelId';
appItem.bundleName = 'MyBundleName';
appItem.abilityName = 'MyAbilityName';
let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
appItem.details = {
    appItemKey1: 123,
    appItemKey2: 'appItemValue',
    appItemKey3: u8Array,
};
let unifiedData = new unifiedDataChannel.UnifiedData(appItem);

SystemDefinedPixelMap

与系统侧定义的PixelMap数据类型对应的图片数据类型，是SystemDefinedRecord的子类，仅保存PixelMap的二进制数据。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

import image from '@ohos.multimedia.image'; // PixelMap类定义所在模块

const color = new ArrayBuffer(96); // 创建pixelmap对象
let opts: image.InitializationOptions = {
  editable: true, pixelFormat: 3, size: {
    height: 4, width: 6
  }
}
image.createPixelMap(color, opts, (error, pixelmap) => {
  if (error) {
    console.error('Failed to create pixelmap.');
  } else {
    console.info('Succeeded in creating pixelmap.');
    let arrayBuf = new ArrayBuffer(pixelmap.getPixelBytesNumber());
    pixelmap.readPixelsToBuffer(arrayBuf);
    let u8Array = new Uint8Array(arrayBuf);
    let sdpixel = new unifiedDataChannel.SystemDefinedPixelMap();
    sdpixel.rawData = u8Array;
    let unifiedData = new unifiedDataChannel.UnifiedData(sdpixel);
  }
})

ApplicationDefinedRecord

ApplicationDefinedRecord是UnifiedRecord的子类，也是应用自定义数据类型的基类，用于描述仅在应用生态内部流通的自定义数据类型，应用可基于此类进行自定义数据类型的扩展。

系统能力：SystemCapability.DistributedDataManager.UDMF.Core

示例：

let record = new unifiedDataChannel.ApplicationDefinedRecord();
let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
record.applicationDefinedType = 'ApplicationDefinedType';
record.rawData = u8Array;
let unifiedData = new unifiedDataChannel.UnifiedData(record);

Intention

UDMF已经支持的数据通路枚举类型。其主要用途是标识各种UDMF数据通路所面向的不同业务场景。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

Options

UDMF提供的数据操作接口可选项，包含intention和key两个可选参数。无默认值，当对应接口不需要此参数时可不填，具体要求参照方法接口的参数说明。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

unifiedDataChannel.insertData

insertData(options: Options, data: UnifiedData, callback: AsyncCallback<string>): void

将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import { BusinessError } from '@ohos.base';

let plainText = new unifiedDataChannel.PlainText();
plainText.textContent = 'hello world!';
let unifiedData = new unifiedDataChannel.UnifiedData(plainText);

let options: unifiedDataChannel.Options = {
  intention: unifiedDataChannel.Intention.DATA_HUB
}
try {
  unifiedDataChannel.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) {
    let error: BusinessError = e as BusinessError;
    console.error(`Insert data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.insertData

insertData(options: Options, data: UnifiedData): Promise<string>

将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

返回值：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import { BusinessError } from '@ohos.base';

let plainText = new unifiedDataChannel.PlainText();
plainText.textContent = 'hello world!';
let unifiedData = new unifiedDataChannel.UnifiedData(plainText);

let options: unifiedDataChannel.Options = {
  intention: unifiedDataChannel.Intention.DATA_HUB
}
try {
  unifiedDataChannel.insertData(options, unifiedData).then((data) => {
    console.info(`Succeeded in inserting data. key = ${data}`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to insert data. code is ${err.code},message is ${err.message} `);
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Insert data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.updateData

updateData(options: Options, data: UnifiedData, callback: AsyncCallback<void>): void

更新已写入UDMF的公共数据通路的数据，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import { BusinessError } from '@ohos.base';

let plainText = new unifiedDataChannel.PlainText();
plainText.textContent = 'hello world!';
let unifiedData = new unifiedDataChannel.UnifiedData(plainText);

let options: unifiedDataChannel.Options = {
  key: 'udmf://DataHub/com.ohos.test/0123456789'
};

try {
  unifiedDataChannel.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) {
  let error: BusinessError = e as BusinessError;
  console.error(`Update data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.updateData

updateData(options: Options, data: UnifiedData): Promise<void>

更新已写入UDMF的公共数据通路的数据，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

返回值：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import { BusinessError } from '@ohos.base';

let plainText = new unifiedDataChannel.PlainText();
plainText.textContent = 'hello world!';
let unifiedData = new unifiedDataChannel.UnifiedData(plainText);

let options: unifiedDataChannel.Options = {
  key: 'udmf://DataHub/com.ohos.test/0123456789'
};

try {
  unifiedDataChannel.updateData(options, unifiedData).then(() => {
    console.info('Succeeded in updating data.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to update data. code is ${err.code},message is ${err.message} `);
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Update data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.queryData

queryData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void

查询UDMF公共数据通路的数据，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';
import { BusinessError } from '@ohos.base';

let options: unifiedDataChannel.Options = {
  intention: unifiedDataChannel.Intention.DATA_HUB
};

try {
  unifiedDataChannel.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() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
            let text = records[j] as unifiedDataChannel.PlainText;
            console.info(`${i + 1}.${text.textContent}`);
          }
        }
      }
    } else {
      console.error(`Failed to query data. code is ${err.code},message is ${err.message} `);
    }
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.queryData

queryData(options: Options): Promise<Array<UnifiedData>>

查询UDMF公共数据通路的数据，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

返回值：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';
import { BusinessError } from '@ohos.base';

let options: unifiedDataChannel.Options = {
  key: 'udmf://DataHub/com.ohos.test/0123456789'
};

try {
  unifiedDataChannel.queryData(options).then((data) => {
    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() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
          let text = records[j] as unifiedDataChannel.PlainText;
          console.info(`${i + 1}.${text.textContent}`);
        }
      }
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to query data. code is ${err.code},message is ${err.message} `);
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.deleteData

deleteData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void

删除UDMF公共数据通路的数据，返回删除的数据集，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';
import { BusinessError } from '@ohos.base';

let options: unifiedDataChannel.Options = {
  intention: unifiedDataChannel.Intention.DATA_HUB
};

try {
  unifiedDataChannel.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() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
            let text = records[j] as unifiedDataChannel.PlainText;
            console.info(`${i + 1}.${text.textContent}`);
          }
        }
      }
    } else {
      console.error(`Failed to delete data. code is ${err.code},message is ${err.message} `);
    }
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Delete data throws an exception. code is ${error.code},message is ${error.message} `);
}

unifiedDataChannel.deleteData

deleteData(options: Options): Promise<Array<UnifiedData>>

删除UDMF公共数据通路的数据，返回删除的数据集，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.UDMF.Core

参数：

返回值：

示例：

import unifiedDataChannel from '@ohos.data.unifiedDataChannel';
import uniformTypeDescriptor from '@ohos.data.uniformTypeDescriptor';
import { BusinessError } from '@ohos.base';

let options: unifiedDataChannel.Options = {
  key: 'udmf://DataHub/com.ohos.test/0123456789'
};

try {
  unifiedDataChannel.deleteData(options).then((data) => {
    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() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) {
          let text = records[j] as unifiedDataChannel.PlainText;
          console.info(`${i + 1}.${text.textContent}`);
        }
      }
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to delete data. code is ${err.code},message is ${err.message} `);
  });
} catch (e) {
  let error: BusinessError = e as BusinessError;
  console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `);
}