更新记录

1.0.0（2026-03-06）

游戏手柄、虚拟摇杆组件，安卓、iOS、鸿蒙三端都支持，支持纯色/图片样式与方向事件

平台兼容性

uni-app x(3.6.17)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - √ √ √ -

其他

多语言 暗黑模式 宽屏模式
√ × √

ba-game-ctrl-u

UTS 虚拟摇杆组件（uni-app-x），拖动摇杆松手回弹，支持纯色/图片样式与自定义颜色。

平台支持

  • uni-app-x：App（Android / iOS / Harmony）

基本用法

<template>
  <ba-game-ctrl-u
    :size="140"
    @direction="onDirection"
  />
</template>

<script setup lang="uts">
function onDirection(e) {
  const dir = e.direction   // 方向：up/down/left/right/up_left/up_right/down_left/down_right/center
  const state = e.state     // 状态：down（按下）/ up（抬起）
}
</script>

属性 (Props)

属性 类型 默认值 说明
size Number 120 摇杆区域边长（px），正方形
baseImage String '' 底座图片地址，如 /static/joystick_base.png；传空则仅用 baseStyle 样式
stickImage String '' 摇杆钮图片地址，如 /static/joystick_knob.png；传空则仅用 stickCustomStyle 样式
baseStyle Object {} 底座自定义样式（backgroundColor、borderWidth、borderColor 等）
stickCustomStyle Object {} 摇杆钮自定义样式（同上）

说明：uni-app-x 的 view 不支持 background-image: url()，故底座/摇杆背景图需通过 baseImage / stickImage 传入，由组件内 <image> 渲染。纯色或边框等仍可用 baseStyle / stickCustomStyle 动态设置。

事件 (Events)

事件名 payload 说明
direction { direction, state } 方向或状态变化时触发。direction：up/down/left/right/up_left/up_right/down_left/down_right/center；state：down（按下）/ up（抬起）

样式与图片示例

纯色 + 动态颜色：

<ba-game-ctrl-u
  :size="140"
  :base-style="{ backgroundColor: 'rgba(26,26,46,0.85)', borderWidth: '1px', borderColor: 'rgba(255,255,255,0.25)' }"
  :stick-custom-style="{ backgroundColor: 'rgba(232,232,232,0.95)', borderWidth: '1px' }"
  @direction="onDirection"
/>

图片样式（两套可切换）：

<ba-game-ctrl-u
  :size="140"
  base-image="/static/joystick_base_hok.png"
  stick-image="/static/joystick_knob_hok.png"
  :base-style="{ backgroundColor: 'transparent', borderWidth: '0px' }"
  :stick-custom-style="{ backgroundColor: 'transparent', borderWidth: '0px' }"
  @direction="onDirection"
/>

将对应底座/摇杆图放入项目 static 目录即可；可在调用页用变量切换不同图片路径实现多套皮肤。

参考

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。