Skip to content

界面开发:组件、布局与多端适配 ​

本篇要点:用一套 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 组件关键差异
divview没有默认样式,块级,等同裸 div
spantext只能嵌套 text;连续空格与换行会被压缩
imgimage默认按 320×240 渲染,必须给宽高或 mode
buttonbutton自带圆角与边框(画在 ::after 上),要手动重置
ul/liview + v-for没有列表语义,也没有默认缩进
inputinput没有 change 语义,用 @input 与 @blur
selectpicker弹层由系统提供,样式改不动
带 overflow 的 divscroll-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 指示条是典型。四个值都要记:

变量微信小程序AppH5用途
--status-bar-height固定 25px真实状态栏高度0自定义导航栏占位
--window-top00导航栏高度内容区距顶
--window-bottom00tabBar 高度固定按钮避开 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。手写一套当然也行,代价是每个页面都要重复「什么时候校验、错误挂在哪、提交时怎么拦」。

js
// 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:

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 而不给高度,安卓上高度会先按默认值算一次再跳变。

第二步,页面用它,并把底部栏顶到安全区之上:

vue
<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 放项目根目录:

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,这个文件不会报错,只是永远不生效。

第四步,让页面内容也跟上,并记下当前主题:

js
// 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 里怎么和本地缓存接上,以及弱网下请求该怎么重试。