Forem: zhonghua

HarmonyOS Sports Project Development: Project Runtime Environment Switcher

zhonghua — Sun, 22 Jun 2025 02:17:18 +0000

Core Technologies of HarmonyOS ## Sports Development

When developing HarmonyOS sports projects, managing different runtime environments (such as development, testing, and production environments) is a common requirement. By properly switching runtime environments, developers can conveniently debug, test, and deploy their applications. This article will introduce how to implement a project runtime environment switcher to help you efficiently manage configurations for different environments in HarmonyOS development.

Preface

In modern software development, environment management is one of the key factors in ensuring the stability and maintainability of applications. Whether it is the development, testing, or production environment, each environment may have different configuration requirements, such as API addresses, log levels, and feature toggles. By implementing a runtime environment switcher, we can easily switch between different environments without modifying the code, thereby improving development efficiency and flexibility.

I. Design of the Environment Switcher

(I) Environment Configuration Types

To support configurations for different environments, we have defined the EnvironmentConfigs and CurrentEnvironment types.

export type EnvironmentConfigs = Map<string, Map<string, string>>;

export interface CurrentEnvironment {
  name: string;
  configs: Map<string, string>;
}

Core Points Analysis:

EnvironmentConfigs: A mapping table where the key is the environment name (e.g., production, development), and the value is the configuration mapping table for that environment.
CurrentEnvironment: Represents the name and configurations of the current environment.

(II) Environment Type Enum

We have defined the supported environment types through an enumeration.

export enum EnvironmentType {
  TYPE_PRODUCTION = "production",
  TYPE_DEVELOP = "develop"
}

Core Points Analysis:

Enum Type: Two environment types are defined through the enumeration: production environment (production) and development environment (develop). More environment types can be added as needed.

(III) Environment Management Class

The Environment class, which is the core of the entire environment switcher, is responsible for storing environment configurations, loading the saved environment, switching environments, and notifying callbacks.

export class Environment {
  private static instance: Environment;
  private static readonly ENVIRONMENT_STORAGE_KEY = 'current_environment';

  private currentEnvironment?: CurrentEnvironment;
  private environments: EnvironmentConfigs = new Map();
  private preferences: LibPreferencesSync;
  private environmentChangeCallbacks: Array<(newEnvironment: CurrentEnvironment) => void> = [];

  private constructor() {
    this.preferences = new LibPreferencesSync();
  }

  public static getInstance(): Environment {
    if (!Environment.instance) {
      Environment.instance = new Environment();
    }
    return Environment.instance;
  }

  public initEnvironments(evn: EnvironmentConfigs) {
    this.environments = evn;
    this.loadSavedEnvironment();
  }

  private loadSavedEnvironment() {
    if (!IS_PRODUCTION) {
      const savedEnvironmentName = this.preferences.getValue(Environment.ENVIRONMENT_STORAGE_KEY) as string;
      if (savedEnvironmentName && this.environments.has(savedEnvironmentName)) {
        this.currentEnvironment = {
          name: savedEnvironmentName,
          configs: this.environments.get(savedEnvironmentName)!
        };
      } else {
        this.currentEnvironment = {
          name: EnvironmentType.TYPE_DEVELOP,
          configs: this.environments.get(EnvironmentType.TYPE_DEVELOP)!
        };
      }
    } else {
      this.currentEnvironment = {
        name: EnvironmentType.TYPE_PRODUCTION,
        configs: this.environments.get(EnvironmentType.TYPE_PRODUCTION)!
      };
    }
  }

  public switchEnvironment(name: string) {
    const configs = this.environments.get(name);
    if (configs) {
      this.currentEnvironment = { name, configs };
      this.preferences.saveKeyValue(Environment.ENVIRONMENT_STORAGE_KEY, name);
      this.environmentChangeCallbacks.forEach(callback => callback(this.currentEnvironment!));
    }
  }

  public getCurrentEnvironment(): CurrentEnvironment {
    return this.currentEnvironment!;
  }

  public getAllEnvironmentNames(): string[] {
    return Array.from(this.environments.keys());
  }

  public registerEnvironmentChangeCallback(callback: (newEnvironment: CurrentEnvironment) => void) {
    this.environmentChangeCallbacks.push(callback);
  }

  public unregisterEnvironmentChangeCallback(callback: (newEnvironment: CurrentEnvironment) => void) {
    this.environmentChangeCallbacks = this.environmentChangeCallbacks.filter(cb => cb !== callback);
  }
}

Core Points Analysis:

Singleton Pattern: The getInstance method ensures the global uniqueness of the Environment instance.
Environment Initialization: The initEnvironments method initializes the environment configurations.
Loading Saved Environment: In the loadSavedEnvironment method, the corresponding environment configuration is loaded based on the stored environment name.
Environment Switching: The switchEnvironment method switches the environment and notifies all registered callback functions.
Callback Mechanism: Supports registering and unregistering environment change callbacks to facilitate operations when the environment is switched.

II. Using the Environment Switcher

(I) Environment Switch Dialog

To facilitate environment switching for users, we have implemented an environment switch dialog called EnvironmentDialog.

@CustomDialog
export struct EnvironmentDialog {
  public controller: CustomDialogController;
  private themeManager: ThemeManager = ThemeManager.getInstance();
  private environment: Environment = Environment.getInstance();
  public onEnvironmentChanged?: () => void;

  build() {
    Column() {
      Text('Select Environment')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .fontColor(this.themeManager.getTextPrimaryColor())
        .margin({ top: 24, bottom: 16 })

      List() {
        ForEach(this.environment.getAllEnvironmentNames(), (envname: string) => {
          ListItem() {
            Row() {
              Column() {
                Text(envname)
                  .fontSize(16)
                  .fontColor(this.themeManager.getTextPrimaryColor())
                  .margin({ bottom: 4 })
              }
              .alignItems(HorizontalAlign.Start)
              .layoutWeight(1)

              if (this.environment.getCurrentEnvironment().name === envname) {
                Image($r('app.media.base_icon_select'))
                  .width(24)
                  .height(24)
                  .margin({ left: 8 })
              }
            }
            .width('100%')
            .padding(16)
            .backgroundColor(this.themeManager.getSurfaceColor())
            .borderRadius(8)
            .onClick(() => {
              this.environment.switchEnvironment(envname);
              this.onEnvironmentChanged?.();
              this.controller.close();
            })
          }
          .margin({ bottom: 8 })
        }, (envname: string) => envname)
      }
      .width('100%')
      .layoutWeight(1)

      Button('Close')
        .width('100%')
        .height(48)
        .backgroundColor(this.themeManager.getPrimaryColor())
        .margin({ top: 16 })
        .onClick(() => {
          this.controller.close();
        })
    }
    .width('90%')
    .padding(16)
    .backgroundColor(this.themeManager.getBackgroundColor())
    .borderRadius(16)
  }
}

Core Points Analysis:

Environment List: The ForEach loop iterates over all environment names and generates a list item for each environment.
Current Environment Indicator: If the current environment matches the list item environment, a selection icon is displayed.
Environment Switching: When a list item is clicked, the switchEnvironment method is called to switch the environment, and the dialog is closed.
Callback Notification: After the environment switch, the onEnvironmentChanged callback function is called to notify the outside that the environment has been switched.

(II) Callback Mechanism for Environment Switching

To perform related operations when the environment is switched, we can implement this by registering callback functions.

const environment = Environment.getInstance();

environment.registerEnvironmentChangeCallback((newEnvironment) => {
  console.log(`Environment switched to: ${newEnvironment.name}`);
  // Perform related operations after the environment switch here, such as reloading configurations, refreshing the interface, etc.
});

Core Points Analysis:

Register Callback: The registerEnvironmentChangeCallback method is used to register a callback function.
Callback Execution: The callback function is automatically called when the environment is switched.

III. Summary

By implementing a project runtime environment switcher, we can easily manage configurations for different environments in HarmonyOS sports projects. The environment switcher not only supports dynamic environment switching but also provides a callback mechanism to facilitate related operations when the environment is switched. In this way, developers can quickly switch between development, testing, and production environments without modifying the code, thereby improving development efficiency and flexibility.

In actual development, you can further extend and optimize the environment switcher based on the specific needs of your project. For example:

Support More Environment Types: Add more environment types according to project requirements, such as testing environments, pre-release environments, etc.
Dynamic Configuration Loading: Dynamically load environment configurations from a remote server.
Integration with Build Tools: Integrate the environment switcher with build tools to support specifying the runtime environment during the build process.

I hope this article provides valuable insights for your HarmonyOS development journey! If you have any questions or suggestions, feel free to reach out and discuss.

HarmonyOS Sports Project Development: Packaging an Extremely Useful RCP Network Library (Part 3)

zhonghua — Fri, 20 Jun 2025 01:09:34 +0000

Core Technologies of HarmonyOS ## Sports Development ## Remote Communication Kit (Remote Communication Services)

In the previous articles, we have introduced in detail how to package a complete RCP network library and explored its core functions and advanced features. In this part, we will demonstrate how to use this network library in HarmonyOS sports projects to implement specific network request functions.

Preface

In HarmonyOS sports projects, network requests are a key part of implementing functionality. Whether it is obtaining sports data, synchronizing user information, or loading sports video resources, a stable, efficient, and easy-to-use network library is required. In this part, we will show how to use the packaged RCP network library to achieve these functions through practical code examples.

I. Packaging Exception Handling

In actual development, exception handling is an indispensable part of network requests. By defining custom exception classes, we can better manage various errors that may occur in network requests.

(I) Custom Exception Class

A ApiException class has been defined to encapsulate error information in API requests.

export class ApiException extends Error {
  apiCode?: number;
  apiMessage?: string;

  constructor(apiCode?: number, apiMessage?: string) {
    super();
    this.name = "ApiException";
    this.apiCode = apiCode;
    this.apiMessage = apiMessage;
  }
}

Core Points Analysis:

Custom Properties: apiCode and apiMessage are used to store the error code and error message returned by the API.
Constructor: The constructor initializes the exception object and sets the error code and error message.

II. Packaging Network Requests

To simplify the implementation of network requests, you have packaged an ApiRequest class to manage network requests and error handling uniformly.

(I) Singleton Pattern

The ApiRequest class uses the singleton pattern to ensure that there is only one global instance.


import { DataResult, ErrorCodes, ErrorData, LibToast, NetworkException, SuccessData } from "lib_base";
import { RcpNetworkService } from "lib_base/src/main/ets/utils/rcpnet/RcpService";
import { ApiResult } from "../data/models/ApiResult";
import { ApiException } from "./ApiException";

export interface IApiRequestHandleBusinessError{
  handleBusinessError(apiException: ApiException): boolean
}

export class ApiRequest{

  private static instance: ApiRequest


  static getInstance (): ApiRequest {
    if (!ApiRequest.instance) {
      ApiRequest.instance = new ApiRequest()
    }
    return ApiRequest.instance
  }

  private _net?: RcpNetworkService | undefined;
  private _i_api_equest_handle_business_error?: IApiRequestHandleBusinessError | undefined;

  public set i_api_equest_handle_business_error(value: IApiRequestHandleBusinessError | undefined) {
    this._i_api_equest_handle_business_error = value;
  }

  public set net(value: RcpNetworkService | undefined) {
    this._net = value;
  }

  public getService() : RcpNetworkService{
    return this._net!;
  }




}

Core Points Analysis:

Singleton Pattern: The getInstance method ensures the global uniqueness of the ApiRequest instance.
Dependency Injection: The set method is used to inject RcpNetworkService and IApiRequestHandleBusinessError, enhancing the flexibility of the class.

(II) Unified Request Method

The ApiRequest class provides a unified request method remoteApi to handle network requests and encapsulate the return results.

export interface IApiRequestHandleBusinessError {
  handleBusinessError(apiException: ApiException): boolean;
}

export class ApiRequest {

  public static async remoteApi<T>(api:()=>Promise<ApiResult<T>>): Promise<DataResult<ApiResult<T>|null>>{
    try{
      const data = await api()
      if(data.success && data.success){
        let bean = new SuccessData<ApiResult<T>>(data)
        return bean;
      } else {
        let bean = ErrorData.fromError(new ApiException(data.code,data.msg) as Error,data.code?.toString(),data.msg)
        return bean;
      }
    }catch (e) {
      if(e instanceof NetworkException){
        let bean = ErrorData.fromError(e)
        // Request was canceled by the framework, client does not enter exception handling to avoid business pop-ups
        if(e.code !== ErrorCodes.REQUEST_CANCEL){
          LibToast.show(e.message)
        }
        return bean;
      }
      throw e as Error
    }

  }
}

Core Points Analysis:

Request Execution: The specific network request is executed through the api function passed in.
Success Handling: If the request is successful, a SuccessData object is returned.
Failure Handling: If the request fails, an ErrorData object is returned based on the error type.
Network Exception Handling: NetworkException is caught, and a prompt message is displayed based on the error code.

(III) Business Logic Handling

