DEV Community: 刘年华

How to Call Global Dialogs from Classes in HarmonyOS

刘年华 — Fri, 27 Jun 2025 10:06:55 +0000

Introduction

I'm sure many of you have been using @CustomDialog for custom dialogs in your development, writing a bunch of initialization code on each page, and finding it particularly difficult to call from within classes. Today, I'd like to share how to use promptAction.openCustomDialog to call global dialogs from within classes in HarmonyOS.

Implementation Guide

Step 1: Store the Context in EntryAbility (Required)

onWindowStageCreate(windowStage: window.WindowStage): void {
  windowStage.loadContent('pages/Index', (err) => {
    window.getLastWindow(this.context).then((data: window.Window) => {
      let uiContext = data.getUIContext();
      AppStorage.setOrCreate<UIContext>('UIContext', uiContext);
    });
  });
}

Step 2: Create a Builder (Customize the Style)

export class Params {
  text: ResourceStr = ""

  constructor(text: ResourceStr) {
    this.text = text;
  }
}

@Builder
export function testTextBuilder(params: Params) {
  Column() {
    Text(params.text)
      .textAlign(TextAlign.Center)
      .fontSize(20)
      .borderRadius(6)
      .backgroundColor('rgba(24, 25, 26, 0.85)')
      .fontColor($r('sys.color.comp_background_list_card'))
      .padding(16)
  }
}

Step 3: Define a Global Class

export class DialogModel {
  static showDialog(message: string) {
    if (message != '') {
      let timeId: number = -1
      // Get the context
      let uiContext = AppStorage.get('UIContext') as UIContext
      let promptAction = uiContext.getPromptAction();
      let contentNode = new ComponentContent(uiContext, wrapBuilder(testTextBuilder), new Params(message));
      promptAction.openCustomDialog(contentNode, {
        isModal: false,
        onWillAppear: () => {
          timeId = setTimeout(() => {
            promptAction.closeCustomDialog(contentNode)
          }, 2000)
        },
        onDidDisappear: () => {
          clearTimeout(timeId)
        },
        keyboardAvoidMode: KeyboardAvoidMode.NONE,
        showInSubWindow: true,
      })
    }
  }
}

Step 4: Implementation

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('Click me for a dialog')
        .onClick(() => {
          DialogModel.showDialog('Here it is!')
        })
    }
  }
}

Result

Limitations

The dialog closes when navigating back (not an issue for toast notifications)
Continuous clicks will keep showing dialogs (some requirements may need to close the previous dialog when opening a new one)
You might want to exit the page stack without closing the dialog

Spacing Solution for Span Components in HarmonyOS Text

刘年华 — Fri, 27 Jun 2025 07:13:19 +0000

Spacing Solution for Span Components in HarmonyOS Text

I. Problem Analysis

In HarmonyOS development, Span child components within Text components cannot directly set margin/padding properties. Instead, text-level attributes must be used to control spacing. After thorough testing, using letterSpacing combined with special placeholders has proven to be the optimal solution.

II. Technical Solution

1. Core API

letterSpacing

Purpose: Sets the character spacing within the same Span
Unit: vp (virtual pixels)
Characteristics: Supports both positive and negative values (positive values increase spacing, negative values decrease spacing)

Demo Implementation

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text() {
        Span('Sample Text')
          .fontSize('20fp')
          .textBackgroundStyle({color: Color.Green, radius: "5vp"})
          .fontColor(Color.White)
        // Spacing control using letterSpacing
        Span(' ').letterSpacing(10)
        Span('Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua')
          .fontSize('20fp')
      }.maxLines(2).textOverflow({ overflow: TextOverflow.Ellipsis }).width('80%')
    }.width('100%').alignItems(HorizontalAlign.Center)
  }
}

2. Implementation Principle

The spacing between Spans is controlled by inserting a space character Span or using \u200B (zero-width space) instead of a regular space, and then applying letterSpacing to it:

