DEV Community: 在人间耕耘

pdf-kit-practical-notes

在人间耕耘 — Thu, 26 Jun 2025 09:24:29 +0000

HarmonyOS PDF Kit Practical Notes

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 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)

reader-kit-practical-notes

在人间耕耘 — Thu, 26 Jun 2025 09:23:17 +0000

Reader Kit Practical Notes (HarmonyOS)

About HarmonyOS 5

About the Author

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 Developer Toolbox - Amount Converter Development Notes

在人间耕耘 — Fri, 20 Jun 2025 05:07:23 +0000

HarmonyOS Developer Toolbox - Amount Converter Development Notes

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 Amount Converter, let's briefly review some basic concepts:

Amount Conversion: The process of converting numeric amounts into Chinese uppercase representations, e.g., "1234.56" to "壹仟贰佰叁拾肆元伍角陆分".
Decimal Handling: Managing the number of decimal places, rounding, and formatting.
Zero Handling: Special rules for consecutive zeros and leading zeros in Chinese uppercase conversion.

Preface

Recently, while working on the HarmonyOS Toolbox, I wanted to add an amount conversion feature. At first glance, it seemed simple, but once I started, I realized there were many pitfalls. For example, converting "1234.56" to "壹仟贰佰叁拾肆元伍角陆分" involved handling edge cases, and it took several days of debugging to get it right.

During development, I encountered many issues, such as amount formatting, decimal places, and zero handling. In the end, all problems were solved, and the tool is now quite handy.

I. Feature Overview

1.1 Main Features

Convert numbers to Chinese uppercase
Support for decimals
One-click copy
Favorites feature

1.2 UI Features

Amount input box
Convert button
Result display area
Copy button

II. Implementation Process

2.1 Development Stories

At first, I copied a conversion function from the internet, but it had many issues. For example, entering "1000.00" produced "壹仟元整", but users complained it should be "壹仟元零角零分". I found that different scenarios have different requirements for zeros—sometimes they should be shown, sometimes not.

Another time, a user wanted "0.1" to convert to "零元壹角" instead of just "壹角". I revised the code several times and finally added logic to display "零元" when the integer part is 0.

The most confusing was handling decimals. Initially, there was no limit on decimal places, so "123.456" became "壹佰贰拾叁元肆角伍分陆厘", which confused users. I then limited the output to two decimal places.

2.2 Temporary Solutions

Zero Handling
- Temporary: Use regex to replace consecutive zeros with a single zero
- Problem: Sometimes removes zeros that should be kept, causing strange results
- Final: Use a counter to track consecutive zeros for reliable handling
Large Number Handling
- Temporary: String concatenation, adding one digit at a time
- Problem: Slow and error-prone, especially for large numbers
- Final: Process in segments of four digits for higher efficiency
Decimal Handling
- Temporary: Truncate to two decimal places
- Problem: Sometimes loses precision, users dissatisfied
- Final: Round first, then truncate for better experience
Leading Zero Handling
- Temporary: Remove all leading zeros
- Problem: Users wanted to keep one zero for "00123"
- Final: Keep one zero if all digits are zero, otherwise remove

2.3 Debugging Examples

Amount Formatting

private formatAmount(value: string): string {
  // Remove non-numeric and non-dot characters
  value = value.replace(/[^\d.]/g, '');

  // Handle multiple dots
  const parts = value.split('.');
  if (parts.length > 2) {
    value = parts[0] + '.' + parts[1];
  }

  // Handle decimal places
  if (parts.length === 2) {
    parts[1] = parts[1].slice(0, 2);
    value = parts[0] + (parts[1] ? '.' + parts[1] : '');
  }

  // Handle leading zeros
  if (parts[0].length > 1 && parts[0].startsWith('0')) {
    parts[0] = parts[0].replace(/^0+/, '') || '0';
    value = parts[0] + (parts.length > 1 ? '.' + parts[1] : '');
  }

  // If only a dot is entered, add leading zero
  if (value === '.') {
    value = '0.';
  }

  return value;
}

Amount Validation

private validateAmount(amount: string): boolean {
  this.showError = false;
  this.errorMessage = '';

  if (!amount) {
    this.showError = true;
    this.errorMessage = 'Please enter an amount';
    return false;
  }

  if (!/^\d+(\.\d{0,2})?$/.test(amount)) {
    this.showError = true;
    this.errorMessage = 'Please enter a valid amount format';
    return false;
  }

  const num = parseFloat(amount);

  if (num > this.MAX_AMOUNT) {
    this.showError = true;
    this.errorMessage = 'Amount exceeds the limit';
    return false;
  }

  if (num < this.MIN_AMOUNT) {
    this.showError = true;
    this.errorMessage = 'Amount cannot be less than 0.01';
    return false;
  }

  return true;
}

Conversion Implementation

