HarmonyOS】鸿蒙应用开发中常用的三方库介绍和使用示例

发布于：2025-08-05 ⋅ 阅读:(14) ⋅ 点赞:(0)

 🌟 鸿蒙应用开发常用三方库指南（2025 最新版）

适用版本：HarmonyOS NEXT / API 12+
参考来源：HarmonyOS 三方库中心
截止至 2025 年 8 月 1 日，本文整理了当前社区中下载量高、稳定性强、生态完善的热门三方库，涵盖网络请求、UI 组件、状态管理、数据存储、工具函数及媒体处理等核心模块，帮助开发者快速构建高效、现代化的鸿蒙应用。

一、网络与数据交互

1. @ohos/axios —— 熟悉的 HTTP 客户端

@ohos/axios 是 Axios 在 HarmonyOS 平台的适配版本，支持 Promise 风格的异步请求，语法与 Web 端保持一致，极大降低迁移成本。

✅ 特性
  • 支持 GET/POST/PUT/DELETE 请求
  • 自动 JSON 序列化
  • 拦截器（请求/响应）
  • 超时控制、取消请求
  • HTTPS 安全通信
🔧 安装
{
  "dependencies": {
    "@ohos/axios": "1.3.2"
  }
}
💡 使用示例
import axios from '@ohos/axios';

// 全局配置
axios.defaults.baseURL = 'https://api.example.com';
axios.defaults.timeout = 5000;

// 添加请求拦截器（如鉴权）
axios.interceptors.request.use(
  (config) => {
    const token = 'your-jwt-token';
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// GET 请求
async function fetchUser(id: number) {
  try {
    const response = await axios.get('/user', {
      params: { id }
    });
    console.info('用户数据:', response.data);
    return response.data;
  } catch (error: any) {
    console.error('请求失败:', error.message);
  }
}

// POST 请求
async function createUser(userData: object) {
  const res = await axios.post('/user', userData);
  console.log('创建成功:', res.data);
}

⚠️ 注意：在 module.json5 中需声明网络权限：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }
]

2. @ohos/websocket —— 实时通信支持

适用于聊天、通知推送、实时监控等场景，提供稳定的 WebSocket 客户端能力。

✅ 特性
  • 支持 wss:// 安全连接
  • 消息监听与发送
  • 断线重连机制（需自行实现或使用扩展）
🔧 安装
{
  "dependencies": {
    "@ohos/websocket": "2.1.0"
  }
}
💡 使用示例
import WebSocket from '@ohos/websocket';

const ws = new WebSocket('wss://echo.websocket.org');

ws.onopen = () => {
  console.log('WebSocket 连接成功');
  ws.send('Hello, HarmonyOS!');
};

ws.onmessage = (event) => {
  console.log('收到消息:', event.data);
};

ws.onerror = (event) => {
  console.error('WebSocket 错误:', event);
};

ws.onclose = (code, reason) => {
  console.log(`连接关闭: code=${code}, reason=${reason}`);
};

✅ 建议封装为 Service 类，并集成心跳保活机制。

二、UI 组件与交互

1. @tdesign/arkui-harmonyos —— 企业级 UI 解决方案

由腾讯 TDesign 团队维护，专为 HarmonyOS 设计的企业级 UI 组件库，风格统一、文档完善、支持暗黑模式。

✅ 特性
  • 覆盖按钮、弹窗、表单、列表、导航等 50+ 组件
  • 支持主题定制
  • TypeScript 类型提示完善
  • 开箱即用，适配 ArkUI
🔧 安装
{
  "dependencies": {
    "@tdesign/arkui-harmonyos": "0.8.5"
  }
}
💡 使用示例
import { Button, Dialog } from '@tdesign/arkui-harmonyos';
import { Column } from '@arkui-x/components';

@Entry
@Component
struct TDesignDemo {
  @State showDialog: boolean = false;

  build() {
    Column() {
      Button({ type: 'primary', content: '打开弹窗' })
        .onClick(() => this.showDialog = true)

      Dialog({
        title: '提示',
        content: '这是 TDesign 弹窗组件',
        visible: this.showDialog,
        onClose: () => this.showDialog = false
      })
    }
    .width('100%')
    .padding(20)
  }
}

📌 推荐用于中后台、管理类应用。

2. @ohos/calendar —— 高性能日历组件

支持单选、范围选择、节假日标注、自定义样式等功能，适用于日程、打卡、预约类应用。

🔧 安装
{
  "dependencies": {
    "@ohos/calendar": "3.2.1"
  }
}
💡 使用示例
import { Calendar } from '@ohos/calendar';
import { Column } from '@arkui-x/components';

@Entry
@Component
struct CalendarDemo {
  @State selectedDate: Date = new Date();

  build() {
    Column() {
      Calendar({
        startDate: new Date(2024, 0, 1),
        endDate: new Date(2025, 11, 31),
        selectedDate: this.selectedDate,
        onSelect: (date: Date) => {
          this.selectedDate = date;
          console.log(`选中日期: ${date.toLocaleDateString()}`);
        }
      })
      .width('90%')
      .height(400)
    }
  }
}

✅ 支持农历、节气显示（需启用对应配置）。

三、状态管理

1. @ohos/pinia —— 轻量级状态管理库

灵感来自 Vue 的 Pinia，专为 HarmonyOS 设计的状态管理方案，API 简洁，支持模块化和类型推导。

✅ 特性
  • 模块化 Store 设计
  • 支持 actions、getters、state
  • 与 TypeScript 深度集成
  • 无 mutations，代码更简洁
