1. 插件介绍

flutter_widget_from_html 是一个功能强大的 Flutter 插件，能够将 HTML 内容转换为 Flutter 小部件树，支持多种 HTML 标签、样式和媒体元素。该插件为 OpenHarmony（鸿蒙）平台提供了专门的适配版本，使开发者能够在鸿蒙应用中轻松实现 HTML 内容的渲染。

核心功能

• 支持标准 HTML 标签和 CSS 样式
• 支持图片、视频、音频等媒体元素
• 支持自定义样式和自定义小部件构建
• 支持异步构建和缓存机制
• 提供多种渲染模式（Column、ListView、SliverList）
• 支持点击事件处理（图片、链接等）

适用场景

• 显示富文本内容（如新闻、博客、帮助文档等）
• 渲染来自网络的 HTML 内容
• 实现自定义格式的文本显示
• 构建包含多种媒体元素的复杂界面

2. 安装与配置

2.1 Git 依赖配置

由于这是一个专为鸿蒙平台定制的修改版本，需要通过 Git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  flutter_widget_from_html:
    git:
      url: "https://atomgit.com/openharmony-sig/flutter_widget_from_html.git"
      path: "packages/enhanced"

2.2 依赖获取

添加依赖后，执行以下命令获取包：

flutter pub get

2.3 权限配置

在鸿蒙平台上，如需访问网络资源（如加载网络图片、视频等），需要在项目中配置网络权限：

1. 打开 entry/src/main/module.json5，添加权限配置：

"requestPermissions": [
  {
   "name": "ohos.permission.INTERNET",
    "reason": "$string:network_reason",
    "usedScene": {
      "abilities": [
        "EntryAbility"
      ],
      "when":"inuse"
    }
  },
]

2. 打开 entry/src/main/resources/base/element/string.json，添加权限说明：

{
  "string": [
    {
      "name": "network_reason",
      "value": "使用网络"
    },
  ]
}

3. API 使用

3.1 基本导入

在需要使用该插件的 Dart 文件中导入包：

import 'package:flutter_widget_from_html/flutter_widget_from_html.dart';

3.2 核心 API：HtmlWidget

HtmlWidget 是该插件的核心类，用于将 HTML 内容转换为 Flutter 小部件。

构造函数

const HtmlWidget(
  String html, {
  Key? key,
  Uri? baseUrl,
  bool? buildAsync,
  CustomStylesBuilder? customStylesBuilder,
  CustomWidgetBuilder? customWidgetBuilder,
  bool? enableCaching,
  WidgetFactory Function()? factoryBuilder,
  OnErrorBuilder? onErrorBuilder,
  OnLoadingBuilder? onLoadingBuilder,
  OnTapImage? onTapImage,
  FutureOr<bool> Function(String)? onTapUrl,
  List<dynamic>? rebuildTriggers,
  RenderMode renderMode = RenderMode.column,
  TextStyle? textStyle,
})

主要参数说明

参数名	类型	说明	鸿蒙支持
html	String	要渲染的 HTML 字符串（不能为空）	yes
baseUrl	Uri?	解析链接和图像 URL 的基本 URL	yes
buildAsync	bool?	控制是否异步构建小部件树	yes
customStylesBuilder	CustomStylesBuilder?	自定义 HTML 标签的样式	yes
customWidgetBuilder	CustomWidgetBuilder?	自定义 HTML 标签的渲染逻辑	yes
enableCaching	bool?	控制是否启用缓存机制	yes
onErrorBuilder	OnErrorBuilder?	错误处理构建器	yes
onLoadingBuilder	OnLoadingBuilder?	加载状态构建器	yes
onTapImage	OnTapImage?	图片点击事件处理	yes
onTapUrl	FutureOr Function(String)?	链接点击事件处理	yes
renderMode	RenderMode	渲染模式（默认：RenderMode.column）	yes
textStyle	TextStyle?	文本元素的默认样式	yes

3.3 渲染模式

该插件提供了三种渲染模式，以适应不同规模的 HTML 内容：

渲染模式	说明	适用场景
RenderMode.column	将内容渲染为 Column 小部件	中小型文档
RenderMode.listView	将内容渲染为 ListView 小部件	中型/大型文档，需要滚动查看
RenderMode.sliverList	将内容渲染为 SliverList 小部件	大型/巨大文档，用于复杂滚动布局

