diff --git a/README.en.md b/README.en.md index d16009501035c73f2073eddd9a892213fe149819..df00ed4b50e5e706e9f7254163f7765ec5c9b122 100644 --- a/README.en.md +++ b/README.en.md @@ -1,37 +1,77 @@ -# Distributed Contacts +# Realization of address book function based on distributed key-value database -## Introduction +## Overview -With Contacts as an example, this codelab will show you how to create a distributed key-value (KV) store and how to add, delete, modify, query, and synchronize data. +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 -![](screenshots/devices/contact.en.gif) -## Concepts +| Add | Delete | Edit | Query | +|:----------------------------------------------------------------:|:----------------------------------------------------------------:|:-----------------------------------------------------------------:|:------------------------------------------------------------------:| +| | | | | -- Application data persistence: refers to the process in which applications save data in the memory to devices in the form of files or databases. The data in the memory is usually saved in the forms of data structs or data objects, while the data in storage media can be saved in the forms of text, databases, or binary files. -- KV store: stores data in the form of KV pairs. It allows you to store data organized in a simple model, for example, product names and prices, or employee IDs and daily attendances. The simple data structure allows higher compatibility with different database versions and device types. -- **@ohos.data.distributedKVStore** (distributed KV store): provides the distributed synergy capability between databases of different devices for applications. By calling the APIs, applications can save data to a distributed KV store and perform operations, such as adding, deleting, modifying, and querying data in the distributed KV store. +## How to Use -## Permissions +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. -This codelab uses the distributed capability. It requires you to add the data exchange permission **ohos.permission.DISTRIBUTED_DATASYNC** to the **module.json5** configuration file. +## 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 +``` -## How to Use +## 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. + +## Permissions -1. On the app home page, tap the Add button in the upper right corner. You can create a contact. -2. On the app home page, tap the More button in the upper right corner and then Batch Delete. You can delete contacts in batches. -3. On the app home page, tap Contacts to access the contact details page. -4. On the contact details page, tap Edit to edit a contact. -5. On the contact details page, tap Delete to delete a contact. -6. On the New Contact page, enter the contact information and tap Save in the upper right corner to add a contact. -7. On the batch deletion page, tap Select All to select or deselect all contacts. -8. On the batch deletion page, select the contacts to be deleted and tap Delete. -9. On the contact editing page, edit the contact information and tap Save in the upper right corner. You can modify the contact information. +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。 ## Constraints 1. The sample is only supported on Huawei phones with standard systems. -2. HarmonyOS: HarmonyOS 5.1.1 Release or later. -3. DevEco Studio: DevEco Studio 5.1.1 Release or later. -4. HarmonyOS SDK: HarmonyOS 5.1.1 Release SDK or later. +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. diff --git a/screenshots/devices/contact.en.gif b/screenshots/devices/contact.en.gif deleted file mode 100644 index 0715456d985de3ca07b47602e9ca43f294372da1..0000000000000000000000000000000000000000 Binary files a/screenshots/devices/contact.en.gif and /dev/null differ diff --git a/screenshots/devices/contactAdd.en.gif b/screenshots/devices/contactAdd.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..19c872ffabd74c7e585ec2a9652ff4acd04230ec Binary files /dev/null and b/screenshots/devices/contactAdd.en.gif differ diff --git a/screenshots/devices/contactAdd.gif b/screenshots/devices/contactAdd.gif index 2385241fb25fee1f97a990a7790bc6b6b8f53298..5c9db39fb832c28f5f97e9581322d997549aa674 100644 Binary files a/screenshots/devices/contactAdd.gif and b/screenshots/devices/contactAdd.gif differ diff --git a/screenshots/devices/contactDel.en.gif b/screenshots/devices/contactDel.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..2e4da8c32910662c0758374254afc04a063534c3 Binary files /dev/null and b/screenshots/devices/contactDel.en.gif differ diff --git a/screenshots/devices/contactDel.gif b/screenshots/devices/contactDel.gif index 441c31e5d2879e3443d5214a7e6f6252e87f149b..2cf4f542d97ccb9ef376b32a007c5ae398245821 100644 Binary files a/screenshots/devices/contactDel.gif and b/screenshots/devices/contactDel.gif differ diff --git a/screenshots/devices/contactEdit.en.gif b/screenshots/devices/contactEdit.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..b96365d7b6cde20b9c254b839d5d8ca8b0fc66dd Binary files /dev/null and b/screenshots/devices/contactEdit.en.gif differ diff --git a/screenshots/devices/contactEdit.gif b/screenshots/devices/contactEdit.gif index c36cc37310fdc54a5692e4a186325710c17d949e..d9e6c5ccf43225e207d4c1afb46d44102b768941 100644 Binary files a/screenshots/devices/contactEdit.gif and b/screenshots/devices/contactEdit.gif differ diff --git a/screenshots/devices/contactQuery.en.gif b/screenshots/devices/contactQuery.en.gif new file mode 100644 index 0000000000000000000000000000000000000000..16633cdcd1085cda386c61b0c967d0f728b7ef50 Binary files /dev/null and b/screenshots/devices/contactQuery.en.gif differ diff --git a/screenshots/devices/contactQuery.gif b/screenshots/devices/contactQuery.gif index e54748937a093c5af53e6c2dbad465e6663377b4..50d727ee51f8ee0aeb91678618536a384207a2d5 100644 Binary files a/screenshots/devices/contactQuery.gif and b/screenshots/devices/contactQuery.gif differ