• 界面高级组件
  • 应用工具
    • 快速上手：引导好评
    • 打开微信，没装就提示
    • 权限被拒后引导去设置
    • 方法
    • 平台说明
  • 自动完成
    • 快速上手
    • 常见问题
    • 属性
    • 事件
    • 方法
  • 组件动画
    • 快速上手
    • 属性
    • 事件
    • 方法
  • 组件美化
    • 快速上手
    • 属性
    • 事件
    • 方法
  • 设备信息
    • 快速上手
    • 属性
    • 事件
    • 方法
    • 平台说明
  • 动态组件
    • 要点
    • 快速上手：按数据生成一排按钮
    • 用模板一次创建一张卡片
    • 属性
    • 事件
    • 方法
    • 平台说明
  • 悬浮窗
    • 快速上手：应用内悬浮按钮
    • 桌面悬浮计时器
    • 属性
    • 事件
    • 方法
    • 平台说明
  • 虚拟摇杆
    • 快速上手：蓝牙遥控小车
    • 画布游戏：摇杆控制角色
    • 摇杆叠在画布上方
    • 属性
    • 事件
    • 通用位置与尺寸属性
  • 本地通知
    • 快速上手：喝水提醒与会议提醒
    • 进度通知
    • 媒体通知：锁屏和通知栏控制播放
    • 常见问题
    • 属性
    • 事件
    • 方法
    • 平台说明
  • 滑动菜单
    • 快速上手：底部分享面板
    • 侧边抽屉（侧滑菜单）
    • 常见问题
    • 属性
    • 事件
    • 方法
  • 隐私政策
    • 快速上手
    • 属性
    • 事件
    • 方法
  • 二维码生成
    • 快速上手
    • 属性
    • 事件
    • 方法
  • 评分条
    • 快速上手：提交评价
    • 属性
    • 事件
    • 通用位置与尺寸属性
  • 屏幕控制
    • 快速上手：阅读页常亮 + 浅色系统栏
    • 沉浸式状态栏
    • 截图
    • 常见问题
    • 属性
    • 事件
    • 方法
  • 设置页
    • 属性
    • 事件
    • 方法
    • 位置与尺寸属性
  • 开屏动画
    • 快速上手
    • 属性
    • 事件
    • 方法
  • 下拉刷新
    • 快速上手
    • 常见问题
    • 属性
    • 事件
    • 方法

« 返回首页

界面高级组件

目录：

1. 应用工具 指导
2. 自动完成 指导
3. 组件动画 指导
4. 组件美化 指导
5. 设备信息 指导
6. 动态组件 指导
7. 悬浮窗 指导
8. 虚拟摇杆 指导
9. 本地通知 指导
10. 滑动菜单 指导
11. 隐私政策 指导
12. 二维码生成 指导
13. 评分条 指导
14. 屏幕控制 指导
15. 设置页（SettingsList） 指导
16. 开屏动画 指导
17. 下拉刷新 指导

应用工具

不可见组件：和手机上的其它 App、应用市场、系统设置打交道的常用小工具：

• 跳应用市场：打开本应用（或指定 App）在应用市场的详情页，引导用户评分、下载；
• 检测 / 打开其它 App：判断微信、支付宝等是否已安装，按包名打开；
• 打开链接：网址用浏览器打开，weixin://、alipays://、tel: 等链接交给对应 App；
• 打开系统设置：本应用的设置页、通知设置页——用户拒绝了权限或关掉了通知后，引导他去手动开启；也能打开系统设置、网络设置；
• 剪贴板：复制文本到系统剪贴板、读出剪贴板里的文本，与其它 App 互通；
• 桌面快捷方式：在手机桌面添加一个打开本应用的图标，可自定义名称和图标；
• 返回桌面 / 退出应用：应用退到后台，或彻底结束进程；
• 本应用信息：版本名、安装来源（哪个应用商店装的）、是否第一次运行（首次打开弹引导）。

使用指导引导好评、打开其它 App、去设置开权限、复制粘贴、识别口令、添加桌面快捷方式、首次启动引导的完整案例查看 →

快速上手：引导好评

when 按钮_好评.Click() {
  应用工具1.OpenAppMarket("")
}

包名留空表示本应用。应用要先在应用市场上架，详情页才打得开。

打开微信，没装就提示

when 按钮_微信.Click() {
  if 应用工具1.IsAppInstalled("com.tencent.mm") {
    应用工具1.OpenApp("com.tencent.mm")
  } else {
    对话框1.ShowAlert("请先安装微信")
  }
}

权限被拒后引导去设置

用户点了「拒绝」后，再申请系统也不会弹窗了，只能让用户去设置页手动打开：

when Screen1.PermissionDenied(组件, 函数名称, 权限名称) {
  对话框1.ShowChooseDialog("需要这个权限才能继续，去设置里打开吗？", "权限被拒绝", "去设置", "取消", false)
}

when 对话框1.AfterChoosing(选择值) {
  if 选择值 == "去设置" {
    应用工具1.OpenAppSettings()
  }
}

方法

复制文本(文本)

把文本复制到系统剪贴板，可与其它应用互通。复制不弹提示，需要反馈时在积木里自己弹提示。

创建快捷方式(名称,图标)

请求在桌面创建一个打开本应用的快捷方式。名称为快捷方式显示的名字； 图标为素材文件名、本地路径或网络图片地址，留空使用应用图标（图标加载失败也回退应用图标，不阻断创建）。 返回 true 只代表已发起创建请求——Android 8.0 及以上和鸿蒙还需用户在系统确认框点「添加」； 返回 false 表示当前桌面或系统版本不支持固定快捷方式，或申请无法启动。有返回值，要接在「如果」或赋值里用。

获取安装程序()

获取本应用的安装来源，如应用商店包名（com.android.vending 是谷歌商店）； 直接安装 APK 返回 sideloaded。可用来区分商店渠道与直装用户。

获取版本名()

获取本应用的版本名（即工程里「应用版本名」属性设置的值）。

回首页()

返回手机桌面，应用退到后台但不结束进程（不像退出应用 那样杀进程）。做「退出登录回桌面」类功能时比直接退出更温和。

是否已安装(包名)

指定包名的 App 是否已安装（包名留空为本应用）。常用包名：微信 com.tencent.mm、支付宝 com.eg.android.AlipayGphone、QQ com.tencent.mobileqq； 鸿蒙上包名不同（如微信是 com.tencent.wechat）。

是否首次运行()

判断本应用是否第一次运行：第一次调用返回真并记录标记，之后返回假。 常用于「首次打开弹引导/欢迎语」；配合重置首次运行 可以在调试时反复触发首启逻辑。

打开应用(包名)

打开指定 App 的首页，没有安装时报错。

打开应用市场(包名)

打开应用市场里指定 App 的详情页，包名留空为本应用。安卓由手机自带的应用商店打开，没有商店时打开网页版；鸿蒙打开华为应用市场。

打开应用设置页()

打开本应用的系统设置页（权限、通知、存储等都在这里）。

打开链接(链接)

网址用浏览器打开；weixin://、alipays://、tel:10086 等链接由对应 App 打开。没有能打开它的 App 时报错。

打开通知设置页()

打开本应用的通知设置页，系统不支持时打开应用设置页。

粘贴文本()

读取剪贴板中的文本并返回；剪贴板为空或内容不是文本时返回空文本。App 在前台时才能读剪贴板。

重置首次运行()

清除首次运行标记，之后是否首次运行又会返回真。

关机()

彻底退出应用：结束当前界面并结束进程，下次打开是全新启动。 普通场景不建议滥用——Android 推荐让系统自己回收后台应用。

打开系统设置()

打开系统设置界面。

打开网络设置()

打开无线与网络设置界面；部分新系统不支持该页面时退回系统设置主页。

平台说明

