虚拟摇杆使用指导
一个圆形摇杆，手指拖动摇杆头控制方向。它有两种用法：
- 遥控小车、机械臂：用方向改变时（方向）（
DirectionChanged）事件。方向（上、下、左、右，8 方向时还有斜向，松手为「中间」）只在变化时触发一次，直接按方向发蓝牙指令，不会刷屏； - 游戏：用位置改变时（x坐标，y坐标）（
PositionChanged）事件或读 X坐标、Y坐标。取值在 -1 到 1 之间，右、上为正，推得越远数值越大。
摇杆是独立组件，放在任意布局里即可；做画布游戏时放在画布下方。
快速上手：蓝牙遥控小车
方向数设为 4，先用蓝牙客户端连上小车（如 HC-05 模块），小车程序约定 F 前进、B 后退、L 左转、R 右转、S 停车：
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 虚拟摇杆1.DirectionChanged(方向) {
if 蓝牙客户端1.IsConnected {
if 方向 == "上" {
蓝牙客户端1.SendText("F")
} else if 方向 == "下" {
蓝牙客户端1.SendText("B")
} else if 方向 == "左" {
蓝牙客户端1.SendText("L")
} else if 方向 == "右" {
蓝牙客户端1.SendText("R")
} else {
蓝牙客户端1.SendText("S")
}
}
}
松手时摇杆自动回中，触发一次「中间」，小车随即停下。
画布游戏：摇杆控制角色
计时器每 30 毫秒按摇杆位置移动精灵。画布的 y 轴向下，摇杆的 y 向上为正，所以纵向用减法：
when 计时器1.Timer() {
图像精灵1.X = 图像精灵1.X + 虚拟摇杆1.X * 8
图像精灵1.Y = 图像精灵1.Y - 虚拟摇杆1.Y * 8
}
摇杆叠在画布上方
想让摇杆浮在游戏画面上（手机游戏常见的左下角摇杆），用悬浮窗：
把摇杆放进一个水平布局 水平布局_摇杆（设计器里可以把它设为不可见），悬浮窗的可拖动设为假，
否则拖摇杆时会把整个悬浮窗拖走：
when Screen1.Initialize() {
悬浮窗1.Draggable = false
悬浮窗1.StartPosition = "左下"
悬浮窗1.ShowComponent(水平布局_摇杆)
}
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：松手归零
放虚拟摇杆和标签。AutoCenter 为真时松手回中心，用 Released 事件处理停止动作。
when Screen1.Initialize() {
虚拟摇杆1.AutoCenter = true
虚拟摇杆1.DeadZone = 0.1
}
when 虚拟摇杆1.PositionChanged(x坐标, y坐标) {
标签1.Text = join("X=", x坐标, "，Y=", y坐标)
}
when 虚拟摇杆1.Released() {
标签1.Text = "已松手，停止移动"
}
X、Y 在 -1 到 1 范围内，向右和向上为正。死区用于过滤中心附近的小幅抖动；控制真实设备时也要发送停止指令。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
角度（Angle） |
当前推动的角度（度），0 为正右、90 为正上，逆时针增加；在中间时为 0。 |
松手回中（AutoCenter） |
松手后摇杆自动回到中间（默认真）；为假时停在松手的位置（如油门）。 |
底盘颜色（BaseColor） |
底盘颜色，默认半透明灰。 |
死区（DeadZone） |
死区：推动力度小于它时方向算「中间」（防手抖），0 到 0.9，默认 0.2。 |
方向（Direction） |
当前方向：上、下、左、右（8 方向时还有左上等），在死区内为「中间」。 |
方向数（Directions） |
方向数：4（上下左右）或 8（再加斜向），默认 8。 |
距离（Distance） |
当前推动的力度，0（中间）到 1（推到边缘）。 |
摇杆颜色（KnobColor） |
摇杆头颜色，默认蓝色。 |
尺寸（Size） |
摇杆底盘的直径（像素），默认 140。 |
X坐标（X） |
当前横向位置，-1（最左）到 1（最右）。 |
Y坐标（Y） |
当前纵向位置，-1（最下）到 1（最上）。 |
方向改变时（方向）（DirectionChanged） |
方向改变时触发一次：上、下、左、右（8 方向时还有左上、右上、左下、右下），回到死区内为「中间」。遥控小车直接按方向发指令用它。 |
位置改变时（x坐标，y坐标）（PositionChanged） |
摇杆位置改变（拖动中连续触发，松手回中时也触发一次 0,0）。x、y 在 -1 到 1 之间，右、上为正。 |
被压紧时（Pressed） |
手指按下摇杆。 |
被松开时（Released） |
手指松开摇杆。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在、编号和索引是否在范围内。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
不用蓝牙设备即可测试真实摇杆坐标、角度、方向和按压事件。上方固定触摸区，下方独立滚动控制区；界面只显示硬件指令建议，不伪装设备连接或发送成功。
导入 JoystickAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| Pressed、PositionChanged、DirectionChanged、Released | 在上方摇杆区按下、拖动四个方向、斜向、松手 | 按压与坐标反馈；方向仅改变时更新，松手有真实事件 |
| X、Y、Angle、Distance、Direction | 推向右边、上边、中心，观察事件和属性 | 右与上为正，中心距离0，角度0右90上；输入不伪造 |
| AutoCenter | 关闭回中，拖动松手；再开启并触摸松手 | 关闭保留位置，开启真实回中心；停止按钮不伪造归零事件 |
| Directions、DeadZone、Size | 4/8方向、0.2死区、180直径，应用参数 | 实际配置读回；死区防抖；直径同步方形宽高 |
| BaseColor、KnobColor | 切换颜色 | 底盘、摇杆头颜色读回并更改 |
| Visible、Left、Top、Width、Height、WidthPercent、HeightPercent | 下方控制隐藏并恢复、像素和百分比设置 | 外部控件可用；任意尺寸示例用于测试布局，常规推荐宽高等于直径 |
| 设计器属性 | 查看设计器初始4方向、非回中及颜色；初始化运行 | 运行默认8方向、回中，所有设计器项及代码读写可查看 |
| 遥控建议 | 拖向上下左右 | 显示F/B/L/R/S建议；未连接设备不会声称发送成功 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
虚拟摇杆遥控
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 不用蓝牙设备即可测试真实摇杆坐标、角度、方向和按压事件。上方固定触摸区，下方独立滚动控制区；界面只显示硬件指令建议，不伪装设备连接或发送成功。 覆盖检查 42/42。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
