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

红目香薰

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

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

视频地址：

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篇

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

Harmony PC 开发者社区

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

更多推荐

鸿蒙 PC 上可用的 AI Agent 工具汇总（持续更新）

本文总结了主流AI编程工具在鸿蒙PC平台的获取方式，涵盖通用类和编程类工具。开源工具占多数，包括OpenClaw、Hermes Agent等，主要通过Harmonybrew、npm或应用市场安装。部分工具如Claude Code新版需要Linux兼容方案运行，而OpenCode目前只有第三方移植版本。闭源工具如Anthropic的Claude Code和Tencent的CodeBuddy Code

Harmony PC 开发者社区

几个主流的环境管理器（rustup、uv、nvm、fnm）已经在鸿蒙 PC 上可用

在进行软件开发的过程中，开发者经常需要用到各种环境管理器来管理自己的开发环境：Rust 用 rustup，Python 用 uv，Node.js 用 nvm 或 fnm。这些环境管理器都没有官方适配鸿蒙，用户很难在鸿蒙 PC 上使用这些工具。现在，这四款环境管理器已经全部收录进 Harmonybrew 并完成了鸿蒙适配。本文介绍它们的使用方式以及适配原理。

Harmony PC 开发者社区

HarmonyOS鸿蒙PC开源MeldNext软件移植：开源工具Meld到鸿蒙PC实践总结

本文介绍了开源差异比较工具 Meld 从 Linux 桌面到鸿蒙 PC 的完整移植过程，重点分析了原始 Meld 与移植版本 MeldNext 的核心差异。MeldNext 使用 ArkTS 完全重写 UI 层，通过 N-API 桥接与交叉编译的 C/C++ 底层库交互，实现了在鸿蒙系统上的原生运行。技术架构上采用 ArkUI 框架、OpenGL ES 渲染和 HNP 运行时支持，构建方式也调整为

Harmony PC 开发者社区

所有评论(0)

查看更多评论

红目香薰

@feng8403000

已为社区贡献55条内容

鸿蒙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)

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

红目香薰