• 安卓：用到「是否已安装」「打开应用」时，应用清单会声明能看到带桌面图标的其它 App（安卓 11 起必须声明才查得到），不需要受限的「查询所有应用」权限。
• 鸿蒙：「是否已安装」「打开应用」需要系统 5.0.2（API 14）及以上，更低版本一律当作未安装；通知设置页需要 API 18 及以上，更低版本打开应用信息页；桌面快捷方式需要 API 14 及以上，返回真表示已开始申请，最终添加需要用户确认；申请失败会触发屏幕的「发生错误时」事件； 获取安装程序：应用市场装的返回来源包名，直接安装的 HAP 返回 sideloaded。

自动完成

不可见组件：给文本输入框加上下拉联想——输入时在框下方弹出匹配的候选词，点一下自动填入。 常用于搜索框、城市/商品名输入、历史记录提示。

功能参照 ColinTree 的 AutoCompleteBox 拓展。内置版不替换原输入框， 只在它下方挂一个候选列表，输入框自身的属性和事件都照常可用；一个组件可以同时管理多个输入框。 默认「包含即匹配」（输入「京」能匹配「北京」），可改为只匹配开头。

鸿蒙（HarmonyOS）端目前不弹出下拉候选框：组件可正常使用、项目照常运行，只是没有联想效果。

使用指导城市输入、搜索历史、省市联动、联网搜索建议的完整案例查看 →

快速上手

1. 拖一个文本输入框、一个标签和一个自动完成到屏幕；
2. 搭下面的代码块：

when Screen1.Initialize() {
  自动完成1.SetSuggestions(文本输入框1, list("北京", "上海", "广州", "深圳", "南京", "东京"))
}

when 自动完成1.SuggestionSelected(文本输入框, 选择项) {
  标签1.Text = join("你选了：", 选择项)
}

运行后在输入框里打「京」，下方弹出「北京」「南京」「东京」；点「南京」，输入框自动填入，标签显示「你选了：南京」。

常见问题

属性

任意位置匹配

为真时候选词任意位置包含输入内容就算匹配（默认）；为假时只匹配开头。不区分大小写。

最多条数

最多显示几条候选词，默认 8。

起始字数

至少输入几个字才开始提示，默认 1。

事件

选中候选词时(文本输入框,选择项)

用户点了某个候选词时触发，候选词已自动填入该输入框。

方法

设置候选词(文本输入框,候选词)

给文本输入框设置候选词列表；再次调用会替换原来的候选词。

组件动画

用一个启动积木给任意可见组件播放动画：淡入淡出、滑入滑出、放大缩小、弹跳、抖动、旋转、翻转等 22 种。

动画只改变组件的显示效果（透明度、位移、缩放、旋转），不会让界面重新排版，大量组件同时播放也流畅。

使用指导22 种动画效果、连续播放与组合动画的完整案例查看 →

快速上手

拖一个组件动画和一个按钮到屏幕。点按钮时让按钮弹一下，动画结束后在标签里提示：

when 按钮1.Click() {
  组件动画1.Start(按钮1, "pop")
}

when 组件动画1.AnimationEnded(组件, 动画类型) {
  标签1.Text = join("播放完了：", 动画类型)
}

动画类型直接在积木的下拉菜单里选；时长、延迟、重复次数、往返和速度曲线在属性面板里设。

属性

自动往返

重复时是否倒放回起点。做持续呼吸、摇摆效果时可开启；重复次数为 0 时没有影响。

显示时长

一次动画的时长，单位毫秒，默认 500。取值会限制在 0 到 60000 之间。

缓动方式

速度变化方式，可选标准、匀速、加速、减速、回弹和弹跳。通常保持“标准”即可。

重复次数

首次播放结束后额外重复的次数，默认 0。例如填 2，总共播放三次。

开始延迟

动画开始前的等待时间，单位毫秒。

事件

动画结束时(组件,动画类型)

动画完整播放结束时触发；主动停止不会触发本事件。

方法

正在播放动画(组件)

组件当前是否正在播放动画（等待延迟也算正在播放）。

复位(组件)

停止动画，并把组件恢复到第一次播放动画前的位置、透明度、缩放和旋转状态。

开始(组件,动画类型)

在组件上播放所选动画。同一组件已有动画时会自动停止旧动画。动画类型直接从下拉菜单选择。

停止(组件)

停止组件正在播放的动画，组件停在当前画面。

组件美化

不可见工具组件：给组件添加圆角、边框、渐变背景、卡片阴影、字体和行距字距，也可注册、取消点击事件；按钮等组件原有的点击事件仍会触发。

卡片样式在设计器属性里设一次，设为卡片只传布局；背景色、圆角、边框先后设置互不覆盖；颜色参数传列表（一个颜色为纯色，两个以上为渐变）。 另外还能给标签、图像、布局等原本没有点击事件的组件加上点击事件（设置可点击）， 以及把组件背景设为透明（设置透明）。

使用指导组件美化工具：添加圆角、边框、渐变背景、卡片样式、字体和行间距；还可为标签、图像、布局等组件注册和取消点击事件，按钮等组件原有的点击事件仍会触发查看 →

快速上手

界面：拖入 垂直布局1，在里面放 标签1 和 按钮1；再拖一个组件美化（默认名 组件美化1）。

代码块：屏幕打开时把布局变成白底圆角卡片、按钮换成蓝色渐变圆角，并让标签可以点击。卡片的颜色、圆角、边距用组件美化的默认属性（白底、圆角 14），想统一改就在设计器里改组件美化的「卡片」属性。

when Screen1.Initialize() {
  组件美化1.SetAsCard(垂直布局1)
  组件美化1.SetBgColor(按钮1, list(&HFF42A5F5, &HFF1E88E5), 0)
  组件美化1.SetRoundCorner(按钮1, 24)
  组件美化1.SetClickable(标签1)
}

when 组件美化1.ComponentClicked(组件) {
  if 组件 == 标签1 {
    标签1.Text = "点了标签"
  }
}

运行效果：布局变成带阴影的白色圆角卡片，按钮是左浅右深的蓝色渐变圆角按钮；点标签，标签文字变成「点了标签」。

要点：

• 所有卡片的样式在设计器里统一设：卡片背景色、圆角、边框宽度与颜色、内边距、外边距、阴影，长度单位都是 dp；设为卡片只需要传布局。个别卡片要不一样，在它之后再用设置圆角、设置内边距单独调。
• 背景色、圆角、边框先后顺序无关：先设圆角再设背景色，圆角不会丢。
• 设置背景色的颜色列表只放一个颜色就是纯色；最后一个参数是渐变方向（0 左到右、6 上到下）。
• 多个组件都要点击时，都用设置可点击注册，在同一个点击事件里用「组件 = 某组件」区分。

属性

卡片边框颜色

设为卡片用的边框颜色，卡片边框宽度大于 0 时生效。默认浅灰 #E2E8F0。

卡片边框宽度

卡片的边框宽度，单位 dp，默认 0（无边框）。

卡片背景色

卡片的背景色，默认白色。

卡片阴影

卡片的阴影高度，单位 dp，默认 2；0 为无阴影。

卡片外边距

卡片四周与相邻组件的距离，单位 dp，默认 10。

卡片内边距

卡片边缘到里面内容的距离，单位 dp，默认 14。

卡片圆角

卡片的圆角半径，单位 dp，默认 14。

事件

组件被点击(组件)

点击经注册点击注册过的组件时触发。组件 为被点击的组件本身，用「等于」和组件比较就知道点的是哪一个。

方法

取消点击注册(组件)

取消组件的点击注册。按钮等本来有点击事件的组件恢复原来的点击，其它组件恢复为不可点击。

卡片样式(布局)

把布局容器设置成卡片：背景色、圆角、边框、内边距、外边距、阴影都用组件美化的「卡片」属性（在设计器里设一次，所有卡片统一）。个别卡片想不一样，之后再用设置圆角、设置内边距等单独调整。

