DEV Community: HarmonyOS

Grid Item Drag and Move with Auto-Scroll Functionality

HarmonyOS — Fri, 04 Sep 2026 01:16:00 +0000

Read the original article：Grid Item Drag and Move with Auto-Scroll Functionality

Context

When implementing drag-and-drop functionality for grid items, developers may encounter limitations where items can only be exchanged within the visible range, and attempting to implement custom scrolling logic can cause display abnormalities.

Description

The issue involves two main scenarios when implementing grid item reordering:

Limited Exchange Range: Items can only be repositioned within the currently visible area of the grid
Manual Scroll Implementation Issues: Custom sliding logic implementation can lead to visual abnormalities and unstable behavior

These limitations prevent smooth user experience when trying to move items to positions outside the current viewport.

Solution

Use the onMove attribute which provides built-in support for both scrolling and component swapping animations. This approach eliminates the need for manual scroll implementation and handles edge cases automatically.

Example Code

@Entry
@Component
struct ForEachSort {
  @State arr: Array<string> = [];

  build() {
    Row() {
      List() {
        ForEach(this.arr, (item: string) => {
          ListItem() {
            Text(item.toString())
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .size({height: 100, width: "100%"})
          }
          .margin(10)
          .borderRadius(10)
          .backgroundColor("#FFFFFFFF")
        }, (item: string) => item)
        .onMove((from: number, to: number) => {
          let tmp = this.arr.splice(from, 1);
          this.arr.splice(to, 0, tmp[0]);
        })
      }
      .width('100%')
      .height('100%')
      .backgroundColor("#FFDCDCDC")
    }
  }

  aboutToAppear(): void {
    for (let i = 0; i < 30; i++) {
      this.arr.push(i.toString());
    }
  }
}

Key Features of onMove

Automatic Scrolling: Handles viewport scrolling when dragging items to edges
Built-in Animations: Provides smooth transition animations during item swapping
Edge Case Handling: Manages boundary conditions and prevents display abnormalities
Simple Implementation: Requires minimal code compared to custom scroll logic

Key Takeaways

Use the native onMove attribute instead of implementing custom drag-and-scroll logic
The onMove callback receives from and to parameters for easy array manipulation
Built-in scrolling and animations eliminate common edge case issues
This approach works reliably across different screen sizes and content lengths
Avoid manual scroll implementation as it can cause visual abnormalities and unstable behavior

Written by Emincan Ozcan

How to Solve TextInput Input Restriction Abnormality Issues

HarmonyOS — Fri, 04 Sep 2026 01:09:00 +0000

Read the original article：How to Solve TextInput Input Restriction Abnormality Issues

Context

In HarmonyOS, the $$ two-way binding symbol can synchronize state variables with the internal state of system components. When using the TextInput component for text input, you can perform operations such as limiting input content in the onChange event.

Description

Adding restriction conditions to TextInput component to only allow input of numbers within a certain range. Implementing specific logic in onChange callback, but it doesn't take effect after running. Two issues occur:

Set input range in callback, but can still input numbers beyond the range
After adding $$ two-way binding to text, range restriction works but cannot input decimal points, resulting in only integer input

Problem code:

@Entry
@Component
struct TextInputPage {
  @State inputValue: string = '';

  build() {
    Column() {
      TextInput({
        text: this.inputValue, // Cannot input decimal points after adding two-way binding symbol $$
        placeholder: 'Please enter a number between -50 and 150.'
      })
        .type(InputType.NUMBER_DECIMAL)
        .onChange((value: string) => {
          // Convert to number for range judgment
          let numValue = parseFloat(value) ;
          if (numValue <= -50) { 
            this.inputValue = '-50';
          }else if (numValue >= 150) {
            this.inputValue = '150';
          }else {
            this.inputValue = numValue.toString()
          }
        })
    }
  }
}

Problem analysis:

Check whether $$ two-way binding symbol is used when passing values to TextInput component's text parameter
Trace the source of final displayed numeric values, check if there are operations limiting decimal point input or if decimal points are lost during data conversion

Root cause:

Not using $$ two-way binding symbol when passing values to TextInput text parameter, causing state variable changes unable to synchronize with TextInput component
Decimal points lost after conversion through parseFloat() and toString() methods, causing input failure

Solution

Fix Recommendations:

Add $$ two-way binding symbol to TextInput component's text parameter
Use original string value - onChange event's value is already string type, use value directly for text display instead of converting parseFloat() result back to string
Use inputFilter for negative decimals - When type is set to InputType.NUMBER_DECIMAL, negative decimals are not supported. Use inputFilter to implement negative decimal input

Corrected code:

@Entry
@Component
struct TextInputPage {
  @State inputValue: string = '';

  build() {
    Column() {
      TextInput({
        text: $$this.inputValue,
        placeholder: 'Please enter a number between -50 and 150.'
      })
        .onChange((value: string) => {
          // Convert to number for range judgment
          let numValue = parseFloat(value) ;
          if (numValue <= -50) {
            this.inputValue = '-50';
          }else if (numValue >= 150) {
            this.inputValue = '150';
          }else {
            this.inputValue = value
          }
        })
        .inputFilter('^-?\\d*\\.?\\d{0,2}$', (val) => { // Use regex to limit input content
          return 0
        })
    }
  }
}

Key Takeaways

Two-way Binding: Use $$ symbol for TextInput text parameter to synchronize state changes
Data Type Handling: Avoid unnecessary type conversions that cause decimal point loss
Input Validation: Use inputFilter with regex for complex input restrictions like negative decimals
Range Limitations: InputType.NUMBER_DECIMAL doesn't support negative numbers; use inputFilter as alternative
Performance: Direct string usage is more efficient than parseFloat() + toString() conversion chain

Written by Emincan Ozcan

Dynamically display different pages based on whether the web page is loaded successfully

HarmonyOS — Fri, 04 Sep 2026 01:06:00 +0000

Read the original article：Dynamically display different pages based on whether the web page is loaded successfully

Problem Description

The following functions need to be implemented:

When the web page is loaded normally, the page displays the web page.
When a web page is loaded abnormally, the default page is displayed (the page contains a reload button).

Background Knowledge

onErrorReceive : This callback is triggered when a webpage loading error occurs. This callback is called for both main and subresource errors. You can use isMainFrame to determine whether the error is primarily related to the main resource. For performance reasons, it's recommended to keep this callback as simple as possible. This callback is triggered only when there's no network connection.
visibility: Controls whether the component is shown or hidden. When visibility is not set, the component defaults to being shown.
- Hidden: Hidden, but participates in layout and takes up space.
- Visible: Display.
- None: Hidden, but does not participate in layout and does not occupy placeholders.

Solution

