DEV Community: lovehmos

HarmonyOS Utility Functions: Dev Cheatsheet & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:56:12 +0000

HarmonyOS Utility Functions: Dev Cheatsheet & Pitfalls

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) represents a revolutionary step in the evolution of Huawei's distributed operating system. As someone who has been following its development closely, I can attest to the remarkable improvements in this version. The system's microkernel architecture not only enhances security but also provides unprecedented flexibility in cross-device collaboration. What excites me most about HarmonyOS 5 is its focus on developer experience - the new ArkTS language, enhanced UI components, and improved debugging tools have made development much more efficient. The distributed capabilities allow us to create truly seamless experiences across different devices, from smartphones to tablets, smart TVs, and IoT devices.

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about utility functions and performance optimization, which led me to explore the util package in depth. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

Preface

Recently, while working on HarmonyOS development, I found the util package quite useful, containing many practical functions. Today, I'll share some of the most commonly used ones, hoping it helps everyone.

Development Environment

DevEco Studio 4.0
HarmonyOS SDK API 14 (HarmonyOS 5.0)
Test Device: Huawei Mate 60 Pro

Common Utility Functions

1. Import Package

import { util } from '@kit.ArkTS';

2. String Processing

// String formatting, most commonly used
let name = 'Zhang San';
let age = 25;
let str = util.format('My name is %s, I am %d years old', name, age);
console.info(str);  // Output: My name is Zhang San, I am 25 years old

// Object to string, frequently used in debugging
const person = {
  name: 'Zhang San',
  age: 25,
  address: {
    city: 'Beijing',
    country: 'China'
  }
};
console.info(util.format('Personal Info: %j', person));
// Output: Personal Info: {"name":"Zhang San","age":25,"address":{"city":"Beijing","country":"China"}}

// Number formatting, convenient for decimal handling
const pi = 3.141592653;
console.info(util.format('Value of π: %f', pi));  // Output: Value of π: 3.141592653

3. Error Handling

// Get error message, essential for debugging
let errnum = -1;
let result = util.errnoToString(errnum);
console.info("Error message: " + result);  // Output: Error message: operation not permitted

// Common error codes, recommended to bookmark
const errorCodes = {
  '-1': 'operation not permitted',
  '-2': 'no such file or directory',
  '-3': 'no such process',
  '-4': 'interrupted system call',
  '-5': 'i/o error',
  '-11': 'resource temporarily unavailable',
  '-12': 'not enough memory',
  '-13': 'permission denied',
  '-100': 'network is down'
};

4. Asynchronous Processing

// Callback to Promise, essential for legacy code refactoring
async function fetchData() {
  return 'hello world';
}

let cb = util.callbackWrapper(fetchData);
cb((err: Object, ret: string) => {
  if (err) throw new Error;
  console.info(ret);  // Output: hello world
});

// Promisify, makes coding more enjoyable
const addCall = util.promisify(util.callbackWrapper(fetchData));
(async () => {
  try {
    let res: string = await addCall();
    console.info(res);  // Output: hello world
  } catch (err) {
    console.info(err);
  }
})();

5. UUID Generation

// Generate UUID, used for unique identification
let uuid = util.generateRandomUUID(true);
console.info("UUID: " + uuid);  // Output similar to: 84bdf796-66cc-4655-9b89-d6218d100f9c

// Binary UUID, used in special scenarios
let binaryUuid = util.generateRandomBinaryUUID(true);
console.info(JSON.stringify(binaryUuid));  // Output binary array

// UUID parsing, occasionally used
let parsedUuid = util.parseUUID("84bdf796-66cc-4655-9b89-d6218d100f9c");
console.info("Parsed UUID: " + parsedUuid);

6. Base64 Encoding/Decoding

// Synchronous encoding, for simple scenarios
let base64 = new util.Base64();
let array = new Uint8Array([115, 49, 51]);
let encoded = base64.encodeSync(array);
console.info("Encoded result: " + encoded);  // Output: 99,122,69,122

// Synchronous encoding to string, most commonly used
let encodedStr = base64.encodeToStringSync(array);
console.info("Encoded string: " + encodedStr);  // Output: czEz

// Synchronous decoding, used with above
let decoded = base64.decodeSync(encodedStr);
console.info("Decoded result: " + decoded);  // Output: 115,49,51

// Asynchronous encoding, for large data
base64.encode(array).then((val) => {
  console.info("Async encoded result: " + val.toString());
});

// Asynchronous encoding to string, commonly used in image processing
base64.encodeToString(array).then((val) => {
  console.info("Async encoded string: " + val);
});

// Asynchronous decoding, used with above
base64.decode(encoded).then((val) => {
  console.info("Async decoded result: " + val.toString());
});

// Image to Base64, commonly used when uploading images
async function imageToBase64(imageData: Uint8Array): Promise<string> {
  try {
    return await base64.encodeToString(imageData);
  } catch (err) {
    console.error('Image to Base64 conversion failed:', err);
    return '';
  }
}

// Base64 to Image, used when downloading images
async function base64ToImage(base64Str: string): Promise<Uint8Array> {
  try {
    return await base64.decode(base64Str);
  } catch (err) {
    console.error('Base64 to Image conversion failed:', err);
    return new Uint8Array();
  }
}

7. Practical Application

Here's a simple example combining all these features:

@Entry
@Component
struct UtilExample {
  @State message: string = '';
  @State uuid: string = '';
  @State base64Result: string = '';

  aboutToAppear() {
    // String processing
    let name = 'Zhang San';
    this.message = util.format('Welcome %s to HarmonyOS application', name);

    // Generate UUID
    this.uuid = util.generateRandomUUID(true);

    // Error handling
    try {
      let errnum = -1;
      let errorMsg = util.errnoToString(errnum);
      console.info('Error message:', errorMsg);
    } catch (err) {
      console.error('Error occurred:', err);
    }

    // Base64 test
    let testData = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
    let base64 = new util.Base64();
    this.base64Result = base64.encodeToStringSync(testData);
    console.info('Base64 encoded result:', this.base64Result);
  }

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .margin({ top: 20 })

      Text('UUID: ' + this.uuid)
        .fontSize(16)
        .margin({ top: 10 })

      Text('Base64: ' + this.base64Result)
        .fontSize(16)
        .margin({ top: 10 })

      Button('Test Async')
        .onClick(async () => {
          async function testAsync() {
            return 'Test successful';
          }

          const asyncCall = util.promisify(util.callbackWrapper(testAsync));
          try {
            let result = await asyncCall();
            console.info('Async test result:', result);
          } catch (err) {
            console.error('Async test error:', err);
          }
        })

