企业官网建设流程全解析

导读

本指南讲解 open-slide 仓库中vercel-composition-patterns技能包的核心架构规则——避免布尔属性泛滥（Avoid Boolean Prop Proliferation）。它面向两类读者：一类是在 open-slide 的 UI 组件（如packages/core/src/app/components/ui/下的组件）或自己构建幻灯片组件时，需要设计可扩展组件 API 的开发者；另一类是编写代码的 Agent，需要识别和重构「isThread、isEditing、isDMThread」这类布尔开关堆砌的组件。读完本文，你将掌握布尔属性为何会产生指数级复杂度、如何用组合式（Compound）组件与显式变体重构它们，以及 open-slide 源码中可验证的落地范例。

规则定位：为什么它是 CRITICAL 级架构规则

该规则文件位于 .agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md，frontmatter 中明确标注：

• title: Avoid Boolean Prop Proliferation
• impact: CRITICAL
• impactDescription: prevents unmaintainable component variants（防止产生不可维护的组件变体）
• tags: composition, props, architecture

在整个技能包中，这条规则与 architecture-compound-components.md 一起被归入Component Architecture（组件架构）分类，并排在优先级第一位。正如 .agents/skills/vercel-composition-patterns/README.md 所述，它的核心原则是：

1. 组合优先于配置（Composition over configuration）——与其不断加属性，不如让使用者自由组合；
2. 提升状态（Lift your state）——状态放在 Provider 中，而不是困在组件内部；
3. 组合内部实现（Compose your internals）——子组件通过 Context 访问共享状态，而不是接收一堆属性；
4. 显式变体（Explicit variants）——创建ThreadComposer、EditComposer，而不是一个带isThread的Composer。

问题本质：每个布尔属性都让状态空间翻倍

规则文档给出了核心论断：

Don't add boolean props likeisThread,isEditing,isDMThreadto customize component behavior. Each boolean doubles possible states and creates unmaintainable conditional logic. Use composition instead.

这里的数学是直观且可推导的：一个组件每增加一个布尔属性，其可能的状态组合数量就翻一倍。n个布尔属性意味着2^n种状态组合：

• 3 个布尔：2³ = 8种组合；
• 5 个布尔：2⁵ = 32种组合；
• 8 个布尔：2⁸ = 256种组合。

而其中绝大多数组合是「不可能状态」（例如isDMThread && isThread同时为真时语义是什么？isEditing && isForwarding并存时渲染哪套操作？），测试用例、类型定义、代码审查者都必须逐一考虑这些组合。更隐蔽的问题是条件逻辑的嵌套顺序：代码中isDMThread ? ... : isThread ? ... : ...的优先级本身就成了隐式契约，一旦调用方传入的组合落在某个未预期的分支里，渲染结果就变成「看似能跑但逻辑错误」。

反模式示例：一个 Composer，六个布尔开关

规则文档给出了一个教科书式的反面案例——一个聊天 Composer 组件，用isThread、isDMThread、isEditing、isForwarding四个布尔属性（连同channelId、dmId两个业务字段）来控制所有变体：

function Composer({ onSubmit, isThread, channelId, isDMThread, dmId, isEditing, isForwarding, }: Props) { return ( <form> <Header /> <Input /> {isDMThread ? ( <AlsoSendToDMField id={dmId} /> ) : isThread ? ( <AlsoSendToChannelField id={channelId} /> ) : null} {isEditing ? ( <EditActions /> ) : isForwarding ? ( <ForwardActions /> ) : ( <DefaultActions /> )} <Footer onSubmit={onSubmit} /> </form> ) }

这段代码的问题清单：

• 不可维护的条件逻辑：三段式三元表达式层层嵌套，新增一个「转发到群组」的变体就要再插一层分支，并重新梳理优先级；
• 组合爆炸：4 个布尔开关意味着 16 种状态组合，绝大多数没有意义；
• 隐式契约：isEditing ? <EditActions/> : isForwarding ? ...中的分支顺序就是没人写下来的规则，改错顺序就会静默产生错误 UI；
• 无法被类型系统约束：Props 层面允许任何布尔组合，isEditing && isForwarding这类非法状态在编译期无法拦截。

