组件系统升级通知与迁移指南

为了赋予组件更强大的表现力、更灵动的交互响应能力以及更专业的配置体验，Zion 平台近期对组件系统进行了全面重构和重磅升级！

本次升级优化了底层架构，引入了更精细的样式、布局及逻辑控制。为了帮助广大开发者顺利过渡，本文将详细梳理升级的新增能力、升级后可能出现的编辑器校验报错与解决方法、以及常见问题解答（QA）。

⚠️

重要提示：重构升级仅作用于编辑器及预览环境。只要您不点击“正式发布”，您现有的线上版本将维持原样，绝对不受任何影响。

📅 迁移升级时间表

为了让您有充分的时间进行测试与适配，本次组件系统升级将分阶段逐步推行：

阶段 1：内测启动（2026年5月1日） — 开启内测体验，支持开发者主动进行旧项目迁移测试。
阶段 2：全新项目默认启用（2026年5月13日） — 所有新创建的项目将默认采用全新升级的组件系统。
阶段 3：免费版项目统一迁移（2026年6月3日） — 届时将统一将所有免费版项目平滑迁移至新版组件系统。
阶段 4：全量项目迁移（时间待定） — 将视阶段 3 的运行状况，决定并公布付费版等其他所有项目的最终统一迁移时间。

🚀 核心升级能力

弹窗 (Modal) 独立配置：新版组件系统支持将弹窗 (Modal) 作为独立资源进行配置和管理，显著提升了其复用性。
旧版弹窗统一迁移：原有的页面弹窗 (Modal) 组件已统一重构并迁移为条件式容器。

2. 🎨 样式与布局：从“基础”到“精细”

重构后，我们赋予了组件更强大的表现力：

新增视觉特效：文本、按钮、输入框等基础组件现已支持阴影、背景模糊及装饰线配置，助您轻松实现毛玻璃等高级视觉效果。
智能溢出控制：页面及容器的溢出属性从简单的“滚动/隐藏”升级为支持 X/Y 轴独立控制（支持自动、滚动、可见、隐藏四种状态），完美解决内容遮挡或布局错乱问题。
自定义内边距：按钮、输入框、日期选择器等组件新增了内边距配置，让您精确控制内容与边框的距离。
表格与列表细节优化：
- 表格组件细化了表头和尾部的文字颜色及背景色配置。
- 列表组件支持修改列表项的光标样式，极大提升了用户交互体验。
换行逻辑增强：视图、列表、标签栏等容器类组件新增了换行、不换行、反向换行的配置，让列表布局设计更加灵活多变。

3. ⚙️ 交互与逻辑：从“死板”到“灵动”

我们增强了组件的交互属性，让页面具备更强的逻辑响应能力：

动效行为化：动画效果修改为在行为中添加。这有助于根据具体的业务逻辑条件触发动效，提升用户操作时的视觉反馈。
静态数据支持：日期时间选择器的开始/结束时间、地图组件的经纬度，现在均支持直接进行静态输入。配置时不再强制依赖数据绑定，极大地提升了常规场景下的配置便捷性。

4. 🖼️ 媒体与展示：从“单一”到“多元”

针对图片、视频等媒体组件，我们优化了展示模式，以适应不同的屏幕尺寸和设计需求：

图片填充模式大升级：图片组件不再局限于“填充空间”或“完整图片”，新增了完整显示、裁剪填充、拉伸填充以及自动压缩选项。无论是头像裁剪还是全屏背景图，都能完美适配。
视频与 HTML 增强：视频组件支持不透明度调整，可与背景完美融合；HTML 组件则大幅扩展了样式配置项（圆角、边框、光标样式等）。

5. 📊 数据：更专业的配置

隐藏配置公式化：将以往隐藏较深的零散配置移除，并用新增的公式进行统一替代：
- 新增 FORMAT_DATE_TIME 公式替换原时间格式的配置。
- 新增 ARRAY_MAPPING 公式替换原数组字段的选择。

⚠️ 迁移后可能出现的校验报错及排查指南

