DEV Community: liu yang

Cross-device file copying

liu yang — Sun, 29 Jun 2025 09:31:02 +0000

Development Steps

Completing Distributed Networking

Connect devices that need cross-device access to the same local network and complete networking via the same account authentication.
Authorize Distributed Data Sync Permissions:

   import { common, abilityAccessCtrl } from '@kit.AbilityKit';
   let context = getContext(this) as common.UIAbilityContext;
   let atManager = abilityAccessCtrl.createAtManager();
   try {
     atManager.requestPermissionsFromUser(context, ['ohos.permission.DISTRIBUTED_DATASYNC']).then((data) => {
       console.log(`data: ${JSON.stringify(data)}`);
     }).catch((err: object) => {
       console.log(`err: ${JSON.stringify(err)}`);
     })
   } catch (err) {
     console.log(`catch err-> ${JSON.stringify(err)}`);
   }

Copying Cross-Device Files

Copy Files on Device A:

   import { fileIo as fs } from '@kit.CoreFileKit';
   import { common } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { fileUri } from '@kit.CoreFileKit';

   let context = getContext(this) as common.UIAbilityContext;
   let pathDir: string = context.filesDir;
   let distributedPathDir: string = context.distributedFilesDir;
   let filePath: string = pathDir + '/src.txt';

   try {
     let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
     fs.writeSync(file.fd, 'Create file success');
     fs.closeSync(file);
   } catch (error) {
     console.error(`Failed to createFile. Code: ${error.code}, message: ${error.message}`);
   }

   let srcUri = fileUri.getUriFromPath(filePath);
   let destUri: string = fileUri.getUriFromPath(distributedPathDir + '/src.txt');

   try {
     fs.copy(srcUri, destUri).then(() => {
       console.info(`Succeeded in copying---. `);
       console.info(`src: ${srcUri} dest: ${destUri}`);
     }).catch((error: BusinessError) => {
       let err: BusinessError = error as BusinessError;
       console.info(`Failed to copy. Code: ${err.code}, message: ${err.message}`);
     })
   } catch (error) {
     console.error(`Failed to copy. Code: ${error.code}, message: ${error.message}`);
   }

Copy Files on Device B:

   import { fileIo as fs } from '@kit.CoreFileKit';
   import { common } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { fileUri } from '@kit.CoreFileKit';
   import { distributedDeviceManager } from '@kit.DistributedServiceKit';

   let context = getContext(this) as common.UIAbilityContext;
   let pathDir: string = context.filesDir;
   let distributedPathDir: string = context.distributedFilesDir;
   let destPath: string = pathDir + '/dest.txt';
   let destUri = fileUri.getUriFromPath(destPath);
   let srcPath = distributedPathDir + '/src.txt';
   let srcUri: string = fileUri.getUriFromPath(srcPath);

   let progressListener: fs.ProgressListener = (progress: fs.Progress) => {
     console.info(`progressSize: ${progress.processedSize}, totalSize: ${progress.totalSize}`);
   };
   let options: fs.CopyOptions = {
     "progressListener": progressListener
   };

   let dmInstance = distributedDeviceManager.createDeviceManager("com.example.hap");
   let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();
   if (deviceInfoList && deviceInfoList.length > 0) {
     let networkId = deviceInfoList[0].networkId;
     let listeners: fs.DfsListeners = {
       onStatus: (networkId: string, status: number): void => {
         console.info(`Failed to access public directory`);
       }
     };
     fs.connectDfs(networkId, listeners).then(() => {
       try {
         fs.copy(srcUri, destUri, options).then(() => {
           console.info(`Succeeded in copying from distribted path`);
           console.info(`src: ${srcUri} dest: ${destUri}`);
           fs.unlinkSync(srcPath);
         }).catch((error: BusinessError) => {
           let err: BusinessError = error as BusinessError;
           console.info(`Failed to copy. Code: ${err.code}, message: ${err.message}`);
         });
       } catch (error) {
         console.error(`Failed to copy. Code: ${error.code}, message: ${error.message}`);
       }
     });
   }

Disconnecting the Link on Device B:

   import { distributedDeviceManager } from '@kit.DistributedServiceKit';
   import { fileIo as fs } from '@kit.CoreFileKit';
   import { BusinessError } from '@kit.BasicServicesKit';

   let dmInstance = distributedDeviceManager.createDeviceManager("com.example.hap");
   let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();
   if (deviceInfoList && deviceInfoList.length > 0) {
     let networkId = deviceInfoList[0].networkId;
     fs.disconnectDfs(networkId).then(() => {
       console.info(`Success to disconnectDfs`);
     }).catch((error: BusinessError) => {
       console.error(`Failed to disconnectDfs Code: ${error.code}, message: ${error.message}`);
     });
   }

Cross-device file access

liu yang — Sun, 29 Jun 2025 09:21:04 +0000

Development Steps for Distributed Networking and Cross-Device File Access in HarmonyOS

Completing Distributed Networking

To enable distributed networking and cross-device communication in HarmonyOS, you need to ensure that both devices are logged into the same account and have Bluetooth and Wi-Fi enabled. This setup allows devices to discover and communicate with each other without requiring Bluetooth pairing or connecting to the same Wi-Fi network.

Steps to Enable Distributed Networking

Log in to the Same Account: Ensure both devices are logged into the same HarmonyOS account. This account synchronization is crucial for device discovery and communication.
Enable Bluetooth and Wi-Fi: Both devices must have Bluetooth and Wi-Fi enabled. These technologies facilitate device discovery and data transfer.
No Pairing Required: Unlike traditional Bluetooth communication, HarmonyOS does not require explicit pairing between devices. The distributed networking feature handles device discovery and connection automatically.

Accessing Cross-Device Files

To enable cross-device file access, you need to place the relevant files in the distributed files directory of the app's sandbox. This directory is synchronized across devices running the same app.

Creating a Test File on Device A

The following code demonstrates how to create and write to a test file in the distributed files directory on Device A.

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let context = getContext(this) as common.UIAbilityContext;
let pathDir: string = context.distributedFilesDir;
let filePath: string = pathDir + '/test.txt';

