vue2-monthrange

一个基于 Vue 2 的月份范围选择器组件。

功能特性

• 📅 月份范围选择（开始月份 - 结束月份）
• 🔢 可选最小/最大日期限制
• 🔄 前后年份切换
• ❌ 一键清空
• 📏 选择范围限制（月数）
• 🚫 支持禁用状态
• 🎨 高度可定制（占位符、显示格式、分隔符、颜色主题等）
• 🌐 支持自定义月份/年份文本（可隐藏"月""年"）
• 📦 支持 v-model 双向绑定

安装

npm install vue2-monthrange

快速上手

方式一：全局注册

// main.js
import Vue from 'vue'
import MonthRangePicker from 'vue2-monthrange'
import 'vue2-monthrange/dist/vue2-monthrange.css'

Vue.use(MonthRangePicker)

<!-- 在组件中使用 -->
<template>
  <MonthRangePicker v-model="range" />
</template>

<script>
export default {
  data() {
    return { range: [] }
  }
}
</script>

方式二：局部导入

<template>
  <MonthRangePicker v-model="range" />
</template>

<script>
import MonthRangePicker from 'vue2-monthrange'
import 'vue2-monthrange/dist/vue2-monthrange.css'

export default {
  components: { MonthRangePicker },
  data() {
    return { range: [] }
  }
}
</script>

v-model 数据格式

v-model 绑定的数据为字符串数组，格式为 ['YYYY-MM', 'YYYY-MM']：

// 示例：2025年5月 至 2025年9月
range = ['2025-05', '2025-09']

// 未选择时
range = []

Props

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | value | Array | [] | 绑定值，通过 v-model 使用，格式 ['YYYY-MM', 'YYYY-MM'] | | size | String | '' | 输入框尺寸，可选 'mini' / 'small' / 'medium' / '' | | minDate | String | '' | 最早可选月份，格式 'YYYY-MM' | | maxDate | String | '' | 最晚可选月份，格式 'YYYY-MM' | | clearable | Boolean | true | 是否显示清空按钮 | | rangeLimit | Number | 12 | 范围限制（月数），超出会触发警告 | | onWarning | Function | window.alert | 自定义警告提示函数，参数为提示消息字符串 | | placeholder | String | '请选择月份范围' | 未选择时显示的占位符文字 | | yearSuffix | String | '年' | 下拉框中年份文字的后缀 | | showYearLabel | Boolean | true | 下拉框中是否显示当前年份文本 | | monthSuffix | String | '月' | 月份单元格中的后缀文字 | | showMonthLabel | Boolean | true | 月份单元格是否显示后缀文本 | | rangeSeparator | String | ' - ' | 开始与结束日期之间的分隔符 | | formatLabel | Function | null | 自定义显示格式函数，详见下方"自定义显示格式" | | disabled | Boolean | false | 是否禁用组件 | | placeholderColor | String | '#c0c4cc' | 占位符文字颜色 | | textColor | String | '#606266' | displayValue（已选日期文本）颜色 | | navBtnColor | String | '#606266' | 左右切换年份按钮颜色 | | yearLabelColor | String | '#303133' | 当前年份文本颜色 | | monthDefaultColor | String | '#606266' | 月份默认（未选中）文字色 | | monthHoverBgColor | String | '#f5f7fa' | 月份 hover 背景色 | | monthSelectedBgColor | String | '#409eff' | 月份选中（start/end）背景色 | | monthSelectedTextColor | String | '#ffffff' | 月份选中文字色 | | monthInRangeBgColor | String | '#ecf5ff' | 范围内月份背景色 | | monthInRangeTextColor | String | '#409eff' | 范围内月份文字色 | | monthRangeHoverBgColor | String | '#d9ecff' | 范围 hover 背景色 | | monthDisabledColor | String | '#c0c4cc' | 禁用月份文字色 | | monthDisabledBgColor | String | '#f5f7fa' | 禁用月份背景色 |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | input | 值变化时触发 | ['YYYY-MM', 'YYYY-MM'] 或 [] | | change | 值变化时触发 | ['YYYY-MM', 'YYYY-MM'] 或 [] |

使用示例

1. 基础用法

<template>
  <MonthRangePicker v-model="range" />
</template>

<script>
import MonthRangePicker from 'vue2-monthrange'
import 'vue2-monthrange/dist/vue2-monthrange.css'

export default {
  components: { MonthRangePicker },
  data() {
    return { range: [] }
  }
}
</script>

2. 带默认值

<template>
  <MonthRangePicker v-model="range" />
</template>

<script>
export default {
  data() {
    return {
      // 2025年3月 - 2025年8月
      range: ['2025-03', '2025-08']
    }
  }
}
</script>

3. 日期范围限制

<MonthRangePicker
  v-model="range"
  min-date="2024-01"
  max-date="2026-12"
  :range-limit="6"
