SensitiveInput 敏感输入框

用于 API Key 与密钥的掩码输入框

已验证自 0.6.0

用法

基础

示例加载中...

最佳实践

用户之后还要读回的存量密钥用它；正在输入、永不回读的凭据用 TxInput type="password"。
宿主签发、用户不能改的密钥加 readonly：仍可揭示与复制，揭示后焦点留在容器上。
引导用户复制而不是揭示后手选；凭据界面需要审计时监听 reveal。
传 error 而不是 status="error"，状态与文案不会走散。
用 labels 本地化：十条文案中有七条只有屏幕阅读器听得到。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`string`	`''`	密钥本身（受控）。
`label`	`string`	`''`	字段标签，同时是掩码容器的可访问名。
`placeholder`	`string`	`''`	原生占位文本，仅在空状态可见。
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`	高度、内边距、圆角与图标尺寸；`md` 与 `TxInput` 对齐。
`status`	`'default' \| 'error'`	—	显式视觉状态；不传时由 `error` 推导。
`description`	`string`	`''`	字段下方的说明；有 `error` 时被替换。
`error`	`string`	`''`	校验信息；非空时字段变红并设置 `aria-invalid`。
`disabled`	`boolean`	`false`	不能揭示、复制或编辑。
`readonly`	`boolean`	`false`	禁止编辑，仍可揭示与复制。
`required`	`boolean`	`false`	在标签上标记必填。
`copyable`	`boolean`	`true`	渲染复制标签。
`mask`	`string`	`'••••••••'`	代替真实值绘制的符号；数量固定，不泄露密钥长度。
`copiedDuration`	`number`	`2000`	复制标签保持「已复制」的时长（ms）。
`labels`	`Partial<SensitiveInputLabels>`	—	覆盖渲染的全部文案，叠加在 `SENSITIVE_INPUT_DEFAULT_LABELS` 之上。

事件

事件名	回调参数	说明
`update:modelValue`	`(value: string)`	值变化时触发。
`copy`	`(value: string)`	值写入剪贴板后触发。
`copyError`	`(error: unknown)`	剪贴板拒绝写入时触发。
`reveal`	—	值变为可见时触发；凭据场景值得记入审计。
`mask`	—	值重新掩码时触发。

暴露方法

方法名	说明
`focus()`	掩码时聚焦容器，否则聚焦输入框。
`blur()`	使输入框失焦。
`reveal()`	以编程方式揭示值。
`mask()`	重新掩码。
`copy()`	执行复制流程，返回 Promise。

三种状态

状态	行为
已掩码	有值时的默认状态。显示 `mask` 符号；容器成为 `role="button"`，点击、回车或空格揭示；悬停或聚焦时符号换成「点击查看」。
已揭示	`type` 切为 `text`，焦点进入输入框。失焦或按 Esc 重新掩码，Esc 把焦点交还容器；聚焦眼睛或复制按钮不算失焦。
空	普通输入框，没有掩码、复制标签与 `role="button"`。输入首个字符即进入已揭示；外部传入的值落地即掩码。

概述

复制不会揭示值。
掩码容器是 role="button"（内含按钮，不能用 <button>），自带 tabindex、aria-label（<label>, 已遮蔽。）与 aria-describedby；掩码期间 <input> 为 aria-hidden 且 tabindex="-1"。
role="status" aria-live="polite" 区域播报「值已隐藏」与「已复制到剪贴板」。
点击 <label> 直接揭示，而不是转发焦点。
autocomplete="off" 与 data-1p-ignore / data-lpignore 让密码管理器浮层避开该字段。
唯一的过渡是复制标签的透明度，减弱动效下关闭。

技术实现

复制优先用 navigator.clipboard.writeText；不可用时回退到隐藏 textarea 的 execCommand，并在 finally 中移除该节点，失败也不会把密钥留在 DOM 里。
源码：packages/tuffex/packages/components/src/sensitive-input/。
行为参考 Kumo 的 SensitiveInput。

packages/tuffex/packages/components/src/sensitive-input/index.ts