Markdown(AI 场景)
ui/markdown 把 Markdown 渲染成 ui/el 元素,针对的是 AI 聊天的特点:回答几个字几个字地到达,而且越写越长。
doc := markdown.New("").OnLink(openInBrowser)
doc.SetStreaming(true)
go func() { // 读模型的流式输出
for tok := range tokens {
core.Update(func() { doc.Append(tok) })
}
core.Update(func() { doc.SetStreaming(false) })
}()
// 在视图的 Render 里
el.Div().Child(doc.Render(cx))
Doc 的方法都要在 UI 锁下调用:回调里直接调,其他 goroutine 通过 core.Update。
完整示例:examples/chat,模拟流式回答,消息区跟随到底,可以中途停止。空白页提供跨段落选择、数学公式、长代码、双击与三击、脚注与引用、图片六项验证样例;go run ./examples/chat -sample=all -lang zh-CN 直接展示中文完整内容。样例说明列出了各项交互的检查方法。
Markdown 插件
doc.Plugins(markdown.Plugin{...}) 为单篇文档注册 Goldmark 语法扩展与原生渲染工厂。Extensions 接收 goldmark.Extender,可安装块级/行内解析器或 AST 转换;Blocks 按 ast.NodeKind 返回 el.View,Inlines 返回 InlineObject{Text, Widget}。后注册者覆盖同类节点。块工厂返回 nil,或行内工厂返回空文字/nil widget 时,使用内置转换。
行内对象作为一个整体测量和换行,底部对齐文字基线;Text 是选择、复制和渲染文本区间中的表示。双击按整个对象选择。对象自己提供语义及交互,动态尺寸每帧重新测量;其绘制不参与文字淡入。块级自定义视图每帧 Render,自己管理文字选择,不加入文档的可选文字。代码围栏内部以及 HTML 转换生成的内部节点不经过插件映射。
在初始化时配置插件,不要每帧重新注册。注册/移除会重建解析结果,清空选区和待定位请求。含插件的文档整篇解析,让自定义块跨空行工作;若每个插件都设置 Local: true(语法不跨空行,如行内对象和逐块渲染),文档仍按空行分块,流式追加只重新解析最后一块;编辑时工厂可能再次调用,需要保留的控件状态由应用按业务标识复用。回调在 UI 锁内执行,不能修改正在解析的文档;传入 AST 和源码只读。Plugins() 移除全部插件。插件代码是应用代码,没有沙箱。
组件库 text_view 演示把指定引用渲染成提示卡片、把 @Keel 代码片段替换成行内标签。自动测试覆盖文档隔离、默认回退、自定义语法与嵌套块、应用状态复用、行内控件点击/选择复制、追加和注销。原生窗口交互仍待验收。
注册插件不会关闭普通已完成块的视图和布局缓存。只有实际含自定义视图或行内对象的块(包括列表、引用和表格单元格中嵌套的对象)每帧重建,动态控件仍能更新,其余内容继续复用缓存。
流式淡入
doc.StreamFade(true) 开启新增文字淡入,默认 350ms、三次缓出;StreamFadeDuration(500*time.Millisecond) 可调整到 0–10 秒,零表示立即显示。首次展示已有全文不动画;后续 Append 或内容以原文开头的 SetSource 会为新增文字计时。连续片段的动画重叠,之前已经开始的片段不重置。
计时按渲染文字与样式保留,补全 Markdown 时发生字重、颜色等变化的文字重新淡入。替换全文直接显示,系统或应用开启减少动画时也立即显示。文字只排版一次,动画分段绘制字形和文字装饰;选区、范围高亮、背景、图片、代码卡片按钮及流式光标不淡入。自定义代码渲染器自行管理动画。
已通过连续追加、语法补全、减少动画及 1×/2× GPU 像素测试;稳定文字不进入透明度图层,避免抗锯齿颜色变化。组件库 text_view 的“演示流式淡入”按 120ms 间隔追加正文、粗体和代码片段。
折叠预览
表格宽度随内容:每列取该列最宽单元格的单行宽度,各行一致。列宽使用 sp,随字号一起缩放;宽度超出文档时横向滚动,不再压缩列宽。滚动条在最后一行下方预留空间。
行间和列间的内部分隔线使用 theme.Border。列间竖线贯穿整行,包括单元格换行后的高度;启用 Palette.Frameless 时这些分隔线保留,表格外框隐藏。
doc.TableDividers(false) 关闭内部横竖分隔线,TableDividers(true) 恢复显示(默认开启)。已有表格和流式追加的表格会在下一帧生效,布局、内容和文字选择保持不变。表格外框仍独立跟随调色板。
doc.MaxLines(6) 将整篇高度限制为六个正文行高(theme.BodySize × 1.6),字号缩放、标题、段落间距、表格和代码卡片都占这份预算。MaxLines(0) 取消限制;IsClamped() 返回上一绘制帧是否确实隐藏了内容,可据此显示展开按钮。限制为 1–100000 行,负数视作取消。
doc.MaxHeight(dp) 用 dp 高度限制预览,替代正文行数限制;与 MaxLines 互相覆盖。零、负值或非有限高度取消限制。IsClamped、完整行裁剪和全文选择/复制遵循 MaxLines 的相同规则,可用于随窗口高度变化的消息预览,原文保持完整。
普通文字跨越底边时整行隐藏;图片和高于整个预算的单行保留落在框内的部分。表格下一行连首行文字都放不下时,隐藏该行的前导边框与留白。组件不会自动添加省略号或展开按钮;自定义代码卡片按框裁剪。预览期间忽略区间定位请求,展开后再调用 RevealRange。全文仍保留在 RenderedText 和全选复制中。
双倍率布局测试覆盖长文折叠、展开和内容替换,GPU 像素测试检查混合表格内容没有越过预览底边。组件库 text_view 演示折叠、展开和截断状态。
渲染文本区间
RenderedText() 返回最近一次绘制的可选中文字,首次绘制前为空;它保留块间分隔符,不包含列表标记、按钮、流式光标和自定义代码卡片的内容。更换源文后,等下一帧绘制再取偏移。TextRange{Start, End} 使用这段文本的 UTF-8 字节半开区间,不能直接套用 Markdown 源码位置。
SetRangeHighlights([]RangeHighlight) 整批替换背景高亮,nil 清空。越界、倒序、截断 UTF-8 字符或源文尚未绘制时返回 false,保留原高亮;空区间不绘制。后项覆盖前项,选区在高亮上方。分隔符本身没有矩形,跨块区间会分别画在各块文字后方。源文更新时,完全落在公共前缀或后缀的高亮保留并迁移,涉及中间改动的高亮移除;不追踪中间搬移的文字。
RevealRange(r) 请求最近的 ScrollY 以最小纵向滚动露出区间起点所在行,允许空区间。返回 true 只表示区间有效,不能保证存在可滚动祖先。只保留最新请求,源文变化或一秒超时后取消。不调整代码块内部的横向滚动。
自动测试覆盖中文 UTF-8 边界、无效更新原子拒绝、前后缀迁移、重叠高亮像素及双向滚动定位。组件库 text_view 提供高亮、清除和定位按钮。
YAML front matter
文档开头 --- 之间的 YAML 元数据(静态站点生成器、笔记软件常用)不算正文,默认不显示:
d := markdown.New(src)
d.Meta()["title"] // 顶层 key: value,去掉两端引号
d.FrontMatter() // 原始 YAML,嵌套或列表值交给 YAML 解析器
d.ShowFrontMatter(true) // 在文档顶部显示为键值表
只认文档最开头、并且有结束行(--- 或 ...)的块;还在流式输出、没写到结束行时按原文显示。文档中间的 --- 仍是分隔线。
支持的语法
段落、标题、加粗、斜体、删除线、行内代码(灰色底)、链接(悬停显示下划线)、自动链接、带语法高亮(引入 ui/highlight 时)和复制按钮的代码块、引用、有序/无序/任务列表、GFM 表格(支持对齐)、分隔线。支持图片、脚注及跨块引用式链接。
HTML:渲染成富文本,不显示源码。
- 行内标签:
<b><strong><i><em><u><ins><s><del><mark>(高亮底色)、<code><kbd>、<sup><sub>、<a href>、<br>、<img src alt>。 - 块级 HTML 转成相应的 Markdown 块:
<h1>–<h6>、<p>、<div>、<ul><ol><li>、<blockquote>、<pre><code class="language-go">、<table>(<th>或<thead>作表头,align对齐)、<hr>。 <details>的<summary>加粗显示,内容照常展开;空行隔开的 Markdown 内容照常渲染。<script>、<style>、表单、<iframe>等连内容一起丢弃,什么都不执行。- 注释隐藏;不是 HTML 元素名的“标签”按原文显示,所以
Vec<String>、List<T>不会消失。
选中复制:从段落、标题、引用、列表、代码块或表格单元格开始拖动,可以跨块选择文字。双击按 Unicode 词边界选词(中文按字),三击选中整段;代码块三击选中当前源码行。双击或三击后按住拖动,按整词或整段扩展选区。Cmd/Ctrl+C 复制选区,Cmd/Ctrl+A 选中这篇文档,点别处取消。拖选到上下边缘时,最近的 ScrollY() 容器自动滚动;按住鼠标或松开后均可使用滚轮。复制的是显示的纯文本:文字块之间保留空行,表格单元格用制表符分隔、行之间换行;不包含列表标记、代码块的语言标签、复制按钮或流式光标。代码块的复制按钮仍只复制该块代码。
代码块:圆角卡片左侧显示代码图标和语言名称,未指定语言或标记为 text、txt、plaintext 时显示“纯文本”;右侧提供换行和复制图标,悬停显示操作提示,复制成功后短暂显示勾选图标。默认保留源文的代码行,长行可通过水平滚轮、触控板或底部滚动条查看;底部整条轨道支持点击和拖动,鼠标停在滚动条上时,普通滚轮也可左右滚动;点击“自动换行”按代码区宽度折行,再次点击恢复原始行。语言名称和按钮固定,每个代码块独立保存换行与滚动状态,流式追加不会重置这些状态。
数学公式:$...$ 随正文基线排版,$$...$$ 独立居中。原生排版支持:
- 上下标、分式、根号、
\binom; - 希腊字母及变体,约 200 个关系符、箭头、运算符和杂项符号,
\not否定; - 大型运算符:求和、积分、
\bigoplus等,显示模式下\sum、\lim、\max的上下限在上下方; - 字体:
\mathbb、\mathcal、\mathfrak、\mathsf、\mathtt、\mathbf、\boldsymbol、\mathrm、\text; - 重音:
\hat\bar\vec\dot\ddot\tilde\check\breve\acute\grave,以及\widehat、\overline、\underline、\overrightarrow; - 结构:
\overbrace、\underbrace(带标签)、\overset、\underset、\stackrel、\boxed; - 颜色:
\color、\textcolor、\colorbox,可用常见颜色名或#rrggbb; - 间距:
\phantom、\quad、\hspace等; - 环境:
matrix、pmatrix、bmatrix、Bmatrix、vmatrix、Vmatrix、cases、aligned、align、split、gather、equation、array、smallmatrix,以及\tag。
矩阵可以嵌套,\left / \right 分隔符随内容伸缩(. 隐藏一侧)。支持 \newcommand、\renewcommand、\providecommand 及无分隔参数的 \def,最多 9 个参数;\newcommand 可设置首个参数的默认值。宏按文档顺序生效,替换文档后清除。分式和矩阵撑开行高,公式按整体换行和选择,复制保留带分隔符的 TeX 源码。代码中的美元符号不参与解析;未闭合、语法错误或含未知命令的公式显示源码,流式补全后重新排版。无需外部 TeX 服务。
脚注与引用:引用定义可以放在后面的段落,完整、折叠和缩略引用共享文档上下文。脚注按首次出现排序;点击上标跳到文末脚注,点击返回箭头回到对应引用。重复引用各有返回位置,多段脚注保留格式。
图片:异步加载本地路径、file://、data URL,以及引入 ui/netimage 后的 HTTP(S) 地址,支持 PNG、JPEG、GIF 首帧和 WebP。按原始宽高比缩小到容器宽度,加载期间和失败时显示带替代文字的占位;加载完成会重新布局,同篇文档的相同地址共享资源。默认路径相对工作目录;需鉴权或相对文档路径时,在首次渲染前配置 doc.ImageLoader(func(context.Context, string) (image.Image, error))。选区复制图片的替代文字,链接图片仍可点击。默认加载器限制 16 MiB 文件、3200 万像素和 15 秒请求时间。
流式渲染怎么做到又快又稳
1. 按块切分,只解析变化的块。 源文本在"代码块和独立公式外的空行"处切成顶层块,每块单独解析并缓存。追加文字时,只有最后一块的内容变了,只重新解析它。空行后面跟着缩进行时不切(列表项续行、缩进代码)。
存在脚注、引用定义或数学宏时,需要按整篇文档解析,才能使后续定义影响前面的引用、使宏跨段生效;未变化的块仍复用视图和布局缓存。普通文档保持尾块增量解析。
测试 TestStreamingReparsesOnlyTheTail 逐字追加 2KB 的回答,解析次数不超过"追加次数 + 2 × 块数",而不是"追加次数 × 块数"。
2. 未闭合的语法临时补全。 流式输出时,最后一段里没闭合的 **、*、`、~~、[文字](链接 会在解析前临时补上闭合符,所以 **加粗 一出现就显示为粗体,不会先显示星号、等右边的 ** 到了再突然变粗。代码块没闭合时不需要补,解析器会把它延伸到末尾。回答结束(SetStreaming(false))后按原文重新解析最后一块。
3. 写完的块跳过重建和重排。 写完的块通过 cx.Cache 缓存:元素树和布局结果都复用,每帧几乎不花时间;只有正在写的那一块每帧重建。富文本块还缓存测量结果,避免同一帧里被重复排版。
4. 看不见的不画。 滚动容器外的元素跳过绘制。
结果(Apple M 系列,一次追加加一帧的渲染、布局和绘制;go test -bench StreamingFrame ./ui/markdown):
| 文档大小 | 每帧耗时 | 优化前 |
|---|---|---|
| 2 KB | 0.19 ms | 1.3 ms |
| 11 KB | 0.52 ms | 5.0 ms |
60Hz 的一帧预算是 16ms。优化前的时间主要花在富文本每帧被完整排版三次;详见设计决策。
聊天界面的配套能力(在 ui/el 里)
| 能力 | 用法 |
|---|---|
| 跟随到底 | 滚动容器加 StickToBottom():在底部时随内容增长保持在底部;用户往上翻就停下,翻回底部恢复 |
| 发消息跳到底部 | ScrollToEndOn(len(msgs)):参数变化时跳到底部并恢复跟随 |
| 复制 | 代码块自带复制按钮;自己的按钮用 el.WriteClipboard(text) |
| 光标 | 流式输出时,正在写的位置显示一个光标 |
定制
包级变量,渲染前修改:
| 变量 | 默认 | 说明 |
|---|---|---|
CodeBg |
#f0f1f3 |
代码块背景 |
CodeBorder |
#e3e5e8 |
代码块边框 |
CodeHover |
#e2e5e9 |
代码块按钮悬停与选中背景 |
InlineCode |
#1f2328 |
行内代码颜色 |
CodeStyle |
github |
chroma 高亮风格名(需要引入 ui/highlight) |
MonoFace |
theme.MonoFace |
代码字体,中文回退到 theme.Face 里的中文字体 |
标题、正文颜色和字号跟随 ui/theme。
Agent 能看到什么
段落、标题是 text;段落里的每个链接是单独的 link 元素,值是网址,可以直接 click;代码块是 code,名字是语言或“纯文本”,里面的代码文字、“自动换行”或“取消自动换行”按钮,以及“复制”或“已复制”按钮单独列出;表格是 table 和 row。图片是 image,名字来自替代文字,值表示 loading、loaded 或 error;脚注是 footnotes 容器,引用和返回箭头可直接点击。
排版器
段落和代码用 text.go 里自己的富文本排版器,折行算法来自 gioui.org/x/styledtext,另外记录每段文字在每一行的位置,所以能画 Gio 富文本画不了的东西:行内代码的底色、删除线、链接下划线和选区,并给每个链接单独的点击区域。普通文字的行高固定(正文 1.6 倍、代码 1.45 倍字号;公式和图片可撑开行高),字形在行内垂直居中,不同字号共用基线,所以中英混排、代码里的中文注释不会让某一行变高或偏上。
selection.go 为整篇文档维护一个按 rune 计数的选区。绘制前读取各文字块的布局位置,把段落缩进、代码内边距、表格列位置统一到文档坐标,再将选区映射回每个块绘制高亮。滚动后仍按文档坐标定位;流式追加或结束时保留选区,SetSource 替换内容时清除选区。从链接开始拖选不会打开链接,单击仍触发 OnLink。
已知限制
数学排版覆盖日常和教科书里常见的 TeX,但不是完整的 TeX 引擎:不执行 TeX 包、文件命令或任意代码;不支持的命令保留源码。宏展开限制递归深度和输出长度,不提供完整 TeX 分组作用域或带分隔符的 \def 参数。图片暂不解码 SVG,也不播放 GIF 动画。
Doc.CodeBlockActions(func(*el.Context, markdown.CodeBlockContext) el.Element) 在默认代码块标题栏末尾添加操作,保留复制和换行按钮;返回 nil 不添加,传 nil 移除扩展。上下文包含稳定展示 ID、语言、原始代码文本和当前换行状态。代码不会自动执行,按钮的业务行为由应用提供。
Doc.CodeBlockRenderer(language, fn) 按语言替换整个代码块卡片,语言键忽略大小写,空语言匹配无语言代码。回调返回 nil 时使用默认代码卡片,传 nil 注销。替换展示后,按钮、文本选区及复制由应用实现;不自动叠加 CodeBlockActions。代码源文档保持不变。
两类回调只在渲染时构造元素,不应修改 Doc;应用状态修改放在事件处理函数中。代码块所在的列表、引用等包含块也会重新构建,以刷新自定义控件状态;其余文档继续使用块缓存。展示 ID 在解析器保留代码块状态期间稳定,不是持久文档标识。
示例:go run ./examples/components -section text_view。自动测试验证嵌套操作点击、换行状态及 ID 保留、替换/注销后的缓存更新与默认复制恢复。通用解析插件见上文;原生窗口完整交互尚未验收。
跨文档选择
Doc 默认各自管理选区。需要跨消息拖选时,保留一个 SelectionGroup,
把不同消息连接为同一段可选文本;消息可以位于嵌入根或虚拟列表内:
var selection markdown.SelectionGroup // 跨帧保留
selection.SetDocuments(first, second, third) // 完整的阅读顺序
// 在 Render 中构造共同父元素后调用:
return selection.Decorate(cx, el.Div().Child(first.Render(cx), second.Render(cx), third.Render(cx)))
共同父元素必须在拖选期间保持挂载,虚拟滚动列表放在它内部。嵌入根使用
LayoutIn 继承坐标和滚动父级。每个文档只传入一次,折叠详情和控件不加入。
拖选及 Cmd/Ctrl+A/C 可以跨文档操作,复制时消息之间保留空行。
前插历史、追加消息时,选区端点仍绑定原文档;Append 保留端点,
对组内文档调用 SetSource 会清除共享选区。
平时仍只挂载可见行。开始选择后,尚未展示过的文档会在屏幕外测量一次, 取得用于复制的渲染文本;文本和文档偏移缓存到内容变化为止。 自定义控件不属于 Markdown 选区。
正文、标题、表格测量和代码语言标签跟随 theme.Material.Face,与普通控件一致;代码保留 markdown.MonoFace。修改字体会使文档视图缓存失效,不改变原文。
流式渐显在空格前分段时,裁剪边界放在空格内部,避免换字体后切掉前一个字形超出逻辑宽度的笔画;相邻渐显片段共用同一边界。