static numberToChineseMoney(money: string): string {
  const num = parseFloat(money);
  if (isNaN(num)) return 'Invalid amount format';
  if (num === 0) return '零元整';

  const cnNums = ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖'];
  const cnIntRadice = ['', '拾', '佰', '仟'];
  const cnIntUnits = ['', '万', '亿', '兆'];
  const cnDecUnits = ['角', '分'];

  const parts = money.split('.');
  let integerPart = parts[0];
  const decimalPart = parts[1] ? parts[1].substr(0, 2) : '';

  let chineseStr = '';

  // Process integer part
  if (parseInt(integerPart) > 0) {
    let zeroCount = 0;
    const IntLen = integerPart.length;
    for (let i = 0; i < IntLen; i++) {
      const n = parseInt(integerPart.substr(i, 1));
      const p = IntLen - i - 1;
      const q = p / 4;
      const m = p % 4;

      if (n === 0) {
        zeroCount++;
      } else {
        if (zeroCount > 0) {
          chineseStr += cnNums[0];
        }
        zeroCount = 0;
        chineseStr += cnNums[n] + cnIntRadice[m];
      }

      if (m === 0 && zeroCount < 4) {
        chineseStr += cnIntUnits[q];
      }
    }
    chineseStr += '元';
  }

  // Process decimal part
  if (decimalPart) {
    for (let i = 0; i < decimalPart.length; i++) {
      const n = parseInt(decimalPart.substr(i, 1));
      if (n !== 0) {
        chineseStr += cnNums[n] + cnDecUnits[i];
      }
    }
  }

  if (!decimalPart) {
    chineseStr += '整';
  }

  return chineseStr;
}

III. Pitfalls and Lessons

3.1 Problems Encountered

Amount Format Issues
- Problem: Users enter irregular formats, e.g., multiple dots
- Solution: Add formatting function to auto-handle
- Suggestion: Restrict format at input to avoid trouble
Decimal Places Issues
- Problem: Decimal places not fixed
- Solution: Always keep two decimal places
- Suggestion: Allow user customization if needed
Zero Handling Issues
- Problem: Consecutive zeros not handled properly
- Solution: Keep only one zero for multiple zeros
- Suggestion: Add custom options if needed
Amount Range Issues
- Problem: Amount out of range
- Solution: Add range limits
- Suggestion: Allow custom range for flexibility

3.2 Optimization Suggestions

Feature Optimization
- Support more amount formats
- Add history records
- Support batch conversion
- Add amount 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 amount converter tool now covers all basic functions:

Convert numbers to Chinese uppercase
Support for decimal conversion
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 amount 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 Developer Toolbox - Case Converter Development Notes

在人间耕耘 — Fri, 20 Jun 2025 05:05:16 +0000

HarmonyOS Developer Toolbox - Case Converter Development Notes

About HarmonyOS 5

About the Author

Basic Knowledge

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

Case Conversion: The process of converting text between different naming conventions, such as camelCase, PascalCase, snake_case, kebab-case, etc.
Separators: Characters like spaces, hyphens, underscores, and dots used to split words in different formats.
Capitalization: Adjusting the case of the first letter or all letters in a word or phrase.

Preface

Recently, while working on the HarmonyOS Toolbox, I wanted to add a case conversion feature. The main purpose is to convert between various naming formats, such as turning "hello world" into "HelloWorld", "HELLO_WORLD", "hello-world", etc. At first, I thought it would be simple, but I soon realized that handling all the formats was tricky and required several rounds of debugging.

During development, I encountered many pitfalls, such as separator handling, capitalization, and special character processing. In the end, all issues were resolved, and the tool is now quite handy.

I. Feature Overview

1.1 Main Features

Support for 14 different text format conversions
Real-time preview of conversion results
One-click copy of results
Favorites feature

1.2 UI Features

Text input box
Format selection list
Result display area
Copy button

II. Implementation Process

2.1 Development Stories

At first, I used a conversion function found online, but it had many issues. For example, when entering "hello-world", the output was "helloWorld", but users said it should be "helloWorld". I found that different scenarios require different handling of separators, sometimes keeping them, sometimes removing them.

Another time, a user wanted to see "HelloWorld" when converting "hello_world" to "helloWorld". This requirement made me revise the code several times, and I finally added logic to capitalize the first letter as needed.

The funniest was handling special characters. Initially, I didn't process special characters, so when users entered "hello@world", the output was "hello@world", but users said the "@" should be treated as a separator. I then updated the code to treat special characters as separators, which made users happy.

2.2 Temporary Solutions

Separator Handling
- Temporary: Use regex to replace separators with spaces (quick and dirty)
- Problem: Sometimes replaces separators that shouldn't be replaced, causing strange results
- Final: Use regex to split input text and keep separators as needed
Capitalization
- Temporary: Convert all to uppercase, regardless of position
- Problem: Sometimes capitalizes letters that shouldn't be capitalized
- Final: Capitalize as needed based on format type
Special Character Handling
- Temporary: Ignore special characters
- Problem: Users wanted special characters treated as separators
- Final: Treat special characters as separators
Format Selection
- Temporary: Use dropdown for format selection
- Problem: Not user-friendly, users had to try each one
- Final: Use Radio component for easy switching

