基础组件
标题、文本、按钮、标签、提示、进度、统计、加载、Markdown、代码高亮等最高频的展示组件。每个示例左侧为格式化 + 高亮的 TokUI DSL，右侧为实时渲染，点「编辑」可即时改动。
标题 h1 ~ h6
六级标题，自闭合。tx 文本（可省略直接写正文），v 控制对齐与装饰，bg / fc 配色。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 文本内容（亦可直接写正文） | [h1 标题] |
v | 变体（对齐 / 装饰，可逗号组合） | v:underline、v:"center,ribbon" |
bg | 背景/装饰主色：主题色名（primary/success/warning/danger/dark/light）或 6 位 hex（不带 #） | bg:success、bg:722ed1 |
fc | 文字颜色（取值同 bg） | fc:danger |
id | 元素 ID（供 upd/del/ins 定位） | id:title1 |
变体：left / center / right（对齐），ribbon（缎带），underline（下划线），badge / pill（徽标）。装饰色变体（ribbon/badge/pill/underline）统一走「浅底 + 主色文字」配色：bg: 指定主色后自动派生 10% 浅底与淡描边，深浅主题自适应。bg 不带装饰变体时则为整行实底。
六级字号对比：
对齐变体：
装饰变体（bg 换主色）：
bg 实底 + fc 文字色、对齐与装饰组合：
段落 p
正文段落，双模（与 card 的 tx 自闭合陷阱同理）：标签内有正文 → 叶子自闭合；无正文 → 容器收子节点。v 控制对齐与字重。
- 叶子模式
[p 文本]/[p v:bold 文本]：文本作正文，可夹内联子节点（a/tag/b/strong/em/mark/spin/sub/sup/code），遇块级兄弟自动闭合。 - 容器模式
[p]...[/p]：放btn/form/card等块级子节点时用，必须[/p]闭合。 - 正文里写
英文:值（如Q:/A:）会被解析成属性吞掉（无空格→正文空、带空格→前缀消失）——改全角：或去冒号（详见 DSL 语法）。
变体：left / center / right（对齐），muted（弱化），bold（加粗），sm / lg（字号）。
链接 a
超链接，自闭合。u 地址、tx 文本、target 打开方式。
| 属性 | 含义 | 示例 |
|---|---|---|
u | 链接地址 | u:https://tokui.jboltai.com |
tx | 文本 | tx:官网 |
target | 打开方式 | target:_blank |
v | 变体 | v:underline |
变体：muted / danger / success / underline。
分割线 hr / dv
hr 普通水平线（自闭合）。dv 带文本与样式的分割线（自闭合）。
| 属性 | 含义 | 适用 |
|---|---|---|
tx | 分割线文本 | dv |
v | 线型/方向 | dv |
bg | 颜色 | dv |
dv 变体：dashed / dotted（线型），sm / md / lg（间距），vert（竖向），plain。
图片 img / 多图 imgs
img 单图，点击可灯箱预览。imgs 容器，多图自适应九宫格。
| 属性 | 含义 | 示例 |
|---|---|---|
s | 图片地址 | s:https://... |
alt | 替代文本 | alt:封面 |
w / h | 宽 / 高 | w:120 |
v | 变体 | v:avatar |
img 变体：avatar（头像），rounded（圆角），bordered（边框）。
imgs 多图：s 用逗号分隔多个 URL，自动排成 1~9 宫格。
图片预览组 preview-group
容器。把一组 img 绑定为共享预览会话：点击其中任意一张即开灯箱，并携带整组 src 列表（灯箱支持缩放 / 旋转 / 翻转 / 计数 / 前后切换）。流式渲染中后到的图自动入组。
| 属性 | 含义 | 示例 |
|---|---|---|
id | 元素 ID | id:gallery |
与
imgs的区别：imgs是九宫格简写布局，preview-group是显式「一组图共享预览会话」语义，组内图片排版照旧。
键盘按键 kbd
自闭合行内元素。键帽样式文本，适合快捷键/操作说明文档；可作为 p 的行内子节点与文字混排。
变体：sm / lg。
浮动按钮组 float-button
容器。将一组子组件（btn/backtop 等）固定于视口四角，子组件自动圆形悬浮化。
| 属性 | 含义 | 示例 |
|---|---|---|
pos | 固位：right-bottom（缺省）/ right-top / left-bottom / left-top | pos:left-top |
offset | 距视口边距（px，缺省 24） | offset:80 |
按钮 btn / 按钮组 btngroup
btn 自闭合，最常用交互组件。btngroup 容器包裹一组按钮。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 文本 | tx:提交 |
clk | 点击处理器名 | clk:onSave |
sub | 表单提交处理器名（内置 submit 动作） | sub:onSubmit |
reset | 重置绑定表单（内置 reset 动作，裸写或 reset:H 回调） | reset |
print | 打印目标区域（内置 print 动作，print:ID / print:self） | print:invoice |
form | 显式绑定表单 ID（按钮在表单外时用） | form:loginForm |
dis | 禁用 | dis |
w | 宽度 | w:200 |
bg / fc | 背景色 / 文字色 | bg:4f46e5 |
v | 变体（类型/尺寸/形状） | v:"primary,pill" |
icon | SVG 图标名（自动继承钮色） | icon:view |
i | emoji / 字符图标 | i:🔍 |
l | icon-only 标签（无障碍 + 悬停 tooltip） | l:删除 |
内置动作：
sub/reset/registerHandler（仅sub的业务回调仍需注册）。优先级print > reset > submit > clk。详见表单组件 · 表单动作与打印区。
类型变体：primary / danger / success / warning / ghost。 尺寸/形状变体：sm / lg / pill（圆角）/ square（直角）/ block（块级宽）。
图标按钮
两种图标来源，[btn] 与表格操作列通用：
icon:NAME— 内置 SVG（Lucide 风格 stroke，stroke=currentColor自动继承钮色）i:GLYPH— emoji / 字符（字面渲染）
无 tx 时为 icon-only：自动紧凑钮，l: 提供无障碍 aria-label + 悬停 tooltip。
图标名表：view edit delete add copy download upload refresh check close search setting warn info lock unlock more save export filter sort star link menu
clk:/sub:指向的处理器需通过TokUI.registerHandler(name, fn)预先注册，DSL 本身不含可执行代码。
标签 tag
标记与分类，自闭合。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 文本 | tx:新功能 |
t | 类型/颜色 | t:danger |
s | 尺寸 | s:sm |
round | 圆角 | round |
closable | 可关闭 | closable |
bordered | 描边 | bordered |
提示框 callout
带图标的信息提示。双模：自闭合 [callout t:info tx:文本] 与容器 [callout t:info]文本[/callout] 均可。
| 属性 | 含义 | 示例 |
|---|---|---|
t | 类型 | t:success |
tt | 标题 | tt:操作成功 |
tx | 正文（自闭合用） | tx:已保存 |
类型：info / success / warning / error / tip。
流式：长文本用容器模式
[callout t:info]...[/callout]，正文逐字流式（自闭合tx:在]处一次性出）。详见流式渲染优先级。
条形码 barcode
Code128 Set B 纯 SVG 条码（零依赖），适用运单号/订单号/序列号等字母数字变长数据。扫描器自动识别。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 编码数据（同时作条码下方可读文本） | tx:"SF1026883749" |
l / tt | 顶部标签 | l:"运单号" |
s | 尺寸 sm/md/lg（默认 md，兼容 small/medium/large） | s:medium |
支持可见 ASCII（32~126）。条码保持模块比例（
preserveAspectRatio meet），缩放不变形、可扫描。
二维码 qrcode
纯 SVG QR 码（矩阵生成 vendored 自 qrcode-generator Arase, MIT；本仓库零 npm 依赖）。支持 URL/文本/UTF-8 中文。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 编码数据（URL/文本，UTF-8） | tx:"https://tokui.jboltai.com" |
l / tt | 下方标签 | l:"扫码访问" |
s | 尺寸 sm/md/lg（默认 md） | s:md |
ec | 纠错级 L(7%)/M(15%)/Q(25%)/H(30%)，默认 M | ec:H |
含 4 模块静默区（quiet zone）+ 白底，
shape-rendering=crispEdges、preserveAspectRatio meet保持模块比例，缩放可扫描。纠错级越高越抗污损但模块越密。
状态点 dot
状态指示器，自闭合。
| 属性 | 含义 | 示例 |
|---|---|---|
t | 状态类型 | t:success |
tx | 文本 | tx:运行中 |
s | 尺寸 | s:lg |
pulse | 脉冲动画 | pulse |
徽标 badge / badge-box
badge 数字/小红点徽标（自闭合），包裹子元素。badge-box 容器，给子元素加角标。
| 属性 | 含义 | 适用 |
|---|---|---|
count | 数字（parseInt 截断小数，版本号/小数请用 tx） | 两者 |
dot | 小红点 | 两者 |
tx | 文本徽标 | 两者（badge-box 兼容旧写法 label，推荐 tx） |
t | 状态色（default/primary/success/warning/error） | 两者 |
overflow | 数字溢出显示（如 99+） | 两者 |
pill | 胶囊圆角 | badge |
size | 尺寸（sm/lg） | badge |
title | 悬停提示 | badge |
标题加徽标有两种写法（h3 是自闭合组件，禁止 [h3 文本 [badge]] 嵌套）：
- 并排 pill（标题旁标签，如版本号/状态）：用
row v:inline（flex 模式）托管h3+badge。必须v:inline——默认row是 12 列 grid，直接放标题会被挤窄换行。 - 右上角角标（贴角，如未读/红点）：用
badge-box包裹h3。
进度条 progress
自闭合。v 当前值（0-100）。
| 属性 | 含义 | 示例 |
|---|---|---|
v | 当前值 | v:60 |
l | 标签 | l:下载中 |
t | 形态 | t:circle |
stripe | 斑马纹 | stripe |
status | 状态色 | status:success |
形态：line（默认）/ circle（环形）/ span（内联）。
统计 stat
数据展示卡片，自闭合。
| 属性 | 含义 | 示例 |
|---|---|---|
tt | 标签 | tt:今日访问 |
v | 数值 | v:12345 |
pre / suf | 前缀 / 后缀 | suf:% |
trend | 趋势 | trend:up |
dec | 小数位 | dec:1 |
anim | 数字动画 | anim |
id | 元素 ID（供 upd 定向更新 v/trend） | id:kpi1 |
倒计时 countdown
自闭合。target 目标时间戳或 dur 倒计时秒数。
| 属性 | 含义 | 示例 |
|---|---|---|
target | 目标时间（ms 时间戳 / 日期） | target:2026-12-31 |
dur | 持续秒数 | dur:3600 |
fmt | 启用单位：d/h/m/s 各字母启用一单位（默认 dhms） | fmt:hh:mm:ss |
tx | 结束文案 | tx:已结束 |
l | 标签 | l:距结束 |
s | 尺寸 | s:lg |
clk | 计时结束回调 | clk:onEnd |
id | 元素 ID | id:cd1 |
加载 spin / 骨架 skeleton / 闪光 shimmer
spin 加载指示器、skeleton 骨架屏、shimmer 闪光占位，均自闭合。
| 属性 | 含义 | 适用 |
|---|---|---|
t | 类型 | 三者 |
s | 尺寸 | spin |
tx | 文本 | spin |
rows | 行数 | skeleton / shimmer |
空状态 empty / 结果页 result
empty 无数据占位、result 操作结果页，均自闭合。
| 属性 | 含义 | 适用 |
|---|---|---|
tx | 描述文本 | 两者 |
icon | 图标 | empty |
t | 类型 | result |
tt | 标题 | result |
result 类型：success / error / warning / info。
复制 copy
一键复制按钮，自闭合。id 指向要复制的目标元素 ID，或复制 tx 文本。
| 属性 | 含义 | 示例 |
|---|---|---|
id | 目标元素 ID | id:codeBlock |
tx | 按钮文本 | tx:复制 |
tt | 成功提示 | tt:已复制 |
Markdown md
Markdown 渲染容器。支持标题、列表、引用、代码、表格、链接等常用语法。
可选插件增强：
```mermaid围栏与$$公式$$/$公式$在宿主加载window.mermaid/window.katex全局对象时自动增强渲染；未加载插件时回退源码展示（零依赖不受损，$5 $6这类货币金额不会被误吃）。
可选插件增强：
```mermaid围栏与$$公式$$/$公式$在宿主加载window.mermaid/window.katex全局对象时自动增强渲染；未加载插件时回退源码展示（零依赖不受损，$5 $6这类货币金额不会被误吃）。
公式 katex / 图 mermaid
md 插件管线的独立组件别名，不走 md 文本直接声明：
[katex]O(n) = \sum_{i=1}^{n} t_i[/katex]— 容器，块级公式[katex f:"E = mc^2"]—f:属性，行内公式[mermaid]flowchart LR\n A --> B[/mermaid]— 容器，图源（raw 内容，内部[不解析）
宿主未加载 katex/mermaid 时分别回退为源码 / 代码块。katex 内容豁免 raw 转义解码，\nabla/\times/\to 等 LaTeX 命令按标准语法直接书写即可。
代码块 code
语法高亮代码块容器。lang 指定语言，零依赖内置 11 种语言着色：js / ts / python / java / go / rust / sql / html / css / json / bash。
| 属性 | 含义 | 示例 |
|---|---|---|
lang | 语言 | lang:js |
tx | 标题（文件名） | tx:app.js |
代码内容中的换行用
\n表示。完整属性表见 DSL 语法。