MotionForm | Tuff Docs

用法

全部变体

validate 只发起请求；调用方写回 status 与 error，改变 validationKey 重播震动。

示例加载中...

最佳实践

模型、校验消息与业务状态由调用方维护；组件不自行判定成功，也不定时清除错误。
filesSelected 只表示选中文件：用应用自己的服务上传每个 File，再用结果驱动 status。
始终提供 label 与本地化的 labels；OTP 每格的名称也由 label 生成。
readonly 只用于文本类字段与 OTP；选择、文件、滑块与动作用 disabled。
只有外层原生表单负责提交时才设 nativeType="submit"，不要在点击与表单 submit 中重复执行同一操作。

API 参考

属性

名称	类型	默认值	说明
`variant`	`MotionFormVariant`	`'floating-label-input'`	十五个效果之一，见下方变体表。
`modelValue`	`MotionFormValue`	未设置	受控值，形状由变体决定。
`label`	`string`	`''`	可见标签与无障碍名称；为空时用 `labels.field`。
`placeholder`	`string`	`''`	文本与选择的占位；浮动标签静止时会遮住它。
`description`	`string`	`''`	消息区的辅助文案；错误与状态优先。
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`	高度、选择标记与圆角；动作按钮的 `xs` 对应 Button 的 `sm`。
`disabled`	`boolean`	`false`	禁止编辑、选择、移除、显示密码与动作请求。
`readonly`	`boolean`	`false`	文本、文本域与 OTP 只读；仍可显示密码。
`required`	`boolean`	`false`	必填标记与无障碍状态；原生文本字段同时设置 `required`。
`status`	`'default' \| 'loading' \| 'success' \| 'error'`	`'default'`	调用方驱动的状态；`loading` 时阻止动作请求。
`error`	`string`	`''`	非空时进入错误状态并显示该消息。
`validationKey`	`string \| number`	未设置	变化时重播当前错误。
`labels`	`Partial<MotionFormLabels>`	未设置	本地化静态文案、数字框名称与移除标签。
`options`	`MotionFormOption[]`	`[]`	单选、下拉与标签的选项。
`inputType`	`'text' \| 'email' \| 'number' \| 'date'`	`'text'`	文本控件类型；密码变体自行切换 text/password。
`autocomplete`	`string`	未设置	原生自动完成；OTP 首格固定为 `one-time-code`。
`passwordVisible`	`boolean`	未设置	受控的密码显示状态，配合 `update:passwordVisible`。
`rows`	`number`	`2`	文本域最小行数。
`maxRows`	`number`	`8`	自动增高的最大行数，超出后滚动；不小于 `rows`。
`maxLength`	`number`	未设置	文本与文本域的长度上限；OTP 固定 4 位。
`accept`	`string`	`'/'`	文件选择与拖放的类型过滤。
`multiple`	`boolean`	`true`	多选文件；为 `false` 时新文件替换旧文件。
`maxFiles`	`number`	`10`	文件数量上限。
`min`	`number`	`0`	滑块最小值。
`max`	`number`	`100`	滑块最大值。
`step`	`number`	`1`	滑块步长。
`formatValue`	`(value: number) => string`	未设置	滑块数值与提示的格式化函数。
`nativeType`	`'button' \| 'submit'`	`'button'`	提交按钮的原生类型。
`motion`	`boolean`	`true`	启用动效；仍受可见性、KeepAlive 与减少动态效果限制。

事件

事件	参数	含义
`update:modelValue`	`MotionFormValue`	用户编辑或选择时触发。
`change`	`MotionFormValue`	与 `update:modelValue` 同时触发。
`update:passwordVisible`	`boolean`	切换密码显示时触发。
`focus`, `blur`	`FocusEvent`	焦点进入或离开组件时触发；内部移动不触发。
`search`	`string`	search-expand 的文本变化时触发；不发请求。
`validate`	`MotionFormValue`	请求调用方校验当前值。
`submit`	`[value: MotionFormValue \| undefined, event: MouseEvent]`	请求调用方执行操作；不修改 `status`。
`otpComplete`	`string`	四格都填入数字时触发；改写后可再次触发。
`filesSelected`	`FileUploaderFile[]`	本次新增并被接受的文件；不是累计列表，也不是上传完成。
`fileRemove`	`{ id: string, value: FileUploaderFile[] }`	移除文件时触发，携带 ID 与新列表。

插槽

插槽	作用域	用途
`label`	无	可见标签，通过稳定 ID 关联控件。
`prefix`, `suffix`	无	输入前后缀；`suffix` 会替换密码显示按钮。
`option`	`{ option, selected }`	单选与下拉的选项内容。
`chip`	`{ option }`	标签文案；移除按钮保留。
`file`	`{ file, remove: () => void }`	文件行内容；移除按钮保留。
`submit`	`{ status: MotionFormStatus, label: string }`	提交按钮文案，与状态图标并排。
`status`	`{ status, error, value }`	实时消息区的内容。

暴露方法

方法	行为
`focus()`	聚焦第一个可用的输入、文本域或动作按钮。
`blur()`	让当前聚焦的子控件失焦。

类型

import type { FileUploaderFile } from '@talex-touch/tuffex/file-uploader'
import type { MotionFormProps, MotionFormVariant } from '@talex-touch/tuffex/motion-form'

type MotionFormValue = string | number | boolean | (string | number)[] | FileUploaderFile[]
type MotionFormOption = TxSelectOption // { value, label, disabled?, icon?, description? }
// FileUploaderFile: { id, name, size, type, file: File }
// MOTION_FORM_VARIANTS 导出完整只读变体元组。

MotionFormVariant

原始 ID	`variant`	模型	效果
`frm1`	`floating-label-input`	`string` 或 `number`	聚焦或有值时标签上浮缩小。
`frm2`	`input-focus-glow`	`string` 或 `number`	聚焦时扩散光环，失焦收回。
`frm3`	`password-toggle`	`string`	显示按钮切换明文，眼睛图标旋转；不改值。
`frm4`	`search-expand`	`string`	聚焦时在可用宽度内展开，图标位移。
`frm5`	`checkbox-draw`	`boolean`	勾选时绘出勾并轻微放大。
`frm6`	`radio-scale`	`string` 或 `number`	单选，中心圆点弹性缩放。
`frm7`	`error-shake`	`string` 或 `number`	`error`、错误状态或 `validationKey` 变化时震动。
`frm8`	`success-check`	`string` 或 `number`	请求校验；成功状态弹出并绘出勾。
`frm9`	`select-dropdown`	`string` 或 `number`	Select 按锚点方向缩放、位移并淡入。
`frm10`	`multi-select-chips`	`(string \| number)[]`	已选标签弹性进出，移除按钮更新数组。
`frm11`	`textarea-auto-grow`	`string`	按实际滚动高度弹性增高，有上限。
`frm12`	`otp-input`	`string`	四格数字自动前进，粘贴内容自动分发。
`frm13`	`file-upload-dropzone`	`FileUploaderFile[]`	选择或拖放文件；拖入时边框脉动、箭头上抬。
`frm14`	`range-slider`	`number`	Slider 处理指针与键盘，拇指弹性并浮动显示数值。
`frm15`	`form-submit-button`	可选 `MotionFormValue`	按调用方状态切换文字、转圈与勾。

MotionFormLabels

默认值导出为 MOTION_FORM_DEFAULT_LABELS，labels 可局部覆盖。

键	默认值/类型
`field`	`'Field'`
`showPassword`, `hidePassword`, `capsLock`	`'Show password'`, `'Hide password'`, `'CapsLock is on'`
`validate`, `validating`, `verified`, `validationError`	`'Validate'`, `'Validating…'`, `'Verified'`, `'Validation failed'`
`submit`, `submitting`, `submitted`, `submitError`	`'Submit'`, `'Submitting…'`, `'Submitted'`, `'Submission failed'`
`chooseFiles`, `dropFiles`, `fileHint`	`'Choose files'`, `'Drop files here'`, `'or click to browse'`
`searchOptions`, `noOptions`	`'Search options'`, `'No options'`
`otpDigit`	`(index: number) => string`；从 1 开始，默认 `Digit N of 4`
`removeOption`	`(label: string) => string`；默认 `Remove <label>`
`removeFile`	`(name: string) => string`；默认 `Remove <name>`

CSS 变量

变量	`md` 默认值	用途
`--tx-mf-height`	`36px`	输入与动作高度；各尺寸为 26/30/36/42px。
`--tx-mf-choice`	`22px`	复选与单选标记尺寸；各尺寸为 16/18/22/24px。
`--tx-mf-radius`	`12px`	字段圆角；各尺寸为 8/10/12/12px。

颜色来自 --tx-color-*、--tx-text-color-*、--tx-bg-color 与 --tx-border-color-*；动效变量由内部生成，不是公开 API。

概述

编辑、选项、拖放与键盘语义由 Input、Select、Checkbox、Radio、Textarea、FileUploader 与 Slider 负责；本组件只添加动效与受控事件。
标签与控件相邻，useId 关联标签、辅助文案与 OTP；密码按钮是带 aria-pressed 的原生按钮。
状态与错误显示在 role="status" aria-live="polite" 区域；重播动效不重置焦点。
OTP 支持粘贴、自动填充、←/→、Home/End、Backspace 与 Delete；外部传入的新值替换全部四格。
标签变体每次添加一个选项，已选项不能重复添加。
不可见或 KeepAlive 失活时暂停动效与监听；减少动态效果只关闭装饰动效，不影响输入与测量。

技术实现

文字过渡用 TxTextMorph，曲线来自共享的 liquid spring resolver；上游的定时清除错误与模拟提交成功改为调用方维护的 error 与 status。
上游：Amicro 提交 43c29ce 的 src/components/forms/AnimatedFormElement.tsx，MIT，Copyright (c) 2026 SYED SUBHAN UDDIN。
源码：packages/tuffex/packages/components/src/motion-form/。

查看源码

packages/tuffex/packages/components/src/motion-form/index.ts