【踩坑】Uni-app微信小程序自定义组件在 Flex 布局中未铺满整行

适用范围：Uni-app、Vue 3、微信小程序（WeChat Mini Program）。

一、问题现象

页面顶部有两个筛选项：设备/回路选择器和日期选择器。设计目标是让它们各占一行：

第一行： [              设备/回路选择器              ]

第二行： [               日期选择器                   ]

实际在微信小程序端却出现了右侧留白：

第一行： [              设备/回路选择器              ]

第二行： [ 日期选择器 ] [            空白             ]

日期组件内部已经设置了以下样式，但没有解决问题：

.quota-period-filter {
	flex: 0 0 100%;
	width: 100%;
}

这不是 width: 100% 失效，也不是微信小程序丢失了组件样式；根因是这段样式作用在了错误的布局层级。

二、先建立三个基础概念

1. 弹性布局只管理直接子项

弹性布局（Flexible Box Layout，简称 Flexbox）由父容器决定其直接子项如何排列。

.quota-filters {
	display: flex;
	flex-wrap: wrap;
}

这段代码表示：

• display: flex：将直接子项按水平方向排列；
• flex-wrap: wrap：当前行放不下时，允许子项换行；
• 父容器不会直接安排孙节点或更深层节点。

可以把它想象成货架管理员：管理员只决定直接放在货架上的盒子怎样摆放，不会打开盒子去摆里面的物品。

2. width: 100% 不是屏幕宽度

width: 100% 的含义不是"占满屏幕"，而是"占满父容器已经分配给我的可用宽度"。

例如，外层盒子宽度只有 300rpx 时，内部元素即使写了 width: 100%，结果仍然只是 300rpx。内部元素不能通过自己的百分比宽度，反过来要求外层盒子变成全屏宽度。

3. 自定义组件会增加一个组件宿主节点

Vue 源码中的：

<EnergyQuotaPeriodFilter />

编译到微信小程序后，会成为独立的自定义组件标签：

<energy-quota-period-filter />

这个标签是组件宿主节点（Component Host）。父页面的 Flexbox 实际排列的是它；组件模板中的根 view 位于它的内部。

三、问题是怎样产生的

修复前，相关节点关系如下：

.quota-filters（display: flex）
├─ .quota-filter                         ← 直接 Flex 子项
└─ <energy-quota-period-filter>          ← 直接 Flex 子项，也是组件宿主
   └─ .quota-period-filter               ← 组件内部根节点
      ├─ 按月 / 按年切换
      └─ 日期选择器

设备筛选项是普通 view，并且在父页面中匹配了：

.quota-filters > .quota-filter:first-child {
	flex-basis: 100%;
}

flex-basis: 100% 可以理解为"在 Flexbox 主轴上，以一整行宽度作为自己的基础尺寸"，所以它能够独占第一行。

而日期筛选器的 flex: 0 0 100% 和 width: 100% 写在 .quota-period-filter 上。它不是 .quota-filters 的直接子项，不能决定父容器如何给 <energy-quota-period-filter> 分配宽度。

组件宿主没有显式设置 flex 或宽度时，近似按默认规则 flex: 0 1 auto 参与布局：

• flex-grow: 0：不主动占用右侧剩余空间；
• flex-shrink: 1：空间不足时允许缩小；
• flex-basis: auto：基础宽度由自身尺寸或内容尺寸决定。

因此，第二行的组件宿主会保持内容所需的宽度，并从左侧开始排布；内部元素的 width: 100% 只会填满这个较窄的宿主节点，右侧自然留下空白。

四、为什么浏览器端可能"不容易暴露"

在 H5 端，框架渲染结构、组件属性透传（Attribute Fallthrough）和浏览器布局细节，可能让问题看起来不明显。但微信小程序会保留独立的自定义组件标签，并且组件之间存在明确的渲染与样式边界。