/>

4. 不同尺寸

<MonthRangePicker v-model="range" size="mini" />
<MonthRangePicker v-model="range" size="small" />
<MonthRangePicker v-model="range" size="medium" />
<MonthRangePicker v-model="range" />

5. 自定义占位符

<MonthRangePicker
  v-model="range"
  placeholder="请选择起止月份"
/>

6. 自定义分隔符

<MonthRangePicker
  v-model="range"
  range-separator=" 至 "
/>

7. 自定义显示格式

<template>
  <MonthRangePicker
    v-model="range"
    :format-label="formatLabel"
  />
</template>

<script>
export default {
  data() {
    return { range: [] }
  },
  methods: {
    // 参数 start、end 为 { year, month }，month 为 0-11
    // 返回字符串显示在输入框中
    formatLabel(start, end) {
      const pad = (n) => (n < 9 ? `0${n + 1}` : `${n + 1}`)
      if (start && end) {
        return `${start.year}/${pad(start.month)} - ${end.year}/${pad(end.month)}`
      }
      return ''
    }
  }
}
</script>

8. 英文格式（不带"月""年"字）

<template>
  <MonthRangePicker
    v-model="range"
    placeholder="Select month range"
    year-suffix=""
    :show-year-label="true"
    :show-month-label="false"
    :format-label="formatEnglish"
  />
</template>

<script>
export default {
  data() {
    return { range: [] }
  },
  methods: {
    formatEnglish(start, end) {
      const months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
      if (start && end) {
        return `${months[start.month]} ${start.year} - ${months[end.month]} ${end.year}`
      }
      return ''
    }
  }
}
</script>

9. 自定义警告提示

<!-- 配合 ElementUI 的 $message -->
<MonthRangePicker
  v-model="range"
  :range-limit="6"
  :on-warning="(msg) => this.$message.warning(msg)"
/>

<!-- 或使用 alert -->
<MonthRangePicker
  v-model="range"
  :range-limit="6"
  :on-warning="(msg) => alert(msg)"
/>

10. 禁用状态

<!-- 禁用 -->
<MonthRangePicker v-model="range" disabled />

<!-- 动态控制 -->
<MonthRangePicker v-model="range" :disabled="!isEditable" />

11. 可清空

<MonthRangePicker v-model="range" clearable />

12. 自定义主题色（橙色系）

<MonthRangePicker
  v-model="range"
  text-color="#55380f"
  placeholder-color="#c9a66b"
  nav-btn-color="#55380f"
  year-label-color="#3a2508"
  month-default-color="#55380f"
  month-hover-bg-color="#fbeccd"
  month-selected-bg-color="#e6a23c"
  month-selected-text-color="#ffffff"
  month-in-range-bg-color="#faecd8"
  month-in-range-text-color="#e6a23c"
  month-range-hover-bg-color="#f5dab1"
/>

13. 自定义主题色（绿色系）

<MonthRangePicker
  v-model="range"
  text-color="#0f3d2e"
  placeholder-color="#6ab88b"
  nav-btn-color="#0f3d2e"
  year-label-color="#07291c"
  month-default-color="#0f3d2e"
  month-hover-bg-color="#d4f4e4"
  month-selected-bg-color="#28c76f"
  month-selected-text-color="#ffffff"
  month-in-range-bg-color="#dcfce7"
  month-in-range-text-color="#28c76f"
  month-range-hover-bg-color="#bbf7d0"
/>

14. 综合示例（橙色主题 + 自定义格式 + 范围限制）

<template>
  <MonthRangePicker
    v-model="range"
    placeholder="请选择报账月份区间"
    min-date="2024-01"
    max-date="2026-12"
    :range-limit="12"
    size="medium"
    range-separator=" 至 "
    :format-label="formatCustom"
    text-color="#55380f"
    placeholder-color="#c9a66b"
    nav-btn-color="#55380f"
    year-label-color="#3a2508"
    month-default-color="#55380f"
    month-hover-bg-color="#fbeccd"
    month-selected-bg-color="#e6a23c"
    month-selected-text-color="#ffffff"
    month-in-range-bg-color="#faecd8"
    month-in-range-text-color="#e6a23c"
    month-range-hover-bg-color="#f5dab1"
    :on-warning="showWarning"
  />
</template>

<script>
import MonthRangePicker from 'vue2-monthrange'
import 'vue2-monthrange/dist/vue2-monthrange.css'

export default {
  components: { MonthRangePicker },
  data() {
    return { range: [] }
  },
  methods: {
    formatCustom(start, end) {
      const pad = (n) => (n < 9 ? `0${n + 1}` : `${n + 1}`)
      if (start && end) {
        return `${start.year}/${pad(start.month)} - ${end.year}/${pad(end.month)}`
      }
      return ''
    },
    showWarning(msg) {
      alert(msg)
    }
  }
}
</script>

MIT