图片轮播使用指导
可见组件：横向滑动切换多张图片，可自动播放、循环播放，底部显示圆点指示器。 图片可以是素材文件名、本地路径或网址（网址异步加载，不卡界面）。
功能参照 ColinTree 的 ColinTreeSlideShow 拓展：原版要先放一个水平滚动条布局再调用注册方法绑定， 且加入图片后调整布局大小图片不跟随；内置版直接拖进屏幕即可，宽高随时可调。 高度设为「自动」时默认显示 200 像素高。
快速上手
- 上传几张图片素材（如
1.jpg、2.jpg、3.jpg）； - 拖一个图片轮播到屏幕，宽度设为「充满」，在属性面板的图片列表字串（
ImagesFromString）点击「编辑图片…」，选择素材、上传本地图片或添加网络网址，并按需要调整顺序； - 再放一个标签，搭下面的代码块：
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 图片轮播1.PageChanged(索引) {
标签1.Text = join(索引, " / ", 图片轮播1.Count)
}
when 图片轮播1.Click(索引) {
标签1.Text = join("点了第 ", 索引, " 张")
}
运行后图片每 3 秒自动切换，标签显示「2 / 3」这样的页码；点图片，标签显示点的是第几张。
积木编辑器会像图像组件一样自动列出项目素材：「添加图片」和「替换图片」的路径参数默认带素材下拉积木。素材积木也可以放进列表，用「图片列表」一次设置多张图片；网络地址使用文本积木，素材和网址可以混用。
也可以在代码里换一组图片：
when Screen1.Initialize() {
图片轮播1.Images = list("1.jpg", "2.jpg", "https://www.fun123.cn/static/images/logo.png")
}
常见问题
| 现象 | 检查 |
|---|---|
| 拖进来什么都不显示 | 还没有设置图片；在设计器的图片列表字串（ImagesFromString）弹窗添加图片，或代码里设图片列表（Images） |
| 网络图片一直是空白 | 网址能否在浏览器打开；加载失败会触发图片加载失败时（索引，路径，消息）（ImageLoadFailed）事件，可在里面显示原因 |
| 图片被裁掉了一部分 | 默认裁切铺满（CropToFill）；想完整显示整张图就把它设为假 |
| 想手动翻页、不要自动播放 | 把自动播放（AutoPlay）设为假，用下一张（Next）/上一张（Previous）控制 |
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：动态管理本地与网络图片
上传 banner1.jpg、banner2.jpg；设计器点击图片列表的“编辑图片…”添加素材或网址。再放标签及上一张、下一张按钮。
when Screen1.Initialize() {
图片轮播1.Images = list("banner1.jpg", "banner2.jpg")
图片轮播1.AddImage("https://www.fun123.cn/static/images/logo.png")
}
when 按钮_上一张.Click() {
图片轮播1.Previous()
}
when 按钮_下一张.Click() {
图片轮播1.Next()
}
when 图片轮播1.ImageLoadFailed(索引, 路径, 消息) {
标签1.Text = join("第 ", 索引, " 张加载失败：", 消息)
}
添加图片和替换图片带项目素材下拉积木。索引从 1 开始；删除后后续索引会改变。网络网址中的英文逗号在设计器列表中写为 %2C。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
自动播放（AutoPlay） |
是否自动播放。 |
图片数（Count） |
图片总数。 |
裁切铺满（CropToFill） |
为真时图片裁切铺满整个区域；为假时完整显示图片（可能留边）。 |
当前序号（CurrentIndex） |
当前显示第几张，从 1 开始。设置它可直接跳到指定图片。 |
图片列表（Images） |
图片列表：每项是素材文件名、本地路径或网址。整体替换现有图片。 |
图片列表字串（ImagesFromString） |
用英文逗号分隔的图片列表，如 1.jpg,2.jpg,https://example.com/3.png |
指示器颜色（IndicatorColor） |
圆点指示器的颜色（当前页不透明，其余半透明）。 |
间隔（Interval） |
自动播放的间隔，单位毫秒，最小 500。 |
循环播放（Loop） |
是否循环：最后一张之后接第一张，可以一直朝同一方向滑。 |
显示圆点（ShowIndicator） |
是否在底部显示圆点指示器。 |
添加图片（路径）（AddImage） |
在末尾追加一张图片：素材文件名、本地路径或网址。 |
清空图片（ClearImages） |
删除全部图片。 |
下一张（Next） |
切到下一张。开启循环时最后一张之后回到第一张。 |
上一张（Previous） |
切到上一张。开启循环时第一张之前回到最后一张。 |
删除图片（索引）（RemoveImage） |
删除第几张（从 1 开始）图片。 |
替换图片（索引，路径）（SetImage） |
把第几张（从 1 开始）图片换成新图片。 |
被点击时（索引）（Click） |
点击图片时触发，序号从 1 开始。 |
图片加载失败时（索引，路径，消息）（ImageLoadFailed） |
某张图片加载失败时触发，如网址无法访问或文件不存在。 |
切换时（索引）（PageChanged） |
切换到另一张图片时触发（滑动、自动播放或代码切换），序号从 1 开始。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在、编号和索引是否在范围内。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
默认三张仓库真实图片可离线轮播；可从相册添加本地路径、填写真实HTTP图片网址。自动播放、动态替换和空列表都可从界面测试，上方轮播与下方滚动控制区分离。
导入 ImageCarouselAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| Images、ImagesFromString、设计器图片弹窗 | 默认三图；列表恢复、字串恢复；查看图片弹窗 | 实际图片列表和数量，图像来自打包素材，无需网络 |
| AutoPlay、Loop、Interval、ShowIndicator、CropToFill、IndicatorColor | 应用开关、间隔；切换颜色 | 设置读回，完整显示与裁切可比较；自动翻页最小500毫秒 |
| Count、CurrentIndex、Next、Previous、PageChanged | 前后翻页、合法索引跳转、关闭循环到边界 | 实际索引与真实切换事件；同页或边界不伪造事件 |
| AddImage、SetImage、RemoveImage | 添加car3.png、按索引替换、删除 | 列表真实变化；索引从1开始，删除后索引变化 |
| ClearImages | 清空，再点恢复列表 | 图片数0，停止自动播放；可再次恢复 |
| Click、ImageLoadFailed | 点实际图片；缺失素材按钮；坏网络路径 | 真实点击／失败参数，不手动触发事件 |
| 本地路径、网络网址 | 选相册添加；填电脑服务的真实URL再添加 | 本地真实路径和HTTP图片可混合，网址错误显示失败 |
| Visible、Left、Top、Width、Height、WidthPercent、HeightPercent | 外部控制区隐藏恢复、像素、百分比 | 目标有独立尺寸，控制区不随目标隐藏 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
应用图片轮播
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 默认三张仓库真实图片可离线轮播；可从相册添加本地路径、填写真实HTTP图片网址。自动播放、动态替换和空列表都可从界面测试，上方轮播与下方滚动控制区分离。 覆盖检查 49/49。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
网络图片闭环
电脑与手机在同一局域网，把下载的ImageCarouselAllFeatures.aia放到电脑一个目录，进入该目录执行（Windows可将python3改为python）：
python3 -m zipfile -e ImageCarouselAllFeatures.aia image-case
python3 -m http.server 8769 --bind 0.0.0.0 --directory image-case/assets
保持服务器窗口运行，将应用中的路径填为 http://电脑实际IPv4:8769/car1.png，点击添加并切到最后一张。电脑地址必须换成实际局域网IP，手机不填127.0.0.1。测试404可把文件名改为missing.png。测试完Ctrl+C停止服务器。接口本身支持网络图片，不把有效网址当作成功加载证明，只有图片实际显示才算完成；没有专用加载成功事件。
素材分别来自仓库aiplayapp/assets/app-icon.png、mooning.png、mooning-dark.png，字节未修改。设计器图片列表可直接编辑；轮播图片加载失败后“列表恢复”可恢复正常素材。
扫码添加客服咨询
