---
name: zui-component
description: "在 ZUI 主仓库的 lib/* 中设计、实现或修复组件及 Web Component 适配；需求明确时完成必要设计后直接实施。"
---

# ZUI 组件开发

## 准备

按 [共享工作流](../zui-standards/references/workflow.md) 定位目标、检查所有权并复用已有发现。组件实现读取 [组件规范](../zui-standards/references/component.md) 的相关部分；运行时加载外部资源再读 external-library 规范，涉及包元数据再读 library 规范，其他领域按需路由。

涉及自定义元素时，读取 [Web Component 规范](../zui-standards/references/web-component.md)。无论采用独立工厂配置还是元素子类，定义必须在 `lib/<lib-name>/src/web-component/` 内实现，并经该目录 `index.ts` 和库 `src/main.ts` 导出。

阅读本次判断所需的目标源码；架构或公开契约尚不清楚时再检查相似实现。默认仅修改目标库；新增第三方依赖时，按[第三方依赖的版权与文档](../zui-standards/references/workflow.md#第三方依赖的版权与文档)将 `licenses/` 和公共依赖说明纳入必要文件集，其余跨库修改须在任务范围内。

新增组件或能力前执行[先查找，再复用](../zui-standards/references/workflow.md#复用已有能力)，检索并核实可组合的已有组件和 helper；设计中说明所复用的 API 或必须新增的缺口。

可视组件库读取[组件预览规范](../zui-standards/references/component-preview.md)，检查 `assets/preview.html`。新建时随组件交付，维护时按该规范补齐目标库缺失的预览，并随主要外观或用途变化更新。

## 理解与设计

1. 从现有代码、请求及已确认决定推断用途、场景、目标用户和约束。合理沿用既有约定并说明；同一术语仍有无法可靠消除、会实质改变组件身份、包角色、架构或公开契约的歧义时，提出 1–3 个最少必要问题，暂缓依赖该答案的设计，不以假设代替高影响选择。其他只读调查可继续。
2. 只询问无法从仓库发现且会改变设计的信息，通常包括：
   - 需要支持的 HTML/CSS、Preact、vanilla 构造器、Web Component、`zui-create` 或 toggle 消费方式；
   - 受控或非受控状态、事件、命令式方法、异步和错误行为；
   - 视觉变体、响应式、键盘、焦点、ARIA 与国际化要求。
3. 提问时说明已确认的背景及问题影响；答案明确后继续相关设计。需求明确后按共享工作流继续实施。
4. 分别判断包角色和实现架构。不要因为包类型是 `component` 就默认使用 Preact，也不要因使用 Preact 就改变包角色。
5. 定义最小公开 API、状态或数据流、DOM 生命周期与清理策略。仅暴露真实需要的入口。

## 实施计划

按共享工作流形成可直接实施的计划；以下仅展开本次相关决策：

- 类型判断：包角色、组件架构及必要参考依据；
- 目标、非目标和验收场景；
- 公开 API：消费方式、options/props、事件、方法、类型及兼容性；Web Component 还需确定标签、注册时机、attribute/property 映射和表单关联需求；
- 实现方式：渲染、状态/数据流、生命周期、清理、无障碍和 i18n；
- 外部资源（若有）：`LibLoader` 所有权、注册名、资源/check/依赖、加载时机、失败重试、开发资源与销毁竞态；
- 文件集、入口导出、依赖和 `contributes` 影响；
- 标准组件预览的代表状态、文件与验证；正式文档与调试页是否纳入；
- 验证方式、边界场景和仍存在的假设。

需求明确后直接实施；任务范围、必要澄清及协作模式遵循共享工作流。

## 实施

1. 重新检查工作区状态，按任务范围和计划实施。
2. 使用 Preact 而不是 React，并遵循[状态与副作用规范](../zui-standards/references/component.md#preact-状态与副作用)：禁止 hooks，响应式状态推荐 signals，按生命周期清理 `effect`。跨库导入使用 `@zui/<name>`；显式维护局部和库入口导出。
3. 运行时外部依赖统一通过库内单例 `LibLoader<T>` 按需加载，并落实加载失败、重试、异步销毁竞态和第三方实例清理；不要在组件内直接调用 `$.getLib`、注入资源标签或维护第二份模块缓存。
4. 按 [布局与样式规范](../zui-standards/references/component.md#布局与样式) 实现样式，落实组件 CSS 的 `@apply` 优先和 `src/style/index.ts` 统一入口规则；新增或修改布局类时，读取并执行 [CSS utilities 核实流程](../zui-standards/references/utilities.md)，核对公开支持、实际效果及目标产物后再使用。落实语义标签、键盘、焦点和 ARIA。
5. 按组件预览规范交付或维护目标库的静态预览及封面页入口；其余 i18n、正式文档与调试页仅在任务范围内调用或遵循 `$zui-i18n`、`$zui-doc`、`$zui-dev`。
6. 按共享工作流验证本次改动、修复范围内问题并复跑受影响检查；组件验收项目按本次涉及的行为选择。
7. 汇报实现文件、公开 API、验证结果和未验证风险，不自动提交。