--- doc_id: GOV-001 title: "README" owner: 文档治理团队 approver: 业务与技术负责人 status: active version: 1.0.0 classification: internal last_reviewed: 2026-08-25 next_review: 2027-02-21 --- # 百宝工具箱 ToolBox Pro · 鸿蒙原生版 兼容多系统的本地离线工具箱。参考 QQ 浏览器工具箱设计，主打文件处理与开发辅助。 **所有计算均在设备本地完成，不联网、不上传、不依赖任何云 API**，适合个体开发者上架。 本工程为 **纯血鸿蒙原生版（ArkTS）**，同一套代码可运行于： - HarmonyOS 4.x（你的大型科技企业 4.3 手机）✅ - HarmonyOS NEXT（纯血鸿蒙）✅ > Android 版 / 通用版（桌面+Web）/ iOS 版 将在后续批次实现，iOS 最后做。 --- ## 一、技术栈 - 语言：ArkTS - UI：ArkUI（声明式，Stage 模型） - 编译目标：compatibleSdkVersion 10（兼容 HarmonyOS 4.0+ 与 NEXT） - 仅使用 HarmonyOS 4.x 公开标准 Kit，未使用 NEXT 专属 API，可广泛运行于各类大型科技企业设备 - 系统能力： - `@ohos.security.cryptoFramework`（MD5/SHA 哈希） - `@ohos.util.Base64Helper` / `@ohos.buffer`（编解码） - `@ohos.resourceManager`（rawfile 字典加载） - `@ohos.pasteboard`（复制） - `@ohos.file.picker`（PhotoViewPicker / DocumentViewPicker 选择文件） - `@ohos.file.fs`（文件读写） - `@ohos.multimedia.image`（图片解码 / 编码 / PixelMap 操作） - `@ohos.zlib`（ZIP 解压） - `Canvas` / `CanvasRenderingContext2D` / `OffscreenCanvasRenderingContext2D`（绘制） --- ## 二、工程结构 ``` ToolBoxPro-HarmonyOS/ ├── AppScope/ │ ├── app.json5 # 应用配置（bundleName/version） │ └── resources/base/ │ ├── element/string.json # 应用名 │ └── media/app_icon.jpg # 应用图标 ├── entry/ # 主模块 │ ├── src/main/ │ │ ├── ets/ │ │ │ ├── entryability/EntryAbility.ets │ │ │ ├── pages/ # 页面 │ │ │ │ ├── Index.ets # 首页（分类+全部工具+搜索） │ │ │ │ ├── CategoryPage.ets # 分类详情 │ │ │ │ ├── ToolRunnerPage.ets # 工具分发器 │ │ │ │ └── SettingsPage.ets # 设置/关于 │ │ │ ├── components/ToolCommon.ets # 通用组件（头部/按钮/IO卡片/规划占位） │ │ │ ├── model/ToolRegistry.ets # 工具元数据注册表 │ │ │ ├── tools/ │ │ │ │ ├── dev/ # 开发工具（6） │ │ │ │ ├── text/ # 文本工具（6） │ │ │ │ ├── image/ # 图片工具（4） │ │ │ │ ├── compress/ # 压缩包工具（3） │ │ │ │ ├── pdf/ # PDF 工具（4） │ │ │ │ └── media/ # 多媒体工具（3） │ │ │ └── utils/ # 工具库 │ │ │ ├── theme.ets │ │ │ ├── CryptoUtil.ets # 哈希/字节 │ │ │ ├── EncodingUtil.ets # Base64/URL/进制 │ │ │ ├── QRCodeUtil.ets # 二维码生成器（纯TS） │ │ │ ├── DictLoader.ets # 拼音/简繁字典加载 │ │ │ ├── ImageUtil.ets # 图片选择/读写/打包 │ │ │ └── ZipUtil.ets # ZIP 写入/解压/CRC32 │ │ ├── resources/ │ │ │ ├── base/ # 字符串/颜色/字号/路由 │ │ │ ├── dark/ # 暗色模式 │ │ │ └── rawfile/ # 字典数据 │ │ │ ├── pinyin.txt # 拼音字典（4.4万条） │ │ │ ├── s2t.txt # 简转繁映射 │ │ │ └── t2s.txt # 繁转简映射 │ │ └── module.json5 │ ├── build-profile.json5 │ ├── hvigorfile.ts │ └── oh-package.json5 ├── build-profile.json5 # 工程级构建配置 ├── hvigorfile.ts └── oh-package.json5 ``` --- ## 三、已实现功能（v1.0.0，共 26 个工具） ### ✅ 开发工具（6，全部可用） | 工具 | 说明 | |---|---| | 哈希计算 | MD5 / SHA-1 / SHA-224 / SHA-256 / SHA-384 / SHA-512 | | Base64 | 编码 / 解码（非法输入容错） | | URL编解码 | encodeURIComponent / decodeURIComponent | | 进制转换 | 二/八/十/十六进制互转，**支持大整数**（无精度丢失） | | JSON格式化 | 美化 / 压缩 / 语法校验 | | 二维码生成 | 字节模式，版本 1-40 自动选版，L/M/Q/H 纠错，8 种掩码，Reed-Solomon 纠错 | ### ✅ 文本工具（6，全部可用） | 工具 | 说明 | |---|---| | 字数统计 | 字符/词数/行数/中英文/数字/标点/UTF-8 字节 | | 排序去重 | 升降序 / 去重 / 反转 / 按长度排序 | | 文本对比 | 基于 LCS 的逐行差异（+/- 标记 + 统计） | | 大小写转换 | 全大/全小/首字母大写/句首大写/反转/全角转半角 | | 拼音转换 | 汉字转拼音，带声调/无声调可选，覆盖 4.4 万字 | | 简繁转换 | 简体 ⇄ 繁体 互转，基于 OpenCC 字符映射 | ### ✅ 图片工具（4，全部可用） | 工具 | 说明 | |---|---| | 图片压缩 | JPEG/WebP 输出，质量 10-100% 可调，自动计算压缩率 | | 格式转换 | PNG / JPEG / WebP 互转 | | 加水印 | 文字水印，字号/颜色/透明度/位置（4 角）可调 | | 九宫格切图 | 一张图居中裁剪为正方形后切成 3x3 共 9 张朋友圈图 | ### ✅ 压缩包工具（2 可用 + 1 规划中） | 工具 | 说明 | |---|---| | ZIP压缩 | 多文件打包为 ZIP（STORED 归档模式，纯 TS 实现，含 CRC32） | | 解压压缩包 | @ohos.zlib 解压 ZIP/GZ 到沙箱并列表展示（RAR/7Z 不支持） | | 密码管理 | 规划中：ZIP 加密需 NAPI 集成 minizip-ng | ### 🚧 PDF 工具（4，全部规划中） | 工具 | 说明 | |---|---| | PDF合并 | 规划中：需 NAPI 集成 pdfium | | PDF拆分 | 规划中：需 NAPI 集成 pdfium | | PDF转图片 | 规划中：需 NAPI 集成 pdfium 渲染引擎 | | PDF加水印 | 规划中：需 NAPI 集成 pdfium 内容流注入 | ### 🚧 多媒体工具（3，全部规划中） | 工具 | 说明 | |---|---| | 视频转GIF | 规划中：需 NAPI 集成 AVCodec 解码视频帧 | | GIF合成 | 规划中：纯 TS GIF89a 编码器（含色彩量化与 LZW） | | m3u8转mp4 | 不支持：涉及网络下载，违反「全本地、无网络」合规原则 | > **状态说明**：✅ = 完全可用；🚧 = 已实现 UI 占位，能力规划中（含技术方案与临时方案） --- ## 四、规划中能力的实现路径 | 模块 | 实现方式 | 难度 | 备注 | |---|---|---|---| | ZIP 加密 | NAPI + minizip-ng | 中 | AES-256 / 传统 ZipCrypto | | RAR / 7Z 解压 | NAPI + unrar / 7zip SDK | 高 | 商用授权注意 | | PDF 合并/拆分/转图/水印 | NAPI + pdfium | 中 | Google Chromium 同款引擎 | | 视频转 GIF | NAPI AVCodec + TS LZW | 高 | 色彩量化在 TS 侧 | | GIF 合成 | 纯 TS GIF89a 编码器 | 中 | 无 NAPI 依赖 | --- ## 五、构建与安装 ### 环境要求 - DevEco Studio 4.1 或更高（推荐 5.0+） - HarmonyOS SDK（API 10+） ### 步骤 1. **打开工程** - DevEco Studio → File → Open → 选择 `ToolBoxPro-HarmonyOS` 目录 2. **同步依赖** - 打开后 IDE 会自动 Sync；若未自动，点击右上角 `Sync Now` 3. **连接手机** - 大型科技企业手机（HarmonyOS 4.3）开启「开发者选项」与「USB 调试」 - USB 连接电脑，手机弹窗选择「允许调试」 4. **运行** - 顶部设备下拉框选中你的手机 - 点击 ▶ Run（或 Shift+F10） - 等待 hvigor 编译并自动安装到手机 5. **签名**（首次运行） - File → Project Structure → Project → Signing Configs - 勾选「Automatically generate signature」自动生成调试证书 - 保存后重新 Run ### 单独构建 HAP ``` hvigorw assembleHap ``` 产物位于 `entry/build/default/outputs/default/entry-default-signed.hap` --- ## 六、字典数据来源与许可 | 文件 | 来源 | 许可 | |---|---|---| | pinyin.txt | [mozillazg/pinyin-data](https://github.com/mozillazg/pinyin-data) | MIT | | s2t.txt / t2s.txt | [BYVoid/OpenCC](https://github.com/BYVoid/OpenCC) | Apache-2.0 | 数据已处理为 `char\tpinyin` 紧凑格式，作为 rawfile 打包，首次使用时解析缓存。 --- ## 七、设计取舍说明（针对个体开发者） - **已剔除所有需调用云 API 的功能**：OCR/AI 证件照/翻译/识别/汇率等。 - **已剔除敏感信息功能**：扫描身份证/银行卡/户口本等，便于应用商店审核。 - **无任何联网权限**，仅本地计算，隐私安全。 - **不实现 m3u8 转 mp4 等涉及网络下载的功能**，确保审核合规。 - **暂未集成 NAPI 第三方库**：ZIP 加密、RAR/7Z 解压、PDF 操作等需要原生库的能力以「规划中」占位形式展示，避免引入审核风险。 --- ## 八、已知问题与后续 - ZIP 压缩当前为 STORED 归档模式（不压缩，仅打包）；DEFLATE 压缩需后续 NAPI 或第三方纯 TS 库实现。 - 二维码建议首次用手机相机扫描验证（若某版本纠错表偏差导致不可扫，反馈后修正）。 - 多音字拼音取首个常用读音。 - 图片水印使用 OffscreenCanvas 绘制，大图可能耗时；超过 4000px 的图建议先压缩。 --- ## 九、后续端规划 | 端 | 形态 | 技术栈 | 优先级 | |---|---|---|---| | 纯血鸿蒙版 | 原生 App | ArkTS / ArkUI（本工程） | ✅ 已完成 | | 通用版 | 桌面 App + Web | Tauri (Rust) + Web 前端 / SPA + WASM | 中 | | 安卓版 | 原生 App | Kotlin / Jetpack Compose | 中 | | iOS 版 | 原生 App | Swift / SwiftUI | 低（最后做） | 如需新增端（Android / 桌面+Web / iOS），告诉我即可继续。