2.3 Debugging Examples

Conversion Implementation

private convertCase(text: string, type: CaseType): string {
  const words = text.trim().split(/[\s-_./]+/)

  switch (type) {
    case CaseType.LOWER:
      return text.toLowerCase()

    case CaseType.UPPER:
      return text.toUpperCase()

    case CaseType.CAMEL:
      return words.map((word, index) => 
        index === 0 ? word.toLowerCase() : 
        word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
      ).join('')

    case CaseType.CAPITAL:
      return words.map(word => 
        word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
      ).join(' ')

    case CaseType.CONSTANT:
      return words.map(word => word.toUpperCase()).join('_')

    case CaseType.DOT:
      return words.map(word => word.toLowerCase()).join('.')

    case CaseType.HEADER:
      return words.map(word => 
        word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
      ).join('-')

    case CaseType.DEFAULT:
      return words.map(word => word.toLowerCase()).join('-')

    case CaseType.PARAM:
      return words.map(word => word.toLowerCase()).join('_')

    case CaseType.PASCAL:
      return words.map(word => 
        word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
      ).join('')

    case CaseType.PATH:
      return words.map(word => word.toLowerCase()).join('/')

    case CaseType.SENTENCE:
      return words.map((word, index) => 
        index === 0 ? word.charAt(0).toUpperCase() + word.slice(1).toLowerCase() :
        word.toLowerCase()
      ).join(' ')

    case CaseType.SNAKE:
      return words.map(word => word.toLowerCase()).join('_')

    case CaseType.MOCK:
      return text.split('').map((char, index) => 
        index % 2 === 0 ? char.toLowerCase() : char.toUpperCase()
      ).join('')

    default:
      return text
  }
}

Format Selection Implementation

enum CaseType {
  LOWER = 'lower',         // lower case: hello world
  UPPER = 'upper',         // upper case: HELLO WORLD
  CAMEL = 'camel',         // camel case: helloWorld
  CAPITAL = 'capital',     // capital case: Hello World
  CONSTANT = 'constant',   // constant case: HELLO_WORLD
  DOT = 'dot',            // dot case: hello.world
  HEADER = 'header',      // header case: Hello-World
  DEFAULT = 'default',    // default case: hello-world
  PARAM = 'param',        // param case: hello_world
  PASCAL = 'pascal',      // pascal case: HelloWorld
  PATH = 'path',          // path case: hello/world
  SENTENCE = 'sentence',  // sentence case: Hello world
  SNAKE = 'snake',        // snake case: hello_world
  MOCK = 'mock'           // mock case: hElLo WoRlD
}

III. Pitfalls and Lessons

3.1 Problems Encountered

Separator Handling
- Problem: Users enter irregular formats, e.g., multiple separators
- Solution: Use regex to split and auto-handle
- Suggestion: Restrict format at input to avoid trouble
Capitalization
- Problem: Inconsistent capitalization
- Solution: Capitalize as needed based on format type
- Suggestion: Allow user customization
Special Character Handling
- Problem: Special characters not handled properly
- Solution: Treat special characters as separators
- Suggestion: Add custom options if needed
Format Selection
- Problem: Format selection not convenient
- Solution: Use Radio component
- Suggestion: Allow custom formats

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 case converter tool now covers all basic functions:

Support for 14 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 case 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 Developer Toolbox - Color Converter Development Notes

在人间耕耘 — Fri, 20 Jun 2025 05:01:47 +0000

HarmonyOS Developer Toolbox - Color Converter Development Notes

About HarmonyOS 5

About the Author

Basic Knowledge

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

HEX: A hexadecimal color code, e.g., #FF0000.
RGB: Red, Green, Blue color model, e.g., rgb(255, 0, 0).
HSL: Hue, Saturation, Lightness color model, e.g., hsl(0, 100%, 50%).
Color Space Conversion: The process of converting between different color representations.

Preface

Recently, while working on the HarmonyOS Toolbox, I wanted to add a color conversion feature. The main purpose is to convert between various color formats, such as converting "#FF0000" to "rgb(255, 0, 0)" or "hsl(0, 100%, 50%)". At first, I thought it would be simple, but I soon realized that handling all the formats was tricky and required several rounds of debugging.

During development, I encountered many pitfalls, such as color format validation, color space conversion, and implementing a color picker. In the end, all issues were resolved, and the tool is now quite handy.

I. Feature Overview

1.1 Main Features

Support conversion between multiple color formats: HEX, RGB, HSL
Visual color picker
Quick selection of common colors
Precise adjustment of HSL parameters
Real-time preview of conversion results
One-click copy of results
Favorites feature

