《文件查询》一、小说查询案例总体介绍指南

HarmonyOS 小说查询应用：TaskPool 多线程 + 状态管理 V2 + Navigation 导航 全栈实战

效果

前言

本文完整介绍一个基于 HarmonyOS (API 23) 开发的小说文件查询应用。该应用综合运用了 TaskPool 多线程并发、State Management V2 状态管理和 Navigation 页面导航三大核心技术，实现了从文件初始化、关键词搜索、分类筛选、多维排序到详情查看的完整功能链路。

本文作为案例的总体介绍，帮助你快速了解应用的整体架构、功能效果和核心设计思路。如需深入了解某个模块的实现细节，请参考系列中的其他指南文档。

系列文档：

1. 📘 @ohos.taskpool 使用指南 — TaskPool API 详解与使用规范
2. 📗 小说文件查询案例指南 — 基础查询功能的完整实现过程
3. 📙 Navigation 页面导航实现指南 — 详情页跳转功能的添加步骤
4. 📕 本文 — 案例总体介绍与效果展示

一、应用概述

1.1 应用定位

一个面向 HarmonyOS 开发者的教学级示范应用，通过一个实用的小型工具——小说文件查询器，展示如何在实际项目中综合运用 ArkTS 的核心能力。

1.2 核心功能

1.3 技术栈总览

二、效果展示

2.1 首页 — 搜索与列表

┌──────────────────────────────────────┐
│  小说查询                    TaskPool │
├──────────────────────────────────────┤
│  🔍 搜索小说名称、作者或内容...    ✕  │
├──────────────────────────────────────┤
│  全部  科幻  悬疑  文学  历史  现代   │
├──────────────────────────────────────┤
│  共 100 个结果      匹配度 | 大小 | 名称│
├──────────────────────────────────────┤
│ ┌──────────────────────────────────┐ │
│ │ 科幻                  匹配度 100%│ │
│ │ 星际迷航纪                      │ │
│ │ 作者：陈星河                    │ │
│ │ 公元2387年，人类文明已经跨越    │ │
│ │ 太阳系的边界，在半人马座阿尔法  │ │
│ │ 星系建立了第一个星际殖民地...   │ │
│ │ 📄 1.2KB  📅 2024-06-20  星际迷航纪.txt │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ 科幻                  匹配度 80% │ │
│ │ 量子之境                        │ │
│ │ 作者：赵明远                    │ │
│ │ 量子物理学家周子涵在进行一次    │ │
│ │ 高能粒子对撞实验时...           │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ 悬疑                  匹配度 80% │ │
│ │ 古城密码                        │ │
│ │ ...                             │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘

2.2 详情页 — 小说详情

┌──────────────────────────────────────┐
│  ← 星际迷航纪                        │
├──────────────────────────────────────┤
│ ┌──────────────────────────────────┐ │
│ │ 科幻                  匹配度 100%│ │
│ │                                  │ │
│ │ 星际迷航纪                       │ │
│ │ 作者：陈星河                     │ │
│ │ 📄 1.2KB  📅 2024-06-20         │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ 内容简介                         │ │
│ │                                  │ │
│ │ 公元2387年，人类文明已经跨越太阳 │ │
│ │ 系的边界，在半人马座阿尔法星系建 │ │
│ │ 立了第一个星际殖民地。然而，一次 │ │
│ │ 突如其来的空间异变打破了...      │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ 章节目录（共 5 章）              │ │
│ │ 第一章 星海彼岸              →   │ │
│ │ ──────────────────────────────   │ │
│ │ 第二章 空间异变              →   │ │
│ │ ──────────────────────────────   │ │
│ │ 第三章 殖民地危机            →   │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ 全文内容                         │ │
│ │ 标题：星际迷航纪                 │ │
│ │ 作者：陈星河                     │ │
│ │ 分类：科幻                       │ │
│ │ 【内容简介】                     │ │
│ │ 公元2387年，人类文明已经...      │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘

2.3 交互流程

