416 lines
16 KiB
Markdown
416 lines
16 KiB
Markdown
# 门户全终端自适应技术实现方案
|
||
|
||
> 项目：`txw-mhzc-web`（Vue 2.6 + vue-cli 4 + TDesign Vue + Less）
|
||
> 目标：移动端重新排版 + 平板/桌面/超宽屏统一自适应，兼顾视觉一致性与可用性
|
||
> 参考站点：[上海市企业走出去综合服务平台](https://segg.sh.gov.cn/)（固定版心 + 断点响应，非整页 scale）
|
||
> 版本：v1.0 | 2026-05-26
|
||
|
||
---
|
||
|
||
## 一、方案总览与原则
|
||
|
||
### 1.1 技术路线（推荐）
|
||
|
||
采用 **「CSS 设计令牌 + 断点媒体查询 + 流式布局」** 为主、**「路由级 scale 画布」** 为辅的 **混合方案**：
|
||
|
||
| 场景 | 策略 | 说明 |
|
||
|------|------|------|
|
||
| 门户主站（home2、fwsc、gxnlpt、qych 等） | 响应式重排 | 与 [segg.sh.gov.cn](https://segg.sh.gov.cn/) 同类政务门户一致 |
|
||
| 固定画布子系统（iframe 大屏、部分 mhNewMain） | 可选 `scale` | 仅 `meta.fixedCanvas === true` 的路由启用 |
|
||
| 禁止 | 全站整页 `transform: scale` | 手机端字糊、触控区缩小、弹层错位 |
|
||
|
||
**视觉一致性** 指：品牌色、版心对齐关系、模块层级、间距节奏在各断点可预测变化，而非「桌面缩小版像素级一致」。
|
||
|
||
### 1.2 与现有代码的关系
|
||
|
||
仓库内已具备基础能力，实施时 **优先激活与统一**，避免重复引入重型框架：
|
||
|
||
| 资产 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| 断点常量 | `src/pages/index/styles/breakpoints.less` | 已定义 |
|
||
| 版心 / 栅格变量 | `src/pages/index/styles/page-layout.less` | 已定义 |
|
||
| 移动端全局样式 | `src/pages/index/styles/mobile-adaptation.less` | **需在 `main.js` 引入** |
|
||
| 验证清单 | `docs/test-reports/mobile-adaptation-checklist.md` | 已存在 |
|
||
| 大屏 scale 试验 | `app.vue` / `mhNewMain.vue` | 与门户主流程隔离 |
|
||
|
||
---
|
||
|
||
## 二、开源方案调研与对比（第一部分交付）
|
||
|
||
### 2.1 筛选标准
|
||
|
||
- 持续维护（近 12 个月有 release 或活跃 commit）
|
||
- 社区文档完善、Issue 可检索
|
||
- 兼容 iOS 12+、Android 8+、Chrome / Safari / Edge 近两代
|
||
- 轻量化：不强制替换 Vue 技术栈
|
||
- 集成成本低：与 Vue CLI 4、Less、TDesign 共存
|
||
|
||
### 2.2 方案分类说明
|
||
|
||
自适应实现分四类，**门户类项目通常只需 A + 少量 D**：
|
||
|
||
- **A. CSS 响应式体系**（断点、Grid/Flex、CSS 变量）— 主推
|
||
- **B. 构建期单位转换**（px→vw/rem）— 活动页/H5 子模块可选
|
||
- **C. 运行时整页 scale**（autofit、v-scale-screen）— 仅大屏/数据可视化
|
||
- **D. JS 能力增强**（断点检测、懒加载、resize 节流）— 辅助
|
||
|
||
以下 **不推荐** 作为门户主方案全量引入：Bootstrap 全量、Element UI 第二套组件库、整站 rem flexible（amfe-flexible）— 与现有 TDesign + Less 变量体系冲突且收益低。
|
||
|
||
### 2.3 对比清单
|
||
|
||
| 方案 | 类型 | 维护 / 生态 | 核心特性 | 适用场景 | 集成流程（概要） | 优点 | 缺点 |
|
||
|------|------|-------------|----------|----------|------------------|------|------|
|
||
| **原生 CSS + 项目令牌**（`page-layout` / `breakpoints`） | A | 标准、零依赖 | 变量、@media、Grid、clamp | **门户全站（首选）** | 已有；补 `main.js` 引入 `mobile-adaptation.less` | 可控、无运行时开销、与 Figma 1440 对齐 | 需逐页改样式 |
|
||
| **TDesign Vue Row/Col + 断点** | A | 腾讯维护 | 24 栅格、`xs/sm/md/lg` | 表单、列表、后台区块 | 已依赖，按文档包一层 | 与组件库一致 | 需熟悉 TDesign 断点 API |
|
||
| **Tailwind CSS**（项目已部分引入） | A | 活跃 | 工具类、响应式前缀 `md:` | 局部快速排版 | `vue.config` 配 PostCSS；避免与 Less 变量双主源 | 开发快 | 与 Less 混用易混乱，需约束使用范围 |
|
||
| **postcss-px-to-viewport-modern** | B | 活跃 fork | 设计稿 px 自动转 vw | 375 宽 H5 活动页 | `vue.config.js` → `css.loaderOptions.postcss` | 一稿多宽省事 | 不适合 1200 版心门户；与变量体系冲突 |
|
||
| **postcss-pxtorem** + lib-flexible | B | 经典但大屏少用 | rem 等比 | 老 H5 | flexible 脚本 + postcss | 移动端成熟 | Vue2 门户性价比低 |
|
||
| **autofit.js** | C | 活跃 | 整页 scale、ignore 节点 | 1920 固定画布大屏 | `mounted` → `autofit.init({ dw, dh, el })` | 接入极简 | 门户手机不可用 |
|
||
| **v-scale-screen@1.x** | C | 活跃 | Vue 2.6 组件包裹 scale | 可视化大屏页 | `Vue.use` + 包一层 template | 与 Vue 集成好 | 仅适合大屏路由 |
|
||
| **@fit-screen/vue** | C | 中等 | Vue2/3 scale 封装 | 同上 | 需 `@vue/composition-api` | 类型友好 | Vue 2.6 多一层依赖 |
|
||
| **@vueuse/core` `useBreakpoints`** | D | 极活跃 | `matchMedia` 响应式 | 需 JS 切换布局时 | Vue 2.7+ 原生；2.6 用 composition-api | API 优雅 | Vue 2.6 需额外插件 |
|
||
| **vue-mq / vue-screen** | D | 一般 | 断点 inject | 少量组件切换 | 注册插件 + `$mq` | 简单 | 维护不如 VueUse |
|
||
| **Container Queries**（原生 CSS） | A | 浏览器已普及 | 按父容器宽度适配卡片 | 卡片、侧栏模块 | `@container` + `container-type` | 比纯 vw 稳 | 需 postcss 插件做旧版兜底（可选） |
|
||
|
||
### 2.4 本项目推荐组合（集成成本最低）
|
||
|
||
```
|
||
主路径：page-layout.less + breakpoints.less + mobile-adaptation.less + 各页 @media
|
||
组件层：TDesign Grid / Drawer（移动菜单）
|
||
增强层：v-lazy（已有清单）+ resize 节流 + ECharts resize
|
||
隔离路径：meta.fixedCanvas 路由 → autofit 或 v-scale-screen（可选）
|
||
```
|
||
|
||
**不引入** 新的 UI 框架；**不** 全站 postcss-px-to-viewport；**不** 全站 scale。
|
||
|
||
---
|
||
|
||
## 三、断点设计规范
|
||
|
||
### 3.1 断点表（与 Figma / 现有 Less 对齐）
|
||
|
||
| 令牌 | 范围 | 设备 | 版心 / 列数策略 |
|
||
|------|------|------|-----------------|
|
||
| `xs` | 0 – 359px | 小屏手机 | 100% 宽，gutter 12px，栅格 1 列 |
|
||
| `sm` | 360 – 480px | 常规手机 | 100% 宽，gutter 16px，栅格 1 列 |
|
||
| `md` | 481 – 767px | 大屏手机 / 小平板竖屏 | 100% 宽，gutter 16–36px，栅格 1–2 列 |
|
||
| `lg` | 768 – 1023px | 平板 | max-width 100%，部分 2 列 |
|
||
| `xl` | 1024 – 1279px | 小桌面 | 版心可 100% 或保留 padding 40px |
|
||
| `2xl` | 1280 – 1439px | 标准桌面（Figma 1440 画布） | `--page-content-max-width: 1200px` |
|
||
| `3xl` | 1440 – 1919px | 宽桌面 | 版心 1200 居中，两侧留白随屏宽增加 |
|
||
| `4xl` | ≥ 1920px | 超宽屏 | 版心仍 1200；**禁止** 无限制拉伸内容区 |
|
||
|
||
Less 常量（已有，建议扩展）：
|
||
|
||
```less
|
||
// breakpoints.less
|
||
@mq-mobile-xs-max: 360px;
|
||
@mq-mobile-sm-max: 480px;
|
||
@mq-mobile-max: 767px;
|
||
@mq-tablet-max: 1023px;
|
||
@mq-desktop-sm-max: 1279px;
|
||
@mq-desktop-max: 1439px;
|
||
@mq-ultrawide-min: 1920px;
|
||
```
|
||
|
||
### 3.2 媒体查询书写约定
|
||
|
||
1. **移动优先（推荐新代码）**：默认手机样式 → `min-width` 逐级增强。
|
||
2. **桌面优先（兼容旧代码）**：保持现有 `max-width` 块，逐步迁移。
|
||
3. **禁止** 同一属性在多个断点反复覆盖且无变量来源。
|
||
4. 断点内只改 **CSS 变量** 或 **布局模式**（列数、flex-direction），避免魔法数字散落。
|
||
|
||
### 3.3 设计令牌扩展（`:root`）
|
||
|
||
在 `page-layout.less` 按断点扩展（示例）：
|
||
|
||
```less
|
||
// 平板
|
||
@media (min-width: 768px) and (max-width: 1023px) {
|
||
:root {
|
||
--portal-services-fwsc-cols: 2;
|
||
--page-section-padding-y: 48px;
|
||
}
|
||
}
|
||
|
||
// 超宽屏：版心不变，仅增大「出血背景」感知
|
||
@media (min-width: 1920px) {
|
||
:root {
|
||
--page-content-max-width: 1200px; /* 保持 */
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、流式布局适配逻辑
|
||
|
||
### 4.1 版心模型（与 segg 类门户一致）
|
||
|
||
```
|
||
┌──────────────────────────────────────────── viewport ────┐
|
||
│ margin-auto │
|
||
│ ┌──────────────── page-content-max 1200 ─────────────┐ │
|
||
│ │ gutter │ content aligned to nav logo │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 容器：`.page-content-wrap` / `.page-nav-inner`（已有）
|
||
- 宽度：`width: 100%` + `max-width: var(--page-content-max-width)`
|
||
- 小屏：`--page-content-max-width: 100%`（`mobile-adaptation.less` 已定义）
|
||
|
||
### 4.2 栅格与模块列数
|
||
|
||
| 模块 | ≥1280 | 768–1279 | 481–767 | ≤480 |
|
||
|------|-------|----------|---------|------|
|
||
| 服务中心四宫格 | 4 列 | 2 列 | 2 列 | 1 列 |
|
||
| 共性能力卡片 | 3–4 列 | 2 列 | 2 列 | 1 列 |
|
||
| 页脚链接组 | 横排 | 横排/折行 | 纵排 | 纵排 |
|
||
| 首页 Hero 搜索 | 横排 | 横排 | 纵排 | 纵排（home2 已部分实现） |
|
||
|
||
实现方式：
|
||
|
||
```less
|
||
.portal-services-grid {
|
||
display: grid;
|
||
grid-template-columns: repeat(var(--portal-services-fwsc-cols, 4), minmax(0, 1fr));
|
||
gap: var(--portal-services-grid-gap, 24px);
|
||
}
|
||
```
|
||
|
||
### 4.3 超宽屏策略
|
||
|
||
- **内容区不随 4K 变宽**：保持 1200px 版心，避免行长过长。
|
||
- **全宽背景** 使用 `.home-section-bleed()`（已有 mixin）铺满视口。
|
||
- **装饰性大图** 使用 `max-width: 100%` + 居中，而非拉伸版心。
|
||
|
||
### 4.4 大屏固定画布（可选子路由）
|
||
|
||
仅 `route.meta.layout === 'fixed-canvas'`：
|
||
|
||
```js
|
||
scale = Math.min(innerWidth / DESIGN_W, innerHeight / DESIGN_H)
|
||
```
|
||
|
||
与门户响应式 **路由级隔离**，避免 `app.vue` 全局 scale 影响主站。
|
||
|
||
---
|
||
|
||
## 五、弹性图片与媒体资源
|
||
|
||
### 5.1 图片
|
||
|
||
| 策略 | 实现 |
|
||
|------|------|
|
||
| 响应式尺寸 | `max-width: 100%; height: auto;`（mobile-adaptation 已有） |
|
||
| 分辨率适配 | `<img srcset="..." sizes="(max-width: 768px) 100vw, 1200px">` 对 Banner/大图 |
|
||
| 懒加载 | `loading="lazy"` 或 `v-lazy`（见 checklist） |
|
||
| 格式 | 优先 WebP（构建或 CDN），PNG 用于透明图标 |
|
||
| 艺术方向 | 窄屏可选裁切图（`picture` + `source media`） |
|
||
|
||
### 5.2 视频 / 背景
|
||
|
||
- 首页 Banner 视频：窄屏降低 `preload`，必要时 `poster` 静帧。
|
||
- CSS 背景：`background-size: cover; background-position: center;`
|
||
- 避免固定 `1920px` 背景宽导致小屏横向滚动（参考政务站仅背景层用 1920 的情况）。
|
||
|
||
### 5.3 图标与 SVG
|
||
|
||
- 图标优先 SVG / iconfont，随字号 `em` 缩放。
|
||
- Font Awesome 已引入，控制只打包使用子集（长期优化）。
|
||
|
||
---
|
||
|
||
## 六、响应式交互适配策略
|
||
|
||
### 6.1 导航
|
||
|
||
| 断点 | 行为 |
|
||
|------|------|
|
||
| ≥768px | 横排菜单（`new-nav` / `nav/index2`） |
|
||
| <768px | 隐藏横菜单，汉堡 + Drawer/侧滑（`mobile-menu-item` 样式已有） |
|
||
|
||
### 6.2 触控与表单（WCAG 2.5 目标尺寸）
|
||
|
||
- 可点击区域 **≥ 48×48px**（`mobile-adaptation.less`）
|
||
- 输入框 `font-size: 16px` 防止 iOS 聚焦放大
|
||
- `touch-action: pan-y` 于主滚动容器，减少误触横向滑动
|
||
|
||
### 6.3 弹层与固定元素
|
||
|
||
- TDesign `Dialog` / `Drawer`：窄屏优先 `placement` 全屏或底部抽屉。
|
||
- **避免** 在带 `transform` 的 scale 祖先内挂 `position: fixed` 弹层。
|
||
- 返回顶部、悬浮客服：小屏抬高 `bottom`，避开安全区：
|
||
|
||
```css
|
||
padding-bottom: env(safe-area-inset-bottom, 0);
|
||
```
|
||
|
||
### 6.4 JS 辅助（按需）
|
||
|
||
```js
|
||
// utils/breakpoint.js
|
||
export const BP = { mobile: 768, tablet: 1024, desktop: 1280 }
|
||
|
||
export function getDeviceClass() {
|
||
const w = window.innerWidth
|
||
if (w < BP.mobile) return 'is-mobile'
|
||
if (w < BP.tablet) return 'is-tablet'
|
||
if (w < BP.desktop) return 'is-desktop-sm'
|
||
return 'is-desktop'
|
||
}
|
||
```
|
||
|
||
用于：ECharts `resize`、是否加载重动画、Tab 横滑 vs 下拉。
|
||
|
||
### 6.5 图表（ECharts）
|
||
|
||
```js
|
||
window.addEventListener('resize', throttle(() => chart.resize(), 200))
|
||
```
|
||
|
||
移动端 legend 改底部、减小 `grid` 边距，在 `@media` 或 `getDeviceClass()` 分支配置 option。
|
||
|
||
---
|
||
|
||
## 七、性能优化措施
|
||
|
||
| 项 | 措施 |
|
||
|----|------|
|
||
| CSS | 断点样式集中在 `mobile-adaptation.less`，避免每组件重复 `@media` |
|
||
| 图片 | 懒加载 + 合适尺寸，首屏 LCP 图不用 lazy |
|
||
| JS | `resize` / `scroll` 监听必须 throttle（200–300ms） |
|
||
| 字体 | 子集化或系统字体栈回退，减少 FOUT |
|
||
| 长列表 | 虚拟滚动（TDesign Table 大数据）或分页 |
|
||
| 动画 | `prefers-reduced-motion: reduce` 关闭非必要动效 |
|
||
| 构建 | 路由懒加载（已有 vue-router）；按页拆分 CSS |
|
||
|
||
---
|
||
|
||
## 八、落地实施路线图
|
||
|
||
### 阶段 0：基线（1 天）
|
||
|
||
- [ ] `main.js` 增加：`import './styles/mobile-adaptation.less'`
|
||
- [ ] 确认 `public/index.html` viewport：`width=device-width, initial-scale=1`
|
||
- [ ] 移除或路由隔离 `app.vue` 未使用的全局 scale 逻辑
|
||
- [ ] 统一断点：新代码引用 `breakpoints.less` 变量
|
||
|
||
### 阶段 1：全局与导航（2–3 天）
|
||
|
||
- [ ] 导航：移动 Drawer + 桌面横栏双态完整联调
|
||
- [ ] `page-layout.less`：补齐 tablet / ultrawide 变量
|
||
- [ ] 页脚、面包屑窄屏折行
|
||
|
||
### 阶段 2：核心页面重排（5–8 天）
|
||
|
||
按 checklist 顺序：
|
||
|
||
1. `home2/index.vue` — 合并零散 `@media` 到变量驱动
|
||
2. `fwsc` — 四宫格 + 列表筛选堆叠
|
||
3. `gxnlpt` — 侧栏置顶 + 卡片单列
|
||
4. `qych` — 法案区块与卡片
|
||
|
||
每页完成即在 `mobile-adaptation-checklist.md` 打勾。
|
||
|
||
### 阶段 3：大屏与回归（2 天）
|
||
|
||
- [ ] ≥1280 / 1920 / 2560 版心居中与背景出血
|
||
- [ ] 固定画布子路由（若有）单独测 scale
|
||
- [ ] 桌面回归：与改版前 1280 对齐
|
||
|
||
### 阶段 4：验收
|
||
|
||
- 真机：iOS Safari、Android Chrome，宽度 320 / 390 / 414
|
||
- 桌面：1280、1440、1920、2560
|
||
- 工具：Chrome DevTools + Lighthouse 移动端评分
|
||
|
||
---
|
||
|
||
## 九、目录与文件规范（建议）
|
||
|
||
```
|
||
src/pages/index/styles/
|
||
breakpoints.less # 断点常量（唯一来源）
|
||
page-layout.less # 版心、间距令牌
|
||
mobile-adaptation.less # 全局移动端 @media
|
||
mixins/
|
||
responsive.less # .respond-to(@bp) 等 mixin（可选新建）
|
||
|
||
src/pages/index/utils/
|
||
breakpoint.js # 设备类名 / matchMedia（可选）
|
||
|
||
docs/
|
||
responsive-adaptation-implementation-plan.md # 本文档
|
||
test-reports/mobile-adaptation-checklist.md # 验收清单
|
||
```
|
||
|
||
### Less mixin 示例（可选）
|
||
|
||
```less
|
||
.respond-to(@max) when (default()) {
|
||
@media screen and (max-width: @max) {
|
||
@content();
|
||
}
|
||
}
|
||
|
||
// 使用
|
||
.respond-to(@mq-mobile-max) {
|
||
.foo { flex-direction: column; }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十、风险与决策记录
|
||
|
||
| 风险 | 缓解 |
|
||
|------|------|
|
||
| 双轨样式（桌面 scale + 移动重排）冲突 | 路由 meta 明确 `layout: portal \| fixed-canvas` |
|
||
| TDesign 组件窄屏溢出 | 表格外包 `.table-scroll-x { overflow-x: auto }` |
|
||
| 旧页大量魔法 `@media` | 逐页迁移，不一次性重写 |
|
||
| 超宽屏内容过宽 | 严格 max-width 1200，不改用 scale 撑满 |
|
||
|
||
---
|
||
|
||
## 十一、附录：快速集成示例
|
||
|
||
### A. 启用全局移动端样式
|
||
|
||
```js
|
||
// main.js
|
||
import './styles/page-layout.less';
|
||
import './styles/mobile-adaptation.less';
|
||
```
|
||
|
||
### B. 页面内仅补结构差异
|
||
|
||
```vue
|
||
<template>
|
||
<div class="page-content-wrap portal-page">
|
||
<section class="portal-services-grid">...</section>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
列数由 `--portal-services-fwsc-cols` 控制，不在组件内写死 `width: 280px`。
|
||
|
||
### C. 可选大屏路由（autofit）
|
||
|
||
```js
|
||
// 仅 fixed-canvas 布局的 mounted
|
||
import autofit from 'autofit.js'
|
||
autofit.init({ dw: 1920, dh: 1080, el: '#fixed-canvas-root', resize: true })
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、结论
|
||
|
||
- **移动端重新排版**：依赖 **CSS 变量 + 断点 + Grid/Flex**，激活并扩展现有 `mobile-adaptation.less`，逐页改造核心视图。
|
||
- **大屏/超宽屏**：**版心锁定 + 背景出血**，与 [segg.sh.gov.cn](https://segg.sh.gov.cn/) 同类，**不用** 整站 scale。
|
||
- **开源框架**：不新增重型 UI 框架；可选 **autofit / v-scale-screen** 仅服务固定画布子系统；主站以 **原生响应式 + TDesign** 为准。
|
||
|
||
本文档为实施依据，具体排期可与 `mobile-adaptation-checklist.md` 联合跟踪。
|