ArkUI 软键盘：键盘一弹出，页面别乱跳

今天我们只看软键盘和输入组件的关系：什么时候弹、弹什么、怎么收。

软键盘很容易被写成一个完整聊天页、表单页或者支付页。那样当然真实，但主题会散。这个 Demo 只保留三个最基础的点：系统键盘、不自动弹键盘、自定义键盘。

系统键盘

最普通的输入框，获取焦点就弹系统键盘：

TextInput({ placeholder: '获取焦点时弹出系统键盘' })
  .enterKeyType(EnterKeyType.Done)
  .enableKeyboardOnFocus(true)

enterKeyType 控制键盘右下角按钮的语义。这里用 Done，读者一眼就知道“输入完了”。

不自动弹键盘

有些输入框只是临时聚焦，不希望马上拉起键盘：

TextInput({ placeholder: '只聚焦，不主动拉起键盘' })
  .enableKeyboardOnFocus(false)

这个能力适合特殊交互，比如扫码填入、外部设备输入，或者你准备接自定义键盘。

自定义键盘

案例里做了一个很小的数字键盘：

TextInput({ text: this.pinCode, placeholder: '点这里输入 1、2、3', controller: this.inputController })
  .customKeyboard(this.numberKeyboard)

自定义键盘按钮里直接改 pinCode，完成按钮调用：

this.inputController.stopEditing()

这一步的重点不是做一个完整密码键盘，而是记住收起编辑态可以交给控制器。后面你要做支付密码、筛选器输入、金额键盘，都可以沿着这个方向扩展。

你做输入页时，最烦的是键盘遮住按钮，还是键盘类型不对？这个问题很具体，下一篇如果继续写键盘，我会优先挑最容易踩的那个方向。

完整代码

@Entry
@Component
struct ArkUIKeyboardDemo {
  private inputController: TextInputController = new TextInputController();
  @State pinCode: string = '';

  @Builder
  sectionTitle(title: string) {
    Text(title)
      .width('100%')
      .fontSize(15)
      .fontWeight(700)
      .fontColor('#334155')
  }

  @Builder
  numberKeyboard() {
    Column({ space: 10 }) {
      Text('自定义数字键盘')
        .width('100%')
        .fontSize(14)
        .fontWeight(700)
        .fontColor('#334155')

      Row({ space: 8 }) {
        ForEach(['1', '2', '3'], (item: string) => {
          Button(item)
            .width(64)
            .height(42)
            .backgroundColor('#DBEAFE')
            .fontColor('#2563EB')
            .onClick(() => {
              this.pinCode += item
            })
        }, (item: string) => item)
      }

      Row({ space: 8 }) {
        Button('清空')
          .width(88)
          .height(40)
          .backgroundColor('#F1F5F9')
          .fontColor('#475569')
          .onClick(() => {
            this.pinCode = ''
          })

        Button('完成')
          .width(88)
          .height(40)
          .backgroundColor('#2563EB')
          .fontColor('#FFFFFF')
          .onClick(() => {
            this.inputController.stopEditing()
          })
      }
    }
    .width('100%')
    .height(170)
    .padding(16)
    .backgroundColor('#FFFFFF')
  }

  build() {
    Scroll() {
      Column({ space: 18 }) {
        Text('ArkUI 软键盘')
          .width('100%')
          .fontSize(24)
          .fontWeight(700)
          .fontColor('#0F172A')

        Text('键盘一弹出，页面别乱跳')
          .width('100%')
          .fontSize(22)
          .fontWeight(700)
          .fontColor('#111827')

        Text('这篇只看输入组件和软键盘的关系：什么时候弹、弹什么、怎么收。')
          .width('100%')
          .fontSize(14)
          .fontColor('#64748B')
          .lineHeight(22)

        Column({ space: 12 }) {
          this.sectionTitle('系统键盘')

          TextInput({ placeholder: '获取焦点时弹出系统键盘' })
            .width('100%')
            .height(48)
            .fontSize(15)
            .enterKeyType(EnterKeyType.Done)
            .enableKeyboardOnFocus(true)
            .backgroundColor('#FFFFFF')
            .border({ width: 1, color: '#CBD5E1' })
            .borderRadius(8)
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#F8FAFC')
        .borderRadius(8)

        Column({ space: 12 }) {
          this.sectionTitle('不自动弹键盘')

          TextInput({ placeholder: '只聚焦，不主动拉起键盘' })
            .width('100%')
            .height(48)
            .fontSize(15)
            .enableKeyboardOnFocus(false)
            .backgroundColor('#FFFFFF')
            .border({ width: 1, color: '#CBD5E1' })
            .borderRadius(8)
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#EFF6FF')
        .borderRadius(8)

        Column({ space: 12 }) {
          this.sectionTitle('自定义键盘')

          TextInput({ text: this.pinCode, placeholder: '点这里输入 1、2、3', controller: this.inputController })
            .width('100%')
            .height(48)
            .fontSize(15)
            .backgroundColor('#FFFFFF')
            .border({ width: 1, color: '#CBD5E1' })
            .borderRadius(8)
            .customKeyboard(this.numberKeyboard)

          Text('自定义键盘不会拿焦点，完成按钮调用 stopEditing() 收起键盘。')
            .width('100%')
            .fontSize(13)
            .fontColor('#64748B')
            .lineHeight(21)
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#F0FDFA')
        .borderRadius(8)
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
  }
}