Flutter自定义键盘布局插件virtual_keyboard_custom_layout的使用

关于

virtual_keyboard_custom_layout 是一个为没有原生键盘的设备（如自助服务终端、ATM等）显示键盘的包。该库用Dart编写，不依赖任何原生代码。它分叉自 virtual_keyboard_multi_language。

我选择从多语言版本中分叉出来，因为它更新得更频繁，并且有一些额外的自定义功能。

目标

这个依赖项非常适合我的项目，但其中一个小方面促使我分叉并发布了一个自定义版本。问题在于键盘布局缺乏足够的自定义性。我需要从两个初始预设中只保留几个键，并不能按照我想要的方式个性化它。因此，为了方便使用和自我提升，我创建了这个包，并对结果非常满意。

参考

VirtualKeyboard

Flutter小部件用于显示虚拟键盘。

• 类型：可以是数字、字母数字或自定义。

  VirtualKeyboardType type
  

• 按键事件回调：按下按键时调用，带有被按下的 Key 对象。

  Function onKeyPress;
  

• 虚拟键盘高度：默认为300。

  double height;
  

• 虚拟键盘宽度：默认为全屏宽度。

  double width;
  

• 键文本和图标颜色：

  Color textColor;
  

• 键盘键字体大小：

  double fontSize;
  

• 仅大写字母启用：

  bool alwaysCaps;
  

• 多语言或单语言的自定义布局：

  VirtualKeyboardLayoutKeys customLayoutKeys;
  

• 用于多语言的默认布局：默认只有英语。

  List<VirtualKeyboardDefaultLayouts> defaultLayouts;
  

• 反转布局以修复从右到左语言的问题：

  bool reverseLayout;
  

• 按键列表：所有都需要设置为字符串。

  bool keys;
  

• 设置键盘所有键的边框颜色：

  Color borderColor
  

VirtualKeyboardType

可用的虚拟键盘类型的枚举。

• 仅数字：

  VirtualKeyboardType.Numeric
  

• 字母数字：字母 [A-Z] + 数字 [0-9] + @ + .。

  VirtualKeyboardType.Alphanumeric
  

• 自定义：所有类型+特殊键如 [“BACKSPACE”, “RETURN”, “SHIFT”, “SPACE” 和 “SWITCHLANGUAGE”]。

  VirtualKeyboardType.Custom
  

VirtualKeyboardKey

虚拟键盘键。

• 键的文本：

  String text
  

• 大写的键文本：

  String capsText;
  

• 动作或字符串：

  VirtualKeyboardKeyType keyType;
  

• 键的动作：

  VirtualKeyboardKeyAction action;
  

VirtualKeyboardKeyType

虚拟键盘键类型。

• 可以是动作键 - Return, Backspace 等：

  VirtualKeyboardKeyType.Action
  

• 有文本值的键 - 字母、数字、逗号等：

  VirtualKeyboardKeyType.String
  

VirtualKeyboardKeyAction

虚拟键盘动作。

enum VirtualKeyboardKeyAction { Backspace, Return, Shift, Space }

使用示例

显示自定义键盘

Container(
  color: Colors.grey,
  child: VirtualKeyboard(
    height: 350,
    width: 600,
    textColor: Colors.white,
    fontSize: 20,
    defaultLayouts: [VirtualKeyboardDefaultLayouts.English],
    type: VirtualKeyboardType.Custom,
    keys: const [
      ["T", "E", "S", "T"],
      ["C", "U", "S", "T", "O", "M"],
      ["L", "A", "Y", "O", "U", "T"],
      ["RETURN", "SHIFT", "BACKSPACE", "SPACE"],
    ],
    onKeyPress: _onKeyPress,
  ),
)

显示字母数字键盘

Container(
  color: Colors.deepPurple,
  child: VirtualKeyboard(
    height: 350,
    width: 600,
    textColor: Colors.white,
    fontSize: 20,
    defaultLayouts: [VirtualKeyboardDefaultLayouts.English],
    type: VirtualKeyboardType.Alphanumeric,
    onKeyPress: _onKeyPress,
  ),
)

显示数字键盘

Container(
  color: Colors.red,
  child: VirtualKeyboard(
    type: VirtualKeyboardType.Numeric,
    onKeyPress: (key) => print(key.text),
  ),
)

onKeyPressed事件基本用法示例

String text = '';
bool shiftEnabled = false;

_onKeyPress(VirtualKeyboardKey key) {
  if (key.keyType == VirtualKeyboardKeyType.String) {
    text = text + (shiftEnabled ? key.capsText : key.text);
  } else if (key.keyType == VirtualKeyboardKeyType.Action) {
    switch (key.action) {
      case VirtualKeyboardKeyAction.Backspace:
        if (text.length == 0) return;
        text = text.substring(0, text.length - 1);
        break;
      case VirtualKeyboardKeyAction.Return:
        text = text + '\n';
        break;
      case VirtualKeyboardKeyAction.Space:
        text = text + key.text;
        break;
      case VirtualKeyboardKeyAction.Shift:
        shiftEnabled = !shiftEnabled;
        break;
      default:
    }
  }
  setState(() {});
}

完整示例demo

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

void main() => runApp(const MyApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Virtual Keyboard Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Virtual Keyboard Demo'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  final String title;
  const MyHomePage({super.key, required this.title});

  @override
  // ignore: library_private_types_in_public_api
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  String text = '';
  bool shiftEnabled = false;
  bool isNumericMode = false;
  TextEditingController controllerField01 = TextEditingController();
  TextEditingController controllerField02 = TextEditingController();
  TextEditingController controllerField03 = TextEditingController();
  var isKeyboardVisible = false;
  var controllerKeyboard = TextEditingController();
  late TypeLayout typeLayout;

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

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        FocusScope.of(context).unfocus();
        setState(() {
          isKeyboardVisible = false;
        });
      },
      child: Scaffold(
        appBar: AppBar(
          title: Text(widget.title),
        ),
        body: Center(
          child: Column(
            children: <Widget>[
              TextFormField(
                keyboardType: TextInputType.none,
                controller: controllerField01,
                onTap: () {
                  setState(() {
                    isKeyboardVisible = true;
                    controllerKeyboard = controllerField01;
                    typeLayout = TypeLayout.alphabet;
                  });
                },
              ),
              TextFormField(
                keyboardType: TextInputType.none,
                controller: controllerField02,
                onTap: () {
                  setState(() {
                    isKeyboardVisible = true;
                    controllerKeyboard = controllerField02;
                    typeLayout = TypeLayout.alphaEmail;
                  });
                },
              ),
              TextFormField(
                keyboardType: TextInputType.none,
                controller: controllerField03,
                onTap: () {
                  setState(() {
                    isKeyboardVisible = true;
                    controllerKeyboard = controllerField03;
                    typeLayout = TypeLayout.numeric;
                  });
                },
              ),
              Expanded(
                child: Container(),
              ),
              if (isKeyboardVisible)
                Stack(children: [
                  KeyboardAux(
                    alwaysCaps: true,
                    controller: controllerKeyboard,
                    typeLayout: typeLayout,
                    typeKeyboard: VirtualKeyboardType.Custom,
                  ),
                ]),
            ],
          ),
        ),
      ),
    );
  }
}

此完整示例展示了如何在不同场景下使用 virtual_keyboard_custom_layout 插件，包括显示自定义键盘、字母数字键盘和数字键盘，并处理按键事件。希望这对您有所帮助！