← 返回悬浮窗组件参考 · 全部使用指导

悬浮窗使用指导

• 悬浮窗使用指导
  • 快速上手：应用内悬浮按钮
  • 避开底部 Tab 栏：独立设置两个间距
  • 将一个布局显示为悬浮窗口
  • 桌面悬浮计时器
  • 搭建与测试
  • 属性、方法与事件速查
  • 常见问题与验收
  • 完整 .aia 源码与操作指导
    • 悬浮球与工具窗口
  • 操作顺序

不可见组件，一个组件支持两种显示方式：

两种方式共用可拖动、初始位置、水平间距、垂直间距和启用阴影属性。再次显示另一种方式会替换当前悬浮内容，不会额外叠加一个窗口。默认不启用阴影。

两种浮法，由在其它应用上层（OverOtherApps）属性决定：

浮起来的布局里的按钮、标签照常可以点、可以改文字；关闭（Close）后布局放回原来的位置。 布局里有要拖动的组件（虚拟摇杆、滑动条等）时，把可拖动设为假，否则拖它们会把整个悬浮窗拖走—— 游戏里把摇杆叠在画布上方就是这样做的，见摇杆叠在画布上方。 本组件合并了第三方拓展 FloatActionBtn 与 FloatingView 的常用功能。

快速上手：应用内悬浮按钮

拖一个悬浮窗到屏幕，不用改任何属性，屏幕打开时显示悬浮按钮，点它弹出提示：

各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。

when Screen1.Initialize() {
  悬浮窗1.ShowButton()
}

when 悬浮窗1.Click() {
  对话框1.ShowAlert("点了悬浮按钮")
}

避开底部 Tab 栏：独立设置两个间距

设计器属性里直接设置水平间距和垂直间距，二者独立，默认均为 16；不再提供把 X、Y 一起修改的旧“边距”。例如 Tab 栏高 64，希望空隙 16，就把垂直间距设为 80，水平间距保持 16。

在屏幕放 悬浮窗1 和非可视的 对话框1，使用下面完整代码；它与上面的快速上手是独立案例：

when Screen1.Initialize() {
  悬浮窗1.HorizontalMargin = 16
  悬浮窗1.VerticalMargin = 80
  悬浮窗1.ShadowEnabled = false
  悬浮窗1.StartPosition = "右下"
  悬浮窗1.ShowButton()
}

when 悬浮窗1.Click() {
  对话框1.ShowAlert("这是圆形悬浮球")
}

验证：悬浮球右侧离内容区边缘 16，底部离内容区边缘 80；只改垂直间距，左右位置不变。拖动或调用移动到指定位置时也不能进入预留区域。初始位置改左上时，相同两项控制左侧与顶部距离。间距单位与设计器组件尺寸一致，随屏幕密度缩放；间距太大时会对称缩小有效边界，优先保证窗口可见。

显示中修改间距会立即把越界部分移回允许区域，修改启用阴影也立即生效。屏幕旋转、浮窗自身尺寸变化时重新限制位置。系统悬浮模式沿用相同间距规则，但操作系统的状态栏、导航区和权限仍由系统管理；它不会自动检测你的 App 的 Tab 高度，请填写实际需避开的高度。

将一个布局显示为悬浮窗口

1. 放 悬浮窗1；不勾选在其它应用上层，先测试本应用内。
2. 放竖直布局 竖直布局_浮窗，宽 180、高自动、背景白色、可见为假；里面放标签（文本“工具面板”）和按钮 按钮_关闭（文本“关闭”）。
3. 使用本节完整代码，不与其它例子的初始化事件叠加：

when Screen1.Initialize() {
  悬浮窗1.HorizontalMargin = 16
  悬浮窗1.VerticalMargin = 80
  悬浮窗1.ShadowEnabled = false
  悬浮窗1.ShowComponent(竖直布局_浮窗)
}

when 按钮_关闭.Click() {
  悬浮窗1.Close()
}