设置背景图片(组件,图片地址)

设置组件背景图片，图片拉伸铺满组件。图片地址 为素材文件名或本地路径。圆角和边框用设置圆角、设置边框设置，对图片背景同样生效，和先后顺序无关；之后再设置背景色会用颜色取代图片。

设置背景色(组件,颜色列表,渐变方向)

设置组件背景色或渐变背景。颜色列表 传颜色列表：单个颜色为纯色，两个及以上为渐变（从列表第一种渐变到最后一种）。渐变方向 取 0-7：0 左到右、1 左下到右上、2 下到上、3 右下到左上、4 右到左、5 右上到左下、6 上到下、7 左上到右下。已设置的圆角和边框保留；布局在设计器里设的背景图片会被新颜色取代。

设置边框(组件,边框宽度,边框颜色)

设置组件边框。边框宽度 单位 dp（0 去掉边框），边框颜色 为边框颜色。已有的背景色、渐变和圆角保留，和其它设置的先后顺序无关。

注册点击(组件)

为任意组件注册点击事件。标签、图片、布局等原本没有点击事件的组件，注册后点击时会触发组件被点击事件，事件参数就是被点击的组件本身。按钮等本来有点击事件的组件，原来的被点击事件照常触发。

设置阴影(组件,阴影高度)

设置组件阴影高度，单位 dp（需 Android 5.0 及以上）。

设置字体(组件,字体名称)

设置文本组件字体。字体名称 可直接写素材文件名（如 font.ttf），也支持 //font.ttf。本地文件使用绝对路径或 file:// 路径。只能用于标签、按钮、文本输入框等文本类组件。素材名须与素材列表中的名称一致，例如 playfair_display.ttf；文件位于素材根目录时，不要另加 /fonts/ 或 assets/ 前缀。伴侣联机与打包应用均使用同一素材名称。

设置字间距(组件,间距)

设置文本组件字间距，0 为默认值（需 Android 5.0 及以上）。

设置行间距(组件,间距)

设置文本组件的行间距增量，单位为像素。

设置外边距(组件,外边距)

设置组件外边距，四边同样大小，单位 dp。要求组件所在父布局支持外边距（AI2 的布局容器均支持）。

设置内边距(组件,内边距)

设置组件内边距，四边同样大小，单位 dp。

设置圆角(组件,半径)

设置组件圆角，四个角同样大小。半径 为圆角半径，单位 dp。已有的背景色、渐变和边框保留，和其它设置的先后顺序无关；布局容器在设计器里设的背景色也会保留。

设置背景透明(组件,是否透明)

设置组件背景是否透明。透明后下层内容（如屏幕背景图）可以透出来，常用于 WebView、布局容器等。是否透明 为真时透明（已设的圆角、边框保留）；为假时恢复设成透明之前的背景，包括布局在设计器里设的背景色和背景图片。

设备信息

不可见组件：查询设备与应用的常用信息，无需任何权限弹窗。

包括：WiFi IP 与网络类型、系统版本、手机型号、ANDROID_ID、系统语言、定位开关、飞行模式、 电量与电池详情。本应用的版本名、安装来源、是否首次运行，以及返回桌面、打开系统设置、退出应用见应用工具。 电量、飞行模式、网络类型变化时有对应事件。

原 PhoneInfo、手机电量、飞行模式、网络状态等拓展的常用功能都已并入本组件（AI2Utils 拓展的功能在应用工具），新项目无需再导入这些拓展。

使用指导电量、网络、系统版本等设备信息的完整案例查看 →

快速上手

拖一个设备信息到屏幕，屏幕打开时把网络和电量显示到标签上：

when Screen1.Initialize() {
  标签1.Text = join("网络：", 设备信息1.GetNetworkState(), "　电量：", 设备信息1.BatteryLevel(), "%")
}

when 设备信息1.NetworkStateChanged(状态) {
  标签1.Text = join("网络变成了：", 状态)
}

属性

无

事件

飞行模式变化时(状态)

飞行模式开关变化时触发，参数值为 开启 或 关闭。

电量变化时(电量,是否充电中)

电量百分比或充电状态发生变化时触发。系统电量广播很频繁（温度抖动也发）， 事件已按「电量百分比或充电状态真正变化」节流。

网络类型变化时(状态)

网络类型变化时触发，参数值同获取网络类型的返回值 （WIFI、2G、3G、4G、5G、未连接网络、未知网络）。

方法

电量()

返回当前电量百分比（0 到 100）；读取失败返回 -1。

电池温度()

返回电池温度，单位摄氏度；读取失败返回 0。

获取飞行模式()

获取飞行模式状态：开启 或 关闭。

获取ANDROID_ID()

获取 ANDROID_ID：应用可访问的设备标识。恢复出厂设置或部分多用户环境下会变化，它不是 IMEI 也不是硬件序列号，应用侧区分设备时优先用它。读取失败返回空文本。

获取安卓版本()

获取 Android 系统版本名，如 14、13。

获取网络类型()

获取当前网络类型：WIFI、2G、3G、4G、5G、未连接网络 或 未知网络。

获取手机型号()

获取手机型号，如 Pixel 8、Mi 14。

获取无线网络地址()

获取当前 WiFi 网络分配给本机的 IP 地址；未连接 WiFi 或获取失败时返回空文本。

是否充电中()

判断设备是否在充电（充电中，或已充满但仍接着电源）。

定位是否开启()

判断系统定位功能是否开启（GPS 或网络定位任一可用即算开启）。

WiFi是否连接()

判断当前是否通过 WiFi 联网。

SDK版本()

获取 Android SDK 级别（API Level，整数）。做系统版本判断时用它：如 SDK 级别 ≥ 33 是 Android 13。

系统语言()

获取系统默认语言代码，如 zh、en。

平台说明

鸿蒙（HarmonyOS）端积木写法完全相同，三个变化事件也都支持。个别返回值按鸿蒙系统取：

动态组件

不可见组件：在程序运行时创建组件——按钮、标签、布局……任何组件都可以，拓展组件也可以； 还能设置属性、调用方法、删除、调整顺序、移到别的布局，或用 JSON 模板一次创建一批。 适合组件个数由数据决定的界面：问卷的题目、购物车的商品、聊天气泡等。

本组件内化自第三方拓展 DynamicComponents（作者 Yusuf Cihan，MIT 许可证），积木与原拓展一致。

先看是不是用布局列表框更合适：只是「一行一条数据」的列表或网格，用布局列表框更省事， 数据绑定、点击事件都是现成的，而且滚动时组件会复用，数据再多也不卡。

使用指导动态组件：运行时按名字创建任意组件（按钮、标签、布局……也可以创建拓展组件），设置属性、调用方法、删除、调整顺序，或用 JSON 模板一次创建一批查看 →

要点

• 每个动态组件创建时给一个编号（文本，不能重复），之后用编号取回、删除它；不关心编号时用生成编号。
• 组件只能创建在布局（或画布）里，不能直接创建在屏幕上，所以先在设计器里放一个空的布局当容器。
• 组件类型写英文类型名，如 Button、Label、HorizontalArrangement；也可以传一个现有组件（创建同类型的新组件，拓展组件用这种办法）。
• 动态组件的事件用「任意组件」积木接：在代码块编辑器左侧「任意组件」里拖出如「任意按钮.被点击」， 事件参数 component 就是被点的那个按钮，再用取编号知道是哪一个。

快速上手：按数据生成一排按钮

设计器里放一个垂直布局 垂直布局_容器：

global fruits = ["苹果", "香蕉", "橙子"]

when Screen1.Initialize() {
  foreach name in fruits {
    动态组件1.Create(垂直布局_容器, "Button", name)
    动态组件1.SetProperty(动态组件1.GetComponent(name), "Text", join("买", name))
  }
}

when 按钮_清空.Click() {
  foreach name in fruits {
    动态组件1.Remove(name)
  }
}

