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

PasswordInput 是专为密码输入场景设计的组件，基于 TextInput 扩展，具有显示/隐藏切换、密码强度显示、验证等功能。核心特性包括安全优先设计、强度提示、多种尺寸和状态支持，左下角自动包含品牌标识。提供完整的 API 支持，如双向绑定、标签/提示文本、错误状态等，适用于登录、注册等场景。组件支持三种尺寸规格，所有样式均可通过代码配置，并附带详细的使用示例和最佳实践指导。

红目香薰

981人浏览 · 2025-12-13 22:54:18

红目香薰 · 2025-12-13 22:54:18 发布

视频地址：

https://www.bilibili.com/video/BV1jomdBBE4H/
在这里插入图片描述

概述

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篇

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

Harmony PC 开发者社区

赋能鸿蒙PC开发者，共建全场景原生生态，共享一次开发多端部署创新价值。

更多推荐

鸿蒙 PC 底层开发技术详解（二）：OpenHarmony、HarmonyOS 与 GNU/Linux 的关系

OpenHarmony：非 GNU 系的 Linux 发行版；HarmonyOS：OpenHarmony 的商业发行版。

Harmony PC 开发者社区

鸿蒙 PC 底层开发技术详解（五）：应用沙箱环境和非应用沙箱环境的区别

本文分析了鸿蒙系统（HarmonyOS/OpenHarmony）的应用沙箱机制及其对终端操作的影响。系统通过类似Docker容器的沙箱隔离每个应用，HiShell终端运行在这种受限环境中，导致诸多限制：挂载点隔离、DAC机制差异、SELinux管控和seccomp过滤等，使得常规UNIX命令和调试工具无法正常工作。相比之下，通过hdc shell接入的调试终端虽能脱离沙箱限制，但仍受权限约束，仅在

Harmony PC 开发者社区

鸿蒙 PC 底层开发技术详解（四）：代码签名机制对我们的影响

在鸿蒙 PC 的 HiShell 环境中运行二进制文件时，系统会强制校验该文件及其加载的所有 `.so` 库的代码签名。若签名无效，系统将拦截运行并报错 `permission denied`。

Harmony PC 开发者社区

所有评论(0)

查看更多评论

红目香薰

@feng8403000

已为社区贡献19条内容

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

红目香薰

视频地址：

📋 目录

概述

设计理念

适用场景

特性

✨ 核心特性

🎨 视觉特点

快速开始

基础用法

关于双向绑定

API 参考

Props

PasswordStrength 枚举

尺寸规格

使用示例

1. 基础密码输入框

2. 带标签和提示

3. 密码强度显示

4. 不同尺寸

5. 必填和状态

6. 隐藏切换按钮

7. 最大长度限制

8. 登录表单示例

9. 注册表单示例

主题配置

修改默认颜色

批量配置

最佳实践

1. 尺寸选择

2. 密码强度显示

3. 显示/隐藏切换

4. 验证规则

5. 用户体验

常见问题

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

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

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

Q4: 密码强度如何计算？

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

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

总结

关键要点

适用场景

所有评论(0)

温馨提示：您尚未绑定手机号

红目香薰