三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

基于Element Plus封装季度选择器：从业务需求到组件实现

发布时间：2026/8/6 6:50:50 三亩地 编程学习日记
基于Element Plus封装季度选择器：从业务需求到组件实现

1. 项目缘起：为什么需要封装一个季度选择器？

在后台管理系统的开发中，日期选择是最高频的操作之一。Element Plus 作为 Vue 3 生态中最主流的 UI 组件库，其el-date-picker组件功能强大，覆盖了年、月、周、日、日期范围等多种选择模式。然而，当产品经理拿着原型图，指着“请选择季度”的需求时，我们往往会发现，原生的组件库里并没有一个开箱即用的el-quarter-picker。

这其实是一个典型的业务场景倒逼组件封装的需求。在财务分析、销售报表、季度考核等模块中，按季度筛选和统计数据是刚需。虽然我们可以通过组合年选择器和季度下拉框来实现，但这破坏了交互的一致性，也增加了用户的操作步骤。一个独立的、与el-date-picker风格和 API 保持一致的季度选择器，能显著提升用户体验和开发效率。

因此，封装一个el-quart-picker（这里我们遵循 Element Plus 的命名习惯，使用el-前缀和-picker后缀）并非炫技，而是解决实际业务痛点。本文将手把手带你从零开始，封装一个功能完整、易于维护的季度选择器组件，并深入探讨封装过程中的设计决策、技术细节和避坑指南。

2. 核心设计：如何定义组件的形态与API？

在动手写代码之前，明确组件的设计目标是关键。一个好的封装，应该让使用者感觉它就像是 Element Plus 原生的一部分。

2.1 形态与交互设计

首先，我们需要确定这个选择器长什么样。参考el-date-picker，季度选择器最直观的形态应该是一个输入框，点击后弹出一个面板，面板上可以快速选择年份和季度。这比两个独立的下拉框（一个选年，一个选季）要优雅得多。

交互流程可以设计为：

  1. 用户点击输入框，弹出选择面板。
  2. 面板顶部显示当前选中的年份，并提供“前一年”、“后一年”的切换按钮。
  3. 面板主体部分以网格形式展示四个季度（Q1, Q2, Q3, Q4）。
  4. 用户点击某个季度，该季度高亮，面板关闭，输入框显示格式化后的季度值（如“2024-Q1”）。

2.2 属性（Props）设计

组件的属性是其与外部通信的接口。我们的设计应尽可能与el-date-picker对齐，降低使用者的学习成本。以下是一些核心属性：

  • model-value / v-model：这是 Vue 组件的“黄金标准”，用于双向绑定选中的值。值类型应该是什么？一个日期字符串（如 “2024-01-01” 代表第一季度）？还是一个数组[year, quarter]？为了与后端接口和日期处理库（如 dayjs）更好地兼容，我推荐使用字符串格式YYYY-Q[1-4]，例如"2024-Q1"。这样既清晰，也便于序列化。
  • placeholder：输入框的占位符文本。
  • disabled：是否禁用选择器。
  • clearable：是否显示清空按钮。
  • format：显示在输入框中的日期格式。默认可以是YYYY-[Q]Q，显示为 “2024-Q1”。高级用户可能希望自定义，比如显示为 “2024年第一季度”。
  • value-format：绑定值（model-value）的格式。通常我们保持与内部值一致（YYYY-Q[1-4]），但提供此选项可以增加灵活性，例如允许绑定一个 Date 对象（虽然不推荐用于季度）。
  • size：尺寸，与 Element Plus 其他表单组件保持一致（large, default, small）。

2.3 事件（Events）与插槽（Slots）设计

  • 事件：至少需要提供change事件，当选中值发生变化时触发。事件回调参数应包含新的值(newValue)和旧的值(oldValue)。为了更精细的控制，还可以提供focus、blur、clear等事件。
  • 插槽：为了最大化灵活性，可以暴露几个关键插槽：
    • default：通常不需要，因为输入框内容由组件内部决定。
    • prefix：输入框前置内容插槽，可以放一个日历图标。
    • range-separator：虽然季度选择器是单值，但为了 API 一致性，可以预留（非必需）。