As you can see in the key code above, I've added an empty Span with letterSpacing where spacing is needed. This effectively creates the desired spacing between Spans.

3. Key Benefits

Simple implementation: Requires minimal code changes
Precise control: Allows fine-tuning of spacing with exact pixel values
Cross-device consistency: Works reliably across different screen sizes and densities
Performance efficient: Minimal impact on rendering performance

4. Usage Recommendations

For small spacing adjustments (1-5vp), use regular space characters
For larger gaps (>5vp), the letterSpacing approach is more reliable
When working with mixed text styles, place the spacing Span between different styled content
Test on multiple device sizes to ensure consistent appearance

III. Conclusion

This solution provides a reliable workaround for the limitation of Span components in HarmonyOS Text. By leveraging the letterSpacing property with empty space characters, developers can achieve precise control over spacing between text segments without compromising performance or compatibility.

HarmonyOS Best Practices: Dynamic Component Creation

刘年华 — Thu, 26 Jun 2025 08:55:25 +0000

HarmonyOS Best Practices: Dynamic Component Creation

Introduction

Hello everyone! I'm Jun Moxiao from the Qinglan Zhuma organization. Today, I'll share an analysis of dynamic component creation in HarmonyOS.

What Problem Does Dynamic Component Creation Solve?

It addresses the issue of slow component loading by accelerating component rendering and creation.

What's the Principle Behind It?

According to the official documentation, the ArkUI framework's dynamic UI operations support component pre-creation. This allows developers to create components outside the build lifecycle. Once created, these components can undergo property setting and layout calculations. When used during page loading, this significantly improves page response speed.

As shown in the diagram below, the component pre-creation mechanism utilizes idle time during animation execution to pre-create components and set properties. After the animation ends, properties and layouts are updated, saving component creation time and accelerating page rendering.

Dynamic Component Creation Uses FrameNode Custom Nodes

What performance advantages do FrameNode custom nodes offer?

Reduced Custom Component Creation Overhead: In declarative development paradigms, using ArkUI custom components to define each node in the node tree often leads to inefficient node creation. This is primarily because each node requires memory allocation in the ArkTS engine to store custom components and state variables. During node creation, operations like component ID, component closure, and state variable dependency collection must be performed. In contrast, using ArkUI's FrameNode avoids creating custom component objects and state variable objects, eliminating the need for dependency collection, thus significantly improving component creation speed.
Faster Component Updates: In dynamic layout framework update scenarios, there's typically a UI component tree (TreeA) created from a tree-structured data model (ViewModelA). When updating TreeA with a new data structure (ViewModelB), although declarative development paradigms can achieve data-driven automatic updates, this process involves numerous diff operations, as shown below. For the ArkTS engine, executing diff algorithms on a complex component tree (depth exceeding 30 layers, containing 100-200 components) makes it nearly impossible to maintain full frame rates at 120Hz. However, using ArkUI's FrameNode extension, the framework can independently control the update process, achieving efficient pruning as needed. This is particularly beneficial for dynamic layout frameworks serving specific business needs, enabling rapid update operations.

Direct Component Tree Manipulation: Declarative development paradigms also face challenges in updating component tree structures. For example, moving a subtree from one child node to another cannot be done by directly adjusting component instance structural relationships—it requires re-rendering the entire component tree. With ArkUI's FrameNode extension, you can easily manipulate the subtree by operating on FrameNode and transplant it to another node, resulting in only local rendering refreshes and better performance.

Implementation Steps

1. Create Custom Nodes

// Parameter type
class Params {
  text: string
  img: ResourceStr

  constructor(text: string, img: ResourceStr) {
    this.text = text;
    this.img = img;
  }
}
// UI component
@Builder
function buildText(params: Params) {
  Column() {
    Text(params.text)
      .fontSize(20)
    Image(params.img)
      .width(30)
  }
}

2. Implement NodeController Class

class TextNodeController extends NodeController {
  private textNode: BuilderNode<[Params]> | null = null;

