Input 输入框
原生 <input> 增强的基础输入组件。
基础用法
基础用法
无障碍名称（label）
label（可访问名称）
label 作为输入框的可访问名称（aria-label）来源，读屏朗读该名称。未设置 label 时依次回退 placeholder → 内置文案「输入框」；设置后（如「登录邮箱」）覆盖回退链。
原生表单与 label 关联
form-associated：label for / FormData / reset
组件是 form-associated 自定义元素（formAssociated: true）：<label for> 原生关联生效（点击 label 聚焦到 shadow 内真实 input，读屏朗读 label 文本）；放进原生 <form> 后经标准 FormData 收集（有 name 才提交）、form.reset() 回到 value 初始值、父级 fieldset[disabled] 联动禁用。与 oas-form 的 collectFields 机制并行可用。
程序性读/写当前值走公开 value property（对齐原生 input.value）：el.value 读取——parser/mask 感知的提交值语义（与 oas-input/oas-change/FormData 口径一致）；el.value = x 写入——写受控 value 属性并即时回写内部控件，不派发事件。受控赋值即生效语义：即使传入值与当前属性值相同也会强制回写内部控件；Vue 等框架对自定义元素的 :value 绑定在每次 patch 会无条件重写，受控绑定下请以事件（oas-input/oas-change）同步外部状态，避免无关重渲染抹掉用户未提交的输入。
类型
type
type 透传原生 input 类型，支持 text / password / number / email 等。
密码可见切换
show-password
show-password 在 type="password" 时于输入框右侧渲染眼睛按钮，点击在明文/密文间切换；按钮带 aria-label（locale 文案）与 aria-pressed，聚焦时有焦点环。
可清空
可清空（clearable）
存在内容且设置 clearable 时显示清除按钮，点击后清空并聚焦，派发 oas-clear。
加载态
loading 加载态（不禁用输入）
设置 loading 后输入框行尾显示 spinner 并同步 aria-busy="true"：输入不被禁用（用户可继续编辑，适合远程校验/联想请求场景）；与 clearable 共存时 spinner 优先、清除按钮让位，退出 loading 后恢复。
禁用与只读
disabled / readonly
前后缀（addon）
addon-before / addon-after
addon-before / addon-after 为输入框外侧的 addon 文案块（如单位、域名），分别走独立的 ::part(prepend) / ::part(append)，禁用时 addon 灰化。
图标
prefix-icon / suffix-icon
prefix-icon / suffix-icon 接受图标名（@oas-ui/icons 的 内置图标名），内联渲染 SVG 装饰图标。
内嵌前后缀与清空并存
prefix / suffix + clearable
prefix-text / suffix-text 为输入框内部文案，与 clearable、图标、addon 可并存不冲突。prefix / suffix 为兼容别名（attribute 与 property 两条通道均可写入，React / Vue 绑定也生效）——规范名是 prefix-text / suffix-text。
自定义清除图标（clear-icon 插槽）
clear-icon 插槽
clearable 的清除按钮默认渲染内置关闭图标；需要个性化时用 slot="clear-icon" 分发自定义图标（slot 有内容时原生替换内置 fallback，图标尺寸由分发内容自定）。
字数统计
show-count + maxlength
show-count 在输入框右下角显示字数统计：设置 maxlength 时显示 当前长度/maxlength，未设置时仅显示当前长度；maxlength 同时透传原生 input 限制输入长度。超过限制时计数数字变 danger 色。
提示文案（hint）
hint 静态提示（与校验错误独立）
hint 在输入框下方常驻一段静态提示文案（字号 --oas-font-size-sm、次要色），并通过 aria-describedby 关联到内层 input（读屏朗读提示内容）。它与校验错误（status / aria-invalid）相互独立：错误态出现时提示仍保留。点击按钮切换 status="error" 可看到错误边框与提示文案共存。
回车提交事件
oas-enter
输入时按 Enter（非输入法组合上屏）派发 oas-enter，detail: { value }。
事件
输入与清除事件
监听 oas-input（输入中）与 oas-clear（清除）：
复杂前后缀（slot 分发）
slot=prefix / slot=suffix
简单文本用 prefix-text / suffix-text 属性；复杂内容（图标/按钮/徽标等）用同名 slot="prefix" / slot="suffix" 分发，slot 有内容时原生替换属性文本。prefix / suffix 为兼容别名（规范名 prefix-text / suffix-text），attribute 与 property（React / Vue 绑定）两条通道均可用。
尺寸
size 尺寸档位
size 支持 small / medium（默认）/ large 三档，高度对齐全局尺寸 token（--oas-control-height-sm/md/lg，24/32/40px），字号同步缩放，内嵌前后缀、addon、清除/眼睛按钮同档联动。未显式设置时就近继承 oas-config-provider 的 size 注入（全局表单密度）。
形态
variant 形态
variant 支持 outlined（默认描边）/ filled（填充底色、聚焦才出边框）/ borderless（无框无底色，用于纯文本嵌入场景）。
校验态
status 校验态
status 支持 error / warning / success 三态：边框与焦点环切换语义色。error 会同步内层 input 的 aria-invalid="true"（读屏可感知「无效」）；warning / success 仅视觉提示、不标无效语义。表单校验（oas-form）写宿主 aria-invalid 的既有通道仍然生效，与 status 可叠加（error 优先）。
原生属性透传
原生属性透传白名单
以下原生属性镜像到 shadow 内原生 input（宿主移除后同步解除）：name / autocomplete / autofocus / inputmode / minlength / min / max / step / required / spellcheck / enterkeyhint / pattern。可用于原生表单语义、自动填充与移动端键盘优化（inputmode / enterkeyhint）；其中 min / max / step 供 type="number" 使用（其余类型浏览器原生忽略）。autofocus 由组件在挂载后转发聚焦一次（原生 autofocus 不穿透 shadow DOM），页面加载即可聚焦输入框。
焦点与提交事件
oas-focus / oas-blur / oas-change + select()
oas-focus/oas-blur：内层 input 聚焦/失焦时派发，detail: { value }携带当前值。oas-change：提交语义——失焦或按 Enter 时值相对上次提交发生变化才派发（输入中不派发，与oas-input区分）。select()方法：全选输入框内容（委托原生 input.select）；blur()同理委托失焦。
addon 复杂内容（slot 分发）
slot=prepend / slot=append（文本 / 图标 / 按钮）
addon-before / addon-after 属性只接文案；复杂内容用 slot="prepend" / slot="append" 分发。纯文本、图标渲染在灰底 addon 面上（圆角合并/边框去重与 addon 属性一致，文本双通道并存——slot 有内容时原生替换属性 fallback）。分发自包含控件（oas-button / oas-button-group / oas-compact）时，addon 会自动退化为贴合容器：去掉文本 addon 的灰底、描边与左右内边距，高度与输入框同档对齐，相邻边 -1px 压边合并为单线，并把圆角合并协议（--oas-button-group-radius）穿透给控件，使其外角与输入框外框拼成连续圆角。选择器等自带边框/底色的复合控件仍不建议放进 addon 槽：跨 Shadow 边界无法安全去除其内部样式（其下拉层与触发器共享颜色 token，透明化会连带下拉菜单），与输入框拼接复合控件请用 oas-compact 紧凑容器：
select + input 组合（oas-compact 紧凑拼接）
块级 addon（block-start / block-end）
slot=block-start / slot=block-end（输入框上/下方整行块）
slot="block-start" / slot="block-end" 在输入框上方 / 下方各渲染一个整行块级 addon：与 prepend / append（水平拼接在输入框两侧）不同维度，块级行独立占位、不参与边框拼接，可放提示文案、动作按钮、链接等任意内容。行容器字号走 --oas-font-size-sm、次要色（禁用时灰化），经 ::part(block-start) / ::part(block-end) 可深度定制。与 show-count（outside 计数同在输入框下方）并存时，计数自动挂进 block-end 行内靠右显示，不重叠。
字数统计位置与字素计数
count-position + emoji 字素计数
show-count 计数按**字素（grapheme）**统计（内建 Intl.Segmenter，无该 API 时按码点兜底）——emoji、ZWJ 组合字符（如家庭 emoji）计 1，避免 JS length 把一个 emoji 算作多个。count-position="inside" 把计数移到输入区内右侧（默认 outside 右下角）。注意：maxlength 的原生截断仍按码元口径，与统计口径分离（需要超限场景见下方 allow-over-max）。
超限不截断
allow-over-max + oas-validate
默认 maxlength 透传原生硬截断；设置 allow-over-max 后不再截断，超限可继续输入，计数标红（danger），并在越界状态翻转时派发 oas-validate（detail.error 为 exceed-maximum，回到限内为 null），宿主可据此提示而不打断输入。
显示格式化（formatter / parser）
formatter / parser（千分位，property 通道）
formatter / parser 仅 JS property 通道（el.formatter = fn）——Web Components 的 attribute 无法传函数，无对应 HTML 属性。显示值 = formatter(原始值)，oas-input / oas-change 等事件 detail.value 携带 parser(显示值) 解析后的原始值；移除（置 null）恢复原始显示。输入时光标按格式化前后长度差近似保持（卡号分段等场景够用）。
输入掩码（mask）
mask 输入掩码（###-####）与 mask-raw 原始值
mask 定义输入掩码模板：# 数字、A 字母、* 字母数字，其余字符为字面量（如 ###-#### 的 -）。键入自动跳过字面量、非法字符被过滤、粘贴只收合法位、退格删到字面量即停（字面量由模板管理，不会被删穿），光标始终保持在正确位置。默认事件与表单提交值携带显示值（含字面量）；设置 mask-raw 后改为去格式化的原始字符序列（FormData 提交值同口径）。mask 与 formatter/parser 互斥，同设时 mask 优先并告警；maxlength 在 mask 模式下不透传（避免原生截断破坏掩码）。（show-count 计数口径随提交通道：缺省按显示值（含字面量），mask-raw 时按原始序列）
清除按钮显隐
show-clear-on
show-clear-on 控制清除按钮显隐策略：默认 always（有值即常显，现状不变）；focus 仅聚焦时显示；hover 悬浮或聚焦时显示（降低密集表单的视觉噪声）。
宽度自适应
auto-width
auto-width 开启后宽度随内容自适应（mirror 测宽技术：与输入框同字体/内边距的隐藏测量元素，空值回落占位文本宽度）；auto-width-min / auto-width-max（px 数值）钳制宽度范围，min 缺省 72px、max 缺省 100%。行内编辑、标签输入等场景常用。
范围输入（组合写法）
两个输入框 + 分隔符（范围输入）
范围输入用两个 oas-input + 分隔符布局即可（组件不提供 pair 双输入 API）：两个输入框各自的 oas-change 提交值，宿主组合成区间。需要紧凑圆角拼接时外层套 oas-compact 容器。
API
oas-input
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
addon-after | 后置 addon 文案块 | — | — |
addon-before | 前置 addon 文案块 | — | — |
allow-over-max | 超限不截断：maxlength 不再透传原生（可继续输入），计数标红并派发 oas-validate | boolean | — |
auto-width | 宽度随内容自适应（mirror 测宽；空值回落 placeholder 宽），常配 auto-width-min/max 钳制 | boolean | — |
auto-width-max | auto-width 最大宽度 px 或百分比（默认 100%） | — | — |
auto-width-min | auto-width 最小宽度 px（默认 72） | — | — |
autocomplete | 透传内层原生 input 的自动填充提示（密码管理器/浏览器自动填充） | — | — |
autofocus | 挂载后自动聚焦内层输入框（原生 autofocus 不穿透 shadow，组件转发） | boolean | — |
clearable | 可清空 | boolean | — |
count-position | 字数计数位置：outside（默认，框外）/ inside（输入区内右侧） | string | — |
disabled | 禁用 | boolean | — |
enterkeyhint | 透传内层原生 input 的移动虚拟键盘回车键形态（如 search/send/go） | — | — |
hint | 输入框下方常驻静态提示文案（aria-describedby 关联，独立于校验错误） | string | — |
inputmode | 透传内层原生 input 的移动虚拟键盘类型 | — | — |
label | 可访问名称（aria-label 来源，未设时回退 placeholder → 内置文案「输入框」） | — | — |
loading | 加载态：行尾 spinner + aria-busy（不禁用输入）；与 clearable 共存时优先显示 | boolean | — |
mask | 输入掩码模板：# 数字 / A 字母 / * 字母数字，其余字符为字面量（如 ###-####）；键入自动跳字面量、粘贴只收合法位、退格删到字面量停；与 formatter/parser 互斥（mask 优先） | string | — |
mask-raw | 提交值/FormData 为去格式化的原始字符序列；缺省提交显示值 | boolean | — |
max | 透传内层原生 input 的最大值 | — | — |
maxlength | 最大输入长度（透传原生 maxlength） | string | — |
min | 透传内层原生 input 的最小值（number 类型生效） | — | — |
minlength | 透传内层原生 input 的最小长度约束 | — | — |
name | 原生表单字段名（form-associated：FormData 提交的键） | — | — |
pattern | 透传内层原生 input 的正则校验模式 | — | — |
placeholder | 占位提示 | string | — |
prefix-icon | 前置图标名 | string | — |
prefix-text | 内嵌前置文案；prefix 为兼容别名（attribute 与 property 通道均可用） | string | — |
readonly | 只读 | boolean | — |
required | 必填标记（透传原生 input；驱动原生校验链 valueMissing） | boolean | — |
show-clear-on | 清除按钮显隐：always（默认常显）/ hover / focus | string | — |
show-count | 显示字数统计（右下角，超限标 danger） | boolean | — |
show-password | 密码可见切换（type="password" 时渲染眼睛按钮） | boolean | — |
size | 尺寸档位 small / medium（默认）/ large：高度与字号联动 | string | medium |
spellcheck | 透传内层原生 input 的拼写检查开关 | — | — |
status | 校验态：error / warning / success；error 同步内层 aria-invalid | string | — |
step | 透传内层原生 input 的步长 | — | — |
suffix-icon | 后置图标名 | string | — |
suffix-text | 内嵌后置文案；suffix 为兼容别名（attribute 与 property 通道均可用） | string | — |
type | 原生 input 类型 | string | text |
value | 值（受控） | string | — |
variant | 形态：outlined（默认描边）/ filled（填充底色）/ borderless（无框） | string | — |
Property（JS property；是否写回 attribute 见各行说明）
| Property | 说明 | 类型 | 默认值 |
|---|---|---|---|
value | 当前值：parser/mask 感知的提交值语义（el.value 读；el.value = x 写受控 value 并即时回写内部控件，不派发事件） | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-blur | 失焦时派发，detail: { value } |
oas-change | 提交语义：失焦/Enter 且值相对上次提交变化时派发，detail: { value } |
oas-clear | 点击清除，detail: { originalEvent } |
oas-enter | 按 Enter（非输入法组合），detail: { value } |
oas-focus | 聚焦时派发，detail: { value } |
oas-input | 输入中，detail: { value } |
oas-validate | allow-over-max 越界状态翻转时派发，detail: { error: "exceed-maximum" | null } |
插槽
| 名称 | 说明 |
|---|---|
append | 后置 addon 区（可嵌 select/按钮等任意内容） |
block-end | 输入框下方整行块级 addon（动作行/计数行，任意内容；outside 字数计数并存时自动挂入本行） |
block-start | 输入框上方整行块级 addon（提示行/说明行，任意内容） |
clear-icon | 自定义清除按钮图标（插槽有内容即替换内置） |
prefix | 内嵌前置内容（图标/按钮等复杂内容，分发时优先于 prefix 属性文本）；简单文本用 prefix 属性即可 |
prepend | 前置 addon 区（可嵌 select/按钮等任意内容） |
suffix | 内嵌后置内容（图标/按钮等复杂内容，分发时优先于 suffix 属性文本）；简单文本用 suffix 属性即可 |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-button-group-radius | var(--oas-radius-md) |
--oas-input-auto-max | 100% |
--oas-input-auto-min | 72px |
--oas-input-measured | 100% |