这些按钮是运行时才有的，设计器里没有它们的「被点击」积木，用「任意按钮.被点击」接事件， component 就是被点的那个按钮，用取编号知道是哪一个（这里编号就是水果名）：

when any Button.Click(component, notAlreadyHandled) {
  var fruit = 动态组件1.GetId(component)
  if fruit != "" {
    标签1.Text = join("已加入购物车：", fruit)
    any Button(component).Enabled = false
  }
}

用模板一次创建一张卡片

模板是 JSON：components 里每个组件写 id、type、properties，可以用 components 嵌套子组件； keys 列出占位符，{名字} 会被参数列表里对应的值替换：

when 按钮_添加.Click() {
  动态组件1.Schema(垂直布局_容器, 文本输入框_模板.Text, [文本输入框_标题.Text])
}

文本输入框_模板 里的模板示例：

{
  "metadata-version": "1",
  "name": "card",
  "keys": ["title"],
  "components": [
    {"id": "card_{title}", "type": "HorizontalArrangement", "properties": {"BackgroundColor": "&HFFE3F2FD"},
     "components": [
       {"id": "label_{title}", "type": "Label", "properties": {"Text": "{title}", "FontSize": "18"}}
     ]}
  ]
}

属性

线程

创建组件的方式：UI（默认）排到界面线程上创建，大量创建时不卡住当前积木；Main 立即创建。鸿蒙一律立即创建。

版本

原拓展的版本号（11）。

版本名称

原拓展的版本名（2.3.1）。

事件

组件已创建(组件,编号,类别)

组件创建完成后触发：新组件、它的编号和类型名。

模板已创建(名称,参数列表)

按模板创建完成后触发。

方法

修改编号(编号,新编号)

把编号改成新编号。注意：所有包含旧编号的编号都会被替换（如把 Timmy 改成 Tom 时，Timmy-truck 也会变成 Tom-truck）。

创建(所在布局,组件类型,编号)

在布局里创建组件并登记编号，完成后触发组件已创建。编号重复会报错。

临时创建(所在布局,组件类型)

创建组件并直接返回，不登记编号。

立即创建(所在布局,组件类型,编号)

立即创建组件并返回它，同时登记编号；编号留空时自动生成。

生成编号()

生成一个随机的唯一编号。

取组件(编号)

按编号取回组件；找不到时返回空文本。

组件元数据(组件)

组件的类型、分类、描述等信息（字典）。

事件元数据(组件)

组件全部事件的信息（字典）。

方法元数据(组件)

组件全部方法的信息（字典）。

取编号(组件)

取组件的编号；不是动态创建的返回空文本。

取位置(组件)

组件在所在布局里的位置，从 1 开始。

取属性(组件,名称)

按属性名读属性值，值为空时返回空文本。

属性元数据(组件)

组件全部属性的信息和当前值（字典）。

调用方法(组件,名称,参数列表)

按方法名调用组件的方法，返回结果（为空时返回空文本）。

是否动态创建(组件)

组件是否由本组件创建。

最近用的编号()

最近一次创建组件用的编号。

移到布局(布局,组件)

把组件移到另一个布局里（排在最后）。

按编号删除(编号)

删除组件，编号随之注销，可以再用来创建新组件。

删除组件(组件)

删除一个组件（设计时放的组件也可以）；如果是动态创建的，同时注销编号。

替换编号(编号,新编号)

只把这一个编号换成新编号。

按模板创建(所在布局,模板,参数列表)

按 JSON 模板批量创建组件，完成后触发模板已创建。

设置位置(组件,索引)

设置组件在所在布局里的位置，从 1 开始；0 移到最后。

批量设属性(组件,属性字典)

用字典一次设置多个属性：键是属性名，值是属性值。

设属性(组件,名称,值)

按属性名设置属性，只能在设计器里设的属性也可以。

全部编号()

本组件创建的全部组件编号。

平台说明

• 安卓：与原拓展一致（基于 Java 反射），支持所有内置组件和已导入的拓展。内化时修了原拓展的三个问题： 「修改编号」一找到就崩溃、「按模板创建」必定崩溃、「属性元数据 / 事件元数据 / 方法元数据」读不出来。
• 鸿蒙：支持鸿蒙版已有的全部组件类型；一律立即创建；元数据来自组件描述，不含设计器编辑器细节。

悬浮窗

不可见组件，既可以显示圆形悬浮球（显示悬浮按钮），也可以把一个布局显示为悬浮窗口（悬浮显示组件）。内部按钮照常可点；两种方式共用阴影开关和独立的水平、垂直间距，默认不添加阴影。

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

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

使用指导一个组件既能显示圆形悬浮球，也能显示布局悬浮窗口；阴影开关与独立水平、垂直间距查看 →

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

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

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

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

桌面悬浮计时器

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))
}

属性

按钮颜色

悬浮按钮的底色，默认蓝色。

按钮大小

悬浮按钮的直径（像素），默认 56，最小 24。

可拖动

是否可以用手指拖动悬浮窗，默认为真。手指移动超过一小段距离才算拖动，所以浮起来的布局里的按钮照常能点。

图标

悬浮按钮上的图标图片（素材文件名）。留空时显示加号。

图标颜色

默认加号的颜色，默认白色；设置了图标图片时不起作用。

水平间距

左右边缘预留的距离，默认 16，与垂直间距独立。初始显示、拖动、移动到指定位置都会保留，显示中修改立即限制位置。单位与组件尺寸相同，随密度缩放。

垂直间距

上下边缘预留的距离，默认 16，与水平间距独立。设为底部 Tab 栏高度加期望空隙，可防止浮窗覆盖 Tab；拖动也保留，显示中修改立即限制位置。间距过大时会自动缩小有效边界，保证窗口可见。

启用阴影

默认假，不添加阴影；为真时圆形悬浮球和悬浮窗口均可显示阴影，Android 5.0 及以上支持，显示中修改立即生效。悬浮布局或子组件本身已有的阴影由对应组件控制。

在其它应用上层

为真时是系统悬浮窗，切到桌面或其它应用也一直显示，需要先获得悬浮窗权限（见申请悬浮窗权限）； 为假（默认）时只浮在本应用当前屏幕上方，不需要权限。显示中修改，要重新显示才生效。

显示中

悬浮窗是否正在显示。

初始位置

显示时摆在哪个角：右下（默认）、左下、右上、左上，左右距离由水平间距决定，上下距离由垂直间距决定。

X坐标

悬浮窗左上角的横坐标（像素）。设置它会移动悬浮窗。

Y坐标

悬浮窗左上角的纵坐标（像素）。设置它会移动悬浮窗。

事件

被点击时()

轻点悬浮按钮，或悬浮布局里没有被按钮等组件占用的地方时触发。拖动不算点击。

拖动结束时(x坐标,y坐标)

拖动结束时触发，参数是新位置左上角的坐标（像素）。

悬浮窗权限结果(已授权)

调用申请悬浮窗权限、用户从设置页回到应用后触发。

方法

关闭()

关闭悬浮窗。浮起来的布局放回原来的位置和顺序，并恢复原来的可见状态。

有悬浮窗权限()

是否已获得「显示在其他应用的上层」权限。只在在其它应用上层为真时需要。

移动到指定位置(x坐标,y坐标)

把悬浮窗移到指定位置（左上角坐标，像素），超出屏幕的部分会自动收回。

申请悬浮窗权限()

打开系统设置页，让用户允许本应用「显示在其他应用的上层」。已有权限时直接触发结果事件。

显示悬浮按钮()

显示圆形悬浮按钮（外观由按钮大小、按钮颜色、图标、图标颜色决定），位置由初始位置和边距决定。 已经在显示的内容会先关闭。

悬浮显示组件(组件)

把屏幕上的一个组件（通常是一个布局）浮起来显示。它会从原来的位置移进悬浮窗， 组件原本不可见也会被显示出来；关闭后放回原处并恢复原来的可见状态。

