388 lines
10 KiB
Markdown
388 lines
10 KiB
Markdown
# 018-responsive.mdc (Deep Reference)
|
||
|
||
> 该文件为原始详细规范归档，供 Tier 3 按需读取。
|
||
|
||
---
|
||
|
||
|
||
# 📱 Responsive Design & Multi-Device Standards
|
||
|
||
## 断点体系（与 Tailwind 统一）
|
||
|
||
> **⚠️ 双前端区分**：本文件中的 Element Plus 移动端适配内容**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
|
||
> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
|
||
|
||
| 断点 | Tailwind 前缀 | 最小宽度 | 目标设备 |
|
||
|------|--------------|---------|---------|
|
||
| 默认 | (无前缀) | 0px | 手机竖屏 (< 640px) |
|
||
| sm | `sm:` | 640px | 手机横屏 / 小平板 |
|
||
| md | `md:` | 768px | 平板竖屏 (iPad) |
|
||
| lg | `lg:` | 1024px | 平板横屏 / 小屏笔记本 |
|
||
| xl | `xl:` | 1280px | 桌面 |
|
||
| 2xl | `2xl:` | 1536px | 大屏桌面 / 4K |
|
||
|
||
> **原则**：移动优先（Mobile-First）— 先写手机样式，用断点向上覆盖。
|
||
|
||
```html
|
||
<!-- ✅ 移动优先：默认手机，逐步增强 -->
|
||
<div class="p-4 md:p-6 xl:p-8 grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
|
||
<!-- 手机 1列 → 平板 2列 → 桌面 3列 -->
|
||
</div>
|
||
|
||
<!-- ❌ 桌面优先（禁用）：max-* 限制往下适配 -->
|
||
<div class="grid grid-cols-3 max-md:grid-cols-1">...</div>
|
||
```
|
||
|
||
---
|
||
|
||
## 布局组件响应式模式
|
||
|
||
### 侧边栏布局（后台管理系统标准模式）
|
||
|
||
```vue
|
||
<!-- src/layouts/AppLayout.vue -->
|
||
<template>
|
||
<div class="flex h-screen overflow-hidden bg-gray-50 dark:bg-gray-900">
|
||
<!-- 遮罩层：移动端打开侧边栏时显示 -->
|
||
<Transition name="fade">
|
||
<div
|
||
v-if="isMobile && sidebarOpen"
|
||
class="fixed inset-0 z-20 bg-black/50"
|
||
@click="sidebarOpen = false"
|
||
/>
|
||
</Transition>
|
||
|
||
<!-- 侧边栏：桌面固定，移动端抽屉式 -->
|
||
<aside
|
||
:class="[
|
||
'fixed lg:relative z-30 h-full transition-transform duration-300',
|
||
'w-64 bg-white dark:bg-gray-800 border-r border-gray-200 dark:border-gray-700',
|
||
isMobile && !sidebarOpen ? '-translate-x-full' : 'translate-x-0',
|
||
]"
|
||
>
|
||
<ArtSidebarMenu />
|
||
</aside>
|
||
|
||
<!-- 主内容区 -->
|
||
<div class="flex-1 flex flex-col min-w-0 overflow-hidden">
|
||
<!-- 顶部导航 -->
|
||
<header class="h-14 md:h-16 flex items-center px-4 md:px-6 border-b bg-white dark:bg-gray-800">
|
||
<!-- 移动端：汉堡菜单按钮 -->
|
||
<button
|
||
class="lg:hidden mr-3 p-2 rounded-lg text-gray-500 hover:bg-gray-100"
|
||
aria-label="打开菜单"
|
||
@click="sidebarOpen = !sidebarOpen"
|
||
>
|
||
<el-icon :size="20"><Menu /></el-icon>
|
||
</button>
|
||
<ArtHeader />
|
||
</header>
|
||
|
||
<!-- 页面内容 -->
|
||
<main class="flex-1 overflow-auto">
|
||
<div class="p-4 md:p-6 xl:p-8 max-w-screen-2xl mx-auto">
|
||
<router-view />
|
||
</div>
|
||
</main>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
const { isMobile } = useDevice()
|
||
const sidebarOpen = ref(false)
|
||
|
||
// 路由变化时关闭移动端侧边栏
|
||
const route = useRoute()
|
||
watch(() => route.path, () => {
|
||
if (isMobile.value) sidebarOpen.value = false
|
||
})
|
||
</script>
|
||
```
|
||
|
||
### `useDevice` Composable
|
||
|
||
```typescript
|
||
// src/composables/useDevice.ts
|
||
export function useDevice() {
|
||
const width = ref(window.innerWidth)
|
||
|
||
const handleResize = useDebounceFn(() => {
|
||
width.value = window.innerWidth
|
||
}, 100)
|
||
|
||
onMounted(() => window.addEventListener('resize', handleResize))
|
||
onUnmounted(() => window.removeEventListener('resize', handleResize))
|
||
|
||
return {
|
||
width: readonly(width),
|
||
isMobile: computed(() => width.value < 768),
|
||
isTablet: computed(() => width.value >= 768 && width.value < 1024),
|
||
isDesktop: computed(() => width.value >= 1024),
|
||
isTouch: computed(() => 'ontouchstart' in window),
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Element Plus 移动端适配（仅管理端）
|
||
|
||
### 组件尺寸策略
|
||
|
||
```vue
|
||
<script setup>
|
||
const { isMobile } = useDevice()
|
||
const elSize = computed(() => (isMobile.value ? 'small' : 'default'))
|
||
</script>
|
||
|
||
<template>
|
||
<!-- ✅ 根据设备自适应 size -->
|
||
<el-form :size="elSize">
|
||
<el-input :size="elSize" />
|
||
<el-button :size="elSize" type="primary">提交</el-button>
|
||
</el-form>
|
||
|
||
<!-- ✅ 表格移动端简化列 -->
|
||
<el-table :data="tableData">
|
||
<el-table-column prop="name" label="名称" min-width="120" />
|
||
<el-table-column v-if="!isMobile" prop="createdAt" label="创建时间" width="160" />
|
||
<el-table-column v-if="!isMobile" prop="status" label="状态" width="100" />
|
||
<!-- 移动端合并展示 -->
|
||
<el-table-column v-if="isMobile" label="详情" min-width="200">
|
||
<template #default="{ row }">
|
||
<div class="text-sm">{{ row.status }} · {{ row.createdAt }}</div>
|
||
</template>
|
||
</el-table-column>
|
||
</el-table>
|
||
</template>
|
||
```
|
||
|
||
### 对话框适配
|
||
|
||
```vue
|
||
<!-- ✅ 移动端全屏对话框 -->
|
||
<el-dialog
|
||
v-model="dialogVisible"
|
||
:fullscreen="isMobile"
|
||
:width="isMobile ? '100%' : '600px'"
|
||
:class="{ 'rounded-t-2xl': isMobile }"
|
||
>
|
||
```
|
||
|
||
### 分页适配
|
||
|
||
```vue
|
||
<!-- ✅ 移动端简化分页 -->
|
||
<el-pagination
|
||
v-model:current-page="currentPage"
|
||
v-model:page-size="pageSize"
|
||
:layout="isMobile ? 'prev, pager, next' : 'total, sizes, prev, pager, next, jumper'"
|
||
:pager-count="isMobile ? 3 : 7"
|
||
:page-sizes="isMobile ? [10, 20] : [10, 20, 50, 100]"
|
||
:total="total"
|
||
/>
|
||
```
|
||
|
||
### 表单布局
|
||
|
||
```vue
|
||
<!-- ✅ 移动端垂直布局，桌面水平布局 -->
|
||
<el-form
|
||
:label-position="isMobile ? 'top' : 'right'"
|
||
:label-width="isMobile ? 'auto' : '100px'"
|
||
>
|
||
```
|
||
|
||
---
|
||
|
||
## 触摸与手势优化
|
||
|
||
### 最小触摸目标尺寸
|
||
|
||
```scss
|
||
// src/assets/styles/touch.scss
|
||
// 根据 WCAG 2.5.5，触摸目标最小 44×44px
|
||
.touch-target {
|
||
min-width: 44px;
|
||
min-height: 44px;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
}
|
||
|
||
@media (hover: none) and (pointer: coarse) {
|
||
// 触屏设备：增大可点击区域
|
||
.el-button {
|
||
min-height: 44px;
|
||
padding-left: 16px;
|
||
padding-right: 16px;
|
||
}
|
||
|
||
.el-input__wrapper {
|
||
min-height: 44px;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 滑动手势（移动端列表操作）
|
||
|
||
```typescript
|
||
// src/composables/useSwipeAction.ts
|
||
export function useSwipeAction(onDelete: () => void, onEdit: () => void) {
|
||
const startX = ref(0)
|
||
const offsetX = ref(0)
|
||
const THRESHOLD = 80
|
||
|
||
function onTouchStart(e: TouchEvent) {
|
||
startX.value = e.touches[0].clientX
|
||
}
|
||
|
||
function onTouchMove(e: TouchEvent) {
|
||
const diff = e.touches[0].clientX - startX.value
|
||
offsetX.value = Math.max(-160, Math.min(0, diff)) // 最多滑动 160px
|
||
}
|
||
|
||
function onTouchEnd() {
|
||
if (offsetX.value < -THRESHOLD) {
|
||
// 滑过阈值：显示操作按钮
|
||
} else {
|
||
offsetX.value = 0 // 弹回
|
||
}
|
||
}
|
||
|
||
return { offsetX, onTouchStart, onTouchMove, onTouchEnd }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 图片与媒体响应式
|
||
|
||
```vue
|
||
<template>
|
||
<!-- ✅ 响应式图片：不同分辨率加载不同尺寸 -->
|
||
<picture>
|
||
<source media="(min-width: 1280px)" srcset="/img/banner-xl.webp" />
|
||
<source media="(min-width: 768px)" srcset="/img/banner-md.webp" />
|
||
<img src="/img/banner-sm.webp" alt="Banner" class="w-full h-auto object-cover" loading="lazy" />
|
||
</picture>
|
||
|
||
<!-- ✅ 使用 Intersection Observer 懒加载 -->
|
||
<img
|
||
v-lazy="imageUrl"
|
||
alt="产品图片"
|
||
class="w-full aspect-square object-cover rounded-lg"
|
||
:class="{ 'animate-pulse bg-gray-200': !isLoaded }"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 字体与文字排版
|
||
|
||
```scss
|
||
// 流式字体大小：随屏幕宽度线性变化
|
||
:root {
|
||
--font-base: clamp(14px, 1vw + 12px, 16px);
|
||
--font-heading: clamp(20px, 3vw + 10px, 36px);
|
||
}
|
||
|
||
body { font-size: var(--font-base); }
|
||
h1 { font-size: var(--font-heading); }
|
||
|
||
// 行高：移动端更宽松（小屏阅读舒适度）
|
||
p {
|
||
line-height: 1.6;
|
||
|
||
@media (max-width: 767px) {
|
||
line-height: 1.8;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 安全区域（刘海屏 / 全面屏）
|
||
|
||
```css
|
||
/* 底部安全区域（iOS 全面屏 Home Bar）*/
|
||
.bottom-nav {
|
||
padding-bottom: env(safe-area-inset-bottom, 16px);
|
||
}
|
||
|
||
/* 顶部安全区域（刘海屏）*/
|
||
.top-bar {
|
||
padding-top: env(safe-area-inset-top, 0px);
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// tailwind.config.ts — 添加安全区域工具类
|
||
theme: {
|
||
extend: {
|
||
padding: {
|
||
'safe-bottom': 'env(safe-area-inset-bottom, 16px)',
|
||
'safe-top': 'env(safe-area-inset-top, 0px)',
|
||
},
|
||
},
|
||
},
|
||
```
|
||
|
||
---
|
||
|
||
## 响应式测试矩阵
|
||
|
||
| 设备 | 分辨率 | 断点 | 关键功能检查 |
|
||
|------|--------|------|------------|
|
||
| iPhone SE (3代) | 375×667 | xs | 侧边栏抽屉、表单垂直布局 |
|
||
| iPhone 14 Pro | 393×852 | xs | 安全区域、全面屏底部导航 |
|
||
| iPhone 14 Pro Max | 430×932 | sm | 横屏布局、键盘遮挡处理 |
|
||
| iPad (10代) | 820×1180 | md | 平板双栏、对话框宽度 |
|
||
| iPad Pro 12.9" | 1024×1366 | lg | 分页组件、表格完整列 |
|
||
| MacBook Air 13" | 1280×800 | xl | 完整侧边栏、桌面表格 |
|
||
| 4K 显示器 | 1920×1080 | 2xl | 最大宽度限制、留白 |
|
||
|
||
### 测试脚本（Playwright）
|
||
|
||
```typescript
|
||
// tests/responsive.spec.ts
|
||
import { test, expect } from '@playwright/test'
|
||
|
||
const viewports = [
|
||
{ name: 'mobile', width: 375, height: 812 },
|
||
{ name: 'tablet', width: 768, height: 1024 },
|
||
{ name: 'desktop', width: 1280, height: 800 },
|
||
]
|
||
|
||
for (const vp of viewports) {
|
||
test(`dashboard layout on ${vp.name}`, async ({ page }) => {
|
||
await page.setViewportSize({ width: vp.width, height: vp.height })
|
||
await page.goto('/dashboard')
|
||
|
||
if (vp.name === 'mobile') {
|
||
// 移动端：侧边栏默认隐藏
|
||
await expect(page.locator('aside')).toHaveCSS('transform', 'matrix(1, 0, 0, 1, -256, 0)')
|
||
// 汉堡按钮可见
|
||
await expect(page.locator('[aria-label="打开菜单"]')).toBeVisible()
|
||
} else {
|
||
// 平板/桌面：侧边栏默认显示
|
||
await expect(page.locator('aside')).toBeVisible()
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 规则
|
||
|
||
- 所有新页面必须在 375px / 768px / 1280px 三个断点下验证
|
||
- 禁止使用 `px` 设置字体大小（用 `rem` 或 Tailwind 文本类）
|
||
- 触摸目标最小 44×44px
|
||
- 禁止使用 `:hover` 作为唯一交互反馈（移动端无 hover）
|
||
- 管理端：所有 `el-dialog` 必须处理移动端 `fullscreen` 属性（用户端使用 Headless UI Dialog）
|
||
- 图片必须设置 `loading="lazy"` 和 `aspect-ratio`（防止布局抖动 CLS）
|
||
- 横屏（landscape）模式下的布局需专门测试
|