Flutter三方库适配OpenHarmony【doc_text】— OpenHarmony 插件工程搭建与配置文件详解

前言

欢迎加入开源鸿蒙跨平台社区：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 完整内容

json5 复制代码

{
  "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 零依赖的意义

json5 复制代码

// 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 完整内容

json5 复制代码

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

3.2 字段说明

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

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

四、module.json5 模块声明

4.1 完整内容

json5 复制代码

{
  "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 的对比

json5 复制代码

// 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 完整内容

typescript 复制代码

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 内容

typescript 复制代码

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

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

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

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

7.1 关键配置

yaml 复制代码

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 的匹配

yaml 复制代码

# pubspec.yaml
pluginClass: DocTextPlugin

typescript 复制代码

// index.ets
export default DocTextPlugin;

typescript 复制代码

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

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

pubspec.yaml 的 pluginClass
index.ets 的 export default
类的 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 的集成成本

yaml 复制代码

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

dart 复制代码

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

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

8.3 系统 API 使用清单

typescript 复制代码

// 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 插件工程有以下特点：

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

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

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

相关资源：