平台说明

• 安卓：两种浮法都支持。用到「申请悬浮窗权限 / 有悬浮窗权限」积木时，应用清单才会声明悬浮窗权限；只做应用内悬浮按钮的应用不会多出这个权限。
• 鸿蒙：只支持本应用内悬浮。鸿蒙不允许普通应用在其它应用上层显示悬浮窗，在其它应用上层为真时会报错并不显示。

虚拟摇杆

一个圆形摇杆，手指拖动摇杆头控制方向。它有两种用法：

• 遥控小车、机械臂：用方向改变事件。方向（上、下、左、右，8 方向时还有斜向，松手为「中间」）只在变化时触发一次，直接按方向发蓝牙指令，不会刷屏；
• 游戏：用位置改变事件或读 X坐标、Y坐标。取值在 -1 到 1 之间，右、上为正，推得越远数值越大。

摇杆是独立组件，放在任意布局里即可；做画布游戏时放在画布下方。

使用指导虚拟摇杆：手指拖动圆形摇杆，输出 -1 到 1 的 x、y 和上/下/左/右（可选 8 方向）查看 →

快速上手：蓝牙遥控小车

方向数设为 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(水平布局_摇杆)
}

属性

角度

当前推动的角度（度），0 为正右、90 为正上，逆时针增加；在中间时为 0。

松手回中

松手后摇杆自动回到中间（默认真）；为假时停在松手的位置（如油门）。

底盘颜色

底盘颜色，默认半透明灰。

死区

推动力度小于它时方向算「中间」（防手抖），0 到 0.9，默认 0.2。

方向

当前方向：上、下、左、右（8 方向时还有左上、右上、左下、右下），在死区内为「中间」。

方向数

4（上下左右）或 8（再加斜向），默认 8。遥控小车一般用 4。

距离

当前推动的力度，0（中间）到 1（推到边缘），可用来控制速度。

摇杆颜色

摇杆头颜色，默认蓝色。

尺寸

底盘直径（像素），默认 140。

可见性

是否显示摇杆。

X坐标

当前横向位置，-1（最左）到 1（最右）。

Y坐标

当前纵向位置，-1（最下）到 1（最上）。

事件

方向改变时(方向)

方向变化时触发一次；回到死区内为「中间」。遥控小车按方向发指令用它。

位置改变时(x坐标,y坐标)

拖动中连续触发，松手回中时也触发一次 0,0。x、y 在 -1 到 1 之间，右、上为正。

被压紧时()

手指按下摇杆。

被松开时()

手指松开摇杆。

通用位置与尺寸属性

高度

设置组件高度；可选自动、充满或固定值。

高度百分比

将高度设置为屏幕高度的指定百分比。

左侧位置

组件位于绝对布局时的横向位置。

顶部位置

组件位于绝对布局时的纵向位置。

宽度

设置组件宽度；可选自动、充满或固定值。

宽度百分比

将宽度设置为屏幕宽度的指定百分比。

本地通知

不可见组件：在手机顶部的通知栏发通知——普通通知（文字长时下拉可展开看全）、大图通知、 进度通知（下载/上传进度，反复调用即可更新）、带按钮的通知（如「知道了 / 稍后提醒」）。 用户点通知会回到 App 并触发被点击。App Inventor 原本没有通知功能。 还能显示媒体通知：通知栏和锁屏上的播放控制（歌名、歌手、封面、上一首 / 播放暂停 / 下一首）， 耳机和蓝牙按键也能控制，显示期间 App 退到后台继续播放。

每条通知用一个序号（整数）区分：同一序号再发就是更新原来那条，不同序号各占一条； 取消也按序号收起。 Android 13 及以上第一次发通知时会弹出授权提示，用户拒绝后通知发不出来，并触发屏幕的「权限被拒绝」事件。 本组件在 App 运行时发通知；App 被关掉后点通知按钮没有反应。要每天几点提醒、App 关着也到点弹通知，用定时任务。

使用指导定时提醒、带按钮与稍后提醒、进度通知、大图通知、点通知跳转、媒体通知的完整案例查看 →

快速上手：喝水提醒与会议提醒

1. 拖一个本地通知，两个按钮（改名 按钮_提醒、按钮_会议）和一个标签（改名 标签_结果）；
2. 搭下面的代码块：

when 按钮_提醒.Click {
  本地通知1.Show(1, "喝水提醒", "工作一小时了，起来喝杯水、活动一下吧")
}

when 按钮_会议.Click {
  本地通知1.ShowWithButtons(2, "会议提醒", "10 分钟后在三楼会议室开会", ["知道了", "稍后提醒"])
}

when 本地通知1.ButtonClicked(编号, 按钮) {
  标签_结果.Text = join("点了通知上的：", 按钮)
}

when 本地通知1.Clicked(编号) {
  标签_结果.Text = join("从第 ", 编号, " 条通知回到了 App")
}

运行后点「提醒」，通知栏出现一条喝水提醒；点「会议」出现带两个按钮的通知，点按钮后通知收起、标签显示点了哪个。

进度通知

下载、上传、批量处理时，用同一个序号反复调用显示进度通知更新进度； 进度没到最大值时通知不能划掉，到了最大值自动变成普通通知。下面用计时器模拟下载：

global 进度 = 0

when 按钮_下载.Click {
  进度 = 0
  计时器1.TimerEnabled = true
}

when 计时器1.Timer() {
  进度 = 进度 + 10
  本地通知1.ShowProgress(3, "正在下载", join("已完成 ", 进度, "%"), 进度, 100)
  if 进度 >= 100 {
    计时器1.TimerEnabled = false
  }
}

最大值传 0 时显示来回滚动的「不确定进度」，适合不知道总量的任务。

媒体通知：锁屏和通知栏控制播放

显示媒体通知在通知栏和锁屏显示歌曲名、歌手、封面和「上一首 / 播放暂停 / 下一首」按钮， 耳机、蓝牙耳机、车机的播放键也能控制；显示期间 App 退到后台、锁屏后也能继续播放，不会被系统停掉。 适合音乐、听书、播客、白噪音类 App。它只是「控制面板」，自己不放音，要配合音频播放器。

素材里放 a.mp3、b.mp3，音频播放器的「仅前台播放」保持不勾选。 设计器里把本地通知的播放器属性选成 音频播放器1（或像下面这样在屏幕初始化时用积木设置）： 通知栏、锁屏和耳机的播放 / 暂停就直接控制这个播放器，按钮图标也自动跟着它变，只需要处理切歌：

global songs = ["a.mp3", "b.mp3"]
global names = ["晴天", "七里香"]
global index = 1

procedure PlayCurrent() {
  音频播放器1.Source = songs[index]
  音频播放器1.Start()
  本地通知1.ShowMedia(names[index], "周杰伦", "")
}

when Screen1.Initialize() {
  本地通知1.Player = 音频播放器1
}

when 按钮_播放.Click() {
  PlayCurrent()
}

when 本地通知1.NextClicked() {
  index = choose(index >= length(songs), 1, index + 1)
  PlayCurrent()
}

when 本地通知1.PreviousClicked() {
  index = choose(index <= 1, length(songs), index - 1)
  PlayCurrent()
}

when 音频播放器1.Completed() {
  index = choose(index >= length(songs), 1, index + 1)
  PlayCurrent()
}

不播了（比如退出登录）调用关闭媒体通知，通知消失，后台保活随之结束。 不设播放器属性时，要自己在「播放被点击」「暂停被点击」里控制播放器，并用设置播放状态同步按钮图标。 媒体通知只有一条，和普通通知的序号互不影响；全部取消不会关掉它。

配合媒体信息：歌名、歌手、封面可以用媒体信息从音乐文件里读出来再交给「显示媒体通知」； 下载器下完的音乐文件同样可以直接读（用下载完成事件给出的文件路径）。

