DEV Community: xhunmon

ZeroOneApp Privacy Agreement Checkbox Component: Design and Implementation

xhunmon — Thu, 26 Jun 2025 14:24:10 +0000

Introduction

In mobile application development, the consent mechanism for privacy policies and user agreements is a crucial环节 to protect user rights and comply with regulatory requirements. The PrivacyCheckbox component in ZeroOneApp provides a fully functional and user-friendly solution for privacy agreement consent. This article will detailedly analyze its design philosophy, implementation details, and best practices.

Core Component Architecture

The PrivacyCheckbox component is located in the project's common/ui module at the path common/ui/src/main/ets/components/PrivacyCheckbox.ets. It is a custom component developed based on the HarmonyOS ArkUI framework. The component mainly consists of the following parts:

File Structure

common/ui/src/main/ets/components/
└── PrivacyCheckbox.ets  # Privacy agreement checkbox component

Core Dependencies

The component depends on utility classes and resource management modules in the project:

IntentUtil: Used to handle page navigation after rich text clicks
ResColor: Provides unified color resource management
loginComponentManager: Defines the data structure and types for privacy text

Component Implementation Details

1. Component Property Definition

The component defines rich configurable parameters to support requirements in different scenarios:

@ComponentV2
export struct PrivacyCheckbox {
  // Agreement content array
  @Param texts: loginComponentManager.PrivacyText[] = [];
  // Whether the agreement is checked
  @Param isCheckboxSelected: boolean = false;
  // Checkbox state change event
  @Event boxChange: (select: boolean) => void;
  // Unselected state animation trigger counter
  @Param unselectAnimalCount: number = 0;
  // Custom rich text click event
  @Event onCustomItemClick?: (item: loginComponentManager.PrivacyText) => void;
  // Animation-related properties
  @Local translateX: number = 0;
}

2. UI Structure Design

The component adopts a Row-nested-Row layout structure to achieve horizontal arrangement of checkbox and text:

build() {
  Row() {
    // Checkbox part
    Row() {
      Checkbox(...) // Checkbox implementation
    }

    // Text content part
    Row() {
      Text() {
        ForEach(this.texts, (item: loginComponentManager.PrivacyText) => {
          // Render different styles according to text type
        })
      }
    }
    .layoutWeight(1)
    .margin({ left: 12 })
  }
  .width('100%')
  .alignItems(VerticalAlign.Top)
  .justifyContent(FlexAlign.Start)
}

3. Core Checkbox Implementation

The checkbox is the core interactive element of the component, implementing state display, animation effects, and event callbacks:

Checkbox({ name: 'privacyCheckbox', group: 'privacyCheckboxGroup' })
  .width(24)
  .height(24)
  .focusable(true)
  .focusOnTouch(true)
  .selectedColor(ResColor.themeLight())
  .margin({ top: 0 })
  .select(this.isCheckboxSelected)
  .unselectedColor(this.translateX === 0 ? Color.Gray : Color.Red)
  .translate({ x: this.translateX })
  .animation({ curve: curves.springMotion() })
  .onChange((value: boolean) => {
    this.boxChange(value);
    log.i(TAG, `agreementChecked: ${value}`);
  })

4. Rich Text Processing Mechanism

The component supports mixed display of plain text and rich text, and provides click interaction for rich text:

ForEach(this.texts, (item: loginComponentManager.PrivacyText) => {
  if (item?.type == loginComponentManager.TextType.PLAIN_TEXT && item?.text) {
    // Plain text rendering
    Span(item?.text)
      .fontColor(ResColor.desc())
      .fontWeight(FontWeight.Regular)
      .fontSize($r('sys.float.ohos_id_text_size_body3'))
  } else if (item?.type == loginComponentManager.TextType.RICH_TEXT && item?.text) {
    // Rich text rendering
    Span(item?.text)
      .fontColor(ResColor.themeLight())
      .fontWeight(FontWeight.Medium)
      .fontSize($r('sys.float.ohos_id_text_size_body3'))
      .focusable(true)
      .focusOnTouch(true)
      .onClick(() => {
        // Rich text click handling
      })
  }
})

5. Unselected State Animation

To enhance user experience, the component implements a shaking animation in the unselected state to remind users to check the agreement:

@Monitor('unselectAnimalCount')
checkAgreeAnimate() {
  if (this.isCheckboxSelected) {
    return;
  }
  let count = 10;
  let t = 0;
  const id = setInterval(() => {
    count -= 1;
    if (count === 0) {
      clearInterval(id);
      this.translateX = 1;
      return;
    }
    t += 30;
    this.translateX = 30 * Math.sin(t);
  }, 100)
}

Component Usage Methods

Basic Usage

PrivacyCheckbox({
  texts: [
    { type: TextType.PLAIN_TEXT, text: 'I have read and agree to the' },
    { type: TextType.RICH_TEXT, text: 'User Agreement', tag: 'user_agreement' },
    { type: TextType.PLAIN_TEXT, text: 'and' },
    { type: TextType.RICH_TEXT, text: 'Privacy Policy', tag: 'privacy_policy' }
  ],
  isCheckboxSelected: this.isAgree,
  onCustomItemClick: (item) => {
    // Custom click handling
  },
  boxChange: (isSelected) => {
    this.isAgree = isSelected;
    // Update button status and other operations
  }
})

Text Data Structure

The loginComponentManager.PrivacyText interface is defined as follows:

interface PrivacyText {
  type: TextType; // PLAIN_TEXT or RICH_TEXT
  text: string;  // Display text
  tag?: string;  // Identifier for navigation
}

Advanced Features and Best Practices

1. Custom Rich Text Click Handling

The onCustomItemClick event allows custom rich text click behavior, such as navigating to in-app pages instead of external links:

onCustomItemClick: (item) => {
  if (item.tag === 'user_agreement') {
    router.pushUrl({
      url: 'pages/UserAgreementPage'
    });
  } else if (item.tag === 'privacy_policy') {
    router.pushUrl({
      url: 'pages/PrivacyPolicyPage'
    });
  }
}

2. Form Validation Integration

It is recommended to use the component with form validation to ensure users check the agreement before proceeding:

Button('Register')
  .enabled(this.isAgree)
  .onClick(() => {
    // Execute registration logic
  })

3. Animation Trigger Timing

Trigger the unselected state animation by modifying the unselectAnimalCount property, typically used when users attempt to submit without checking the agreement:

if (!this.isAgree) {
  this.unselectCount += 1; // Trigger animation
  promptAction.showToast({
    message: 'Please read and agree to the privacy agreement'
  });
}

Summary and Outlook

The PrivacyCheckbox component provides a compliant and user-friendly privacy agreement consent solution through elegant design and comprehensive functionality. Its main advantages include:

Clear Structure: Adopts modular design with distinct code logic
User-Friendly Interaction: Provides intuitive visual feedback and animation effects
Highly Customizable: Supports custom text content, click behavior, and styles
Easy Integration: Simple API design for quick project integration

Future enhancement considerations:

Support for multilingual text display
Adding agreement content collapse/expand functionality
Implementing agreement version control mechanism
Supporting dark/light mode adaptation

Reference Resources

ZeroOneApp Loading Component: Advanced Customization and Best Practices

xhunmon — Thu, 26 Jun 2025 14:22:51 +0000

Introduction

As a crucial feedback mechanism for user interaction, the quality of loading components directly impacts the user experience of an application. Building upon its basic implementation, ZeroOneApp's loading component offers rich advanced customization capabilities and performance optimization strategies, meeting diverse requirements in complex application scenarios. This article will explore advanced customization techniques, performance optimization practices, and integration solutions with other system features for the loading component, helping developers create smoother, more personalized loading experiences.

Official Resources

ArkUI Custom Component Development Guide: Detailed instructions on building reusable, highly extensible custom components ArkUI Custom Component Documentation
HarmonyOS Performance Optimization Guide: Official recommendations for application performance tuning HarmonyOS Performance Optimization Documentation
Lottie Animation Advanced Features: Advanced usage and performance optimization techniques for Lottie animations Lottie Advanced Usage

Detailed Explanation

1. Advanced Style Customization Techniques

1.1 Complete Guide to Custom Loading Layouts

ZeroOneApp's loading component supports fully customized loading layouts through the layout property, implemented using ArkUI's WrappedBuilder. Here's an example of a complex custom layout:

// Custom loading layout example
const CustomLoadingLayout = wrapBuilder((message: string) => {
  Column() {
    // Custom animation component
    Image($r('app.media.loading_icon'))
      .width(60)
      .height(60)
      .animation({
        duration: 1000,
        curve: Curve.Linear,
        iterations: -1,
        playMode: PlayMode.Normal
      })
      .rotate({ angle: 360 })

    // Loading text
    Text(message || 'Loading data...')
      .fontSize(16)
      .fontColor($r('app.color.primary_text'))
      .margin({ top: 12 })

    // Cancel button
    Button('Cancel')
      .width(120)
      .height(36)
      .margin({ top: 20 })
      .onClick(() => {
        Loading.close();
      })
  }
  .padding(24)
  .backgroundColor(Color.White)
  .borderRadius(16)
  .shadow({
    radius: 10,
    color: Color.Black.withAlpha(0.1),
    offsetX: 0,
    offsetY: 4
  })
});

// Using custom layout
Loading.open({
  layout: CustomLoadingLayout,
  alignment: Alignment.Center,
  outsideCancel: true
});

Key technical points for custom layouts:

Wrap any UI structure with wrapBuilder to achieve complete layout customization
Combine with ArkUI's animation system to implement non-Lottie animation effects
Add interactive elements (like cancel buttons) to enhance user control
Beautify appearance with properties like padding, backgroundColor, and borderRadius
Add depth with shadow properties to improve visual experience

1.2 Global vs. Local Style Priority Mechanism

ZeroOneApp's loading component supports both global default styles and local call styles, following clear priority rules:

// 1. Global style initialization (at application startup)
Loading.initDefaultStyle({
  alignment: Alignment.Center,
  pressBackCancel: true,
  outsideCancel: false,
  outBoxAttr: {
    backgroundColor: Color.Black.withAlpha(0.5)
  }
});

// 2. Override specific styles when calling locally
Loading.open({
  // Only override properties that need modification, others use global configuration
  outsideCancel: true,
  alignment: Alignment.Bottom
});

Priority order (from highest to lowest):

LoadingStyle parameters passed during local calls
Globally initialized loadingStyle configuration
Component internal default values

This mechanism ensures style consistency within the application while allowing flexible adjustments for specific scenarios.

2. Advanced Lottie Animation Applications

