MobileSpec

## 开发规范

### 1. 移动设备适配

#### 1.1 基础概念

##### 1.1.1 设备像素

从 iphone 4 发布会引入“视网膜屏”的概念之后，市面上移动设备显示屏的清晰度有了比较大的发展，各厂商不断推出了高分屏机型，单位面积的屏幕里被塞入了越来越多像素，正是因为这些高分屏出现的缘故，我们需要搞先清楚以下几个概念：

1. 物理像素 物理像素是设备上实际存在的真实物理单元。设备的分辨率值表示在横纵坐标上分别有多少个物理像素点，例如 iphone X 的分辨率为 1125px*2436px，那就表示它在水平方向每一行有 1125 个物理像素点，垂直方向每一列有 2436 个物理像素点。
2. 设备独立像素（Device Independent Pixels） 设备独立像素是一个长度单位，在页面缩放比例为 100% 时，等于前端开发者常用 css 像素单位，设备的 dips 由设备硬件和系统底层软件标定，它确定了开发者可使用的尺寸，例如 iphone X 的分辨率较高，但是实际可使用设备独立像素为 375px*812px
3. 设备像素比（Device Pixel Ratio） 设备像素比的值为在水平或者垂直方向上，物理像素与设备独立像素的比值，可以通过 `window.devicePixelRatio` 获取。例如 iphone X 的 DPR 为 3、iphone 6/6s 的 DPR 为 2、iphone 6 plus 的 DPR 为 2.608，

##### 1.1.2 视口

1. layout viewport 移动端设备因为尺寸比较小，默认情况下，在渲染页面时通常会设置一个较大的宽度来模拟 pc 端的布局，不同的系统设置的默认值可能会不同，例如 ios 设备会设置为 980px，这个布局的视口就是 layout viewport。可通过 document.documentElement.clientWidth，document.documentElement.clientHeight 来获取页面的文档的布局宽高。 【图片占位】
2. visual viewport visual viweport 为视觉视口，默认等于浏览器的窗口大小， 可通过 window.innerWidth，window.innerHeight 分别获取。用户在对浏览器进行缩放时，css 像素所占的设备物理像素会发生变化，用户可见的内容也会改变，但是因为布局视口不变，页面的结构不会发生变化。
3. ideal viewport ideal viewport 不是固定尺寸，layout viewport 的宽度通常大于浏览器的可是区域宽度，为了确保用户能正常看到网站内容，不让页面出现横向滚动条，我们需要把 layout viewport 宽度设置为 ideal viewport 宽度。当页面缩放比例设置为 100% 时，css 像素与设备独立像素相等，ideal viewport 与 visual viewport 相等。
4. meta 元素设置 我们可以通过 meta 元素的 viewport 来设置视口的缩放、布局宽度，从而让移动端达到理想的效果。

```html
<meta name="viewport" content="width=device-width; initial-scale=1; minimum-scale=1; maximum-scale=1; user-scalable=no;">
```

viewport 支持的属性以及值见下表：

| 属性          | 值                                        |
| ------------- | ----------------------------------------- |
| width         | viewport 宽度，支持整数或者"device-width" |
| height        | viewport 高度，支持整数，一般不会手动配置 |
| initial-scale | 页面初始缩放比例，数字或者小数            |
| minimum-scale | 允许用户缩小的最下比例，数字或者小数      |
| maximum-scale | 允许用户放大的最下比例，数字或者小数      |
| user-scalable | 是否允许用户缩放，布尔值或者"yes"、"no"   |

#### 2.1 适配方案

移动端适配不同尺寸常用的有三种方案，目前我们推荐使用 vw 布局方案。

##### 2.1.1 百分比方案