常见问题

属性

颜色

通知的强调色（小图标、按钮文字等处）。鸿蒙系统由系统决定，此属性不生效。

媒体通知显示中

媒体通知是否正在显示。

播放器

媒体通知绑定的音频播放器。设了以后，播放 / 暂停按钮（含锁屏、耳机）直接控制它，按钮图标自动跟随它的播放状态， 不用再写「播放被点击」「暂停被点击」和「设置播放状态」；事件仍会触发，可以追加自己的逻辑。

播放中

媒体通知当前是否为播放状态。

显示上一首下一首

媒体通知是否显示「上一首 / 下一首」按钮，默认为真；单曲、听书可以设为假。

小图标

状态栏小图标（素材文件，建议白色透明底的简单图形）；留空用系统通知图标。通知里的大图标固定用 App 图标。鸿蒙系统由系统决定，此属性不生效。

事件

按钮被点击(编号,按钮)

用户点击通知上的按钮时触发（通知随之收起），按钮是按钮文字。

被点击(编号)

用户点击通知回到 App 时触发，编号是通知序号。

下一首被点击()

用户点了媒体通知的「下一首」（通知栏、锁屏、耳机或蓝牙按键）。

暂停被点击()

用户点了媒体通知的「暂停」。

播放被点击()

用户点了媒体通知的「播放」。

上一首被点击()

用户点了媒体通知的「上一首」。

方法

取消(编号)

收起指定序号的通知。

全部取消()

收起本 App 发出的全部通知（媒体通知用关闭媒体通知）。

关闭媒体通知()

关闭媒体通知并结束后台保活。

设置播放状态(正在播放)

真在媒体通知上显示「暂停」按钮（正在播放），假显示「播放」按钮。在播放器开始或暂停后调用；设了播放器属性时自动跟随，不用调用。

显示(编号,标题,文本)

发一条普通通知，文字较长时下拉可展开看全。同一序号再发会更新原通知。

显示媒体通知(标题,艺术家,封面)

显示或更新媒体通知：歌曲名、歌手、封面图片（素材文件名或路径，可留空）。显示期间 App 退到后台也能继续播放。

显示进度通知(编号,标题,文本,进度,最大值)

发或更新一条进度通知。最大值为 0 时显示不确定进度；进度没到最大值时通知不能划掉，到了最大值变成普通通知。

显示带按钮通知(编号,标题,文本,按钮列表)

发一条带按钮的通知，最多 3 个按钮，用户点按钮触发按钮被点击。

显示带图通知(编号,标题,文本,图像位址)

发一条带大图的通知（下拉展开后显示图片），图片可以是素材文件名或本地路径。

平台说明

• 安卓：媒体通知显示期间运行媒体播放类前台服务（只有用到「显示媒体通知」的应用才会在清单里声明这项服务与权限）；安卓 5.0 以下只有通知栏按钮，没有锁屏和耳机控制。
• 鸿蒙：小图标与颜色由系统决定；进度通知按百分比显示。媒体通知接入系统播控中心（下拉通知栏、锁屏、耳机按键），显示期间申请音频播放类长时任务，退到后台继续播放。

滑动菜单

不可见组件：把屏幕上的一个布局装进弹出层显示——从底部滑出（分享面板、筛选条件、选择器）、 居中弹出当自定义对话框（登录框、确认页），或从左右两侧滑出当侧边抽屉（侧滑菜单）。原生对话框只能放文字， 滑动菜单里可以放任意组件：输入框、按钮、列表、图片都行，各组件的事件照常写。

用法三步：设计器里搭好一个布局当面板内容 → 屏幕初始化时设置内容 → 需要时显示/关闭。 「设置内容」会把这个布局从屏幕上挪进面板，不再占原来的位置；「显示」时自动让它可见。 所以面板布局在设计器里通常取消勾选「可见」，免得打开屏幕时一闪而过（设计器里勾选「显示隐藏组件」就能继续编辑它）。

使用指导滑动菜单：把一个布局从屏幕底部滑出显示、居中弹出当对话框，或从左右两侧滑出当侧边抽屉（侧滑菜单），面板里可以放任意组件查看 →

快速上手：底部分享面板

1. 拖一个按钮（改名 按钮_分享）和一个标签（改名 标签_结果）；
2. 拖一个垂直布局（改名 垂直布局_面板，宽度设为充满，取消勾选「可见」），里面放三个按钮： 按钮_微信、按钮_朋友圈、按钮_取消；
3. 拖一个滑动菜单（默认从底部滑出）；
4. 搭下面的代码块：

when Screen1.Initialize() {
  滑动菜单1.SetContent(垂直布局_面板)
}

when 按钮_分享.Click {
  滑动菜单1.Show()
}

when 按钮_微信.Click {
  标签_结果.Text = "已分享到微信"
  滑动菜单1.Hide()
}

when 按钮_朋友圈.Click {
  标签_结果.Text = "已分享到朋友圈"
  滑动菜单1.Hide()
}

when 按钮_取消.Click {
  滑动菜单1.Hide()
}

运行后点「分享」，面板从底部滑上来；点面板外面、按返回键或点「取消」都会收起。 把弹出方式改成 center 就变成居中的自定义对话框。

侧边抽屉（侧滑菜单）

模式设为 left（或 right），面板就从屏幕左侧（右侧）滑出，铺满高度、宽度为屏幕的 80%。 菜单内容自己搭：顶部放头像和昵称，下面放几个按钮当菜单项。

1. 拖一个垂直布局（改名 垂直布局_菜单，宽度充满，取消勾选「可见」），里面放一个标签（标签_昵称）和三个按钮 按钮_首页、按钮_收藏、按钮_设置；
2. 拖一个滑动菜单，模式选 left；再拖一个按钮（按钮_菜单）用来打开抽屉，一个标签（标签_结果）显示点了哪项；
3. 搭下面的代码块：

when Screen1.Initialize() {
  滑动菜单1.SetContent(垂直布局_菜单)
  标签_昵称.Text = "你好，小明"
}

when 按钮_菜单.Click {
  滑动菜单1.Show()
}

when 按钮_首页.Click {
  标签_结果.Text = "打开了首页"
  滑动菜单1.Hide()
}

when 按钮_设置.Click {
  标签_结果.Text = "打开了设置"
  滑动菜单1.Hide()
}

常见问题

关闭时播放打开动画的反向效果。点外面可关闭为真时，左侧菜单向左滑、右侧菜单向右滑、底部面板向下滑也能收回；短滑回弹，居中模式不使用滑动关闭。“已关闭”事件在关闭动画完成后触发。

属性

背景颜色

面板底色，默认白色。

点外面可关闭

点面板外面、按返回键或向外滑动是否关闭面板，默认真。为假时只能用关闭方法关闭，适合必须作答的面板。

圆角半径

面板圆角半径，默认 16。底部滑出时只有上面两个角是圆的。

模式

弹出方式：bottom 从底部滑出、铺满宽度（默认）；center 居中弹出，宽度为屏幕的 85%； left / right 从左侧 / 右侧滑出的侧边抽屉，铺满高度，宽度为屏幕的 80%。

显示中

面板当前是否显示着。

事件

已关闭()

关闭动画完成后触发：调用「关闭」、点面板外面、按返回键或向外滑动关闭都会触发。

已打开()

面板显示出来时触发。

方法

关闭()

播放反向动画关闭面板，结束后触发已关闭事件。

设置内容(布局)

指定面板里显示的布局（通常是一个垂直布局）。这个布局会从屏幕上挪进面板，不再占原来的位置；可以多次调用换成别的布局。

显示()

显示面板，并让内容布局可见。还没有「设置内容」时弹出错误提示。

隐私政策

不可见组件：应用首次启动时弹出隐私政策确认框，用户同意后记住选择、不再弹出；不同意可直接退出应用。