try {
  let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  fs.writeSync(file.fd, 'content');
  fs.closeSync(file.fd);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to openSync / writeSync / closeSync. Code: ${err.code}, message: ${err.message}`);
}

Explanation

fileIo Module: The fileIo module provides file operations such as opening, reading, writing, and closing files.
distributedFilesDir: This property of the UIAbilityContext object provides the path to the distributed files directory.
OpenMode: The OpenMode enum specifies the mode for opening the file (e.g., read/write or create).

Reading the Test File on Device B

The following code demonstrates how to read the test file created on Device A from Device B.

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { buffer } from '@kit.ArkTS';
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

let dmInstance = distributedDeviceManager.createDeviceManager("com.example.hap");
let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();
let networkId = deviceInfoList[0].networkId;

let listeners: fs.DfsListeners = {
  onStatus: (networkId: string, status: number): void => {
    console.info('Failed to access public directory');
  }
};

fs.connectDfs(networkId, listeners).then(() => {
  let context = getContext() as common.UIAbilityContext;
  let pathDir: string = context.distributedFilesDir;
  let filePath: string = pathDir + '/test.txt';

  try {
    let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE);
    let arrayBuffer = new ArrayBuffer(4096);
    class Option {
        public offset: number = 0;
        public length: number = 0;
    }
    let option = new Option();
    option.length = arrayBuffer.byteLength;
    let num = fs.readSync(file.fd, arrayBuffer, option);
    let buf = buffer.from(arrayBuffer, 0, num);
    console.info('read result: ' + buf.toString());
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to openSync / readSync. Code: ${err.code}, message: ${err.message}`);
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to connectDfs Code: ${error.code}, message: ${error.message}`);
});

Explanation

distributedDeviceManager: This module provides methods for managing distributed devices, including getting the list of available devices.
connectDfs: This method connects to the distributed file system of the specified device.
DfsListeners: This interface provides a callback for status updates during the connection process.
Reading the File: After connecting to the distributed file system, the file is opened, read, and its content is logged to the console.

Disconnecting the Link on Device B

To disconnect from the distributed file system, use the disconnectDfs method.

import { distributedDeviceManager } from '@kit.DistributedServiceKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

let dmInstance = distributedDeviceManager.createDeviceManager("com.example.hap");
let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();
let networkId = deviceInfoList[0].networkId;

fs.disconnectDfs(networkId).then(() => {
  console.info("Success to disconnectDfs");
}).catch((error: BusinessError) => {
  console.error(`Failed to disconnectDfs Code: ${error.code}, message: ${err.message}`);
});

Explanation

disconnectDfs: This method disconnects from the distributed file system of the specified device.
Error Handling: The catch block handles any errors that occur during disconnection.

Practical Use Cases

File Synchronization: Use distributed networking to synchronize files across multiple devices, ensuring that users have access to the latest versions of their files.
Multi-Device Applications: Develop applications that leverage the capabilities of multiple devices, such as sharing data between a smartphone and a smartwatch.
Enhanced User Experience: Provide a seamless user experience by allowing users to access and modify files on any device running the same app.

Authorization persistence

liu yang — Sun, 29 Jun 2025 09:18:02 +0000

Managing File Permissions in HarmonyOS: A Comprehensive Guide

Introduction

In HarmonyOS, managing file permissions is crucial for ensuring secure and efficient data access across devices. This guide provides detailed examples and explanations for persisting and revoking file permissions using the fileShare module. By following these steps, you can ensure that your application handles file permissions correctly, enhancing both security and user experience.

Persisting File Permissions

Persisting file permissions allows your application to maintain access to specific files even after the app or device restarts. This is particularly useful for applications that need to access files across multiple sessions.

Example: Persisting File Permissions

import { BusinessError } from '@kit.BasicServicesKit';
import { picker } from '@kit.CoreFileKit';
import { fileShare } from '@kit.CoreFileKit';

async function persistPermissionExample() {
    try {
        let DocumentSelectOptions = new picker.DocumentSelectOptions();
        let documentPicker = new picker.DocumentViewPicker();
        let uris = await documentPicker.select(DocumentSelectOptions);
        let policyInfo: fileShare.PolicyInfo = {
            uri: uris[0],
            operationMode: fileShare.OperationMode.READ_MODE,
        };
        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
        fileShare.persistPermission(policies).then(() => {
            console.info("persistPermission successfully");
        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
            console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code);
            if (err.code == 13900001 && err.data) {
                for (let i = 0; i < err.data.length; i++) {
                    console.error("error code : " + JSON.stringify(err.data[i].code));
                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
                    console.error("error reason : " + JSON.stringify(err.data[i].message));
                }
            }
        });
    } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error('persistPermission failed with err: ' + JSON.stringify(err));
    }
}

Explanation

DocumentSelectOptions and DocumentViewPicker: These classes are used to open a file picker dialog and allow the user to select a file. The selected file's URI is captured and stored in the uris array.
PolicyInfo: This object defines the file access policy, including the URI of the file and the operation mode (e.g., read or write).
persistPermission: This method persists the file permissions, allowing the application to access the file across sessions. The method returns a promise that resolves if the operation is successful or rejects with an error.

Notes

Storing Persisted Authorization File Information: It is recommended to store persisted authorization file information locally for subsequent activation. This ensures that the application can quickly access the necessary files without needing to re-persist permissions.
Activation After Restart: Persisted authorization data is stored in the system database and needs to be activated after app or device restart.
Device Compatibility: The persistPermission interface only takes effect on 2in1 devices and requires permission.
Clearing Authorization Data: Uninstalling the app will clear all authorization data.

Revoking File Permissions

Revoking file permissions is essential for managing access to sensitive files and ensuring that permissions are not misused. This process involves specifying the file URI and the operation mode, similar to persisting permissions.

Example: Revoking File Permissions

import { BusinessError } from '@kit.BasicServicesKit';
import { fileShare } from '@kit.CoreFileKit';

async function revokePermissionExample() {
    try {
        let uri = "file://docs/storage/Users/username/tmp.txt";
        let policyInfo: fileShare.PolicyInfo = {
            uri: uri,
            operationMode: fileShare.OperationMode.READ_MODE,
        };
        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
        fileShare.revokePermission(policies).then(() => {
            console.info("revokePermission successfully");
        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
            console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code);
            if (err.code == 13900001 && err.data) {
                for (let i = 0; i < err.data.length; i++) {
                    console.error("error code : " + JSON.stringify(err.data[i].code));
                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
                    console.error("error reason : " + JSON.stringify(err.data[i].message));
                }
            }
        });
    } catch (error) {
        let err: BusinessError = error as BusinessError;
        console.error('revokePermission failed with err: ' + JSON.stringify(err));
    }
}

Explanation

URI Specification: The URI of the file for which permissions are to be revoked is specified. This URI should match the one used during the persisting process.
PolicyInfo: Similar to persisting permissions, a PolicyInfo object is created to define the file access policy.
revokePermission: This method revokes the specified file permissions. The method returns a promise that resolves if the operation is successful or rejects with an error.

Notes

URI Source: The URI in the example comes from the app's persisted data storage. Ensure that the URI is correctly formatted and accessible.
Activation: Activate persisted permissions as needed. This ensures that the application can access the necessary files without needing to re-persist permissions.
Device Compatibility: The revokePermission interface is only effective on 2in1 devices and requires permission.

Practical Use Cases

Secure File Access

Secure Storage: Use persisted permissions to securely store and access sensitive files across multiple sessions.
User Control: Allow users to control which files are accessible by the application, enhancing privacy and security.

Multi-Device Synchronization

File Synchronization: Ensure that files are synchronized across multiple devices by persisting permissions, allowing seamless access.
Cross-Device Access: Enable cross-device access to files, ensuring that users can access their data from any device running the same application.

Error Handling and Debugging

Error Logging: Implement comprehensive error logging to capture and diagnose issues related to file permissions.
User Feedback: Provide clear feedback to users when permissions are successfully persisted or revoked, enhancing the user experience.

FileUri Development guidance

liu yang — Sun, 29 Jun 2025 09:12:53 +0000

Development Steps for File URI Management in HarmonyOS

Linking Dynamic Library in CMake Script

To manage file URIs in HarmonyOS, you need to link the appropriate dynamic library in your CMakeLists.txt file. This ensures that your application has access to the necessary functions for file URI operations.

target_link_libraries(sample PUBLIC libohfileuri.so)

Explanation

target_link_libraries: This CMake command links the specified libraries to the target. In this case, sample is the target (your application), and libohfileuri.so is the dynamic library that provides file URI management functions.

Including Header File

To use the file URI management functions, you need to include the appropriate header file in your C++ code.

#include <filemanagement/file_uri/oh_file_uri.h>

Explanation

oh_file_uri.h: This header file contains the declarations for the file URI management functions, such as OH_FileUri_GetUriFromPath, OH_FileUri_GetPathFromUri, and others.

Calling OH_FileUri_GetUriFromPath

This function converts a file path to a URI.

#include <cstring>

void OH_FileUri_GetUriFromPathExample() {
    char *path = "/data/storage/el2/base/files/test.txt";
    unsigned int length = strlen(path);
    char *uriResult = NULL;
    FileManagement_ErrCode ret = OH_FileUri_GetUriFromPath(path, length, &uriResult); 
    if (ret == 0 && uriResult != NULL) {
        printf("pathUri=%s", uriResult);
    }
    if (uriResult != NULL) {
        free(uriResult);
    }
}

Explanation

OH_FileUri_GetUriFromPath: This function takes a file path and its length, and converts it to a URI. The resulting URI is stored in uriResult.
FileManagement_ErrCode: This is the error code returned by the function. A return value of 0 indicates success.
Memory Management: The uriResult is dynamically allocated, so it must be freed after use to avoid memory leaks.

Calling OH_FileUri_GetPathFromUri

This function converts a URI back to a file path.

#include <cstring>

void OH_FileUri_GetPathFromUriExample() {
    char *uri = "file://com.example.demo/data/storage/el2/base/files/test.txt";
    unsigned int length = strlen(uri);
    char *pathResult = NULL;
    FileManagement_ErrCode ret = OH_FileUri_GetPathFromUri(uri, length, &pathResult);
    if (ret == 0 && pathResult != NULL) {
        printf("pathResult=%s", pathResult);
    }
    if (pathResult != NULL) {
        free(pathResult);
    }
}

Explanation

OH_FileUri_GetPathFromUri: This function takes a URI and its length, and converts it back to a file path. The resulting path is stored in pathResult.
Memory Management: Similar to the previous example, pathResult must be freed after use.

Calling OH_FileUri_GetFullDirectoryUri

This function retrieves the full directory URI from a given URI.

#include <cstring>

void OH_FileUri_GetFullDirectoryUriExample() {
    char *uri = "file://com.example.demo/data/storage/el2/base/files/test.txt";
    unsigned int length = strlen(uri);
    char *uriResult = NULL;
    FileManagement_ErrCode ret = OH_FileUri_GetFullDirectoryUri(uri, length, &uriResult);
    if (ret == 0 && uriResult != NULL) {
        printf("pathUri=%s", uriResult);
    }
    if (uriResult != NULL) {
        free(uriResult);
    }
}

Explanation

OH_FileUri_GetFullDirectoryUri: This function extracts the full directory URI from the given URI. The resulting URI is stored in uriResult.
Memory Management: The uriResult must be freed after use to avoid memory leaks.

Calling OH_FileUri_IsValidUri

This function checks if a given URI is valid.

#include <cstring>

void OH_FileUri_IsValidUriExample() {
    char *uri = "file://com.example.demo/data/storage/el2/base/files/test.txt";
    unsigned int length = strlen(uri);
    bool flags = OH_FileUri_IsValidUri(uri, length);
    printf("The URI is valid? flags=%d", flags);
}

Explanation

OH_FileUri_IsValidUri: This function checks if the provided URI is valid. It returns true if the URI is valid, otherwise false.

Calling OH_FileUri_GetFileName

This function extracts the file name from a given URI.

#include <cstring>

void OH_FileUri_GetFileNameExample() {
    char *uri = "file://com.example.demo/data/storage/el2/base/files/test.txt";
    unsigned int length = strlen(uri);
    char *uriResult = NULL;
    FileManagement_ErrCode ret = OH_FileUri_GetFileName(uri, length, &uriResult);
    if (ret == 0 && uriResult != NULL) {
        printf("pathUri=%s", uriResult);
    }
    if (uriResult != NULL) {
        free(uriResult);
    }
}

Explanation

OH_FileUri_GetFileName: This function extracts the file name from the given URI. The resulting file name is stored in uriResult.
Memory Management: The uriResult must be freed after use to avoid memory leaks.

Practical Use Cases

Secure File Access

Secure Storage: Use these functions to securely store and access sensitive files by converting paths to URIs and vice versa.
User Control: Allow users to control which files are accessible by the application, enhancing privacy and security.

Multi-Device Synchronization

File Synchronization: Ensure that files are synchronized across multiple devices by converting paths to URIs, allowing seamless access.
Cross-Device Access: Enable cross-device access to files, ensuring that users can access their data from any device running the same application.

Application and file system space statistics

liu yang — Sun, 29 Jun 2025 09:04:41 +0000

API Introduction for File System and Application Space Statistics in HarmonyOS

Detailed API Information

For comprehensive API information, refer to the official HarmonyOS documentation for ohos.file.statvfs and ohos.file.storageStatistics.

File System and Application Space Statistics

Available Modules and Interfaces

Module	Interface Name	Function
`@ohos.file.storageStatistics`	`getCurrentBundleStats`	Gets the storage size of the current app (in bytes).
`@ohos.file.statvfs`	`getFreeSize`	Gets the remaining space of the specified file system (in bytes).
`@ohos.file.statvfs`	`getTotalSize`	Gets the total space of the specified file system (in bytes).

Application Space Statistics

BundleStats Property	Meaning	Statistical Path
`appSize`	Size of the app installation file (in bytes).	App installation files are stored in: `/data/storage/el1/bundle`.
`cacheSize`	Size of the app cache files (in bytes).	App cache files are stored in: `/data/storage/el1/base/cache`, `/data/storage/el1/base/haps/entry/cache`, `/data/storage/el2/base/cache`, `/data/storage/el2/base/haps/entry/cache`.
`dataSize`	Size of app file storage (excluding installation and cache files, in bytes).	App files include local, distributed, and database files. Local files are stored in: `/data/storage/el1/base`, `/data/storage/el2/base`. Distributed files are stored in: `/data/storage/el2/distributedfiles`. Database files are stored in: `/data/storage/el1/database`, `/data/storage/el2/database`.

Development Examples

Getting the Remaining Space of the File System's Data Partition

To get the remaining space of the file system's data partition, you can use the getFreeSize method from the statfs module.

import { statfs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context = getContext(this) as common.UIAbilityContext;
let path = context.filesDir; // Get the path to the app's private directory
statfs.getFreeSize(path, (err: BusinessError, number: number) => {
  if (err) {
    console.error(`Invoke getFreeSize failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info(`Invoke getFreeSize succeeded, size is ${number} bytes`);
  }
});

