如何正确使用van-calendar的formatter格式化日期显示？

Question

**问题描述：** 在使用 Vant 的 van-calendar 组件时，如何正确使用 `formatter` 属性来自定义日期显示格式？例如希望在日历中展示“2025-04-05”格式的日期，或者添加中文星期、节日标注等。开发者常常遇到 formatter 函数未生效、参数不明确或返回值错误的问题。请说明 van-calendar 的 formatter 使用方法及其注意事项，并提供一个可运行的示例代码片段。

Answer 1

一、van-calendar 的 formatter 属性简介

van-calendar 是 Vant 提供的一个日历组件，常用于日期选择和展示。其中的 formatter 属性允许开发者对每个日期单元格的内容进行自定义渲染。通过该属性，我们可以实现诸如：

• 显示“2025-04-05”格式的日期；
• 在日期下方添加中文星期信息；
• 标注节日或特殊日期（如春节、清明节等）。

但很多开发者在使用时会遇到 formatter 函数未生效、参数理解错误、返回值类型不对等问题。

二、formatter 函数的基本结构与参数说明

formatter 是一个函数，接收两个参数：

1. date: 当前渲染的日期对象（JavaScript Date 类型）；
2. type: 当前日历的类型（可为 'day' 或 'month'），用于区分是按天还是按月展示。

函数需返回一个对象，包含以下字段：

字段名	类型	描述
text	string	主文本内容，显示在日期单元格中
bottomInfo	string	底部附加信息，常用于显示星期或节日
className	string	自定义类名，可用于样式定制

三、formatter 使用示例：格式化日期并添加星期信息

下面是一个完整的 Vue 组件代码示例，演示如何将日期格式化为“YYYY-MM-DD”，并在底部显示中文星期：

<template>
  <van-calendar v-model:show="showCalendar" :formatter="customFormatter" />
</template>

<script setup>
import { ref } from 'vue';
const showCalendar = ref(true);

// 自定义 formatter 函数
const customFormatter = (date, type) => {
  if (type === 'day') {
    const year = date.getFullYear();
    const month = String(date.getMonth() + 1).padStart(2, '0');
    const day = String(date.getDate()).padStart(2, '0');
    const weekDay = ['日', '一', '二', '三', '四', '五', '六'][date.getDay()];
    
    return {
      text: `${year}-${month}-${day}`,
      bottomInfo: `周${weekDay}`
    };
  }
  return null;
};
</script>

四、formatter 进阶：添加节日标注

可以在 formatter 中判断特定日期是否为节日，并添加相应的标记。例如，在春节、清明节等日期下方标注节日名称：

const festivals = {
  '01-01': '元旦',
  '02-10': '除夕',
  '02-11': '春节',
  '04-04': '清明节',
  '05-01': '劳动节',
  '06-22': '端午节',
  '09-17': '中秋节'
};

const customFormatterWithFestival = (date, type) => {
  if (type === 'day') {
    const month = String(date.getMonth() + 1).padStart(2, '0');
    const day = String(date.getDate()).padStart(2, '0');
    const festivalKey = `${month}-${day}`;
    const festivalName = festivals[festivalKey];

    return {
      text: date.getDate(),
      bottomInfo: festivalName ? festivalName : `周${['日','一','二','三','四','五','六'][date.getDay()]}`,
      className: festivalName ? 'festival-day' : ''
    };
  }
  return null;
};

五、formatter 常见问题与调试技巧

在实际开发中，常见问题包括：

• formatter 未生效：检查是否正确绑定属性名，是否拼写错误，如 v-model:show 和 formatter 是否正确使用。
• 返回值为空：确保函数返回的是对象，且包含 text 字段，否则可能不会渲染。
• 类型错误：注意 type 参数的取值范围，只处理需要的类型（如仅处理 'day' 类型）。
• 性能问题：如果 formatter 涉及大量计算或请求，请考虑缓存结果或优化逻辑。

推荐使用浏览器调试工具查看控制台输出，或在函数内部打印 date 对象，确认传入的数据是否符合预期。

六、formatter 的扩展应用场景

除了基本的日期格式化和节日标注，formatter 还可以用于：

• 高亮显示用户指定的日期区间；
• 结合后端接口动态加载节假日数据；
• 根据业务需求添加图标、状态标识等富文本内容；
• 支持多语言切换，适配国际化场景。

这些高级应用可以通过结合 Vuex、Axios 等工具进一步拓展。