# PC / 移动端响应式规范

> 适用项目：`schedule-invest-plan`  
> 版本：v1.0  
> 策略：**Mobile First（移动优先）** + 单代码库适配 PC 与移动端浏览器

---

## 1. 目标与原则

| 原则 | 说明 |
|------|------|
| 一套代码 | 不维护独立 H5 仓库，通过断点与布局组件适配 |
| 移动优先 | 默认样式面向小屏；使用 `min-width` 媒体查询逐级增强 |
| 流式布局 | 宽度优先 `%` / `fr` / `max-width`，避免写死大屏像素宽度 |
| 触控友好 | 可点击区域最小 **44×44px**（含按钮、图标按钮） |
| 与 Element Plus 一致 | 栅格、表单 `label-position`、对话框宽度遵循 EP 响应式用法 |
| 主题无关 | 深浅色只改 CSS 变量，不改变断点与间距阶梯 |

---

## 2. 视口与设备范围

- **最小支持宽度**：320px（`body` 已设置 `min-width: 320px`）
- **主要适配对象**：
  - 移动端：竖屏手机（320–767px）
  - 平板：768–1023px
  - PC：≥1024px
- **HTML**：保留 `viewport` meta，禁止用户缩放锁死（不设 `user-scalable=no`），以保证无障碍与系统字体缩放。

---

## 3. 断点定义（统一来源）

断点数值以 **`src/constants/breakpoints.ts`** 为 JS/TS 唯一真相；SCSS 使用 **`src/styles/breakpoints.scss`**（数值须与 TS 保持一致）。

| 令牌 | 宽度 | 典型场景 |
|------|------|----------|
| `sm` | ≥576px | 大屏手机横屏、小平板 |
| `md` | ≥768px | 平板竖屏 |
| `lg` | ≥1024px | 笔记本 / PC 主内容区 |
| `xl` | ≥1280px | 宽屏，内容区达到 `max-width` |

### 3.1 语义化设备类型（业务判断用）

在脚本中通过 **`useBreakpoint()`** 获取（勿在各页面重复 `resize` 监听）：

| 字段 | 条件 | 用途示例 |
|------|------|----------|
| `isMobile` | 宽度 < 768px | 表单单列、`label-position="top"` |
| `isTablet` | 768px ≤ 宽度 < 1024px | 双列栅格 |
| `isDesktop` | 宽度 ≥ 1024px | 侧栏 + 主内容 |
| `isWide` | 宽度 ≥ 1280px | 宽表、多列看板 |

---

## 4. 布局规范

### 4.1 页面壳层

```
#app
 └── .app-shell          （min-height: 100vh）
      └── .app-container （max-width + 水平居中 + 内边距）
           ├── AppHeader
           └── AppPage / 页面内容
```

- **内容最大宽度**：`1280px`（`--layout-max-width`）
- **页面内边距**：使用 CSS 变量，禁止在业务页写死 `padding: 32px`：

| 变量 | 移动端（<768） | 平板（≥768） | PC（≥1024） |
|------|------------------|--------------|--------------|
| `--page-padding-x` | 16px | 24px | 32px |
| `--page-padding-y` | 16px | 24px | 32px |

### 4.2 页面组件

- 路由级视图根节点使用 **`AppPage`**（`src/components/layout/AppPage.vue`），类名 `app-page`。
- 需要全宽区块（如顶栏下横幅）时，在 `AppPage` 内再包一层 `.app-page__section`，通过负 margin 拉满（见组件注释，慎用）。

### 4.3 Element Plus 栅格

```vue
<el-row :gutter="gutter">
  <el-col :xs="24" :sm="12" :lg="8">...</el-col>
</el-row>
```

- **gutter**：移动端 `12`，PC `20`（可用 `useBreakpoint().isMobile` 计算）。
- 默认单列：`xs="24"`，再按 `sm` / `md` / `lg` 递增列数。

### 4.4 表单

| 场景 | 规范 |
|------|------|
| 移动端 | `label-position="top"`，`size="default"` 或 `large` |
| PC | `label-position="right"`，`label-width` 统一（如 `100px`） |
| 按钮区 | 移动端主按钮 `width: 100%` 或 `el-button` 块级排列 |

