浩瀚唐诗 - HarmonyOS6 应用开发实战

一款基于 HarmonyOS ArkTS 开发的沉浸式古诗词应用，融合传统文化与现代交互体验。

📱 应用介绍

浩瀚唐诗 是一款专注于唐诗阅读与学习的鸿蒙原生应用。它不仅收录了海量经典唐诗，更通过现代化的交互设计，让用户在指尖感受传统文化的魅力。

核心亮点

• 海量诗库：内置近 5 万首唐诗数据，支持离线搜索与浏览。
• 精选赏析：特别收录《唐诗三百首》，提供深度译文与赏析。
• 沉浸阅读：支持全屏阅读模式，配合自定义古风字体与动态背景，营造静谧的阅读氛围。
• 趣味互动：
  • 九宫格游戏：基于诗句的趣味填字挑战，自动记录挑战数据并生成周报图表。
  • 飞花令：智能提取诗中意象，串联诗词脉络。
• 个性化体验：支持全局主题切换、收藏夹管理及阅读足迹自动记录。
• 桌面卡片：提供多种尺寸的服务卡片（Service Widget），让诗词每日可见。

---

🛠️ 技术架构

本项目采用 HarmonyOS 纯血版（API 12+）开发，完全基于 ArkTS 语言与 ArkUI 声明式框架。

技术栈概览

分类	技术选型	说明
开发语言	ArkTS	鸿蒙首选开发语言，基于 TypeScript 扩展
UI 框架	ArkUI	声明式 UI 开发范式，高效构建界面
数据存储	RelationalStore (RDB)	本地 SQLite 数据库，处理海量诗词数据
并发处理	TaskPool	负责数据库初始化与批量写入等耗时任务
路由管理	Navigation + NavPathStack	系统级路由栈，支持更加灵活的页面跳转
图表展示	McCharts	绘制九宫格游戏挑战数据的可视化图表
状态管理	@State / AppStorage / Emitter	组件级与应用级状态同步及事件通信

架构设计

项目采用经典的 分层架构 设计，确保代码的高内聚低耦合：

1. UI Layer (视图层)

   • pages: 页面级组件（如详情页、搜索页），通过 route_map.json 注册。
   • views: 业务视图模块（HomeView, MineView 等），对应底部导航 Tab。
   • components: 可复用原子组件（如诗词卡片 PoemItemComp）。

2. Service Layer (服务层)

   • PoetryRdbService: 核心数据服务单例，封装所有 RDB 操作（增删改查、模糊搜索、分页加载）。
   • ThemeStore: 主题管理服务，负责全局背景切换与持久化存储。
   • NineGridRecordService: 游戏记录管理服务。

3. Data Layer (数据层)

   • models: 定义统一的数据接口（Poem, PoemItem 等），规范数据流转。
   • rawfile: 预置 JSON 数据源，首次启动时导入数据库。

4. Utils (工具层)

   • 全局配置、路由栈封装、日期处理等通用工具。

---

📦 依赖与资源

核心依赖库

• @mcui/mccharts: 用于在“我的”页面展示近一周九宫格游戏挑战次数的折线图。
• check_app_update: 本地模块，用于实现应用内版本检测与更新提示。

关键资源

• 数据源:
  • tang.json: 包含约 4.9 万首全量唐诗数据。
  • tang300.json: 含译文与赏析的精选数据。
• 字体:
  • wk.ttf: 引入文楷字体，为应用提供统一的古风视觉体验。
• 媒体资源:
  • 内置多套精美背景图（app.media.bg, app.media.bg2 等），支持用户自定义切换。

---

🚀 开发实战片段

1. 数据库单例服务

使用 relationalStore 构建单例服务，管理诗词数据的核心逻辑：

// entry/src/main/ets/services/PoetryRdbService.ets
class PoetryRdbService {
  private static instance: PoetryRdbService | null = null;
  // ...
  
  static getInstance(): PoetryRdbService {
    if (!PoetryRdbService.instance) {
      PoetryRdbService.instance = new PoetryRdbService();
    }
    return PoetryRdbService.instance;
  }

  // 模糊搜索实现
  async search(keyword: string): Promise<Poem[]> {
    const predicates = new relationalStore.RdbPredicates(this.config.tableName);
    predicates.like('title', `%${keyword}%`)
      .or().like('author', `%${keyword}%`)
      .or().like('content', `%${keyword}%`);
    // ...
  }
}

2. 全局主题切换

通过 ThemeStore 与 AppStorage 实现全应用背景的一键切换：

// entry/src/main/ets/utils/ThemeStore.ets
export class ThemeStore {
  // 切换主题并持久化
  async switchTheme(ctx: common.Context, index: number) {
    // 保存索引到 Preferences
    await store.put('theme_index', index);
    // 发送全局变更通知
    emitter.emit('theme-changed', { data: { index: index } });
  }
}

3. 九宫格游戏逻辑

利用算法从诗句中提取汉字生成九宫格，并结合 McCharts 展示数据：

// 生成九宫格数据 payload
private buildNineGridPayload(): string {
  // 随机选诗 -> 提取5/7言句 -> 补齐9字 -> 随机打乱
  const shuffled = this.shuffleText(chosen);
  // ...
  return JSON.stringify(payload);
}

---

结语：通过本项目，我们不仅实践了 HarmonyOS 的全链路开发流程，更探索了如何利用技术手段重现传统文化的精髓。如果你也对鸿蒙开发感兴趣，欢迎一起交流探讨！