# t-joystick

Joystick 摇杆

t-joystick 组件介绍

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

t-joystick 平台兼容

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

t-joystick 基础用法

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

<template>
	<view class="h-100% bg-#000!">
		<t-joystick class="twh-100%"
					@change="onJoystickChange"
					:sticks="sticks"></t-joystick>
	</view>
</template>
<script setup>
	import { JoyStickItem } from '@/uni_modules/tui-common'

	// 定义多个摇杆
	const sticks = ref<JoyStickItem[]>([
		{
			name: 'leftjoy',//摇杆名称
			x: 50,           // 左边摇杆
			y: 50,
			arrow: '/static/joystick/arrow.png',
			compass: '/static/joystick/compass.png',
			pokeBall: '/static/joystick/poke-ball.png',
			joySize: 200,
			arrowSize: 200,
			compassSize: 160,
			ballSize: 50,
			transition: false,
			arrowReset: false, // 指示箭头结束是否复位
			ballReset: false //中间小球结束是否复位
		},
		{
			name: 'leftjoy1',//摇杆名称
			x: 80,          // 右边摇杆
			y: 300,
			arrow: '/static/joystick/arrow.png',
			compass: '/static/joystick/compass.png',
			pokeBall: '/static/joystick/poke-ball.png',
			joySize: 150,    // 不同大小
			arrowSize: 150,
			compassSize: 120,
			ballSize: 40,
			transition: false,
			arrowReset: true, // 指示箭头结束是否复位
			ballReset: true //中间小球结束是否复位
		}
	])
	function onJoystickChange(e : UTSJSONObject) {
		console.log(`摇杆 ${e.name} 角度: ${e.angle}°, 力度: ${e.distance}`);

		// 根据角度判断方向
		const angle = e.getNumber('angle')!
		if (angle > 45 && angle < 135) {
			console.log('向右移动');
		} else if (angle > 135 && angle < 225) {
			console.log('向下移动');
		} else if (angle > 225 && angle < 315) {
			console.log('向左移动');
		} else {
			console.log('向上移动'); // 包括 0° 和接近 360°
		}

		// 若需要速度控制，可结合 distance 使用
	}
</script>

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

t-joystick Events

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