# 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 规范调整命名
```

---

&gt; **Pika 其他组件计划完成！所有必要组件的规范已制定完毕。**