diff --git a/zh-cn/application-dev/database/database-datashare-guildlines.md b/zh-cn/application-dev/database/database-datashare-guildlines.md new file mode 100644 index 0000000000000000000000000000000000000000..571c3b991fb76893da2b55361d4bf8dec80be1ca --- /dev/null +++ b/zh-cn/application-dev/database/database-datashare-guildlines.md @@ -0,0 +1,321 @@ +# DataShareå¼€å‘指导 +## åœºæ™¯ä»‹ç» +DataShare,用于应用管ç†å…¶è‡ªèº«æ•°æ®ï¼Œå¹¶æ”¯æŒåŒä¸ªè®¾å¤‡ä¸Šä¸åŒåº”用间的数æ®å…±äº«ã€‚ + +DataShareå¯åˆ†ä¸ºæ•°æ®çš„æ供方和访问方两部分,æ供方å¯ä»¥é€‰æ‹©æ€§å®žçŽ°æ•°æ®çš„增ã€åˆ ã€æ”¹ã€æŸ¥ï¼Œä»¥åŠæ–‡ä»¶æ‰“å¼€ç‰åŠŸèƒ½ï¼Œå¹¶å¯¹å¤–æ供这些接å£ã€‚访问方利用工具类,便å¯ä»¥è®¿é—®æ供方æ供的å„ç§åŠŸèƒ½ã€‚ + +## 接å£è¯´æ˜Ž + +**表1** DataShareæ供方需è¦å®žçŽ°çš„API + +|接å£å|æè¿°| +|:------|:------| +|onCreate?(want: Want, callback: AsyncCallback<void>): void|DataShareExtensionAbility生命周期回调,在数æ®æ供方应用创建时回调,执行åˆå§‹åŒ–业务逻辑æ“作,如创建数æ®åº“。| +|insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数,在访问方å‘æ•°æ®åº“ä¸æ’入数æ®æ—¶å›žè°ƒã€‚| +|update?(uri: string, predicates: DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数,在访问方更新数æ®æ—¶å›žè°ƒã€‚| +|query?(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void|业务函数,在访问方查询数æ®æ—¶å›žè°ƒã€‚| +|delete?(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void|ä¸šåŠ¡å‡½æ•°ï¼Œåœ¨è®¿é—®æ–¹åˆ é™¤æ•°æ®æ—¶å›žè°ƒã€‚| +|batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void|业务函数,在访问方调用批é‡æ’入数æ®æŽ¥å£æ—¶å›žè°ƒã€‚| +|getType?(uri: string, callback: AsyncCallback<string>): void|业务函数,返回URI所指定数æ®çš„MIME类型。| +|getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void|业务函数,返回支æŒçš„文件的MIME类型。| +|normalizeUri?(uri: string, callback: AsyncCallback<string>): void|业务函数,实现对URI进行规范化。一个规范化的URIå¯ä»¥æ”¯æŒè·¨è®¾å¤‡ä½¿ç”¨ã€æŒä¹…化ã€å¤‡ä»½å’Œè¿˜åŽŸç‰ï¼Œå½“上下文改å˜æ—¶ä»ç„¶å¯ä»¥å¼•ç”¨åˆ°ç›¸åŒçš„æ•°æ®é¡¹ã€‚| +|denormalizeUri?(uri: string, callback: AsyncCallback<string>): void|业务函数,实现将规范化URI转æ¢æˆéžè§„范化的URI。| +|openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void|业务函数,在访问方调用打开文件时回调。æ供方需è¦å®žçŽ°æŒ‰mode所指定的方å¼æ‰“å¼€uri所指定的文件,并返回其文件æ述符。| + + +## å¼€å‘æ¥éª¤ +### æ•°æ®æ供方应用的开å‘(仅é™ç³»ç»Ÿåº”用) + +1. æ•°æ®æ供方(也称æœåŠ¡ç«¯ï¼‰åº”用的开å‘者å¯ç»§æ‰¿äºŽDataShareExtensionAbilityï¼Œå¹¶æ ¹æ®è‡ªå·±çš„éœ€æ±‚æˆ–ç›®æ ‡é€‰æ‹©æ€§å®žçŽ°Insertã€Queryã€Updateã€Deleteç‰æŽ¥å£çš„业务内容,例如数æ®æ供方åªæ供查询æœåŠ¡ï¼Œåˆ™å¯åªé‡å†™æŸ¥è¯¢æŽ¥å£ã€‚业务的实现å¯ç”±å¼€å‘者自定义,例如数æ®å˜å‚¨å®žçŽ°å¯ä»¥é€‰æ‹©OpenHarmony支æŒçš„æ•°æ®åº“,也å¯ä»¥ç›´æŽ¥ä½¿ç”¨æ–‡ä»¶è¿›è¡Œè¯»å†™ï¼Œç”šè‡³å¯ä»¥è®¿é—®ç½‘络数æ®ã€‚ç”±æ¤å¯è§ï¼ŒDataShare并ä¸äº§ç”Ÿæˆ–å˜å‚¨æ•°æ®ï¼Œå®ƒåªæ˜¯â€œæ•°æ®çš„æ¬è¿å·¥â€ã€‚ + + 创建数æ®æ供方的代ç 示例如下: + + ```ets + import Extension from '@ohos.application.DataShareExtensionAbility' + import rdb from '@ohos.data.rdb'; + import fileIo from '@ohos.fileio' + import dataSharePredicates from '@ohos.data.dataSharePredicates' + + + let DB_NAME = "DB00.db"; + let TBL_NAME = "TBL00"; + let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS " + + TBL_NAME + + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, isStudent BOOLEAN, Binary BINARY)"; + + let rdbStore; + let result; + + export default class DataShareExtAbility extends Extension { + private rdbStore_; + + onCreate(want, callback) { + result = this.context.cacheDir + '/datashare.txt' + rdb.getRdbStore(this.context, { + name: DB_NAME + }, 1, function (err, data) { + rdbStore = data; + rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) { + console.log('DataShareExtAbility onCreate, executeSql done err:' + JSON.stringify(err)); + }); + callback(); + }); + } + + insert(uri, value, callback) { + if (value == null) { + console.info('invalid valueBuckets'); + return; + } + rdbStore.insert(TBL_NAME, value, function (err, ret) { + console.info('callback ret:' + ret); + if (callback != undefined) { + callback(err, ret); + } + }); + } + + update(uri, predicates, value, callback) { + if (predicates == null || predicates == undefined) { + console.info('invalid predicates'); + return; + } + try { + rdbStore.update(TBL_NAME,value, predicates, function (err, ret) { + console.info('callback ret:' + ret); + console.info('callback err:' + err); + if (callback != undefined) { + callback(err, ret); + } + }); + } catch (err) { + console.error('error' + err); + } + } + + delete(uri, predicates, callback) { + if (predicates == null || predicates == undefined) { + console.info('invalid predicates'); + return; + } + try { + rdbStore.delete(TBL_NAME,predicates, function (err, ret) { + console.info('ret:' + ret); + if (callback != undefined) { + callback(err, ret); + } + }); + } catch (err) { + console.error('error' + err); + } + } + + query(uri, predicates, columns, callback) { + if (predicates == null || predicates == undefined) { + console.info('invalid predicates'); + } + try { + rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) { + if (resultSet != undefined) { + console.info('resultSet.rowCount: ' + resultSet.rowCount); + } + if (callback != undefined) { + callback(err, resultSet); + } + }); + } catch (err) { + console.error('error' + err); + } + } + + batchInsert(uri: string, valueBuckets, callback) { + if (valueBuckets == null || valueBuckets.length == undefined) { + console.info('invalid valueBuckets'); + return; + } + let resultNum = valueBuckets.length + valueBuckets.forEach(vb => { + console.info('valueBuckets:' + JSON.stringify(vb)); + rdbStore.insert(TBL_NAME, vb, function (err, ret) { + console.info('callback ret:' + ret); + if (callback != undefined) { + callback(err, resultNum); + } + }); + }); + } + + getType(uri: string,callback) { + let ret = "image"; + console.info('ret:' + ret); + let err = {"code":0}; + callback(err,ret); + return ret; + } + + getFileTypes(uri: string, mimeTypeFilter: string, callback) { + let ret = new Array("type01", "type02", "type03"); + console.info('ret:' + ret); + let err = {"code":2}; + callback(err,ret); + return ret; + } + + openFile(uri: string, mode: string, callback) { + fileIo.open(result, 0o2 | 0o100, 0o666, function(err, fd) { + if(err) { + console.info('OpenFile err = ' + err); + } + let num = fileIo.writeSync(fd, "this is a interesting test of DataShare"); + callback(err,fd); + }) + } + + normalizeUri(uri: string,callback) { + let ret = "normalize+" + uri; + console.info('ret:' + ret); + let err = {"code":2}; + callback(err,ret); + } + + denormalizeUri(uri: string,callback) { + let ret = "denormalize+" + uri; + console.info('ret:' + ret); + let err = {"code":2}; + callback(err,ret); + return ret; + } + }; + ``` + +2. å模å—é…ç½® + + | Jsoné‡è¦å—段 | 备注说明 | + | ------------ | ------------------------------------------------------------ | + | "name" | Abilityå称,对应Ability派生的Dataç±»å。 | + | "type" | Ability类型,Data对应的Ability类型为â€data“。 | + | "uri" | 通信使用的URI。 | + | "visible" | 对其他应用是å¦å¯è§ï¼Œè®¾ç½®ä¸ºtrue时,Dataæ‰èƒ½ä¸Žå…¶ä»–åº”ç”¨è¿›è¡Œé€šä¿¡ä¼ è¾“æ•°æ®ã€‚ | + + **module.json5é…ç½®æ ·ä¾‹** + + ```ets + "extensionAbilities": [ + { + "srcEntrance": "./ets/DataShareExtAbility/DataShareExtAbility.ts", + "name": "DataShareExtAbility", + "icon": "$media:icon", + "description": "$string:description_datashareextability", + "type": "dataShare", + "uri": "datashare://com.samples.datasharetest.DataShare", + "visible": true + } + ] + ``` + +### æ•°æ®è®¿é—®æ–¹åº”ç”¨çš„å¼€å‘ +#### æ•°æ®è®¿é—®æ–¹åº”用开å‘指导 + + +1. 导入基础ä¾èµ–包,以åŠèŽ·å–与数æ®æ供方通信的URIå—符串。 + + å…¶ä¸ï¼ŒåŸºç¡€ä¾èµ–包包括: + + - @ohos.application.Ability + - @ohos.data.dataShare + - @ohos.data.dataSharePredicates + + ```ets + // 作为å‚æ•°ä¼ é€’çš„URI,与module.json5ä¸å®šä¹‰çš„URI的区别是多了一个"/"ï¼Œæ˜¯å› ä¸ºä½œä¸ºå‚æ•°ä¼ é€’çš„URIä¸ï¼Œåœ¨ç¬¬äºŒä¸ªä¸Žç¬¬ä¸‰ä¸ª"/"ä¸é—´ï¼Œå˜åœ¨ä¸€ä¸ªDeviceIDçš„å‚æ•° + import Ability from '@ohos.application.Ability' + import dataShare from '@ohos.data.dataShare' + import dataSharePredicates from '@ohos.data.dataSharePredicates' + + let dsHelper; + let abilityContext; + let dseUri = ("datashare:///com.samples.datasharetest.DataShare"); + ``` + +2. 创建工具接å£ç±»å¯¹è±¡ã€‚ + + 工具接å£ç±»å¯¹è±¡DataShareHelper相关接å£å¯å‚考[DataShareHelper](../reference/apis/js-apis-dataShareHelper.md)文档。 + ```ets + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + abilityContext = this.context; + dataShare.createDataShareHelper(abilityContext, dseUri, (err,data)=>{ + dsHelper = data; + }); + } + } + ``` + +3. 获å–到接å£ç±»å¯¹è±¡åŽï¼Œä¾¿å¯åˆ©ç”¨å…¶æ供的接å£è®¿é—®æ供方æ供的æœåŠ¡ï¼Œå¦‚进行数æ®çš„å¢žåˆ æ”¹æŸ¥ç‰ã€‚ + + ```ets + // 构建一æ¡æ•°æ® + var valuesBucket = {"name": "ZhangSan", "age": 21, "isStudent": false, "Binary": new Uint8Array([1,2,3])}; + var updateBucket = {"name": "LiSi", "age": 18, "isStudent": true, "Binary": new Uint8Array([1,2,3])}; + let da = new dataSharePredicates.DataSharePredicates(); + var valArray =new Array("*"); + let people = new Array( + {"name": "LiSi", "age": 41, "Binary": ar}, + {"name": "WangWu", "age": 21, "Binary": arr}, + {"name": "ZhaoLiu", "age": 61, "Binary": arr}); + ``` + + ```ets + // æ’入一æ¡æ•°æ®ï¼Œcallbackæ–¹å¼è°ƒç”¨: + dsHelper.insert(dseUri, valuesBucket, (err,data) => { + console.log("dsHelper insert result: " + data); + }); + ``` + + ```ets + // æ’入一æ¡æ•°æ®ï¼Œpromiseæ–¹å¼è°ƒç”¨: + let ret = await dsHelper.insert(dseUri, valuesBucket); + ``` + + ```ets + // åˆ é™¤æŒ‡å®šçš„æ•°æ®ï¼Œcallbackæ–¹å¼è°ƒç”¨: + dsHelper.delete(dseUri, da, (err,data) => { + console.log("dsHelper delete result: " + data); + }); + ``` + + ```ets + // åˆ é™¤æŒ‡å®šçš„æ•°æ®ï¼Œpromiseæ–¹å¼è°ƒç”¨: + let ret = await dsHelper.delete(dseUri, da); + ``` + + ```ets + // æ›´æ–°æ•°æ®ï¼Œcallbackæ–¹å¼è°ƒç”¨: + dsHelper.update(dseUri, da, updateBucket, (err,data) => { + console.log("dsHelper update result: " + data); + }); + ``` + + ```ets + // æ›´æ–°æ•°æ®ï¼Œpromiseæ–¹å¼è°ƒç”¨: + let ret = await dsHelper.update(dseUri, da, updateBucket); + ``` + + ```ets + // 查询数æ®ï¼Œcallbackæ–¹å¼è°ƒç”¨: + dsHelper.query(dseUri, da, valArray, (err,data) => { + console.log("dsHelper query result: " + data); + }); + ``` + + ```ets + // 查询数æ®ï¼Œpromiseæ–¹å¼è°ƒç”¨: + let result = await dsHelper.query(dseUri, da, valArray); + ``` + +## 相关实例 + +针对DataShareå¼€å‘,有以下相关实例å¯ä¾›å‚考: + +待补充。 + +- [`DataShare`:DataShare的创建与访问(eTS)(API9)](https://gitee.com/openharmony/app_samples/tree/master/ability/DataAbility) diff --git a/zh-cn/application-dev/database/database-datashare-overview.md b/zh-cn/application-dev/database/database-datashare-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..220ab376c69e9dc07afe6fcd3882b14684a6c143 --- /dev/null +++ b/zh-cn/application-dev/database/database-datashare-overview.md @@ -0,0 +1,54 @@ +# æ•°æ®å…±äº«å¼€å‘概述 + +## æ•°æ®å…±äº«ç®€ä»‹ + +DataShareå³æ•°æ®å…±äº«æ¨¡å—用于应用管ç†å…¶è‡ªèº«æ•°æ®ï¼Œä¹Ÿæ供了å‘其他应用共享以åŠç®¡ç†å…¶æ•°æ®çš„方法,目å‰ä»…支æŒåŒä¸ªè®¾å¤‡ä¸Šåº”用之间的数æ®å…±äº«ã€‚ + +在许多应用场景ä¸éƒ½éœ€è¦å°†æˆ‘们程åºä¸çš„æ•°æ®å…±äº«ç»™å…¶ä»–程åºï¼Œä¾‹å¦‚电è¯ç°¿ã€çŸä¿¡ã€åª’体库ç‰ç‰ï¼Œå½“然并ä¸æ˜¯æ‰€æœ‰çš„æ•°æ®éƒ½æ˜¯å…许其他应用去访问的,例如账å·ã€å¯†ç ,有些数æ®åªå…许其他应用查询ä¸å…è®¸å…¶å¢žåˆ æ”¹ï¼Œä¾‹å¦‚çŸä¿¡ï¼Œè¿™å°±è¦æ±‚我们è¦å¯¹è®¿é—®è€…进行æƒé™çš„检查和é™åˆ¶ã€‚ + +OpenHarmonyæ供的æŒä¹…化å˜å‚¨æ–¹æ¡ˆå¦‚文件ã€åˆ†å¸ƒå¼æ•°æ®åº“,è¦ä¹ˆæœ‰éšç§æ³„æ¼çš„风险,è¦ä¹ˆåªèƒ½åœ¨å½“å‰åº”用ä¸è®¿é—®ï¼Œè¦ä¹ˆéœ€è¦å¼€å‘者自己去å°è£…,一个安全ã€ä¾¿æ·çš„å¯ä»¥è·¨è®¾å¤‡è·¨åº”用的数æ®å…±äº«æœºåˆ¶æ˜¯å¿…需的,DataShare便应è¿è€Œç”Ÿã€‚ + +对于数æ®æ供者æ¥è¯´ï¼Œå¯ä»¥ä½¿ç”¨DataShareæ供的框架轻æ¾çš„实现å‘其他应用共享数æ®ï¼Œè€Œä¸éœ€è¦è‡ªå·±è¿›è¡Œç¹ççš„å°è£…;对于数æ®è®¿é—®æ–¹æ¥è¯´ï¼Œå› DataShare的访问方å¼ä¸ä¼šå› æ•°æ®æ供的方å¼è€Œä¸åŒï¼Œæ‰€ä»¥åªéœ€è¦å¦ä¹ 和使用一套接å£ï¼Œæ—¢å‡å°äº†å¼€å‘难度åˆèŠ‚çœäº†å¦ä¹ 多ç§æŽ¥å£çš„时间。 + +## 基本概念 + + +在进行应用的开å‘å‰ï¼Œå¼€å‘者应了解以下基本概念: + + +- æ•°æ®æ供方 + + æ供数æ®åŠå®žçŽ°ç›¸å…³ä¸šåŠ¡çš„应用程åºï¼Œä¹Ÿç§°ä¸ºç”Ÿäº§è€…或æœåŠ¡ç«¯ã€‚ + +- æ•°æ®è®¿é—®æ–¹ + + 访问数æ®æ供方所æ供的数æ®æˆ–业务的应用程åºï¼Œä¹Ÿç§°ä¸ºæ¶ˆè´¹è€…或客户端。 + +- æ•°æ®é›† + + åªç”¨æˆ·è¦æ’入的数æ®é›†åˆï¼Œå¯ä»¥æ˜¯ä¸€æ¡æˆ–多æ¡æ•°æ®ã€‚æ•°æ®é›†ä»¥é”®å€¼å¯¹çš„å½¢å¼å˜åœ¨ï¼Œå€¼æ”¯æŒå¤šç§æ•°æ®ç±»åž‹ã€‚ + +- 结果集 + 指用户查询之åŽçš„结果集åˆï¼Œå¯ä»¥å¯¹æ•°æ®è¿›è¡Œè®¿é—®ã€‚结果集æ供了çµæ´»çš„æ•°æ®è®¿é—®æ–¹å¼ï¼Œå¯ä»¥æ›´æ–¹ä¾¿çš„拿到用户想è¦çš„æ•°æ®ã€‚ + +- è°“è¯ + æè¿°ç›é€‰æ¡ä»¶çš„集åˆã€‚æ—¢å¯ä»¥æ˜¯æŸ¥è¯¢çš„æ¡ä»¶ä¹Ÿå¯ä»¥æ˜¯åˆ 除的æ¡ä»¶ä¹Ÿå¯ä»¥æ˜¯æ›´æ–°çš„æ¡ä»¶ã€‚ + +## è¿ä½œæœºåˆ¶ + +**图 1** DataShareè¿ä½œæœºåˆ¶<a name="fig3330103712254"></a> + + + + +DataShareExtAbility模å—å³ä¸ºæ•°æ®æ供方,实现跨应用数æ®å…±äº«çš„相关业务。DataShareHelper模å—为数æ®è®¿é—®æ–¹æä¾›æ“作DataShareExtAbilityå³æ•°æ®æ供方的接å£ã€‚æ•°æ®è®¿é—®æ–¹ä¸Žæ供方通过IPC进行通信,数æ®æ供方实现å¯ä»¥æ˜¯æ•°æ®åº“,也å¯ä»¥æ˜¯å…¶ä»–æ•°æ®å˜å‚¨æ–¹å¼ã€‚ + +ResultSet模å—æ供跨应用æ“作或访问查询出的结果集的接å£ï¼Œç»“果集使用共享内å˜å®žçŽ°ã€‚ + +## 约æŸä¸Žé™åˆ¶ + +**æ•°æ®å…±äº«çš„约æŸä¸Žé™åˆ¶**: + +- DataShareå—到数æ®æ供方所使用数æ®åº“,例如支æŒçš„æ•°æ®æ¨¡åž‹ï¼ŒKey的长度ã€Value的长度ã€æ¯ä¸ªåº”用程åºæœ€å¤šæ”¯æŒåŒæ—¶æ‰“开数æ®åº“æ•°é‡éƒ½å—到数æ®åº“çš„é™åˆ¶ã€‚ + +- å› DataShare内部实现ä¾èµ–于IPC通信,所以支æŒæ•°æ®é‡çš„大å°å—到IPC通信的约æŸä¸Žé™åˆ¶ã€‚ diff --git a/zh-cn/application-dev/database/figures/zh-cn_DataShare.png b/zh-cn/application-dev/database/figures/zh-cn_DataShare.png new file mode 100644 index 0000000000000000000000000000000000000000..63d2aea85ed9e89eaa3edd1ac164789c7f4bb7a5 Binary files /dev/null and b/zh-cn/application-dev/database/figures/zh-cn_DataShare.png differ