Skip to content

# 类 Keyboard ​

渲染进程类，不能直接在游戏进程使用，继承自EventEmitter

- 实例成员
  - `id`
  - `keys`
  - `assist`
  - `fontSize`
  - `scope`
- 实例方法
  - 构造器`constructor`
  - `add`
  - `remove`
  - `withAssist`
  - `createScope`
  - `disposeScope`
  - `extend`
  - `emitKey`
- 静态成员
  - `list`
- 静态方法
  - `get`
- 实例事件
  - `add`
  - `remove`
  - `extend`
  - `emit`
  - `scopeCreate`
  - `scopeDispose`

## id ​

ts

    declare var id: string

- 成员说明

  这个虚拟键盘的 id

## keys ​

ts

    declare var keys: KeyboardItem[]

- 成员说明

  包含了所有被添加的按键

- 接口 `KeyboardItem`

  - `key`: 枚举 `KeyCode` 成员，表示按下这个键后触发哪个按键
  - `text`: 可选，表示按键的显示文字，兼容 html 标签
  - `x`: 这个按键的横坐标
  - `y`: 这个按键的纵坐标
  - `width`: 这个按键的宽度
  - `height`: 这个按键的高度

## assist ​

ts

    declare var assist: number

- 成员说明

  表示当前虚拟键盘按下的辅助按键（`ctrl` `shift` `alt`）

## fontSize ​

ts

    declare var fontSize: number

- 成员说明

  当前虚拟键盘的字体大小

## scope ​

ts

    declare var scope: symbol

- 成员说明

  当前虚拟键盘处在的作用域

## constructor() ​

ts

    interface Keyboard {
        new(id: string): Keyboard
    }

## add() ​

ts

    declare function add(item: KeyboardItem): this

- 方法说明

  向这个虚拟键盘添加一个按键

## remove() ​

ts

    declare function remove(item: KeyboardItem): this

- 方法说明

  删除一个按键，参数表示要删除的按键的引用

## withAssist() ​

ts

    declare function withAssist(assist: number): symbol

- 参数说明

  - `assist`: 初始状态下被触发的辅助按键，可以通过`wrapAssist`函数来创建

- 方法说明

  创造一个在某些辅助按键已经按下的情况下的作用域，这些被按下的辅助按键还可以被玩家手动取消

- 返回值

  创建的作用域的`symbol`

## createScope() ​

ts

    declare function createScope(): symbol

- 方法说明

  创建一个全新的作用域，在这个作用域下不会影响到任何其他作用域，例如开关辅助按键等，监听事件也不会相冲突

- 返回值

  这个作用域对应的`symbol`

## disposeScope() ​

ts

    declare function disposeScope(): void

- 方法说明

  销毁上一次创建的作用域

## extend() ​

ts

    declare function extend(
        keyboard: Keyboard,
        offsetX: number = 0,
        offsetY: number = 0
    ): this

- 参数说明

  - `keyboard`: 要继承的按键实例
  - `offsetX`: 继承时所有按键的偏移横坐标
  - `offsetY`: 继承时所有按键的偏移纵坐标

- 方法说明

  继承自一个其他的虚拟按键实例，例如主键盘可以由字母按键、数字按键等继承而来，同时指定偏移坐标

## emitKey() ​

ts

    declare function emitKey(key: KeyboardItem, index: number): void

- 参数说明

  - `key`: 触发的按键信息，是按键的引用
  - `index`: 这个按键在 `keys` 中的索引

- 方法说明

  触发一个虚拟按键

## list ​

ts

    declare var list: Keyboard[]

- 静态成员说明

  包含了所有的 `Keyboard` 实例

## get() ​

ts

    declare function get(id: string): Keyboard

- 方法说明

  根据虚拟按键实例的 id 获取到虚拟按键实例

