Forem: CodeCao

Audio-to-Text Implementation with HarmonyOS AI - Core Speech Kit

CodeCao — Sat, 14 Jun 2025 10:54:02 +0000

I. Scenarios and Constraints

Scenario Requirements:

Convert Chinese audio (including mixed Chinese-English content) to text in real-time or offline on devices like phones/tablets without network connectivity. Suitable for scenarios such as real-time subtitles for hearing-impaired users and offline interactions with voice assistants.

Constraints:

● Audio Format: Supports PCM format, short speech mode (≤60 seconds), and long speech mode (≤8 hours).

● Device Limitations: Does not support emulators; requires physical device debugging.

● Offline Capability: Relies on HarmonyOS's local speech recognition engine, currently supporting only Mandarin Chinese.

II. Development Preparation

1. Permission Configuration

○ Microphone Permission: Declare ohos.permission.MICROPHONE in module.json5 and dynamically request user authorization:

"requestPermissions": [{
  "name": "ohos.permission.MICROPHONE",
  "reason": "Used for speech-to-text conversion",
  "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
}]

2. Dependency Import

Import speech recognition and audio processing modules:

import { speechRecognizer } from '@kit.CoreSpeechKit';
import { audio, AudioCapturer } from '@kit.AudioKit';

III. Core Development Steps

1. Initialize the Speech Recognition Engine

let asrEngine: speechRecognizer.SpeechRecognitionEngine;
const sessionId = 'session_001';

// Configure engine parameters: Chinese, offline mode, short speech type
const initParams: speechRecognizer.CreateEngineParams = {
  language: 'zh-CN',
  online: 0, // 0 indicates offline mode
  extraParams: { "recognizerMode": "short" }
};

// Create the engine instance
speechRecognizer.createEngine(initParams, (err, engine) => {
  if (!err) {
    asrEngine = engine;
    console.info('Engine initialized successfully');
  } else {
    console.error(`Engine initialization failed: ${err.code}-${err.message}`);
  }
});

Key Parameter Explanations:

● online: 0 for local recognition, 1 for online recognition (requires network).

● recognizerMode: short (short speech) or long (long speech mode).

2. Configure Callback Listeners

Set up callbacks to handle recognition results and errors:

asrEngine.setListener({
  onStart: (sessionId, msg) => console.info(`Recognition started: ${msg}`),
  onResult: (sessionId, result) => {
    console.info(`Recognition result: ${result.result}`); // Real-time text output
    // Process intermediate (unstable) and final (stable) results
  },
  onError: (sessionId, code, msg) => console.error(`Error: ${code}-${msg}`),
  onComplete: (sessionId, msg) => console.info(`Recognition completed: ${msg}`)
});

3. Audio Input Processing

Option A: Read PCM Stream from File

async function readPCMFile(filePath: string) {
  const file = fileIo.openSync(filePath, fileIo.OpenMode.READ_ONLY);
  let buffer = new ArrayBuffer(1280); // Read 1280 bytes at a time
  while (fileIo.readSync(file.fd, buffer) === 1280) {
    const uint8Array = new Uint8Array(buffer);
    asrEngine.writeAudio(sessionId, uint8Array); // Write audio stream in segments
    await sleep(40); // 40ms interval to simulate real-time stream
  }
  fileIo.closeSync(file);
}

Option B: Real-time Microphone Recording

const audioCapturer = new AudioCapturer();
audioCapturer.init((data: ArrayBuffer) => {
  const uint8Array = new Uint8Array(data);
  asrEngine.writeAudio(sessionId, uint8Array); // Write real-time audio stream
});
audioCapturer.start(); // Start recording

Notes:

● Audio stream length must be 640 or 1280 bytes. Recommended write intervals: 20ms (640 bytes) or 40ms (1280 bytes).

● Configure maxAudioDuration (unit: ms) in long speech mode to control maximum recognition time.

4. Start and Stop Recognition

// Start recognition (file or real-time stream)
const startParams: speechRecognizer.StartParams = {
  sessionId,
  audioInfo: {
    audioType: 'pcm',
    sampleRate: 16000,  // 16kHz sampling rate
    soundChannel: 1,    // Mono channel
    sampleBit: 16       // 16-bit depth
  }
};
asrEngine.startListening(startParams);

// Stop recognition
asrEngine.finish(sessionId);  // Normal completion
asrEngine.cancel(sessionId);  // Force cancellation
asrEngine.shutdown();         // Release engine resources

5. Error Handling and Debugging

Common Error Codes:

● 1002200002: Recognition started repeatedly. Ensure single invocation per session.

● 1002200006: Engine busy. Check concurrency limits.

● Permission denial: Ensure dynamic microphone permission request and verify via checkAccessToken().

IV. Complete Example and Optimization Suggestions

Example Code: The provided Index.ets and AudioCapturer.ts fully implement both file reading and microphone recording input methods. Developers can directly integrate and adapt them.

Optimization Suggestions:

Audio Preprocessing: Ensure input PCM meets 16kHz/16bit/mono format to avoid recognition failures.
Resource Management: Call shutdown() promptly after recognition to prevent memory leaks.
User Experience: Add UI progress indicators, e.g., update text area in real-time within onResult callback.

V. Application Scenario Expansion

● Real-time Subtitles: Overlay recognized text on video playback interfaces using the onResult callback.

● Offline Command Recognition: Predefine keywords to enable voice control without network connectivity.

● Accessibility Interaction: Provide conversation transcription for hearing-impaired users, supporting text record saving.

Technical Analysis and Development Practice of HarmonyOS AI - Core Speech Kit Offline Text-to-Speech Technology

CodeCao — Sat, 14 Jun 2025 10:52:23 +0000

I. Technical Background and Scenario Value

Huawei Core Speech Kit provides HarmonyOS developers with offline text-to-speech (TTS) capabilities, supporting Chinese, numeric, and mixed Chinese-English text synthesis. Its core scenarios focus on accessibility services, such as providing screen reading for visually impaired users in offline environments, addressing the pain point that traditional TTS relies on the internet. Key features include:

● Offline operation: No network connection required, ensuring privacy and stability

● Multi-strategy broadcasting: Supports word/number pronunciation, silent insertion, and Chinese character tone customization

● Low-latency response: Meets real-time interaction needs

II. Core Function Implementation

1. Engine Initialization

Create a TTS engine instance via createEngine and configure language, voice (e.g., "Ling Xiaoshan"), and operation mode (online/offline):

// Engine parameter configuration example  
let initParams: textToSpeech.CreateEngineParams = {  
  language: 'zh-CN',  
  person: 0,  // Default voice  
  online: 1,   // Online mode  
  extraParams: { style: 'interaction-broadcast', locate: 'CN' }  
};  
textToSpeech.createEngine(initParams, (err, engine) => {  
  // Process the engine instance  
});

2. Text Broadcasting Control

Trigger broadcasting via the speak method, supporting dynamic parameter adjustment:

let speakParams: textToSpeech.SpeakParams = {  
  requestId: 'unique_id',  // Unique identifier  
  extraParams: {  
    speed: 1.2,     // Speaking rate  
    volume: 15,     // Volume  
    pitch: 0.8      // Pitch  
  }  
};  
ttsEngine.speak("文本内容[h1][n2]", speakParams);

3. Broadcasting Strategy Configuration (Syntax Markup)

● Word broadcasting strategy: [hN]

"Hello[h1] World" // h1=letter-by-letter pronunciation, h2=word pronunciation

● Number processing strategy: [nN]

"[n2]12345" // n2=numeric reading (e.g., "一万两千三百四十五")

● Silent insertion: [pN] (unit: ms)

"开始[p500]播报" // Insert 500ms silence

● Chinese character pronunciation calibration: [=Pinyin+Tone]

"着[=zhuo2]手" // Force pronunciation as "zhuó"

III. Development Practice Key Points

1. Lifecycle Management

● Status monitoring: Handle broadcasting events via SpeakListener callback

speakListener: textToSpeech.SpeakListener = {  
  onStart: (id, res) => { /* Broadcasting starts */ },  
  onData: (id, audio) => { /* Receive audio stream */ },  
  onError: (id, code, msg) => { /* Error handling */ }  
};

● Resource release:

ttsEngine.stop();      // Stop current broadcasting  
ttsEngine.shutdown();  // Destroy the engine instance

2. Advanced Function Integration

● Audio stream processing: Obtain PCM data via onData callback for custom playback

● Multilingual support: Query available voices via listVoices

ttsEngine.listVoices({ online: 1 }, (err, voices) => {  
  console.log("Supported voices:", voices);  
});

IV. Constraints and Optimization Suggestions

● Device limitations: Only supports real devices, not emulators

● Text length: Single input ≤ 10,000 characters

● Performance optimization: Reuse engine instances to avoid frequent creation/destruction

● Error handling: Listen to onError and handle error codes (e.g., network exceptions, engine busy states)

V. Application Scenario Expansion

● Accessibility services: System-level screen reading

● Education: E-book reading, language learning pronunciation assistance

● IoT devices: Smart home voice feedback

Conclusion

Huawei Core Speech Kit provides an efficient accessibility solution for the HarmonyOS ecosystem through offline TTS capabilities and flexible broadcasting strategies. Developers can quickly integrate using the code paradigms provided in this article, customize voice interaction solutions based on business needs, and help build more inclusive smart terminal experiences.

Implementing Vertical Carousel Notifications in HarmonyOS Next

CodeCao — Sat, 14 Jun 2025 10:48:18 +0000

To achieve the automatic vertical scrolling effect for text in ArkUI, the Swiper component can be used. The Swiper component provides the capability to display content in a sliding carousel. As a container component, Swiper can carousel through its child components when multiple ones are configured.

1. Vertical Carousel Implementation

Swiper() {
  ForEach(this.transactionList, (item: TransactionInfo) => {
    Row() {
      Image(StrUtil.isBlank(item.TitleImage) ? $r("app.media.icon_circular_default_head") : item.TitleImage)
        .width(44)
        .height(44)
        .borderRadius(22)
      Text(item.Title)
        .fontSize(14)
        .fontColor($r("app.color.text_one"))
        .maxLines(2)
        .ellipsisMode(EllipsisMode.END)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
        .lineHeight(22)
        .margin({ left: 9 })
        .layoutWeight(1)
    }.onClick(() => {
      ToastUtil.showToast("Clicked on transaction report")
    })
  })
}
.vertical(true) // Enable vertical carousel direction
.loop(true)    // Enable loop playback
.autoPlay(true) // Enable auto-play
.indicator(false) // Whether to show navigation dots
.height(44)
.margin({ left: 9 })
.layoutWeight(1)

Key Properties:

vertical: When true, the carousel slides vertically; when false, it slides horizontally (default: false).
loop: Controls whether the carousel loops (default: true).
autoPlay: Enables automatic carousel of child components (default: false, interval: 3000ms).
interval: Carousel interval in milliseconds (default: 3000ms).
indicator: Whether to display navigation dots.

2. Implementing a Custom Dialog

Use the @CustomDialog decorator to create a custom dialog where you can define the dialog's content, add confirm/cancel buttons, and include data functions.

import { StrUtil } from "@pura/harmony-utils"
import { TransactionInfo } from "../model/TransactionInfo"

@Preview
@CustomDialog
export struct DealInfoDialog {
  dealDialogController?: CustomDialogController
  @Prop transaction?: TransactionInfo = undefined

  build() {
    Column() {
      Text("Breaking News: Important Announcement")
        .width("60%")
        .margin({ top: 92 })
        .fontSize(16)
        .fontWeight(600)
        .fontColor($r("app.color.yellow_aureus"))
        .textAlign(TextAlign.Center)
      Row() {
        Image(StrUtil.isBlank(this.transaction?.TitleImage) ? $r("app.media.placeholder") :
          this.transaction?.TitleImage).width(68).height(68).borderRadius(6)
        Column() {
          Text(this.transaction?.Title)
            .fontSize(13)
            .fontWeight(600)
            .fontColor($r("app.color.yellow_aureus"))
            .maxLines(1)
            .width("70%")
            .ellipsisMode(EllipsisMode.END)
            .textOverflow({ overflow: TextOverflow.Ellipsis })
          Text("Property ID: " + StrUtil.toStr(this.transaction?.PropertyNo))
            .fontSize(12)
            .fontColor($r("app.color.yellow_aureus"))
          Row() {
            Text(this.transaction?.Price.toString()).fontColor("#DC2424").fontSize(18).fontWeight(800)
            Text("CNY").fontColor("#DC2424").fontSize(12).fontWeight(600).baselineOffset(-2)
          }.backgroundColor($r("app.color.yellow_aureus"))
          .padding({
            left: 10,
            right: 10,
            top: 1,
            bottom: 1
          })
          .borderRadius(4)
        }.height(68)
        .alignItems(HorizontalAlign.Start)
        .justifyContent(FlexAlign.SpaceBetween)
        .margin({ left: 12 })
      }.width("65%")
      .margin({ top: 14 }).alignItems(VerticalAlign.Top)

      Text(this.transaction?.ShareInfo)
        .width("65%")
        .margin({ top: 20 })
        .fontSize(13)
        .fontColor($r("app.color.yellow_aureus"))
    }
    .width("100%")
    .height(529)
    .backgroundImage($r("app.media.icon_deal_dialog_bg"))
    .backgroundImageSize({ width: "100%", height: "100%" })
  }
}

Create a Controller to Link with the Decorator:

this.dealDialogController = new CustomDialogController({
  builder: DealInfoDialog({ transaction: this.transaction }),
  alignment: DialogAlignment.Center,
  customStyle: true,
  offset: { dx: 0, dy: -20 },
  maskColor: 0x66000000
})

Usage:

this.dealDialogController?.open()

The Usage of Pop-up Boxes in HarmonyOS

CodeCao — Sat, 14 Jun 2025 10:46:40 +0000

Overview and Classification of Pop-up Boxes in HarmonyOS Next

A pop-up box is a modal window that temporarily displays information or actions requiring user attention while maintaining the current contextual environment. Users must complete relevant interactive tasks within the modal pop-up before exiting the modal mode. Pop-up boxes can be independent of any component binding, and their content is typically composed of various components (such as text, lists, input fields, images, etc.) to achieve layout. ArkUI currently provides two categories of pop-up components: custom-style and fixed-style.

Custom Pop-up Boxes

Developers need to pass custom components into the pop-up box based on the usage scenario to implement personalized content. These mainly include:

Basic custom pop-up box (CustomDialog)
UI-component-independent global custom pop-up box (openCustomDialog)

Fixed-style Pop-up Boxes

Developers can use fixed-style pop-up boxes by specifying the text content and button operations to achieve simple interactive effects. These mainly include:

Alert dialog (AlertDialog)
Action sheet (ActionSheet)
Picker dialog (PickerDialog)
Dialog (showDialog)
Action menu (showActionMenu)

This article focuses on the usage of custom pop-up boxes (fixed-style pop-ups can refer to the official documentation). There are two main implementation methods for custom pop-ups:

Basic custom pop-up box (CustomDialog) (not recommended)
UI-component-independent global custom pop-up box (openCustomDialog) (recommended)

Basic Custom Pop-up Box (`CustomDialog`)

CustomDialog is a custom pop-up box suitable for user interaction scenarios such as advertisements, rewards, warnings, and software updates. It displays custom pop-ups through the CustomDialogController class. When using pop-up components, custom pop-ups are preferred for easy customization of styles and content.

1. `@CustomDialog` Decorator

Use the @CustomDialog decorator to define a custom pop-up box, where you can customize the pop-up content (e.g., adding confirm/cancel buttons and data functions):

2. `CustomContentDialog`

Use CustomContentDialog to customize pop-up boxes, supporting both custom content areas and operation-area button styles (available from API version 12).

Name	Type	Required	Decorator Type	Description
controller	CustomDialogController	Yes	-	Pop-up controller. Note: Not decorated with `@Require`, so parameter validation is not enforced during construction.
contentBuilder	() => void	Yes	@BuilderParam	Pop-up content.
primaryTitle	ResourceStr	No	-	Pop-up title.
secondaryTitle	ResourceStr	No	-	Pop-up auxiliary text.
localizedContentAreaPadding	LocalizedPadding	No	-	Inner padding of the pop-up content area.
contentAreaPadding	Padding	No	-	Inner padding of the pop-up content area (invalid if `localizedContentAreaPadding` is set).
buttons	ButtonOptions[]	No	-	Buttons in the pop-up operation area (supports up to 4 buttons).
theme	Theme / CustomTheme	No	-	Theme information (can be a `CustomTheme` or a `Theme` instance from `onWillApplyTheme`).
themeColorMode	ThemeColorMode	No	-	Custom pop-up light/dark mode.

CustomContentDialog supports custom content with contentBuilder, buttons, etc. Similar to the @CustomDialog decorator, it can include buttons and data. For fully customized styles, only the contentBuilder parameter is needed:

