鸿蒙PC UI控件库 - TextInput 文本输入框详解

红目香薰

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

1300

文章被收录于专栏：CSDNToQQCodeCSDNToQQCode

视频地址：

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

📋 目录

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

概述

TextInput 是控件库中的基础文本输入框组件，支持验证、提示、图标、多种尺寸和状态，适用于表单输入、搜索、数据录入等场景。

设计理念

文本输入框采用清晰易用设计，具有以下特点：

功能完整：支持多种输入类型、验证、提示等
状态清晰：正常、聚焦、错误、禁用、只读等状态明确
尺寸多样：支持 small、medium、large 三种尺寸
图标支持：支持左侧和右侧图标（文字图标和图片图标）
品牌标识：左下角自动包含品牌标识（圆圈红字"PC"）
主题统一：所有样式配置都在代码中，方便定制

适用场景

表单输入：用户名、邮箱、密码等表单字段
搜索功能：搜索框、筛选输入
数据录入：各种文本数据输入
验证输入：需要验证的输入场景

特性

✨ 核心特性

✅ 多种输入类型：支持 text、email、number、password、tel、url
✅ 标签和提示：支持标签、提示文本、错误提示
✅ 图标支持：支持左侧和右侧图标（文字图标和图片图标）
✅ 清除按钮：支持显示清除按钮
✅ 多种尺寸：支持 small、medium、large 三种尺寸
✅ 状态管理：支持禁用、只读、必填等状态
✅ 长度限制：支持最大长度限制
✅ 验证功能：支持自定义验证函数
✅ 品牌标识：自动包含左下角品牌标识
✅ 主题配置：所有样式都可通过代码配置

🎨 视觉特点

正常状态：白色背景 + 灰色边框
聚焦状态：主色边框高亮
错误状态：红色边框 + 红色错误提示
禁用状态：灰色背景 + 灰色文字 + 灰色边框
只读状态：正常样式但不可编辑

快速开始

