npmapps 1.1.6 → 1.3.1

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

@@ -1,485 +0,0 @@
-# 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`。