鸿蒙PC UI控件库 - PasswordInput 密码输入框详解

红目香薰

发布于 2025-12-16 17:01:00

6200

文章被收录于专栏：CSDNToQQCodeCSDNToQQCode

视频地址：

https://www.bilibili.com/video/BV1jomdBBE4H/

📋 目录

概述
特性
快速开始
API 参考
使用示例
主题配置
最佳实践
常见问题
总结

概述

PasswordInput 是控件库中专用于密码输入的组件，基于 TextInput 扩展而来，支持显示/隐藏密码切换、密码强度显示、验证等功能，适用于登录、注册、密码修改等场景。

设计理念

密码输入框采用安全易用设计，具有以下特点：

安全优先：默认隐藏密码，支持一键切换显示/隐藏
强度提示：实时显示密码强度，帮助用户创建安全密码
功能完整：支持验证、提示、多种尺寸和状态
品牌标识：左下角自动包含品牌标识（圆圈红字"PC"）
主题统一：所有样式配置都在代码中，方便定制

适用场景

用户登录：登录页面的密码输入
用户注册：注册页面的密码设置
密码修改：修改密码功能
安全验证：需要密码确认的场景

特性

✨ 核心特性

✅ 显示/隐藏切换：支持一键切换密码显示/隐藏状态
✅ 密码强度显示：实时计算并显示密码强度（弱/中/强）
✅ 强度指示条：可视化显示密码强度等级
✅ 标签和提示：支持标签、提示文本、错误提示
✅ 多种尺寸：支持 small、medium、large 三种尺寸
✅ 状态管理：支持禁用、只读、必填等状态
✅ 长度限制：支持最大长度限制
✅ 品牌标识：自动包含左下角品牌标识
✅ 主题配置：所有样式都可通过代码配置

🎨 视觉特点

正常状态：白色背景 + 灰色边框
错误状态：红色边框 + 红色错误提示
禁用状态：灰色背景 + 灰色文字 + 灰色边框
只读状态：正常样式但不可编辑
强度指示：弱（红）、中（橙）、强（绿）三种颜色

快速开始

基础用法

import { PasswordInput } from '../components/base'

@Entry
@Component
struct MyPage {
  @State password: string = ''

  build() {
    Column({ space: 20 }) {
      // 基础密码输入框
      PasswordInput({
        value: $password,
        placeholder: '请输入密码'
      })
      
      // 带标签的密码输入框
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码'
      })
      
      // 带密码强度的密码输入框
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码',
        showStrength: true
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

关于双向绑定

PasswordInput 使用 @Link 实现双向绑定，需要使用 $variableName 语法：

@State password: string = ''

PasswordInput({
  value: $password  // 使用 $ 创建双向绑定
})

API 参考

Props

属性名	类型	默认值	说明
value	@Link string	-	密码值（必需，双向绑定）
placeholder	string	'请输入密码'	占位符文本
label	string?	undefined	标签文本（可选）
hint	string?	undefined	提示文本（可选，显示在输入框下方）
errorMessage	string?	undefined	错误提示文本（可选，优先级高于 hint）
inputSize	'small' \| 'medium' \| 'large'	'medium'	输入框尺寸
disabled	boolean	false	是否禁用
readonly	boolean	false	是否只读
required	boolean	false	是否必填
maxLength	number?	undefined	最大长度
showStrength	boolean	false	是否显示密码强度
showToggleButton	boolean	true	是否显示显示/隐藏切换按钮
showBrand	boolean	true	是否显示品牌标识
inputWidth	string \| number?	undefined	输入框宽度

PasswordStrength 枚举

值	说明
None	无（空密码）
Weak	弱
Medium	中
Strong	强

尺寸规格

尺寸	高度	字体大小	图标大小	内边距（左右）
small	48vp	14vp	18vp	12vp
medium	60vp	16vp	20vp	14vp
large	72vp	18vp	24vp	16vp

使用示例

1. 基础密码输入框

@Entry
@Component
struct PasswordExample1 {
  @State password: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password,
        placeholder: '请输入密码'
      })
      
      Text(`密码长度：${this.password.length}`)
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

2. 带标签和提示