对于页面结构比较简单，内容均匀分布，高度固定的场景下，可以使用百分比布局，元素的宽高、间距等大小根据父元素设置，随着设备宽高的调整，内容区域可以达到比较好的适配效果。对于图片、视频、iframe 等需要等比例缩放的元素，可以利用 padding-bottom 的值设置为百分比时，是相对于元素的 width 计算特性，采用绝对定位的方式去做处理。对于复杂的页面场景，百分比布局有比较大的局限性，百分比所参考的计算对象分散，不利于维护，图片等元素的等比例缩放需要改变原有的正常流布局等问题，所以更推荐 flexible 和 vw/vh 方案。

##### 2.1.2 flexible 方案

flexible 最早是阿里应用在手机淘宝页面上的一套方案，它的核心代码比较简单，主要思路是获取浏览器的布局宽度(clientWidth)，将 html 元素的 font-size 设置为宽度的 1/10，然后页面的布局依赖 rem 单位，页面宽度变化时，通过动态设置 html 的 font-size 就可以实现多屏适配：

```js
// set 1rem = viewWidth / 10
function setRemUnit () {
    var rem = docEl.clientWidth / 10
    docEl.style.fontSize = rem + 'px'
}

setRemUnit()

// reset rem unit on page resize
window.addEventListener('resize', setRemUnit)
window.addEventListener('pageshow', function (e) {
    if (e.persisted) {
        setRemUnit()
    }
})
```

比如页面设计稿按照 iphone 6s 的分辨率为 750px*1334px 输出，设备的独立像素为 375px*617px，那么 dom 根元素 html 的 font-size 会被设置为 37.5px，那么 1 rem 等于 37.5px，设计稿上的高度为 150px 的元素，我们只需要设置为 4rem 即可。每次手动计算 px 转 rem 有点麻烦，可以利用 [postcss-px2rem](javascript:void(0)) 插件去做自动处理。

因为移动端设备的对 vw/vh 的兼容性越来越好，得到了主流机型的支持，rem 已经被淘宝弃用，转而使用下面的 vw/vh 方案。

##### 2.1.3 vw/vh 方案

vw、vh 分别表示可视视口的宽度和高度，1vw 表示视口宽度的 1/100，1vh 表示视口高度的 1/100。使用 vw 布局方案，不需要像 flexible 方案动态设置根元素的 font-size，大小单位使用 vw 即可。设计稿以 iphone 6s 分辨率为基准，设备视口宽度为 375px，那么 1vw 就等于 3.75px, 设计稿上 75px 宽度的元素，对应 20vw。同样也可以利用 [postcss-px-to-viewport](javascript:void(0))来代替人工计算。

### 2. 静态资源优化

移动端使用的是无线网络，网络条件比较复杂，对于网页性能要求要高一些，所以需要对静态资源的请求做一些优化。

#### 2.1 减少体积

图片、视频、音频拿到源文件后，一般需要压缩，保证不失真的前提下尽量减少体积。

#### 2.2 CDN 缓存

对于内容基本不变化的静态资源建议放到 CDN 做缓存处理，提高资源加载速度。

#### 2.3 合理切图

设计稿输出的资源，切图时拆分细一些，方便做动画效果，同时可以重复利用的 icon 可以做成 iconfont 字体文件或者拼接为 css-sprite，减少资源请求次数。

### 3. 埋点和数据统计

如果活动页面有运营数据的统计需求，开发者需要提前和相关人员确定好埋点的地方，需要上报什么数据。

## 设计规范

### 1. 设计稿输出标准尺寸

移动端设备尺寸繁多，为满足主流机型的适配，一般建议设计师做设计稿时，选用 iphone 6/6s 的屏幕分辨率 750px * 1334 作为标准尺寸，针对其他特殊尺寸机型(如 iphone SE、iphone 5)再做差异化适配。

### 2. 全屏场景

对于首屏或者是多张页卡竖向滑动的场景，通常是一张设计稿铺满单屏，不会出现滚动条，这时设计稿需要考虑不同机型的下的效果，保证兼容主流移动端设备的高度。

【图片占位】