1.2 UI Features

Text input box
Color picker
Format selection list
Result display area
Copy button

II. Implementation Process

2.1 Development Stories

At first, I used a conversion function found online, but it had many issues. For example, when entering "#FFF", the output was "rgb(255, 255, 255)", but users said it should be "rgb(255, 255, 255, 1)". I found that different scenarios require different handling of color formats, sometimes with alpha, sometimes without.

Another time, a user wanted to see "hsl(0, 100%, 50%)" when converting "rgb(255, 0, 0)" to "#FF0000". This requirement made me revise the code several times, and I finally added logic to convert based on the selected format.

The funniest was handling HSL conversion. Initially, I didn't support HSL, but users insisted on it. After adding HSL conversion, I found that converting HSL to RGB sometimes produced errors, such as out-of-range hue values. After several revisions, it finally worked.

There was also a small episode where a user said the color picker was not easy to use. At first, I thought it was simple, but after trying it myself, I found issues such as selecting the wrong color and the preview not being intuitive. After several iterations, I added a magnifier effect, which improved the experience.

2.2 Temporary Solutions

Color 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
Color Space Conversion
- Temporary: Convert directly to RGB, ignore other formats
- Problem: Sometimes converts formats that shouldn't be converted, causing user dissatisfaction
- Final: Determine whether conversion is needed based on format type
Color Picker
- Temporary: Use system color picker
- Problem: Users said it was not user-friendly, wanted customization
- Final: Implement a custom color picker for better experience
HSL Adjustment
- Temporary: Input HSL values in a text box
- Problem: Users said it was not user-friendly, wanted sliders
- Final: Use sliders for HSL adjustment, improving user experience

2.3 Debugging Examples

Color Format Validation

static isValidHex(color: string): boolean {
  return /^#([A-Fa-f0-9]{3}){1,2}$/.test(color)
}

static isValidRGB(color: string): boolean {
  return /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/.test(color)
}

static isValidHSL(color: string): boolean {
  return /^hsl\(\s*(\d{1,3})\s*,\s*(\d{1,3})%\s*,\s*(\d{1,3})%\s*\)$/.test(color)
}

Color Space Conversion

static hexToRgb(hex: string): string {
  hex = hex.replace('#', '')
  if(hex.length === 3) {
    hex = hex.split('').map(char => char + char).join('')
  }
  const r: number = parseInt(hex.substring(0, 2), 16)
  const g: number = parseInt(hex.substring(2, 4), 16)
  const b: number = parseInt(hex.substring(4, 6), 16)
  return `rgb(${r}, ${g}, ${b})`
}

static rgbToHex(rgb: string): string {
  const matches: RegExpMatchArray | null = rgb.match(/^rgb\((\d+),\s*(\d+),\s*(\d+)\)$/)
  if (!matches) return rgb
  const r: number = parseInt(matches[1])
  const g: number = parseInt(matches[2])
  const b: number = parseInt(matches[3])
  const toHex = (n: number): string => {
    const hex = n.toString(16)
    return hex.length === 1 ? '0' + hex : hex
  }
  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
}

III. Pitfalls and Lessons

3.1 Problems Encountered

Color 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
Color Space Conversion
- Problem: Inaccurate conversion results
- Solution: Determine by format type
- Suggestion: Allow user customization
Color Picker
- Problem: Picker not user-friendly
- Solution: Implement custom picker
- Suggestion: Allow custom pickers
HSL Adjustment
- Problem: Adjustment not convenient
- Solution: Use sliders
- Suggestion: Allow custom adjustment 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 color 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 color 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 Developer Toolbox - Timestamp Converter Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:29:31 +0000

HarmonyOS Developer Toolbox - Timestamp Converter Development Notes

About HarmonyOS 5

About the Author

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 Developer Toolbox - HTTP Request Tester Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:26:58 +0000

HarmonyOS Developer Toolbox - HTTP Request Tester Development Notes

About HarmonyOS 5

HarmonyOS 5 (also known as HarmonyOS Next) is a significant 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

Basic Knowledge

Before diving into the HTTP Request Tester, let's briefly review some basic concepts:

HTTP (HyperText Transfer Protocol): The foundation of data communication for the web, supporting various request methods (GET, POST, PUT, DELETE, etc.).
Query Parameters: Key-value pairs appended to the URL to pass data to the server.
Request Headers: Metadata sent with HTTP requests to provide information about the request or the client.
Request Body: The data sent with POST/PUT requests, often in JSON or form-data format.
Response Formatting: Making server responses readable and easy to analyze.

Preface

Recently, while working on the HarmonyOS Toolbox, I decided to add an HTTP request testing feature. The goal was to make interface testing simple and intuitive. At first, I thought it would be easy, but I soon encountered challenges with request methods, parameters, headers, bodies, and error handling.