- 系统自带虚拟按键

  - `qwe`: 字母键盘，包含 A-Z
  - `num`: 字母键盘上方的数字键盘，非小键盘，包含 0-9 及反引号键、减号键、等号键和退格键
  - `char`: 符号键盘，包含 []\;',./
  - `fn`: Fn 键盘，包含 F1-F12 及 Escape
  - `assist`: 辅助按键键盘，包含 Tab、大写锁定、左右 Shift、左右 Ctrl、左右 Alt、左右 Meta（Windows 电脑的 Win 键，或是 Mac 电脑的 Command 键）、空格键、回车键
  - `arrow`: 方向键，包含上下左右四个方向键
  - `numpad`: 小键盘，包含小键盘的 0-9（与数字键盘的 0-9 不同）、小键盘锁（NumLock）、小键盘的+-*/、小键盘的点、回车（与主键盘的回车相同）
  - `media`: 媒体按键，包含播放/暂停、停止播放、上一首、下一首
  - `tool`: 功能按键，包含 PageUp、PageDn、Insert、Delete、Home、End
  - `main`: 主键盘，继承 `qwe` `num` `char` `fn` `assist`，无新增按键
  - `toolArrow`: 方向键与功能键，继承 `arrow` `tool`，无新增按键
  - `mini`: 小键盘，继承 `numpad`，无新增按键
  - `full`: 全按键，继承 `main` `toolArrow` `mini` `media`，无新增按键

## add 事件 ​

ts

    interface VirtualKeyboardEvent {
        add: (item: KeyboardItem) => void
    }

- 事件说明

  当添加虚拟按键时触发事件

## remove 事件 ​

ts

    interface VirtualKeyboardEvent {
        remove: (item: KeyboardItem) => void
    }

- 事件说明

  当移除一个虚拟按键时触发

## extend 事件 ​

ts

    interface VirtualKeyboardEvent {
        extend: (extended: Keyboard) => void
    }

- 事件说明

  当继承其他虚拟键盘实例时触发

## emit 事件 ​

ts

    interface VirtualKeyboardEvent {
        emit: (
            item: KeyboardItem,
            assist: number,
            index: number,
            ev: VirtualKeyEmit
        ) => void
    }

- 参数说明

  - `item`: 触发的按键信息
  - `assist`: 触发时的辅助按键按下情况
  - `index`: 按键信息处在的按键列表中的索引
  - `ev`: 剩余内容，包含一些函数以供调用

- 接口 `VirtualKeyEmit`

  ts

      interface VirtualKeyEmit {
          preventDefault(): void
          preventAssist(): void
      }

  - `preventDefault`: 阻止非辅助虚拟按键的默认行为。虚拟按键的默认行为为触发 `Hotkey` 在当前作用域下对应的按键，调用后即可阻止这一默认行为的发生
  - `preventAssist`: 阻止辅助按键的默认行为。辅助按键的默认行为是开关对应的辅助按键开关状态，调用后可以阻止这一默认行为的发生

- 事件说明

  当触发一个虚拟按键时触发这个事件

- 示例

  以下是样板自带函数 `getVirtualKeyOnce` 的源代码实现，这个函数便依赖于这个事件。

  ts

      export function getVitualKeyOnce(
          emitAssist: boolean = false,
          assist: number = 0,
          emittable: KeyCode[] = []
      ): Promise<KeyboardEmits> {
          return new Promise(res => {
              const key = Keyboard.get('full')!;
              key.withAssist(assist);
              const id = mainUi.open('virtualKey', { keyboard: key });
              key.on('emit', (item, assist, index, ev) => {
                  ev.preventDefault();
                  if (emitAssist) {
                      if (emittable.length === 0 || emittable.includes(item.key)) {
                          res({ key: item.key, assist: 0 });
                          key.disposeScope();
                          mainUi.close(id);
                      }
                  } else {
                      if (
                          !isAssist(item.key) &&
                          (emittable.length === 0 || emittable.includes(item.key))
                      ) {
                          res({ key: item.key, assist });
                          key.disposeScope();
                          mainUi.close(id);
                      }
                  }
              });
          });
      }

## scopeCreate 事件 ​

ts

    interface VirtualKeyboardEvent {
        scopeCreate: (scope: symbol) => void
    }

- 事件说明

  当创建一个作用域时触发这个事件

## scopeDispose 事件 ​

ts

    interface VirtualKeyboardEvent {
        scopeDispose: (scope: symbol) => void
    }

- 事件说明

  当释放一个作用域时触发这个事件