从调用方的视角看，这个组件同样难以理解——patterns-explicit-variants.md 用一句反问点破了这种体验：「What does this component actually render?（这个组件到底渲染了什么？）」：

<Composer isThread isEditing={false} channelId='abc' showAttachments showFormatting={false} />

没人能一眼看出这个调用会渲染出什么 UI。

正确做法：组合式变体，显式声明每个组件渲染什么

规则文档给出的正确示例，是把 Composer 拆成一个可复用的组合式骨架（Composer.Frame、Composer.Header、Composer.Input、Composer.Footer），然后用显式变体组件去组合出不同的能力：

// Channel composer function ChannelComposer() { return ( <Composer.Frame> <Composer.Header /> <Composer.Input /> <Composer.Footer> <Composer.Attachments /> <Composer.Formatting /> <Composer.Emojis /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> ) } // Thread composer - adds "also send to channel" field function ThreadComposer({ channelId }: { channelId: string }) { return ( <Composer.Frame> <Composer.Header /> <Composer.Input /> <AlsoSendToChannelField id={channelId} /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> ) } // Edit composer - different footer actions function EditComposer() { return ( <Composer.Frame> <Composer.Input /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.CancelEdit /> <Composer.SaveEdit /> </Composer.Footer> </Composer.Frame> ) }

规则文档的收尾总结值得逐句品味：

Each variant is explicit about what it renders. We can share internals without sharing a single monolithic parent.

也就是说：每个变体都明确声明自己渲染什么；共享的是内部零件，而不是一个臃肿的父组件。调用方也因此获得了自文档化的 API——patterns-explicit-variants.md中对应的重构结果一目了然：

// Immediately clear what this renders <ThreadComposer channelId="abc" /> // Or <EditMessageComposer messageId="xyz" /> // Or <ForwardMessageComposer messageId="123" />

类型系统现在也真正参与约束：ThreadComposer只接受channelId，EditMessageComposer只接受messageId，非法状态在编译期就不可能构造出来。正如该规则文件所述，每个显式变体都清楚标明「使用哪个 Provider/状态、包含哪些 UI 元素、提供哪些操作」，不存在需要推理的布尔组合，也不存在不可能状态。

支撑它的底层模式：复合组件 + Context + 显式变体

「避免布尔属性」并非孤立规则，它依赖技能包内一整套相互咬合的模式（见 .agents/skills/vercel-composition-patterns/SKILL.md 的规则分类）：

复合组件（Compound Components）——architecture-compound-components.md 说明，复杂组件应拆成「共享一个 Context 的复合组件」，每个子组件通过 Context 而非 props 访问共享状态，消费者按需拼装。其典型形态是Composer作为一个对象，挂载Provider / Frame / Input / Submit / Header / Footer等子组件；状态、操作（actions）与元信息（meta）由父级 Provider 依赖注入：

const ComposerContext = createContext<ComposerContextValue | null>(null) function ComposerProvider({ children, state, actions, meta }: ProviderProps) { return ( <ComposerContext value={{ state, actions, meta }}> {children} </ComposerContext> ) } function ComposerInput() { const { state, actions: { update }, meta: { inputRef }, } = use(ComposerContext) return ( <TextInput ref={inputRef} value={state.input} onChangeText={(text) => update((s) => ({ ...s, input: text }))} /> ) } // Export as compound component const Composer = { Provider: ComposerProvider, Frame: ComposerFrame, Input: ComposerInput, Submit: ComposerSubmit, Header: ComposerHeader, Footer: ComposerFooter, Attachments: ComposerAttachments, Formatting: ComposerFormatting, Emojis: ComposerEmojis, }

注意示例中读取 Context 使用的是 React 19 的use()而非useContext()——这正是技能包中 react19-no-forwardref.md 所强调的 React 19 API 迁移（该技能包同时提示：React 19 之前请跳过此节）。

状态提升与 Context 接口——同属该技能包的 state-lift-state.md（把状态提升进 Provider 以便兄弟组件共享）与 state-context-interface.md（定义state / actions / meta三段式 Context 接口）为复合组件提供了状态侧的支撑，正是前面ComposerContextValue三元组的来源。