ArkWeb's network protocol stack error list, when ErrorCode is 0, it indicates a normal load; other values indicate an abnormal load.
You can define a successLoad variable and assign the ErrorCode value to it when a load fails. When refreshing the page, set the successLoad value to 0 (if not set to 0, the default page will always be displayed). The page uses a Stack layout, with one layer for the default page and one layer for the web page. When successLoad is 0, the web page is displayed; other values display the default page.

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  @State successLoad: number = 0
  webController: webview.WebviewController = new webview.WebviewController();

  build() {
    Stack(){
      Column(){
        Button('Reload')
          .onClick(()=>{
            this.successLoad = 0
            this.webController.refresh()
          })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
      .backgroundColor('#fff1f1f1')
      .visibility(this.successLoad !== 0 ? Visibility.Visible : Visibility.None)

      Web({ controller: this.webController, src: 'www.example.com'})
        .width('100%')
        .height('100%')
        .visibility(this.successLoad === 0 ? Visibility.Visible : Visibility.Hidden)
        .onErrorReceive((event) => {
          this.successLoad = event.error.getErrorCode()
        })
    }
    .width('100%')
    .height('100%')
  }
}

Written by Emincan Ozcan

Best Practice Design for Pre-Release Validation and Testing Before AppGallery Submission

HarmonyOS — Thu, 03 Sep 2026 01:29:00 +0000

Read the original article：Best Practice Design for Pre-Release Validation and Testing Before AppGallery Submission

Question

What are best practices designs for pre-release validation and testing before appgallery submission?

Short Answer

Every application submitted to Huawei AppGallery goes through a series of validation and quality checks to ensure that it meets the store’s standards and provides a seamless user experience. The quality of a developer’s pre-release testing significantly affects the review duration and approval rate. This article outlines the best practices for validation and testing before submitting an app to AppGallery.

Environment Setup & Configuration Validation

Check whether you have created a release certficate before building APP
Signed APP is must be signed with release .cer.
All permissions used in the application must be clearly declared, and unused permissions must be removed.
Min API / target API, compatibleSDKversion must be verified in order to prevent crashes.
Orientation and aspect ratio issues must be tested across both rounded and rectangular devices.

Functional Test Best Practices

All critical flows such as routing, login, signup, payments, QR scanning, and media playback should be tested end-to-end.
Behavior during background/foreground, offline mode should be validated and tested.
Edge case scenarios lise low ram, low battery mode must be tested.
Apps behavior when permissions are rejected must be tested.
Dark Mode and Light Mode of the device must be tested.

Performance & Stability Testing

CPU load especially on wearable devices, FPS stability, and memory leaks should be tested using DevEco Profiler.
Behavior on slow networks (2G/3G)

Security Validation

Sensitive data (tokens, passwords) must not be stored in plain text.
GDPR validation for the EU region

CI/CD Pipeline

Code Checkout
Static Code Analysis (Linter)
Unit tests
Signing
App packaging

Applicable Scenarios

When releasing a major version update
Before publishing the app to AppGallery for the first time
When adding support for new device categories
When updating the application’s target compatible SDK
Before enabling region-specific functionality

Written by Egemen Ayhan

How to Write Effective Release Notes

HarmonyOS — Thu, 03 Sep 2026 01:26:00 +0000

Read the original article：How to Write Effective Release Notes

Requirement Description

Release notes must clearly communicate what has changed in a new version of an application or library. Developers, testers, and stakeholders should be able to quickly understand new features, improvements, bug fixes, breaking changes, and migration requirements.
This document provides guidelines and a standard structure for preparing effective, concise, and technically accurate release notes.

Background Knowledge

Before writing release notes, contributors should be familiar with:

Versioning Practices Follow semantic versioning when possible (e.g., MAJOR.MINOR.PATCH). Example: 2.3.1 (bug fixes only), 3.0.0 (major breaking update).
Change Types Release notes commonly include the following categories:
- New Features
- Improvements
- Bug Fixes
- Deprecations
- Breaking Changes
- Security Updates
- Migration Notes (if applicable)
Audience Release notes must serve:
- Developers integrating your SDK/library
- QA teams validating updates
- Product managers or technical stakeholders
- End users (optional, depending on distribution channel)
Clarity Standards Huawei’s documentation style emphasizes:
- Action-oriented descriptions
- Consistent formatting
- Compact, easy-to-scan bullet points
- Direct references to API changes, system behaviors, and configuration updates

Implementation Steps

Follow these steps every time you prepare release notes for a new version:

1. Define the Release Scope

Identify everything included in the release:

Features completed
Tickets fixed
Enhancements merged
Internal APIs removed or modified
Known issues resolved or newly identified

This list becomes your raw material.

2. Categorize the Changes

Group the scope items under consistent sections:

New Features: New capabilities or modules
Enhancements: Performance or UX improvements
Bug Fixes: Corrected defects and stability fixes
Breaking Changes: API or behavior changes that require developer action
Deprecations: APIs to be removed in future versions
Security: Permission, policy, or encryption updates
Other: Documentation updates, internal refactors, tooling changes

3. Write Clear, Actionable Items

Use short, developer-oriented bullet points.

Good format examples:

Added LocationUtils.getCurrentCity() API to simplify geolocation queries.
Improved Push Kit initialization time by ~20%.
Fixed a crash occurring when vibrate() was called before permission grant.
Removed the deprecated HmsMapView component. Use MapViewComponent instead.

Avoid:

Marketing language
Vague statements like “various improvements”
Overly detailed internal notes

4. Add Migration/Upgrade Notes (if needed)

Include mandatory developer actions when:

API behavior changes
Permissions change
Data schema updates
Module names or package paths change

Example:

Migration Note: Replace usages of oldApi.getToken() with authManager.requestToken() and update the import path to @kit/AuthKit.

5. Provide Configuration or Code Updates

If the release requires developers to modify code or configuration, include minimal examples.

Examples:

Required imports
New API call patterns
Manifest permissions
New module dependencies

6. Finalize the Document

Keep the document short (ideal: 1 page per release).
Maintain consistent version headers:

Code Snippet / Configuration

Sample:

## Version X.Y.Z (YYYY-MM-DD)

### New Features
- Added <feature> for <purpose>.
- Introduced <API/module> enabling <functionality>.

### Improvements
- Optimized <component> to reduce <latency/memory usage>.
- Updated UI behavior for <module> to improve <experience>.

### Bug Fixes
- Fixed issue where <condition> caused <crash/incorrect data>.
- Resolved synchronization error in <component> during <scenario>.