Explanation

statfs Module: Provides methods for querying file system statistics.
getFreeSize Method: Retrieves the remaining space of the specified file system path.
Error Handling: The callback function handles errors by logging the error code and message.
Success Handling: Logs the remaining space in bytes.

Getting the Storage Space Size of the Current Application

To get the storage space size of the current application, you can use the getCurrentBundleStats method from the storageStatistics module.

import { storageStatistics } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

storageStatistics.getCurrentBundleStats((err: BusinessError, bundleStats: storageStatistics.BundleStats) => {
  if (err) {
    console.error(`Invoke getCurrentBundleStats failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info(`Invoke getCurrentBundleStats succeeded, appSize is ${bundleStats.appSize} bytes`);
    console.info(`Invoke getCurrentBundleStats succeeded, cacheSize is ${bundleStats.cacheSize} bytes`);
    console.info(`Invoke getCurrentBundleStats succeeded, dataSize is ${bundleStats.dataSize} bytes`);
  }
});

Explanation

storageStatistics Module: Provides methods for querying storage statistics related to the current application.
getCurrentBundleStats Method: Retrieves the storage statistics of the current application, including appSize, cacheSize, and dataSize.
Error Handling: The callback function handles errors by logging the error code and message.
Success Handling: Logs the storage sizes in bytes for different categories (appSize, cacheSize, dataSize).

Additional Examples

Getting the Total Space of the File System's Data Partition

To get the total space of the file system's data partition, you can use the getTotalSize method from the statvfs module.

import { statfs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context = getContext(this) as common.UIAbilityContext;
let path = context.filesDir; // Get the path to the app's private directory
statfs.getTotalSize(path, (err: BusinessError, number: number) => {
  if (err) {
    console.error(`Invoke getTotalSize failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info(`Invoke getTotalSize succeeded, size is ${number} bytes`);
  }
});

Explanation

getTotalSize Method: Retrieves the total space of the specified file system path.
Error Handling: The callback function handles errors by logging the error code and message.
Success Handling: Logs the total space in bytes.

Practical Use Cases

Monitoring Application Storage Usage

Usage Monitoring: Regularly monitor the storage usage of your application to ensure it does not exceed allocated limits.
User Notifications: Notify users if the application is approaching its storage limit, prompting them to clear cache or uninstall unnecessary files.

Optimizing Storage Management

Cache Management: Use the cacheSize property to manage the cache size effectively, clearing unnecessary cache files to free up space.
Data Management: Use the dataSize property to manage application data, ensuring efficient storage and retrieval of user data.

Error Handling and Debugging

Comprehensive Logging: Implement comprehensive logging to capture and diagnose issues related to storage statistics.
User Feedback: Provide clear feedback to users when operations are successful or fail, enhancing the user experience.

Application File Access (ArkTS)

liu yang — Sun, 29 Jun 2025 08:54:30 +0000

File Operations in ArkUI

Creating and Reading/Writing a File

// pages/xxx.ets
import { fileIo as fs, ReadOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { buffer } from '@kit.ArkTS';

// Get the application file path
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;

function createFile(): void {
  // Create and open the file if it does not exist; open the file if it exists
  let file = fs.openSync(filesDir + '/test.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  // Write content to the file
  let writeLen = fs.writeSync(file.fd, "Try to write str.");
  console.info("The length of str is: " + writeLen);
  // Create an ArrayBuffer object with a size of 1024 bytes to store data read from the file
  let arrayBuffer = new ArrayBuffer(1024);
  // Set the offset and length for reading
  let readOptions: ReadOptions = {
    offset: 0,
    length: arrayBuffer.byteLength
  };
  // Read the file content into the ArrayBuffer object and return the actual number of bytes read
  let readLen = fs.readSync(file.fd, arrayBuffer, readOptions);
  // Convert the ArrayBuffer object to a Buffer object and output as a string
  let buf = buffer.from(arrayBuffer, 0, readLen);
  console.info("the content of file: " + buf.toString());
  // Close the file
  fs.closeSync(file);
}

Reading from One File and Writing to Another

// pages/xxx.ets
import { fileIo as fs, ReadOptions, WriteOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

// Get the application file path
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;

function readWriteFile(): void {
  // Open the source and destination files
  let srcFile = fs.openSync(filesDir + '/test.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  let destFile = fs.openSync(filesDir + '/destFile.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  // Read content from the source file and write it to the destination file
  let bufSize = 4096;
  let readSize = 0;
  let buf = new ArrayBuffer(bufSize);
  let readOptions: ReadOptions = {
    offset: readSize,
    length: bufSize
  };
  let readLen = fs.readSync(srcFile.fd, buf, readOptions);
  while (readLen > 0) {
    readSize += readLen;
    let writeOptions: WriteOptions = {
      length: readLen
    };
    fs.writeSync(destFile.fd, buf, writeOptions);
    readOptions.offset = readSize;
    readLen = fs.readSync(srcFile.fd, buf, readOptions);
  }
  // Close the files
  fs.closeSync(srcFile);
  fs.closeSync(destFile);
}

Reading/Writing Files Using Streams

// pages/xxx.ets
import { fileIo as fs, ReadOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

// Get the application file path
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;

async function readWriteFileWithStream(): Promise<void> {
  // Create and open the input file stream
  let inputStream = fs.createStreamSync(filesDir + '/test.txt', 'r+');
  // Create and open the output file stream
  let outputStream = fs.createStreamSync(filesDir + '/destFile.txt', "w+");

  let bufSize = 4096;
  let readSize = 0;
  let buf = new ArrayBuffer(bufSize);
  let readOptions: ReadOptions = {
    offset: readSize,
    length: bufSize
  };
  // Read content from the source file and write it to the destination file using streams
  let readLen = await inputStream.read(buf, readOptions);
  readSize += readLen;
  while (readLen > 0) {
    const writeBuf = readLen < bufSize ? buf.slice(0, readLen) : buf;
    await outputStream.write(writeBuf);
    readOptions.offset = readSize;
    readLen = await inputStream.read(buf, readOptions);
    readSize += readLen;
  }
  // Close the file streams
  inputStream.closeSync();
  outputStream.closeSync();
}

Listing Files

import { fileIo as fs, Filter, ListFileOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

// Get the application file path
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;

// List files
function getListFile(): void {
  let listFileOption: ListFileOptions = {
    recursion: false,
    listNum: 0,
    filter: {
      suffix: [".png", ".jpg", ".txt"],
      displayName: ["test*"],
      fileSizeOver: 0,
      lastModifiedAfter: new Date(0).getTime()
    }
  };
  let files = fs.listFileSync(filesDir, listFileOption);
  for (let i = 0; i < files.length; i++) {
    console.info(`The name of file: ${files[i]}`);
  }
}

Binding gesture method

liu yang — Fri, 27 Jun 2025 15:12:09 +0000

Gesture Binding Methods in ArkUI

Gesture Binding Methods

gesture (General Gesture Binding Method)

.gesture(gesture: GestureType, mask?: GestureMask)

Description: The gesture method is a general way to bind gestures to components.
Example: Binding a TapGesture to a Text component using the gesture method.

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Gesture').fontSize(28)
        // Binding TapGesture to Text component using gesture method
        .gesture(
          TapGesture()
            .onAction(() => {
              console.info('TapGesture is onAction');
            }))
    }
    .height(200)
    .width(250)
  }
}

priorityGesture (Priority Gesture Binding Method)

.priorityGesture(gesture: GestureType, mask?: GestureMask)

Description: The priorityGesture method binds gestures with priority to components.
Behavior: By default, when both parent and child components bind the same type of gesture using gesture, the child component's gesture takes precedence. When the parent component binds the same type of gesture using priorityGesture, the parent component's gesture takes precedence.
Long Press Gesture: The component with the shorter minimum duration for long press will take precedence, ignoring priorityGesture settings.
Example: When both Column and Text components bind TapGesture, the parent Column component's TapGesture takes precedence when bound with priorityGesture.

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Gesture').fontSize(28)
        .gesture(
          TapGesture()
            .onAction(() => {
              console.info('Text TapGesture is onAction');
            }))
    }
    .height(200)
    .width(250)
    // Setting to priorityGesture, clicking on the text area will ignore the TapGesture event of the Text component and prioritize the TapGesture event of the parent Column component
    .priorityGesture(
      TapGesture()
        .onAction(() => {
          console.info('Column TapGesture is onAction');
        }), GestureMask.IgnoreInternal)
  }
}

parallelGesture (Parallel Gesture Binding Method)

.parallelGesture(gesture: GestureType, mask?: GestureMask)

Description: The parallelGesture method allows binding gestures that can be simultaneously recognized by both parent and child components.
Behavior: By default, gesture events are non-bubbling. When both parent and child components bind the same gesture, they compete for recognition, and at most, only one component's gesture event can be triggered. When the parent component binds a gesture using parallelGesture, both parent and child components' gesture events can be triggered, achieving a similar effect to bubbling.
Example: Both Column and Text components' TapGesture events are triggered when clicking on the text area.

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Gesture').fontSize(28)
        .gesture(
          TapGesture()
            .onAction(() => {
              console.info('Text TapGesture is onAction');
            }))
    }
    .height(200)
    .width(250)
    // Setting to parallelGesture, clicking on the text area will trigger both the parent Column and child Text components' TapGesture events
    .parallelGesture(
      TapGesture()
        .onAction(() => {
          console.info('Column TapGesture is onAction');
        }), GestureMask.Normal)
  }
}