显式变体——patterns-explicit-variants.md 把「拆变体」进一步落地为带各自 Provider 的独立组件，每个变体内部可以用不同 Provider 注入不同业务状态（如ThreadProvider、EditMessageProvider、ForwardMessageProvider），进一步消除了「一个组件多个模式」的残留。

仓库中的落地证据：open-slide 组件库正是这么做的

该规则并非悬空的教条——open-slide 自己的组件实现就是「Context + 复合组件」的实际案例，可以直接对照源码验证。

ToggleGroup：共享 Context 的复合组件。在 packages/core/src/app/components/ui/toggle-group.tsx 中，ToggleGroup建立了一个包含size / variant / spacing的ToggleGroupContext，用ToggleGroupContext.Provider把配置注入子树；ToggleGroupItem则通过React.useContext(ToggleGroupContext)读取这些值来推导自己的样式（context.variant || variant、context.size || size）。这正是「父组件通过 Context 而非逐项传 prop 分发共享配置」的组合式结构，spacing这类样式配置只需在根上声明一次，所有子项自动继承。

Provider 化的状态管理。open-slide 源码中存在多处「状态提升到 Provider」的实现，可以印证该技能的 state 侧规则：

• inspector-provider.tsx：Inspector 的编辑状态由 Provider 统一管理，子组件通过 Context 访问；
• design-provider.tsx：样式面板的设计状态（对应use-design.ts的消费）通过 Provider 注入；
• page-context.tsx 与 step-context.tsx：页与 Step 的上下文以 Provider 形态向幻灯片渲染树广播；
• history-provider.tsx：编辑历史状态集中管理。

从这些文件可以看出，open-slide 的 UI 层广泛采用「Provider + Context 消费」而非「把布尔开关塞进每个子组件」的架构——这正是 architecture-avoid-boolean-props.md 所倡导的方向，在仓库中是可持续验证的实现事实。

另外，该技能包的用途在 SKILL.md 中有明确描述：它专门用于「重构存在布尔属性泛滥的组件、构建可复用组件库、设计灵活组件 API、审查组件架构」等场景。它甚至点明了这套模式对 Agent 的价值——组合式的代码库「让人类和 AI Agent 都更容易在规模增长时继续工作」。

实战检查清单：如何把这条规则落到 open-slide 的组件上

结合规则文档与技能包 README.md，可以在写或审查组件时执行以下检查：

1. 数一数 props 里的布尔开关：出现isXxx、showXxx、hasXxx超过一个时，立即评估是否进入2^n状态空间；
2. 识别「模式」而非「选项」：isThread、isEditing这类描述的是组件的不同工作模式，应该拆成ThreadComposer、EditComposer这样的独立变体组件（参考 patterns-explicit-variants.md）；
3. 共享部分下沉为复合组件：把Frame / Header / Input / Footer这类骨架作为复合组件暴露（参考 architecture-compound-components.md），变体之间共享零件但各自声明渲染内容；
4. 用 Context 承载共享状态：变体内共享的状态放进 Provider，子组件用use(Context)消费，避免 prop drilling 卷土重来（参考 state-lift-state.md 与 state-context-interface.md）；
5. 验证调用方能否「一眼看懂」：如果一行调用<X isA isB={false} ... />无法瞬间说清渲染结果，说明重构还没到位。

总结

「避免布尔属性泛滥」这条 CRITICAL 级规则的实质，是把组件的变体从调用方的 props 迁移到独立的组件类型：布尔开关把复杂度分摊给所有调用点，而组合式变体把复杂度收拢到一处、显式声明，其余调用点拿到的是自文档化、类型受限、不可能构造非法状态的 API。open-slide 的技能包为其配套了复合组件、状态提升、Context 接口与显式变体一整套模式，仓库自身的 UI 组件（如toggle-group.tsx及各类 Provider）也验证了这些模式在真实项目中的可落地性。对编写 open-slide 相关组件的开发者与 Agent 而言，这条规则是组件架构审查的第一道关卡——它能最直接地防止组件在迭代中滑向「不可维护的变体集合」。