2.1 Multi-animation Resource Management and Dynamic Switching

For complex applications requiring multiple loading animations, implement dynamic management of animation resources:

// Animation resource management utility class
class LottieAnimationManager {
  private static animations: Map<string, string> = new Map();

  // Preload animation resources
  static preloadAnimations(context: common.UIAbilityContext) {
    const animationFiles = ['loading_default.json', 'loading_success.json', 'loading_error.json'];
    const decoder = new util.TextDecoder('utf-8', { ignoreBOM: true });

    animationFiles.forEach(file => {
      context.resourceManager.getRawFile(file, (err, data) => {
        if (data?.buffer) {
          const jsonStr = decoder.decode(new Uint8Array(data.buffer));
          this.animations.set(file, jsonStr);
        }
      });
    });
  }

  // Get animation data
  static getAnimationData(key: string): object | undefined {
    const jsonStr = this.animations.get(key);
    return jsonStr ? JSON.parse(jsonStr) : undefined;
  }
}

// Custom Lottie loading component
@ComponentV2
struct CustomLottieLoading {
  @Prop animationKey: string = 'loading_default.json';
  // ...other properties and methods

  private createAnimation() {
    lottie.destroy();
    const animationData = LottieAnimationManager.getAnimationData(this.animationKey);
    if (animationData) {
      lottie.loadAnimation({
        container: this.mainCanvasRenderingContext,
        renderer: 'canvas',
        loop: this.animationKey === 'loading_default.json', // Only default animation loops
        autoplay: true,
        animationData: animationData,
        context: getContext() as common.UIAbilityContext
      });
    }
  }
}

Advantages of this implementation:

Preloading mechanism reduces animation display delay
Centralized management of multiple animation resources for easier maintenance
Supports dynamic switching between animations for different states (loading, success, error)
Non-looping animations for status prompts enhance interaction experience

2.2 Lottie Animation Performance Optimization

For performance issues that may arise with Lottie animations, implement the following optimization strategies in common/ui/src/main/ets/components/loading/LottieLoading.ets:

// Optimized LottieLoading component
@ComponentV2
export struct OptimizedLottieLoading {
  // ...other properties
  private animationInstance: any = null;
  private isAnimationLoaded: boolean = false;

  // Limit animation frame rate
  private frameRate: number = 30;
  private lastFrameTime: number = 0;

  @Monitor('isStartLoading')
  loadAnimation() {
    if (!this.isStartLoading) {
      this.destroyAnimation();
      return;
    }
    // Play directly if animation is already loaded to avoid re-creation
    if (this.isAnimationLoaded && this.animationInstance) {
      this.animationInstance.play();
      return;
    }
    this.createAnimation();
  }

  private createAnimation() {
    // ...original code
    this.animationInstance = lottie.loadAnimation({
      // ...configuration
      rendererSettings: {
        preserveAspectRatio: 'xMidYMid meet',
        clearCanvas: true
      }
    });
    this.isAnimationLoaded = true;

    // Custom frame rate control
    this.animationInstance.setSubframe(false);
    this.animationInstance.frameRate = this.frameRate;
  }

  private destroyAnimation() {
    if (this.animationInstance) {
      this.animationInstance.stop();
      // Keep instance but stop playback to avoid frequent destruction and creation
      // lottie.destroy()
    }
  }

  build() {
    Canvas(this.mainCanvasRenderingContext)
      .width('85%')
      .height('50%')
      .onDisappear(() => {
        this.destroyAnimation();
      })
  }
}

Key optimization points:

Avoid frequent destruction and creation of animation instances by using pause/play mode
Limit frame rate (e.g., 30fps) to reduce CPU usage
Disable subframe rendering (setSubframe(false)) to reduce drawing complexity
Properly set preserveAspectRatio to avoid unnecessary scaling calculations
Stop animations promptly when components disappear to release resources

3. Advanced Interaction and State Management

3.1 Decoupling Loading State from Business Logic

Implement decoupling of loading state and business logic through state management patterns:

// Loading state management class
class LoadingManager {
  private static loadingCount: number = 0;

  // Show loading with support for叠加计数
  static showLoading(options: LoadingStyle = {}): void {
    if (this.loadingCount === 0) {
      Loading.open(options);
    }
    this.loadingCount++;
  }

  // Hide loading, requires matching show count
  static hideLoading(): void {
    if (this.loadingCount > 0) {
      this.loadingCount--;
      if (this.loadingCount === 0) {
        Loading.close();
      }
    }
  }

  // Force hide all loading
  static forceHide(): void {
    this.loadingCount = 0;
    Loading.close();
  }
}

// Usage in business logic
class DataService {
  fetchData(): Promise<any> {
    LoadingManager.showLoading();
    return new Promise((resolve) => {
      // Network request
      net.post<DataResp>(API.data, {}, {
        onSuccess: (data) => resolve(data),
        onFail: () => resolve(null),
        onFinally: () => LoadingManager.hideLoading()
      });
    });
  }
}

This design solves the following problems:

Loading state conflicts with multiple concurrent requests
Avoid loading flicker caused by rapid consecutive calls
Unified management of all loading states in the application
Simplified loading control logic in business code

3.2 Integration with Routing and Page Lifecycle

Implement automatic association of loading state with page lifecycle:

// Integrate loading management in route interceptor
RouterUtil.addInterceptor({
  beforePush: (url: string) => {
    // Some pages need automatic loading display
    if (['DetailPage', 'ProfilePage'].includes(url)) {
      LoadingManager.showLoading();
    }
    return true;
  },
  afterPush: (url: string) => {
    // Automatically hide loading after page entry
    if (['DetailPage', 'ProfilePage'].includes(url)) {
      // Allow time for page initialization
      setTimeout(() => LoadingManager.hideLoading(), 300);
    }
  }
});

// Usage in page components
@Component
struct DetailPage {
  aboutToAppear() {
    // Start data loading when page appears
    this.loadData();
  }

  loadData() {
    // Loading already shown by route interceptor, no need to call again
    dataService.fetchDetail().then(data => {
      // Process data
    });
  }
}

4. Special Scenario Handling

4.1 Loading Strategies for Weak Network Environments

Optimize loading experience for weak network environments:

// Weak network detection utility
class NetworkQualityMonitor {
  static isWeakNetwork(): boolean {
    const netType = network.getCurrentType();
    const signal = network.getSignalStrength();
    // Determine based on network type and signal strength
    return netType === network.NetworkType.NETWORK_MOBILE && signal < 2 ||
           netType === network.NetworkType.NETWORK_WIFI && signal < 30;
  }
}

// Weak network loading configuration
const createWeakNetworkLoading = () => {
  return wrapBuilder(() => {
    Column() {
      LottieLoading()
      Text(NetworkQualityMonitor.isWeakNetwork() ? 'Poor network condition, still trying to load...' : 'Loading...')
        .fontSize(14)
        .margin({ top: 10 })
      if (NetworkQualityMonitor.isWeakNetwork()) {
        Button('Switch to Offline Mode')
          .margin({ top: 15 })
          .onClick(() => {
            AppState.switchOfflineMode();
            Loading.close();
          })
      }
    }
  });
};

// Use weak network adapted loading
Loading.open({
  layout: createWeakNetworkLoading(),
  pressBackCancel: true
});

4.2 Loading Timeout Handling

Implement automatic cancellation mechanism for loading timeouts:

// Loading utility with timeout
class TimeoutLoading {
  private timeoutId: number = -1;

  showLoading(options: LoadingStyle = {}, timeoutMs: number = 10000): Promise<boolean> {
    return new Promise((resolve) => {
      Loading.open(options);
      // Set timeout timer
      this.timeoutId = setTimeout(() => {
        Loading.close();
        resolve(false); // Timeout
      }, timeoutMs);

      // Listen for loading close event (implemented through custom events)
      LoadingEvent.on('close', () => {
        if (this.timeoutId !== -1) {
          clearTimeout(this.timeoutId);
          resolve(true); // Normal close
        }
      });
    });
  }
}

// Usage example
const timeoutLoading = new TimeoutLoading();
const loadSuccess = await timeoutLoading.showLoading({}, 8000);
if (!loadSuccess) {
  promptAction.showToast({ message: 'Loading timed out, please try again' });
}

Practical Recommendations

1. Performance Optimization Checklist

Animation Optimization:
- Prefer Lottie for complex animations over custom property animations
- Control animation frame rate below 30fps
- Avoid playing multiple animations simultaneously
Resource Management:
- Preload commonly used animation resources
- Destroy animation instances when no longer needed
- Compress Lottie JSON file sizes
Interaction Design:
- All loading states must provide a cancellation method
- Long loading processes should display progress hints
- Error states should have clear retry guidance

2. Accessibility Optimization

Ensure loading components are accessible to all users:

// Accessible loading component
@Builder
function AccessibleLoading() {
  Column() {
    LottieLoading()
    Text('Loading data')
      .fontSize(16)
      .margin({ top: 12 })
  }
  .semanticsLabel('Data loading') // Accessibility label
  .semanticsHint('Please wait, data is being loaded') // Accessibility hint
  .focusable(true) // Support focus
}

3. Testing Strategy

Unit Testing: Test the counting logic of LoadingManager
Performance Testing: Monitor animation CPU usage with performance analysis tools
Scenario Testing: Simulate weak network, timeout, concurrent requests, etc.
UI Testing: Verify loading positions and styles on different sized devices

Summary and Outlook

The advanced features of ZeroOneApp's loading component provide powerful support for complex application scenarios, with key advantages including:

Highly Customizable: From simple style adjustments to fully custom layouts, meeting diverse design needs
Performance Optimized: Ensuring smooth experiences through animation management and resource preloading
Scenario Adaptable: Providing solutions for special cases like weak networks and timeouts
Architecturally Flexible: Supporting deep integration with state management and routing systems

Future exploration directions:

Progressive loading solutions based on skeleton screens
Intelligent loading strategies combined with application state
Consistent loading experiences across devices
A/B testing framework for loading states

ZeroOneApp Loading Component: Basic Implementation and Usage

xhunmon — Wed, 25 Jun 2025 05:46:45 +0000

Introduction

In mobile application development, displaying loading states is a crucial aspect of enhancing user experience. A well-designed loading component can effectively alleviate user waiting anxiety and provide clear interaction feedback. ZeroOneApp's UI component library includes a fully functional loading component developed based on HarmonyOS's ArkUI framework, supporting multiple loading styles, custom configurations, and convenient API calls. This article will analyze the implementation principles of ZeroOneApp's loading component from a basic level, including its core architecture, style definitions, and basic usage methods, helping developers quickly master the integration and application of this component.