4. 使用示例

4.1 基本 HTML 渲染

HtmlWidget(
  '''<h1>Hello World</h1>
  <p>This is a paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
  </ul>''',
)

4.2 处理点击事件

HtmlWidget(
  '''<a href="https://openharmonycrossplatform.csdn.net">访问开源鸿蒙社区</a>
  <img src="https://example.com/image.jpg" alt="示例图片">''',
  onTapUrl: (url) {
    print('点击了链接: $url');
    // 处理链接点击事件
    return true; // 返回true表示已处理，不再执行默认行为
  },
  onTapImage: (imageData) {
    print('点击了图片: ${imageData.sources.first.url}');
    // 处理图片点击事件
  },
)

4.3 自定义样式

HtmlWidget(
  '''<div class="custom-box">自定义样式内容</div>
  <p class="highlight">高亮文本</p>''',
  customStylesBuilder: (element) {
    if (element.classes.contains('custom-box')) {
      return {
        'background-color': '#f0f0f0',
        'padding': '10px',
        'border-radius': '5px',
      };
    }
    if (element.classes.contains('highlight')) {
      return {
        'color': 'red',
        'font-weight': 'bold',
      };
    }
    return null;
  },
)

4.4 自定义小部件

HtmlWidget(
  '''<my-widget data-value="42"></my-widget>''',
  customWidgetBuilder: (element) {
    if (element.localName == 'my-widget') {
      final value = element.attributes['data-value'];
      return WidgetPlaceholder(
        child: Container(
          padding: EdgeInsets.all(10),
          decoration: BoxDecoration(
            border: Border.all(color: Colors.blue),
            borderRadius: BorderRadius.circular(5),
          ),
          child: Text('自定义小部件，值为: $value'),
        ),
      );
    }
    return null;
  },
)

4.5 选择合适的渲染模式

// 小型文档使用Column模式
HtmlWidget(
  smallHtmlContent,
  renderMode: RenderMode.column,
)

// 大型文档使用ListView模式
HtmlWidget(
  largeHtmlContent,
  renderMode: RenderMode.listView,
)

// 在CustomScrollView中使用SliverList模式
CustomScrollView(
  slivers: [
    SliverAppBar(title: Text('HTML内容')),
    HtmlWidget(
      hugeHtmlContent,
      renderMode: RenderMode.sliverList,
    ).sliver,
  ],
)

4.6 加载状态和错误处理

HtmlWidget(
  networkHtmlContent,
  onLoadingBuilder: (context, element, loadingProgress) {
    return Center(
      child: CircularProgressIndicator(value: loadingProgress),
    );
  },
  onErrorBuilder: (context, element, error) {
    return Center(
      child: Text('加载失败: $error'),
    );
  },
)

5. 兼容性与限制

5.1 兼容性

该插件在以下环境中已测试通过：

• Flutter: 3.7.12-ohos-1.0.6
• SDK: 5.0.0(12)
• IDE: DevEco Studio: 5.0.13.200
• ROM: 5.1.0.120 SP3

5.2 限制

• 部分高级 CSS 特性可能不被完全支持
• 某些复杂的 HTML 结构可能需要额外的自定义处理
• 大型 HTML 文档可能需要优化以提高性能

6. 示例应用

该插件提供了完整的示例应用，位于项目的 demo_app 目录中。示例应用展示了插件的各种功能和使用方法，包括：

• 基本 HTML 渲染
• 图片和媒体元素处理
• 自定义样式和小部件
• 各种渲染模式的使用
• 事件处理

开发者可以参考示例应用的代码来快速上手该插件。

7. 总结

flutter_widget_from_html 为鸿蒙平台提供了强大的 HTML 内容渲染能力，使开发者能够轻松在鸿蒙应用中实现富文本内容的显示。该插件具有以下优势：

• 功能全面：支持多种 HTML 标签、样式和媒体元素
• 使用简单：提供直观的 API 和丰富的配置选项
• 性能优秀：支持异步构建和缓存机制
• 灵活性高：支持自定义样式和自定义小部件构建
• 完全适配：专为鸿蒙平台进行了优化和适配

通过本指南的学习，开发者应该能够快速掌握该插件的使用方法，并在自己的鸿蒙应用中实现高质量的 HTML 内容渲染。

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