t-joystick

Joystick 摇杆

组件介绍

t-joystick 基于自研 Canvas Flex 布局引擎实现，纯 Canvas 绘制，跨端兼容适配良好。支持多摇杆、方向控制、力度感应等功能，适用于游戏控制、遥控操作等场景。

平台兼容

Harmony	H5	Android	iOS	小程序	UTS
✅	✅	✅	✅	✅	✅

基础用法

基础用法参考 demo/joystick/joystick.uvue，通过 sticks 属性配置摇杆参数。

<template>
  <view class="joystick-demo">
    <t-joystick :sticks="sticks" @change="onJoystickChange"></t-joystick>
    <view class="info">
      <text>摇杆: {{ joystickInfo.name }}</text>
      <text>角度: {{ joystickInfo.angle }}°</text>
      <text>力度: {{ joystickInfo.distance }}</text>
    </view>
  </view>
</template>

<script setup>
const sticks = ref([
  {
    name: 'left',
    x: 50,
    y: 200,
    joySize: 150,
    compassSize: 120,
    ballSize: 50,
    arrow: '/static/arrow.png',
    compass: '/static/compass.png',
    pokeBall: '/static/ball.png',
    arrowReset: true,
    ballReset: true
  }
]);

const joystickInfo = ref({
  name: '',
  angle: 0,
  distance: 0
});

function onJoystickChange(e) {
  joystickInfo.value = e;
  console.log('摇杆变化:', e);
}
</script>

<style scoped>
.joystick-demo {
  padding: 40rpx;
  height: 500rpx;
}
.info {
  margin-top: 40rpx;
  padding: 20rpx;
  background: #f5f5f5;
  border-radius: 12rpx;
}
.info text {
  display: block;
  margin-bottom: 10rpx;
}
</style>

Props

属性名	说明	类型	默认值
sticks	摇杆配置数组	JoyStickItem[]	[]

JoyStickItem 配置项

属性名	说明	类型
name	摇杆名称，用于区分多个摇杆	string
x	摇杆 X 坐标	number
y	摇杆 Y 坐标	number
joySize	摇杆整体尺寸	number
compassSize	指南针背景尺寸	number
ballSize	控制球尺寸	number
arrow	箭头图片路径	string
compass	指南针图片路径	string
pokeBall	控制球图片路径	string
arrowReset	松开后箭头是否复位	boolean
ballReset	松开后球是否复位	boolean

Events

事件名	说明	回调参数
change	摇杆状态变化时触发	{ name: string, angle: number, distance: number }