Flutter最佳实践:用 flutter_html 渲染富文本

一、需求来源

开发资讯 App 遇到一个痛点:后端返回的文章正文是一段 HTML,图片尺寸五花八门------有的带固定 width/height,有的只给一个 data-href 宽高比,有的宽高比还是假的。

直接用 flutter_html 一把梭,图片经常撑爆布局、宽高比失真。这篇文章把完整踩坑和最佳实践整理出来。

一段真实的资讯正文:

xml 复制代码
<p><img src="https://cdn.xxx.com/news/xxx.png"
        data-href="1500|1688|image/png||share" style=""/></p>
<p>25/26赛季德甲联赛第12轮,拜仁慕尼黑3-1战胜圣保利......</p>
<blockquote>关键事件</blockquote>
<p><img src="https://cdn.xxx.com/news/icon.png"
        data-href="16|16|png|icon" style="width: 20px;height: 20px;"/>
   44'迪亚斯倒地将球捅给格雷罗......</p>

图片的尺寸信息散落在三个地方,可信度不同:

  1. style 的 width/height:最可靠,运营手写,直接照用;
  2. data-href 的 宽|高|类型|... :次可靠,可算宽高比占位;但带 share 标记的图真实尺寸常与标注不符,要丢弃;
  3. 什么都不带:等网络图片真实加载后再定高度。

flutter_html 默认把 <img> 当 inline 元素渲染,没有任何尺寸策略。核心需求就是:给 <img> 定制一套「从可信到兜底」的降级解析,保证任何脏数据下布局都不崩。

二、方案探索:两个扩展点

flutter_html 提供两个关键扩展点:

  • style:给选择器设默认样式,解决整体排版;
  • extensions(TagExtension) :接管指定标签的渲染,解决个别标签的定制。

整体排版:style 配 body

less 复制代码
Html(
  data: detail?.context ?? "",
  style: {
    "body": Style(
      color: themeProvider.titleColor,       // 跟随主题
      lineHeight: LineHeight.number(1.3),    // 行高
      fontSize: FontSize(16.5, Unit.px),     // 字号
      display: Display.block,
      textAlign: TextAlign.left,
    ),
    "p img": Style(                          // 块级图默认撑满居中
      display: Display.block,
      margin: Margins(left: Margin.auto(), right: Margin.auto()),
    ),
  },
  extensions: [...],
)

注意 Style 是 flutter_html 自己的一套类型,字号用 FontSize(16.5, Unit.px),行高用 LineHeight.number(1.3),跟 Flutter 原生 TextStyle 不是一回事。

接管标签:TagExtension

TagExtension 里能拿到 element.attributes,这是读取 src / style / data-href 的唯一途径。把 <img> 完全接管:

ini 复制代码
TagExtension(
  tagsToExtend: {"img"},
  builder: (exContext) {
    final element = exContext.element;
    if (element == null) return const SizedBox.shrink();
    final url = element.attributes['src'] ?? '';
    final styleSize = resolveImageStyleSize(element.attributes['style']);
    final aspectRatio = resolveImageAspectRatio(element.attributes['data-href']);
    return buildHtmlImage(
      url: url,
      width: styleSize.$1,
      height: styleSize.$2,
      aspectRatio: aspectRatio,
    );
  },
),

<blockquote>(如「关键事件」小标题)默认引用样式太丑,同样接管,渲染成带主题色竖条的项目标题栏即可。

三、图片尺寸:三级降级策略

这是核心。逐级尝试,能拿到就用,拿不到就降级:

第一级:style 固定宽高(最可信)

dart 复制代码
(double?, double?) resolveImageStyleSize(String? style) {
  if (style == null || style.isEmpty) return (null, null);
  final widthMatch = RegExp(r'width\s*:\s*([\d.]+)px', caseSensitive: false).firstMatch(style);
  final heightMatch = RegExp(r'height\s*:\s*([\d.]+)px', caseSensitive: false).firstMatch(style);
  final width = widthMatch == null ? null : double.tryParse(widthMatch.group(1)!);
  final height = heightMatch == null ? null : double.tryParse(heightMatch.group(1)!);
  return (width, height);
}

第二级:data-href 宽高比(次可信)

arduino 复制代码
double? resolveImageAspectRatio(String? dataHref) {
  if (dataHref == null || dataHref.isEmpty) return null;
  final parts = dataHref.split('|');
  if (parts.length < 2) return null;
  // 例:1500|1688|image/png||share ------ share 图真实尺寸常与标注不符
  if (parts.any((e) => e.trim().toLowerCase() == 'share')) return null;
  final width = double.tryParse(parts[0]) ?? 0;
  final height = double.tryParse(parts[1]) ?? 0;
  if (width <= 0 || height <= 0) return null;
  return width / height;
}

关键坑 :带 share 标记的封面图,元数据是「假尺寸」,直接算宽高比会拉伸变形,必须放弃这一级。

第三级:都没有 → 真实加载兜底

php 复制代码
Widget buildHtmlImage({required String url, double? width, double? height, double? aspectRatio}) {
  // 1. 有固定宽高:直接照用
  if (width != null && height != null && width > 0 && height > 0) {
    return ClipRRect(
      borderRadius: BorderRadius.circular(2),
      child: buildNetworkImageFitWidth(url: url, width: width, height: height, fit: BoxFit.contain),
    );
  }
  // 2. 有宽高比:按屏宽占位,LayoutBuilder 算高
  if (aspectRatio != null) {
    return SizedBox(
      width: double.infinity,
      child: LayoutBuilder(builder: (context, constraints) {
        final maxWidth = constraints.maxWidth;
        if (!maxWidth.isFinite || maxWidth <= 0) return buildNetworkImageFitWidth(url: url);
        return ClipRRect(
          borderRadius: BorderRadius.circular(4),
          child: buildNetworkImageFitWidth(
            url: url, width: maxWidth, height: maxWidth / aspectRatio,
            fit: BoxFit.fitWidth, alignment: Alignment.topCenter,
          ),
        );
      }),
    );
  }
  // 3. 都没有:真实尺寸
  return ClipRRect(borderRadius: BorderRadius.circular(4), child: buildNetworkImageFitWidth(url: url));
}

无论哪一级,最终都收敛到一个统一网络图组件:用 CachedNetworkImage 缓存,width ?? double.infinity 撑满屏宽,占位/错误态统一处理。图标类小图传 SizedBox.shrink() 占位,避免加载时闪一大块默认图。

四、总结

1、选择 flutter_html 的原因就是他可以对标签做单独处理加工。

2、flutter_html 只是「把 HTML 转成 Widget」的库,真正决定渲染质量的,是你对非结构化数据的处理策略。核心就一句话:

把 <img> 的尺寸解析做成「可信 → 次可信 → 兜底」的降级链,并统一收敛到缓存网络图组件。

这样无论后端返回什么脏数据,布局都不崩、图片不变形、加载体验一致。配合 TagExtension 定制 blockquote 等标签,一个「跟原生一样」的富文本资讯页就成型了。


源码参考:

github

相关推荐
Flynt1 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑2 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星2 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson2 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
其实防守也摸鱼3 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊3 小时前
CNC计算机数控加工模拟器
前端
张一凡934 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
Brookty4 小时前
CSS基础知识(一):选择器、优先级、层叠与继承、边框属性及盒模型
前端·css
颜进强4 小时前
微信小微AI-灰度与命中排查|代码全对、版本已发,为什么同事就是问不中?
前端·ai编程·全栈