Quasar 响应式容器组件 QResponsive 完全指南：基于宽度的宽高比控制

• 前端
• UI组件
• 跨平台

QResponsive 是 Quasar Framework 提供的一个纯展示型 Vue 组件，其核心能力是根据容器宽度自动推算高度，强制内部内容保持指定的宽高比（aspect ratio）。在卡片缩略图、轮播图、视频占位、表格自适应等场景中，它可以帮助开发者告别手写媒体查询与百分比 padding 技巧，一行配置即可获得稳定的比例布局。读完本文，你将掌握 QResponsive 的完整 API、与 QImg/QVideo 等自带 ratio 组件的边界划分，以及如何在 Flex 布局、QCard、QTable、QCarousel 等真实组件中落地使用。

组件定位与设计原理

QResponsive 的官方定位是"forces the content to maintain an aspect ratio based on its width"——即仅依据宽度约束内容高度，从而维持固定宽高比。它本身不关心内部内容是什么，可以是图片、视频、文本块，也可以是任意 Vue 组件，只要传入的唯一直接子节点能撑满容器即可。

从源码看，该组件实现极其轻量，完整实现位于 ui/src/components/responsive/QResponsive.js：

import { h } from 'vue' import useRatio, { useRatioProps } from '../../composables/private.use-ratio/use-ratio.js' import { createComponent } from '../../utils/private.create/create.js' import { hSlot } from '../../utils/private.render/render.js' export default /*#__PURE__*/ createComponent({ name: 'QResponsive', props: useRatioProps, setup(props, { slots }) { const ratioStyle = useRatio(props) return () => h( 'div', { class: 'q-responsive', style: ratioStyle.value }, [ h( 'div', { class: 'q-responsive__content absolute-full fit' }, hSlot(slots.default) ) ] ) } })

可以看到渲染结构为两层嵌套的<div>：

• 外层div.q-responsive：接收由useRatio计算出的aspect-ratioCSS 内联样式，是比例约束的承担者；
• 内层div.q-responsive__content：叠加了absolute-full与fit两个 Quasar 实用类，实现绝对定位铺满（position: absolute; inset: 0）与width: 100%; height: 100%，从而让内容完整填满外层容器。

由于aspect-ratio是现代浏览器原生 CSS 属性，QResponsive 在渲染时零 JavaScript 计算高度，只输出一个内联样式，性能开销极低，非常适合列表页中大量重复出现的等比例占位区域。

核心 API：ratio 属性

QResponsive 只暴露一个属性ratio，定义于 ui/src/composables/private.use-ratio/use-ratio.js：

export const useRatioProps = { ratio: [String, Number] }

ratio接受String或Number两种类型，语义是宽度 ÷ 高度的结果：

底层解析逻辑值得注意（同样见use-ratio.js）：

const rawValue = props.ratio || naturalRatio?.value if (typeof rawValue === 'string' && rawValue.trim() === '') { return null } const aspectRatio = Number(rawValue) return Number.isFinite(aspectRatio) && aspectRatio > 0 ? { aspectRatio } : null

• 字符串形式的'4/3'、'16/9'会被Number()直接解析为小数（JS 中Number('4/3')即 1.333…）；
• 空字符串、NaN、非正数都会被判定为无效，此时不输出aspect-ratio样式，组件退化为普通容器；
• 该 composable 同时预留了naturalRatio参数，供 QImg、QVideo 等自带 ratio 能力的组件复用——这正是文档警告"不要在已有ratio属性的组件上再包一层 QResponsive"的原因所在。

单元测试 ui/src/components/responsive/QResponsive.test.js 用三种用例锁定了该属性的行为契约：

// 字符串类型生效 await wrapper.setProps({ ratio: '1.7778' }) expect(Number.parseFloat(getRatio(wrapper))).toBeCloseTo(1.7778) // 数字类型生效 await wrapper.setProps({ ratio: 2 }) expect(Number.parseFloat(getRatio(wrapper))).toBe(2) // 由宽度推算高度：ratio=2 且 width=200px 时，高度应为 100px const wrapper = mount(QResponsive, { props: { ratio: 2 }, attrs: { style: 'width: 200px' } }) expect(wrapper.element.offsetHeight).toBe(100)

第三组用例直观印证了核心机制：外层容器的宽度由外部决定，高度则由aspect-ratio自动推导，这正是"基于宽度的宽高比控制"的含义。

基本用法：唯一直接子节点约束

[!TIP]使用提示

• 组件可以承载任意内容，但只能有一个直接子元素。若需要放置多个元素，请先用一个<div>包裹起来；
• 保证内容不溢出容器是你的责任——QResponsive 只负责比例，不负责裁剪或缩放。

[!WARNING]不要用在已有ratio属性的 Quasar 组件上（如 QImg、QVideo），也不要用于有强制高度的组件。

基本用法如下，此时容器宽度默认由父级撑开（或自行设置宽度），高度按ratio推导：