┌─────────┐  输入关键词   ┌─────────┐  300ms 防抖   ┌──────────┐
│  用户输入 │ ──────────→ │ 防抖等待  │ ───────────→ │ TaskPool  │
└─────────┘              └─────────┘               │ 子线程搜索 │
                                                    └─────┬────┘
                                                          │ 返回结果
                                                          ▼
┌─────────┐  点击卡片    ┌─────────┐  pushPath    ┌──────────┐
│  详情页   │ ←────────── │ 导航跳转  │ ←────────── │  列表页   │
│ (NavDest)│  ← 返回     │(NavStack)│             │(Navigation)│
└─────────┘  pop()       └─────────┘             └──────────┘

三、架构设计

3.1 分层架构

┌──────────────────────────────────────────────────────────┐
│  页面层 (Pages)                                           │
│  ┌──────────────────┐    ┌──────────────────────────┐    │
│  │ Index (首页)      │    │ NovelDetailPage (详情页)   │    │
│  │ Navigation 容器   │ ←→ │ NavDestination            │    │
│  │ @ComponentV2      │    │ @ComponentV2 + @Param     │    │
│  └────────┬─────────┘    └────────────┬─────────────┘    │
│           │ @Local viewModel          │ @Local fullContent│
└───────────┼───────────────────────────┼──────────────────┘
            │                           │
┌───────────▼───────────────────────────▼──────────────────┐
│  ViewModel 层                                              │
│  NovelListViewModel (@ObservedV2 + @Trace)                 │
│  - novelList / filteredList / searchKeyword                │
│  - updateFilteredList() / setSortType() / setCategory()    │
└───────────┬────────────────────────────────────────────────┘
            │ 调用
┌───────────▼────────────────────────────────────────────────┐
│  Service 层 (主线程封装)                                     │
│  NovelQueryHelper                                            │
│  - initFiles(seeds) → 初始化文件                             │
│  - search(keyword) → 搜索小说                                │
│  - readContent(filePath) → 读取全文                          │
└───────────┬────────────────────────────────────────────────┘
            │ taskpool.execute
┌───────────▼────────────────────────────────────────────────┐
│  TaskPool 层 (子线程 @Concurrent)                            │
│  - initNovelFiles() → 种子数据写入沙箱                       │
│  - queryNovelFiles() → 文件名/内容匹配                       │
│  - readNovelContent() → 全文读取                             │
│  - fileIo (同步 API，不阻塞主线程)                           │
└────────────────────────────────────────────────────────────┘

3.2 项目目录

entry/src/main/
├── ets/
│   ├── common/
│   │   └── Constants.ets              # 常量定义 + 种子数据 (NOVEL_SEEDS)
│   ├── model/
│   │   └── NovelFileInfo.ets          # 数据模型 + 传输接口
│   ├── service/
│   │   └── NovelQueryService.ets      # @Concurrent 并发函数 + Helper
│   ├── viewmodel/
│   │   └── NovelListViewModel.ets     # 视图模型 (过滤/排序/状态)
│   └── pages/
│       ├── Index.ets                  # 首页 (Navigation 容器)
│       └── NovelDetailPage.ets        # 详情页 (NavDestination)
├── resources/
│   ├── base/
│   │   ├── element/
│   │   │   ├── color.json
│   │   │   ├── float.json
│   │   │   └── string.json
│   │   └── profile/
│   │       └── main_pages.json
│   └── rawfile/
│       └── novels/                    # 参考素材 (非运行时依赖)
│           ├── 星际迷航纪.txt
│           ├── 古城密码.txt
│           ├── 山间岁月.txt
│           ├── 量子之境.txt
│           ├── 长安旧事.txt
│           ├── 深海回声.txt
│           ├── 云端之城.txt
│           ├── 荒漠旅人.txt
│           ├── 时间裂隙.txt
│           └── 雾都迷踪.txt

3.3 模块职责

四、核心设计思路

4.1 种子数据方案

由于 TaskPool 子线程无法通过 fileIo 访问 rawfile 目录，我们采用了种子数据嵌入代码的方案：

NOVEL_SEEDS (代码常量)  ──序列化──→  子线程  ──fileIo──→  沙箱文件
     ↑                                                    │
     │                                                    ↓
  元数据嵌入代码                                      后续查询直接读沙箱
  (不依赖 rawfile)                                   (无路径限制)

