1# 应用间配置共享 (ArkTS) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @woodenarow--> 5<!--Designer: @woodenarow; @xuelei3--> 6<!--Tester: @chenwan188; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9## 场景介绍 10 11应用间配置共享通过集中管理公共配置信息，在不同应用间共享配置，提升协作效率。 12 13从API version 20开始，支持应用间配置共享。 14 15## 运作机制 16 17应用间配置共享运作机制如下所示： 18 191. **配置发布方（即数据提供方）**：负责提供默认共享配置项，并能动态修改配置项信息。当前支持静态配置和动态配置两种配置方式。 20 - **静态配置**：应用包在安装时提供的默认共享配置项（不依赖应用启动即生效）。 21 - **动态配置**：配置发布方通过调用相关接口可以动态新增、删除或修改配置项（不依赖应用升级）。 222. **配置访问方（即数据访问方）**：可通过调用接口获取配置信息、或者监听/取消监听配置变化。 23 24## 约束与限制 25 26一个应用最多可以发布32个配置项，这个数量是静态配置与动态配置的总和。 27 28## 接口说明 29以下接口为应用间配置共享的相关接口。详细接口和说明，请参考[应用间配置共享接口](../reference/apis-arkdata/js-apis-data-dataShare.md#datasharecreatedataproxyhandle20)。 30 31### 公共接口 32 33| 接口名称 | 描述 | 34| ------------------------------- | ------------------------------------------------------------------------------------------------------ | 35| createDataProxyHandle(): Promise<DataProxyHandle> | 创建数据代理操作句柄，可用于订阅、发布、获取等操作。 | 36 37### 配置发布方接口 38 39| 接口名称 | 描述 | 40| ------------------------------------------------------------ | ------------------ | 41| publish(data: ProxyData[], config: DataProxyConfig): Promise<DataProxyResult[]> | 发布或修改配置项。 | 42| delete(uris: string[], config: DataProxyConfig): Promise<DataProxyResult[]> | 删除配置项。 | 43 44### 配置访问方接口 45 46| 接口名称 | 描述 | 47| ------------------------------------------------------------ | -------------------- | 48| get(uris: string[], config: DataProxyConfig): Promise<DataProxyGetResult[]> | 获取配置项信息。 | 49| on(event: 'dataChange', uris: string[], config: DataProxyConfig, callback: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] | 监听配置项变化。 | 50| off(event: 'dataChange', uris: string[], config: DataProxyConfig, callback?: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] | 取消监听配置项变化。 | 51 52 53## 配置发布方 54### module.json5 配置 55配置发布方需要配置module.json5文件中的crossAppSharedConfig字段，通过crossAppSharedConfig字段引用shared_config.json文件，shared_config.json为共享配置文件，定义了应用希望与其他应用共享的配置项。共享配置文件需放置在工程resources/base/profile目录下，并通过`$`资源访问方式引用。 56 57 58```json 59{ 60 "module":{ 61 "crossAppSharedConfig": "$profile:shared_config" 62 } 63} 64``` 65 66 67共享配置文件shared_config.json的文件名"shared_config"可自定义，根节点名称为crossAppSharedConfig，为对象数组，标识当前共享配置项的数量。（一个应用最多可以发布32个配置项，这个数量是静态配置项与动态配置项的总和。静态配置项数量超过32时，只解析前32个符合crossAppSharedConfig字段配置说明要求的配置项，其余配置项不生效。） 68 69crossAppSharedConfig字段配置说明： 70 71| 属性名称 | 含义 | 数据类型 | 必填 | 72| ------- | ------- | ------- | ------- | 73| uri | 共享配置项的全局唯一标识。固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复。uri最大长度为256字节。 | 字符串 | 是 | 74| value | 共享配置项的值，最大长度为4096字节。 | 字符串 | 是 | 75| allowList | 允许访问该共享配置项的应用程序列表。数组最大长度为256，超过256的部分不生效。数组中每个元素为应用的[appIdentifier](../quick-start/common_problem_of_application.md#什么是appidentifier)，单个appIdentifier为只包含数字的字符串，最大长度为128字节，超过128字节的appIdentifier不会生效。可使用[getBundleInfoForSelf](../reference/apis-ability-kit/js-apis-bundleManager.md#bundlemanagergetbundleinfoforself)接口来获取当前应用的appIdentifier。 | 字符串数组 | 是 | 76 77```json 78{ 79 "crossAppSharedConfig": [ 80 { 81 "uri": "datashareproxy://com.example.example/key1", 82 "value": "SHARED_CONFIG_DEMO1", 83 "allowList": ["6917573629901742292"] 84 }, 85 { 86 "uri": "datashareproxy://com.example.example/key2", 87 "value": "SHARED_CONFIG_DEMO2", 88 "allowList": ["6917573298752100864", "6917573298752100864"] 89 } 90 ] 91} 92``` 93 94### 静态配置 95 96应用包在安装时提供的默认共享配置项，即在应用安装过程中，预先定义并设置好的共享配置项，这些配置项不依赖应用的启动即可生效。 97 98### 动态配置 99 100可通过调用publish接口或delete接口，动态新增、删除或修改配置项。 101 102- 通过调用publish接口发布或修改配置项。 103 104 ```ts 105 import { dataShare } from '@kit.ArkData'; 106 import { BusinessError } from '@kit.BasicServicesKit'; 107 108 export function publish() { 109 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 110 const newConfigData: dataShare.ProxyData[] = [{ 111 uri: 'datashareproxy://com.example.app1/config1', 112 value: 'Value1', 113 allowList: ['com.example.app2', 'com.example.app3'], 114 }, { 115 uri: 'datashareproxy://com.example.app1/config2', 116 value: 'Value2', 117 allowList: ['com.example.app3', 'com.example.app4'], 118 },]; 119 const config: dataShare.DataProxyConfig = { 120 type: dataShare.DataProxyType.SHARED_CONFIG, 121 }; 122 dsProxyHelper.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => { 123 results.forEach((result) => { 124 console.info(`URI: ${result.uri}, Result: ${result.result}`); 125 }); 126 }).catch((error: BusinessError) => { 127 console.error('Error publishing config:', error); 128 }); 129 }).catch((error: BusinessError) => { 130 console.error('Error creating DataProxyHandle:', error); 131 }); 132 } 133 ``` 134 135- 通过调用delete接口删除配置项。 136 137 ```ts 138 import { dataShare } from '@kit.ArkData'; 139 import { BusinessError } from '@kit.BasicServicesKit'; 140 141 export function deleteShareConfig() { 142 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 143 const urisToDelete: string[] = 144 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 145 const config: dataShare.DataProxyConfig = { 146 type: dataShare.DataProxyType.SHARED_CONFIG, 147 }; 148 dsProxyHelper.delete(urisToDelete, config).then((results: dataShare.DataProxyResult[]) => { 149 results.forEach((result) => { 150 console.info(`URI: ${result.uri}, Result: ${result.result}`); 151 }); 152 }).catch((error: BusinessError) => { 153 console.error('Error deleting config:', error); 154 }); 155 }).catch((error: BusinessError) => { 156 console.error('Error creating DataProxyHandle:', error); 157 }); 158 } 159 ``` 160 161## 配置访问方 162 163配置访问方可以通过调用get、on或off接口来获取配置信息或监听/取消监听配置变化。 164 165### 获取配置项信息 166 167使用get接口获取配置信息。 168 169```ts 170import { dataShare } from '@kit.ArkData'; 171import { BusinessError } from '@kit.BasicServicesKit'; 172 173export function get() { 174 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 175 const urisToGet: string[] = 176 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 177 const config: dataShare.DataProxyConfig = { 178 type: dataShare.DataProxyType.SHARED_CONFIG, 179 }; 180 dsProxyHelper.get(urisToGet, config).then((results: dataShare.DataProxyGetResult[]) => { 181 results.forEach((result) => { 182 console.info(`URI: ${result.uri}, Result: ${result.result}, AllowList: ${result.allowList}`); 183 }); 184 }).catch((error: BusinessError) => { 185 console.error('Error getting config:', error); 186 }); 187 }).catch((error: BusinessError) => { 188 console.error('Error creating DataProxyHandle:', error); 189 }); 190} 191``` 192 193### 监听/取消监听配置变化 194 195使用on接口监听配置变化，使用off接口取消监听配置变化。 196 197```ts 198import { dataShare } from '@kit.ArkData'; 199import { BusinessError } from '@kit.BasicServicesKit'; 200 201export function watchConfigChanges() { 202 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 203 const uris: string[] = 204 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 205 const config: dataShare.DataProxyConfig = { 206 type: dataShare.DataProxyType.SHARED_CONFIG, 207 }; 208 const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => { 209 if (err) { 210 console.error('err:', err); 211 } else { 212 changes.forEach((change) => { 213 console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`); 214 }); 215 } 216 }; 217 // 监听配置变化 218 const listenResults: dataShare.DataProxyResult[] = dsProxyHelper.on('dataChange', uris, config, callback); 219 listenResults.forEach((result) => { 220 console.info(`URI: ${result.uri}, Result: ${result.result}`); 221 }); 222 // 取消监听配置变化 223 const unListenResults: dataShare.DataProxyResult[] = dsProxyHelper.off('dataChange', uris, config, callback); 224 unListenResults.forEach((result) => { 225 console.info(`URI: ${result.uri}, Result: ${result.result}`); 226 }); 227 }).catch((error: BusinessError) => { 228 console.error('Error creating DataProxyHandle:', error); 229 }); 230} 231``` 232