Yida Canvas Upgrade

平台 JSX 组件页面迁移到 YidaCodeCanvas 组件实现

核心定位

本技能用于迁移存量页面：把已有的 JSX 组件页面转换为使用 YidaCodeCanvas 组件实现的页面，产出等价的 React18 函数组件源码并承载到 YidaCodeCanvas。

• 迁移前页面：OpenYida 平台 JSX 组件页面，通常是 project/pages/src/*.oyd.jsx、export function renderJsx()、_customState、this.utils.yida.*，openyida publish 发布为 Jsx 组件；用户称 .oyb.jsx 时先按平台 JSX 组件页面需求识别，再确认实际源码后缀。
• 目标实现：页面 Schema 中承载 YidaCodeCanvas 组件，组件属性包含 code、runtimeCode、importedModules，运行时执行 YidaComp。

迁移前必须确认

openyida publish 已能把 .canvas.jsx 发布为 YidaCodeCanvas 组件页面；升级的真正门槛在源码等价改写（尤其 this.utils.yida.* / dataSourceMap 在 YidaCodeCanvas 组件内没有平台 JSX 组件实例桥对应物），而非发布能力。改写受阻、无法保证等价时，只交付源码草案和迁移报告，不要声称已完成升级。

可迁移性分级

输出产物位置

• 可维护的 .canvas.jsx 源码放在 project/pages/src/<页面名>.canvas.jsx。
• 临时分析、Schema 回读、编译返回值、依赖清单放在 .cache/openyida/canvas-upgrade/。
• 不要把一次性 runtimeCode、接口抓包、调试 JSON 放到仓库根目录。

迁移步骤

1. 盘点原页面

   • 读取源文件，不从 project/pages/dist/*.js 反推。
   • 列出导出的函数、顶层常量、_customState 字段、生命周期、API 调用、第三方脚本。
   • 标记依赖 this 的能力：this.utils、this.dataSourceMap、this.state、this.setState。

2. 判断是否能自动升级

   • 如果页面主要是 UI + 本地状态 + 白名单图表库，可以继续生成 .canvas.jsx 源码。
   • 如果页面强依赖 this.utils.yida.* 或设计器数据源，但 YidaCodeCanvas props 未验证，先输出阻塞点和迁移计划。
   • 如果目标诉求其实是字段结构、流程、报表、权限，停止迁移，切到对应配置型技能。

3. 生成 .canvas.jsx 源码

   • 把 export function renderJsx() 的 JSX 提取到 function YidaComp(props)。
   • 把 _customState 拆为 React state；复杂派生数据用 useMemo。
   • 把生命周期副作用放进 useEffect 并返回 cleanup。
   • 把普通页面 API 适配逻辑抽成 props 调用或明确的 TODO，不要假装可用。
   • 保持 UI 结构和文案尽量不变，先做等价迁移，再考虑重构。

4. 处理依赖

   • import 只使用 YidaCodeCanvas 可用资源清单内的包（能被 CLI 编译识别并注入 importedModules）。
   • 对照 YidaCodeCanvas 依赖规则检查 importedModules。
   • 外部 CDN 脚本要么换成白名单依赖，要么在最小验证页确认可加载。

5. 发布 / 验证 Schema

   • 用 openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid> 发布：.canvas.jsx 自动写入 YidaCodeCanvas Schema，CLI 本地用 Babel 编译出 runtimeCode + importedModules（code / runtimeCode / importedModules 由 CLI 填充，无需手工拼 Schema）。
   • 源码改写受阻、无法保证等价时，只交付 .canvas.jsx 草案和升级报告，不要发布覆盖线上页。
   • 发布后回读 Schema，确认组件树中存在 YidaCodeCanvas，且 runtimeCode 不是空。

6. 运行验收

   • 打开真实页面，确认首屏非空。
   • 控制台无依赖缺失、YidaComp 未定义、CSS 缺失等错误。
   • 核心交互能触发；移动端至少做一次宽度/弹层检查。
   • 如涉及 EmployeeField，按 EmployeeField 验收点逐项验证。

转换模式与升级报告

• 转换核心：_customState → useState/useMemo；didMount/didUnmount → useEffect + cleanup；删掉 forceUpdate/timestamp 强刷；this.utils.yida.*/dataSourceMap 抽成 props 或明确 TODO（YidaCodeCanvas 组件没有平台 JSX 组件实例桥，不要假装可用）；JSX 从 renderJsx() 提到 function YidaComp(props) 并 export default。
• 迁移完成或受阻时输出简短升级报告（含 source/target、status、依赖、schema write path、blockers、验收勾选项）。

📖 before/after 完整转换 JSX 示例 + 升级报告模板 → references/migration-examples.md

常见阻塞