企业官网建设流程全解析

Vant 4 PasswordInput 密码输入框组件完全指南：用法、API 与主题定制

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant

PasswordInput 是 Vant 移动端组件库中专门用于密码、短信验证码等安全输入的网格状输入框组件。它本身不接收系统键盘输入，而是通过value属性受控展示内容，并对外触发focus事件，通常与数字键盘组件 NumberKeyboard 搭配构成完整的“点选式”输入体验。读完本文，你将掌握 PasswordInput 的注册方式、全部 Props/Events API、与 NumberKeyboard 的联动写法、错误提示逻辑，以及通过 CSS 变量深度定制样式的完整方法。

组件介绍与适用场景

密码输入框是移动端支付、登录、身份验证等场景的高频组件。PasswordInput 以“格子 + 圆点”的可视化形式呈现输入内容，相比原生<input type="password">更适合与虚拟数字键盘搭配，规避移动端系统键盘弹出的不可控行为。

从源码结构看，该组件位于 packages/vant/src/password-input，目录内包含组件实现PasswordInput.tsx、样式文件index.less、类型定义types.ts以及独立的测试与演示代码，是标准的 Vant 单组件模块布局。

引入与注册

PasswordInput 和 NumberKeyboard 都支持通过 Vue 插件方式全局注册：

import { createApp } from 'vue'; import { PasswordInput, NumberKeyboard } from 'vant'; const app = createApp(); app.use(PasswordInput); app.use(NumberKeyboard);

从 index.ts 的实现可以看出，组件通过withInstall包装导出，同时声明了全局组件类型：

export const PasswordInput = withInstall(_PasswordInput); export default PasswordInput; export { passwordInputProps } from './PasswordInput'; export type { PasswordInputProps } from './PasswordInput'; export type { PasswordInputThemeVars } from './types'; declare module 'vue' { export interface GlobalComponents { VanPasswordInput: typeof PasswordInput; } }

这意味着在<script setup>或模板中直接使用<van-password-input>时，TypeScript 也能获得完整的类型提示。除全局注册外，也支持按需引入后局部注册。

基础用法：与数字键盘联动

PasswordInput 的核心交互模型是：组件本身只负责“展示”和“聚焦反馈”，输入内容由数字键盘回填到value。典型代码如下：

<!-- 密码输入框 --> <van-password-input :value="value" :focused="showKeyboard" @focus="showKeyboard = true" /> <!-- 数字键盘 --> <van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false" />

import { ref } from 'vue'; export default { setup() { const value = ref('123'); const showKeyboard = ref(true); return { value, showKeyboard, }; }, };

联动要点：

• value是受控属性，密码框格子数量固定，输入内容通过圆点/明文展示；
• focused决定是否在“下一个待输入格子”显示闪烁光标；
• 点击密码框触发focus事件，用它来唤起数字键盘（showKeyboard = true）；
• 数字键盘的@blur收起键盘并同步关闭focused。

组件源码中的触摸处理也印证了这一交互：在 PasswordInput.tsx 中，安全区域监听了touchstart（onTouchstartPassive），在事件上调用stopPropagation后向外 emitfocus。stopPropagation的作用与 NumberKeyboard 文档 中的说明一致——阻止点击键盘以外的区域时键盘自动收起。

常用配置示例

自定义长度

支付密码通常为 4 位或 6 位，通过length属性控制格子数量：

<van-password-input :value="value" :length="4" :focused="showKeyboard" @focus="showKeyboard = true" />

格子间距

gutter用于设置格子之间的间距，支持px、em等单位，默认单位为px：

<van-password-input :value="value" :gutter="10" :focused="showKeyboard" @focus="showKeyboard = true" />

从 PasswordInput.tsx 的渲染逻辑可以看到，gutter不为 0 时格子间通过marginLeft产生间隔（使用addUnit自动补充单位，见 utils/format.ts 中的addUnit），同时不再绘制格子左侧分隔线，整体呈现“独立圆角卡片”风格；当gutter为默认值0时则使用BORDER_SURROUND绘制整体边框、用BORDER_LEFT绘制格子之间的分隔线。

明文展示

mask控制是否隐藏输入内容。将mask设为false即明文展示，适用于短信验证码等无需遮挡的场景：

<van-password-input :value="value" :mask="false" :focused="showKeyboard" @focus="showKeyboard = true" />

源码中明文/密文的渲染逻辑非常直观（PasswordInput.tsx）：mask为true时渲染一个<i>圆点元素，仅当对应位置存在字符时才将其visibility设为visible；mask为false时直接渲染对应字符。

提示信息与错误提示

info用于展示普通提示（如“密码为 6 位数字”），error-info用于展示错误提示（如密码校验失败）。两者同时传入时，错误提示优先显示。示例：输入满 6 位但密码不正确时显示“密码错误”。

<van-password-input :value="value" info="密码为 6 位数字" :error-info="errorInfo" :focused="showKeyboard" @focus="showKeyboard = true" /> <van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false" />