      Button('Test Base64')
        .onClick(async () => {
          let base64 = new util.Base64();
          let testData = new Uint8Array([72, 101, 108, 108, 111]);

          try {
            let encoded = await base64.encodeToString(testData);
            console.info('Async encoded result:', encoded);

            let decoded = await base64.decode(encoded);
            console.info('Async decoded result:', decoded);
          } catch (err) {
            console.error('Base64 operation failed:', err);
          }
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

Common Pitfalls

Using %s and %d incorrectly in string formatting, resulting in wrong output
Writing callback function parameters in wrong order when wrapping async functions, took hours to debug
Poor UUID generation performance due to improper cache settings
Error codes not matching actual error messages, spent hours checking documentation
Wrong input data type in Base64 encoding/decoding, causing errors
Program crashing due to unhandled exceptions in Base64 async operations

HarmonyOS Reader Kit: Hands-on Tips & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:53:04 +0000

HarmonyOS Reader Kit: Hands-on Tips & Pitfalls

About HarmonyOS 5

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about real-time communication and distributed applications, which led me to explore WebSocket implementations in HarmonyOS 5. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

So, What Can Reader Kit Actually Do?

The first time I tried to build an eBook reader, I thought it was just "read a txt and show it." Turns out, there are a million gotchas—formats, layout, page-flip effects, TOC jumps... all sorts of traps. Reader Kit honestly saved my bacon. This doc is just my "war story" for the next dev, and a reminder to myself.

What's It Good At?

Handles txt, epub, mobi, azw, azw3—title, author, cover, TOC, content, you name it.
Lays out txt and rich text (html+css), does simulation and horizontal swipe paging, and even gives you layout snapshots.
The ReadPageComponent shows content, handles page turns, animations, and tracks reading progress.

Stuff I Actually Like

Multi-format parsing—pretty much any book, any info, you can grab it.
Rich text layout is fast, supports custom fonts, W3C standard, no compatibility headaches.
Page-flip effects are smooth (thanks OpenGL), sometimes I just keep flipping for fun.

Some Terms You Can't Avoid

ReadPageComponent: The main UI for reading—shows content, handles page turns, tracks progress.
BookParser: The engine that chews through any book format.
spine: Not your back, but the book's reading order. Each SpineItem is a chunk of content.

Gotchas & Limits

Only reads local files—don't even think about cloud books (yet).
DRM-protected books? Don't bother, they won't open.
Only supports txt, epub, mobi, azw, azw3. Don't try pdf.
Layout and interaction must use ReadPageComponent—rolling your own is a pain.
Only works on real HarmonyOS NEXT 5.0.4+ devices. Emulators? Forget it.
Mainland China only for now—HK, Macau, overseas, sorry.

How Do I Get the Title and Cover?

Sometimes the product just wants to show a cover and title on the bookshelf. Reader Kit makes this easy.

Here's how I do it (don't mess up spineIndex, or you'll get a blank cover—don't ask how I know):

// This code works if you copy-paste, just mind your paths and permissions
import { bookParser } from '@kit.ReaderKit';
import { image } from '@kit.ImageKit';

let path: string = './download/ebook/abc.epub';
let bookParserHandler: bookParser.BookParserHandler = await bookParser.getDefaultHandler(path);
let bookInfo: bookParser.BookInfo = bookParserHandler.getBookInfo();
let bookTitle = bookInfo.bookTitle;
let buffer: ArrayBuffer = bookParserHandler.getResourceContent(-1, bookInfo.bookCoverImage);
let imageSource: image.ImageSource = image.createImageSource(buffer);
let bookCover: image.PixelMap = await imageSource.createPixelMap();
imageSource.release();

How Do I Handle TOC and Jumps?

TOC and chapter jumps—product always wants them. Reader Kit's TOC parsing and jumping is pretty smooth.

Here's how I do it (don't mess up catalogLevel or your TOC will look like stairs):

// TOC rendering and jumping—copy this, but tweak the indentation
import { bookParser } from '@kit.ReaderKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@State catalogItemList: bookParser.CatalogItem[] = [];
private defaultHandler: bookParser.BookParserHandler | null = null;

private async getCatalogItemList(){
  let path: string = './download/ebook/abc.epub';
  this.defaultHandler = await bookParser.getDefaultHandler(path);
  this.catalogItemList = this.defaultHandler.getCatalogList() || [];
}

// Render TOC
build() {
  Column() {
    List() {
      ForEach(this.catalogItemList, (item: bookParser.CatalogItem) => {
        ListItem() {
          // ...chapter name, click to jump, etc...
        }
      })
    }
  }
}

Jumping to a chapter:

private async jumpToCatalogItem(catalogItem: bookParser.CatalogItem){
  const domPos = await this.getDomPos(catalogItem);
  const resourceIndex = this.getResourceItemByCatalog(catalogItem).index;
  // Use domPos and resourceIndex to jump
}

private async getDomPos(catalogItem: bookParser.CatalogItem): Promise<string> {
  const domPos: string = this.defaultHandler?.getDomPosByCatalogHref(catalogItem.href || '') || '';
  return domPos;
}

private getResourceItemByCatalog(catalogItem: bookParser.CatalogItem): bookParser.SpineItem {
  let resourceFile = catalogItem.resourceFile || '';
  let spineList: bookParser.SpineItem[] = this.defaultHandler?.getSpineList() || [];
  let resourceItemArr = spineList.filter(item => item.href === resourceFile);
  if (resourceItemArr.length > 0) {
    hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource ', resourceItemArr[0]);
    return resourceItemArr[0];
  }  else if (spineList.length > 0) {
    hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource in resourceList', spineList[0]);
    return spineList[0];
  } else {
    hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource in escape');
    return {
      idRef: '',
      index: 0,
      href: '',
      properties: ''
    };
  }
}

How Do I Build the Reader?

ReadPageComponent is the "soul" of the reader—page turns, progress, interaction, all on it.

First time I built a reader, I hid the loading before the page finished rendering—users got a black screen. Don't be me, add a loading state!

Here's how I do it:

// Just copy this, but swap in your own paths and params
import { bookParser, ReadPageComponent, readerCore } from '@kit.ReaderKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { display } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';

private readerComponentController: readerCore.ReaderComponentController = new readerCore.ReaderComponentController();
private readerSetting: readerCore.ReaderSetting = {
  fontName: 'System Font',
  fontPath: '',
  fontSize: 18,
  fontColor: '#000000',
  fontWeight: 400,
  lineHeight: 1.9,
  nightMode: false,
  themeColor: 'rgba(248, 249, 250, 1)',
  themeBgImg: '',
  flipMode: '0',
  scaledDensity: display.getDefaultDisplaySync().scaledDensity > 0 ? display.getDefaultDisplaySync().scaledDensity : 1,
  viewPortWidth: 370,
  viewPortHeight: 800,
};
private bookParserHandler: bookParser.BookParserHandler | null = null;
@State isLoading: boolean = true;

// Build the reading component
build() {
  Stack() {
    ReadPageComponent({
      controller: this.readerComponentController,
      readerCallback: (err: BusinessError, data: readerCore.ReaderComponentController) => {
        this.readerComponentController = data;
      }
    })

    Row() {
      Text('Loading...')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor(Color.White)
    .visibility(this.isLoading ? Visibility.Visible : Visibility.None)
  }.width('100%').height('100%')
}

// Open the book at a specific spot
aboutToAppear(): void {
  let filePath: string = 'xxx/download/ebook/abc.epub';
  let spineIndex: number = 0;
  let domPos: string = '';
  this.registerListener();
  this.startPlay(filePath, spineIndex, domPos);
}

private registerListener(): void {
  this.readerComponentController.on('pageShow', (data: readerCore.PageDataInfo): void => {
    hilog.error(0x0000, 'testTag', 'pageshow: data is: ' + JSON.stringify(data));
    if (data.state === readerCore.PageState.PAGE_ON_SHOW) {
      this.isLoading = false;
    }
  });
}

private async startPlay(filePath: string, spineIndex: number, domPos: string) {
  try {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    let initPromise = this.readerComponentController.init(context);
    let bookParserHandler = bookParser.getDefaultHandler(filePath);
    let result: [bookParser.BookParserHandler, void] = await Promise.all([bookParserHandler, initPromise]);
    this.bookParserHandler = result[0];
    this.readerComponentController.setPageConfig(this.readerSetting);
    this.readerComponentController.registerBookParser(this.bookParserHandler);
    this.readerComponentController.startPlay(spineIndex || 0, domPos);
  } catch (err) {
    hilog.error(0x0000, 'testTag', 'startPlay: err: ' + JSON.stringify(err));
  }
}

aboutToDisappear(): void {
  this.readerComponentController.off('pageShow');
  this.readerComponentController.releaseBook();
}

Want Custom Fonts? Here's How

Sometimes the product says, "Can we use a different font?" and you have to support custom fonts. You can put font files in resources/rawfile/fonts or the sandbox path—just don't forget to register the resourceRequest callback, or the font won't load.

Here's how I do it:

// Swap fonts—don't mess up the path, and don't forget the callback
import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let filePath: string = 'fonts/SourceHanSerifCN-VF.ttf';
// let filePath: string = this.getUIContext().getHostContext()!.filesDir + 'fonts/SourceHanSerifCN-VF.ttf';

this.readerSetting.fontName = 'Source Han Serif';
this.readerSetting.fontPath = filePath;
this.readerComponentController.setPageConfig(this.readerSetting);

aboutToAppear(): void {
  this.readerComponentController.on('resourceRequest', this.resourceRequest);
}

aboutToDisappear(): void {
  this.readerComponentController.off('resourceRequest');
}

private isFont(filePath: string): boolean {
  let options = [".ttf", ".woff2", ".otf"];
  let path = filePath.toLowerCase();
  return options.some(ext => path.indexOf(ext) !== -1);
}

private resourceRequest: bookParser.CallbackRes<string, ArrayBuffer> = (filePath: string): ArrayBuffer => {
  if(filePath.length === 0){
    return new ArrayBuffer(0);
  }
  let resourcePath = filePath;
  if(this.isFont(filePath)){
    resourcePath = 'fonts/' + resourcePath;
  }
  try {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    let value: Uint8Array = context.resourceManager.getRawFileContentSync(resourcePath);
    return value.buffer as ArrayBuffer;
  } catch (error) {
    return this.loadFileFromPath(resourcePath);
  }
}

private loadFileFromPath(filePath: string): ArrayBuffer {
  try {
    let stats = fs.statSync(filePath);
    let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
    let buffer = new ArrayBuffer(stats.size);
    fs.readSync(file.fd, buffer);
    fs.closeSync(file);
    return buffer;
  } catch (err) {
    return new ArrayBuffer(0);
  }
}

Custom Backgrounds? Go Wild

Want your reader to look unique? You can set custom background colors and images. If you use a light background, turn off night mode and make sure your font color matches—white on white is a classic rookie mistake.

Here's how I do it:

// Change backgrounds—play with images and colors, but don't forget to match the font color
import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

this.readerSetting.themeColor = '#FFFFFF';
this.readerSetting.themeBgImg = '';
this.readerSetting.nightMode = false;
this.readerSetting.fontColor = '#000000';

this.readerSetting.themeBgImg = 'white_sky_first.jpg';
this.readerSetting.themeColor = '#FFFFFF';
this.readerSetting.nightMode = false;
this.readerSetting.fontColor = '#000000';
this.readerComponentController.setPageConfig(this.readerSetting);

aboutToAppear(): void {
  this.readerComponentController.on('resourceRequest', this.resourceRequest);
}

aboutToDisappear(): void {
  this.readerComponentController.off('resourceRequest');
}

private resourceRequest: bookParser.CallbackRes<string, ArrayBuffer> = (filePath: string): ArrayBuffer => {
  if(filePath.length === 0){
    return new ArrayBuffer(0);
  }
  try {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    let value: Uint8Array = context.resourceManager.getRawFileContentSync(filePath);
    return value.buffer as ArrayBuffer;
  } catch (error) {
    return this.loadFileFromPath(filePath);
  }
}

private loadFileFromPath(filePath: string): ArrayBuffer {
  try {
    let stats = fs.statSync(filePath);
    let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
    let buffer = new ArrayBuffer(stats.size);
    fs.readSync(file.fd, buffer);
    fs.closeSync(file);
    return buffer;
  } catch (err) {
    return new ArrayBuffer(0);
  }
}

Don't Forget Dark/Light Mode

Everyone loves switching between dark and light mode these days. Reader Kit can adapt dynamically. Listen for colorMode changes, and when you switch themes, update both the font and background colors.

Here's how I do it:

// Theme switching—don't forget to update both font and background colors
import { Configuration, UIAbility } from '@kit.AbilityKit';
import { ConfigurationConstant } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onConfigurationUpdate(newConfig: Configuration): void {
    AppStorage.setOrCreate('colorMode', newConfig.colorMode);
  }
}

@StorageLink('colorMode') @Watch('colorModeChange') colorMode: ConfigurationConstant.ColorMode =
  ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET;

colorModeChange() {
  if (this.colorMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {
    this.readerSetting.nightMode = true;
    this.readerSetting.fontColor = '#ffffff';
    this.readerSetting.themeColor = '#202224';
  } else {
    this.readerSetting.nightMode = false;
    this.readerSetting.fontColor = '#000000';
    this.readerSetting.themeColor = '#FFFFFF';
  }
  this.readerComponentController.setPageConfig(this.readerSetting);
}

Pitfalls & Tips

Only reads local books—don't expect to load from the cloud.
DRM-protected books? Don't bother, they won't open.
Only supports those formats—don't try pdf.
Layout and interaction must use ReadPageComponent—don't try to reinvent the wheel.
Only works on real devices—don't waste time on emulators.
Mainland China only for now.
If you hit a wall, don't panic—try the code, break things, and you'll figure it out. Got a cooler trick? Drop a comment!

Official Docs & Community (Worth a Look)

HarmonyOS PDF Kit: Dev Survival Guide & Gotchas

lovehmos — Mon, 30 Jun 2025 09:48:44 +0000

HarmonyOS PDF Kit: Dev Survival Guide & Gotchas

About HarmonyOS 5

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about real-time communication and distributed applications, which led me to explore WebSocket implementations in HarmonyOS 5. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

Why This Note Exists

PDFs are everywhere in dev work. My first time dealing with PDF features was when a colleague asked me to help with a contract preview. I was totally lost and hit a bunch of snags. But after using HarmonyOS PDF Kit for a while, I found it pretty handy—editing, previewing, adding annotations, you name it. Most dev needs are covered.

This note is meant as a "pitfall guide" for those who come after me, and a record of the little traps and lessons I picked up. If you use PDF Kit, I hope you'll take fewer detours and have a bit more fun.

What's This Kit Anyway?

HarmonyOS PDF Kit gives you a bunch of PDF document handling features, with two main modules: pdfService and PdfView.

pdfService: For loading, saving, and editing PDFs—add text, images, annotations, headers/footers, watermarks, backgrounds, bookmarks, encryption/decryption, and more.
PdfView: For previewing PDFs, page navigation, zooming, keyword search, highlighting, annotations, etc.

Sometimes, all it takes is a product manager saying, "Can we add PDF annotations?" and you have to dig through the API from scratch. Don't panic—these examples and stories are all from my real-world experience.

For more examples, check out the official CodeLab and SampleCode (or just poke around and see what breaks).

What Can Each Module Do? (A Not-So-Official Comparison)

Let's be honest: pdfService and PdfView each have their own superpowers. Here's my not-so-official, developer-style rundown:

Opening and saving documents? Both can do it, no sweat.
Releasing documents? Both handle it, so no memory leaks to worry about.
PDF to image? Both can, though I rarely use it.
Annotations? Both can add and remove them—whatever the product wants.
Bookmarks? pdfService can manage them, PdfView can't.
Adding/removing PDF pages, text, images, watermarks, headers/footers? pdfService does it all; PdfView just sticks to previewing.
Checking if a PDF is encrypted or decrypting? pdfService can do it, PdfView just watches.
Preview, search, event callbacks? That's PdfView's turf—pdfService doesn't get involved.

Bottom line: pdfService is the "hands-on" type—edit, add, delete, whatever. PdfView is more of a "viewer"—great for previewing, flipping pages, searching, and annotating. In real development, just use whichever feels right. Don't get stuck in the API docs—try, fail, and you'll get it.

Sometimes I wish pdfService and PdfView could merge, so I wouldn't have to switch back and forth. But for now, they each do their own thing—just roll with it.

Some Annoying Limits

Supported regions: Mainland China only (not including Hong Kong, Macau, or Taiwan).
Supported devices: Real devices only (Phone, Tablet, PC/2in1). Emulators are not supported.

Opening and Saving PDF Documents (How I Usually Do It)

For editing PDF content, use pdfService.
For preview, search, or event listening, use PdfView.

What I usually call:

loadDocument(path: string, password?: string, onProgress?: Callback<number>): ParseResult — Load a PDF.
saveDocument(path: string, onProgress?: Callback<number>): boolean — Save a PDF.

A little story:
The first time I did a "Save As" feature, I got nothing when I clicked the button. Turns out, I mixed up the sandbox and resource paths—don't try to write a PDF to a read-only directory!

Here's how I did it (and it finally worked):

import { pdfService } from '@kit.PDFKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo } from '@kit.CoreFileKit';

@Entry
@Component
struct PdfPage {
  private pdfDocument: pdfService.PdfDocument = new pdfService.PdfDocument();
  private context = this.getUIContext().getHostContext() as Context;
  private filePath = '';
  @State saveEnable: boolean = false;

  aboutToAppear(): void {
    this.filePath = this.context.filesDir + '/input.pdf';
    let res = fileIo.accessSync(this.filePath);
    if(!res) {
      // Make sure input.pdf exists in src/main/resources/rawfile
      let content: Uint8Array = this.context.resourceManager.getRawFileContentSync('rawfile/input.pdf');
      let fdSand = fileIo.openSync(this.filePath, fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
      fileIo.writeSync(fdSand.fd, content.buffer);
      fileIo.closeSync(fdSand.fd);
    }
    this.pdfDocument.loadDocument(this.filePath);
  }

  build() {
    Column() {
      // Save as a new PDF
      Button('Save As').onClick(() => {
        let outPdfPath = this.context.filesDir + '/testSaveAsPdf.pdf';
        let result = this.pdfDocument.saveDocument(outPdfPath);
        this.saveEnable = true;
        hilog.info(0x0000, 'PdfPage', 'saveAsPdf %{public}s!', result ? 'success' : 'fail');
      })
      // Overwrite original PDF
      Button('Save').enabled(this.saveEnable).onClick(() => {
        let tempDir = this.context.tempDir;
        let tempFilePath = tempDir + `/temp${Math.random()}.pdf`;
        fileIo.copyFileSync(this.filePath, tempFilePath);
        let pdfDocument: pdfService.PdfDocument = new pdfService.PdfDocument();
        let loadResult = pdfDocument.loadDocument(tempFilePath, '');
        if (loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
          let result = pdfDocument.saveDocument(this.filePath);
          hilog.info(0x0000, 'PdfPage', 'savePdf %{public}s!', result ? 'success' : 'fail');
        }
      })
    }
  }
}

Adding and Deleting PDF Pages (Yes, You'll Need This)

Supports inserting blank pages, merging pages from other PDFs, and deleting specific pages.

What I usually call:

insertBlankPage(index, width, height) — Insert a blank page.
getPage(index) — Get a page object.
insertPageFromDocument(document, fromIndex, pageCount, index) — Merge pages from another document.
deletePage(index, count) — Delete pages.

A quick anecdote:
A tester once asked, "Why are all the inserted pages at the end?" Turns out, I misunderstood the index parameter. Get the insert position right, or the user experience will be weird.

Here's a code snippet (don't copy-paste blindly, tweak as needed):

import { pdfService } from '@kit.PDFKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct PdfPage {
  private pdfDocument: pdfService.PdfDocument = new pdfService.PdfDocument();
  private context = this.getUIContext().getHostContext() as Context;

  aboutToAppear(): void {
    let filePath = this.context.filesDir + '/input.pdf';
    this.pdfDocument.loadDocument(filePath);
  }

  build() {
    Column() {
      // Insert a single blank page
      Button('insertBlankPage').onClick(async () => {
        let page = this.pdfDocument.getPage(0);
        this.pdfDocument.insertBlankPage(2, page.getWidth(), page.getHeight());
        let outPdfPath = this.context.filesDir + '/testInsertBlankPage.pdf';
        let result = this.pdfDocument.saveDocument(outPdfPath);
        hilog.info(0x0000, 'PdfPage', 'insertBlankPage %{public}s!', result ? 'success' : 'fail');
      })
      // Insert multiple blank pages
      Button('insertSomeBlankPage').onClick(async () => {
        let page = this.pdfDocument.getPage(0);
        for (let i = 0; i < 3; i++) {
          this.pdfDocument.insertBlankPage(2, page.getWidth(), page.getHeight());
        }
        let outPdfPath = this.context.filesDir + '/testInsertSomeBlankPage.pdf';
        let result = this.pdfDocument.saveDocument(outPdfPath);
        hilog.info(0x0000, 'PdfPage', 'insertSomeBlankPage %{public}s!', result ? 'success' : 'fail');
      })
      // Merge pages from another PDF
      Button('insertPageFromDocument').onClick(async () => {
        let pdfDoc = new pdfService.PdfDocument();
        pdfDoc.loadDocument(this.context.filesDir + '/input2.pdf');
        this.pdfDocument.insertPageFromDocument(pdfDoc, 1, 3, 0);
        let outPdfPath = this.context.filesDir + '/testInsertPageFromDocument.pdf';
        let result = this.pdfDocument.saveDocument(outPdfPath);
        hilog.info(0x0000, 'PdfPage', 'insertPageFromDocument %{public}s!', result ? 'success' : 'fail');
      })
      // Delete pages
      Button('deletePage').onClick(async () => {
        this.pdfDocument.deletePage(2, 2);
        let outPdfPath = this.context.filesDir + '/testDeletePage.pdf';
        let result = this.pdfDocument.saveDocument(outPdfPath);
        hilog.info(0x0000, 'PdfPage', 'deletePage %{public}s!', result ? 'success' : 'fail');
      })
    }
  }
}

Previewing PDF Documents (Don't Skip This)

Supports page navigation, zoom, single/double-page display, fit modes, scrolling, search, annotations, and more.
Make sure the PDF file is in the sandbox directory.

Dev thoughts:
When previewing PDFs, the worst is "slow loading" or "laggy page turns." I recommend using event callbacks and adding a loading animation for users—it makes a big difference.

Here's what worked for me:

import { pdfService, pdfViewManager, PdfView } from '@kit.PDFKit';
import { fileIo } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();

  aboutToAppear(): void {
    let context = this.getUIContext().getHostContext() as Context;
    let dir = context.filesDir;
    let filePath = dir + '/input.pdf';
    let res = fileIo.accessSync(filePath);
    if (!res) {
      let content = context.resourceManager.getRawFileContentSync('rawfile/input.pdf');
      let fdSand = fileIo.openSync(filePath, fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
      fileIo.writeSync(fdSand.fd, content.buffer);
      fileIo.closeSync(fdSand.fd);
    }
    (async () => {
      // Register listener before loading document
      this.controller.registerPageCountChangedListener((pageCount: number) => {
        hilog.info(0x0000, 'registerPageCountChanged-', pageCount.toString());
      });
      let loadResult1 = await this.controller.loadDocument(filePath);
    })();
  }

  build() {
    Row() {
      PdfView({
        controller: this.controller,
        pageFit: pdfService.PageFit.FIT_WIDTH,
        showScroll: true
      })
        .id('pdfview_app_view')
        .layoutWeight(1);
    }
    .width('100%')
    .height('100%')
  }
}

Advanced PdfView Usage (A Few More Tricks)

Asynchronous Opening and Saving (Promise Style)

A little story:
Once, I had a huge file and the UI just froze when saving. Later, I realized I should use Promises for async operations—don't block the main thread, and the user experience gets way better.

Here's the async way:

import { pdfService, PdfView, pdfViewManager } from '@kit.PDFKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct PdfPage {
  private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();
  private context = this.getUIContext().getHostContext() as Context;
  private loadResult: pdfService.ParseResult = pdfService.ParseResult.PARSE_ERROR_FORMAT;

  aboutToAppear(): void {
    let filePath = this.context.filesDir + '/input.pdf';
    (async () => {
      this.loadResult = await this.controller.loadDocument(filePath);
    })()
  }

  build() {
    Column() {
      Button('savePdfDocument').onClick(async () => {
        if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
          let savePath = this.context.filesDir + '/savePdfDocument.pdf';
          let result = await this.controller.saveDocument(savePath);
          hilog.info(0x0000, 'PdfPage', 'savePdfDocument %{public}s!', result ? 'success' : 'fail');
        }
      })
      PdfView({
        controller: this.controller,
        pageFit: pdfService.PageFit.FIT_WIDTH,
        showScroll: true
      })
        .id('pdfview_app_view')
        .layoutWeight(1);
    }
    .width('100%')
    .height('100%')
  }
}

Setting PDF Preview Effects (Because PMs Love Fancy Stuff)

Dev anecdote:
The product manager said, "Can we do double-page like a book?" I thought it'd be tough, but it was just one line with setPageLayout. Sometimes HarmonyOS APIs are surprisingly friendly.

Try this (and impress your PM):

import { pdfService, PdfView, pdfViewManager } from '@kit.PDFKit';

@Entry
@Component
struct PdfPage {
  private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();
  private context = this.getUIContext().getHostContext() as Context;
  private loadResult: pdfService.ParseResult = pdfService.ParseResult.PARSE_ERROR_FORMAT;