The ApiRequest class also provides a service method to handle business logic and errors.

export class ApiRequest {
  // ... Other code ...

  public static async service<T>(source:()=>Promise<DataResult<ApiResult<T>|null>>,
    request : (data:DataResult<T|null>)=>void,
    apiError : (apiError:ErrorData)=>void,
    netError? : (netError:ErrorData)=>void,
  ){
    let data = await source();
    if(data instanceof SuccessData){
      request(data.data)
    }else {
      let error = data as ErrorData
      if(error.error&&error.error instanceof ApiException){
        // Business exception
        if(ApiRequest.instance._i_api_equest_handle_business_error){
          ApiRequest.instance._i_api_equest_handle_business_error.handleBusinessError(error.error)
        }
        apiError(error)
      }else {
        // Network exception
        if(netError){
          netError(error)
        }
      }
    }
  }
}

Core Points Analysis:

Request Execution: The network request is executed through the source function.
Success Handling: If the request is successful, the request callback function is called to handle the data.
Error Handling: The apiError or netError callback function is called based on the error type.
Business Logic Separation: Business logic errors are handled through the IApiRequestHandleBusinessError interface.

III. Packaging Common Request Headers

In actual development, many requests need to carry common request headers, such as device information, user tokens, etc. You have packaged the common request headers through the CommonHeaderInterceptor class.

export async function getCommonHeaders(): Promise<Record<string, string>> {
  return {
    "device": LibDevice.getDeviceInfo(),
    "machineCode": await USystem.getUniqueKey(),
    "terminalType": "1", // Example terminal type
    "timestamp": new Date().toISOString(),
    "versionNumber": LibDevice.getAppVersionCode().toString(),
    "osId": Platform.appPlatform, // Example osId
    "versionCode": LibDevice.getAppVersionName(),
    "token": AccountManager.getToken()
  };
}

export class CommonHeaderInterceptor implements rcp.Interceptor {
  async intercept(context: rcp.RequestContext, next: rcp.RequestHandler): Promise<rcp.Response> {
    const commonHeaders = await getCommonHeaders();
    const keys = Object.keys(commonHeaders);
    for (let i = 0; i < keys.length; i++) {
      const key = keys[i];
      if (!context.request.headers) {
        context.request.headers = {};
      }
      context.request.headers[key] = commonHeaders[key];
    }
    return next.handle(context);
  }
}

Core Points Analysis:

Common Header Information: Common header information is obtained through the getCommonHeaders function.
Interceptor Implementation: In the intercept method, common header information is added to the request headers.
Dynamic Addition: Common header information is dynamically added through a loop to ensure that each request carries the necessary information.

IV. Packaging Response Converter

To better handle response data, a CommonTextResponseConverter class is packaged to handle response content.

export class CommonTextResponseConverter extends TextResponseConverter {
  convert(response: rcp.Response): string | object | null {
    if (response.toJSON()) {
      return response.toJSON();
    } else {
      return super.convert(response);
    }
  }
}

Core Points Analysis:

JSON Conversion: Prioritize converting the response content to JSON format.
Fallback Handling: If it cannot be converted to JSON, call the convert method of the parent class to handle the response content.

V. Practical Application Case: Obtaining Sports Data

Assuming we need to obtain the user's sports data from the server, such as sports records and sports plans, we will implement this function through the packaged RCP network library.

(I) Packaging Request Method

export async function getAllLookSubjectList(params: Record<"parentId", string>, requestKeyFun?: (str: string) => void): Promise<ApiResult<Subject[]>> {
  return ApiRequest.getInstance().getService().request<ApiResult<Subject[]>>>({
    act: AllLOOK_SUBJECT_LIST,
    method: RequestMethod.POST,
    contentType: RcpContentType.JSON,
    content: params
  }, requestKeyFun);
}

Core Points Analysis:

Request Configuration: The basic information of the request, such as API path, request method, and content type, is configured through RequestOptions.
Request Sending: The request is sent using the ApiRequest.getInstance().getService().request method.
Callback Function: The request key value is provided through requestKeyFun for operations such as canceling the request.

(II) Calling Request Method

In actual pages or components, we can call the packaged request method to obtain sports data.

aboutToAppear(): void {
  super.aboutToAppear();
  this.showLoading();
  ApiRequest.service<Subject[]>(() => {
    return LookResponsitory.getInstance().getAllLookSubjectList("1", (requestKey) => {
      if (requestKey) {
        this.addRequestId(requestKey);
      }
    });
  }, (data) => {
    this.hideLoading();
    if (data.data && data.data.length > 0) {
      this.tabs = data.data;
    } else {
      this.setDefalutTab();
    }
  }, (apiError) => {
    this.hideLoading();
    this.setDefalutTab();
    // Business exception
    // LibToast.show(apiError.message ?? "Get exception");
  }, () => {
    this.hideLoading();
    this.setDefalutTab();
    // Network and other exceptions
    // LibToast.show("Network exception");
  });
}

Core Points Analysis:

Request Execution: The network request is executed through the ApiRequest.service method.
Success Handling: If the request is successful, handle the returned data.
Error Handling: Call the corresponding callback function to handle the error based on the error type.
Loading Status: Display the loading status at the start of the request and hide it at the end of the request.

VI. Summary

Through the practical case in this part, we have demonstrated how to use the packaged RCP network library to implement specific network request functions. By defining exception classes, packaging request methods, handling common request headers and response converters, and implementing specific request logic, we can efficiently complete network request tasks. The packaged network library not only provides basic request and response handling functions but also has advanced features such as error handling, log recording, session management, and network status detection, which can meet the needs of most network request scenarios.

HarmonyOS Sports Project Development: Packaging an Extremely Useful RCP Network Library (Part 2)

zhonghua — Wed, 18 Jun 2025 01:06:49 +0000

Core Technologies of HarmonyOS ## Sports Development ## Remote Communication Kit (Remote Communication Services)

In the previous part, we introduced the core functions of the RCP network library, including request parameter packaging, response content conversion, and the interceptor and log recording mechanism. These functions provide a solid foundation for our network library. In this part, we will continue to delve into the advanced features of the network library, including error handling, session management, and network status detection, to further enhance the robustness and usability of the network library.

IV. Advanced Features of the Network Library: Error Handling and Exception Management

(I) Custom Exception Class

Error handling is crucial in network requests. To better manage errors, we have defined a NetworkException class to encapsulate various network-related exceptions.

import { ErrorCodes } from "../NetConstants";
import { BusinessError } from "@kit.BasicServicesKit";
import { appLogger } from "../../../app/Application";


export class NetworkException extends Error {

  private static errorMessages: Record<string, string> = {
    [ErrorCodes.NETWORK_UNAVAILABLE]: "Network is unavailable, please check your network connection",
    [ErrorCodes.REQUEST_TIMEOUT]: "Request timed out, please try again later",
    [ErrorCodes.SERVER_ERROR]: "The server is down, please try again later",
    [ErrorCodes.INVALID_RESPONSE]: "The server returned an invalid data format",
    [ErrorCodes.UNAUTHORIZED]: "Your login has expired, please log in again",
    [ErrorCodes.FORBIDDEN]: "You do not have permission to access this resource",
    [ErrorCodes.NOT_FOUND]: "The requested resource does not exist",
    [ErrorCodes.UNKNOWN_ERROR]: "Unknown error, please contact customer service",
    [ErrorCodes.URL_NOT_EXIST_ERROR]: "URL does not exist",
    [ErrorCodes.URL_ERROR]: "URL format is invalid",
    [ErrorCodes.BAD_REQUEST]: "The client request syntax is incorrect, the server cannot understand it.",
    [ErrorCodes.REQUEST_CANCEL]: "The request was canceled"
  };

  private responseCode?:number
  private originalError?:Error | BusinessError
  private _code: string;

  public get code(): string {
    return this._code;
  }



  constructor(code : string, originalError?: Error | BusinessError,customMessage?: string,responseCode?:number) {
    super(customMessage || NetworkException.getMessage(code))
    this._code = code
    this.name = "NetworkException";
    this.responseCode = responseCode
    this.originalError = originalError
  }


  public isResponseError(): boolean{
    if (this.responseCode) {
      return true
    }else {
      return false
    }
  }

  private static getMessage(code: string): string {
    return NetworkException.errorMessages[code] || NetworkException.errorMessages[ErrorCodes.UNKNOWN_ERROR];
  }


  static updateErrorMessages(newMessages: Record<string, string>): void {
    const keys = Object.keys(newMessages);
    for (let i = 0; i < keys.length; i++) {
      const key = keys[i];
      const value = newMessages[key];
      NetworkException.errorMessages[key] = value
    }
  }

}

Core Points Analysis:

Error Message Mapping: Through the errorMessages object, map error codes to specific error messages.
Custom Error Messages: Allow custom error messages to be passed in to override the default error descriptions.
Error Classification: Through the isResponseError() method, distinguish between response errors and other types of errors.
Dynamic Error Message Updates: Through the updateErrorMessages() method, allow dynamic updates to the error message mapping table.

(II) Error Handling Logic

In network requests, error handling logic needs to cover a variety of scenarios, including network unavailability, request timeouts, server errors, etc. We have implemented unified error handling by catching and throwing NetworkException in the RcpNetworkService class.


async request<T>(requestOption: RequestOptions,requestKeyFun?:(str:string)=>void): Promise<T> {
  const session = this.rcpSessionManager.getSession(requestOption.connectTimeout??this.httpConfig.connectTimeout,requestOption.transferTimeout??this.httpConfig.transferTimeout)

  try {

    let baseUrl = requestOption.baseUrl?requestOption.baseUrl:this.baseUrl
    if(baseUrl === null || baseUrl.trim().length === 0){
      throw new NetworkException(ErrorCodes.URL_NOT_EXIST_ERROR);
    }

    if (!LibNetworkStatus.getInstance().isNetworkAvailable()) {
      appLogger.error("HttpCore network is unavailable")
      throw new NetworkException(ErrorCodes.NETWORK_UNAVAILABLE);
    }


    let url = baseUrl + requestOption.act;

    if (!isValidUrl(url)) {
      appLogger.error("HttpCore URL format is invalid")
      throw new NetworkException(ErrorCodes.URL_ERROR);
    }
    const contentType = requestOption.contentType??RcpContentType.JSON

    const headers: rcp.RequestHeaders = {
      'Content-Type': contentType
    };
    const cacheKey = await USystem.getUniqueId()

    if (this.queryParamAppender) {
      let param = this.queryParamAppender.append(requestOption.queryParams);
      if(param){
        url = url + "?" + param
      }
    }


    const requestObj = new rcp.Request(url, requestOption.method??RequestMethod.GET, headers, this.converterManger.selectRequestConverter(requestOption.content,contentType));
    // Store the mapping relationship between the request and the session
    this.requestMap.set(cacheKey, { session, request: requestObj });
    if(requestKeyFun){
      requestKeyFun(cacheKey)
    }
    let response = await session.fetch(requestObj);

    if (!response.statusCode) {
      throw new NetworkException(ErrorCodes.INVALID_RESPONSE);
    }

    if (response.statusCode >= HttpStatus.SUCCESS && response.statusCode < 300) {
      // Get Content-Type
      const responseContentType = response.headers['Content-Type'];
      const responseData = this.converterManger.selectResponseConverter(response, responseContentType)
      const parsedResult = responseData as T

      return parsedResult;

    }

    switch (response.statusCode) {
      case HttpStatus.UNAUTHORIZED:
        throw new NetworkException(ErrorCodes.UNAUTHORIZED,undefined,undefined,response.statusCode);
      case HttpStatus.FORBIDDEN:
        throw new NetworkException(ErrorCodes.FORBIDDEN,undefined,undefined,response.statusCode);
      case HttpStatus.NOT_FOUND:
        throw new NetworkException(ErrorCodes.NOT_FOUND,undefined,undefined,response.statusCode);
      case HttpStatus.REQUEST_TIMEOUT:
        throw new NetworkException(ErrorCodes.REQUEST_TIMEOUT,undefined,undefined,response.statusCode);
      case HttpStatus.BAD_REQUEST:
        throw new NetworkException(ErrorCodes.BAD_REQUEST,undefined,undefined,response.statusCode);
      case HttpStatus.SERVER_ERROR:
      case HttpStatus.BAD_GATEWAY:
      case HttpStatus.SERVICE_UNAVAILABLE:
      case HttpStatus.GATEWAY_TIMEOUT:
        throw new NetworkException(ErrorCodes.SERVER_ERROR,undefined,undefined,response.statusCode);
      default:
        throw new NetworkException(ErrorCodes.UNKNOWN_ERROR,undefined,undefined,response.statusCode);
    }



  }catch (e) {
    if(e instanceof NetworkException){
      throw e
    } else {
      try{
        let err = e as BusinessError;
        appLogger.error(` ${err.code.toString()} ${err.stack} ${err.message} ${err.name}`)
        throw new NetworkException(err.code.toString(),err,err.message)
      }catch  {
        let err = e as Error;
        appLogger.error(`Exception: ${err.stack} ${err.message} ${err.name}`)
        throw err
      }
    }
  }finally {
    this.rcpSessionManager?.releaseSession(session)
    // When the session is closed, remove all requests associated with this session
    this.requestMap.forEach((entry, key) => {
      if (entry.session === session) {
        this.requestMap.delete(key);
      }
    });
  }
}