Dragging event

liu yang — Fri, 27 Jun 2025 14:59:59 +0000

Universal Drag and Drop Adaptation

Basic Steps and Considerations for Component Drag and Drop Development

Enabling Component Drag and Drop

Set draggable Property: Set the draggable property to true and configure the onDragStart callback function. In the callback, you can use the Unified Data Management Framework (UDMF) to set the drag data and return a custom drag background image.

import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData';

Image($r('app.media.app_icon'))
    .width(100)
    .height(100)
    .draggable(true)
    .onDragStart((event) => {
        let data: unifiedDataChannel.Image = new unifiedDataChannel.Image();
        data.imageUri = 'common/pic/img.png';
        let unifiedData = new unifiedDataChannel.UnifiedData(data);
        event.setData(unifiedData);

        let dragItemInfo: DragItemInfo = {
            pixelMap: this.pixmap,
            extraInfo: "this is extraInfo",
        };
        // Return custom drag background image in onDragStart callback
        return dragItemInfo;
    })

Handling Long Press Gesture Conflicts

If you bind a long press gesture to a draggable component, it may conflict with the underlying long press gesture, causing the drag operation to fail. To resolve this, you can use parallel gestures.

.parallelGesture(LongPressGesture().onAction(() => {
    promptAction.showToast({ duration: 100, message: 'Long press gesture trigger' });
}))