  aboutToAppear(): void {
    let filePath = this.context.filesDir + '/input.pdf';
    (async () => {
      this.loadResult = await this.controller.loadDocument(filePath);
    })()
  }

  build() {
    Column() {
      Row() {
        Button('setPreviewMode').onClick(() => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            this.controller.setPageLayout(pdfService.PageLayout.LAYOUT_SINGLE); // Single page
            this.controller.setPageContinuous(true); // Continuous scroll
            this.controller.setPageFit(pdfService.PageFit.FIT_PAGE); // Fit whole page
          }
        })
        Button('goToPage').onClick(() => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            this.controller.goToPage(10); // Jump to page 11
          }
        })
        Button('zoomPage2').onClick(() => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            this.controller.setPageZoom(2); // Zoom in 2x
          }
        })
      }
      PdfView({
        controller: this.controller,
        pageFit: pdfService.PageFit.FIT_WIDTH,
        showScroll: true
      })
        .id('pdfview_app_view')
        .layoutWeight(1);
    }
  }
}

Keyword Search and Highlighting (For the Perfectionists)

Supports searching PDF content, auto-highlighting all matches.
Jump to previous/next match, get the current highlight index, clear all highlights.

A quick story:
A user once said, "Why doesn't searching for C++ work?" Turns out, you have to watch out for case and special characters. The API isn't case-sensitive, but some symbols need escaping.

Here's how I handle it:

import { pdfService, PdfView, pdfViewManager } from '@kit.PDFKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct PdfPage {
  private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();
  private context = this.getUIContext().getHostContext() as Context;
  private loadResult: pdfService.ParseResult = pdfService.ParseResult.PARSE_ERROR_FORMAT;
  private searchIndex = 0;
  private charCount = 0;

  aboutToAppear(): void {
    let filePath = this.context.filesDir + '/input.pdf';
    (async () => {
      this.loadResult = await this.controller.loadDocument(filePath);
    })()
  }

  build() {
    Column() {
      Row() {
        Button('searchKey').onClick(async () => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            this.controller.searchKey('C++', (index: number) => {
              this.charCount = index;
              hilog.info(0x0000, 'PdfPage', 'searchKey %{public}s!', index + '');
            })
          }
        })
        Button('setSearchPrevIndex').onClick(async () => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            if(this.searchIndex > 0) {
              this.controller.setSearchIndex(--this.searchIndex);
            }
          }
        })
        Button('setSearchNextIndex').onClick(async () => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            if(this.searchIndex < this.charCount) {
              this.controller.setSearchIndex(++this.searchIndex);
            }
          }
        })
        Button('getSearchIndex').onClick(async () => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            let curSearchIndex = this.controller.getSearchIndex();
            hilog.info(0x0000, 'PdfPage', 'curSearchIndex %{public}s!', curSearchIndex + '');
          }
        })
        Button('clearSearch').onClick(async () => {
          if (this.loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
            this.controller.clearSearch();
          }
        })
      }
      PdfView({
        controller: this.controller,
        pageFit: pdfService.PageFit.FIT_WIDTH,
        showScroll: true
      })
        .id('pdfview_app_view')
        .layoutWeight(1);
    }
  }
}