  constructor() {
    super();
  }

  makeNode(context: UIContext): FrameNode | null {
    this.textNode = new BuilderNode(context);
    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params('Hello', $r('app.media.startIcon')));
    return this.textNode.getFrameNode();
  }
}

Note: Use the BuilderNode's build method to construct the component tree. The build() method requires two parameters: the first is the global @builder method wrapped by wrapBuilder(), and the second is the parameter object required by the @builder method. If the @builder method has no parameters or has default parameters, the second parameter of build() can be omitted.

3. Display Custom Nodes

@Entry
@Component
struct Index {
  textNodeController: TextNodeController = new TextNodeController()

  build() {
    Column() {
      NodeContainer(this.textNodeController)
    }
  }
}

Result:

4. Dynamically Remove Components

NodeContainer nodes can be removed or displayed using conditional control statements:

Column() {
  if (this.isShow) {
    NodeContainer(this.textNodeController)
  }
  Button('Click me')
    .onClick(() => {
      this.isShow = !this.isShow
    })
}

5. Dynamically Update Components

replaceBuilderNode(newNode: BuilderNode<Object[]>) {
  this.textNode = newNode;
  this.rebuild();
}

@Entry
@Component
struct Index {
  textNodeController: TextNodeController = new TextNodeController()
  @State isShow: boolean = true

  buildNewNode(): BuilderNode<[Params]> {
    let uiContext: UIContext = this.getUIContext();
    let textNode = new BuilderNode<[Params]>(uiContext);
    textNode.build(wrapBuilder<[Params]>(buildText), new Params('Create new node', $r('app.media.app_background')))
    return textNode;
  }

  build() {
    Column() {
      NodeContainer(this.textNodeController)
      Button('Click me')
        .onClick(() => {
          this.textNodeController.replaceBuilderNode(this.buildNewNode());
        })
    }
  }
}

Note: After clicking, the image will flicker because the node is deleted and then added again. If you use update() to update the custom node, the image flickering won't occur.

Demo:

update() {
  if (this.textNode !== null) {
    this.textNode.update(new Params('Update', $r('app.media.background')));
  }
}

@Entry
@Component
struct Index {
  textNodeController: TextNodeController = new TextNodeController()
  @State isShow: boolean = true

  buildNewNode(): BuilderNode<[Params]> {
    let uiContext: UIContext = this.getUIContext();
    let textNode = new BuilderNode<[Params]>(uiContext);
    textNode.build(wrapBuilder<[Params]>(buildText), new Params('Create new node', $r('app.media.app_background')))
    return textNode;
  }

  build() {
    Column() {
      NodeContainer(this.textNodeController)
      Button('Click to create new node')
        .onClick(() => {
          this.textNodeController.replaceBuilderNode(this.buildNewNode());
        })
      Button('Click to update node')
        .onClick(() => {
          this.textNodeController.update()
        })
    }
  }
}

From Zero to One: A Complete Guide to Implementing WeChat Sharing in HarmonyOS

刘年华 — Wed, 25 Jun 2025 08:21:31 +0000

From Zero to One: A Complete Guide to Implementing WeChat Sharing in HarmonyOS

Introduction

Hello everyone, I'm Jun Moxiao from the Qinglan Code Organization.

As the HarmonyOS ecosystem continues to flourish, various WeChat functionalities can now be integrated. Today, I'll teach you how to implement all WeChat sharing features, primarily including WeChat mini-program sharing and WeChat H5 sharing. This guide will focus on the key code components, and you'll need to combine them into a utility class on your own.

First, Integrate the WeChat SDK

Simply enter ohpm i @tencent/wechat_open_sdk in the terminal to include the WeChat SDK dependency.

Create a HarmonyOS Application on the WeChat Platform (Skip if Already Created)

Using the WeChat SDK requires creating a HarmonyOS application on the WeChat development platform. You can check the link for the creation process, which won't be covered in this tutorial.

Preparation for WeChat Sharing Implementation

