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

OpenHarmony 开源三方库中心仓: @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 控制器。 样式、图片，超链接点击监听拦截、图片代理均由此控制器完成。
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 文件的完整沙箱路径。 例：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")

其他

OpenHarmony 开源三方库中心仓: @luvi/lv-markdown-in

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

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

版权声明

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