HarmonyOS + uni-app x Real-World Dev Guide & Pitfalls

About HarmonyOS 5

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

About the Author

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

Basic Knowledge

Let's first understand the basics of developing HarmonyOS applications with uni-app x:

1. uni-app x

   • A cross-platform framework supporting HarmonyOS Next (from version 4.61+)
   • Can compile directly to ArkTS native applications
   • Supports rapid development and multi-platform deployment

2. Development Tools

   • HBuilderX: Main IDE for uni-app x
   • DevEco Studio: Official HarmonyOS IDE
   • HarmonyOS device: API version 14+

3. Key Concepts

   • Manifest and harmony-config for project configuration
   • Permission management
   • Module and component usage
   • Performance and memory management

Preface

Recently, while developing HarmonyOS applications, I discovered that uni-app x has supported Pure Harmony (Harmony Next) since version 4.61, allowing direct compilation into ArkTS native applications. Here, I share some experiences and pitfalls encountered during the development process.

I. Environment Setup

1.1 Development Tools

• HBuilderX 4.61+ (required)
• DevEco Studio 5.0.7.210+ (required)
• HarmonyOS phone with API version 14+ (required)

1.2 Pitfalls

1. DevEco Studio Installation

   • The download is very large, over 10GB
   • Ensure enough disk space during installation
   • SSD is recommended; mechanical hard drives are too slow

2. Certificate Issues

   • Debug certificates must be applied for manually
   • Real device debugging requires signing
   • Pay attention to certificate validity period

II. Development Process

2.1 Project Creation

1. Create a new project in HBuilderX
2. Select the HarmonyOS platform
3. Configure manifest.json
4. Configure harmony-config

2.2 Issues Encountered During Development

1. Compilation Issues

   • Every code change requires a rebuild
   • No hot update, which is inconvenient
   • Breakpoint debugging is available

2. Performance Issues

   • Pay special attention to memory leaks
   • ArkTS engine is still being optimized
   • Use complex animations with caution

3. UI Issues

   • Landscape mode is not supported
   • rpx units are not available
   • Fonts must be updated manually

2.3 Code Example

// A simple page
@Entry
@Component
struct Index {
  @State message: string = 'Hello HarmonyOS'

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

2.4 Module Configuration

Example manifest.json configuration:

{
  "app-harmony": {
    "distribute": {
      "modules": {
        "uni-location": {
          "system": {} // Location module
        },
        "uni-map": {
          "tencent": {} // Map module
        },
        "uni-oauth": {
          "huawei": {} // Huawei login
        }
        // Other modules...
      }
    }
  }
}

2.5 Permission Configuration

harmony-config/permissions.json:

{
  "permissions": [
    "ohos.permission.INTERNET",
    "ohos.permission.LOCATION",
    "ohos.permission.READ_MEDIA",
    "ohos.permission.WRITE_MEDIA"
  ]
}

III. Debugging and Release

3.1 Debugging Methods

1. HBuilderX Debugging

   • Log viewing
   • Breakpoint debugging
   • Performance analysis

2. DevEco Studio Debugging

   • Memory analysis
   • Performance analysis
   • Deep debugging

3.2 Release Process

1. Prepare certificates
2. Configure information
3. Package and sign
4. Upload to the app market

IV. Pitfalls and Lessons

4.1 Development Pitfalls

1. Windows Path Issues

   • Paths that are too long will cause errors
   • Keep project paths short
   • The uni_modules directory name should be short

2. Permission Issues

   • Permissions must be configured manually
   • The application process is complex
   • Easy to miss configurations

3. Component Issues

   • rich-text has issues
   • animateTo animation has issues
   • Some components are not compatible

4.2 Performance Pitfalls

1. Memory Issues

   • Release memory in time
   • Avoid leaks
   • Watch for circular references

2. Rendering Issues

   • Control component nesting
   • Avoid excessive rendering
   • Pay attention to performance overhead

V. Experience Summary

5.1 Development Suggestions

1. Use TypeScript
2. Follow best practices
3. Handle errors properly
4. Focus on performance optimization
5. Import modules as needed

5.2 Project Structure

project/
├── src/
│   ├── pages/
│   ├── components/
│   ├── utils/
│   └── static/
├── harmony-config/
└── manifest.json

VI. Conclusion

Developing HarmonyOS applications with uni-app x, although there are still many limitations, most basic functions can be implemented. Pay attention to performance optimization and avoid memory leaks during development. As HarmonyOS continues to improve, the development experience should get better and better.

Reference Resources

• uni-app x HarmonyOS Development Guide
• HarmonyOS Development Documentation

Welcome to Experience

This uni-app x HarmonyOS application development practice has been integrated into the HarmonyOS Developer Toolbox. Welcome to download and experience it!

HarmonyOS Developer Toolbox

---

Author: In the World of Development
Email: [e-mail]
Copyright Notice: This article is an original work by the CSDN blogger, please include the original source link and this statement when reprinting.