董海洋
49 lines
1.4 KiB
Markdown
49 lines
1.4 KiB
Markdown
# Pika 开发约定
|
||
|
||
## 目录结构
|
||
|
||
- 组件目录使用 **kebab-case**：`display/avatar/`、`entry/tree-select/`
|
||
- 组件文件使用 **PascalCase**：`Avatar.tsx`
|
||
- 每个组件目录包含：`*.tsx`、`*.module.css`、`index.ts`、`*.test.tsx`
|
||
|
||
## 导出规范
|
||
|
||
- 组件 TSX 使用 **named export**
|
||
- barrel `index.ts` 统一 re-export 类型与组件
|
||
|
||
## Props 规范
|
||
|
||
- 接口中只声明**已实现**的 props，避免 AI 生成无效代码
|
||
- 暂未实现的 API 不要提前写入类型定义
|
||
|
||
## 样式规范
|
||
|
||
| 层级 | 前缀 | 示例 |
|
||
|------|------|------|
|
||
| 全局 token | `--nv-` | `--nv-color-primary` |
|
||
| 组件动态值 | `--_*` | `--_height`、`--_padding` |
|
||
|
||
- 优先使用 CSS Module + `var(--nv-*)`
|
||
- className 拼接使用 `cn()` from `shared/utils/classNames`
|
||
|
||
## 共享层
|
||
|
||
| 模块 | 用途 |
|
||
|------|------|
|
||
| `shared/hooks/useControllableState` | 受控/非受控状态 |
|
||
| `shared/hooks/usePikaContext` | ConfigProvider 上下文 |
|
||
| `shared/hooks/useClickOutside` | 下拉/浮层点击外部关闭 |
|
||
| `shared/overlay/useOverlay` | Tooltip/Popover 浮层逻辑 |
|
||
| `shared/utils/cn` | className 合并 |
|
||
| `shared/utils/getSemanticProps` | semantic DOM 样式 |
|
||
|
||
## 类型
|
||
|
||
- 统一使用 `PikaSize`、`PikaStatus`（`shared/types/common.ts`）
|
||
- Entry 组件通过 `DataEntrySize` / `DataEntryStatus` 别名引用
|
||
|
||
## 测试
|
||
|
||
- 每个主组件至少一个 `*.test.tsx`
|
||
- 测试交互行为，而非实现细节
|