import { ref, watch } from 'vue'; export default { setup() { const value = ref('123'); const errorInfo = ref(''); const showKeyboard = ref(true); watch(value, (newVal) => { if (newVal.length === 6 && newVal !== '123456') { errorInfo.value = '密码错误'; } else { errorInfo.value = ''; } }); return { value, errorInfo, showKeyboard, }; }, };

在 PasswordInput.tsx 中，提示信息的优先级逻辑为const info = props.errorInfo || props.info，即error-info存在时优先渲染错误提示，并为其追加van-password-input__error-info样式类；仅传入info时使用van-password-input__info类。两者均不传时不渲染提示区域。组件测试 test/index.spec.ts 也覆盖了error-info的渲染快照断言。

API 说明

Props

这些 Props 在 PasswordInput.tsx 中通过 Vant 的工具函数声明，其底层行为值得说明：

export const passwordInputProps = { info: String, mask: truthProp, // 默认值为 true 的布尔属性 value: makeStringProp(''), // 字符串属性，默认 '' gutter: numericProp, // 数值或带单位字符串，如 '20px'、2em length: makeNumericProp(6),// 数值或字符串，默认 6 focused: Boolean, errorInfo: String, };

• value、gutter、length都支持数字与字符串两种写法，如:gutter="10"与gutter="20px"等价，单位字符串会被原样传入样式；
• length在渲染前会统一转为数字（const length = +props.length）；
• mask使用truthProp声明，默认即为true，这正是“默认隐藏密码内容”的由来。

Events

focus事件在组件声明为emits: ['focus']，触发时机为安全区域（格子区域）被touchstart触碰时，因此点击密码框任意位置都能唤起键盘。测试用例 test/index.spec.ts 专门验证了该行为：

test('should emit focus event when security is touched', () => { const wrapper = mount(PasswordInput); wrapper.find('.van-password-input__security').trigger('touchstart'); expect(wrapper.emitted('focus')).toHaveLength(1); });

类型定义

组件导出以下类型定义，便于在 TSX 或业务代码中做类型约束：

import type { PasswordInputProps } from 'vant';

此外还导出了PasswordInputThemeVars主题变量类型（见 types.ts），用于在配置 ConfigProvider 主题时获得完整的类型提示。

主题定制：CSS 变量

PasswordInput 提供了丰富的 CSS 变量用于定制样式，可在任意需要覆盖的元素上声明，或统一通过 ConfigProvider 组件 进行全局配置。

这些变量的默认值定义在 index.less 的:root中，与 types.ts 的PasswordInputThemeVars一一对应。例如将圆点改为品牌色并缩小密码框高度：

:root { --van-password-input-dot-color: #1989fa; --van-password-input-height: 44px; }

从样式源码还可观察到两个实现细节：

• 光标闪烁：van-password-input__cursor通过van-cursor-flicker关键帧动画实现透明度 0 → 1 → 0 的循环，动画时长由--van-password-input-cursor-duration控制，这与focused属性“聚焦时显示光标”的行为对应；
• 布局结构：整个组件包含.van-password-input__security（格子容器）与__info/__error-info（提示区域），格子容器为flex布局，每个<li>以flex: 1均分宽度，圆点<i>与光标均通过绝对定位 +translate(-50%, -50%)居中。

完整可运行示例

参考官方演示 demo/index.vue 的交互设计，下面给出一个带错误校验的完整示例：键盘输入满 6 位后自动校验，非123456时展示错误提示。

<template> <van-password-input :value="value" info="请输入 6 位支付密码" :error-info="errorInfo" :focused="showKeyboard" @focus="showKeyboard = true" /> <van-number-keyboard :show="showKeyboard" @blur="showKeyboard = false" @input="onInput" @delete="onDelete" /> </template> <script setup> import { ref } from 'vue'; const value = ref(''); const errorInfo = ref(''); const showKeyboard = ref(false); const onInput = (key) => { value.value = (value.value + key).slice(0, 6); if (value.value.length === 6) { errorInfo.value = value.value === '123456' ? '' : '密码错误'; } }; const onDelete = () => { value.value = value.value.slice(0, -1); errorInfo.value = ''; }; </script>

要点提示：在真实业务中，应使用服务端返回的校验结果驱动error-info，并注意在键盘输入过程中清空上一次的错误状态；value达到length上限后，可结合业务需要自动执行提交逻辑。

小结

PasswordInput 是一个“展示型受控组件”：通过value接收输入内容、length控制格子数量、mask切换明文/密文、gutter调整间距，配合focused与focus事件完成与数字键盘的状态同步；info/error-info提供了提示与错误反馈能力，而完整的 CSS 变量体系让视觉定制变得简单可控。结合 PasswordInput.tsx 源码与 test/index.spec.ts 测试，你可以放心地在支付、登录、验证码等场景中直接使用该组件。

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant