---
title: "密码输入"
description: "PasswordInput 是带显隐按钮的原生密码框：保持光标位置、对接密码管理器、提交时自动隐藏。"
---
> Documentation Index
> Fetch the complete documentation index at: https://ui-sdk.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.
# 密码输入
`PasswordInput`（密码输入）是一个原生密码输入加上显示、隐藏按钮。切换显隐时光标与选区留在原处，密码管理器能识别该填哪种密码，表单提交时会自动把明文重新遮罩。只需要普通文本时用[输入框](https://ui-sdk.ndjp.net/docs/components/input)；短验证码用[验证码输入](https://ui-sdk.ndjp.net/docs/components/otp-input)。
## 组合
```text
PasswordInput
├── PasswordInputControl
└── PasswordInputToggle
```
`PasswordInput` 持有值与显隐状态；`PasswordInputControl` 渲染原生输入；`PasswordInputToggle` 渲染切换按钮，它在 `password` 与 `text` 两种类型之间切换，自身是 `type="button"`，所以在输入里按 `Enter` 仍然提交表单。
表单相关属性（`name`、`form`、`required`、`disabled`、`readOnly`）放在 `PasswordInput` 上；其余原生输入属性（`placeholder`、`id` 等）放在 `PasswordInputControl` 上。
## 用法
```tsx
import { Field, FieldLabel } from "@ui-sdk/react/field";
import { PasswordInput, PasswordInputControl, PasswordInputToggle } from "@ui-sdk/react/password-input";
密码
{(state) => (state.visible ? "隐藏" : "显示")}
;
```
部件的 children 可以是函数，收到该部件的状态；这里用 `state.visible` 切换按钮内容。放进[字段](https://ui-sdk.ndjp.net/docs/components/field)后，`FieldLabel` 为输入命名，`FieldDescription` 作为说明被一起朗读。
## 显隐状态
`defaultVisible` 让密码一开始就是明文，适合需要被读出或复制的场景，例如展示给访客的 Wi-Fi 密码。要完全受控就传 `visible` 与 `onVisibleChange`：
```tsx
const [visible, setVisible] = React.useState(false);
{(state) => (state.visible ? "隐藏" : "显示")}
;
```
`details.reason` 区分 `toggle-press`、`form-submit`、`reset`、`page-hide` 与 `imperative`。表单提交与页面被隐藏（例如跳转离开）时组件会主动隐藏明文，前者让浏览器正常提示保存密码，后者避免明文被浏览器缓存进页面快照。`details.cancel()` 可以拒绝显隐变更，但提交过程中浏览器读取表单的那一刻，输入仍会临时回到密码类型。
## 自动填充与密码管理器
`autoComplete` 默认是 `"current-password"`，用于登录；注册或修改密码时改成 `"new-password"`，浏览器与密码管理器才会提供生成、保存新密码的流程，也可以设 `"off"`。
```tsx
{(state) => (state.visible ? "隐藏" : "显示")}
```
组件本身不施加任何密码强度策略。要做强度清单，用受控值 `value` + `onValueChange` 自己推导规则并渲染，自动填充与密码管理器填入的值同样以 `input-change` 报告。
## 大写锁定提示
聚焦期间按键事件会更新大写锁定状态，用 `data-capslock` 写样式，或读根的 `capsLock` 状态渲染提示：
```tsx
{(state) => (
<>
{state.capsLock ? "!" : ""}
{(toggle) => (toggle.visible ? "隐藏" : "显示")}
)}
```
给图标与提示预留固定位置，状态切换时布局才不会跳动。失焦或关闭大写锁定后提示消失。
## 控制器与表单
用 `createPasswordInputController()` 创建控制器传给根，可在字段之外读写：`getValue / setValue / clear / isVisible / setVisible / toggleVisible / focus`。写入方法接受 `{ reason, event }`，像用户输入或按下按钮一样触发变更回调，被取消时返回 `false`，默认原因是 `imperative`。参见[控制器](https://ui-sdk.ndjp.net/docs/concepts/controllers)。
```tsx
const password = createPasswordInputController();
password.setValue("plum-kettle-orbit-42");
password.setVisible(true);
```
原生输入参与 `FormData`、校验与重置：`name` 决定提交字段名（在字段内可用 `Field` 的 `name`），`form` 关联页面中其他表单的 id，`required` 阻止空值提交，重置回到 `defaultValue`。`disabled` 同时禁用输入与按钮且不提交；`readOnly` 只锁住文本，显隐按钮仍然可用。`disabled` 也会从 `Field` 或外层 `