前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

doc_text 的 OpenHarmony 插件工程有一个很有意思的特点：零外部依赖。oh-package.json5 的 dependencies 是空的，所有解析逻辑都用系统自带的 API 实现。这篇把工程结构和每个配置文件都过一遍。

一、ohos 目录结构

1.1 完整目录树

ohos/
├── .gitignore                          # Git 忽略规则
├── BuildProfile.ets                    # 构建配置（ArkTS）
├── build-profile.json5                 # 构建配置（JSON）
├── hvigorfile.ts                       # 构建脚本
├── index.ets                           # 入口文件
├── oh-package.json5                    # 包配置
└── src/
    └── main/
        ├── ets/
        │   └── components/
        │       └── plugin/
        │           └── DocTextPlugin.ets   # 插件主文件（684行）
        └── module.json5                    # 模块声明

1.2 各文件职责

二、oh-package.json5 包配置

2.1 完整内容

{
  "name": "doc_text",
  "version": "1.0.0",
  "description": "A Flutter plugin to extract the content of DOC and DOCX files as String.",
  "main": "index.ets",
  "author": "GabbyGreat",
  "license": "Apache-2.0",
  "dependencies": {}
}

2.2 字段说明

字段	值	说明
name	"doc_text"	包名，与 pubspec.yaml 一致
version	"1.0.0"	包版本
description	描述文字	包的功能描述
main	"index.ets"	入口文件路径
author	"GabbyGreat"	原作者
license	"Apache-2.0"	开源协议
dependencies	{}	空！零外部依赖

2.3 零依赖的意义

// doc_text：零依赖
"dependencies": {}

// 对比：某些插件可能需要依赖
"dependencies": {
  "@ohos/some_library": "^1.0.0"
}

doc_text 的所有功能都用系统 API 实现：

功能	使用的系统 API
文件读写	@ohos.file.fs
ZIP 解压	@ohos.zlib
缓冲区操作	@ohos.buffer
XML 相关	@ohos.xml（实际未使用）
文本编解码	@ohos.util

💡 零依赖意味着不会有版本冲突、不会有依赖下载失败、不会有包体积膨胀。这是 doc_text OpenHarmony 实现的一个重要优势。

三、build-profile.json5 构建配置

3.1 完整内容

{
  "apiType": "stageMode",
  "targets": [
    {
      "name": "default"
    }
  ]
}

3.2 字段说明

字段	值	说明
apiType	"stageMode"	Stage 模型（OpenHarmony 推荐）
targets	[{"name": "default"}]	构建目标

这个文件很简单，大多数插件都是这样的配置。

四、module.json5 模块声明

4.1 完整内容

{
  "module": {
    "name": "doc_text",
    "type": "har",
    "deviceTypes": [
      "default",
      "tablet"
    ]
  }
}

4.2 字段说明

字段	值	说明
name	"doc_text"	模块名称
type	"har"	HAR（Harmony Archive）类型
deviceTypes	["default", "tablet"]	支持的设备类型

4.3 与 flutter_web_auth 的对比

// doc_text：简单的 HAR 模块
{
  "module": {
    "name": "doc_text",
    "type": "har",
    "deviceTypes": ["default", "tablet"]
  }
}

// flutter_web_auth：也是简单的 HAR 模块
{
  "module": {
    "name": "flutter_web_auth",
    "type": "har",
    "deviceTypes": ["default", "tablet"]
  }
}

两个插件的 module.json5 几乎一样。不同的是，flutter_web_auth 的宿主应用需要在 module.json5 中配置 skills（深度链接），而 doc_text 不需要——因为 doc_text 不涉及任何系统级交互。

📌 doc_text 不需要宿主应用做任何配置。安装插件后直接用，不需要改 EntryAbility、不需要配置 skills、不需要声明权限。这比 flutter_web_auth 的集成成本低很多。

五、index.ets 入口文件

5.1 完整内容

import DocTextPlugin from './src/main/ets/components/plugin/DocTextPlugin';
export default DocTextPlugin;

5.2 作用

Flutter 引擎加载插件时的查找路径：
1. pubspec.yaml → pluginClass: DocTextPlugin
2. oh-package.json5 → main: "index.ets"
3. index.ets → export default DocTextPlugin
4. 引擎实例化 DocTextPlugin

5.3 为什么需要 index.ets

如果没有 index.ets：
引擎需要知道 DocTextPlugin 在哪个文件里
→ 路径可能很深：src/main/ets/components/plugin/DocTextPlugin.ets
→ 不方便配置