Official Resources

ArkUI Component Development Guide: Official HarmonyOS documentation providing UI component development specifications and best practices ArkUI Component Development Documentation
Lottie Animation Library: Airbnb's open-source animation library that supports rendering JSON format animation files Lottie Official Documentation
HarmonyOS Lottie Adaptation Library: Lottie animation implementation for HarmonyOS @ohos/lottie

Detailed Explanation

1. Core Architecture of Loading Component

ZeroOneApp's loading component adopts a modular design, mainly consisting of three core files:

Loading.ets: Main entry of the loading component, responsible for component display, lifecycle management, and API encapsulation
LoadingStyle.ets: Defines the style interface of the loading component, standardizing configurable properties
LottieLoading.ets: Animation loading effect implemented based on Lottie, providing default animation display

This layered design gives the component good maintainability and extensibility. Developers can easily customize loading effects through the style interface without modifying core logic.

2. LoadingStyle Interface Definition

The LoadingStyle interface defines the configurable properties of the loading component, located in common/ui/src/main/ets/components/loading/LoadingStyle.ets:

export interface LoadingStyle {
  /** Position, default is center */
  alignment?: Alignment
  /** Whether pressing the system back button can cancel, default true */
  pressBackCancel?: boolean
  /** Whether clicking outside area can cancel, default false */
  outsideCancel?: boolean
  /** Custom loading animation layout */
  layout?: WrappedBuilder<[object]>;
  /** Style of the outermost UI, for setting background depth, etc. */
  outBoxAttr?: AttributeModifier<StackAttribute>
}

The interface design follows these principles:

All properties are optional to ensure the component has reasonable default behavior
Functional modularization, separating layout, interaction, and style configurations
Using ArkUI's basic types (such as Alignment, AttributeModifier) to ensure compatibility
Supporting custom layouts through WrappedBuilder for maximum flexibility

3. Detailed Implementation of Loading Component

3.1 Component Structure and Lifecycle

The Loading component uses NavDestination as a container and displays in dialog mode. The core code is located in common/ui/src/main/ets/components/loading/Loading.ets:

@ComponentV2
export struct Loading {
  private gStyle: LoadingStyle | undefined = global.getObject<LoadingStyle>('loadingStyle');
  private style: LoadingStyle = this.gStyle ? this.gStyle : {};
  private pathStack: NavPathStack = new NavPathStack()
  @Local backCancel: boolean = true;
  @Local outsideCancel: boolean = false;
  @Local alignment: Alignment = Alignment.Center;
  @Local layout: WrappedBuilder<[object]> = this.style.layout ? this.style.layout : wrapBuilder(defaultLoading);
  @Local outBoxAttr: AttributeModifier<StackAttribute> = {};
  @Provider() isStartLoading: boolean = false;

  build() {
    NavDestination() {
      Stack() {
        // Background mask layer
        Stack()
          .width('100%')
          .height('100%')
          .onClick(() => {
            if (this.outsideCancel) {
              this.pathStack.pop();
            }
          })
        // Loading animation layout
        this.layout.builder(undefined)
      }
      .backgroundColor($r('sys.color.mask_secondary'))
      .alignContent(this.alignment)
      .width('100%')
      .height('100%')
      .attributeModifier(this.outBoxAttr)
    }
    .onReady(cxt => {
      this.pathStack = cxt.pathStack
      const parm = cxt.pathInfo.param as LoadingStyle
      this.creatCurStyle(parm)
    })
    .onAppear(() => {
      this.isStartLoading = true;
    })
    .onDisAppear(() => {
      this.isStartLoading = false;
    })
    .onBackPressed(() => {
      return !this.backCancel;
    })
    .mode(NavDestinationMode.DIALOG)
    .hideTitleBar(true)
  }
  // ...other methods
}

Core features of the component include:

Using NavDestinationMode.DIALOG mode to display as a dialog without affecting the page stack structure
Implementing hierarchical relationship between background mask layer and loading content through Stack layout
Supporting cancellation of loading by clicking outside area and pressing back button (configurable)
Automatically controlling animation start and stop when the component appears and disappears
Communicating with animation components through @provider decorator to control animation state

3.2 API Design and Usage

The Loading component provides a concise static method API for easy calling anywhere by developers:

/**
 * Global initialization of style
 */
static initDefaultStyle(loadingStyle: LoadingStyle) {
  global.setObject('loadingStyle', loadingStyle)
}

public static open(parm: LoadingStyle = {}) {
  RouterUtil.push('Loading', parm);
}

public static close() {
  RouterUtil.finishPage('Loading');
}

Advantages of this design:

Providing global style initialization to ensure consistent style of loading components within the application
Simple and intuitive static method calls without creating component instances
Supporting passing different configurations for each call to meet diverse scenario requirements
Implemented based on route management, seamlessly integrating with application navigation system

4. LottieLoading Animation Implementation

The default loading animation is implemented based on Lottie, located in common/ui/src/main/ets/components/loading/LottieLoading.ets:

@ComponentV2
export struct LottieLoading {
  private mainRenderingSettings: RenderingContextSettings = new RenderingContextSettings(true)
  private mainCanvasRenderingContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.mainRenderingSettings)
  private jsonData: string = '';
  @Consumer() isStartLoading: boolean = false;

  @Monitor('isStartLoading')
  loadAnimation() {
    if (!this.isStartLoading) {
      lottie.destroy();
      return
    }
    this.createAnimation();
  }

  private createAnimation() {
    lottie.destroy();
    let resStr = new util.TextDecoder('utf-8', { ignoreBOM: true });
    let contexts = getContext() as common.UIAbilityContext
    contexts.resourceManager.getRawFile('loading.json', (err: Error, data: Uint8Array) => {
      if (data?.buffer) {
        let lottieStr = resStr.decode(new Uint8Array(data.buffer));
        this.jsonData = JSON.parse(lottieStr);

        lottie.loadAnimation({
          container: this.mainCanvasRenderingContext, // Rendering context
          renderer: 'canvas', // Rendering method
          loop: true, // Loop playback
          autoplay: true, // Auto play
          animationData: this.jsonData, // JSON animation data
          context: contexts // Current scene context
        })
      }
    })
  }

  build() {
    Canvas(this.mainCanvasRenderingContext)
      .width('85%')
      .height('50%')
      .onReady(() => {
        this.mainCanvasRenderingContext.imageSmoothingEnabled = true;
        this.mainCanvasRenderingContext.imageSmoothingQuality = 'medium'
      })
  }
}

Key points of Lottie animation implementation:

Using Canvas component as rendering container, drawing animation through RenderingContext2D
Monitoring isStartLoading state changes to control animation start and destruction
Loading JSON format Lottie animation files from application resources
Supporting anti-aliasing settings to improve animation display quality
Destroying resources when animation ends or component disappears to avoid memory leaks

Practical Recommendations

1. Basic Usage Example

// Simply display loading
Loading.open();

// Close loading after 2 seconds
setTimeout(() => {
  Loading.close();
}, 2000);

2. Custom Configuration Example

// Custom loading position and cancellation behavior
Loading.open({
  alignment: Alignment.Bottom,
  pressBackCancel: false,
  outsideCancel: true,
  outBoxAttr: {
    backgroundColor: Color.Black.withAlpha(0.7)
  }
});

3. Global Style Initialization

Initialize global loading style at application entry:

// Initialization code in app.ets or main page
Loading.initDefaultStyle({
  alignment: Alignment.Center,
  pressBackCancel: true,
  outsideCancel: false,
  // Set global default loading animation
  layout: wrapBuilder(() => {
    Column() {
      Progress()
        .color(Color.Blue)
        .width(50)
        .height(50)
      Text('Loading...')
        .fontSize(14)
        .margin({ top: 10 })
    }
  })
});

4. Using with Network Requests

Using with the previously introduced network request framework:

// Show loading before发起请求
Loading.open();

// Network request
net.post<DataResp>(API.getData, params, {
  onSuccess: (data) => {
    // Process data
  },
  onFail: (code, msg) => {
    // Show error message
  },
  onFinally: () => {
    // Request completed, close loading
    Loading.close();
  }
});

Summary and Outlook

The basic implementation of ZeroOneApp's loading component has the following characteristics:

Clear Architecture: Adopting modular design, separating component logic, style definition, and animation implementation
Easy to Use: Providing concise static API, supporting one-line code calling
Flexible Configuration: Supporting multiple custom requirements through style interface
Performance Optimization: Reasonably managing animation resources to avoid memory leaks
Good Compatibility: Developed based on HarmonyOS standard API, adapting to different devices

Basic usage scenarios already cover most loading requirements, but there is still room for expansion in complex applications. Advanced features such as loading state management and multi-instance control will be discussed in subsequent articles.

ZeroOneApp Network Download Function Implementation and Optimization

xhunmon — Wed, 25 Jun 2025 05:44:20 +0000

Introduction

In mobile application development, file downloading is a common and critical feature involving network requests, progress monitoring, file operations, and exception handling. ZeroOneApp's network module not only provides basic HTTP request capabilities but also encapsulates an efficient and reliable download functionality that supports progress feedback, file management, and error recovery. This article will deeply analyze the download implementation details in the NetRequest class, explore its design ideas and optimization strategies, providing reference for implementing download functionality in HarmonyOS applications.

Official Resources

HarmonyOS File Management: Provides complete APIs for file operations within the application sandbox, including creating, deleting, reading, and writing files HarmonyOS File Management Documentation
Axios Download Progress: The @ohos/axios library supports obtaining download progress information through the onDownloadProgress callback Axios Request Configuration
HarmonyOS Network Status Management: Provides network connection status monitoring capabilities that can be used to optimize download experience HarmonyOS Network Status

Detailed Explanation

1. Core Implementation of Download Function

ZeroOneApp's download functionality is implemented through the download method, which encapsulates the complete lifecycle of file downloading, including request configuration, progress monitoring, file processing, and result callbacks:

