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