应用商店上架普遍要求「首次启动先征得隐私同意」，用这个组件一步完成。

使用指导隐私政策与隐私确认弹窗组件查看 →

快速上手

在 Screen1.Initialize 里调用一次显示即可——已经同意过的用户不会再看到弹窗：

when Screen1.Initialize() {
  隐私政策1.Show("https://example.com/privacy.html")
}

when 隐私政策1.OnAgreed() {
  标签1.Text = "已同意，进入应用"
}

用户同意后触发同意时；用户拒绝后触发拒绝时并退出应用。 内容可以是网址、素材文件名（如 privacy.html）、本地文件路径、HTML 或纯文本，组件自动识别。 测试时想重新看到弹窗，调用一次复位。 隐私政策页面应由应用开发者提供，内容应与应用实际收集、使用的数据保持一致。

属性

无

事件

同意时()

当用户同意隐私政策时触发。

隐私确认框关闭时(编号)

当隐私确认框关闭时触发。

点隐私确认继续时(编号)

当用户点击继续按钮时触发。

拒绝时()

当用户拒绝隐私政策时触发。

方法

是否已同意()

检查用户是否已经同意隐私政策。

复位()

清除「已同意」「已拒绝」的记录，下次调用显示会重新弹出隐私政策。

重置隐私确认(编号)

重置隐私确认框的显示状态

显示(内容)

显示隐私政策弹窗。内容 可以是网址、素材文件名、本地文件路径、HTML 或纯文本，自动识别。 已同意过则直接触发同意时；已拒绝过则直接触发拒绝时。

显示隐私确认对话框(编号,内容)

显示带「不再提示」选项的用途说明弹窗（如申请定位、相机权限前的说明）。 编号 用于分别保存不同用途的确认状态。

二维码生成

不可见组件：把一段文本（网址、名片、任意文字）生成二维码，直接显示在指定组件（图像、布局等）的背景上。

可以自定义二维码前景色和背景色；中文内容按 UTF-8 编码，主流扫码软件都能正确识别。

使用指导网址、名片、WiFi 连接二维码与彩色二维码的完整案例查看 →

快速上手

界面：拖入 文本输入框1、按钮1（文字改为「生成」）、标签1，以及一个 垂直布局1（宽、高都设为 250 像素，用来显示二维码）； 再拖一个二维码生成（默认名 二维码生成1）。

代码块：

when 按钮1.Click() {
  二维码生成1.GenerateQRCode(文本输入框1.Text, 垂直布局1)
}

when 二维码生成1.OnSuccess() {
  标签1.Text = "已生成，可以用手机扫一扫"
}

when 二维码生成1.OnError(消息) {
  标签1.Text = 消息
}

运行效果：输入网址或任意文字点「生成」，二维码显示在方形布局里；输入为空时标签提示错误原因。

要点：

• 二维码画在目标组件的背景上，所以目标组件要有固定的宽和高（正方形最佳）；用图像组件也可以，同样要设好宽高。
• 前景色、背景色用属性前景色、背景色设置，对比要足够大，否则扫不出来。

属性

前景色

二维码的前景色。

背景色

二维码的背景色。

事件

出错时(消息)

二维码生成失败时触发。

生成成功时()

二维码生成成功时触发。

方法

生成二维码(文本,组件)

生成二维码并显示在指定组件（布局、图像等）的背景上。

评分条

一排星星，用户点击或拖动打分（商品评价、服务满意度、问卷），也可以设为只读显示平均分（支持半星，比如 4.5 分）。 用户打完分后触发评分改变；在代码里设置评分不会触发。

使用指导评分条：一排星星，用户点击或拖动打分，也可设为只读用来显示平均分（支持半星）查看 →

快速上手：提交评价

when 评分条1.RatingChanged(评分) {
  标签1.Text = join("你打了 ", 评分, " 分")
}

when 按钮_提交.Click() {
  if 评分条1.Rating == 0 {
    对话框1.ShowAlert("请先打分")
  } else {
    Web客户端1.PostText(join("score=", 评分条1.Rating))
  }
}

显示平均分：只读勾选为真、步长设为 0.5，再把算好的平均分赋给评分，例如 评分条1.Rating = 4.5。

属性

未点亮颜色

未点亮星星的颜色，默认浅灰。

高度

评分条的高度，默认为星星大小。

星星个数

星星个数，1 到 10，默认 5。

评分

当前评分，0 到星星个数之间，按步长取整。代码里设置不触发「评分改变」。

只读

为真时只显示评分，用户不能改。

星星颜色

已点亮星星的颜色，默认琥珀色。

星星大小

每颗星星的大小（像素），默认 28。

步长

1 为整颗星（默认），0.5 可以打半星。

可见性

是否显示评分条。

宽度

评分条的宽度，默认按星星个数和大小自动确定。

事件

评分改变(评分)

用户点击或拖动改分、手指抬起后触发。分数没变不触发。

通用位置与尺寸属性

高度百分比

将高度设置为屏幕高度的指定百分比。

左侧位置

组件位于绝对布局时的横向位置。

顶部位置

组件位于绝对布局时的纵向位置。

宽度百分比

将宽度设置为屏幕宽度的指定百分比。

屏幕控制

不可见组件：保持屏幕常亮不自动熄灭，设置状态栏和底部导航栏（返回/主页键所在的系统栏）的颜色与图标深浅， 沉浸式状态栏（页面内容延伸到状态栏下方）、沉浸式全屏（隐藏状态栏和导航栏），以及屏幕截图。不需要任何权限。

常亮针对小米 MIUI/HyperOS 会悄悄清掉常亮标志的问题做了加固（回到前台和开启期间定时重新设置）。 各属性保持默认时不会改动屏幕原有的系统栏外观；隐藏状态栏用屏幕的「显示状态栏」属性。

使用指导常亮、系统栏配色、沉浸式状态栏与全屏、截图分享的完整案例查看 →

快速上手：阅读页常亮 + 浅色系统栏

1. 拖一个屏幕控制到屏幕，把屏幕背景设成白色；
2. 在设计器属性里勾选保持常亮，或者用代码块设置：

when Screen1.Initialize() {
  屏幕控制1.KeepScreenOn = true
  屏幕控制1.StatusBarColor = &HFFFFFFFF
  屏幕控制1.DarkStatusBarIcons = true
  屏幕控制1.NavigationBarColor = &HFFFFFFFF
  屏幕控制1.DarkNavigationBarIcons = true
}

运行后屏幕一直亮着；状态栏和底部导航栏变成白底，时间、电量和返回键变成深色，看得清。

沉浸式状态栏

页面顶部是大图或整块背景色时，打开沉浸式状态栏，内容会延伸到状态栏下方、 状态栏变透明。顶部要留出一段空白（约 24 像素高的布局），免得文字被时间、电量图标盖住。 图片偏亮时再给状态栏颜色设一个半透明深色（如 &H66000000）：

when Screen1.Initialize() {
  屏幕控制1.ImmersiveStatusBar = true
  屏幕控制1.StatusBarColor = &H66000000
}

截图

调用截图把当前屏幕保存为图片，保存好后触发截图完成时，参数是图片的完整路径。 图片存在应用专属目录（无需存储权限，卸载应用时随之删除）。点按钮截屏，并把截图显示到图像组件里：

when Screen1.Initialize() {
  屏幕控制1.ScreenshotFileName = "我的截图.png"
}

when 按钮_截屏.Click() {
  屏幕控制1.TakeScreenshot()
}

when 屏幕控制1.AfterScreenshot(图像位址) {
  图像1.Picture = 图像位址
}

常见问题

属性

导航栏深色图标

底部导航栏的按钮图标用深色，适合浅色导航栏背景（Android 8.0 及以上）。

状态栏深色图标

状态栏的时间、电量等图标用深色，适合浅色状态栏背景（Android 6.0 及以上）。

沉浸式全屏

