用途:在 Common UI v2 组件库(packages/ui/src/v2)中创建或修改以 cf- 为前缀的 Lit Web 组件,实现主题感知组件、接入运行时 Cell 抽象、构建响应式组件,以及排查组件生命周期与响应性问题。不适用于编写或设置消费 cf- 组件的 pattern UI,那属于 pattern-ui 职责。
主要能力与设计理念:遵循 SwiftUI 式思路,强调默认配置可用、组合优于精细样式控制、尊重系统与主题偏好、FRP 风格 Cell 响应式绑定、渐进增强(普通值可用,Cell 增强响应性)与关注点分离。组件按类别分为布局、视觉、输入、复杂集成四类,应选用满足需求的最简模式。
使用方式:在 packages/ui/src/v2/components/cf-component-name/ 下创建组件文件、index.ts 与可选 styles.ts,继承 BaseElement,定义静态 properties 与 render(),并在 index 中以守卫方式 customElements.define 注册。主题大多使用 var(--cf-theme-*) CSS 变量并提供回退;需要运行时逻辑时才消费 cfThemeContext。Cell 集成以 @property({ attribute: false }) 声明,用 cell.sink() 订阅并在断开时取消订阅,通过事务修改。测试与组件同目录,使用 deno task test 运行。
限制与注意:不得在构造函数中 setAttribute,应在 connectedCallback 中设置;Cell 订阅必须清理并在 disconnectedCallback 取消;不要直接用数组索引作 repeat 的 key;对象、数组与 Cell 使用 attribute: false;始终调用 super 生命周期方法;需提供 CSS 变量回退。具体主题变量、Cell 模式与高级架构细节见随附参考文档。