During development, I faced many pitfalls, such as request encapsulation, error handling, and parameter processing. After several iterations, the tool became stable and user-friendly.

I. Feature Overview

1.1 Main Features

Support for GET, POST, PUT, DELETE request methods
URL auto-completion and validation
Support for query parameters
Custom request headers
Multiple request body formats (Form-data/JSON)
Automatic JSON response formatting
Copy response content
Favorites feature

1.2 UI Features

URL input box
Request method selector
Parameter configuration area
Request body editor
Response display area
Send button

II. Implementation Process

2.1 Development Stories

At first, I used the system's built-in http module, but quickly ran into problems. For example, if a frontend developer sent a malformed request, the program would crash. Users wanted friendly error messages, so I had to add try-catch blocks and provide detailed feedback.

A backend developer complained that the request headers were not flexible enough. I realized I needed to allow users to add custom headers, so I implemented this feature.

Handling large request bodies was another challenge. Initially, synchronous processing caused the app to freeze with big inputs. I switched to asynchronous processing and added a loading state to improve performance.

The copy-to-clipboard feature also needed refinement. Users wanted feedback when copying succeeded or failed, so I added toast notifications for better UX.

URL auto-completion was also tricky. Users wanted the tool to automatically complete URLs, so I implemented an auto-completion algorithm after several iterations.

Finally, users requested response formatting for better readability. I added automatic formatting for JSON responses to enhance the experience.

2.2 Request Encapsulation

Import Modules

import http from '@ohos.net.http'
import {
  ParamItem,
  SelectOption,
  HttpHeader as CustomHttpHeader,
  HttpOptions
} from '../../common/model/http'
import { HttpUtils } from '../../utils/http'
import router from '@ohos.router'
import promptAction from '@ohos.promptAction'
import clipboard from '@ohos.pasteboard'
import { StorageUtil } from '../../utils/storage'

Request Method Enum

enum HttpMethod {
  GET = 'GET',
  POST = 'POST',
  PUT = 'PUT',
  DELETE = 'DELETE'
}

Request Options Class

class HttpOptions {
  method: string
  header: Record<string, string>
  extraData?: string

  constructor(method: string, header: Record<string, string>) {
    this.method = method
    this.header = header
  }
}

Send Request Function

async sendRequest(): Promise<void> {
  if (this.loading) return
  this.loading = true

  let httpRequest: http.HttpRequest | null = null

  try {
    // 1. Build request URL
    let url = this.url.trim()
    if (!url.startsWith('http://') && !url.startsWith('https://')) {
      url = 'https://' + url
    }

    // 2. Add query parameters
    const enabledParams = this.queryParams.filter(p => p.enabled && p.key.trim())
    if (enabledParams.length > 0) {
      const queryString = enabledParams
        .map(p => `${encodeURIComponent(p.key.trim())}=${encodeURIComponent(p.value.trim())}`)
        .join('&')
      url += url.includes('?') ? '&' : '?'
      url += queryString
    }

    // 3. Build request headers
    const headers: Record<string, string> = {}
    this.headers
      .filter(header => header.enabled && header.key.trim())
      .forEach(header => {
        headers[header.key.trim()] = header.value.trim()
      })

    // 4. Create request options
    const options = new HttpOptions(this.method, headers)

    // 5. Handle request body
    if (this.method !== 'GET') {
      if (this.bodyType === 'form-data') {
        const formData: Record<string, string> = {}
        this.bodyParams
          .filter(param => param.enabled && param.key.trim())
          .forEach(param => {
            formData[param.key.trim()] = param.value.trim()
          })
        options.extraData = JSON.stringify(formData)
      } else {
        try {
          JSON.parse(this.jsonBody) // Validate JSON format
          options.extraData = this.jsonBody
        } catch {
          this.response = 'Request body JSON format error'
          this.loading = false
          return
        }
      }
    }

    // 6. Send request
    console.info('Request URL:', url)
    console.info('Request Options:', JSON.stringify(options))

    httpRequest = http.createHttp()
    const result = await httpRequest.request(url, options)

    // 7. Handle response
    if (result.responseCode === 200) {
      this.response = this.formatResponse(result.result as ResponseType)
    } else {
      this.response = `Request failed: ${result.responseCode}\n${JSON.stringify(result.result, null, 2)}`
    }
  } catch (error) {
    console.error('Request error:', error)
    this.response = `Request error: ${error instanceof Error ? error.message : String(error)}`
  } finally {
    if (httpRequest) {
      httpRequest.destroy()
    }
    this.loading = false
  }
}

2.3 Temporary Solutions

