1. 插件介绍

keyboard_actions 是一个功能强大的 Flutter 插件，允许开发者在键盘上方添加自定义操作栏，以增强用户的输入体验。该插件基于 keyboard_actions 开发，并针对鸿蒙 OS 进行了适配。

主要功能特性：

• ✅ 在键盘上方添加自定义操作栏
• ✅ 支持导航箭头，方便在输入框间切换
• ✅ 自定义工具栏按钮和完成按钮
• ✅ 支持自定义键盘页脚（如数字键盘、颜色选择器等）
• ✅ 支持点击外部区域关闭键盘
• ✅ 支持在对话框中使用
• ✅ 完全适配鸿蒙 OS

2. 安装与配置

2.1 Git 依赖引入

在项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  keyboard_actions:
    git:
      url: https://gitcode.com/openharmony-sig/fluttertpc_keyboard_actions.git

2.2 安装依赖

执行以下命令安装依赖：

flutter pub get

3. API 调用与使用

3.1 基本使用流程

1. 导入包

import 'package:keyboard_actions/keyboard_actions.dart';

2. 创建 FocusNode

为每个需要自定义键盘操作的输入框创建 FocusNode：

final FocusNode _nodeText1 = FocusNode();
final FocusNode _nodeText2 = FocusNode();
final FocusNode _nodeText3 = FocusNode();

3. 配置 KeyboardActions

创建 KeyboardActionsConfig 配置对象：

KeyboardActionsConfig _buildConfig(BuildContext context) {
  return KeyboardActionsConfig(
    keyboardActionsPlatform: KeyboardActionsPlatform.OHOS, // 指定为鸿蒙平台
    keyboardBarColor: Colors.grey[200], // 操作栏背景色
    nextFocus: true, // 显示导航箭头
    actions: [
      // 为每个输入框配置操作
      KeyboardActionsItem(focusNode: _nodeText1),
      KeyboardActionsItem(focusNode: _nodeText2),
      KeyboardActionsItem(
        focusNode: _nodeText3,
        onTapAction: () { // 点击完成按钮的回调
          print('完成按钮被点击');
        },
      ),
    ],
  );
}

4. 包裹输入内容

使用 KeyboardActions 组件包裹输入内容：

@override
Widget build(BuildContext context) {
  return KeyboardActions(
    config: _buildConfig(context),
    child: Container(
      padding: const EdgeInsets.all(15.0),
      child: Column(
        children: <Widget>[
          TextField(
            focusNode: _nodeText1,
            decoration: InputDecoration(hintText: "普通输入框"),
          ),
          TextField(
            focusNode: _nodeText2,
            decoration: InputDecoration(hintText: "带导航的输入框"),
          ),
          TextField(
            focusNode: _nodeText3,
            decoration: InputDecoration(hintText: "带回调的输入框"),
          ),
        ],
      ),
    ),
  );
}

3.2 高级用法

3.2.1 自定义工具栏按钮

KeyboardActionsItem(
  focusNode: _nodeText,
  toolbarButtons: [
    (node) {
      return GestureDetector(
        onTap: () {
          print('自定义按钮被点击');
          node.unfocus();
        },
        child: Padding(
          padding: EdgeInsets.all(8.0),
          child: Icon(Icons.close),
        ),
      );
    },
  ],
),

3.2.2 自定义键盘页脚

KeyboardActionsItem(
  focusNode: _nodeText,
  footerBuilder: (_) => PreferredSize(
      child: SizedBox(
          height: 40,
          child: Center(
            child: Text('自定义页脚'),
          )),
      preferredSize: Size.fromHeight(40)),
),

3.2.3 在对话框中使用

KeyboardActions(
  isDialog: true, // 设置为 true 以在对话框中使用
  config: _buildConfig(context),
  child: // 对话框内容
),

3.2.4 点击外部区域关闭键盘

KeyboardActions(
  tapOutsideBehavior: TapOutsideBehavior.opaqueDismiss, // 点击外部区域关闭键盘
  config: _buildConfig(context),
  child: // 内容
),

3.3 核心 API 说明

KeyboardActions 组件

属性	类型	说明
child	Widget	需要自定义键盘操作的内容
config	KeyboardActionsConfig	键盘操作配置
autoScroll	bool	是否自动滚动到聚焦的输入框
enable	bool	是否启用键盘操作栏
isDialog	bool	是否在对话框中使用
tapOutsideBehavior	TapOutsideBehavior	点击外部区域的行为
overscroll	double	额外的滚动偏移量

KeyboardActionsConfig 配置

属性	类型	说明
keyboardActionsPlatform	KeyboardActionsPlatform	支持的平台（ALL/ANDROID/IOS/OHOS）
keyboardBarColor	Color	操作栏背景颜色
nextFocus	bool	是否显示导航箭头
actions	List	输入框的键盘操作列表
keyboardBarElevation	double	操作栏的阴影高度
keyboardSeparatorColor	Color	操作栏与键盘之间的分隔线颜色
defaultDoneWidget	Widget	自定义默认完成按钮

KeyboardActionsItem 配置