特小或者特大尺寸的设备，可能需要做差异化处理，设计师确定好需要支持设备的最大、最小尺寸极限值，然后输出对应的设计稿，例如实际场景：

【图片占位】

### 3. 安全区域

移动端绝大多数的使用场景都不是在全屏幕下，页面通常为嵌入到移动端浏览器、微信、手 Q 或者其他 webview 中，设备实际有效区域可能需要减去导航栏、状态栏、标签栏的高度，另外对于“刘海屏”设备（如 iphone X）还需要考虑减去“刘海”的高度，对于部分“全面屏”设备（如 iphone X） 还需要考虑底部用来触发窗口操作区域，所以需要输出设计稿时需要考虑实际的应用场景：

1. 考虑“刘海”、“圆角”、“小黑条”区域，尽量留空或者用背景填充，不要在这些地方放信息或者可操作元素
2. 全屏场景需要按照设备可使用尺寸输出设计稿，以 iphone 6s 为标准的话设计稿尺寸应为 750 * 1095，设计时尽量在底部和左右留足够的边距，保证在小尺寸设备下按钮、文字等重要元素能够在一屏里显示完整 【图片占位】
3. 横屏场景，对于有横屏需求的场景，也需要旋转后左右的宽度问题，一般需要输出横屏下的设计稿，iphone 6s 横屏下的设备物理像素 1422 * 600，安全区域尺寸 960 * 600  【图片占位】

### 4. 字体规范

PC 端一般用微软雅黑、苹方作为默认字体来输出设计稿，移动端系统 ios、android 等不支持微软雅黑，设计师可按照 ios 系统默认的字体 （中文苹方，英文 San Francisco） 作为设计稿标准字体，如果有特殊文字或者 icon 的需求，可以引入 web 字体。

### 5. 其他注意事项

1. 设计稿输出时最好带上尺寸标注 ，推荐标记工具[markman](javascript:void(0))
2. 音乐或者视频的版权问题

## 真机调试方案

前端工程师在做 H5 的应用的时候，通常会在开发电脑上利用 chrome 浏览器的[设备模拟器](javascript:void(0))来做开发，模拟器的功能很强大，它提供了大多数主流机型的选项，如果有特殊机型需求，自己也可以定义设备分辨率和 DPR，对于本地开发来说非常的便利。但是有的时候可能会出现这样一种情况，在模拟器上开发的预期效果，放到某些机型上会出现一些奇怪的问题，相信对大部分前端开发来说，大概都碰到过。这个时候就需要用真机来做调试，解决出现的问题。

移动端真机调试常用的方案大概有以下几种：

1.数据线连接调试：iOS 和 Android 设备可以用数据线连接开发电脑，打开对应系统工具的调试选项，可以通过电脑端的 safari、chrome 浏览器的 Web Inspector 来检查移动端设备浏览器的页面。

2.代理工具 + weinre：macOS 和 windows 下可以使用 [Charles](javascript:void(0)) 或者 [Fiddler](javascript:void(0)) 作为代理工具，在同一网段下配置移动端 Wi-Fi 代理地址到开发电脑，电脑端通过对移动端的请求进行抓取，可以把电脑上的本地文件反向代理到移动端，再配合 [weinre](javascript:void(0)) 实现 Web Inspector 的功能。

3.whistle：[whistle](javascript:void(0)) 集成了代理工具 + weinre 的方案，通过类似配置系统 hosts 的方式即可实现跨平台的调试。

数据线连接调试虽然使用 Web Inspector 检查页面比较方便，但是往往需要先把本地代码打包发布到线上环境，移动设备才可以看到效果，本地的更新没法实时同步到移动端设备上，在开发过程中采用这种调试方式会非常的繁琐。代理工具 + weinre 的方案功能强大，但是代理工具需要下载客户端（两个软件的正版 license 价格不菲），还要单独配置一个 weinre 服务，本地配置的成本比较高。所以，以上两种调试方式的具体配置就不具体展开了，接下来主要描述第 3 种方案。

