【HarmonyOS】原生 Markdown 渲染解决方案 —— @luvi/lv-markdown-in 原创

简介

鸿蒙原生 Markdown 解析与渲染三方库，一款专为 OpenHarmony 与 HarmonyOS 系统设计的原生 Markdown 渲染解决方案。让Markdown 内容在界面中拥有更平滑的性能表现与更统一的视觉体验。

该库以高性能与原生体验为核心，提供 30+ 可定制样式 API，助力开发者灵活定义 Markdown
内容的视觉风格与交互体验。从基础文本排版到复杂组件布局，都能精确适配系统特性。

充分结合鸿蒙资源机制，支持 三种内容加载模式：

• 纯文本加载：适用于动态内容；
• 资源文件加载：便于内置模板与预设内容展示；
• 沙箱文件加载：保障用户内容安全与私有化存储。

适配 $rawfile 原生资源图片加载能力，并支持 html常用标签解析 与 图片加载代理，兼顾 Markdown 与富文本场景的灵活性。

lv-markdown-in 目前支持

基本语法	拓展语法
标题	表格
段落	代码块
换行	脚注
强调（粗体、斜体、粗斜体）	任务列表
引用块	删除线
列表	支持html常用标签解析
代码
分割线
链接
图片

立即使用

1.运行命令

ohpm install @luvi/lv-markdown-in

2.在项目中引入插件

import { Markdown } from @luvi/lv-markdown-in

3.在代码中使用

Markdown({ text: "想让文字像在原生世界里呼吸，就得从**渲染**开始" })

升级指南

2.0 及之前版本中的 LvMarkdownIn() 组件已弃用，可以使用 3.0 及以上导出的 Markdown() 组件，体验最新版本的改动。

组件及字段变更：

旧版本	变更	说明
LvMarkdownIn	Markdown	使用 Markdown() 组件，体验最新版本的改动。
	controller	新增 MarkdownController 控制器。<br>样式、图片，超链接点击监听拦截、图片代理均由此控制器完成。
text	text	markdown 文本内容，保持不变。
loadMode	mode	加载模式，字段名称调整。
context	context	上下文，保持不变。
rawfilePath	rawfilePath	资源文件路径，保持不变。
sandboxPath	sandboxPath	沙箱文件路径，保持不变。
loadCallBack	callback	字段名称调整。

多种内容加载模式（纯文本、资源文件、沙箱文件）

1. 纯文本模式（text）

Markdown({
    text: "想让文字像在原生世界里呼吸，就得从**渲染**开始",
    mode: "text",               // 默认 text 可省略
    callback: {                 // callback 可省略
      complete: () => {
        console.log("Markdown component load success.")
      },
      fail: (code: number, message: string) => {
        console.error("Markdown component load error. code: " + code + ", message: " + message)
      }
    }
})

2. 资源文件模式（rawfile）

使用资源文件模式，需要将 mode 字段设置为 rawfile，rawfilePath 需要填写模块中 rawfile
目录的文件路径，同时需要传递应用上下文context，callback 为可选参数，用于资源加载时的回调检查。

Markdown({
    mode: "rawfile",
    context: getContext(),      // 资源文件模式必填参数
    rawfilePath: "t/text.md",   // 资源文件地址
    callback: {                 // callback 可省略
      complete: () => {
        console.log("Markdown component load success.")
      },
      fail: (code: number, message: string) => {
        console.error("Markdown component load error. code: " + code + ", message: " + message)
      }
    }
})

3. 沙箱文件模式（sandbox）

使用沙箱文件模式，需要将 mode 字段设置为 sandbox，callback 为可选参数，用于资源加载时的回调检查。

Markdown({
    mode: "sandbox",
    sandboxPath: getContext().getApplicationContext().filesDir + "/t2/text.md",
    callback: {                 // callback 可省略
      complete: () => {
        console.log("Markdown component load success.")
      },
      fail: (code: number, message: string) => {
        console.error("Markdown component load error. code: " + code + ", message: " + message)
      }
    }
})

超链接、图片点击，自定义控制跳转行为

需要注意的是，使用拦截行为后，return true 才可拦截正常拦截库中默认打开行为，return false 则不拦截，但会进入该逻辑。

// 导入 MarkdownController
import { MarkdownController } from '@luvi/lv-markdown-in'

// 注册超链接点击回调，return true 则表示拦截，自行处理超链接跳转逻辑
this.markdownController.setHyperlinkClickListener((title: string, src: string) => {
    console.log("拦截跳转 title: " + title) // 标题
    console.log("拦截跳转 src: " + src) // 网页地址
    promptAction.showToast({ message: title + "\n" + src })
    return true
})