🔧 安装
{
  "dependencies": {
    "@ohos/pinia": "2.2.3"
  }
}
💡 使用示例
import { createPinia, defineStore } from '@ohos/pinia';

// 创建全局状态容器
const pinia = createPinia();

// 定义用户模块
const useUserStore = defineStore('user', {
  state: () => ({
    name: 'HarmonyOS',
    age: 3
  }),
  getters: {
    doubleAge: (state) => state.age * 2
  },
  actions: {
    incrementAge() {
      this.age++;
    },
    updateName(newName: string) {
      this.name = newName;
    }
  }
});

// 在组件中使用
@Component
struct UserInfo {
  private userStore = useUserStore(pinia); // 注入 store

  build() {
    Column() {
      Text(`姓名: ${this.userStore.name}`)
        .fontSize(18)
      Text(`年龄: ${this.userStore.age}`)
      Text(`双倍年龄: ${this.userStore.doubleAge}`)
      Button('增加年龄')
        .onClick(() => this.userStore.incrementAge())
    }
    .padding(20)
  }
}

✅ 推荐用于中大型应用的状态集中管理。

四、数据存储

1. @ohos/sqlite-orm —— ORM 数据库操作

基于 SQLite 的对象关系映射库，支持实体类注解、自动建表、CRUD 操作，适合结构化数据持久化。

🔧 安装
{
  "dependencies": {
    "@ohos/sqlite-orm": "4.1.0"
  }
}
💡 使用示例
import { Database, Entity, Column, PrimaryGeneratedColumn } from '@ohos/sqlite-orm';

@Entity('user')
class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  age: number;
}

// 初始化数据库
const db = new Database({
  name: 'myApp.db',
  entities: [User],
  version: 1
});

// 数据操作
async function dbOperations() {
  const repo = db.getRepository(User);

  // 插入
  const user = new User();
  user.name = 'Alice';
  user.age = 25;
  await repo.save(user);

  // 查询全部
  const users = await repo.find();
  console.log('用户列表:', users);

  // 条件查询
  const adultUsers = await repo.find({ where: { age: { $gte: 18 } } });
}

✅ 适合存储用户信息、日志、缓存等复杂数据结构。

五、工具类

1. @ohos/lodash —— 实用工具函数库

Lodash 的 HarmonyOS 移植版，提供大量数组、对象、函数操作工具，提升编码效率。

🔧 安装
{
  "dependencies": {
    "@ohos/lodash": "4.17.21"
  }
}
💡 常用方法示例
import _ from '@ohos/lodash';

// 数组去重
const unique = _.uniq([1, 2, 2, 3, 3, 3]); // [1, 2, 3]

// 深拷贝
const obj = { a: 1, b: { c: 2 } };
const copy = _.cloneDeep(obj);

// 防抖（适用于搜索框）
const search = _.debounce((query: string) => {
  console.log('执行搜索:', query);
}, 300);

// 节流（适用于滚动事件）
const scrollHandler = _.throttle(() => {
  console.log('滚动中...');
}, 100);

// 对象取值安全
const name = _.get(user, 'profile.info.name', '默认名称');

✅ 推荐用于处理复杂数据结构或性能优化场景。

六、媒体与图形

1. @ohos/glide —— 图片加载与缓存

仿 Android Glide 设计，支持网络/本地图片加载、内存+磁盘缓存、占位图、错误图、圆角裁剪等。

🔧 安装
{
  "dependencies": {
    "@ohos/glide": "2.3.0"
  }
}
💡 使用示例
import { Glide } from '@ohos/glide';
import { Image } from '@arkui-x/components';

@Component
struct ImageDemo {
  build() {
    Column() {
      Image()
        .width(300)
        .height(200)
        .onAppear(() => {
          // 图片加载
          Glide.with(this)
            .load('https://picsum.photos/300/200')
            .placeholder($r('app.media.placeholder')) // 占位图资源
            .error($r('app.media.error'))           // 加载失败图
            .circleCrop()                            // 圆形裁剪
            .into(this);                             // 绑定到当前 Image
        })
    }
  }
}

✅ 支持 GIF、WebP 等格式（需系统支持）。

✅ 总结：推荐组合方案

功能模块 推荐库 优势说明
网络请求 @ohos/axios 语法熟悉，功能完整
实时通信 @ohos/websocket 原生封装，稳定可靠
UI 组件 @tdesign/arkui-harmonyos 企业级，开箱即用
状态管理 @ohos/pinia 轻量、类型友好
数据库 @ohos/sqlite-orm ORM 提升开发效率
工具函数 @ohos/lodash 开发提效神器
图片加载 @ohos/glide 缓存优化，体验佳

📚 学习建议

  1. 优先使用官方推荐库：通过 OHPM 三方库中心 查看最新版本与兼容性。
  2. 注意权限声明：网络、存储、相机等功能需在 module.json5 中申请对应权限。
  3. 结合 ArkUI 使用：所有 UI 库均基于 ArkUI 构建，建议掌握 @Component、@State 等基础语法。
  4. 关注 TypeScript 支持：现代鸿蒙开发推荐使用 TS，提升类型安全。

📢 更新提示：本文内容基于 2025 年 8 月 1 日 的生态现状整理，三方库版本可能持续更新，请以 OHPM 官网 为准。

✅ 立即开始你的高效鸿蒙开发之旅吧！
📌 收藏本文，作为日常开发的“三方库速查手册”。

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布