表单组件
表单容器、各类输入控件与选择器。每个示例左侧为格式化 + 高亮的 TokUI DSL，右侧为实时渲染，点「编辑」可即时改动。所有表单控件的 label 在带 req 时都渲染必填星号。
表单容器 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 事件供外部监听。
值变更上报（change 事件）
表单控件用 on:"change:处理器"（必须双引号）把用户的值变更实时上报给已注册的 handler，构成「用户 → AI」交互回路：
[input n:city l:城市 on:"change:onCityChange"]
[switch l:邮件通知 n:notify on:"change:onNotifyChange"]- 输入防抖：
input/pwd/textarea/numinput停止输入 300ms 后上报，db:可覆盖毫秒数（如db:500）。 - 值变即报：
select/radio/checkbox/switch/slider/rate/picker/transfer/cascader/datepicker系列 /input-tag值一变立即上报。 - upload：选择 / 移除文件时上报
change，detail 为{value: 文件名数组, name}。 - detail 形状：handler 签名
(detail, event, element)，detail为{value, name}。 - 统一出口：所有交互同时发到
new TokUI({ onEvent })的onEvent('component', { type, id, event, detail })——不声明on:也能在宿主侧全量监听。
完整事件清单见 DSL 语法 · 交互事件上报。
DSL 校验规则
input / pwd / textarea / select 支持 rule: + msg: 声明式校验规则，提交时统一执行（sub / t:submit 全部路径），失败拦截提交、错误字段标红 + hint 出文案并聚焦首个错误字段：
[input n:email l:"邮箱" rule:"required|email"]
[input n:code l:"验证码" rule:"required|len:6" msg:"请输入 6 位验证码"]
[select n:city l:"城市" rule:"required" opt:"bj:北京;sh:上海"]- 规则管道分隔、按序短路：
requiredemailurlnumberlen:N（精确长度）min:Nmax:N（字符数）re:正则。 - 空值跳过非
required规则（HTML5 同语义：空且非必填 = 合法）。 msg:自定义错误文案（缺省用内置 i18n 文案）；未知规则名 / 非法正则console.warn跳过。- 与
live组合：blur 实时校验，error 态下输入即时重检。 select的req会写原生required属性（多选除外，语义不符）。
打印区 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 |
ml | 最大字符数（maxlength） | ml:20 |
min / max / step | 数字边界 / 步长（t:number） | min:0 max:99 |
w | 宽度 | w:240 |
hint | 提示文字 | hint:6~16 个字符 |
search | 搜索样式（search right 图标加右侧） | search |
pre / app | 前置 / 后置文本（可带变体 文本|变体） | pre:¥ |
prebtn / appbtn | 前置 / 后置按钮（文本:处理器|变体） | prebtn:"搜索:doSearch|primary" |
rule / msg | DSL 校验规则 / 自定义错误文案（见 DSL 校验规则） | `rule:"required |
sug | 输入联想数据源 handler | sug:onSuggest |
req / dis / ro | 必填 / 禁用 / 只读 | req |
变体：error / success（校验状态），sm / lg（尺寸），underline（下划线风格），pill（圆角），inline（标签与控件同行）。
输入联想（sug）：
sug:数据源handler名启用联想下拉——fn({value})返回数组或 Promise（项为字符串或{v, tx}），↑↓ / Enter / Esc 导航，选定触发change上报。
密码框 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 选项；同组同 n 互斥。两种写法：容器（[opt] 子项）或 opt:"..." 简写（自闭合，无需 [/radio]）。
| 属性 | 含义 | 适用 |
|---|---|---|
l | 组标签 | radio |
n | 字段名（同组共享，提交键） | radio |
id | 组 ID | radio |
v | inline（标签与控件同行）/ vertical（选项竖排左对齐） | radio |
opt | 简写选项串 opt:"v:文;v:文"（自闭合写法，与 [opt] 子项二选一） | radio |
tx | 选项文本 | opt |
v | 选项值 | opt |
chk | 默认选中 | opt |
复选框 checkbox
三态（按是否带 opt / multi 自动判定）：
| 形态 | 判定 | 写法 | 提交值 |
|---|---|---|---|
| 单布尔 | 无 opt 无 multi（自闭合） | [checkbox l:同意协议 n:agree chk] | 布尔（勾选=agree 出现） |
| 简写多选 | 有 opt（自闭合） | [checkbox n:tag l:标签 opt:"1:A;2:B;3:C"] | data.tag = 数组 |
| 容器多选 | 有 multi（容器） | [checkbox n:tag l:标签 multi][opt v:1 tx:A chk][/checkbox] | data.tag = 数组 |
| 属性 | 含义 | 适用 |
|---|---|---|
l | 标签 | checkbox |
n | 字段名（多选提交键） | checkbox |
opt | 简写选项串（自闭合多选） | checkbox |
multi | 标记容器多选模式（需 [/checkbox]） | checkbox |
v | inline/vertical | checkbox |
chk | 默认勾选 / 选中 | checkbox / opt |
dis | 禁用 | checkbox |
多选提交走原生 FormData，同 n 多值自动聚合为数组（如勾选 A、C → data.tag = ["1","3"]）。单布尔 / 简写多选是自闭合，不写 [/checkbox]；只有 multi 容器多选需要 [/checkbox]。
取值按钮位置（写错就拿不到数据）：放 form 内
[form id:F sub:H]...[btn tx:提交 clk:H][/form]（clk 自动收集所在 form）；或放 form 外但必须加form:表单ID显式绑定[btn tx:提交 form:F clk:H]。按钮在 form 外、又不写form:ID→ handler 收到null。
开关 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 |
range | 双滑块区间模式 | range |
marks | 刻度标签（值:标签 逗号分隔） | marks:"0:免费,50:标准" |
变体：sm / lg。
区间与刻度：
range双滑块选区间（v:"20,60"），change上报{value: [min, max]}；marks:"0:免费,50:标准,100:旗舰"渲染刻度标签。
评分 rate
自闭合。max 星级上限、v 当前分、clk 选择回调。
| 属性 | 含义 | 示例 |
|---|---|---|
l | 标签 | l:评分 |
v | 当前值 | v:4 |
max | 最大星级 | max:5 |
clk | 选择回调 | clk:onRate |
dis | 只读/禁用 | dis |
tx | 文案 | tx:很好 |
half | 半选（0.5 步进，同值再点清零） | half |
数字输入 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 |
u | 上传地址（仅 http(s) / 相对路径，启用自动传输） | u:/api/upload |
mtd | 上传方法 | mtd:post |
变体：sm / lg。
传输层：带 u: 时选择文件后自动经 XHR 逐个上传，文件项呈现进度条 / 成功 ✓ / 失败 ✗+重试三态，并上报 progress {file, percent} / success {file, response} / error {file, error} 事件；不带 u: 仅前端选择（仅 change 事件）。
服务端可推
[upd id:file act:clear]清空已选文件列表。
日期选择 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 |
range | 范围模式（两次点击选起止） | range |
范围模式：
range下两次点击选定起止日期，值格式YYYY-MM-DD ~ YYYY-MM-DD。
时间选择 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 |
分段控制器 segmented
一组互斥选项的轻量切换（tabs 的表单控件版）。两种写法：opt 简写（原子自闭合）或容器模式 opt 子节点（支持图标、单项禁用）。
| 属性 | 含义 | 示例 |
|---|---|---|
opt | 选项简写串 v:label;...（必须双引号） | opt:"list:列表;grid:宫格" |
v | 当前选中值（可与形态变体组合） | v:"sm,grid" |
n | 字段名 | n:view |
l | 标签 | l:视图 |
dis | 整组禁用 | dis |
on | change 上报 {value,name} | on:"change:h" |
id | 元素 ID | id:view |
变体：sm / lg / block（撑满）/ pill（胶囊）/ vertical（垂直）。
容器模式 opt 子节点（逐项精细控制）：
| 属性 | 含义 | 示例 |
|---|---|---|
v | 选项值 | v:grid |
tx | 显示文本 | tx:宫格 |
i | 图标字符（emoji/符号） | i:📊 |
chk | 默认选中（v 命中优先） | chk |
dis | 单项禁用 | dis |
服务端可用
[upd id:view v:grid]程序化切换；form reset 恢复初始值。
颜色选择 color-picker
自闭合。取色面板含饱和明度取色区 + hue 滑条 + hex 输入 + 预设色 + 清除，presets 配置预设色。面板开启时 portal 到 body 并 fixed 定位，不被父容器 overflow 裁切；滚动时跟随重定位，外点/Esc 关闭。
| 属性 | 含义 | 示例 |
|---|---|---|
v | 初始色（#rrggbb，缺省 #1677ff） | v:#1677ff |
presets | 预设色（逗号分隔 hex） | presets:"#f5222d,#fa8c16" |
n | 字段名 | n:color |
l | 标签 | l:主题色 |
dis | 禁用 | dis |
on | change 上报 {value,name} | on:"change:h" |
id | 元素 ID | id:color |
服务端可用
[upd id:color v:#hex]程序化改色、[upd id:color dis:false]解除禁用；form reset 恢复初始值。
行内编辑 editable
自闭合行内元素。文本带虚线下划线标识可编辑，点击进入编辑态：Enter/失焦提交，Esc 还原（不上报）。
| 属性 | 含义 | 示例 |
|---|---|---|
tx / v | 初始文本 | tx:小木屋 |
ph | 空值占位 | ph:点击填写 |
n | 字段名 | n:nick |
dis | 禁用 | dis |
on | 提交（值变化）上报 {value,name} | on:"change:h" |
id | 元素 ID | id:ed1 |
服务端可用
[upd id:ed1 tx:新值]程序化改值（silent）、[upd id:ed1 dis:false]解锁。
完整 DSL 语法（属性简写、变体白名单、流式渲染约束等）见 DSL 语法。