split-ui-components git:20261018.4caf5d8A

Immutable. This exact content never changes and is served at /api/v1/blob/bea430409334b16f.

---
name: split-ui-components
description: "Choose or refactor UI component boundaries and state ownership. Use for oversized components, over-abstraction or behavior-preserving component extraction."
---

# UI 组件拆分

按业务语义、变化原因和状态所有权选择边界。文件行数、JSX 深度和 props 数量不能代替工程判断。

## 选择动作

检查目标组件、相关调用方及影响本次改动的项目约定。区分一起变化的职责与仅处在同一文件的代码，不预读整套架构或框架文档。

| 事实 | 动作 |
| --- | --- |
| 单一语境且没有独立变化或交互边界 | 保持原状 |
| 有清晰语义和独立职责，尚无跨语境复用 | 提取私有组件或逻辑单元 |
| 多个实际消费者共享同一业务契约 | 提取业务共享组件 |
| 跨业务契约、主题和无障碍要求均已稳定 | 考虑设计系统基础组件 |

分析请求只给建议；实施请求完成边界调整和相关验证；评审请求优先指出有证据的欠拆、过拆、错误抽象或状态问题。不要把局部拆分扩大为全仓迁移。

## 保持的契约

- DOM 语义、可访问名称、键盘操作、焦点和事件结果。
- 状态身份、重置时机、异步取消及错误处理。
- 公开 props、导出、导入路径及调用方，除非任务明确要求变更。
- 样式作用域、响应式行为和资源加载。

先移动边界清楚的代码，再做必要抽象。按实际所有权放置状态；不因视觉框、一次重复或可能的未来复用创建通用组件。不为方便测试暴露内部实现，也不以猜测的性能问题驱动拆分。

## 按需参考与验证

- 边界或共享 API 存在真实取舍时读 [decision-framework.md](references/decision-framework.md)。
- React 状态身份、Effect、Hook 或组合语义受影响时读 [react.md](references/react.md)；其他框架不套用 React 规则。
- 需要辨别具体错误抽象时读 [examples.md](references/examples.md)。

根据变更运行相关类型、行为或构建检查，遵守项目强制门禁。状态、交互和生命周期变化需要验证对应的页面操作与失败路径；单纯代码移动不自动要求所有状态或全量构建。测试用户可观察行为，不固定私有组件树。

完成范围内修复、相关复验和临时资源清理，再说明结果和剩余验证缺口。