// 注册图像点击回调，return true 则表示拦截，自行处理图像展示逻辑
this.markdownController.setImageClickListener((src: string) => {
    console.log("拦截跳转 src: " + src) // 图片地址
    promptAction.showToast({ message: src })
    return true
})

动态样式改变

需在 Markdown 渲染完成后动态改变样式，可以绑定 MarkdownController 至对应 Markdown 组件后直接调用 MarkdownController 的多样化接口设置样式。

深色模式

在代码中引用自定义的颜色资源值，使用 $r 加载自定义颜色资源，系统将自动在应用深浅色变化时，加载对应限定词目录下的资源文件，从而改变 Markdown

元素的颜色完成深浅色适配。详细可参阅文章：ArkUI深色模式适配指南

import { Markdown, MarkdownController } from '@luvi/lv-markdown-in';

@Entry
@Component
struct Dark {
    controller: MarkdownController = new MarkdownController()
    @State content: string = `
      ## 鸿蒙原生应用开发笔记
      *鸿蒙原生*，意味着**纯净**与**性能**的平衡。
      > 想让文字像在原生世界里呼吸，就得从渲染开始。
    `

    aboutToAppear(): void {
        // 深色模式适配
        this.controller
            .setTitleColor($r("app.color.title"))
            .setTextColor($r("app.color.primary_text"))
            .setQuoteBackgroundColor($r("app.color.quote_bgc"))
    }

    build() {
        Scroll() {
            Markdown({
                controller: this.controller,
                text: this.content
            })
        }
        .padding({
            left: 15,
            right: 15,
            top: 60,
        })
    }
}

Markdown

承载 Markdown 内容渲染的组件。项目采用 v1 + v2 装饰器混合开发，可同时在 v1 或 v2 项目中使用。

装饰器类型： @Component

参数

名称	类型	必填	装饰器类型	说明
controller	string | undefined	否	@Prop	通过 MarkdownController 可以控制 Markdown 组件各种行为，如：自定义样式、设置图片点击拦截、设置超链接点击拦截等。
text	string | undefined	否	@Prop	markdown 文本内容。
mode	“text” | “rawfile” | “sandbox” | undefined	否	@Prop	Markdown 组件加载模式，支持纯文本加载、沙箱文件加载、资源文件加载，不填默认为 “text”。
context	Context | undefined	否	/	mode 字段设置为 rawfile 时， context 为必填项。
rawfilePath	string | undefined	否	@Prop	mode 字段设置为 rawfile 时， rawfilePath 为必填项，需传入 resources/rawfile 目录下对应的 rawfile 文件路径。
sandboxPath	string | undefined	否	@Prop	mode 字段设置为 sandbox 时， sandboxPath 为必填项，需传入沙箱 text/md 文件的完整沙箱路径。<br>例：getContext().getApplicationContext().filesDir + “/t2/text.md”。
callback	MdCallback | undefined	否	/	Markdown 组件加载状态结果告知。用于组件加载完成时，组件加载失败时回调，并返回错误码 code，错误信息 message，可用于问题分析。

MarkdownController

Markdown 组件的控制器。可以将此对象绑定至 Markdown 组件，然后通过它控制 Markdown 组件的自定义样式。同一个控制器可以控制多个 Markdown 组件，多个 API 支持链式调用语法。

• v1 版本开发中不支持使用 @State 装饰器进行修饰，无需使用装饰器修饰。
• v2 版本开发中可支持 v2 装饰器使用。
• 当然，您也可以完全不选择使用装饰器，这并不影响组件的正常渲染。

导入对象

// 导入 MarkdownController
import { MarkdownController } from '@luvi/lv-markdown-in'
// 获取对象
markdownController: MarkdownController = new MarkdownController()

setTitleColor

setTitleColor(color: ResourceColor)

设置标题字体颜色。

参数

参数名	类型	必填	说明
color	ResourceColor	是	设置标题字体颜色，默认：32

使用示例

this.controller.setTitleColor("#000")

setTitleSize

setTitleSize(
titleSize: [ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number])

设置标题字号（1-6级）。

参数

参数名	类型	必填	说明
titleSize	[ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number]	是	设置标题1-6级字号。数组中0-5项分别为1-6级标题字号，默认： [30, 28, 24, 20, 18, 16] 。

使用示例

this.controller.setTitleSize([30, 28, 24, 20, 18, 16])

setTitleLineHeight

设置标题行高（1-6级）。

setTitleLineHeight(
lineHeights: [ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number])

参数

参数名	类型	必填	说明
lineHeights	[ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number, ResourceStr | number]	是	设置标题1-6级行高。数组中0-5项分别为1-6级标题行高，默认： [36, 34, 30, 26, 24, 22] 。

使用示例

this.controller.setTitleLineHeight([36, 34, 30, 26, 24, 22])

