Back to Details

compose-component-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Compose component design

Compose组件设计

Core principle

核心原则

Make reusable components caller-placeable and caller-composable: the component owns its invariant structure while callers retain placement, content, and policy choices that vary by use.
让可复用组件支持调用方定位与调用方组合：组件负责其不变的结构，而调用方保留随使用场景变化的定位、内容和策略选择。

Procedure

实施步骤

  1. State the component's invariant visual structure and identify every varying region, placement concern, and policy choice.
  2. Accept and apply a caller modifier at the component root unless a concrete API boundary makes another placement correct.
  3. Represent caller-controlled, unconstrained visual regions with slots rather than proliferating primitive content parameters or Boolean shape flags. Keep semantic and design-system constraints as primitive parameters.
  4. Keep simple conditional structure inline; extract only a coherent reusable contract.
  5. Read the relevant focused reference below before editing public signatures.
  6. Finish when callers can position the component, supply variable content, and understand ownership without needing hidden layout or content switches.
  1. 明确组件的不变视觉结构，识别所有可变区域、定位关注点和策略选择。
  2. 除非具体的API边界要求其他定位方式，否则在组件根节点接收并应用调用方提供的modifier。
  3. 使用Slot而非大量原始内容参数或布尔形状标志来表示调用方可控的无约束视觉区域。将语义和设计系统约束保留为原始参数。
  4. 简单的条件结构保持内联；仅提取连贯的可复用契约。
  5. 修改公共签名前，阅读下方相关的聚焦参考文档。
  6. 当调用方能够定位组件、提供可变内容，且无需隐藏的布局或内容切换即可明确职责归属时，完成设计。

Topic router

主题指引

SignalRead
Modifier parameter, root layout placement, modifier ordering, or conditional layout wrappersModifier and layout
Caller-controlled variable visual regions, optional content, primitive content parameters, or Boolean shape flagsSlot APIs
Animation belongs to the public component contractCompose animations
State ownership changes while designing the componentCompose state and effects
Semantics or screenshot coverage is neededCompose UI testing patterns
信号阅读文档
Modifier参数、根布局定位、Modifier排序或条件布局包装器Modifier与布局
调用方可控的可变视觉区域、可选内容、原始内容参数或布尔形状标志Slot API
动画属于公共组件契约的一部分Compose动画
设计组件时需要变更状态归属Compose状态与副作用
需要语义或截图覆盖Compose UI测试模式

RED/GREEN agent scenarios

RED/GREEN方案场景

  1. RED exposes 
    title: String
    , 
    icon: ImageVector?
    , and several display flags for a reusable card. GREEN keeps invariant chrome and gives callers the variable regions as named slots.
  2. Novel case: a component needs both a root modifier and caller-supplied trailing content. GREEN applies the modifier at the root and supplies a trailing slot without leaking internal layout.
  3. Counterexample: a private screen helper has one fixed child and no callers. GREEN keeps it simple instead of inventing slots for hypothetical reuse.
  1. RED方案为可复用卡片暴露
    title: String
    、
    icon: ImageVector?
    以及若干显示标志。GREEN方案保留不变的框架部分，并将可变区域以命名Slot的形式提供给调用方。
  2. 特殊案例：组件同时需要根节点modifier和调用方提供的尾部内容。GREEN方案在根节点应用modifier，并提供尾部Slot，不泄露内部布局细节。
  3. 反例：私有页面助手只有一个固定子节点且无调用方。GREEN方案保持简洁，不为假设的复用场景创建Slot。