npmapps 1.1.3 → 1.1.5

package/app/wujie-vue2-child/src/components/EventCalendar/README.md

@@ -0,0 +1,368 @@
+# EventCalendar 日程日历组件
+
+一个零第三方依赖的 Vue 2 月历组件。支持月份自动补全（含跨年）、下拉切换、自动轮播、
+字段映射、插槽定制、骨架屏与多种切换动效。
+
+> 整个 `EventCalendar` 文件夹可以直接拷贝到任意 Vue 2 项目使用，
+> **不依赖 element-ui / dayjs / moment / lodash 等任何第三方库**，只用原生 `Date` 与 CSS。
+
+## 目录结构
+
+```
+EventCalendar/
+├── index.vue            # 组件本体
+├── MonthSelect.vue      # 自研月份下拉框（不依赖 UI 库）
+├── CalendarSkeleton.vue # 骨架屏
+├── CodeBlock.vue        # 示例页用的代码块（业务中可删）
+├── utils.js             # 日期计算与字段映射工具
+├── mockData.js          # 模拟数据（setTimeout 模拟异步接口）
+├── example.vue          # 完整示例集合（12 个 demo + API 文档）
+└── README.md
+```
+
+真正接入业务时，**必需**的只有 `index.vue`、`MonthSelect.vue`、`CalendarSkeleton.vue`、`utils.js`。
+`mockData.js` / `example.vue` / `CodeBlock.vue` 是演示用的，可以删掉。
+
+## 快速开始
+
+```vue
+<template>
+  <EventCalendar
+    :data="data"
+    :loading="loading"
+    title="宣讲日历"
+    subtitle="更多场次陆续上线中，宣讲进程以实际安排为准"
+    @item-click="onItemClick"
+  />
+</template>
+
+<script>
+import EventCalendar from '@/components/EventCalendar/index.vue'
+
+export default {
+  components: { EventCalendar },
+  data() {
+    return { data: [], loading: true }
+  },
+  async created() {
+    this.loading = true
+    try {
+      this.data = await this.$api.getCalendar()
+    } finally {
+      // 放 finally：接口失败也要收掉骨架屏，否则页面会一直卡在加载态
+      this.loading = false
+    }
+  },
+  methods: {
+    onItemClick(scope) {
+      console.log(scope.item)  // 后端返回的原始对象
+    }
+  }
+}
+</script>
+```
+
+## 数据结构
+
+### 默认结构（按月分组）
+
+```js
+[
+  {
+    month: '2026-09',          // 月份标识
+    monthLabel: '2026年9月',    // 下拉框文案，不传则自动生成
+    days: [
+      {
+        date: '2026-09-09',    // 日期标识
+        items: [               // 当天的条目
+          {
+            id: 'a1',
+            label: '香港中文大学（深圳）',  // 主文案
+            badge: '宣讲',                 // 右上角角标
+            type: 'talk'                   // 类型，决定配色
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### 扁平结构（也支持）
+
+不按月分组，直接给一维日期数组，组件会自动按日期归月：
+
+```js
+[
+  { date: '2026-09-09', items: [...] },
+  { date: '2026-10-01', items: [...] }
+]
+```
+
+## 字段映射（后端字段不一致时）
+
+**不需要改数据**，传 `field-names` 即可。字段路径支持 `'a.b.c'` 形式。
+
+```js
+const fieldNames = {
+  month:        'ym',
+  monthLabel:   'ymText',
+  days:         'dateList',
+  date:         'dayStr',
+  items:        'activityList',
+  itemKey:      'activityId',
+  itemLabel:    'schoolName',
+  itemBadge:    'activityTypeName',
+  itemType:     'activityType',
+  itemDisabled: 'expired'
+}
+```
+
+```vue
+<EventCalendar :data="data" :field-names="fieldNames" />
+```
+
+完整默认值见 `utils.js` 里的 `DEFAULT_FIELD_NAMES`。
+
+## 核心机制说明
+
+### 1. 月份补全与跨年
+
+每个月天数（28/29/30/31）和「1 号是星期几」都不固定，组件会自动补齐首尾：
+
+- 若 2 月 1 号是**周三**，首行补上 1 月的周日、周一、周二；
+- 若 2 月 28 号是**周三**，末行补上 3 月的周四、周五、周六；
+- 非当月的补位日期自动**置灰**（`.is-other-month`）。
+
+实现上先算出本月 1 号相对「一周起始日」的偏移量 `leading`，再用
+`new Date(year, month - 1, 1 - leading + i)` 递推生成所有格子。
+原生 `Date` 对天数越界会自动进位/借位，**跨年（1 月往前补 12 月、12 月往后补次年 1 月）无需任何特判**。
+
+补位格子默认也会渲染条目，可用 `:show-adjacent-items="false"` 关掉。
+
+### 2. 行高与条目溢出
+
+**行高由该行条目最多的那一天决定** —— 这是 CSS Grid 的天然行为
+（同一行的格子会自动拉伸到该行最高格子的高度），无需 JS 计算，也不会因为窗口缩放而失准。
+
+单日条目超过 `max-visible-items`（默认 4）后有两种处理：
+
+| overflow-mode | 行为 |
+| --- | --- |
+| `scroll`（默认） | 格内出现细滚动条，滚动区高度 = `n × item-height + (n-1) × item-gap` |
+| `collapse` | 只显示前 n-1 条，末尾出现「还有 N 项」，可监听 `more-click` |
+
+`min-row-height` 保证没有条目的行不会塌陷。
+
+### 3. 轮播与暂停
+
+`autoplay` 开启后按 `autoplay-interval` 自动切换月份，顶部细进度条展示剩余时间。
+以下情况会**自动暂停并保留剩余时间**（恢复时接着走，进度条不跳）：
+
+- 鼠标悬停在组件上（`pause-on-hover`，默认开）
+- 月份下拉框展开中
+- 浏览器标签页切到后台（`visibilitychange`）
+- 用户点击了暂停按钮
+
+`loop="false"` 时播到最后一个月会停止并触发 `autoplay-end`。
+
+### 4. 切换动效
+
+| transition-effect | 效果 |
+| --- | --- |
+| `slide`（默认） | 按切换方向左右滑入滑出 |
+| `fade` | 淡入淡出 |
+| `zoom` | 缩放 |
+| `flip` | 带透视的 3D 翻页 |
+| `none` | 关闭动效 |
+
+另有 `cell-stagger` 让单元格从左上到右下错峰入场。
+动效时长由 `transition-duration` 控制，设为 `0` 亦可视作关闭。
+
+切月时行数可能从 5 行变 6 行，组件用 `ResizeObserver` 测量面板高度并做高度过渡，不会突然跳动。
+
+> 组件已适配 `prefers-reduced-motion`：系统开启「减少动态效果」时自动关闭全部动画。
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| data | 日历数据，支持按月分组与扁平两种结构 | Array | `[]` |
+| field-names | 字段映射，支持 `a.b.c` 点路径 | Object | `{}` |
+| loading | 加载中，为 true 时渲染骨架屏 | Boolean | `false` |
+| skeleton-rows | 骨架屏行数 | Number | `5` |
+| active-month | 当前月份，支持 `v-model` / `.sync` | String | `''` |
+| show-month-select | 是否显示月份下拉框 | Boolean | `true` |
+| show-arrows | 是否显示左右翻月箭头 | Boolean | `false` |
+| autoplay | 是否开启自动轮播 | Boolean | `false` |
+| autoplay-interval | 轮播间隔（毫秒） | Number | `60000` |
+| loop | 播到最后一个月后是否回到第一个 | Boolean | `true` |
+| pause-on-hover | 鼠标悬停时暂停轮播 | Boolean | `true` |
+| show-progress | 显示轮播倒计时进度条 | Boolean | `true` |
+| show-autoplay-toggle | 显示播放/暂停按钮 | Boolean | `true` |
+| transition-effect | `slide` / `fade` / `zoom` / `flip` / `none` | String | `'slide'` |
+| transition-duration | 动效时长（毫秒） | Number | `420` |
+| cell-stagger | 单元格错峰入场动画 | Boolean | `false` |
+| show-header | 是否显示顶部区域 | Boolean | `true` |
+| title / subtitle | 默认标题与副标题（`header-left` 未传时生效） | String | `''` |
+| first-day-of-week | 一周起始日，0=周日 1=周一 | Number | `0` |
+| week-labels | 星期文案，下标对应 `Date.getDay()` | Array | `['周日'…'周六']` |
+| max-visible-items | 单日最多显示条目数 | Number | `4` |
+| overflow-mode | 溢出处理：`scroll` / `collapse` | String | `'scroll'` |
+| item-height | 单条条目高度（px） | Number | `28` |
+| item-gap | 条目间距（px） | Number | `6` |
+| min-row-height | 单元格最小高度（px） | Number | `118` |
+| show-adjacent-items | 补位日期是否也渲染条目 | Boolean | `true` |
+| highlight-today | 高亮今天 | Boolean | `true` |
+| colorful | 角标是否按 type 上色 | Boolean | `true` |
+| type-colors | 类型配色 `{ type: { color, bg } }` | Object | 内置 4 种 |
+| day-formatter | 日期文案格式化 `(cell) => string` | Function | `'9月7日'` |
+| month-formatter | 月份下拉文案格式化 `(monthKey, raw) => string` | Function | `null` |
+| empty-text | 空数据文案 | String | `'暂无日程数据'` |
+| cell-focusable | 单元格可聚焦（键盘无障碍） | Boolean | `false` |
+| theme | 主题变量覆盖 | Object | `{}` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| day-click | 点击日期格子 | `(scope, event)` |
+| item-click | 点击条目 | `(scope, event)` |
+| tag-click | 点击条目右上角角标；**未监听时自动退化为 item-click** | `(scope, event)` |
+| more-click | `collapse` 模式下点击「还有 N 项」 | `(scope, event)` |
+| month-change | 月份变化 | `(month, { index, source, option, raw })` |
+| update:activeMonth | 配合 `v-model` / `.sync` | `(month)` |
+| autoplay-toggle | 点击播放/暂停按钮 | `(playing: Boolean)` |
+| autoplay-end | `loop=false` 时播到最后一个月 | — |
+| transition-end | 月份切换动画结束 | `(month)` |
+
+`month-change` 的 `source` 表明触发来源：`select` / `arrow` / `autoplay` / `prop` / `api`。
+
+日期格子的 `scope`：
+
+```js
+{ day, date, dateKey, items, visibleItems, raw, isCurrentMonth, isToday, isWeekend, label }
+```
+
+条目的 `scope`：
+
+```js
+{ item, raw, label, badge, type, disabled, index, day, dateKey }
+```
+
+其中 `item` / `raw` 是后端返回的**原始对象**，字段齐全，不受 `field-names` 影响。
+
+### Slots
+
+| 名称 | 说明 | 作用域参数 |
+| --- | --- | --- |
+| header-left | 顶部左侧（设计稿的标题区） | `{ month, monthLabel, monthIndex, monthCount, monthOptions, loading, paused, prev, next, goTo, toggleAutoplay }` |
+| header-right | 顶部右侧，整体替换默认按钮与下拉 | 同上 |
+| weekday | 星期表头单元 | `{ label, weekday, isWeekend, index }` |
+| day | 整个日期格子（覆盖所有默认内容） | 日期 scope |
+| day-header | 格子里的日期行 | 日期 scope |
+| items | 格子里的条目列表区域 | 日期 scope |
+| item | 单个条目 | 条目 scope |
+| day-empty | 当天无数据时的占位 | 日期 scope |
+| loading | 自定义骨架屏 | `{ rows }` |
+| empty | 整体空状态 | — |
+
+不传插槽时全部回落到默认样式（即设计稿效果）。
+
+```vue
+<EventCalendar :data="data">
+  <template #header-left="{ monthLabel }">
+    <div class="my-head">{{ monthLabel }}</div>
+  </template>
+
+  <template #item="{ item, label, badge }">
+    <div class="my-item">{{ item.startTime }} {{ label }} · {{ badge }}</div>
+  </template>
+</EventCalendar>
+```
+
+### Methods（通过 `ref` 调用）
+
+| 方法 | 说明 |
+| --- | --- |
+| `prev()` | 切到上一个月 |
+| `next()` | 切到下一个月 |
+| `goTo(index)` | 切到第 index 个月（从 0 开始） |
+| `setMonth(month)` | 切到指定月份，如 `setMonth('2026-10')` |
+| `restartAutoplay()` | 重置轮播计时 |
+
+## 主题定制
+
+所有颜色都走 CSS 变量，用 `theme` 传入即可换肤：
+
+```vue
+<EventCalendar
+  :data="data"
+  :theme="{
+    primary: '#10a37f',
+    primaryGhost: 'rgba(16,163,127,.12)',
+    border: '#e4e7ed',
+    borderLight: '#eef0f4',
+    text: '#303133',
+    textSecondary: '#606266',
+    muted: '#c8ccd4',
+    itemBg: '#f2f9f6',
+    cellHover: '#f7fcfa',
+    radius: '10px'
+  }"
+/>
+```
+
+按业务类型配色用 `type-colors`：
+
+```vue
+<EventCalendar
+  :data="data"
+  :type-colors="{
+    talk: { color: '#3d6cf0', bg: 'rgba(61,108,240,.10)' },
+    fair: { color: '#e0821b', bg: 'rgba(224,130,27,.12)' }
+  }"
+/>
+```
+
+`:colorful="false"` 会让角标统一回到中性灰（更贴近原始设计稿）。
+
+## 模拟数据
+
+`mockData.js` 用 `setTimeout` 模拟异步接口，方便脱离后端联调：
+
+```js
+import {
+  fetchCalendarData,    // 默认字段，可指定月份 / 延迟 / 数据密度
+  fetchCalendarDataV2,  // 字段名完全不同，配合 ALT_FIELD_NAMES 演示映射
+  fetchCrossYearData,   // 2025-12 / 2026-01 / 2026-02，验证跨年补全
+  fetchEmptyData,       // 空数据
+  SIMPLE_DATA,          // 一份写死的小数据
+  ALT_FIELD_NAMES
+} from './mockData'
+
+const data = await fetchCalendarData({
+  months: ['2026-09', '2026-10'],
+  delay: 1500,
+  maxItems: 6,
+  density: 0.62
+})
+```
+
+数据用固定种子的伪随机生成，**每次刷新结果一致**，方便调样式和截图对比。
+
+## 示例页
+
+`example.vue` 是按 UI 组件库文档形式组织的完整示例集合，包含 12 个可交互 demo
+（基础用法、异步骨架屏、多月切换、自动轮播、切换动效、跨年补全、字段映射、
+溢出与行高、插槽定制、事件、主题、空状态）与完整 API 表格。
+
+本项目中已挂到路由 `/calendar`。
+
+## 浏览器兼容
+
+- 依赖 CSS Grid、CSS 自定义属性 —— 现代浏览器均支持，不支持 IE11；
+- `ResizeObserver` 用于高度过渡，缺失时自动降级（高度不做动画，功能不受影响）；
+- 复制代码在非 HTTPS 环境会回退到 `document.execCommand`。