#夏日挑战赛# 3.6 TextInput组件和TextArea组件 原创 精华

[ 本文正在参加星光计划3.0–夏日挑战赛 ]本节讲解ArkUI eTS文本输入组件TextInput和TextArea的基本用法，分别对应单行文本输入场景和多行文本输入场景。最后，针对TextInput组件UI外观无法定制的弊端，演示HUI文本输入增强组件Input的运行效果。

3.6.1 TextInput组件

新建TextInputSample.ets页面。TextInput组件的接口、属性和事件说明如下：

/**
 * 3.6.1 TextInput组件
 * 单行文本输入组件。
 *
 * 接口:
 *  TextInput(value?: { placeholder?: string })
 *    placeholder: 无输入时的提示文本。
 *
 * 属性:
 *  .type(InputType) 默认值InputType.Normal，设置输入框类型。
 *    InputType.Normal 基本输入模式。
 *    InputType.Password 密码输入模式。
 *    InputType.Email e-mail地址输入模式。
 *    InputType.Number 纯数字输入模式。
 *  .placeholderColor(Color) 设置placeholder颜色。
 *  .placeholderFont({
      size?: number,
      weight?:number | FontWeight,
      family?: string,
      style?: FontStyle
    }) 设置placeholder文本样式。
 *  .enterKeyType(EnterKeyType) 默认值EnterKeyType.Done，设置输入法回车键类型。
 *    EnterKeyType.Go 显示Go文本。
 *    EnterKeyType.Search 显示为搜索样式。
 *    EnterKeyType.Send 显示为发送样式。
 *    EnterKeyType.Next 显示为下一个样式。
 *    EnterKeyType.Done 标准样式。
 *  .caretColor(Color) 设置输入框光标颜色。
 *  .maxLength(number) 设置文本的最大输入字符数。
 *
 * 事件：
 *  .onChange(value: string) => void 输入发生变化时，触发回调。
 *  .onSubmit(callback: (enterKey: EnterKeyType) => void) 回车键或者软键盘回车键触发该回调，参数为当前软键盘回车键类型。
 *  .onEditChanged(callback: (isEditing: boolean) => void) 输入状态变化时，触发回调。
 */

其中：

接口参数placeholder是可选的，为了对用户更友好，建议设置。同时，建议使用文字资源，适应多语言显示。

属性placeholderColor建议使用颜色资源$r(“app.color.fgLevel1”)，适应深色模式/浅色模式切换时的完美表现。

属性type、placeholderFont、enterKeyType和caretColor视需求而定，如果省略这几个属性也能满足需要，可以节省代码。

事件中onChange是最实用的，监测文本变化后可将值记录下来用于表单提交。其它两个事件通常可以省略。

调用示范代码如下：

      TextInput({ placeholder: $r("app.string.hint") })  // 无输入时的提示文本(可选)。
        .type(InputType.Normal)  // 输入框类型
        .placeholderColor($r("app.color.fgLevel1")) // 设置placeholder颜色
        .placeholderFont({ size: 20, weight: FontWeight.Normal, family: "sans-serif", style: FontStyle.Normal }) // 设置placeholder文本样式
        .enterKeyType(EnterKeyType.Next) // 设置输入法回车键类型
        .caretColor($r("app.color.info"))  // 设置输入框光标颜色
        .maxLength(20)  // 设置文本的最大输入字符数
        .onChange((value: string) => {
          console.log(value) // 输入发生变化时，触发回调
        })
        .onSubmit((enterKey) => {
          // 回车键或者软键盘回车键触发该回调
        })
        .onEditChanged((isEditing) => {
          // 输入状态变化时，触发回调
        })

在浅色模式和深色模式下运行效果，如下图所示：

本地预览器无法调出手机键盘，可在远程模拟器体验效果：

从上面的效果表现，我们发现TextInput组件已经是一个多态组件了：

TextInput组件的背景色可以自动适配深色模式和浅色模式；

组件的宽度默认撑开为100%，可以适配手机横竖屏和平板设备；

组件的外边框已设置为胶囊型边框外观，和胶囊行按钮类似。

3.6.2 TextArea组件

多行文本组件TextArea的接口、属性和方法与TextInput类似，说明如下：

/**
 * 3.6.2 TextArea组件
 * 多行文本输入组件。
 *
 * 接口:
 *  TextArea(value?: { placeholder?: string })
 *    placeholder: string 无输入时的提示文本。
 *
 * 属性:
 *  .placeholderColor(Color) 设置placeholder文本颜色。
 *  .placeholderFont({
      size?: number,
      weight?:number | FontWeight,
      family?: string,
      style?: FontStyle
    }) 设置placeholder文本样式。
    .caretColor(Color) 设置输入框光标颜色。
 *  .textAlign(TextAlign) 默认值TextAlign.Start，设置文本水平对齐方式。
 *    TextAlign.Center 水平居中对齐。
 *    TextAlign.Start 水平对齐首部。
 *    TextAlign.End 水平对齐尾部。
 *
 * 事件：
 *  .onChange(callback: (value: string) => void) 输入发生变化时，触发回调。
 */

相对TextInput组件，增加了一个设置文本水平对齐的属性.textAlign(TextAlign)。通常，我们会设置多行文本组件的高度属性和文本颜色属性。示范代码如下：

      TextArea({ placeholder: $r("app.string.hint") })  // 无输入时的提示文本(可选)。
        .placeholderColor($r("app.color.fgLevel2"))   // 设置placeholder颜色
        .placeholderFont({ size: 20, weight: FontWeight.Normal, family: "sans-serif", style: FontStyle.Normal }) // 设置placeholder文本样式
        .textAlign(TextAlign.Center)  // 设置文本水平对齐方式
        .caretColor($r("app.color.info"))  // 设置输入框光标颜色
        .height(100) // 多行文本框的高度
        .fontColor($r("app.color.fgLevel1")) // 输入文本颜色适配深色模式和浅色模式
        .onChange((value: string) => { // 输入发生变化时，触发回调
          console.log(value)
        })

在竖屏手机浅色模式和平板横屏深色模式下，效果如下：

可以看出，多行文本组件TextArea也是一个多态组件。

3.6.3 HUI文本输入增强组件Input

TextInput组件是一个已经被鸿蒙官方封装的多态组件，它的外观固定为胶囊型风格。如果希望文本输入组件是无边框效果呢？这个时候你会发现，即使你设置边框的属性，也没办法达成你想要的效果。在后面《第9章 为ArkUI量身打造的多态组件库HUI》中，我会发布一款文本输入增强组件，命名采用Html中通用的名称Input。Input组件从外观定制灵活性和功能性方面全面增强目前TextInput组件的不足。在远程模拟器上运行效果如下：