Gotchas & Tips

Only supports real devices in mainland China; emulators and Hong Kong/Macau/Taiwan are not supported.
Resource files must be placed in the rawfile directory and copied to the sandbox.
For editing, use pdfService; for pure preview, use PdfView.
Be careful with file paths and permissions when saving/overwriting.
If you get stuck, don't panic—sometimes even the docs won't help, but trial and error usually does. And if you find a better way, let me know!

Where to Find More (or Get Stuck)

HarmonyOS HiLog: Real-World Logging Tips & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:47:49 +0000

HarmonyOS HiLog: Real-World Logging Tips & Pitfalls

1. Preface

Recently, while developing HarmonyOS applications, I realized that log debugging is truly indispensable in the development process. I remember when I first encountered HiLog, I thought it was just like console.log, but after going live, I found that too many logs affected performance, and I almost printed sensitive information in the production logs—got a "lesson" from the security team. Later, after digging deeper into HiLog, I discovered its log levels, privacy protection, and formatting features are very powerful. Using it well can greatly improve development and operations efficiency.

Once, an online user reported an occasional bug, and our team spent two days trying to locate it. In the end, it was HiLog's leveled logs and key process tracking that helped us pinpoint the root cause among thousands of log entries. At that moment, I truly felt: "Good logs, easy troubleshooting!"

Supported Platforms: Phone, PC, 2in1, Tablet, Wearable

API Support: Supported from API version 7, with some interfaces supporting more features from API version 11/15/20

2. Typical Use Cases

Debugging: Output detailed debug information to help locate issues during development.
Business Process Tracing: Record key business nodes to restore user actions and business flows.
Exception & Warning Monitoring: Capture and output exceptions, errors, and warnings for quick online troubleshooting.
Performance Analysis: Output performance-related data using log levels and formatting to assist optimization.
Privacy Compliance: Use privacy flags to protect sensitive information and meet compliance requirements.

3. Module Import

import { hilog } from '@kit.PerformanceAnalysisKit';

4. Main APIs and Parameter Description

4.1 Log Levels (LogLevel)

Name	Value	Description
DEBUG	3	Detailed process records for analysis and troubleshooting
INFO	4	Key business process, expected abnormal situations
WARN	5	More serious but recoverable unexpected situations
ERROR	6	Errors affecting functionality or user experience
FATAL	7	Critical fatal exceptions, app about to crash

4.2 Main APIs

hilog.isLoggable(domain: number, tag: string, level: LogLevel): boolean
- Check if logs of the specified domain, tag, and level can be printed.
hilog.debug(domain, tag, format, ...args)
hilog.info(domain, tag, format, ...args)
hilog.warn(domain, tag, format, ...args)
hilog.error(domain, tag, format, ...args)
hilog.fatal(domain, tag, format, ...args)
- Output logs at different levels.
hilog.setMinLogLevel(level: LogLevel)
- Set the minimum log level for the app.

Main Parameter Description

domain: Log domain identifier (0x0~0xFFFF), recommended to customize within the app.
tag: Log tag (suggest class/business name, max 31 bytes, avoid Chinese).
format: Format string, supports parameter types and privacy flags.
args: Parameter list corresponding to format.

Privacy Flags and Formatting

%{public}s outputs in plain text, %{private}d outputs as private (default is private, content shown as ).
Supported types: d/i (number/bigint), s (string/bool/null/undefined), o/O (object/undefined/null, API 20+).

5. Code Examples

5.1 Basic Usage

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0001;
const TAG = "Demo";

// Check if INFO level log can be printed
if (hilog.isLoggable(DOMAIN, TAG, hilog.LogLevel.INFO)) {
  hilog.info(DOMAIN, TAG, "App started at %{public}s", new Date().toISOString());
}

// Output logs at different levels
hilog.debug(DOMAIN, TAG, "Debug info: %{public}s", "debugging...");
hilog.info(DOMAIN, TAG, "User login: %{public}s", "user123");
hilog.warn(DOMAIN, TAG, "Network unstable, retry count: %{public}d", 2);
hilog.error(DOMAIN, TAG, "Request failed, code: %{public}d", 500);
hilog.fatal(DOMAIN, TAG, "App crashed, error: %{public}s", "NullPointerException");

5.2 Privacy and Formatting

// Private parameters will not be output in plain text
hilog.info(DOMAIN, TAG, "User phone: %{private}s, login at %{public}s", "138****8888", "2025-06-21 11:14");
// Object, null, undefined, boolean, bigint, etc.
let obj = { name: "Jack", age: 22 };
hilog.info(DOMAIN, TAG, "User info: %{public}o", obj);
hilog.info(DOMAIN, TAG, "Null value: %{public}s", null);
hilog.info(DOMAIN, TAG, "Boolean: %{public}s", true);
hilog.info(DOMAIN, TAG, "BigInt: %{public}d", BigInt(1234567890123456789));

5.3 Set Minimum Log Level

hilog.setMinLogLevel(hilog.LogLevel.WARN);
hilog.info(DOMAIN, TAG, "This info log will not be printed");
hilog.error(DOMAIN, TAG, "This error log will be printed");

6. Pitfalls and Developer Experience

6.1 Problems Encountered

Log Flooding
- Problem: At first, all logs were set to info, resulting in too many logs and key logs being buried.
- Solution: Use log levels properly—info for important processes, debug for details, error/warn for exceptions.
Sensitive Information Leakage
- Problem: Once, I printed a user's phone number directly in the logs and got reminded by the security team.
- Solution: Always use %{private} for sensitive content and regularly review log content.
Performance Impact
- Problem: Frequent logging in loops caused UI lag.
- Solution: Only keep necessary logs in high-frequency scenarios, avoid debug logs in production.
Log Loss
- Problem: Setting the minimum log level too high caused key logs to be missed, making troubleshooting difficult.
- Solution: Set the minimum level to debug during development, adjust as needed for production.

6.2 Optimization Suggestions

Domain-based Log Management
- Properly divide domain and tag for easier log search and issue location later.
Concise Log Content
- Keep log content concise, avoid useless information.
Privacy Compliance
- Always use private flag for user data and sensitive info to prevent leaks.
Log Cleanup and Archiving
- Regularly clean up useless logs, archive important ones.

7. Summary

If you use HiLog well, both development efficiency and online operations experience can be greatly improved. My suggestions:

Develop good habits for log levels and privacy protection
Always log key processes, exceptions, and performance nodes
Make your logs "warm"—help yourself troubleshoot and make team collaboration smoother

Once, we had an urgent production release, and thanks to the key logs we had set up earlier, we located and fixed an online bug in half an hour. The team all said: "Good logs, no ops worries!"

8. FAQ

Logs not output: Check if domain/tag/level are correct, or if setMinLogLevel is too high.
Chinese garbled/misalignment: Avoid using Chinese characters in tag.
Private parameters not shown in plain text: Default is private, use %{public} for plain output.
Too many logs affect performance: Only output high-frequency logs when necessary.

9. Reference

HarmonyOS Official HiLog API Documentation

Author: Tilling in the World
Email: 1743914721@qq.com
Copyright: This article is original by a CSDN blogger. Please include the original link and this statement when reprinting.

HarmonyOS Webview (ArkWeb) Hands-on Guide & Common Pitfalls

lovehmos — Mon, 30 Jun 2025 09:38:41 +0000

HarmonyOS Webview (ArkWeb) Hands-on Guide & Common Pitfalls

Introduction

Embedding web content is a common requirement in HarmonyOS app development. ArkWeb provides a powerful Webview component, making it easy for developers to integrate web browsing and H5 page interaction within their apps. This document summarizes core usage and common issues based on real development experience, helping you get started quickly.

Features

The main features of the Webview component:

Embed web content within the app
Control pages via WebviewController
Subscribe to Web engine initialization events with webview.once
Support Cookie synchronization, page navigation, forward/backward operations
Export current web content as a PDF file

Back/Forward Cache Settings (BackForwardCacheOptions)

Since API version 12, Webview supports back/forward page caching. Use the BackForwardCacheOptions class to set the number of cached pages and their lifetime, improving page switching smoothness.

size: Maximum number of cached pages per Webview. Default is 1, max is 50. 0 or negative disables caching.
timeToLive: Maximum seconds a page stays in cache. Default is 600. 0 or negative disables caching.

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

const cacheOptions = new webview.BackForwardCacheOptions();
cacheOptions.size = 5; // Cache up to 5 pages
cacheOptions.timeToLive = 300; // Each page cached for up to 5 minutes

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController({
    backForwardCacheOptions: cacheOptions
  });

  build() {
    Column() {
      Web({ src: 'https://www.example.com', controller: this.controller })
    }
  }
}

In practice, set cache size according to memory and business needs. Too much caching may affect performance.

Geolocation Permission Management (GeolocationPermissions)

Webview supports fine-grained geolocation permission management for web pages. Real device testing is required, and permissions such as ohos.permission.LOCATION must be requested.

