Flutter虚拟键盘插件virtual_keyboard的使用

简介

virtual_keyboard 是一个简单的 Flutter 包，用于在设备（如自助服务终端或 ATM）上显示虚拟键盘。该库完全用 Dart 编写，不依赖任何原生代码。

虚拟键盘提供了核心功能以显示屏幕上的虚拟键盘，并且事件管理应在项目级别完成。

参考文档

VirtualKeyboard

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

// 键盘类型：可以是数字或字母数字。
VirtualKeyboardType type

// 按键按下时的回调函数。按下的 `Key` 对象将作为参数传递。
Function onKeyPress;

// 虚拟键盘的高度。默认值为 300。
double height;

// 键文字和图标的颜色。
Color textColor;

// 键字体大小。
double fontSize;

// 仅启用大写字母。
bool alwaysCaps;

VirtualKeyboardType

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

// 仅数字。
VirtualKeyboardType.Numeric

// 字母数字：字母 `[A-Z]` + 数字 `[0-9]` + `@` + `.`。
VirtualKeyboardType.Alphanumeric

VirtualKeyboardKey

虚拟键盘按键。

// 按钮的文字。
String text

// 按钮的大写文字。
String capsText;

// 动作或字符串。
VirtualKeyboardKeyType keyType;

// 按钮的动作。
VirtualKeyboardKeyAction action;

VirtualKeyboardKeyType

虚拟键盘按键类型。

// 可以为动作键 - 返回、退格等。
VirtualKeyboardKeyType.Action

// 具有文本值的键 - 字母、数字、逗号等。
VirtualKeyboardKeyType.String

VirtualKeyboardKeyAction

虚拟键盘操作枚举。

/// 虚拟键盘操作。
enum VirtualKeyboardKeyAction { Backspace, Return, Shift, Space }

使用方法

显示默认的字母数字键盘

Container(
  // 设置键盘背景颜色。
  color: Colors.deepPurple,
  child: VirtualKeyboard(
    // 默认高度为 300。
    height: 350,
    // 默认文字颜色为白色。
    textColor: Colors.white,
    // 默认字体大小为 20。
    fontSize: 20,
    // 类型为字母数字。
    type: VirtualKeyboardType.Alphanumeric,
    // 按键按下事件回调。
    onKeyPress: _onKeyPress,
  ),
)

显示默认的数字键盘

Container(
  // 设置键盘背景颜色。
  color: Colors.red,
  child: VirtualKeyboard(
    // 类型为数字。
    type: VirtualKeyboardType.Numeric,
    // 按键按下事件回调。
    onKeyPress: (key) => print(key.text),
  ),
)

显示自定义样式的字母数字键盘

Container(
  color: Colors.deepPurple,
  child: VirtualKeyboard(
    height: keyboardHeight,
    textColor: Colors.white,
    fontSize: 20,
    builder: _builder,
    type: VirtualKeyboardType.Numeric,
    onKeyPress: _onKeyPress,
  ),
)

/// 自定义按键构建器。
Widget _builder(BuildContext context, VirtualKeyboardKey key) {
  Widget keyWidget;

  switch (key.keyType) {
    case VirtualKeyboardKeyType.String:
      // 绘制字符串键。
      keyWidget = _keyboardDefaultKey(key);
      break;
    case VirtualKeyboardKeyType.Action:
      // 绘制动作键。
      keyWidget = _keyboardDefaultActionKey(key);
      break;
  }

  return keyWidget;
}

按键按下事件的基本使用示例

// 本地变量，用于存储用户输入。
String text;

/// 当虚拟键盘按键被按下时触发。
_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(() {});
}

示例代码

以下是完整的示例代码，展示如何集成虚拟键盘并处理按键事件：

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

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

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Virtual Keyboard Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Virtual Keyboard Demo'),
    );
  }
}

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

  [@override](/user/override)
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  // 存储用户输入的文本。
  String text = '';

  // 是否启用了 Shift 键。
  bool shiftEnabled = false;

  // 是否显示数字键盘。
  bool isNumericMode = true;

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          children: <Widget>[
            Text(
              text,
              style: Theme.of(context).textTheme.display1,
            ),
            SwitchListTile(
              title: Text(
                'Keyboard Type = ' +
                    (isNumericMode
                        ? 'VirtualKeyboardType.Numeric'
                        : 'VirtualKeyboardType.Alphanumeric'),
              ),
              value: isNumericMode,
              onChanged: (val) {
                setState(() {
                  isNumericMode = val;
                });
              },
            ),
            Expanded(
              child: Container(),
            ),
            Container(
              color: Colors.deepPurple,
              child: VirtualKeyboard(
                height: 300,
                textColor: Colors.white,
                type: isNumericMode
                    ? VirtualKeyboardType.Numeric
                    : VirtualKeyboardType.Alphanumeric,
                onKeyPress: _onKeyPress,
              ),
            ),
          ],
        ),
      ),
    );
  }

  /// 按键按下事件处理函数。
  _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(() {});
  }
}