隐藏状态栏和底部导航栏，页面铺满整个屏幕；从屏幕边缘滑动可临时呼出系统栏，回到应用后重新隐藏。 适合游戏、视频、阅读等页面，设为假恢复显示。

沉浸式状态栏

页面内容延伸到状态栏下方，状态栏默认透明，可再设半透明的状态栏颜色。

保持常亮

开启后本应用在前台时屏幕不会自动熄灭；关闭后恢复系统的自动息屏。

导航栏颜色

底部导航栏的背景颜色。默认跟随屏幕主题。

截图文件名

截图保存的文件名，默认 screenshot.jpg。以 .png 结尾保存为 PNG，其余保存为 JPEG；留空回退默认名。 多次截图使用同一文件名会覆盖旧文件——想留历史截图，每次调用前拼上时间戳。

状态栏颜色

状态栏的背景颜色。默认跟随屏幕主题；沉浸式时默认透明。

事件

截图完成时(图像位址)

截图完成后触发，参数为图片文件的完整路径。

方法

截图()

截取当前屏幕并保存为图片。完成后触发截图完成时事件，参数为图片的完整路径。

设置页

可见组件，用表格配置分组、开关、单选、多选、输入、滑块和操作项。默认自动保存在本机，用户修改通过统一事件返回编号、新旧值。

使用指导用表格制作常用设置页，自动保存、统一事件和动态配置查看 →

属性

设置项

点击「编辑设置项」通过表格添加、排序和删除项目，编号不能重复。代码中为 JSON 数组文本；批量积木配置可用「设置全部设置项」传入字典列表。

自动保存

默认真。用户和代码修改的值都保存在本机；关闭后仅保留当前组件内存值。

存储名称

默认 Settings。同一应用相同名称和编号共享设置值，不同名称互相独立；切换后重新读取对应值。

背景颜色

默认跟随应用主题。

文本颜色

默认跟随应用主题。

字体大小

标题字号，默认 16，最小 8。

可见性

是否显示组件。宽度、高度及其百分比属性与其它可见组件相同。

事件

设置改变(键, 旧值, 新值)

用户确认修改或恢复默认后触发，未改变的值不触发。开关值为真/假，滑块值为数字，单选和输入值为文本，多选值为列表。代码设置值不触发。

操作被点击(键)

点击操作项触发，由积木实现实际操作。

错误发生(操作, 消息)

配置、值或保存失败时触发；配置无效时保留原列表。

方法

取值(键, 备用值)

返回设置值；编号不存在或分组、操作项没有值时返回备用值。

设置值(键, 值)

设置并按需保存，不触发设置改变。选择值须在候选项中，滑块值夹紧并按步长取整。

设置全部设置项(设置项列表)

用字典列表替换配置，字段与表格对应。详见使用指导。相同编号保留合法的保存值。

添加项(设置项)

添加一个字典；重复编号或参数无效时保留原列表并报错。

移除项目(键)

移除界面项目，保留保存值，重新加入同编号可恢复。

设置说明(键, 说明)

修改当前项目说明。

设置项目可见(键, 可见)

显示或隐藏项目，不删除值。

设置项目启用(键, 启用)

禁用后不接受用户操作。

恢复默认设置()

弹确认框，确认后恢复当前项目默认值；实际改变的项目逐项触发设置改变。

位置与尺寸属性

宽度

设置组件宽度，可选自动、充满或固定值。

高度

设置组件高度，可选自动、充满或固定值。

宽度百分比

将宽度设置为屏幕宽度的指定百分比。

高度百分比

将高度设置为屏幕高度的指定百分比。

左侧位置

在绝对布局中的横向位置。

顶部位置

在绝对布局中的纵向位置。

开屏动画

不可见组件：应用启动时全屏显示一张广告图（GIF 动图或 SVG 矢量图），带倒计时和「跳过」按钮，结束后自动消失。

最简单的用法不写任何代码：拖入屏幕、选好图片即可。

使用指导开屏广告图、倒计时与跳过的快速上手和使用建议查看 →

快速上手

拖一个开屏动画到屏幕，在属性面板把图片设为上传的广告图（或填网址）。「启动时显示」默认勾选，打开 App 就会显示，不用写代码；需要在广告结束后做事时：

when 开屏动画1.Closed(原因) {
  if 原因 == "finished" {
    标签1.Text = "欢迎回来"
  }
}

when 开屏动画1.LoadFailed(消息) {
  标签1.Text = "广告没加载出来，直接进入"
}

属性

背景颜色

广告未覆盖区域的背景色。

显示时长

广告显示秒数，范围为 1 到 60 秒。

正在显示

广告当前是否正在显示。

加载超时

网络图片加载超时时间（毫秒），范围为 500 到 15000。

图片

广告图片。可使用项目素材、文件路径或 http/https 地址，支持 GIF 动图与 SVG 矢量图。

缩放方式

图片缩放方式：crop（铺满裁切）、fit（完整显示）或 stretch（拉伸）。

显示倒计时

是否显示剩余秒数。

启动时显示

屏幕初始化后是否自动显示广告。

跳过文字

跳过按钮显示的文字。

允许跳过

用户是否可以点击右上角按钮跳过广告。

事件

被点击()

用户点击广告图片时触发。

已关闭(原因)

广告关闭时触发。原因可能为 finished、skipped 或 dismissed。

加载失败(消息)

广告图片加载失败或超时时触发。

已显示()

广告显示时触发。

方法

关闭()

立即关闭当前广告。

显示()

加载并显示启动广告。图片成功加载后才开始计时。

下拉刷新

不可见组件：给列表显示框、垂直滚动条布局、布局列表框、Web浏览框等可滚动组件加上「下拉刷新」手势—— 手指在顶部往下拉，出现转圈，松手触发下拉刷新时事件，数据加载完调用结束刷新收起转圈。

内化自开源拓展 SwipeRefresh（ColinTree），改用新版 Android 组件库，修复了原版默认配色不生效等问题， 两个注册方法合并为一个注册。列表滚到中间时下拉只会滚动列表，不会误触发刷新。

使用指导下拉刷新：给列表、垂直滚动条布局、布局列表框、网页等可滚动组件加上下拉刷新手势查看 →

快速上手

1. 拖一个列表显示框（高度设为「充满」）和一个下拉刷新到屏幕；
2. 搭下面的代码块，用延时运行模拟 1 秒的网络加载：

global 数据 = ["第1条", "第2条", "第3条"]

when Screen1.Initialize() {
  下拉刷新1.Register(列表显示框1)
  列表显示框1.Elements = 数据
}

when 下拉刷新1.Refresh() {
  after(1000) {
    listInsert(数据, 1, "刚刚刷新")
    列表显示框1.Elements = 数据
    下拉刷新1.FinishRefresh()
  }
}

运行后在列表顶部往下拉，出现蓝色转圈；1 秒后列表顶部多出一条「刚刚刷新」，转圈收起。

实际项目里把「延时运行」换成真正的数据加载（如 Web 组件的 Get），在对应的完成事件（如「获得文本时」）里再调用结束刷新。

常见问题

属性

启用

是否允许下拉刷新，默认真。设为假时下拉没有反应。

指示器背景色

转圈底下圆形背景的颜色，默认白色。

指示器颜色

转圈的颜色，默认蓝色。

大号转圈

是否使用大号转圈，默认假。

正在刷新

是否正在刷新（转圈显示中）。设为真可在代码里主动显示转圈，设为假收起转圈。

事件

下拉刷新时()

用户下拉并松手时触发。在这里加载数据，完成后调用结束刷新。

方法

结束刷新()

收起转圈。在数据加载完成后调用。

注册(组件)

把下拉刷新加到指定组件上（通常是列表显示框、垂直滚动条布局、布局列表框或 Web浏览框），一般在屏幕初始化时调用一次。 再次调用会把手势移到新组件上。注册前先设好该组件的宽高。