Core Points Analysis:

Network Status Detection: Before initiating a request, detect whether the network is available through LibNetworkStatus.getInstance().isNetworkAvailable().
URL Validation: Validate the URL format through the isValidUrl() method.
Error Classification and Throwing: Throw the corresponding NetworkException based on different error scenarios.
Unified Error Handling: In the catch block, handle all exceptions uniformly to ensure consistency of error messages.

V. Advanced Features of the Network Library: Session Management

(I) Implementation of the Session Pool

To optimize the performance of network requests, we have implemented a session pool mechanism. By reusing sessions, we can reduce the overhead of frequently creating and destroying sessions.

import { rcp } from "@kit.RemoteCommunicationKit";
import { HttpConfig } from "./HttpConfig";


// Create a security configuration to skip certificate validation
const securityConfig: rcp.SecurityConfiguration = {
  remoteValidation: 'skip'
};


export class RcpSessionManager{

  private currentConcurrentRequests = 0;

  // Define a connection pool
  private connectionPool: rcp.Session[] = [];
  private _interceptor: rcp.Interceptor[] = [];

  public set interceptor(value: rcp.Interceptor[]) {
    this._interceptor = value;
  }

  private _httpConfig: HttpConfig = new HttpConfig();

  public set httpConfig(value: HttpConfig) {
    this._httpConfig = value;
  }

  public getSession(connectTimeout:number,transferTimeout:number): rcp.Session {
    // If there is an available session in the connection pool, return it directly
    if (this.connectionPool.length > 0) {
      return this.connectionPool.pop()!;
    }

    // If there is no available session, create a new one
    const session = rcp.createSession({
      interceptors: [...this._interceptor],
      requestConfiguration: {
        transfer: {
          timeout: {
            connectMs: connectTimeout,
            transferMs: transferTimeout
          }
        },
        security: this._httpConfig.security?undefined:securityConfig
      }
    });

    return session;
  }

  public releaseSession(session: rcp.Session): void {
    // If the current concurrent requests are less than the maximum concurrent limit, put the session back into the connection pool
    if (this.currentConcurrentRequests < this._httpConfig.maxConcurrentRequests) {
      this.connectionPool.push(session);
    } else {
      session.close();
    }
  }

  public destroy(): void {
    // Close all sessions
    this.connectionPool.forEach(session => session.close());
    this.connectionPool.length = 0;
  }
}

Core Points Analysis:

Session Reuse: Store idle sessions in the connectionPool to avoid the overhead of frequently creating and destroying sessions.
Concurrency Limit: Limit the number of concurrent requests based on the maxConcurrentRequests configuration in HttpConfig.
Session Release: After the request is completed, put the session back into the session pool or close the session to optimize resource usage.

(II) The Importance of Session Management

Session management plays a crucial role in network requests. By managing sessions properly, we can significantly improve the performance and stability of network requests. For example:

Reduce Connection Overhead: By reusing sessions, reduce the overhead of frequently establishing and closing connections.
Control Concurrency: Limit the number of concurrent requests to avoid overwhelming the server with too many concurrent requests.
Resource Recycling: Timely release session resources after the request is completed to avoid resource leaks.

VI. Advanced Features of the Network Library: Network Status Detection

Network status detection is essential in network requests. By detecting whether the network is available, we can avoid request failures caused by network issues in advance.


import connection from '@ohos.net.connection'
import { appLogger } from '../../app/Application'
import { LibNetworkStatusCallback } from './LibNetworkStatusCallback'

const TAG : string = "LibNetworkStatus"

/**
 * Enum: Network Type
 */
export enum NetworkType {
  STATE_NULL = 'NULL',// Network status indicator: Not connected to the network
  UNKNOWN = 'UNKNOWN',// Unknown network
  MOBILE = 'MOBILE',
  WIFI = 'WIFI',
  ETHERNET = 'ETHERNET'
}

/**
 * Enum: Bearer Type (Internal use,对接具体平台API)
 * Note: The values of this enumeration should be consistent with the actual values in the platform API
 */
enum BearerType {
  MOBILE = 0,
  WIFI = 1,
  // ... There may be other bearer types, add according to the platform API
  ETHERNET = 3
}

/**
 * Network Information:
 * 1. Network connection status management
 * 2. Network event registration and cancellation
 */
export class LibNetworkStatus {


  /**
   * LibNetworkStatus singleton instance
   */
  private static instance: LibNetworkStatus
  /**
   * Current network status
   */
  private currentNetworkStatus:NetworkType = NetworkType.STATE_NULL
  /**
   * Whether the network is available
   */
  private isAvailable = false
  /**
   * HarmonyOS network connection object
   */
  private networkConnectio?: connection.NetConnection
  /**
   * Define a set of callback methods, use WeakSet to avoid memory leaks
   */
  private callbacks = new Set<LibNetworkStatusCallback>()

  /**
   * Debounce timer
   */
  private debounceTimer: number | null = null

  /**
   * Debounce delay (milliseconds)
   */
  private static readonly DEBOUNCE_DELAY = 300

  /**
   * Obtain the LibNetworkStatus singleton instance
   * @returns LibNetworkStatus singleton instance
   */
  static getInstance (): LibNetworkStatus {
    if (!LibNetworkStatus.instance) {
      LibNetworkStatus.instance = new LibNetworkStatus()
    }
    return LibNetworkStatus.instance
  }

  /**
   * Add a callback method
   * @param callback Callback method
   * @param isCallBackCurrentNetworkStatus Whether to immediately return the current network status
   */
  addCallback (callback: LibNetworkStatusCallback, isCallBackCurrentNetworkStatus: boolean) {
    if (callback && this.callbacks) {
      appLogger.debug(TAG+"Add callback method")
      if(this.callbacks.has(callback)){
        return
      }
      this.callbacks.add(callback)

      // Immediately callback the current network status
      if (isCallBackCurrentNetworkStatus) {
        appLogger.debug(TAG+'Immediately callback the current network status: ' + this.currentNetworkStatus)
        callback(this.currentNetworkStatus)
      }
    }
  }

  /**
   * Remove a callback method
   * @param callback Callback method
   */
  removeCallback (callback: LibNetworkStatusCallback) {
    if (callback && this.callbacks && this.callbacks.has(callback)) {
      appLogger.debug(TAG+'Remove callback method')
      this.callbacks.delete(callback)
    }
  }

  /**
   * Debounce processing of network status callback
   */
  private debouncedCallback() {
    if (this.debounceTimer !== null) {
      clearTimeout(this.debounceTimer);
    }

    this.debounceTimer = setTimeout(()    () => {
      if (this.callbacks && this.callbacks.size > 0) {
        appLogger.debug(TAG + 'Iterate through the callback set and callback the current network status')
        this.callbacks.forEach(callback => {
          callback(this.currentNetworkStatus)
        })
      }
      this.debounceTimer = null;
    }, LibNetworkStatus.DEBOUNCE_DELAY);
  }

  /**
   * Callback the current network status
   */
  callbackNetworkStatus() {
    this.debouncedCallback();
  }

  /**
   * Register network status listener:
   * The device will trigger "netAvailable", "netCapabilitiesChange", and "netConnectionPropertiesChange" events when switching from no network to a network;
   * The device will trigger the "netLost" event when switching from a network to no network
   * The device will trigger the "netLost" event when switching from Wi-Fi to cellular network (Wi-Fi is unavailable), and then trigger the "netAvailable" event (cellular is available)
   */
  registerNetConnectListener () {
    if (this.networkConnectio) {
      appLogger.debug(TAG+'Already subscribed to network events, no need to subscribe again')
      return
    }

    // Create a NetConnection object
    this.networkConnectio = connection.createNetConnection()

    // Determine the default network status
    let hasDefaultNet = connection.hasDefaultNetSync()
    if (hasDefaultNet) {
      appLogger.debug(TAG+'hasDefaultNetSync  ' + hasDefaultNet)
      this.isAvailable = true
      // Get the default network type
      this.getDefaultNetSync()
    }

    // Register
    this.networkConnectio.register((error) => {
      if (error) {
        appLogger.debug(TAG+'networkConnectio.register failure: ' + JSON.stringify(error))
      } else {
        appLogger.debug(TAG+' networkConnectio.register success')
      }
    })

    // Subscribe to network available event
    appLogger.debug(TAG+'Subscribe to network available event-->')
    this.networkConnectio.on('netAvailable', (data: connection.NetHandle) => {
      appLogger.debug(TAG+'netAvailable：' + JSON.stringify(data))
      this.isAvailable = true

      // Get the default network type
      this.getDefaultNetSync()

      // Callback network status
      this.callbackNetworkStatus()
    })

    // Subscribe to network lost event
    appLogger.debug(TAG+'Subscribe to network lost event-->')
    this.networkConnectio.on('netLost', (data: connection.NetHandle) => {
      appLogger.debug(TAG+'netLost：' + JSON.stringify(data))
      this.isAvailable = false
      this.currentNetworkStatus = NetworkType.STATE_NULL

      // Callback network status
      this.callbackNetworkStatus()
    })

    // Subscribe to network unavailable event
    appLogger.debug(TAG+'Subscribe to network unavailable event-->')
    this.networkConnectio.on('netUnavailable', () => {
      appLogger.debug(TAG+'netUnavailable')
      this.isAvailable = false
      this.currentNetworkStatus = NetworkType.STATE_NULL

      // Callback network status
      this.callbackNetworkStatus()
    })
  }

  /**
   * Get the default network type
   */
  getDefaultNetSync () {
    // Get the current network status
    let netHandle = connection.getDefaultNetSync()
    if (netHandle) {
      let capabilities = connection.getNetCapabilitiesSync(netHandle)
      appLogger.debug(TAG+'getNetCapabilitiesSync：' + JSON.stringify(capabilities))
      if (capabilities && capabilities.bearerTypes && capabilities.bearerTypes.length > 0) {

        // Get the first bearer type
        const bearerType = capabilities.bearerTypes[0];
        // Determine the network type based on the bearer type
        switch (bearerType) {
          case BearerType.MOBILE.valueOf():
          // Cellular network
            appLogger.debug(TAG+'currentNetworkState：Cellular network')
            this.currentNetworkStatus =  NetworkType.MOBILE;
                break;
          case BearerType.WIFI.valueOf():
          // Wi-Fi network
            appLogger.debug(TAG+'currentNetworkState：Wi-Fi network')
            this.currentNetworkStatus =  NetworkType.WIFI;
            break;
          case BearerType.ETHERNET.valueOf():
          // Ethernet network (usually not supported on mobile devices, but retained for completeness)
            appLogger.debug(TAG+'currentNetworkState：Ethernet network')
            this.currentNetworkStatus =  NetworkType.ETHERNET;
            break;
          default:
          // Unknown network type
            appLogger.debug(TAG+'currentNetworkState：Unknown network type')
            this.currentNetworkStatus =  NetworkType.UNKNOWN;
            break;
        }

      }
    }
  }

  /**
   * Is the current network available
   */
  isNetworkAvailable () {
    return this.isAvailable
  }

  /**
   * Get the current network status
   * @returns
   */
  getCurrentNetworkStatus () {
    return this.currentNetworkStatus
  }
}

Core Points Analysis:

Singleton Pattern: Ensure that the LibNetworkStatus instance is unique throughout the application using the singleton pattern.
Network Status Detection: Determine whether the network is available by calling the HarmonyOS-provided network status detection API.

VII. Summary

In this part, we have delved into the advanced features of the RCP network library, including error handling, session management, and network status detection. With these features, we can build a more robust, efficient, and easy-to-use network library. In the next part, we will demonstrate how to use this network library in HarmonyOS sports projects through practical cases to implement various network request functions. Stay tuned!

HarmonyOS Sports Project Development: Packaging an Extremely Useful RCP Network Library (Part 1)

zhonghua — Tue, 17 Jun 2025 01:09:00 +0000

Core Technologies of HarmonyOS ## Sports Development ## Remote Communication Kit (Remote Communication Services)

In HarmonyOS sports project development, network communication is an indispensable part. Whether it is obtaining sports data, synchronizing user information, or loading sports video resources, a stable, efficient, and easy-to-use network library is required. This article will take you deep into how to package an extremely useful RCP network library to help you easily deal with various network requests in HarmonyOS development. This series of articles is divided into three parts: upper, middle, and lower, which introduce the core functions of the network library, advanced features, and practical application cases respectively.

Preface

In mobile application development, network requests are the basis for interacting with backend services. A good network library not only needs to provide basic request functions but also needs to have advanced features such as error handling, log recording, and cache management. The HarmonyOS system provides a powerful RCP (Remote Communication Protocol) module for efficient network communication. By packaging the RCP module, we can build a complete and easy-to-use network library to improve development efficiency and application performance.