Allow/delete geolocation permission for a specific origin
Query permission status (supports callback and Promise)
Get/clear all stored permissions

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

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  origin: string = "file:///";

  build() {
    Column() {
      Button('Allow Geolocation')
        .onClick(() => {
          try {
            webview.GeolocationPermissions.allowGeolocation(this.origin);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Check Permission')
        .onClick(() => {
          webview.GeolocationPermissions.getAccessibleGeolocation(this.origin)
            .then(result => {
              console.log('Permission status: ' + result);
            }).catch((error: BusinessError) => {
            console.error(`getAccessibleGeolocation error, ErrorCode: ${error.code},  Message: ${error.message}`);
          });
        })
      Button('Delete Permission')
        .onClick(() => {
          try {
            webview.GeolocationPermissions.deleteGeolocation(this.origin);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: 'https://www.example.com', controller: this.controller })
    }
  }
}

The origin parameter must be a valid origin string. Parameter type errors will return 401. If not authorized, the page cannot access geolocation.

Export Webpage to PDF (createPdf)

Webview supports exporting the current web content as a PDF file. Use the createPdf method of WebviewController to asynchronously obtain the PDF data stream of the web page.

configuration: PdfConfiguration object, sets PDF page width, height, margins, and whether to print background.
callback: Callback function, returns the PDF data stream.

Common issues:

WebviewController must be associated with a Web component, otherwise error 17100001 will occur.
Parameter type errors will return 401.

import { fileIo as fs } from '@kit.CoreFileKit';
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  controller: webview.WebviewController = new webview.WebviewController();
  pdfConfig: webview.PdfConfiguration = {
    width: 8.27,
    height: 11.69,
    marginTop: 0,
    marginBottom: 0,
    marginRight: 0,
    marginLeft: 0,
    shouldPrintBackground: true
  }

  build() {
    Column() {
      Button('SavePDF')
        .onClick(() => {
          this.controller.createPdf(
            this.pdfConfig,
            (error, result: webview.PdfData) => {
              try {
                // Get component context
                let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
                // Get sandbox path and set PDF file name
                let filePath = context.filesDir + "/test.pdf";
                let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
                fs.write(file.fd, result.pdfArrayBuffer().buffer).then((writeLen: number) => {
                  console.info("createPDF write data to file succeed and size is:" + writeLen);
                }).catch((err: BusinessError) => {
                  console.error("createPDF write data to file failed with error message: " + err.message +
                    ", error code: " + err.code);
                }).finally(() => {
                  fs.closeSync(file);
                });
              } catch (resError) {
                console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
              }
            });
        })
      Web({ src: "www.example.com", controller: this.controller })
    }
  }
}

In practice, make sure WebviewController is bound to a Web component first. It is recommended to save PDF files to the sandbox directory to avoid permission issues.

Usage Scenarios

Embed H5 pages: Integrate third-party web pages, event pages, help centers, etc. within the app.
Hybrid development: Implement some features with web technology to improve development efficiency.
Data display: Dynamically display data or charts via web pages.

Pitfalls & Notes

webview.once triggers only once: Only fires on the first load of the Web component. Pay attention to lifecycle management.
DevEco Studio previewer does not support Webview: Always test on a real device to avoid misjudgment by the previewer.
Strict parameter validation: webview.once will return error code 401 for parameter type errors. Check your arguments.
Cookie sync timing: It is recommended to sync cookies after the webInited event, otherwise it may be invalid.
Page navigation/refresh control: Use WebviewController for unified management to avoid state confusion.

Summary

The Webview component provides powerful web integration capabilities for HarmonyOS apps. Pay attention to lifecycle, event subscription, and parameter validation during development. Refer to official documentation and community experience when encountering issues. As the API continues to improve, the Webview experience will get even better.

References

Welcome to Try

If you are also developing HarmonyOS apps, feel free to use the Webview component. Hope it helps you!

Using HarmonyOS Native Scan in uni-app or x Dev Notes & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:35:29 +0000

Using HarmonyOS Native Scan in uni-app or x Dev Notes & Pitfalls

About HarmonyOS 5

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about cross-platform development and native capabilities integration, which led me to develop this comprehensive scanning module. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

I. Background Introduction

Recently, while developing a HarmonyOS application, we encountered a need for scanning functionality. We had tried many scanning solutions before, but none were ideal. Until we discovered the hmos-scan plugin, which finally solved our pain points. Let me share our experience.

1.1 Why Choose hmos-scan?

To be honest, we've encountered many pitfalls before:

Traditional scanning solutions were problematic:
- WebView scanning was painfully slow and often froze
- Third-party libraries doubled the app size
- Different phones had different performance
- Poor recognition of slightly blurry codes, terrible user experience
Native development was painful:
- Writing native code took too much time
- Had to write code for each platform
- Maintenance was particularly troublesome
- Development cycle was too long, boss couldn't wait
hmos-scan is excellent:
- Uses HarmonyOS native capabilities, scanning is super fast
- High recognition rate, can scan even at angles
- Just a few lines of code, very convenient
- Good performance, low memory usage
- Can select images from gallery, very user-friendly

1.2 Practical Use Cases

E-commerce Price Comparison:

   // Scan product code for price comparison
   async function scanProduct() {
     try {
       const barcode = await scanapiSync()
       // Call price comparison API
       const priceInfo = await comparePrice(barcode)
       showPriceResult(priceInfo)
     } catch (error) {
       showError('Scan failed, please try again')
     }
   }

Express Tracking:

   // Scan express tracking number
   async function scanExpress() {
     try {
       const trackingNumber = await scanapiSync()
       // Query logistics information
       const expressInfo = await queryExpress(trackingNumber)
       showExpressInfo(expressInfo)
     } catch (error) {
       showError('Scan failed, please try again')
     }
   }

Meeting Check-in:

   // Scan meeting code for check-in
   async function scanMeeting() {
     try {
       const meetingCode = await scanapiSync()
       // Verify meeting code
       const checkInResult = await verifyMeeting(meetingCode)
       showCheckInResult(checkInResult)
     } catch (error) {
       showError('Check-in failed, please try again')
     }
   }

II. Environment Preparation

Development Tools:
- HBuilderX 3.8.0 or above
- DevEco Studio (required for HarmonyOS development)
Project Requirements:
- Use uni-app x framework
- Choose Vue 3

III. Plugin Usage

1. Plugin Installation

Visit plugin market: hmos-scan plugin
Download and import into HBuilderX

IV. Using in Project

1. Basic Example

<!-- pages/index/index.uvue -->
<template>
  <view class="content">
    <button @click="startScan">Start Scanning</button>
    <text v-if="scanResult">Scan Result: {{scanResult}}</text>
  </view>
</template>

<script>
import { scanapiSync } from "@/uni_modules/hmos-scan/utssdk/app-harmony";

export default {
  data() {
    return {
      scanResult: ''
    }
  },
  methods: {
    async startScan() {
      try {
        const result = await scanapiSync()
        this.scanResult = result
        console.log('Scan Result:', result)
      } catch (error) {
        console.error('Scan Failed:', error)
        this.scanResult = 'Scan Failed'
      }
    }
  }
}
</script>

<style>
.content {
  padding: 20px;
}
button {
  margin: 20px 0;
}
</style>

2. Advanced Example (with History)

<!-- pages/advanced/index.uvue -->
<template>
  <view class="container">
    <view class="scan-area">
      <button @click="startScan" :disabled="isScanning">
        {{isScanning ? 'Scanning...' : 'Start Scan'}}
      </button>
    </view>

    <view class="result-area" v-if="scanHistory.length > 0">
      <text class="title">Scan History</text>
      <view v-for="(item, index) in scanHistory" :key="index" class="history-item">
        <text class="time">{{item.time}}</text>
        <text class="content">{{item.content}}</text>
      </view>
    </view>
  </view>
</template>

<script>
import { scanapiSync } from "@/uni_modules/hmos-scan/utssdk/app-harmony";

export default {
  data() {
    return {
      isScanning: false,
      scanHistory: []
    }
  },
  methods: {
    async startScan() {
      if (this.isScanning) return

      this.isScanning = true
      try {
        const result = await scanapiSync()
        this.scanHistory.unshift({
          time: new Date().toLocaleTimeString(),
          content: result
        })
      } catch (error) {
        console.error('Scan Failed:', error)
      } finally {
        this.isScanning = false
      }
    }
  }
}
</script>

<style>
.container {
  padding: 20px;
}
.scan-area {
  margin-bottom: 20px;
}
.result-area {
  border-top: 1px solid #eee;
  padding-top: 20px;
}
.title {
  font-size: 16px;
  font-weight: bold;
  margin-bottom: 10px;
}
.history-item {
  padding: 10px;
  border-bottom: 1px solid #eee;
}
.time {
  font-size: 12px;
  color: #999;
}
.content {
  margin-top: 5px;
}
</style>

V. Features

Multiple Mode Support:
- QR codes and barcodes
- Gallery image selection
Error Handling:
- Comprehensive exception handling
- User-friendly error messages
- Detailed logging
User Experience:
- Simple operation
- Status feedback
- Asynchronous processing

VI. Notes

Compatibility:
- Only supports HarmonyOS
- Ensure device has scanning capability
Performance Optimization:
- Monitor memory usage
- Release resources promptly
- Avoid repeated scanning

VII. Common Issues

Scanning Failure:
- Check device compatibility
- Check logs for errors
Result Parsing Errors:
- Check result format
- Handle various return types
- Add error handling

VIII. Summary

After using the hmos-scan plugin, scanning functionality development has become very simple. Native capabilities are fully preserved, development experience is excellent, highly recommended!

IX. References

HarmonyOS 5.0 WebSocket – Developer’s Field Notes

lovehmos — Mon, 30 Jun 2025 09:31:59 +0000

HarmonyOS 5.0 WebSocket – Developer’s Field Notes

About HarmonyOS 5

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about real-time communication and distributed applications, which led me to explore WebSocket implementations in HarmonyOS 5. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

Preface

Recently, while developing HarmonyOS applications, I encountered a need for real-time communication. After some research, I found that HarmonyOS 5.0 provides more comprehensive WebSocket support, so I created a simple demo to test it. Below, I'll share my implementation process, hoping it helps others with similar needs.

Development Environment

DevEco Studio 4.0
HarmonyOS SDK API 14 (HarmonyOS 5.0)
Test Device: Huawei Mate 60 Pro

Implementation Process

1. Import Required Packages

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

2. Create a Simple Component

Here I've created a simple component mainly for testing WebSocket's ping functionality. HarmonyOS 5.0's component system has seen significant improvements, making it more convenient to use.

@Entry
@Component
struct WebSocketExample {
  @State pingResult: string = '';
  private ws: webSocket.WebSocket | undefined = undefined;
  private pingStartTime: number = 0;
  private pingCount: number = 0;
  private totalPingTime: number = 0;

  // Initialize when component is created
  aboutToAppear() {
    this.initWebSocket();
  }

  // Remember to close connection when component is destroyed
  aboutToDisappear() {
    this.closeWebSocket();
  }
}

3. Initialize WebSocket

HarmonyOS 5.0's WebSocket API has been significantly optimized with improved error handling. This code section might look long, but it's essentially just a few event listeners:

private initWebSocket() {
  // Create instance
  this.ws = webSocket.createWebSocket();

  // Handle successful connection
  this.ws.on('open', (err: BusinessError, value: Object) => {
    if (err) {
      console.error('Connection failed:', JSON.stringify(err));
      this.pingResult = 'Connection failed';
      return;
    }
    console.log('Connection successful!');
  });

  // Handle received messages
  this.ws.on('message', (error: BusinessError, value: string | ArrayBuffer) => {
    if (error) {
      console.error('Message error:', JSON.stringify(error));
      return;
    }

    // If it's a pong message, calculate the delay
    if (value === 'pong') {
      const endTime = Date.now();
      const duration = endTime - this.pingStartTime;
      this.pingCount++;
      this.totalPingTime += duration;
      const avgPing = this.totalPingTime / this.pingCount;
      this.pingResult = `Delay: ${duration}ms (Average: ${avgPing.toFixed(2)}ms)`;
    }
  });

  // Error handling
  this.ws.on('error', (err: BusinessError) => {
    console.error('Error occurred:', JSON.stringify(err));
    this.pingResult = 'Connection error';
  });

  // Handle connection close
  this.ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
    console.log(`Connection closed: ${value.code} - ${value.reason}`);
  });

  // Start connecting to server
  this.ws.connect('ws://your-server-address', {
    header: {
      'Content-Type': 'application/json'
    },
    // New configuration options in API 14
    protocols: ['my-protocol'],
    timeout: 10000, // 10 second timeout
    proxy: {
      host: '192.168.0.150',
      port: 8888,
      exclusionList: []
    }
  }, (err: BusinessError, value: boolean) => {
    if (err) {
      console.error('Connection failed:', JSON.stringify(err));
      this.pingResult = 'Connection failed';
    }
  });
}

4. Implement Ping Functionality

WebSocket message sending in HarmonyOS 5.0 is more stable, and this functionality is simple:

private sendPing() {
  if (!this.ws) {
    this.pingResult = 'Not connected yet';
    return;
  }

  this.pingStartTime = Date.now();
  this.ws.send('ping', (err: BusinessError, value: boolean) => {
    if (err) {
      console.error('Send failed:', JSON.stringify(err));
      this.pingResult = 'Send failed';
    }
  });
}

5. Close Connection

Connection closing in API 14 is more reliable:

private closeWebSocket() {
  if (this.ws) {
    this.ws.close((err: BusinessError) => {
      if (err) {
        console.error('Close failed:', JSON.stringify(err));
      }
    });
  }
}

6. Create a Simple Interface

HarmonyOS 5.0's UI system has seen significant improvements, making it more convenient to use:

build() {
  Column() {
    Button('Test Latency')
      .onClick(() => this.sendPing())
    Text(this.pingResult)
      .fontSize(16)
      .margin({ top: 10 })
  }
  .width('100%')
  .height('100%')
  .justifyContent(FlexAlign.Center)
}

Common Pitfalls