### whistle 方案

whistle 是 avenwu 开发的一个 Node.js 工具，可跨多系统平台，配置项可共享，并且内部集成了 weinre，功能丰富、强大，可视化的配置方式使用也比较简单，非常适合前端来做真机调试。

#### 安装和命令

- 安装

```js
npm install -g whistle # 推荐使用最新的 Node.js LTS 版本
```

- 常用命令

安装完包后，可以在命令行工具使用 `whistle` 或 `w2`

```js
w2 start # 启动
w2 start -p 8088 # 启动，配置监听端口为 8088
w2 stop # 停止
w2 run # 启动调试模式，用于查看异常和 whistle 插件开发
```

正常启动后的命令行：

![](https://static.cloudcare.cn/cloudcare-mrdoc/img/2024-07-15_160639_8267010.9905313711020647.png)

访问 http://local.whistlejs.com 链接打开线上的配置和调试页面，whistle 主要的`rules` 、`values`、`weinre 调试` 、`https证书安装`都在上面操作。

#### 代理配置

需要保证移动设备和开发电脑在同一个局域网段内

- 浏览器代理配置

使用 chrome 并安装 SwitchyOmega 插件，新建一个情景模式将浏览器代理指向 whistle。

![](https://static.cloudcare.cn/cloudcare-mrdoc/img/2024-07-15_160702_5586450.7598272780708506.png)

- 移动设备代理配置

首先在电脑端的命令行工具执行 `ifconfig` 查看本机 ip 地址，准备配置到移动端。

iOS 设备代理配置路径：`设置` > `无线局域网` > `点击当前连接网络右侧的 icon 进入详情` > `配置代理` > `手动` > `服务器填写开发机 ip 地址，端口填写开发机监听端口` > `点击右上角保存`

Andriod 设备代理配置路径（以小米手机为例）：`设置` > `点击当前连接网络进入详情` > `代理` > `手动` > `主机名填写开发机 ip 地址，端口填写开发机监听端口` > `点击右上角保存`

#### https 捕获

使用 whistle 代理 https 请求，开发机和移动端设备都需要安装根证书，在开发机配置页面点击 `https` 弹出对话框

![](https://static.cloudcare.cn/cloudcare-mrdoc/img/2024-07-15_160712_6571150.514897543808844.png)

点击 `Download RootCA` 下载开发机证书，移动端扫码或者在浏览器访问 `rootca.pro`来下载证书，如果不了解如何安装可[参考文档](javascript:void(0))。 **提醒一下，开发机使用 windows 安装证书时，一定要手动选择安装到 `受信任的根证书颁发机构` 目录下**

#### 常用 rules 配置

- weinre 调试

移动端设备使用 weinre 提供的 Web Inspector 来调试页面，可以根据页面地址配置对应的 rule

```shell
# 本地调试页面被 weinre 捕获配置
# 协议采用 weinre，协议后的名称为分组名称，根据管理需求可自定义
https://m.jd.com	weinre://debug-h5
http://dev.weixinh5.com	weinre://debug-h5
```

- 插入文件

如果需要在移动端页面注入文件，可以使用 `js` 协议配置，例如使用 [vConsole](javascript:void(0))（不能与 weinre 同时使用）来模拟 PC 端浏览器的 console 的功能，可以配置：

```shell
dev.weixinh5.com	js://{vConsole.js}
```

#### Mock 数据

另外 whistle 也可以通过增加 `values`来构造数据，然后在 `rules`里面配置代理规则，通过转发来 mocks 移动端设备请求的返回数据。

#### 文档

1. [iOS](javascript:void(0))、[Android](javascript:void(0)) 设备数据线调试模式官方文档
2. [Charles + weinre 调试](javascript:void(0))
3. [avenwu：利于 whistle 调试移动端页面](javascript:void(0))