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

一、核心价值

1.1 基础概念

为了在 Flutter 层捕获键盘状态，插件通过 MethodChannel 与鸿蒙原生的键盘生命周期钩子进行握手。

1.2 进阶概念

• Reactive State (响应式状态)：不仅仅是真/假（True/False），你可以实时监听键盘高度的变化轨迹（在某些平台上），从而实现与键盘高度完全同步的“跟手”动画。
• Auto-Dispose：在鸿蒙页面销毁时自动切断监听，防止内存泄露。

二、核心 API / 组件详解

2.1 依赖引入

由于官方主仓库尚未完全合入鸿蒙原生代码，目前推荐使用由 OpenHarmony-SIG 维护的适配版本，并通过本地 packages 目录进行管理。

1. 获取源码：将适配仓库克隆至本地 packages 目录。

git clone https://atomgit.com/openharmony-sig/flutter_keyboard_visibility.git packages/flutter_keyboard_visibility

2. 配置依赖：在 pubspec.yaml 中通过 path 指向适配库。

dependencies:
  flutter_keyboard_visibility:
    path: packages/flutter_keyboard_visibility/flutter_keyboard_visibility

避坑指南：为什么不直接用 Git 引用？
因为克隆到本地后，我们需要对 ohos/BuildProfile.ets 进行微调（如将类静态常量改为顶层 export const），以避开新版 ArkTS 编译器（API 11+）的严格模式冲突，确保项目能正常编译并正确注入构建配置。

2.2 使用 Builder 快速驱动 UI

在鸿蒙工程中，如果你只想在键盘出现时隐藏某个组件，这是最简单的方法：

import 'package:flutter_keyboard_visibility/flutter_keyboard_visibility.dart';

Widget buildHarmonyInputPage() {
  return KeyboardVisibilityBuilder(
    builder: (context, isKeyboardVisible) {
      return Column(
        children: [
          const TextField(decoration: InputDecoration(labelText: '请输入反馈内容')),
          const Spacer(),
          // ✅ 推荐做法：当键盘可见时，自动隐藏底部装饰或广告
          if (!isKeyboardVisible) 
            const Text('💡 鸿蒙提示：输入完成后请确认无误')
        ],
      );
    },
  );
}

2.3 在逻辑层进行全局监听

var keyboardVisibilityController = KeyboardVisibilityController();

// 监听状态改变
keyboardVisibilityController.onChange.listen((bool visible) {
  print('⌨️ 鸿蒙软键盘状态变化: ${visible ? "弹起" : "收起"}');
});

三、场景示例

3.1 场景一：鸿蒙级聊天的“跟手”底部输入框

在聊天页面，键盘弹起的瞬间需要同时平滑上移输入框，并由于视口变小自动滚动列表到底部。

import 'package:flutter_keyboard_visibility/flutter_keyboard_visibility.dart';

void setupHarmonyChat() {
  keyboardVisibilityController.onChange.listen((bool visible) {
    if (visible) {
       // 💡 技巧：延时微调，确保键盘动画完成
       _scrollController.jumpTo(_scrollController.position.maxScrollExtent);
    }
  });
}

四、鸿蒙适配核心要点

在 OpenHarmony 平台上，除了依赖引入外，还需注意以下实战要点：

• 原生桥接原理：通过 MethodChannel 监听系统的 avoidAreaChange 事件。当键盘弹出导致安全区域改变时，插件会捕获并通知 Flutter 层。
• 高度适配建议：由于不同输入法（百度、搜狗等）的预测栏高度不一，建议优先使用 isVisible 状态。若需精确避让，请配合 MediaQuery.of(context).viewInsets.bottom 获取系统反馈的真实遮挡像素。
• 生命周期优化：在页面销毁时务必切断监听流，防止 EventChannel 在鸿蒙 HAP 中导致内存抖动。

五、综合实战示例代码

这是一个包含了基础 UI 自动避让与状态反馈的鸿蒙登录页面：

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

class HarmonyKeyboardLab extends StatelessWidget {
  const HarmonyKeyboardLab({super.key});

  @override
  Widget build(BuildContext context) {
    return KeyboardVisibilityBuilder(
      builder: (context, isVisible) {
        return Scaffold(
          appBar: AppBar(title: const Text('键盘感知 - 鸿蒙实战')),
          body: Padding(
            padding: const EdgeInsets.all(30),
            child: Column(
              children: [
                // 💡 演示：键盘出现时缩小 Logo，留出输入空间
                AnimatedContainer(
                  duration: const Duration(milliseconds: 300),
                  height: isVisible ? 50 : 150,
                  child: const Icon(Icons.security, size: 80, color: Colors.blue),
                ),
                const TextField(decoration: InputDecoration(labelText: '开发者账号')),
                const TextField(decoration: InputDecoration(labelText: '动态校验码')),
                const Spacer(),
                if (!isVisible) 
                  ElevatedButton(onPressed: () {}, child: const Text('安全登录鸿蒙中心')),
              ],
            ),
          ),
        );
      },
    );
  }
}

六、总结

flutter_keyboard_visibility 为鸿蒙应用提供了一种极其体面的方式来处理“小屏幕下的输入竞争”。它让开发者能以极其敏锐的姿态，响应系统最频繁的交互动作。

✅ 核心建议：

1. 大型表单页面，使用该插件来动态隐藏不必要的非输入组件。
2. 在处理复杂的键盘联动动画时，它是监听触发的第一时机。