Quasar QTimeline 组件完全指南：三种布局、插槽体系与无障碍时间线实战

前端UI组件跨平台【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址https://gitcode.com/gh_mirrors/qu/quasar点击查看免费下载Quasar Framework 的QTimeline组件用于以时间轴的形式按时间顺序展示事件列表其视觉形态是一条贯穿页面的时间线沿线标注日期与事件。本文以 timeline.md 官方文档为主线结合仓库内组件源码QTimeline.js、QTimelineEntry.js与全部官方示例完整讲解 QTimeline 的三种布局、QTimelineEntry 的属性/插槽双体系用法、响应式切换方案与无障碍细节读完后你将能独立搭建从紧凑列表到双侧交替排布的时间线界面。组件定位与适用场景QTimeline 展示按时间顺序排列的事件列表时间轴可以采用任意时间尺度日、月、年、里程碑阶段等取决于主题与数据本身。它由两个组件协作构成QTimeline时间线的容器负责布局layout、整体侧边side与主题色color控制QTimelineEntry时间线上的单个条目承载标题、副标题、正文、图标/头像等具体内容。官方文档定义其典型场景为一条长条时间轴轴上标注日期并伴随事件的图形化设计例如项目里程碑、产品发布记录、简历工作经历、订单物流跟踪等。三大布局模式dense / comfortable / looseQTimeline 内置三种布局layoutprop官方文档的原始定义如下dense默认标题heading、条目标题title、副标题subtitle与内容全部显示在时间线指定的一侧默认右侧comfortable标题、条目标题与内容显示在时间线指定的一侧默认右侧而副标题显示在另一侧loose标题heading居中显示条目标题与内容显示在条目自身指定的一侧默认右侧副标题显示在另一侧。从源码 QTimeline.js 可见三个合法值被严格限定const sideValues [left, right] const layoutValues [dense, comfortable, loose]容器据此生成的 CSS 类名直接编码了布局 侧边的组合QTimeline.jsconst classes computed( () q-timeline q-timeline--${props.layout} q-timeline--${props.layout}--${props.side} (isDark() ? q-timeline--dark : ) )例如默认情况生成q-timeline q-timeline--dense q-timeline--dense--right。对应的样式在 QTimeline.sass 中分块实现--dense--right/left、--comfortable--right/left、--loose。其中loose模式把圆点定位在水平 50% 处left: 50%; margin-left: -7.15px条目内容与副标题各占 50% 宽度并左右浮动float: left/right、width: 50%这正是双侧交替排布效果的实现基础。QTimeline 组件 API 详解依据组件定义文件 QTimeline.json 与源码QTimeline提供如下 propsProp类型默认值可选值说明colorStringprimary任意 Quasar 调色板颜色时间线圆点的主题色作为条目颜色的回退值sideStringrightleft/rightdense 与 comfortable 布局下条目所在侧loose 布局下被各条目自身的sideprop 覆盖layoutStringdensedense/comfortable/loose时间线布局模式darkBooleanfalse—强制深色模式复用 Quasar 统一的 dark 复合属性插槽方面仅有一个default插槽用于放置QTimelineEntry列表。在源码实现中QTimeline通过provide(timelineKey, props)把自身 props 提供给所有子孙条目QTimeline.js条目内部再通过inject(timelineKey, emptyRenderFn)获取从而实现条目默认继承容器颜色、布局感知的协作机制QTimelineEntry.js若条目脱离容器单独使用控制台会输出QTimelineEntry needs to be child of QTimeline并返回空渲染。容器最终渲染为原生ulh(ul, { class: classes.value }, ...)这为后续无障碍列表语义奠定了基础。QTimelineEntry 组件 API 详解依据 QTimelineEntry.json 与源码条目提供以下 propsProp类型默认值说明headingBooleanfalse将条目定义为标题型条目时间轴分段节点tagStringh3仅对heading型条目生效指定标题渲染标签如h1、h4sideStringright条目所在侧仅当 QTimeline 为loose布局时生效iconString—圆点处的图标名与avatar同时使用时图标优先avatarString—圆点处的头像图片 URL支持transformAssetUrls可指向 public、assets 或任意 URLcolorString—覆盖容器color的条目级颜色titleString—条目标题使用title插槽时被覆盖subtitleString—条目副标题使用subtitle插槽时被覆盖bodyString—条目正文与默认插槽二选一插槽共三个default条目正文内容title可选标题插槽使用时覆盖titlepropsubtitle可选副标题插槽使用时覆盖subtitleprop。源码中的实现细节值得注意圆点内容优先级icon存在时渲染QIcon否则avatar存在时渲染img classq-timeline__dot-img两者皆无则渲染空心圆点QTimelineEntry.js标题固定渲染为h6正文默认插槽与bodyprop 会被合并进内容区body在前、插槽内容在后QTimelineEntry.js条目最终渲染为li保证作为ul容器的合法子元素源码注释明确说明QTimeline 是原生 ul只允许列表项作为子元素在comfortable布局且容器sideleft时条目内部会自动对内容顺序取反reverse计算属性以保持副标题与标题的正确左右排布QTimelineEntry.js。基础用法组合 prop 与默认插槽最典型的基础写法如下出自官方示例 Basic.vue容器设置color用heading型条目做分段标题普通条目用title/subtitleprop 配默认插槽填充正文并以icon/avatar装饰圆点q-timeline colorsecondary q-timeline-entry heading Timeline heading /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 div Lorem ipsum dolor sit amet, consectetur adipisicing elit... /div /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 21, 1986 icondelete div.../div /q-timeline-entry q-timeline-entry heading November, 2017 /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 avatarhttps://cdn.quasar.dev/img/avatar2.jpg div.../div /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 colororange icondone_all div.../div /q-timeline-entry /q-timeline注意这里体现了颜色继承链条目未显式设置color时圆点取容器色dotClass计算属性中props.color || $timeline.color而最后一条显式传入colororange则覆盖容器色。仅用 props 的简洁写法当正文是纯文本、无需复杂结构时可以完全不写默认插槽全部通过 props 声明PropsOnly.vue。这种写法尤其适合由数据驱动渲染的时间线q-timeline colorsecondary q-timeline-entry heading bodyTimeline heading / q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 avatarhttps://cdn.quasar.dev/img/avatar3.jpg :bodybody / q-timeline-entry titleEvent Title subtitleFebruary 21, 1986 icondelete :bodybody / q-timeline-entry heading bodyNovember, 2017 / q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 colororange icondone_all :bodybody / /q-timeline script setup const body Lorem ipsum dolor sit amet, consectetur adipisicing elit... /script结合源码可见body与默认插槽在渲染时会被合并进.q-timeline__content区域因此prop 驱动 插槽补充可以混合使用。仅用插槽的写法反之也可以完全不用title/subtitle/bodyprops全部通过命名插槽注入SlotsOnly.vue。这种方式适合标题/副标题需要富文本如内嵌链接、图标、HTML 结构的场景q-timeline colorsecondary q-timeline-entry heading Timeline heading /q-timeline-entry q-timeline-entry icondelete template #title Event Title /template template #subtitle February 21, 1986 /template div Lorem ipsum dolor sit amet, consectetur adipisicing elit... /div /q-timeline-entry q-timeline-entry heading November, 2017 /q-timeline-entry q-timeline-entry avatarhttps://cdn.quasar.dev/img/avatar5.jpg template #title Event Title /template template #subtitle February 22, 1986 /template div.../div /q-timeline-entry q-timeline-entry colororange icondone_all template #title Event Title /template template #subtitle February 22, 1986 /template div.../div /q-timeline-entry /q-timeline源码中插槽与 prop 的关系由hSlot(slots.title, [props.title])这类调用实现——插槽存在时优先渲染插槽内容否则回退到 prop 值因此 props 与 slots 可以按需混搭。深色模式Dark designQTimeline 支持通过darkprop 强制深色显示Dark.vue通常搭配深色背景容器使用div classq-px-lg q-py-md bg-grey-9 text-white q-timeline dark colorsecondary q-timeline-entry headingTimeline heading/q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 avatarhttps://cdn.quasar.dev/img/avatar5.jpg div.../div /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 21, 1986 icondelete div.../div /q-timeline-entry /q-timeline /div实现层面容器通过useDark组合式函数useDark(props, $q)见 QTimeline.js感知显式darkprop 与全局深色模式命中后追加q-timeline--dark类样式文件为其将文字设为白色并把副标题透明度降到 0.7QTimeline.sass。布局切换与条目侧边选择官方文档明确给出一个WARNINGQTimelineEntry的sideprop仅在 QTimeline 处于loose布局时才会生效。在dense与comfortable布局下所有条目的方位完全由容器级side决定。这一点在源码中得到印证——条目的sideprop 只参与生成q-timeline__entry--left/right类而该类只在loose布局的样式规则中被消费QTimeline.sass。官方示例 Layouts.vue 演示了通过q-option-group实时切换布局与侧边的完整交互template div classq-pa-lg div classrow q-gutter-md q-mb-lg q-option-group typeradio dense v-modellayout :options[ { label: Dense layout, value: dense }, { label: Comfortable layout, value: comfortable }, { label: Loose layout, value: loose } ] / q-option-group typeradio dense v-modelside :disablelayout loose :options[ { label: Content on right, value: right }, { label: Content on left, value: left } ] / /div q-timeline :layoutlayout :sideside colorsecondary q-timeline-entry headingTimeline heading/q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 sideleft div.../div /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 21, 1986 sideright icondelete div.../div /q-timeline-entry q-timeline-entry headingNovember, 2017/q-timeline-entry !-- 更多 sideleft / sideright 条目... -- /q-timeline /div /template script setup import { ref } from vue const layout ref(dense) const side ref(right) /script值得注意的细节示例在layout loose时禁用了容器侧边选择器:disablelayout loose因为 loose 布局下容器side会被条目级side覆盖。同时该示例向读者展示了三种布局的典型形态差异dense 是单侧紧凑列表comfortable 把副标题挤到对侧形成两栏loose 则是左右两侧交替、标题居中的经典时间轴。响应式布局切换由于layout是普通的响应式 prop可以结合 Quasar 的$q.screen全局对象按窗口尺寸动态切换三种布局官方 TIP 说明示例正是用$q.screen检测窗口大小变化以观察全部 3 种布局。完整实现见 Responsive.vueq-timeline :layoutlayout colorsecondary q-timeline-entry heading Timeline heading br / ({{ $q.screen.lt.sm ? Dense : $q.screen.lt.md ? Comfortable : Loose }} layout) /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 22, 1986 sideleft div.../div /q-timeline-entry q-timeline-entry titleEvent Title subtitleFebruary 21, 1986 sideright icondelete div.../div /q-timeline-entry /q-timeline script setup import { useQuasar } from quasar import { computed } from vue const $q useQuasar() const layout computed(() $q.screen.lt.sm ? dense : $q.screen.lt.md ? comfortable : loose ) /script该方案体现的断点策略非常实用小屏lt.sm用单侧 dense 节省横向空间中屏lt.md用 comfortable 兼顾信息密度大屏用 loose 展示完整双侧时间轴。由于条目级side在 loose 下生效示例中预置的sideleft/right会在切换到大屏时自动形成交错布局——这正是响应式时间线的最佳实践模式。无障碍Accessibility自 v2.25 起QTimeline 针对可访问性做了原生语义化处理官方文档给出了三条明确的注意事项列表语义QTimeline渲染为原生ul每个条目是li因此屏幕阅读器会将整条时间线识别为列表结构标题层级条目标题固定渲染为h6元素无论时间线在页面标题大纲中处于什么位置唯一例外是heading型条目——它通过tagprop 自定义标题级别默认h3。因此在使用时需根据文档大纲手工选择合适的tag避免标题层级跳跃头像 alt 缺失通过avatarprop 渲染的img不带alt属性对于关键头像应改由插槽自建带alt的图片结构或通过icon替代。这些行为均有源码与测试支撑heading条目渲染为li div div tagh3默认的结构QTimelineEntry.js普通条目标题固定h6QTimelineEntry.js测试 QTimelineEntry.test.js 验证了 heading 条目必须是li元素、tagprop 能改变标题标签名。源码与测试佐证从 API 到渲染为了让读者对组件行为有确定性的把握这里汇总仓库内的关键证据链API 契约QTimeline.json 与 QTimelineEntry.json 是官方 API 定义的机器可读来源上文表格全部字段均出自这两份文件容器实现QTimeline.js 通过provide向条目下发 props并生成q-timeline--{layout}--{side}类条目实现QTimelineEntry.js 通过inject读取容器配置处理 icon/avatar 优先级、reverse 顺序、heading 结构样式实现QTimeline.sass 完整定义三种布局的排版规则包括 loose 的居中圆点left: 50%与 50/50 双栏布局自动化测试QTimeline.test.js 与 QTimelineEntry.test.js 使用 Vitest Vue Test Utils 验证了color类名注入text-secondary、side类名q-timeline--dense--left/right、layout类名、heading 的LI语义及tag渲染等行为可作为你修改或扩展时间线时的回归保障。小结QTimeline 是 Quasar 中高度声明式的时间线组件QTimeline管布局与主题、QTimelineEntry管内容props 与插槽双通道可互换loose布局支持条目级左右交错配合$q.screen还能实现小屏单侧、大屏交错的响应式方案而原生ul/li语义则为无障碍应用提供了坚实底座。动手实践时可直接在 playground 的 timeline.vue 页面中修改代码实时预览并对照 Basic.vue、PropsOnly.vue、SlotsOnly.vue、Layouts.vue、Responsive.vue、Dark.vue 六个官方示例逐项验证。赞分享前端UI组件跨平台【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址https://gitcode.com/gh_mirrors/qu/quasar点击查看免费下载相关推荐Quasar QBanner 组件完全指南属性、插槽、无障碍与实践用法Quasar QBanner 组件完全指南属性、插槽、无障碍与实践用法 QBanner 是 Quasar Framework 内置的横幅Banner组件前端UI组件跨平台Quasar QAvatar 组件完全指南尺寸、字体、形状与无障碍实践Quasar QAvatar 组件完全指南尺寸、字体、形状与无障碍实践 QAvatar 是 Quasar Framework 中用于在圆形默认、方形或圆角前端UI组件跨平台Quasar QRange 组件实战指南区间选择、步进、标记与无障碍支持Quasar QRange 组件实战指南区间选择、步进、标记与无障碍支持 QRange 是 Quasar Framework 中用于让用户在一个最小值和最大值前端UI组件跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考