download(url: string, filePath: string, onResult: (status: number, progress: number, msg: string) => void) {
  log.i(TAG, `[Download][${url}]: ${filePath}`);
  FileUtil.delete(filePath);
  axios({
    url: url,
    method: 'get',
    context: context,
    filePath: filePath,
    onDownloadProgress: (progressEvent: AxiosProgressEvent): void => {
      if (progressEvent === undefined || progressEvent.total === undefined) {
        return;
      }
      const progress = progressEvent.total ? Math.ceil(progressEvent.loaded / progressEvent.total * 100) : 0;
      log.i(TAG, `progress: ${progress} | ${StringUtil.toStr(progressEvent)}`);
      onResult(2, progress, 'Downloading');
    }
  }).then((response: AxiosResponse<string>) => {
    log.i(TAG, `response: ${StringUtil.toStr(response)}`);
    if (response.status === 200) {
      onResult(1, 100, response.data);
    } else {
      FileUtil.delete(filePath);
      onResult(-1, 0, response.data);
    }
  }).catch((error: AxiosError) => {
    log.e(TAG, `[Exception][${url}]: ${StringUtil.toStr(error)}`);
    FileUtil.delete(filePath);
    onResult(-1, 0, error.message);
  })
}

2. Key Technical Points Analysis

2.1 File Path Handling and Conflict Resolution

The target path file is deleted before downloading to avoid interference from old files and path conflicts:

FileUtil.delete(filePath);

This operation ensures that each download starts fresh, preventing verification errors or version confusion caused by file residues.

2.2 Progress Monitoring Implementation

Real-time download progress is obtained through Axios's onDownloadProgress callback:

onDownloadProgress: (progressEvent: AxiosProgressEvent): void => {
  if (progressEvent === undefined || progressEvent.total === undefined) {
    return;
  }
  const progress = progressEvent.total ? Math.ceil(progressEvent.loaded / progressEvent.total * 100) : 0;
  onResult(2, progress, 'Downloading');
}

Progress calculation uses the formula loaded/total*100 with Math.ceil to ensure progress values are integer percentages for easy UI display.

2.3 Status Code Design

Download status is传递 through the status parameter of the callback function, defining four clear states:

-1: Download failed
0: Not downloaded (initial state)
1: Download successful
2: Downloading This state design enables the caller to easily handle UI display and business logic for different download phases.

2.4 Error Handling and Resource Cleanup

In case of download failure, the framework automatically deletes incomplete files to avoid occupying storage space:

.catch((error: AxiosError) => {
  log.e(TAG, `[Exception][${url}]: ${StringUtil.toStr(error)}`);
  FileUtil.delete(filePath);
  onResult(-1, 0, error.message);
})

This mechanism ensures the cleanliness of the file system and prevents accumulation of invalid files.

Practical Recommendations

1. Complete Download Function Usage Example

// Download APK update package
net.download(
  'https://example.com/xxx.zip',
  getContext().filesDir + '/update.apk',
  (status, progress, msg) => {
    switch (status) {
      case 2:
        // Update progress bar
        this.downloadProgress = progress;
        break;
      case 1:
        // Download successful, install APK
        this.installApk(getContext().filesDir + '/update.apk');
        break;
      case -1:
        // Download failed, display error message
        promptAction.showToast({ message: 'Download failed: ' + msg });
        break;
    }
  }
);

2. Network Status Adaptation

Optimize download strategy by combining with network status management:

// Check network status
const networkStatus = network.getCurrentType();
if (networkStatus === network.NetworkType.NETWORK_WIFI) {
  // Direct download in WIFI environment
  startDownload();
} else if (networkStatus === network.NetworkType.NETWORK_MOBILE) {
  // Ask user in mobile network
  promptAction.showDialog({
    message: 'Currently using mobile data, continue downloading?',
    buttons: [{
      text: 'Cancel'
    }, {
      text: 'Continue'
    }]
  }).then(result => {
    if (result.index === 1) {
      startDownload();
    }
  });
} else {
  promptAction.showToast({ message: 'No network connection' });
}

3. Resumable Download Implementation Idea

Although the current framework does not implement resumable download, it can be extended based on existing code:

// Extend download method to support range requests
async function downloadWithResume(url: string, filePath: string) {
  const fileSize = await FileUtil.getFileSize(filePath);
  const headers = fileSize > 0 ? {
    'Range': `bytes=${fileSize}-`
  } : {};

  // Use headers to initiate partial request
  // Append to file instead of overwriting when downloading
}

4. Download Task Management

For multi-file download scenarios, it is recommended to implement a task queue:

class DownloadManager {
  private queue: DownloadTask[] = [];
  private currentTask: DownloadTask | null = null;

  addTask(task: DownloadTask) {
    this.queue.push(task);
    this.processQueue();
  }

  private processQueue() {
    if (this.currentTask || this.queue.length === 0) return;
    this.currentTask = this.queue.shift();
    this.startTask(this.currentTask);
  }

  // Other implementations...
}

Summary and Outlook

ZeroOneApp's download functionality implements core file download requirements through a concise yet powerful design, featuring:

Security: Cleans target files before downloading to avoid version conflicts
Reliability: Complete error handling and resource recovery mechanisms
Usability: Concise API design and clear status code definition
Extensibility: Modular structure facilitating function expansion

Future optimization directions to consider:

Implement resumable download to support chunked downloading of large files
Add download task management supporting pause, resume, and cancel operations
Increase network type judgment and download strategy selection
Implement download speed limitation to avoid affecting other network requests
Add file verification mechanism to ensure download integrity

References

ZeroOneApp Network Request Framework Design and Implementation

xhunmon — Wed, 25 Jun 2025 05:41:24 +0000

Introduction

In modern application development, the network module serves as the core hub connecting the frontend and backend services. As an open-source practice project in the QuickApp series, ZeroOneApp's network module is built on the Axios library to create an efficient and scalable request framework. This article will deeply analyze the design philosophy and implementation details of the NetRequest class in ZeroOneApp, helping developers master best practices for network requests in HarmonyOS applications.

Official Resources

Axios for HarmonyOS: ZeroOneApp uses @ohos/axios as the basic network request library, which is a Promise-based HTTP client supporting request/response interception, data transformation, and other features Axios Official Documentation
HarmonyOS Network Development Guide: Provides official specifications and recommendations for network requests, data security, etc. HarmonyOS Network Development Documentation

Detailed Explanation

1. Core Design of Network Request Framework

The NetRequest class adopts a singleton pattern design to ensure there is only one network request instance in the application, avoiding resource waste from repeated creation. The core code structure is as follows:

class NetRequest {
  private instance: AxiosInstance;
  private responseInterceptFunc?: (response: AxiosResponse) => AxiosResponse;
  private errorInterceptFunc?: (error: AxiosError) => AxiosError;

  constructor() {
    this.instance = axios.create({
      baseURL: API.base_url,
      timeout: 5000,
      connectTimeout: 60000,
      headers: {}
    });
    this.initIntercept(this.instance);
  }

  // Singleton instance export
  export const net: NetRequest = new NetRequest();
}

2. Implementation of Request and Response Interceptors

The framework implements unified request processing, response parsing, and error handling through interceptors:

private initIntercept(instance: AxiosInstance) {
  // Response interceptor
  instance.interceptors.response.use((response: AxiosResponse) => {
    if (this.responseInterceptFunc) {
      return this.responseInterceptFunc(response);
    }
    return response;
  }, (error: AxiosError) => {
    // Error handling logic
    log.i(TAG, 'initIntercept error: code=' + error.code + ' | message=' + error.message);
    if (this.errorInterceptFunc) {
      return this.errorInterceptFunc(error);
    }
    return error;
  });
}

Advantages of the interceptor mechanism:

Centralized processing of all requests/responses, reducing duplicate code
Unified addition of authentication tokens, request headers, etc.
Unified handling of error status codes such as 401 Unauthorized and 500 Server Error
Support for custom interception logic extension

3. Request Method Encapsulation

The framework encapsulates Axios's POST method to provide a more concise API and unified callback handling:

post<T, D>(url: string, data?: D, callback?: Callback<T>) {
  log.i(TAG, `[Request][${url}]: ${StringUtil.toStr(data)}`);
  this.instance
    .post<string, AxiosResponse<MagicResp<T>>, D>(url, data)
    .then((response: AxiosResponse<MagicResp<T>>) => {
      log.i(TAG, `[Response][${url}]: ${StringUtil.toStr(response.data)}`);
      // Response handling logic
    })
    .catch((error: Error) => {
      // Error handling logic
    })
    .finally(() => {
      if (callback && callback.onFinally) {
        callback.onFinally();
      }
    });
}

Features of the encapsulated POST method:

Generic support for type safety
Unified log printing for debugging
Standardized callback interface (onSuccess/onFail/onFinally)
Deep integration with MagicResp response model

Practical Recommendations

1. Interceptor Usage Tips

// Configure global response interception during application initialization
net.onResponseIntercept((response) => {
  // Unified response data processing
  if (response.data.code === 401) {
    // Handle unauthorized access, such as redirecting to login page
  }
  return response;
});

2. Dynamic Request Header Addition

// Add authentication token after login
net.addHeader({
  'Authorization': `Bearer ${token}`,
  'X-Platform': 'HarmonyOS'
});

3. Error Handling Best Practices

net.post<LoginResp, LoginReq>(API.login, {username, password}, {
  onSuccess: (data) => {
    // Handle success logic
  },
  onFail: (code, msg) => {
    if (code === -1) {
      promptAction.showToast({ message: 'Network connection failed' });
    } else {
      promptAction.showToast({ message: msg });
    }
  },
  onFinally: () => {
    //收尾操作，如隐藏加载动画
  }
});

Summary and Outlook

ZeroOneApp's network request framework achieves code reuse, unified management, and flexible expansion through elegant design. Core advantages include:

Reasonable Architecture Design: Singleton pattern ensures efficient resource utilization, and interceptor mechanism achieves separation of cross-cutting concerns
User-Friendly API Design: Generic support and callback interface provide a good development experience
Strong Extensibility: Supports custom interception logic and request configuration
Comprehensive Error Handling: Covers various exception scenarios including network errors and business errors

Future features to consider adding:

Request retry mechanism
Network caching strategy
Request priority management
Batch request processing

References

HintDialog Best Practices and Performance Optimization in Real Projects

xhunmon — Tue, 24 Jun 2025 05:41:25 +0000

1. Integration Strategies for Medium to Large Projects
2. Common Problem Diagnosis and Solutions
3. C++/ArkTS Hybrid Programming Performance Optimization
4. Testing Strategies and Automated Test Case Design
5. Community Feedback and Future Plans
6. Practical Code Snippets and Resource Links
7. Summary

Abstract

This article shares integration experience of hint-dialog in medium to large projects, deeply analyzes solutions to common issues such as memory leaks and duplicate pop-ups, explores how to improve performance through ArkTS hybrid programming, and provides testing strategies and automated test case design suggestions to help developers build efficient and stable dialog systems.

1. Integration Strategies for Medium to Large Projects

1.1 Global Configuration and Encapsulation

