useGamepad

类别

Browser

导出大小

1.47 kB

最近修改

2 days ago

为 Gamepad API 提供响应式绑定。

🌐 Provides reactive bindings for the Gamepad API.

示例

源代码在线运行

用法

🌐 Usage

由于游戏句柄 API 的工作原理，你必须先使用游戏句柄与页面进行交互，它才能被检测到。

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

游戏句柄触觉 API 功能有限，因此在使用前请查看兼容性表。

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!

SSR 兼容性

🌐 SSR Compatibility

该组件旨在用于客户端。在某些情况下，SSR 可能会导致一些 hydration 不匹配。

🌐 This component is designed to be used in the client side. In some cases, SSR might cause some hydration mismatches.

如果你正在使用 Nuxt，你可以简单地将你的组件文件重命名为带有 .client.vue 后缀（例如，GamepadComponent.client.vue），这样它就会自动只在客户端渲染，从而避免水合不匹配问题。

🌐 If you are using Nuxt, you can simply rename your component file with the .client.vue suffix (e.g., GamepadComponent.client.vue) which will automatically make it render only on the client side, avoiding hydration mismatches.

在其他框架或纯 Vue 中，你可以用 <ClientOnly> 组件封装你的使用组件，以确保它只在客户端渲染。

🌐 In other frameworks or plain Vue, you can wrap your usage component with a <ClientOnly> component to ensure it is only rendered on the client side.