100 本原创小说，涵盖 5 个分类（每类 20 篇）：

4.2 跨线程数据传递

子线程 (@Concurrent)                    主线程
┌─────────────────┐                    ┌──────────────────────┐
│ 返回纯 interface │  ──序列化──→       │ 转换为 @ObservedV2    │
│ NovelFileRawData │                    │ NovelFileInfo         │
│ (可序列化)       │                    │ (@Trace 细粒度响应式) │
└─────────────────┘                    └──────────────────────┘

设计原则：

• 子线程只处理纯数据（interface），不接触 UI 框架
• 主线程负责将纯数据转换为响应式对象
• 这种模式保证了线程安全和序列化兼容性

4.3 搜索匹配度评分

4.4 State Management V2 全景

@ObservedV2 NovelListViewModel
├── @Trace novelList: NovelFileInfo[]
├── @Trace filteredList: NovelFileInfo[]
├── @Trace searchKeyword: string
├── @Trace currentCategory: string
├── @Trace currentSort: SortType
├── @Trace isLoading: boolean
├── @Trace totalCount: number
└── @Trace errorMessage: string
        │
        │ 属性级响应式
        ▼
@ObservedV2 NovelFileInfo
├── @Trace title → Text(title)
├── @Trace author → Text(author)
├── @Trace matchScore → Text(matchScore%)
├── @Trace category → Text(category)
└── @Trace preview → Text(preview)
        │
        │ 只有变化的属性触发对应组件重渲染
        ▼
UI 精确刷新（非整体重绘）

4.5 导航架构

Navigation (pathStack)
├── 首页内容 (Column)
│   ├── 自定义标题栏
│   ├── 搜索栏
│   ├── 分类过滤条
│   ├── 排序按钮
│   └── 小说卡片列表 ← 点击卡片 pushPathByName
│
└── NavDestination (NovelDetailPage)
    ├── 系统标题栏 + 返回按钮
    ├── 封面信息区
    ├── 内容简介
    ├── 章节目录
    └── 全文内容

五、性能优化策略

六、关键技术点速查

6.1 State Management V1 → V2 对照

6.2 @Concurrent 函数设计要点

6.3 Navigation 配置速查

七、系列文档索引

本案例共提供 4 份指南文档，覆盖从基础 API 到完整实现的全部内容：

八、源码文件清单

九、运行与体验

9.1 环境要求

• DevEco Studio 6.1+
• HarmonyOS 6.1 SDK (API 23)
• 模拟器或真机

9.2 操作步骤

1. 克隆项目 → 使用 DevEco Studio 打开
2. 同步依赖 → 点击 Sync Now 同步 ohpm 依赖
3. 运行应用 → 选择模拟器/真机，点击 Run
4. 体验首页 → 查看小说列表，尝试搜索和分类筛选
5. 体验详情 → 点击任意小说卡片，进入详情页查看全文
6. 返回首页 → 点击左上角返回箭头

十、总结

本案例展示了一个完整的 HarmonyOS 应用开发流程，涵盖了以下核心能力：

1. TaskPool 多线程：将文件 IO 放在子线程，保证 UI 流畅
2. State Management V2：@ObservedV2 + @Trace 实现细粒度响应式
3. Navigation 导航：NavPathStack 实现栈式页面跳转
4. 跨线程数据传递：纯 interface 序列化 → @ObservedV2 响应式转换
5. 种子数据方案：绕过 rawfile 子线程访问限制

这套技术方案可以直接应用到类似的文件管理类应用中，如文档搜索器、音乐文件管理、图片浏览器等场景。

系列文档：

• 📘 @ohos.taskpool 使用指南 — TaskPool API 详解
• 📗 小说文件查询案例指南 — 查询功能实现
• 📙 Navigation 页面导航实现指南 — 详情页跳转
• 📓 小说初始化实现指南 — 种子数据与批量初始化
• 📕 本文 — 总体介绍与效果展示

参考文档：

• 官方 API - @ohos.taskpool
• TaskPool 文件查询实践
• Navigation 组件
• State Management V2
• @ohos.taskpool