HumanBreak/docs/api/class/keyboard.md

类 Keyboard

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

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

id

declare var id: string

• 成员说明

  这个虚拟键盘的 id

keys

declare var keys: KeyboardItem[]

• 成员说明

  包含了所有被添加的按键

• 接口 KeyboardItem

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

assist

declare var assist: number

• 成员说明

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

fontSize

declare var fontSize: number

• 成员说明

  当前虚拟键盘的字体大小

scope

declare var scope: symbol

• 成员说明

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

constructor()

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

add()

declare function add(item: KeyboardItem): this

• 方法说明

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

remove()

declare function remove(item: KeyboardItem): this

• 方法说明

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

withAssist()

declare function withAssist(assist: number): symbol

• 参数说明

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

• 方法说明

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

• 返回值

  创建的作用域的symbol

createScope()

declare function createScope(): symbol

• 方法说明

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

• 返回值

  这个作用域对应的symbol

disposeScope()

declare function disposeScope(): void

• 方法说明

  销毁上一次创建的作用域

extend()

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

• 参数说明

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

• 方法说明

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

emitKey()

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

• 参数说明

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

• 方法说明

  触发一个虚拟按键

list

declare var list: Keyboard[]

• 静态成员说明

  包含了所有的 Keyboard 实例

get()

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 事件

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

• 事件说明

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

remove 事件

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

• 事件说明

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

extend 事件

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

• 事件说明

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

emit 事件

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

• 参数说明

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

• 接口 VirtualKeyEmit

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

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

• 事件说明

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

• 示例

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

  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 事件

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

• 事件说明

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

scopeDispose 事件

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

• 事件说明

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