git:20260728.2c22517 to git:20260728.ca83c23

+ description: "宜搭全屏幻灯片页面开发，兼容旧 yida-ppt / PPT / 演示 / 幻灯片触发词，默认使用 Code Canvas + React hooks 管理翻页、URL hash、键盘/演讲笔、全屏和副作用清理。支持浅色简约与 dark-tech 主题。普通自定义页面生命周期模式仅用于 legacy/native 维护。"

+ ## 核心定位

+

+ 本技能用于在宜搭内交付全屏演示页。新建演示默认走 **Code Canvas**：

+

+ - `.canvas.jsx` / `.canvas.tsx` + `YidaComp` 函数组件。

+ - `useState` 管当前页、主题、语言、导航显隐和全屏状态。

+ - `useEffect` 管键盘、hash、触摸、定时器和 cleanup。

+ - `useMemo` 派生当前页与页码数据。

+ - 常规图表默认交 `yida-rechart`；明确 ECharts/复杂 option 时才使用 `yida-chart`。

+

+ 已有 `.oyd.jsx` 或深度依赖普通页实例桥时，才使用 legacy/native fallback。

+

+ | 在宜搭内创建演示文稿 | "PPT"、"yida-ppt"、"幻灯片"、"演示页面"、"产品路演" | 使用本技能，默认 Canvas |

+ | 需要读取宜搭数据的演示 | 演示页要接入表单、权限或宜搭页面能力 | Canvas + `yida-canvas-data-binding` |

+ | 维护已有 `renderJsx` / `didMount` PPT | 已有普通自定义页面或强依赖普通页面实例桥 | legacy `yida-custom-page` |

+ ## 致命规则

+ 1. **默认 Canvas**：新建页面不得把 `.oyd.jsx`、`renderJsx`、`didMount` 写成默认。

+ 2. **状态归 hooks**：翻页、导航、语言、主题、全屏状态用 React hooks。

+ 3. **副作用必须清理**：键盘、触摸、鼠标、hash、fullscreen、定时器和图表副作用均在 `useEffect` cleanup。

+ 4. **事件真实可触发**：禁止 `onClick={foo()}`、小写 `onclick`；可见按钮必须有 handler 或 disabled。

+ 5. **图片完整展示**：默认 `object-fit: contain`，不得裁掉关键演示素材。

+ 6. **hash 双向同步**：初始页读取 hash；翻页更新 hash；浏览器前进/后退能恢复页码。

+ 7. **全屏由用户手势触发**：监听 `fullscreenchange` 同步 UI；卸载时移除监听。

+ 8. **隐藏平台导航**：演示页发布后配置 `isRenderNav=false` 并验证最终 URL。

+ ## 开发流程

+ ```bash

+ # 1. 只读检测

+ openyida env --json

+ openyida login --check-only --json

+ # 2. 已获授权后创建应用/页面（已有则跳过）

+ openyida create-app "<应用名>"

+ openyida create-page <appType> "<页面名>"

+ # 3. 编写 Canvas 源码

+ # project/pages/src/<页面名>.canvas.jsx

+ # 4. Canvas 本地快检（以 yida-canvas-custom-page 的 compileCanvasLocal 为准）

+ # 5. 用户确认内容与主题后发布

+ openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid>

+ # 6. 隐藏宜搭导航并回读验证

+ openyida update-form-config <appType> <formUuid> false "<页面名>"

+ openyida get-schema <appType> <formUuid>

+ ```

+ `openyida check-page` / `openyida compile` 是普通自定义页面校验，不是 Canvas 默认验证步骤。

+ ## Canvas 技术骨架