Request Method Issue
- Temporary: Use http module directly
- Problem: Crashes on format errors, poor UX
- Final: Add try-catch and friendly error messages
Request Header Issue
- Temporary: Fixed headers
- Problem: Not flexible
- Final: Add custom header feature
Large Request Body Issue
- Temporary: Synchronous processing
- Problem: Freezes on large bodies
- Final: Asynchronous processing with loading state
Copy Function Issue
- Temporary: Direct copy
- Problem: No feedback
- Final: Add copy success notification
URL Auto-completion Issue
- Temporary: Manual input
- Problem: Poor UX
- Final: Add auto-completion feature
Response Formatting Issue
- Temporary: Direct display
- Problem: Not intuitive
- Final: Add formatting feature

III. Pitfalls and Lessons

3.1 Problems Encountered

Request Method Issue
- Problem: Crashes on format errors
- Solution: Add try-catch
- Suggestion: Provide friendly error messages
Request Header Issue
- Problem: Not flexible
- Solution: Add custom headers
- Suggestion: Let users add their own
Large Request Body Issue
- Problem: Freezes
- Solution: Asynchronous processing
- Suggestion: Add loading state
Copy Function Issue
- Problem: No feedback
- Solution: Add notification
- Suggestion: Handle errors
URL Auto-completion Issue
- Problem: Poor UX
- Solution: Add auto-completion
- Suggestion: Optimize algorithm
Response Formatting Issue
- Problem: Not intuitive
- Solution: Add formatting
- Suggestion: Support more formats

3.2 Optimization Suggestions

Feature Optimization
- Support more request methods
- Add history records
- Support batch requests
- Add request categorization, import/export, management, sharing, backup, etc.
Performance Optimization
- Optimize request 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 HTTP Request Tester tool now covers all basic functions:

Support for multiple request methods
Support for various parameter formats
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 HTTP Request Tester 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 Developer Toolbox - JSON Formatter Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:25:03 +0000

HarmonyOS Developer Toolbox - JSON Formatter Development Notes

About HarmonyOS 5

About the Author

Basic Knowledge

Before diving into the JSON Formatter, let's briefly review some basic concepts:

JSON (JavaScript Object Notation): A lightweight data-interchange format, easy for humans to read and write, and easy for machines to parse and generate.
Indentation: Refers to the number of spaces or tabs used to format JSON for better readability.
Error Handling: Ensuring that invalid JSON or user mistakes do not crash the application, but instead provide friendly feedback.

Preface

Recently, while working on the HarmonyOS Toolbox, I decided to add a JSON formatting feature. The goal was to make messy JSON data neat and readable. At first, I thought it would be simple, but I soon encountered challenges with indentation, line breaks, and error handling.

During development, I faced many pitfalls, such as JSON parsing, error handling, and indentation settings. After several iterations, the tool became stable and user-friendly.

I. Feature Overview

1.1 Main Features

Format JSON text
Customizable indentation (number of spaces)
One-click copy of results
Error prompts for invalid JSON
Real-time preview of formatted results
Favorites for commonly used settings

1.2 UI Features

JSON input box
Indentation setting
Format button
Result display area
Copy button

II. Implementation Process

2.1 Development Stories

At first, I used the system's built-in JSON.parse, but quickly ran into problems. For example, if a user entered malformed JSON, the program would crash. Users wanted friendly error messages, so I had to add try-catch blocks and provide detailed feedback.

A frontend developer friend complained that the indentation was fixed at 2 spaces and not flexible. I realized I needed to allow users to adjust the indentation size, so I added a counter for this purpose.

Handling large JSON files was another challenge. Initially, synchronous processing caused the app to freeze with big inputs. I switched to asynchronous processing and added a loading state to improve performance.

The copy-to-clipboard feature also needed refinement. Users wanted feedback when copying succeeded or failed, so I added toast notifications for better UX.

2.2 Temporary Solutions

JSON Parsing Issue
- Temporary: Directly use JSON.parse (simple but risky)
- Problem: Crashes on invalid JSON
- Final: Add try-catch and user-friendly error messages
Indentation Setting Issue
- Temporary: Fixed at 2 spaces
- Problem: Not flexible
- Final: Add a counter for user adjustment
Large JSON Handling
- Temporary: Synchronous processing
- Problem: Freezes on large JSON
- Final: Asynchronous processing with loading state
Copy Function
- Temporary: Direct copy
- Problem: No feedback
- Final: Add success/failure notifications

2.3 Debugging Examples

JSON Formatting

private async formatJson() {
  if (!this.inputJson) {
    await promptAction.showToast({ message: 'Please enter JSON text' })
    return
  }
  try {
    this.isProcessing = true
    const parsed: object = JSON.parse(this.inputJson)
    this.formattedJson = JSON.stringify(parsed, null, this.indentSize)
    await promptAction.showToast({ message: 'Formatting successful' })
  } catch (err) {
    console.error('JSON formatting failed:', err)
    await promptAction.showToast({ message: 'JSON format error' })
  } finally {
    this.isProcessing = false
  }
}

Copy to Clipboard