Add the following fields to module.json5:

Create a WX Instance (The Earlier the Better)

// WXApi is the openApi interface for communication between third-party apps and WeChat. Its instance is obtained through WXAPIFactory and requires the AppID that the application has applied for
export const WXApi = wxOpenSdk.WXAPIFactory.createWXAPI(APP_ID)

Note:

The appID is the same as the Android application's appID on the WeChat platform. You can reuse it directly after creating a HarmonyOS application.

Now Let's Implement the WeChat Sharing Utility Class (Building the Foundation, Combine the Complete Utility Class on Your Own)

/**
 * WeChat Sharing
 */
export class WxShareViewModel {
  // Replace with your actual appID
  WXApi = wxOpenSdk.WXAPIFactory.createWXAPI('')
  static instance: WxShareViewModel | null = null
  isWXApp: boolean = this.WXApi.isWXAppInstalled()

  private constructor() {

  }

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

Note:

I recommend implementing utility classes as singletons, which is more concise and prevents encapsulation from being contaminated.

Implement Text Sharing

/**
 * Share text
 * @param text Text content
 */
textShare(text: string) {
  this.isWXAPPCallback(() => {
    let textObject = new wxOpenSdk.WXTextObject
    textObject.text = text
    let mediaMessage = new wxOpenSdk.WXMediaMessage()
    mediaMessage.mediaObject = textObject
    let req = new wxOpenSdk.SendMessageToWXReq()
    req.scene = wxOpenSdk.SendMessageToWXReq.WXSceneSession
    req.message = mediaMessage
    this.WXApi.sendReq(getContext(this) as common.UIAbilityContext, req)
  })
}

Implement H5 Sharing

1. It's important to note that when sharing H5 pages or mini-programs with images, you need to download the image buffer and compress it to below 64KB for sharing, otherwise it will result in errors with no response.

2. Let's first implement buffer compression to below 64KB

I highly recommend the compression algorithm from the Huawei official website

Note:

I won't demonstrate other compression methods here, only buffer format compression, since downloaded images are returned as buffers. We can directly compress the buffer to below 64KB and pass it to the SDK without further expansion.
I've modified Huawei's official example to make it directly usable for compressing buffer formats.

import { image } from '@kit.ImageKit';

/**
 * Image compression and saving
 * @param sourcePixelMap: Original PixelMap object of the image to be compressed
 * @param maxCompressedImageSize: Specified target size for image compression, in KB
 * @returns compressedImageInfo: Returns the final compressed image information
 */
export async function compressedImage(sourcePixelMap: image.PixelMap,
  maxCompressedImageSize: number): Promise<ArrayBuffer> {
  // Create ImagePacker object for image encoding
  const imagePackerApi = image.createImagePacker();
  const IMAGE_QUALITY = 0;
  const packOpts: image.PackingOption = { format: "image/jpeg", quality: IMAGE_QUALITY };
  // Encode through PixelMap. compressedImageData is the image file stream obtained from packing.
  let compressedImageData: ArrayBuffer = await imagePackerApi.packing(sourcePixelMap, packOpts);
  // Target compressed image byte length
  const maxCompressedImageByte = maxCompressedImageSize * 1024;
  // Image compression. First determine if the minimum byte size that can be compressed by packing with quality parameter set to 0 meets the specified image compression size. If it does, use packing to binary search for the quality closest to the specified image compression target size. If not, use scale to first resize the image, using a while loop to decrease the scale by 0.4 times each iteration, then use packing (with quality parameter set to 0) to get the compressed image size, ultimately finding the scaling factor closest to the specified image compression target size.
  if (maxCompressedImageByte > compressedImageData.byteLength) {
    // Use binary packing compression to get the image file stream
    compressedImageData =
      await packingImage(compressedImageData, sourcePixelMap, IMAGE_QUALITY, maxCompressedImageByte);
  } else {
    // Use scale to first resize the image, using a while loop to decrease the scale by 0.4 times each iteration, then use packing (with quality parameter set to 0) to get the compressed image size
    let imageScale = 1;
    const REDUCE_SCALE = 0.4;
    // Check if the compressed image size is greater than the specified target size; if so, continue reducing the scale factor.
    while (compressedImageData.byteLength > maxCompressedImageByte) {
      if (imageScale > 0) {
        // Performance note: Since scale directly modifies the image PixelMap data, binary search for scale factor is not suitable. Here we use a loop to decrease by 0.4 times each iteration to determine the most suitable scale factor. If image compression quality requirements are not high, consider increasing the reduceScale value to reduce loops and improve scale compression performance.
        imageScale = imageScale - REDUCE_SCALE;
        await sourcePixelMap.scale(imageScale, imageScale);
        compressedImageData = await packing(sourcePixelMap, IMAGE_QUALITY);
      } else {
        // When imageScale is less than or equal to 0, it has no meaning, so end compression. We don't consider cases where the image scale factor is less than reduceScale.
        break;
      }
    }
  }
  return compressedImageData;
}


/**
 * Packing compression
 * @param sourcePixelMap: Original PixelMap of the image to be compressed
 * @param imageQuality: Image quality parameter
 * @returns data: Returns the compressed image data
 */
async function packing(sourcePixelMap: image.PixelMap, imageQuality: number): Promise<ArrayBuffer> {
  const imagePackerApi = image.createImagePacker();
  const packOpts: image.PackingOption = { format: "image/jpeg", quality: imageQuality };
  const data: ArrayBuffer = await imagePackerApi.packing(sourcePixelMap, packOpts);
  return data;
}

/**
 * Binary packing compression method
 * @param compressedImageData: ArrayBuffer of the compressed image
 * @param sourcePixelMap: Original PixelMap of the image to be compressed
 * @param imageQuality: Image quality parameter
 * @param maxCompressedImageByte: Target compressed image byte length
 * @returns compressedImageData: Returns the image data compressed by binary packing
 */
async function packingImage(compressedImageData: ArrayBuffer, sourcePixelMap: image.PixelMap, imageQuality: number,
  maxCompressedImageByte: number): Promise<ArrayBuffer> {
  // Image quality parameter range is 0-100, here we create an array for binary packing image quality parameters with 10 as the minimum binary unit.
  const packingArray: number[] = [];
  const DICHOTOMY_ACCURACY = 10;
  // Performance note: If image compression quality requirements are not high, consider increasing the minimum binary unit dichotomyAccuracy to reduce loops and improve packing compression performance.
  for (let i = 0; i <= 100; i += DICHOTOMY_ACCURACY) {
    packingArray.push(i);
  }
  let left = 0;
  let right = packingArray.length - 1;
  // Binary compression of the image
  while (left <= right) {
    const mid = Math.floor((left + right) / 2);
    imageQuality = packingArray[mid];
    // Perform packing compression based on the input image quality parameter, returning the compressed image file stream data.
    compressedImageData = await packing(sourcePixelMap, imageQuality);
    // Find a compression size as close as possible to but not exceeding the target
    if (compressedImageData.byteLength <= maxCompressedImageByte) {
      left = mid + 1;
      if (mid === packingArray.length - 1) {
        break;
      }
      // Get the image file stream data compressed with the next binary image quality parameter (mid+1)
      compressedImageData = await packing(sourcePixelMap, packingArray[mid + 1]);
      // Check if the image size compressed with the next image quality parameter (mid+1) is greater than the specified target size. If so, it means the current image quality parameter (mid) produces an image size closest to the target. Use the current mid parameter to get the final target compressed image data.
      if (compressedImageData.byteLength > maxCompressedImageByte) {
        compressedImageData = await packing(sourcePixelMap, packingArray[mid]);
        break;
      }
    } else {
      // The target value is not in the right half of the current range, move the right boundary of the search range to the left to narrow the search range and continue searching the left half in the next iteration.
      right = mid - 1;
    }
  }
  return compressedImageData;
}

3. Implement Image Download

export function loadImageUrl(url: string, successCallBack: (ImgArrayBuffer: ArrayBuffer) => void) {
  http.createHttp()
    .request(url,
      {
        method: http.RequestMethod.GET,
      },
      async (error: BusinessError, data: http.HttpResponse) => {
        if (http.ResponseCode.OK === data.responseCode) {
          let imageBuffer: ArrayBuffer = data.result as ArrayBuffer;
          const imageSource = image.createImageSource(imageBuffer)
          imageSource.createPixelMap()
            .then((pixelMap: image.PixelMap) => {
              compressedImage(pixelMap, 64)
                .then((arrayBuffer) => {
                  successCallBack(arrayBuffer)
                })
            })
        }
      })
}

Note:

Download images using createHttp, with the url parameter being the actual network address
The second parameter, successCallBack, is the success callback function that processes the compressed arrayBuffer after a successful network request
Since Huawei's official example cannot directly compress arrayBuffer and requires pixelMap format, we need to convert arrayBuffer to pixelMap format

4. Implement WeChat Installation Check Callback Function

isWXAPPCallback(callback: Function) {
  if (!this.isWXApp) {
    AlertDialog.show({ message: JSON.stringify("Please install WeChat first") })
  } else {
    callback()
  }
}

5. Core Preparation Work is Complete, Now Let's Implement H5 Sharing

/**
 * Share H5
 * @param Url Web page address
 * @param title Title
 * @param description Description
 * @param imgUrl Image network address
 */
h5Share(Url: string, title: string, description: string, imgUrl: string) {
  this.isWXAPPCallback(async () => {
    const webpageObject = new wxOpenSdk.WXWebpageObject()
    webpageObject.webpageUrl = Url
    const mediaMessage = new wxOpenSdk.WXMediaMessage()
    mediaMessage.mediaObject = webpageObject
    mediaMessage.title = title
    mediaMessage.description = description
    loadImageUrl(imgUrl, async (buffer) => {
      mediaMessage.thumbData = new Uint8Array(buffer)
      const req = new wxOpenSdk.SendMessageToWXReq()
      req.scene = wxOpenSdk.SendMessageToWXReq.WXSceneSession
      req.message = mediaMessage
      this.WXApi.sendReq(getContext(this) as common.UIAbilityContext, req)
    })
  })
}

Note:

Wrap with the WeChat installation check callback function before executing the core code
Finally, use the image buffer download function, pass in the function after successful callback, and pass the compressed buffer to the SDK for sharing

Implement WeChat Mini-Program Sharing

/**
 * Share mini-program
 * @param userName Original ID of the mini-program (in gh_xxxx format)
 * @param path Path of the mini-program
 * @param miniprogramType Type of mini-program, default is release version
 * @param title Title
 * @param description Description
 * @param imgUrl Network image address
 */
miniProgramShare(userName: string, path: string, miniprogramType: number, title: string, description: string,
  imgUrl: string) {
  this.isWXAPPCallback(async () => {
    const miniProgramObject = new wxOpenSdk.WXMiniProgramObject()
    miniProgramObject.userName = userName
    miniProgramObject.path = path
    miniProgramObject.miniprogramType = miniprogramType
    const mediaMessage = new wxOpenSdk.WXMediaMessage()
    mediaMessage.mediaObject = miniProgramObject
    mediaMessage.title = title
    mediaMessage.description = description
    loadImageUrl(imgUrl, async (buffer) => {
      mediaMessage.thumbData = new Uint8Array(buffer)
      const req = new wxOpenSdk.SendMessageToWXReq()
      req.scene = wxOpenSdk.SendMessageToWXReq.WXSceneSession
      req.message = mediaMessage
      this.WXApi.sendReq(getContext(this) as common.UIAbilityContext, req)
    })
  })
}

Note:

The image compression function works the same as for H5 sharing
Most parameters are provided by the API