表单组件
表单容器、各类输入控件与选择器。每个示例左侧为格式化 + 高亮的 TokUI DSL，右侧为实时渲染，点「编辑」可即时改动。
表单容器 form
包裹一组表单控件，提交时触发 sub: 处理器或 act 原生提交。
| 属性 | 含义 | 示例 |
|---|---|---|
id | 表单标识，供按钮 form:ID 显式绑定 | id:loginForm |
act | 提交地址 | act:/api/save |
mtd | 提交方法 | mtd:post |
sub | 提交处理器名 | sub:onSubmit |
clk | 通用事件处理器名 | clk:onFormClick |
sub:指向的处理器需通过TokUI.registerHandler(name, fn)预先注册；btn上用sub:xxx触发表单提交。 表单外的按钮可用form:ID显式绑定目标表单（见下节表单动作），不再依赖 DOM 层级。
表单动作：提交 / 重置 / 数据收集
btn 内置三类动作，由 renderer 自动解析，无需 registerHandler（仅 sub 的业务处理仍需注册）。优先级 print > reset > submit > clk。
| DSL | 动作 | 说明 |
|---|---|---|
[btn form:F sub:H] | 提交 | 收集表单 F 的全部字段（含 slider/rate/picker 等自定义控件的 hidden 值），调用 handler H |
[btn form:F reset] | 重置 | 一键复原表单 F：原生输入走 form.reset()，自定义控件走内置 _tokuiReset；可选 reset:H 在复位后回调 |
[btn form:F clk:H] | 普通点击 | 不收集数据，走 event-bus（form: 可省略，仅用于让 handler 拿到 data） |
form:ID 显式绑定（关键能力）：按钮放在表单外部时，靠 form:ID 精确指明收集哪个表单，跨层级、多表单互不干扰。解析用 getElementById 且校验目标为 <form>，防 id 伪造。
[form id:formA sub:onA] ... [/form]
[form id:formB sub:onB] ... [/form]
[btn tx:"提交 A" form:formA sub:onA t:primary] ← 只收集 formA
[btn tx:"提交 B" form:formB sub:onB t:primary] ← 只收集 formB重置覆盖范围：input/pwd/select/textarea/checkbox 等原生控件 + slider/rate/numinput/switch/transfer/picker/cascader 等自定义控件均实现复位契约（data-tokui-resettable + _tokuiReset），renderer 遍历调用并向 form 广播 tokuireset 事件供外部监听。
打印区 print-area
标记一块 1:1 打印区域，配合 [btn print:ID] 触发浏览器打印。打印时仅该区域可见、如实还原配色与布局；打印按钮自身不进预览。
| 属性 | 含义 | 示例 |
|---|---|---|
id | 打印区标识，供 print:ID 引用 | id:invoice |
tt | 可选标题（打印文档标题） | tt:收款单 |
触发打印（btn 的 print 动作，内置、无需 handler）：
| DSL | 行为 |
|---|---|
[btn print:invoice] | 打印 #invoice 打印区 |
[btn print:self] | 打印按钮所在的最近 print-area / card |
[btn print] | 裸写，等价 print:self |
打印机制：renderer 给目标加
.tokui-print-target+body[data-tokui-printing]，@media print用 visibility 仅令该作用域可见（1:1）。响应式断点已限定screen，打印不触发堆叠。@page页边 + 打印区内边距构成文档边界；暗色主题下强制白底省墨。
输入框 input
单行文本输入，自闭合。l 标签、ph 占位、t 原生 type、val 初值。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:姓名 |
ph | 占位提示 | ph:"请输入姓名" |
t | 原生 input type | t:email |
n | 字段名 | n:username |
val | 默认值 | val:Tom |
id | 元素 ID | id:username |
w | 宽度 | w:240 |
hint | 提示文字 | hint:6~16 个字符 |
search | 搜索样式 | search |
req / dis / ro | 必填 / 禁用 / 只读 | req |
变体：error / success（校验状态），sm / lg（尺寸），underline（下划线风格），pill（圆角）。
密码框 pwd
带显隐切换的密码输入，自闭合。属性同 input，额外 toggle 控制是否允许切换明文。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:密码 |
ph | 占位提示 | ph:"至少 6 位" |
toggle | 显隐切换按钮 | toggle |
req / dis | 必填 / 禁用 | req |
v | 变体（同 input） | v:error |
多行文本 textarea
多行文本输入容器。rows 初始行数、maxlen 最大字数、auto 高度自适应。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:描述 |
ph | 占位提示 | ph:"请输入描述" |
rows | 初始行数 | rows:4 |
maxrows | 最大行数（auto 模式） | maxrows:8 |
maxlen | 最大字数 | maxlen:200 |
auto | 高度自适应 | auto |
tx | 默认内容 | tx:"默认文本" |
req / dis / ro | 必填 / 禁用 / 只读 | req |
下拉选择 select / opt
select 容器，子节点 opt 选项。multi 多选、req 必填。
| 属性 | 含义 | 适用 |
|---|---|---|
l | 标签 | select |
ph | 占位提示 | select |
multi | 多选 | select |
n | 字段名 | select |
req | 必填 | select |
v | 变体 | select |
tx | 选项文本 | opt |
v | 选项值 | opt |
chk | 默认选中 | opt |
select 变体：error / success。
单选组 radio
radio 容器，子节点 opt 选项；同组互斥。
| 属性 | 含义 | 适用 |
|---|---|---|
l | 组标签 | radio |
n | 字段名 | radio |
v | 变体 | radio |
tx | 选项文本 | opt |
v | 选项值 | opt |
chk | 默认选中 | opt |
复选框 checkbox
自闭合。l 标签、chk 默认勾选。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:同意条款 |
chk | 默认勾选 | chk |
n | 字段名 | n:agree |
v | 选项值 | v:1 |
id | 元素 ID | id:agree |
dis | 禁用 | dis |
开关 switch
自闭合。chk 开启、clk 切换回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:邮件通知 |
chk | 默认开启 | chk |
dis | 禁用 | dis |
clk | 切换处理器名 | clk:onToggle |
n | 字段名 | n:notify |
v | 值 | v:1 |
id | 元素 ID | id:notify |
变体：sm / lg。
滑块 slider
自闭合。min/max/step 区间与步进、v 当前值。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:音量 |
min | 最小值 | min:0 |
max | 最大值 | max:100 |
step | 步进 | step:5 |
v | 当前值 | v:60 |
dis | 禁用 | dis |
clk | 拖动回调 | clk:onSlide |
n | 字段名 | n:volume |
id | 元素 ID | id:volume |
变体：sm / lg。
评分 rate
自闭合。max 星级上限、v 当前分、clk 选择回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:评分 |
v | 当前值 | v:4 |
max | 最大星级 | max:5 |
clk | 选择回调 | clk:onRate |
dis | 只读/禁用 | dis |
tx | 文案 | tx:很好 |
数字输入 numinput
自闭合。带加减按钮的数字输入，min/max/step 约束范围。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:数量 |
v | 当前值 | v:1 |
min | 最小值 | min:1 |
max | 最大值 | max:99 |
step | 步进 | step:1 |
dis | 禁用 | dis |
n | 字段名 | n:qty |
id | 元素 ID | id:qty |
按钮组 btngroup
容器，包裹一组 btn。表单场景里常用于多按钮操作区（主要按钮用法见基础组件）。
| 属性 | 含义 | 示例 |
|---|---|---|
id | 组 ID | id:actions |
v | 变体 | v:vertical |
变体：vertical（垂直排列）、pill（圆角组）。
选择器 picker
容器，比 select 更丰富的选择面板（含搜索/多列）。multi 多选、dis 禁用。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:城市 |
ph | 占位提示 | ph:"请选择" |
multi | 多选 | multi |
dis | 禁用 | dis |
n | 字段名 | n:city |
v | 值 | v:bj |
id | 元素 ID | id:city |
变体：error / success。
级联选择 cascader
容器，逐级展开的多级选择（如省市区）。clk 选择回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:地区 |
ph | 占位提示 | ph:"请选择" |
dis | 禁用 | dis |
clk | 选择回调 | clk:onPick |
v | 值 | v:"北京-朝阳" |
n | 字段名 | n:region |
id | 元素 ID | id:region |
变体：error / success。
文件上传 upload
自闭合。accept 限制类型、multi 多选、max 最大数量。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:附件 |
ph | 占位提示 | ph:"点击或拖拽上传" |
accept | 允许类型 | accept:"image/*" |
multi | 多文件 | multi |
max | 最大数量 | max:5 |
dis | 禁用 | dis |
clk | 上传回调 | clk:onUpload |
n | 字段名 | n:file |
id | 元素 ID | id:file |
变体：sm / lg。
日期选择 datepicker
自闭合。fmt 日期格式、v 默认值、clk 选择回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:出生日期 |
ph | 占位提示 | ph:"请选择日期" |
fmt | 日期格式 | fmt:yyyy-MM-dd |
v | 默认值 | v:2026-06-20 |
clk | 选择回调 | clk:onDate |
dis | 禁用 | dis |
n | 字段名 | n:birthday |
id | 元素 ID | id:birthday |
时间选择 timepicker
自闭合。fmt 时间格式、v 默认值。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:开始时间 |
ph | 占位提示 | ph:"请选择时间" |
fmt | 时间格式 | fmt:HH:mm |
v | 默认值 | v:09:30 |
clk | 选择回调 | clk:onTime |
dis | 禁用 | dis |
n | 字段名 | n:time |
id | 元素 ID | id:time |
日期时间 datetimepicker
自闭合。日期 + 时间合一选择，fmt 自定义格式。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:预约时间 |
ph | 占位提示 | ph:"请选择日期时间" |
fmt | 格式 | fmt:"yyyy-MM-dd HH:mm" |
v | 默认值 | v:"2026-06-20 09:30" |
clk | 选择回调 | clk:onDateTime |
dis | 禁用 | dis |
n | 字段名 | n:dt |
id | 元素 ID | id:dt |
穿梭框 transfer
容器，左右两栏互斥的多选移动。tt/tt2 两侧标题、clk 移动回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:分配角色 |
tt | 左侧标题 | tt:未选 |
tt2 | 右侧标题 | tt2:已选 |
clk | 移动回调 | clk:onTransfer |
h | 固定高度（内容滚动） | h:240 / h:40vh |
mh | 最大高度（覆盖默认 320px） | mh:200 |
dis | 禁用 | dis |
n | 字段名 | n:roles |
id | 元素 ID | id:roles |
变体：sm（max 260px）/ lg（max 400px）。默认最大高度 320px，列表超出时内部滚动（滚动条默认透明，hover 显灰色半透明）。
opt 子项填数据：带 chk 的初始在右侧（已分配），其余在左侧（待分配）。勾选后点 → / ← 穿梭。
h 固定高度、mh 最大高度示例：
标签输入 input-tag
回车添加标签、点击标签 × 移除。tags 初始标签、max 最大数量。带 tags 时可自闭合；无 tags 需 [/input-tag] 闭合。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:标签 |
ph | 占位提示 | ph:"输入后回车添加" |
n | 字段名 | n:tags |
max | 最大数量 | max:8 |
tags | 初始标签（逗号分隔） | tags:"JS,Python" |
dis | 禁用 | dis |
完整 DSL 语法（属性简写、变体白名单、流式渲染约束等）见 DSL 语法。