setTextColor

setTextColor(textColor: ResourceColor)

设置普通文本字体颜色。

参数

参数名	类型	必填	说明
textColor	ResourceColor	是	设置普通文本的颜色，默认：“#e61f1f39” 。

使用示例

this.controller.setTextColor("#e61f1f39")

setTextLineHeight

setTextLineHeight(textLineHeight: ResourceStr | number)

设置普通文本字体行高。

参数

参数名	类型	必填	说明
textLineHeight	ResourceStr | number	是	设置普通文本的行高，默认：24vp 。

使用示例

this.controller.setTextLineHeight(24)

setTextSize

setTextSize(textSize: ResourceStr | number)

设置普通文本字号。

参数

参数名	类型	必填	说明
textSize	ResourceStr | number	是	设置普通文本的字号，默认：16fp 。

使用示例

this.controller.setTextSize(16)

setInlineCodeColor

setInlineCodeColor(inlineCodeColor: ResourceColor)

设置行内代码颜色。

参数

参数名	类型	必填	说明
inlineCodeColor	ResourceColor	是	设置行内代码的颜色，默认：“#F4271C” 。

使用示例

this.controller.setInlineCodeColor("#F4271C")

setInlineCodeBackgroundColor

setInlineCodeBackgroundColor(inlineCodeBackgroundColor: ResourceColor)

设置行内代码背景颜色。

参数

参数名	类型	必填	说明
inlineCodeBackgroundColor	ResourceColor	是	设置行内代码的背景颜色，默认：“#0eff0000” 。

使用示例

this.controller.setInlineCodeBackgroundColor("#0eff0000")

setQuoteBorderColor

setQuoteBorderColor(quoteBorderColor: ResourceColor)

设置引用块左边颜色。

参数

参数名	类型	必填	说明
quoteBorderColor	ResourceColor	是	设置引用块左边的颜色，默认：“#F4271C” 。

使用示例

this.controller.setQuoteBorderColor("#F4271C")

setQuoteBackgroundColor

setQuoteBackgroundColor(quoteBackgroundColor: ResourceColor)

设置引用块背景颜色。

参数

参数名	类型	必填	说明
quoteBackgroundColor	ResourceColor	是	设置引用块的背景颜色，默认：“#ccf5f7fa” 。

使用示例

this.controller.setQuoteBackgroundColor("#ccf5f7fa")

setCodeBlockTheme

setCodeBlockTheme(codeBlockTheme: CodeTheme)

设置代码块主题。

参数

参数名	类型	必填	说明
codeBlockTheme	“light” | “dark”	是	设置代码块的主题，默认：“light” 。

使用示例

this.controller.setCodeBlockTheme("light")

setCodeBlockIdxState

setCodeBlockIdxState(codeBlockIdxState: boolean)

设置代码块索引展示状态。

参数

参数名	类型	必填	说明
codeBlockIdxState	boolean	是	设置代码块索引的展示状态，默认：false 。

使用示例

this.controller.setCodeBlockIdxState(false)

setImageWidth

setImageWidth(imageWidth: ResourceStr | number | null)

设置图片宽度。

参数

参数名	类型	必填	说明
imageWidth	ResourceStr | number | null	是	设置图片的宽度，默认：“100%” 。

使用示例

this.controller.setImageWidth("100%")

setImageMaxWidth

setImageMaxWidth(imageMaxWidth: ResourceStr | number | null)

设置图片最大宽度。

参数

参数名	类型	必填	说明
imageMaxWidth	ResourceStr | number | null	是	设置图片的最大宽度，默认：null 。

使用示例

this.controller.setImageMaxWidth(null)

setImageHeight

setImageHeight(imageHeight: ResourceStr | number | null)

设置图片高度。

参数

参数名	类型	必填	说明
imageHeight	ResourceStr | number | null	是	设置图片的高度，默认：null 。

使用示例

this.controller.setImageHeight(null)

setImageMaxHeight

setImageMaxHeight(imageMaxHeight: ResourceStr | number | null)

设置图片最大高度。

参数

参数名	类型	必填	说明
imageMaxHeight	ResourceStr | number | null	是	设置图片的最大高度，默认：null 。

使用示例

this.controller.setImageMaxHeight(null)

setImageClickListener

setImageClickListener(event: (src: string) => boolean)

设置图片点击监听回调，return false 不拦截，return true 拦截。

参数

参数名	类型	必填	说明
event	(src: string) => boolean	是	设置图片的点击监听回调，默认：(src: string) => { return false } 。

使用示例

this.controller.setImageClickListener((src: string) => { 
    console.log("拦截跳转 src: " + src) // 图片地址
    promptAction.showToast({ message: src })
    return true
})