Customizing Drag Background Image

You can prepare a custom drag background image by setting the onPreDrag callback function, which is triggered 50ms after a long press.

.onPreDrag((status: PreDragStatus) => {
    if (status == PreDragStatus.ACTION_DETECTING_STATUS) {
        this.getComponentSnapshot();
    }
})

The pixmap can be generated using the componentSnapshot.createFromBuilder function.

@Builder
pixelMapBuilder() {
    Column() {
        Image($r('app.media.startIcon'))
            .width(120)
            .height(120)
            .backgroundColor(Color.Yellow)
    }
}

private getComponentSnapshot(): void {
    this.getUIContext().getComponentSnapshot().createFromBuilder(() => { this.pixelMapBuilder() },
    (error: Error, pixmap: image.PixelMap) => {
        if (error) {
            console.log("error: " + JSON.stringify(error));
            return;
        }
        this.pixmap = pixmap;
    })
}

Ensuring onDragLeave Event

To ensure the onDragLeave event is triggered, you need to set setDragEventStrictReportingEnabled.

import { UIAbility } from '@kit.AbilityKit';
import { window, UIContext } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage): void {
        windowStage.loadContent('pages/Index', (err, data) => {
            if (err.code) {
                return;
            }
            windowStage.getMainWindow((err, data) => {
                if (err.code) {
                    return;
                }
                let windowClass: window.Window = data;
                let uiContext: UIContext = windowClass.getUIContext();
                uiContext.getDragController().setDragEventStrictReportingEnabled(true);
            });
        });
    }
}