组件系统升级后，编辑器会对已有项目执行智能校验。若您的项目在升级前存在不规范配置，可能会在校验结果中出现报错或状态变更。请参照下表进行排查和修复：

校验报错/变更现象	触发原因	排查及解决方法
条件式容器“切换时保持状态”自动开启	升级重构后的默认逻辑变更。	此为系统自动变更为开启，无需特殊处理。若有特定交互不需要保持状态，可手动前往该容器的属性设置中调整。
输入框组件数据类型不匹配	输入框绑定的变量或字段类型（如长整型与小数类型）与输入值类型不匹配。	需手动修改输入框的输入值类型，确保其与绑定的数据表字段或变量类型严格保持一致。
页面加载引用报错（现不支持选择页面组件）	在页面加载时，逻辑行为中直接引用了页面内部的组件。	新版架构中，页面加载阶段不支持跨层级引用页面组件。请检查页面加载行为，移除对特定页面组件的直接引用，改用变量或参数传值。
地图组件多标记点设置异常	该地图组件在旧版本中曾经开启过“多标记点”功能，后续虽然关闭，但在底层仍残留了历史配置。	需手动前往该地图组件的设置面板，重新手动关闭一次多标记点设置项，即可消除校验报错。
图片组件触发非空校验报错	图片组件新增了非空约束。	新版图片组件对配置和绑定关系进行了非空校验。请检查受影响的图片组件，为其配置默认图或确保数据绑定（Data Binding）的源数据非空。
组件尺寸与实际配置不匹配	组件配置了“最小尺寸”限制，导致实际渲染与设置值产生偏差。	建议在编辑器属性面板中，重新切换一下真实尺寸的单位（如在 `px` 与 `rpx` 等单位间切换），强制让编辑器刷新配置即可。
跨页面操作组件报错	行为中配置了跨页面控制组件的行为（例如在 A 页面触发行为去刷新 B 页面的组件）。	新版组件系统不支持跨页面操作组件。请重新梳理您的交互链路，确保所有组件操作行为（如刷新、显示/隐藏）仅在同一个页面内闭环。

❓ 常见问题解答 (QA)

Q1：升级组件系统后，会影响我线上正在运行的小程序或网页应用吗？

完全不影响。 本次重构升级仅作用于编辑器和预览测试环境。只要您不点击“正式发布”按钮，您线上正在运行的版本就不会有任何变动，风险已进行彻底的物理隔离。

Q2：为什么我的图片组件升级后突然报错，以前明明好好的？

这是因为新版组件系统对图片组件引入了非空校验。如果您的图片组件在旧版中没有设置默认图片，且没有进行有效的数据绑定，就会触发此报错。您只需在属性面板中配置默认图，或确保其绑定的数据非空即可消除报错。

Q3：升级后我还能用行为去控制其他页面的组件吗？

不能。 为了保障逻辑执行的高效性与可靠性，新版架构明确不支持跨页面操作组件（例如通过行为直接刷新其他页面的容器）。建议您通过设置客户端变量或传递页面入参的方式来实现跨页面数据通信与逻辑联动。

Q4：为什么我的地图组件提示多标记点配置错误，但我明明没有开启它？

这属于历史残留配置引起的校验冲突。如果该地图组件在旧版本中“曾经开启过又关闭过”，底层仍然保存了相关数据。解决方法非常简单，只需在属性面板中找到该地图组件，重新手动开启再关闭一次“多标记点设置项”即可。

Q5：如果我在测试预览版时不小心把数据库数据删掉了，能恢复吗？

因为预览/体验环境与线上生产环境共用同一个数据库，所以进行删除操作时请务必小心。我们强烈建议您测试时使用测试账号。如果发生了大批量数据的误删或严重异常，请立即联系我们的客服与技术团队，我们将协助您进行数据库回滚。

Q6：新版组件系统如果用起来很不习惯，或者遇到严重 Bug 无法编辑，可以退回旧版吗？

支持。 如果您在升级后遇到严重阻碍正常开发的异常，请联系我们，我们会帮您手动回滚至迁移前的状态。但请注意：回滚将彻底清除您升级之后在编辑器里进行的所有新增和修改，建议联系回滚前先做好记录。