@Entry
@Component
struct PasswordExample2 {
  @State password: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码',
        hint: '密码长度为8-20个字符'
      })
      
      PasswordInput({
        value: $password,
        placeholder: '请确认密码',
        label: '确认密码',
        errorMessage: '两次输入的密码不一致'
      })
    }
    .width('100%')
    .padding(20)
  }
}

3. 密码强度显示

@Entry
@Component
struct PasswordExample3 {
  @State password: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码',
        showStrength: true,
        hint: '密码应包含大小写字母、数字和特殊字符'
      })
    }
    .width('100%')
    .padding(20)
  }
}

4. 不同尺寸

@Entry
@Component
struct PasswordExample4 {
  @State password1: string = ''
  @State password2: string = ''
  @State password3: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password1,
        placeholder: '小尺寸',
        inputSize: 'small'
      })
      
      PasswordInput({
        value: $password2,
        placeholder: '中等尺寸（默认）',
        inputSize: 'medium'
      })
      
      PasswordInput({
        value: $password3,
        placeholder: '大尺寸',
        inputSize: 'large'
      })
    }
    .width('100%')
    .padding(20)
  }
}

5. 必填和状态

@Entry
@Component
struct PasswordExample5 {
  @State password1: string = ''
  @State password2: string = '已设置密码'
  @State password3: string = '只读密码'

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password1,
        placeholder: '请输入密码',
        label: '密码',
        required: true
      })
      
      PasswordInput({
        value: $password2,
        placeholder: '请输入密码',
        label: '禁用状态',
        disabled: true
      })
      
      PasswordInput({
        value: $password3,
        placeholder: '请输入密码',
        label: '只读状态',
        readonly: true
      })
    }
    .width('100%')
    .padding(20)
  }
}

6. 隐藏切换按钮

@Entry
@Component
struct PasswordExample6 {
  @State password: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password,
        placeholder: '显示切换按钮（默认）',
        label: '密码',
        showToggleButton: true
      })
      
      PasswordInput({
        value: $password,
        placeholder: '隐藏切换按钮',
        label: '密码',
        showToggleButton: false
      })
    }
    .width('100%')
    .padding(20)
  }
}

7. 最大长度限制

@Entry
@Component
struct PasswordExample7 {
  @State password: string = ''

  build() {
    Column({ space: 15 }) {
      PasswordInput({
        value: $password,
        placeholder: '最多输入20个字符',
        label: '密码',
        maxLength: 20,
        hint: `已输入 ${this.password.length}/20 个字符`
      })
    }
    .width('100%')
    .padding(20)
  }
}

8. 登录表单示例

@Entry
@Component
struct LoginForm {
  @State username: string = ''
  @State password: string = ''

  build() {
    Column({ space: 20 }) {
      Text('用户登录')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      
      TextInput({
        value: $username,
        placeholder: '请输入用户名',
        label: '用户名',
        required: true
      })
      
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码',
        required: true
      })
      
      Button('登录')
        .width('100%')
        .height(44)
        .onClick(() => {
          // 处理登录逻辑
        })
    }
    .width('100%')
    .padding(30)
  }
}

9. 注册表单示例

@Entry
@Component
struct RegisterForm {
  @State username: string = ''
  @State password: string = ''
  @State confirmPassword: string = ''

  build() {
    Column({ space: 20 }) {
      Text('用户注册')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      
      TextInput({
        value: $username,
        placeholder: '请输入用户名',
        label: '用户名',
        required: true
      })
      
      PasswordInput({
        value: $password,
        placeholder: '请输入密码',
        label: '密码',
        required: true,
        showStrength: true,
        hint: '密码应包含大小写字母、数字和特殊字符'
      })
      
      PasswordInput({
        value: $confirmPassword,
        placeholder: '请确认密码',
        label: '确认密码',
        required: true,
        errorMessage: this.password !== this.confirmPassword && this.confirmPassword ? '两次输入的密码不一致' : ''
      })
      
      Button('注册')
        .width('100%')
        .height(44)
        .onClick(() => {
          // 处理注册逻辑
        })
    }
    .width('100%')
    .padding(30)
  }
}

主题配置

PasswordInput 的所有样式都通过 ComponentTheme 配置，所有配置都在代码中，不依赖JSON文件。

修改默认颜色

import { ComponentTheme } from '../theme/ComponentTheme'

