BizQuarterPicker 季度选择

同族周期选择件：季度粒度（本组件） / 周粒度（BizWeekPicker），API 形态一致按粒度取用。

季度选择器：年份翻页 + 四季格面板，单季度 / 季度区间（range）两种模式、快捷项（本季度 / 上季度 / 近四季度）、受控 v-model（值格式 'YYYY-Qn'，区间为 ['2026-Q1', '2026-Q3']，区间中间格高亮）、清空与回显定位年份。财务报表、经营分析、绩效考核等按季度统计的筛选条件——Element Plus 的 date-picker 无季度类型，本组件补齐该缺口。

基础选择

2026-Q3

当前值：2026-Q3

点选季度，再次点击已选季度可清空，值格式 'YYYY-Qn'。

<script setup lang="ts">
/** 场景：财务报表——单季度选择 */
import { ref } from 'vue'
import { BizQuarterPicker } from 'vue3-ep-biz-lib'

const quarter = ref('2026-Q3')
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <BizQuarterPicker v-model="quarter" />
    <span style="font-size: 13px; color: var(--el-text-color-secondary)">当前值：{{ quarter || '（空）' }}</span>
  </div>
</template>

显示代码

季度区间

2026-Q1 ~ 2026-Q3

跨度：3 个季度

mode="range" 依次选择起止（反向自动交换），区间中间格高亮。

<script setup lang="ts">
/** 场景：季度区间——对比分析（反向选择自动交换） */
import { computed, ref } from 'vue'
import { BizQuarterPicker, quarterToIndex } from 'vue3-ep-biz-lib'

const range = ref<['2026-Q1' | string, string]>(['2026-Q1', '2026-Q3'])

const span = computed(() => {
  const [a, b] = range.value ?? []
  if (a === undefined || b === undefined) return 0
  return quarterToIndex(b) - quarterToIndex(a) + 1
})
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <BizQuarterPicker v-model="range" mode="range" />
    <span style="font-size: 13px; color: var(--el-text-color-secondary)">跨度：{{ span }} 个季度</span>
  </div>
</template>

显示代码

快捷项

单季

区间

本季度 / 上季度 / 近四季度一键填充（报表默认筛选）。

<script setup lang="ts">
/** 场景：快捷项——一键填充常用季度 */
import { ref } from 'vue'
import { BizQuarterPicker } from 'vue3-ep-biz-lib'

const quarter = ref('')
const range = ref<[string, string]>(['', ''])
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <div style="display: flex; align-items: center; gap: 8px">
      <span style="font-size: 13px">单季</span>
      <BizQuarterPicker v-model="quarter" />
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <span style="font-size: 13px">区间</span>
      <BizQuarterPicker v-model="range" mode="range" />
    </div>
  </div>
</template>

显示代码

表单集成

指标

季度

2026-Q2

与 ElForm 集成（季度维度经营报表筛选），受控回显。

<script setup lang="ts">
/** 场景：报表筛选表单——ElForm 集成 */
import { reactive } from 'vue'
import { ElButton, ElForm, ElFormItem, ElInput, ElMessage } from 'element-plus'
import { BizQuarterPicker } from 'vue3-ep-biz-lib'

const form = reactive({ subject: '营业收入', quarter: '2026-Q2' })

const submit = (): void => {
  ElMessage.success(`查询 ${form.subject} · ${form.quarter}`)
}
</script>

<template>
  <div style="max-width: 480px">
    <ElForm label-width="80px" inline>
      <ElFormItem label="指标">
        <ElInput v-model="form.subject" style="width: 160px" />
      </ElFormItem>
      <ElFormItem label="季度">
        <BizQuarterPicker v-model="form.quarter" :shortcuts="false" />
      </ElFormItem>
      <ElFormItem>
        <ElButton type="primary" @click="submit">查询</ElButton>
      </ElFormItem>
    </ElForm>
  </div>
</template>

显示代码

禁用态

2025-Q4

2025-Q4 ~ 2026-Q2

disabled 禁用触发器（只读回显场景）。

<script setup lang="ts">
/** 场景：禁用态——回显不可改 */
import { BizQuarterPicker } from 'vue3-ep-biz-lib'
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <BizQuarterPicker model-value="2025-Q4" disabled />
    <BizQuarterPicker :model-value="['2025-Q4', '2026-Q2']" mode="range" disabled />
  </div>
</template>

显示代码

变化事件

请选择季度

点我试 quarterToIndex 工具

• 选择季度，事件日志在此显示

change 外抛当前值，配合 quarterToIndex / indexToQuarter 工具做区间计算。

<script setup lang="ts">
/** 场景：变化事件——change 外抛 + 工具函数区间计算 */
import { ref } from 'vue'
import { ElTag } from 'element-plus'
import { BizQuarterPicker, indexToQuarter, quarterToIndex } from 'vue3-ep-biz-lib'

const value = ref('')
const history = ref<string[]>([])

const onChange = (v: string | string[] | undefined): void => {
  history.value = [`change：${JSON.stringify(v)}`, ...history.value].slice(0, 5)
  value.value = v === undefined ? '' : Array.isArray(v) ? v.join(' ~ ') : v
}

/** 演示工具：当前季度前后各推一格 */
const nearby = ref('')
const roll = (): void => {
  const cur = quarterToIndex('2026-Q3')
  nearby.value = `${indexToQuarter(cur - 1)} ~ ${indexToQuarter(cur + 1)}`
}
</script>

<template>
  <div style="max-width: 520px">
    <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 10px">
      <BizQuarterPicker :model-value="undefined" @change="onChange" />
      <ElTag v-if="value !== ''" size="small">{{ value }}</ElTag>
      <ElTag size="small" type="info" @click="roll" style="cursor: pointer">点我试 quarterToIndex 工具</ElTag>
      <span v-if="nearby !== ''" style="font-size: 12px; color: var(--el-text-color-secondary)">{{ nearby }}</span>
    </div>
    <ul style="margin: 0; padding: 8px 12px; list-style: none; border: 1px solid var(--el-border-color-lighter); border-radius: 4px; font-size: 12px; color: var(--el-text-color-secondary)">
      <li v-if="history.length === 0" style="padding: 2px 0">选择季度，事件日志在此显示</li>
      <li v-for="(h, i) in history" :key="i" style="padding: 2px 0">{{ h }}</li>
    </ul>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
v-model	string | [string, string]	—	季度值（range 模式为区间二元组）
mode	'quarter' | 'range'	'quarter'	选择模式
shortcuts	boolean	true	显示快捷项
disabled	boolean	false	禁用
placeholder	string	'请选择季度'	占位

Events

事件名	参数	说明
change	(value)	选择 / 清空（含 undefined）

Expose

名称	类型	说明
toggle	() => void	打开 / 关闭面板
focus	() => void	聚焦触发器

TIP

工具函数 quarterToIndex / indexToQuarter 已随包导出，用于区间跨度计算（如 quarterToIndex(end) - quarterToIndex(start) + 1 个季度）。