In medium to large projects, it is recommended to secondary encapsulate hint-dialog to uniformly manage dialog styles and behaviors:

// utils/DialogManager.ets
import { HintDialog, HintStyle, TitleParm } from '@qincji/dialog';

export class DialogManager {
  // Initialize global style
  static initGlobalStyle() {
    HintDialog.initDefaultStyle({
      titleParm: new TitleParm('System Prompt'),
      outsideCancel: false, // It is recommended to disable outside cancel by default in production environment
      alignment: DialogAlignment.Center,
      // Unified button style
      btnParm: {
        okAttr: { /* Production environment button style */ },
        noAttr: { /* Production environment button style */ }
      }
    });
  }

  // Encapsulate common dialog types
  static showSuccess(message: string) {
    return HintDialog.open({
      content: message,
      showNo: false,
      // Success style customization
    });
  }

  static showError(message: string) {
    return HintDialog.open({
      content: message,
      showNo: false,
      // Error style customization
    });
  }

  static showConfirm(message: string, onOk: () => void) {
    return HintDialog.open({
      content: message,
      onOk: onOk
    });
  }
}

Initialize at the application entry:

// main/AbilityStage.ts
import { DialogManager } from '../utils/DialogManager';

export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    super.onCreate();
    DialogManager.initGlobalStyle(); // Initialize dialog global style
  }
}

1.2 Modular Usage Strategy

Divide dialog configurations according to business modules to avoid style conflicts:

// Business module-specific dialog configuration
export namespace OrderDialog {
  export function showPaymentConfirm(amount: number, onConfirm: () => void) {
    HintDialog.open({
      title: 'Order Payment',
      content: `Confirm payment of ${amount} yuan?`,
      okMsg: 'Pay Now',
      onOk: onConfirm,
      // Order module-specific style
      outBoxAttr: {/* Order module style */}
    });
  }
}

2. Common Problem Diagnosis and Solutions

2.1 Memory Leak Issues

Problem表现: Memory usage continues to increase after frequently opening and closing dialogs
原因分析: Unreleased resource references exist in callback functions
解决方案: Use weak references and lifecycle management

// Wrong example: May cause memory leaks
HintDialog.open({
  onOk: () => {
    this.dataService.fetchData(); // This reference prevents dialog instance from being released
  }
});

// Correct example: Use weak reference
const weakThis = new WeakRef(this);
HintDialog.open({
  onOk: () => {
    const that = weakThis.get();
    if (that) {
      that.dataService.fetchData();
    }
  }
});

2.2 Duplicate Pop-up Issues

Problem表现: Multiple dialogs pop up叠加 when clicking buttons quickly
解决方案: Add pop-up status lock

// Add status control in DialogManager
private static isShowing = false;

static showConfirm(message: string, onOk: () => void) {
  if (DialogManager.isShowing) return;
  DialogManager.isShowing = true;

  return HintDialog.open({
    content: message,
    onOk: () => {
      onOk();
      DialogManager.isShowing = false;
    },
    onNo: () => {
      DialogManager.isShowing = false;
    },
    onDidDisappear: () => {
      DialogManager.isShowing = false; // Ensure status is reset in all cases
    }
  });
}

Official Guide

2.3 Animation Stutter Optimization

Problem表现: Dialog pop-up/disappearance animation stutters
Optimization方案:

Reduce dialog content complexity
Avoid performing heavy operations during animation
Use hardware accelerated rendering

// Optimize animation performance
HintDialog.initDefaultStyle({
  // Simplify animation configuration
  openAnimation: { duration: 200, curve: Curve.EaseOut },
  closeAnimation: { duration: 150, curve: Curve.EaseIn },
  outBoxAttr: {
    applyNormalAttribute: (column) => {
      column
        .backgroundColor('#ffffff')
        .borderRadius(12)
        .clip(true) // Enable clipping optimization
        .transition(TransitionEffect.OPACITY | TransitionEffect.SCALE);
    }
  }
});

3.1 Rendering Optimization

Use ArkTS to implement complex graphics drawing and display through ArkUI's custom drawing components:

// Custom drawing component with C++ backend
@Component
struct ChartView {
  @Prop data: number[];

  build() {
    CustomPaint({
      painter: new ChartPainter(this.data), // C++ implemented painter
      size: { width: '100%', height: 200 }
    })
  }
}

// Use high-performance chart in dialog
HintDialog.open({
  title: 'Data Statistics',
  customContent: () => ChartView({
    data: [12, 34, 23, 56, 45]
  })
});

4. Testing Strategies and Automated Test Case Design

4.1 Unit Testing

Use HarmonyOS testing framework to perform unit testing on dialog logic:

// test/unit/DialogManager.test.ets
import { DialogManager } from '../../utils/DialogManager';
import { HintDialog } from '@qincji/dialog';

describe('DialogManager', () => {
  beforeAll(() => {
    DialogManager.initGlobalStyle();
  });

  test('showSuccess should open dialog with correct parameters', () => {
    // Mock HintDialog.open
    const mockOpen = spyOn(HintDialog, 'open');
    DialogManager.showSuccess('Test success');
    expect(mockOpen).toHaveBeenCalledWith(expect.objectContaining({
      content: 'Test success',
      showNo: false
    }));
  });
});

4.2 UI Automation Testing

Use UI testing framework to verify dialog interactions:

// test/ui/DialogUITest.ets
import { Driver, By, until } from '@ohos.uiautomator';

describe('HintDialog UI Test', () => {
  let driver: Driver;

  beforeAll(async () => {
    driver = await Driver.create();
    await driver.launchApp('com.example.myapp');
  });

  test('dialog should respond to ok click', async () => {
    // Click button to show dialog
    await driver.findElement(By.text('Show Dialog')).click();
    // Verify dialog display
    const dialog = await driver.findElement(By.text('System Prompt'));
    expect(await dialog.isDisplayed()).toBe(true);
    // Click confirm button
    await driver.findElement(By.text('Confirm')).click();
    // Verify dialog closed
    expect(await driver.findElement(By.text('System Prompt')).isDisplayed()).toBe(false);
  });
});

5. Community Feedback and Future Plans

5.1 Community Contribution Guidelines

hint-dialog welcomes community contributions. The contribution process is as follows:

Fork the project to your personal repository
Create a feature branch: git checkout -b feature/xxx
Commit code: git commit -m 'feat: add xxx feature'
Push branch: git push origin feature/xxx
Create Pull Request

Contributors should follow code specifications, ensure test coverage, and describe feature purposes and implementation ideas in the PR.

5.2 Future Feature Plans

Based on community feedback, hint-dialog plans to support in future versions:

Dialog queue management, supporting sequential display of multiple dialogs
Custom animation effect library, providing more transition animation options
Accessibility support, optimizing screen reader compatibility
Multi-language internationalization support, with built-in common language packs
Theme switching function, supporting automatic adaptation of light/dark modes

6. Practical Code Snippets and Resource Links

Complete implementation of common utility class:

// Complete dialog utility class example
import { HintDialog, HintParm } from '@qincji/dialog';
import { Log } from '../utils/Log';

export class DialogUtil {
  private static dialogStack: number = 0;
  private static readonly MAX_STACK = 3;

  static open(params: HintParm) {
    if (this.dialogStack >= this.MAX_STACK) {
      Log.warn('Dialog stack overflow, ignore new dialog');
      return;
    }

    this.dialogStack++;
    const originalOnOk = params.onOk;
    const originalOnNo = params.onNo;
    const originalDisappear = params.onDidDisappear;

    // Wrap callback functions to manage dialog stack
    params.onOk = () => {
      originalOnOk?.();
      this.dialogStack--;
    };

    params.onNo = () => {
      originalOnNo?.();
      this.dialogStack--;
    };

    params.onDidDisappear = () => {
      originalDisappear?.();
      this.dialogStack--;
    };

    return HintDialog.open(params);
  }

  static closeAll() {
    HintDialog.close();
    this.dialogStack = 0;
  }
}

External resource links:

7. Summary

This article systematically introduces the integration strategies of hint-dialog in medium to large projects, deeply analyzes solutions to common problems such as memory leaks and duplicate pop-ups, and explores methods to improve performance through ArkTS programming. At the same time, it provides comprehensive testing strategies, automated test case design suggestions, as well as community contribution guidelines and future plans. Through these best practices, developers can give full play to the advantages of hint-dialog and build an efficient, stable, and user-friendly dialog system. hint-dialog will continue to iterate and optimize, and developers are welcome to participate in contributions and feedback.

HintDialog Advanced Usage and Customization Practices

xhunmon — Tue, 24 Jun 2025 05:39:10 +0000

1. Advanced Parameter Configuration Details
2. Event Handling and Asynchronous Operations
3. Custom Styles and Themes
4. Complex Content Embedding Techniques
5. Core Source Code Architecture Analysis
6. Comparison with Official Dialog Solution
7. Summary

Abstract

This article explores the advanced features of hint-dialog in depth, including advanced parameter configuration, event handling mechanisms, custom styling solutions, complex content embedding, and source code architecture analysis. It helps developers make full use of this component to implement complex business requirements and compares the advantages and disadvantages with the official solution to provide references for project selection.

1. Advanced Parameter Configuration Details

hint-dialog provides rich parameter configurations to support various complex scenario requirements:

1.1 Complete Parameter List

interface HintParm {
  content: string;                // Display content
  title?: string;                 // Title
  noMsg?: string;                 // Cancel button text
  okMsg?: string;                 // Confirm button text
  showNo?: boolean;               // Whether to show cancel button
  isWebType?: boolean;            // Whether it is Web type
  controller?: WebviewController; // Web controller
  outsideCancel?: boolean;        // Whether clicking outside can cancel
  onNo?: () => void;              // Cancel callback
  onOk?: () => void;              // Confirm callback
  alignment?: DialogAlignment;    // Alignment method
}

1.2 Web Type Dialog Configuration

When you need to display web content in the dialog, you can configure the isWebType parameter:

import { WebviewController } from '@ohos.web.webview';

// Create Web controller
private webController: WebviewController = new WebviewController();

// Open Web type dialog
HintDialog.open({
  title: 'Web Content Display',
  content: 'https://gitee.com/qincji/hint-dialog',
  isWebType: true,
  controller: this.webController,
  showNo: true,
  onOk: () => {
    // Get current URL
    this.webController.getURL().then(url => {
      console.log('Current web address: ' + url);
    });
  }
})

2. Event Handling and Asynchronous Operations

2.1 Asynchronous Callback Handling