属性	类型	说明
focusNode	FocusNode	输入框的焦点对象
toolbarButtons	List	自定义工具栏按钮
onTapAction	VoidCallback	点击完成按钮的回调
enabled	bool	是否启用该输入框的交互
displayActionBar	bool	是否显示操作栏
displayArrows	bool	是否显示导航箭头
displayDoneButton	bool	是否显示默认完成按钮
footerBuilder	WidgetBuilder	自定义键盘页脚构建器

4. 兼容性与约束

4.1 已测试通过的版本

• Flutter: 3.7.12-ohos-1.1.3; SDK: 5.0.0(12); IDE: DevEco Studio: 5.1.0.828
• Flutter: 3.22.1-ohos-1.0.3; SDK: 5.0.0(12); IDE: DevEco Studio: 5.1.0.828

4.2 使用注意事项

1. 当使用 KeyboardActions 组件时，建议将 Scaffold.resizeToAvoidBottomInset 设置为 false，因为 KeyboardActions 会自行处理键盘遮挡问题。

2. 在对话框中使用时，需要将 KeyboardActions 的 isDialog 属性设置为 true。

3. 如果需要自定义键盘页脚，确保页脚的高度设置合理，以避免遮挡输入内容。

5. 示例代码

以下是一个完整的示例，展示了如何在鸿蒙应用中使用 keyboard_actions 包：

import 'package:flutter/material.dart';
import 'package:keyboard_actions/keyboard_actions.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Keyboard Actions Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: KeyboardActionsDemo(),
    );
  }
}

class KeyboardActionsDemo extends StatefulWidget {
  @override
  _KeyboardActionsDemoState createState() => _KeyboardActionsDemoState();
}

class _KeyboardActionsDemoState extends State<KeyboardActionsDemo> {
  // 创建 FocusNode
  final FocusNode _nodeText1 = FocusNode();
  final FocusNode _nodeText2 = FocusNode();
  final FocusNode _nodeText3 = FocusNode();

  // 构建键盘操作配置
  KeyboardActionsConfig _buildConfig(BuildContext context) {
    return KeyboardActionsConfig(
      keyboardActionsPlatform: KeyboardActionsPlatform.OHOS,
      keyboardBarColor: Colors.grey[200],
      nextFocus: true,
      actions: [
        KeyboardActionsItem(focusNode: _nodeText1),
        KeyboardActionsItem(
          focusNode: _nodeText2,
          toolbarButtons: [
            (node) {
              return GestureDetector(
                onTap: () {
                  print('关闭按钮被点击');
                  node.unfocus();
                },
                child: Padding(
                  padding: EdgeInsets.all(8.0),
                  child: Icon(Icons.close),
                ),
              );
            },
          ],
        ),
        KeyboardActionsItem(
          focusNode: _nodeText3,
          onTapAction: () async {
            await showDialog(
              context: context,
              builder: (context) {
                return AlertDialog(
                  content: Text('自定义完成按钮被点击'),
                  actions: [
                    TextButton(
                      child: Text('确定'),
                      onPressed: () => Navigator.of(context).pop(),
                    ),
                  ],
                );
              },
            );
          },
        ),
      ],
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Keyboard Actions Demo')),
      // 注意：设置为 false，由 KeyboardActions 处理键盘遮挡
      resizeToAvoidBottomInset: false,
      body: KeyboardActions(
        config: _buildConfig(context),
        tapOutsideBehavior: TapOutsideBehavior.opaqueDismiss,
        child: Padding(
          padding: EdgeInsets.all(16.0),
          child: Column(
            children: [
              TextField(
                focusNode: _nodeText1,
                keyboardType: TextInputType.text,
                decoration: InputDecoration(hintText: '普通文本输入'),
                style: TextStyle(fontSize: 18.0),
              ),
              SizedBox(height: 20.0),
              TextField(
                focusNode: _nodeText2,
                keyboardType: TextInputType.emailAddress,
                decoration: InputDecoration(hintText: '邮箱输入（带自定义按钮）'),
                style: TextStyle(fontSize: 18.0),
              ),
              SizedBox(height: 20.0),
              TextField(
                focusNode: _nodeText3,
                keyboardType: TextInputType.number,
                decoration: InputDecoration(hintText: '数字输入（带自定义回调）'),
                style: TextStyle(fontSize: 18.0),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

6. 总结

keyboard_actions 是一个功能丰富、易于使用的 Flutter 插件，为鸿蒙应用提供了强大的键盘操作自定义能力。通过这个插件，开发者可以轻松地为输入界面添加导航箭头、自定义按钮和键盘页脚，从而提升用户的输入体验。

该插件完全适配鸿蒙 OS，支持在各种场景下使用，包括全屏表单和对话框。通过简单的配置，开发者可以快速集成并实现复杂的键盘交互效果。

如果您想了解更多详细信息，可以查看项目的 示例代码，其中包含了各种使用场景的完整实现。

---

注意：本文档基于 keyboard_actions 包的自定义修改版本编写，该版本已针对鸿蒙 OS 进行了适配和优化。