Initially forgot to close connections when components were destroyed, leading to memory leaks
Poor error handling causing application crashes
Connection timeout set too short, resulting in frequent connection failures
Forgot to implement reconnection logic, leading to poor experience during network instability
Didn't properly utilize new configuration options in API 14, causing unstable connections

Summary

Although this demo is simple, it covers the main functionality of WebSocket. HarmonyOS 5.0's WebSocket API has seen many improvements, making it more stable to use. In actual projects, you might need to add:

Automatic reconnection
Heartbeat detection
Message queue
Offline message retransmission and other features, depending on project requirements.

References

Postscript

While writing this article, I noticed that HarmonyOS 5.0's documentation has been significantly updated, and the APIs have become more user-friendly. Particularly the WebSocket module, which has added many practical features. I hope this article helps those learning HarmonyOS development. If you have any questions, feel free to discuss in the comments section.

HarmonyOS UTS Plugin in Uniapp A Simple Example That Unlocks Real Progress

lovehmos — Mon, 30 Jun 2025 09:29:15 +0000

HarmonyOS UTS Plugin in Uniapp A Simple Example That Unlocks Real Progress

About HarmonyOS 5

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about security tools and cryptographic functions, which led me to develop this comprehensive AES encryption/decryption module. Through my blog and GitHub repositories, I've been sharing my experiences and helping other developers navigate the exciting world of HarmonyOS development.

Preface

In the process of developing HarmonyOS applications, we often need to use UTS plugins to extend functionality. This article will share a simple but practical UTS plugin development example for HarmonyOS, helping developers quickly get started with UTS plugin development.

1. What is UTS Plugin

1.1 Definition

UTS (UniApp TypeScript) is a cross-platform development language based on TypeScript, which can be used to develop plugins for different platforms.

1.2 Features

Cross-platform compatibility
TypeScript-based development
Native performance
Easy to use

2. Development Environment

2.1 Required Tools

HBuilderX
DevEco Studio
Node.js
Git

2.2 Environment Setup

Install HBuilderX
Install DevEco Studio
Install Node.js
Configure development environment

3. Plugin Development

3.1 Project Structure

project
├── src
│   ├── index.uts
│   └── utils
│       └── helper.uts
├── package.json
└── README.md

3.2 Core Code

// index.uts
import { Helper } from './utils/helper'

export class MyPlugin {
  private helper: Helper

  constructor() {
    this.helper = new Helper()
  }

  public sayHello(): string {
    return this.helper.formatMessage('Hello from HarmonyOS!')
  }
}

3.3 Implementation Steps

Create project structure
Write core code
Configure project
Test functionality

4. Common Issues

4.1 Development Issues

Environment configuration
Code compilation
Performance optimization

4.2 Solutions

Check environment setup
Debug compilation errors
Optimize code structure

5. Best Practices

5.1 Code Organization

Clear structure
Modular design
Code reuse

5.2 Performance Optimization

Minimize dependencies
Optimize algorithms
Cache results

6. Summary

This example demonstrates the basic process of developing UTS plugins for HarmonyOS. Although simple, it covers the key points of UTS plugin development and can help developers quickly get started.

References

Welcome to Experience

Welcome to download and experience the HarmonyOS Developer Toolbox, which integrates various practical development tools:
Download Link

HarmonyOS Timestamp Converter: Dev Notes & Gotchas

lovehmos — Mon, 30 Jun 2025 09:26:42 +0000

HarmonyOS Timestamp Converter: Dev Notes & Gotchas

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) is a major milestone in Huawei's distributed operating system. Its microkernel architecture enhances security and enables seamless cross-device collaboration. The developer experience is greatly improved with the new ArkTS language, enhanced UI components, and better debugging tools. Distributed capabilities allow for smooth experiences across smartphones, tablets, TVs, and IoT devices.

About the Author

I am a dedicated HarmonyOS developer from China, with years of experience in the HarmonyOS ecosystem. I focus on cross-platform development and performance optimization, and I enjoy sharing my technical insights and practical experiences with the community.

Basic Knowledge

Before diving into the Timestamp Converter, let's briefly review some basic concepts:

Timestamp: A numeric value representing the number of seconds or milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
Date-Time Format: Common formats include ISO 8601, ISO 9075, RFC 3339, etc.
Time Zone: The region or offset that affects how a timestamp is interpreted or displayed.
Milliseconds/Seconds: Timestamps can be in milliseconds (13 digits) or seconds (10 digits).

Preface

Recently, while working on the HarmonyOS Toolbox, I decided to add a timestamp conversion feature. The goal was to convert between timestamps and date-time strings, such as turning "1709123456" into "2024-02-28 12:34:56". At first, I thought it would be simple, but I soon encountered challenges with formats, time zones, and switching between milliseconds and seconds.

During development, I faced many pitfalls, such as time format validation, time zone conversion, and implementing a date picker. After several iterations, the tool became stable and user-friendly.

I. Feature Overview

1.1 Main Features

Convert timestamp to date-time
Convert date-time to timestamp
Support multiple time formats: ISO 8601, ISO 9075, RFC 3339, etc.
Switch between milliseconds and seconds
Quick access to current time
Real-time preview of conversion results
One-click copy of results
Favorites feature

1.2 UI Features

Timestamp input box
Date-time picker
Format selection list
Result display area
Copy button

II. Implementation Process

2.1 Development Stories

At first, I used the system's built-in Date object, but quickly ran into problems. For example, when entering "1709123456", the output was "2024-02-28T12:34:56.000Z", which confused users who wanted "2024-02-28 12:34:56". I realized that different scenarios require different time formats, some with time zones and some without.

Another user wanted the conversion of "2024-02-28 12:34:56" to be "1709123456000" instead of "1709123456". I had to adjust the code several times to convert based on the selected format.

Time zone conversion was also tricky. Initially, I didn't handle time zones, but users insisted on support. Handling daylight saving time and other issues made it even more complex, but after several revisions, it worked well.

The date picker also needed improvement. Users found the system picker inconvenient, so I implemented a custom calendar view for better usability.

2.2 Temporary Solutions

Time Format Validation
- Temporary: Use regex for validation (simple but crude)
- Problem: Sometimes validates incorrect formats, causing errors
- Final: Use specific regex for each format for reliability
Time Zone Conversion
- Temporary: Convert directly to UTC, ignore other zones
- Problem: Incorrect conversions for some zones
- Final: Determine if conversion is needed based on time zone type
Date Picker
- Temporary: Use system date picker
- Problem: Poor usability, users wanted customization
- Final: Implement a custom date picker for better experience
Milliseconds/Seconds Switch
- Temporary: Input timestamp in a text box
- Problem: Inconvenient, users wanted a toggle
- Final: Add a toggle button for easy switching

2.3 Debugging Examples

Time Format Validation

static isValidISO8601(dateStr: string): boolean {
  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/.test(dateStr)
}

static isValidISO9075(dateStr: string): boolean {
  return /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(dateStr)
}

static isValidRFC3339(dateStr: string): boolean {
  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?[+-]\d{2}:\d{2}$/.test(dateStr)
}

Timestamp Conversion

static timestampToDate(timestamp: string, format: string): string {
  const date = new Date(parseInt(timestamp))
  switch (format) {
    case 'ISO 8601':
      return date.toISOString()
    case 'ISO 9075':
      return date.toISOString().replace('T', ' ').replace('Z', '')
    case 'RFC 3339':
      return date.toISOString()
    default:
      return date.toISOString()
  }
}

static dateToTimestamp(dateStr: string, format: string): string {
  const date = new Date(dateStr)
  return date.getTime().toString()
}

III. Pitfalls and Lessons

3.1 Problems Encountered

Time Format Validation
- Problem: Users enter irregular formats, e.g., multiple separators
- Solution: Add regex validation, auto-handle
- Suggestion: Restrict format at input to avoid trouble
Time Zone Conversion
- Problem: Inaccurate conversion results
- Solution: Judge by time zone type
- Suggestion: Allow user customization
Date Picker
- Problem: Picker not user-friendly
- Solution: Implement custom picker
- Suggestion: Allow custom pickers
Milliseconds/Seconds Switch
- Problem: Inconvenient switching
- Solution: Use toggle button
- Suggestion: Allow custom switching methods

3.2 Optimization Suggestions

Feature Optimization
- Support more formats
- Add history records
- Support batch conversion
- Add format classification, import/export, management, sharing, backup, etc.
Performance Optimization
- Optimize conversion speed
- Reduce memory usage
- Release resources promptly
- Try multithreading, algorithm optimization, result caching, asynchronous processing, etc.
User Experience
- Add usage instructions
- Support keyboard shortcuts
- Add animation effects, themes, sharing, favorites, import, backup, etc.

IV. Summary

The timestamp converter tool now covers all basic functions:

Support for multiple format conversions
Real-time result preview
One-click copy of results
Favorites for common settings

Some minor issues remain, but it works well for most scenarios. Further optimizations will be made over time.

V. Reference Resources

HarmonyOS Application Development Guide

Welcome to Experience

This timestamp converter tool is integrated into the HarmonyOS Developer Toolbox. Welcome to download and try it!

HarmonyOS Developer Toolbox

Author: In the World of Development
Email: 1743914721@qq.com
Copyright Notice: This article is original. Please indicate the source when reprinting.

If you encounter similar problems, feel free to leave a comment and discuss. If you can't solve it, let's have a headache together!

HarmonyOS RDB Utils Practical Guide & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:21:35 +0000

HarmonyOS RDB Utils Practical Guide & Pitfalls

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) represents a revolutionary step in the evolution of Huawei's distributed operating system. As someone who has been following its development closely, I can attest to the remarkable improvements in this version. The system's microkernel architecture not only enhances security but also provides unprecedented flexibility in cross-device collaboration. What excites me most about HarmonyOS 5 is its focus on developer experience—the new ArkTS language, enhanced UI components, and improved debugging tools have made development much more efficient. The distributed capabilities allow us to create truly seamless experiences across different devices, from smartphones to tablets, smart TVs, and IoT devices.

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about data storage, database encapsulation, and code reusability, and I enjoy sharing my experiences through blogs and open-source contributions to help more developers embrace the HarmonyOS ecosystem.

Basic Knowledge

Let's first understand the basics of SQL and RDB in HarmonyOS:

What is SQL
- SQL (Structured Query Language) is the standard language for operating relational databases.
- Most common operations are simple; for complex queries, search engines or ChatGPT can help.
Common SQL Statements
1. Create Table

   CREATE TABLE user_info (
     id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Primary key, auto-increment
     name TEXT,                            -- Text type
     age INTEGER,                          -- Integer type
     score REAL,                           -- Float type
     is_active INTEGER DEFAULT 0           -- Default value
   );

Insert Data

   INSERT INTO user_info (name, age) VALUES ('Zhang San', 18);

Query Data

   -- Query all fields
   SELECT * FROM user_info;

   -- Conditional query
   SELECT name, age FROM user_info WHERE age > 18;

   -- Sorting
   SELECT * FROM user_info ORDER BY age DESC;

   -- Limit number
   SELECT * FROM user_info LIMIT 10;

Update Data

   UPDATE user_info SET age = 20 WHERE name = 'Zhang San';

Delete Data

   DELETE FROM user_info WHERE age < 18;

Preface

Recently, our project required data storage again. Using HarmonyOS RDB is a bit verbose, so I simply encapsulated a utility class to avoid writing repetitive code every time. Here are my notes, in case I need to refer back in the future.

I. Development Background

At first, I didn't plan to encapsulate anything, but every time I used RDB, I had to write a lot of initialization, table creation, try-catch, etc. It was annoying. So I wrote an RDBUtils class for convenience.

II. Implementation Steps

2.1 Creating the RDB Utility Class

import relationalStore from '@ohos.data.relationalStore';
import common from '@ohos.app.ability.common';