import { CustomContentDialog } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomContentDialog({
      primaryTitle: 'Title',
      secondaryTitle: 'Auxiliary text',
      contentBuilder: () => {
        this.buildContent();
      },
      buttons: [
        { 
          value: 'Button 1',
          buttonStyle: ButtonStyleMode.TEXTUAL, 
          action: () => {
            console.info('Callback when the button is clicked')
          }
        },
        {
          value: 'Button 2',
          buttonStyle: ButtonStyleMode.TEXTUAL,
          role: ButtonRole.ERROR
        }
      ],
    }),
  });

  build() {
    Column() {
      Button("Show custom content pop-up")
        .onClick(() => {
          this.dialogController.open()
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  // Custom pop-up content area
  @Builder
  buildContent(): void {
    Column() {
      Text('Content area')
    }
    .width('100%')
  }
}

UI-component-independent Global Custom Pop-up Box (openCustomDialog)

The official recommendation is to use openCustomDialog over CustomDialogController for implementing custom pop-up boxes. Due to multiple limitations of CustomDialogController (e.g., no support for dynamic creation or refresh), in relatively complex scenarios, it is recommended to use the openCustomDialog interface provided by the PromptAction object obtained from UIContext to implement custom pop-ups.

There are two parameter passing methods for creating custom pop-up boxes with openCustomDialog:

:::info

openCustomDialog (with ComponentContent)

Encapsulating content via ComponentContent decouples from the UI, enabling more flexible calls to meet developers' encapsulation needs. It offers stronger flexibility with fully customizable styles and supports dynamically updating pop-up parameters using updateCustomDialog after the pop-up is opened.

openCustomDialog (with builder)

Compared to ComponentContent, builder must bind to the context, introducing some UI coupling. This method uses default pop-up styles, suitable for scenarios where developers want consistency with the system's default pop-up aesthetics.

:::

1. Initialize Pop-up Configuration

Obtain the PromptAction object and initialize pop-up configurations (e.g., modify position, animation, and other settings).
Create ComponentContent to define the pop-up content, where wrapBuilder(radioDialogView) encapsulates custom components.

2. Open the Custom Pop-up Box

Calling the openCustomDialog interface opens a pop-up with customStyle: true by default, meaning the content style fully follows the contentNode customization.

3. Close the Custom Pop-up Box

After closing the pop-up, call the dispose() method of ComponentContent to release the corresponding resources.

Tip: The ComponentContent object to be closed must be passed in when closing the pop-up.

4. Update the Custom Pop-up Content

To update the content of custom components in the pop-up, use the update() method provided by ComponentContent, passing in the same data object used during display.

5. Complete Code

// Import ArkUI dialog operation modules and basic service error types
promptAction?: PromptAction

// Private constructor
private constructor() {
  console.info('Creating custom dialog singleton');
}

/**
 * Get the singleton instance (static method)
 * @returns The global unique instance
 */
public static getInstance(): RadioAppDialog {
  if (!RadioAppDialog.instance) {
    RadioAppDialog.instance = new RadioAppDialog();
  }
  return RadioAppDialog.instance;
}

/**
 * Reset the singleton instance (for testing or special scenarios)
 */
public static resetInstance(): void {
  RadioAppDialog.instance = new RadioAppDialog();
}


// Set dialog content component (supports chaining)
init(context: UIContext, radioSelectBean: RadioSelectBean): RadioAppDialog {
  this.contentNode = new ComponentContent(context, wrapBuilder<[RadioSelectBean]>(radioDialogView), radioSelectBean);
  this.promptAction = context.getPromptAction();
  this.options = {
    alignment: DialogAlignment.Bottom,
    transition: TransitionEffect.move(TransitionEdge.BOTTOM)
      .animation({ duration: 300 }),
  }
  return this
}

// Set dialog options (supports chaining)
setOptions(options: promptAction.BaseDialogOptions): RadioAppDialog {
  this.options = options;
  return this;
}

// Update dialog data
updateData(obj?: Object) {
  this.contentNode?.update(obj)
}


// Show the custom dialog
show() {
  if (this.contentNode !== null) {
    this.promptAction?.openCustomDialog(this.contentNode, this.options)
      .then(() => {
        console.info('Custom dialog opened successfully')
      })
      .catch((error: BusinessError) => {
        // Error handling: get error code and message
        let message = (error as BusinessError).message;
        let code = (error as BusinessError).code;
        console.error(`Dialog opening failed. Error code: ${code}, message: ${message}`);
      })
  }
}

// Close the custom dialog
close() {
  if (this.contentNode !== null) {
    this.promptAction?.closeCustomDialog(this.contentNode)
      .then(() => {
        this.contentNode?.dispose()
        console.info('Custom dialog closed successfully')
      })
      .catch((error: BusinessError) => {
        let message = (error as BusinessError).message;
        let code = (error as BusinessError).code;
        console.error(`Dialog closing failed. Error code: ${code}, message: ${message}`);
      })
  }
}

// Update dialog configuration
updateDialog(options: promptAction.BaseDialogOptions) {
  if (this.contentNode !== null) {
    this.promptAction?.updateCustomDialog(this.contentNode, options)
      .then(() => {
        console.info('Dialog configuration updated successfully')
      })
      .catch((error: BusinessError) => {
        let message = (error as BusinessError).message;
        let code = (error as BusinessError).code;
        console.error(`Dialog update failed. Error code: ${code}, message: ${message}`);
      })
  }
}

Implementing the Wooden Fish Knocking Mini Game on HarmonyOS

CodeCao — Sat, 14 Jun 2025 10:44:52 +0000

"Knocking the Wooden Fish" - A Zen-inspired Mini Game

This article delves into the core technical aspects of implementing a "knocking wooden fish" game using HarmonyOS's ArkUI framework. Key features include animated interactions, state management, haptic feedback, and sound effects.

I. Architecture Design & Project Setup

1.1 Project Structure

The complete project consists of these core modules:

├── entry/src/main/ets/
│   ├── components/         // Custom UI components
│   ├── model/              // Data models (e.g., StateArray)
│   ├── pages/              // Page components (WoodenFishGame.ets)
│   └── resources/          // Media assets (wooden fish icons, sound effects)

This modular design separates the UI layer (pages), logic layer (model), and resource layer (resources), adhering to HarmonyOS development standards.

1.2 Component-based Development

Using the @Component decorator to create reusable UI units, with @Entry marking the page entry. Key states are managed via @State:

@Entry
@Component
struct WoodenFishGame {
  @State count: number = 0;                // Merit counter
  @State scaleWood: number = 1;           // Wooden fish scale factor
  @State rotateWood: number = 0;          // Wooden fish rotation angle
  @State animateTexts: Array<StateArray> = []; // Animation queue
  private audioPlayer?: media.AVPlayer;    // Audio player instance
  private autoPlay: boolean = false;       // Auto-tap flag
}

@State enables reactive programming: UI elements automatically re-render when state variables change.

II. Animation System Deep Dive

2.1 Composite Animation for Knocking

The animation consists of two phases: compression (100ms) and elastic recovery (200ms), using animateTo for smooth transitions:

playAnimation() {
  // Phase 1: Quick compression + left rotation
  animateTo({
    duration: 100, 
    curve: Curve.Friction // Simulates physical resistance
  }, () => {
    this.scaleWood = 0.9; // Scale X/Y to 90%
    this.rotateWood = -2; // Rotate counter-clockwise 2 degrees
  });

  // Phase 2: Elastic recovery
  setTimeout(() => {
    animateTo({
      duration: 200,
      curve: Curve.Linear // Ensures smooth recovery
    }, () => {
      this.scaleWood = 1; 
      this.rotateWood = 0;
    });
  }, 100); // Delay for animation chaining
}

Curve Selection:

Curve.Friction: Simulates impact resistance
Curve.Linear: Ensures consistent recovery speed

2.2 Floating Merit Text Animation

Manages multiple animations using a dynamic array with unique IDs:

countAnimation() {
  const animId = new Date().getTime(); // Unique timestamp ID
  // Add new animation element
  this.animateTexts = [...this.animateTexts, { 
    id: animId, 
    opacity: 1, 
    offsetY: 20 
  }];

  // Fade out and float animation
  animateTo({
    duration: 800,
    curve: Curve.EaseOut // Simulates inertia
  }, () => {
    this.animateTexts = this.animateTexts.map(item => 
      item.id === animId ? 
        { ...item, opacity: 0, offsetY: -100 } : item
    );
  });

  // Clean up after animation completes
  setTimeout(() => {
    this.animateTexts = this.animateTexts.filter(t => t.id !== animId);
  }, 800); // Synchronized with animation duration
}

Key Techniques:

Data-driven: Modifying animateTexts triggers UI re-render
Layered animation: Control opacity and vertical offset
Memory optimization: Remove completed animations to prevent bloat

III. Multi-modal Interaction

3.1 Haptic Feedback

Utilizes the @kit.SensorServiceKit vibration module:

vibrator.startVibration({
  type: "time",       // Time-based vibration
  duration: 50        // 50ms short pulse
}, {
  id: 0,              // Vibrator ID
  usage: 'alarm'      // Resource usage scenario
});

Parameter Tuning:

Duration: 50ms mimics the "crisp" feel of striking wood
Intensity: Automatically optimized by HarmonyOS based on usage

3.2 Audio Playback & Resource Management

Implements sound effects with media.AVPlayer:

aboutToAppear(): void {
  media.createAVPlayer().then(player => {
    this.audioPlayer = player;
    this.audioPlayer.url = ""; 
    this.audioPlayer.loop = false; // Disable looping
  });
}

// Reset playback position on tap
if (this.audioPlayer) {
  this.audioPlayer.seek(0);    // Jump to 0ms
  this.audioPlayer.play();     // Play sound
}

Best Practices:

Preload resources: Initialize player during page setup
Avoid delays: Use seek(0) for instant sound
Resource cleanup: Call release() in onPageHide to prevent leaks

IV. Auto-Tap Functionality

4.1 Timer-State Integration

Toggle auto-tap mode with the Toggle component:

// State toggle callback
Toggle({ type: ToggleType.Checkbox, isOn: false })
  .onChange((isOn: boolean) => {
    this.autoPlay = isOn;
    if (isOn) {
      this.startAutoPlay();
    } else {
      clearInterval(this.intervalId); // Clear timer
    }
  });

// Start timer
private intervalId: number = 0;
startAutoPlay() {
  this.intervalId = setInterval(() => {
    if (this.autoPlay) this.handleTap();
  }, 400); // 400ms interval mimics human tapping
}

Key Improvements:

Track timer with intervalId to ensure cleanup
400ms interval balances smoothness and performance

4.2 Thread Safety & Performance

Risk: Frequent timer triggers may block the UI thread

Solution:

// Clear timer when page is hidden
aboutToDisappear() {
  clearInterval(this.intervalId);
}

Ensures resources are released when the page is inactive.

V. UI Layout & Rendering Optimization

5.1 Layered Layout & Animation Composition

Use Stack for overlapping UI elements:

Stack() {
  // Wooden fish base (bottom layer)
  Image($r("app.media.icon_wooden_fish"))
    .width(280)
    .height(280)
    .margin({ top: -10 })
    .scale({ x: this.scaleWood, y: this.scaleWood })
    .rotate({ angle: this.rotateWood });

  // Floating merit text (top layer)
  ForEach(this.animateTexts, (item, index) => {
    Text(`+1`)
      .translate({ y: -item.offsetY * index }) // Staggered positioning
  });
}

Rendering Optimization:

Add fixedSize(true) to static images to avoid re-layout
Use translate instead of margin for animations to reduce layout recalculations

5.2 Efficient State-to-UI Binding

Dynamic styling with chain methods:

Text(`Merit +${this.count}`)
  .fontSize(20)
  .fontColor('#4A4A4A')
  .margin({ 
    top: 20 + AppUtil.getStatusBarHeight() // Adaptive to notch screens
  })

Adaptation Strategies:

Use AppUtil.getStatusBarHeight() to avoid notch interference
Leverage HarmonyOS's flexible layout for screen size adaptability

VI. Complete Code

import { media } from '@kit.MediaKit';
import { vibrator } from '@kit.SensorServiceKit';
import { AppUtil, ToastUtil } from '@pura/harmony-utils';
import { StateArray } from '../model/HomeModel';

@Entry
@Component
struct WoodenFishGame {
  @State count: number = 0;
  @State scaleWood: number = 1;
  @State rotateWood: number = 0;
  audioPlayer?: media.AVPlayer;
  // Auto-tap feature
  autoPlay: boolean = false;

  // New state variable
  @State animateTexts: Array<StateArray> = []

  aboutToAppear(): void {
    media.createAVPlayer().then(player => {
      this.audioPlayer = player
      this.audioPlayer.url = ""
    })
  }

  startAutoPlay() {
    setInterval(() => {
      if (this.autoPlay) {
        this.handleTap();
      }
    }, 400);
  }

  // Knocking animation
  playAnimation() {
    animateTo({
      duration: 100,
      curve: Curve.Friction
    }, () => {
      this.scaleWood = 0.9;
      this.rotateWood = -2;
    });

    setTimeout(() => {
      animateTo({
        duration: 200,
        curve: Curve.Linear
      }, () => {
        this.scaleWood = 1;
        this.rotateWood = 0;
      });
    }, 100);
  }

  // Tap handler
  handleTap() {
    this.count++;
    this.playAnimation();
    this.countAnimation();

    // Add haptic feedback
    vibrator.startVibration({
      type: "time",
      duration: 50
    }, {
      id: 0,
      usage: 'alarm'
    });

    // Play sound effect
    if (this.audioPlayer) {
      this.audioPlayer.seek(0);
      this.audioPlayer.play();
    }
  }

  countAnimation() {
    // Unique ID to prevent animation conflicts
    const animId = new Date().getTime();
    // Initialize animation state
    this.animateTexts = [...this.animateTexts, {id: animId, opacity: 1, offsetY: 20}];

    // Execute animation
    animateTo({
      duration: 800,
      curve: Curve.EaseOut
    }, () => {
      this.animateTexts = this.animateTexts.map(item => {
        if (item.id === animId) {
          return { id: item.id, opacity: 0, offsetY: -100 };
        }
        return item;
      });
    });

    // Clean up after animation
    setTimeout(() => {
      this.animateTexts = this.animateTexts.filter(t => t.id !== animId);
    }, 800);
  }

  build() {
    Column() {
      // Counter display
      Text(`Merit +${this.count}`)
        .fontSize(20)
        .margin({ top: 20 + AppUtil.getStatusBarHeight() })

      // Wooden fish container
      Stack() {
        // Tappable area
        Image($r("app.media.icon_wooden_fish"))
          .width(280)
          .height(280)
          .margin({ top: -10 })
          .scale({ x: this.scaleWood, y: this.scaleWood })
          .rotate({ angle: this.rotateWood })
          .onClick(() => this.handleTap())

        // Floating text container
        ForEach(this.animateTexts, (item: StateArray, index) => {
          Text(`+1`)
            .fontSize(24)
            .fontColor('#FFD700')
            .opacity(item.opacity)
            .margin({ top: -100 }) // Initial position
            .translate({ y: -item.offsetY * index }) // Vertical displacement
            .animation({ duration: 800, curve: Curve.EaseOut })
        })
      }
      .margin({ top: 50 })

      // Auto-tap toggle (extended feature)
      Row() {
        Toggle({ type: ToggleType.Checkbox, isOn: false })
          .onChange((isOn: boolean) => {
            this.autoPlay = isOn;
            if (isOn) {
              this.startAutoPlay();
            } else {
              clearInterval();
            }
          })
        Text("Auto-Tap")
      }
      .alignItems(VerticalAlign.Center)
      .justifyContent(FlexAlign.Center)
      .width("100%")
      .position({ bottom: 100 })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#f0f0f0')
  }
}

This implementation showcases HarmonyOS ArkUI's capabilities in building engaging, interactive applications with smooth animations, responsive state management, and multi-modal feedback.

Implementing the 2048 Puzzle Game on HarmonyOS Next

CodeCao — Sat, 14 Jun 2025 10:37:07 +0000

2048 is a classic puzzle game where players slide the screen to merge blocks with the same numbers, with the ultimate goal of synthesizing the number 2048. This article is based on the HarmonyOS ArkUI framework and provides a detailed analysis of its implementation process, explaining how to use declarative UI and state management to build such games.

I. Core Data Structures and State Management

1. Game Grid and Scores

The core of the game is a 4x4 two-dimensional array used to store the numbers in each grid. The grid state is managed through the @State decorator to ensure that the UI is automatically refreshed when the data changes:

@State grid: number[][] = Array(4).fill(0).map(() => Array(4).fill(0));
@State score: number = 0; // Current score
@State bestScore: number = 0; // Historical highest score

2. Game Initialization

The initGame method is responsible for resetting the grid, adding initial blocks, and resetting the score. addNewTile is used to generate new blocks in random empty positions (90% probability of generating 2, 10% probability of generating 4):

initGame() {
  this.grid = this.grid.map(() => Array(4).fill(0));
  this.addNewTile();
  this.addNewTile();
  this.score = 0;
}

II. Sliding Logic and Merging Algorithm

1. Direction Handling and Matrix Rotation

The game supports sliding in four directions: up, down, left, and right. To simplify the code logic, matrix rotation is used to uniformly convert movements in different directions into leftward movements:

Leftward: Directly process each row.
Rightward: Reverse the row, move left, and then reverse it back.
Upward/Downward: Rotate the matrix into rows, process it, and then restore it to columns.

// Matrix rotation helper method
const rotate = (matrix: number[][]): number[][] => {
  return matrix[0].map((_, i) => matrix.map(row => row[i]).reverse());
};

2. Single-Row Merging Logic

The processing of each row is divided into three steps:

Remove Spaces: Filter out non-zero numbers.
Merge Identical Numbers: Merge adjacent identical numbers and accumulate the score.
Complete Length: Fill with zeros to a length of 4.

const moveRow = (row: number[]): number[] => {
  let newRow = row.filter(cell => cell !== 0);
  for (let i = 0; i < newRow.length - 1; i++) {
    if (newRow[i] === newRow[i + 1]) {
      newRow[i] *= 2;
      this.score += newRow[i]; // Score accumulation
      newRow.splice(i + 1, 1);
    }
  }
  return [...newRow, ...Array(4 - newRow.length).fill(0)];
};

III. Game End Judgment

The game ends when the grid is full and there are no adjacent blocks that can be merged. The detection is carried out through the following steps:

Check for Spaces: If there are spaces, the game has not ended.
Horizontal Detection: Traverse each row to check for adjacent identical numbers.
Vertical Detection: Traverse each column to check for adjacent identical numbers.

isGameOver(): boolean {
  if (this.grid.some(row => row.includes(0))) return false;
  // Horizontal and vertical detection logic
  // ...
  return true;
}

IV. UI Implementation and Interaction Design

1. Grid Rendering

The Grid component is used to dynamically generate a 4x4 grid, and each GridItem displays different background colors and text colors according to the numerical value:

Grid() {
  ForEach(this.grid, (row: number[], i) => {
    ForEach(row, (value: number, j) => {
      GridItem() {
        Text(value ? `${value}` : '')
          .backgroundColor(this.getTileColor(value))
          .fontColor(this.getTextColor(value));
      }
    })
  })
}

2. Touch Event Handling

The onTouch event listens for sliding events, calculates the difference between the start and end coordinates, and determines the sliding direction:

onTouch((event) => {
  if (event.type === TouchType.Down) {
    this.startX = event.touches[0].x;
    this.startY = event.touches[0].y;
  } else if (event.type === TouchType.Up) {
    const deltaX = event.touches[0].x - this.startX;
    const deltaY = event.touches[0].y - this.startY;
    // Judge the direction and call the move method
  }
});

V. Local Storage and Animation Effects

1. High Score Persistence

PreferencesUtil is used to store and read the highest score to ensure that the data is retained after the application is restarted:

aboutToAppear() {
  this.bestScore = PreferencesUtil.getNumberSync("bestScore");
}

// Update the highest score
if (this.score > this.bestScore) {
  PreferencesUtil.putSync('bestScore', this.score);
}

2. Animation and Visual Effects

Each block's text change is added with a 150ms gradient animation to enhance the user experience:

Text(value ? `${value}` : '')
  .animation({ duration: 150, curve: Curve.EaseOut });

VI. Summary and Complete Code

Through ArkUI's declarative UI and state management, the core logic of 2048 can be efficiently implemented. The key points include:

Matrix rotation simplifies direction processing.
State-driven UI automatic update.
Smooth combination of touch events and animations.

import { HashMap } from '@kit.ArkTS'
import { AppUtil, PreferencesUtil, ToastUtil } from '@pura/harmony-utils'

// index.ets
@Entry
@Component
struct Game2048 {
  @State grid: number[][] = Array(4).fill(0).map(() => Array(4).fill(0)) // 4x4 game grid
  @State score: number = 0 // Current score
  @State bestScore: number = 0 // Historical highest score
  private startX: number = 0 // Touch start X coordinate
  private startY: number = 0 // Touch start Y coordinate

  // Lifecycle method: triggered when the page is about to be displayed
  aboutToAppear() {
    this.initGame()
    this.bestScore = PreferencesUtil.getNumberSync("bestScore") // Read the highest score stored locally
  }

  // Initialize the game
  initGame() {
    this.grid = this.grid.map(() => Array(4).fill(0)) // Reset the grid
    this.addNewTile() // Add two new blocks
    this.addNewTile() // Reset the current score
    this.score = 0
  }

  addNewTile() {
    const emptyCells: [number, number][] = [] // Collect the coordinates of empty cells
    this.grid.forEach((row, i) => {
      row.forEach((cell, j) => {
        if (cell === 0) {
          emptyCells.push([i, j])
        }
      })
    })

    if (emptyCells.length > 0) {
      let n = Math.floor(Math.random() * emptyCells.length) // Randomly select an empty cell
      const i = emptyCells[n][0]
      const j = emptyCells[n][1]
      this.grid[i][j] = Math.random() < 0.9 ? 2 : 4 // 90% probability of generating 2, 10% probability of generating 4
    }
  }

  // Process movement logic
  move(direction: 'left' | 'right' | 'up' | 'down') {
    let newGrid = this.grid.map(row => [...row]) // Create a grid copy
    let moved = false // Movement flag

    // Matrix rotation helper methods
    const rotate = (matrix: number[][]): number[][] => {
      return matrix[0].map((_, i) => matrix.map(row => row[i]).reverse())
    }
    const rotateReverse = (matrix: number[][]): number[][] => {
      return matrix[0].map((_, i) => matrix.map(row => row[row.length - 1 - i]))
    }

    // Process single-row movement and merging
    const moveRow = (row: number[]): number[] => {
      let newRow = row.filter(cell => cell !== 0) // Remove spaces
      for (let i = 0; i < newRow.length - 1; i++) {
        if (newRow[i] === newRow[i + 1]) { // Merge identical numbers
          newRow[i] *= 2
          this.score += newRow[i] // Update the score
          newRow.splice(i + 1, 1) // Remove the merged element
        }
      }

      // Complete the length
      while (newRow.length < 4) {
        newRow.push(0)
      }
      return newRow
    }

    // Process movement according to direction
    switch (direction) {
      case 'left':
        newGrid.forEach((row, i) => newGrid[i] = moveRow(row))
        break
      case 'right':
        newGrid.forEach((row, i) => newGrid[i] = moveRow(row.reverse()).reverse())
        break
      case 'up':
        let rotatedDown = rotate(newGrid)
        rotatedDown.forEach((row, i) => rotatedDown[i] = moveRow(row.reverse()).reverse())
        newGrid = rotateReverse(rotatedDown)
        break
      case 'down':
        let rotatedUp = rotate(newGrid)
        rotatedUp.forEach((row, i) => rotatedUp[i] = moveRow(row))
        newGrid = rotateReverse(rotatedUp)
        break
    }

    moved = JSON.stringify(newGrid) !== JSON.stringify(this.grid) // Judge whether movement has occurred
    this.grid = newGrid

    if (moved) {
      this.addNewTile() // Add a new block after movement
      if (this.score > this.bestScore) { // Update the highest score
        this.bestScore = this.score
        PreferencesUtil.putSync('bestScore', this.bestScore) // Save the highest score
      }
    }

    if (this.isGameOver()) { // Game end detection
      ToastUtil.showToast('Game Over!')
    }
  }

  // Game end judgment
  isGameOver(): boolean {
    // Check for empty cells
    if (this.grid.some(row => row.includes(0))) {
      return false
    }

    // Check for horizontal merges
    for (let i = 0; i < 4; i++) {
      for (let j = 0; j < 3; j++) {
        if (this.grid[i][j] === this.grid[i][j + 1]) {
          return false
        }
      }
    }

    // Check for vertical merges
    for (let j = 0; j < 4; j++) {
      for (let i = 0; i < 3; i++) {
        if (this.grid[i][j] === this.grid[i + 1][j]) {
          return false
        }
      }
    }

    return true
  }

  build() {
    Column() {
      // Score display row
      Row() {
        Text(`Score: ${this.score}`)
          .fontSize(20)
          .margin(10)
        Text(`Highest Score: ${this.bestScore}`)
          .fontSize(20)
          .margin(10)
        Button('New Game')
          .onClick(() => this.initGame())
          .margin(10)
      }.margin({ top: px2vp(AppUtil.getStatusBarHeight()) })

      // Game grid
      Grid() {
        ForEach(this.grid, (row: number[], i) => {
          ForEach(row, (value: number, j) => {
            GridItem() {
              Text(value ? `${value}` : '')
                .textAlign(TextAlign.Center)
                .fontSize(24)
                .fontColor(this.getTextColor(value))
                .width('100%')
                .height('100%')
                .backgroundColor(this.getTileColor(value))
                .animation({
                  duration: 150,
                  curve: Curve.EaseOut
                })
            }.key(`${i}-${j}`)
          })
        })
      }
      .columnsTemplate('1fr 1fr 1fr 1fr')    // 4 equal columns
      .rowsTemplate('1fr 1fr 1fr 1fr')       // 4 equal rows
      .width('90%')
      .aspectRatio(1)                        // Maintain square shape
      .margin(10)
      .onTouch((event) => {                  // Touch event handling
        if (event.type === TouchType.Down) {
          this.startX = event.touches[0].x
          this.startY = event.touches[0].y
        } else if (event.type === TouchType.Up) {
          const deltaX = event.touches[0].x - this.startX
          const deltaY = event.touches[0].y - this.startY

          // Judge the movement according to the sliding direction
          if (Math.abs(deltaX) > Math.abs(deltaY)) {
            deltaX > 0 ? this.move('right') : this.move('left')
          } else {
            deltaY > 0 ? this.move('down') : this.move('up')
          }
        }
      })
    }
    .width('100%')
  }

  // Get the block background color
  getTileColor(value: number): string {
    const colors = new HashMap<number, string>()
    colors.set(0, '#CDC1B4')
    colors.set(2, '#EEE4DA')
    colors.set(4, '#EDE0C8')
    colors.set(8, '#F2B179')
    colors.set(16, '#F59563')
    colors.set(32, '#F67C5F')
    colors.set(64, '#F65E3B')
    colors.set(128, '#EDCF72')
    colors.set(256, '#EDCF72')
    colors.set(512, '#EDCC61')
    colors.set(1024, '#EDC850')
    colors.set(2048, '#EDC22E')
    return colors.get(value) || '#CDC1B4'
  }

  // Get the text color
  getTextColor(value: number): Color {
    return value > 4 ? Color.White : Color.Black
  }
}

Modifying the Color of the Image Component in HarmonyOS Next

CodeCao — Thu, 12 Jun 2025 10:38:43 +0000

In HarmonyOS development, the need to modify image colors often arises in scenarios such as theme switching, status indication, or style unification. The following comprehensively covers technical principles, implementation methods, and optimization strategies across various scenarios including vector graphics, bitmaps, and dynamic rendering:

I. Modifying Vector Graphic Colors: Flexible Adaptation via `fillColor`

1. Core Principles and Use Cases

Vector graphics (e.g., SVG, AI) describe shapes through mathematical paths, allowing direct modification of fill colors using the fillColor property. Advantages include:

Lightweight Rendering: No additional resource files required; color changes via property configuration
Dynamic Responsiveness: Real-time color switching based on runtime states (e.g., theme mode, interaction state)
Consistency Maintenance: Single vector graphic adaptable to multiple color schemes, reducing resource redundancy

2. Advanced Usage and Code Examples

// Basic usage: Dynamically switch icon color based on system theme
Image({
  source: $r('app.media.icon_search'), // Reference SVG resource
  fillColor: App.abilityContext?.colorMode === 1 ? '#FFFFFF' : '#000000'
})
.width(24)
.height(24)

// Interaction state color change: Icon color switches on button press
@Entry
@Component
struct IconColorDemo {
  @State isPressed: boolean = false

  build() {
    Button('Click to Switch Color') {
      Image({
        source: $r('app.media.icon_star'),
        fillColor: this.isPressed ? '#FF5500' : '#999999'
      })
      .width(20)
      .height(20)
    }
    .onClick(() => {
      this.isPressed = !this.isPressed
    })
  }
}

// Multi-color gradient fill (supported by some vector formats)
Image({
  source: $r('app.media.icon_compass'),
  fillColor: 'linear-gradient(to right, #3A7BD5, #6B46C1)'
})
.width(32)
.height(32)

3. Notes

Resource Format Limitation: Only vector graphics support the fillColor property; bitmaps (PNG/JPG) require alternative methods
Transparency Compatibility: If vector graphics contain transparent channels (e.g., opacity in .svg), fillColor will blend with transparency

II. Modifying Bitmap Colors: Multi-Resource Adaptation and Dynamic Rendering

1. Static Resource Adaptation

Distinguish theme-specific resources via directory structure; the system auto-loads appropriate files:

// Resource directory structure
src/main/resources/
├── base/              # Default resources for light mode
│   ├── image_normal.png
│   └── icon_default.svg
└── dark/              # Exclusive resources for dark mode
    ├── image_normal.png  # Dark theme bitmap
    └── icon_default.svg  # Dark theme vector graphic

2. Dynamic Color Filtering (ColorFilter)

For real-time color adjustments (e.g., grayscale, inversion), use ColorFilter:

// Grayscale processing (suitable for disabled state icons)
Image($r('app.media.image_original'))
  .width(100)
  .height(100)
  .colorFilter({
    type: ColorFilterType.Matrix,
    matrix: [
      0.2126, 0.7152, 0.0722, 0, 0,  // R channel grayscale weight
      0.2126, 0.7152, 0.0722, 0, 0,  // G channel grayscale weight
      0.2126, 0.7152, 0.0722, 0, 0,  // B channel grayscale weight
      0, 0, 0, 1, 0                  // Alpha channel preserved
    ]
  })

// Theme color filtering (map image primary color to app theme)
Image($r('app.media.image_original'))
  .width(120)
  .height(120)
  .colorFilter({
    type: ColorFilterType.Lighting,
    lighting: {
      mul: '#FF0000',  // Color blend value (red)
      add: '#000000'   // Color overlay value (black)
    }
  })

3. Runtime Resource Replacement

Dynamically load and modify bitmap colors via ImageSource (complex programmatic scenarios):

import image from '@ohos.multimedia.image'

async function modifyImageColor() {
  // 1. Load original image
  const imageSource = await image.createImageSource(
    await fetch($r('app.media.image_original')).arrayBuffer()
  )
  const imageInfo = await imageSource.getImageInfo()

  // 2. Create color matrix (enhance red channel by 50%)
  const colorMatrix = new Float32Array([
    1.5, 0, 0, 0, 0,    // R channel
    0, 1, 0, 0, 0,      // G channel
    0, 0, 1, 0, 0,      // B channel
    0, 0, 0, 1, 0       // Alpha channel
  ])

  // 3. Apply color filter and generate new image
  const options = {
    colorFilter: {
      type: image.ColorFilterType.MATRIX,
      matrix: colorMatrix
    }
  }
  const newImage = await imageSource.createImage(options)

  // 4. Display modified image in UI
  this.modifiedImage = newImage
}

III. Hybrid Approach: Synergistic Optimization of Vector and Bitmap Graphics

1. Automatic Format Detection and Adaptation

// Automatically select color modification method based on image format
@Builder
ImageWithColorAdaptation(source: ResourceStr, color: string) {
  // Detect resource extension (simplified logic; actual implementation requires resource manager)
  const isVector = source.endsWith('.svg') || source.endsWith('.ai')

  if (isVector) {
    // Use fillColor for vector graphics
    Image({ source: source, fillColor: color })
  } else {
    // Use color filtering for bitmaps
    Image(source)
      .colorFilter({
        type: ColorFilterType.Lighting,
        lighting: { mul: color, add: '#000000' }
      })
  }
}

2. Performance Optimization Strategies

Prioritize Vector Graphics: Use SVG for complex icons to reduce resource size and memory usage
Caching Mechanism: Cache processed PixelMap objects for frequently used color-filtered images
Lazy Loading: Defer color modification operations for non-visible images

IV. Common Issues and Solutions

Problem Scenario	Solution
`fillColor` ineffective for vector graphics	Ensure resource is a pure path graphic (SVG with embedded bitmaps not supported)
Blurred bitmap after color filtering	Adjust `colorMatrix` parameters or use `ColorFilterType.LUT` for lookup table optimization
Chaotic multi-theme resource management	Use `$r` resource references with conditional compilation (e.g., `#ifdef DARK_MODE`)

These approaches enable developers to achieve full-scenario color control in HarmonyOS, from simple theme switching to complex image effects, while balancing performance optimization and development efficiency.

The Core Component System of HarmonyOS and Its Characteristics

CodeCao — Thu, 12 Jun 2025 10:37:12 +0000

I. Core Features of ArkUI Framework

Declarative Syntax ○ Replaces imperative code with natural and intuitive UI description syntax, allowing developers to focus on UI presentation logic rather than interface updates.
Cross-Platform Collaboration and Efficient Rendering ○ Supports one-time development for multi-terminal deployment (e.g., phones, tablets, vehicle systems). Fine-grained UI update binding via compile-time optimization enhances layout rendering performance.
Multi-Dimensional State Management ○ Provides a flexible state management mechanism, supporting state sharing and responsive updates between components.

II. Classification and Typical Examples of ArkUI Components

Basic Interactive Components ● Button Triggers operations, supporting custom text, types (normal/capsule), click effects, and event binding (e.g., form submission, link navigation). ● TextInput Receives user text input, supporting placeholders, input types (password/email), and input content validation. ● Slider Slider component, allowing configuration of minimum/maximum values, step sizes, and sliding callbacks.
Layout Container Components ● Linear Layout ○ Row: Horizontally arranges child components, sets spacing via space, and controls alignment with alignItems. ○ Column: Vertically arranges child components, supporting scrolling for超长 content (adaptive extension). ● Flex Layout Child components can be compressed/stretched to dynamically adapt to container space, suitable for complex adaptive interfaces. ● Grid Layout (GridRow/GridCol) Defines row and column ratios via rowsTemplate and columnsTemplate, supporting cell layouts that span rows and columns. ● Stack Layout (Stack) Child components are stacked in sequence, often used for pop-ups, floating buttons, and other overlay effects.
Data Display Components ● List High-performance list container supporting vertical/horizontal scrolling, displaying structured data via ListItem or grouping (ListItemGroup). ● Grid Grid layout suitable for interfaces requiring uniform space allocation, such as calculators and photo albums. ● Swiper Carousel component supporting loop playback of advertisements or image preview scenarios.
Media and Graphics Components ● Image Supports various image sources (local, network, Base64), configurable scaling modes (objectFit), rounded corners, and loading events (onComplete/onError). ● Video Video playback component integrating decoding and playback control functions. ● Canvas Provides 2D drawing capabilities, supporting custom graphics, text, and animations.
Auxiliary Function Components ● Popup Pop-up component supporting custom content (e.g., confirmation boxes, menus) with configurable animation effects. ● Divider Divider component for distinguishing content blocks. ● Badge Badge component supporting top-right/left/right markers for unread messages or status indicators.

III. Advanced Layout Capabilities of ArkUI

Relative Layout (RelativeContainer) Flexibly controls the relative positions of child components via anchor rules (AlignRules), avoiding excessive nesting.
Media Query (@ohos.mediaquery) Dynamically adjusts layouts based on device attributes (screen size, orientation) to achieve responsive design.
Adaptive Scaling and Extension ○ Uses percentage or fr units to proportionally adjust component sizes. ○ Handles content overflow in conjunction with scroll containers (e.g., Scroll).

IV. New Capabilities and Cross-Platform Support

Enhanced One-Many Components ○ Column components support multi-terminal adaptation, and lists gain sticky top/bottom capabilities.
ArkUI-X Extension Reuses code across platforms like Android/iOS, maintaining UI consistency and reducing multi-terminal development costs.

Summary

ArkUI covers full-scenario requirements from basic interactions to complex data display through its rich component library and flexible layout system. Developers can efficiently build high-performance, cross-device HarmonyOS applications by combining declarative syntax with state management.

Implementing Department Tree List in HarmonyOS Next

CodeCao — Thu, 12 Jun 2025 10:34:58 +0000

When developing an ERP system, department tree lists are often used. The page mainly consists of a search box, a top-level department breadcrumb, and a multi-level department list. Each department list item is composed of a department name and a right-pointing arrow indicating the next level. Clicking on the department name area can pass department data back to the previous page, while clicking on the next-level arrow button can display the next-level department list and add the parent department to the top breadcrumb.

Load Department Tree Data

The department tree data consists of multiple department information objects. Each department object contains an array of subordinate departments, which may nest multiple child department objects. The JSON data used here is as follows:

[
  {
    "DepartCode": 0,
    "DepartNo": "",
    "FirstName": "",
    "DepartName": "所有部门",
    "SystemTag": 0,
    "DepartType": 0,
    "DepartStatus": 0,
    "DepartLevel": 0,
    "DepartStatusName": "",
    "DepartmentListZtree": [
      {
        "DepartCode": 50001,
        "DepartNo": "002",
        "FirstName": "测试大区",
        "DepartName": "测试大区",
        "SystemTag": 1,
        "DepartType": 1,
        "DepartStatus": 1,
        "DepartLevel": 1,
        "DepartStatusName": "",
        "DepartmentListZtree": []
      }
    ]
  }
]

Customize the Top Input Box

The top input box is composed of a TextInput input box component and an Image component wrapped in a Stack component.

/**
 * Build the search box
 */
@Builder
BuildSearch() {
  Stack() {
    TextInput({ text: this.depWord, placeholder: "搜索部门" })
      .height(36)
      .placeholderFont({ size: 14 })
      .placeholderColor($r("app.color.text_auxiliary"))
      .backgroundColor($r("app.color.tag_default"))
      .borderRadius(4)
      .padding({ left: 36 })
      .onChange((value) => {
        this.depWord = value
      })
    Image($r("app.media.icon_search")).width(14).height(14).margin({ left: 12 })
  }.align(Alignment.Start)
}

Customize the Department Breadcrumb

The department breadcrumb consists of a Row component wrapped in a Scroll component. When multiple levels are selected and exceed one screen, it can be scrolled horizontally. The Row component contains Text components for department names and Image components for right-pointing arrows. Clicking on a department name will display all sub-department data of the currently clicked department in the department list. The specific code is as follows:

/**
 * Build the top department breadcrumb
 */
@Builder
BuildTopDep() {
  Scroll(this.topScroller) {
    Row() {
      ForEach(this.topDeps, (item: DepartBean, index) => {
        Text(item.DepartName).fontSize(14).fontColor($r("app.color.main_color"))
          .onClick(() => {
            this.topDeps.splice(index + 1, this.topDeps.length - index - 1)
            this.listDeps = item.DepartmentListZtree ?? []
          })
        if (index < this.topDeps.length - 1) {
          Image($r("app.media.icon_back"))
            .width(12).height(12).margin({ left: 4, right: 4 })
            .rotate({ angle: 180 })
        }
      })
    }
  }.scrollable(ScrollDirection.Horizontal) // Horizontal scrolling
  .scrollBar(BarState.Off)
  .margin({ top: 12 })
}

Draw the Department List

Each item in the department list consists of a department name and a next-level button. Clicking on the department name area will pass the current department back to the previous page, while clicking on the next-level button will display the next-level department list data. The code is as follows:

// Build the department list
@Builder
BuildListDep() {
  List({ space: 1, scroller: this.listScroller }) {
    ForEach(this.listDeps, (item: DepartBean, index) => {
      ListItem() {
        Row() {
          Text(item.DepartName).fontSize(14).fontColor($r("app.color.text_two")).layoutWeight(1)
          // If there are sub-departments, display a right-pointing arrow
          if (item.DepartmentListZtree?.length ?? 0 > 0) {
            Image($r("app.media.icon_back"))
              .width(12).height(12).margin({ left: 4, right: 4 })
              .rotate({ angle: 180 })
              .margin({ right: 12 })
              .onClick(() => {
                // Click to jump to the next-level department
                this.topDeps.push(item)
                this.listDeps = item.DepartmentListZtree ?? []
                this.topScroller.scrollPage({ next: true }) // Scroll the breadcrumb to the far right
              })
          }
        }
        .margin({ left: 12 })
      }
      .backgroundColor(Color.White)
      .height(50)
      .width("100%")
      .align(Alignment.Start)
      .onClick(() => {
        // Click to return the selected department information to the previous page
        router.back({
          url: "",
          params: {
            depBean: item
          }
        })
      })
    })
  }.layoutWeight(1)
  .scrollBar(BarState.Off)
  .margin({ top: 8 })
}

Pass Department Data Back to the Previous Page

After clicking on a department name, call the router.back method to return to the previous page and pass the department data back to the previous page through the params. Note that the url is a required parameter; when returning to the previous page, you can directly pass an empty string.

// Click to return the selected department information to the previous page
router.back({
  url: "",
  params: {
    depBean: item
  }
})

Receive Data Passed Back from the Page

Receive the passed-back data in the onPageShow method of the page lifecycle. You can obtain the passed-back parameters through router.getParams(), and the department object data through params['depBean'], where depBean corresponds to the key of the passed-back parameter.

onPageShow(): void {
  let params = router.getParams() as Record<string, DepartBean>
  if (params) {
    this.depBean = params['depBean']
  }
}

The complete code is as follows:

import { AppUtil, JSONUtil, LogUtil, ToastUtil } from '@pura/harmony-utils'
import { TAB_ARRAY } from '../constant/HomeConstant'
import { Tab } from '../model/HomeModel'
import { createWaterMarkView } from '../view/WaterMarkView'
import { CustomerPage } from './customer/CustomerPage'
import { HomePage } from './home/HomePage'
import { HousePage } from './house/HousePage'
import { MessagePage } from './message/MessagePage'
import { MinePage } from './mine/MinePage'
import { DepartBean } from '../model/DepartBean'
import { router } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  @State currentIndex: number = 0
  @State depBean: DepartBean = new DepartBean()

  onPageShow(): void {
    let params = router.getParams() as Record<string, DepartBean>
    if (params) {
      this.depBean = params['depBean']
    }
  }

  build() {
    Tabs({ barPosition: BarPosition.End }) {
      ForEach(TAB_ARRAY, (item: Tab, index) => {
        TabContent() {
          if (index == 0) {
            HomePage({ depBean: this.depBean })
          } else if (index == 1) {
            HousePage()
          } else if (index == 2) {
            CustomerPage()
          } else if (index == 3) {
            MessagePage()
          } else {
            MinePage()
          }
        }.align(Alignment.Top)
        .tabBar(this.tabBuilder(item.tabText, index, item.tabSelectIcon, item.tabNormalIcon))
      })
    }
    .overlay(createWaterMarkView())
    .scrollable(false)
    .animationDuration(0)
    .backgroundColor($r("app.color.white"))
    .padding({ bottom: px2vp(AppUtil.getNavigationIndicatorHeight()) })
    .onChange((index) => {
      this.currentIndex = index
    })
  }

  @Builder
  tabBuilder(title: string, targetIndex: number, selectedImg: Resource, normalImg: Resource) {
    Column() {
      Image(this.currentIndex === targetIndex ? selectedImg : normalImg)
        .size({ width: 24, height: 24 })
      Text(title)
        .fontColor(this.currentIndex == targetIndex ? $r("app.color.main_color") : $r("app.color.text_auxiliary"))
        .fontSize(10)
        .padding(2)
    }
    .width('100%')
    .padding({ top: 8, bottom: 8 })
    .backgroundColor($r("app.color.white"))
    .borderWidth({ top: 0.5 })
    .borderColor($r("app.color.border_color"))
    .justifyContent(FlexAlign.Center)
  }
}

Implementing the Map-based House Search Effect in HarmonyOS Next

CodeCao — Thu, 12 Jun 2025 10:32:53 +0000

The commonly used map-based house search function involves adding custom markers for regions, business districts, properties, etc., on the map, combined with the filtering logic of the application. Here is a simple implementation of adding region/business district and property markers using HarmonyOS ArkUI.

1. Enable Map Service

Register the application on the Huawei Developer Website, then enable the Map Kit service in My Projects > My Apps > API Management.

2. Map-Related Configuration

Configure the client_id in the module.json5 file of the entry module. The client_id can be found in Project Settings > General > App. You may need to configure the public key fingerprint; refer to the developer website for details.

"module": {
  "name": "xxxx",
  "type": "entry",
  "description": "xxxx",
  "mainElement": "xxxx",
  "deviceTypes": [
    "phone",
    "tablet"
  ],
  "pages": "xxxx",
  "abilities": [],
  "metadata": [
    {
      "name": "client_id",
      "value": "xxxxxx"  // Configure with the obtained Client ID
    }
  ]
}

3. Create a Map

Use the MapComponent to create a map, which requires two parameters: mapOptions and mapCallback. Override the lifecycle methods onPageShow and onPageHide to display and hide the map. If the map does not display, refer to the official website for troubleshooting.

MapComponent(mapOptions: mapCommon.MapOptions, mapCallback: AsyncCallback<map.MapComponentController>)

// Map initialization parameters: set the map center coordinates and zoom level
this.mapOptions = {
  position: {
    target: {
      latitude: 39.9,
      longitude: 116.4
    },
    zoom: 10
  }
};

// Map initialization callback
this.callback = async (err, mapController) => {
  if (!err) {
    // Get the map controller to operate the map
    this.mapController = mapController;
    this.mapEventManager = this.mapController.getEventManager();
    const callback = () => {
      console.info(this.TAG, `on-mapLoad`);
    }
    this.mapEventManager.on("mapLoad", callback);
  }
};

// Triggered each time the page is displayed (including routing and app foreground scenarios), only valid for @Entry-decorated custom components
onPageShow(): void {
  // Bring the map to the foreground
  if (this.mapController) {
    this.mapController.show();
  }
}

// Triggered each time the page is hidden (including routing and app background scenarios), only valid for @Entry-decorated custom components
onPageHide(): void {
  // Send the map to the background
  if (this.mapController) {
    this.mapController.hide();
  }
}

build() {
  Stack() {
    // Initialize the map by calling MapComponent
    MapComponent({ mapOptions: this.mapOptions, mapCallback: this.callback }).width('100%').height('100%');
  }.height('100%')
}

4. Display My Location Icon on the Map

First, dynamically request location permissions. After obtaining the specific location coordinates, use the map operation class mapController to call setMyLocation to set the location coordinates and animateCamera to move the map to the location (with a configurable zoom level) to display a location icon.

static LocationPermissions: Array<Permissions> =
  ['ohos.permission.LOCATION', 'ohos.permission.APPROXIMATELY_LOCATION'];

// Start location positioning
startLocation() {
  // Request location permissions
  AgentUtil.requestPermissions(AgentUtil.LocationPermissions, async () => {
    // Location permission granted
    // Enable the my-location layer (mapController is obtained as described in the "Display Map" section)
    this.mapController?.setMyLocationEnabled(true);
    // Enable the my-location button
    this.mapController?.setMyLocationControlsEnabled(true);

    // Get the user's location coordinates
    const location = await geoLocationManager.getCurrentLocation();
    // Convert coordinate system (if needed)
    // const wgs84LatLng = AgentUtil.wgs84LatLng(location.latitude, location.longitude);
    // location.latitude = wgs84LatLng.latitude;
    // location.longitude = wgs84LatLng.longitude;
    // Set the user's location
    this.mapController?.setMyLocation(location);

    setTimeout(() => {
      // Move the map to the target location
      this.mapController?.animateCamera(map.newLatLng(location, 15));
    }, 100);
  });
}

5. Listen for Map Movement Stop

After the map moves to the location coordinates, use mapController.on("cameraIdle", () => {}) to listen for when the map stops moving. In the callback, implement the logic to display markers based on the map zoom level (e.g., display regions/districts at lower zooms and properties at higher zooms), and further refine business logic such as business district layers.

this.mapEventManager.on("cameraIdle", () => {
  // The map has stopped moving; perform operations
  const position = this.mapController?.getCameraPosition();
  const currentZoom = position?.zoom ?? 0;
  if (currentZoom < 14) {
    // Display region/business district markers
    this.addAreaMarkers();
  } else {
    // Display property markers
    this.addHouseMarkers();
  }
});

6. Customize Markers

Custom Circular Marker

Used to display regions and business districts. Since Map Kit does not support custom styles for markers, only icon settings, use a @Builder custom component to draw a circular marker:

@Builder
BuilderMapCircularLabel(text: string, id: string) {
  Stack() {
    // Draw a circular background
    Circle({ width: 70, height: 70 })
      .shadow({ radius: 8 })
      .fill($r("app.color.main_color"));
    Text(text)
      .fontSize(12)
      .fontColor($r("app.color.white"))
      .textAlign(TextAlign.Center)
      .padding({ left: 4, right: 4 });
  }.id(id);
}

Custom Property Display Marker

Draw a small triangle at the bottom using a Path path.

/**
 * Rectangular marker with a small triangle indicator
 * @param text
 */
@Builder
BuilderMapRectLabel(text: string, id: string) {
  Column() {
    Text(text)
      .fontSize(14)
      .fontColor($r("app.color.white"))
      .backgroundColor($r("app.color.main_color"))
      .shadow({ radius: 5, color: $r("app.color.white") })
      .borderRadius(14)
      .padding({ left: 15, right: 15, top: 4, bottom: 4 });
    // Draw a small triangle using path commands
    Path()
      .width(12)
      .height(6)
      .commands('M0 0 L30 0 L15 15 Z')
      .fill($r("app.color.main_color"))
      .strokeWidth(0);
  }.id(id).alignItems(HorizontalAlign.Center);
}

7. Display Custom Markers on the Map

Use the screenshot class componentSnapshot to generate a snapshot of the custom component via createFromBuilder. In the callback, obtain the PixelMap object, set it as the icon in MarkerOptions, and call addMarker to generate the marker on the map.

componentSnapshot.createFromBuilder(() => {
  // The custom component to generate a PixelMap image
  this.BuilderMapRectLabel(text, houseId);
}, async (error, imagePixelMap) => {
  if (error) {
    LogUtil.debug("snapshot failure: " + JSON.stringify(error));
    return;
  }

  const markerOptions: mapCommon.MarkerOptions = {
    position: latLng,
    icon: imagePixelMap, // Custom component converted to PixelMap
    title: houseId,       // Pass custom parameters to bind with the component for click operations
  };
  if (!this.rectMarkers.find(marker => marker.getTitle() === houseId)) {
    // Add the marker if it doesn't exist in the marker collection
    const marker = await this.mapController?.addMarker(markerOptions);
    marker?.setClickable(true);
    if (marker) {
      this.rectMarkers.push(marker);
    }
  }
});

8. Listen for Marker Click Events

Use mapEventManager.on("markerClick", () => {}) to listen for marker clicks. In the callback, handle business logic based on the map level (e.g., navigate to the property layer when a region/business district marker is clicked).

this.mapEventManager.on("markerClick", (marker) => {
  if (marker.getTitle().length === 2) {
    // Clicked a region/business district marker: switch to the property layer and display property information
    this.mapController?.animateCamera(map.newLatLng({
      latitude: 30.513746,
      longitude: 114.403009
    }, 15));
  } else {
    // Clicked a property marker: perform subsequent operations
    ToastUtil.showToast(marker?.getTitle());
  }
});

Summary

The above is the basic process for implementing map-based house search with HarmonyOS ArkUI. Details can be customized according to business needs. Currently, custom markers are displayed by generating images from custom components, which may affect performance with a large number of markers. Optimization can be done by displaying only markers within the current screen, removing those outside the screen when scrolling, and reusing generated PixelMap objects to avoid repeated creation.

Custom Scroll Sliding Indicator for HarmonyOS Next

CodeCao — Wed, 11 Jun 2025 08:54:44 +0000

Recently, there was a requirement in the project regarding the effect of the bottom indicator of the sliding component Scroll following the gesture sliding and displaying proportionally. The following image shows the effect to be implemented.

Custom Indicator Component

Actually, this is not a progress bar, so we need to customize and draw this component. In HarmonyOS, we can use the Canvas component to draw specified graphics on the page. There are 7 drawing types, namely Circle, Ellipse, Line, Polyline, Polygon, Path, and Rect. Here, we use Rect to draw a rectangle, with a black Rect as the background of the indicator and blue as the progress of the indicator. Then, dynamically set the left margin of the progress.

@Entry
@Component
export struct RectIndicator {
  @Prop marginLeft: number = 0 // The left margin of the indicator from the progress, default is 0
  indicatorHeight: number = 20 // The height of the indicator
  indicatorWidth: number = 200 // The background width of the indicator
  indicatorProgressWidth: number = 160 // The progress width of the indicator

  build() {
    Stack() {
      // Draw the rectangular background
      Rect({ width: this.indicatorWidth, height: this.indicatorHeight })
        .radius(this.indicatorHeight / 2)
        .fill($r('app.color.bg_gray'))
        .stroke(Color.Transparent)

      // Draw the rectangular progress
      Rect({ width: this.indicatorProgressWidth, height: this.indicatorHeight })
        .radius(this.indicatorHeight / 2)
        .fill($r('app.color.main_color'))
        .margin({ left: this.marginLeft })
        .stroke(Color.Transparent)
    }.alignContent(Alignment.Start)
  }
}

Adding Scroll Listener

Create a new RectIndicator class. Since two rectangles need to be stacked together, use the Stack layout for nesting. When calling this custom component, you can set the width (indicatorWidth), height (indicatorHeight), progress width (indicatorProgressWidth) of the component, and dynamically set the left margin (marginLeft) of the progress. You can dynamically set marginLeft by listening to the scroll event of Scroll.

Scroll(this.scroll) {
  Row() {
    ForEach(SUB_MENUS, (item: Menu, index) => {
      Column() {
        Image(item.menuIcon).width(28).height(28)
        Text(item.menuText).fontSize(12).fontColor($r("app.color.text_two")).margin({ top: 5 })
      }.width("20%").id("item")
    })
  }
}.scrollable(ScrollDirection.Horizontal)
.margin({ top: 12 })
.scrollBar(BarState.Off)
// Scroll listener
.onDidScroll((_xOffset, _yOffset, scrollState) => {
  // The current state is the scrolling state
  if (scrollState == ScrollState.Scroll) {
    // Get the scrolling offset. It's more accurate to get it through the controller
    const currentOffsetX = this.scroll.currentOffset().xOffset
    LogUtil.debug("Scrolling offset", vp2px(currentOffsetX).toString())
    // Subcomponent width * 2 = the component not displayed / the gray part of the indicator
    let ratio = this.itemWidth * 2 / 10
    // The offset of the indicator progress = scroll offset / ratio
    this.indicatorLeft = vp2px(currentOffsetX) / ratio
  }
})

The onDidScroll can set a listener for sliding components (including but not limited to Scroll). Here, we judge that the scrollState is the sliding state, get the current sliding offset currentOffsetX, and calculate the left margin (indicatorLeft) of the indicator through the offset of Scroll.

Using the Custom RectIndicator Component

RectIndicator({
  marginLeft: this.indicatorLeft, // Left margin
  indicatorHeight: 4,  // The height of the indicator
  indicatorWidth: 30,  // The background width of the indicator
  indicatorProgressWidth: 20  // The progress width of the indicator
}).margin({ top: 8, bottom: 8 })

Usage method: Call the RectIndicator custom component and pass relevant parameters such as height and width into the component. The progress width here can be calculated through the length of the Scroll component. Here, I just set a width, which does not affect the use.

It should be noted that indicatorLeft needs to add a @State annotation to ensure that the component can refresh the UI in real-time according to indicatorLeft.

HarmonyOS Next Customize TabBar components

CodeCao — Mon, 26 May 2025 06:25:13 +0000

Tabs in ArkUI are container components that facilitate content view switching through tabs. Each tab corresponds to a specific content view. The content is presented using the TabContent component, which is a child component of Tabs. You can customize the style of the navigation bar by setting the tabBar property on TabContent. Now, let's implement the effect shown in the following UI design based on the reference image:

Analysis and Implementation Steps

Based on the analysis of the above image, achieving the desired effect requires the following steps:

Set the background color of the tabBar and the selected tab style.
Customize the navigation bar indicator.
Configure the indicator to slide smoothly with the content view during transitions.

Setting TabBar Background Color and Selected Tab Style

First, use the @Builder decorator to define a custom component.
Set the background image and color based on the currently selected tab index. Note that the top-left and top-right corners should have rounded edges, which need to be determined based on the tab's position.
Since the selected tab style is a trapezoid with rounded corners, we use three different trapezoid images for this effect.

@Builder
tabBuilder(title: string, targetIndex: number, selectImage: ResourceStr) {
  // Create a Column layout
  Column() {
    // Create a Text component to display the title
    Text(title)
      // Set font color based on whether the tab is selected
      .fontColor(this.currentIndex === targetIndex ? $r("app.color.text_one") : $r("app.color.text_two"))
      // Set font size to 14
      .fontSize(14)
      // Set font weight based on selection state
      .fontWeight(this.currentIndex === targetIndex ? 600 : 400)
  }
  // Set Column width to 100%
  .width('100%')
  // Set Column height to 100%
  .height("100%")
  // Vertically center the child component
  .justifyContent(FlexAlign.Center)
  // Set background image if the tab is selected
  .backgroundImage(this.currentIndex == targetIndex ? selectImage : null)
  // Set background color
  .backgroundColor($r("app.color.bg_data_color"))
  // Set rounded corners for top-left and top-right based on tab position
  .borderRadius({ topLeft: targetIndex == 0 ? 8 : 0, topRight: targetIndex == 2 ? 8 : 0 })
  // Set background image to fill the container
  .backgroundImageSize(ImageSize.FILL)
}

Customizing the Navigation Bar Indicator

Since the indicator needs to slide smoothly with the content view, it cannot be set within the individual tabBuilder. Instead:

Use a Column component to define the bottom indicator with a blue bar that matches the text width and has a height of 3.
The indicator width can be dynamically set to match the text width or a fixed value.
The left margin of the indicator should be dynamically adjusted with animation to achieve smooth sliding effects.

Stack() {
  Tabs({ barPosition: BarPosition.Start }) {
    TabContent() {
      this.tripPage()
    }.tabBar(this.tabBuilder("Property", 0, $r("app.media.trip_data_start_bg")))
    .align(Alignment.TopStart).margin({ top: 54 })

    // Additional TabContent components would follow...
    // ...
    // ...
  }
  .backgroundColor($r("app.color.white"))
  .borderRadius(8)
  .barHeight(44)
  .width("93.6%")
  .height(380)
  .onChange((index) => {
    this.currentIndex = index
  })

  // Custom indicator: a blue bar with dynamic width and position
  Column()
    .width(this.indicatorWidth)
    .height(3)
    .backgroundColor($r("app.color.main_color"))
    .margin({ left: this.indicatorLeftMargin, top: 42 })
    .borderRadius(1)
}

Adding Indicator Animation

To make the indicator slide smoothly with finger gestures during tab transitions, we need to add animations and listen for tab animation events and gesture interactions.

/**
 * Starts an animation to move the indicator to a specified position
 * 
 * @param duration Animation duration in milliseconds
 * @param leftMargin Left margin after animation completes
 * @param width Width after animation completes
 */
private startAnimateTo(duration: number, leftMargin: number, width: number) {
  // Set animation start flag
  this.isStartAnimateTo = true
  animateTo({
    // Animation duration
    duration: duration,
    // Animation curve
    curve: Curve.Linear,
    // Number of iterations
    iterations: 1,
    // Play mode
    playMode: PlayMode.Normal,
    // Callback when animation finishes
    onFinish: () => {
      // Reset animation flag
      this.isStartAnimateTo = false
      // Log animation completion
      console.info('Animation finished')
    }
  }, () => {
    // Update indicator position and width
    this.indicatorLeftMargin = leftMargin
    this.indicatorWidth = width
  })
}

1. Animation Start Listener

When the tab switching animation starts, set the target index as the current index and start the indicator animation to dynamically adjust its left margin.

Tabs({ barPosition: BarPosition.Start })
// ...
.onAnimationStart((index: number, targetIndex: number, event: TabsAnimationEvent) => {
  // Triggered when tab animation starts. Move indicator with the page transition.
  this.currentIndex = targetIndex
  this.startAnimateTo(this.animationDuration, this.textInfos[targetIndex][0], this.textInfos[targetIndex][1])
})

2. Animation End Listener

When the tab switching animation ends, the onAnimationEnd callback is triggered to finalize the indicator position.

Tabs({ barPosition: BarPosition.Start })
// ...
.onAnimationEnd((index: number, event: TabsAnimationEvent) => {
  // Triggered when tab animation ends. Stop the indicator animation.
  let currentIndicatorInfo = this.getCurrentIndicatorInfo(index, event)
  this.startAnimateTo(0, currentIndicatorInfo.left, currentIndicatorInfo.width)
})

3. Gesture Swipe Listener

This callback is triggered frame by frame during the page swipe gesture, allowing the indicator to follow the user's finger movement.

Tabs({ barPosition: BarPosition.Start })
// ...
.onGestureSwipe((index: number, event: TabsAnimationEvent) => {
  // Triggered frame by frame during page swipe.
  let currentIndicatorInfo = this.getCurrentIndicatorInfo(index, event)
  // Update current index
  this.currentIndex = currentIndicatorInfo.index
  // Update indicator left margin
  this.indicatorLeftMargin = currentIndicatorInfo.left
  // Update indicator width
  this.indicatorWidth = currentIndicatorInfo.width
})

Encapsulating Indicator Information Retrieval

We encapsulate the logic to calculate the indicator's position and width in a separate method. This method is called during gesture swipes to dynamically update the indicator's properties, ensuring it follows the user's gesture smoothly and achieves the desired UI effect.

/**
 * Calculates the current indicator information based on the swipe event
 * 
 * @param index Current tab index
 * @param event Tabs animation event containing swipe information
 * @returns Object containing indicator index, left margin, and width
 */
private getCurrentIndicatorInfo(index: number, event: TabsAnimationEvent): Record<string, number> {
  // Determine next tab index based on swipe direction
  let nextIndex = index

  // Swiping left (from user perspective)
  if (index > 0 && event.currentOffset > 0) {
    nextIndex--
  }
  // Swiping right (from user perspective)
  else if (index < 3 && event.currentOffset < 0) {
    nextIndex++
  }

  // Get information about current and next tabs
  let indexInfo = this.textInfos[index]
  let nextIndexInfo = this.textInfos[nextIndex]

  // Calculate swipe ratio
  let swipeRatio = Math.abs(event.currentOffset / this.tabsWidth)

  // Determine current index based on swipe progress
  // Switch to next tab's style when swiped more than halfway
  let currentIndex = swipeRatio > 0.5 ? nextIndex : index

  // Interpolate left margin and width based on swipe ratio
  let currentLeft = indexInfo[0] + (nextIndexInfo[0] - indexInfo[0]) * swipeRatio
  let currentWidth = indexInfo[1] + (nextIndexInfo[1] - indexInfo[1]) * swipeRatio

  // Return calculated properties
  return { 'index': currentIndex, 'left': currentLeft, 'width': currentWidth }
}

This implementation effectively creates a smooth and visually appealing tab navigation system that closely matches modern UI design standards.

Forem: CodeCao

Audio-to-Text Implementation with HarmonyOS AI - Core Speech Kit

I. Scenarios and Constraints

II. Development Preparation

1. Permission Configuration

2. Dependency Import

III. Core Development Steps

1. Initialize the Speech Recognition Engine

2. Configure Callback Listeners

3. Audio Input Processing

4. Start and Stop Recognition

5. Error Handling and Debugging

IV. Complete Example and Optimization Suggestions

V. Application Scenario Expansion

Technical Analysis and Development Practice of HarmonyOS AI - Core Speech Kit Offline Text-to-Speech Technology

I. Technical Background and Scenario Value

II. Core Function Implementation

1. Engine Initialization

2. Text Broadcasting Control

3. Broadcasting Strategy Configuration (Syntax Markup)

III. Development Practice Key Points

1. Lifecycle Management

2. Advanced Function Integration

IV. Constraints and Optimization Suggestions

V. Application Scenario Expansion

Conclusion

Implementing Vertical Carousel Notifications in HarmonyOS Next

1. Vertical Carousel Implementation

2. Implementing a Custom Dialog

The Usage of Pop-up Boxes in HarmonyOS

Overview and Classification of Pop-up Boxes in HarmonyOS Next

Custom Pop-up Boxes

Fixed-style Pop-up Boxes

Basic Custom Pop-up Box (CustomDialog)

1. @CustomDialog Decorator

2. CustomContentDialog

UI-component-independent Global Custom Pop-up Box (openCustomDialog)

openCustomDialog (with ComponentContent)

openCustomDialog (with builder)

1. Initialize Pop-up Configuration

2. Open the Custom Pop-up Box

3. Close the Custom Pop-up Box

4. Update the Custom Pop-up Content

5. Complete Code

Implementing the Wooden Fish Knocking Mini Game on HarmonyOS

I. Architecture Design & Project Setup

1.1 Project Structure

1.2 Component-based Development

II. Animation System Deep Dive

2.1 Composite Animation for Knocking

2.2 Floating Merit Text Animation

III. Multi-modal Interaction

3.1 Haptic Feedback

3.2 Audio Playback & Resource Management

IV. Auto-Tap Functionality

4.1 Timer-State Integration

4.2 Thread Safety & Performance

V. UI Layout & Rendering Optimization

5.1 Layered Layout & Animation Composition

5.2 Efficient State-to-UI Binding

VI. Complete Code

Implementing the 2048 Puzzle Game on HarmonyOS Next

I. Core Data Structures and State Management

1. Game Grid and Scores

2. Game Initialization

II. Sliding Logic and Merging Algorithm

1. Direction Handling and Matrix Rotation

2. Single-Row Merging Logic

III. Game End Judgment

IV. UI Implementation and Interaction Design

1. Grid Rendering

2. Touch Event Handling

V. Local Storage and Animation Effects

1. High Score Persistence

2. Animation and Visual Effects

VI. Summary and Complete Code

Modifying the Color of the Image Component in HarmonyOS Next

I. Modifying Vector Graphic Colors: Flexible Adaptation via fillColor

1. Core Principles and Use Cases

2. Advanced Usage and Code Examples

Basic Custom Pop-up Box (`CustomDialog`)

1. `@CustomDialog` Decorator

2. `CustomContentDialog`

I. Modifying Vector Graphic Colors: Flexible Adaptation via `fillColor`