界面开发:组件、布局与多端适配
本篇要点:用一套
view加 flex 加 rpx 写出的页面在三端都不变形,表单校验与暗色主题各只有一个入口。 前置:《uni-app 入门:工程结构、运行机制与多端差异》的页面注册与生命周期、《工程化:Vue3 + Vite、条件编译与分包》的 easycom 与条件编译;这一章把页面从「能显示」推到「能交付」。
为什么需要它
一个商城改版,设计稿是 375 宽的 iPhone 稿。开发照着标注量,商品卡片写 width: 340px:在 iPhone SE 上刚好,在 iPhone 15 Pro Max 上两边留出两条白边,在 iPad 上缩在正中间像张邮票。改成 rpx 之后卡片撑满了,标题字号也跟着一起放大,大屏上像开了放大镜。底部结算栏在 iOS 上被 Home 指示条压住三成,安卓上又空出一截。切到系统深色模式,原生导航栏变黑了,页面内容还是白的。
三件事,三个不同层次。单位决定「长多大」,安全区决定「点不点得到」,主题决定「看不看得清」。这一章按这三层往下走,最后合成一个页面。
图 3-1 界面在三端走样的三层,以及每层对应的处理手段
如图 3-1 所示,三层里只有第一层是纯数学,另外两层都得知道目标平台的行为。先修单位,再对组件,最后补主题,顺序反了会白改一遍。
核心概念
内置组件不是 HTML 标签
内置组件(built-in component)是一组跨端语义一致的基础标签,编译时会被翻译成各端的实现:小程序端变成原生组件,H5 端变成 Web 元素,App 的 vue 页面变成 WebView 里的节点。名字像 HTML,行为不一样。
| HTML 写法 | uni-app 组件 | 关键差异 |
|---|---|---|
div | view | 没有默认样式,块级,等同裸 div |
span | text | 只能嵌套 text;连续空格与换行会被压缩 |
img | image | 默认按 320×240 渲染,必须给宽高或 mode |
button | button | 自带圆角与边框(画在 ::after 上),要手动重置 |
ul/li | view + v-for | 没有列表语义,也没有默认缩进 |
input | input | 没有 change 语义,用 @input 与 @blur |
select | picker | 弹层由系统提供,样式改不动 |
带 overflow 的 div | scroll-view | 必须有确定高度才会滚动 |
image 不给宽高就按 320×240 渲染,这是「图片怎么突然这么大」的第一来源。button 的边框画在伪元素上,覆盖不掉就写 button::after { border: none; }。
布局上还有一处方向相反的差异。vue 页面里 view 是块级元素,得自己写 display: flex 才变成弹性容器;nvue 与 uvue 页面里容器默认就是 flex,主轴还是纵向。同一句 flex-direction: row,在 vue 页面里是废话,在 nvue 里是必须写的一句。
反例:scroll-view 写了 height: 100%,父级 view 却没有高度,于是它高度算出来是 0,滚不动也不报错。要么给父级一个确定高度,要么给 scroll-view 一个 calc(100vh - 88px) 这样的表达式。
尺寸单位与安全区
rpx 是响应式像素,以 750 为基准宽度,750rpx 恰好等于屏幕宽度。换算公式是 750 × 设计稿元素宽 ÷ 设计稿基准宽:640 宽的稿子里一个 100px 的按钮,写成 117rpx。
rpx 只跟宽度等比。字号用 rpx,屏越宽字越大;1px 描边用 rpx,在两倍屏上变成 0.5px,有些安卓机会直接不画。可以记成一条分工:宽度、间距、圆角用 rpx,字号、描边、图标尺寸用 px。
H5 端还有一层兜底。pages.json 的 globalStyle.rpxCalcMaxDeviceWidth 默认 960,设备宽度超过它之后按 rpxCalcBaseDeviceWidth(默认 375)换算,否则 iPad 上一张卡片能撑到两千多 rpx。这个兜底在 App 的 vue2 与 H5 上生效,Vue3 项目里以实际渲染为准,改配置前先量一遍。
安全区(safe area)指屏幕上不能被内容侵占的区域,iOS 的刘海和底部 Home 指示条是典型。四个值都要记:
| 变量 | 微信小程序 | App | H5 | 用途 |
|---|---|---|---|---|
--status-bar-height | 固定 25px | 真实状态栏高度 | 0 | 自定义导航栏占位 |
--window-top | 0 | 0 | 导航栏高度 | 内容区距顶 |
--window-bottom | 0 | 0 | tabBar 高度 | 固定按钮避开 tabBar |
env(safe-area-inset-bottom) | 支持 | 支持 | 支持 | 避开 Home 指示条 |
底部固定栏的写法只有一句:padding-bottom: calc(16rpx + env(safe-area-inset-bottom))。安卓上这个值多数机型返回 0,正好不用条件编译;iOS 11.0 到 11.2 要补一句 constant(),用 padding-bottom: 16rpx; padding-bottom: calc(16rpx + constant(safe-area-inset-bottom)); 这种双声明回落。
自定义组件与插槽
自定义组件(custom component)是把一段界面加行为封成一个 .vue 文件。easycom 约定下,放在 components/goods-card/goods-card.vue 就直接能用 <goods-card />,不用 import 也不用注册;目录名和文件名必须一致,改错一个字母就变成「组件未注册」。
三个扩展点各有分工:props 传有限、可枚举的配置;事件通知外部「发生了什么」;插槽(slot)放内容形态不确定的部分。命名插槽负责「有固定位置但内容会变」的区块,作用域插槽把子组件内部数据交回给调用方渲染。
样式隔离要说清楚。小程序端的组件样式天然不外泄,父级选择器进不去;H5 端靠 scoped 给选择器加属性。父级想改子组件内部,只有三条路:组件暴露 custom-class 让外部传类名、用 CSS 变量、或者在 H5 与 vue 页面里用 :deep()。第三条在小程序端不生效,这是「本地调好了,真机没变」的常见原因。
表单与校验
表单(form)这块,uni-forms 能用就用,它把「校验规则、错误提示、滚动到出错项」都收在一个组件里。规则写成对象数组,required、minLength、pattern 都由它处理,validate() 返回 Promise。手写一套当然也行,代价是每个页面都要重复「什么时候校验、错误挂在哪、提交时怎么拦」。
// src/utils/validate.js —— 所有页面共用一份规则
export const rules = {
phone: [
{ required: true, errorMessage: '手机号不能为空' },
{ pattern: '^1[3-9]\\d{9}$', errorMessage: '手机号格式不对' }
],
amount: [
{ required: true, errorMessage: '金额不能为空' },
{ validateFunction: (rule, value) => Number(value) > 0, errorMessage: '金额必须大于 0' }
]
}
export function pickErrors(result) {
// uni-forms 的 validate 回调里,成功时 errors 为 null
return result && result.errors ? result.errors : []
}运行结果:手机号填 123 时 pickErrors 返回一条 { key: 'phone', errorMessage: '手机号格式不对' };金额填 0 返回「金额必须大于 0」;两项都合法时返回空数组。规则集中在一处之后,改提示文案就只改这一个文件。
校验时机比规则更容易出问题。失焦校验(@blur)适合单个字段,用户填完立刻知道对错;提交校验适合整张表单,一次把所有错误标出来。两者都做,用户会在还没填完时就被红字打断。约定一条:字段失焦只清错、不报错,点提交才全量校验并把焦点滚到第一个错误项。
主题与暗色模式
暗色模式(dark mode)在 uni-app 里分四层,缺一层就会露出白块。
第一层是 manifest.json 里对应平台开 "darkmode": true 并给出 "themeLocation": "theme.json"。第二层是 theme.json 里 light、dark 两组变量。第三层是 pages.json 里用 @变量名 引用,但它只能覆盖原生导航栏、tabBar、窗口背景这几项,页面内容管不到。第四层是页面自己的颜色,靠 CSS 变量或 prefers-color-scheme 媒体查询。
uni.getSystemInfoSync().theme 只有在 darkmode: true 之后才有值,之前是 undefined。监听切换用 uni.onThemeChange,App 端还得先调 plus.nativeUI.setUIStyle('auto'),否则系统切了它也收不到。鸿蒙端这套配置从 HBuilderX 5.0 起支持,manifest.json 里写在 app-harmony 节点下。
动手实践
做一个「商品卡片 + 底部结算栏」的页面,四步。
第一步,写卡片组件 components/goods-card/goods-card.vue:
<template>
<view class="card">
<image class="cover" :src="cover" mode="aspectFill" />
<view class="body">
<text class="title">{{ title }}</text>
<slot name="price" :price="price">
<text class="price">¥{{ price }}</text>
</slot>
</view>
</view>
</template>
<script setup>
defineProps({
cover: { type: String, required: true },
title: { type: String, default: '' },
price: { type: Number, default: 0 }
})
</script>
<style scoped>
.card { border-radius: 16rpx; overflow: hidden; background: var(--card-bg, #fff); }
.cover { width: 100%; height: 340rpx; display: block; }
.body { padding: 20rpx 24rpx; }
.title { font-size: 30rpx; line-height: 44rpx; color: var(--text-main, #1f1f1f); }
.price { font-size: 34rpx; color: var(--price, #e4393c); }
</style>运行结果:三端都渲染出等比封面加两行文字,卡片圆角一致。image 有确定高度,不会再出现 320×240 的默认尺寸;把 mode 改成 widthFix 而不给高度,安卓上高度会先按默认值算一次再跳变。
第二步,页面用它,并把底部栏顶到安全区之上:
<template>
<view class="page">
<goods-card :cover="item.cover" :title="item.title" :price="item.price">
<template #price="{ price }">
<text class="price-cut">券后 ¥{{ (price - 10).toFixed(2) }}</text>
</template>
</goods-card>
<view class="bar">
<button class="btn" @click="onBuy">立即结算</button>
</view>
</view>
</template>
<script setup>
import { ref } from 'vue'
const item = ref({ cover: '/static/goods-1.jpg', title: '云南小粒咖啡 250g', price: 68 })
function onBuy() {
uni.navigateTo({ url: '/pages/order/confirm' })
}
</script>
<style scoped>
.page { min-height: 100vh; padding-bottom: 140rpx; background: var(--page-bg, #f6f6f6); }
.bar {
position: fixed; left: 0; right: 0; bottom: 0;
padding: 16rpx 24rpx;
padding-bottom: calc(16rpx + env(safe-area-inset-bottom));
background: var(--card-bg, #fff);
}
.btn { border-radius: 44rpx; background: #e4393c; color: #fff; }
.btn::after { border: none; }
</style>运行结果:底部栏在 iOS 上多出约 34px 的下内边距,按钮完整露出;安卓上 env 返回 0,内边距就是 16rpx,不多不少;H5 上如果把 bottom: 0 写成固定定位又没算 --window-bottom,按钮会压住 tabBar。
第三步,配暗色。theme.json 放项目根目录:
{
"light": {
"navBg": "#ffffff",
"navText": "black",
"tabBg": "#ffffff",
"tabColor": "#7A7E83"
},
"dark": {
"navBg": "#1f1f1f",
"navText": "white",
"tabBg": "#1f1f1f",
"tabColor": "#9a9a9a"
}
}运行结果:pages.json 里把 navigationBarBackgroundColor 写成 "@navBg"、navigationBarTextStyle 写成 "@navText",切到深色模式后导航栏背景与 tabBar 背景跟着变。如果 pages.json 里仍然写死 #ffffff,这个文件不会报错,只是永远不生效。
第四步,让页面内容也跟上,并记下当前主题:
// App.vue 的 script 部分
export default {
onLaunch() {
// #ifdef APP-PLUS
plus.nativeUI.setUIStyle('auto')
// #endif
const { theme } = uni.getSystemInfoSync()
console.log('初始主题:', theme)
uni.onThemeChange(({ theme }) => {
console.log('主题切换为:', theme)
// 存进 store,页面里用 :class 或 CSS 变量跟着改
uni.setStorageSync('theme', theme)
})
}
}运行结果:darkmode: true 时首行打印 初始主题: dark(系统处于深色时);在系统设置里切换外观,第二行打印 主题切换为: light。没配 darkmode 时首行是 初始主题: undefined,监听也不会触发——这两件事经常被当成「API 不好用」。
交付前用三个尺寸各截一张图:375 宽的 iPhone SE、412 宽的安卓、1280 宽的浏览器窗口。看三件事——卡片有没有留白或溢出、底部按钮离屏幕边缘的距离是否一致、深色模式下有没有白底黑字的孤岛。三张图放一起,比在模拟器里来回点十次更容易看出问题出在哪一层。
常见误解
以为 rpx 能替代所有单位。 它只按宽度等比。字号用 rpx,平板上一行标题能撑到 48px;1px 描边用 rpx,一倍屏上会被四舍五入到 0。派工单里写「全站用 rpx」,通常半年后要回来逐个改字号。
以为配了 darkmode 页面就自动变黑。 theme.json 加 @变量 只覆盖原生导航栏、tabBar 和窗口背景,页面里的 background: #fff 是普通 CSS,框架不会替你改。页面颜色得落在 CSS 变量上,或者写 @media (prefers-color-scheme: dark)。
以为 scoped 能挡住父级覆盖。 它只是加了个属性选择器。子组件的根节点会同时带上父组件的 scope 标记,父级的样式照样能命中;反过来,父级想改子组件内部的深层节点,不加 :deep() 就改不动,加了在小程序端又失效。真正的边界靠组件 API 和 CSS 变量,不靠 scoped。
小结
- 内置组件的名字像 HTML,行为不像:
image有默认尺寸,button的边框在伪元素上,input没有change。 scroll-view必须有确定高度才滚;flex 在 vue 页面要自己声明,在 nvue 与 uvue 里默认就是纵向弹性容器。- 宽度、间距、圆角用 rpx,字号、描边、图标用 px;底部固定栏用
calc(内边距 + env(safe-area-inset-bottom))一次写对三端。 - 自定义组件靠 props、事件、插槽三件套划边界;父级要改内部样式,只走
custom-class或 CSS 变量。 - 暗色模式是四层:
manifest.json开关、theme.json变量、pages.json的@引用、页面自己的 CSS 变量或媒体查询。少一层就露出白块。
相关主题
页面画完,数据得从服务器来。《网络与数据:请求封装、缓存与状态管理》 网络与数据:请求封装、缓存与状态管理 讲 uni.request 怎么封拦截器、三端的 cookie 与 token 为什么要分开处理、Pinia 在 uni-app 里怎么和本地缓存接上,以及弱网下请求该怎么重试。