I. Core Functions of the Network Library: Request and Response Processing

(I) Packaging of Request Parameters

In network requests, parameter processing is one of the key links. We need to convert complex request parameters (such as form data, JSON objects, etc.) into a format suitable for transmission. To this end, we have defined a QueryParamAppender interface and implemented the CustomQueryParamAppender class to handle the concatenation of query parameters.

// Define an interface for appending query parameters
export interface QueryParamAppender {
  append(queryParams?: Map<string, number|string|boolean|Array<number> | Array<string> | Array<boolean> >|Record<string,string>| object |undefined): string|undefined;
}

import { QueryParamAppender } from "./QueryParamAppender";

export class CustomQueryParamAppender implements QueryParamAppender {
  append(queryParams?: Map<string, string | number | boolean | number[] | string[] | boolean[]> |Record<string,string> | object |undefined): string|undefined {
    if (queryParams === undefined || (queryParams instanceof Map && queryParams.size === 0) || (typeof queryParams === 'object' && Object.keys(queryParams).length === 0)) {
      return;
    }
    const paramsArray: string[] = [];
    // Use Object.entries() to convert the object into a key-value pair array
    let values:[string,string|number|boolean|number[]|string[]|boolean[]][] = Object.entries(queryParams)
    for (const qp of values) {
      let key = qp[0]
      let value = qp[1]
      let encodedValue = '';
      if (Array.isArray(value)) {
        for (let i = 0; i < value.length; i++) {
          encodedValue += `${encodeURIComponent(`${key}[${i}]`)}=${encodeURIComponent(value[i].toString())}&`;
        }
        if (encodedValue.length > 0) {
          encodedValue = encodedValue.slice(0, -1); // Remove the last '&'
        }
      } else {
        encodedValue = encodeURIComponent(key) + '=' + encodeURIComponent(value.toString());
      }
      paramsArray.push(encodedValue);
    }
    return paramsArray.join('&');
  }

}

Core Points Analysis:

Parameter Type Support: Support for multiple types of parameters, including strings, numbers, booleans, and arrays.
Encoding Processing: Use encodeURIComponent to encode parameters to ensure their validity in the URL.
Array Processing: For array-type parameters, concatenate through indexes, for example, key[0]=value1&key[1]=value2.

(II) Conversion of Response Content

The response content of network requests usually needs to be converted according to different content types (such as JSON, text, etc.). To this end, we have defined the RequestConverter and ResponseConverter interfaces and implemented various converters, such as FormConverter, JsonConverter, TextResponseConverter, and ObjectResponseConverter.

import { rcp } from "@kit.RemoteCommunicationKit";
import { JSONUtil } from "../../JSONUtil";
import { modelToForm } from "../NetUtils";
import { RcpContentType } from "../RcpService";

export interface RequestConverter {
  contentType():RcpContentType;
  convert(value: object|undefined): rcp.RequestContent;
}

/**
 * Form Converter
 */
export class FormConverter implements RequestConverter {
  contentType(): RcpContentType {
    return RcpContentType.FORM_URLENCODED
  }

  convert(value: object|undefined): rcp.RequestContent {
    return modelToForm(value);
  }
}

export class JsonConverter implements RequestConverter {

  contentType(): RcpContentType {
    return RcpContentType.JSON;
  }
  convert(value: object|undefined): rcp.RequestContent {
    if(value){
      return JSONUtil.toString(value);
    }
    return ''
  }
}

export interface ResponseConverter {
  contentType():RcpContentType;
  convert(response: rcp.Response): string|object|null;
}

/**
 * Raw Text Converter
 */
export class TextResponseConverter implements ResponseConverter {
  contentType(): RcpContentType {
    return RcpContentType.TEXT_PLAIN;
  }
  convert(response: rcp.Response): string|object|null {
    return response.toString();
  }
}


export class ObjectResponseConverter implements ResponseConverter{
  contentType(): RcpContentType {
    return RcpContentType.JSON;
  }
  convert(response: rcp.Response): string|object|null {
    return response.toJSON()
  }
}

Core Points Analysis:

Content Type Identification: Clearly specify the content type supported by the converter through the contentType() method.
JSON Conversion: Convert JavaScript objects to JSON strings.
Text Response Processing: Directly convert response content to a string.

(III) Unified Management of Requests and Responses

To better manage requests and responses, we have created the ConverterManager class to register and select appropriate converters.


// src/main/ets/net/converter/ConverterManager.ts
import { rcp } from '@kit.RemoteCommunicationKit';
import { CustomErrorCode, LibError } from '../../LibError';
import { RcpContentType } from '../RcpService';
import { RequestConverter, ResponseConverter } from './RcpConverter';

/**
 * Content type and converter mapping
 */
export class ConverterManager {

  private requestConverters: RequestConverter[] = [];
  private responseConverters: ResponseConverter[] = [];
  private _requestFunc?: ((data: object|undefined, dataType: RcpContentType) => RequestConverter) | undefined;
  private _responseFunc?: ((response: rcp.Response) => ResponseConverter) | undefined;

  public set responseFunc(value: ((response: rcp.Response) => ResponseConverter) | undefined) {
    this._responseFunc = value;
  }

  public set requestFunc(value: ((data: object|undefined, dataType: string) => RequestConverter) | undefined) {
    this._requestFunc = value;
  }

  // Register request converter
  public registerRequestConverter(converter: RequestConverter): void {
    this.requestConverters.push(converter);
  }

  // Register response converter
  public registerResponseConverter(converter: ResponseConverter): void {
    this.responseConverters.push(converter);
  }

  /**
   * Automatically select a converter based on request data
   */
  selectRequestConverter(data: object|undefined,dataType: RcpContentType): rcp.RequestContent {
    if(this._requestFunc){
      return this._requestFunc(data , dataType).convert(data)
    }
    for(const request of this.requestConverters){
      if(request.contentType() == dataType){
        return request.convert(data);
      }
    }
    throw LibError.makeBusinessError(CustomErrorCode.NOT_FIND_REQUEST_CONVERTER_ERROR,"NOT_FIND_REQUEST_CONVERTER_ERROR")
  }

  /**
   * Select a converter based on response headers
   */
  selectResponseConverter(response: rcp.Response,contentType: string | string[] | undefined): string|object|null {
    if(this._responseFunc){
      return this._responseFunc(response).convert(response)
    }
    let dataType = RcpContentType.TEXT_PLAIN
    if(contentType){
      if (contentType.includes('application/json')) {
        dataType = RcpContentType.JSON
      } else if (contentType.includes('text/plain')) {
        dataType = RcpContentType.TEXT_PLAIN
      } else if (contentType.includes('text/html')) {
        dataType = RcpContentType.TEXT_PLAIN
      }
    }
    for(const responseConver of this.responseConverters){
      if(responseConver.contentType() == dataType){
        return responseConver.convert(response);
      }
    }
    throw LibError.makeBusinessError(CustomErrorCode.NOT_FIND_RESPONSE_CONVERTER_ERROR,"NOT_FIND_RESPONSE_CONVERTER_ERROR")
  }

}

Core Points Analysis:

Converter Registration: Register converters to the manager through the registerRequestConverter and registerResponseConverter methods.
Converter Selection: Automatically select the appropriate converter for processing based on the content type of the request or response.
Error Handling: Throw an error prompt if a suitable converter is not found.

II. Advanced Features of the Network Library: Interceptors and Log Recording

(I) Interceptor Mechanism

Interceptors are an important feature in the network library, used to insert custom logic when requests are sent and responses are returned. We have implemented the LoggingInterceptor to record detailed information of requests and responses.

import { rcp } from "@kit.RemoteCommunicationKit";
import { util } from "@kit.ArkTS";
import { appLogger } from "../../../app/Application";


export class LoggingInterceptor implements rcp.Interceptor {
  async intercept(context: rcp.RequestContext, next: rcp.RequestHandler): Promise<rcp.Response> {
    // Record request information
    this.logRequest(context.request);

    // Call the next request handler
    const response = await next.handle(context);

    // Record response information
    this.logResponse(response);

    return response;
  }

  private logRequest(request: rcp.Request) {
    const method = request.method;
    const url = request.url.href;
    const headers = request.headers;
    const body = request.content;

    appLogger.info(`[Request] ${method} ${url}`);
    appLogger.info(`[Request Headers] ${JSON.stringify(headers, null, 2)}`);

    if (body instanceof rcp.Form) {
      appLogger.info(`[Request Body] ${JSON.stringify(body, null, 2)}`);
    } else {
      appLogger.info(`[Request Body] ${body}`);
    }
  }

  private logResponse(response: rcp.Response) {
    const statusCode = response.statusCode;
    const headers = response.headers;
    const body = response.body;

    appLogger.info(`[Response] Status Code: ${statusCode}`);
    appLogger.info(`[Response Headers] ${JSON.stringify(headers, null, 2)}`);

    if (body) {
      try {
        const uint8Array = new Uint8Array(body);
        // Convert ArrayBuffer to string
        const decoder = new util.TextDecoder();
        const bodyString = decoder.decodeToString(uint8Array);
        // Try to parse as JSON
        appLogger.logMultiLine(`[Response Body] ${JSON.stringify(JSON.parse(bodyString), null, 2)}`)

      } catch (error) {
        appLogger.logMultiLine(`[Response Body] ${body}`);
      }
    }
  }
}

Core Points Analysis:

Request Recording: Record the URL, method, header information, and request body of the request.
Response Recording: Record the status code, header information, and response body of the response.
Log Formatting: Use JSON.stringify to format log output for easy reading.

(II) The Importance of Log Recording

Log recording is crucial in network request debugging. By recording detailed information of requests and responses, we can quickly locate problems, such as:

Whether the request parameters are correctly passed.
Whether the response data meets expectations.
Whether the network request times out or fails.

In actual development, it is recommended to enable detailed log recording during the development stage, and to turn it off or only record key information in the production environment to avoid performance loss.

III. Configuration and Initialization of the Network Library

To make the network library more flexible, we provide the HttpConfig class to configure parameters such as connection timeout, transfer timeout, and concurrent request limits.

import { Timeout } from "./NetConstants";

// Define a clear configuration interface
export interface IHttpConfigOptions {
  connectTimeout?: number;
  transferTimeout?: number;
  maxConcurrentRequests?: number;
  security?: boolean;

}

export class HttpConfig {
  /**
   * Connection timeout (milliseconds)
   */
  connectTimeout: number;

  /**
   * Transfer timeout (milliseconds)
   */
  transferTimeout: number;

  /**
   * Maximum number of concurrent requests
   */
  maxConcurrentRequests: number;


  constructor(config?: IHttpConfigOptions) {
    this.connectTimeout = config?.connectTimeout ?? Timeout.CONNECT_TIME_OUT;
    this.transferTimeout = config?.transferTimeout ?? Timeout.TRANS_TIME_OUT;
    this.maxConcurrentRequests = config?.maxConcurrentRequests ?? 5;
    this.security = config?.security ?? true
  }
}

Core Points Analysis:

Default Value Setting: Provide default values for configuration items through the ?? operator.
Flexible Configuration: Allow developers to customize timeout, concurrency limits, and other parameters according to their needs.

In this part, we have introduced in detail the core functions of the network library, including request parameter packaging, response content conversion, and the interceptor and log recording mechanism. These functions provide a solid foundation for our network library. In the upcoming middle part, we will continue to delve into the advanced features of the network library, including error handling, session management, and network status detection, to further enhance the robustness and usability of the network library. Stay tuned!

Practical Development of a Sports Video Player on HarmonyOS: Creating a Personalized Sports Video Player

zhonghua — Sun, 15 Jun 2025 02:57:10 +0000

Practical Development of a Sports Video Player on HarmonyOS: Creating a Personalized Sports Video Player

Core Technologies of HarmonyOS ## Sports Development ## Media Kit (Media Services)

In today's digital age, sports and fitness have become an integral part of many people's lives. Today, I will add a video player to the application to help users better warm up before exercising and stretch after exercising. This article will start from the core points of the code and guide you step by step to understand the key technologies and implementation details in the development process.

I. Project Background and Requirement Analysis

Before developing any application, clarifying the requirements is of vital importance. For a sports video player, we need to consider the following core functions:

Video Playback: Support the playback of sports-related videos, such as warm-up and stretching.
User Interaction: Provide simple button operations, such as play, pause, and resume.

II. Core Points of Code and Analysis

Next, we will go through the core parts of the code to gradually analyze the key steps in implementing the sports video player.

(I) Page Layout and Navigation

In HarmonyOS development, page layout is the foundation of user experience. We used LibNav and LibPage to build the navigation and content layout of the page. Here is the core part of the code:

@Component
export struct SportHelperPage {
  @Builder
  pageNavBuilder(){
    LibNav({
      pageTitle: "Sports Helper"
    }).width("100%")
  }

