Paper
paper让论文里的图跟着正文一步步变化,并能切到投稿用的打印形态
用法
流程图:正文引用驱动讲解
素材是《Attention Is All You Need》的架构图。点正文里的 Figure 1(b) 这类引用,图会切到那一步,必要时滚进视野并描边一下。当前步高亮,讲过的半透明,没讲到的很淡但不隐藏,读者始终看得到整张图。图下方可以逐步点、上一步 / 下一步、自动播放。右上角切到「打印预览」看投稿形态。
Encoder. Input tokens are first embedded and summed with positional encodings Figure 1(a). Each of the N = 6 encoder layers has a multi-head self-attention sub-layer Figure 1(b) and a position-wise feed-forward network Figure 1(c).
Decoder. Its self-attention is masked Figure 1(d), a further sub-layer attends over the encoder output Figure 1(e), and a linear layer with softmax yields next-token probabilities Figure 1(f). The whole model is shown in Figure.
<Paper>
<p>
… a multi-head self-attention sub-layer
<FigRef to={id} state="b">Figure 1(b)</FigRef> …
</p>
<ProcessFigure
id="transformer"
steps={[
{ key: "a", label: "Input embedding", description: "(a) …" },
{ key: "b", label: "Encoder self-attention", description: "(b) …" },
// …
]}
caption="The Transformer – model architecture."
>
<svg viewBox="0 0 600 704">
<FigureStep at="a">{/* 输入嵌入 + 位置编码 */}</FigureStep>
<FigureStep at="b">
<rect className="stroke-muted-foreground group-data-[phase=on]/step:stroke-primary" … />
</FigureStep>
<FigureStep at="b c">{/* 编码器外框,属于两步 */}</FigureStep>
</svg>
</ProcessFigure>
</Paper>参数图:预设加连续调节
状态不只是步骤,也可以是一组参数。正文引用只认有名字的预设,控件用 setState 直接给值。这里演示缩放点积注意力:不除以 √dₖ 时,dₖ 越大,softmax 越集中到一个词上。权重是手设的示意数据。
For small dk scaling makes little difference (Figure, dk = 4). For large dk the dot products grow large in magnitude and push the softmax into regions with extremely small gradients: unscaled, nearly all weight collapses onto one key (Figure, unscaled). Dividing by √dk restores a usable distribution (Figure, scaled).
<PaperFigure
id="attention"
states={{
scaled64: { dk: 64, scaled: true },
raw512: { dk: 512, scaled: false },
scaled512: { dk: 512, scaled: true },
}}
caption="Scaled dot-product attention for the query “it”."
describe={(s) => `d_k = ${s.dk}, ${s.scaled ? "scaled" : "unscaled"}`}
controls={(fig) => (
<Button onClick={() => fig.setState({ ...fig.state, scaled: !fig.state.scaled })}>
切换缩放
</Button>
)}
>
{(state) => <AttentionBars state={state} />}
</PaperFigure>
<FigRef to="attention" state="raw512">Figure 2, unscaled</FigRef>栅格图:热力图
热力图、注意力矩阵这类逐像素的图用 FigureRaster:在离屏 canvas 上画,以 PNG 嵌进图的 <svg>。所以它跟矢量部分共用一套坐标,打印分图各画各的,演示时按舞台缩放,导出 SVG 时原样带走(一份混合 SVG)。颜色用 token 取,切换明暗会重画,导出总是亮色。这里是原文公式 (2) 的正弦位置编码:拖滑块或在热力图上移动选一个维度,下方曲线是它沿位置的取值。
Each dimension of the positional encoding corresponds to a sinusoid, and the wavelengths form a geometric progression from 2π to 10000·2π (Figure). Low dimensions oscillate quickly along the sequence (Figure, i = 2), while higher dimensions change slowly (Figure, i = 20) and barely move within 64 positions (Figure, i = 50).
// 热力图画在图的 <svg> 里:坐标走 viewBox,打印分图、演示、导出 SVG 都照常工作
const drawEncoding = (ctx, { width, height, color }) => {
const positive = color("var(--color-chart-1)"); // 按所在位置的主题解析成 RGBA
const negative = color("var(--color-chart-3)");
const zero = color("var(--color-bg)");
const image = ctx.createImageData(width, height);
// … 每个像素按 PE(pos, dim) 在 zero 与 positive / negative 之间插值
ctx.putImageData(image, 0, 0);
}; // 模块级常量:引用不变就不重画
<PaperFigure
id="encoding"
states={{ c4: { dim: 4 }, c40: { dim: 40 }, c100: { dim: 100 } }}
printSubfigures={["c4", "c40", "c100"]}
caption="Sinusoidal positional encodings …"
controls={(fig) => (
<Slider aria-label="维度" min={0} max={127} value={fig.state.dim}
onValueChange={(v) => fig.setState({ dim: v })} />
)}
>
{({ dim }) => (
<svg viewBox="0 0 520 352">
<FigureRaster x={4} y={4} width={512} height={176}
resolution={[128, 64]} pixelated draw={drawEncoding} />
<rect x={4 + dim * 4} y={4} width={4} height={176} className="fill-none stroke-foreground" />
<path d={curveOf(dim)} className="fill-none stroke-primary" />
</svg>
)}
</PaperFigure>答辩演示
点「演示 ▶」进入全屏演示:按文档顺序把每张图的预设串成一组幻灯片,←/→、空格、PageUp/PageDown 翻页,Esc 退出,焦点回到按钮。演示层用同一个「状态 → 画面」函数重画图,不搬动正文里的图,退出后正文停在原来那一步。演示里图的控件照常可用:点步骤按钮直接翻到那一页,调参数只影响当前页。
Encoder. Input tokens are first embedded and summed with positional encodings Figure 1(a). Each of the N = 6 encoder layers has a multi-head self-attention sub-layer Figure 1(b) and a position-wise feed-forward network Figure 1(c).
Decoder. Its self-attention is masked Figure 1(d), a further sub-layer attends over the encoder output Figure 1(e), and a linear layer with softmax yields next-token probabilities Figure 1(f). The whole model is shown in Figure.
For small dk scaling makes little difference (Figure, dk = 4). For large dk the dot products grow large in magnitude and push the softmax into regions with extremely small gradients: unscaled, nearly all weight collapses onto one key (Figure, unscaled). Dividing by √dk restores a usable distribution (Figure, scaled).
Each dimension of the positional encoding corresponds to a sinusoid, and the wavelengths form a geometric progression from 2π to 10000·2π (Figure). Low dimensions oscillate quickly along the sequence (Figure, i = 2), while higher dimensions change slowly (Figure, i = 20) and barely move within 64 positions (Figure, i = 50).
<Paper>
<PaperPresenter
title="Attention Is All You Need"
trigger={<Button>演示 ▶</Button>}
// 默认:按文档顺序串起每张图的预设(流程图各步 + 全部)
// slides={[{ figure: "attention", state: "raw512" }, …]} 可以改写顺序
/>
<ProcessFigure id="transformer" steps={steps} caption="…">…</ProcessFigure>
<PaperFigure
id="attention"
states={presets}
presentStates={["scaled64", "raw512", "scaled512"]}
caption="…"
>
{(state) => <AttentionBars state={state} />}
</PaperFigure>
</Paper>公式与图联动
公式 (1) 里用 \term{dk}{…} 标出 √dₖ:点它切换图 2 的缩放,悬停或聚焦时图下方的缩放开关一起亮;反过来悬停开关,公式里的 √dₖ 也会亮。公式走 KaTeX,从 @hulianui/ui/math 引入,不进主入口。项上叠的是真按钮,键盘 Tab 得到、读屏念得出它会做什么。公式编号和图号一样用 CSS 计数器自动编号,服务端渲染、打印都有号;正文里的 EqRef 显示「公式 (N)」(英文论文是 Eq. (N)),点击滚到公式并描边。
We compute the dot products of the query with all keys, divide each by √dk, and apply a softmax to obtain the weights on the values:
For small dk scaling makes little difference (Figure, dk = 4). For large dk the dot products grow large in magnitude and push the softmax into regions with extremely small gradients: unscaled, nearly all weight collapses onto one key (Figure, unscaled). Dividing by √dk restores a usable distribution (Figure, scaled).
Since the model contains no recurrence, we add sinusoidal positional encodings to the input embeddings Eq.. Unlike the scaling in Eq., they carry no learned parameters.
// PaperEquation 从 @hulianui/ui/math 引入(KaTeX 不进主入口)
<Paper>
<p>… as shown in <EqRef to="attention-eq" /></p> {/* 正文显示「公式 (1)」,点击滚到公式并描边 */}
<PaperEquation
id="attention-eq" // 不传 number:和图号一样自动编号;number="A.1" 手写覆盖,number={null} 不编号
terms={{
dk: {
label: "√dₖ:切换图 2 的缩放",
figure: "attention",
state: (s) => ({ ...s, scaled: !s.scaled }), // 或预设名 "scaled512"
},
}}
>
{String.raw`\mathrm{softmax}\left(\frac{QK^T}{\term{dk}{\sqrt{d_k}}}\right)V`}
</PaperEquation>
<PaperFigure id="attention" states={presets} controls={(fig) => <ScaleToggle fig={fig} />} …>
{(state) => <AttentionBars state={state} />}
</PaperFigure>
</Paper>
function ScaleToggle({ fig }) {
const term = usePaperTerm("dk"); // 悬停 / 聚焦时公式里的 √dₖ 一起亮
return (
<Button {...term.bind} onClick={() => fig.setState({ ...fig.state, scaled: !fig.state.scaled })}>
切换缩放
</Button>
);
}逐状态导出 SVG
投稿时把每个状态的矢量图插进 Word,或转成 PDF 放进 LaTeX。导出时在屏幕外用同一个「状态 → 画面」函数画一遍,逐个元素读计算样式写成 SVG 属性,颜色换成十六进制,不再依赖页面的 CSS;默认按亮色主题导出,动画不进文件,正文里的图不受影响。下方预览是把导出的文件当 <img> 加载的样子。
function ExportButton({ figure, state }) {
const { exportFigureSvg } = usePaperExport(); // 必须在 Paper 里
return (
<Button
onClick={async () => {
const svg = await exportFigureSvg(figure, state, { background: "white" });
const a = document.createElement("a");
a.href = URL.createObjectURL(new Blob([svg], { type: "image/svg+xml" }));
a.download = `${figure}-${state}.svg`;
a.click();
}}
>
导出 SVG
</Button>
);
}
<Paper>
<ProcessFigure id="transformer" steps={steps} caption="…">…</ProcessFigure>
<ExportButton figure="transformer" state="b" />
</Paper>标题区与参考文献
PaperHeader 排题目、作者、说明行和摘要,题目夹在上粗下细两条线之间。Bibliography 按条目顺序编号,正文里的 Cite 按 id 取号:引几条时排序去重,连续三条及以上压成 1–3。点编号滚到那条文献并描边一下。「摘要」「参考文献」两个标题跟随 Paper 的论文语言。
Attention Is All You Need
- Ashish VaswaniGoogle Brain
- Noam ShazeerGoogle Brain
- Niki ParmarGoogle Research
- Jakob UszkoreitGoogle Research
- Llion JonesGoogle Research
- Aidan N. GomezUniversity of Toronto
- Łukasz KaiserGoogle Brain
- Illia Polosukhin
Abstract
The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder. We propose a new simple network architecture, the Transformer, based solely on attention mechanisms, dispensing with recurrence and convolutions entirely.
Recurrent models have been the standard approach to sequence modeling and transduction problems such as machine translation [?]. Attention mechanisms let a model relate positions regardless of their distance [?], and most competitive models have an encoder–decoder structure [?].
References
- [1]Sepp Hochreiter and Jürgen Schmidhuber. Long short-term memory. Neural Computation, 9(8):1735–1780, 1997.
- [2]Ilya Sutskever, Oriol Vinyals, and Quoc V. Le. Sequence to sequence learning with neural networks. In Advances in Neural Information Processing Systems, 2014.
- [3]Dzmitry Bahdanau, Kyunghyun Cho, and Yoshua Bengio. Neural machine translation by jointly learning to align and translate. CoRR, abs/1409.0473, 2014.
- [4]Jonas Gehring, Michael Auli, David Grangier, Denis Yarats, and Yann N. Dauphin. Convolutional sequence to sequence learning. arXiv preprint arXiv:1705.03122, 2017.
<Paper labels={{ figure: "Figure", separator: ": ", abstract: "Abstract", references: "References" }}>
<PaperHeader
title="Attention Is All You Need"
authors={[{ name: "Ashish Vaswani", affiliation: "Google Brain" }, …]}
meta="NIPS 2017"
abstract="The dominant sequence transduction models …"
/>
<p>
… such as machine translation <Cite to={["hochreiter1997", "sutskever2014"]} />.
</p>
<Bibliography
entries={[
{ id: "hochreiter1997", content: <>Sepp Hochreiter and Jürgen Schmidhuber. Long short-term memory. …</> },
{ id: "sutskever2014", content: <>Ilya Sutskever, Oriol Vinyals, and Quoc V. Le. …</> },
]}
/>
</Paper>打印形态
投稿用的 PDF 形态:每张图定格在打印态,控件不渲染,引用变回正文文字,流程图的每一步展开成 (a)(b)(c)… 分图。浏览器真的打印时,Paper 会在打印前自动切到这个形态,打印完再切回。
Encoder. Input tokens are first embedded and summed with positional encodings Figure 1(a). Each of the N = 6 encoder layers has a multi-head self-attention sub-layer Figure 1(b) and a position-wise feed-forward network Figure 1(c).
Decoder. Its self-attention is masked Figure 1(d), a further sub-layer attends over the encoder output Figure 1(e), and a linear layer with softmax yields next-token probabilities Figure 1(f). The whole model is shown in Figure.
<Paper mode="print">
<ProcessFigure
id="transformer"
steps={steps}
caption="…"
// 默认:主图画 "all",每一步展开一张分图
// printState="e" printSubfigures={["b", "e"]} 可以改
>
…
</ProcessFigure>
</Paper>何时用
把论文、讲义、答辩材料里的图做成「会动的插图」:正文写到「如图 1(b) 所示」时点一下,图切到那一步;投稿或打印时,每张图定格在打印态,流程图展开成 (a)(b)(c) 分图。适合流程图、架构图逐步讲解(ProcessFigure),以及参数会变的公式曲线、权重分布(PaperFigure)。只是一张静态配图,用普通 <figure> 就够;要自由拖拽编排节点用 Flow;要讲服务之间的调用顺序用 SequenceDiagram。
导入
import { Paper, PaperFigure, ProcessFigure, FigureStep, FigRef, EqRef, FigureRaster, PaperPresenter, usePaperMode, usePaperExport, usePaperTerm, usePaperNavigate, PaperHeader, Cite, Bibliography, PaperSection, SecRef, PaperOutline } from "@hulianui/ui"
import { PaperEquation } from "@hulianui/ui/math"
import type { ProcessStep, FigureRenderContext, PresenterSlide, FigureSvgExportOptions, FigureRasterContext, EquationTerm, PaperAuthor, BibliographyEntry } from "@hulianui/ui"结构
Paper 呈现形态(阅读 / 打印)+ 图的注册表 + 图号计数
├─ PaperHeader 标题区:题目、作者、摘要
├─ FigRef 正文引用:切到某个预设、滚到图、描边一下
├─ EqRef 公式引用「公式 (1)」:滚到公式、描边一下
├─ Cite 文献引用 [1, 2],按 Bibliography 编号
├─ PaperSection 自动编号的章节(1、2.1…)
├─ SecRef 章节引用「第 2.1 节」
├─ PaperOutline 目录(内部是 Anchor)
├─ usePaperNavigate 命令式导航:按钮里跳到图 / 公式 / 章节
├─ PaperEquation 公式,其中的项能和图联动(@hulianui/ui/math)
├─ PaperPresenter 答辩演示:全屏,把每张图的预设串成幻灯片
├─ Bibliography 参考文献列表
├─ PaperFigure<S> 通用图:状态是任意值 + 有名字的预设
└─ ProcessFigure 一步步讲的图(PaperFigure 的特化,状态就是步骤 key)
└─ FigureStep 标出图里某一部分属于哪一步
FigureRaster 图的 <svg> 里的一块栅格(热力图),任何图都能用核心约定只有一条:图只由状态决定画成什么样。PaperFigure 的 children 是「状态 → 画面」的函数,打印分图就是同一个函数在几个预设上各调一次。函数里藏的内部状态不会出现在分图和打印里。
Paper
继承 HTMLAttributes<HTMLElement>,ref 落在根元素上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| as | ElementType | "article" | 根元素标签 |
| mode | "read" | "print" | - | 受控形态 |
| defaultMode | "read" | "print" | "read" | 非受控初始形态 |
| labels | { figure?; separator?; abstract?; references?; equation?; section? } | 跟随界面语言 | 图注前缀、自动引用(含 EqRef 的「公式」/ "Eq."、SecRef 的「第 N 节」)、摘要与参考文献标题的文字。论文语言和界面不同时指定,如中文界面里排英文论文:{ figure: "Figure", separator: ": " }。步骤按钮等控件文字仍跟随界面语言 |
| 事件 | 类型 | 说明 |
|---|---|---|
| onModeChange | (mode: PaperMode) => void | 通过 usePaperMode 切换形态时触发 |
- 浏览器真正打印时(
beforeprint),Paper临时切到print,打印完(afterprint)切回,这一次不触发onModeChange。 - 图号和公式号用 CSS 计数器,服务端渲染和打印时都有号。
PaperFigure必须放在Paper里,否则每张图都是「图 1」。 - 正文用衬线字体:
var(--paper-font, "STIX Two Text", "Times New Roman", var(--hl-font-serif, serif))。西文先用 STIX Two Text / Times New Roman,中文和兜底回落到 tokens 的--hl-font-serif(默认汉字落到系统宋体)。只想换中文衬线就设--hl-font-serif,整个替换就在外层设--paper-font。Paper不接管标题、段落的样式,排版由你决定。
usePaperMode() 在 Paper 内部返回 [mode, setMode],用来做自己的「阅读 / 打印预览」切换。
PaperFigure
PaperFigureProps<S> 泛型,S 是状态的类型。继承 HTMLAttributes<HTMLElement>(不含 children / title / id),ref 落在根 <figure> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id * | string | - | 图的稳定 id,FigRef 靠它找图,同时是根 <figure> 的 id(可作锚点) |
| states * | Record<string, S> | - | 有名字的状态预设。键的书写顺序就是讲解顺序 |
| caption * | ReactNode | - | 图注正文,「图 N:」前缀自动生成 |
| children * | (state: S, figure: FigureRenderContext<S>) => ReactNode | - | 画图。只能由 state 决定画面 |
| defaultState | string | states 第一个键 | 初始预设 |
| printState | string | 同 defaultState | 打印形态下主图用的预设 |
| printSubfigures | string[] | - | 打印形态下在主图下方展开成 (a)(b)… 分图的预设 |
| presentStates | string[] | states 全部键 | PaperPresenter 演示时依次展示的预设;[] 表示演示时跳过这张图 |
| describe | (state: S, key: string | null) => ReactNode | - | 图注第二行,说明当前状态;变化时读屏会念 |
| subfigureLabel | (key: string, index: number) => ReactNode | (a) + describe | 分图小标题 |
| controls | (figure: FigureRenderContext<S>) => ReactNode | - | 图下方的交互控件,只在阅读形态渲染 |
| hideCaption | boolean | false | 不渲染图注(「图 N:…」整条,含状态说明)。图号照常递增,后面的图不跳号 |
| hideDescription | boolean | false | 不渲染图注第二行的状态说明。hideCaption 时自然也没有 |
| collapsibleControls | boolean | false | 控件行可收起:末尾多一个图标按钮;收起后整行不占位,只剩图角上一个悬停 / 键盘聚焦才出现的「显示控件」(触屏常显) |
| defaultControlsCollapsed | boolean | false | 初始就收起控件行(仅 collapsibleControls 时有效)。首页那种「先看动画、要细看再展开」的图用它 |
| 事件 | 类型 | 说明 |
|---|---|---|
| onStateChange | (state: S, key: string | null) => void | 用户操作、FigRef 跳转都会触发 |
FigureRenderContext<S>:
interface FigureRenderContext<S> {
state: S; // 当前画的状态
stateKey: string | null; // 对应的预设名;用 setState 直接给值时为 null
select: (key: string) => void; // 切到预设
setState: (state: S) => void; // 直接给值(滑块、开关)
mode: "read" | "print";
presenting?: boolean; // 在演示层里画(放映时 autoPlay 不生效)
}ProcessFigure
一步步讲的图。状态就是步骤的 key,外加保留名 "all"(每一部分都亮着)。继承 PaperFigure 的 id / caption / defaultState / subfigureLabel / onStateChange 和原生属性。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| steps * | ProcessStep[] | - | 按讲解顺序排列的步骤 |
| children * | ReactNode | - | 图本身,一般是用 FigureStep 标好各部分的 SVG |
| overview | boolean | true | 是否有「全部」状态 |
| overviewDescription | ReactNode | - | 「全部」状态的说明 |
| printState | string | "all"(无 overview 时为最后一步) | 打印态 |
| printSubfigures | string[] | 每一步各一张 | 打印分图;传 [] 不展开 |
| presentStates | string[] | 各步 + "all" | 演示时依次展示的预设 |
| interval | number | 2200 | 自动播放每步停留的毫秒数。倍速在它的基础上乘除 |
| autoPlay | boolean | false | 进视口后自己开播,不用等人点。滚出视口暂停、滚回来接着播;读者按过暂停,或从正文引用 / 卡片上的定位按钮改了状态,就由读者接管、不再自动恢复;prefers-reduced-motion: reduce 下不自动播 |
| loop | boolean | false | 播到最后一步后回到第一步继续(默认播完停下)。控件上的循环按钮也能直接开关 |
| speeds | number[] | [0.5, 1, 1.5, 2] | 倍速档位,1 = interval 原速。传 [] 不渲染倍速按钮 |
| defaultSpeed | number | 1 | 初始倍速,不在 speeds 里时用第一个档位 |
interface ProcessStep {
key: string; // 不能用 "all"
label: string; // 短名:步骤按钮提示、分图小标题
description?: ReactNode; // 图注第二行
}图下方自带步骤控件:上一步 / 下一步(首尾禁用)、每一步一个字母按钮(a、b、c…)、「全部」、播放 / 暂停、循环开关、倍速按钮(1× 这种,点一下换下一档)。播放到最后一步默认停下,loop 或控件上的循环按钮打开后回到第一步继续。配合 collapsibleControls 可以整排收起,图角上留一个悬停才现的「显示控件」,不给图下加一行。
FigureStep
<g> 元素,标出图里一部分属于哪一步,只能放在 SVG 里。继承 SVGAttributes<SVGGElement>。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| at * | string | string[] | - | 属于哪一步。可以属于几步:["b", "c"] 或 "b c" |
| until | string | - | 从哪一步起被取代、不再画出。讲到 until 及之后、以及「全部」状态下隐藏(导出 SVG 时也不进文件)。用于会移动的东西:分支指针、被替换的旧节点 |
它带 data-phase:
| phase | 含义 | 组件给的样式 |
|---|---|---|
on | 正在讲这一步 | 不透明 |
done | 已经讲过 | 半透明 |
off | 还没讲到 | 很淡,但不隐藏,读者始终看得到整张图 |
all | 「全部」状态 | 不透明,不强调 |
gone | 带 until,已被取代或处于「全部」 | 不渲染(display: none) |
组件只管透明度。强调色和流动虚线由你在图里写,FigureStep 带 group/step:
<FigureStep at="b">
<rect className="stroke-muted-foreground group-data-[phase=on]/step:stroke-primary" />
<path className="stroke-muted-foreground group-data-[phase=on]/step:[stroke-dasharray:5_4] group-data-[phase=on]/step:motion-safe:animate-[hulian-paper-flow_0.9s_linear_infinite]" />
</FigureStep>会移动的部分画两份,旧的一份写 until。下例里 main 指针在 (a)(b) 指向 C2,(c) 起移到 C3;「全部」和打印主图里只剩 C3 上那一个:
<FigureStep at="a" until="c"><RefLabel x={150} label="main" /></FigureStep>
<FigureStep at="c"><RefLabel x={240} label="main" /></FigureStep>hulian-paper-flow 关键帧在 @hulianui/tokens 的 preset-core.css 里。
FigureRaster
图里逐像素的部分:热力图、注意力矩阵、显微照片。<image> 元素,只能放在图的 <svg> 里。draw 在离屏 canvas 上画,编码成 PNG 写进 href。继承 SVGAttributes<SVGImageElement>(不含 href),ref 落在 <image> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| width / height | number | - | 在图的 SVG 坐标(viewBox)里的大小 |
| x / y | number | 0 | 在图的 SVG 坐标里的位置 |
| resolution * | [宽, 高] | - | 画布像素尺寸。数据栅格一般就是数据的列数和行数 |
| draw * | (ctx, { width, height, color }) => void | - | 在画布上画。只能由数据决定画面。按引用比较,引用不变就不重画,所以提到模块级常量或用 useCallback |
| pixelated | boolean | false | 一个像素就是一个数据格:放大后保持方块,不插值。照片类栅格保持 false |
| preserveAspectRatio | string | "none" | 默认拉伸填满 width × height,和数据格的坐标一一对应 |
color(css) 把任意 CSS 颜色(含 var(--color-chart-1) 这类 token)按栅格所在位置的主题解析成 0–255 的 [r, g, b, a],可以直接写进 ImageData。
const drawHeat = (ctx, { width, height, color }) => {
const positive = color("var(--color-chart-1)");
const negative = color("var(--color-chart-3)");
const zero = color("var(--color-bg)");
const image = ctx.createImageData(width, height);
// … 每个像素按数值在 zero 与 positive / negative 之间插值
ctx.putImageData(image, 0, 0);
};
<PaperFigure id="encoding" states={presets} printSubfigures={["c4", "c40"]} caption="…">
{({ dim }) => (
<svg viewBox="0 0 520 352">
<FigureRaster x={4} y={4} width={512} height={176} resolution={[128, 64]} pixelated draw={drawHeat} />
<rect x={4 + dim * 4} y={4} width={4} height={176} className="fill-none stroke-foreground" />
</svg>
)}
</PaperFigure>- 为什么放进 SVG:画面仍然是单独一个
<svg>,所以栅格和矢量部分(坐标轴、标记、曲线)共用viewBox坐标。打印分图里每份各画各的,演示时按舞台缩放,导出 SVG 时原样内嵌,得到一份混合 SVG。 - 主题:颜色在栅格自己的位置解析。页面上任意一处
data-theme改变或系统明暗切换时重画;导出时在亮色槽里画,所以导出的总是亮色。 - pixelated:编码时按整数倍最近邻放大(编码尺寸约为显示尺寸的 3 倍,长边不超过 4096 像素)。Word、PDF 转换器这些不认
image-rendering的地方也是锐利的方块。 - 时机:在 layout effect 里画。浏览器打印前
Paper同步切到打印态,分图的栅格在打印快照之前就已画好。服务端渲染时输出没有href的<image>,位置已经占好,不会跳动。 - 栅格不响应指针。要在上面选点,就叠一个透明的
<rect>接事件,键盘操作交给图下方的控件(如Slider)。 - 发散数据(有正有负)用两个色相加中性的中点,例如
chart-1/chart-3加底色。不要用warning/danger这类状态色。
FigRef
<a href="#id">,继承 AnchorHTMLAttributes(不含 href),ref 落在 <a> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| to * | string | - | 目标图的 id |
| state | string | - | 要切到的预设;不传只跳到图,不改状态 |
| children | ReactNode | 「图 N」 | 引用文字。不传时按文档顺序自动取号(挂载后才有号);state 是这张图的打印分图之一时带上分图字母,如「图 1(b)」,与打印版一致(ProcessFigure 默认每一步都是分图) |
点击时:把图切到 state → 图不在视野里就滚过去(减弱动效时不平滑滚动)→ 图描边约 1.2 秒。没有 JS 或不在 Paper 里时退化成普通锚点。打印形态下去掉链接色和下划线。
Button 这类本身就是交互元素的触发器不要写 render={<FigRef/>}:引用本体是 <a>,会继承链接色和下划线,也破坏按钮语义。改用下方的 usePaperNavigate。
PaperPresenter
答辩演示:一个全屏层,把论文里每张图的预设串成一组幻灯片。放在 Paper 里任意位置(一般是工具栏)。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| trigger | ReactElement | - | 打开演示的按钮,如 <Button>演示</Button>。关闭后焦点回到它 |
| open | boolean | - | 受控:是否打开。不用 trigger 时用它打开,关闭后焦点回到打开前聚焦的元素 |
| defaultOpen | boolean | false | 非受控初始是否打开 |
| title | ReactNode | - | 页眉左侧的标题,一般是论文题目 |
| slides | PresenterSlide[] | 见下 | 整组幻灯片,{ figure: 图 id, state: 预设名 } |
| controls | boolean | true | 是否渲染图自带的控件(步骤按钮、参数开关) |
| hideChrome | boolean | false | 初始就隐藏演示界面(标题、页码、退出、翻页条),只留画面。顶栏的「隐藏界面」收起、画面右上角的「显示界面」唤回 |
| className | string | - | 加在全屏层根元素上 |
| 事件 | 类型 | 说明 |
|---|---|---|
| onOpenChange | (open: boolean) => void | 打开 / 关闭(含 Esc、退出按钮) |
| onSlideChange | (slide: PresenterSlide, index: number) => void | 翻到某一页时触发,含打开时的第一页 |
- 幻灯片怎么来:默认按文档顺序,把每张图的
presentStates依次排开。PaperFigure默认是全部预设,ProcessFigure默认是各步加「全部」。传slides可以整体改写顺序,或把几张图交错着讲;不存在的图或预设在开发环境告警一次并跳过。页眉里的图号始终按文档顺序。 - 不搬 DOM:演示层用图的同一个
children(state)函数再画一遍,正文里的图不动、状态不变,退出后读者还停在原来那一步。图的 props 变了(如切换语言),演示里跟着重画。 - 图的控件照常可用:控件
select到某个预设时翻到对应那一页(ProcessFigure的步骤按钮就是跳页);setState给的值只覆盖当前页,翻页即还原。 - 界面可以收掉:顶栏的「隐藏界面」把标题、页码、退出和翻页条一起收走,只剩幻灯片;画面右上角的「显示界面」把它们叫回来。放映前只想让观众看画面时用
hideChrome直接以收起态打开。 - 按键:
→/空格/PageDown下一页,←/PageUp上一页,Esc退出。焦点在输入框、滑块、单选组等控件上时,方向键留给控件;焦点在按钮上时,空格是按下按钮。 - 无障碍:
role="dialog",名字是「演示模式」(跟随界面语言)。焦点困在演示层里,打开后落在「下一页」,退出后回到触发按钮。演示层之外的内容对读屏隐藏。 - 演示层渲染在
Paper的 DOM 之外(Portal),打开时沿用Paper所处位置的字体(含--paper-font等覆盖)和主题岛(Paper最近的data-theme祖先,演示中切换也跟着变)。只靠自定义属性局部改色、不带data-theme的容器传不进演示层。图的渲染函数若依赖放在Paper与图之间的 context,演示里取不到。 - SVG 图在演示里按舞台高度撑满(宽度跟着
viewBox比例),不需要另写演示尺寸。
<Paper>
<PaperPresenter title="Attention Is All You Need" trigger={<Button>演示 ▶</Button>} />
<ProcessFigure id="transformer" steps={steps} caption="…">…</ProcessFigure>
<PaperFigure id="attention" states={presets} presentStates={["scaled64", "raw512", "scaled512"]} caption="…">
{(state) => <AttentionBars state={state} />}
</PaperFigure>
</Paper>逐状态导出 SVG
投稿时把每个状态的矢量图插进 Word,或转成 PDF 放进 LaTeX。在 Paper 里用 usePaperExport():
const { exportFigureSvg } = usePaperExport();
const svg = await exportFigureSvg("transformer", "b", { background: "white" }); // SVG 文本exportFigureSvg(id, stateKey, options?) => Promise<string>:
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
| theme | "light" | "current" | "light" | 按哪套主题出色。默认亮色:读者开着暗色也导出白纸上的图 |
| background | string | 透明 | 底色,任意 CSS 颜色 |
| width | number | viewBox 的宽 | 输出的 width(px),高度按比例 |
- 怎么做的:在
Paper里临时挂一个屏幕外的槽,用图的同一个children(state)画出这个预设(画面的mode是"print"),等字体就绪后逐个元素读计算样式,写成 SVG 表现属性(fill="#…"、stroke-width="1.3"…),去掉class/style/data-*。正文里的图不受影响。 - 颜色:Tailwind 类和 CSS 变量离开页面就失效,浏览器给的计算值又常是
oklab()/oklch(),Word、Inkscape 不认。导出时一律换成#rrggbb,透明度并进fill-opacity/stroke-opacity。 - 定格:动画和过渡在槽里关掉,流动虚线定格在起点;
FigureStep的阶段透明度按导出的那一步算。display: none的元素不进文件;aria-label变成<title>(Word 当替代文字用)。 - 文字保留为
<text>,带上Paper的字体栈。写入的是计算后的整条字体栈:打开文件的机器上没有 STIX Two Text 时回退到 Times New Roman,中文落到--hl-font-serif里的字体或系统衬线(宋体)。LaTeX 里用\includesvg(svg 宏包,需要 Inkscape)或先转成 PDF,转换的机器上要装好字体。 - 前提:图的画面必须是单独一个
<svg>。画面是裸的 canvas、HTML 或带<foreignObject>时 reject 并说明原因(canvas 栅格改用FigureRaster画在<svg>里,导出时以 PNG 内嵌);图找不到、预设不存在时也 reject。 - 图里的 CSS
transform(如 Tailwind 的rotate-*)不会写进文件,要旋转、平移请用 SVG 的transform属性。
公式与图联动
公式里的某一项可以点、可以悬停,和图的状态、控件互相高亮。分两半:
PaperEquation:从@hulianui/ui/math引入。公式走 KaTeX,放在主入口会把 KaTeX 拉进每个消费方的包里。usePaperTerm:从@hulianui/ui引入,给图里的控件用,不依赖 KaTeX。
import { PaperEquation } from "@hulianui/ui/math";
import { usePaperTerm } from "@hulianui/ui";
<PaperEquation
number={1}
terms={{
dk: { label: "√dₖ:切换图 2 的缩放", figure: "attention", state: (s) => ({ ...s, scaled: !s.scaled }) },
}}
>
{String.raw`\mathrm{softmax}\left(\frac{QK^T}{\term{dk}{\sqrt{d_k}}}\right)V`}
</PaperEquation>
function ScaleToggle({ fig }) {
const term = usePaperTerm("dk");
return <Button {...term.bind} className="data-[active]:text-primary" onClick={…}>切换缩放</Button>;
}PaperEquation
继承 HTMLAttributes<HTMLDivElement>(不含 children),ref 落在根元素上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| children * | string | - | 整条公式的 LaTeX(数学模式,不用包 $)。用 \term{name}{…} 标出可交互的项,name 只能是字母、数字、_、- |
| terms | Record<string, EquationTerm> | - | 各项的配置,键是 name |
| number | ReactNode | 自动编号 | 右侧的编号。在 Paper 里不传时自动编号,见下方「公式编号与 EqRef」;传值显示成 (值),不占自动编号(同 LaTeX \tag);传 null / false 不编号。在 Paper 外不传时不编号 |
| display | boolean | true | 块级排版 |
| macros | Record<string, string> | - | 自定义宏,透传给 KaTeX;\term 是保留名 |
interface EquationTerm {
label: string; // 读屏名和悬停提示,说清点了会怎样
figure?: string; // 点击驱动的图 id;不传则这一项只做高亮联动,不能点
state?: string | ((current: unknown) => unknown); // 预设名,或由当前状态算新状态
}- 点击:
state是预设名就切到那个预设,是函数就用图的当前状态算出新状态(如开关取反)。之后和FigRef一样,图不在视野里就滚过去并描边。 - 高亮:悬停或聚焦公式里的项时,用
usePaperTerm绑定了同名的控件active为 true;悬停或聚焦控件时,公式里的项带data-active高亮。 - 可达性:KaTeX 的 HTML 层整体是
aria-hidden,读屏读的是并排的 MathML,项本身不能聚焦。PaperEquation在每个可点的项上叠一个透明的真<button>(aria-label即label),键盘 Tab 得到,焦点环画在项上。尺寸变化和字体加载后会重新定位。 - 安全:
\term展开成 KaTeX 的\htmlData。trust 只放行「唯一属性是paper-term、值是安全名字」的这一种,\href、\htmlClass、\includegraphics等照旧拒绝。 - 打印形态下不叠按钮、不高亮。公式里写了
terms没配的项,开发环境告警一次。
usePaperTerm
usePaperTerm(name) => { active, bind }。把 bind 展开到控件(或图的一部分)上,悬停、聚焦时公式里同名的项会亮。高亮时 bind 带 data-active,可以用 data-[active]: 写样式。在 Paper 外调用时 active 恒为 false。
公式编号与 EqRef
<p>… as shown in <EqRef to="attention" />.</p> {/* 「公式 (1)」,英文论文 "Eq. (1)" */}
<PaperEquation id="attention">{String.raw`\mathrm{softmax}(QK^T/\sqrt{d_k})V`}</PaperEquation> {/* (1) */}
<PaperEquation number="A.1">{…}</PaperEquation> {/* (A.1),不占号 */}
<PaperEquation number={null}>{…}</PaperEquation> {/* 不编号 */}
<PaperEquation>{…}</PaperEquation> {/* (2) */}- 自动编号:在
Paper里不传number的公式占 CSS 计数器的一个号,和图号一样,服务端渲染和打印时都有号,不等 JS。手写number覆盖显示、不占号;null/false不编号。 EqRef从@hulianui/ui引入(不依赖 KaTeX),是<a href="#id">,继承AnchorHTMLAttributes(不含href),ref落在<a>上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| to * | string | - | 目标公式的 id(写在 PaperEquation 上) |
| children | ReactNode | 「公式 (N)」 | 引用文字。不传时按文档顺序自动取号(挂载后才有号),手写覆盖的号原样显示 |
- 点击:公式不在视野里就滚过去(减弱动效时不平滑),公式描边约 1.2 秒。没有 JS 或不在
Paper里时退化成普通锚点;打印形态下去掉链接色。 - 「公式」/ "Eq." 属于论文内容,跟随
Paper的labels.equation,不传时跟随界面语言。 - 找不到公式时点击告警一次;引用了
number={null}的公式时只显示「公式」,开发环境告警一次。 - 公式 id 和图 id、文献 id 共用页面的 DOM id 空间,不要取同名。
标题区与参考文献
PaperHeader
论文标题区:题目夹在上粗下细两条线之间,下面是作者、一行说明、摘要。和 Paper 不同,它自带排版。继承 HTMLAttributes<HTMLElement>(不含 title),ref 落在 <header> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| title * | ReactNode | - | 论文题目 |
| titleAs | ElementType | "h1" | 题目的标签 |
| authors | PaperAuthor[] | - | { name, affiliation?, email? },居中换行排列 |
| meta | ReactNode | - | 作者下方的一行说明,如会议、日期、arXiv 号 |
| abstract | ReactNode | - | 摘要。字符串会包成一个段落;标题是 labels.abstract |
Bibliography 与 Cite
<p>… machine translation <Cite to={["hochreiter1997", "sutskever2014"]} />.</p>
<Bibliography
entries={[
{ id: "hochreiter1997", content: <>Sepp Hochreiter and Jürgen Schmidhuber. Long short-term memory. …</> },
{ id: "sutskever2014", content: <>Ilya Sutskever, Oriol Vinyals, and Quoc V. Le. …</> },
]}
/>Bibliography 继承 HTMLAttributes<HTMLElement>(不含 title),ref 落在 <section> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| entries * | BibliographyEntry[] | - | { id, content },按编号顺序,第一条是 [1]。id 同时是条目 <li> 的 DOM id |
| title | ReactNode | labels.references | 标题;传 null 不渲染 |
| titleAs | ElementType | "h2" | 标题的标签 |
Cite 是 <span>,继承 HTMLAttributes<HTMLSpanElement>(不含 children),ref 落在 <span> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| to * | string | string[] | - | 引用的文献 id,可以是几条 |
- 编号:按
Bibliography里的顺序。一处引几条时排序去重,两个相邻写成[1, 2],连续三条及以上压成[1–3],每个号各自链接到条目。 - 点击:滚到条目(减弱动效时不平滑),条目描边约 1.2 秒。没有 JS 时是普通锚点。打印形态下去掉链接色。
- 号要等
Bibliography挂载登记后才有(同FigRef的自动图号),服务端渲染时先显示[?]。找不到的 id 显示?,开发环境告警一次。 - 同一个
Paper只放一份Bibliography;有两份时告警,Cite按后登记的那份编号。 - 「摘要」「参考文献」两个标题属于论文内容,跟随
Paper的labels(abstract、references),不跟界面语言。 - 条目 id 和图 id 共用页面的 DOM id 空间,不要取同名。
章节编号、SecRef 与目录
<Paper>
<PaperOutline className="sticky top-6" /> {/* 目录,编号与正文一致 */}
<p>细节见 <SecRef to="objects" />。</p> {/* 「第 2.2 节」 */}
<PaperSection id="intro" title="引言">…</PaperSection> {/* 1 引言 */}
<PaperSection id="model" title="模型">
<PaperSection id="trees" title="三棵树">…</PaperSection> {/* 2.1 */}
<PaperSection id="objects" title="对象">…</PaperSection> {/* 2.2 */}
</PaperSection>
<PaperSection id="ack" title="致谢" numbered={false}>…</PaperSection>
</Paper>PaperSection
<section>,继承 HTMLAttributes<HTMLElement>(不含 title),ref 落在 <section> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id * | string | - | 章节 id,SecRef / PaperOutline 靠它找章节,同时是 <section> 的 id |
| title * | ReactNode | - | 标题,层级编号自动加在前面 |
| titleAs | ElementType | 按深度 h2 / h3 / h4 | 标题标签 |
| titleClassName | string | - | 加在标题上,改标题排版 |
| numbered | boolean | true | 是否编号。致谢、附录传 false;不要在不编号的章节里再嵌编号的子节 |
- 编号:CSS 计数器
paper-section,嵌套的子节自动成为「2.1」「2.1.3」,服务端渲染和打印时都有号。PaperSection必须放在Paper里。 - 标题样式:和
Paper不接管正文不同,章节标题自带一套克制的默认排版(字号随深度递减),用titleClassName改。
SecRef
<a href="#id">,继承 AnchorHTMLAttributes(不含 href),ref 落在 <a> 上。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| to * | string | - | 目标章节的 id |
| children | ReactNode | 「第 N 节」 | 引用文字。不传时按文档顺序和嵌套取号(挂载后才有号,服务端先显示「第 ? 节」);引用不编号的章节时显示其标题 |
- 点击:标题不在视野里就滚过去(减弱动效时不平滑),标题描边约 1.2 秒。没有 JS 或不在
Paper里时是普通锚点;打印形态下去掉链接色。 - 「第 N 节」/ "Section N" 属于论文内容,跟随
Paper的labels.section(函数,(n) => string),不传时跟随界面语言。
PaperOutline
论文目录。从章节注册表生成,编号与正文标题一致;内部就是 Anchor(滚动高亮 + 平滑跳转),继承 Anchor 除 items 外的全部 props(offsetTop、getContainer、onChange)。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| depth | 1 | 2 | 2 | 列到第几层。Anchor 最多两层,第三层子节不进目录 |
- 放在
Paper里任意位置,一般是侧栏:<Paper as="div">包住「目录 +<article>正文」两栏。 - 挂载后才有条目(服务端渲染为空);打印形态下不渲染。页面滚动体不是 window 时照
Anchor的要求传getContainer。 - 章节 id 和图、公式、文献 id 共用页面的 DOM id 空间,不要取同名。
命令式导航
Button、Menu.Item 这类本身就是交互元素的触发器,不要用 render={<FigRef/>} 把引用嵌进去:引用本体是 <a>,会继承链接色和下划线,也破坏按钮语义。改用 usePaperNavigate(),在事件里跳转:
const navigate = usePaperNavigate();
<Button onClick={() => navigate.figure("attention", "b")}>看图 2(b)</Button>
<Button onClick={() => navigate.equation("attention-eq")}>看公式 (1)</Button>
<Button onClick={() => navigate.section("method")}>看第 2 节</Button>| 方法 | 说明 |
|---|---|
| figure(id, state?) | 跳到图。state 是预设名,传了就切到那一步;之后和 FigRef 一样滚进视野、描边约 1.2 秒 |
| equation(id) | 跳到公式,滚过去并描边;同 EqRef |
| section(id) | 跳到章节,滚到标题并描边;同 SecRef |
- 只做跳转,不改 URL hash。要可分享、能在新标签页打开的锚点链接,仍用
FigRef/SecRef/EqRef。 - 目标不存在时开发环境告警一次,不做任何跳转;在
Paper外调用不跳转,开发环境同样告警一次。 usePaperNavigate()本身要在Paper里调用,返回的方法可以传进任意事件回调。
注意
- 图里不要写
id(SVGmarker、clipPath、渐变)。打印分图会把同一张图渲染好几遍,id 会重复。箭头直接画成polygon。 - 分图是
aria-hidden的:读屏读主图和图注就够了,不把同一张图念六遍。 - 预设名在一张图里唯一;
FigRef引用不存在的图或预设,开发环境告警一次,状态不变。 - 同一个
Paper里图 id 重复时,引用只会找到后挂载的那一张,并告警。
Playground
Encoder. Input tokens are first embedded and summed with positional encodings Figure 1(a). Each of the N = 6 encoder layers has a multi-head self-attention sub-layer Figure 1(b) and a position-wise feed-forward network Figure 1(c).
Decoder. Its self-attention is masked Figure 1(d), a further sub-layer attends over the encoder output Figure 1(e), and a linear layer with softmax yields next-token probabilities Figure 1(f). The whole model is shown in Figure.
<Paper>
<ProcessFigure id="transformer" steps={steps} caption="…">
<TransformerArchitecture />
</ProcessFigure>
</Paper>