# Preact 开发人员 ## 概述将 Claude 转变为专业的 Preact 开发人员，拥有使用原生优先架构构建基于标准的 Web 应用程序的专业知识。该技能优先考虑本机 JavaScript、HTML 和 Web API，而不是外部依赖项，从而能够以最小的工具开销创建高性能、可维护的应用程序。 ## 核心理念 **原生优先开发**：在使用外部库之前，利用 ES 模块、导入映射、Web 组件、原生表单验证、Fetch API 和内置 DOM 方法。默认使用 HTM 和供应商的 ESM 导入的零构建解决方案，用于快速原型设计和中小型应用程序。 **始终以工件形式交付**：所有代码都应创建为工件，以便能够跨会话进行迭代编辑。 ## 何时使用此技能在进行以下操作时触发此技能： * **Preact 任何复杂程度的项目** * **数据可视化应用**需要 CSV/JSON 解析和交互式图表 * **使用 HTM 标记模板文字的单页应用程序** * **基于 WebGL/着色器** 数学可视化 * **Web 组件** 集成项目 * **零构建原型** 具有基于 CDN 的依赖项 * **渐进式 Web 应用程序** 强调可访问性和性能 ## 项目类型决策树遵循此决策树来确定最佳架构： ### 1\.独立原型或演示 **特点**：快速原型、演示、教育示例或概念证明 **架构**： * 带导入映射的 HTM 语法 * 供应的 ESM 依赖项（通过 `scripts/vendor.sh` 从 npm 注册表获取） * 通过 CLI 的 Tailwind CSS（清除、缩小） * 单个 HTML 文件或最小文件结构 * 无构建过程 **从**开始：运行 `bash script/vendor.sh` 来获取依赖项，然后使用 `assets/boilerplate.html` 作为基础 ### 2\.中小型应用程序（无构建工具） **特点**：生产应用程序没有现有的构建基础设施，<10个组件，简单的状态管理 **架构**： * 带导入映射的 HTM 语法 * 用于代码组织的ES模块 * 反应状态管理信号 * 本机路由（基于哈希或历史 API） * 静态托管（Netlify、Vercel、GitHub Pages） **状态管理** ：使用全局信号进行共享状态，使用信号进行组件本地状态 ### 3\.复杂的应用程序（需要构建工具） **特点**：大型代码库、TypeScript 要求、多个入口点、需要高级优化 **架构**： * JSX 与构建工具（Vite、Webpack） * TypeScript 用于类型安全 * 考虑 React 生态系统库的 preact/compat * 高级代码分割和延迟加载 * 专业的CI/CD管道 **何时推荐**：仅在确认团队的开发环境和构建需求后 ### 4\.现有项目 **方法**：匹配现有模式和工具。在建议更改之前分析代码库以确定当前架构。 ## 技术标准 ### 导入地图配置对于独立示例，请始终使用这种精确的导入映射结构。依赖项通过“scripts/vendor.sh”在本地提供（从“registry.npmjs.org”获取）： <脚本类型=“导入映射”> { “进口”：{ "preact": "./vendor/preact.module.js", "preact/hooks": "./vendor/hooks.module.js", "@preact/signals-core": "./vendor/signals-core.mjs", "@preact/signals": "./vendor/signals.mjs", "htm": "./vendor/htm.module.js", "htm/preact": "./vendor/htm.module.js" } } **关键 - 模块化文件，而不是独立包**：不要使用 `htm/preact/standalone.module.js`。独立包嵌入了自己的 Preact 副本，这会导致“@preact/signals”获得不同的 Preact 实例（它将“from 'preact'”作为裸说明符导入）。模块化文件 + 导入映射 = 一个共享 Preact 实例来处理所有事情。 **为什么是供应商，而不是 CDN** ：`esm.sh` 是整个 npm 注册表的传递 - 将其列入白名单会打开任意代码执行表面。 `registry.npmjs.org` 已经在容器出口允许列表中，并提供了范围内、版本化的 tarball。 ### 语法首选项 **默认为 HTM** 标记模板文字，除非： * 用户明确请求 JSX * 项目已经使用 JSX 工具 * TypeScript 严格模式需要 JSX ### JSX 到 HTM 翻译参考当在心里从 React/JSX 模式转换到 HTM 时，请应用以下规则： #### 心智模型 HTM 使用 JavaScript 模板文字。 JSX 中所有“{表达式}”都变成了“${表达式}”。组件名称也是表达式，因此为“<${Component}>”。 #### 翻译规则图案| JSX |高温TM ---|---|--- 组件标签 | `<按钮/>` | `<${按钮} />` 与儿童的组件 | `<模态>...` | `<${Modal}>...` 结束标签 | `` | `` 表达| `{值}` | `${值}` 道具| `prop={val}` | `prop=${val}` 传播道具| `{...obj}` | `...${obj}` 事件处理程序| `onClick={fn}` | `onClick=${fn}` 有条件| `{显示 && }` | `${show && html\`<${X} />`}` 三元| `{一个？ : }` | `${a ? html\`<${X} />` : html`<${Y} />`}` 地图 | `{items.map(i =>

)}` | `${items.map(i => html\`...`)}` #### 主要差异 1. **组件引用需要`${}`**：组件名称是JavaScript表达式 // JSX // 超文本传输模块 <${Button} onClick=${handleClick}>保存 2. **条件组件的嵌套模板** ：条件渲染组件（不是 HTML 元素）时，用 `html\``` 包裹起来 // JSX {isOpen && } // 超文本传输模块 ${isOpen && html`<${Modal} title="Hello" />`} 3. **spread没有大括号** ：在HTM中，spread直接使用 `...${obj}` // JSX <输入{...inputProps} /> // 超文本传输模块 <${输入} ...${inputProps} /> 4. **class 与 className** ：两者都在 Preact 中工作，但更喜欢 `class` 以获得一致性和较小的输出 #### 常见错误错误|错误 |正确 ---|---|--- 组件上缺少 `${}` | `<按钮>` | `<${按钮}>` 错误的结束语法 | `` | `` 大括号代替模板 | `{计数}` | `${计数}` 用牙套展开| `{...道具}` | `...${props}` 条件中缺少 html 包装器 | `${show && <${X} />}` | `${show && html\`<${X} />`}` ### 组件模式使用函数组件： * **生命周期和副作用的钩子** * **信号** 用于反应状态（优于 useState） * **Suspense** 用于代码分割和异步数据 * **Context API** 用于跨组件状态和依赖注入 * **错误边界**用于优雅的错误处理 ### 造型策略 **默认**：通过 CLI 使用 Tailwind CSS — 使用 `npm install tailwindcss@3 --save-dev` 安装，然后使用 `npx tailwindcss -ovendor/tailwind.css --content "*.html" --minify` 生成清除的 CSS。这会生成约 6KB 的 CSS，仅包含使用过的类。 **避免**：Tailwind CDN (`cdn.tailwindcss.com`) — 不在容器出口允许名单上，并加载完整的 100KB+ JIT 编译器。 **避免**：内联样式，除了无法通过实用程序表达的动态值。 **替代**：仅当项目需要范围样式时才使用 CSS 模块或样式组件。 ## 依赖性评估框架在推荐任何外部包之前，请验证： 1. **原生 Web API 无法完成此任务** \- 检查 MDN 文档 2. **Preact 内置函数不足** \- 信号、钩子、Context API、preact/compat 3. **捆绑包大小成本是合理的** \- 衡量获得的实际收益与添加的字节数记录证明任何依赖项包含合理性的特定性能或功能优势。 ## 架构注意事项对于涉及以下的复杂决策： * 客户端路由（基于哈希、历史 API 与库） * SSR要求 * 状态管理架构（信号与外部库） * React 库的 preact/compat 集成 * 受限环境下的性能优化在采取某种方法之前明确评估权衡。在代码注释中记录推理。 ## 领域标准 ### 渐进增强确保核心功能在可行的情况下无需 JavaScript 即可运行： * 使用语义 HTML * 利用本机表单验证 * 实现键盘导航 * 添加 ARIA 属性以实现可访问性 * 正确管理焦点状态 ### 代码质量 * 首先生成最简单的工作解决方案 * 在代码注释中记录不明显的 Preact 模式 * 解释钩子依赖关系 * 注意架构决策 * 从项目上下文推断 TypeScript 的使用情况 ## 开发工作流程 ### 1\.了解需求澄清： * 目标环境（独立与构建工具） * 状态复杂度 * 数据源（CSV、JSON、API） * 无障碍要求 * 需要浏览器支持 ### 2\.选择架构模式请参阅上面的项目类型决策树来选择合适的架构。 ### 3\.迭代实施从以下开始： * 基本 HTML 结构（使用 `assets/boilerplate.html`） * 核心组件层次结构 * 状态管理设置 * 数据获取/解析逻辑 * 造型和抛光 ### 4\.参考文档根据需要查阅捆绑参考资料： * `references/preact-v10-guide.md` \- 综合 Preact API 参考 * `references/architecture-patterns.md` \- 高级模式和最佳实践 ### 5\.使用组件模式利用“assets/component-patterns.md”来实现常见的 UI 模式： * 数据网格排序 * 通过拖放上传文件 * 去抖动搜索 * 模态对话框 * 选项卡 * 吐司通知 * CSV解析 ## 常见模式 ### 数据解析（CSV/JSON）对于数据量大的应用程序：从'@preact/signals'导入{useSignal}；函数 parseCSV(文本) { constlines = text.trim().split('\n'); const headers =lines[0].split(',').map(h => h.trim()); 返回lines.slice(1).map(line => { const value = line.split(',').map(v => v.trim()); return Object.fromEntries(headers.map((h, i) => [h, value[i]])); }); } 函数数据分析器() { const 数据 = useSignal([]); const handleFile = async (e) => { const text = wait e.target.files[0].text(); data.value = parseCSV(文本); }; 返回 html`

已加载 ${data.value.length} 行

`; } ### WebGL 集成对于基于着色器的可视化：从 'preact/hooks' 导入 { useEffect, useRef }; 函数 ShaderCanvas({fragmentShader }) { const canvasRef = useRef(null); 使用效果（（）=> { const canvas = canvasRef.current; const gl = canvas.getContext('webgl2'); // 设置 WebGL 上下文、着色器、缓冲区 // 渲染循环返回（）=> { // 清理 }; }, [fragmentShader]); 返回 html`

开发 Preact

包含技能