useGamepad
为 Gamepad API 提供响应式绑定。
演示
用法
由于 Gamepad API 的工作方式，您必须先使用游戏手柄与页面进行交互，然后才能检测到它。
vue
<script setup lang="ts">
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 API 没有事件支持来更新游戏手柄的状态。为了更新游戏手柄状态，使用 requestAnimationFrame 来轮询游戏手柄的变化。您可以通过使用 useGamepad 提供的 pause 和 resume 函数来控制此轮询
ts
import { useGamepad } from '@vueuse/core'
const { pause, resume, gamepads } = useGamepad()
pause()
// gamepads object will not update
resume()
// gamepads object will update on user input游戏手柄连接和断开事件
当游戏手柄连接或断开时，onConnected 和 onDisconnected 事件将触发。
ts
const { gamepads, onConnected, onDisconnected } = useGamepad()
onConnected((index) => {
console.log(`${gamepads.value[index].id} connected`)
})
onDisconnected((index) => {
console.log(`${index} disconnected`)
})振动
Gamepad 触觉 API 稀少，因此在使用前请查看兼容性表格。
ts
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,
})
}
}映射
为了使 Gamepad API 更易于使用，我们提供了映射，将控制器映射到控制器的按钮布局。
Xbox360 控制器
vue
<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 以获取更多控制器映射！
SSR 兼容性
此组件设计用于客户端。在某些情况下，SSR 可能会导致一些水合不匹配。
如果您正在使用 Nuxt，您可以简单地将组件文件重命名为带有 .client.vue 后缀的文件（例如，GamepadComponent.client.vue），这将自动使其仅在客户端渲染，避免水合不匹配。
在其他框架或纯 Vue 中，您可以使用 <ClientOnly> 组件包装您的使用组件，以确保它仅在客户端渲染。
类型声明
显示类型声明
ts
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<ShallowRef<boolean>>
}
export type UseGamepadReturn = ReturnType<typeof useGamepad>来源
贡献者
Anthony Fu
wheat
SerKo
Anthony Fu
Jelf
Arthur Darkstone
isolcat
Fernando Fernández
Robin
Aaron-zon
yue
Curt Grimes
Stefan
Antonin Rousset
丶远方
三咲智子