// 修改主色（影响聚焦状态的边框颜色）
ComponentTheme.PRIMARY_COLOR = '#007AFF'

// 修改错误色（影响错误状态的边框和提示颜色）
ComponentTheme.ERROR_COLOR = '#FF3B30'

// 修改边框颜色
ComponentTheme.BORDER_COLOR = '#E5E5E5'

// 修改圆角
ComponentTheme.BORDER_RADIUS = 8

批量配置

import { ComponentTheme } from '../theme/ComponentTheme'

// 使用 setTheme 方法批量配置
ComponentTheme.setTheme({
  primaryColor: '#007AFF',
  errorColor: '#FF3B30',
  borderRadius: 8,
  spacing: 16
})

最佳实践

1. 尺寸选择

2. 密码强度显示

注册场景：建议开启 showStrength，帮助用户创建安全密码
登录场景：可以关闭 showStrength，简化界面
密码修改：建议开启 showStrength，确保新密码安全

3. 显示/隐藏切换

默认开启：showToggleButton: true，方便用户确认输入
安全场景：可以关闭切换按钮，提高安全性
公共环境：建议关闭切换按钮，防止密码泄露

4. 验证规则

长度验证：使用 maxLength 限制最大长度
格式验证：通过 errorMessage 显示验证错误
强度验证：结合 showStrength 提示用户密码强度

5. 用户体验

实时反馈：密码强度实时更新，给用户即时反馈
清晰提示：使用 hint 提供密码要求说明
错误提示：使用 errorMessage 显示明确的错误信息

常见问题

Q1: 如何自定义密码强度计算规则？

A: 当前密码强度计算规则是内置的，基于以下因素：

密码长度（≥8个字符）
包含小写字母
包含大写字母
包含数字
包含特殊字符

如果需要自定义规则，可以在外部监听 value 变化，自行计算强度并显示。

Q2: 如何禁用显示/隐藏切换功能？

A: 设置 showToggleButton: false：

PasswordInput({
  value: $password,
  showToggleButton: false
})

Q3: 如何隐藏密码强度显示？

A: 设置 showStrength: false（默认值）：

PasswordInput({
  value: $password,
  showStrength: false
})

Q4: 密码强度如何计算？

A: 密码强度根据以下规则计算：

弱：满足1-2个条件
中：满足3-4个条件
强：满足5个条件

条件包括：长度≥8、小写字母、大写字母、数字、特殊字符。

Q5: 如何设置输入框宽度？

A: 使用 inputWidth 属性：

PasswordInput({
  value: $password,
  inputWidth: 300  // 固定宽度
})

PasswordInput({
  value: $password,
  inputWidth: '100%'  // 百分比宽度
})

Q6: 如何实现密码确认验证？

A: 通过监听两个密码输入框的值进行比较：

@State password: string = ''
@State confirmPassword: string = ''

PasswordInput({
  value: $password,
  label: '密码'
})

PasswordInput({
  value: $confirmPassword,
  label: '确认密码',
  errorMessage: this.password !== this.confirmPassword && this.confirmPassword ? '两次输入的密码不一致' : ''
})

总结

PasswordInput 是控件库中专用于密码输入的组件，具有以下核心特性：

安全优先：默认隐藏密码，支持一键切换显示/隐藏
强度提示：实时显示密码强度，帮助用户创建安全密码
功能完整：支持验证、提示、多种尺寸和状态
易于使用：简单的 API，开箱即用
主题配置：所有样式都可通过代码配置
品牌标识：自动包含品牌标识，保持视觉统一

关键要点

✅ 使用 $variableName 创建双向绑定
✅ 使用 showStrength 显示密码强度
✅ 使用 showToggleButton 控制显示/隐藏按钮
✅ 使用 label 属性添加标签
✅ 使用 hint 或 errorMessage 显示提示
✅ 使用 inputSize 属性选择合适尺寸
✅ 通过 ComponentTheme 自定义全局样式

适用场景

用户登录
用户注册
密码修改
安全验证

下一篇预告：NumberInput（数字输入框）详解

本文档属于《鸿蒙PC UI控件库开发系列文章》第8篇

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2025-12-16，如有侵权请联系 cloudcommunity@tencent.com 删除

安全

string

配置