### 4.5 表格

- 移动端：优先 **卡片列表** 或 **横向滚动**（`el-table` 外包 `.app-table-scroll`），避免压缩到不可读。
- PC：常规表格；列过多时使用 `fixed` 与 `min-width`。

---

## 5. 样式编写规范（Sass）

### 5.1 媒体查询

统一使用 **`src/styles/mixins/_respond.scss`** 中的 mixin（已在 Vite 中全局注入）：

```scss
.app-card {
  padding: 12px;

  @include respond-up(md) {
    padding: 16px;
  }

  @include respond-up(lg) {
    padding: 20px;
  }
}

.app-toolbar {
  @include respond-down(md) {
    flex-direction: column;
    align-items: stretch;
  }
}
```

| Mixin | 含义 |
|-------|------|
| `respond-up($name)` | `min-width`，从该断点起生效 |
| `respond-down($name)` | `max-width`，小于该断点生效 |
| `respond-between($from, $to)` | 闭开区间，用于仅平板样式 |

**禁止**在业务组件中手写零散 `@media (max-width: 750px)`，除非规范文档修订并同步 `breakpoints.scss`。

### 5.2 尺寸与字体

- 间距使用 **4px 基准**：4、8、12、16、24、32、48。
- 正文字号：移动 **14px**，PC **14–16px**（`--font-size-base`）。
- 标题：移动比 PC 小一级（如 `h1` 移动 20px，PC 24px）。

### 5.3 颜色与主题

- 业务样式只引用 **`var(--color-*)`**，不写死 `#fff` / `#000`（图表等特殊场景除外）。

---

## 6. 脚本与组合式 API

```ts
import { useBreakpoint } from '@/composables/useBreakpoint'

const { isMobile, isDesktop, width } = useBreakpoint()
```

- 仅当 **布局结构** 或 **组件属性** 需要切换时使用（如 `label-position`）。
- 不要用 `width` 做业务权限或接口参数。

---

## 7. 导航与顶栏

- **PC**：标题与导航同一行，控件横向排列。
- **移动**：标题独占一行；导航与语言/主题控件换行，选择器 **等分或 100% 宽**。
- 路由跳转须保留 URL 上的 `lang`、`theme`（`useRouteWithPreferences`）。

---

## 8. 测试与验收

| 类型 | 要求 |
|------|------|
| 浏览器 | Chrome 最新 + Safari iOS / Android Chrome 各一 |
| 断点抽测 | 375、414、768、1024、1280 宽度无横向滚动条（除表格滚动容器） |
| 横竖屏 | 图表与弹层在旋转后 `resize` 正常 |
| 无障碍 | 焦点可见；表单控件具备 `aria-label` 或可见 label |

---

## 9. 禁止事项

- 禁止为 PC / H5 复制两套页面文件（除非产品明确要求独立路由）。
- 禁止 `position: fixed` 大面积遮挡而不留安全区（刘海屏注意 `env(safe-area-inset-*)` 后续扩展）。
- 禁止在 &lt;768px 使用 hover 作为唯一交互提示。
- 禁止未读规范即新增断点数值。

---

## 10. 相关文件索引

| 文件 | 职责 |
|------|------|
| `src/constants/breakpoints.ts` | 断点像素、设备语义 |
| `src/composables/useBreakpoint.ts` | 响应式设备状态 |
| `src/styles/breakpoints.scss` | Sass 断点 Map |
| `src/styles/mixins/_respond.scss` | 媒体查询 mixin |
| `src/styles/layout.scss` | 壳层与工具类 |
| `src/components/layout/AppPage.vue` | 页面根布局 |
| `docs/RESPONSIVE_SPEC.md` | 本文档 |

---

## 11. 变更流程

修改断点或间距阶梯时须：

1. 同步更新 `breakpoints.ts` 与 `breakpoints.scss`；
2. 更新本文档版本号与变更说明；
3. 在 `IMPACT_ANALYSIS.md` 中注明是否影响既有页面布局；
4. 回归测试 §9 所列宽度。