智能客服
你问我答，随时在线为你解决问题
-
本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
-
本模块接口仅可在Stage模型下使用。
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
@ohos.data.dataShare (数据共享)
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
本文导读
DataShare用于应用管理其自身数据，同时支持同一个设备上不同应用间的数据共享。
说明
导入模块
- import { dataShare } from '@kit.ArkData';
dataShare.createDataProxyHandle20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
createDataProxyHandle(): Promise<DataProxyHandle>
创建DataProxyHandle实例。使用Promise异步回调。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DataProxyHandle> | Promise对象。返回DataProxyHandle实例。 |
错误码：
错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
示例：
- import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
-
- export default class EntryAbility extends UIAbility {
- onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
- dataShare.createDataProxyHandle().then((dataProxyHandle) => {
- console.info("createDataProxyHandle succeed");
- }).catch((err: BusinessError) => {
- console.error(`Failed to create DataProxyHandle. Code: ${err.code}, message: ${err.message}`);
- });
- }
- }
ChangeType20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
数据变更类型枚举。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 值 | 说明 |
|---|---|---|
| INSERT | 0 | 表示数据添加。 |
| DELETE | 1 | 表示数据删除。 |
| UPDATE | 2 | 表示数据更新。 |
ProxyData20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
共享配置的数据结构。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| uri | string | 否 | 否 | 共享配置的全局唯一标识。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复。字符串长度不超过256个字节。 |
| value | ValueType | 否 | 是 | 共享配置的值。不填则为空字符串。 说明： 1. API版本26.0.0之前，字符串长度不超过4096个字节；从API版本26.0.0开始，默认允许的字符串最大长度为4096字节，可以在DataProxyConfig中配置maxValueLength将最大长度扩展到102400字节。 2. 当首次发布共享配置时，如果未填写，将默认设置为空字符串。在更新共享配置时，如果未填写，共享配置的值将不会被更新。 |
| allowList | string[] | 否 | 是 | 允许订阅和读取共享配置的应用程序列表。不填则为空的字符串数组。数组最大长度为256，超过256的部分不生效。当首次发布共享配置时，如果未填写，将默认为空的允许列表。在更新共享配置时，如果未填写，共享配置的允许列表将不会被更新。一个空的允许列表表示只有发布者能够访问该共享配置。 API版本26.0.0之前，数组中每个元素为应用的appIdentifier，单个appIdentifier最大长度128字节，超过128字节的appIdentifier不会生效。 从API版本26.0.0开始，数组支持配置特殊字符串"all"（区分大小写）表示允许所有应用访问。 |
| isMultiValues | boolean | 否 | 是 | 表示是否为使用values的多值类型的共享配置。true表示本次发布的数据是多值类型，则value参数将被忽略。false表示非多值类型。默认为false。 起始版本： 26.0.0 |
| values | Record<number, ValueType> | 否 | 是 | 多值类型取值。Record中的第一个参数为key，key由用户指定，必须唯一。第二个参数为key对应的value。单个应用在单个URI下最多支持添加10个value，每个value最大长度为4096字节。同时，所有value的总长度受DataProxyConfig中maxValueLength字段限制。该参数仅在isMultiValues设置为true时生效，且不允许为空。当isMultiValues为false时默认为undefined。 起始版本： 26.0.0 |
| trustProviders | string[] | 否 | 是 | 可对多值类型共享多值配置进行赋值的App列表。数组最多包含256个元素，超出部分无效。数组中每个元素为某个应用的appIdentifier。appIdentifier最大长度为128字节，超过128字节的部分不生效。 若首次发布共享配置时未设置该参数，则默认赋值列表为空。赋值列表为空表示仅发布者可以对多值类型的共享配置进行赋值。该数组支持特殊字符串"all"（区分大小写），表示允许所有应用对多值类型的共享配置进行赋值。该参数仅在isMultiValues设置为true时生效。 起始版本： 26.0.0 |
DataProxyChangeInfo20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
通知订阅者共享配置变更的数据结构。包括数据变更类型、变化的URI、变更的数据内容。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| type | ChangeType | 否 | 否 | 通知变更的类型。 |
| uri | string | 否 | 否 | 通知变更指定URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| value | ValueType | 否 | 否 | 更新的数据。 |
| values | ValueType[] | 否 | 是 | 多值类型的变更数据。如果变更的数据类型不是多值类型，则values值为undefined。 起始版本： 26.0.0 |
DataProxyErrorCode20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
配置共享批量操作返回值的状态码枚举。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 值 | 说明 |
|---|---|---|
| SUCCESS | 0 | 表示操作成功。 |
| URI_NOT_EXIST | 1 | URI不存在或取消订阅一个未订阅过的URI。 |
| NO_PERMISSION | 2 | 没有权限在该URI上执行此操作。 |
| OVER_LIMIT | 3 | API版本26.0.0之前，表示当前应用发布的配置超过32个配置的上限；从API版本26.0.0开始，表示当前应用发布的配置超过64个配置的上限或获取的共享配置项的值超出DataProxyConfig中maxValueLength字段配置的最大长度限制。 |
DataProxyResult20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
配置共享批量操作结果的数据结构。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| uri | string | 否 | 否 | 被操作的URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| result | DataProxyErrorCode | 否 | 否 | 操作结果的错误码。 |
DataProxyGetResult20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
配置共享批量获取操作结果的数据结构。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| uri | string | 否 | 否 | 被操作的URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| result | DataProxyErrorCode | 否 | 否 | 操作结果的错误码。 |
| value | ValueType | undefined | 否 | 否 | 如果获取操作成功，则为共享配置的值；如果获取操作失败，则未定义。 |
| allowList | string[] | undefined | 否 | 否 | 如果获取操作成功，则为共享配置的允许列表；如果获取操作失败，则未定义。只有发布者才能获取允许列表，其他应用只能获取值。 |
DataProxyType20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
数据代理类型的枚举。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 值 | 说明 |
|---|---|---|
| SHARED_CONFIG | 0 | 表示应用之间的共享配置。 |
DataProxyConfig20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
数据代理操作配置的数据结构。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| type | DataProxyType | 否 | 否 | 数据代理操作的类型。 |
| maxValueLength | DataProxyMaxValueLength | 否 | 是 | 设置共享配置的值允许的最大长度。如果未填写，默认为MAX_LENGTH_4K，即共享配置的值允许的最大长度为4096字节。 起始版本： 26.0.0 |
DataProxyMaxValueLength
Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+
共享配置的值允许的最大长度的枚举值。
起始版本： 26.0.0
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
| 名称 | 值 | 说明 |
|---|---|---|
| MAX_LENGTH_4K | 4096 | 表示共享配置的值允许的最大长度为4096字节。 |
| MAX_LENGTH_100K | 102400 | 表示共享配置的值允许的最大长度为102400字节。 |
DataProxyHandle20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
数据代理操作句柄的实例，可使用此实例访问或管理共享配置信息。在调用DataProxyHandle提供的方法前，需要先通过createDataProxyHandle构建一个实例。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
on('dataChange')20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
on(event: 'dataChange', uris: string[], config: DataProxyConfig, callback: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[]
订阅指定URI对应共享配置变更事件。若订阅者已注册变更通知，当配置发布方修改配置时，订阅者将会接收到callback通知，通知携带数据变更类型、变化的URI、变更的共享配置内容。使用callback异步回调。该功能不允许跨用户订阅通知，不允许订阅未发布的配置。订阅成功后若权限被收回，则后续不再通知订阅者。
配对调用：
- 订阅后必须在不需要时调用off('dataChange')取消订阅。
- 取消订阅时需确保event、uris、config和callback参数与订阅时一致。
- 未取消订阅可能导致内存泄漏和资源占用。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当配置发布方修改配置时，触发该事件。 |
| uris | string[] | 是 | 表示要订阅的共享配置对应的URI数组。 说明： 1. API版本26.0.0之前，数组最大长度为32；从API版本26.0.0开始，数组最大长度为64。 2. URI固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。从API版本26.0.0开始，当变更的共享配置内容长度超过DataProxyConfig中maxValueLength字段配置的最大长度限制时，该共享配置内容会被截断。 |
| callback | AsyncCallback<DataProxyChangeInfo[]> | 是 | 回调函数。当订阅成功时，err为undefined，data为获取到的DataProxyChangeInfo数组，包含变更类型、URI和变更的共享配置内容；否则为错误对象。 |
返回值：
| 类型 | 说明 |
|---|---|
| DataProxyResult[] | 批量操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const urisToWatch: string[] =
- ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',];
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => {
- if (err) {
- console.error(`Failed to receive data change notification. Code: ${err.code}, message: ${err.message}`);
- } else {
- changes.forEach((change) => {
- console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`);
- });
- }
- };
- const results: dataShare.DataProxyResult[] = dataProxyHandle.on('dataChange', urisToWatch, config, callback);
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
off('dataChange')20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
off(event: 'dataChange', uris: string[], config: DataProxyConfig, callback?: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[]
取消订阅指定URI对应代理数据变更事件。
配对调用：
- 必须在已调用on('dataChange')订阅后使用。
- 取消订阅时需确保event、uris、config参数与订阅时一致。
- 如未指定callback参数，将取消该URI的所有已注册回调函数。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'。 |
| uris | string[] | 是 | 表示要取消订阅的共享配置对应的URI数组。 说明： 1. API版本26.0.0之前，数组最大长度为32；从API版本26.0.0开始，数组最大长度为64。 2. URI固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。 |
| callback | AsyncCallback<DataProxyChangeInfo[]> | 否 | 回调函数。当取消订阅成功时，err为undefined，data为获取到的DataProxyChangeInfo数组，包含变更类型、URI和变更的共享配置内容；否则为错误对象。不填写则取消所有已注册的回调函数。 |
返回值：
| 类型 | 说明 |
|---|---|
| DataProxyResult[] | 批量操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const urisToUnWatch: string[] =
- ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',];
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => {
- if (err) {
- console.error(`Failed to receive data change notification. Code: ${err.code}, message: ${err.message}`);
- } else {
- changes.forEach((change) => {
- console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`);
- });
- }
- };
- const results: dataShare.DataProxyResult[] = dataProxyHandle.off('dataChange', urisToUnWatch, config, callback);
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
publish20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
publish(data: ProxyData[], config: DataProxyConfig): Promise<DataProxyResult[]>
发布共享配置项。使用Promise异步回调。
发布后，发布者和允许列表中指定的应用可以访问该共享配置项。
如果要发布的URI已经存在，则更新对应的共享配置项。如果发布的配置项中存在任一URI的长度超出上限或者格式校验失败，则当前发布操作失败。
只有发布者才允许更新共享配置项。
API版本26.0.0之前，每个应用支持最多32个共享配置；从API版本26.0.0开始，每个应用支持最多64个共享配置。
从API版本26.0.0开始，支持发布多值类型配置，一个uri只能对应一种值类型。且配置发布后不允许使用publish更新已发布的多值类型uri。多值类型的操作接口见putValue、removeValue和getValues。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| data | ProxyData[] | 是 | 表示需要创建或者更新的共享配置项数组。API版本26.0.0之前，数组最大长度为32；从API版本26.0.0开始，数组最大长度为64。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。从API版本26.0.0开始，如果发布的配置项中存在任一值的长度超过DataProxyConfig中maxValueLength字段配置的最大长度限制，则当前发布操作失败。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DataProxyResult[]> | Promise对象。返回批量操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const newConfigData: dataShare.ProxyData[] = [{
- uri: 'datashareproxy://com.example.app1/config1',
- value: 'Value1',
- allowList: ['appIdentifier2', 'appIdentifier3'], // 此处字符串仅作示例，使用时需替换为应用实际的appIdentifier
- }, {
- uri: 'datashareproxy://com.example.app1/config2',
- value: 'Value2',
- allowList: ['appIdentifier3', 'appIdentifier4'], // 此处字符串仅作示例，使用时需替换为应用实际的appIdentifier
- }];
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- dataProxyHandle.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to publish config. code: ${error.code}, message: ${error.message}`);
- });
delete20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
delete(uris: string[], config: DataProxyConfig): Promise<DataProxyResult[]>
根据URI删除指定的共享配置项。使用Promise异步回调。只有配置发布方能删除共享配置项。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uris | string[] | 是 | 表示需要删除的共享配置对应的URI数组。 说明： 1. API版本26.0.0之前，数组最大长度为32；从API版本26.0.0开始，数组最大长度为64。 2. URI固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DataProxyResult[]> | Promise对象。返回批量操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const urisToDelete: string[] =
- ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',];
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- dataProxyHandle.delete(urisToDelete, config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to delete config. code: ${error.code}, message: ${error.message}`);
- });
deleteMyPublishedData
Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+
deleteMyPublishedData(config: DataProxyConfig): Promise<DataProxyResult[]>
删除当前发布者发布的所有共享配置项。使用Promise异步回调。只有配置发布方能删除共享配置项。
起始版本： 26.0.0
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DataProxyResult[]> | Promise对象。返回批量操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- dataProxyHandle.deleteMyPublishedData(config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to delete all configs. Code: ${error.code}, message: ${error.message}`);
- });
get20+
Phone20+PC/2in120+Tablet20+TV20+Wearable20+
get(uris: string[], config: DataProxyConfig): Promise<DataProxyGetResult[]>
根据URI获取指定的共享配置项。使用Promise异步回调。只有发布者和允许列表中指定的应用可以访问该共享配置项。
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uris | string[] | 是 | 表示需要获取的共享配置的URI数组。 说明： 1. API版本26.0.0之前，数组最大长度为32；从API版本26.0.0开始，数组最大长度为64。 2. URI固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。从API版本26.0.0开始，获取的共享配置项的值长度不能超出DataProxyConfig中maxValueLength字段配置的最大长度限制。超出限制时，对应获取操作结果的返回值状态码DataProxyErrorCode为OVER_LIMIT。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DataProxyGetResult[]> | Promise对象。返回批量获取操作的结果数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
示例：
- const urisToGet: string[] =
- ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',];
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- dataProxyHandle.get(urisToGet, config).then((results: dataShare.DataProxyGetResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}, AllowList: ${result.allowList}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to get config. code: ${error.code}, message: ${error.message}`);
- });
putValue
Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+
putValue(uri: string, key: number, value: ValueType, config: DataProxyConfig): Promise<void>
将一个值写入到已发布的数据中。该操作仅支持对多值类型数据执行。使用Promise异步回调。
若传入的key不存在，则添加新的值；若传入的key已存在，则更新该key对应的值。
默认情况下，单条数据（即URI）在单个应用中最多可添加10个值，每个值最大长度为4096字节。同时，单条数据（即一个URI）在单个应用中所有值总长度受限于数据publish时指定的maxValueLength参数值。
起始版本： 26.0.0
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uri | string | 是 | 要操作的数据所对应的URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| key | number | 是 | 添加的值所对应的Key，对同一个应用来说是唯一的。 取值范围为全体整数。 |
| value | ValueType | 是 | 待添加的值。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。配置中maxValueLength参数不生效。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象，无返回结果。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700011 | The URI does not exist. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
| 15700015 | No permission to access the data specified by the URI. |
示例：
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- let testUri: string = 'datashareproxy://com.test.dataproxyhandle/test/pv/001';
- let newConfigData: dataShare.ProxyData[] = [{
- uri: testUri,
- values: { 0: 'init' },
- isMultiValues: true,
- allowList: [],
- trustProviders: []
- }];
-
- await dataProxyHandle?.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to publish config. code: ${error.code}, message: ${error.message}`);
- });
-
- try {
- await dataProxyHandle?.putValue(testUri, 1, 'hello', config);
- console.info(`putValue success`);
- } catch (error) {
- console.error(`putValue failed: code: ${error.code}, message: ${error.message}`);
- }
removeValue
Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+
removeValue(uri: string, key: number, config: DataProxyConfig): Promise<void>
移除键对应的值。该操作仅能对多值类型数据执行。仅能移除本应用添加过的值。使用Promise异步回调。
起始版本： 26.0.0
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uri | string | 是 | 要操作的数据所对应的URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| key | number | 是 | 要移除的值所对应的Key。 取值范围为全体整数。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象，无返回结果。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700011 | The URI does not exist. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
| 15700015 | No permission to access the data specified by the URI. |
示例：
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- let testUri: string = 'datashareproxy://com.test.dataproxyhandle/test/pv/001';
- let newConfigData: dataShare.ProxyData[] = [{
- uri: testUri,
- values: { 0: 'init' },
- isMultiValues: true,
- allowList: [],
- trustProviders: []
- }];
-
- await dataProxyHandle?.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to publish config. code: ${error.code}, message: ${error.message}`);
- });
-
- try {
- await dataProxyHandle?.removeValue(testUri, 0, config);
- console.info(`removeValue success`);
- } catch (error) {
- console.error(`removeValue failed: code: ${error.code}, message: ${error.message}`);
- }
getValues
Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+
getValues(uri: string, config: DataProxyConfig): Promise<ValueType[]>
获取指定URI下的所有多值类型数据。只有发布者和位于allowList中的应用程序才能获取此数据。使用Promise异步回调。
起始版本： 26.0.0
系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uri | string | 是 | 要操作的数据所对应的URI。固定格式为"datashareproxy://{bundleName}/{path}"，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 |
| config | DataProxyConfig | 是 | 表示数据代理操作的配置。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<ValueType[]> | Promise对象，返回URI下所有值的数组。 |
错误码：
以下错误码的详细介绍请参见数据共享错误码。
| 错误码ID | 错误信息 |
|---|---|
| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. |
| 15700011 | The URI does not exist. |
| 15700014 | The parameter format is incorrect or the value range is invalid. |
| 15700015 | No permission to access the data specified by the URI. |
示例：
- const config: dataShare.DataProxyConfig = {
- type: dataShare.DataProxyType.SHARED_CONFIG,
- };
- let testUri: string = 'datashareproxy://com.test.dataproxyhandle/test/pv/001';
- let newConfigData: dataShare.ProxyData[] = [{
- uri: testUri,
- values: { 0: 'init' },
- isMultiValues: true,
- allowList: [],
- trustProviders: []
- }];
-
- await dataProxyHandle!.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => {
- results.forEach((result) => {
- console.info(`URI: ${result.uri}, Result: ${result.result}`);
- });
- }).catch((error: BusinessError) => {
- console.error(`Failed to publish config. code: ${error.code}, message: ${error.message}`);
- });
-
- try {
- let result: ValueType[] = await dataProxyHandle?.getValues(testUri, config);
- console.info(`getValues success. Values: ` + JSON.stringify(result));
- } catch (error) {
- console.error(`getValues failed: code: ${error.code}, message: ${error.message}`);
- }
在 API参考 中进行搜索
请输入您想要搜索的关键词