验证：浮起来的是整个工具面板，不是圆球；内部关闭按钮可以点，关闭后原布局恢复原来的隐藏状态。把上方代码中的启用阴影设为真再运行（或删掉该赋值、在设计器中勾选启用阴影），观察面板边缘的阴影；球形示例开启阴影时则沿圆球边缘显示。这里的开关控制悬浮窗组件增加的阴影；布局或子组件自己设置的阴影需在对应组件里设置。

桌面悬浮计时器

1. 放一个水平布局（改名 水平布局_计时），里面放一个标签 标签_计时，布局设背景色、把它的可见设为假（平时不占位置）；
2. 悬浮窗的在其它应用上层勾选为真；再放一个计时器；
3. 第一次需要用户授权悬浮窗权限，授权后回到应用会触发「悬浮窗权限结果」：

global seconds = 0

when 按钮_开始.Click() {
  if 悬浮窗1.HasOverlayPermission() {
    悬浮窗1.ShowComponent(水平布局_计时)
  } else {
    悬浮窗1.RequestOverlayPermission()
  }
}

when 悬浮窗1.OverlayPermissionResult(已授权) {
  if 已授权 {
    悬浮窗1.ShowComponent(水平布局_计时)
  } else {
    对话框1.ShowAlert("没有悬浮窗权限，无法在桌面显示")
  }
}

when 计时器1.Timer() {
  seconds = seconds + 1
  标签_计时.Text = join("⏱ ", seconds, " 秒")
}

when 按钮_停止.Click() {
  悬浮窗1.Close()
}

回到桌面，计时小窗仍然浮在上面，可以拖到任意位置。

记住拖动后的位置：拖动结束时把坐标存进微数据库，下次显示后移回去：

when 悬浮窗1.Moved(x坐标, y坐标) {
  微数据库1.StoreValue("fw_x", x坐标)
  微数据库1.StoreValue("fw_y", y坐标)
}

when Screen1.Initialize() {
  悬浮窗1.ShowButton()
  悬浮窗1.MoveTo(微数据库1.GetValue("fw_x", 300), 微数据库1.GetValue("fw_y", 500))
}

搭建与测试

在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。

可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。

属性、方法与事件速查

完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。

常见问题与验收

完整 .aia 源码与操作指导

下载 .aia 源码

一个工程测试圆形悬浮球和真实布局工具窗口：独立横纵间距、阴影、拖动、坐标、素材图标及权限。默认只在本应用内显示，不弹跨应用授权；鸿蒙系统不支持跨应用悬浮，界面和文档明确反馈。

导入 FloatingWindowAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

悬浮球与工具窗口

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 一个工程测试圆形悬浮球和真实布局工具窗口：独立横纵间距、阴影、拖动、坐标、素材图标及权限。默认只在本应用内显示，不弹跨应用授权；鸿蒙系统不支持跨应用悬浮，界面和文档明确反馈。 覆盖检查 44/44。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

操作顺序

初次运行应显示本应用内的圆形加号球，底部预留80、右侧预留16。修改配置时会先关闭，点击“显示球”或“显示工具窗口”应用新模式；不要把关闭后的Showing=false当成故障。

阴影默认关闭。勾阴影后应用、再显示；两个间距独立修改。横纵坐标可能被允许边界夹紧，以实际读回为准。关闭拖动适合窗口里有滑块／摇杆的场景。工具布局原本隐藏，关闭浮窗后恢复隐藏，计数文本仍保留。

安卓跨应用测试请编译独立安装：先申请权限，在系统设置允许，回来查看实际权限，勾跨应用、应用，再显示；拒绝则不能显示。鸿蒙HasOverlayPermission与权限结果均为假，跨应用显示应报告不支持，可取消该开关回到应用内模式继续测试。没有将不支持的系统能力包装成成功。

图标ball.png复制自仓库aiplayapp/assets/share.png，不修改图片字节。默认加号时才测试IconColor。