<q-responsive :ratio="16 / 9"> <img src="banner.jpg" alt="Banner" style="width: 100%; height: 100%; object-fit: cover;"> </q-responsive>

多个子元素时先包裹：

<q-responsive :ratio="4 / 3"> <div> <p>第一段文字</p> <button>操作按钮</button> </div> </q-responsive>

Flex 行布局中的正确姿势

当 QResponsive 作为 flex 容器（如q-flex/.row）的直接子项出现时，需要注意 flexbox 的默认align-items: stretch会强制拉伸每个子项的高度，从而覆盖 QResponsive 依据比例推导出的高度。

官方建议：使用items-start（即align-items: flex-start）等垂直对齐方式来关闭拉伸行为：

<div class="row items-start"> <div class="col-4"> <q-responsive :ratio="16 / 9"> <q-img src="cover-1.jpg" /> </q-responsive> </div> <div class="col-4"> <q-responsive :ratio="16 / 9"> <q-img src="cover-2.jpg" /> </q-responsive> </div> <div class="col-4"> <q-responsive :ratio="16 / 9"> <q-img src="cover-3.jpg" /> </q-responsive> </div> </div>

不加items-start时，三个子项会被拉伸到等高，各自推导出的高度失效，比例约束被破坏。

在既有 Quasar 组件上使用

QResponsive 并不局限于某一种组件，官方文档以 QCard、QCardSection、QTable、QCarousel 为例，说明它可作为通用比例容器嵌入任意组件树。以下场景具备典型参考价值：

QCard 缩略图区——常见于图文卡片头部：

<q-card> <q-responsive :ratio="16 / 9"> <q-img src="article-cover.jpg" /> </q-responsive> <q-card-section> <div class="text-h6">文章标题</div> <div class="text-subtitle2">by Quasar Team</div> </q-card-section> </q-card>

QCardSection——需要按比例排版的分区内容。

QTable 外层包裹——让表格整体维持固定视觉比例，或在表格与工具栏组合时统一高度节奏：

<q-responsive :ratio="16 / 9"> <q-table :rows="rows" :columns="columns" row-key="name" /> </q-responsive>

QCarousel 轮播——这是最典型的应用场景。官方特别强调：当使用 QResponsive 包裹 QCarousel 时，不要再给 QCarousel 传height属性，因为高度职责已交给 QResponsive，两者同时设置会造成冲突：

<q-responsive :ratio="16 / 9"> <q-carousel v-model="slide" animated navigation infinite > <q-carousel-slide :name="1" img-src="slide-1.jpg" /> <q-carousel-slide :name="2" img-src="slide-2.jpg" /> </q-carousel> </q-responsive>

最大高度等尺寸约束

比例容器同样受 CSS 尺寸约束支配。若希望"比例优先、高度封顶"，可直接在外层 QResponsive 上通过 CSS 类或内联样式施加max-height（或max-width等）：

<q-responsive :ratio="16 / 9" class="q-mx-auto" style="max-height: 300px; max-width: 720px;"> <q-img src="cover.jpg" /> </q-responsive>

需要牢记的是：限制最大高度后，实际渲染高度取"比例推导值"与"约束值"中的较小者，此时宽高比可能不再严格等于ratio；同样地，保证内容不溢出仍是开发者自己的责任，例如图片应配合object-fit: cover或使用 QImg 自带的裁剪能力。

无障碍（Accessibility）

自 v2.25 起，官方在文档中明确了 QResponsive 的无障碍定位：它纯粹是一个展示型（presentational）宽高比包装器，自身不携带任何无障碍语义表面（no accessibility surface of its own）。

这意味着：

• 它不会向辅助技术暴露可聚焦节点、角色（role）或可访问名称；
• 无障碍信息的承载应交给内部真实内容（如<img>的alt、按钮的可访问文本、视频的字幕等）；
• 使用它不会对页面整体的无障碍树产生额外负担，也无需为它编写额外的 ARIA 属性。

与 QImg / QVideo 等自带 ratio 组件的边界

QResponsive 的 ratio 机制与 QImg、QVideo 内部的ratio属性同源于useRatiocomposable（见use-ratio.js的naturalRatio参数）。官方文档明确警告不要嵌套使用，原因有二：

1. 职责重复：QImg / QVideo 已经基于同一套机制完成比例计算，外层再包一层属于冗余，且内外两层比例不一致时会出现不可预期的留白或溢出；
2. 高度冲突：QResponsive 推导出的高度会被内层组件的强制高度覆盖或叠加，导致布局错乱。

正确的做法是二选一：要么直接用<q-img :ratio="16/9" />，要么用 QResponsive 包裹无 ratio 能力的普通内容。

小结

QResponsive 以极小的 API 面解决了一个高频布局问题。理解其"只算比例、不碰内容"的边界后，你可以放心地把它用在任何需要等比例占位的界面中——相关实现与测试均可直接查看 ui/src/components/responsive/QResponsive.js 与 ui/src/components/responsive/QResponsive.test.js 加深理解。

• 前端
• UI组件
• 跨平台