frappeframework/ui贡献者开发指南组合式组件库的工作区规范与实践【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappeui/CLAUDE.md是 frappe 框架内framework/ui前端组件库的工作区笔记它为贡献者含 AI Agent划定了在该仓库内写组件、改组件、跑格式化、维护 Story 时必须遵守的操作细则。这份指南不会重述设计规则本身规则在ui/PHILOSOPHY.md而是补齐规则落地时最容易踩的坑如何区分framework/ui与上游frappe-ui两个包、如何遵守 tab 缩进与 Prettier 纪律、如何用 frappe-ui 原子组件搭建 Story、以及如何把 FormLayout 字段类型的改动同步到 CRM 应用中的手动测试 Story。读完本文你将能在该仓库内按规范安全地完成一次组件贡献的完整流程。这份文档的定位规则之外的操作细则ui/CLAUDE.md开篇就划清了它的边界设计规则design rules本身不在这里而在 ui/PHILOSOPHY.md。它自称是支撑这些规则的操作性细则operational specifics解决的是一线开发中与代码库结构、工具链、包身份相关的实际问题。它面向的读者是三类人组件贡献者、负责改代码的 AI Agent、以及代码评审者。文档明确要求在起草或重构组件前先通读 ui/PHILOSOPHY.md在评审中按编号引用原则如FP1、P3而不是模糊地说不符合我们的风格。这种规则集中在规则书、操作细则集中在工作区笔记的分层与仓库内其他文档形成互补ui/README.md讲消费方如何接入该包ui/CONTEXT.md定义术语词汇表Sort、Filter、Column、Controlled component、View Snapshot 等ui/docs/adr/记录针对具体问题的架构决策而ui/CLAUDE.md讲的是动手之前必须知道的事。设计规则体系继承 frappe-ui 的 P1–P14 与自有的 FP 原则虽然设计规则不在ui/CLAUDE.md内但它是理解整份文档的起点所以文档第一件事就是引导读者去读 ui/PHILOSOPHY.md。这套规则体系由两层组成第一层完全继承 frappe-ui 的 PHILOSOPHYP1–P14。因为framework/ui的每个组件都由 frappe-ui 原子组件组合而来所以 frappe-ui 关于命名P1、v-modelP2、原始 propsP3、颜色轴P4、标签P5、插槽词汇P6/P7、拆分P8、data-* 样式P10、图标P11、无障碍P12、弃用P13等规则全部适用。ui/PHILOSOPHY.md特意指出它不重述这些规则以两个并行副本会各自漂移为由直接链接上游权威版本。第二层framework/ui独有的生成式 FP 原则。每个原则都是生成式的——不仅约束它明确覆盖的场景还能在未覆盖的新场景中推导出正确答案当两个原则互相拉扯时原则正文通常会指出决胜方。目前ui/PHILOSOPHY.md定义了三条核心 FPFP1组合 frappe-ui 原子组件不要重建它们。动手写任何 UI 元素之前先找frappe-ui的等价物Dialog、Button、Select、TextInput、Switch、Tabs、TabButtons、ErrorMessage……。framework/ui的定位是更高级、与 Frappe 集成的瘦库职责是把原子组合成 doctype 感知的控件而不是重新实现原子。只有当 frappe-ui 确实没有等价物时才允许自建自定义元素且必须留注释说明这个缺口让自定义代码读起来像深思熟虑的回退而非漏掉的复用。理由是原子已经内置了 ARIA、键盘导航、焦点管理与主题基线对应 frappe-ui 的 P12重建等于重复这套表面并与其漂移、丢掉上游修复。FP2列表视图控件是受控组件——宿主拥有数据获取与持久化。一个控件SortBy、Filter、Column Settings、Quick Filter……通过v-model加一个doctype恰好拥有视图状态的一个切片发出变更事件但绝不触碰数据获取资源或持久化层。宿主负责接线获取、跨控件同步以及何时、何处保存。库的边界止于可序列化的 View Snapshot绝不拥有已保存的 View 实体。FP3从 doctype Meta 派生选项而非应用专属接口。控件提供的字段可排序字段、可过滤字段、列候选应在客户端通过共享的useDoctypeMeta从 doctype Meta 派生而不是从消费应用的自定义端点sort_options、filterable_fields……拉取。Meta 是每个 Frappe 应用都有的单一来源派生自它能让控件保持应用无关。评审时按FP1、P3这样的编号引用是这套体系鼓励的沟通方式ui/CLAUDE.md将其写为明确约定。关键辨识framework/ui与frappe-ui是两个包ui/CLAUDE.md指出FP1组合而非重建依赖一个操作层面的前提区分两个名字相似的包。这是整份文档里最容易踩的陷阱本仓库是framework/ui一个精简的 in-house 库只有少数几个组件位于 ui/package.jsonname: framework/uisrc/下每个组件目录自带stories/、tests/与index.ts。import ... from frappe-ui解析到的则是完整的上游依赖包位于node_modules/frappe-ui例如 bench 环境下apps/crm/frontend/node_modules/frappe-ui其组件数量多得多Tabs、TabButtons等。因此在断定这个组件不存在之前应先在上游包里 grep而不是只搜本地src/——否则你可能会重建一个上游已经提供的东西违反 FP1。这一点在 ui/README.md 中得到印证framework/ui以原始.vue/.ts源码形式交付无构建步骤由消费应用的打包器编译vue、vue-router、frappe-ui都是 peer dependency每个 Frappe 前端都已提供。文档举了一个例证FileUpload/FileUploadDialog.vue的源切换器使用 frappe-ui 的Tabs而不是手搓 tablist——Tabs提供 ARIA 与键盘导航reka-ui 的unmountOnHide让非激活面板如 CameraSource保持懒加载。需要注意的是从当前源码看ui/src/components/FileUpload/FileUploadDialog.vue 的头部注释已说明它被重写为Notion 风格添加菜单bare popover而非旧式 source tabs但 FP1 的组合原则在该组件中依然处处可见Dialog、Button、Dropdown、ErrorMessage、TextInput全部来自frappe-ui见该文件import { Button, Dialog, Dropdown, ErrorMessage, TextInput } from frappe-ui。而更直接的现行案例是 ui/src/components/FormLayout/FormLayout.vue它直接import { Tabs } from frappe-ui把节区渲染在 frappe-ui 的Tabs之上并复用其[roletablist]语义。这正是组合原子而非重建在当前代码中的实际体现。格式化纪律.editorconfig的 tab 约定与 Prettierui/CLAUDE.md明确要求仓库使用tabs缩进。仓库根目录的 .editorconfig 证实了这一约定[{*.py,*.js,*.vue,*.css,*.scss,*.html}] indent_style tab indent_size 4 max_line_length 99即对*.vue、*.js、*.css、*.scss、*.html使用 tab 缩进视觉宽度 4单行上限 99 字符而 JSON多为 doctype schema 文件例外使用空格、缩进 1。Prettier 会读取.editorconfig因此提交前应始终对改动过的文件运行 Prettier避免产生缩进/lint 噪音 diffnpx prettier --write $(git diff --name-only)$(git diff --name-only)只对当前工作区中已修改的文件生效配合仓库的 .editorconfig 即可让 tab 约定自动套用。这也是对 AI Agent 尤其重要的纪律生成的代码如果不跑这一步几乎必然在 CI lint 或 code review 中制造与功能无关的格式 diff。用 frappe-ui 组件构建 Story而不是裸 HTMLStory 是这个库的展示橱窗因此Story 自身的控件与外壳也应使用 frappe-ui 组件而不是裸 HTML 元素。文档给出了明确的优先级能用Select就不用select能用Button就不用button此外还有TextInput、Checkbox、Switch等。这样做的双重收益是Story 视觉上与它所演示的组件保持一致同时dogfood内部试吃这个库。文档特别提到Select的接口它接受v-model加一个options数组纯字符串会自动归一化为{ label, value }对象。仓库中可看到同样模式的实例例如 ui/src/components/Composer/stories/Composer.story.vue 用TabButtons v-modelchannel :optionschannels /构建 Story 内部的频道切换ui/src/components/DataImport/PreviewStep.vue 用TabButtons :buttonstabButtons v-modelactiveTab /做数据预览的页签。这些代码印证了Story/演示界面优先用库内组件的约定是贯穿全仓的。FormLayout 字段类型改动后还要同步 CRM Story这是ui/CLAUDE.md给出的一条具体、可执行的跨仓库维护流程新增或修改FormLayout的 fieldtype 时要把改动同步镜像到 CRM 应用的手动测试 Story。涉及两处文件本仓库内的 ui/src/components/FormLayout/stories/StaticSchema.story.vueCRM 应用中的apps/crm/frontend/src/pages/stories/StaticSchema.story.vueCRM 是 bench 下独立仓库用于在真实消费应用里手动测试各字段类型。两处 Story 必须保持同步因为 CRM 的 Story 才是真实消费应用里验证字段类型的手动测试入口。需要注意一个格式化差异CRM 前端使用 2 空格缩进它有自己独立的 prettier/eslint 配置而本仓库用 tab所以对 CRM 文件运行 Prettier 时必须从apps/crm/frontend目录执行例如cd apps/crm/frontend npx prettier --write src/pages/stories/StaticSchema.story.vue这个例子很好地体现了ui/CLAUDE.md的操作细则属性规则如 FP 原则不告诉你改了 fieldtype 还要同步哪个文件只有工作区笔记会。从源码结构看FormLayout是当前库中接口面最大、测试最密集的模块之一ui/src/components/FormLayout/ 下仅tests/就有十余个测试文件其字段类型确实横跨本仓库与消费应用两侧同步维护的必要性与此一致。子代理Subagents协作模式保持主上下文精简ui/CLAUDE.md最后一部分给出了面向 AI Agent 的协作约定把探索与支线工作下放给子代理默认就做、不用请示以保持主上下文精简。文档建议默认下放的场景有三类代码库探索——定位文件、跨栈追踪特性、查找调用方/使用点、为取一个事实而读大文件。优先用只读的Explore代理它返回结论而非整份文件 dump。无数据依赖的并行工作——互不相关的查询/编辑在同一条消息里一起启动让它们并发运行。验证类支线——测试子集、构建检查、grep 扫描这些原始输出会淹没主上下文。主上下文应保留的是综合结论、决策和真正的修复子代理的输出用户看不到只需把结果中真正重要的部分转述给用户。同时文档给出两条反例例外对于单个已知事实已经知道文件/符号直接读即可——派代理只会增加延迟一旦已把某次搜索委托出去不要自己再跑一遍等待结果即可。这条约定本质上是把上下文窗口是稀缺资源这一工程现实显式化适合任何大模型辅助编码的协作场景也是该仓库鼓励 AI 贡献者采用的工作方式。与仓库其他文档的配套关系要完整使用这份工作区笔记需要把它放在仓库的文档体系中理解ui/PHILOSOPHY.md设计规则书FP*原则的权威出处与ui/CLAUDE.md配套阅读ui/README.md面向消费方的接入指南yarnlink:相对路径安装、tsconfigpaths映射、Vite 插件、island 机制等ui/CONTEXT.md词汇表定义 Sort、Filter、Column、Controlled component、View Snapshot 等术语ui/docs/adr/架构决策记录是原则在具体问题上的应用实例。四者关系可以概括为README 讲怎么用CONTEXT 讲术语是什么PHILOSOPHY 讲规则是什么而ui/CLAUDE.md讲动手时要注意什么。贡献者从ui/CLAUDE.md入门按它的指引走向 PHILOSOPHY 与具体源码即可在framework/ui中做出符合规范、可直接合并的组件改动。【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考