设计原则是：80%的常用场景开箱即用，20%的特殊需求可通过配置和插槽满足。

3. 技术实现：从零构建el-quart-picker

明确了设计，我们就可以开始编码了。我们将使用 Vue 3 的<script setup>语法和 TypeScript，确保代码的现代性和类型安全。

3.1 项目结构与组件骨架

首先，在你的组件目录下（例如src/components/QuartPicker）创建以下文件：

src/components/QuartPicker/ ├── index.ts // 组件导出文件 ├── QuartPicker.vue // 主组件文件 └── QuartPickerPanel.vue // 弹出的选择面板组件

QuartPicker.vue骨架：这个文件是选择器的主体，负责输入框的渲染、面板的弹出/关闭、以及值的双向绑定管理。

<template> <div class="el-quart-picker"> <!-- 使用el-input来保持样式一致，并监听其事件 --> <el-input ref="inputRef" :model-value="displayValue" :placeholder="placeholder" :size="size" :disabled="disabled" :clearable="clearable" @focus="handleFocus" @blur="handleBlur" @input="handleInput" @clear="handleClear" > <template #prefix> <slot name="prefix"> <el-icon><calendar /></el-icon> </slot> </template> </el-input> <!-- 弹出的选择面板 --> <QuartPickerPanel v-if="panelVisible" ref="panelRef" v-model:current-date="innerDate" :model-value="innerValue" @pick="handlePick" @mousedown.stop /> </div> </template> <script setup lang="ts"> import { ref, computed, watch, nextTick } from 'vue' import { ElInput, ElIcon } from 'element-plus' import { Calendar } from '@element-plus/icons-vue' import QuartPickerPanel from './QuartPickerPanel.vue' import dayjs from 'dayjs' // 引入日期库 interface Props { modelValue?: string // 格式如 '2024-Q1' placeholder?: string disabled?: boolean clearable?: boolean size?: 'large' | 'default' | 'small' format?: string // 显示格式，默认 'YYYY-[Q]Q' valueFormat?: string // 值格式，默认同 modelValue } const props = withDefaults(defineProps<Props>(), { placeholder: '请选择季度', clearable: true, size: 'default', format: 'YYYY-[Q]Q', valueFormat: '', }) const emit = defineEmits<{ 'update:modelValue': [value: string | undefined] 'change': [value: string | undefined, oldValue: string | undefined] 'focus': [event: FocusEvent] 'blur': [event: FocusEvent] 'clear': [] }>() // 核心响应式数据 const inputRef = ref<InstanceType<typeof ElInput>>() const panelRef = ref<InstanceType<typeof QuartPickerPanel>>() const panelVisible = ref(false) const innerDate = ref(dayjs()) // 用于面板内部维护的当前“视图日期”，初始化为今天或modelValue对应的日期 const innerValue = ref<string | undefined>(props.modelValue) // 内部维护的实际值 // 显示在输入框中的值 const displayValue = computed(() => { if (!innerValue.value) return '' const [year, quarter] = parseQuarterString(innerValue.value) const date = dayjs(`${year}-${(quarter - 1) * 3 + 1}-01`) // 构造一个该季度第一天的日期 return date.format(props.format) }) // 监听外部传入的 modelValue 变化 watch(() => props.modelValue, (newVal) => { if (newVal !== innerValue.value) { innerValue.value = newVal updateInnerDateFromValue(newVal) } }, { immediate: true }) // 解析 '2024-Q1' 这样的字符串 function parseQuarterString(val: string): [number, number] { const match = val.match(/^(\d{4})-Q([1-4])$/) if (!match) { // 可以提供一个默认值或抛出错误，这里返回当前季度 const now = dayjs() return [now.year(), Math.floor(now.month() / 3) + 1] } return [parseInt(match[1], 10), parseInt(match[2], 10)] } // 根据值更新内部视图日期 function updateInnerDateFromValue(val: string | undefined) { if (val) { const [year] = parseQuarterString(val) innerDate.value = dayjs(`${year}-01-01`) // 设置为该年1月1日，面板会以此年份为基础 } else { innerDate.value = dayjs() // 清空时，面板显示当前年份 } } // 事件处理函数 function handleFocus(event: FocusEvent) { panelVisible.value = true emit('focus', event) nextTick(() => { // 面板显示后，可以做一些聚焦处理，例如让面板获取焦点以备键盘操作 }) } function handleBlur(event: FocusEvent) { // 需要延时判断，因为点击面板选项时，会先触发input的blur，再触发面板的click setTimeout(() => { if (!panelRef.value?.isFocusInsidePanel?.()) { // 假设面板有一个方法判断内部焦点 panelVisible.value = false emit('blur', event) } }, 100) } function handlePick(value: string) { const oldValue = innerValue.value innerValue.value = value panelVisible.value = false emit('update:modelValue', value) emit('change', value, oldValue) // 让输入框重新获取焦点（可选，提升体验） nextTick(() => inputRef.value?.focus()) } function handleClear() { const oldValue = innerValue.value innerValue.value = undefined emit('update:modelValue', undefined) emit('change', undefined, oldValue) emit('clear') } function handleInput(value: string) { // 这里可以处理手动输入的情况，但季度选择器通常不建议手动输入，可以忽略或做复杂解析 // 简单实现：忽略手动输入，或者尝试解析 console.log('Manual input:', value) } </script> <style scoped> .el-quart-picker { position: relative; display: inline-block; width: 100%; } </style>

