Yida Custom Page

JSX 自定义页面开发

平台导航下的管理页面默认只实现业务内容，跨模块由平台菜单切换；同任务分类可用页内 Tab。维护 JSX 页同样遵守管理页面边界，不默认追加自绘导航或隐藏平台导航。

Resource-First 页面开发

编写页面源码前，先按根技能解析目标 app/page/form context：

• 已有页面 URL、display formUuid、bound page 或 workspace cache/config 中可确认的自定义页面时，直接为该页面编写/修改源码，并交给 yida-publish-page 发布；不要先调用 yida-create-page。
• bound page 只是默认页面，不是锁定目标；如果当前会话绑定页面 A，但用户本轮明确说要修改页面 B，先解析 B 的 URL / display formUuid / 页面名称。B 能唯一解析时改 B；B 无法唯一解析时询问用户；禁止静默把需求发布到 A。
• 完整应用统一编排如果已有 bound app/page，主页面源码直接落到该页面；只在缺少主入口 display page 且用户意图允许新增时创建页面容器。
• 用户只说“优化这个页面 URL / 修改现有页面 / 重新发布”时，本技能与 yida-publish-page 配合即可完成，不创建 app/page。
• 如果用户给的是普通表单 formUuid，页面源码只能把它作为数据源或入口链接使用；不能把数据表单 ID 当作发布目标。
• 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 project/pages/src/...；如果 cwd 已是 <workspace>/project，用 pages/src/...，不要写成 project/pages/src/...。

核心规则

致命规则（FATAL）

违反会导致页面崩溃或运行时报错：

1. 默认使用 OpenYida 页面源码格式：推荐文件名 project/pages/src/<页面名>.oyd.jsx。宜搭原生写法仍使用 export function renderJsx()；有限现代 authoring 可用 export default function Page() + useState + useEffect(..., [])，由 OpenYida 发布前降级
2. export function 定义方法：所有需要 this 的方法必须用 export function 定义，不得用箭头函数或函数表达式
3. 事件绑定箭头函数包裹：renderJsx 顶部先写 var self = this，事件使用 onClick={(e) => { self.handleClick(e) }}，严禁 onClick={this.handleClick} 或 .bind(this)
4. .map()/.filter() 回调用箭头函数：.map((item) => ...)，禁止 .map(function(item) {...})，否则回调内 this 丢失；.oyd.jsx 构建会尝试自动修复，但生成时仍应直接写正确形式
5. 输入框非受控模式：<input> 用 defaultValue + onChange 写入 _customState，禁止 value 受控模式
6. 禁止 import/require：第三方库通过 this.utils.loadScript 加载 CDN 脚本
7. 字段 ID 必须通过 get-schema 获取：执行 openyida get-schema <appType> <formUuid> 获取真实 fieldId，文件顶部定义 FIELDS 常量映射字段别名，禁止猜测或手写
8. 所有 API 调用必须 .catch()：异常通过 this.utils.toast({ title: message, type: 'error' }) 提示用户
9. renderJsx 每个 return 分支必须渲染 timestamp：<div style={{ display: 'none' }}>{this.state && this.state.timestamp}</div>；.oyd.jsx 构建会自动补齐，但生成原生写法时仍必须显式写出
10. 禁止 ES6 计算属性名：不要写 { [key]: value }、{ [FIELDS.xxx]: value } 或 setCustomState({ [key]: value })；宜搭运行时可能静默白屏，check-page 会以 computed-property error 阻塞。改用 var obj = {}; obj[key] = value;
11. 生命周期名称大小写固定：只允许 export function didMount() 与 export function didUnmount()；didmount、componentDidMount、componentWillUnmount 会被 check-page 阻塞
12. 按钮必须真的绑定事件：禁止 onclick 小写属性、onClick={self.save()}、onClick={(e) => self.save}、<button>静态标签</button> 等看起来有按钮但不会正确绑定的写法；统一使用 onClick={(e) => { self.save(e); }}。如果只是状态标签/截图标记，用 span/div，不要用 button
13. 业务状态禁止直接 this.setState：业务态只写 _customState，通过 setCustomState() / forceUpdate() 触发重渲染；this.setState 只允许写 timestamp 等运行时保留字段
14. 读状态只能用 getCustomState()，禁止读 this.state.<业务字段>：this.state 里只有 timestamp（重渲染标记）和 urlParams，业务态在 _customState。读 this.state.agg、this.state.loading 等恒为 undefined，页面无报错却渲染成"数据全占位、图表全空"的空壳页，极难排查。renderJsx/renderCharts 等所有读状态处一律 this.getCustomState()；遇到状态同步问题时再读 编码指南 · 状态管理
15. JSX 文案只能是文本或字符串：JSX 文案只能写成纯文本 所有级别 或带引号字符串 {'所有级别'}；筛选项、按钮、状态、空态和表格列名等中文业务文案都按此规则书写。花括号里只能放真实变量/表达式，不能写 {所有级别}、{处理中} 这类裸中文表达式，否则运行时会报 所有级别 is not defined。