// Database configuration
const STORE_CONFIG: relationalStore.StoreConfig = {
  name: 'user.db',
  securityLevel: relationalStore.SecurityLevel.S1
};

// Database version
const DB_VERSION = 2;

// SQL to create table
const SQL_CREATE_TABLE = `
  CREATE TABLE IF NOT EXISTS user_info (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    avatarUri TEXT,
    nickName TEXT,
    unionID TEXT,
    openID TEXT,
    authorizationCode TEXT,
    createTime INTEGER,
    memo TEXT,
    isSynced INTEGER DEFAULT 0
  )
`;

export class RDBUtils {
  private static instance: RDBUtils | null = null;
  private rdbStore: relationalStore.RdbStore | null = null;
  private context: common.Context;

  // Singleton pattern
  public static getInstance(context: common.Context): RDBUtils {
    if (!RDBUtils.instance) {
      RDBUtils.instance = new RDBUtils(context);
    }
    return RDBUtils.instance;
  }

  // Initialize database
  async initRDB(): Promise<void> {
    if (this.rdbStore) {
      return;
    }

    try {
      this.rdbStore = await relationalStore.getRdbStore(this.context, STORE_CONFIG);
      await this.rdbStore.executeSql(SQL_CREATE_TABLE);
      await this.checkAndUpdateVersion();
    } catch (err) {
      console.error(`Failed to initialize database: ${err}`);
      throw err;
    }
  }

  // Database upgrade
  private async checkAndUpdateVersion(): Promise<void> {
    // Check version and perform upgrade
    const currentVersion = await this.getCurrentVersion();
    if (currentVersion < DB_VERSION) {
      await this.upgradeDatabase(currentVersion);
    }
  }
}

2.2 Implementing CRUD Operations

export class RDBUtils {
  // ... previous code ...

  // Insert data
  async insertUser(user: UserInfo): Promise<number> {
    if (!this.rdbStore) {
      throw new Error('Database not initialized');
    }

    const valueBucket: relationalStore.ValuesBucket = {
      'avatarUri': user.avatarUri || '',
      'nickName': user.nickName || '',
      'unionID': user.unionID || '',
      'openID': user.openID || '',
      'authorizationCode': user.authorizationCode || '',
      'createTime': user.createTime || Date.now(),
      'memo': user.memo || '',
      'isSynced': user.isSynced ? 1 : 0
    };

    try {
      return await this.rdbStore.insert('user_info', valueBucket);
    } catch (err) {
      console.error(`Failed to insert data: ${err}`);
      throw err;
    }
  }

  // Update data
  async updateUser(user: UserInfo): Promise<number> {
    if (!this.rdbStore || !user.id) {
      throw new Error('Invalid parameters');
    }

    const valueBucket: relationalStore.ValuesBucket = {
      'avatarUri': user.avatarUri || '',
      'nickName': user.nickName || '',
      // ... other fields
    };

    const predicates = new relationalStore.RdbPredicates('user_info');
    predicates.equalTo('id', user.id);

    try {
      return await this.rdbStore.update(valueBucket, predicates);
    } catch (err) {
      console.error(`Failed to update data: ${err}`);
      throw err;
    }
  }

  // Query data
  async queryUserById(id: number): Promise<UserInfo | null> {
    if (!this.rdbStore) {
      throw new Error('Database not initialized');
    }

    const predicates = new relationalStore.RdbPredicates('user_info');
    predicates.equalTo('id', id);

    try {
      const resultSet = await this.rdbStore.query(predicates, ['*']);
      if (resultSet.goToNextRow()) {
        const user = this.parseUserFromResultSet(resultSet);
        resultSet.close();
        return user;
      }
      resultSet.close();
      return null;
    } catch (err) {
      console.error(`Failed to query data: ${err}`);
      throw err;
    }
  }
}

III. Pitfalls and Issues

Not using singleton pattern caused memory spikes and app freezes—a painful lesson.
Forgetting to close result sets led to memory leaks, which took a long time to debug.
Batch inserts without transactions were extremely slow.
Not handling null values when inserting data caused database errors.
Not checking ID when updating data led to update failures and long debugging sessions.

IV. Usage Example

For example, with a user table, you can insert, query, update, and delete with just a few lines of code—very convenient.

// Initialize database
const rdbUtils = RDBUtils.getInstance(context);
await rdbUtils.initRDB();

// Insert data
const user: UserInfo = {
  avatarUri: 'https://example.com/avatar.jpg',
  nickName: 'Zhang San',
  unionID: '123456',
  openID: '789012',
  authorizationCode: 'abc123'
};
const id = await rdbUtils.insertUser(user);

// Query data
const user = await rdbUtils.queryUserById(id);
console.info(`Queried user: ${user?.nickName}`);

// Update data
if (user) {
  user.nickName = 'Li Si';
  await rdbUtils.updateUser(user);
}

// Delete data
await rdbUtils.deleteUser(id);

V. Notes

Never forget exception handling; if errors are not reported, users will be confused.
Always close result sets when done, or you'll question your sanity.
Don't get data types wrong; debugging will be painful.
Use indexes wisely; use transactions for batch operations.
Encrypt sensitive data; never let user data be exposed.

VI. Summary

This utility works well for my own use. If you have better approaches, feel free to comment and share—let's avoid pitfalls together.

VII. Reference Resources

Welcome to Experience

This RDB utility class has been integrated into the HarmonyOS Developer Toolbox. Welcome to download and experience it!

HarmonyOS Developer Toolbox

Author: In the World of Development
Email: 1743914721@qq.com
Copyright Notice: This article is an original work by the CSDN blogger, please include the original source link and this statement when reprinting.

HarmonyOS QR Code Tool: Dev Notes & Pitfalls

lovehmos — Mon, 30 Jun 2025 09:20:46 +0000

HarmonyOS QR Code Tool: Dev Notes & Pitfalls

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) represents a revolutionary step in the evolution of Huawei's distributed operating system. As someone who has been following its development closely, I can attest to the remarkable improvements in this version. The system's microkernel architecture not only enhances security but also provides unprecedented flexibility in cross-device collaboration. What excites me most about HarmonyOS 5 is its focus on developer experience—the new ArkTS language, enhanced UI components, and improved debugging tools have made development much more efficient. The distributed capabilities allow us to create truly seamless experiences across different devices, from smartphones to tablets, smart TVs, and IoT devices.

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about tool development, QR code technology, and user experience, and I enjoy sharing my experiences through blogs and open-source contributions to help more developers embrace the HarmonyOS ecosystem.

Preface

Recently, while working on the HarmonyOS Toolbox, I was inspired to add a QR code tool. Honestly, I was quite confident at first—"It's just a simple QR code, how hard can it be?" But once I started, I realized I was too naive! Various formats, parameters, saving, scanning—it was overwhelming. The scanning feature especially kept crashing, making me want to smash my keyboard.

I encountered many pitfalls while developing this tool, such as scan encapsulation, image saving, permission handling, etc. I remember one night debugging the save feature until 3 a.m., almost smashing my computer. But hard work paid off, and now it works smoothly. Seeing users say "It's really useful" makes me very happy!

I. Feature Description

1.1 Main Features

Support QR code generation
Support QR code scanning
Support selecting images from the gallery
Support saving QR codes to the gallery
Support copying scan results
Favorites feature

1.2 UI Features

Generate/Scan tab switch
Content input box
QR code preview
Scan button
Save button
Copy button

II. Implementation Process

2.1 Development Stories

Story 1: The Scanning Crash Saga

At first, I used the system's built-in scanning module, thinking, "Isn't this just calling an API? Easy!" But all sorts of problems followed. The funniest was when a user scanned a blurry QR code and the app crashed. The user was furious: "What is this? I want a friendly error message!" I thought, "Isn't that just an error message? Easy!" But once I started, I realized I needed to add try-catch and provide specific error info. After several revisions and adding a loading animation, things finally improved.

Story 2: The Awkward Save Moment

Another time, a user said the save feature didn't work well. At first, I felt wronged: "Isn't this simple?" But after trying it myself, I realized there was indeed a problem. The most awkward part was that there was no prompt when saving, and sometimes it failed. The user said, "I tried to save for a long time, but didn't know where it went. So annoying!" I quickly revised it several times and added a success prompt. Now, thinking back, I'm grateful for that user's feedback—otherwise, I wouldn't have noticed the issue.

After some research, I found that saving is actually quite complex:

First, convert the QR code to an image format, which may cause memory issues (sometimes OOM, really frustrating)
Then, request gallery permissions, which can be tricky (sometimes the popup doesn't appear, really annoying)
Finally, handle various exceptions when saving to the gallery

The funniest was when I tested and saved successfully, but couldn't find the image. After a long time, I realized it was a path issue. HarmonyOS's gallery path is different from Android, and you need to use a special API. This pitfall was both funny and frustrating.

Story 3: The Big Image Freeze Crisis

The funniest was handling big images. At first, I didn't consider performance, and a user sent a huge image, causing the app to freeze. I thought, "It's just an image, easy!" But once I started, I realized I needed to consider memory usage and do async processing. After several revisions and adding a loading state, things finally improved. Now, thinking back, I'm grateful for that user's "big image"—otherwise, I wouldn't have noticed the performance issue.

Story 4: The Copy Feature Surprise

Another user said the copy feature didn't work well. At first, I felt wronged: "Isn't this simple?" But after trying it myself, I realized there was indeed a problem. The most awkward part was that there was no prompt when copying, and sometimes it failed. The user said, "I tried to copy for a long time, but didn't know if it succeeded. So annoying!" I quickly revised it several times and added a success prompt. Now, thinking back, I'm grateful for that user's feedback—otherwise, I wouldn't have noticed the issue.

2.2 Core Feature Implementation

Import modules

import router from '@ohos.router'
import promptAction from '@ohos.promptAction'
import { scanCore, scanBarcode } from '@kit.ScanKit'
import { hilog } from '@kit.PerformanceAnalysisKit'
import pasteboard from '@ohos.pasteboard'
import common from '@ohos.app.ability.common'
import image from '@ohos.multimedia.image'
import fileio from '@ohos.fileio'
import { photoAccessHelper } from '@kit.MediaLibraryKit'
import { StorageUtil } from '../../utils/storage'
import { componentSnapshot } from '@kit.ArkUI'
import { fileIo } from '@kit.CoreFileKit'
import { BusinessError } from '@kit.BasicServicesKit'

Scan feature implementation

private startScan() {
  try {
    let options: scanBarcode.ScanOptions = {
      scanTypes: [scanCore.ScanType.ALL],
      enableMultiMode: true,
      enableAlbum: true
    }

    scanBarcode.startScanForResult(getContext(this), options, (error, result: scanBarcode.ScanResult) => {
      if (error) {
        hilog.error(0x0001, 'QRCodeTool', `Failed to get ScanResult. Code: ${error.code}, message: ${error.message}`)
        promptAction.showToast({ message: 'Scan failed' })
        return
      }

      if (result) {
        try {
          console.info('Scan result:', JSON.stringify(result))

          let scanText = ''
          if (typeof result === 'object') {
            scanText = result['originalValue'] || result['result'] || result['value'] || ''
          }

          if (scanText) {
            this.scanContent = scanText
            hilog.info(0x0001, 'QRCodeTool', `Scan success: ${scanText}`)
            promptAction.showToast({ message: 'Scan successful' })
          } else {
            hilog.error(0x0001, 'QRCodeTool', 'Empty scan result')
            promptAction.showToast({ message: 'No scan content found' })
          }
        } catch (err) {
          hilog.error(0x0001, 'QRCodeTool', `Parse result error: ${err}`)
          promptAction.showToast({ message: 'Failed to parse scan result' })
        }
      }
    })
  } catch (error) {
    hilog.error(0x0001, 'QRCodeTool', `Failed to startScanForResult. Code: ${error.code}, message: ${error.message}`)
    promptAction.showToast({ message: 'Failed to start scan' })
  }
}

Save feature implementation

// Pack PixelMap as jpg
async packingPixelMap2Jpg(pixelMap: PixelMap): Promise<ArrayBuffer> {
  const imagePackerApi = image.createImagePacker();
  const packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 };
  let imageBuffer: ArrayBuffer = new ArrayBuffer(1);
  try {
    imageBuffer = await imagePackerApi.packing(pixelMap, packOpts);
  } catch (err) {
    console.error(`Invoke packingPixelMap2Jpg failed, err: ${JSON.stringify(err)}`);
  }
  return imageBuffer;
}

