1# @ohos.application.DataShareExtensionAbility (数据共享扩展能力)(系统接口) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @woodenarow--> 5<!--Designer: @woodenarow; @xuelei3--> 6<!--Tester: @chenwan188; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9**DataShareExtensionAbility**基于ExtensionAbility框架，提供支持数据共享业务的能力。 10 11>**说明：** 12> 13> - 本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> - 本模块接口为系统接口。 16> 17> - 本模块接口仅可在Stage模型下使用。 18 19 20## 导入模块 21 22```ts 23import { DataShareExtensionAbility } from '@kit.ArkData'; 24``` 25 26## 属性 27 28**系统能力**：SystemCapability.DistributedDataManager.DataShare.Provider 29 30| 名称 | 类型 | 只读 | 可选 | 说明 | 31| -------- | -------- | -------- | -------- | -------- | 32| context<sup>10+</sup> | [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md) | 是 | 否 |表示数据共享扩展能力上下文。 | 33 34## onCreate 35 36onCreate?(want: Want, callback: AsyncCallback<void>): void 37 38DataShare客户端连接DataShareExtensionAbility服务端时，服务端回调此接口，执行初始化业务逻辑操作。该方法可以选择性重写。 39 40**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| ----- | ------ | ------ | ------ | 46| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md#want) | 是 | Want类型信息，包括Ability名称、Bundle名称等。 | 47| callback | AsyncCallback<void> | 是 | 回调函数。无返回值。 | 48 49**示例：** 50 51```ts 52import { DataShareExtensionAbility, relationalStore } from '@kit.ArkData'; 53import { Want } from '@kit.AbilityKit'; 54 55let DB_NAME = 'DB00.db'; 56let TBL_NAME = 'TBL00'; 57let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS ' 58 + TBL_NAME 59 + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)'; 60let rdbStore: relationalStore.RdbStore; 61 62export default class DataShareExtAbility extends DataShareExtensionAbility { 63 onCreate(want: Want, callback: Function) { 64 relationalStore.getRdbStore(this.context, { 65 name: DB_NAME, 66 securityLevel: relationalStore.SecurityLevel.S3 67 }, (err, data) => { 68 console.info(`getRdbStore done, data : ${data}`); 69 rdbStore = data; 70 rdbStore.executeSql(DDL_TBL_CREATE, [], (err) => { 71 console.error(`executeSql done, error message : ${err}`); 72 }); 73 if (callback) { 74 callback(); 75 } 76 }); 77 } 78}; 79``` 80 81## UpdateOperation<sup>12+</sup> 82 83批量更新操作的参数结构。 84 85**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 86 87| 名称 | 类型 | 必填 | 说明 | 88| --------------- | ------------------------------------------------------------ | ---- | -------------- | 89| UpdateOperation | [dataShare.UpdateOperation](js-apis-data-dataShare-sys.md#updateoperation12) | 是 | 要更新的数据。 | 90 91## insert 92 93insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void 94 95在数据库插入时回调此接口，该方法可以选择性重写。 96 97**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ----- | ------ | ------ | ------ | 103| uri |string | 是 | 指示要插入的数据的路径。 | 104| valueBucket |[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。 | 105| callback |AsyncCallback<number> | 是 | 回调函数。返回插入数据记录的索引。 | 106 107**示例：** 108 109```ts 110import { DataShareExtensionAbility, relationalStore, ValuesBucket } from '@kit.ArkData'; 111 112let TBL_NAME = 'TBL00'; 113let rdbStore: relationalStore.RdbStore; 114 115export default class DataShareExtAbility extends DataShareExtensionAbility { 116 insert(uri: string, valueBucket: ValuesBucket, callback: Function) { 117 if (valueBucket === null) { 118 console.error('invalid valueBuckets'); 119 return; 120 } 121 rdbStore.insert(TBL_NAME, valueBucket, (err, ret) => { 122 console.info(`callback ret: ${ret}`); 123 if (callback !== undefined) { 124 callback(err, ret); 125 } 126 }); 127 } 128}; 129``` 130 131## update 132 133update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void 134 135在数据库更新时服务端回调此接口，该方法可以选择性重写。 136 137**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| ----- | ------ | ------ | ------ | 143| uri | string | 是 | 指示要更新的数据的路径。 | 144| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。 | 145| valueBucket | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 | 146| callback | AsyncCallback<number> | 是 | 回调函数。返回更新的数据记录数。 | 147 148**示例：** 149 150```ts 151import { DataShareExtensionAbility, relationalStore, dataSharePredicates, ValuesBucket } from '@kit.ArkData'; 152 153let TBL_NAME = 'TBL00'; 154let rdbStore: relationalStore.RdbStore; 155 156export default class DataShareExtAbility extends DataShareExtensionAbility { 157 update(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: Function) { 158 if (predicates === null || predicates === undefined) { 159 return; 160 } 161 rdbStore.update(TBL_NAME, valueBucket, predicates, (err, ret) => { 162 if (callback !== undefined) { 163 callback(err, ret); 164 } 165 }); 166 } 167}; 168``` 169 170## batchUpdate<sup>12+</sup> 171 172batchUpdate?( operations: Record<string, Array<UpdateOperation>> , callback: AsyncCallback<Record<string, Array<number>>>): void 173 174在数据库批量更新时服务端回调此接口，该方法可以选择性重写。 175 176**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------ | 182| operations | Record<string, Array<[UpdateOperation](#updateoperation12)>> | 是 | 要更新数据的路径、筛选条件和数据集合。 | 183| callback | AsyncCallback<Record<string, Array<number>>> | 是 | 回调函数。返回更新的数据记录数集合，更新失败的UpdateOperation的数据记录数为-1。 | 184 185**示例：** 186 187```ts 188import { DataShareExtensionAbility, relationalStore, dataShare } from '@kit.ArkData'; 189import { BusinessError } from '@kit.BasicServicesKit' 190 191let TBL_NAME = 'TBL00'; 192let rdbStore: relationalStore.RdbStore; 193 194export default class DataShareExtAbility extends DataShareExtensionAbility { 195 batchUpdate(operations:Record<string, Array<dataShare.UpdateOperation>>, callback:Function) { 196 let recordOps : Record<string, Array<dataShare.UpdateOperation>> = operations; 197 let results : Record<string, Array<number>> = {}; 198 let a = Object.entries(recordOps); 199 for (let i = 0; i < a.length; i++) { 200 let key = a[i][0]; 201 let values = a[i][1]; 202 let result : number[] = []; 203 for (const value of values) { 204 rdbStore.update(TBL_NAME, value.values, value.predicates).then(async (rows) => { 205 console.info('Update row count is ' + rows); 206 result.push(rows); 207 }).catch((err:BusinessError) => { 208 console.info('Update failed, err is ' + JSON.stringify(err)); 209 result.push(-1) 210 }) 211 } 212 results[key] = result; 213 } 214 callback(null, results); 215 } 216}; 217``` 218 219## delete 220 221delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 222 223在删除数据库记录时服务端回调此接口，该方法可以选择性重写。 224 225**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- | 231| uri | string | 是 | 指示要删除的数据的路径。 | 232| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。 | 233| callback | AsyncCallback<number> | 是 | 回调函数。返回已删除的数据记录数。 | 234 235**示例：** 236 237```ts 238import { DataShareExtensionAbility, relationalStore, dataSharePredicates } from '@kit.ArkData'; 239 240let TBL_NAME = 'TBL00'; 241let rdbStore: relationalStore.RdbStore; 242 243export default class DataShareExtAbility extends DataShareExtensionAbility { 244 delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: Function) { 245 if (predicates === null || predicates === undefined) { 246 return; 247 } 248 rdbStore.delete(TBL_NAME, predicates, (err, ret) => { 249 if (callback !== undefined) { 250 callback(err, ret); 251 } 252 }); 253 } 254}; 255``` 256 257## query 258 259query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void 260 261在查询数据库时服务端回调此接口，该方法可以选择性重写。 262 263**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| ----- | ------ | ------ | ------ | 269| uri | string | 是 | 指示要查询的数据的路径。 | 270| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。 | 271| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 | 272| callback | AsyncCallback<Object> | 是 | 回调函数。返回查询到的结果集。 | 273 274**示例：** 275 276```ts 277import { DataShareExtensionAbility, relationalStore, dataSharePredicates } from '@kit.ArkData'; 278 279let TBL_NAME = 'TBL00'; 280let rdbStore: relationalStore.RdbStore; 281 282export default class DataShareExtAbility extends DataShareExtensionAbility { 283 query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: Function) { 284 if (predicates === null || predicates === undefined) { 285 return; 286 } 287 rdbStore.query(TBL_NAME, predicates, columns, (err, resultSet) => { 288 if (resultSet !== undefined) { 289 console.info(`resultSet.rowCount: ${resultSet.rowCount}`); 290 } 291 if (callback !== undefined) { 292 callback(err, resultSet); 293 } 294 }); 295 } 296}; 297``` 298 299## batchInsert 300 301batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void 302 303在数据库批量插入时服务端回调此接口，该方法可以选择性重写。 304 305**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 306 307**参数：** 308 309| 参数名 | 类型 | 必填 | 说明 | 310| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- | 311| uri | string | 是 | 指示要批量插入的数据的路径。 | 312| valueBuckets | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 指示要批量插入的数据。 | 313| callback | AsyncCallback<number> | 是 | 回调函数。返回插入的数据记录数。 | 314 315**示例：** 316 317```ts 318import { DataShareExtensionAbility, relationalStore, ValuesBucket } from '@kit.ArkData'; 319 320let TBL_NAME = 'TBL00'; 321let rdbStore: relationalStore.RdbStore; 322 323export default class DataShareExtAbility extends DataShareExtensionAbility { 324 batchInsert(uri: string, valueBuckets: Array<ValuesBucket>, callback: Function) { 325 if (valueBuckets === null || valueBuckets.length <= 0) { 326 console.error('invalid valueBuckets'); 327 return; 328 } 329 rdbStore.batchInsert(TBL_NAME, valueBuckets, (err, ret) => { 330 if (callback !== undefined) { 331 callback(err, ret); 332 } 333 }); 334 }; 335}; 336``` 337 338## normalizeUri 339 340normalizeUri?(uri: string, callback: AsyncCallback<string>): void 341 342用户给定的URI转换为服务端使用的URI时回调此接口，该方法可以选择性重写。 343 344**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 345 346**参数：** 347 348| 参数名 | 类型 | 必填 | 说明 | 349| -------- | --------------------- | ---- | ----------------------- | 350| uri | string | 是 | 指示用户传入的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 351| callback | AsyncCallback<string> | 是 | 回调函数。如果支持URI规范化，则返回规范化URI，否则返回空。 | 352 353**示例：** 354 355```ts 356import { DataShareExtensionAbility } from '@kit.ArkData'; 357import { BusinessError } from '@kit.BasicServicesKit' 358 359export default class DataShareExtAbility extends DataShareExtensionAbility { 360 normalizeUri(uri: string, callback: Function) { 361 let key = 'code'; 362 let value = 0; 363 let err: BusinessError = { 364 code: value, 365 name: key, 366 message: key 367 }; 368 let ret: string = `normalize: ${uri}`; 369 callback(err, ret); 370 } 371}; 372``` 373 374## denormalizeUri 375 376denormalizeUri?(uri: string, callback: AsyncCallback<string>): void 377 378服务端使用的URI转换为用户传入的初始URI时服务端回调此接口，该方法可以选择性重写。 379 380**系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider 381 382**参数：** 383 384| 参数名 | 类型 | 必填 | 说明 | 385| -------- | --------------------- | ---- | ----------------------- | 386| uri | string | 是 | 指示服务端使用的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 387| callback | AsyncCallback<string> | 是 | 回调函数。如果反规范化成功，则返回反规范化的URI；如果无需进行反规范化，则返回原始URI；若不支持则返回空。 | 388 389**示例：** 390 391```ts 392import { DataShareExtensionAbility } from '@kit.ArkData'; 393import { BusinessError } from '@kit.BasicServicesKit' 394 395export default class DataShareExtAbility extends DataShareExtensionAbility { 396 denormalizeUri(uri: string, callback: Function) { 397 let key = 'code'; 398 let value = 0; 399 let err: BusinessError = { 400 code: value, 401 name: key, 402 message: key 403 }; 404 let ret = `denormalize ${uri}`; 405 callback(err, ret); 406 } 407}; 408``` 409