diff --git a/README.en.md b/README.en.md index df00ed4b50e5e706e9f7254163f7765ec5c9b122..426afd14abcf4bf6ad8b715d982ef1791e543e93 100644 --- a/README.en.md +++ b/README.en.md @@ -1,10 +1,9 @@ -# Realization of address book function based on distributed key-value database +# Implementing Contacts Based on the Distributed KV Store ## Overview -Taking the address book as an example, this Codelab introduces the creation of distributed key-value database, data addition/deletion/modification/query/synchronization and other operation methods. - -## Preview +With Contacts as an example, learn to create a distributed key-value (KV) store and implement the functionalities of adding, deleting, updating, querying, and synchronizing data. +## Effect | Add | Delete | Edit | Query | |:----------------------------------------------------------------:|:----------------------------------------------------------------:|:-----------------------------------------------------------------:|:------------------------------------------------------------------:| @@ -12,66 +11,66 @@ Taking the address book as an example, this Codelab introduces the creation of d ## How to Use -1. Apply the home page, click the "Add" button in the upper right corner to enter the new contact page. -2. Apply the homepage, click the "More" button in the upper right corner, and click "Bulk Delete" to enter the contact bulk deletion page. -3. On the application homepage, click on the contact list to enter the contact details page. -4. Contact details page, click the "edit" button below to enter the contact editing page. -5. Contact details page, click the "Delete" button below to delete the contact. -6. Create a new contact page, enter the contact information, click the "Save" button on the upper right to add a contact, and the page will jump to the application home page. -7. On the contact bulk deletion page, click Select All below to select/uncheck all contacts. -8. Batch contact deletion page, select the contact to be deleted, and click "Delete" below to delete the selected contact. -9. On the contact editing page, after editing the contact information, click the "Save" button in the upper right corner to modify the contact information. +1. On the application home page, tap the Add button in the upper-right corner to navigate to the Add Contact page. +2. On the application home page, tap the More button in the upper-right corner, then tap Batch Delete to navigate to the batch contact deletion page. +3. On the application home page, tap a contact in the list to navigate to the contact details page. +4. On the contact details page, tap the Edit button to edit the contact. +5. On the contact details page, tap the Delete button to delete the contact. +6. On the Add Contact page, enter the contact information and tap the Save button in the upper-right corner to add the contact. The page will then redirect to the application home page. +7. On the batch deletion page, tap Select All to select or deselect all contacts. +8. On the batch deletion page, select the contact to be deleted and tap the Delete button. +9. On the contact editing page, modify the contact information and tap the Save button in the upper-right corner to update the contact. ## Project Directory ``` -├──entry/src/main/ets -│ ├──common -│ │ └──CommonConstants.ets // Constant set -│ ├──components -│ │ ├──ContactBottomBar.ets // Tab component at the bottom of address book deletion page -│ │ ├──ContactDeleteDialog.ets // Address Book Delete Pop-up Component -│ │ ├──ContactDetailItem.ets // List Item Component of Address Book Details Page -│ │ ├──ContactDeviceDialog.ets // Address book device pop-up component -│ │ └──ContactListItem.ets // Address Book List Page List Item Component -│ ├──entryability -│ │ └──EntryAbility.ets // Entry file -│ ├──pages -│ │ ├──ContactAddAndEditPage.ets // Address Book Add and Edit Page -│ │ ├──ContactDeletePage.ets // Address book deletion page -│ │ ├──ContactDetailPage.ets // Address book details page -│ │ └──ContactHomePage.ets // Address book home page -│ ├──utils -│ │ ├──ContactDeviceManager.ets // Address book device management class -│ │ └──KvManager.ets // Key-value database management class -│ └──viewmodel -│ └──ContactViewModel.ets // Address book model -└──entry/src/main/resources // Resource file +├──entry/src/main/ets +│ ├──common +│ │ └──CommonConstants.ets // Common constants +│ ├──components +│ │ ├──ContactBottomBar.ets // Bottom tab component for the contact deletion page +│ │ ├──ContactDeleteDialog.ets // Contact deletion dialog component +│ │ ├──ContactDetailItem.ets // List item component for the contact details page +│ │ ├──ContactDeviceDialog.ets // Contact device dialog component +│ │ └──ContactListItem.ets // List item component for the contact list page +│ ├──entryability +│ │ └──EntryAbility.ets // Entry ability +│ ├──pages +│ │ ├──ContactAddAndEditPage.ets // Contact addition and editing page +│ │ ├──ContactDeletePage.ets // Contact deletion page +│ │ ├──ContactDetailPage.ets // Contact details page +│ │ └──ContactHomePage.ets // Contacts home page +│ ├──utils +│ │ ├──ContactDeviceManager.ets // Contact device manager +│ │ └──KvManager.ets // KV store manager +│ └──viewmodel +│ └──ContactViewModel.ets // Contact ViewModel +└──entry/src/main/resources // Resource files ``` ## How to Implement -1. Encapsulate the device management class, and call the device management capability distributedDeviceManager.CreateDeviceManager() to create a device management instance. The device management instance is the call portal of the distributed device management method, which is used to obtain the relevant information of trusted devices and local devices. -2. Register the device state callback through the on('deviceStateChange') event of the DeviceManager, so as to inform the trusted devices in the application network of changes in the device state in time, register the device state change callback function, and perform different methods to update the device list according to the returned device state data.action. -3. Register the device status callback through the on('discoverSuccess') event of the device management instance DeviceManager, so as to inform the change of the devices in the application network in time when it is discovered, and call startDiscovering() to discover the surrounding devices. -4. If the device is in the list of trusted devices, execute the startAbility() method to start the application on the connected device, and send the current device information as a parameter to the connected device. If the device is not a trusted device, execute the bindTarget() method to start the verification. At this time, the connecting device prompts whether to accept or not. After receiving the connection, the connecting device displays the PIN code, and the local device enters the PIN code to confirm that the connection is successful. Click the Query Device button again, select the connected device, and click OK to start the application on the connected device. -5. When the device pop-up window is closed, stopDiscovering() is called to stop discovering peripheral devices, and the device monitoring task is cancelled through the off('deviceStateChange') and off('discoverSuccess') events of the device management instance DeviceManager. -6. When the application starts for the first time, call the requestPermissionsFromUser() method to dynamically pop up the window to get authorization. -7. Create a key-value database object instance, call distributedKvStore.createKvManager() to create a KVManager object instance, which is used to manage database objects, and call the getKVStore() method of KVManager to create and obtain a distributed key-value database. -8. Call the on('dataChange') interface to subscribe to the data changes of other devices in the networking, and register the data change callback function. -9. Encapsulates six methods of adding(put()), deleting(delete(), deleteBatch()), changing(put()), checking(get()), getEntries()) to the operation database. -10. Call the interface sync() of synchronous data to push the current device data change to other devices in the networking. -11. When the data of other devices in the networking changes, the callback function is executed, and all the data of the devices with data changes are obtained through the self-defined getAllData() method, so as to update the local data. +1. Encapsulate the device management class by calling the device management capability [distributedDeviceManager.createDeviceManager()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#distributeddevicemanagercreatedevicemanager) to create a device manager instance. This instance serves as the entry point for calling distributed device management methods, used to obtain information about trusted devices and local devices. +2. Register a device state callback through the [on('deviceStateChange')](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#ondevicestatechange) event of the DeviceManager instance to promptly notify the application of changes in trusted devices within the device network. Register a device state change callback function and execute different methods to update the device list based on the returned data.action. +3. Register a device state callback through the [on('discoverSuccess')](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#ondiscoversuccess) event of the DeviceManager instance to promptly notify the application of device changes within the network when devices are discovered. Call [startDiscovering()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#startdiscovering) to discover surrounding devices. +4. If the discovered device is in the trusted device list, execute the [startAbility()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-inner-application-uiabilitycontext#startability) method to launch the application on the connected device, passing the current device information as parameters. For untrusted devices, execute the [bindTarget()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#bindtarget) method to initiate verification. This triggers a connection prompt on the target device. Upon user acceptance, the target device displays a PIN code, which must then be entered on the local device for successful verification and connection. Subsequent device selection (for example, after a user taps the device query button and picks a connected device) will also trigger startAbility() to launch the application on the selected device. +5. When the device selection dialog is closed, call [stopDiscovering()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#stopdiscovering) to stop discovering surrounding devices, and unregister device listening tasks through the [off('deviceStateChange')](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#offdevicestatechange) and [off('discoverSuccess')](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributeddevicemanager#offdiscoversuccess) events of the DeviceManager instance. +6. Upon the application's first launch, dynamically request necessary authorization from the user by calling [requestPermissionsFromUser()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-abilityaccessctrl#requestpermissionsfromuser9). +7. Call [distributedKVStore.createKVManager()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#distributedkvstorecreatekvmanager) to create a KVManager instance for managing database objects. Then, call the [getKVStore()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#getkvstore) method of the KVManager to create and obtain a distributed KV store. +8. Call the [on('dataChange')](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#ondatachange) API to subscribe to data changes on other devices within the network and register a data change callback function. +9. Encapsulate six methods for store operations: adding ([put()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#put)), deleting ([delete()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#delete)and [deleteBatch()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#deletebatch)), updating ([put()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#put)), and querying ([get()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#get) and [getEntries()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#getentries)). +10. Call the data synchronization API [sync()](https://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-distributedkvstore#sync) to push current device data changes to other devices within the network. +11. When data changes occur on other devices within the network, execute the callback function, use the custom getAllData() method to obtain all data from the device where the data changed, and update the local data. -## Permissions +## Required Permissions -This Codelab uses distributed capabilities, and it needs to add data exchange permissions between different devices in the configuration file module.json5.：ohos.permission.DISTRIBUTED_DATASYNC。 +To achieve the distributed capabilities involved in this codelab, you need to add the data exchange permission ohos.permission.DISTRIBUTED_DATASYNC to the module.json5 configuration file. ## Constraints -1. The sample is only supported on Huawei phones with standard systems. -2. The HarmonyOS version must be HarmonyOS 5.1.1 Release or later. -3. The DevEco Studio version must be DevEco Studio 5.1.1 Release or later. -4. The HarmonyOS SDK version must be HarmonyOS 5.1.1 Release SDK or later. -5. Double-ended devices need to log in to the same Huawei account, so it is recommended to turn on the device finding function. -6. Double-ended devices need to turn on the Wi-Fi and Bluetooth switches. When conditions permit, it is recommended to connect to the same LAN. -7. Both end devices need this application. +1. This sample is only supported on Huawei phones running standard systems. +2. The HarmonyOS version must be HarmonyOS 6.0.0 Release or later. +3. The DevEco Studio version must be DevEco Studio 6.0.0 Release or later. +4. The HarmonyOS SDK version must be HarmonyOS 6.0.0 Release SDK or later. +5. Both devices must be logged in with the same HUAWEI ID. You are advised to enable Find Device. +6. Wi-Fi and Bluetooth must be enabled on both devices. If possible, both devices should be connected to the same LAN. +7. Both devices must have the application installed. \ No newline at end of file diff --git a/README.md b/README.md index 7fd5acc2b04f6de4b63b391835270e5b6d37ba1d..0afe08baaf8649b817edb0a05260e26a416bc714 100644 --- a/README.md +++ b/README.md @@ -69,9 +69,9 @@ ## 约束与限制 1. 本示例仅支持标准系统上运行，支持设备：华为手机。 -2. HarmonyOS系统：HarmonyOS 5.1.1 Release及以上。 -3. DevEco Studio版本：DevEco Studio 5.1.1 Release及以上。 -4. HarmonyOS SDK版本：HarmonyOS 5.1.1 Release SDK及以上。 +2. HarmonyOS系统：HarmonyOS 6.0.0 Release及以上。 +3. DevEco Studio版本：DevEco Studio 6.0.0 Release及以上。 +4. HarmonyOS SDK版本：HarmonyOS 6.0.0 Release SDK及以上。 5. 双端设备需要登录同一华为账号，建议打开查找设备功能。 6. 双端设备需要打开Wi-Fi和蓝牙开关，条件允许时，建议连接同一局域网。 7. 双端设备都需要有该应用。 diff --git a/screenshots/devices/contactAdd.en.gif b/screenshots/devices/contactAdd.en.gif index 19c872ffabd74c7e585ec2a9652ff4acd04230ec..540cc45097aa660dd042850a94698f073238ead9 100644 Binary files a/screenshots/devices/contactAdd.en.gif and b/screenshots/devices/contactAdd.en.gif differ diff --git a/screenshots/devices/contactBatch.en.gif b/screenshots/devices/contactBatch.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..9d54152f52822c9518382eca9fe96b94bbe1c2ba Binary files /dev/null and b/screenshots/devices/contactBatch.en.gif differ diff --git a/screenshots/devices/contactBatch.gif b/screenshots/devices/contactBatch.gif new file mode 100644 index 0000000000000000000000000000000000000000..7f9f786b500cd7196a9f65aa01418784ca470572 Binary files /dev/null and b/screenshots/devices/contactBatch.gif differ diff --git a/screenshots/devices/contactDel.en.gif b/screenshots/devices/contactDel.en.gif index 2e4da8c32910662c0758374254afc04a063534c3..212613d02a3109b104072b37c8f1f8d9910e5d9d 100644 Binary files a/screenshots/devices/contactDel.en.gif and b/screenshots/devices/contactDel.en.gif differ diff --git a/screenshots/devices/contactDevice.en.gif b/screenshots/devices/contactDevice.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..85b866402d5bdce6824ddd0daf6d2cfb61530f77 Binary files /dev/null and b/screenshots/devices/contactDevice.en.gif differ diff --git a/screenshots/devices/contactDevice.en.mp4 b/screenshots/devices/contactDevice.en.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..e9ad11a4d35eb36cc9922581fb3af87e72aaba19 Binary files /dev/null and b/screenshots/devices/contactDevice.en.mp4 differ diff --git a/screenshots/devices/contactDevice.gif b/screenshots/devices/contactDevice.gif new file mode 100644 index 0000000000000000000000000000000000000000..2b43c4cf2d4feb499e5308b9f930377b3ebe5deb Binary files /dev/null and b/screenshots/devices/contactDevice.gif differ diff --git a/screenshots/devices/contactDevice.mp4 b/screenshots/devices/contactDevice.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..bff0d9363fa43344e5aa8ea25c80f3005386df69 Binary files /dev/null and b/screenshots/devices/contactDevice.mp4 differ diff --git a/screenshots/devices/contactEdit.en.gif b/screenshots/devices/contactEdit.en.gif index b96365d7b6cde20b9c254b839d5d8ca8b0fc66dd..a917170fa528ca9c73dd7f20f259a0fbd80a6d15 100644 Binary files a/screenshots/devices/contactEdit.en.gif and b/screenshots/devices/contactEdit.en.gif differ diff --git a/screenshots/devices/contactQuery.en.gif b/screenshots/devices/contactQuery.en.gif index 16633cdcd1085cda386c61b0c967d0f728b7ef50..e066ec1519b26ea95422823386ebc993ea7a0171 100644 Binary files a/screenshots/devices/contactQuery.en.gif and b/screenshots/devices/contactQuery.en.gif differ