  @Builder
  pageContentBuilder(){
    Column() {
      Text('Sports Helper')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })
      Button('Warm-up Before Running')
        .onClick(() => this.playVideo('https://video.111.com/p/bms/warmup_before_running.mp4'))
        .margin({ top: 10 })
      Button('Stretch After Running')
        .onClick(() => this.playVideo('https://video.111.com/p/bms/stretch_after_running.mp4'))
        .margin({ top: 10 })
      Button('Pause Playback')
        .onClick(() => {
          this.avPlayer?.pause()
        })
      Button('Resume Playback')
        .onClick(() => {
          this.avPlayer?.play()
        })
      XComponent({ type: XComponentType.SURFACE, controller: mXComponentController })
        .width('100%')
        .height(300)
    }
    .padding(20)
    .backgroundColor(Color.White)
  }
}

Page Navigation: By using LibNav, the page title is set to "Sports Helper", and its width is set to 100% to ensure that the navigation bar covers the entire top of the screen.
Page Content: A Column layout is used to arrange text, buttons, and the video playback component (XComponent) in sequence. Each button is bound to a click event to trigger video playback or control the playback status.

(II) Initialization and Control of the Video Player

Video playback is the core function of the application, and we have used HarmonyOS's media.AVPlayer to implement it. Here is the code for initialization and playback control:

async initPlay() {
  try {
    this.avPlayer = await media.createAVPlayer();
    this.setAVPlayerCallback(this.avPlayer);
  } catch (error) {
    console.error('Failed to initialize video:', error);
  }
}

async playVideo(url: string) {
  try {
    if(this.avPlayer){
      this.avPlayer.url = url;
      this.avPlayer.play();
    }
  } catch (error) {
    console.error('Failed to play video:', error);
  }
}

Initialize Player: An AVPlayer instance is created through media.createAVPlayer(), and a callback function is registered to monitor changes in playback status.
Play Video: By setting the avPlayer.url property to the video's URL and calling the play() method, playback begins. It should be noted that the video URL must be valid; otherwise, playback will fail.

(III) State Machine Callbacks and Error Handling

During video playback, various state changes and errors may occur. By registering callback functions, we can better manage these situations:

setAVPlayerCallback(avPlayer: media.AVPlayer) {
  avPlayer.on('startRenderFrame', () => {
    console.info(`AVPlayer start render frame`);
  });
  avPlayer.on('seekDone', (seekDoneTime: number) => {
    console.info(`AVPlayer seek succeeded, seek time is ${seekDoneTime}`);
  });
  avPlayer.on('error', (err: BusinessError) => {
    console.error(`Invoke avPlayer failed, code is ${err.code}, message is ${err.message}`);
    avPlayer.reset();
  });
  avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => {
    switch (state) {
      case 'idle':
        avPlayer.release();
        break;
      case 'initialized':
        const id = mXComponentController.getXComponentSurfaceId();
        avPlayer.surfaceId = id;
        avPlayer.prepare();
        break;
      case 'prepared':
        avPlayer.play();
        break;
      case 'paused':
        console.info('AVPlayer state paused called.');
        break;
      case 'completed':
        avPlayer.stop();
        break;
      case 'stopped':
        avPlayer.reset();
        break;
      case 'released':
        console.info('AVPlayer state released called.');
        break;
      default:
        console.info('AVPlayer state unknown called.');
        break;
    }
  });
}

State Callbacks: By listening to the stateChange event, we can perform corresponding actions based on different states (such as initialized, prepared, playing, etc.). For example, in the initialized state, set the surfaceId for the playback surface and call the prepare() method to prepare for playback.
Error Handling: By listening to the error event, capture possible errors during playback and call the reset() method to reset the player's state.

III. Precautions and Optimization Suggestions in Development

During the development process, we need to pay attention to the following key points to ensure the stability of the application and the user experience:

Validity of Video URLs: When calling the playVideo() method, the URL passed in must be valid. If the URL is invalid or the network is unavailable, the player will not work properly. It is recommended to validate the video URL in actual development and provide friendly error messages.
Performance Optimization: To reduce video loading time, consider preloading video resources when the application starts. In addition, manage the player's lifecycle properly to avoid occupying system resources when it is not needed.
User Experience: In page layout, the arrangement of buttons and text should be simple and clear, avoiding overly complex operations. Also, consider adding features such as a progress bar and volume control to further enhance the user experience.

IV. Conclusion

In actual development, developers can further expand the functions according to the requirements, such as adding more categories of sports videos and supporting offline downloads.

I'm sorry that I failed to parse the web pages you provided. The reason might be related to the web links or the network. You can check the validity of the web links and try again. If you have any other questions, feel free to ask.

Practical HarmonyOS Sports Development: In-Depth Analysis of Correct File Preview Practices

zhonghua — Fri, 13 Jun 2025 01:25:37 +0000

Practical HarmonyOS Sports Development: In-Depth Analysis of Correct File Preview Practices

Foreword

In HarmonyOS development, the file preview feature is a common requirement, especially when dealing with user-uploaded resources such as images, documents, audio, or video. However, implementing file preview is not always straightforward, particularly when it comes to file permissions and managing the preview window. This article will delve into the core aspects of file preview in HarmonyOS, focusing on the theme of "choosing the right file for preview." It will share practical tips and tricks to help developers avoid common pitfalls.

I. Pain Points and Challenges of File Preview

In HarmonyOS, file preview may seem simple, but it hides many details. Developers often encounter issues such as insufficient file permissions, preview windows failing to open properly, or opening repeatedly. These issues not only affect user experience but can also lead to app crashes or data loss. Therefore, mastering the correct implementation of file preview is crucial.

II. Core Points: Persisting File URI Permissions

In HarmonyOS, the file URI obtained through DocumentViewPicker only has temporary permissions, which cannot be used directly for file preview, as it will result in preview failure. Therefore, we need to handle the persistence of file URI permissions.

Code Analysis for Persisting Permissions

await fileShare.persistPermission([
  {
    uri: uri,
    operationMode: fileShare.OperationMode.READ_MODE
  }
]);

fileShare.persistPermission: This is the key method for persisting permissions. It changes the file URI's permissions from temporary to persistent, ensuring that the preview function can access the file properly.
uri: This is the file path, which must be in the correct format.
operationMode: Specified as READ_MODE, indicating that only read permission is granted, which is the minimum required for preview functionality.

Additionally, to use the persistPermission method, you need to declare the following permission in the app's config.json file:

{
  "name": "ohos.permission.FILE_ACCESS_PERSIST"
}

III. Obtaining the File MIME Type

Before previewing a file, it is essential to determine the file's MIME type, which is crucial for the correctness of the preview function. Below is the code implementation for obtaining the MIME type:

private getMimeType(filePath: string): string {
  const extension = filePath.split('.').pop()?.toLowerCase() || '';

  switch (extension) {
    case 'jpg':
    case 'jpeg':
      return 'image/jpeg';
    case 'png':
      return 'image/png';
    case 'gif':
      return 'image/gif';
    case 'bmp':
      return 'image/bmp';
    case 'webp':
      return 'image/webp';

    case 'mp4':
      return 'video/mp4';
    case 'mov':
      return 'video/quicktime';
    case 'avi':
      return 'video/x-msvideo';

    case 'mp3':
      return 'audio/mpeg';
    case 'wav':
      return 'audio/wav';
    case 'ogg':
      return 'audio/ogg';

    case 'txt':
    case 'log':
      return 'text/plain';

    case 'html':
    case 'htm':
      return 'text/html';

    default:
      return 'application/octet-stream';
  }
}

Code Analysis

filePath.split('.').pop(): Obtain the file extension from the file path, which is key to determining the MIME type.
switch statement: Returns the corresponding MIME type based on the extension. This covers common image, video, audio, text, and HTML file types.
Default value: If the file type cannot be identified, it returns application/octet-stream, a generic binary stream type.

IV. Implementation Details of File Preview

Implementing file preview involves several steps, including checking if the file exists, whether it can be previewed, preparing preview parameters, and managing the preview window. Below is the complete code implementation:

async previewFile(): Promise<void> {
  if (!this.selectedFilePath) {
    promptAction.showToast({ message: 'Please select a file first', duration: 2000 });
    return;
  }

  try {
    let uiContext = this.getUIContext().getHostContext() as Context;

    // 1. Check if the file exists
    try {
      await fs.access(this.selectedFilePath);
    } catch {
      promptAction.showToast({ message: 'File does not exist or is not accessible', duration: 2000 });
      return;
    }

    // 2. Check if it can be previewed
    const uri = this.selectedFilePath.startsWith('file://') ?
      this.selectedFilePath :
      `file://${this.selectedFilePath}`;

    await fileShare.persistPermission([
      {
        uri: uri,
        operationMode: fileShare.OperationMode.READ_MODE
      }
    ]);

    const canPreview = await filePreview.canPreview(uiContext, uri);
    if (!canPreview) {
      promptAction.showToast({ message: 'This file type is not supported for preview', duration: 2000 });
      return;
    }

    // 3. Prepare preview parameters
    const fileInfo: filePreview.PreviewInfo = {
      title: this.fileName,
      uri: uri,
      mimeType: this.getMimeType(this.selectedFilePath)
    };

    // 4. Check if a preview window already exists
    const hasDisplayed = await filePreview.hasDisplayed(uiContext);

    if (hasDisplayed) {
        // Close the existing window
        await filePreview.closePreview(uiContext)
    } else {
      // Open a new preview window
      const displayInfo: filePreview.DisplayInfo = {
        x: 100,  // Window starting x-coordinate
        y: 100,  // Window starting y-coordinate
        width: 800, // Window width
        height: 800 // Window height
      };

      await filePreview.openPreview(uiContext, fileInfo, displayInfo);
    }

    console.info('File preview successful');
  } catch (err) {
    const error = err as BusinessError;
    console.error(`Preview failed, error code: ${error.code}, error message: ${error.message}`);
    promptAction.showToast({
      message: `Preview failed: ${error.message}`,
      duration: 2000
    });
  }
}

Code Analysis

Check if the file exists: Use the fs.access method to check if the file path is valid.
Persist file permissions: Use the fileShare.persistPermission method to ensure the file URI has persistent read permissions.
Check if it can be previewed: Call the filePreview.canPreview method to determine if the file type supports preview.
Prepare preview parameters: Construct the filePreview.PreviewInfo object, containing the file title, URI, and MIME type.
Manage the preview window: Use filePreview.hasDisplayed to check if a preview window already exists. If it does, call filePreview.closePreview to close the window; if not, call filePreview.openPreview to open a new preview window.

V. Summary: The Correct Way to Implement File Preview

In HarmonyOS development, implementing file preview requires attention to multiple aspects, including file permissions, obtaining MIME types, and managing the preview window.

Practical HarmonyOS Sports Development: Creating a Convenient Static Quick Menu

zhonghua — Thu, 12 Jun 2025 03:21:16 +0000

Practical HarmonyOS Sports Development: Creating a Convenient Static Quick Menu

Foreword

In sports applications, users often need to quickly access frequently used functions, such as viewing results, event information, or starting sports. To enhance user experience, HarmonyOS provides the static quick menu feature, which allows users to jump directly to specific pages of the application from the home screen. This article will delve into how to develop a static quick menu based on practical HarmonyOS development experience to achieve the function of quick page jumps.

I. Why We Need a Static Quick Menu

A static quick menu provides users with a way to quickly access specific functions of the application without having to open the application and click multiple times. This is especially important for sports applications, as users may need to quickly start sports mode or view sports data before exercising. With a static quick menu, users can launch these functions directly from the home screen, greatly improving the convenience and user experience of the application.

II. Configuring the Static Quick Menu

Configuration File

The configuration file for the static quick menu is located in the base->profile directory. You need to create a shortcuts_config.json file in this directory and define the quick menu items. Below is the core content of the configuration file:

{
  "shortcuts": [
    {
      "shortcutId": "my_scores",
      "label": "$string:shortcut_grades",
      "icon": "$media:icon_shortcut_grades",
      "wants": [
        {
          "bundleName": "package_name",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "action": "action.view.scores"
          }
        }
      ]
    },
    {
      "shortcutId": "my_events",
      "label": "$string:shortcut_race",
      "icon": "$media:icon_shortcut_race",
      "wants": [
        {
          "bundleName": "package_name",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "action": "action.view.events"
          }
        }
      ]
    },
    {
      "shortcutId": "start_running",
      "label": "$string:shortcut_sport",
      "icon": "$media:icon_shortcut_sport",
      "wants": [
        {
          "bundleName": "package_name",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "action": "action.start.running"
          }
        }
      ]
    }
  ]
}

Core Points Analysis

shortcutId: A unique identifier for each quick menu item.
label: The display name of the quick menu item, which supports internationalization resources.
icon: The icon resource for the quick menu item.
wants: Defines the target page and its parameters to be launched when the quick menu item is clicked.

Adding Configuration in the Module’s abilities

Add a reference to the quick menu configuration in the module’s abilities configuration file. Below is the configuration code:

"metadata": [
  {
    "name": "ohos.ability.shortcuts",
    "resource": "$profile:shortcuts_config"
  }
]

Core Points Analysis

metadata: Defines metadata related to the ability.
name: The name of the metadata, which is fixed as ohos.ability.shortcuts.
resource: Points to the path of the quick menu configuration file.

III. Handling Quick Menu Jumps

In EntryAbility, you need to handle the click events of the quick menu items. Through the onNewWant method, you can capture the click events of the quick menu items and jump to the corresponding pages based on the passed parameters. Below is the core code for handling logic:

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // Handle shortcut jumps
  if (want.parameters?.action) {
    let action = want.parameters['action'];
    if (action) {
      this.handleShortcutAction(action as string);
    }
  }
}

private handleShortcutAction(action: string): void {
  switch (action) {
    case 'action.view.scores':
      LibNavigator.pushPathByName(SportRouteName.MetronomePage, undefined);
      break;
    case 'action.view.events':
      LibNavigator.pushPathByName(SportRouteName.FileSelectPage, undefined);
      break;
    case 'action.start.running':
      LibNavigator.pushPathByName(SportRouteName.RunningSettingPage, undefined);
      break;
    default:
      entryLogger.warn(`Unknown shortcut action: ${action}`);
  }
}

Core Points Analysis

onNewWant: When the user clicks a quick menu item, the system calls the onNewWant method.
want.parameters: Obtain the passed parameters, including the custom action.
handleShortcutAction: Based on the value of action, call the corresponding page jump logic.

IV. Summary and Outlook

With the static quick menu feature of HarmonyOS, you can provide users with a convenient way to quickly jump to specific functions of the application.

Practical HarmonyOS Sports Development: How to Select and Upload Sports Records

zhonghua — Wed, 11 Jun 2025 03:34:26 +0000

Practical HarmonyOS Sports Development: How to Select and Upload Sports Records

Foreword

In sports applications, the ability to quickly import and analyze sports records from other applications is a highly attractive feature. It not only provides convenience for users but also enhances the utility and appeal of the application. This article will combine practical HarmonyOS development experience to delve into how to implement a sports record selection and upload feature, making sports data management more efficient.

I. Why We Need Sports Record Upload Functionality

The sports record upload feature allows users to import sports data from other applications (such as Keep) into our application for analysis and management. This not only enriches our application data but also provides users with more comprehensive sports analysis and recommendations. Additionally, through the upload feature, users can easily back up and synchronize their sports records, allowing them to view their sports history anytime and anywhere.

II. Core Function Implementation

File Selection

To implement the file selection feature, we used HarmonyOS's DocumentViewPicker API. Below is the core code for file selection:

async selectFile() {
  if (this.isLoading) return;

  this.isLoading = true;
  try {
    let context = getContext(this) as common.Context; // Ensure getContext(this) returns a UIAbilityContext
    let documentPicker = new picker.DocumentViewPicker(context);
    let documentSelectOptions = new picker.DocumentSelectOptions();
    // Maximum number of documents to select (optional)
    documentSelectOptions.maxSelectNumber = 1;
    // File suffix filters ['Suffix description|Suffix'] (optional) If there are multiple suffixes, separate each with a comma (optional), and the suffix name should not exceed 100 characters. To select all files: 'All files(*.*)|.*';
    documentSelectOptions.fileSuffixFilters = ['Images(.png, .jpg)|.png,.jpg', 'Documents|.txt', 'Videos|.mp4', '.pdf', 'Sports data files|.gpx,.tcx'];

    const result = await documentPicker.select(documentSelectOptions);

    if (result && result.length > 0) {
      const fileUri = result[0];
      this.selectedFilePath = fileUri;

      // Get the file name
      this.fileName = fileUri.split('/').pop() || 'Unknown file';

      // Get the file size
      try {
        let file = fs.openSync(fileUri, fs.OpenMode.READ_ONLY);
        const stat = await fs.stat(file.fd);
        this.fileSize = this.formatFileSize(stat.size);
      } catch (error) {
        console.error('Failed to get file size:', error);
        this.fileSize = 'Size unknown';
      }

      promptAction.showToast({ message: 'File selection successful', duration: 2000 });
    }
  } catch (err) {
    console.error('Failed to select file. Cause: ' + (err as BusinessError).message);
    promptAction.showToast({ message: 'File selection failed', duration: 2000 });
  } finally {
    this.isLoading = false;
  }
}

Core Points Analysis

DocumentViewPicker: A component used for file selection, supporting various file types.
fileSuffixFilters: Set the types of files that can be selected, such as images, documents, videos, etc.
fs.openSync and fs.stat: Used to get the size and status information of the file.
promptAction.showToast: Used to display a toast message to inform the user of the result of the file selection.

File Upload

The file upload feature allows users to upload the selected file to the server for further processing. The details of this are not covered here.

III. User Interface Design

To enable users to conveniently select and upload files, we need to design a simple and intuitive user interface. Below is the core code for the user interface:

@Builder
pageContentBuilder() {
  Column() {
    Text('Select the file for sports records:')
      .fontSize(20)
      .margin({ top: 20, bottom: 10 })
      .width('100%')
      .textAlign(TextAlign.Center);

    // File selection area
    Column() {
      if (!this.selectedFilePath) {
        Image($r('app.media.szxd_sport_home_setting_icon')) // Replace with your file icon resource
          .width(80)
          .height(80)
          .margin({ bottom: 10 });
      }

      Text(this.selectedFilePath ? this.fileName : 'Please select a file')
        .fontSize(16)
        .width('90%')
        .height(40)
        .backgroundColor('#f0f0f0')
        .borderRadius(8)
        .padding(10)
        .textAlign(TextAlign.Center)
        .margin({ bottom: 10 });
    }
    .width('90%')
    .height(150)
    .border({ width: 1, color: '#ddd', style: BorderStyle.Dashed })
    .borderRadius(8)
    .justifyContent(FlexAlign.Center)
    .onClick(() => this.selectFile())
    .margin({ bottom: 20 });

    // File information display
    this.fileInfoBuilder();

    // Select file button
    Button(this.selectedFilePath ? 'Re-select file' : 'Select file')
      .onClick(() => this.selectFile())
      .width('60%')
      .height(40)
      .fontSize(16)
      .backgroundColor('#007dff')
      .borderRadius(8)
      .opacity(this.isLoading ? 0.5 : 1)
      .enabled(!this.isLoading);

    // Upload button (if upload functionality is available)
    if (this.selectedFilePath) {
      Button('Upload file')
        .onClick(() => this.uploadFile())
        .width('60%')
        .height(40)
        .fontSize(16)
        .backgroundColor('#07c160')
        .borderRadius(8)
        .margin({ top: 20 })
        .opacity(this.isLoading ? 0.5 : 1)
        .enabled(!this.isLoading);
    }
  }
  .width('100%')
  .height('100%')
  .justifyContent(FlexAlign.Start)
  .alignItems(HorizontalAlign.Center);
}

Core Points Analysis

File Selection Area: Display the status of file selection using Image and Text components, triggering file selection logic when the user clicks.
File Information Display: Display the file's name and size information using Text components.
Select File Button: Allows users to re-select a file.
Upload Button: Allows users to upload the selected file.

IV. Summary

Using HarmonyOS's DocumentViewPicker and related file operation APIs, we can easily implement the feature for selecting sports records.

HarmonyOS Sports Development: Creating Your Personal Sports MetronomeCore HarmonyOS Technology

zhonghua — Mon, 09 Jun 2025 07:37:34 +0000

## Sports Development ## Media Kit (Media Services)

Foreword

Maintaining a steady rhythm during exercise is crucial for enhancing the effectiveness of your workout. Whether you're running, cycling, or engaging in high-intensity interval training (HIIT), a precise metronome can help you better control your exercise rhythm, thereby achieving better training results. This article will delve into how to develop a sports metronome, combining practical HarmonyOS development experience, allowing you to easily master the rhythm during exercise.

I. Why Choose SoundPool Over AVPlayer

When developing the sports metronome, we opted for SoundPool instead of AVPlayer. This is because SoundPool excels at playing short, sharp提示 sounds, capable of responding quickly and ensuring the timely playback of sound effects, which is vital for a sports metronome that requires precise rhythm control. In contrast, AVPlayer is more suitable for playing long audio files, such as music or videos, and its responsiveness and immediacy in sound effect playback are not as good as SoundPool.

II. Core Logic of the Sports Metronome

Initializing Sound Effects

Before the metronome starts, we need to load the sound effect files and initialize the SoundPool. Below is the core code for initializing sound effects:

async initSound() {
  this.soundPool = await media.createSoundPool(1, {
    usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music
    rendererFlags: 1
  });

  const context = getContext(this) as common.UIAbilityContext;
  const fd = context.resourceManager.getRawFdSync('medias/metronome2.mp3'); // It is recommended to use a short "tick" sound
  this.soundId = await this.soundPool.load(
    fd.fd,
    fd.offset,
    fd.length
  );
}

Metronome Playback Logic

The core logic of the metronome is to play sound effects at regular intervals based on the set BPM (beats per minute) and trigger visual cues (such as flashing) each time it plays. Below is the core code for the metronome playback logic:

startMetronome() {
  if (this.isPlaying) return;

  this.isPlaying = true;
  const interval = 60000 / this.bpm; // Beat interval

  const playWithFlash = () => {
    this.flashActive = true;
    setTimeout(() => this.flashActive = false, 100); // Set flashActive to false after 100 milliseconds to restore the visual state.

    if (this.soundPool && this.soundId !== -1) {
      this.soundPool.play(this.soundId, {
        loop: 0,
        rate: 1.0,
        leftVolume: 1.0, // Maximum volume to ensure it can be heard during exercise
        rightVolume: 1.0,
        priority: 0
      });
    }

    this.timerId = setTimeout(playWithFlash, interval);
  };

  playWithFlash();
}

Stopping the Metronome

When stopping the metronome, we need to clear the timer and release the SoundPool resources. Below is the core code for stopping the metronome:

stopMetronome() {
  this.isPlaying = false;
  clearTimeout(this.timerId);
}

III. User Interface Design

To allow users to conveniently control the metronome, we need to design a simple and intuitive user interface. Below is the core code for the user interface:

build() {
  Column() {
    // Large visual cue area
    Circle()
      .width(200)
      .height(200)
      .fill(this.flashActive ? Color.Red : Color.White)
      .margin({ bottom: 40 })
      .animation({ duration: 50, curve: Curve.EaseIn })

    // Extra-large BPM display
    Text(`${this.bpm}`)
      .fontSize(60)
      .fontWeight(FontWeight.Bold)
      .margin({ bottom: 30 })

    // Sports-specific BPM range slider
    Slider({
      value: this.bpm,
      min: 40,  // Lowest effective sports rhythm
      max: 200, // High-intensity interval training upper limit
      step: 1
    })
      .width('90%')
      .height(60)
      .onChange((value: number) => {
        this.bpm = value;
        if (this.isPlaying) {
          this.stopMetronome();
          this.startMetronome();
        }
      })

    // Sports-specific control button
    Button(this.isPlaying ? 'Stop Exercise' : 'Start Exercise')
      .width(200)
      .height(80)
      .fontSize(24)
      .backgroundColor(this.isPlaying ? Color.Red : Color.Green)
      .onClick(() => {
        this.isPlaying ? this.stopMetronome() : this.startMetronome();
      })
  }
  .width('100%')
  .height('100%')
  .justifyContent(FlexAlign.Center)
}

Key Points Analysis

Visual Cue: Implement visual beat cues using the Circle component and the flashActive state.
BPM Display: Display the current BPM value using the Text component, allowing users to intuitively see the beat frequency.
BPM Adjustment: Allow users to adjust the BPM value using the Slider component, and automatically update the metronome frequency after adjustment.
Control Button: Implement the start and stop functions of the metronome using the Button component.

IV. Optimization and Improvement

Setting the Metronome Frequency Based on Exercise Step Frequency

To better adapt to the user's exercise rhythm, we can dynamically adjust the metronome frequency based on the user's step frequency. I previously wrote an article on how to obtain step frequency and stride length.

private async updateBpmFromStepFrequency() {
  // Get the current step frequency
  const currentStepFrequency = await this.getStepFrequency();
  this.bpm = Math.round(currentStepFrequency * 60); // Convert step frequency to BPM
  if (this.isPlaying) {
    this.stopMetronome();
    this.startMetronome();
  }
}

Adding Sound Effect Selection Functionality

To meet the needs of different users, we can add sound effect selection functionality, allowing users to choose different提示 sounds. For example, provide multiple sound effect files for users to choose from.

private soundOptions: string[] = ['metronome1.mp3', 'metronome2.mp3', 'metronome3.mp3'];
private selectedSoundIndex: number = 0;

private async loadSound() {
  const context = getContext(this) as common.UIAbilityContext;
  const fd = context.resourceManager.getRawFdSync(`medias/${this.soundOptions[this.selectedSoundIndex]}`);
  this.soundId = await this.soundPool.load(
    fd.fd,
    fd.offset,
    fd.length
  );
}