Dialog buttons support asynchronous callback operations, enabling complex business logic:

HintDialog.open({
  title: 'Asynchronous Operation Example',
  content: 'Are you sure you want to submit the form?',
  onOk: async () => {
    // Show loading status
    HintDialog.open({
      content: 'Submitting...',
      showNo: false
    });

    try {
      // Simulate API request
      await new Promise(resolve => setTimeout(resolve, 2000));
      // Close loading dialog
      HintDialog.close();
      // Show success prompt
      HintDialog.open({
        content: 'Submission successful',
        showNo: false
      });
    } catch (e) {
      HintDialog.close();
      HintDialog.open({
        content: 'Submission failed, please try again',
        showNo: false
      });
    }
  }
})

2.2 Lifecycle Events

Starting from API version 19, custom popups provide lifecycle functions:

HintDialog.initDefaultStyle({
  // Callback before popup appears
  onWillAppear: () => {
    console.log('Dialog is about to show');
  },
  // Callback after popup appears
  onDidAppear: () => {
    console.log('Dialog has shown');
  },
  // Callback before popup disappears
  onWillDisappear: () => {
    console.log('Dialog is about to disappear');
  },
  // Callback after popup disappears
  onDidDisappear: () => {
    console.log('Dialog has disappeared');
  }
})

Official Guide

3. Custom Styles and Themes

3.1 Global Style Initialization

You can configure dialog styles globally through the initDefaultStyle method:

// Import related classes
import { HintDialog, HintStyle, TitleParm } from '@qincji/dialog';
import { AttributeModifier, TextAttribute, ColumnAttribute } from '@ohos.ui';

// Custom title style
const titleAttr: AttributeModifier<TextAttribute> = {
  applyNormalAttribute(instance: TextAttribute): void {
    instance.fontColor('#ff1145e5')
           .fontWeight(FontWeight.Bolder)
           .fontSize(25)
           .margin({ bottom: 15 });
  }
};

// Custom outer container style
const outBoxAttr: AttributeModifier<ColumnAttribute> = {
  applyNormalAttribute(instance: ColumnAttribute): void {
    instance.backgroundColor('#ffc8f1b3')
           .borderRadius(15)
           .padding(20)
           .margin(50);
  }
};

// Initialize global style
HintDialog.initDefaultStyle({
  titleParm: new TitleParm('Custom Title', titleAttr),
  outBoxAttr: outBoxAttr,
  alignment: DialogAlignment.Bottom,
  outsideCancel: true
})

3.2 Button Style Customization

Customize button styles through the btnParm parameter:

HintDialog.initDefaultStyle({
  btnParm: {
    okAttr: {
      applyNormalAttribute(btn: ButtonAttribute) {
        btn.backgroundColor('#007dff')
           .fontColor('#ffffff')
           .borderRadius(8)
           .width(120)
           .height(40);
      }
    },
    noAttr: {
      applyNormalAttribute(btn: ButtonAttribute) {
        btn.backgroundColor('#f2f2f2')
           .fontColor('#333333')
           .borderRadius(8)
           .width(120)
           .height(40);
      }
    },
    space: 15 // Button spacing
  }
})

4. Complex Content Embedding Techniques

4.1 Embedding Custom Components

The content parameter supports custom component embedding:

// Define custom content component
@Component
struct CustomContent {
  @State count: number = 0;

  build() {
    Column({
      space: 10
    }) {
      Text('This is a custom counter')
      Button('+')
        .onClick(() => this.count++)
      Text(`Current value: ${this.count}`)
    }
    .padding(10)
  }
}

// Use in dialog
HintDialog.open({
  title: 'Custom Content Example',
  content: '', // Must be provided, can be empty string
  customContent: () => CustomContent(), // Custom content component
  showNo: true
})

4.2 Form Data Collection

Implement form collection using custom content:

@State username: string = '';
@State password: string = '';

HintDialog.open({
  title: 'User Login',
  customContent: () => Column({
    space: 15
  }) {
    TextInput({
      placeholder: 'Please enter username'
    })
    .onChange(value => this.username = value)
    .width('100%')

    TextInput({
      placeholder: 'Please enter password',
      type: InputType.Password
    })
    .onChange(value => this.password = value)
    .width('100%')
  }
  .padding(10),
  onOk: () => {
    // Handle login logic
    console.log(`Login information: ${this.username}, ${this.password}`);
  }
})

5. Core Source Code Architecture Analysis

hint-dialog's core architecture adopts a singleton pattern design to ensure there is only one dialog instance globally:

// Simplified core implementation
class HintDialog {
  private static instance: HintDialog;
  private controller: CustomDialogController;
  private style: HintStyle = defaultStyle;

  // Singleton pattern
  private constructor() {
    this.initController();
  }

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

  // Initialize dialog controller
  private initController() {
    this.controller = new CustomDialogController({
      builder: this.buildContent,
      style: this.style
    });
  }

  // Open dialog
  static open(params: HintParm) {
    const instance = HintDialog.getInstance();
    instance.updateParams(params);
    instance.controller.open();
  }

  // Other methods...
}

The advantages of this design are:

Avoids the problem of multiple dialogs popping up simultaneously
Unified management of dialog state
Simplifies API calls without needing to create instances
Facilitates global style configuration

6. Comparison with Official Dialog Solution

Feature	hint-dialog	Official CustomDialog
Usage Complexity	Simple (static method call)	Medium (needs controller creation)
Style Customization	Rich API support	Requires manual implementation
Feature Completeness	Built-in common functions	Basic functions need extension
Code Amount	Less (one-line call)	More (needs component and controller definition)
Flexibility	High (supports custom content)	High (fully customizable)
Learning Cost	Low	Medium

Basic usage example of official CustomDialog:

// Official CustomDialog implementation
@CustomDialog
struct OfficialDialog {
  controller: CustomDialogController;
  message: string;

  build() {
    Column() {
      Text(this.message)
      Button('Confirm')
        .onClick(() => this.controller.close())
    }
  }
}

// Need to create controller when using
private dialogController: CustomDialogController = new CustomDialogController({
  builder: OfficialDialog({
    message: 'Official dialog',
    controller: this.dialogController
  })
});

// Call to display
this.dialogController.open();

7. Summary

This article detailed the advanced usage and customization techniques of hint-dialog, including parameter configuration, event handling, style customization, and complex content embedding. Through source code analysis, we understood its singleton pattern design idea and compared it with the official solution. hint-dialog provides a more concise API while maintaining flexibility, making it suitable for rapid development. The next article will explore best practices and performance optimization strategies of hint-dialog in actual projects.

HintDialog Basic Introduction and Quick Start

xhunmon — Tue, 24 Jun 2025 05:36:38 +0000

1. Background and Application Scenarios of HarmonyOS Custom Dialogs
2. Design Philosophy and Advantages of hint-dialog
3. Project Address and Installation Method
4. Quick Integration and Basic Usage
5. Hello World Example and Parameter Description
6. API Documentation and Resource Links
7. Summary

Abstract

This article will introduce the basic usage of the custom dialog component hint-dialog under the HarmonyOS platform, including background introduction, installation steps, quick integration examples, and core API explanations, helping developers quickly get started with this powerful dialog component.

1. Background and Application Scenarios of HarmonyOS Custom Dialogs

In mobile application development, dialogs are important components for interacting with users, widely used in scenarios such as information prompts, operation confirmation, and input collection. As a new generation of intelligent terminal operating system, HarmonyOS provides rich UI components, among which CustomDialog allows developers to customize pop-up content and interaction logic according to business needs Official Documentation.

However, the native CustomDialog has problems such as cumbersome usage steps, complex style customization, and single function in actual development. To solve these pain points, the hint-dialog open source library came into being, aiming to provide a set of easy-to-use and highly customizable dialog solutions.

2. Design Philosophy and Advantages of hint-dialog

The design philosophy of hint-dialog is "Simple API, Rich Functions", with main advantages including:

Easy to use: Direct call through static methods without complex initialization process
Flexible styling: Supports comprehensive style customization of title, content, buttons, etc.
Comprehensive functionality: Supports text/web content display, multi-button configuration, event callbacks, etc.
Good compatibility: Adapts to different versions of HarmonyOS and provides a consistent user experience
Lightweight and efficient: Streamlined core code with optimized performance

Compared with the official CustomDialog, hint-dialog encapsulates more commonly used functions, reducing repetitive coding work and allowing developers to focus on business logic implementation rather than UI details Project Repository.

3. Project Address and Installation Method

Project Address: hint-dialog Open Source Repository

Installation Method:
Use ohpm (OpenHarmony Package Manager) for installation:

ohpm install @qincji/dialog

Note: Please ensure that your development environment has ohpm configured and supports HarmonyOS API Version 9 or higher.

4. Quick Integration and Basic Usage

Integrating hint-dialog into your project requires just the following steps:

4.1 Import Component

Import HintDialog in the page where you need to use the dialog:

import { HintDialog } from '@qincji/dialog';

4.2 Initialize Component

Add HintDialog initialization code in the build method of the application's main page (usually MainPage.ets):

@Entry
@Component
struct MainPage {
  build() {
    Row() {
      // Other page content
      HintDialog() // Initialize HintDialog
    }
    .width('100%')
    .height('100%')
  }
}

Note: HintDialog only needs to be initialized once on the main page and is available globally. There is no need to reinitialize after page routing jumps Project Details.

5. Hello World Example and Parameter Description

The following is a simplest example of using HintDialog:

// Call in button click event
Button('Show Prompt')
  .onClick(() => {
    HintDialog.open({
      content: 'This is my first HintDialog',
      showNo: false,
      onOk: () => {
        console.log('User clicked OK button');
      }
    })
  })

Parameter Description:

content: The content displayed in the dialog, which is text or web content depending on the isWebType property
title: Title text, default: "Warm Prompt"
showNo: Whether to display the cancel button, default: true
okMsg: OK button text, default: "OK"
noMsg: Cancel button text, default: "Cancel"
onOk: OK button click callback function
onNo: Cancel button click callback function
isWebType: Whether it is web type content, default: false
outsideCancel: Whether clicking the outside area can cancel, default: true
alignment: Dialog position, default: center

6. API Documentation and Resource Links

7. Summary

This article introduces the basic usage of hint-dialog, including installation steps, initialization process, and simple examples. With hint-dialog, developers can quickly implement fully functional dialogs, greatly reducing development workload. The next article will delve into advanced usage and customization techniques of hint-dialog, helping developers build dialog components that better meet business needs.

HarmonyOS Learning: Developer Certification

xhunmon — Wed, 18 Jun 2025 13:50:59 +0000

