Input

提供单行输入，支持文本、搜索、密码、数字、日期时间与颜色，可组合标签、图标和校验反馈。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于单行文本输入。搜索用 SearchInput，多行输入用 Textarea；需要 label、帮助和错误时组合 Field。

bind:value 同步编辑值，显式 value 优先于 defaultValue；数字类型输入后的值仍需业务自行转换。
name 用于表单提交，受控表单重置时恢复绑定初值；bind:element 得到外层元素，不能当作原生 input。
file / range 不提供上传或滑杆能力；附件用 leading / trailing 角色，清除按钮可接管 trailing。

导入

import { Input } from '@snowui-design-system/components';

用法

表单

图标

数字

验证

只读状态

禁用状态

清除

电话

日期

时间

日期与时间

颜色

自动填充

多个邮箱

建议

自定义选项

数字键盘

自动聚焦

外部表单

月份

星期

事件

加载中

状态

Tab 顺序

API 参考

属性	类型	默认值	示例	描述
`element`	`HTMLElement`	`—`	`bind:element={element}`	外层 Frame 根元素引用，支持 bind:element；不是原生 input 引用。
`gap`	`number`	`—`	`gap={42}`	继承 Frame 的间距 token 索引；省略时保留组件原首选间距，显式值覆盖首选间距，有效图文间距仍至少为 4 CSS px；显式零和根字号／间距缩放不压低下限。
`type`	`HTMLInputAttributes["type"]`	`"text"`	`type="email"`	选择单行输入类型；支持 text、search、email、password、url、tel、number、date、time、datetime-local、month、week、color。日期时间和颜色具有组件展示层及原生值宿主；file / range 会回退为 text，不提供上传或滑杆。
`value`	`InputValue`	`—`	`bind:value={siteName}`	当前值，支持 bind:value 双向同步；显式 value 优先于 defaultValue。原生编辑和内置清除事件同步 input.value 字符串；number 可使用数字初值，业务计算需自行转换。
`defaultValue`	`InputValue`	`—`	`defaultValue="SnowUI Workshop"`	未传 value 时的初始值；输入后的值由组件同步管理；表单重置若需恢复业务初值，应在 onreset 中显式恢复绑定值。
`placeholder`	`string`	`—`	`placeholder="Search documentation"`	空输入的提示文字，不替代可访问标签；日期时间输入保留分段占位。
`name`	`string`	`—`	`name="siteName"`	原生表单字段名；FormData 使用该名称收集字段。
`disabled`	`boolean`	`false`	`disabled`	禁止用户输入与交互，原生禁用字段不参与表单提交。
`readonly`	`boolean`	`false`	`readonly`	保留聚焦、选择与提交，禁止编辑并隐藏清除入口；自定义 trailing 聚焦后仍保留，使用只读视觉。
`clearable`	`boolean`	`true`	`clearable`	是否允许显示内置清除 X；false 时不渲染 X，不改变编辑、校验或自定义 trailing。适用于普通及 Field 内嵌 Input。
`required`	`boolean`	`false`	`required`	参与浏览器原生必填校验；不自动产生业务错误文案。
`autocomplete`	`HTMLInputAttributes["autocomplete"]`	`—`	`autocomplete="username"`	透传浏览器自动填充字段语义，如 username、email、new-password；候选来自浏览器已有数据。
`minlength`	`number`	`—`	`minlength={3}`	适用文本输入的最小字符长度，由浏览器在适用的用户编辑和表单校验路径执行。
`maxlength`	`number`	`—`	`maxlength={24}`	适用文本输入的最大字符长度；浮层 as="search" 未显式设置时回退为 100。
`pattern`	`string`	`—`	`pattern="[a-z0-9-]+"`	适用文本输入的原生校验正则，不包含斜杠；需要整体匹配，空值是否有效由 required 决定。
`min`	`number \| string`	`—`	`min={5}`	数字或日期时间输入的最小值；数字按输入数值，日期时间按对应原生格式表达。
`max`	`number \| string`	`—`	`max={100}`	数字或日期时间输入的最大值；数字按输入数值，日期时间按对应原生格式表达。
`step`	`number \| string`	`—`	`step={5}`	原生步进约束；number 以数值单位步进，日期时间使用浏览器对应类型的步进单位。
`inputmode`	`HTMLInputAttributes["inputmode"]`	`—`	`inputmode="numeric"`	向设备提示软键盘类型，如 numeric、decimal、tel；不执行输入过滤或校验。
`enterkeyhint`	`HTMLInputAttributes["enterkeyhint"]`	`—`	`enterkeyhint="next"`	向软键盘提示回车动作，如 next、search、done；不自动执行导航或提交。
`spellcheck`	`boolean`	`—`	`spellcheck={false}`	透传拼写检查开关；未指定时遵循浏览器与继承环境。
`list`	`string`	`—`	`list="snowui-sections"`	关联原生 datalist 的 id，候选与浏览器呈现由调用方和浏览器提供。
`accept`	`string`	`—`	`accept="image/*"`	保留的原生属性透传入口；Input 不支持 file，不能通过此属性获得文件类型限制或上传能力。
`multiple`	`boolean`	`—`	`multiple`	原生多值提示，适用于 email 多邮箱等浏览器支持的输入；Input 不支持多文件上传。
`capture`	`boolean \| "user" \| "environment"`	`—`	`capture="environment"`	保留的原生采集属性；由于 file 会回退为 text，在 Input 中不提供相机或文件采集能力。
`form`	`string`	`—`	`form="site-settings"`	按 id 关联外部 form；原生提交与重置包含该字段，不要求字段位于 form 内。
`autofocus`	`boolean`	`—`	`autofocus`	普通输入透传原生自动聚焦提示，浏览器可能保留已有焦点；日期时间展示层在首次挂载主动聚焦首段。避免页面加载抢焦点。
`tabindex`	`number`	`—`	`tabindex={0}`	透传原生焦点顺序；0 使用自然顺序，-1 退出顺序导航，正数定义显式顺序。常规表单推荐自然顺序。
`title`	`string`	`—`	`title="Public contributor name"`	原生提示文字；日期时间与颜色输入同时为展示层提供相应提示，不替代 label。
`id`	`string`	`—`	`id="site-account"`	原生输入标识，可供 label 的 for 与原生关联属性引用。
`invalid`	`boolean`	`false`	`invalid`	与 aria-invalid 汇总无效态，显示错误视觉；独立输入自动错误反馈，Field 内由 Field 汇总。
`error`	`string \| Snippet`	`—`	`error="Use a scoped, lowercase package name."`	invalid 时生成下方内置错误 Text；字符串为文案，Snippet 无参数并提供错误内容，默认不生成。
`parts`	`ComponentPartsOf<{ Text: typeof Text; Button: typeof Button }>`	`—`	`parts={{ Text: { "aria-live": "polite" } }}`	通过 Text / Button 键配置内置错误文案或操作按钮的公开 Props，仅对组件生成的 Text 生效；显式子项自行声明 Props。
`onclick`	`(event: MouseEvent) => void`	`—`	`onclick={(event) => log(event)}`	单击原生输入或相应展示层时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`ondblclick`	`(event: MouseEvent) => void`	`—`	`ondblclick={(event) => log(event)}`	双击时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`oninput`	`(event: Event) => void`	`—`	`oninput={(event) => log(event)}`	用户输入以及组件清除、步进等输入同步时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onchange`	`(event: Event) => void`	`—`	`onchange={(event) => log(event)}`	原生提交值变化或组件发出 change 同步时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onfocus`	`(event: FocusEvent) => void`	`—`	`onfocus={(event) => log(event)}`	输入获得焦点时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onblur`	`(event: FocusEvent) => void`	`—`	`onblur={(event) => log(event)}`	输入失去焦点时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onkeydown`	`(event: KeyboardEvent) => void`	`—`	`onkeydown={(event) => log(event)}`	按下键盘按键时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onkeyup`	`(event: KeyboardEvent) => void`	`—`	`onkeyup={(event) => log(event)}`	释放键盘按键时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onkeypress`	`(event: KeyboardEvent) => void`	`—`	`onkeypress={(event) => log(event)}`	浏览器触发已弃用的 keypress 时；新代码推荐 onkeydown回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`onpaste`	`(event: ClipboardEvent) => void`	`—`	`onpaste={(event) => log(event)}`	粘贴时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`oncopy`	`(event: ClipboardEvent) => void`	`—`	`oncopy={(event) => log(event)}`	复制时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`oncut`	`(event: ClipboardEvent) => void`	`—`	`oncut={(event) => log(event)}`	剪切时回调，参数为对应事件，无返回值；可取消的浏览器默认行为使用 event.preventDefault()，回调不用于撤销已经执行的组件内部值同步。
`children`	`Snippet`	`—`	`<Input placeholder="Search"><Icon as="leading"><MagnifyingGlass /></Icon></Input>`	无参数显式子内容，用 as="leading" / as="trailing" 组合图标或附件；清除可见时接管 trailing 位置。
`allowCustomValue`	`boolean`	`false`	`allowCustomValue`	仅 as="search" 位于 Listbox 时生效；无匹配时 Enter 将输入添加为自定义项并选中，支持删除自定义项。