Drag and Drop Process with Badge Style

Define the accepted data types using allowDrop, which affects the badge display. When the dragged data matches the allowed types, a "COPY" badge is shown. If the data type is not allowed, a "FORBIDDEN" badge is shown. If allowDrop is not set, a "MOVE" badge is shown.

.allowDrop([uniformTypeDescriptor.UniformDataType.HYPERLINK, uniformTypeDescriptor.UniformDataType.PLAIN_TEXT])

In the onDragMove callback, you can set DragResult to DROP_ENABLED and DragBehavior to COPY or MOVE to control the badge display.

.onDragMove((event) => {
    event.setResult(DragResult.DROP_ENABLED);
    event.dragBehavior = DragBehavior.MOVE;
})

Receiving Dragged Data

Set the onDrop callback function to handle the dragged data and set the drag result.

.onDrop((dragEvent?: DragEvent) => {
    // Get dragged data
    this.getDataFromUdmf((dragEvent as DragEvent), (event: DragEvent) => {
        let records: Array<unifiedDataChannel.UnifiedRecord> = event.getData().getRecords();
        let rect: Rectangle = event.getPreviewRect();
        this.imageWidth = Number(rect.width);
        this.imageHeight = Number(rect.height);
        this.targetImage = (records[0] as unifiedDataChannel.Image).imageUri;
        this.imgState = Visibility.None;
        // Explicitly set result to successful, which will be passed to the onDragEnd of the drag source
        event.setResult(DragResult.DRAG_SUCCESSFUL);
    })
})

Focus event

liu yang — Fri, 27 Jun 2025 14:56:48 +0000

Focus and Blur Events in ArkUI

Focus and Blur Event Callbacks

onFocus(event: () => void)

Description: The callback function for the focus event. It is triggered when the component that binds this interface gains focus.

onBlur(event: () => void)

Description: The callback function for the blur event. It is triggered when the component that binds this interface loses focus.

The onFocus and onBlur interfaces are typically used in pairs to monitor focus changes of components.

Example: Focus Event Handling

@Entry
@Component
struct FocusEventExample {
  @State oneButtonColor: Color = Color.Gray;
  @State twoButtonColor: Color = Color.Gray;
  @State threeButtonColor: Color = Color.Gray;

  build() {
    Column({ space: 20 }) {
      // Use the up and down keys on an external keyboard to move focus between the three buttons.
      // The button changes color when it gains focus and reverts to the original background color when it loses focus.
      Button('First Button')
        .width(260)
        .height(70)
        .backgroundColor(this.oneButtonColor)
        .fontColor(Color.Black)
        // Listen for the focus event of the first component and change the color when it gains focus.
        .onFocus(() => {
          this.oneButtonColor = Color.Green;
        })
        // Listen for the blur event of the first component and change the color when it loses focus.
        .onBlur(() => {
          this.oneButtonColor = Color.Gray;
        })

      Button('Second Button')
        .width(260)
        .height(70)
        .backgroundColor(this.twoButtonColor)
        .fontColor(Color.Black)
        // Listen for the focus event of the second component and change the color when it gains focus.
        .onFocus(() => {
          this.twoButtonColor = Color.Green;
        })
        // Listen for the blur event of the second component and change the color when it loses focus.
        .onBlur(() => {
          this.twoButtonColor = Color.Gray;
        })

      Button('Third Button')
        .width(260)
        .height(70)
        .backgroundColor(this.threeButtonColor)
        .fontColor(Color.Black)
        // Listen for the focus event of the third component and change the color when it gains focus.
        .onFocus(() => {
          this.threeButtonColor = Color.Green;
        })
        // Listen for the blur event of the third component and change the color when it loses focus.
        .onBlur(() => {
          this.threeButtonColor = Color.Gray;
        })
    }.width('100%').margin({ top: 20 })
  }
}

Explanation

Application Launch: Press the TAB key to activate focus. "First Button" displays the focused state style: a blue closed frame around the component, the onFocus callback is triggered, and the background color changes to green.
Press TAB Key: Focus is moved to "Second Button", the onFocus callback is triggered, and the background color changes to green; "First Button" loses focus, the onBlur callback is triggered, and the background color reverts to gray.
Press TAB Key: Focus is moved to "Third Button", the onFocus callback is triggered, and the background color changes to green; "Second Button" loses focus, the onBlur callback is triggered, and the background color reverts to gray.

Setting Component Focusability

focusable(value: boolean)

Description: Sets whether a component can gain focus.

Components can be categorized based on their focusability into three types:

Default Focusable Components: These are typically interactive components, such as Button, Checkbox, and TextInput. These components can gain focus by default without setting any properties.
Focusable but Default Non-Focusable Components: Typical examples include Text and Image components. These components cannot gain focus by default. To enable them to gain focus, use the general property focusable(true). For components that have focusability but are default non-focusable and do not have the focusable property configured, configuring an onClick event or a single-finger tap gesture will implicitly make the component focusable. If the focusable property is set to false, the component remains non-focusable even if the above events are configured.
Non-Focusable Components: These are typically display components with no interactive behavior, such as Blank and Circle. These components cannot gain focus even if the focusable property is used.

enabled(value: boolean)

Description: Sets the component's interactivity. If enabled is set to false, the component is non-interactive and cannot gain focus.

visibility(value: Visibility)

Description: Sets the component's visibility. If visibility is set to Visibility.None or Visibility.Hidden, the component is invisible and cannot gain focus.

focusOnTouch(value: boolean)

Description: Sets whether the component supports gaining focus on touch.

Notes

When a component is in a focused state, setting its focusable or enabled property to false will automatically cause the component to lose focus. The focus will then be transferred to another component according to the focus movement rules.

Example: Focusable and Enabled Properties

@Entry
@Component
struct FocusableExample {
  @State textFocusable: boolean = true;
  @State textEnabled: boolean = true;
  @State color1: Color = Color.Yellow;
  @State color2: Color = Color.Yellow;
  @State color3: Color = Color.Yellow;