Introduction

HarmonyOS Developer Certification is an official technical competency assessment system launched by Huawei, designed to validate developers' professional expertise in HarmonyOS application development. Obtaining certification not only provides authoritative skill endorsement but also enhances career competitiveness and unlocks more business opportunities. This article details the certification system, exam content, and preparation strategies to help developers efficiently plan their certification path.

Official Resources

HarmonyOS Developer Certification portal:

This platform offers one-stop services including certification system introductions, exam outlines, registration portals, and certificate verification.

Detailed Explanation

Certification System Architecture

HarmonyOS Developer Certification comprises three progressive levels:

HarmonyOS Application Developer (Junior)
- Target: Foundational skills for entry-level developers
- Key Content: DevEco Studio usage, ArkUI basic components, page routing, data storage
- Exam Format: Theoretical exam (MCQ/T/F, 90 minutes)
- Passing Score: 60/100 points
HarmonyOS Application Developer (Intermediate)
- Target: Advanced skills for developers with 6+ months of HarmonyOS experience
- Key Content: Complex UI development, state management, distributed capabilities, performance optimization, multi-device adaptation
- Exam Format: Theoretical exam (120 minutes) + Practical exam (180 minutes)
- Passing Score: ≥60 in both sections
HarmonyOS Application Expert (Senior)
- Target: Expert-level certification for developers with 2+ years of architecture design experience
- Key Content: Architecture design, cross-device solutions, security compliance, ecosystem integration
- Exam Format: Technical review (project submission + defense)
- Passing Score: ≥70/100 from review committee

Exam Registration Process

