布局组件
卡片、栅格、列表、标签页、折叠、对话框、抽屉、时间轴、步骤条、轮播、树、菜单等容器型布局组件。容器组件需用 [/type] 闭合，左侧为格式化的 TokUI DSL，右侧为实时渲染，点「编辑」可即时改动。
卡片 card / 页脚 ft
card 通用内容容器，tt 出标题、tx 直接写正文（自闭合模式），主体内容由子节点填充。ft 作为 card 的子容器，自动落到卡片底部作页脚。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
tt | 标题 | card | tt:用户信息 |
tx | 自闭合正文 | card | tx:一段说明 |
hc | 标题色（预设或色值） | card | hc:primary |
ht | 标题装饰样式 | card | ht:underline |
w | 宽度 | card | w:320 |
v | 变体 | card | v:highlight |
v | 对齐 | ft | v:right |
card 变体：highlight（高亮边）、flat（扁平无阴影）、bordered（描边）、center / right（标题对齐）。 ht 标题装饰：fill（浅主色底填充）、accent（左侧色条）、underline（下划线）、dot（前缀圆点）、pill（浅底胶囊）。fill/pill 为「10% 主色浅底 + 主色文字」柔和配色，hc 自定义色同样自动浅化。 ft 变体：left / center / right。
栅格 row / col
基于 12 栅格系统的响应式布局。row 容器行，col 列，span 指定列宽（1-12）。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
v | 对齐方式 | row | v:center |
span | 列宽（1-12） | col | span:4 |
row 变体：left / center / right（水平对齐）、inline（行内排列）。
列表 list / item
列表容器，list 默认无序（ul），t:ol 切换有序列表（ol）。item 列表项（<li> 语义），文本写标签内，可嵌套子 list，plain 隐藏前缀。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
t | 列表类型 | list | t:ol |
plain | 去除序号/圆点 | list | plain |
tx | 项文本 | item | tx:第一项 |
标签页 tabs / tab
tabs 容器包裹多个 tab，tt 为每个标签页的导航标题，纯 CSS 切换。支持键盘左右箭头导航。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
tt | 标签页标题 | tab | tt:详情 |
切页回调：
tabs声明on:"change:h"后，用户切页上报{index, title}；程序化upd切换不触发。
手风琴 accordion / 折叠面板 collapse
accordion 容器包裹多个 collapse，每个 collapse 独立可折叠。tt 标题、open 默认展开。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
tt | 标题 | collapse | tt:第一章 |
open | 默认展开 | collapse | open |
id | 标识 | collapse | id:sec1 |
对话框 dialog
原生 <dialog> 元素实现，遮罩层 + 居中模态框，Esc / 点击遮罩 / 关闭按钮均可关闭。
| 属性 | 含义 | 示例 |
|---|---|---|
tt | 标题 | tt:确认操作 |
id | 标识（触发按钮 data-target 指向它） | id:myDialog |
clk | 关联处理器名 | clk:openDialog |
由按钮触发：触发按钮写
clk:openDialog data-target:"<dialog 的 id>"，对应[dialog id:...]必须带相同 id。点击按钮调用内置openDialog处理器按 id 找到 dialog 并showModal()弹出；弹窗内的取消/确认按钮写clk:closeDialog自动收起所在弹窗（无需手写 id）。
关闭回调：声明
on:"close:h"后，用户关闭路径（Esc / 遮罩 / ✕）都会上报，detail 为{}；程序化[upd id:x act:close]不上报（防回环）。
抽屉 drawer
侧边滑出的面板，pos 控制弹出方向，左右用 w 控宽、上下用 h 控高。Esc / 遮罩 / 关闭按钮均可关闭。
| 属性 | 含义 | 示例 |
|---|---|---|
tt | 标题 | tt:筛选条件 |
pos | 位置（left/right/top/bottom，默认 right） | pos:left |
w | 宽度（左右抽屉，默认 360px） | w:420 |
h | 高度（上下抽屉，默认 300px） | h:260 |
id | 标识（触发按钮 data-target 指向它） | id:myDrawer |
clk | 关联处理器名 | clk:openDrawer |
pos 变体：left / right / top / bottom。
由按钮触发：触发按钮写
clk:openDrawer data-target:"<drawer 的 id>"，对应[drawer id:...]必须带相同 id。点击按钮调用内置openDrawer处理器按 id 找到 drawer 并添加tokui-drawer--open类滑出；抽屉内取消/确认按钮写clk:closeDrawer自动收起。
关闭回调：声明
on:"close:h"后，用户关闭路径（Esc / 遮罩 / ✕）都会上报，detail 为{}；程序化[upd id:x act:close]不上报（防回环）。
时间轴 timeline / ti
timeline 容器，ti 单条记录。tm 时间戳、tt 标题、t 状态色（primary/success/warning/error/info），正文写标签内。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
v | 布局（h/alternate/card） | timeline | v:alternate |
tm | 时间戳 | ti | tm:2026-06-01 |
tt | 标题 | ti | tt:提交申请 |
t | 状态色 | ti | t:success |
timeline 变体：h / horizontal（水平）、alternate / alt（交替左右）、card（卡片样式）。
步骤条 steps / step
横向流程指示，v 指定当前步序（1-based），vd:vertical 切换竖向，s:sm 缩小尺寸。step 子项的 status:error 标记错误态。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
v | 当前步骤（1-based） | steps | v:2 |
vd | 方向（horizontal/vertical） | steps | vd:vertical |
s | 尺寸 | steps | s:sm |
tt | 步骤标题 | step | tt:填写信息 |
status | 单步状态 | step | status:error |
可点击步骤：
steps声明on:"change:h"后步骤变为可点击，点击上报{index, title}。
轮播 carousel / carousel-item
carousel 容器，子项为 carousel-item（或直接 img）。carousel 的子项也可写 [item]——在 carousel 内自动按幻灯片渲染（与 list/desc 内的 [item] 同名不同义，按父级区分；item 与 carousel-item 等价，可混用）。auto 设置自动播放间隔（毫秒），支持左右箭头、指示点、拖动、键盘左右键切换。thumb 改用下方缩略图图例（替代指示点，点击丝滑跳转）。尺寸：w 宽、h 高（纯数字按 px，亦支持 %/vw/rem），或 ratio 宽高比（如 16:9 / 4:3 / 1）；设了 h 或 ratio 时幻灯片撑满高度、图片 object-fit:cover 裁切，h 优先于 ratio。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
auto | 自动播放间隔（ms） | carousel | auto:3000 |
id | 标识 | carousel | id:myCarousel |
thumb | 显示缩略图图例（替代指示点） | carousel | thumb |
w | 宽度（纯数字→px，或 %/vw/rem） | carousel | w:480 / w:100% |
h | 高度（px，优先于 ratio） | carousel | h:240 |
ratio | 宽高比（16:9 / 4:3 / 1） | carousel | ratio:16:9 |
s | 图片地址 | carousel-item / item | s:https://... |
tt | 幻灯片标题 | carousel-item / item | tt:第一张 |
tx | 幻灯片描述 | carousel-item / item | tx:说明文字 |
切换上报：声明
on:"change:h"后，手动切换（箭头 / 指示点 / 拖动 / 键盘）上报{index}；autoplay 自动播放不触发。
固定尺寸（h）/ 比例尺寸（ratio）/ 缩略图图例（thumb）：
树 tree / tn
tree 容器，子节点 tn 可递归嵌套。tn 的 leaf 标记叶节点、open 默认展开、chk 选中、dis 禁用。tree 的 chk 开启复选框模式。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
l | 字段标签 | tree | l:目录 |
clk | 选中回调 | tree | clk:onPick |
chk | 复选框模式 | tree | chk |
dis | 整树禁用 | tree | dis |
v / tx | 值 / 显示文本 | tn | tx:src |
leaf | 叶节点 | tn | leaf |
open | 默认展开 | tn | open |
chk / dis | 选中 / 禁用 | tn | chk |
load | 懒加载数据 handler | tn | load:loadChildren |
选中与复选上报：声明
on:"change:h"后选中节点上报{value, id}；复选框模式（chk）下声明on:"check:h"，复选变化上报{value: 选中值数组}。
懒加载（load）：
tn声明load:数据handler名后，首次展开该节点调用fn({id, value})（返回子节点对象数组或 Promise），展开时显示 loading 态；已加载的节点不重复请求，返回的子节点可继续带load递归懒加载。加载完成上报load事件{value, count}。
菜单 menu / menu-item
menu 容器，menu-item 自闭合。v 切换方向（vertical 默认 / horizontal 横向 / inline 内联），act 默认激活项的 clk 值，bg/fc 自定义配色。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
v | 方向变体 | menu | v:horizontal |
act | 默认激活项 clk | menu | act:goHome |
bg / fc | 背景 / 文字色 | menu | bg:1f2937 |
tx | 文字 | menu-item | tx:首页 |
clk | 点击处理器 | menu-item | clk:goHome |
i | 图标字符 | menu-item | i:🏠 |
dis | 禁用 | menu-item | dis |
激活回调与程序化激活：
menu声明on:"change:h"后，激活项变化上报{value}（项标识取 id > v > 文本）；服务端可用[upd id:m act:activate v:标识]程序化激活菜单项。
可调面板 resizable
双面板可拖拽分隔条，dir 控制方向，min/max/default 限制第一面板尺寸。第一个子节点进第一面板，其余进第二面板。支持键盘箭头微调。
| 属性 | 含义 | 示例 |
|---|---|---|
dir | 方向（h 横向默认 / v 纵向） | dir:v |
min | 最小尺寸（px） | min:120 |
max | 最大尺寸（px） | max:600 |
default | 初始尺寸（px） | default:240 |
w | 整体宽度 | w:100% |
横向 · 侧边导航 + 主内容 — 最常见的 IDE / 后台布局：左栏定宽可拖宽，右栏吃满剩余空间。
纵向 · 编辑器 + 终端 — dir:v 上下分割：上方代码 / 预览，下方日志 / 控制台。
嵌套 · 三栏工作台 — resizable 可嵌套：外层横向分左右，右栏内再纵向分上下，构成三区域。
紧约束 · 浮动徽标条 — min 接近 max 时第一面板尺寸几乎固定，仅留微调余量。
滚动区域 scroll-area
固定外层尺寸 + 自定义滚动条样式的内容区。h/w 控制视口大小，超长内容即可滚动。
| 属性 | 含义 | 示例 |
|---|---|---|
h | 高度 | h:160 |
w | 宽度 | w:100% |
id | 标识 | id:myScroll |
virtual | 虚拟滚动（均匀行高模式） | virtual |
ih | 行高（px，默认 36） | ih:40 |
虚拟滚动与触底加载：
virtual仅把可视窗口 + buffer 的行挂入 DOM（均匀行高模式，不等高行不适用）；滚动到 80% 阈值触底时上报loadmore事件（on:"loadmore:h"，detail{}）——长列表 / 对话历史加载更多用。
侧边栏 sidebar
sidebar 容器，子节点为 sidebar-content（主内容区）和 sidebar-footer（页脚区）。collapsible 开启折叠按钮。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
w | 宽度（默认 260） | sidebar | w:240 |
pos | 位置（left/right） | sidebar | pos:left |
collapsible | 可折叠 | sidebar | collapsible |
tt | 标题 / Logo 文本 | sidebar | tt:控制台 |
bg / fc | 背景 / 文字色 | sidebar | bg:111827 |
文字提示 tooltip
悬浮显示的轻量文字提示，tt 为提示内容、tx 为触发文本、pos 控制方向。鼠标移入即弹出，移出/失焦/Esc 收起。
| 属性 | 含义 | 示例 |
|---|---|---|
tt | 提示文本 | tt:这是提示 |
tx | 触发文本 | tx:悬停看我 |
pos | 方向（默认 top） | pos:bottom |
变体：top / bottom / left / right。
气泡卡片 popover
比 tooltip 更丰富的弹出卡片，可放标题与任意子节点内容。trig 切换触发方式（click 默认 / hover），pos 控制方向，w 控制面板宽。
| 属性 | 含义 | 示例 |
|---|---|---|
tx | 触发文本 | tx:点击查看 |
tt | 标题 | tt:用户信息 |
pos | 方向（默认 top） | pos:bottom |
trig | 触发方式 | trig:hover |
w | 面板宽度 | w:240 |
悬停卡片 hover-card
hover-card 容器，子节点为 hover-trigger（触发区）与 hover-content（弹出内容）。delay 控制显示延迟，pos 控制方向，内容用 position:fixed 定位避免裁切。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
pos | 方向（默认 bottom） | hover-card | pos:right |
w | 弹层宽度（px） | hover-card | w:280 |
delay | 显示延迟（ms，默认 300） | hover-card | delay:200 |
确认气泡 popconfirm
点击触发后弹出小型确认框，含确定 / 取消按钮。tt 询问文案、tx 触发按钮文字、clk 确定回调、t 确定按钮类型、pos 方向。
| 属性 | 含义 | 示例 |
|---|---|---|
tt | 询问文案 | tt:确定删除吗？ |
tx | 触发按钮文字 | tx:删除 |
clk | 确定回调 | clk:onConfirm |
t | 确定按钮类型（默认 primary） | t:danger |
pos | 方向（默认 top） | pos:right |
ok-text / cancel-text | 按钮文字 | ok-text:删除 |
回到顶部 backtop
页面或容器滚动超过阈值后浮现的回到顶部按钮。t 设置阈值（默认 200），container 切换为容器内模式，v 控形状。
| 属性 | 含义 | 示例 |
|---|---|---|
t | 出现阈值（px，默认 200） | t:300 |
v | 形状（circle / round / square） | v:round |
tx | 按钮文字（默认 ↑） | tx:顶部 |
s | 尺寸 | s:lg |
container | 容器内模式 | container |
bottom / right | 距底 / 距右（px） | bottom:40 |
backtop浮于右下角，滚动后才可见；下例用 callout 说明其行为。
命令面板 command
command 容器，子节点为 command-group（分组，tt 标题），其下命令项用 item（或 command-item，两者等价；推荐 item）。内置模糊搜索、键盘上下选择、回车确认。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
ph | 搜索框占位 | command | ph:搜索命令... |
clk | 选中回调 | command | clk:onCommand |
id | 标识（触发按钮 data-target 指向它） | command | id:cmdMain |
hotkey | 启用 Cmd/Ctrl+K 全局快捷键（页面只应一个实例） | command | hotkey |
tt | 分组标题 | command-group | tt:常用 |
tx | 显示文本 | item / command-item | tx:新建文件 |
v | 搜索值（默认同 tx） | item / command-item | v:new file |
clk | 项回调 | item / command-item | clk:cmdNew |
shortcut | 快捷键提示 | item / command-item | shortcut:⌘N |
命令面板默认隐藏，由按钮触发：触发按钮写
clk:openCommand data-target:"<command 的 id>"，对应[command id:...]带相同 id。需要Cmd/Ctrl+K时显式写hotkey（页面只应有一个 hotkey 实例）。 选中命令项时：项级clk的 handler 第一参为{ value, text }；若command根也设了clk，会再触发一次根级回调，第一参为{ value, text, clk }（clk为该项的项级回调名）。点击面板空白 / 搜索框不触发任何回调。
画布面板 canvas
canvas 容器，子节点为 canvas-content（内容区）。pos 控制停靠方向、w 控宽、open 默认展开、closable 是否可关闭。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
tt | 标题（默认 Canvas） | canvas | tt:预览 |
pos | 位置（left/right，默认 right） | canvas | pos:right |
w | 宽度（默认 400） | canvas | w:360 |
open | 默认展开 | canvas | open |
closable | 是否可关闭（默认开） | canvas | closable |
tx | 自闭合正文 | canvas | tx:简单内容 |
锚点导航 anchor
双模式。长文档内的章节跳转导航：点击平滑滚动到目标章节，滚动时 scroll-spy 自动高亮最近过顶的一项。目标元素需带 id（如 [h2 id:sec-a 第一章]）。
| 属性 | 含义 | 示例 |
|---|---|---|
opt | 锚点简写串 目标id:标题;...（必须双引号，原子自闭合） | opt:"sec-a:第一章;sec-b:第二章" |
top | scroll-spy 激活偏移（px，缺省 12） | top:20 |
v | 变体：horizontal 横向模式 | v:horizontal |
on | change 上报 {value}（目标 id） | on:"change:h" |
id | 元素 ID | id:pageAnchor |
容器模式 lk 子项（支持二级锚点）：
| 属性 | 含义 | 示例 |
|---|---|---|
h | 目标元素 id（可带 #） | h:sec-a |
tx | 显示文本 | tx:第一章 |
d | 层级深度 1-3（缩进） | d:1 |
点击激活后平滑滚动途中 spy 不会抢回高亮（900ms 抑制窗）；
upd v:目标id程序化高亮（silent）。
点击调用
scrollIntoView平滑滚动。服务端可用[upd id:pageAnchor v:目标id]程序化高亮（silent，不上报）。
固钉 affix
容器。滚动越过偏移时将内容以 position:fixed 固定（固顶或固底），并自动插入占位元素防止布局跳动；固定状态切换经 change 事件上报。
| 属性 | 含义 | 示例 |
|---|---|---|
top | 固顶：距滚动容器顶部偏移（px），缺省 top:0 | top:8 |
bottom | 固底：距滚动容器底部偏移（px，与 top 二选一） | bottom:8 |
target | 显式滚动容器选择器（缺省自动探测最近可滚动祖先） | target:#list |
on | 固定状态切换上报 {fixed:true/false} | on:"change:h" |
固底语义：元素位于底线之下时先固定于底部，滚动经过其原始位置后释放（同 AntD
offsetBottom）。滚动监听挂 window 捕获阶段，嵌套滚动容器（对话区/scroll-area）均可感知。
瀑布流 masonry
容器。CSS columns 瀑布流：cols 固定列数或 minw 自动列（子项最小宽度，列数随容器宽度自适应），gap 间距。子项自动分列平衡，流式追加自然流动；零 JS 布局计算，子项 break-inside: avoid 不被截断。
| 属性 | 含义 | 示例 |
|---|---|---|
cols | 固定列数（1-6，缺省 2） | cols:3 |
minw | 自动列模式：子项最小宽度（px，优先于 cols） | minw:200 |
gap | 间距（px，缺省 8） | gap:10 |
漫游引导 tour / tour-step
tour 容器包裹若干 tour-step（自闭合标记），分步高亮讲解页面元素。键盘：Esc 关闭、←/→ 切步。无 tgt 的步骤面板居中显示。
| 属性 | 含义 | 适用 | 示例 |
|---|---|---|---|
open | 容器闭合后自动开启 | tour | open |
mask | 遮罩（默认开，mask:false 关） | tour | mask:false |
id | 标识（供 upd 定向控制） | tour | id:tour1 |
on | 事件上报（见下） | tour | on:"change:h,finish:h,close:h" |
tgt | 目标元素 id（可带 #） | tour-step | tgt:"#btn-a" |
tt | 步骤标题 | tour-step | tt:第一步 |
tx | 步骤说明（或直接写正文） | tour-step | tx:说明文字 |
pos | 面板方位（top/bottom/left/right，默认 bottom） | tour-step | pos:bottom |
事件：
change（切步，detail{index,target}）/finish（完成）/close（跳过·✕·Esc）。 程序化控制：[upd id:tour1 act:open]（v可选起始步）、[upd id:tour1 act:goto v:N]、[upd id:tour1 act:close]，均 silent 不上报。
命令式确认 modal.confirm
命令式确认对话框——宿主侧 JS API，不经 DSL，由页面代码直接调用。返回 Promise<boolean>：确认得 true，取消 / Esc / 点击遮罩得 false。别名 TokUI.confirm(opts) 等价。
const ok = await TokUI.modal.confirm({
tt: '删除确认',
tx: '确定要删除这条记录吗？',
t: 'danger', // 确认按钮类型：'danger' | 'primary'（默认）
'ok-text': '删除', // 缺省走 i18n common.ok
'cancel-text': '取消', // 缺省走 i18n common.cancel
onOk() { /* 与 Promise 并存的回调 */ },
onCancel() {}
});| 选项 | 含义 | 默认 |
|---|---|---|
tt | 标题 | i18n modal.aria |
tx | 正文 | 无（缺省不渲染正文区） |
t | 确认按钮类型 | primary |
ok-text / cancel-text | 按钮文案 | i18n common.ok / common.cancel |
onOk / onCancel | 回调（与 Promise 并存） | — |
遮罩 aria 文案同样走 i18n（
modal.aria），多语言站点无需手工处理。
容器型组件层级较深时，建议在每个容器后立即写好闭合标签
[/type]，避免流式解析下因隐式闭合时机错位导致渲染异常。