private async copyToClipboard(): Promise<void> {
  try {
    const pasteData: pasteboard.PasteData = pasteboard.createData(
      pasteboard.MIMETYPE_TEXT_PLAIN,
      this.formattedJson
    )
    const systemPasteboard = pasteboard.getSystemPasteboard()
    await systemPasteboard.setData(pasteData)
    await promptAction.showToast({ message: 'Copied to clipboard' })
  } catch (err) {
    console.error('Copy failed:', err)
    await promptAction.showToast({ message: 'Copy failed' })
  }
}

III. Pitfalls and Lessons

3.1 Problems Encountered

JSON Parsing
- Problem: Crashes on invalid JSON
- Solution: Add try-catch
- Suggestion: Provide user-friendly error messages
Indentation Setting
- Problem: Not flexible
- Solution: Add a counter
- Suggestion: Let users adjust indentation
Large JSON Handling
- Problem: Freezes on large JSON
- Solution: Asynchronous processing
- Suggestion: Add loading state
Copy Function
- Problem: No feedback
- Solution: Add notifications
- Suggestion: Handle errors gracefully

3.2 Optimization Suggestions

Feature Optimization
- Support more formats
- Add history records
- Support batch formatting
- Add format classification, import/export, management, sharing, backup, etc.
Performance Optimization
- Optimize parsing 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 JSON Formatter tool now covers all basic functions:

JSON formatting
Real-time result preview
One-click copy
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 JSON Formatter 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 QR Code Tool Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:16:05 +0000

HarmonyOS QR Code Tool Development Notes

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!

Jump to App Market Feature Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:14:06 +0000

Jump to App Market Feature Development Notes

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 user experience, feature integration, and cross-app interaction, 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 users often need to quickly jump to the app market for legal consultation. To improve user experience, I decided to develop a legal consultation module that allows users to quickly access related apps. Here I share my development insights.

I. Feature Description

The main features of this module are as follows:

Provide an entry for legal consultation
Support jumping to the app market
Support favorites functionality
Provide user feedback

II. Implementation Process

1. Jump to App Market

// Example: Jump to App Market
jumpToLegalApp() {
  let want: Want = {
    action: 'ohos.want.action.appdetail',
    uri: 'store://appgallery.huawei.com/app/detail?id=zy.zhenlvfalvzixun.law',
  };
  const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
  context.startAbility(want).then(() => {
    promptAction.showToast({ message: 'Redirecting to App Store...' });
  }).catch((error: BusinessError) => {
    console.error('Jump failed:', error);
    promptAction.showToast({ message: 'Jump failed, please try again later' });
  });
}

2. The Awkward Moment of the Favorites Feature

Another time, a user said the favorites 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 favoriting, and sometimes it failed. The user said, "I tried to favorite 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.

// Example: Favorites feature
async toggleFavorite() {
  try {
    if (this.isFavorite) {
      await StorageUtil.removeFavorite('legalAdvice');
      promptAction.showToast({ message: 'Removed from favorites' });
    } else {
      await StorageUtil.addFavorite({
        id: 'legalAdvice',
        name: 'Legal Consultation',
        path: 'pages/Legaladvice/Legaladvice',
        icon: '🤝',
        timestamp: Date.now()
      });
      promptAction.showToast({ message: 'Added to favorites' });
    }
    this.isFavorite = !this.isFavorite;
  } catch (err) {
    console.error('Favorites operation failed:', err);
  }
}

III. Usage Scenarios

Quick Consultation: Users can quickly jump to the app market for legal consultation by clicking a button.
Favorites Feature: Users can favorite frequently used legal consultation entries for quick access next time.
User Feedback: Prompt messages let users know the result of their actions.

IV. Pitfalls and Issues

Sometimes there are permission issues when jumping to the app market (sometimes an error pops up unexpectedly, really frustrating)
Sometimes popups don't appear when using the favorites feature, which is annoying
Sometimes strange errors pop up during user feedback, really frustrating

V. Summary

This legal consultation module covers all the basics:

Supports jumping to the app market
Supports favorites feature
Provides user feedback

