npmapps 1.1.4 → 1.1.6

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

@@ -0,0 +1,485 @@
+# 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             # 日期计算与字段映射工具
+├── recruitmentAdapter.js # NodeQ mock 响应 -> EventCalendar 数据
+├── mockData.js          # 模拟数据（setTimeout 模拟异步接口）
+├── example.vue          # 完整示例集合（14 个 demo + API 文档）
+└── README.md
+```
+
+真正接入普通日历时，**必需**的只有 `index.vue`、`MonthSelect.vue`、`CalendarSkeleton.vue`、`utils.js`。
+接 NodeQ 招聘接口时再加入 `recruitmentAdapter.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: '香港中文大学（深圳）',  // 主文案
+            address: '深圳市南山区校区报告厅', // 地址，为空时不显示地址行
+            badge: '宣讲',                 // 右上角角标
+            type: 'talk'                   // 类型，决定配色
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### 扁平结构（也支持）
+
+不按月分组，直接给一维日期数组，组件会自动按日期归月：
+
+```js
+[
+  { date: '2026-09-09', items: [...] },
+  { date: '2026-10-01', items: [...] }
+]
+```
+
+## NodeQ mock 数据转换
+
+转换方法只负责把当前 mock 响应中的 `data.nbcbRecAnnJourneyMaps` 映射为组件默认结构，
+不包含字段猜测或展示配置：
+
+```js
+import EventCalendar from '@/components/EventCalendar/index.vue'
+import { transformNodeqCalendarResponse } from '@/components/EventCalendar/recruitmentAdapter'
+
+const data = transformNodeqCalendarResponse(response)
+```
+
+```vue
+<EventCalendar
+  :data="data"
+  item-align="center"
+  :item-horizontal-padding="0"
+  :item-height="40"
+/>
+```
+
+转换后条目固定包含 `id`、`label`、`address`、`badge`、`type`、`disabled`。
+mock 中没有的值使用空字符串或 `false`。`address` 为空时，日历组件不会渲染地址行。
+
+大学名称不超过 7 个字符时为 14px，超过 7 个字符时为 12px；地址统一为 12px。
+`item-align` 控制靠左或居中，`item-horizontal-padding="0"` 可去掉条目左右内边距。
+
+## 原生布局配置工具栏
+
+外边距、内边距、条目、溢出与行高、角标缩放等均为组件原生 Props。开启工具栏后，
+改完点「复制配置」，把 JSON 粘回 `layoutConfig` 再 `v-bind` 即可：
+
+```vue
+<EventCalendar
+  :data="data"
+  v-bind="layoutConfig"
+  :show-config-toolbar="isDevelopment"
+/>
+```
+
+```js
+export default {
+  data() {
+    return {
+      isDevelopment: process.env.NODE_ENV !== 'production',
+      // 结构与工具栏「复制配置」得到的 JSON 一致，可直接赋值应用
+      layoutConfig: {
+        itemAlign: 'center',
+        calendarMargin: 0,
+        calendarPadding: 0,
+        headerPadding: '4px 4px 16px',
+        cellPadding: '12px 10px',
+        mobileCellPadding: '8px 6px',
+        itemHorizontalPadding: 0,
+        itemVerticalPadding: 4,
+        itemGap: 6,
+        itemLineGap: 2,
+        itemBgGradient: false,
+        itemBgGradientDir: 'to-bottom',
+        itemBgHover: true,
+        overflowMode: 'scroll',
+        maxVisibleItems: 4,
+        itemHeight: 28,
+        minRowHeight: 118,
+        badgeScale: 0.75,
+        // 条目色留空表示沿用 type/主题配色
+        itemTextColor: '',
+        itemBgColor: ''
+      }
+    }
+  }
+}
+```
+
+`show-config-toolbar` 默认是 `false`。开启后组件顶部会出现配置工具栏（P1～P14）：
+条目对齐、日期格/窄屏日期格内边距（各拆「上下 / 左右」两块）、条目左右/上下内边距与间距、
+名称与地址间距、单格最多显示、条目高度、条目背景效果（纯色/渐变，方向可上下或左右）、
+悬浮加深（可关闭）与条目文字色/背景色；每张卡片右上角都有「还原」可回到初始值。
+选定条目背景色后，鼠标悬浮会自动把背景调淡一档，不喜欢可在「悬浮加深」里关闭。
+底部实时显示当前配置 JSON，右上角「复制配置」一键复制。用户把复制出的 JSON 发回后，
+研发直接把它赋给 `layoutConfig` 通过 `v-bind` 应用即可。
+
+## 字段映射（后端字段不一致时）
+
+**不需要改数据**，传 `field-names` 即可。字段路径支持 `'a.b.c'` 形式。
+
+```js
+const fieldNames = {
+  month:        'ym',
+  monthLabel:   'ymText',
+  days:         'dateList',
+  date:         'dayStr',
+  items:        'activityList',
+  itemKey:      'activityId',
+  itemLabel:    'schoolName',
+  itemAddress:  'rawAddress',
+  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` |
+
+大学名称不超过 7 个字符时使用 14px，超过 7 个字符时使用 12px；地址行统一使用 12px，
+地址为空时不渲染。
+
+`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` |
+| item-align | 条目内容对齐方式：`left` / `center` | String | `'left'` |
+| calendar-margin | 日历根节点外边距；Number 按 px 处理，String 支持 CSS 简写 | Number / String | `0` |
+| calendar-padding | 日历根节点内边距；Number 按 px 处理，String 支持 CSS 简写 | Number / String | `0` |
+| header-padding | 顶部区域内边距，支持 CSS 简写 | Number / String | `'4px 4px 16px'` |
+| cell-padding | 日期格内边距，支持 CSS 简写 | Number / String | `'12px 10px'` |
+| mobile-cell-padding | 768px 及以下日期格内边距 | Number / String | `'8px 6px'` |
+| item-horizontal-padding | 条目左右内边距（px），传 0 可去除 | Number | `8` |
+| item-vertical-padding | 条目上下内边距（px） | Number | `4` |
+| item-line-gap | 条目内名称与地址的行间距（px） | Number | `2` |
+| item-bg-gradient | 条目背景是否启用渐变（在底色上叠柔和渐变） | Boolean | `false` |
+| item-bg-gradient-dir | 渐变方向：to-bottom 上到下 | to-right 左到右 | String | `'to-bottom'` |
+| item-bg-hover | 悬浮时是否自动把条目背景调淡一档 | Boolean | `true` |
+| badge-scale | 右上角角标整体缩放倍率（越小越紧凑） | Number | `0.75` |
+| show-config-toolbar | 显示原生布局配置工具栏 | Boolean | `false` |
+| item-bg-color | 条目(.ec__item)背景色覆盖；空串按 type/主题配色（工具栏可取色） | String | `''` |
+| item-text-color | 条目(.ec__item)文字色覆盖；空串按 type/主题配色（工具栏可取色） | String | `''` |
+| 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)` |
+| config-change | 工具栏配置变化（编辑每一项都会触发） | `(config)` |
+
+`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()` | 重置轮播计时 |
+| `getLayoutConfig()` | 获取可直接通过 `v-bind` 应用的当前布局配置 |
+
+## 主题定制
+
+所有颜色都走 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,       // 空数据
+  fetchNodeqCalendarData, // NodeQ mock 响应（三个月、每天 3～5 条）
+  NODEQ_MOCK_RESPONSE,  // 同一份响应的同步版本
+  createNodeqMockResponse,
+  SIMPLE_DATA,          // 一份写死的小数据
+  ALT_FIELD_NAMES
+} from './mockData'
+import { transformNodeqCalendarResponse } from './recruitmentAdapter'
+
+const data = await fetchCalendarData({
+  months: ['2026-09', '2026-10'],
+  delay: 1500,
+  maxItems: 6,
+  density: 0.62
+})
+
+const nodeqResponse = await fetchNodeqCalendarData()
+const nodeqData = transformNodeqCalendarResponse(nodeqResponse)
+```
+
+数据用固定种子的伪随机生成，**每次刷新结果一致**，方便调样式和截图对比。
+`createNodeqMockResponse()` 默认生成 2026 年 9～11 月，每个月 14 个有安排的日期，
+每天 3～5 条 NodeQ mock 记录。转换方法只按这份 mock 的固定字段做映射。
+
+## 示例页
+
+`example.vue` 是按 UI 组件库文档形式组织的完整示例集合，包含 14 个可交互 demo
+（基础用法、异步骨架屏、多月切换、自动轮播、切换动效、跨年补全、字段映射、
+溢出与行高、插槽定制、事件、主题、空状态、NodeQ 后端适配、布局配置与 JSON 导出）
+与完整 API 表格。
+
+本项目中已挂到路由 `/calendar`。
+
+## 浏览器兼容
+
+- 依赖 CSS Grid、CSS 自定义属性 —— 现代浏览器均支持，不支持 IE11；
+- `ResizeObserver` 用于高度过渡，缺失时自动降级（高度不做动画，功能不受影响）；
+- 复制代码在非 HTTPS 环境会回退到 `document.execCommand`。