  build() {
    Column({ space: 5 }) {
      Text('Default Text')    // The first Text component does not set the focusable property and is non-focusable by default
        .borderColor(this.color1)
        .borderWidth(2)
        .width(300)
        .height(70)
        .onFocus(() => {
          this.color1 = Color.Blue;
        })
        .onBlur(() => {
          this.color1 = Color.Yellow;
        })
      Divider()

      Text('focusable: ' + this.textFocusable)    // The second Text sets focusable to true initially and focusableOnTouch to true
        .borderColor(this.color2)
        .borderWidth(2)
        .width(300)
        .height(70)
        .focusable(this.textFocusable)
        .focusOnTouch(true)
        .onFocus(() => {
          this.color2 = Color.Blue;
        })
        .onBlur(() => {
          this.color2 = Color.Yellow;
        })

      Text('enabled: ' + this.textEnabled)    // The third Text sets focusable to true and enabled to true initially
        .borderColor(this.color3)
        .borderWidth(2)
        .width(300)
        .height(70)
        .focusable(true)
        .enabled(this.textEnabled)
        .focusOnTouch(true)
        .onFocus(() => {
          this.color3 = Color.Blue;
        })
        .onBlur(() => {
          this.color3 = Color.Yellow;
        })

      Divider()

      Row() {
        Button('Button1')
          .width(140).height(70)
        Button('Button2')
          .width(160).height(70)
      }

      Divider()
      Button('Button3')
        .width(300).height(70)

      Divider()
    }.width('100%').justifyContent(FlexAlign.Center)
    .onKeyEvent((e) => {
      // Bind onKeyEvent to toggle the focusable property of the second Text when the 'F' key is pressed
      if (e.keyCode === 2022 && e.type === KeyType.Down) {
        this.textFocusable = !this.textFocusable;
      }
      // Bind onKeyEvent to toggle the enabled property of the third Text when the 'G' key is pressed
      if (e.keyCode === 2023 && e.type === KeyType.Down) {
        this.textEnabled = !this.textEnabled;
      }
    })
  }
}

Keyboard and mouse event

liu yang — Fri, 27 Jun 2025 14:53:52 +0000

Mouse and Key Events in ArkUI

Mouse Events

Supported mouse events include those triggered by an external mouse or touchpad.

Mouse Event Callbacks

Name	Description
onHover(event: (isHover: boolean) => void)	Triggered when the mouse enters or exits a component. `isHover`: Indicates whether the mouse is hovering over the component, `true` when entering, `false` when exiting.
onMouse(event: (event?: MouseEvent) => void)	Triggered when the component is clicked by a mouse button or when the mouse hovers and moves over the component. The `event` return value includes the timestamp, mouse button, action, screen coordinates, and component-relative coordinates at the time of the event.

When a component binds the onHover callback, you can set the hover effect of the component using the hoverEffect property.

Mouse Event Data Flow

After mouse events are passed to ArkUI, they are first checked to see if they are left-click down/up/move events. Different responses are made accordingly:

Yes: The mouse event is first converted into a touch event at the same position, and the touch event's collision test, gesture judgment, and callback response are executed. Then, the mouse event's collision test and callback response are executed.
No: The event is only used to perform the mouse event's collision test and callback response.

Notes

All single-finger touch events/gesture events can be operated and responded to using the mouse left button. For example, to develop a function that jumps to a page when clicking a Button and supports both finger clicks and mouse left-button clicks, binding a single click event (onClick) is sufficient. If you need to implement different effects for finger and mouse left-button clicks, you can use the source field in the callback parameters to determine whether the event source is a finger or a mouse.
The onHover callback is triggered when the mouse pointer enters or leaves the component. This event does not support custom bubble settings and defaults to parent-child bubbling.

Example: Using onHover

@Entry
@Component
struct MouseExample {
  @State hoverText: string = 'Not Hover';
  @State Color: Color = Color.Gray;

  build() {
    Column() {
      Button(this.hoverText)
        .width(200).height(100)
        .backgroundColor(this.Color)
        .onHover((isHover?: boolean) => { // Use onHover to listen for mouse hover on the Button component
          if (isHover) {
            this.hoverText = 'Hovered!';
            this.Color = Color.Green;
          }
          else {
            this.hoverText = 'Not Hover';
            this.Color = Color.Gray;
          }
        })
    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
  }
}

Explanation

Button Component: The button's onHover event changes the button's text and background color when the mouse hovers over or leaves the button.
State Variables: hoverText and Color store the current hover state and button color.

Key Events

Example: Using onKeyEvent

@Entry
@Component
struct KeyEventExample {
  @State buttonText: string = '';
  @State buttonType: string = '';
  @State columnText: string = '';
  @State columnType: string = '';


  build() {
    Column() {
      Button('onKeyEvent')
        .defaultFocus(true)
        .width(140).height(70)
        .onKeyEvent((event?: KeyEvent) => { // Set onKeyEvent for Button
          if(event){
            if (event.type === KeyType.Down) {
              this.buttonType = 'Down';
            }
            if (event.type === KeyType.Up) {
              this.buttonType = 'Up';
            }
            this.buttonText = 'Button: \n' +
            'KeyType:' + this.buttonType + '\n' +
            'KeyCode:' + event.keyCode + '\n' +
            'KeyText:' + event.keyText;
          }
        })


      Divider()
      Text(this.buttonText).fontColor(Color.Green)


      Divider()
      Text(this.columnText).fontColor(Color.Red)
    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
    .onKeyEvent((event?: KeyEvent) => { // Set onKeyEvent for the parent Column component
      if(event){
        if (event.type === KeyType.Down) {
          this.columnType = 'Down';
        }
        if (event.type === KeyType.Up) {
          this.columnType = 'Up';
        }
        this.columnText = 'Column: \n' +
        'KeyType:' + this.buttonType + '\n' +
        'KeyCode:' + event.keyCode + '\n' +
        'KeyText:' + event.keyText;
      }
    })
  }
}

Touchscreen event

liu yang — Fri, 27 Jun 2025 14:51:29 +0000

Click and Touch Events in ArkUI

Click Events

Click events are fundamental interactions in any user interface, triggered by a complete press and release action using a finger or stylus. These events are essential for user interactions, such as button presses or link clicks. In ArkUI, click events are handled using the onClick callback function, which provides detailed information about the event.

Example: Controlling Image Visibility with a Button Click

@Entry
@Component
struct IfElseTransition {
  @State flag: boolean = true;
  @State btnMsg: string = 'show';