setImageLoadProxy

setImageLoadProxy(event: (src: string) => string)

设置图片加载代理，回调图片加载前的 src ，返回值需返回处理后的 src 。

仅支持 http, https 协议的图片设置加载代理，$rawfile 本地资源图片不支持设置代理。

参数

参数名	类型	必填	说明
event	(src: string) => string	是	设置图片加载代理，默认：(src: string) => { return src } 。

使用示例

this.controller.setImageLoadProxy((src) => {
  console.log("imageLoadSrc > " + src)
  // 在这里处理完整的图片 url 后 return 即可。
  src = "http://xxxx.example/" + src
  return src
})

setHyperlinkTextColor

setHyperlinkTextColor(hyperlinkTextColor: ResourceColor)

设置超链接文字颜色。

参数

参数名	类型	必填	说明
hyperlinkTextColor	ResourceColor	是	设置超链接的文字颜色，默认：“#0664EC” 。

使用示例

this.controller.setHyperlinkTextColor("#0664EC")

setHyperlinkUnderlineState

setHyperlinkUnderlineState(hyperlinkUnderlineState: boolean)

设置超链接下划线展示状态。

参数

参数名	类型	必填	说明
hyperlinkUnderlineState	boolean	是	设置超链接下划线的展示状态，默认：false 不展示。

使用示例

this.controller.setHyperlinkUnderlineState(false)

setHyperlinkClickListener

setHyperlinkClickListener(event: (title: string, src: string) => boolean)

设置超链接点击监听回调，return false 不拦截，return true 拦截。

参数

参数名	类型	必填	说明
event	(title: string, src: string) => boolean	是	设置超链接的点击监听回调，默认：(src: string) => { return false } 。

使用示例

this.controller.setHyperlinkClickListener((src: string) => { 
    console.log("拦截跳转 title: " + title) // 标题
    console.log("拦截跳转 src: " + src) // 网页地址
    promptAction.showToast({ message: title + "\n" + src })
    return true
})

setTableBackgroundColor

setTableBackgroundColor(tableBackgroundColor: ResourceColor)

设置表格背景色。

参数

参数名	类型	必填	说明
tableBackgroundColor	ResourceColor	是	设置表格的背景色，默认：“#FFFFFF” 。

使用示例

this.controller.setTableBackgroundColor("#FFFFFF")

setTableTitleBackgroundColor

setTableTitleBackgroundColor(tableTitleBackgroundColor: ResourceColor)

设置表格表头背景色。

参数

参数名	类型	必填	说明
tableTitleBackgroundColor	ResourceColor	是	设置表格表头的背景色，默认：“#F5F7FA” 。

使用示例

this.controller.setTableTitleBackgroundColor("#F5F7FA")

setTableInterleaveBackgroundColor

setTableInterleaveBackgroundColor(tableInterleaveBackgroundColor: ResourceColor)

设置表格错行背景色。

参数

参数名	类型	必填	说明
tableInterleaveBackgroundColor	ResourceColor	是	设置表格错行的背景色，默认：“#80f5f7fa” 。

使用示例

this.controller.setTableInterleaveBackgroundColor("#80f5f7fa")

setTodoSelectedColor

setTodoSelectedColor(todoSelectedColor: ResourceColor)

设置任务列表选中颜色。

参数

参数名	类型	必填	说明
todoSelectedColor	ResourceColor	是	设置任务列表的选中颜色，默认：“#0A59F7” 。

使用示例

this.controller.setTodoSelectedColor("#0A59F7")

setTodoSelectSize

setTodoSelectSize(todoSelectSize: ResourceStr | number)

设置任务列表选项大小。

参数

参数名	类型	必填	说明
todoSelectSize	ResourceStr | number	是	设置任务列表选项的大小，默认：16vp 。

使用示例

this.controller.setTodoSelectSize(16)

setFootnoteTextColor

setFootnoteTextColor(footnoteTextColor: ResourceColor)

设置脚注文字颜色。

参数

参数名	类型	必填	说明
footnoteTextColor	ResourceColor	是	设置脚注的文字颜色，默认：“#fffa460d” 。

使用示例

this.controller.setFootnoteTextColor("#fffa460d")

setLineColor

setLineColor(lineColor: ResourceColor)

设置分割线颜色。

参数

参数名	类型	必填	说明
lineColor	ResourceColor	是	设置分割线的颜色，默认：“#EEE” 。

使用示例

this.controller.setLineColor("#EEE")

其他

有关 Markdown 的更多信息，请参阅 Markdown 官方教程 Markdown 。

使用过程中发现任何问题都可以提出 Issues 。

版权声明

本项目采用 MIT 开源协议，允许商用，修改，再分发。再分发时请注明原作者及原仓库地址。