@ohos.data.dataShare (数据共享)

DataShare用于应用管理其自身数据，同时支持同个设备上不同应用间的数据共享。

说明：

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

本模块接口为系统接口。

本模块接口仅可在Stage模型下使用。

导入模块

import dataShare from '@ohos.data.dataShare'

uri命名规则

标准uri定义结构如下:

Scheme://authority/path

• Scheme: 协议名，对于data share统一为datashare
• authority: [userinfo@]host[:port]
  • userinfo: 登录信息，不需要填写。
  • host: 服务器地址，如果跨设备访问则为目标设备的ID，如果为本设备则为空。
  • port: 服务器端口，不需要填写。
• path: data share的标识信息和资源的路径信息，需要包含data share的标识信息，资源的路径信息可以不填写。

uri示例:

• 不包含资源路径: datashare:///com.samples.datasharetest.DataShare

• 包含资源路径: datashare:///com.samples.datasharetest.DataShare/DB00/TBL00

其中，data share的标识信息为com.samples.datasharetest.DataShare，资源路径为DB00/TBL00。

dataShare.createDataShareHelper

createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void

创建DataShareHelper实例。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

错误码：

以下错误码的详细介绍请参见数据共享错误码。

示例：

import UIAbility from '@ohos.app.ability.UIAbility'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
try {
    dataShare.createDataShareHelper(this.context, uri, (err, data) => {
        if (err !== undefined) {
            console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    });
} catch (err) {
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
};

dataShare.createDataShareHelper

createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper>

创建DataShareHelper实例。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

错误码：

以下错误码的详细介绍请参见数据共享错误码。

示例：

import UIAbility from '@ohos.app.ability.UIAbility'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
try {
    dataShare.createDataShareHelper(this.context, uri).then((data) => {
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    }). catch((err) => {
        console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
};

DataShareHelper

DataShare管理工具实例，可使用此实例访问或管理服务端的数据。在调用DataShareHelper提供的方法前，需要先通过createDataShareHelper构建一个实例。

on('dataChange')

on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void

订阅指定URI对应数据的数据变更事件。若用户（订阅者）已注册了观察者，当有其他用户触发了变更通知时（调用了下文中的notifyChange方法），订阅者将会接收到callback通知。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
function onCallback() {
    console.info("**** Observer on callback ****");
}
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.on("dataChange", uri, onCallback);

off('dataChange')

off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void

取消订阅指定URI对应的数据资源的变更通知。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
function offCallback() {
    console.info("**** Observer off callback ****");
}
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.off("dataChange", uri, offCallback);

insert

insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void

将单条数据插入数据库。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
const valueBucket = {
    "name": "rose",
    "age": 22,
    "salary": 200.5,
}
try {
    dataShareHelper.insert(uri, valueBucket, (err, data) => {
        if (err != undefined) {
            console.error(`insert error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("insert succeed, data : " + data);
    });
} catch (err) {
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
};

insert

insert(uri: string, value: ValuesBucket): Promise<number>

将单条数据插入数据库。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
const valueBucket = {
    "name": "rose1",
    "age": 221,
    "salary": 20.5,
}
try {
    dataShareHelper.insert(uri, valueBucket).then((data) => {
        console.info("insert succeed, data : " + data);
    }). catch((err) => {
        console.error(`insert error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
};

delete

delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void

从数据库中删除一条或多条数据记录。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.delete(uri, da, (err, data) => {
        if (err !== undefined) {
            console.error(`delete error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("delete succeed, data : " + data);
    });
} catch (err) {
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
};

delete

delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number>

从数据库中删除一条或多条数据记录。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.delete(uri, da).then((data) =>  {
        console.info("delete succeed, data : " + data);
    }). catch((err) => {
        console.error(`delete error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
};

query

query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void

查询数据库中的数据。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.query(uri, da, columns, (err, data) => {
        if (err !== undefined) {
            console.error(`query error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("query succeed, rowCount : " + data.rowCount);
    });
} catch (err) {
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
};

query

query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet>

查询数据库中的数据。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.query(uri, da, columns).then((data) =>  {
        console.info("query succeed, rowCount : " + data.rowCount);
    }). catch((err) => {
        console.error(`query error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
};

update

update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void

更新数据库中的数据记录。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
try {
    dataShareHelper.update(uri, da, va, (err, data) => {
        if (err !== undefined) {
            console.error(`update error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("update succeed, data : " + data);
    });
} catch (err) {
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
};

update

update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number>

更新数据库中的数据记录。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
try {
    dataShareHelper.update(uri, da, va).then((data) =>  {
        console.info("update succeed, data : " + data);
    }). catch((err) => {
        console.error(`update error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
};

batchInsert

batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void

将批量数据插入数据库。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
try {
    dataShareHelper.batchInsert(uri, vbs, (err, data) => {
        if (err !== undefined) {
            console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("batchInsert succeed, data : " + data);
    });
} catch (err) {
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
};

batchInsert

batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number>

将批量数据插入数据库。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
try {
    dataShareHelper.batchInsert(uri, vbs).then((data) =>  {
        console.info("batchInsert succeed, data : " + data);
    }). catch((err) => {
        console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
};

normalizeUri

normalizeUri(uri: string, callback: AsyncCallback<string>): void

将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.normalizeUri(uri, (err, data) => {
    if (err !== undefined) {
        console.error("normalizeUri failed, error message : " + err);
    }else{
        console.info("normalizeUri = " + data);
    }
});

normalizeUri

normalizeUri(uri: string): Promise<string>

将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.normalizeUri(uri).then((data) => {
    console.info("normalizeUri = " + data);
}).catch((err) => {
    console.error("normalizeUri failed, error message : " + err);
});

denormalizeUri

denormalizeUri(uri: string, callback: AsyncCallback<string>): void

将指定的URI转换为非规范化URI。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.denormalizeUri(uri, (err, data) => {
    if (err !== undefined) {
        console.error("denormalizeUri failed, error message : " + err);
    }else{
        console.info("denormalizeUri = " + data);
    }
});

denormalizeUri

denormalizeUri(uri: string): Promise<string>

将指定的URI转换为非规范化URI。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.denormalizeUri(uri).then((data) => {
    console.info("denormalizeUri = " + data);
}).catch((err) => {
    console.error("denormalizeUri failed, error message : " + err);
});

notifyChange

notifyChange(uri: string, callback: AsyncCallback<void>): void

通知已注册的观察者指定URI对应的数据资源已发生变更。使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.notifyChange(uri, () => {
    console.info("***** notifyChange *****");
});

notifyChange

notifyChange(uri: string): Promise<void>

通知已注册的观察者指定URI对应的数据资源已发生变更。使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.DataShare.Consumer

参数：

返回值：

示例：

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.notifyChange(uri);