### Breaking Changes
- Removed <API>. Use <new API> instead.
- Updated permission model. Ensure the following permission is granted:
  ```ts
  // Example for ArkTS
  @ohos.permission.LOCATION

Written by Dogan Evci

Creating and Managing Build Variants in DevEco Studio Projects

HarmonyOS — Thu, 03 Sep 2026 01:24:00 +0000

Read the original article：Creating and Managing Build Variants in DevEco Studio Projects

Requirement Description

How can we implement different build variants in a HarmonyOS application with different configurations.

Background Knowledge

Build variants allow developers to create different versions of an app with configurations for various environments (For example: development, staging, production). This is achieved through build profile configurations that define environment-specific variables.

Implementation Steps

1. Configure project-level build-profile.json5 to define available modules and targets.

"modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "dev",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "staging",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "production",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    }
  ]

2. Configure module-level build-profile.json5 to specify environment-specific variables.

"targets": [
    {
      "name": "dev",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "dev",
              "BG_COLOR": "#e3f2fd",
              "APP_TITLE": "Development"
            }
          }
        }
      }
    },
    {
      "name": "staging",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "staging",
              "BG_COLOR": "#fff9c4",
              "APP_TITLE": "Staging"
            }
          }
        }
      }
    },
    {
      "name": "production",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "prod",
              "BG_COLOR": "#c8e6c9",
              "APP_TITLE": "Production"
            }
          }
        }
      }
    }
  ]

3. Clean the project and generate build profiles.

4. Access these variables in the code using the BuildProfile object.

import BuildProfile from 'BuildProfile';

@Entry
@Component
struct Index {
  @State message: string = BuildProfile.APP_TITLE.toString();
  @State color: string = BuildProfile.BG_COLOR.toString();

  build() {
    Column() {
      Text(`Build Variant: ${this.message}`)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Black)
    }
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .width('100%')
    .backgroundColor(this.color)
  }
}

You can have different implementations for each profile, either through direct usage of BuildProfile variables or build different components based on the build variant.

5. Switch between different targets.

Code Snippet

Complete codes are below;

Project level build-profile.json5;

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "5.1.0(18)",
        "compatibleSdkVersion": "5.1.0(18)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],
    "buildModeSet": [
      {
        "name": "debug",
      },
      {
        "name": "release"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "dev",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "staging",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "production",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    }
  ]
}

Module level build-profile.json5;

{
  "apiType": "stageMode",
  "buildOption": {
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      }
    },
  ],
  "targets": [
    {
      "name": "dev",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "dev",
              "BG_COLOR": "#e3f2fd",
              "APP_TITLE": "Development"
            }
          }
        }
      }
    },
    {
      "name": "staging",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "staging",
              "BG_COLOR": "#fff9c4",
              "APP_TITLE": "Staging"
            }
          }
        }
      }
    },
    {
      "name": "production",
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              "VARIANT_NAME": "prod",
              "BG_COLOR": "#c8e6c9",
              "APP_TITLE": "Production"
            }
          }
        }
      }
    }
  ]
}

Index.ets;

import BuildProfile from 'BuildProfile';

@Entry
@Component
struct Index {
  @State message: string = BuildProfile.APP_TITLE.toString();
  @State color: string = BuildProfile.BG_COLOR.toString();

  build() {
    Column() {
      Text(`Build Variant: ${this.message}`)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Black)
    }
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .width('100%')
    .backgroundColor(this.color)
  }
}

Test Results

Limitations or Considerations

Build profile fields must be defined for all targets.
Changing build variants requires rebuilding the application.

Written by Can Kankaya

How to Obtain Key Logs for Compilation and Build Issues

HarmonyOS — Wed, 02 Sep 2026 02:14:00 +0000

Read the original article：How to Obtain Key Logs for Compilation and Build Issues

Problem Description

During daily development, developers frequently use IDEs to develop and run projects, often encountering various IDE-related compilation and build issues and errors. How can one collect information to identify the root cause of these problems?

Background Knowledge

The hvigor-config.json5 file primarily contains the following:

Specifies the version number of the development-state build tools for the current project, build tasks, and script dependencies.
Specifies relevant capabilities of the build tools, including log levels and execution policies.
Specifies runtime node configuration parameters for the build, as well as additional parameters passed to the build scripts.

A daemon is a computer program that runs as a background process rather than under the direct control of an interactive user. The Hvigor daemon is a persistent background process that reduces the time required to run builds.

The Build Analyzer is a tool used to analyze and optimize project build processes. It helps developers visually analyze and troubleshoot performance and memory issues during builds.

Analysis Conclusion

Most issues can be resolved by analyzing logs, while others require additional context about the runtime scenario and conditions. When collecting logs, note the following:

Log timeliness: Some logs may be lost after a device restart. Export and analyze logs immediately after discovering an issue.
Obfuscated projects: For crashes in Release builds, use the IDE's deobfuscation tool to restore the symbol table and ensure it can be linked to the source code.

Solution

Compilation Errors in the Build Window;

First, obtain the IDE version, SDK version (compilation toolchain version, strongly related to hvigor), hvigor version, and hvigor-config.json5 configuration information.Set stacktrace to true and recompile.

Recompile and provide the compilation error information (including stack traces) from the Build window. Ensure the complete build log includes the error stack context (preferably the full error text in a .txt file).

Daemon-Related Issues;

Obtain the hvigor version and a screenshot of hvigor-config.json5.

Retrieve the daemon logs from the Build window.
If the error message indicates a specific daemon issue, retrieve the corresponding daemon logs. If not, reproduce the issue and collect the daemon logs again. The logs can typically be found at;
**C:\Users\xxxxx.hvigor\daemon\log\5.19.0**
Retrieve the idea.log logs by navigating to Help > Show Log in Explorer in the IDE.

Build Time Issues;

Obtain the IDE and hvigor versions.

Enable advanced mode and rebuild the project to collect new analysis logs. In Settings, search for Hvigor, enable "Use build analysis mode," and select verbose (older versions) or advanced (newer versions).

Identify the most time-consuming tasks.
Expand the tasks to locate the longest-running subtasks.
Finally, retrieve the report.json (preferably for the current compilation). Click the export button in the top-right corner to export the report.

FAQ

Q: The IDE reports many build errors during compilation. How can I quickly locate the error information?

A: Search for "hvigor ERROR" in the IDE's Build window to quickly locate hvigor-related build errors.

Q: Error messages in the Build Output window are often buried among warnings. How can I filter them out quickly?

A: Under Build Output, click the second button on the left ("Open Build Analyzer") and navigate to Tasks. Click "Error" to view specific error messages.

Written by Can Kankaya

Expanding the Clickable Area of Image Components with responseRegion and Container Wrapping

HarmonyOS — Wed, 02 Sep 2026 02:03:00 +0000

Read the original article：Expanding the Clickable Area of Image Components with responseRegion and Container Wrapping

Expanding the Clickable Area of Image Components with responseRegion and Container Wrapping

Requirement Description

In some HarmonyOS ArkUI layouts, an Image component (such as a 20×20 icon) can be difficult for users to tap accurately, especially on dense UIs or wearable devices with small screens.

The requirement is:

How can we expand the clickable / touch area of an Image component without visually enlarging the icon itself?

The goal is to improve touch usability while keeping the visual size of the image unchanged.

Background Knowledge

Image component

The Image component is used to display bitmap or vector images (PNG, JPG, SVG, WEBP, GIF, etc.) within ArkUI applications.(Huawei Developer)

In real-world designs, icons (e.g., 16–24 vp) are often visually small but should remain easy to tap.

Touch target and responseRegion

ArkUI provides a Touch Target capability to configure the interactive (touch / click) region of components that support universal click/touch events. This is documented in the Touch Target Doc. (Huawei Developer)

Key concept: responseRegion

responseRegion allows setting one or more touch hot zones.
Each region is defined by { x, y, width, height }.
Default region: { x: 0, y: 0, width: '100%', height: '100%' }, i.e., the component’s own visual area.
width/height can be:
- Absolute values (e.g., 200),
- Or percentages (e.g., '100%').

By increasing width and height, you can expand the clickable area without changing the visual size of the component.

Container-based click region

Another common pattern is to:

Wrap the Image in a container (Row, Column, Stack).
Attach .onClick to the outer container.
Use padding or margin on that container to enlarge the actual interactive area.

This pattern is especially useful when:

You want to group multiple UI elements (icon + text) but treat them as a single touch target.
You want complete control over layout and hit test behavior.(Huawei Developer)

Implementation Steps

There are two equivalent solutions:

Solution 1 – Use `responseRegion` on the Image

Keep the Image component’s width and height as the visual icon size (e.g., 20×20).
Attach an onClick handler directly to the Image.
Use .responseRegion({ width, height }) to make the touch target larger than the visual area.
Optionally, adjust x and y to shift the hot zone relative to the image.

This is the most direct way using ArkUI’s built-in touch target mechanism.

Solution 2 – Wrap the Image in a Container

Wrap the Image inside a Row or Column.
Attach .onClick to the outer Row/Column rather than to the Image itself.
Use padding/margin on the container to make the layout box (and thus the touch area) larger.
The Image can stay visually small inside this larger container.

This approach is API-agnostic, works with any component, and is familiar to developers coming from other UI frameworks.

Code Snippet / Configuration

Solution 1 – Expanding the Click Area with `responseRegion`

@Entry
@Component
struct Index1 {
  build() {
    Column() {
      Image($r('app.media.startIcon'))
        .width(20)
        .height(20)
        .onClick(() => {
          this.getUIContext().getPromptAction().showToast({
            message: 'Triggered'
          });
        })
        // Expand the actual touch area to 200x200, 
        // while the image remains visually 20x20.
        .responseRegion({ width: 200, height: 200 });
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 });
  }
}

Visual size of icon: 20×20.
Touch/Click area: 200×200 rectangular region centered on the image (depending on layout).
Ideal when you want minimal layout changes and direct control via responseRegion.(Huawei Developer)

Solution 2 – Expanding the Click Area via Container Padding

@Entry
@Component
struct Index2 {
  build() {
    Column() {
      Row() {
        Image($r('app.media.startIcon'))
          .width(20)
          .height(20)
          .margin({ bottom: 200 }) // effectively enlarges the Row's area around the image
      }
      .onClick(() => {
        this.getUIContext().getPromptAction().showToast({
          message: 'Triggered'
        });
      });
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 });
  }
}

The Row becomes a larger clickable box (due to margins/padding).
The Image stays visually small at the center/top.
This pattern is handy when:
- The entire row (icon + text, etc.) should be clickable.
- You want flexible layout control using padding/margin alone.(Huawei Developer)

Both solutions ultimately achieve the same user-visible effect: the icon is easy to tap despite its small visual size.

Complete Index.ets

@Entry
@Component
struct Index {
  @State currentSolution: number = 1;

  private showToast(message: string) {
    this.getUIContext().getPromptAction().showToast({
      message
    });
  }

  build() {
    Column() {
      // Simple toggle between Solution 1 and Solution 2
      Row() {
        Button(this.currentSolution === 1 ? 'Solution 1' : 'Go to Solution 1')
          .fontSize(10)
          .onClick(() => {
            this.currentSolution = 1;
          })
          .margin({ right: 6 })

        Button(this.currentSolution === 2 ? 'Solution 2' : 'Go to Solution 2')
          .fontSize(10)
          .onClick(() => {
            this.currentSolution = 2;
          })
      }
      .justifyContent(FlexAlign.Center)
      .margin({ bottom: 12 })

      if (this.currentSolution === 1) {
        this.ResponseRegionDemo();
      } else {
        this.ContainerDemo();
      }
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .padding(12)
    .backgroundColor(0x222222);
  }

  @Builder
  ResponseRegionDemo() {
    Column() {
      Text('Solution 1: responseRegion')
        .fontSize(12)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 8 })
        .fontColor(0xFFFFFF)

      // Small icon, large touch target using responseRegion
      Image($r('app.media.startIcon'))
        .width(24)
        .height(24)
        .onClick(() => {
          this.showToast('responseRegion tapped');
        })
        // For wearable, 72x72 is usually a comfortable tap area
        .responseRegion({ width: 72, height: 72 })
        .backgroundColor(0x444444) // optional visual hint
        .borderRadius(36)

      Text('Try tapping around the icon area')
        .fontSize(10)
        .margin({ top: 8 })
        .fontColor(0xCCCCCC)
    }
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }

  @Builder
  ContainerDemo() {
    Column() {
      Text('Solution 2: Container click')
        .fontSize(12)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 8 })
        .fontColor(0xFFFFFF)

      // Larger Row acts as the tap target, Image stays visually small inside
      Row() {
        Image($r('app.media.startIcon'))
          .width(24)
          .height(24)
      }
      .onClick(() => {
        this.showToast('Container tapped');
      })
      .padding(16) // enlarge tap area via padding
      .backgroundColor(0x444444)
      .borderRadius(36)

      Text('Tap anywhere inside the gray circle')
        .fontSize(10)
        .margin({ top: 8 })
        .fontColor(0xCCCCCC)
    }
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

Test Results

Verified that:
- Both Solution 1 and Solution 2 correctly trigger the onClick handler even when the user taps outside the 20×20 visual image but inside the expanded hot zone.
- Toast message “Triggered” appears reliably.
Any static analysis / Code Check passes, as the code strictly uses documented ArkUI attributes and event handling.

Limitations or Considerations

responseRegion only applies to components that support universal click/touch/gesture events, as described in the Touch Target Doc. (Huawei Developer)
When increasing the touch area:
- Be careful not to overlap with neighboring components’ touch targets.
- On complex layouts (e.g., Stack with overlapping components), you may need to adjust hitTestBehavior or layout to ensure the correct component receives the event.(CSDN Blog)
On wearable devices, oversized touch regions might:
- Interfere with scroll gestures if they cover a large portion of the screen.
- Require careful design to balance usability and gesture behavior.

Written by Bunyamin Eymen Alagoz

Keeping a bindSheet Semi-Modal Page Visible When the Host Component Is Hidden

HarmonyOS — Wed, 02 Sep 2026 01:18:00 +0000

Read the original article：Keeping a bindSheet Semi-Modal Page Visible When the Host Component Is Hidden

Keeping a bindSheet Semi-Modal Page Visible While Hiding Its Host Component

Requirement Description

In a HarmonyOS ArkUI application, a semi-modal page is bound to a host component using bindSheet. When the user taps the host component, the semi-modal page (sheet) appears as expected.

However, the host component itself can later be hidden based on business logic. The requirement is:

Even when the host component becomes hidden, the bound semi-modal page should remain visible until the user closes it.

In the current implementation, when the host component is hidden via conditional rendering, both the host component and its bound semi-modal page disappear at the same time, which does not meet the UX requirement.

Background Knowledge

1. Semi-modal page (bindSheet)

The semi-modal page is a modal, non-fullscreen popup that partially overlays the parent view while keeping part of the underlying UI visible. It is implemented via the bindSheet sheet transition attribute. (Huawei Developer)

Key points:

bindSheet binds a sheet to a host component.
The sheet is typically shown when the host component is tapped.
The sheet’s size can be customized via SheetOptions.height.

If the bound host component is removed from the component tree, the sheet also disappears because its lifecycle is tied to that host.

2. Visibility vs Conditional Rendering (`if`)

Visibility control is a universal ArkUI attribute that controls whether a component is visible, hidden but occupying space, or completely removed from layout. (Gitee)

Visibility.Visible – Component is visible.
Visibility.Hidden – Component is not visible but still occupies layout space.
Visibility.None – Component is not visible and does not occupy layout space, but it still exists in the component tree.

By contrast:

Conditional rendering with if/else adds or removes components from the component tree entirely.
When the host component of bindSheet is removed via if logic, the sheet is removed as well.

For scenarios where a component frequently switches between shown and hidden (like a host for bindSheet), using visibility is preferred over conditional rendering for both performance and lifecycle stability. (Gitee)

Implementation Steps

1.Identify the problem pattern
The original implementation uses an if (isShow) block to decide whether the host component (bound to bindSheet) exists:

   if (this.isShow) {
     Text('Component bound to bindSheet')
       .bindSheet($$this.sheetShow, this.SheetBuilder(), {
         height: 500
       })
   }
   Copy codeCopy code

2.Once isShow is set to false, the host component is removed from the component tree, and the semi-modal page disappears as well.

3.Keep the host component in the component tree
Instead of removing the component using if, keep the component always rendered and control its visibility via the visibility attribute:

   Text('Component bound to bindSheet')
     .visibility(this.isShow ? Visibility.Visible : Visibility.None)
     .bindSheet($$this.sheetShow, this.SheetBuilder(), {
       height: 500
     })
   Copy codeCopy code

When isShow is false, the host component is not visible and does not occupy space.
But it still exists in the component tree, so bindSheet continues to work and the semi-modal remains visible until explicitly closed.

4.Control the timing

After opening the semi-modal page, you can hide the host component after a delay (for example, 3 seconds), while leaving the sheet visible:

   Text('Click')
     .fontSize(24)
     .fontWeight(FontWeight.Bold)
     .onClick(() => {
       this.sheetShow = true;
       setTimeout(() => {
         this.isShow = false; // Now only visibility changes, not existence.
       }, 3000);
     })
   Copy codeCopy code

5.Apply the same pattern for HarmonyOS wearable

On HarmonyOS 6 / HarmonyOS wearable, the same core idea works:

The UI is adapted to a watch form-factor (smaller height, percentages instead of large absolute vp).
bindSheet + visibility still control semi-modal and host independently.
Only layout and height values need to be tuned (for example, using "60%" of screen height instead of 500).

Code Snippet / Configuration

1. Problematic Sample (Host Removed with `if`)

@Entry
@Component
struct Index {
  @State isShow: boolean = true;
  @State sheetShow: boolean = false;

  @Builder
  SheetBuilder() {
    Text('Semi-modal content')
      .margin({ top: 16 })
  }

  build() {
    Column() {
      Text('Click')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          this.sheetShow = !this.sheetShow;
          setTimeout(() => {
            // Host component is removed from the tree
            this.isShow = false;
          }, 3000);
        });

      if (this.isShow) {
        Text('Component bound to bindSheet')
          .bindSheet($$this.sheetShow, this.SheetBuilder(), {
            height: 500
          });
      }
    }
    .padding(24)
    .height('100%')
    .width('100%')
  }
}Copy codeCopy code

Effect: After 3 seconds, both the host text and the semi-modal page disappear.

2. Corrected Sample (Host Hidden via `visibility`)

@Entry
@Component
struct Index {
  @State isShow: boolean = true;
  @State sheetShow: boolean = false;

  @Builder
  SheetBuilder() {
    Column() {
      Text('Semi-modal content')
        .margin({ top: 16 })

      Button('Close')
        .margin({ top: 16 })
        .onClick(() => {
          this.sheetShow = false;
          // Optionally show host again
          this.isShow = true;
        })
    }
    .width('100%')
    .padding(16)
  }

  build() {
    Column() {
      Text('Click')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          this.sheetShow = true;
          setTimeout(() => {
            // Only hide visually, keep in component tree
            this.isShow = false;
          }, 3000);
        });

      Text('Component bound to bindSheet')
        .visibility(this.isShow ? Visibility.Visible : Visibility.None)
        .bindSheet($$this.sheetShow, this.SheetBuilder(), {
          height: 500
        })
    }
    .padding(24)
    .height('100%')
    .width('100%')
  }
}Copy codeCopy code

Complete Index.ets

@Entry
@Component
struct Index {
  @State sheetShow: boolean = false;
  @State hostVisible: boolean = true;

  @Builder
  SheetContent() {
    Column() {
      Text('Semi-modal content')
        .fontSize(16)
        .margin({ top: 12 })

      Button('Close')
        .margin({ top: 12 })
        .fontSize(14)
        .onClick(() => {
          this.sheetShow = false;
          this.hostVisible = true;
        })
    }
    .width('100%')
    .padding(16)
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }

  build() {
    Column() {
      Text('Show sheet')
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          this.sheetShow = true;
          // Hide host component after 3 seconds, but keep sheet visible
          setTimeout(() => {
            this.hostVisible = false;
          }, 3000);
        })
        .margin({ bottom: 24 })

      // Host component bound to bindSheet, only visibility is toggled
      Text('Host component')
        .fontSize(14)
        .visibility(this.hostVisible ? Visibility.Visible : Visibility.None)
        .bindSheet($$this.sheetShow, this.SheetContent(), {
          // For wearable, use a percentage of screen height
          height: '60%'
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .padding(12)
  }
}Copy codeCopy code

Effect:

After tapping "Click", the semi-modal page appears.
Three seconds later, the host text becomes invisible (and no longer occupies space), but the semi-modal page remains visible.
The user can close the semi-modal page from inside the sheet.

This pattern is directly reusable on HarmonyOS wearable; only UI sizes should be adjusted.

Test Results

Verified that:
- The semi-modal page opens correctly when the host component is tapped.
- After the host component’s visibility switches to Visibility.None, the semi-modal stays visible.
- Closing the semi-modal from within the sheet works and can optionally restore the host’s visibility.
Static analysis (Code Check) passes with no issues; Code Check clearing screenshot was captured in the original article.

Limitations or Considerations

This approach is ideal when:
- The host component and semi-modal page frequently toggle between visible and hidden.
- You want to avoid destroying and recreating the component tree for performance reasons. (Gitee)
For components that:
- Are rarely shown, or
- Consume a large amount of memory,

it may still be better to use conditional rendering (if/else) to fully destroy them when not needed, to save memory. (Gitee)

The sample environment from the original case:
- Supports API Version 19 Release or later.
- Built with HarmonyOS 5.1.1 Release SDK or later.
- Compiled and run using DevEco Studio 5.1.1 Release or later.
For HarmonyOS 6 / HarmonyOS wearable, the same visibility logic applies; you mainly need to:
- Update SDK/API version.
- Re-adjust layout (e.g., using percentages or SheetSize for watch screens). (Gitee)

Written by Bunyamin Eymen Alagoz

Differences and application scenarios of HAR, HSP, and HAP files

HarmonyOS — Tue, 01 Sep 2026 01:12:00 +0000

Read the original article：Differences and application scenarios of HAR, HSP, and HAP files

Differences and application scenarios of HAR, HSP, and HAP files

Problem Description

In projects, we often come across HAR, HSP, and HAP. What are the differences between these three, and what are their respective use cases?

Background Knowledge

HAP: A HAP is the basic unit for installing and running an application. It is a module package that contains code, resources, third-party libraries, and configuration files. There are two types of HAPs: entry and feature. An application package can contain only one basic entry HAP or one basic entry HAP and multiple feature HAPs.

HAR: This is a static shared package that can include code, C++ libraries, resources, and configuration files. Through HAR, multiple modules or projects can share ArkUI components, resources, and related code.

Supports in-app sharing and can also be published for use by other applications.
As a second-party library, it is released to the OHPM private repository for use by other applications within the company.
As a third-party library, it is published to the OHPM central repository for use by other applications.
If multiple HAPs or HSPs reference the same HAR, the code and resources in the HAR will be copied repeatedly, resulting in larger application packages.

HSP: It is a dynamic shared package that can include code, C++ libraries, resources, and configuration files. Through HSP, code and resources can be shared. HSP cannot be released independently; instead, it is released together with the host application's APP package, sharing the same process as the host application and having the same package name and lifecycle. Code and resources shared by multiple HAPs/HSPs are placed in the same HSP, which enhances the reusability and maintainability of the code and resources. Additionally, during compilation and packaging, only one set of HSP code and resources is retained, effectively controlling the size of the application package.

HSPs in an app: During compilation, they are strongly coupled with the bundle name of the app and can be used only by a specific app.
Integrated HSP: During the build and release process, it is not coupled with a specific application package name. When in use, the toolchain supports automatically replacing the package name of the integrated HSP with the host application's package name and will re-sign to generate a new HSP package, which serves as the installation package for the host application. This new HSP also falls under the category of in-app HSPs.

Solution

Comparison dimension	HAP	HAR	HSP
Definition	A basic unit for installing and running an application, including code, resources, and configurations., Entry (main module) and feature (feature module) are supported.)	Static shared package, used for code/resource reuse (such as UI components and utility classes).)	Dynamic shared package, shared by multiple modules at runtime.
Cross-application sharing	Not shareable	Can be published to OHPM central warehouse/private warehouse.	Sharing only within the app.
Resource Reuse Methodology	N/A	Copying to the Referenced Module During Compilation	Dynamic loading at runtime
Multi-module reference impact	N/A	Code/resource duplication → Increased package size	Keep only one copy → Save space.
Typical Use Cases	1. Entry module: implements the app startup page and core functions.; 2. Feature module: extended functions (such as the payment module), which are loaded on demand.	1. Encapsulation of the common UI component library and tool classes; 2. Cross-team/enterprise sharing: Publish to OHPM central warehouse or private warehouse for other applications to call.	1. Multiple modules share large resources (such as images and videos) to avoid repeated packaging and copying.; 2. Quick App Subcontracting preloading, improving performance; 3. The packet expansion problem caused by HAR is resolved.
Key constraints	1. Declaration of Abilities/Pages is not supported, but pages can be included through navigation redirection.; 2. Cyclic dependency is not allowed. AppScope resources cannot be referenced.	1. The version number must be the same as that of the host HAP.; 2. It cannot be independently released to the app store.	Cannot be used as a shared package for other applications.

FAQs

Q: If multiple modules use the same HAR, will there be multiple HAR packages or only one HAR package in the app?
A: There may be multiple copies. Each user will copy a HAR file to the corresponding module, which increases the package size. For large files such as duplicate resources, it is recommended to use HSP for replacement.

Q: Can I create an AbilityStage in the HAR package? When is the lifecycle of the AbilityStage executed?
A: No. An AbilityStage corresponds to a HAP. The following figure shows the relationship between them.:

Q: What should I do if a compilation error is reported after the HAR is converted to the HSP?
A: After HAR to HSP package conversion /no_think. Ensure that the following configurations are correct:

Check whether the type is set to shared and deliveryWithInstall is added in the module.json5 file in the HAR.
Check whether the name of the hvigorfile.ts file in the module is changed from harTasks to hspTasks.
By default, the build-profile.json5 file of the HAR package contains "consumerFiles": './consumer-rules.txt'. This item is only configurable for the HAR module and is the default obfuscation rule that is exported. You need to delete this item.

Q: Multiple HSPs reference the same HAR. The values in the HAR have been initialized in HSP A, but when used in HSP B, the values in the HAR are still the default. How can this issue be resolved?
A: After a HAR is referenced by multiple HSPs, it will be copied to each HSP. Therefore, instances in a HAR cannot be shared by multiple modules. In this case, you are advised to use HSPs instead of HARs.

Q: In which scenarios are multiple HAPs used?
A: Multiple HAPs are primarily designed to facilitate developers in managing applications in a modular manner. This allows developers to reasonably combine and deploy multiple HAPs on different devices, load them as needed, and reduce the package size. For example, in a payment application, there is a unified main interface that manages various modules such as "Scan," "Payment," "Messages," and "Financial Management." The logic for managing these other modules within the main interface is implemented in the entry package, while the "Scan," "Payment," "Messages," and "Financial Management" modules are implemented in separate feature packages. Developers can simultaneously develop multiple feature packages, enabling independent development and testing of each feature package, which are ultimately integrated into the entry package to provide the unified functionality of the feature packages.

Q: Can HAP be used as a shared package for other applications?
A: No, to share the package with other applications, please use HAR or integrated HSP.

Q: How can HSP be uploaded to the central repository for use by other third-party applications?
A: The OpenHarmony third-party library central repository only supports the release of HAR shared packages and does not support the release of HSP shared packages. If you need to share HSP within an application, you can publish the HSP shared package to a private repository for use. Please refer to ohpm private repository setup tool.

Q: In a project, there is one entry module and multiple feature modules. How can I specify the feature modules to be loaded after the program is started?
A: The entry module is the only module that can be used as the program startup entry. You cannot specify the feature modules to be loaded after the program is started. However, you can specify the type of each module as either entry or feature, and ensure that only one entry module exists. When the program is started, the entry module will be loaded. You can modify the type attribute in the module.json5 file of the module.

Q: How can an HSP compiled into an.tgz package for in-app sharing depend on external HAR packages?
A: The dependent HAR package needs to be embedded in the HSP package and compiled into a.tgz package.

Q: How can an in-app shared HSP compiled into a.tgz package depend on external HSP packages?
A: The dependent HSP package needs to be embedded in the HSP package and compiled together into the.tgz format, or the dependent HSP needs to be released to a private repository and shared during HSP development using version numbers for dependency management.

Q: Can a HAP be set as an independent process?
A: On 2-in-1 and tablet devices, the HAP can be set as an independent process for UIAbility. Modular Independent Processes

Q: Why is the size of the app package released to AppGallery smaller than that of the HAP package?
A: The HAP package compiled in the app is generally smaller than the normally compiled HAP package. The default compilation mode for the app package is non-Debug, while the default for the HAP package is Debug mode. Compared to the release version, the Debug version includes complete debugging information and symbol tables, which help developers quickly locate issues during debugging, view variable values, function call stacks, etc. In addition, the Debug version has not undergone obfuscation and optimization, resulting in a larger package size compared to the release version.

Q: During installation, the HSP was installed first, followed by the HAP. If there are subsequent updates for the HAP, can I directly hdc install hap? If I uninstall the HAP, will the related dependent HSP also be uninstalled?
A: You can directly hdc install xxx.hap without needing to uninstall and reinstall; the HSP will not be uninstalled. The HSP is a shared module and may be used by multiple HAPs.

Q: In the project-level oh-package.json file, the A HAR module is depended on. After compilation, the A HAR module is packed into the B HSP module. However, the B HSP module does not depend on the A HAR module, and a message is displayed indicating that the A and B modules are cyclically depended on.
A: The dependencies declared in the project-level oh-package.json file are used by all modules in the project. Currently, you are not advised to configure dependencies that are not in devDependencies in the project-level dependencies. That is, the non-development dependencies of an HSP or HAR module must be declared in the dependencies and dynamicDependencies of the corresponding module. You can declare the dependencies in the project-level oh-package.json file in the oh-package.json file of the required module as required.

Q: HAP depends on HSP and HAR. When HSP does not depend on HAR, can HSP use the resources in HAR?
A: There is no dependency relationship between HSP and HAR; HSP cannot use resources from HAR.

Written by Emine INAN

Best Practice Design for Handling Source and Asset Changes Across Build Variants

HarmonyOS — Tue, 01 Sep 2026 01:07:00 +0000

Read the original article：Best Practice Design for Handling Source and Asset Changes Across Build Variants

Requirement Description

In multi‑variant application development (e.g., free vs. paid, debug vs. release), it's essential to manage both source code and resources/assets (images, strings, layouts) across variants. The goal is to:

Create a flexible build system where shared code and variant‑specific overrides (assets or code) can coexist with minimal duplication.
For resources, use directory structures that allow automatic resource picking at build time without runtime branching.
For source code, use conditional compilation or flagging to ensure variant‑specific logic and behavior while maintaining a clean codebase.

Background Knowledge

Managing Modules: Organizing your project into modules (entry, feature, common) to separate shared and variant-specific code.
Configuring Multiple Targets and Products: In build‑profile.json5, you define products (variants) and targets to customize the build for each variant (e.g., free_debug, paid_release).
Conditional Source Flags: Using buildProfileFields to set flags that allow conditional logic based on the variant.
Generating the BuildProfile Class File

Implementation Steps

1. Define Modules & Variants

Split the project into modules (e.g., commonLib, entry) and define build targets for each variant in build‑profile.json5.
In the root build‑profile.json5, define products and their corresponding build configurations (e.g., free/paid, debug/release). Each product points to different targets.
Example:

  "targets": [
          {
            "name": "default",
            "applyToProducts": [ "default" ]
          },
          {
            "name": "free",
            "applyToProducts": [ "free" ]
          },
          {
            "name": "paid",
            "applyToProducts": [ "paid" ]
          }
        ]

2. Organize Resource Folders for Variants

Use a resource folder structure that supports variant overrides, such as:

  AppScope
  ├───common
  │    └───media
  │           └─── image.png
  ├───freeResources
  │    └───media
  │           └─── image.png
  └───paidResources
       └───media
            └─── image.png

In the build‑profile.json5 for each module, map the appropriate resource directories for each target. HarmonyOS supports this and resolves the correct resource automatically.
Example for a module:

  "products": [
        {
          "name": "free",
          "resource" : {
            "directories" : [
              "./AppScope/freeResources"
            ]
          }
        },
        {
          "name": "paid",
          "resource" : {
            "directories" : [
              "./AppScope/paidResources"
            ]
          }
        }
  ]

When building the "paid" variant, the build system will pick image.png from paid/, and if not available, it will fallback to common/.

3. Handle Source Code Management (Conditional Compilation)

For source code, you can conditionally compile or execute variant-specific logic using flags set in build‑profile.json5 (e.g., IS_PREMIUM). You can then use these flags in your code to determine which logic or functionality to enable based on the variant.
Use these flags in source code to adjust logic:

  import BuildProfile from "BuildProfile"

  @Entry
  @Component
  struct Index {
    public target = BuildProfile.TARGET_NAME

    @Builder
    private setupPremiumFeatures() {
      Text("Premium")
    }

    @Builder
    private setupFreeFeatures() {
      Text("Free")
    }

    build() {
      Column() {
        if (this.target === 'paid') {
          this.setupPremiumFeatures();
        } else {
          this.setupFreeFeatures();
        }
      }
      .width('100%')
      .height('100%')
    }
  }

4. Asset and Source Override Workflow

For shared resources, update the common resource folder.
For variant‑specific changes, place assets in the respective variant folders (e.g., free/, paid/).
For source code, conditionally compile based on buildProfileFields. Use if/else for runtime decisions if variants cannot be handled by the build system alone.
Example:
- Shared assets: common/logo.png is used across all variants unless overridden by paid/logo.png.
- Conditional code: Different API endpoints for paid and free users, determined by BuildProfile.TARGET_NAME.

5. Create BuildProfile class

Select the module for build and choose Build > Generate Build Profile ${moduleName} on the menu bar.

Code Snippet / Configuration

Project-level `build‑profile.json5` :

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "6.0.0(20)",
          "compatibleSdkVersion": "6.0.0(20)",
            "runtimeOS":"HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      },
      {
        "name": "free",
        "signingConfig": "default",
        "targetSdkVersion": "6.0.0(20)",
        "compatibleSdkVersion": "6.0.0(20)",
        "runtimeOS":"HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        },
        "resource" : {
          "directories" : [
            "./AppScope/freeResources"
          ]
        }
      },
      {
        "name": "paid",
        "signingConfig": "default",
        "targetSdkVersion": "6.0.0(20)",
        "compatibleSdkVersion": "6.0.0(20)",
        "runtimeOS":"HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        },
        "resource" : {
          "directories" : [
            "./AppScope/paidResources"
          ]
        }
      }
    ],
    "buildModeSet": [
      {
          "name": "debug",
      },
      {
        "name": "release"
      }
    ]
  },
  "modules": [

  {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "free",
          "applyToProducts": [
            "free"
          ]
        },
        {
          "name": "paid",
          "applyToProducts": [
            "paid"
          ]
        }
      ]
    }]
}

Module-level `entry/build‑profile.json5` (resource configuration):

{
  "apiType": "stageMode",
  "buildOption": {

    "resOptions": {
      "copyCodeResource": {
        "enable": false
      }
    }
  },
  "buildOptionSet": [
    {
      "name": "free",
      "arkOptions": {
        "buildProfileFields": {
          "IS_PREMIUM": false
        },
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      }
    },
    {
      "name": "paid",
      "arkOptions": {
        "buildProfileFields": {
          "IS_PREMIUM": true
        },
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      }
    }
  ],
  "targets": [
    {
      "name": "free"
    },
    {
      "name": "paid"
    }
  ]
}

Asset Directory Structure :

AppScope
├───freeResources
│    └───media
│         └─── image.png
└───paidResources
     └───media
            └─── image.png

ArkTS Source Code with Conditional Compilation and Resource Handling:

import BuildProfile from "BuildProfile"

@Entry
@Component
struct Index {
  public target = BuildProfile.TARGET_NAME
  public img = this.getUIContext().getHostContext()?.resourceManager.getMediaContent($r('app.media.image').id)

  @Builder
  private setupPremiumFeatures() {
    Text("Premium")
  }

  @Builder
  private setupFreeFeatures() {
    Text("Free")
  }

  build() {
    Column() {
      if (this.target === 'paid') {
        this.setupPremiumFeatures();
      } else {
        this.setupFreeFeatures();
      }
      Image($r('app.media.image'))
        .width(100)
        .height(100)
        .objectFit(ImageFit.Contain)

    }
    .width('100%')
    .height('100%')
  }
}

Test Results

Select product:
Check that no unintended resources are included, and the right source code paths are compiled.
Asset Validation: Ensure that variant‑specific assets (e.g., images) are correctly selected based on the variant.
Source Validation: Ensure that the correct logic is being executed based on flags (BuildProfile.TARG_NAME).

Limitations or Considerations

This sample supports API Version 12 Release and above.
This sample supports HarmonyOS 5.0.0 Release SDK and above.
Compilation and execution require DevEco Studio 5.0.0 Release or later

Written by Bunyamin Akcay

In Release mode, objects cannot use the Object.attribute method to access attributes

HarmonyOS — Tue, 01 Sep 2026 01:02:00 +0000

Read the original article：In Release mode, objects cannot use the Object.attribute method to access attributes

Problem Description

When the build mode is set to release, the value obtained from the Record object through T.a is undefined. It can only be accessed using T["a"]. However, in debug or other build modes, the value can be accessed normally.
Developers hope that DevEco Studio can provide an out-of-the-box obfuscation configuration, or automatically generate a general obfuscation rule file when creating a new project, eliminating the need for additional configuration.

Background Knowledge

Starting from DevEco Studio NEXT Developer Beta3 (5.0.3.600), the code obfuscation feature is disabled by default for new projects and modules. If code obfuscation is enabled in the module-level build-profile.json5 configuration file, the obfuscation rule file obfuscation-rules.txt will enable the recommended rules by default, including -enable-property-obfuscation, -enable-toplevel-obfuscation, -enable-filename-obfuscation, and -enable-export-obfuscation. Developers can further choose which rules to enable in the obfuscation-rules.txt file. For more information about these rules, please refer to Obfuscation Rules.
After enabling obfuscation, methods, properties, or paths in the code are obfuscated. However, the runtime accesses the unobfuscated names, which may lead to functionality issues. Therefore, it is necessary to configure the keep options for the corresponding fields. For troubleshooting and configuring keep options, refer to Obfuscation Rules. If you do not want properties to be obfuscated, you can open the obfuscation-rules.txt file in the module directory and configure the rules to keep the properties. For details on keep options, see Keep Options.
If there are many scenarios or fields that need to be checked and configured, DevEco Studio provides an Obfuscation Helper tool. It can scan the source code based on modules and scenarios to quickly identify the fields and keep options that need configuration, and generate a whitelist rule file with one click. However, please note that for some cases where names or properties are accessed dynamically at runtime, the Obfuscation Helper will detect such scenarios, and developers will need to manually verify and configure the whitelist according to business needs. For details, refer to Configuring Keep Options via Obfuscation Helper.

Troubleshooting Process

Check the data source to confirm whether the data was already obfuscated before being passed in.
Compare the behavior with obfuscation enabled and disabled to see if the issue can be reproduced. It was found that when obfuscation is enabled, T.a cannot access the property correctly and returns undefined, but the issue disappears when obfuscation is disabled.
The Obfuscation Helper can scan the source code based on modules and scenarios to quickly identify the required keep options and whitelist fields, and generate a whitelist rule file with one click. This not only reduces manual configuration but also helps avoid runtime issues caused by missing critical configurations.

Analysis Conclusion

The root cause is that code obfuscation is enabled. Enabling obfuscation causes object property names to be obfuscated, resulting in T.a being unable to correctly access the property value. The reason T["a"] works is that string keys are not obfuscated.
For simplifying obfuscation configuration, it is recommended to use the Obfuscation Helper tool.

Reference document: Code Obfuscation.

Solution

Disable obfuscation to resolve the issue.
If obfuscation must be enabled, use T["a"] to access the property.
If the codebase is large and you do not want to disable obfuscation, configure the properties in the Record object to the whitelist using the -keep-property-name option.
During HarmonyOS app development, if certain classes or methods need to be excluded from obfuscation, developers must manually configure whitelist rules. To simplify this process, it is recommended to use the Obfuscation Helper to automate part of the configuration.

DEV Community: HarmonyOS

Grid Item Drag and Move with Auto-Scroll Functionality

Context

Description

Solution

Example Code

Key Features of onMove

Key Takeaways

Written by Emincan Ozcan

How to Solve TextInput Input Restriction Abnormality Issues

Context

Description

Solution

Fix Recommendations:

Key Takeaways

Written by Emincan Ozcan

Dynamically display different pages based on whether the web page is loaded successfully

Problem Description

Background Knowledge

Solution

Written by Emincan Ozcan

Best Practice Design for Pre-Release Validation and Testing Before AppGallery Submission

Question

Short Answer

Applicable Scenarios

Written by Egemen Ayhan

How to Write Effective Release Notes

Requirement Description

Background Knowledge

Implementation Steps

Code Snippet / Configuration

Written by Dogan Evci

Creating and Managing Build Variants in DevEco Studio Projects

Requirement Description

Background Knowledge

Implementation Steps

Code Snippet

Test Results

Limitations or Considerations

Written by Can Kankaya

How to Obtain Key Logs for Compilation and Build Issues

Problem Description

Background Knowledge

Analysis Conclusion

Solution

Related Documents or Links

Written by Can Kankaya

Expanding the Clickable Area of Image Components with responseRegion and Container Wrapping

Expanding the Clickable Area of Image Components with responseRegion and Container Wrapping

Requirement Description

Background Knowledge

Image component

Touch target and responseRegion

Container-based click region

Implementation Steps

Solution 1 – Use responseRegion on the Image

Solution 2 – Wrap the Image in a Container

Code Snippet / Configuration

Solution 1 – Expanding the Click Area with responseRegion

Solution 2 – Expanding the Click Area via Container Padding

Test Results

Limitations or Considerations

Related Documents or Links

Written by Bunyamin Eymen Alagoz

Keeping a bindSheet Semi-Modal Page Visible When the Host Component Is Hidden

Keeping a bindSheet Semi-Modal Page Visible While Hiding Its Host Component

Requirement Description

Background Knowledge

1. Semi-modal page (bindSheet)

2. Visibility vs Conditional Rendering (if)

Implementation Steps

Code Snippet / Configuration

1. Problematic Sample (Host Removed with if)

2. Corrected Sample (Host Hidden via visibility)

Complete Index.ets

Test Results

Limitations or Considerations

Related Documents or Links

Written by Bunyamin Eymen Alagoz

Differences and application scenarios of HAR, HSP, and HAP files

Solution 1 – Use `responseRegion` on the Image

Solution 1 – Expanding the Click Area with `responseRegion`

2. Visibility vs Conditional Rendering (`if`)

1. Problematic Sample (Host Removed with `if`)

2. Corrected Sample (Host Hidden via `visibility`)

Project-level `build‑profile.json5` :

Module-level `entry/build‑profile.json5` (resource configuration):