Optimizing Visual Cue Effects

To enhance the user experience, we can further optimize the visual cue effects, such as adding animation effects or changing the cue color.

Circle()
  .width(200)
  .height(200)
  .fill(this.flashActive ? Color.Red : Color.White)
  .margin({ bottom: 40 })
  .animation({ duration: 100, curve: Curve.EaseInOut }) // Add animation effects

V. Summary

Using HarmonyOS's SoundPool and related APIs, we can easily develop a powerful sports metronome.

Practical Development of HarmonyOS NEXT: Implementing Efficient Pull-Down Refresh and Pull-Up Load Components (Part II)

zhonghua — Sun, 08 Jun 2025 09:00:28 +0000

Practical Development of HarmonyOS NEXT: Implementing Efficient Pull-Down Refresh and Pull-Up Load Components (Part II) Core Logic of Refresh and Integration with Empty Pages

Foreword:
In the previous article, we delved into how to implement a fully functional empty page component in HarmonyOS. Now, we will move on to the core logic implementation of pull-down refresh and pull-up load features. This is not just about technical implementation, but more importantly, it is about a deep understanding of user experience. This article will detail how to integrate empty pages with the logic of pull-down refresh and pull-up load to create an efficient and user-friendly interactive experience.

I. Building the Core Logic
When developing pull-down refresh and pull-up load features, we first need to define several key fields: the total number of pages, the starting page number, and the number of data entries per page. These fields are the foundation for pagination requests and the starting point for our logic implementation.

So in our core utility class, we need to make the network request into a function parameter for external requests.
Code Example:

private requestData:(currentPage:number,pageSize:number)=>void

Next, we need to implement external call listeners so that our loading logic can communicate with the outside. This includes refresh completion, load completion, empty data listening, etc.

Code Example:

export interface PullRefreshListener<T> {
  refreshCompleted:()=>void; 
  loadMoreCompleted:()=>void;
  emptyPage:()=>void;
  setData:(data:T[], isRefreshLast:boolean)=>void;
  lastData:()=>void;
  moreLoadFail:(error:BaseError)=>void;
  onLoadFail:(error:BaseError)=>void;
}

II. Implementation of Pull-Down Refresh and Pull-Up Load
When implementing pull-down refresh and pull-up load, we need to consider various states, including empty data and load errors. The core logic includes determining whether the data is empty, whether the last page has been reached, and how to handle load errors.

Core Logic Code:

import { BaseError } from '@kangraoo/baselibrary/src/main/ets/exception/NetworkError';
import { Log } from '@kangraoo/utils';

export interface PullRefreshListener<T> {
  refreshCompleted:()=>void;
  loadMoreCompleted:()=>void;
  emptyPage:()=>void;
  setData:(data:T[], isRefreshLast:boolean)=>void;
  lastData:()=>void;
  moreLoadFail:(error:BaseError)=>void;
  onLoadFail:(error:BaseError)=>void;
}

export class PullRefreshList<T>{

  // Total number of pages
  readonly PAGE_COUNT_SIZE:number = 10
  // Current page number
  readonly CURRENT_PAGE:number = 1

  private isRefreshLast:boolean = true
  // Start
  private currentPage:number
  // Page number
  private pageSize: number

  // Network request data
  private requestData:(currentPage:number,pageSize:number)=>void

  private pullRefreshListener:PullRefreshListener<T>;

  constructor(requestData: (currentPage: number, pageSize: number) => void, pullRefreshListener: PullRefreshListener<T>
    ,currentPage?: number, pageSize?: number) {
    this.currentPage = currentPage??this.CURRENT_PAGE;
    this.pageSize = pageSize??this.PAGE_COUNT_SIZE;
    this.requestData = requestData;
    this.pullRefreshListener = pullRefreshListener;
  }

  private makeCurrentPage(){
    this.currentPage++;
    Log.debug(`Current ${this.currentPage}`);
    this.isRefreshLast = false;
  }

  // Refresh
  refreshData() {
    this.isRefreshLast = true;
    this.currentPage = 1;
    this.requestData(this.currentPage,this.pageSize);
  }

  /// Refresh the already loaded data (only when data exists)
  refreshLoadData(){
    this.isRefreshLast = true;
    Log.debug(`Current${this.currentPage} Total ${this.pageSize}*${this.currentPage}`);
    this.requestData(1,this.pageSize*(this.currentPage--));
  }

  /// Load more
  loadMore() {
    this.isRefreshLast = false;
    this.requestData(this.currentPage,this.pageSize);
  }


  dataError(error:BaseError) {
    this.pullRefreshListener.loadMoreCompleted();
    this.pullRefreshListener.refreshCompleted();
    if (this.isRefreshLast) {
      this.pullRefreshListener.onLoadFail(error);
    } else {
      this.pullRefreshListener.moreLoadFail(error);
    }
  }



  dataSucces(data:T[]|null, total:number) {
    this.pullRefreshListener.loadMoreCompleted();
    this.pullRefreshListener.refreshCompleted();
    if (total === 0) {
      if (this.isRefreshLast) {
        this.pullRefreshListener.setData([], this.isRefreshLast);
        this.pullRefreshListener.emptyPage();
      }
    } else {
      if (data === null || data.length===0) {
        if (this.isRefreshLast) {
          this.pullRefreshListener.setData([], this.isRefreshLast);
          this.pullRefreshListener.emptyPage();
        }
      } else {
        Log.debug(`page${this.currentPage},total${total}`);
        this.pullRefreshListener.setData(data, this.isRefreshLast);
        if (this.pageSize * this.currentPage >= total) {
          this.pullRefreshListener.lastData();
        }
        this.makeCurrentPage();
      }
    }
  }


}

III. Component Selection and Basic Logic
Choosing the right components is crucial for implementing pull-down refresh and pull-up load. We have chosen the system component Refresh, which provides natural pull-down refresh handling and page customization features.

To achieve this, we need to integrate the empty page from the previous article with the Refresh component.

First, let's familiarize ourselves with a few variables:

Empty page state: layoutType
Pull-up refresh completion: finished
Pull-up loading: loading
Pull-down refresh: isRefreshing
Refresh status: refreshStatus

Next, let's get to know a few methods:

The content wrapped by pull-down refresh, usually a list or other list-like component: content
The method called on pull-down: onRefreshing
The method called when the refresh button on the empty page is clicked: onButtonRefreshing

Core Code:

@Preview
@Component
export struct PullRefreshWidget {

  public mCmpController: PullRefreshController|null = null;

  aboutToAppear(): void {
    if (this.mCmpController!=null) {
      this.mCmpController.attach(this); // Bind the controller
    }
  }

  @State isRefreshing: boolean = false
  @State
  refreshStatus: RefreshStatus = RefreshStatus.Inactive
  @Link finished: boolean

  @Link loading: boolean

  @Link moreLoadFail: boolean

  @BuilderParam
  content:()=>void

  onRefreshing?:()=>void

  onButtonRefreshing?:()=>void



  @Builder
  baseRefresh(){
    Refresh({
      refreshing : $$this.isRefreshing,
      builder: this.customRefreshComponent()
    }){
      this.content()
    }.onRefreshing(()=>{
      if(this.onRefreshing){
        this.onRefreshing()
      }
    })
    .onStateChange(async (status) => {
      this.refreshStatus = status
    })
    .height("100%")
  }

  @State
  layoutType : EmptyStatus =  EmptyStatus.none

  build() {
    EmptyWidget({
      child : ()=>{
        this.baseRefresh()
      },
      layoutType : this.layoutType,
      refresh : ()=>{
        if(this.onButtonRefreshing){
          this.onButtonRefreshing()
        }
      }
    })

  }

  @Builder
  customRefreshComponent()
  {
    Stack()
    {
      Row()
      {
        LoadingProgress().height(32)
        Text(this.getTextByStatus()).fontSize(16).margin({left:20})
      }
      .alignItems(VerticalAlign.Center)
    }
    .align(Alignment.Center)
    .clip(true)
    .constraintSize({minHeight:32}) // Set minimum height constraint to ensure the custom component's height does not fall below minHeight when the refresh area's height changes
    .width("100%")
  }

  getTextByStatus() {
    switch (this.refreshStatus) {
      case RefreshStatus.Drag:
        return Application.getInstance().resourceManager.getStringSync($r("app.string.continue_pull_down").id)
      case RefreshStatus.OverDrag:
        return Application.getInstance().resourceManager.getStringSync($r("app.string.release_to_load").id)
      case RefreshStatus.Refresh:
        return Application.getInstance().resourceManager.getStringSync($r("app.string.loading").id)
    }
    return ""
  }

}

export class PullRefreshController{

  private mComponent: PullRefreshWidget | null = null;

  attach(component: PullRefreshWidget) {
    this.mComponent = component;
  }
  refreshCompleted(){
    if(this.mComponent!=null){
      this.mComponent.isRefreshing = false;
    }
  }
  loadMoreCompleted() {
    if(this.mComponent!=null){
      this.mComponent.finished = false
      this.mComponent.moreLoadFail = false
      this.mComponent.loading = false
    }
  }
  lastData(){
    if(this.mComponent!=null){
      this.mComponent.finished = true
    }
  }
  moreLoadFail(){
    if(this.mComponent!=null){
      this.mComponent.moreLoadFail = true;
    }
  }
  emptyPage(){
    if(this.mComponent!=null){
      this.mComponent.layoutType = EmptyStatus.nodata
    }
  }
  nonePage(){
    if(this.mComponent!=null){
      this.mComponent.layoutType = EmptyStatus.none
    }
  }
  onLoadFail(){
    if(this.mComponent!=null){
      this.mComponent.layoutType = EmptyStatus.fail
    }
  }

}

IV. Data Source Selection and Implementation
In business terms, to use a waterfall flow, I adopted WaterFlow as the data component. At the same time, we implemented a data source class to support dynamic data loading and updating.

First, since I used LazyForEach for the data source, I need to create a wrapper class.

BasicDataSource implements IDataSource to handle data listeners.

// Basic implementation of IDataSource to handle data listener
export class BasicDataSource<T> implements IDataSource {
  private listeners: DataChangeListener[] = [];

  private originDataArray: T[] = [];

  public totalCount(): number {
    return this.originDataArray.length;
  }
  public getData(index: number): T {
    return this.originDataArray[index];
  }

  // Register a data change listener
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener)
    }
  }

  // Unregister a data change listener
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener)
    if (pos >= 0) {
      this.listeners.splice(pos, 1)
    }
  }

  // Notify the listener of data reload
  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded()
    })
  }

  // Notify the listener of data addition
  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index)
    })
  }

  // Notify the listener of data change
  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index)
    })
  }

  // Notify the listener of data deletion
  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index)
    })
  }

  // Notify the listener of data movement
  notifyDataMove(from: number, to: number): void {
    this.listeners.forEach(listener => {
      listener.onDataMove(from, to)
    })
  }

  // Add a data entry at the specified position
  public addData(index: number, data: T): void {
    this.originDataArray.splice(index, 0, data);
    this.notifyDataAdd(index);
  }

  // Add a data entry at the first position
  public add1stItem(data: T): void {
    this.addData(0,data)
  }

  // Add a data entry
  public pushData(data: T): void {
    this.originDataArray.push(data);
    this.notifyDataAdd(this.originDataArray.length - 1);
  }

  // Delete a data entry at the specified index
  public deleteItem(index: number): void {
    this.originDataArray.splice(index, 1)
    this.notifyDataDelete(index)
  }

  // Delete the first data entry
  public delete1stItem(): void {
    this.deleteItem(0)
  }

  // Delete the last data entry
  public deleteLastItem(): void {
    this.originDataArray.splice(-1, 1)
    this.notifyDataDelete(this.originDataArray.length)
  }

  // Clear data
  public clearData () {
    this.originDataArray = []
    this.notifyDataReload()
  }

  // Set new data
  public setData(dataArray: T[]){
    this.originDataArray = dataArray
    this.notifyDataReload()
  }

  // Add list data
  public addDatas(dataArray: T[]){
    let l = this.originDataArray.length
    this.originDataArray.push(...dataArray)
    this.notifyDataAdd(l-1)
    // this.originDataArray.push(...dataArray)
    // this.notifyDataReload()
  }

}

My data class is ExperienceListResponse, and I need to implement this data source.

class WaterFlowDataSource extends BasicDataSource<ExperienceListResponse> {

}

V. Complete Pull-Down Refresh Implementation
Finally, we integrate all components and logic to implement a complete pull-down refresh feature. This includes data loading, state updates, and handling user interactions.

Complete Code:

@Component
export struct MyPullRefreshWidget{

  @State list:ExperienceListResponse[] = []

  dataSource: WaterFlowDataSource = new WaterFlowDataSource()

  mCmpController: PullRefreshController = new PullRefreshController()

