Skip to content

响应式布局 xLayout ​


预览

介绍 ​

断点容器,两种用法: split(默认):窄屏只有主内容(整屏),宽屏多出一个 #side 区,「列表 + 详情」「侧栏 + 主区」不用跳页面、不用把内容写两份。 screen:窄屏、宽屏各一套整屏内容(#narrow 窄屏专属、默认槽宽屏专属),宽屏一般再配 #side 做左/右栏。 显示判断:App / 小程序交给官方 match-media(宽屏区 = min-width: wide);Web 生产构建里 match-media 的标签替换会失效(uni-app x 5.32 编译器缺陷),Web 改由组件按窗口宽度判断。 跨断点时触发 change 事件,业务拿它同步状态。

平台兼容 ​

HarmonyH5andriodIOS小程序UTSUNIAPP-X SDKversion
☑☑☑️☑️☑️☑️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,会一直停在窄屏。
number640
side#side 区排在主内容前面还是后面。end(默认):主内容在左、侧栏/详情在右;
start:侧栏在左,适合「导航 + 内容」。
xLayoutSide'end'
sideWidth#side 区宽度:px/rpx/% 都行,也支持 "calc(100% - 320px)" 这类表达式。空值按内容宽。
union''
space#side 区和主内容之间的间距。写在 #side 区自己身上,窄屏 #side 区不显示时不会凭空多出一段空隙。
页面上没写 #side 插槽时不需要设置。
union0
direction主内容内部的排列方向,默认 column(业务内容基本都是纵向堆叠)。内容要横排就写 row。
xLayoutDirection'column'
fill是否撑满父级剩余高度,左右分栏时两栏都会拉满。
父级必须有确定高度(写死 height 或带最小高的页面根节点);内容比父级高时 App 端会被
``overflow: hidden裁掉(uvue 的min-height默认0px,没有 Web 的 auto 下限),别拿它兜页面高度。
booleanfalse
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 事件 ​

名称参数说明
changewide: 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>
最近更新
稳定tokens