因此，不应依赖"组件内部根节点的样式能够控制组件在父容器中的尺寸"。跨端页面应明确由父页面控制组件在页面中的行、列和宽度；组件自身只控制内部元素的比例、间距和视觉样式。

五、稳定修复方案：增加普通包装节点

在父页面中增加普通 view，让它成为 Flexbox 的直接子项：

<view class="quota-period-filter-wrapper">
	<EnergyQuotaPeriodFilter
		:quota-type="selectedQuotaType"
		:period="selectedPeriod"
		:period-options="periodOptions"
		@quota-type-change="selectQuotaType"
		@period-change="selectPeriod"
	/>
</view>

为包装节点设置整行宽度：

.quota-period-filter-wrapper {
	flex: 0 0 100%;
	width: 100%;
	min-width: 0;
}

修复后的关系变为：

.quota-filters（display: flex）
├─ .quota-filter
└─ .quota-period-filter-wrapper          ← 直接 Flex 子项，明确占满整行
   └─ <energy-quota-period-filter>
      └─ .quota-period-filter

宽度会按正确方向传递：

父级筛选区域确定可用宽度
        ↓
包装节点占据整行
        ↓
自定义组件获得包装节点宽度
        ↓
组件内部 width: 100% 填满组件可用宽度

min-width: 0 用于允许包装节点在窄屏或内容较长时正常收缩，避免文本或内部控件的最小内容宽度撑破 Flexbox 布局。

六、不要采用的修复方式

1. 只修改组件内部的 width: 100%

无效原因：内部 100% 仍然以组件宿主的实际宽度为基准，无法控制宿主作为 Flex 子项的尺寸。

2. 手工修改 unpackage/ 下的 WXML 或 WXSS

unpackage/ 是构建产物，下一次编译会被覆盖。应该修改 subpackages/ 下的 Vue 源码，再重新编译小程序。

3. 仅给组件标签直接追加 CSS 类

例如：

<EnergyQuotaPeriodFilter class="quota-period-filter-wrapper" />

在某些端可能有效，但不应把跨组件布局建立在属性透传、组件宿主实现或样式隔离行为之上。显式使用普通 view 作为直接 Flex 子项，结构和兼容性都更清楚。

4. 用 justify-content: space-between 填补空白

这只会改变 Flex 子项之间的分布位置，不能让日期组件本身获得整行宽度，也会破坏后续多个筛选项的排版规则。

七、排查同类问题的步骤

当移动端页面出现"宽度 100% 却没有铺满"的问题时，按以下顺序检查：

1. 找到设置 display: flex 的父容器。
2. 确认视觉上未铺满的元素，是否真的是该父容器的直接子项。
3. 若它是自定义组件，检查编译后的 WXML 中是否存在独立组件宿主标签。
4. 将 flex、flex-basis、width 等"页面排版规则"放在父容器的直接子项上。
5. 将组件内部样式限定为内容比例、文字省略、间距、边框和背景等"组件自身视觉规则"。
6. 重新编译并在微信开发者工具中检查窄屏、长文本、按月和按年两种状态。

八、验证清单

• 设备/回路选择器独占第一行。
• 日期选择器独占第二行并铺满筛选区域。
• 日期组件内部"按月/按年"与日期区域仍按既定比例展示。
• 长设备名、长日期文本不会挤出容器或产生横向滚动。
• 在微信开发者工具与真机上均正常显示。
• 重新构建后，未依赖手工修改 unpackage/ 产物。

九、可复用结论

在 Uni-app 的微信小程序端，自定义组件嵌入 Flexbox 时：

父页面负责组件在页面布局中的尺寸；组件内部负责自身内容的布局。

需要让自定义组件占满一行时，优先在父页面增加一个普通包装节点，并把 flex: 0 0 100% 放在这个直接 Flex 子项上。这样既符合 CSS 的布局规则，也避免了不同端自定义组件宿主行为差异带来的隐患。