基础用法

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

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

  build() {
    Column({ space: 20 }) {
      // 基础输入框
      TextInput({
        value: $inputValue,
        placeholder: '请输入内容'
      })
      
      // 带标签的输入框
      TextInput({
        value: $inputValue,
        placeholder: '请输入用户名',
        label: '用户名'
      })
      
      // 带提示的输入框
      TextInput({
        value: $inputValue,
        placeholder: '请输入邮箱',
        label: '邮箱',
        hint: '请输入有效的邮箱地址'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

关于双向绑定

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

@State inputValue: string = ''

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

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	最大长度
type	'text' \| 'email' \| 'number' \| 'password' \| 'tel' \| 'url'	'text'	输入类型
leftIcon	ResourceStr?	undefined	左侧图片图标（可选）
leftTextIcon	string?	undefined	左侧文字图标（可选，优先级高于 leftIcon）
rightIcon	ResourceStr?	undefined	右侧图片图标（可选）
rightTextIcon	string?	undefined	右侧文字图标（可选，优先级高于 rightIcon）
showClearButton	boolean	true	是否显示清除按钮
showBrand	boolean	true	是否显示品牌标识
inputWidth	string \| number?	undefined	输入框宽度
validator	@BuilderParam (value: string) => ValidationResult?	undefined	验证函数（可选）
onChangeBuilder	@BuilderParam (value: string) => void?	undefined	值变化回调（可选）

ValidationResult 接口

属性名	类型	说明
valid	boolean	验证是否通过
message	string?	验证消息（可选）

尺寸规格

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

使用示例

1. 基础输入框

@Entry
@Component
struct InputExample1 {
  @State inputValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $inputValue,
        placeholder: '请输入内容'
      })
      
      Text(`当前值：${this.inputValue || '(空)'}`)
        .fontSize(14)
        .fontColor('#666666')
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

2. 不同尺寸

@Entry
@Component
struct InputExample2 {
  @State inputValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $inputValue,
        placeholder: '小尺寸',
        inputSize: 'small'
      })
      
      TextInput({
        value: $inputValue,
        placeholder: '中等尺寸（默认）',
        inputSize: 'medium'
      })
      
      TextInput({
        value: $inputValue,
        placeholder: '大尺寸',
        inputSize: 'large'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

3. 不同输入类型

@Entry
@Component
struct InputExample3 {
  @State emailValue: string = ''
  @State passwordValue: string = ''
  @State phoneValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $emailValue,
        placeholder: '请输入邮箱',
        type: 'email',
        label: '邮箱地址'
      })
      
      TextInput({
        value: $passwordValue,
        placeholder: '请输入密码',
        type: 'password',
        label: '密码'
      })
      
      TextInput({
        value: $phoneValue,
        placeholder: '请输入手机号',
        type: 'tel',
        label: '手机号'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

4. 带标签和提示

@Entry
@Component
struct InputExample4 {
  @State usernameValue: string = ''
  @State contentValue: string = ''
  @State errorValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $usernameValue,
        placeholder: '请输入用户名',
        label: '用户名',
        hint: '用户名长度为3-20个字符'
      })
      
      TextInput({
        value: $contentValue,
        placeholder: '请输入内容',
        label: '内容',
        hint: '这是提示信息'
      })
      
      TextInput({
        value: $errorValue,
        placeholder: '请输入内容',
        label: '内容',
        errorMessage: '输入内容有误，请重新输入'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

5. 必填和状态

@Entry
@Component
struct InputExample5 {
  @State requiredValue: string = ''
  @State disabledValue: string = '禁用状态'
  @State readonlyValue: string = '只读状态'

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $requiredValue,
        placeholder: '请输入内容',
        label: '必填项',
        required: true
      })
      
      TextInput({
        value: $disabledValue,
        placeholder: '请输入内容',
        label: '禁用状态',
        disabled: true
      })
      
      TextInput({
        value: $readonlyValue,
        placeholder: '请输入内容',
        label: '只读状态',
        readonly: true
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

6. 带图标

@Entry
@Component
struct InputExample6 {
  @State usernameValue: string = ''
  @State emailValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $usernameValue,
        placeholder: '请输入用户名',
        leftTextIcon: 'U',  // U = User（用户）
        label: '用户名'
      })
      
      TextInput({
        value: $emailValue,
        placeholder: '请输入邮箱',
        leftTextIcon: '@',
        rightTextIcon: '✓',  // ✓ = Check（确认）
        label: '邮箱'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

7. 最大长度限制

@Entry
@Component
struct InputExample7 {
  @State inputValue: string = ''

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $inputValue,
        placeholder: '最多输入10个字符',
        label: '内容',
        maxLength: 10,
        hint: `已输入 ${this.inputValue.length}/10 个字符`
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

8. 自定义验证

import { TextInput, ValidationResult } from '../components/base'

@Entry
@Component
struct InputExample8 {
  @State emailValue: string = ''

  // 邮箱验证函数
  @Builder
  validateEmail(value: string): ValidationResult {
    if (!value) {
      return { valid: false, message: '邮箱不能为空' }
    }
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    if (!emailRegex.test(value)) {
      return { valid: false, message: '请输入有效的邮箱地址' }
    }
    return { valid: true }
  }

  build() {
    Column({ space: 15 }) {
      TextInput({
        value: $emailValue,
        placeholder: '请输入邮箱',
        label: '邮箱',
        validator: this.validateEmail
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

主题配置

TextInput 的所有样式都通过 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. 标签和提示

标签：用于说明输入框的用途
提示文本：提供输入指导或格式要求
错误提示：显示验证错误信息
必填标识：使用 required 属性显示红色星号

3. 输入类型

text：普通文本输入（默认）
email：邮箱输入，会触发邮箱键盘
password：密码输入，自动隐藏输入内容
number：数字输入，会触发数字键盘
tel：电话号码输入
url：URL 输入

4. 图标使用

左侧图标：用于标识输入类型（如用户图标、邮箱图标）
右侧图标：用于显示状态（如成功图标、错误图标）
清除按钮：自动显示在有内容时，方便快速清除

5. 验证功能

使用 validator 属性进行自定义验证
验证函数返回 ValidationResult 对象
验证失败时显示错误提示
可以结合 errorMessage 属性显示错误信息

6. 状态管理

禁用状态：使用 disabled 属性，适用于不可编辑的场景
只读状态：使用 readonly 属性，适用于仅展示的场景
必填状态：使用 required 属性，显示红色星号标识

7. 响应式设计

使用 inputWidth 属性控制输入框宽度
在小屏幕上考虑使用 smaller 尺寸
保持输入框之间的合理间距

常见问题

Q1: TextInput 和其他输入框有什么区别？

A: TextInput 是基础文本输入框，与其他输入框的区别：

TextInput：基础文本输入框，支持多种输入类型
PasswordInput：专门的密码输入框，支持显示/隐藏切换
NumberInput：数字输入框，支持步进器和范围限制
SearchInput：搜索输入框，支持清除按钮和历史记录
TextArea：多行文本输入框，支持字数统计

Q2: 如何实现双向绑定？

A: 使用 @Link 和 $ 语法：

@State inputValue: string = ''

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

Q3: 如何自定义验证？

A: 使用 validator 属性：

@Builder
validateEmail(value: string): ValidationResult {
  if (!value) {
    return { valid: false, message: '邮箱不能为空' }
  }
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
  if (!emailRegex.test(value)) {
    return { valid: false, message: '请输入有效的邮箱地址' }
  }
  return { valid: true }
}

TextInput({
  value: $emailValue,
  validator: this.validateEmail
})

Q4: 如何禁用清除按钮？

A: 设置 showClearButton 为 false：

TextInput({
  value: $inputValue,
  showClearButton: false
})

Q5: 如何控制输入框宽度？

A: 使用 inputWidth 属性：

TextInput({
  value: $inputValue,
  inputWidth: 300  // 固定宽度
})

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

Q6: 如何监听输入变化？

A: 使用 onChangeBuilder 属性：

@Builder
handleChange(value: string) {
  console.info('输入值变化：', value)
  // 处理输入变化
}

TextInput({
  value: $inputValue,
  onChangeBuilder: this.handleChange
})

总结

TextInput 是控件库中的基础文本输入框组件，具有以下核心特性：

功能完整：支持多种输入类型、验证、提示等
状态清晰：正常、聚焦、错误、禁用、只读等状态明确
尺寸多样：三种尺寸满足不同场景需求
图标支持：支持左侧和右侧图标
易于使用：简单的 API，开箱即用
主题配置：所有样式都可通过代码配置
品牌标识：自动包含品牌标识，保持视觉统一

关键要点

✅ 使用 $variableName 创建双向绑定
✅ 使用 label 属性添加标签
✅ 使用 hint 或 errorMessage 显示提示
✅ 使用 type 属性选择输入类型
✅ 使用 validator 属性进行自定义验证
✅ 使用 inputSize 属性选择合适尺寸
✅ 通过 ComponentTheme 自定义全局样式

适用场景

表单输入
搜索功能
数据录入
验证输入

下一篇预告：PasswordInput（密码输入框）详解

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

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

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

基础

配置

搜索

textinput

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度