// Save image to gallery
async savePhotoToGallery(context: common.UIAbilityContext) {
  let helper = photoAccessHelper.getPhotoAccessHelper(context);
  try {
    const imageBuffer = await this.packingPixelMap2Jpg(this.pixmap as image.PixelMap)

    let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg');
    let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
    await fileIo.write(file.fd, imageBuffer);
    await fileIo.close(file.fd);
    promptAction.showToast({ message: 'Saved to gallery!' });
  }
  catch (error) {
    const err: BusinessError = error as BusinessError;
    console.error(`Failed to save photo. Code is ${err.code}, message is ${err.message}`);
  }
}

Copy feature implementation

private async copyToClipboard(content: string) {
  try {
    const pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, content)
    const systemPasteboard = pasteboard.getSystemPasteboard()
    await systemPasteboard.setData(pasteData)
    await promptAction.showToast({ message: 'Copied to clipboard' })
  } catch (error) {
    console.error('Copy failed:', error)
    await promptAction.showToast({ message: 'Copy failed' })
  }
}

2.3 Temporary Solutions

Scan issues
- Temporary: Use scan module directly, simple and crude
- Problem: Crashes on format error, poor user experience
- Final: Add try-catch, provide friendly prompts
Save issues
- Temporary: Save directly, simple
- Problem: No prompt, poor experience, incomplete permission handling
- Final:
  - Add save success prompt
  - Improve permission request process
  - Optimize error handling
  - Ensure files are properly closed
  - Add detailed error prompts
Big image issues
- Temporary: Synchronous processing, simple
- Problem: Big images cause freezes
- Final: Async processing, add loading state
Copy issues
- Temporary: Copy directly, simple
- Problem: No prompt, poor experience
- Final: Add copy success prompt

III. Pitfalls and Issues

3.1 Problems Encountered

Scan issues
- Problem: Crashes on format error
- Solution: Add try-catch
- Suggestion: Provide friendly prompts
Save issues
- Problem: Save failed
- Solution: Use SaveButton and componentSnapshot
- Suggestion: Pay attention to permission requests
Big image issues
- Problem: Causes freezes
- Solution: Async processing
- Suggestion: Add loading state
Copy issues
- Problem: No prompt
- Solution: Add prompt
- Suggestion: Handle errors

3.2 Optimization Suggestions

Feature optimization
- Support more QR code formats
- Add history
- Support batch scanning
- Beautify QR codes, custom styles, batch generation, etc.
Performance optimization
- Optimize scan speed
- Reduce memory usage
- Release resources promptly
- Try multithreading, algorithm optimization, result caching, async processing
User experience
- Add usage instructions
- Support shortcuts
- Add animation effects, themes, sharing, favorites, import, backup, etc.

IV. Summary

This QR code tool covers all the basics:

Support QR code generation
Support QR code scanning
Support saving to gallery
Support copying results
Favorites for common settings

To be honest, developing this tool was a love-hate process. I loved seeing it grow from nothing to something useful, but hated all the pitfalls along the way. Looking back, those pitfalls were worth it! Without them, I wouldn't have found so many areas to optimize.

Some edge cases are still not fully resolved, such as occasional slow scanning or UI stutter when saving big images (and sometimes strange errors pop up, which is really frustrating). But it works for most scenarios, and user feedback has been positive. I'll keep optimizing as time allows—after all, good products are polished over time.

V. Reference Resources

HarmonyOS Application Development Guide

Welcome to Experience

This QR code tool has been integrated into the HarmonyOS Developer Toolbox. Welcome to download and experience it! If you encounter any issues, feel free to give feedback, and I will continue to improve it!

HarmonyOS Developer Toolbox

Author: In the World of Development
Email: 1743914721@qq.com
Copyright Notice: This article is an original work by the CSDN blogger, please include the original source link and this statement when reprinting.

If you encounter similar issues, feel free to comment and discuss. Let's improve and grow together!

HarmonyOS Privacy Popup Dev Guide & Compliance Pitfalls

lovehmos — Mon, 30 Jun 2025 09:03:08 +0000

HarmonyOS Privacy Popup Dev Guide & Compliance Pitfalls

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) represents a revolutionary step in the evolution of Huawei's distributed operating system. As someone who has been following its development closely, I can attest to the remarkable improvements in this version. The system's microkernel architecture not only enhances security but also provides unprecedented flexibility in cross-device collaboration. What excites me most about HarmonyOS 5 is its focus on developer experience—the new ArkTS language, enhanced UI components, and improved debugging tools have made development much more efficient. The distributed capabilities allow us to create truly seamless experiences across different devices, from smartphones to tablets, smart TVs, and IoT devices.

About the Author

I am a dedicated HarmonyOS developer based in China, with over three years of experience in the ecosystem. My journey with HarmonyOS began with its early versions, and I've witnessed its remarkable evolution. As a developer who has contributed to several open-source HarmonyOS projects, I've gained valuable insights into its architecture and best practices. I'm particularly passionate about privacy protection, UI/UX, and compliance, and I enjoy sharing my experiences through blogs and open-source contributions to help more developers embrace the HarmonyOS ecosystem.

Preface

Recently, while developing HarmonyOS applications, I found that privacy popups are an unavoidable feature. They are not only crucial for user experience but also for app compliance. After some exploration and practice, I finally implemented a privacy popup that I am quite satisfied with. Here I share my development insights.

I. Development Background

When developing HarmonyOS apps, privacy popups are extremely important. They impact both user experience and compliance. This article details how to implement a beautiful and practical custom privacy popup in HarmonyOS apps.

II. Implementation Steps

2.1 Creating the Privacy Popup Component

First, create a custom privacy popup component PrivacyDialog.ets:

@CustomDialog
export struct PrivacyDialog {
  controller: CustomDialogController;
  context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
  confirm: () => void = () => {};
  cancel: () => void = () => {};

  build() {
    Column() {
      // Title
      Text('Privacy Policy')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 16, bottom: 16 })
        .textAlign(TextAlign.Center)
        .fontColor($r('app.color.text_primary'))

      // Content
      Text() {
        Span('This app values and protects all users\' personal privacy. To provide you with more accurate and personalized services, this app will use and disclose your personal information in accordance with the privacy policy')
          .fontSize(16)
          .fontColor($r('app.color.text_secondary'))

        Span(' as stipulated. You can read the ')
          .fontSize(16)
          .fontColor($r('app.color.text_secondary'))

        Span('Service Agreement')
          .fontSize(16)
          .fontColor($r('app.color.brand_color'))
          .onClick(() => {
            this.controller.close();
            router.pushUrl({
              url: 'pages/UserAgreementDetail',
              params: { needShowDialog: true }
            });
          })

        Span(' and ')
          .fontSize(16)
          .fontColor($r('app.color.text_secondary'))

        Span('Privacy Policy')
          .fontSize(16)
          .fontColor($r('app.color.brand_color'))
          .onClick(() => {
            this.controller.close();
            router.pushUrl({
              url: 'pages/PrivacyPolicyDetail',
              params: { needShowDialog: true }
            });
          })
      }
      .margin({ left: 16, right: 16 })
      .textAlign(TextAlign.Center)

      // Buttons
      Row() {
        Button('Agree')
          .width('45%')
          .height(40)
          .backgroundColor($r('app.color.brand_color'))
          .fontColor(Color.White)
          .onClick(() => {
            this.confirm();
            this.controller.close();
          })

        Button('Disagree and Exit')
          .width('45%')
          .height(40)
          .fontColor($r('app.color.text_secondary'))
          .backgroundColor($r('app.color.card_background'))
          .onClick(() => {
            this.cancel();
            this.controller.close();
          })
      }
      .width('100%')
      .justifyContent(FlexAlign.SpaceAround)
      .margin({ top: 40, bottom: 16 })
    }
    .width('90%')
    .backgroundColor($r('app.color.card_background'))
    .borderRadius(16)
    .padding(16)
  }
}

2.2 Using in the Welcome Page

Integrate the privacy popup in the welcome page Welcome.ets:

@Entry
@Component
struct Welcome {
  @State showPrivacyDialog: boolean = false;
  private context = getContext(this) as common.UIAbilityContext;
  private preferences: dataPreferences.Preferences | null = null;

  private dialogController: CustomDialogController = new CustomDialogController({
    builder: PrivacyDialog({
      context: this.context,
      confirm: async () => {
        try {
          if (this.preferences) {
            await this.preferences.put('privacy_agreed', true);
            await this.preferences.flush();
          }
          router.replaceUrl({ url: 'pages/Index' });
        } catch (error) {
          console.error('Update privacy agreement flag failed:', error);
        }
      },
      cancel: () => {
        this.context.terminateSelfWithResult({
          resultCode: 0,
          want: {}
        });
      }
    }),
    alignment: DialogAlignment.Center,
    offset: { dx: 0, dy: 0 },
    customStyle: true,
    autoCancel: false
  });

  async aboutToAppear() {
    try {
      this.preferences = await dataPreferences.getPreferences(this.context, 'app_settings');
      const hasAgreed = await this.preferences.get('privacy_agreed', false);

      if (!hasAgreed) {
        this.showPrivacyDialog = true;
        this.dialogController.open();
      } else {
        setTimeout(() => {
          router.replaceUrl({ url: 'pages/Index' });
        }, 1100);
      }
    } catch (error) {
      console.error('Initialize preferences failed:', error);
    }
  }
}

III. Pitfalls and Issues

3.1 UI Design

The initial popup layout was random; after referencing mainstream apps, it became more beautiful
Privacy policy text was too long at first; users wouldn't read it, so it was simplified
Button styles were not prominent enough at first; took several revisions to be satisfied
Dark mode adaptation took a lot of time

3.2 Interaction Experience

When viewing detailed privacy policy, the popup was not closed at first, causing user confusion
The navigation logic for Service Agreement and Privacy Policy was revised several times
The timing for redirecting after agreement was tricky; added a delay later
No confirmation for exit at first when disagreeing

3.3 Data Storage

Exception handling for Preferences storage was poor at first, causing data loss
The issue of repeated popups took a long time to fix
The reset privacy setting feature was added later due to user demand

IV. Notes

Permission Management
- Storage permissions must be requested, or data cannot be saved
- The permission request process should be user-friendly
User Experience
- Popup content should be simple and direct
- Operation guidance should be clear
- Detailed policies should be easy to find but not too prominent
Compliance
- Follow laws and regulations
- Protect user privacy—this is the bottom line
- Clearly state necessary information

V. Summary

This privacy popup feature went through several iterations and many pitfalls. But with persistence, the final result is satisfactory. If you are working on a similar feature, I hope this article helps you.

VI. Reference Resources

HarmonyOS Application Development Guide

Welcome to Experience

This privacy popup feature has been integrated into the HarmonyOS Developer Toolbox. Welcome to download and experience it!

HarmonyOS Developer Toolbox

Author: In the World of Development
Email: 1743914721@qq.com
Copyright Notice: This article is an original work by the CSDN blogger, please include the original source link and this statement when reprinting.