董海洋
902 lines
20 KiB
Markdown
902 lines
20 KiB
Markdown
# Pika 其他组件开发计划与规范
|
||
|
||
> 基于 Pika 设计规范，参照 Ant Design 剩余组件体系，构建专为 AI 代码生成优化的其他组件库。
|
||
|
||
---
|
||
|
||
## 一、组件总览
|
||
|
||
Pika 其他组件分为以下几类：
|
||
|
||
| 类别 | 组件 | antd 对标 | 优先级 |
|
||
|------|------|-----------|--------|
|
||
| **通用组件** | Affix, Anchor, App, ConfigProvider, BackTop, Watermark | Ant Design 通用组件 | P0-P1 |
|
||
| **容器组件** | Drawer | Ant Design 抽屉 | P1 |
|
||
| **数据展示** | List | Ant Design 列表 | P1 |
|
||
|
||
---
|
||
|
||
## 二、核心设计原则（与根规范一致）
|
||
|
||
### 2.1 AI 优先设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **零歧义** | Props 名称自解释，无简称、无隐式行为 |
|
||
| **零默认假设** | 所有视觉行为显式声明 |
|
||
| **一致性** | 相同概念用相同 prop 名 |
|
||
| **扁平化** | 最多一层嵌套 |
|
||
| **确定性** | 相同输入始终产生相同输出 |
|
||
|
||
### 2.2 统一尺寸体系
|
||
|
||
所有组件使用统一的三级尺寸体系：
|
||
|
||
| 级别 | 说明 | 常用值 |
|
||
|------|------|-------|
|
||
| **small** | 小尺寸 | 紧凑列表、表格内 |
|
||
| **middle** | 中尺寸（默认） | 默认使用 |
|
||
| **large** | 大尺寸 | 突出显示、重点元素 |
|
||
|
||
---
|
||
|
||
## 三、通用组件
|
||
|
||
### 3.1 Affix 固钉
|
||
|
||
#### 组件定位
|
||
将页面元素固定在可视区域内，常用于导航栏、侧边栏、回到顶部按钮等。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface AffixProps {
|
||
/** 距离窗口顶部达到指定偏移量后触发 */
|
||
offsetTop?: number;
|
||
/** 距离窗口底部达到指定偏移量后触发 */
|
||
offsetBottom?: number;
|
||
/** 指定 Affix 挂载的 HTML 节点 */
|
||
target?: () => HTMLElement | null;
|
||
/** 监听滚动事件的容器 */
|
||
getContainer?: () => HTMLElement | Window;
|
||
/** 固定状态改变时触发的回调 */
|
||
onChange?: (isAffixed: boolean) => void;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
/** 样式类名 */
|
||
className?: string;
|
||
/** 自定义样式 */
|
||
style?: React.CSSProperties;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { Affix, Button } from '@Pika/ui/affix';
|
||
|
||
// 基本使用
|
||
<Affix offsetTop={10}>
|
||
<Button variant="solid">固钉在顶部</Button>
|
||
</Affix>;
|
||
|
||
// 固钉在底部
|
||
<Affix offsetBottom={10}>
|
||
<Button variant="solid">固钉在底部</Button>
|
||
</Affix>;
|
||
|
||
// 自定义容器
|
||
<Affix target={() => document.getElementById('scroll-container')} offsetTop={10}>
|
||
<Button variant="solid">在容器内固钉</Button>
|
||
</Affix>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-affix-z-index: 10;
|
||
```
|
||
|
||
#### 开发优先级：P1
|
||
|
||
---
|
||
|
||
### 3.2 Anchor 锚点
|
||
|
||
#### 组件定位
|
||
用于跳转到页面指定位置，或显示当前滚动位置。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface AnchorProps {
|
||
/** 锚点方向 */
|
||
direction?: 'vertical' | 'horizontal';
|
||
/** 当前激活的锚点链接 */
|
||
activeLink?: string;
|
||
/** 锚点滚动偏移量 */
|
||
targetOffset?: number;
|
||
/** 点击锚点链接的回调 */
|
||
onClick?: (
|
||
e: React.MouseEvent<HTMLElement>,
|
||
link: { href: string; title: ReactNode }
|
||
) => void;
|
||
/** 锚点链接改变时的回调 */
|
||
onChange?: (currentActiveLink: string) => void;
|
||
/** 获取锚点容器 */
|
||
getContainer?: () => HTMLElement | Window;
|
||
/** 是否改变 hash */
|
||
hash?: boolean;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
/** 样式类名 */
|
||
className?: string;
|
||
/** 自定义样式 */
|
||
style?: React.CSSProperties;
|
||
}
|
||
|
||
export interface AnchorLinkProps {
|
||
/** 锚点链接 */
|
||
href: string;
|
||
/** 锚点文本 */
|
||
title: ReactNode;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { Anchor } from '@Pika/ui/anchor';
|
||
|
||
// 基本使用
|
||
<Anchor>
|
||
<Anchor.Link href="#section-1" title="第一章" />
|
||
<Anchor.Link href="#section-2" title="第二章">
|
||
<Anchor.Link href="#section-2-1" title="2.1 小节" />
|
||
<Anchor.Link href="#section-2-2" title="2.2 小节" />
|
||
</Anchor.Link>
|
||
<Anchor.Link href="#section-3" title="第三章" />
|
||
</Anchor>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-anchor-link-height: 32px;
|
||
--nv-anchor-link-color: var(--nv-text-color-secondary);
|
||
--nv-anchor-link-active-color: var(--nv-color-primary);
|
||
--nv-anchor-link-active-width: 2px;
|
||
--nv-anchor-wrapper-padding: 4px 0;
|
||
```
|
||
|
||
#### 开发优先级：P1
|
||
|
||
---
|
||
|
||
### 3.3 App 包裹组件
|
||
|
||
#### 组件定位
|
||
提供全局上下文，用于 Message、Modal、Notification 等组件的静态方法调用。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface AppProps {
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
}
|
||
|
||
export interface AppContextProps {
|
||
message: MessageStatic;
|
||
modal: ModalStatic;
|
||
notification: NotificationStatic;
|
||
}
|
||
|
||
export declare function useApp(): AppContextProps;
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { App, Button } from '@Pika/ui/app';
|
||
|
||
// 基本使用
|
||
function AppDemo() {
|
||
const { message, modal, notification } = App.useApp();
|
||
|
||
const showMessage = () => {
|
||
message.success('操作成功');
|
||
};
|
||
|
||
const showModal = () => {
|
||
modal.info({ title: '提示', content: '这是一条提示信息' });
|
||
};
|
||
|
||
return (
|
||
<App>
|
||
<Button onClick={showMessage}>显示消息</Button>
|
||
<Button onClick={showModal}>显示对话框</Button>
|
||
</App>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 开发优先级：P0
|
||
|
||
---
|
||
|
||
### 3.4 ConfigProvider 全局配置
|
||
|
||
#### 组件定位
|
||
为组件提供统一的全局配置，包括主题、语言、国际化等。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface ConfigProviderProps {
|
||
/** 主题配置 */
|
||
theme?: {
|
||
token?: Record<string, any>;
|
||
components?: Record<string, any>;
|
||
algorithm?: 'default' | 'dark' | 'compact' | Array<'default' | 'dark' | 'compact'>;
|
||
};
|
||
/** 语言包 */
|
||
locale?: Record<string, any>;
|
||
/** 全局 zIndex */
|
||
zIndex?: number;
|
||
/** 设置主题色 */
|
||
colorPrimary?: string;
|
||
/** 设置图标前缀 */
|
||
iconPrefixCls?: string;
|
||
/** 设置组件类名前缀 */
|
||
prefixCls?: string;
|
||
/** 设置弹框的默认渲染容器 */
|
||
getPopupContainer?: (node: HTMLElement) => HTMLElement;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { ConfigProvider, Button } from '@Pika/ui/config-provider';
|
||
|
||
// 基本使用
|
||
<ConfigProvider
|
||
theme={{
|
||
token: {
|
||
colorPrimary: '#1890ff',
|
||
borderRadius: 8,
|
||
},
|
||
}}
|
||
>
|
||
<App />
|
||
</ConfigProvider>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
与根设计规范中的 Token 一致。
|
||
|
||
#### 开发优先级：P0
|
||
|
||
---
|
||
|
||
### 3.5 BackTop 回到顶部
|
||
|
||
#### 组件定位
|
||
提供快速回到页面顶部的功能。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface BackTopProps {
|
||
/** 距离顶部多少像素时显示 */
|
||
visibilityHeight?: number;
|
||
/** 点击回调 */
|
||
onClick?: () => void;
|
||
/** 监听滚动的容器 */
|
||
target?: () => HTMLElement | Window;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
/** 样式类名 */
|
||
className?: string;
|
||
/** 自定义样式 */
|
||
style?: React.CSSProperties;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { BackTop } from '@Pika/ui/back-top';
|
||
|
||
// 基本使用
|
||
<BackTop />;
|
||
|
||
// 自定义图标
|
||
<BackTop>
|
||
<div style={{
|
||
height: 40,
|
||
width: 40,
|
||
lineHeight: '40px',
|
||
borderRadius: 4,
|
||
backgroundColor: '#1088e9',
|
||
color: '#fff',
|
||
textAlign: 'center',
|
||
fontSize: 20,
|
||
}}>
|
||
UP
|
||
</div>
|
||
</BackTop>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-back-top-size: 40px;
|
||
--nv-back-top-z-index: 10;
|
||
--nv-back-top-color: var(--nv-color-primary);
|
||
--nv-back-top-hover-color: var(--nv-color-primary-hover);
|
||
```
|
||
|
||
#### 开发优先级：P1
|
||
|
||
---
|
||
|
||
### 3.6 Watermark 水印
|
||
|
||
#### 组件定位
|
||
为页面或元素添加水印，防止截图泄露或证明来源。（注意：在 FEEDBACK_COMPONENTS.md 中已有定义，这里补充完整）
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface WatermarkProps {
|
||
/** 水印文字 */
|
||
content?: string | string[];
|
||
/** 自定义图片水印 */
|
||
image?: string;
|
||
/** 水印宽度（文字模式时为单个文字宽度） */
|
||
width?: number;
|
||
/** 水印高度（文字模式时为单个文字高度） */
|
||
height?: number;
|
||
/** 旋转角度 */
|
||
rotate?: number;
|
||
/** 水印之间的水平间距 */
|
||
gap?: [number, number];
|
||
/** 水印在 canvas 上绘制时的偏移量 */
|
||
offset?: [number, number];
|
||
/** 文字样式 */
|
||
font?: {
|
||
color?: string;
|
||
fontSize?: number;
|
||
fontFamily?: string;
|
||
fontWeight?: 'normal' | 'light' | 'weight' | number;
|
||
};
|
||
/** 水印层级 */
|
||
zIndex?: number;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { Watermark, Card } from '@Pika/ui/watermark';
|
||
|
||
// 基本使用
|
||
<Watermark content="Pika UI">
|
||
<Card style={{ width: 600, height: 400 }}>
|
||
<p>这是一些内容，会有水印覆盖</p>
|
||
</Card>
|
||
</Watermark>;
|
||
|
||
// 多行水印
|
||
<Watermark content={['Pika UI', '内部文档']}>
|
||
<div>内容</div>
|
||
</Watermark>;
|
||
|
||
// 自定义样式
|
||
<Watermark
|
||
content="Pika UI"
|
||
rotate={-25}
|
||
font={{
|
||
color: 'rgba(0, 0, 0, 0.08)',
|
||
fontSize: 16,
|
||
}}
|
||
>
|
||
<div>内容</div>
|
||
</Watermark>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-watermark-font-size: 14px;
|
||
--nv-watermark-font-color: rgba(0, 0, 0, 0.08);
|
||
--nv-watermark-rotate: -22deg;
|
||
--nv-watermark-gap: [100, 100];
|
||
--nv-watermark-z-index: 9;
|
||
```
|
||
|
||
#### 开发优先级：P3
|
||
|
||
---
|
||
|
||
## 四、容器组件
|
||
|
||
### 4.1 Drawer 抽屉
|
||
|
||
#### 组件定位
|
||
抽屉组件，用于从屏幕边缘滑出内容面板，常用于详情页、表单页、筛选页等。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export type DrawerPlacement = 'top' | 'right' | 'bottom' | 'left';
|
||
export type DrawerSize = 'small' | 'middle' | 'large' | number | string;
|
||
|
||
export interface DrawerProps {
|
||
/** 抽屉是否可见 */
|
||
open: boolean;
|
||
/** 抽屉标题 */
|
||
title?: ReactNode;
|
||
/** 抽屉宽度（placement 为 left/right 时生效） */
|
||
width?: number | string;
|
||
/** 抽屉高度（placement 为 top/bottom 时生效） */
|
||
height?: number | string;
|
||
/** 抽屉尺寸预设 */
|
||
size?: DrawerSize;
|
||
/** 抽屉放置位置 */
|
||
placement?: DrawerPlacement;
|
||
/** 是否显示遮罩 */
|
||
mask?: boolean;
|
||
/** 点击遮罩是否关闭 */
|
||
maskClosable?: boolean;
|
||
/** 是否显示右上角关闭按钮 */
|
||
closable?: boolean;
|
||
/** 自定义关闭图标 */
|
||
closeIcon?: ReactNode;
|
||
/** 点击关闭图标的回调 */
|
||
onClose?: () => void;
|
||
/** 抽屉打开后的回调 */
|
||
afterOpenChange?: (open: boolean) => void;
|
||
/** 抽屉的容器 */
|
||
getContainer?: HTMLElement | (() => HTMLElement) | null;
|
||
/** 预渲染，防止抖动 */
|
||
forceRender?: boolean;
|
||
/** 关闭时销毁 Drawer 里的子元素 */
|
||
destroyOnClose?: boolean;
|
||
/** 抽屉的样式 */
|
||
style?: React.CSSProperties;
|
||
/** 抽屉标题的样式 */
|
||
headerStyle?: React.CSSProperties;
|
||
/** 抽屉内容的样式 */
|
||
bodyStyle?: React.CSSProperties;
|
||
/** 自定义遮罩样式 */
|
||
maskStyle?: React.CSSProperties;
|
||
/** 抽屉的类名 */
|
||
className?: string;
|
||
/** 抽屉根元素的类名 */
|
||
rootClassName?: string;
|
||
/** 是否支持键盘 esc 关闭 */
|
||
keyboard?: boolean;
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
/** 抽屉页脚 */
|
||
footer?: ReactNode;
|
||
/** 页脚的样式 */
|
||
footerStyle?: React.CSSProperties;
|
||
/** 是否显示页脚 */
|
||
footer?: ReactNode | null;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { Drawer, Button, Form, Input } from '@Pika/ui/drawer';
|
||
|
||
function DrawerDemo() {
|
||
const [open, setOpen] = useState(false);
|
||
|
||
return (
|
||
<>
|
||
<Button onClick={() => setOpen(true)}>打开抽屉</Button>
|
||
<Drawer
|
||
title="基本抽屉"
|
||
width={480}
|
||
open={open}
|
||
onClose={() => setOpen(false)}
|
||
>
|
||
<p>这是抽屉的内容</p>
|
||
<p>可以放置任何内容</p>
|
||
</Drawer>
|
||
</>
|
||
);
|
||
}
|
||
|
||
// 表单抽屉
|
||
function FormDrawer() {
|
||
const [open, setOpen] = useState(false);
|
||
|
||
return (
|
||
<>
|
||
<Button onClick={() => setOpen(true)}>新建</Button>
|
||
<Drawer
|
||
title="新建"
|
||
width={480}
|
||
open={open}
|
||
onClose={() => setOpen(false)}
|
||
footer={
|
||
<div style={{ textAlign: 'right' }}>
|
||
<Button onClick={() => setOpen(false)} style={{ marginRight: 8 }}>
|
||
取消
|
||
</Button>
|
||
<Button variant="solid" onClick={() => setOpen(false)}>
|
||
确定
|
||
</Button>
|
||
</div>
|
||
}
|
||
>
|
||
<Form layout="vertical">
|
||
<Form.Item label="名称" name="name">
|
||
<Input placeholder="请输入名称" />
|
||
</Form.Item>
|
||
<Form.Item label="描述" name="description">
|
||
<TextArea placeholder="请输入描述" rows={4} />
|
||
</Form.Item>
|
||
</Form>
|
||
</Drawer>
|
||
</>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-drawer-z-index: 1000;
|
||
--nv-drawer-header-height: 56px;
|
||
--nv-drawer-header-padding: 16px 24px;
|
||
--nv-drawer-body-padding: 24px;
|
||
--nv-drawer-footer-padding: 16px 24px;
|
||
--nv-drawer-mask-bg: rgba(0, 0, 0, 0.45);
|
||
--nv-drawer-bg: #fff;
|
||
--nv-drawer-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
|
||
--nv-drawer-width-small: 378px;
|
||
--nv-drawer-width-middle: 480px;
|
||
--nv-drawer-width-large: 736px;
|
||
```
|
||
|
||
#### 开发优先级：P1
|
||
|
||
---
|
||
|
||
## 五、数据展示组件
|
||
|
||
### 5.1 List 列表
|
||
|
||
#### 组件定位
|
||
通用列表组件，用于展示一系列同类数据。
|
||
|
||
#### Props 定义
|
||
|
||
```tsx
|
||
export interface ListProps<T> {
|
||
/** 列表数据 */
|
||
data?: T[];
|
||
/** 列表尺寸 */
|
||
size?: 'small' | 'middle' | 'large';
|
||
/** 列表边框 */
|
||
bordered?: boolean;
|
||
/** 是否显示分割线 */
|
||
split?: boolean;
|
||
/** 列表项头部 */
|
||
header?: ReactNode;
|
||
/** 列表项底部 */
|
||
footer?: ReactNode;
|
||
/** 列表加载状态 */
|
||
loading?: boolean;
|
||
/** 空列表时显示的内容 */
|
||
empty?: ReactNode;
|
||
/** 渲染列表项 */
|
||
renderItem?: (item: T, index: number) => ReactNode;
|
||
/** 列表项布局 */
|
||
itemLayout?: 'horizontal' | 'vertical';
|
||
/** 列表行高 */
|
||
rowKey?: string | ((item: T) => string);
|
||
/** 是否显示网格 */
|
||
grid?: {
|
||
gutter?: number;
|
||
column?: number;
|
||
xs?: number;
|
||
sm?: number;
|
||
md?: number;
|
||
lg?: number;
|
||
xl?: number;
|
||
xxl?: number;
|
||
};
|
||
/** 子元素 */
|
||
children?: ReactNode;
|
||
/** 样式类名 */
|
||
className?: string;
|
||
/** 自定义样式 */
|
||
style?: React.CSSProperties;
|
||
}
|
||
|
||
export interface ListItemProps {
|
||
/** 列表项内容 */
|
||
children?: ReactNode;
|
||
/** 列表项的额外内容 */
|
||
extra?: ReactNode;
|
||
/** 列表项的类名 */
|
||
className?: string;
|
||
/** 列表项的样式 */
|
||
style?: React.CSSProperties;
|
||
/** 列表项的 actions */
|
||
actions?: ReactNode[];
|
||
}
|
||
|
||
export interface ListItemMetaProps {
|
||
/** 头像 */
|
||
avatar?: ReactNode;
|
||
/** 标题 */
|
||
title?: ReactNode;
|
||
/** 描述 */
|
||
description?: ReactNode;
|
||
/** 类名 */
|
||
className?: string;
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
import { List, Avatar, Button } from '@Pika/ui/list';
|
||
|
||
// 基本使用
|
||
const data = [
|
||
{ name: '张三', age: 25, avatar: 'https://example.com/avatar1.jpg' },
|
||
{ name: '李四', age: 30, avatar: 'https://example.com/avatar2.jpg' },
|
||
{ name: '王五', age: 28, avatar: 'https://example.com/avatar3.jpg' },
|
||
];
|
||
|
||
<List
|
||
data={data}
|
||
renderItem={(item) => (
|
||
<List.Item>
|
||
<List.Item.Meta
|
||
avatar={<Avatar src={item.avatar} />}
|
||
title={<a href="#">{item.name}</a>}
|
||
description={`年龄: ${item.age}岁`}
|
||
/>
|
||
</List.Item>
|
||
)}
|
||
/>;
|
||
|
||
// 网格列表
|
||
<List
|
||
grid={{ gutter: 16, column: 4 }}
|
||
data={data}
|
||
renderItem={(item) => (
|
||
<List.Item>
|
||
<Card title={item.name}>
|
||
<p>{item.age}岁</p>
|
||
</Card>
|
||
</List.Item>
|
||
)}
|
||
/>;
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-list-item-height-small: 32px;
|
||
--nv-list-item-height-middle: 40px;
|
||
--nv-list-item-height-large: 48px;
|
||
--nv-list-item-padding-small: 8px 12px;
|
||
--nv-list-item-padding-middle: 12px 16px;
|
||
--nv-list-item-padding-large: 16px 24px;
|
||
--nv-list-border-color: var(--nv-color-border);
|
||
--nv-list-split-color: var(--nv-color-border);
|
||
```
|
||
|
||
#### 开发优先级：P1
|
||
|
||
---
|
||
|
||
## 六、开发计划与优先级
|
||
|
||
### 6.1 优先级规划
|
||
|
||
#### Phase 1: 核心通用组件（P0）
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|------|------|---------|
|
||
| App | 包裹组件，提供全局上下文 | 0.5 天 |
|
||
| ConfigProvider | 全局配置组件 | 1 天 |
|
||
|
||
#### Phase 2: 重要通用组件（P1）
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|------|------|---------|
|
||
| Affix | 固钉组件 | 0.5 天 |
|
||
| Anchor | 锚点组件 | 0.5 天 |
|
||
| BackTop | 回到顶部 | 0.5 天 |
|
||
| Drawer | 抽屉组件 | 1.5 天 |
|
||
| List | 列表组件 | 1.5 天 |
|
||
|
||
#### Phase 3: 高级组件（P3）
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|------|------|---------|
|
||
| Watermark | 水印组件 | 0.5 天 |
|
||
|
||
### 6.2 开发里程碑
|
||
|
||
| 阶段 | 任务 | 时间 |
|
||
|------|------|------|
|
||
| Phase 1 | App 和 ConfigProvider | 1 周 |
|
||
| Phase 2 | Affix、Anchor、BackTop、Drawer、List | 2 周 |
|
||
| Phase 3 | Watermark | 0.5 周 |
|
||
|
||
---
|
||
|
||
## 七、通用设计规范
|
||
|
||
### 7.1 Props 命名规范
|
||
|
||
```tsx
|
||
// ✅ Pika 方式
|
||
interface ComponentProps {
|
||
// 尺寸统一
|
||
size?: 'small' | 'middle' | 'large';
|
||
|
||
// 状态统一
|
||
status?: 'default' | 'success' | 'warning' | 'error' | 'info';
|
||
|
||
// 数据统一
|
||
data?: T[];
|
||
|
||
// 布尔属性：动词/形容词 + 肯定形式
|
||
showIcon?: boolean;
|
||
showClose?: boolean;
|
||
closable?: boolean;
|
||
disabled?: boolean;
|
||
loading?: boolean;
|
||
|
||
// 事件：on + 动词 + 名词
|
||
onChange?: (value: any) => void;
|
||
onClick?: (event: MouseEvent) => void;
|
||
onClose?: () => void;
|
||
onOpenChange?: (open: boolean) => void;
|
||
}
|
||
```
|
||
|
||
### 7.2 样式绑定规范
|
||
|
||
```tsx
|
||
// ✅ Pika 方式：使用 data-* 属性
|
||
<div
|
||
data-size={size}
|
||
data-status={status}
|
||
data-variant={variant}
|
||
data-loading={loading}
|
||
/>
|
||
|
||
// CSS 中使用属性选择器
|
||
.component[data-size="small"] {
|
||
font-size: 12px;
|
||
}
|
||
```
|
||
|
||
### 7.3 类型定义规范
|
||
|
||
```tsx
|
||
// ✅ 使用联合类型字面量
|
||
type Size = 'small' | 'middle' | 'large';
|
||
type Status = 'default' | 'success' | 'warning' | 'error' | 'info';
|
||
|
||
// ❌ 避免使用 string 或 any
|
||
type Size = string; // 范围不明确
|
||
type Status = any; // 没有类型提示
|
||
```
|
||
|
||
---
|
||
|
||
## 八、无障碍设计
|
||
|
||
### 8.1 ARIA 属性
|
||
|
||
```tsx
|
||
// Drawer
|
||
<div
|
||
role="dialog"
|
||
aria-modal="true"
|
||
aria-labelledby="drawer-title"
|
||
aria-describedby="drawer-content"
|
||
>
|
||
<h2 id="drawer-title">标题</h2>
|
||
<div id="drawer-content">内容</div>
|
||
</div>
|
||
|
||
// List
|
||
<ul role="list">
|
||
<li role="listitem">列表项 1</li>
|
||
<li role="listitem">列表项 2</li>
|
||
</ul>
|
||
```
|
||
|
||
### 8.2 键盘操作
|
||
|
||
- Drawer 支持 Esc 关闭
|
||
- 所有可点击元素支持 Enter/Space 触发
|
||
- Tab 顺序合理
|
||
|
||
### 8.3 颜色对比度
|
||
|
||
- 文本与背景对比度 ≥ 4.5:1
|
||
- 大文本对比度 ≥ 3:1
|
||
- 图标与背景对比度 ≥ 3:1
|
||
|
||
---
|
||
|
||
## 九、与 Pika 根规范的对照
|
||
|
||
| Pika 根规范 | 实现方式 |
|
||
|------------|---------|
|
||
| **AI 优先** | 所有 Props 使用联合类型字面量，无魔法字符串 |
|
||
| **三级别尺寸** | `small`/`middle`/`large` 统一应用于所有组件 |
|
||
| **统一事件命名** | `on + 动词 + 名词` 规则 |
|
||
| **布尔属性** | 动词/形容词 + 肯定形式 |
|
||
| **data-* 样式绑定** | 使用 `data-*` 属性而非 class 拼接 |
|
||
| **自包含组件** | 每个组件独立导入，路径即名字 |
|
||
| **Apple HIG** | 圆角、间距、动效遵循 Apple 规范 |
|
||
|
||
---
|
||
|
||
## 十、完整组件清单
|
||
|
||
### 10.1 已规划完成的组件
|
||
|
||
- ✅ **通用组件**: Button, FloatButton, Icon, Typography
|
||
- ✅ **数据展示**: Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, Popover, QRCode, Segmented, Statistic, Table, Tag, Timeline, Tooltip, Tour, Tree
|
||
- ✅ **数据录入**: AutoComplete, Cascader, Checkbox, Radio, Switch, DatePicker, Form, Input, InputNumber, Mention, RangePicker, Rate, Select, Slider, Textarea, TimePicker, Transfer, TreeSelect, Upload
|
||
- ✅ **布局组件**: Divider, Flex, Grid, Layout, Masonry, Space, Splitter, Stack
|
||
- ✅ **导航组件**: Breadcrumb, Dropdown, Menu, Pagination, Steps, Tabs
|
||
- ✅ **反馈组件**: Alert, Message, Notification, Modal, Popconfirm, Spin, Progress, Result, Skeleton, Watermark
|
||
|
||
### 10.2 本规范补充的组件
|
||
|
||
- 📋 **通用组件**: Affix, Anchor, App, ConfigProvider, BackTop
|
||
- 📋 **容器组件**: Drawer
|
||
- 📋 **数据展示**: List
|
||
|
||
---
|
||
|
||
## 十一、AI 生成提示
|
||
|
||
当 AI 生成 Pika 组件相关代码时，请遵循以下提示：
|
||
|
||
```
|
||
1. 导入路径 = @Pika/ui/组件名
|
||
2. 尺寸 prop 始终叫 size，值从 small/middle/large 选
|
||
3. 数据 prop 始终叫 data
|
||
4. 布尔 prop 用动词/形容词开头
|
||
5. 所有 prop 类型用联合类型字面量定义
|
||
6. 使用 data-* 属性进行样式绑定
|
||
7. 事件回调 = on + 动词 + 名词
|
||
8. 参考 Ant Design API 但按照 Pika 规范调整命名
|
||
```
|
||
|
||
---
|
||
|
||
> **Pika 其他组件计划完成！所有必要组件的规范已制定完毕。**
|
||
|