Account Setup: Register a Huawei Developer Alliance account ( and complete real-name verification.
Select Certification: Choose target level and review exam outline.
Optional Training: Enroll in paid official courses (theory + hands-on guidance).
Schedule Exam: Book exam slot online (theory) or at designated centers (practical).
Fees:
- Junior: ¥300
- Intermediate: ¥800
- Senior: ¥2,000
Exam Requirements: Webcam-equipped computer + stable internet for online exams.
Certificate Issuance: Digital certificate within 3 business days; physical copy available upon request.

Core Exam Content (Intermediate Example)

ArkUI Declarative Development
- Complex layouts (List/Grid/Stack nesting)
- Custom components (@Component, parameter passing)
- Animations & interactions (property/transition animations, gestures)
State Management
- App-level state (AppStorage/LocalStorage)
- Component communication (@Link/@Provide/@Consume)
- Data persistence (Preferences, databases, file storage)
Distributed Capabilities
- Device discovery (DeviceManager)
- Cross-device data sharing (DistributedData)
- Service migration (AbilityStage, ServiceExtensionAbility)
Performance Optimization
- Startup optimization (cold/warm launch metrics)
- Rendering optimization (LazyForEach, virtual lists)
- Memory management (leak prevention, large-object handling)

Practical Recommendations

Staged Preparation Plan
- Junior: 1-2 weeks (2 hrs/day) – Focus on official docs + basic cases
- Intermediate: 4-6 weeks (3 hrs/day) – Balance theory/practice with 3+ projects
- Senior: 3-6 months – Emphasize architecture via open-source/enterprise projects
Key Resources
- Official textbooks: HarmonyOS Application Development Practice, HarmonyOS from Beginner to Master
- Certification courses: "Exam Prep Series" on Developer Classroom
- Mock exams: Official sample questions + third-party question banks
- Dev environment: Latest DevEco Studio + HarmonyOS NEXT emulator
Exam Strategies
- Theory: Prioritize confident questions; watch for negative keywords ("incorrect", "not")
- Practical: Plan code structure first; reserve 30 mins for debugging
- Senior defense: Prepare PPT highlighting technical challenges/solutions; rehearse delivery
Continuous Learning
- Join official certification groups for updated materials
- Attend HDC Developer Conference for policy updates
- Share experiences on forums for peer support

Conclusion and Outlook

HarmonyOS Developer Certification serves as both a technical credential and an "ecosystem passport." As the ecosystem expands, certifications will become critical for recruitment and collaborations. Future certifications may extend to IoT, automotive, and specialized domains. Developers should align certifications with career goals through systematic learning and hands-on practice.

Case Study: Game Login (ArkTS)

Learn implementation details:

Huawei Account One-Click Login

Core code using Game Service Kit:

// GameApi.ets - Game login API encapsulation
import gamePlayer from '@hms.core.gameservice.gameplayer';
import promptAction from '@ohos.promptAction';

export class GameApi {
  // Unified login
  async unionLogin(): Promise<gamePlayer.UnionLoginResult> {
    try {
      const result = await gamePlayer.unionLogin();
      if (result.resultCode === 0) {
        promptAction.showToast({ message: 'Login successful' });
        return result;
      } else {
        promptAction.showToast({ message: `Login failed: ${result.resultCode}` });
        throw new Error(`Login failed with code: ${result.resultCode}`);
      }
    } catch (error) {
      console.error(`Union login error: ${JSON.stringify(error)}`);
      throw error;
    }
  }

  // Check user existence
  async checkUserExist(unionId: string): Promise<boolean> {
    // Call backend API in real projects
    return new Promise(resolve => setTimeout(() => resolve(true), 500));
  }
}

// Index.ets - Login page implementation
import { GameApi } from '../common/GameApi';

@Entry
@Component
struct LoginPage {
  private gameApi: GameApi = new GameApi();

  build() {
    Column() {
      Button('Huawei Account One-Click Login')
        .width(300)
        .height(50)
        .onClick(async () => {
          try {
            const loginResult = await this.gameApi.unionLogin();
            const isExist = await this.gameApi.checkUserExist(loginResult.unionId);
            if (isExist) {
              // Existing user silent login
              router.pushUrl({ url: 'pages/MainPage' });
            } else {
              // New user registration
              router.pushUrl({ url: 'pages/RegisterPage' });
            }
          } catch (error) {
            console.error(`Login failed: ${error}`);
          }
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

HarmonyOS Learning: Developer Classroom

xhunmon — Wed, 18 Jun 2025 13:49:04 +0000

Introduction

Developer Classroom is a systematic learning platform created by Huawei for HarmonyOS developers, integrating diverse learning resources such as video courses, live session replays, and documentation tutorials. Whether you are a beginner or an advanced developer, you can acquire authoritative and cutting-edge technical knowledge through Developer Classroom to rapidly enhance your HarmonyOS application development capabilities.

Official Resources

Huawei Developer Classroom official portal:
Specialized video courses:

Platform courses cover everything from foundational introductions to advanced practical applications, including technical principles, development tools, and scenario-based practices.

Detailed Explanation

Core Features of Developer Classroom

Authority: Courses are recorded by Huawei's official technical team and certified experts, with content synchronized to the latest HarmonyOS versions.
Systematic Structure: Courses are designed with a three-tier framework ("Technical Domain - Capability Level - Learning Path") to form a complete knowledge system.
Practical Focus: Most courses include hands-on labs with supporting code projects and environment configuration guides.
Interactivity: Supports Q&A in course comments, with some live sessions offering real-time troubleshooting and code reviews.
Diverse Formats: Includes short videos (5-15 min), series courses (30-60 min/session), and live replays (2-3 hours).

Course Categories

Foundational Series
- "HarmonyOS Development Quick Start": Covers environment setup, project creation, and basic component usage.
- "Deep Dive into ArkUI Declarative Development": Core concepts for transitioning from imperative to declarative development.
- "Essential DevEco Studio Techniques": Practical IDE shortcuts, debugging tools, and performance analysis.
Core Technology Series
- "State Management Toolkit": Principles and best practices for decorators like @State/@Prop/@Link.
- "Distributed Capability Development": Cross-device communication, data sharing, and service flow implementation.
- "Deep Customization of UI Components": Custom component development, theme systems, and animation effects.
Practical Case Series
- "End-to-End Weather App Development": Complete case study from requirements analysis to release.
- "E-commerce App Performance Optimization": Techniques for startup speed, memory usage, and rendering FPS.
- "Cross-Device App Development": Building multi-device apps (phone/tablet/PC) with ArkUI-X.
Certification Preparation Series
- "HarmonyOS Application Developer Certification Guide": Exam outline interpretation and key knowledge review.
- "Certification Practice Questions": Analysis of past exam questions and problem-solving strategies.

Effective Learning Methods

Structured Learning Paths: Use preset paths (e.g., "Application Developer Growth Path") to complete courses in stages.
Learn by Doing: Replicate example code immediately after each lesson and verify results in DevEco Studio.
Utilize Learning Tools: Bookmark key content and take notes using built-in course features.
Engage in Live Sessions: Follow the "Live Calendar" to prepare questions for real-time interaction.
Complete Quizzes: Reinforce knowledge with post-lesson assessments.

Practical Recommendations

Fragmented Learning Strategy: Watch short videos (e.g., API overviews) during commutes; study practical cases in dedicated time blocks.
Maintain Learning Records: Track completed courses, proficiency levels, and pending topics using Excel/Notion.
Combine with Documentation: Bookmark official documentation links mentioned in courses for deeper exploration.
Join Learning Communities: Find study partners through course comments or Huawei Developer Forum for collaborative projects.
Monitor Course Updates: Regularly check the "Latest Courses" section for new HarmonyOS features.
Leverage Certification Goals: Validate learning outcomes by pursuing "HarmonyOS Application Developer Certification".

Conclusion and Outlook

As a key educational resource in the HarmonyOS ecosystem, Developer Classroom provides standardized and efficient learning channels. With HarmonyOS's rapid iteration, the platform will continue expanding content and introducing innovations like AI-driven recommendations and virtual labs. Developers should fully utilize this platform to build systematic knowledge and enhance technical capabilities through practice.

Case Study: ArkTS Basic Syntax

Below are core examples of ArkTS basic syntax, covering key concepts like variable declaration, custom components, and event handling:

1. Variable Declaration and Type Inference

// Explicit type declaration
let message: string = 'Hello HarmonyOS';
const version: number = 4.0;

// Automatic type inference (recommended)
let appName = 'MyApp'; // Inferred as string
const maxCount = 100;  // Inferred as number

2. Custom Components and UI Description

@Entry
@Component
struct BasicComponent {
  // State variable: UI auto-refreshes on value change
  @State count: number = 0;

  build() {
    Column() {
      // Text component
      Text('ArkTS Basic Syntax Example')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      // Button component with event handling
      Button('Click Count: ' + this.count)
        .onClick(() => {
          this.count++;
        })
        .margin(10)
        .width(200)

      // Divider component
      Divider()
        .height(2)
        .color('#eeeeee')

      // Conditional rendering
      if (this.count > 3) {
        Text('Count exceeds 3!')
          .fontColor(Color.Red)
      }
    }
    .width('100%')
    .padding(20)
  }
}

3. Event Handling and State Management

@Component
struct EventHandlingExample {
  @State inputText: string = '';

  // Custom function
  private handleInputChange(value: string) {
    this.inputText = value;
  }

  build() {
    Column() {
      TextInput({
        placeholder: 'Enter text'
      })
      .onChange(this.handleInputChange)
      .width(300)
      .margin(10)

      Text('You entered: ' + this.inputText)
        .fontSize(16)
    }
    .padding(20)
  }
}

HarmonyOS Learning: Multi-device Adaptation for Phones, iPads, PCs, and Foldables

xhunmon — Tue, 17 Jun 2025 09:59:25 +0000

Introduction

As the HarmonyOS ecosystem continues to expand, applications need to adapt to diverse device forms including phones, tablets, PCs, and foldable screens. Multi-device adaptation is crucial for enhancing user experience and represents the core capability of HarmonyOS distributed systems. This article details official adaptation solutions and practical techniques to help developers build consistent cross-device application experiences.

Official Resources

Huawei's official multi-device adaptation guide:

This document systematically explains adaptation principles, layout strategies, and device-specific feature utilization, serving as the authoritative reference for multi-device development.

Detailed Explanation

Core Adaptation Principles

Write Once, Run Anywhere: Use ArkUI declarative paradigm to adapt multiple devices with a single codebase.
Prioritize Flexible Layouts: Employ relative units (percentages, Flexbox) instead of fixed pixel values.
Device Capability Awareness: Dynamically adjust UI using APIs to obtain device information (screen size, resolution, input methods).
Interaction Mode Adaptation: Optimize interaction logic for different input methods (touchscreen, mouse/keyboard).

Key Technical Solutions

Adaptive Layout System
- Flex Layout: Use Flex containers with properties (justifyContent, alignItems) for flexible arrangements.
- Grid System: Build responsive grids via Row/Column components with breakpoints property.
- Percentage Units: Use % or vp (virtual pixels) for automatic resolution adaptation.
Device Information Acquisition

import { deviceInfo } from '@kit.BasicServicesKit';
const deviceType = deviceInfo.deviceType; // 'phone' | 'tablet' | '2in1'
const screenWidth = deviceInfo.screenWidth;
const screenHeight = deviceInfo.screenHeight;
console.log(`Device type: ${deviceType}, Screen size: ${screenWidth}x${screenHeight}`);

Conditional Rendering Dynamically load components based on device type:

if (deviceType === 'tablet') {
  // Display sidebar on tablets
  Sidebar();
} else {
  // Display bottom navigation on phones
  BottomNavigation();
}

Foldable Device Adaptation Handling fold state changes:

import { display } from '@kit.ArkUI';
// Monitor fold status changes
display.on('foldStatusChange', (data) => {
  if (data.status === 'unfolded') {
    // Multi-column layout in unfolded state
    this.columnCount = 3;
  } else {
    // Single-column layout in folded state
    this.columnCount = 1;
  }
});

Common Adaptation Scenarios

Screen Size Adaptation: Define styles for different sizes via media queries (@media).
Resolution Adaptation: Store images in resource directories (e.g., hdpi, xhdpi).
Input Method Adaptation: Add keyboard shortcuts for PC and mouse hover effects.
Portrait/Landscape Switching: Adjust layouts when screen orientation changes.
Split-Screen Mode Adaptation: Reorganize UI in multi-window scenarios.

Practical Recommendations

Establish Device Test Matrix: Cover at least 4 device types (phone, 10-inch tablet, 24-inch PC, foldable).
Use Multi-Device Preview: DevEco Studio supports simultaneous preview across devices.
Encapsulate Adaptation Components: Create reusable components (e.g., ResponsiveContainer, DeviceAwareButton).
Avoid Over-Adaptation: Maintain core functionality consistency; optimize for specific devices only when necessary.
Performance Considerations: Mitigate rendering overhead with lazy loading and conditional compilation.
Leverage Official Templates: Use ArkUI-X multi-device templates to reduce repetitive work.

Conclusion and Outlook

Multi-device adaptation is a core challenge in HarmonyOS development and a key advantage of its ecosystem. As device forms diversify, future adaptation will become more intelligent, potentially using AI to generate optimal layouts automatically. Developers should master official adaptation solutions and apply them flexibly to build truly cross-device experiences.

References

Multi-device Development Guide:
ArkUI Layout Documentation:
Foldable Device Development Guide:

HarmonyOS Learning: Problem Finding Solutions

xhunmon — Tue, 17 Jun 2025 09:58:23 +0000

Problem-Solving Strategies in HarmonyOS Development

Introduction

During HarmonyOS application development, encountering technical issues is common. Efficient problem identification and resolution capabilities are crucial for improving development efficiency. Huawei provides multiple problem-solving channels, including precise search tools, official support services, and AI assistants, to help developers quickly locate and resolve issues.

Official Resources Introduction

Huawei Developer Official Search Portal: This platform supports multi-dimensional filtering, allowing specification of search scope (e.g., Guides, API Reference, Forums) and API versions. It also provides the official AI assistant "Xiaoyi" ( as an auxiliary consultation channel.

Detailed Explanation

Core Functions of Official Search Tools

Multi-dimensional Filtering: Left panel allows filtering by "Document Type" (Guides/API/Sample Code), "Product Version" (HarmonyOS NEXT/4.0, etc.), and "Release Date" for precise resource targeting.
Keyword Optimization: Supports technical term suggestions (e.g., entering "LazyForEach" automatically prompts related component documentation) and highlights matching content.
Contextual Association: Search results automatically link to related cases and FAQs, forming a knowledge network.
Multi-language Support: Provides both Chinese and English document retrieval to meet international development needs.

Problem-Solving Priority Strategy

Prioritize "Guides" Documentation: Official Guides offer refined content focusing on core processes and best practices, with concise and highly accurate information suitable for quick resolution of basic issues.
Secondary Choice: API Reference: Consult API Reference when needing specific interface parameters or return value descriptions to ensure standardized calls.
Case Library and Forum Supplement: For complex scenarios, refer to the official case library ( or developer forum ( for experience sharing.
Official Technical Support: If unresolved through above channels, submit issues via the "Ticket Submission" feature (requires developer account login), typically receiving responses within 1-3 business days.

Usage Tips for Official AI Assistant "Xiaoyi" and CodeGenie

Precise Questioning: Include technical context (e.g., "ArkUI-X cross-device adaptation"), specific issues (e.g., "List component scrolling lag"), and attempted solutions to improve answer relevance.
Code Assistance: Directly paste error messages or code snippets; Xiaoyi analyzes syntax errors and provides modification suggestions.
Document Interpretation: Request simplified explanations of complex concepts in official documentation (e.g., "Explain @builder decorator usage with examples").
Multi-turn Dialogue: Refine questions through follow-ups (e.g., "The previous solution is incompatible with HarmonyOS 4.0; are there alternatives?").

Practical Advice

Build Personal Knowledge Base: Record high-frequency issues and solutions (using Notion or Markdown) to create a personalized knowledge repository.
Utilize Browser Bookmarks: Categorize and bookmark frequently used documentation pages (e.g., "UI Component Guides", "State Management Best Practices") to reduce repetitive searches.
Error Log Analysis: For crash issues, prioritize checking Logcat logs in DevEco Studio and extract key error codes (e.g., "ERROR 0x80000000") for targeted searches.
Version Compatibility Checks: Specify HarmonyOS versions explicitly during searches (e.g., "HarmonyOS NEXT 1.0 LazyForEach") to avoid solution failures due to version differences.
Community Participation: Share solutions in forums and monitor "Hot Issues" sections to proactively avoid common pitfalls.

Conclusion and Outlook

Efficient problem-solving capabilities are core competencies for developers. Huawei's search tools, technical support, and AI assistants form a comprehensive problem-solving ecosystem. As the HarmonyOS ecosystem evolves, problem-solving channels will become more intelligent (e.g., precision recommendations based on developer history). Developers should continuously optimize problem-location methods to enhance development fluency.

CodeGenie Case Study

Q: How to dynamically calculate Text length?

A:

In HarmonyOS ArkUI, dynamically calculate Text component length using these methods:

1. Core Calculation Methods

Use measureText Interface Obtain actual text dimensions via measureText from @kit.ArkUI.component.measure[webpage13]:

import measure from '@kit.ArkUI.component.measure';

// Measure text width (unit: px)
const textWidth = measure.measureText({
  textContent: "Sample text",
  fontSize: 20,
  fontWeight: FontWeight.Normal
});

Unit Conversion Techniques

Convert pixels to virtual pixels (vp):

  import { px2vp } from '@kit.ArkUI.component';

  const vpWidth = px2vp(textWidth);

- Use `fp` units for system font scaling adaptation[webpage15]

2. Dynamic Adaptation Implementation

Combine with Screen Dimensions Calculate available space after obtaining screen width:

import display from '@kit.ArkUI.component';

const screenWidth = display.getAllDisplays().then(displays => {
  return displays.width; // Get screen pixel width
});

Container Constraint Handling When parent containers use layoutWeight, apply constraintSize for dimension limits[webpage3][webpage8]:

Text('Long text content')
  .constraintSize({ maxWidth: '70%' })
  .layoutWeight(1)

3. Advanced Application Solutions

Dynamic Text Adjustment Implement truncation logic based on measurement results:

@State textContent: string = "";
@State displayText: string = "";

// Calculate and truncate text
function truncateText() {
  const maxWidth = 200; // Maximum allowed width (px)
  const measuredWidth = measure.measureText({
    textContent: this.textContent,
    fontSize: 16
  });

  if (measuredWidth > maxWidth) {
    this.displayText = this.textContent.slice(0, -3) + '...';
  } else {
    this.displayText = this.textContent;
  }
}

Performance Optimization Tips
- Apply debouncing to frequently changing text content[webpage1]
- Cache calculated text dimensions[webpage13]

4. Key Considerations

Measurement results include font style impacts (bold/italic increase actual width)[webpage13]
Account for character width differences in Chinese-English mixed text[webpage12]
Call measureText after component rendering completes (recommended in onAppear lifecycle)[webpage1]

These solutions enable precise text length calculation and dynamic adaptation across different screen sizes. For optimal display, combine with properties like TextOverflow.Ellipsis[webpage5][webpage12].