  pullRefreshList :PullRefreshList<ExperienceListResponse> = new PullRefreshList((currentPage,pageSize)=>{
    setTimeout(()=>{
      QuickResponsitory.getInstance().experienceList(currentPage,pageSize).then(value=>{
        LibLoading.hide();
        if (value instanceof SuccessData) {
          let data = value as (SuccessData<ApiResult<ExperienceListResponse[]>>)
          this.list = data.data?.data ?? []
          this.pullRefreshList.dataSucces(this.list,data.data?.page?.totalCount??0)
        } else if (value instanceof ErrorData) {
          this.pullRefreshList.dataError(value.error)
        }
      })
    },1000)

  },{
    refreshCompleted:()=>{
      this.mCmpController.refreshCompleted()
    },
    loadMoreCompleted:()=> {
      this.mCmpController.loadMoreCompleted()
    },
    emptyPage:()=> {
      this.mCmpController.emptyPage()
    },
    setData:(data:ExperienceListResponse[], isRefreshLast:boolean)=>{
      if(isRefreshLast){
        this.mCmpController.nonePage()
        this.dataSource.setData(data)
      }else{
        this.dataSource.addDatas(data)
      }
    },
    lastData:()=> {
      this.mCmpController.lastData()
    },
    moreLoadFail:(error:BaseError)=>{
      this.mCmpController.moreLoadFail()
    },
    onLoadFail:(error:BaseError)=>{
      this.mCmpController.onLoadFail()
    }
  })

  aboutToAppear(): void {
    LibLoading.show();
    this.pullRefreshList.refreshData()
  }

  @State finished: boolean = false // Whether the loading is complete

  @State loading: boolean = false

  @State moreLoadFail: boolean = false

  @Builder
  itemFoot() {
    if (this.finished) {
      Row() {
        Text($r("app.string.no_more_data"))
          .fontSize(12)
      }
      .width("100%")
      .height(40)
      .justifyContent(FlexAlign.Center)
    } else {
      if (this.loading) {
        // Loading in progress
        Row({ space: 10 }) {
          Text($r("app.string.loading_data"))
            .fontSize(12)
          LoadingProgress()
            .width(20)
            .height(20)
        }
        .width("100%")
        .height(40)
        .justifyContent(FlexAlign.Center)
      }else {
        if(this.moreLoadFail){
          Row() {
            Text($r("app.string.data_loading_failed"))
              .fontSize(12)
          }
          .width("100%")
          .height(40)
          .justifyContent(FlexAlign.Center)
        }
      }
    }
  }

  @Builder
  dataContent(){
    WaterFlow({footer:this.itemFoot()}){
      LazyForEach(this.dataSource,(item:ExperienceListResponse,index:number)=>{
        FlowItem(){
          ExperienceListItem({experience:item}).padding(4)
        }
      },(item:ExperienceListResponse,index:number)=>{
        return item.id
      })
    }
    .layoutDirection(FlexDirection.Column)
    .columnsTemplate("1fr 1fr")
    .onReachEnd(()=>{
      // Valve control
      if (!this.loading && !this.finished) {
        this.loading = true
        this.pullRefreshList.loadMore()
      }
    })
  }

  build() {
    PullRefreshWidget({
      mCmpController:this.mCmpController,
      content:()=>{
        this.dataContent()
      },
      onRefreshing:()=>{
        this.pullRefreshList.refreshData()
      },
      onButtonRefreshing:()=>{
        LibLoading.show();
        this.pullRefreshList.refreshData()
      }
    ,finished:this.finished,loading:this.loading,moreLoadFail:this.moreLoadFail})
  }
}

V. In-Depth Analysis and Experience Sharing

During the implementation of pull-down refresh and pull-up load, I encountered some challenges, such as how to ensure the smoothness of data loading, how to handle network request exceptions, and how to effectively integrate with empty pages. Through continuous testing and optimization, we found some solutions that make the entire component not only powerful but also provide a good user experience.

Summary:
Through this article, we have not only learned how to implement the core logic of pull-down refresh and pull-up load in HarmonyOS, but also understood how to integrate these logics with the empty page component to provide a richer and smoother user experience.

Practical Development of HarmonyOS NEXT: Creating Efficient Pull-Up Refresh and Pull-Down Load Components (Part I)

zhonghua — Sun, 08 Jun 2025 08:58:58 +0000

Practical Development of HarmonyOS NEXT: Creating Efficient Pull-Up Refresh and Pull-Down Load Components (Part I) Design and Implementation of Empty Pages

Foreword:

In the world of HarmonyOS development, user experience is crucial. I searched online and found that existing pull-up refresh and pull-down load components are either incomplete in functionality or not elegant enough. Therefore, I decided to create a set of components that are both aesthetically pleasing and practical. This series of articles will delve into how to use HarmonyOS system components to encapsulate excellent pull-up refresh and pull-down load controls. Today, we will start with the development of empty pages and explore how to implement this feature in HarmonyOS.

Page Display

Pull-Down Refresh Display Effect:

I. The Importance of Empty Pages and Basic Logic

Empty pages play a vital role in applications, not only for pull-up refresh and pull-down load but also to provide user-friendly feedback before data loading. We divide empty pages into three states: failure view, no data view, and normal data view. Each state has its specific display logic.

Code Display:

export enum EmptyStatus {
  fail, // Failure view
  nodata, // No data view
  none // Normal data view
}

Display Logic:

if(this.layoutType === EmptyStatus.none){
  // Normal page
}else{
  // Exception page
}

II. Flexibility of Resource Replacement

To make the component more flexible, we allow developers to customize the images and text of the empty page by replacing resources with the same name. Whether it's a network anomaly or no data, developers can easily make personalized settings.

Code Example:

Image($r("app.media.emptypage_net_error")).width(100)
Text($r("app.string.emptypage_net_error"))
Image($r("app.media.emptypage_no_data")).width(100)
Text($r("app.string.emptypage_no_data"))

III. Implementation of Button Refresh

We provide an external refresh function for the component so that data can be reloaded when the user clicks the refresh button.

Code Example:

refresh? : () => void

IV. Complete Code Display

Below is the complete code for the empty page component, including the definition of resource files and the implementation of the component.

Resource File:

{
  "name": "emptypage_net_error",
  "value": "Oops，遇到问题了，刷新试试"
},
{
  "name": "emptypage_no_data",
  "value": "暂时没有任何数据，去别处看看吧"
},

All Code for Empty Page:

export enum EmptyStatus {
  fail, // Failure view
  nodata, // No data view
  none // Normal data view
}

@Preview
@Component
export struct EmptyWidget{
  @BuilderParam @Require
  child : () => void

  refresh? : () => void

  @Link layoutType : EmptyStatus

  build() {
    Stack({alignContent:Alignment.Center}){
      if(this.layoutType === EmptyStatus.none){
        this.child()
      }else{
        Column(){
          if(this.layoutType === EmptyStatus.fail){
            Image($r("app.media.emptypage_net_error")).width(100)
            Text($r("app.string.emptypage_net_error"))
          }else if(this.layoutType === EmptyStatus.nodata){
            Image($r("app.media.emptypage_no_data")).width(100)
            Text($r("app.string.emptypage_no_data"))
          }
          Button($r("app.string.emptypage_refresh"))
            .margin({top:10})
            .onClick(()=>{
            this.pressedReload()
          })
        }
        .justifyContent(FlexAlign.Center)
        .backgroundColor(Color.White)
        .width("100%")
        .height("100%")
      }
    }.width("100%")
    .height("100%")
  }

  private pressedReload(){
    if(!LibNetworkStatus.getInstance().isNetworkAvailable()){
      LibToast.show(Application.getInstance().resourceManager.getStringSync($r("app.string.network_no_connect").id))
    }else{
      if(this.refresh){
        this.refresh()
      }
    }
  }
}

Summary:

Through this article, we have not only learned how to implement a fully functional empty page component in HarmonyOS but also understood how to enhance the flexibility and practicality of the component through resource replacement and external function calls. This is just the beginning of our HarmonyOS development series. The following articles will delve into the implementation of pull-up load and pull-down refresh. Stay tuned.

The Secret to Developing HarmonyOS: Creating an Elegant Login Status Management System

zhonghua — Sun, 08 Jun 2025 08:55:24 +0000

The Secret to Developing HarmonyOS: Creating an Elegant Login Status Management System

I. Foreword
During the development process of HarmonyOS, as the scale of the application grows, login status management gradually becomes a challenge in system design. A clear and efficient login status management system can not only simplify the development process but also enhance the user experience. This article will share an elegant login status management design scheme to help developers easily deal with login status control in complex systems.

II. Authentication Events and Authentication Code Design
Authentication events are the core of global application events, triggering login or logout operations and can be broadcast throughout the project. We have defined three basic authentication events: app start, login, and logout.

Authentication event code example:

export class AuthenticationEvent {
  static readonly AppStart = "$AppStart$";
  static readonly LogIn = "$LogIn$";
  static readonly LogOut = "$LogOut$";
}

III. Authentication Status
User authentication status is key for the system to determine whether a user is logged in. We have defined two states: authenticated and unauthenticated.

Authentication status code example:

export const AUTHENTICATION_STATE:string = "$AuthenticationState$"

// Authentication state
export class AuthenticationState {}

// - authenticated - Authentication successful
export class AuthenticationAuthenticated extends AuthenticationState {}

// - unauthenticated - Not authenticated
export class AuthenticationUnauthenticated extends AuthenticationState {}

IV. Authentication Interface Template
The authentication interface is the specific implementation of login status management, including token checking, saving, and deletion, as well as page redirection when authenticated and unauthenticated.

Authentication interface code example:

const TOKEN = "token";

export abstract class IUserAuthentication {
  libPreferencesSync: LibPreferencesSync;

  hasToken(): boolean {
    return this.libPreferencesSync.getValue(TOKEN).toString().length > 0;
  }

  saveToken(token: string) {
    this.libPreferencesSync.saveKeyValue(TOKEN, token);
  }

  deleteToken() {
    this.libPreferencesSync.deleteData(TOKEN);
  }

  abstract authPage(): void;
  abstract unAuthPage(): void;
}

V. Pages for Managing Login Status
Through the event hub, we can notify the global status throughout the application. The login status manager changes the authentication status based on the events sent by the user.

export class Authentication {
  // Private static variable to save the singleton object
  private static _instance :Authentication;

  // Private constructor to prevent direct instantiation from outside
  private constructor() {
    // Constructor content
  }

  // Static method to get the singleton object
  public static getInstance() {
    if (!Authentication._instance) {
      Authentication._instance = new Authentication();
    }
    return Authentication._instance;
  }

  startApp(){
    Application.getInstance().applicationContext.eventHub.emit(AuthenticationEvent.AppStart)
  }

  logIn(token:string){
    Application.getInstance().applicationContext.eventHub.emit(AuthenticationEvent.LogIn,token)
  }

  logOut(){
    Application.getInstance().applicationContext.eventHub.emit(AuthenticationEvent.LogOut)
  }

  init(iuserAuthentciation : IUserAuthentication){
    Application.getInstance().applicationContext.eventHub.on(AuthenticationEvent.AppStart,()=>{
      if(iuserAuthentciation.hasToken()){
        AppStorage.setOrCreate(AUTHENTICATION_STATE,new AuthenticationAuthenticated())
        iuserAuthentciation.authPage();
      }else{
        AppStorage.setOrCreate(AUTHENTICATION_STATE,new AuthenticationUnauthenticated())
        iuserAuthentciation.unAuthPage();
      }
    })
    Application.getInstance().applicationContext.eventHub.on(AuthenticationEvent.LogIn,(token:string)=>{
      iuserAuthentciation.saveToken(token)
      AppStorage.set(AUTHENTICATION_STATE,new AuthenticationAuthenticated())
      iuserAuthentciation.authPage();
    })
    Application.getInstance().applicationContext.eventHub.on(AuthenticationEvent.LogOut,()=>{
      iuserAuthentciation.deleteToken()
      AppStorage.set(AUTHENTICATION_STATE,new AuthenticationUnauthenticated())
      iuserAuthentciation.unAuthPage();
    })
  }
}

VI. Usage in Projects
In projects, we initialize the login status manager and change the page style or behavior based on the authentication status in the pages.

Project usage code example:

class Auth extends IUserAuthentication {
  // ... Implement specific login and non-login page redirection logic
}

// Initialization
Authentication.getInstance().init(new Auth());

// Usage in pages
aboutToAppear(): void {
  this.authentication();
}

authentication() {
  if (this.authetication instanceof AuthenticationAuthenticated) {
    // Get user data
  } else if (this.authetication instanceof AuthenticationUnauthenticated) {
    // Delete user data
  }
}

VII. Summary
Through the sharing in this article, we have learned how to design and implement an elegant login status management system in HarmonyOS. From the design of authentication events to the management of authentication status and the specific implementation of the authentication interface, each step is aimed at simplifying the development process and improving the robustness and maintainability of the system. It is hoped that this article can provide practical references and inspiration for HarmonyOS developers.