+ ```jsx

+ import React, { useCallback, useEffect, useMemo, useState } from 'react';

+ function clampPage(value, total) {

+ return Math.max(0, Math.min(total - 1, value));

+ }

+ function readHashPage(total) {

+ const raw = Number(window.location.hash.replace(/^#/, ''));

+ return Number.isFinite(raw) && raw >= 1 ? clampPage(raw - 1, total) : 0;

+ }

+ function YidaComp() {

+ const total = SLIDES.length;

+ const [current, setCurrent] = useState(() => readHashPage(total));

+ const [navVisible, setNavVisible] = useState(false);

+ const [isFullscreen, setIsFullscreen] = useState(Boolean(document.fullscreenElement));

+ const goTo = useCallback((next) => {

+ setCurrent((previous) => clampPage(

+ typeof next === 'function' ? next(previous) : next,

+ total,

+ ));

+ }, [total]);

+ useEffect(() => {

+ const handleKeyDown = (event) => {

+ if (['ArrowRight', 'ArrowDown', 'PageDown', ' '].includes(event.key)) {

+ event.preventDefault();

+ goTo((page) => page + 1);

+ } else if (['ArrowLeft', 'ArrowUp', 'PageUp'].includes(event.key)) {

+ event.preventDefault();

+ goTo((page) => page - 1);

+ } else if (event.key === 'Home') {

+ goTo(0);

+ } else if (event.key === 'End') {

+ goTo(total - 1);

+ }

+ };

+ window.addEventListener('keydown', handleKeyDown);

+ return () => window.removeEventListener('keydown', handleKeyDown);

+ }, [goTo, total]);

+

+ useEffect(() => {

+ const handleHashChange = () => setCurrent(readHashPage(total));

+ window.addEventListener('hashchange', handleHashChange);

+ return () => window.removeEventListener('hashchange', handleHashChange);

+ }, [total]);

+

+ useEffect(() => {

+ const hash = '#' + String(current + 1);

+ if (window.location.hash !== hash) history.replaceState(null, '', hash);

+ }, [current]);

+

+ useEffect(() => {

+ const handleFullscreen = () => setIsFullscreen(Boolean(document.fullscreenElement));

+ document.addEventListener('fullscreenchange', handleFullscreen);

+ return () => document.removeEventListener('fullscreenchange', handleFullscreen);

+ }, []);

+

+ const slide = useMemo(() => SLIDES[current], [current]);

+ return (

+ <PresentationShell

+ slide={slide}

+ current={current}

+ total={total}

+ navVisible={navVisible}

+ isFullscreen={isFullscreen}

+ onNavigate={goTo}

+ onNavVisibleChange={setNavVisible}

+ />

+ );

+ }

+

+ export default YidaComp;

+ 触摸手势、鼠标底部热区、数字键缓冲和自动播放也分别放进 `useEffect`，每个 effect 独立 cleanup；不要把所有事件塞进一个难以维护的大 effect。

+ ## 幻灯片数据与类型

+ `SLIDES` 放在组件外作为静态数据，或通过 props/数据桥加载；不要把全部文案硬编码在 JSX 分支中。

+ | 类型 | 用途 |

+ | --- | --- |

+ | `cover` | 封面 |

+ | `toc` | 目录 |

+ | `chapter` | 章节过渡 |

+ | `key-points` | 要点列表 |

+ | `image-text` | 图文混排 |

+ | `scene-image` | 场景展示 |

+ | `two-images` | 双图对比 |

+ | `chart` | 业务图表，默认 `yida-rechart` |

+ | `ending` | 结束页 |

+ ## 主题

+ | theme | 风格 | 适合场景 |

+ | --- | --- | --- |

+ | `default` | 浅色简约、内容优先 | 技术分享、产品路演、培训 |

+ | `dark-tech` | 深色、粒子/网格、电影级转场 | 科技发布、沉浸演示 |

+ 粒子背景用 `<canvas>` 时，在 React `ref` + `useEffect` 中初始化 `requestAnimationFrame`，cleanup 必须 `cancelAnimationFrame`、移除 resize 监听并释放引用。不要用固定 `setTimeout` 等 DOM。

+ ## 响应式与交互

+ - 响应式优先 CSS media query / `matchMedia` hook，不使用一次性 `this.utils.isMobile()`。

+ - 页面根节点固定覆盖视口：`position: fixed; inset: 0; overflow: hidden`。

+ - 键盘支持方向键、PageDown/PageUp、Home/End；演讲笔通常映射到这些键。

+ - 数字键跳页用独立 hook 管缓冲与定时器，并在 cleanup 清除。

+ - 底部导航默认隐藏，鼠标靠近底部或触摸时显示；移动端触控目标不少于 44px。

+ - 图片使用 `max-width/max-height: 100%` + `object-fit: contain`。

+ - prefers-reduced-motion 时关闭粒子、自动播放和大幅转场。

+ ## 图表边界

+ - 常规折线、柱、面积、饼/环、组合图：`use_skill("yida-rechart", "在 Canvas 幻灯片中实现业务图表")`。

+ - 只有用户明确要求 ECharts、复杂 ECharts option、bar chart race 或旧 native ECharts 演示时，调用 `yida-chart`。

+ - `references/echarts-race-example.md` 是明确 ECharts 的专项/legacy 参考，不是默认幻灯片骨架。

+

+ ## Legacy/native fallback

+

+ 仅在维护旧普通自定义页面或必须使用页面实例桥时：

+

+ - 使用 `yida-custom-page`。

+ - 状态可用 `_customState + forceUpdate`。

+ - 生命周期使用 `didMount` / `didUnmount`。

+ - 移动端可用 `this.utils.isMobile()`。

+ - 源码使用 `.oyd.jsx`，校验走 `openyida check-page` / `openyida compile`。

+

+ `references/examples.md` 和 `references/dark-tech-theme.md` 中标记为 legacy/native 的代码只用于旧页面维护；新建页面优先把同等能力翻译成 hooks。

+

+ ## 验收

+

+ - Canvas 本地编译通过，发布后回读到非空 `runtimeCode`。

+ - 方向键、PageUp/PageDown、hash 前进后退、全屏按钮、触摸翻页实际可用。

+ - 离开页面后不再响应事件、轮询或动画。

+ - 图片无关键裁切，手机竖屏可读，reduced-motion 有降级。

+ - 平台导航隐藏，分享 URL 定位页码有效。

+ - 使用 ECharts 时已明确记录命中的例外条件；否则图表默认 `yida-rechart`。

+

+ | 文档 | 用途 |

+ | --- | --- |

+ | [核心示例](references/examples.md) | Canvas hooks 示例优先；旧 native 完整示例明确标记 legacy |

+ | [dark-tech 主题](references/dark-tech-theme.md) | Canvas 粒子/转场原则；旧 `renderJsx` 框架只作 legacy |

+ | [ECharts race 示例](references/echarts-race-example.md) | 仅明确 ECharts/bar chart race 或维护旧实现时阅读 |

+ | `yida-canvas-custom-page` | Canvas 运行时、依赖、编译和发布 |

+ | `yida-canvas-data-binding` | 演示页真实数据桥 |