一介布衣

🧭 快速导航

Towxml 富文本与 Markdown 渲染 ​

项目地址：https://github.com/sbfkcel/towxml
文档/示例：见仓库 README 与 Demo
关联清单：https://github.com/justjavac/awesome-wechat-weapp

Towxml 提供在小程序端将 Markdown/HTML 转为可渲染的 WXML/WXSS 结构的方案，并附带代码高亮与样式支持。

🎯 文章目标 ​

  • 在项目中接入 Towxml
  • 渲染 Markdown 与 HTML
  • 处理图片、代码高亮与长文性能

📦 安装与初始化 ​

bash
npm i towxml -S
# 微信开发者工具：工具 -> 构建 npm

项目结构（示例）：

miniprogram/
├─ utils/
│  └─ towxml.js
└─ pages/article/
   ├─ index.wxml
   ├─ index.wxss
   └─ index.js

初始化（封装工具）：

js
// utils/towxml.js
import Towxml from 'towxml'
const towxml = new Towxml()

export function renderMarkdown(md) {
  return towxml(md, 'markdown', {
    theme: 'light', // 或 'dark'
    events: { }     // 可绑定事件
  })
}

export function renderHtml(html) {
  return towxml(html, 'html', { theme: 'light' })
}

🖨️ 页面使用 ​

js
// pages/article/index.js
import { renderMarkdown } from '../../utils/towxml'

Page({
  data: { article: {} },
  onLoad() {
    const md = '# 标题\\n\\n这是 **Markdown** 示例。'
    const result = renderMarkdown(md)
    this.setData({ article: result })
  }
})
xml
<!-- pages/article/index.wxml -->
<import src="/towxml/entry.wxml" />
<template is="entry" data="\{\{...article\}\}" />

注意：根据版本与构建方式，Towxml 的模板/样式目录位置可能不同，请按仓库文档拷贝/配置。

🎨 样式与高亮 ​

  • 代码高亮：确认引入对应的样式与字体；可切换主题
  • 图片适配：为图片容器增加自适应样式，控制最大宽度
  • 表格/列表：补齐常用样式，确保在小屏设备可读

🏗️ 工程实践 ​

  • 长文性能：对超长富文采用分页/折叠；仅渲染首屏，滚动触发加载
  • 安全性：仅渲染可信内容；对 HTML 输入做白名单与清洗
  • 缓存：将渲染结果做本地缓存，减少 CPU 计算

🧪 常见问题 ​

  • 模板路径错误：检查 import src 与 Towxml 资源目录
  • 样式未生效：确认 WXSS 引入顺序与路径
  • 表情/特殊字符：确保编码正确，必要时进行转义

✅ 适用场景 ​

  • 博客、知识库、文档类小程序
  • 富文本详情页、用户协议/帮助中心等页面

🔗 参考 ​

📊 总结 ​

Towxml 让 Markdown/HTML 在小程序中渲染成为可能。合理处理模板/样式、控制性能，并对输入做安全治理，即可落地稳定的富文本阅读体验。