重要规则（IMPORTANT）

影响代码质量和用户体验：

0. 视觉方向先于编码：单点页面美化、页面重构、用户明确要求好看/去 AI 味，或完整应用进入页面实现阶段时，分别读取 yida-prd 的产品事实和调用 use_skill("yida-design", "确定自定义页面视觉方向") 获取 UI 设计。完整应用由 yida-prd 产出 prd/<项目名>/prd.md、由 yida-design 产出 prd/<项目名>/design.md，或提供单页 PRD 章节 + design spec；PRD 包含页面场景、页面区块、functionContract、素材策略、原生表单入口和业务化自检，design.md 包含 themeProfile、tokens、视觉 DNA、visualScaffold、圆角、密度、组件和状态规则。页面重构默认以当前应用主题色为基准，并保持现有数据源、字段映射、按钮动作、筛选逻辑、提交 URL、权限和业务状态。
1. 代码生成前确认功能摘要：详见 编码指南 编注 0
2. pageSize 推荐 50，最大 100：列表/看板默认 pageSize: 50；分页接口 searchFormDatas 等的 pageSize 最大 100
3. didUnmount 清理定时器：在 didUnmount 中清理所有 setInterval/setTimeout，防止内存泄漏
4. 默认 Tailwind 风格层 + native 控件 reset：面向用户的自定义页面默认使用 Tailwind utility className 组织视觉层，并默认导入 Tailwind preflight；同时必须保留 openyida-native-control-reset 或等效页面级样式，覆盖 input/textarea/select/自定义下拉的 focus、appearance、font-weight 和 shadow，避免浏览器黑色粗边。reset 使用 .oyd-page 通用作用域时可以复用全局 id，但不能因为同名 style 已存在就跳过更新；如果页面使用 .oyd-grade-page、.oyd-data-page 等自定义作用域，style id 必须页面专属，避免多 native 页面切换时下拉选项和 SVG 勾选样式丢失。运行时脚本只允许使用已验证的 g.alicdn.com 或企业自托管地址，未配置有效地址时走内联兜底样式
5. DateField 时间戳格式：日期字段值必须是时间戳（毫秒），不能是字符串
6. forceUpdate 后延迟操作 DOM：forceUpdate() 后 DOM 不会立即更新，ECharts/Canvas/第三方组件初始化必须放入 setTimeout 或 requestAnimationFrame
7. 多端适配：使用 this.utils.isMobile() 判断设备类型，适配 PC 和移动端
8. 输入法组合输入处理：使用 _isComposing 标记配合 compositionstart/compositionend 事件，避免输入过程中触发提交
9. 表单打开入口统一容器：数据列表用 workbench/{formUuid}?iframe=true，禁止用 formDetail 冒充列表；新增/提交/查看详情入口统一封装为 FormOpenContainer。PC 端默认用半屏 50vw 抽屉 iframe 承载页面级隐藏导航的 submission/{formUuid}?isRenderNav=false 或 formDetail/{formUuid}?formInstId=...&navConfig.layout=1180&isRenderNav=false，提交页和详情页使用同一宽度规则；详情实例 ID 必须优先取 row.formInstId，缺失时禁用或提示，不打开空 formInstId；移动端才整页或新页打开原生表单页；不要在按钮里直接 window.open
10. Tabs 显隐控制：下拉值变更后自动回退到第一个可见 Tab，内容区用 display: none 保留 DOM
11. 加载态必须可恢复：列表/看板页默认保留空态或演示数据；接口失败、超时或返回异常时必须把 loading 置回 false，不要只渲染“正在加载...”挡住整页
12. 禁止可见原生下拉：筛选、预约、审批等用户可见下拉交互不要使用 <select>；普通自定义页也不要把表单设计器里的 SelectField 当 React 筛选组件直接渲染。默认使用 Tailwind className 组合 button + menu + option 的自定义下拉组件，并带 .oyd-select-arrow 下箭头、.oyd-select-check 选中标记和页面级 focus reset；light 模式下选中项整块背景必须用 --oyd-control-selected-bg 这类低透明度浅色 token，不要直接用 --color-brand1-1
13. 严禁 emoji：平台 JSX 组件页面发布后落到平台 Jsx 组件，源码禁止 import/require。页面渲染出来的任何位置（标题、按钮、标签、状态、空态文案、图表标题等）一律禁止出现 emoji（😀🚀✅⚠️📦📊 等一切彩色符号字符）。需要图标时仍遵守 skills/yida-design 的 iconSystem：图标来源只允许 lucide-react 或 @ant-design/icons，默认 lucide-react；平台 JSX 组件只能通过已验证运行时脚本/global 方式加载这两类图标库，不能写 import。若当前平台 JSX 组件运行环境无法稳定加载图标库，必须去掉非必要图标或使用已验证资源。不得把 emoji 改成 CSS 图形、字母占位、Unicode 符号、iconfont、装饰性临时 SVG 或其他图标库。emoji 是最明显的 AI 味来源之一，且跨端显示不一致。JS 注释、文件路径、数据常量和示例数组里也不要留装饰性符号；check-page / compile / publish 报 emoji 错误时必须改成规定的图标库实现，不能用 --skip-lint 绕过。
14. light 页面使用清爽业务配色：普通业务列表、协同表、录入表、工作台和门户默认使用浅底、清晰分割和应用品牌色；主操作、选中态、筛选焦点和批量操作使用平台品牌色或当前页面确认的品牌色，边框用浅色品牌混合。用户明确要求暗色/高对比时使用深色主视觉。
15. 发布前必须跑检查链路：先执行 openyida check-page <file> 和 openyida compile <file>；若出现 warning/error，按规则修复后再发布
16. 源码修改发布闭环：只要本轮 Write/Edit/Create 了 project/pages/src/*.{oyd.jsx,jsx,tsx} 普通自定义页面源码，check-page / compile 只证明源码可发布，不等于远端页面已更新；final 前必须看到成功的 openyida publish <source> <appType> <displayPageFormUuid>。没有 publish 成功证据时，只能说“源码已修改，尚未发布”，不能说“页面已更新 / 已重新发布”。

每条规则的代码示例、反模式和常见错误见 编码指南；完整应用统一编排默认先遵守 yida-prd 的 prd.md、yida-design 的 design.md 和本技能正文，不预读长 reference，只有 check-page 报错、复杂交互或正文覆盖不了的问题时才读取。 运行时易错点、check-page 规则和兼容层自动修复边界见 运行时护栏，按需读取。 表单类 JSX 控件、筛选栏、表格等组件写法见 组件指南，涉及这些复杂组件时读取；未验证的平台组件能力不得编造。

平台 JSX 组件编译与检查

本技能负责平台 JSX 组件页面发布前的本地检查、兼容构建和编译校验。只要本轮维护的是 .oyd.jsx、.oyb.jsx、已有 renderJsx 源码或平台 Jsx 组件页面，发布前先执行：

openyida check-page project/pages/src/employee-query.oyd.jsx --json
openyida compile project/pages/src/employee-query.oyd.jsx

路径口径同本技能 Resource-First 规则：从仓库根执行时用 project/pages/src/...；如果 cwd 已经是 <workspace>/project，改用 pages/src/...。

兼容构建规则：

1. .oyd.jsx / .openyida.jsx 或显式 --compat：先运行 OpenYida compatibility compiler。
2. 普通 .jsx 源码没有 export function renderJsx() 但存在 export default function Page()：自动尝试有限 authoring 降级，不要求 Agent 手动补 --compat。
3. 源码已有 export function renderJsx()：视为宜搭原生源码，机械修复事件绑定、数组回调，并补齐缺失的基础运行时导出。
4. 源码是 export default function Page()：支持有限 authoring 模式，当前可降级 useState 和 useEffect(..., [])；useEffect 内引用组件局部 helper/state 会被阻塞，避免发布后 didMount 运行时报 undefined。
5. 兼容构建会自动补齐 renderJsx return 分支中的隐藏 timestamp 节点，并将直接事件绑定 / .bind(this) 机械改成箭头函数包裹。
6. check-page 会硬拦截生命周期大小写错误、小写 onclick、渲染时执行事件函数、箭头函数只引用不调用方法、可见 <button> 没有事件等按钮不可点击问题。
7. 对构建后的 .yida.jsx 执行 check-page 规则、Babel 转 ES5、UglifyJS 压缩，再构建 Schema 发布。

这一步是脚本级确定性处理，优先让 lint/fix/build 解决语法和运行时兼容问题，不应把简单机械修改交给 AI 反复重写。check-page / compile 只证明源码可发布，不等于远端页面已更新；远端完成证据仍然必须来自成功的 openyida publish <source> <appType> <displayPageFormUuid>。