1. 插件介绍

flutter_keyboard_visibility 是一个用于检测键盘可见性变化的 Flutter 插件，它提供了多种方式来监听和响应键盘状态的变化。该插件支持在鸿蒙系统上使用，帮助开发者轻松处理键盘显示和隐藏时的 UI 适配问题。

主要功能

• 实时键盘可见性检测：准确获取当前键盘的显示状态
• 多种监听方式：提供 Widget 树内监听和直接订阅两种方式
• 键盘隐藏功能：支持点击屏幕任意位置隐藏键盘
• 跨平台兼容：在鸿蒙系统上与其他平台（iOS/Android）保持一致的 API 接口

适用场景

• 登录/注册页面：根据键盘显示状态调整按钮位置
• 聊天界面：键盘显示时自动滚动到底部
• 表单填写：优化输入体验，避免键盘遮挡输入框
• 任何需要根据键盘状态调整 UI 的场景

2. 插件安装

由于这是一个自定义修改版本，需要以 git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  flutter_keyboard_visibility:
    git:
      url: "https://atomgit.com/openharmony-sig/flutter_keyboard_visibility.git"
      path: "flutter_keyboard_visibility"

然后执行以下命令安装依赖：

flutter pub get

3. API 使用指南

3.1 导入包

在需要使用的文件中导入包：

import 'package:flutter_keyboard_visibility/flutter_keyboard_visibility.dart';

3.2 使用方式

该插件提供了多种使用方式，开发者可以根据实际需求选择合适的方法。

方式一：使用 KeyboardVisibilityBuilder 构建器

在 Widget 树中使用 KeyboardVisibilityBuilder，根据键盘可见性动态构建 UI：

@override
Widget build(BuildContext context) {
  return KeyboardVisibilityBuilder(
      builder: (context, isKeyboardVisible) {
        return Column(
          children: [
            TextField(
              decoration: InputDecoration(
                labelText: '请输入内容',
              ),
            ),
            Visibility(
              visible: !isKeyboardVisible,
              child: ElevatedButton(
                onPressed: () {
                  // 执行提交操作
                },
                child: Text('提交'),
              ),
            ),
            Text(
              '键盘状态: ${isKeyboardVisible ? '可见' : '不可见'}',
            ),
          ],
        );
      }
  );
}

方式二：使用 KeyboardVisibilityProvider

在 Widget 树顶部添加 KeyboardVisibilityProvider，然后在子 Widget 中查询键盘状态：

// 在应用顶层或页面顶层添加
@override
Widget build(BuildContext context) {
  return KeyboardVisibilityProvider(
    child: MyApp(),
  );
}

// 在子组件中使用
class MyComponent extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final bool isKeyboardVisible = KeyboardVisibilityProvider.isKeyboardVisible(context);
    return Container(
      // 根据键盘状态调整布局
      padding: EdgeInsets.only(
        bottom: isKeyboardVisible ? 200.0 : 0.0,
      ),
      child: Text('键盘可见性: $isKeyboardVisible'),
    );
  }
}

方式三：直接使用 KeyboardVisibilityController

直接查询和订阅键盘可见性变化：

import 'dart:async';
import 'package:flutter_keyboard_visibility/flutter_keyboard_visibility.dart';

class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late StreamSubscription<bool> keyboardSubscription;
  bool isKeyboardVisible = false;

  @override
  void initState() {
    super.initState();

    // 初始化控制器
    var keyboardVisibilityController = KeyboardVisibilityController();

    // 直接查询当前状态
    isKeyboardVisible = keyboardVisibilityController.isVisible;

    // 订阅键盘状态变化
    keyboardSubscription = keyboardVisibilityController.onChange.listen((bool visible) {
      setState(() {
        isKeyboardVisible = visible;
      });
      print('键盘可见性变化: $visible');
    });
  }

  @override
  void dispose() {
    keyboardSubscription.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Text('键盘可见性: $isKeyboardVisible');
  }
}

方式四：使用 KeyboardDismissOnTap

点击屏幕任意位置隐藏键盘：

@override
Widget build(BuildContext context) {
  return KeyboardDismissOnTap(
    child: Scaffold(
      appBar: AppBar(title: Text('键盘隐藏示例')),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          children: [
            TextField(decoration: InputDecoration(labelText: '输入框 1')),
            SizedBox(height: 20),
            TextField(decoration: InputDecoration(labelText: '输入框 2')),
            SizedBox(height: 20),
            Text('点击屏幕任意位置可隐藏键盘'),
          ],
        ),
      ),
    ),
  );
}

// 如果需要点击交互组件也隐藏键盘，可以设置 dismissOnCapturedTaps 为 true
@override
Widget build(BuildContext context) {
  return KeyboardDismissOnTap(
    dismissOnCapturedTaps: true,
    child: Scaffold(
      // ...
      body: Column(
        children: [
          TextField(decoration: InputDecoration(labelText: '输入框')),
          ElevatedButton(
            onPressed: () {
              // 点击按钮时，键盘也会被隐藏
            },
            child: Text('按钮'),
          ),
        ],
      ),
    ),
  );
}

4. 约束与限制

兼容性

该插件已在以下环境中测试通过：

• Flutter: 3.7.12-ohos-1.0.6
• SDK: 5.0.0(12)
• IDE: DevEco Studio: 5.0.13.200
• ROM: 5.1.0.120 SP3

支持的 API

名称	返回值	描述	类型	鸿蒙支持
KeyboardVisibilityController	KeyboardVisibilityHandler	提供有关键盘可见性的直接信息并允许订阅更改	function	yes
KeyboardVisibilityWidget	widget	一个widget的构建器，用于显示本机键盘是否可见	function	yes

KeyboardVisibilityHandler

名称	返回值	描述	类型	鸿蒙支持
onchange.listen((bool visible) {})	Stream	每次显示键盘时发出 true，每次关闭键盘时发出 false	function	yes

5. 示例应用

插件提供了完整的示例应用，包含了各种使用场景的演示。示例代码位于 flutter_keyboard_visibility/example/lib/ 目录下，包括：

• main.dart：主示例页面，展示了基本的键盘可见性检测
• keyboard_dismiss_demo.dart：演示如何使用 KeyboardDismissOnTap
• provider_demo.dart：演示如何使用 KeyboardVisibilityProvider

开发者可以参考这些示例代码来快速理解和使用该插件。

6. 总结

flutter_keyboard_visibility 是一个功能强大且易于使用的键盘可见性检测插件，它在鸿蒙系统上提供了与其他平台一致的 API 和功能。通过使用该插件，开发者可以轻松处理键盘显示和隐藏时的 UI 适配问题，提升应用的用户体验。

主要优势：

• API 简洁易用，提供多种使用方式
• 实时准确的键盘状态检测
• 支持键盘隐藏功能，提升输入体验
• 与鸿蒙系统完美兼容
• 跨平台 API 一致，减少学习成本

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net