3.2 核心面板组件 QuartPickerPanel.vue

面板组件是交互的核心，它负责渲染年份切换和季度网格。

<template> <div ref="panelRef" class="el-quart-picker-panel" :class="`is-${size}`" @keydown="handleKeydown" tabindex="-1" > <div class="el-quart-picker-panel__header"> <button type="button" class="el-picker-panel__icon-btn el-icon-d-arrow-left" @click="changeYear(-1)" > <el-icon><ArrowLeft /></el-icon> </button> <span class="el-quart-picker-panel__header-label">{{ currentDate.year() }} 年</span> <button type="button" class="el-picker-panel__icon-btn el-icon-d-arrow-right" @click="changeYear(1)" > <el-icon><ArrowRight /></el-icon> </button> </div> <div class="el-quart-picker-panel__content"> <div v-for="quarter in 4" :key="quarter" class="el-quart-picker-panel__quarter" :class="{ 'is-selected': isSelected(quarter), 'is-current': isCurrentQuarter(quarter), 'is-disabled': isQuarterDisabled(quarter) }" @click="selectQuarter(quarter)" > Q{{ quarter }} </div> </div> </div> </template> <script setup lang="ts"> import { ref, computed, onMounted } from 'vue' import { ElIcon } from 'element-plus' import { ArrowLeft, ArrowRight } from '@element-plus/icons-vue' import dayjs from 'dayjs' interface Props { modelValue?: string currentDate: dayjs.Dayjs // 由父组件传入，控制面板显示的年份 disabledDate?: (date: dayjs.Dayjs) => boolean // 可选：禁用特定季度的函数 size?: 'large' | 'default' | 'small' } const props = withDefaults(defineProps<Props>(), { size: 'default', }) const emit = defineEmits<{ 'update:currentDate': [date: dayjs.Dayjs] 'pick': [value: string] }>() const panelRef = ref<HTMLDivElement>() const innerCurrentDate = ref(props.currentDate) // 计算当前选中的季度（从modelValue解析） const selectedQuarter = computed(() => { if (!props.modelValue) return null const match = props.modelValue.match(/^(\d{4})-Q([1-4])$/) if (match && parseInt(match[1], 10) === innerCurrentDate.value.year()) { return parseInt(match[2], 10) } return null }) // 判断某个季度是否被选中 function isSelected(quarter: number) { return selectedQuarter.value === quarter } // 判断某个季度是否是当前日期所在的季度（用于高亮“今天”） function isCurrentQuarter(quarter: number) { const now = dayjs() return ( innerCurrentDate.value.year() === now.year() && quarter === Math.floor(now.month() / 3) + 1 ) } // 判断季度是否被禁用（需要结合disabledDate函数） function isQuarterDisabled(quarter: number) { if (!props.disabledDate) return false // 构造该季度的第一天和最后一天进行判断 const startOfQuarter = innerCurrentDate.value.month((quarter - 1) * 3).startOf('month') const endOfQuarter = startOfQuarter.endOf('month').add(2, 'month') // 这里是一个简化判断：如果该季度的任何一天被禁用，则整个季度禁用。 // 更精确的实现可能需要遍历或检查关键日期，这里为了性能，可以只检查首日。 return props.disabledDate(startOfQuarter) } // 选择季度 function selectQuarter(quarter: number) { if (isQuarterDisabled(quarter)) return const value = `${innerCurrentDate.value.year()}-Q${quarter}` emit('pick', value) } // 切换年份 function changeYear(step: number) { const newDate = innerCurrentDate.value.add(step, 'year') innerCurrentDate.value = newDate emit('update:currentDate', newDate) } // 简单的键盘导航支持（可选，但能大幅提升体验） function handleKeydown(event: KeyboardEvent) { const actions: Record<string, () => void> = { 'ArrowUp': () => changeYear(-1), 'ArrowDown': () => changeYear(1), 'Escape': () => emit('pick', props.modelValue || ''), // 取消，关闭面板 } const action = actions[event.key] if (action) { event.preventDefault() action() } } // 暴露一个方法给父组件，用于判断焦点是否在面板内 function isFocusInsidePanel() { return panelRef.value?.contains(document.activeElement) } defineExpose({ isFocusInsidePanel }) // 监听父组件传入的currentDate变化 watch(() => props.currentDate, (newVal) => { innerCurrentDate.value = newVal }) </script> <style scoped> .el-quart-picker-panel { position: absolute; top: 100%; left: 0; z-index: 2000; background: var(--el-bg-color-overlay); border: 1px solid var(--el-border-color-light); border-radius: var(--el-border-radius-base); box-shadow: var(--el-box-shadow-light); margin-top: 4px; min-width: 220px; user-select: none; } .el-quart-picker-panel__header { display: flex; justify-content: space-between; align-items: center; padding: 12px; border-bottom: 1px solid var(--el-border-color-light); } .el-quart-picker-panel__header-label { font-weight: 600; color: var(--el-text-color-primary); } .el-picker-panel__icon-btn { border: none; background: transparent; cursor: pointer; color: var(--el-text-color-secondary); font-size: 12px; padding: 4px; border-radius: var(--el-border-radius-base); } .el-picker-panel__icon-btn:hover { background-color: var(--el-fill-color-light); } .el-quart-picker-panel__content { display: grid; grid-template-columns: repeat(2, 1fr); gap: 8px; padding: 12px; } .el-quart-picker-panel__quarter { height: 40px; display: flex; align-items: center; justify-content: center; border-radius: var(--el-border-radius-base); cursor: pointer; color: var(--el-text-color-regular); font-size: 14px; } .el-quart-picker-panel__quarter:hover { background-color: var(--el-fill-color-light); } .el-quart-picker-panel__quarter.is-selected { background-color: var(--el-color-primary); color: var(--el-color-white); } .el-quart-picker-panel__quarter.is-current { border: 1px solid var(--el-color-primary); } .el-quart-picker-panel__quarter.is-disabled { cursor: not-allowed; color: var(--el-text-color-placeholder); background-color: var(--el-fill-color-lighter); } .el-quart-picker-panel__quarter.is-disabled:hover { background-color: var(--el-fill-color-lighter); } </style>

3.3 组件注册与导出

最后，在index.ts中统一导出组件，方便全局注册或按需引入。

// src/components/QuartPicker/index.ts import { App } from 'vue' import QuartPicker from './QuartPicker.vue' // 为组件添加 install 方法，使其可以通过 app.use() 全局注册 QuartPicker.install = (app: App) => { app.component(QuartPicker.name || 'ElQuartPicker', QuartPicker) } export default QuartPicker export { QuartPicker as ElQuartPicker }

在你的主入口文件或某个模块中，可以这样全局注册：

// main.ts 或 plugins/element-plus.ts import { ElQuartPicker } from '@/components/QuartPicker' const app = createApp(App) app.component('ElQuartPicker', ElQuartPicker)

或者，在单文件中按需引入使用：

<template> <el-form> <el-form-item label="报告季度"> <el-quart-picker v-model="selectedQuarter" /> </el-form-item> </el-form> </template> <script setup lang="ts"> import { ref } from 'vue' import { ElQuartPicker } from '@/components/QuartPicker' // 或使用全局注册的 const selectedQuarter = ref('2024-Q2') </script>

4. 进阶优化与深度避坑指南

一个基础组件完成后，我们需要考虑更多生产环境下的细节，这些才是体现封装功力的地方。

4.1 键盘导航与无障碍访问

上面的面板实现了简单的键盘事件，但一个完整的键盘导航应该更强大。可以参考el-date-picker的实现：

  • Tab 键：应在输入框、面板的年份切换按钮、四个季度单元格之间形成焦点循环。
  • 方向键：上下键切换年份，左右键在季度间移动焦点（虽然只有4个，但逻辑要完整）。
  • Enter/Space 键：确认选择当前焦点的季度。
  • 为焦点元素添加明显的:focus-visible样式。

这需要更精细的焦点管理，可能需要在面板内部维护一个currentFocusIndex，并监听所有可交互元素的keydown事件。这是一个工作量不小但体验提升巨大的优化点。

4.2 禁用日期（季度）功能

我们的面板预留了disabledDate属性，但实现isQuarterDisabled时做了简化。一个严谨的季度禁用逻辑应该是什么？

季度本质上是三个月的集合。禁用一个季度，通常意味着这个季度的任何一天都不可选。因此，更合理的实现是：

  1. 接收一个disabledDate函数，该函数判断一个具体的dayjs日期是否禁用。
  2. 在isQuarterDisabled中，构造该季度的三个月份的第一天（或第一天、中间一天、最后一天），只要其中任何一天被disabledDate返回true，则整个季度禁用。
function isQuarterDisabled(quarter: number) { if (!props.disabledDate) return false const year = innerCurrentDate.value.year() const startMonth = (quarter - 1) * 3 // 0, 3, 6, 9 // 检查该季度三个月的首日 for (let month = startMonth; month < startMonth + 3; month++) { const firstDayOfMonth = dayjs(`${year}-${month + 1}-01`) if (props.disabledDate(firstDayOfMonth)) { return true } } return false }

4.3 面板定位与滚动问题

我们的面板使用position: absolute; top: 100%;定位。这在简单布局下没问题，但如果选择器位于页面底部或可滚动容器内，面板可能会被遮挡或显示不全。

解决方案：需要使用一个更智能的定位工具。Element Plus 内部使用了@popperjs/core来处理这类弹出层的定位。我们可以借鉴这一思路：

  1. 安装@popperjs/core。
  2. 在QuartPicker.vue中，使用createPopper函数，将面板作为popper元素，输入框作为reference元素。
  3. 配置placement（如bottom-start）、modifiers（如preventOverflow,offset等）。

这能自动处理边界情况，确保面板始终在可视区域内。这是构建健壮 UI 组件的关键一步。

4.4 国际化与本地化

我们的面板头部显示的是中文“年”，季度是“Q1”。如果要支持多语言呢？

解决方案：集成 Vue I18n。Element Plus 本身支持国际化，我们的组件最好也能融入这个体系。

  1. 将面板中的硬编码文本（如“年”、“Q1”）改为通过注入的t函数获取。
  2. 提供i18n属性或从全局配置中读取。
  3. 季度缩写可能因语言而异（虽然“Q”比较通用），但“年”字肯定需要翻译。
<!-- 在QuartPickerPanel.vue中 --> <span class="el-quart-picker-panel__header-label">{{ currentDate.year() }} {{ t('el.datepicker.year') }}</span>

这要求组件能访问到 Vue 应用的 i18n 上下文，可以通过useI18n()（如果使用vue-i18n）或从ElConfigProvider的上下文获取。

4.5 性能优化：避免不必要的渲染

当modelValue或currentDate变化时，整个面板会重新渲染。对于简单的季度面板，这问题不大。但如果disabledDate是一个复杂函数，每次渲染都计算四个季度的禁用状态可能会成为性能瓶颈（特别是在快速切换年份时）。

优化点：使用computed属性或memoization（记忆化）技术来缓存季度禁用状态的计算结果。

// 使用computed缓存当前年份下所有季度的禁用状态 const quarterDisabledStatus = computed(() => { return [1, 2, 3, 4].map(quarter => isQuarterDisabled(quarter)) }) // 在模板中，使用 quarterDisabledStatus.value[quarter-1] 来判断

4.6 样式隔离与主题适配

我们的组件样式使用了 Element Plus 的 CSS 变量（如--el-color-primary）。这很好，确保了与项目主题的一致性。但需要注意：

  • scoped样式可能会影响子组件（如el-input）的深度选择。如果需要对el-input的内部元素做微调，可能需要使用:deep()选择器。
  • 面板的z-index需要设置得比大多数页面元素高（这里用了2000），但要避免与项目中其他可能更高的z-index冲突。可以考虑从 Element Plus 的配置中读取一个基础z-index值。

5. 测试与集成：确保组件稳定可靠

组件写完不是终点，充分的测试才能保证其可靠性。

5.1 单元测试

使用 Vitest 或 Jest 为组件编写单元测试，覆盖核心功能：

  • 渲染测试：传入不同的props，检查 DOM 结构是否正确。
  • 交互测试：模拟点击年份按钮、点击季度单元格，检查v-model的值是否正确更新，change事件是否触发。
  • 边界测试：测试disabled状态、clearable状态、空值情况、非法值传入等情况。

5.2 集成与使用示例

在 Storybook 或类似工具中创建组件故事，展示不同状态下的组件形态，方便团队其他成员查阅和使用。提供典型的使用代码片段：

<template> <div> <!-- 基础用法 --> <el-quart-picker v-model="quarter1" /> <!-- 带禁用日期 --> <el-quart-picker v-model="quarter2" :disabled-date="(date) => date.isBefore(dayjs(), 'quarter')" placeholder="只能选择当前及未来季度" /> <!-- 自定义格式 --> <el-quart-picker v-model="quarter3" format="YYYY年 第[Q]季度" value-format="YYYY-Q" /> <!-- 禁用状态 --> <el-quart-picker v-model="quarter4" disabled /> <!-- 配合表单验证 --> <el-form :model="form" :rules="rules"> <el-form-item label="财年季度" prop="fiscalQuarter"> <el-quart-picker v-model="form.fiscalQuarter" /> </el-form-item> </el-form> </div> </template>

封装一个el-quart-picker的过程，远不止是将四个按钮塞进一个弹出框那么简单。它涉及对现有组件库设计哲学的深刻理解、对用户交互细节的周密考量、对边界情况的全面处理，以及对代码可维护性和性能的持续优化。从确定 API 设计到处理键盘导航，从实现国际化到编写单元测试，每一步都需要开发者以产品思维和工匠精神去打磨。当你最终将这个组件集成到项目中，看到产品经理和用户流畅地使用它时，你会感受到这种深度封装带来的巨大价值——它不仅仅是一个工具，更是你对前端工程化理解的一次完整实践。

编程学习 学习日记 实战经验
← 返回列表