To be honest, developing this module 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 jumps or UI stutter when favoriting (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.

VI. Reference Resources

HarmonyOS Application Development Guide

Welcome to Experience

This legal consultation module has been integrated into the HarmonyOS Developer Toolbox. Welcome to download and experience it!

HarmonyOS Developer Toolbox

If you are also developing HarmonyOS apps, feel free to use this module—I hope it helps you!

Author Information

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 Lazy Loading Feature Development Notes

在人间耕耘 — Thu, 19 Jun 2025 05:12:29 +0000

HarmonyOS Lazy Loading Feature Development Notes

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 performance optimization, lazy loading, 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 developing HarmonyOS applications, I found that data loading efficiency is always a headache. To improve user experience, I decided to use lazy loading technology to ensure data is loaded only when needed. Here I share my development insights.

I. Feature Description

The main features of lazy loading are as follows:

Load data on demand
Improve application performance
Reduce memory usage

II. Implementation Process

Story 1: The Lazy Loading Crash Saga

When I first wrote this feature, I directly used the system's built-in lazy loading module, thinking, "Isn't this just calling an API? Easy!" But all sorts of problems followed. The funniest was when a user clicked the load button 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. It was a headache. After several revisions and adding a loading animation, things finally improved.

// Example: Lazy loading
class LazyLoader<T> {
  private dataSource: IDataSource<T>;

  constructor(dataSource: IDataSource<T>) {
    this.dataSource = dataSource;
  }

  loadData(index: number): T {
    return this.dataSource.getData(index);
  }
}

Story 2: The Awkward Data Change Moment

Another time, a user said the data change 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 data changed, and sometimes loading failed. The user said, "Waited so long, 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.

// Example: Data change listener
class DataChangeListener {
  onDataReloaded(): void {}
  onDataAdded(index: number): void {}
  onDataMoved(from: number, to: number): void {}
  onDataDeleted(index: number): void {}
  onDataChanged(index: number): void {}
}

III. Usage Scenarios

On-demand loading: Users can click a button to load data as needed, improving app performance.
Data changes: Users can listen for data changes and update the UI in time.
User feedback: Prompt messages let users know the result of their actions.

IV. Pitfalls and Issues

Sometimes memory issues occur during lazy loading (occasionally OOM, really frustrating)
Sometimes popups don't appear when data changes, which is annoying
Sometimes strange errors pop up during user feedback, really frustrating

V. Complete Example

Here is the code I actually use in development for your reference:

// 1. Define the data source interface
interface IDataSource<T> {
  totalCount(): number;
  getData(index: number): T;
  registerDataChangeListener(listener: DataChangeListener): void;
  unregisterDataChangeListener(listener: DataChangeListener): void;
}

// 2. Define the data change listener
class DataChangeListener {
  onDataReloaded(): void {}
  onDataAdded(index: number): void {}
  onDataMoved(from: number, to: number): void {}
  onDataDeleted(index: number): void {}
  onDataChanged(index: number): void {}
}

// 3. Implement the basic data source class
@Observed
class BasicDataSource<T> implements IDataSource<T> {
  private listeners: DataChangeListener[] = [];
  protected dataArray: T[] = [];

  public totalCount(): number {
    return this.dataArray.length;
  }

  public getData(index: number): T {
    return this.dataArray[index];
  }

  // Set the entire data list
  public setData(array: T[]): void {
    this.dataArray = array;
    this.notifyDataReload();
  }

  // Add a single data item
  public addData(item: T): void {
    this.dataArray.push(item);
    this.notifyDataAdd(this.dataArray.length - 1);
  }

  // Delete a single data item
  public deleteData(index: number): void {
    this.dataArray.splice(index, 1);
    this.notifyDataDelete(index);
  }

  // Update a single data item
  public updateData(index: number, data: T): void {
    this.dataArray[index] = data;
    this.notifyDataChange(index);
  }

  // Clear data
  public clearData(): void {
    this.dataArray = [];
    this.notifyDataReload();
  }

  // Register data change listener
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener);
    }
  }

  // Unregister data change listener
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const index = this.listeners.indexOf(listener);
    if (index >= 0) {
      this.listeners.splice(index, 1);
    }
  }

  // Notify data change methods
  protected notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    });
  }

  protected notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdded(index);
    });
  }

  protected notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChanged(index);
    });
  }

  protected notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDeleted(index);
    });
  }

  protected notifyDataMove(from: number, to: number): void {
    this.listeners.forEach(listener => {
      listener.onDataMoved(from, to);
    });
  }
}

// 4. Usage example
@Component
struct IconList {
  @State iconList: BasicDataSource<IconItem> = new BasicDataSource<IconItem>();

  build() {
    Grid() {
      LazyForEach(this.iconList, (icon: IconItem) => {
        GridItem() {
          Column() {
            Image(icon.symbol)
              .width(24)
              .height(24)
            Text(icon.name)
              .fontSize(12)
          }
        }
      }, (icon: IconItem, index: number) => {
        return icon.name + index
      })
    }
    .columnsTemplate('1fr 1fr 1fr 1fr')
    .rowsGap(8)
    .columnsGap(8)
  }
}

VI. Summary

This lazy loading feature covers all the basics:

Supports on-demand data loading
Supports data change listening
Provides user feedback

To be honest, developing this feature 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 loading or UI stutter during data changes (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.

VII. Reference Resources

HarmonyOS Development Documentation
Lazy Loading Technology Documentation

Welcome to Experience

If you are also developing HarmonyOS apps, feel free to use this feature—I hope it helps you!

Author Information

HarmonyOS Privacy Popup Development Practice

在人间耕耘 — Thu, 19 Jun 2025 05:09:55 +0000

HarmonyOS Privacy Popup Development Practice

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.