密码
概述
带显示/隐藏切换按钮的密码输入框组件。适用于登录表单、注册表单等任何敏感凭据输入场景。它组合输入框族系基座并提供可见性切换，同时支持可清除模式。非敏感文本请使用 SInput。
用法
特性
- 📏 6 种尺寸：xs、sm、md、lg、xl、2xl（继承自输入框基座）
- 👁 显示/隐藏切换，带 i18n
aria-label与aria-pressed语义 - 🎛 受控/非受控
visible状态（v-model:visible+defaultVisible） - 🧹 可清除模式，清除按钮带 i18n
aria-label - 🔒
disabled/readonly对 input、切换按钮、清除按钮三元素全守卫 - 📋 设置
name时通过代理隐藏输入框支持原生表单提交 - 🧩 自定义
visible插槽，可定制切换按钮 - ♿ 完整无障碍支持——切换按钮命名、按下态、axe 零违规
演示
基础
100%
图标
100%
API
Aria 层
2Password
25 属性3 事件4 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于根元素的额外类名。 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<PasswordUi> | — | 该组件的按槽类重写。 |
visible | boolean | — | 受控的密码可见性。 |
defaultVisible | boolean | false | 未受控时的初始可见性状态。 |
visibleProps | ButtonProps | — | 转发给可见元素的属性。 |
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
controlProps | InputControlProps | — | 转发给控件的属性。 |
clearProps | InputClearProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | string | — | 输入的默认值 |
modelValue | string | — | 输入的受控值 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
rootProps | BaseProps | — | 转发至根元素的属性 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
update:visible | boolean | 在可见状态发生变化时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | PasswordCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | PasswordCompactSlotProps | 尾部槽位的自定义内容。 |
clear | PasswordCompactSlotProps | 为“clear”槽位定制内容。 |
visible | PasswordCompactSlotProps | 可见插槽的自定义内容。 |
PasswordCompact
22 属性3 事件4 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
visible | boolean | — | 受控的密码可见性。 |
defaultVisible | boolean | false | 未受控时的初始可见性状态。 |
visibleProps | ButtonProps | — | 转发给可见元素的属性。 |
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
controlProps | InputControlProps | — | 转发给控件的属性。 |
clearProps | InputClearProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | string | — | 输入的默认值 |
modelValue | string | — | 输入的受控值 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
rootProps | BaseProps | — | 转发至根元素的属性 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
update:visible | boolean | 在可见状态发生变化时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | PasswordCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | PasswordCompactSlotProps | 尾部槽位的自定义内容。 |
clear | PasswordCompactSlotProps | 为“clear”槽位定制内容。 |
visible | PasswordCompactSlotProps | 可见插槽的自定义内容。 |
注意事项
架构与对标差异
VeanUI 通过复用输入框族系基座构建密码输入：PasswordCompact 组合 InputRoot / InputControl / InputClear，并新增由 useControllableState 支撑的默认 visible 插槽。styled 层在 inputVariants 基础上扩展 visible 插槽覆写，样式为迷你图标按钮。这与 reka-ui、shadcn 的 headless/styled 分离一致，区别于 Element Plus 等单包方案。
| 能力 | VeanUI | reka-ui PasswordInput | shadcn | Element Plus el-input |
|---|---|---|---|---|
| Aria/styled 分离 | ✅ | — | — | — |
受控/非受控 visible | ✅ | ✅ | — | — |
| 显示/隐藏切换（图标） | ✅ | ✅ | ✅ | ✅ |
| i18n 切换标签 | ✅ | — | — | ✅ |
aria-pressed 语义 | ✅ | — | — | — |
| 可清除模式 | ✅ | — | ✅ | ✅ |
disabled / readonly 守卫 | ✅ | ✅ | ✅ | ✅ |
| 尺寸变体（xs…2xl） | ✅ | — | — | — |
自定义 visible 插槽 | ✅ | — | — | — |
| 表单代理（隐藏输入框） | ✅ | — | — | — |
注意事项
type属性会被可见性状态接管（可见时text、否则password），用户传入的type不会生效。- 切换按钮渲染为
type="button"，防止误触原生表单提交。 - 光标位置与密码管理器兼容性由原生 input 契约保证。
常见问题
如何让密码默认显示？
非受控方式传入 defaultVisible；受控方式用 v-model:visible 绑定 visible。
如何自定义切换按钮？
使用 visible 插槽。它提供 modelValue、visible、clear、toggle 等 props，可完全掌控。
如何让输入框可清除？
传入 clearable。清除按钮会清空值并触发 clear 事件；disabled / readonly 时会同步禁用。
为什么传入的 type 不生效？
密码输入框必须切换 text 与 password 以实现可见性切换。该切换由组件持有，因此用户传入的 type 会被覆盖——这是设计意图。