useGamepad

为 游戏句柄 API 提供反应式绑定。

¥Provides reactive bindings for the Gamepad API.

示例

source

Gamepad is not supported on this device.It seems your device does not support the Gamepad API. Check here for a list supported devices.

用法

¥Usage

由于游戏句柄 API 的工作方式，你必须使用游戏句柄与页面进行交互，然后才会检测到它。

¥Due to how the Gamepad API works, you must interact with the page using the gamepad before it will be detected.

<script setup>
import { useGamepad } from '@vueuse/core'
import { computed } from 'vue'

const { isSupported, gamepads } = useGamepad()
const gamepad = computed(() => gamepads.value.find(g => g.mapping === 'standard'))
</script>

<template>
  <span>
    {{ gamepad.id }}
  </span>
</template>

游戏句柄更新

¥Gamepad Updates

目前，游戏句柄 API 不支持更新游戏句柄状态的事件。为了更新游戏句柄状态，requestAnimationFrame 用于轮询游戏句柄更改。你可以使用 useGamepad 提供的 pause 和 resume 函数来控制此轮询

¥Currently the Gamepad API does not have event support to update the state of the gamepad. To update the gamepad state, requestAnimationFrame is used to poll for gamepad changes. You can control this polling by using the pause and resume functions provided by useGamepad

import { useGamepad } from '@vueuse/core'

const { pause, resume, gamepads } = useGamepad()

pause()

// gamepads object will not update

resume()

// gamepads object will update on user input

游戏句柄连接和断开事件

¥Gamepad Connect & Disconnect Events

当游戏句柄连接或断开连接时，将触发 onConnected 和 onDisconnected 事件。

¥The onConnected and onDisconnected events will trigger when a gamepad is connected or disconnected.

const { gamepads, onConnected, onDisconnected } = useGamepad()

onConnected((index) => {
  console.log(`${gamepads.value[index].id} connected`)
})

onDisconnected((index) => {
  console.log(`${index} disconnected`)
})

振动

¥Vibration

Gamepad Haptics API 很少，因此在使用前请检查 兼容性表。

¥The Gamepad Haptics API is sparse, so check the compatibility table before using.

import { computed } from 'vue'

const supportsVibration = computed(() => gamepad.hapticActuators.length > 0)
function vibrate() {
  if (supportsVibration.value) {
    const actuator = gamepad.hapticActuators[0]
    actuator.playEffect('dual-rumble', {
      startDelay: 0,
      duration: 1000,
      weakMagnitude: 1,
      strongMagnitude: 1,
    })
  }
}

映射

¥Mappings

为了使 Gamepad API 更易于使用，我们提供了将控制器映射到控制器按钮布局的映射。

¥To make the Gamepad API easier to use, we provide mappings to map a controller to a controllers button layout.

Xbox360 控制器

¥Xbox360 Controller

<script setup>
import { mapGamepadToXbox360Controller } from '@vueuse/core'

const controller = mapGamepadToXbox360Controller(gamepad)
</script>

<template>
  <span>{{ controller.buttons.a.pressed }}</span>
  <span>{{ controller.buttons.b.pressed }}</span>
  <span>{{ controller.buttons.x.pressed }}</span>
  <span>{{ controller.buttons.y.pressed }}</span>
</template>

目前只有 Xbox 360 控制器的映射。如果你想要为其添加映射的控制器，请随时打开 PR 以获取更多控制器映射！

¥Currently there are only mappings for the Xbox 360 controller. If you have controller you want to add mappings for, feel free to open a PR for more controller mappings!

类型声明

显示类型声明

export interface UseGamepadOptions
  extends ConfigurableWindow,
    ConfigurableNavigator {}
/**
 * Maps a standard standard gamepad to an Xbox 360 Controller.
 */
export declare function mapGamepadToXbox360Controller(
  gamepad: Ref<Gamepad | undefined>,
): ComputedRef<{
  buttons: {
    a: GamepadButton
    b: GamepadButton
    x: GamepadButton
    y: GamepadButton
  }
  bumper: {
    left: GamepadButton
    right: GamepadButton
  }
  triggers: {
    left: GamepadButton
    right: GamepadButton
  }
  stick: {
    left: {
      horizontal: number
      vertical: number
      button: GamepadButton
    }
    right: {
      horizontal: number
      vertical: number
      button: GamepadButton
    }
  }
  dpad: {
    up: GamepadButton
    down: GamepadButton
    left: GamepadButton
    right: GamepadButton
  }
  back: GamepadButton
  start: GamepadButton
} | null>
export declare function useGamepad(options?: UseGamepadOptions): {
  isSupported: ComputedRef<boolean>
  onConnected: EventHookOn<number>
  onDisconnected: EventHookOn<number>
  gamepads: Ref<
    {
      readonly axes: ReadonlyArray<number>
      readonly buttons: readonly {
        readonly pressed: boolean
        readonly touched: boolean
        readonly value: number
      }[]
      readonly connected: boolean
      readonly id: string
      readonly index: number
      readonly mapping: GamepadMappingType
      readonly timestamp: DOMHighResTimeStamp
      readonly vibrationActuator: {
        playEffect: (
          type: GamepadHapticEffectType,
          params?: GamepadEffectParameters,
        ) => Promise<GamepadHapticsResult>
        reset: () => Promise<GamepadHapticsResult>
      }
    }[],
    | Gamepad[]
    | {
        readonly axes: ReadonlyArray<number>
        readonly buttons: readonly {
          readonly pressed: boolean
          readonly touched: boolean
          readonly value: number
        }[]
        readonly connected: boolean
        readonly id: string
        readonly index: number
        readonly mapping: GamepadMappingType
        readonly timestamp: DOMHighResTimeStamp
        readonly vibrationActuator: {
          playEffect: (
            type: GamepadHapticEffectType,
            params?: GamepadEffectParameters,
          ) => Promise<GamepadHapticsResult>
          reset: () => Promise<GamepadHapticsResult>
        }
      }[]
  >
  pause: Fn
  resume: Fn
  isActive: Readonly<Ref<boolean, boolean>>
}
export type UseGamepadReturn = ReturnType<typeof useGamepad>

源代码

源代码 • 示例 • 文档

变更日志

No recent changes