有了 index.ets：
引擎只需要找 main 指向的文件
→ index.ets 负责导出正确的类
→ 解耦了文件路径和包入口

六、hvigorfile.ts 构建脚本

6.1 内容

import { harTasks } from '@ohos/hvigor-ohos-plugin';

export default {
    system: harTasks,
    plugins:[]
}

这是 HAR 模块的标准构建脚本，告诉 hvigor 构建系统使用 HAR 任务来构建这个模块。

七、pubspec.yaml 中的 ohos 平台声明

7.1 关键配置

flutter:
  plugin:
    platforms:
      android:
        package: com.gabbygreat.doc_text
        pluginClass: DocTextPlugin
      ohos:
        package: com.gabbygreat.doc_text
        pluginClass: DocTextPlugin

7.2 字段对照

字段	Android	OpenHarmony
package	com.gabbygreat.doc_text	com.gabbygreat.doc_text
pluginClass	DocTextPlugin	DocTextPlugin

两个平台使用相同的 package 和 pluginClass 名称。这不是必须的，但保持一致可以减少混淆。

7.3 pluginClass 的匹配

# pubspec.yaml
pluginClass: DocTextPlugin

// index.ets
export default DocTextPlugin;

// DocTextPlugin.ets
export default class DocTextPlugin implements FlutterPlugin, MethodCallHandler {
  getUniqueClassName(): string {
    return "DocTextPlugin"  // 必须与 pluginClass 一致
  }
}

三个地方的名称必须一致：

1. pubspec.yaml 的 pluginClass
2. index.ets 的 export default
3. 类的 getUniqueClassName() 返回值

八、与其他插件工程结构的对比

8.1 三个插件的工程对比

维度	doc_text	flutter_web_auth	secure_application
外部依赖	0	0	0
系统 API	fs, zlib, util	无特殊	window
需要宿主配置	❌	✅ (skills + EntryAbility)	❌
需要权限	❌	✅ (INTERNET)	✅ (PRIVACY_WINDOW)
module.json5 复杂度	低	低	低

8.2 doc_text 的集成成本

# 开发者只需要在 pubspec.yaml 中添加依赖
dependencies:
  doc_text:
    git:
      url: https://gitcode.com/oh-flutter/doc_text

// 然后直接使用
final text = await DocText().extractTextFromDoc(filePath);

不需要改任何原生配置文件。这是所有三个插件中集成成本最低的。

8.3 系统 API 使用清单

// doc_text 使用的系统 API
import fs from '@ohos.file.fs';       // 文件读写
import zlib from '@ohos.zlib';        // ZIP 解压
import buffer from '@ohos.buffer';    // 缓冲区操作
import xml from '@ohos.xml';          // XML（导入了但实际用正则）
import util from '@ohos.util';        // TextDecoder 文本编解码

API	用途	使用场景
fs.openSync	打开文件	读取 .doc/.docx
fs.readSync	读取文件内容	读取到 ArrayBuffer
fs.statSync	获取文件信息	获取文件大小
fs.closeSync	关闭文件	释放文件句柄
fs.mkdirSync	创建目录	创建临时解压目录
fs.accessSync	检查文件是否存在	检查 document.xml
fs.listFileSync	列出目录内容	清理临时目录
fs.unlinkSync	删除文件	清理临时文件
fs.rmdirSync	删除目录	清理临时目录
zlib.decompressFile	解压 ZIP	解压 .docx
util.TextDecoder	字节到字符串	XML 内容解码

📌 doc_text 大量使用了 @ohos.file.fs 模块——这是 OpenHarmony 的文件系统 API。几乎每个操作都涉及文件读写，这和 flutter_web_auth（主要是网络和深度链接）形成了鲜明对比。

总结

doc_text 的 OpenHarmony 插件工程有以下特点：

1. 零外部依赖：oh-package.json5 的 dependencies 为空
2. 零宿主配置：不需要改 EntryAbility、skills 或权限
3. 纯文件操作：大量使用 @ohos.file.fs 和 @ohos.zlib
4. 标准 HAR 模块：module.json5 配置简单
5. 集成成本最低：添加依赖后直接使用

下一篇我们看 DocTextPlugin 的接口实现——FlutterPlugin + MethodCallHandler。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• OpenHarmony HAR 模块开发
• oh-package.json5 规范
• @ohos.file.fs 文档
• @ohos.zlib 文档
• doc_text Gitcode 仓库
• Flutter-OHOS 插件开发
• hvigor 构建系统
• 开源鸿蒙跨平台社区