董海洋
661 lines
14 KiB
Markdown
661 lines
14 KiB
Markdown
# Pika 布局组件规划
|
||
|
||
> 基于 Pika 设计规范的布局组件设计
|
||
> 设计原则：以 Apple HIG 为准，AI-First，三级别尺寸体系
|
||
|
||
---
|
||
|
||
## 一、核心理念
|
||
|
||
### 1.1 设计价值观（与根规范一致）
|
||
|
||
Pika 布局组件基于 Apple Human Interface Guidelines 的三大核心原则构建：
|
||
|
||
| 原则 | 说明 |
|
||
|-----|------|
|
||
| **层级** | 建立清晰的视觉层级，区分内容和控件 |
|
||
| **和谐** | 与硬件和软件设计保持一致 |
|
||
| **一致性** | 采用平台约定，跨组件保持统一 |
|
||
|
||
### 1.2 AI-First 设计原则
|
||
|
||
所有布局组件遵循 Pika 的 AI-First 设计原则：
|
||
|
||
| 原则 | 说明 |
|
||
|-----|------|
|
||
| **零歧义** | Props 名称自解释，无简称、无隐式行为 |
|
||
| **零默认假设** | 所有视觉行为显式声明 |
|
||
| **一致性** | 相同概念用相同 prop 名 |
|
||
| **扁平化** | 最多一层嵌套 |
|
||
| **确定性** | 相同输入始终产生相同输出 |
|
||
|
||
---
|
||
|
||
## 二、统一尺寸体系（三级别）
|
||
|
||
所有布局组件使用统一的三级别尺寸体系：
|
||
|
||
| 级别 | 间距 | 圆角 | 字体大小 |
|
||
|-----|------|------|---------|
|
||
| **small** | 8px | 4px | 12px |
|
||
| **middle** | 16px | 8px | 14px |
|
||
| **large** | 24px | 12px | 16px |
|
||
|
||
### 2.1 Design Token（与根规范一致）
|
||
|
||
```css
|
||
--nv-spacing-small: 8px;
|
||
--nv-spacing-middle: 16px;
|
||
--nv-spacing-large: 24px;
|
||
|
||
--nv-radius-small: 4px;
|
||
--nv-radius-middle: 8px;
|
||
--nv-radius-large: 12px;
|
||
--nv-radius-full: 9999px;
|
||
|
||
--nv-font-size-small: 12px;
|
||
--nv-font-size-middle: 14px;
|
||
--nv-font-size-large: 16px;
|
||
```
|
||
|
||
---
|
||
|
||
## 三、组件体系
|
||
|
||
### 3.1 组件清单
|
||
|
||
| 组件 | 说明 | 优先级 |
|
||
|-----|------|-------|
|
||
| **Layout** | 页面布局容器 | P0 |
|
||
| **Header** | 顶部导航栏 | P0 |
|
||
| **Footer** | 底部区域 | P0 |
|
||
| **Content** | 内容区域 | P0 |
|
||
| **Sider** | 侧边栏 | P0 |
|
||
| **Row** | 栅格行 | P1 |
|
||
| **Col** | 栅格列 | P1 |
|
||
| **Space** | 间距组件 | P2 |
|
||
| **HStack** | 水平排列 | P2 |
|
||
| **VStack** | 垂直排列 | P2 |
|
||
| **Divider** | 分隔线 | P2 |
|
||
|
||
---
|
||
|
||
## 四、组件详细设计
|
||
|
||
### 4.1 Layout 布局容器
|
||
|
||
#### Props 定义（AI-First）
|
||
|
||
```tsx
|
||
export interface LayoutProps {
|
||
/** 是否有侧边栏（用于 SSR 避免样式闪烁） */
|
||
hasSider?: boolean
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
export interface HeaderProps {
|
||
/** 高度 */
|
||
height?: number | string
|
||
/** 是否固定在顶部 */
|
||
fixed?: boolean
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
export interface FooterProps {
|
||
/** 内边距 */
|
||
padding?: number | string
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
export interface ContentProps {
|
||
/** 内边距 */
|
||
padding?: number | string
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
export interface SiderProps {
|
||
/** 宽度 */
|
||
width?: number | string
|
||
/** 折叠后的宽度 */
|
||
collapsedWidth?: number
|
||
/** 是否可折叠 */
|
||
collapsible?: boolean
|
||
/** 当前折叠状态 */
|
||
collapsed?: boolean
|
||
/** 默认折叠状态 */
|
||
defaultCollapsed?: boolean
|
||
/** 折叠状态变化回调 */
|
||
onCollapse?: (collapsed: boolean) => void
|
||
/** 响应式断点 */
|
||
breakpoint?: 'small' | 'middle' | 'large'
|
||
/** 断点变化回调 */
|
||
onBreakpoint?: (broken: boolean) => void
|
||
/** 是否反转箭头方向 */
|
||
reverseArrow?: boolean
|
||
/** 自定义触发器 */
|
||
trigger?: React.ReactNode
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 基础布局
|
||
<Layout>
|
||
<Layout.Header>Header</Layout.Header>
|
||
<Layout.Content>Content</Layout.Content>
|
||
<Layout.Footer>Footer</Layout.Footer>
|
||
</Layout>
|
||
|
||
// 经典后台布局
|
||
<Layout>
|
||
<Layout.Sider
|
||
width={200}
|
||
collapsedWidth={80}
|
||
collapsible
|
||
breakpoint="middle"
|
||
>
|
||
<Menu />
|
||
</Layout.Sider>
|
||
<Layout>
|
||
<Layout.Header fixed>Header</Layout.Header>
|
||
<Layout.Content padding={24}>Content</Layout.Content>
|
||
</Layout>
|
||
</Layout>
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-layout-header-height: 64px;
|
||
--nv-layout-footer-padding: var(--nv-spacing-middle);
|
||
--nv-layout-sider-width: 200px;
|
||
--nv-layout-sider-collapsed-width: 80px;
|
||
--nv-layout-trigger-height: 48px;
|
||
--nv-layout-content-padding: var(--nv-spacing-middle);
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 Grid 栅格系统
|
||
|
||
#### Props 定义（AI-First）
|
||
|
||
```tsx
|
||
export interface RowProps {
|
||
/** 栅格间隔 */
|
||
gutter?: number | [number, number]
|
||
/** 主轴对齐方式 */
|
||
justify?: 'start' | 'end' | 'center' | 'space-around' | 'space-between'
|
||
/** 交叉轴对齐方式 */
|
||
align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
export interface ColProps {
|
||
/** 栅格格数 (0-24) */
|
||
span?: number
|
||
/** 左侧偏移格数 */
|
||
offset?: number
|
||
/** 栅格顺序 */
|
||
order?: number
|
||
/** 响应式栅格 */
|
||
small?: number | { span?: number; offset?: number; order?: number }
|
||
middle?: number | { span?: number; offset?: number; order?: number }
|
||
large?: number | { span?: number; offset?: number; order?: number }
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 基础栅格
|
||
<Row gutter={16}>
|
||
<Col span={12}><Card /></Col>
|
||
<Col span={12}><Card /></Col>
|
||
</Row>
|
||
|
||
// 响应式布局
|
||
<Row gutter={[16, 16]}>
|
||
<Col
|
||
small={24}
|
||
middle={12}
|
||
large={6}
|
||
>
|
||
响应式列
|
||
</Col>
|
||
</Row>
|
||
|
||
// 间距和对齐
|
||
<Row
|
||
gutter={[16, 16]}
|
||
justify="space-between"
|
||
align="center"
|
||
>
|
||
<Col span={8} offset={2}></Col>
|
||
<Col span={12}></Col>
|
||
</Row>
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-grid-gutter: var(--nv-spacing-middle);
|
||
--nv-grid-columns: 24;
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 Space 间距组件
|
||
|
||
#### Props 定义（AI-First）
|
||
|
||
```tsx
|
||
export interface SpaceProps {
|
||
/** 间距方向 */
|
||
direction?: 'horizontal' | 'vertical'
|
||
/** 间距大小 */
|
||
size?: 'small' | 'middle' | 'large'
|
||
/** 对齐方式 */
|
||
align?: 'start' | 'end' | 'center' | 'baseline'
|
||
/** 是否换行（仅水平方向有效） */
|
||
wrap?: boolean
|
||
/** 分隔符 */
|
||
split?: React.ReactNode
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 基础使用
|
||
<Space size="middle">
|
||
<Button>按钮</Button>
|
||
<Button>按钮</Button>
|
||
</Space>
|
||
|
||
// 垂直排列
|
||
<Space direction="vertical" size="small">
|
||
<Input />
|
||
<Input />
|
||
</Space>
|
||
|
||
// 带分隔符
|
||
<Space split={<Divider type="vertical" />}>
|
||
<Text>Link 1</Text>
|
||
<Text>Link 2</Text>
|
||
</Space>
|
||
|
||
// 自动换行
|
||
<Space wrap size="middle">
|
||
{tags.map(tag => <Tag key={tag}>{tag}</Tag>)}
|
||
</Space>
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-space-gap-small: var(--nv-spacing-small);
|
||
--nv-space-gap-middle: var(--nv-spacing-middle);
|
||
--nv-space-gap-large: var(--nv-spacing-large);
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 Stack 弹性盒布局
|
||
|
||
#### Props 定义（AI-First）
|
||
|
||
```tsx
|
||
export interface StackProps {
|
||
/** 排列方向 */
|
||
direction?: 'horizontal' | 'vertical'
|
||
/** 间距 */
|
||
gap?: 'small' | 'middle' | 'large' | number | string
|
||
/** 主轴对齐方式 */
|
||
justify?: 'start' | 'end' | 'center' | 'space-around' | 'space-between' | 'space-evenly'
|
||
/** 交叉轴对齐方式 */
|
||
align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
|
||
/** 是否换行 */
|
||
wrap?: boolean
|
||
/** 子元素 */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
|
||
// 便捷组件
|
||
export interface HStackProps extends Omit<StackProps, 'direction'> {}
|
||
export interface VStackProps extends Omit<StackProps, 'direction'> {}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 使用 Stack
|
||
<Stack direction="horizontal" gap="middle" justify="space-between">
|
||
<Logo />
|
||
<Nav />
|
||
</Stack>
|
||
|
||
// 使用 HStack
|
||
<HStack gap="middle" justify="space-between">
|
||
<Logo />
|
||
<Nav />
|
||
</HStack>
|
||
|
||
// 使用 VStack
|
||
<VStack gap="small" align="center">
|
||
<Avatar />
|
||
<Name />
|
||
<Desc />
|
||
</VStack>
|
||
```
|
||
|
||
---
|
||
|
||
### 4.5 Divider 分隔线
|
||
|
||
#### Props 定义（AI-First）
|
||
|
||
```tsx
|
||
export interface DividerProps {
|
||
/** 方向 */
|
||
type?: 'horizontal' | 'vertical'
|
||
/** 是否虚线 */
|
||
dashed?: boolean
|
||
/** 子元素（居中文字） */
|
||
children?: React.ReactNode
|
||
className?: string
|
||
style?: React.CSSProperties
|
||
}
|
||
```
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 水平分隔
|
||
<Divider />
|
||
|
||
// 带文字
|
||
<Divider>内容</Divider>
|
||
|
||
// 垂直分隔
|
||
<Space split={<Divider type="vertical" />}>
|
||
<Text>Link 1</Text>
|
||
<Text>Link 2</Text>
|
||
</Space>
|
||
|
||
// 虚线
|
||
<Divider dashed />
|
||
```
|
||
|
||
#### Design Token
|
||
|
||
```css
|
||
--nv-divider-color: var(--nv-color-border);
|
||
--nv-divider-padding: var(--nv-spacing-middle);
|
||
```
|
||
|
||
---
|
||
|
||
## 五、AI-First 设计规范
|
||
|
||
### 5.1 Props 命名规范
|
||
|
||
| 规则 | 说明 |
|
||
|-----|------|
|
||
| **布尔属性** | 动词/形容词 + 肯定形式：`disabled`, `collapsible`, `fixed`, `wrap`, `dashed` |
|
||
| **事件回调** | `on + 动词 + 名词`：`onCollapse`, `onBreakpoint` |
|
||
| **尺寸** | 统一使用 `small`, `middle`, `large` |
|
||
| **响应式断点** | 统一使用 `small`, `middle`, `large` |
|
||
|
||
### 5.2 样式绑定规范
|
||
|
||
使用 `data-*` 属性进行样式绑定：
|
||
|
||
```tsx
|
||
<div
|
||
data-direction="horizontal"
|
||
data-size="middle"
|
||
data-wrap="true"
|
||
/>
|
||
```
|
||
|
||
### 5.3 组件导入规范
|
||
|
||
每个组件独立导入，路径即名字：
|
||
|
||
```tsx
|
||
import { Layout } from '@Pika/ui/layout'
|
||
import { Header, Footer, Sider, Content } from '@Pika/ui/layout'
|
||
import { Row, Col } from '@Pika/ui/grid'
|
||
import { Space } from '@Pika/ui/space'
|
||
import { Stack, HStack, VStack } from '@Pika/ui/stack'
|
||
import { Divider } from '@Pika/ui/divider'
|
||
```
|
||
|
||
---
|
||
|
||
## 六、完整使用示例
|
||
|
||
### 6.1 经典后台布局
|
||
|
||
```tsx
|
||
import { Layout, Row, Col, Space, HStack, VStack, Divider } from '@Pika/ui'
|
||
|
||
const App = () => {
|
||
const [collapsed, setCollapsed] = useState(false)
|
||
|
||
return (
|
||
<Layout>
|
||
<Layout.Sider
|
||
width={200}
|
||
collapsedWidth={80}
|
||
collapsible
|
||
collapsed={collapsed}
|
||
onCollapse={setCollapsed}
|
||
breakpoint="middle"
|
||
>
|
||
<Menu />
|
||
</Layout.Sider>
|
||
|
||
<Layout>
|
||
<Layout.Header fixed>
|
||
<HStack justify="space-between">
|
||
<Logo />
|
||
<UserMenu />
|
||
</HStack>
|
||
</Layout.Header>
|
||
|
||
<Layout.Content padding={24}>
|
||
<VStack gap="middle">
|
||
<PageTitle />
|
||
|
||
<Row gutter={[16, 16]}>
|
||
<Col
|
||
small={24}
|
||
middle={12}
|
||
large={6}
|
||
>
|
||
<Card />
|
||
</Col>
|
||
<Col
|
||
small={24}
|
||
middle={12}
|
||
large={6}
|
||
>
|
||
<Card />
|
||
</Col>
|
||
<Col
|
||
small={24}
|
||
middle={12}
|
||
large={6}
|
||
>
|
||
<Card />
|
||
</Col>
|
||
<Col
|
||
small={24}
|
||
middle={12}
|
||
large={6}
|
||
>
|
||
<Card />
|
||
</Col>
|
||
</Row>
|
||
|
||
<Divider />
|
||
|
||
<Space size="middle">
|
||
<Button>保存</Button>
|
||
<Button variant="outline">取消</Button>
|
||
</Space>
|
||
</VStack>
|
||
</Layout.Content>
|
||
|
||
<Layout.Footer>
|
||
© 2024 Pika UI
|
||
</Layout.Footer>
|
||
</Layout>
|
||
</Layout>
|
||
)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、文件结构
|
||
|
||
```
|
||
src/components/
|
||
├── layout/
|
||
│ ├── index.ts
|
||
│ ├── Layout.tsx
|
||
│ ├── Header.tsx
|
||
│ ├── Footer.tsx
|
||
│ ├── Sider.tsx
|
||
│ ├── Content.tsx
|
||
│ ├── Layout.module.css
|
||
│ └── Layout.test.tsx
|
||
├── grid/
|
||
│ ├── index.ts
|
||
│ ├── Row.tsx
|
||
│ ├── Col.tsx
|
||
│ ├── Grid.module.css
|
||
│ └── Grid.test.tsx
|
||
├── space/
|
||
│ ├── index.ts
|
||
│ ├── Space.tsx
|
||
│ ├── Space.module.css
|
||
│ └── Space.test.tsx
|
||
├── stack/
|
||
│ ├── index.ts
|
||
│ ├── Stack.tsx
|
||
│ ├── HStack.tsx
|
||
│ ├── VStack.tsx
|
||
│ ├── Stack.module.css
|
||
│ └── Stack.test.tsx
|
||
└── divider/
|
||
├── index.ts
|
||
├── Divider.tsx
|
||
├── Divider.module.css
|
||
└── Divider.test.tsx
|
||
```
|
||
|
||
---
|
||
|
||
## 八、优先级规划
|
||
|
||
### Phase 1: 核心布局 (P0)
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|-----|------|---------|
|
||
| Layout | 布局容器 | 1h |
|
||
| Header | 顶部导航栏 | 0.5h |
|
||
| Footer | 底部区域 | 0.5h |
|
||
| Content | 内容区域 | 0.5h |
|
||
| Sider | 侧边栏 | 2h |
|
||
|
||
### Phase 2: 栅格系统 (P1)
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|-----|------|---------|
|
||
| Row | 行容器 | 1h |
|
||
| Col | 列组件 | 1.5h |
|
||
|
||
### Phase 3: 间距和弹性盒 (P2)
|
||
|
||
| 组件 | 说明 | 预估工时 |
|
||
|-----|------|---------|
|
||
| Space | 间距组件 | 1h |
|
||
| Stack | 弹性盒容器 | 1h |
|
||
| HStack | 水平排列 | 0.25h |
|
||
| VStack | 垂直排列 | 0.25h |
|
||
| Divider | 分隔线 | 0.5h |
|
||
|
||
---
|
||
|
||
## 九、与根设计规范的对照
|
||
|
||
| 根规范 | 实现方式 |
|
||
|------|---------|
|
||
| **三级别尺寸** | `small`, `middle`, `large` 统一应用于所有组件 |
|
||
| **AI-First** | 所有 Props 使用联合类型字面量，无魔法字符串 |
|
||
| **Apple HIG** | 圆角、间距、动效遵循 Apple 规范 |
|
||
| **data-* 样式绑定** | 使用 `data-*` 属性而非 className 拼接 |
|
||
| **自包含组件** | 每个组件独立导入，路径即名字 |
|
||
| **统一事件命名** | `on + 动词 + 名词` 规则 |
|
||
|
||
---
|
||
|
||
## 十、设计总结
|
||
|
||
### Pika 布局组件的特点
|
||
|
||
1. **简洁统一** - 三级别尺寸体系，无过度设计
|
||
2. **AI 友好** - Props 自解释，类型安全，确定导入路径
|
||
3. **Apple HIG 优先** - 遵循 Apple 人机交互指南
|
||
4. **语义化** - Space, HStack, VStack 提供清晰的布局语义
|
||
5. **可扩展** - 支持响应式、折叠等高级功能
|
||
|
||
### AI 提示工程
|
||
|
||
```
|
||
1. 导入路径 = @Pika/ui/组件名 (layout/grid/space/stack/divider)
|
||
2. 尺寸 prop 始终叫 size，值从 small/middle/large 选
|
||
3. 响应式断点统一：small/middle/large
|
||
4. 布尔 prop 用动词开头 (collapsible, fixed, wrap, dashed)
|
||
5. 回调命名 = on + 动词 + 名词 (onCollapse, onBreakpoint)
|
||
6. 所有 prop 类型用联合类型字面量定义
|
||
7. 使用 Space 代替手动计算间距
|
||
8. 使用 HStack/VStack 进行弹性盒布局
|
||
```
|
||
|
||
> **Pika 布局组件：简洁、统一、AI-First**
|