响应式布局 xLayout
预览
介绍
断点容器,两种用法: split(默认):窄屏只有主内容(整屏),宽屏多出一个 #side 区,「列表 + 详情」「侧栏 + 主区」不用跳页面、不用把内容写两份。 screen:窄屏、宽屏各一套整屏内容(#narrow 窄屏专属、默认槽宽屏专属),宽屏一般再配 #side 做左/右栏。 显示判断:App / 小程序交给官方 match-media(宽屏区 = min-width: wide);Web 生产构建里 match-media 的标签替换会失效(uni-app x 5.32 编译器缺陷),Web 改由组件按窗口宽度判断。 跨断点时触发 change 事件,业务拿它同步状态。
平台兼容
| Harmony | H5 | andriod | IOS | 小程序 | UTS | UNIAPP-X SDK | version |
|---|---|---|---|---|---|---|---|
| ☑ | ☑ | ☑️ | ☑️ | ☑️ | ☑️ | 4.76+ | 1.9.9 |
文件路径
ts
@/uni_modules/tmx-ui/components/x-layout/x-layout.uvue使用
ts
<x-layout></x-layout>Props 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| mode | 布局模式。- split(默认):#side 区宽屏才出现,默认槽常驻(窄屏就是它的整屏),适合「列表 + 详情」这类加一栏。- screen:窄屏 / 宽屏两套整屏内容二选一 —— #narrow 只在窄屏显示,默认槽只在宽屏显示, 宽屏一般再配 #side 做左/右栏,适合「手机竖屏一套、宽屏换一套」。 | xLayoutMode | 'split' |
| wide | 宽屏断点,单位固定 px。窗口宽度 >= 该值算宽屏,宽屏才显示 #side 区。默认 640:手机横屏就跨过(最窄的常见横屏是 iPhone SE 的 667),平板竖屏 768 也算宽屏。取 700 会踩坑——iPhone SE / 8 横屏只有 667,会一直停在窄屏。 | number | 640 |
| side | #side 区排在主内容前面还是后面。end(默认):主内容在左、侧栏/详情在右;start:侧栏在左,适合「导航 + 内容」。 | xLayoutSide | 'end' |
| sideWidth | #side 区宽度:px/rpx/% 都行,也支持 "calc(100% - 320px)" 这类表达式。空值按内容宽。 | union | '' |
| space | #side 区和主内容之间的间距。写在 #side 区自己身上,窄屏 #side 区不显示时不会凭空多出一段空隙。页面上没写 #side 插槽时不需要设置。 | union | 0 |
| direction | 主内容内部的排列方向,默认 column(业务内容基本都是纵向堆叠)。内容要横排就写 row。 | xLayoutDirection | 'column' |
| fill | 是否撑满父级剩余高度,左右分栏时两栏都会拉满。父级必须有确定高度(写死 height 或带最小高的页面根节点);内容比父级高时 App 端会被``overflow: hidden 裁掉(uvue 的min-height默认0px,没有 Web 的 auto 下限),别拿它兜页面高度。 | boolean | false |
| padding | 内边距 [全部],[左右,上下],[左,上,右],[左,上,右,下],可传 string/number 自动转为数组 | union | '' |
| round | 圆角 [全部],[左,右],[左,上,右],[左,上,右,下],可传 string/number 自动转为数组 | union | '' |
| bgColor | 背景色。 | string | 'transparent' |
| darkBgColor | 暗黑时的背景色,空值按亮色背景自动加深。 | string | '' |
| customStyle | 追加到根节点的样式,写在最后,可覆盖 bgColor / round / padding / fill。页面背景要铺到窗口底(渐变 + flex:1)、或给整块留边距时用它。 | string | '' |
| customContentStyle | 追加到主内容区(默认槽那一侧)的样式。 | string | '' |
| customSideStyle | 追加到 #side 区(宽屏那一栏)的样式,和 sideWidth / space 作用在同一层。 | string | '' |
Events 事件
| 名称 | 参数 | 说明 |
|---|---|---|
| change | wide: boolean | 跨过断点时触发(窄屏 <-> 宽屏)。挂载后会先按当前断点触发一次,父组件用它拿初始状态; 之后只在真正跨断点时触发,同一断点内反复改窗口尺寸不会重复触发。 |
Slots 插槽
| 名称 | 说明 | 数据 |
|---|---|---|
| narrow | 窄屏内容(mode="screen"),只写一份,宽屏时不渲染 | - |
| side | 宽屏专属区,窗口宽度 >= wide 才显示;默认排在主内容右侧,side="start" 则排在左侧 | - |
| default | 主内容。split 模式下所有断点都显示;screen 模式下只在宽屏显示 | - |
Ref 方法
| 名称 | 参数 | 返回值 | 说明 |
|---|
示例文件路径
json
/pages/chongyong/layout示例源码
uvue
vue
<template>
<!-- #ifdef MP-WEIXIN || MP-ALIPAY -->
<page-meta :page-style="`background-color:${xThemeConfigBgColor}`">
<navigation-bar :background-color="xThemeConfigNavBgColor"
:front-color="xThemeConfigNavFontColor"></navigation-bar>
</page-meta>
<!-- #endif -->
<x-sheet>
<x-text font-size="18" class="text-weight-b mb-8">响应式布局 xLayout</x-text>
<x-text color="#999999">窄屏整屏,宽屏自动多出一栏(断点 {{ WIDE_BP }}px)。</x-text>
<x-text color="#999999">请使用横屏,屏幕旋转,模拟等方式变动本页面宽,展示响应式排版布局。</x-text>
<view class="bp-row">
<text class="bp-label">当前断点:</text>
<text class="bp-state" :style="_bpStyle">{{ _isWide ? '宽屏' : '窄屏' }}</text>
<text class="bp-label">(change 触发 {{ _changeCount }} 次)</text>
</view>
</x-sheet>
<x-sheet>
<x-text font-size="18" class="text-weight-b mb-8">列表 + 详情</x-text>
<x-text color="#999999" class="mb-12">窄屏只有列表;宽屏右侧并排显示详情。</x-text>
</x-sheet>
<x-layout :wide="WIDE_BP" side-width="64%" :space="10" :padding="12" bgColor="white" round="14" class="mx-12"
@change="_onBreakpoint">
<template #side>
<view class="pane pane-detail" :style="{ backgroundColor: _paneDetailBg }">
<x-text font-size="15" class="text-weight-b">详情区</x-text>
</view>
</template>
<view class="pane pane-list" :style="{ backgroundColor: _paneBlueBg }">
<x-text font-size="15" class="text-weight-b">列表区</x-text>
</view>
</x-layout>
<x-sheet margin="12">
<x-text font-size="18" class="text-weight-b mb-8">侧栏 + 主区</x-text>
<x-text color="#999999" class="mb-12">侧栏在左,两栏都撑满父级高度。</x-text>
</x-sheet>
<view class="fill-host">
<x-layout :wide="WIDE_BP" side="start" side-width="20%" :space="10" :fill="true" :padding="12"
bgColor="white" round="14">
<template #side>
<view class="pane pane-nav" :style="{ backgroundColor: _paneGreenBg }">
<x-text font-size="15" class="text-weight-b">侧栏</x-text>
</view>
</template>
<view class="pane pane-body" :style="{ backgroundColor: _paneBlueBg }">
<x-text font-size="15" class="text-weight-b">主区</x-text>
</view>
</x-layout>
</view>
<x-sheet margin="12">
<x-text font-size="18" class="text-weight-b mb-8">窄屏一套、宽屏另换一套</x-text>
<x-text color="#999999" class="mb-12">mode="screen":#narrow 只在窄屏渲染,默认槽只在宽屏渲染,
两套整屏内容各写各的;宽屏再配 #side 就是左栏 + 右栏。节点样式用 customStyle 追加。</x-text>
</x-sheet>
<x-layout mode="screen" :wide="WIDE_BP" side="start" side-width="30%" :space="10" :padding="12" bgColor="white"
round="14" class="mx-12" :custom-style="_screenGradientStyle">
<template #narrow>
<view class="pane pane-narrow" :style="{ backgroundColor: _paneNarrowBg }">
<x-text font-size="15" class="text-weight-b">窄屏整屏</x-text>
<x-text font-size="12" color="#999999" class="mt-6">窗口宽到 {{ WIDE_BP }}px 以上就换成下面那套</x-text>
</view>
</template>
<template #side>
<view class="pane pane-nav" :style="{ backgroundColor: _paneGreenBg }">
<x-text font-size="15" class="text-weight-b pa-n5">侧栏</x-text>
</view>
</template>
<view class="pane pane-body" :style="{ backgroundColor: _paneBlueBg }">
<x-text font-size="15" class="text-weight-b pa-n5">宽屏主区</x-text>
</view>
</x-layout>
<x-sheet margin="12">
<x-text font-size="18" class="text-weight-b mb-8">嵌套:主区里再来一套</x-text>
<x-text color="#999999" class="mb-12">每层各判各的断点(外层 {{ WIDE_BP }}px、内层 {{ NEST_BP }}px),互不干扰;
内层现在:{{ _nestWide ? '宽屏,右边多出详情栏' : '窄屏,只有列表' }}。</x-text>
</x-sheet>
<x-layout :wide="WIDE_BP" side="start" side-width="26%" :space="10" :padding="12" bgColor="white" round="14"
class="mx-12">
<template #side>
<view class="pane pane-nav" :style="{ backgroundColor: _paneGreenBg }">
<x-text font-size="15" class="text-weight-b">外层侧栏</x-text>
</view>
</template>
<!-- 主区里再嵌一套,内层断点比外层靠后:窗口要再宽一档才多出内层的详情栏 -->
<x-layout :wide="NEST_BP" side-width="40%" :space="8" :padding="10" round="10" bgColor="#f4f7ff"
darkBgColor="#1e222b" @change="_onNestChange">
<template #side>
<view class="pane pane-detail" :style="{ backgroundColor: _paneDetailBg }">
<x-text font-size="15" class="text-weight-b">内层详情</x-text>
</view>
</template>
<view class="pane pane-list" :style="{ backgroundColor: _paneBlueBg }">
<x-text font-size="15" class="text-weight-b">内层列表</x-text>
<x-text font-size="12" color="#999999" class="mt-6">宽到 {{ NEST_BP }}px 右边多出详情</x-text>
</view>
</x-layout>
</x-layout>
<view style="height:40px"></view>
</template>
<script lang="ts" setup>
import { computed, ref } from "vue"
import { xConfig } from "@/uni_modules/tmx-ui"
/** 宽屏断点:手机竖屏(375~430)够不着,横过来就跨过(最窄的常见横屏是 iPhone SE 的 667) */
const WIDE_BP = 640
/** 嵌套演示里内层的断点,故意比外层靠后,用来看每层各判各的 */
const NEST_BP = 900
/** change 事件给的状态。显示不靠它,只用来读当前断点和数触发次数 */
const _isWide = ref<boolean>(false)
const _changeCount = ref<number>(0)
/** 内层 layout 自己的断点状态:外层宽了它不一定宽,各判各的 */
const _nestWide = ref<boolean>(false)
/** 暗黑下文字是浅色,分区块的浅底要换成深底,否则白字压在亮底上读不清 */
const _isDark = computed((): boolean => xConfig.dark == 'dark')
/** 蓝底区块(列表区 / 主区) */
const _paneBlueBg = computed((): string => _isDark.value ? '#172741' : '#e8f3ff')
/** 橙底区块(详情区) */
const _paneDetailBg = computed((): string => _isDark.value ? '#3a2b1a' : '#fff5e6')
/** 绿底区块(侧栏) */
const _paneGreenBg = computed((): string => _isDark.value ? '#1b2f21' : '#eafaea')
/** 窄屏整屏区块 */
const _paneNarrowBg = computed((): string => _isDark.value ? '#1b2438' : '#eef3ff')
/** 窄屏/宽屏两套演示的整块渐变底,暗黑用深色渐变 */
const _screenGradientStyle = computed((): string => {
if (_isDark.value) return 'background-image: linear-gradient(to bottom,#1a2438,#1c1c1E)'
return 'background-image: linear-gradient(to bottom,#eaf1ff,#ffffff)'
})
/** 断点颜色:宽屏绿、窄屏橙。暗黑下换成亮一档的颜色,深底上才看得清 */
const _bpStyle = computed((): Map<string, any> => {
const map = new Map<string, any>()
if (_isDark.value) {
map.set("color", _isWide.value ? "#4ade80" : "#fbbf24")
} else {
map.set("color", _isWide.value ? "#1a7f37" : "#8a4b00")
}
return map
})
function _onBreakpoint(wide : boolean) : void {
_isWide.value = wide
_changeCount.value = _changeCount.value + 1
}
/** 内层 layout 的断点回调,和外层那个互不影响 */
function _onNestChange(wide : boolean) : void {
_nestWide.value = wide
}
</script>
<style scoped>
.bp-row {
flex-direction: row;
align-items: center;
margin-top: 10px;
}
.bp-label {
font-size: 12px;
color: #999999;
}
.bp-state {
font-size: 12px;
font-weight: bold;
}
/* 空容器演示:列表区,窄屏整屏、宽屏占剩下的 60% */
.pane-list {
height: 120px;
border-radius: 10px;
background-color: #e8f3ff;
align-items: center;
justify-content: center;
}
/* 空容器演示:详情区,宽屏才出现,和列表等高 */
.pane-detail {
flex: 1;
height: 120px;
border-radius: 10px;
background-color: #fff5e6;
align-items: center;
justify-content: center;
}
.pane-nav {
flex: 1;
border-radius: 10px;
background-color: #eafaea;
align-items: center;
justify-content: center;
}
.pane-body {
flex: 1;
border-radius: 10px;
background-color: #e8f3ff;
align-items: center;
justify-content: center;
}
/* 窄屏整屏:只在窄屏出现,横过来就换成侧栏 + 主区 */
.pane-narrow {
height: 120px;
border-radius: 10px;
background-color: #eef3ff;
align-items: center;
justify-content: center;
}
/* fill 需要一个有确定高度的父级,否则 flex:1 无从吃起 */
.fill-host {
height: 180px;
margin-left: 12px;
margin-right: 12px;
}
</style>