  build() {
    Column() {
      Button(this.btnMsg).width(80).height(30).margin(30)
        .onClick(() => {
          if (this.flag) {
            this.btnMsg = 'hide';
          } else {
            this.btnMsg = 'show';
          }
          // Toggle the visibility of the Image component
          this.flag = !this.flag;
        })
      if (this.flag) {
        Image($r('app.media.icon')).width(200).height(200)
      }
    }.height('100%').width('100%')
  }
}

Explanation

Button Component: The button's onClick event toggles the visibility of an image.
State Variables: flag controls the visibility of the image, and btnMsg updates the button's text to reflect the current state.
Image Component: The image is conditionally rendered based on the flag state.

Detailed Breakdown

State Management: The @State decorator is used to manage the state of the component. In this case, flag and btnMsg are used to control the visibility of the image and the text of the button, respectively.
Conditional Rendering: The if (this.flag) statement conditionally renders the Image component based on the value of flag.
Event Handling: The onClick method is used to handle the click event. When the button is clicked, the flag state is toggled, and the button text is updated accordingly.

Touch Events

Touch events are more granular interactions that occur when a finger or stylus interacts with a component. These events include Down, Move, Up, and Cancel, providing detailed information about the touch interaction.

Example: Handling Touch Events

@Entry
@Component
struct TouchExample {
  @State text: string = '';
  @State eventType: string = '';

  build() {
    Column() {
      Button('Touch').height(40).width(100)
        .onTouch((event?: TouchEvent) => {
          if (event) {
            switch (event.type) {
              case TouchType.Down:
                this.eventType = 'Down';
                break;
              case TouchType.Up:
                this.eventType = 'Up';
                break;
              case TouchType.Move:
                this.eventType = 'Move';
                break;
              case TouchType.Cancel:
                this.eventType = 'Cancel';
                break;
            }
            this.text = `TouchType: ${this.eventType}\nDistance between touch point and touch element:\nx: ${event.touches[0].x}\ny: ${event.touches[0].y}\nComponent globalPos: (${event.target.area.globalPosition.x}, ${event.target.area.globalPosition.y})\nwidth: ${event.target.area.width}\nheight: ${event.target.area.height}`;
          }
        })
      Button('Touch').height(50).width(200).margin(20)
        .onTouch((event?: TouchEvent) => {
          if (event) {
            switch (event.type) {
              case TouchType.Down:
                this.eventType = 'Down';
                break;
              case TouchType.Up:
                this.eventType = 'Up';
                break;
              case TouchType.Move:
                this.eventType = 'Move';
                break;
              case TouchType.Cancel:
                this.eventType = 'Cancel';
                break;
            }
            this.text = `TouchType: ${this.eventType}\nDistance between touch point and touch element:\nx: ${event.touches[0].x}\ny: ${event.touches[0].y}\nComponent globalPos: (${event.target.area.globalPosition.x}, ${event.target.area.globalPosition.y})\nwidth: ${event.target.area.width}\nheight: ${event.target.area.height}`;
          }
        })
      Text(this.text)
    }.width('100%').padding(30)
  }
}

Explanation

Touch Event Handling: The onTouch method is used to handle touch events. It provides detailed information about the touch interaction, including the type of touch event and the coordinates of the touch.
State Variables: text and eventType are used to store and display information about the touch event.
Conditional Logic: The switch statement is used to handle different types of touch events (Down, Up, Move, Cancel).

Detailed Breakdown

Event Types: The TouchEvent object provides the type property, which indicates the type of touch event (Down, Up, Move, Cancel).
Touch Coordinates: The touches array provides the coordinates of the touch event relative to the component. event.touches[0].x and event.touches[0].y give the x and y coordinates of the touch point.
Component Position: The event.target.area.globalPosition object provides the global position of the component, while event.target.area.width and event.target.area.height provide the width and height of the component.

Practical Use Cases

Interactive UI Elements: Use touch events to create interactive UI elements, such as draggable components or resizable windows.
Gesture Recognition: Combine touch events to recognize complex gestures, such as swipes, pinches, and rotations.
Game Development: Implement touch controls for games, such as touch-based movement or interaction with game objects.

Traditional curve

liu yang — Thu, 26 Jun 2025 15:40:46 +0000

Traditional Curve Examples and Effects

Code Explanation and Example

The following code demonstrates how to create a visual representation of different animation curves using ArkUI. Each curve is represented by a rotating ball that follows a specific curve pattern.

Curve Class Definition

class MyCurve {
  public title: string;
  public curve: Curve;
  public color: Color | string;

  constructor(title: string, curve: Curve, color: Color | string = '') {
    this.title = title;
    this.curve = curve;
    this.color = color;
  }
}

Curve Instances

const myCurves: MyCurve[] = [
  new MyCurve('Linear', Curve.Linear, '#317AF7'),
  new MyCurve('Ease', Curve.Ease, '#D94838'),
  new MyCurve('EaseIn', Curve.EaseIn, '#DB6B42'),
  new MyCurve('EaseOut', Curve.EaseOut, '#5BA854'),
  new MyCurve('EaseInOut', Curve.EaseInOut, '#317AF7'),
  new MyCurve('FastOutSlowIn', Curve.FastOutSlowIn, '#D94838')
];

CurveDemo Component

@Entry
@Component
export struct CurveDemo {
  @State dRotate: number = 0; // Rotation angle

  build() {
    Column() {
      // Curve legend
      Grid() {
        ForEach(myCurves, (item: MyCurve) => {
          GridItem() {
            Column() {
              Row()
                .width(30)
                .height(30)
                .borderRadius(15)
                .backgroundColor(item.color)
              Text(item.title)
                .fontSize(15)
                .fontColor(0x909399)
            }
            .width('100%')
          }
        })
      }
      .columnsTemplate('1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr 1fr 1fr 1fr')
      .padding(10)
      .width('100%')
      .height(300)
      .margin({ top: 50 })

      Stack() {
        // Swinging pipe
        Row()
          .width(290)
          .height(290)
          .border({
            width: 15,
            color: 0xE6E8EB,
            radius: 145
          })

        ForEach(myCurves, (item: MyCurve) => {
          // Ball
          Column() {
            Row()
              .width(30)
              .height(30)
              .borderRadius(15)
              .backgroundColor(item.color)
          }
          .width(20)
          .height(300)
          .rotate({ angle: this.dRotate })
          .animation({
            duration: 2000,
            iterations: -1,
            curve: item.curve,
            delay: 100
          })
        })
      }
      .width('100%')
      .height(200)
      .onClick(() => {
        this.dRotate ? null : this.dRotate = 360;
      })
    }
    .width('100%')
  }
}

Explanation

MyCurve Class: This class encapsulates the title, curve type, and color for each curve.
myCurves Array: An array of MyCurve instances, each representing a different animation curve with a unique color.
CurveDemo Component: This component visualizes the curves by rotating balls along a circular path. Each ball follows a different curve pattern.
- Grid: Displays a legend for each curve, showing the curve name and color.
- Stack: Contains a rotating pipe and balls that demonstrate the different curves.
- ForEach: Iterates over the myCurves array to create a ball for each curve, applying the respective curve to the rotation animation.
- onClick: Starts the rotation animation when the component is clicked.