npmapps 1.1.4 → 1.1.6

package/app/wujie-wk/wujie-vue2-child/src/components/EventCalendar/index.vue

@@ -0,0 +1,2720 @@
+<template>
+  <div
+    class="ec"
+    :class="rootClass"
+    :style="cssVars"
+    @mouseenter="handleMouseEnter"
+    @mouseleave="handleMouseLeave"
+  >
+    <!-- 开发/业务配置工具栏：默认关闭；改完点「复制配置」，把 JSON 发给研发即可 -->
+    <section
+      v-if="showConfigToolbar"
+      class="ec__config"
+      aria-label="日历布局配置"
+    >
+      <div class="ec__config-head">
+        <div>
+          <strong class="ec__config-title">布局配置</strong>
+          <span class="ec__config-caption">调整后点「复制配置」，粘贴发给研发即可</span>
+        </div>
+        <div class="ec__config-actions">
+          <button
+            type="button"
+            class="ec__config-btn is-primary"
+            @click="copyLayoutConfig"
+          >复制配置</button>
+        </div>
+      </div>
+
+      <div class="ec__config-list">
+        <div
+          v-for="field in configFields"
+          :key="field.key"
+          class="ec__config-block"
+          :class="'ec__config-block--' + field.kind"
+          :title="field.kind === 'spacing' ? '当前简写：' + spacingShorthand(field.key) : undefined"
+        >
+          <!-- 分段选项：条目对齐 / 溢出方式 -->
+          <template v-if="field.kind === 'seg'">
+            <p class="ec__config-label">
+              <span class="ec__config-priority">P{{ field.priority }}</span>{{ field.label }}
+              <button
+                type="button"
+                class="ec__config-reset"
+                :title="'还原「' + field.label + '」为初始值'"
+                @click="resetField(field.key)"
+              >还原</button>
+            </p>
+            <div class="ec__config-segment">
+              <button
+                v-for="option in field.options"
+                :key="option.value"
+                type="button"
+                :class="{ 'is-active': configDraft[field.key] === option.value }"
+                :aria-pressed="configDraft[field.key] === option.value ? 'true' : 'false'"
+                @click="updateLayoutConfig(field.key, option.value)"
+              >{{ option.label }}</button>
+            </div>
+          </template>
+
+          <!-- 间距：上下 / 左右两块步进 -->
+          <template v-else-if="field.kind === 'spacing'">
+            <p class="ec__config-label">
+              <span class="ec__config-priority">P{{ field.priority }}</span>{{ field.label }}
+              <code class="ec__config-shorthand">{{ spacingShorthand(field.key) }}</code>
+              <button
+                type="button"
+                class="ec__config-reset"
+                :title="'还原「' + field.label + '」为初始值'"
+                @click="resetField(field.key)"
+              >还原</button>
+            </p>
+            <div class="ec__spacing">
+              <div v-for="axis in spacingAxes" :key="axis.key" class="ec__spacing-row">
+                <span class="ec__spacing-row-label">{{ axis.label }}</span>
+                <span class="ec__stepper">
+                  <button
+                    type="button"
+                    class="ec__step-btn"
+                    :aria-label="field.label + '，' + axis.label + '减 1'"
+                    title="减 1（按住 Shift ±5）"
+                    @click="nudgeSpacingAxis(field.key, axis.key, -1, $event)"
+                  >−</button>
+                  <label class="ec__stepper-input">
+                    <input
+                      type="number"
+                      min="0"
+                      step="1"
+                      :value="spacingAxisValue(field.key, axis.key)"
+                      :aria-label="field.label + '，' + axis.label + '（px）'"
+                      @change="updateSpacingAxis(field.key, axis.key, $event)"
+                    />
+                    <span class="ec__stepper-unit" aria-hidden="true">px</span>
+                  </label>
+                  <button
+                    type="button"
+                    class="ec__step-btn"
+                    :aria-label="field.label + '，' + axis.label + '加 1'"
+                    title="加 1（按住 Shift ±5）"
+                    @click="nudgeSpacingAxis(field.key, axis.key, 1, $event)"
+                  >+</button>
+                </span>
+              </div>
+            </div>
+          </template>
+
+          <!-- 单值数值：输入框左右包 −/+ -->
+          <template v-else-if="field.kind === 'number'">
+            <p class="ec__config-label">
+              <span class="ec__config-priority">P{{ field.priority }}</span>{{ field.label }}
+              <button
+                type="button"
+                class="ec__config-reset"
+                :title="'还原「' + field.label + '」为初始值'"
+                @click="resetField(field.key)"
+              >还原</button>
+            </p>
+            <span class="ec__stepper">
+              <button
+                type="button"
+                class="ec__step-btn"
+                :aria-label="field.label + '减 1'"
+                :title="'减 ' + (field.step || 1) + '（按住 Shift ×5）'"
+                @click="nudgeNumber(field.key, -1, $event)"
+              >−</button>
+              <label class="ec__stepper-input">
+                <input
+                  type="number"
+                  :min="typeof field.min === 'number' ? field.min : 0"
+                  :step="field.step || 1"
+                  :value="configDraft[field.key]"
+                  :aria-label="field.label + '（' + field.unit + '）'"
+                  @change="updateLayoutConfig(field.key, $event.target.value, 'number')"
+                />
+                <span v-if="field.unit" class="ec__stepper-unit" aria-hidden="true">{{ field.unit }}</span>
+              </label>
+              <button
+                type="button"
+                class="ec__step-btn"
+                :aria-label="field.label + '加 1'"
+                :title="'加 ' + (field.step || 1) + '（按住 Shift ×5）'"
+                @click="nudgeNumber(field.key, 1, $event)"
+              >+</button>
+            </span>
+          </template>
+
+          <!-- 颜色 -->
+          <template v-else-if="field.kind === 'color'">
+            <label class="ec__color-swatch" :title="field.label">
+              <input
+                type="color"
+                :value="colorValue(field.key)"
+                :aria-label="field.label"
+                @input="updateLayoutConfig(field.key, $event.target.value)"
+              />
+            </label>
+            <span class="ec__color-meta">
+              <span class="ec__config-label">
+                <span class="ec__config-priority">P{{ field.priority }}</span>{{ field.label }}
+              </span>
+              <code class="ec__color-hex">{{ colorValue(field.key) }}</code>
+            </span>
+            <button
+              type="button"
+              class="ec__reset-btn"
+              title="还原为默认配色"
+              :disabled="!configDraft[field.key]"
+              @click="resetColor(field.key)"
+            >还原</button>
+          </template>
+        </div>
+      </div>
+
+      <div class="ec__config-output">
+        <pre class="ec__config-json">{{ configJsonText }}</pre>
+      </div>
+
+      <div class="ec__config-feedback" role="status" aria-live="polite">
+        {{ copyStatus }}
+      </div>
+    </section>
+
+    <!-- ==================== 顶部区域 ==================== -->
+    <div v-if="showHeader" class="ec__header">
+      <!-- 左侧：完全交给使用者的插槽，未传时回落到 title / subtitle -->
+      <div class="ec__header-left">
+        <slot name="header-left" v-bind="headerScope">
+          <div v-if="title || subtitle" class="ec__title-group">
+            <h3 v-if="title" class="ec__title">{{ title }}</h3>
+            <span v-if="subtitle" class="ec__subtitle">{{ subtitle }}</span>
+          </div>
+        </slot>
+      </div>
+
+      <!-- 右侧：默认是「轮播开关 + 翻月箭头 + 月份下拉」 -->
+      <div class="ec__header-right">
+        <slot name="header-right" v-bind="headerScope">
+          <button
+            v-if="autoplay && showAutoplayToggle"
+            type="button"
+            class="ec__icon-btn"
+            :title="manualPaused ? '继续轮播' : '暂停轮播'"
+            :aria-label="manualPaused ? '继续轮播' : '暂停轮播'"
+            @click="toggleAutoplay"
+          >
+            <svg viewBox="0 0 16 16" aria-hidden="true">
+              <path v-if="manualPaused" d="M5 3.5 L12 8 L5 12.5 Z" fill="currentColor" />
+              <g v-else fill="currentColor">
+                <rect x="4.5" y="3.5" width="2.4" height="9" rx="0.8" />
+                <rect x="9.1" y="3.5" width="2.4" height="9" rx="0.8" />
+              </g>
+            </svg>
+          </button>
+
+          <template v-if="showArrows">
+            <button
+              type="button"
+              class="ec__icon-btn"
+              title="上一个月"
+              aria-label="上一个月"
+              :disabled="!canGoPrev"
+              @click="prev()"
+            >
+              <svg viewBox="0 0 16 16" aria-hidden="true">
+                <path d="M10 3 L5 8 L10 13" fill="none" stroke="currentColor" stroke-width="1.7"
+                      stroke-linecap="round" stroke-linejoin="round" />
+              </svg>
+            </button>
+            <button
+              type="button"
+              class="ec__icon-btn"
+              title="下一个月"
+              aria-label="下一个月"
+              :disabled="!canGoNext"
+              @click="next()"
+            >
+              <svg viewBox="0 0 16 16" aria-hidden="true">
+                <path d="M6 3 L11 8 L6 13" fill="none" stroke="currentColor" stroke-width="1.7"
+                      stroke-linecap="round" stroke-linejoin="round" />
+              </svg>
+            </button>
+          </template>
+
+          <MonthSelect
+            v-if="showMonthSelect"
+            :value="innerMonth"
+            :options="monthOptions"
+            :disabled="loading || !monthOptions.length"
+            placeholder="选择月份"
+            @change="handleSelectChange"
+            @visible-change="handleSelectVisibleChange"
+          />
+        </slot>
+      </div>
+    </div>
+
+    <!-- 轮播进度条：直观体现「下一次自动切换还有多久」 -->
+    <div v-if="showProgressBar" class="ec__progress">
+      <div
+        :key="progressKey"
+        class="ec__progress-inner"
+        :style="progressStyle"
+      ></div>
+    </div>
+
+    <!-- ==================== 星期表头 ==================== -->
+    <div class="ec__weekdays" role="row">
+      <div
+        v-for="(w, index) in weekHeaders"
+        :key="w.weekday"
+        class="ec__weekday"
+        :class="{ 'is-weekend': w.isWeekend }"
+        role="columnheader"
+      >
+        <slot name="weekday" v-bind="{ ...w, index }">{{ w.label }}</slot>
+      </div>
+    </div>
+
+    <!-- ==================== 主体（骨架屏 / 日历网格） ==================== -->
+    <div class="ec__stage" :style="stageStyle">
+      <transition
+        :name="transitionName"
+        @before-enter="handleBeforeEnter"
+        @enter="handleEnter"
+        @after-enter="handleAfterEnter"
+      >
+        <!-- 加载中：骨架屏 -->
+        <div v-if="loading" key="__skeleton__" class="ec__panel">
+          <slot name="loading" v-bind="{ rows: skeletonRows }">
+            <CalendarSkeleton
+              :rows="skeletonRows"
+              :min-row-height="cfgMinRowHeight"
+              :item-height="cfgItemHeight"
+            />
+          </slot>
+        </div>
+
+        <!-- 无任何月份数据：空状态 -->
+        <div v-else-if="!monthOptions.length" key="__empty__" class="ec__panel">
+          <slot name="empty">
+            <div class="ec__empty">
+              <svg class="ec__empty-icon" viewBox="0 0 64 64" aria-hidden="true">
+                <rect x="8" y="14" width="48" height="42" rx="6" fill="none"
+                      stroke="currentColor" stroke-width="2.5" />
+                <path d="M8 26 H56" stroke="currentColor" stroke-width="2.5" />
+                <path d="M20 8 V18 M44 8 V18" stroke="currentColor" stroke-width="2.5"
+                      stroke-linecap="round" />
+              </svg>
+              <p class="ec__empty-text">{{ emptyText }}</p>
+            </div>
+          </slot>
+        </div>
+
+        <!-- 正常渲染 -->
+        <div v-else :key="innerMonth" class="ec__panel">
+          <div class="ec__grid" role="grid">
+            <div
+              v-for="(cell, index) in renderCells"
+              :key="cell.dateKey"
+              class="ec__cell"
+              :class="cellClass(cell)"
+              :style="{ '--ec-i': index }"
+              role="gridcell"
+              :tabindex="cellFocusable ? 0 : -1"
+              :aria-label="cell.dateKey"
+              @click="handleDayClick(cell, $event)"
+              @keydown.enter.self="handleDayClick(cell, $event)"
+              @keydown.space.prevent.self="handleDayClick(cell, $event)"
+            >
+              <!-- 整格自定义 -->
+              <slot name="day" v-bind="cellScope(cell)">
+                <!-- 日期行 -->
+                <div class="ec__day-head">
+                  <slot name="day-header" v-bind="cellScope(cell)">
+                    <span class="ec__day-label">{{ dayFormatter(cell) }}</span>
+                    <span v-if="cell.isToday && highlightToday" class="ec__today-dot"></span>
+                  </slot>
+                </div>
+
+                <!-- 条目列表 -->
+                <div class="ec__items-wrap">
+                  <slot name="items" v-bind="cellScope(cell)">
+                    <div
+                      v-if="cell.items.length"
+                      class="ec__items"
+                      :class="{ 'is-scrollable': cell.scrollable }"
+                      :style="itemsStyle"
+                    >
+                      <div
+                        v-for="(entry, i) in cell.visibleItems"
+                        :key="entry.key"
+                        class="ec__item"
+                        :class="{
+                          'is-disabled': entry.disabled,
+                          'has-badge': !!entry.badge,
+                          'is-colorful': colorful && entry.type && !cfgItemBgColor && cfgItemBgHover,
+                          'is-bg-gradient': cfgItemBgGradient,
+                          'is-bg-gradient-h': cfgItemBgGradient && cfgGradientDir === 'to-right'
+                        }"
+                        :style="itemStyle(entry)"
+                        :title="itemTitle(entry)"
+                        @click.stop="handleItemClick(entry, cell, i, $event)"
+                      >
+                        <!-- 单条自定义 -->
+                        <slot name="item" v-bind="itemScope(entry, cell, i)">
+                          <div class="ec__item-content">
+                            <span
+                              class="ec__item-label"
+                              :class="{ 'is-long': isLongItemLabel(entry.label) }"
+                            >{{ entry.label }}</span>
+                            <span
+                              v-if="hasText(entry.address)"
+                              class="ec__item-address"
+                            >{{ entry.address }}</span>
+                          </div>
+                          <span
+                            v-if="entry.badge"
+                            class="ec__item-badge"
+                            :style="badgeStyle(entry)"
+                            @click.stop="handleBadgeClick(entry, cell, i, $event)"
+                          >{{ entry.badge }}</span>
+                        </slot>
+                      </div>
+
+                      <!-- overflowMode='collapse' 时的「更多」提示 -->
+                      <div
+                        v-if="cell.moreCount > 0"
+                        class="ec__more"
+                        @click.stop="handleMoreClick(cell, $event)"
+                      >还有 {{ cell.moreCount }} 项</div>
+                    </div>
+
+                    <!-- 当天无数据 -->
+                    <slot v-else name="day-empty" v-bind="cellScope(cell)"></slot>
+                  </slot>
+                </div>
+              </slot>
+            </div>
+          </div>
+        </div>
+      </transition>
+    </div>
+  </div>
+</template>
+
+<script>
+/**
+ * EventCalendar —— 月历 / 日程日历组件
+ * ==================================================================
+ * 特性一览：
+ *  1. 月份网格自动补全：上个月末尾 + 下个月开头，跨年正确，非当月置灰；
+ *  2. 月份下拉切换 + 自动轮播（间隔可配，支持 hover/下拉/切后台自动暂停）；
+ *  3. 4 种切换动效（slide / fade / zoom / flip）与逐格入场，均可关闭；
+ *  4. 字段名全部可映射（field-names），不用为后端字段改数据；
+ *  5. 行高按「当行条目最多的那天」自动撑开，超过上限出现滚动条；
+ *  6. 骨架屏、空状态、日期点击、条目点击、角标点击、丰富插槽。
+ *
+ * 组件不依赖任何第三方库，整个文件夹可直接拷贝到其它项目使用。
+ */
+import MonthSelect from './MonthSelect.vue'
+import CalendarSkeleton from './CalendarSkeleton.vue'
+import {
+  DEFAULT_FIELD_NAMES,
+  DEFAULT_WEEK_LABELS,
+  buildMonthMatrix,
+  defaultDayFormatter,
+  defaultMonthFormatter,
+  formatMonthKey,
+  getByPath
+} from './utils'
+
+/** 内置类型配色，可被 typeColors prop 覆盖或扩展 */
+const BUILTIN_TYPE_COLORS = {
+  talk: { color: '#3d6cf0', bg: 'rgba(61, 108, 240, 0.10)' },
+  fair: { color: '#e0821b', bg: 'rgba(224, 130, 27, 0.12)' },
+  live: { color: '#10a37f', bg: 'rgba(16, 163, 127, 0.12)' },
+  exam: { color: '#8b5cf6', bg: 'rgba(139, 92, 246, 0.12)' },
+  default: { color: '#6b7280', bg: 'rgba(107, 114, 128, 0.10)' }
+}
+
+/** 布局配置全部对应 EventCalendar 原生 Props，可直接用于 v-bind。 */
+const DEFAULT_LAYOUT_CONFIG = Object.freeze({
+  itemAlign: 'left',
+  calendarMargin: 0,
+  calendarPadding: 0,
+  headerPadding: '4px 4px 16px',
+  cellPadding: '12px 10px',
+  mobileCellPadding: '8px 6px',
+  itemHorizontalPadding: 8,
+  itemVerticalPadding: 4,
+  itemGap: 6,
+  // 溢出 / 行高 / 角标缩放：同样是对应原生 Props
+  overflowMode: 'scroll',
+  maxVisibleItems: 4,
+  itemHeight: 28,
+  minRowHeight: 118,
+  badgeScale: 0.75,
+  // 条目内部排版与外观
+  itemLineGap: 2,           // 名称与地址之间的行间距（px）
+  itemBgGradient: false,    // 条目背景是否启用渐变效果
+  itemBgGradientDir: 'to-bottom', // 渐变方向：to-bottom 上到下 | to-right 左到右
+  itemBgHover: true,        // 悬浮时是否在底色上自动加深
+  // 条目(.ec__item)颜色覆盖：空串 = 按 type/主题配色走
+  itemTextColor: '',
+  itemBgColor: ''
+})
+
+/**
+ * 工具栏统一字段表：按展示顺序排列。
+ * kind: seg=分段选项 | spacing=上下/左右两块 | number=单值步进 | color=取色
+ */
+const CONFIG_FIELDS = Object.freeze([
+  { kind: 'seg', key: 'itemAlign', label: '条目对齐', priority: 1, options: [
+    { label: '靠左', value: 'left' },
+    { label: '居中', value: 'center' }
+  ] },
+
+  { kind: 'spacing', key: 'cellPadding', label: '日期格内边距', priority: 2 },
+  { kind: 'spacing', key: 'mobileCellPadding', label: '窄屏日期格内边距', priority: 3 },
+
+  { kind: 'number', key: 'itemHorizontalPadding', label: '条目左右内边距', priority: 4, unit: 'px', step: 1 },
+  { kind: 'number', key: 'itemVerticalPadding', label: '条目上下内边距', priority: 5, unit: 'px', step: 1 },
+  { kind: 'number', key: 'itemGap', label: '条目间距', priority: 6, unit: 'px', step: 1 },
+
+  { kind: 'number', key: 'maxVisibleItems', label: '单格最多显示', priority: 7, unit: '条', step: 1, min: 1 },
+  { kind: 'number', key: 'itemHeight', label: '条目高度', priority: 8, unit: 'px', step: 1 },
+  { kind: 'number', key: 'itemLineGap', label: '名称地址间距', priority: 9, unit: 'px', step: 1 },
+
+  { kind: 'seg', key: 'itemBgGradient', label: '条目背景效果', priority: 10, options: [
+    { label: '纯色', value: false },
+    { label: '渐变', value: true }
+  ] },
+  { kind: 'seg', key: 'itemBgGradientDir', label: '渐变方向', priority: 11, options: [
+    { label: '上到下', value: 'to-bottom' },
+    { label: '左到右', value: 'to-right' }
+  ] },
+  { kind: 'seg', key: 'itemBgHover', label: '悬浮加深', priority: 12, options: [
+    { label: '开启', value: true },
+    { label: '关闭', value: false }
+  ] },
+
+  { kind: 'color', key: 'itemTextColor', label: '条目文字色', priority: 13, default: '#606266' },
+  { kind: 'color', key: 'itemBgColor', label: '条目背景色', priority: 14, default: '#f5f7fa' }
+])
+
+/** 间距控件的两个轴：vertical=上下(top/bottom)，horizontal=左右(left/right) */
+const CONFIG_SPACING_AXES = Object.freeze([
+  { key: 'vertical', label: '上下', sides: ['top', 'bottom'] },
+  { key: 'horizontal', label: '左右', sides: ['left', 'right'] }
+])
+
+function createLayoutConfig(vm) {
+  return Object.keys(DEFAULT_LAYOUT_CONFIG).reduce((config, key) => {
+    config[key] = vm[key]
+    return config
+  }, {})
+}
+
+function toCssSpacing(value, fallback) {
+  if (typeof value === 'number' && Number.isFinite(value)) return `${Math.max(0, value)}px`
+  if (typeof value === 'string' && value.trim()) return value.trim()
+  return typeof fallback === 'number' ? `${fallback}px` : fallback
+}
+
+/**
+ * 把 CSS 简写（或数字）解析成 { top, right, bottom, left } 的 px 数值。
+ * 支持 1~4 个值，如 '12px 10px' -> { top:12, right:10, bottom:12, left:10 }。
+ * 解析失败返回全 0，避免方向控件拿不到数。
+ */
+function parseSpacingToSides(value) {
+  const zero = { top: 0, right: 0, bottom: 0, left: 0 }
+  let nums = null
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    nums = [value, value, value, value]
+  } else if (typeof value === 'string') {
+    const tokens = value.trim().split(/\s+/).filter(Boolean)
+    const parsed = tokens.map((token) => {
+      const m = /^(-?\d+(?:\.\d+)?)(?:px)?$/i.exec(token)
+      return m ? Number(m[1]) : null
+    })
+    if (parsed.length && parsed.every((n) => n != null && Number.isFinite(n))) nums = parsed
+  }
+  if (!nums) return zero
+  const top = nums[0]
+  const right = nums.length >= 2 ? nums[1] : top
+  const bottom = nums.length >= 3 ? nums[2] : top
+  const left = nums.length >= 4 ? nums[3] : right
+  return { top, right, bottom, left }
+}
+
+/** 4 个方向的 px 合成 CSS 简写：全等/上下左右两两相等时尽量压缩成 1 项或 2 项 */
+function spacingFromSides(sides) {
+  const px = (v) => `${Math.max(0, Math.round(v))}px`
+  const top = sides.top
+  const right = sides.right
+  const bottom = sides.bottom
+  const left = sides.left
+  if (top === right && right === bottom && bottom === left) return px(top)
+  if (top === bottom && right === left) return `${px(top)} ${px(right)}`
+  return `${px(top)} ${px(right)} ${px(bottom)} ${px(left)}`
+}
+
+export default {
+  name: 'EventCalendar',
+
+  components: { MonthSelect, CalendarSkeleton },
+
+  // 同时支持 v-model 与 :active-month.sync
+  model: {
+    prop: 'activeMonth',
+    event: 'update:activeMonth'
+  },
+
+  props: {
+    /* ----------------------------- 数据 ----------------------------- */
+    /**
+     * 月份数据数组，默认结构：
+     * [{ month: '2026-09', monthLabel: '2026年9月',
+     *    days: [{ date: '2026-09-07', items: [{ id, label, badge, type }] }] }]
+     * 也支持直接传扁平的日期数组（自动按日期归月）。
+     */
+    data: {
+      type: Array,
+      default: () => []
+    },
+    /** 字段映射，覆盖 DEFAULT_FIELD_NAMES 中的任意项，支持 'a.b' 点路径 */
+    fieldNames: {
+      type: Object,
+      default: () => ({})
+    },
+    /** 加载中（显示骨架屏） */
+    loading: {
+      type: Boolean,
+      default: false
+    },
+    /** 骨架屏行数 */
+    skeletonRows: {
+      type: Number,
+      default: 5
+    },
+
+    /* --------------------------- 月份与轮播 --------------------------- */
+    /** 当前月份 'YYYY-MM'，支持 v-model / .sync；不传则取第一个月 */
+    activeMonth: {
+      type: String,
+      default: ''
+    },
+    /** 是否展示月份下拉 */
+    showMonthSelect: {
+      type: Boolean,
+      default: true
+    },
+    /** 是否展示左右翻月箭头 */
+    showArrows: {
+      type: Boolean,
+      default: false
+    },
+    /** 开启自动轮播 */
+    autoplay: {
+      type: Boolean,
+      default: false
+    },
+    /** 轮播间隔（毫秒），如 10000=10 秒、60000=1 分钟 */
+    autoplayInterval: {
+      type: Number,
+      default: 60000
+    },
+    /** 轮播到最后一个月后是否回到第一个 */
+    loop: {
+      type: Boolean,
+      default: true
+    },
+    /** 鼠标悬停时暂停轮播 */
+    pauseOnHover: {
+      type: Boolean,
+      default: true
+    },
+    /** 展示轮播倒计时进度条 */
+    showProgress: {
+      type: Boolean,
+      default: true
+    },
+    /** 展示轮播播放/暂停按钮 */
+    showAutoplayToggle: {
+      type: Boolean,
+      default: true
+    },
+
+    /* ----------------------------- 动效 ----------------------------- */
+    /** 月份切换动效：slide | fade | zoom | flip | none */
+    transitionEffect: {
+      type: String,
+      default: 'slide',
+      validator: (v) => ['slide', 'fade', 'zoom', 'flip', 'none'].includes(v)
+    },
+    /** 动效时长（毫秒） */
+    transitionDuration: {
+      type: Number,
+      default: 420
+    },
+    /** 单元格逐个入场的错峰动画 */
+    cellStagger: {
+      type: Boolean,
+      default: false
+    },
+
+    /* ----------------------------- 渲染 ----------------------------- */
+    /** 顶部区域是否显示 */
+    showHeader: {
+      type: Boolean,
+      default: true
+    },
+    /** 默认标题（header-left 插槽未传时生效） */
+    title: {
+      type: String,
+      default: ''
+    },
+    /** 默认副标题 */
+    subtitle: {
+      type: String,
+      default: ''
+    },
+    /** 一周起始日：0=周日（设计图默认）1=周一 */
+    firstDayOfWeek: {
+      type: Number,
+      default: 0,
+      validator: (v) => v >= 0 && v <= 6
+    },
+    /** 星期文案，下标对应 Date.getDay() */
+    weekLabels: {
+      type: Array,
+      default: () => DEFAULT_WEEK_LABELS
+    },
+    /** 单日最多显示的条目数，超出按 overflowMode 处理 */
+    maxVisibleItems: {
+      type: Number,
+      default: 4
+    },
+    /** 超出处理：scroll=出现滚动条 | collapse=折叠并显示「还有 N 项」 */
+    overflowMode: {
+      type: String,
+      default: 'scroll',
+      validator: (v) => ['scroll', 'collapse'].includes(v)
+    },
+    /** 单个条目高度（px），用于精确计算滚动区域高度 */
+    itemHeight: {
+      type: Number,
+      default: 28
+    },
+    /** 条目间距（px） */
+    itemGap: {
+      type: Number,
+      default: 6
+    },
+    /** 条目内容对齐方式 */
+    itemAlign: {
+      type: String,
+      default: 'left',
+      validator: (v) => ['left', 'center'].includes(v)
+    },
+    /** 日历根节点外边距；Number 按 px 处理，String 支持 CSS 简写 */
+    calendarMargin: {
+      type: [Number, String],
+      default: DEFAULT_LAYOUT_CONFIG.calendarMargin
+    },
+    /** 日历根节点内边距；Number 按 px 处理，String 支持 CSS 简写 */
+    calendarPadding: {
+      type: [Number, String],
+      default: DEFAULT_LAYOUT_CONFIG.calendarPadding
+    },
+    /** 顶部区域内边距；支持 CSS 简写 */
+    headerPadding: {
+      type: [Number, String],
+      default: DEFAULT_LAYOUT_CONFIG.headerPadding
+    },
+    /** 日期格内边距；支持 CSS 简写 */
+    cellPadding: {
+      type: [Number, String],
+      default: DEFAULT_LAYOUT_CONFIG.cellPadding
+    },
+    /** 768px 及以下日期格内边距；支持 CSS 简写 */
+    mobileCellPadding: {
+      type: [Number, String],
+      default: DEFAULT_LAYOUT_CONFIG.mobileCellPadding
+    },
+    /** 条目左右内边距（px），传 0 可去除 */
+    itemHorizontalPadding: {
+      type: Number,
+      default: 8,
+      validator: (v) => v >= 0
+    },
+    /** 条目上下内边距（px） */
+    itemVerticalPadding: {
+      type: Number,
+      default: DEFAULT_LAYOUT_CONFIG.itemVerticalPadding,
+      validator: (v) => v >= 0
+    },
+    /** 显示内置布局配置工具栏；生产环境默认隐藏 */
+    showConfigToolbar: {
+      type: Boolean,
+      default: false
+    },
+    /** 单元格最小高度（px），保证空行不塌陷 */
+    minRowHeight: {
+      type: Number,
+      default: 118
+    },
+    /** 右上角角标整体缩放倍率（transform scale，越小越紧凑） */
+    badgeScale: {
+      type: Number,
+      default: 0.75
+    },
+    /** 条目内名称与地址之间的行间距（px） */
+    itemLineGap: {
+      type: Number,
+      default: 2,
+      validator: (v) => v >= 0
+    },
+    /** 条目背景是否启用渐变效果（在所选底色上叠柔和渐变） */
+    itemBgGradient: {
+      type: Boolean,
+      default: false
+    },
+    /** 渐变方向：to-bottom 上到下 | to-right 左到右（仅渐变开启时生效） */
+    itemBgGradientDir: {
+      type: String,
+      default: 'to-bottom',
+      validator: (v) => ['to-bottom', 'to-right'].includes(v)
+    },
+    /** 悬浮时是否自动把条目背景调淡一档（false 则保持原色） */
+    itemBgHover: {
+      type: Boolean,
+      default: true
+    },
+    /** 相邻月份补位格子是否也渲染条目 */
+    showAdjacentItems: {
+      type: Boolean,
+      default: true
+    },
+    /** 高亮今天 */
+    highlightToday: {
+      type: Boolean,
+      default: true
+    },
+    /** 条目角标是否按 type 上色，false 则统一中性灰（更贴近原设计稿） */
+    colorful: {
+      type: Boolean,
+      default: true
+    },
+    /** 类型配色扩展/覆盖：{ talk: { color, bg } } */
+    typeColors: {
+      type: Object,
+      default: () => ({})
+    },
+    /** 日期文案格式化函数 (cell) => string */
+    dayFormatter: {
+      type: Function,
+      default: defaultDayFormatter
+    },
+    /** 月份下拉文案格式化函数 (monthKey, rawMonthItem) => string */
+    monthFormatter: {
+      type: Function,
+      default: null
+    },
+    /** 空数据文案 */
+    emptyText: {
+      type: String,
+      default: '暂无日程数据'
+    },
+    /** 单元格是否可获得焦点（键盘无障碍） */
+    cellFocusable: {
+      type: Boolean,
+      default: false
+    },
+    /** 条目(.ec__item)文字色覆盖，空串 = 按 type/主题配色 */
+    itemTextColor: {
+      type: String,
+      default: ''
+    },
+    /** 条目(.ec__item)背景色覆盖，空串 = 按 type/主题配色 */
+    itemBgColor: {
+      type: String,
+      default: ''
+    },
+    /** 主题变量覆盖，如 { primary: '#10a37f', radius: '12px' } */
+    theme: {
+      type: Object,
+      default: () => ({})
+    }
+  },
+
+  data() {
+    return {
+      /** 组件内部维护的当前月份 */
+      innerMonth: '',
+      /** 切换方向：next / prev，决定动画走向 */
+      direction: 'next',
+      /** 舞台高度，切换月份时用于高度过渡（行数可能 5 行变 6 行） */
+      stageHeight: '',
+      /** 用户主动点了暂停 */
+      manualPaused: false,
+      /** 鼠标悬停中 */
+      hovering: false,
+      /** 月份下拉展开中 */
+      selectOpen: false,
+      /** 页面切到后台 */
+      pageHidden: false,
+      /** 每次切换 +1，用于重置进度条 CSS 动画 */
+      progressKey: 0,
+      /** 骨架屏 -> 内容 的首次切换用淡入，避免莫名其妙的滑动 */
+      useFadeOnce: true,
+      /** 配置工具栏只编辑本地草稿，还原时以此为初始快照 */
+      configDraft: createLayoutConfig(this),
+      /** 初始配置快照：每个「还原」按钮回到这里 */
+      configDefaults: createLayoutConfig(this),
+      /** 复制配置按钮的即时反馈文案 */
+      copyStatus: ''
+    }
+  },
+
+  computed: {
+    /* --------------------------- 字段映射 --------------------------- */
+    fields() {
+      return { ...DEFAULT_FIELD_NAMES, ...this.fieldNames }
+    },
+
+    externalLayoutConfig() {
+      return createLayoutConfig(this)
+    },
+
+    effectiveLayoutConfig() {
+      return this.showConfigToolbar ? this.configDraft : this.externalLayoutConfig
+    },
+
+    /** 工具栏统一字段表（seg / spacing / number / color） */
+    configFields() {
+      // 渐变方向只在启用渐变时才显示
+      return CONFIG_FIELDS.filter((f) => !(f.key === 'itemBgGradientDir' && !this.configDraft.itemBgGradient))
+    },
+
+    /** 间距控件的「上下 / 左右」两组方向定义 */
+    spacingAxes() {
+      return CONFIG_SPACING_AXES
+    },
+
+    /** 实时生成的配置 JSON 文本（复制给用户 / 供展示） */
+    configJsonText() {
+      return JSON.stringify(this.getLayoutConfig(), null, 2)
+    },
+
+    /** 下面几个值统一从布局配置取：工具栏可见时用草稿，否则回落 Props */
+    cfgItemHeight() {
+      return this.effectiveLayoutConfig.itemHeight
+    },
+
+    cfgMaxVisibleItems() {
+      return this.effectiveLayoutConfig.maxVisibleItems
+    },
+
+    cfgOverflowMode() {
+      return this.effectiveLayoutConfig.overflowMode
+    },
+
+    cfgMinRowHeight() {
+      return this.effectiveLayoutConfig.minRowHeight
+    },
+
+    cfgItemBgColor() {
+      return this.effectiveLayoutConfig.itemBgColor
+    },
+
+    cfgItemBgGradient() {
+      return this.effectiveLayoutConfig.itemBgGradient
+    },
+
+    cfgGradientDir() {
+      return this.effectiveLayoutConfig.itemBgGradientDir
+    },
+
+    cfgItemBgHover() {
+      return this.effectiveLayoutConfig.itemBgHover
+    },
+
+    /* --------------------------- 数据归一化 --------------------------- */
+    /**
+     * 把外部数据统一整理成 [{ month, label, raw }]，
+     * 同时兼容「扁平日期数组」的写法。
+     */
+    normalizedMonths() {
+      const f = this.fields
+      const list = Array.isArray(this.data) ? this.data : []
+      if (!list.length) return []
+
+      // 扁平结构判定：第一项没有 days 字段但有 date 字段
+      const isFlat = getByPath(list[0], f.days) === undefined &&
+        getByPath(list[0], f.date) !== undefined
+
+      if (isFlat) {
+        const monthSet = []
+        list.forEach((day) => {
+          const monthKey = formatMonthKey(getByPath(day, f.date))
+          if (monthKey && !monthSet.includes(monthKey)) monthSet.push(monthKey)
+        })
+        return monthSet.sort().map((monthKey) => ({
+          month: monthKey,
+          label: this.resolveMonthLabel(monthKey, null),
+          raw: null
+        }))
+      }
+
+      return list
+        .map((item) => {
+          const monthKey = String(getByPath(item, f.month) || '')
+          if (!monthKey) return null
+          return {
+            month: monthKey,
+            label: this.resolveMonthLabel(monthKey, item),
+            raw: item
+          }
+        })
+        .filter(Boolean)
+    },
+
+    /** 月份下拉选项 */
+    monthOptions() {
+      return this.normalizedMonths.map((m) => ({ label: m.label, value: m.month }))
+    },
+
+    /** 'YYYY-MM-DD' -> 该日的条目数组（扁平化整份数据，便于补位格子取数） */
+    dateItemsMap() {
+      const f = this.fields
+      const map = Object.create(null)
+      const list = Array.isArray(this.data) ? this.data : []
+      if (!list.length) return map
+
+      const collectDay = (day) => {
+        const dateKey = String(getByPath(day, f.date) || '').slice(0, 10)
+        if (!dateKey) return
+        const items = getByPath(day, f.items)
+        if (!map[dateKey]) map[dateKey] = { items: [], raw: day }
+        if (Array.isArray(items)) map[dateKey].items.push(...items)
+      }
+
+      const isFlat = getByPath(list[0], f.days) === undefined &&
+        getByPath(list[0], f.date) !== undefined
+
+      if (isFlat) {
+        list.forEach(collectDay)
+      } else {
+        list.forEach((monthItem) => {
+          const days = getByPath(monthItem, f.days)
+          if (Array.isArray(days)) days.forEach(collectDay)
+        })
+      }
+      return map
+    },
+
+    /** 当前月份在下拉列表中的索引 */
+    currentIndex() {
+      return this.monthOptions.findIndex((o) => o.value === this.innerMonth)
+    },
+
+    /* --------------------------- 网格构建 --------------------------- */
+    /** 表头星期，按 firstDayOfWeek 旋转 */
+    weekHeaders() {
+      const labels = this.weekLabels.length === 7 ? this.weekLabels : DEFAULT_WEEK_LABELS
+      return Array.from({ length: 7 }, (_, i) => {
+        const weekday = (this.firstDayOfWeek + i) % 7
+        return {
+          weekday,
+          label: labels[weekday],
+          isWeekend: weekday === 0 || weekday === 6
+        }
+      })
+    },
+
+    /**
+     * 最终渲染的格子：日期矩阵 + 当天条目（已按 maxVisibleItems 处理溢出）
+     */
+    renderCells() {
+      if (!this.innerMonth) return []
+      const f = this.fields
+      const cells = buildMonthMatrix(this.innerMonth, this.firstDayOfWeek)
+
+      return cells.map((cell) => {
+        const hit = this.dateItemsMap[cell.dateKey]
+        const showItems = cell.isCurrentMonth || this.showAdjacentItems
+        const rawItems = showItems && hit ? hit.items : []
+
+        // 归一化条目，模板里直接用，避免反复取值
+        const items = rawItems.map((raw, i) => ({
+          key: getByPath(raw, f.itemKey) != null
+            ? String(getByPath(raw, f.itemKey))
+            : `${cell.dateKey}-${i}`,
+          label: getByPath(raw, f.itemLabel),
+          address: getByPath(raw, f.itemAddress),
+          badge: getByPath(raw, f.itemBadge),
+          type: getByPath(raw, f.itemType),
+          disabled: !!getByPath(raw, f.itemDisabled),
+          raw
+        }))
+
+        const overflowed = items.length > this.cfgMaxVisibleItems
+        const collapse = this.cfgOverflowMode === 'collapse' && overflowed
+        // collapse 模式留一行给「还有 N 项」
+        const visibleItems = collapse ? items.slice(0, this.cfgMaxVisibleItems - 1) : items
+
+        return {
+          ...cell,
+          dayRaw: hit ? hit.raw : null,
+          items,
+          visibleItems,
+          moreCount: collapse ? items.length - visibleItems.length : 0,
+          /** scroll 模式下是否真的会出现滚动条 */
+          scrollable: this.cfgOverflowMode === 'scroll' && overflowed
+        }
+      })
+    },
+
+    /* --------------------------- 样式相关 --------------------------- */
+    rootClass() {
+      return {
+        'ec--loading': this.loading,
+        'ec--stagger': this.cellStagger && !this.loading,
+        'ec--item-center': this.effectiveLayoutConfig.itemAlign === 'center',
+        [`ec--effect-${this.transitionEffect}`]: true
+      }
+    },
+
+    /** 主题：全部走 CSS 变量，方便外部覆盖 */
+    cssVars() {
+      const t = this.theme || {}
+      const n = this.cfgMaxVisibleItems
+      const layout = this.effectiveLayoutConfig
+      const vars = {
+        '--ec-primary': t.primary || '#3d6cf0',
+        '--ec-primary-ghost': t.primaryGhost || 'rgba(61, 108, 240, 0.12)',
+        '--ec-border': t.border || '#e4e7ed',
+        '--ec-border-light': t.borderLight || '#eef0f4',
+        '--ec-text': t.text || '#303133',
+        '--ec-text-secondary': t.textSecondary || '#606266',
+        '--ec-text-placeholder': t.textPlaceholder || '#c0c4cc',
+        '--ec-muted': t.muted || '#c8ccd4',
+        // 条目颜色：工具栏配置的条目色优先于 theme，theme 优先于默认
+        '--ec-item-bg': layout.itemBgColor || t.itemBg || '#f5f7fa',
+        '--ec-cell-hover': t.cellHover || '#fafbfd',
+        '--ec-radius': t.radius || '8px',
+        '--ec-duration': this.transitionDuration + 'ms',
+        '--ec-item-h': this.cfgItemHeight + 'px',
+        '--ec-badge-scale': Number.isFinite(Number(layout.badgeScale)) ? Number(layout.badgeScale) : 0.75,
+        '--ec-calendar-margin': toCssSpacing(layout.calendarMargin, DEFAULT_LAYOUT_CONFIG.calendarMargin),
+        '--ec-calendar-padding': toCssSpacing(layout.calendarPadding, DEFAULT_LAYOUT_CONFIG.calendarPadding),
+        '--ec-header-padding': toCssSpacing(layout.headerPadding, DEFAULT_LAYOUT_CONFIG.headerPadding),
+        '--ec-cell-padding': toCssSpacing(layout.cellPadding, DEFAULT_LAYOUT_CONFIG.cellPadding),
+        '--ec-cell-padding-mobile': toCssSpacing(layout.mobileCellPadding, DEFAULT_LAYOUT_CONFIG.mobileCellPadding),
+        '--ec-item-gap': layout.itemGap + 'px',
+        '--ec-item-padding-x': layout.itemHorizontalPadding + 'px',
+        '--ec-item-padding-y': layout.itemVerticalPadding + 'px',
+        '--ec-item-line-gap': layout.itemLineGap + 'px',
+        // 悬浮自动调淡一档（白色叠层）；关闭则为透明
+        '--ec-item-hover-mask': layout.itemBgHover === false ? 'transparent' : 'rgba(255, 255, 255, 0.18)',
+        '--ec-min-row-h': this.cfgMinRowHeight + 'px',
+        // 滚动区域最大高度 = n 个条目 + (n-1) 个间距
+        '--ec-items-max-h': `${n * this.cfgItemHeight + (n - 1) * layout.itemGap}px`
+      }
+      // 条目文字色只在显式配置时覆盖；未配置时走 --ec-text-secondary（hover 走 --ec-text）
+      if (layout.itemTextColor) vars['--ec-item-text'] = layout.itemTextColor
+      return vars
+    },
+
+    stageStyle() {
+      return this.stageHeight ? { height: this.stageHeight } : {}
+    },
+
+    itemsStyle() {
+      // collapse 模式不限制高度（本来就已经截断了），scroll 模式限高触发滚动条
+      return this.cfgOverflowMode === 'scroll'
+        ? { maxHeight: 'var(--ec-items-max-h)' }
+        : {}
+    },
+
+    /** 当前生效的过渡名 */
+    transitionName() {
+      if (this.transitionEffect === 'none') return 'ec-none'
+      if (this.useFadeOnce) return 'ec-fade'
+      if (this.transitionEffect === 'slide' || this.transitionEffect === 'flip') {
+        return `ec-${this.transitionEffect}-${this.direction}`
+      }
+      return `ec-${this.transitionEffect}`
+    },
+
+    /* --------------------------- 轮播状态 --------------------------- */
+    /** 任一条件成立即暂停 */
+    isPaused() {
+      return (
+        this.manualPaused ||
+        this.pageHidden ||
+        this.selectOpen ||
+        (this.pauseOnHover && this.hovering)
+      )
+    },
+
+    /** 轮播真正可运行的条件 */
+    autoplayRunnable() {
+      return this.autoplay && !this.loading && this.monthOptions.length > 1
+    },
+
+    showProgressBar() {
+      return this.autoplay && this.showProgress && this.autoplayRunnable
+    },
+
+    progressStyle() {
+      return {
+        animationDuration: this.autoplayInterval + 'ms',
+        animationPlayState: this.isPaused ? 'paused' : 'running'
+      }
+    },
+
+    canGoPrev() {
+      return this.loop ? this.monthOptions.length > 1 : this.currentIndex > 0
+    },
+
+    canGoNext() {
+      return this.loop
+        ? this.monthOptions.length > 1
+        : this.currentIndex > -1 && this.currentIndex < this.monthOptions.length - 1
+    },
+
+    /** 顶部插槽可用的上下文 */
+    headerScope() {
+      return {
+        month: this.innerMonth,
+        monthLabel: (this.monthOptions[this.currentIndex] || {}).label || '',
+        monthIndex: this.currentIndex,
+        monthCount: this.monthOptions.length,
+        monthOptions: this.monthOptions,
+        loading: this.loading,
+        paused: this.isPaused,
+        prev: this.prev,
+        next: this.next,
+        goTo: this.goTo,
+        toggleAutoplay: this.toggleAutoplay
+      }
+    }
+  },
+
+  watch: {
+    /** 外部改月份（v-model / .sync） */
+    activeMonth(val) {
+      if (val && val !== this.innerMonth) this.setMonth(val, 'prop')
+    },
+
+    /** 父组件通过 v-bind 更新已保存配置时，同步到工具栏草稿。 */
+    externalLayoutConfig: {
+      deep: true,
+      handler(val) {
+        this.configDraft = { ...val }
+      }
+    },
+
+    /** 数据变化后校正当前月份（比如接口返回了新的月份列表） */
+    monthOptions: {
+      immediate: true,
+      handler() {
+        this.ensureValidMonth()
+      }
+    },
+
+    loading(val) {
+      // 加载结束后重新起播，并让「骨架屏 -> 内容」用淡入
+      if (val) {
+        this.useFadeOnce = true
+        this.stopAutoplay()
+      } else {
+        this.restartAutoplay()
+      }
+    },
+
+    isPaused(val) {
+      if (val) this.pauseAutoplay()
+      else this.resumeAutoplay()
+    },
+
+    autoplay() {
+      this.restartAutoplay()
+    },
+
+    autoplayInterval() {
+      this.restartAutoplay()
+    }
+  },
+
+  created() {
+    // 计时器相关的中间状态不需要响应式，挂在实例上即可
+    this._timer = null
+    this._tickStart = 0
+    this._remaining = 0
+    this._ro = null
+  },
+
+  mounted() {
+    document.addEventListener('visibilitychange', this.handleVisibilityChange)
+    window.addEventListener('resize', this.syncStageHeight)
+    this.$nextTick(() => {
+      this.observeStage(this.$el.querySelector('.ec__panel'))
+    })
+    this.restartAutoplay()
+  },
+
+  beforeDestroy() {
+    document.removeEventListener('visibilitychange', this.handleVisibilityChange)
+    window.removeEventListener('resize', this.syncStageHeight)
+    this.stopAutoplay()
+    this.disconnectObserver()
+  },
+
+  methods: {
+    /* ========================= 布局配置 ========================= */
+    /** 间距字段某个轴的当前 px 值（vertical 取上下、horizontal 取左右） */
+    spacingAxisValue(key, axisKey) {
+      const sides = parseSpacingToSides(this.configDraft[key])
+      const axis = this.spacingAxes.find((a) => a.key === axisKey)
+      return axis ? sides[axis.sides[0]] : 0
+    },
+
+    /** 间距字段的可读简写，如 12px 10px（也用于标题 tooltip） */
+    spacingShorthand(key) {
+      return spacingFromSides(parseSpacingToSides(this.configDraft[key]))
+    },
+
+    /** 按「上下 / 左右」整轴步进 ±delta px */
+    nudgeSpacingAxis(key, axisKey, delta, event) {
+      const step = event && event.shiftKey ? 5 : 1
+      const sides = parseSpacingToSides(this.configDraft[key])
+      const axis = this.spacingAxes.find((a) => a.key === axisKey)
+      if (!axis) return
+      const current = sides[axis.sides[0]] || 0
+      const next = Math.max(0, Math.round(current + delta * step))
+      if (next === current) return
+      axis.sides.forEach((side) => { sides[side] = next })
+      this.updateLayoutConfig(key, spacingFromSides(sides))
+    },
+
+    /** 直接输入间距字段某个轴（上下/左右）的值，两端一起生效 */
+    updateSpacingAxis(key, axisKey, event) {
+      const raw = Number(event.target.value)
+      const sides = parseSpacingToSides(this.configDraft[key])
+      const axis = this.spacingAxes.find((a) => a.key === axisKey)
+      if (!axis) return
+      const next = Number.isFinite(raw) ? Math.max(0, Math.round(raw)) : 0
+      axis.sides.forEach((side) => { sides[side] = next })
+      this.updateLayoutConfig(key, spacingFromSides(sides))
+    },
+
+    /** 数值字段步进：步长取字段 step（整数 ±1、角标缩放 ±0.05），按住 Shift ×5 */
+    nudgeNumber(key, delta, event) {
+      const field = CONFIG_FIELDS.find((f) => f.key === key)
+      const unit = field && Number(field.step) ? Number(field.step) : 1
+      const multi = event && event.shiftKey ? 5 : 1
+      const current = Number(this.configDraft[key])
+      const base = Number.isFinite(current) ? current : 0
+      this.updateLayoutConfig(key, base + delta * unit * multi, 'number')
+    },
+
+    /** 取色器展示值：未配置（空串）时给一个与默认主题一致的兜底色 */
+    colorValue(key) {
+      const hit = CONFIG_FIELDS.find((f) => f.key === key && f.kind === 'color')
+      return this.configDraft[key] || (hit ? hit.default : '#000000')
+    },
+
+    /** 还原颜色为默认配色（存空串） */
+    resetColor(key) {
+      this.updateLayoutConfig(key, '')
+    },
+
+    /** 还原某个配置项到初始快照（configDefaults） */
+    resetField(key) {
+      if (!Object.prototype.hasOwnProperty.call(this.configDefaults, key)) return
+      this.$set(this.configDraft, key, this.configDefaults[key])
+      this.copyStatus = ''
+      this.$emit('config-change', this.getLayoutConfig())
+    },
+
+    updateLayoutConfig(key, value, inputType) {
+      let nextValue = value
+      if (inputType === 'number') {
+        const parsed = Number(value)
+        const field = CONFIG_FIELDS.find((f) => f.key === key)
+        const min = field && typeof field.min === 'number' ? field.min : 0
+        nextValue = Number.isFinite(parsed)
+          ? Math.max(min, Math.round(parsed * 100) / 100)
+          : min
+      }
+      this.$set(this.configDraft, key, nextValue)
+      this.copyStatus = ''
+      this.$emit('config-change', this.getLayoutConfig())
+    },
+
+    /** 返回可直接 <EventCalendar v-bind="config" /> 的配置对象。 */
+    getLayoutConfig() {
+      return { ...this.effectiveLayoutConfig }
+    },
+
+    /** 复制当前配置 JSON 到剪贴板（用户直接粘贴发回，研发贴到组件上即可） */
+    copyLayoutConfig() {
+      const json = this.configJsonText
+      const fallback = () => {
+        if (typeof document === 'undefined') {
+          this.copyStatus = '已复制，可粘贴发送给研发。'
+          return
+        }
+        const ta = document.createElement('textarea')
+        ta.value = json
+        ta.setAttribute('readonly', '')
+        ta.style.position = 'fixed'
+        ta.style.opacity = '0'
+        document.body.appendChild(ta)
+        ta.select()
+        let ok = false
+        try { ok = document.execCommand('copy') } catch (e) { ok = false }
+        document.body.removeChild(ta)
+        this.copyStatus = ok
+          ? '已复制，可粘贴发送给研发。'
+          : '复制失败，请手动全选下方 JSON 后复制。'
+      }
+      if (typeof navigator !== 'undefined' && navigator.clipboard && window.isSecureContext) {
+        navigator.clipboard.writeText(json).then(() => {
+          this.copyStatus = '已复制，可粘贴发送给研发。'
+        }, fallback)
+      } else {
+        fallback()
+      }
+    },
+
+    /* ========================= 月份切换 ========================= */
+    /**
+     * 切换到指定月份
+     * @param {String} month  'YYYY-MM'
+     * @param {String} source 触发来源：select / arrow / autoplay / prop / api
+     */
+    setMonth(month, source = 'api') {
+      if (!month || month === this.innerMonth) return
+
+      const from = this.currentIndex
+      const to = this.monthOptions.findIndex((o) => o.value === month)
+
+      // 决定动画方向：轮播从末尾回到开头时仍按「向后」处理，视觉更连贯
+      if (from > -1 && to > -1) {
+        const wrapForward = source === 'autoplay' && to < from
+        this.direction = to > from || wrapForward ? 'next' : 'prev'
+      }
+
+      // 第一次从骨架屏切到内容用淡入，之后才用配置的动效
+      if (this.innerMonth) this.useFadeOnce = false
+
+      this.innerMonth = month
+      this.progressKey++
+
+      this.$emit('update:activeMonth', month)
+      this.$emit('month-change', month, {
+        index: to,
+        source,
+        option: this.monthOptions[to] || null,
+        raw: (this.normalizedMonths[to] || {}).raw || null
+      })
+
+      // 用户手动操作后重新计时，避免刚点完就被轮播切走
+      if (source !== 'autoplay') this.restartAutoplay()
+    },
+
+    /** 上一个月 */
+    prev(source = 'arrow') {
+      const len = this.monthOptions.length
+      if (len < 2) return
+      let idx = this.currentIndex - 1
+      if (idx < 0) {
+        if (!this.loop) return
+        idx = len - 1
+      }
+      this.setMonth(this.monthOptions[idx].value, source)
+    },
+
+    /** 下一个月 */
+    next(source = 'arrow') {
+      const len = this.monthOptions.length
+      if (len < 2) return
+      let idx = this.currentIndex + 1
+      if (idx >= len) {
+        if (!this.loop) {
+          this.stopAutoplay()
+          this.$emit('autoplay-end')
+          return
+        }
+        idx = 0
+      }
+      this.setMonth(this.monthOptions[idx].value, source)
+    },
+
+    /** 跳到第 n 个月份（0 开始） */
+    goTo(index, source = 'api') {
+      const opt = this.monthOptions[index]
+      if (opt) this.setMonth(opt.value, source)
+    },
+
+    /** 当前月份失效时（数据变更/首次加载）自动落到一个合法值 */
+    ensureValidMonth() {
+      const options = this.monthOptions
+      if (!options.length) {
+        this.innerMonth = ''
+        return
+      }
+      const exists = options.some((o) => o.value === this.innerMonth)
+      if (exists) return
+
+      const preferred = options.some((o) => o.value === this.activeMonth)
+        ? this.activeMonth
+        : options[0].value
+
+      this.innerMonth = preferred
+      if (preferred !== this.activeMonth) this.$emit('update:activeMonth', preferred)
+    },
+
+    resolveMonthLabel(monthKey, rawItem) {
+      if (typeof this.monthFormatter === 'function') {
+        return this.monthFormatter(monthKey, rawItem)
+      }
+      const custom = rawItem ? getByPath(rawItem, this.fields.monthLabel) : null
+      return custom || defaultMonthFormatter(monthKey)
+    },
+
+    /* ========================= 轮播控制 ========================= */
+    /** 重新开始计时（完整间隔） */
+    restartAutoplay() {
+      this.stopAutoplay()
+      if (!this.autoplayRunnable) return
+      this._remaining = this.autoplayInterval
+      this.progressKey++
+      if (!this.isPaused) this.scheduleTick(this._remaining)
+    },
+
+    /** 挂一个定时器，到点切下一个月 */
+    scheduleTick(delay) {
+      this.clearTimer()
+      this._tickStart = Date.now()
+      this._timer = setTimeout(() => {
+        this._timer = null
+        this.next('autoplay')
+        // next() 内部不会重置计时（source=autoplay），这里续上下一轮
+        this._remaining = this.autoplayInterval
+        this.progressKey++
+        if (!this.isPaused && this.autoplayRunnable) this.scheduleTick(this._remaining)
+      }, delay)
+    },
+
+    /** 暂停：把剩余时间记下来，恢复时接着走，进度条不会跳 */
+    pauseAutoplay() {
+      if (!this._timer) return
+      const elapsed = Date.now() - this._tickStart
+      this._remaining = Math.max(0, this._remaining - elapsed)
+      this.clearTimer()
+    },
+
+    resumeAutoplay() {
+      if (this._timer || !this.autoplayRunnable || this.isPaused) return
+      this.scheduleTick(this._remaining > 0 ? this._remaining : this.autoplayInterval)
+    },
+
+    stopAutoplay() {
+      this.clearTimer()
+      this._remaining = this.autoplayInterval
+    },
+
+    clearTimer() {
+      if (this._timer) {
+        clearTimeout(this._timer)
+        this._timer = null
+      }
+    },
+
+    /** 播放 / 暂停按钮 */
+    toggleAutoplay() {
+      this.manualPaused = !this.manualPaused
+      this.$emit('autoplay-toggle', !this.manualPaused)
+    },
+
+    handleMouseEnter() {
+      this.hovering = true
+    },
+
+    handleMouseLeave() {
+      this.hovering = false
+    },
+
+    handleVisibilityChange() {
+      this.pageHidden = document.hidden
+    },
+
+    handleSelectChange(value) {
+      this.setMonth(value, 'select')
+    },
+
+    handleSelectVisibleChange(visible) {
+      this.selectOpen = visible
+    },
+
+    /* ========================= 舞台高度 ========================= */
+    /**
+     * 月份行数可能是 5 行或 6 行，直接切换会导致高度突变。
+     * 这里显式把舞台高度锁到当前面板高度，配合 CSS transition 平滑过渡。
+     */
+    observeStage(el) {
+      this.disconnectObserver()
+      if (!el) return
+
+      this.syncStageHeightOf(el)
+
+      if (typeof ResizeObserver !== 'undefined') {
+        this._ro = new ResizeObserver(() => this.syncStageHeightOf(el))
+        this._ro.observe(el)
+      }
+    },
+
+    disconnectObserver() {
+      if (this._ro) {
+        this._ro.disconnect()
+        this._ro = null
+      }
+    },
+
+    syncStageHeightOf(el) {
+      if (!el || !el.offsetParent) return
+      const h = el.offsetHeight
+      if (h > 0) this.stageHeight = h + 'px'
+    },
+
+    /** 窗口尺寸变化时重新测量（文字换行会改变行高） */
+    syncStageHeight() {
+      const el = this.$el && this.$el.querySelector('.ec__panel:not([class*="-leave-"])')
+      this.syncStageHeightOf(el)
+    },
+
+    /* ========================= 过渡钩子 ========================= */
+    handleBeforeEnter(el) {
+      // 进场元素先量一次高度，让 stage 的高度动画和内容切换同步开始
+      this.$nextTick(() => this.syncStageHeightOf(el))
+    },
+
+    handleEnter(el) {
+      // 面板是新 DOM，需要重新观察
+      this.observeStage(el)
+    },
+
+    handleAfterEnter(el) {
+      this.syncStageHeightOf(el)
+      this.$emit('transition-end', this.innerMonth)
+    },
+
+    /* ========================= 交互事件 ========================= */
+    /** 单元格样式类 */
+    cellClass(cell) {
+      return {
+        'is-other-month': !cell.isCurrentMonth,
+        'is-today': cell.isToday && this.highlightToday,
+        'is-weekend': cell.isWeekend,
+        'has-items': cell.items.length > 0
+      }
+    },
+
+    /** 传给 day / day-header / items / day-empty 插槽的上下文 */
+    cellScope(cell) {
+      return {
+        day: cell,
+        date: cell.date,
+        dateKey: cell.dateKey,
+        items: cell.items,
+        visibleItems: cell.visibleItems,
+        raw: cell.dayRaw,
+        isCurrentMonth: cell.isCurrentMonth,
+        isToday: cell.isToday,
+        isWeekend: cell.isWeekend,
+        label: this.dayFormatter(cell)
+      }
+    },
+
+    /** 传给 item 插槽的上下文 */
+    itemScope(entry, cell, index) {
+      return {
+        item: entry.raw,
+        raw: entry.raw,
+        label: entry.label,
+        address: entry.address,
+        badge: entry.badge,
+        type: entry.type,
+        disabled: entry.disabled,
+        index,
+        day: cell,
+        dateKey: cell.dateKey
+      }
+    },
+
+    handleDayClick(cell, event) {
+      this.$emit('day-click', this.cellScope(cell), event)
+    },
+
+    handleItemClick(entry, cell, index, event) {
+      if (entry.disabled) return
+      this.$emit('item-click', this.itemScope(entry, cell, index), event)
+    },
+
+    handleBadgeClick(entry, cell, index, event) {
+      if (entry.disabled) return
+      // 未监听 tag-click 时，点角标退化成点条目，避免「点了没反应」
+      if (this.$listeners['tag-click']) {
+        this.$emit('tag-click', this.itemScope(entry, cell, index), event)
+      } else {
+        this.handleItemClick(entry, cell, index, event)
+      }
+    },
+
+    handleMoreClick(cell, event) {
+      this.$emit('more-click', this.cellScope(cell), event)
+    },
+
+    hasText(value) {
+      return value !== undefined && value !== null && String(value).trim() !== ''
+    },
+
+    itemTitle(entry) {
+      const label = this.hasText(entry.label) ? String(entry.label) : ''
+      const address = this.hasText(entry.address) ? `\n${entry.address}` : ''
+      return label + address
+    },
+
+    /** 大学名称超过 7 个字符时使用 12px，否则使用 14px。 */
+    isLongItemLabel(label) {
+      const text = label == null ? '' : String(label)
+      return text.length > 7
+    },
+
+    /* ========================= 配色 ========================= */
+    resolveTypeColor(type) {
+      const merged = { ...BUILTIN_TYPE_COLORS, ...this.typeColors }
+      return merged[type] || merged.default || BUILTIN_TYPE_COLORS.default
+    },
+
+    itemStyle(entry) {
+      if (!this.colorful || !entry.type) return {}
+      const c = this.resolveTypeColor(entry.type)
+      // 只把颜色写进 CSS 变量，具体怎么用交给样式表，方便外部再覆盖
+      return { '--ec-item-accent': c.color, '--ec-item-accent-bg': c.bg }
+    },
+
+    badgeStyle(entry) {
+      if (!this.colorful || !entry.type) return {}
+      const c = this.resolveTypeColor(entry.type)
+      return { color: c.color, backgroundColor: c.bg }
+    }
+  }
+}
+</script>
+
+<style scoped>
+/* ==================================================================
+ * 布局：整体用 CSS Grid，7 列等宽。
+ * 同一行的格子会自动拉伸到该行最高格子的高度，
+ * 因此「行高取决于条目最多的那一天」是天然满足的，无需 JS 计算。
+ * ================================================================== */
+.ec {
+  position: relative;
+  box-sizing: border-box;
+  width: auto;
+  margin: var(--ec-calendar-margin);
+  padding: var(--ec-calendar-padding);
+  color: var(--ec-text);
+  font-size: 14px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* -------------------------- 布局配置工具栏 -------------------------- */
+.ec__config {
+  margin-bottom: 16px;
+  padding: 14px;
+  border: 1px solid var(--ec-border);
+  border-radius: calc(var(--ec-radius) + 2px);
+  background: #f8fafc;
+}
+
+.ec__config-head,
+.ec__config-actions,
+.ec__config-segment {
+  display: flex;
+  align-items: center;
+}
+
+.ec__config-head {
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+.ec__config-title {
+  color: var(--ec-text);
+  font-size: 14px;
+}
+
+.ec__config-caption {
+  margin-left: 8px;
+  color: var(--ec-text-secondary);
+  font-size: 12px;
+}
+
+.ec__config-actions {
+  gap: 8px;
+}
+
+.ec__config-btn,
+.ec__config-segment button {
+  min-height: 34px;
+  border: 1px solid var(--ec-border);
+  border-radius: 6px;
+  background: #fff;
+  color: var(--ec-text-secondary);
+  font: inherit;
+  font-size: 12px;
+  cursor: pointer;
+  transition: color 0.18s, border-color 0.18s, background-color 0.18s;
+}
+
+.ec__config-btn {
+  padding: 0 12px;
+}
+
+.ec__config-btn.is-primary,
+.ec__config-segment button.is-active {
+  border-color: var(--ec-primary);
+  background: var(--ec-primary);
+  color: #fff;
+}
+
+.ec__config-btn:hover,
+.ec__config-segment button:hover {
+  border-color: var(--ec-primary);
+  color: var(--ec-primary);
+}
+
+.ec__config-btn.is-primary:hover,
+.ec__config-segment button.is-active:hover {
+  color: #fff;
+  opacity: 0.9;
+}
+
+.ec__config-btn:focus-visible,
+.ec__config-segment button:focus-visible,
+.ec__stepper:focus-within,
+.ec__reset-btn:focus-visible,
+.ec__config input[type='color']:focus-visible {
+  outline: 2px solid var(--ec-primary);
+  outline-offset: 2px;
+}
+
+/* 自带 +/− 步进按钮，隐藏数字框原生上下箭头 */
+.ec__config input[type='number'] {
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+
+.ec__config input[type='number']::-webkit-outer-spin-button,
+.ec__config input[type='number']::-webkit-inner-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+/* 取色器只保留色块 */
+.ec__config input[type='color'] {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 34px;
+  height: 34px;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+
+.ec__config input[type='color']::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.ec__config input[type='color']::-webkit-color-swatch,
+.ec__config input[type='color']::-moz-color-swatch {
+  border: 1px solid var(--ec-border);
+  border-radius: 8px;
+}
+
+/* 字段网格：默认 5 列一排，卡片更小更矮 */
+.ec__config-list {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  gap: 8px;
+}
+
+/* 每个字段一张白色小卡片 */
+.ec__config-block {
+  min-width: 0;
+  margin: 0;
+  padding: 8px;
+  border: 1px solid var(--ec-border);
+  border-radius: 8px;
+  background: #fff;
+}
+
+.ec__config-block--seg {
+  display: flex;
+  flex-direction: column;
+}
+
+.ec__config-label {
+  display: flex;
+  align-items: baseline;
+  gap: 3px;
+  flex-wrap: wrap;
+  margin: 0 0 6px;
+  color: var(--ec-text-secondary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.ec__config-block--color .ec__config-label {
+  margin: 0;
+}
+
+.ec__config-priority {
+  color: var(--ec-primary);
+  font-weight: 600;
+}
+
+.ec__config-shorthand {
+  margin-left: 6px;
+  max-width: 55%;
+  overflow: hidden;
+  color: var(--ec-text-placeholder);
+  font-family: Consolas, Monaco, monospace;
+  font-size: 10px;
+  font-weight: 400;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ec__config-segment button {
+  min-height: 28px;
+  flex: 1;
+  padding: 0 8px;
+}
+
+.ec__config-segment button + button {
+  margin-left: 6px;
+}
+
+/* ------------ 间距控件：每个字段只拆「上下」「左右」两大块 ------------ */
+.ec__spacing {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.ec__spacing-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.ec__spacing-row-label {
+  flex: none;
+  width: 30px;
+  color: var(--ec-text-secondary);
+  font-size: 11px;
+}
+
+.ec__spacing-row .ec__stepper {
+  flex: 1;
+  min-width: 0;
+}
+
+/* ------------ 单值数值字段：输入框左右包 −/+ ------------ */
+.ec__stepper {
+  display: flex;
+  align-items: stretch;
+  height: 30px;
+  border: 1px solid var(--ec-border);
+  border-radius: 6px;
+  background: #fff;
+}
+
+.ec__step-btn {
+  flex: none;
+  width: 27px;
+  border: 0;
+  background: transparent;
+  color: var(--ec-text-secondary);
+  font-size: 15px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.16s, background-color 0.16s;
+}
+
+.ec__step-btn:first-child {
+  border-right: 1px solid var(--ec-border-light);
+}
+
+.ec__step-btn:last-child {
+  border-left: 1px solid var(--ec-border-light);
+}
+
+.ec__step-btn:hover {
+  color: var(--ec-primary);
+  background: var(--ec-primary-ghost);
+}
+
+.ec__stepper-input {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+}
+
+.ec__stepper-input input {
+  width: 100%;
+  height: 100%;
+  border: 0;
+  outline: 0;
+  padding: 0 22px 0 4px;
+  background: transparent;
+  color: var(--ec-text);
+  font: inherit;
+  font-size: 11px;
+  text-align: center;
+}
+
+.ec__stepper-unit {
+  position: absolute;
+  top: 50%;
+  right: 6px;
+  transform: translateY(-50%);
+  color: var(--ec-text-placeholder);
+  font-size: 10px;
+  pointer-events: none;
+}
+
+/* ------------ 颜色控件（并入字段网格的小卡片） ------------ */
+.ec__config-block--color {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.ec__config-block--color input[type='color'] {
+  width: 28px;
+  height: 28px;
+  border-radius: 6px;
+}
+
+.ec__color-swatch {
+  flex: none;
+  width: 30px;
+  height: 30px;
+}
+
+.ec__color-meta {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.ec__color-hex {
+  margin-top: 1px;
+  color: var(--ec-text);
+  font-family: Consolas, Monaco, monospace;
+  font-size: 11px;
+}
+
+.ec__reset-btn {
+  flex: none;
+  height: 24px;
+  padding: 0 7px;
+  border: 1px solid var(--ec-border);
+  border-radius: 6px;
+  background: #fff;
+  color: var(--ec-text-secondary);
+  font-size: 10px;
+  cursor: pointer;
+}
+
+.ec__reset-btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
+.ec__reset-btn:hover:not(:disabled) {
+  border-color: var(--ec-primary);
+  color: var(--ec-primary);
+}
+
+/* 卡片标题行右上角的「还原」 */
+.ec__config-reset {
+  flex: none;
+  align-self: center;
+  margin-left: auto;
+  padding: 0 6px;
+  height: 20px;
+  border: 1px solid transparent;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--ec-text-placeholder);
+  font-size: 10px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.16s, border-color 0.16s, background-color 0.16s;
+}
+
+.ec__config-reset:hover {
+  border-color: var(--ec-border);
+  background: #fff;
+  color: var(--ec-primary);
+}
+
+/* ------------ 配置 JSON 输出区 ------------ */
+.ec__config-output {
+  margin-top: 10px;
+}
+
+.ec__config-json {
+  max-height: 170px;
+  margin: 0;
+  padding: 10px 12px;
+  overflow: auto;
+  border-radius: 8px;
+  background: #111827;
+  color: #e5e7eb;
+  font: 11px/1.6 Consolas, Monaco, monospace;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.ec__config-feedback {
+  min-height: 16px;
+  margin-top: 6px;
+  color: #059669;
+  font-size: 12px;
+}
+
+@media (max-width: 1100px) {
+  .ec__config-list {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 900px) {
+  .ec__config-list {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 640px) {
+  .ec__config-list {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .ec__spacing-row-label {
+    width: 26px;
+  }
+}
+
+@media (max-width: 420px) {
+  .ec__config-list {
+    grid-template-columns: 1fr;
+  }
+}
+
+.ec *,
+.ec *::before,
+.ec *::after {
+  box-sizing: border-box;
+}
+
+/* ------------------------------ 顶部 ------------------------------ */
+.ec__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: var(--ec-header-padding);
+}
+
+.ec__header-left {
+  flex: 1;
+  min-width: 0;
+}
+
+.ec__header-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: none;
+}
+
+.ec__title-group {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.ec__title {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--ec-text);
+}
+
+.ec__subtitle {
+  font-size: 13px;
+  color: var(--ec-text-secondary);
+}
+
+.ec__icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  padding: 0;
+  border: 1px solid var(--ec-border);
+  border-radius: var(--ec-radius);
+  background: #fff;
+  color: var(--ec-text-secondary);
+  cursor: pointer;
+  transition: color 0.2s, border-color 0.2s, background-color 0.2s;
+}
+
+.ec__icon-btn svg {
+  width: 16px;
+  height: 16px;
+}
+
+.ec__icon-btn:hover:not(:disabled) {
+  color: var(--ec-primary);
+  border-color: var(--ec-primary);
+  background: var(--ec-primary-ghost);
+}
+
+.ec__icon-btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
+/* ---------------------------- 轮播进度条 ---------------------------- */
+.ec__progress {
+  height: 2px;
+  margin-bottom: 8px;
+  border-radius: 2px;
+  background: var(--ec-border-light);
+  overflow: hidden;
+}
+
+.ec__progress-inner {
+  height: 100%;
+  width: 0;
+  border-radius: 2px;
+  background: var(--ec-primary);
+  animation-name: ec-progress;
+  animation-timing-function: linear;
+  animation-fill-mode: forwards;
+}
+
+@keyframes ec-progress {
+  from { width: 0; }
+  to { width: 100%; }
+}
+
+/* ---------------------------- 星期表头 ---------------------------- */
+.ec__weekdays {
+  display: grid;
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+  border-bottom: 1px solid var(--ec-border);
+}
+
+.ec__weekday {
+  padding: 10px 8px;
+  text-align: center;
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--ec-text-secondary);
+}
+
+.ec__weekday.is-weekend {
+  color: var(--ec-text-placeholder);
+}
+
+/* ---------------------------- 舞台 / 面板 ---------------------------- */
+.ec__stage {
+  position: relative;
+  overflow: hidden;
+  transition: height var(--ec-duration) cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.ec__panel {
+  width: 100%;
+}
+
+.ec__grid {
+  display: grid;
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+  /* 行高下限固定，上限交给内容撑开 —— 同行等高由 grid 保证 */
+  grid-auto-rows: minmax(var(--ec-min-row-h), auto);
+}
+
+/* ------------------------------ 单元格 ------------------------------ */
+.ec__cell {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding: var(--ec-cell-padding);
+  border-right: 1px solid var(--ec-border-light);
+  border-bottom: 1px solid var(--ec-border-light);
+  transition: background-color 0.2s;
+}
+
+.ec__cell:nth-child(7n) {
+  border-right: none;
+}
+
+/* 最后一行去掉底边框 */
+.ec__grid > .ec__cell:nth-last-child(-n + 7) {
+  border-bottom: none;
+}
+
+.ec__cell:hover {
+  background: var(--ec-cell-hover);
+}
+
+.ec__cell:focus-visible {
+  outline: 2px solid var(--ec-primary);
+  outline-offset: -2px;
+}
+
+/* 非当月日期整体置灰 */
+.ec__cell.is-other-month {
+  background: #fcfcfd;
+}
+
+.ec__cell.is-other-month .ec__day-label {
+  color: var(--ec-muted);
+}
+
+.ec__cell.is-other-month .ec__item {
+  opacity: 0.55;
+}
+
+/* ------------------------------ 日期行 ------------------------------ */
+.ec__day-head {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 5px;
+  margin-bottom: 10px;
+  min-height: 20px;
+}
+
+.ec__day-label {
+  font-size: 14px;
+  color: var(--ec-text);
+}
+
+.ec__cell.is-today .ec__day-label {
+  color: var(--ec-primary);
+  font-weight: 600;
+}
+
+.ec__today-dot {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--ec-primary);
+}
+
+/* ------------------------------ 条目列表 ------------------------------ */
+.ec__items-wrap {
+  flex: 1;
+  min-height: 0;
+}
+
+.ec__items {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ec-item-gap);
+  overflow-y: auto;
+  overflow-x: hidden;
+  /* 滚动到边界时不把滚动传递给外层页面 */
+  overscroll-behavior: contain;
+}
+
+/* 出现滚动条时右侧留一点空隙，避免内容被压住 */
+.ec__items.is-scrollable {
+  padding-right: 4px;
+}
+
+.ec__items::-webkit-scrollbar {
+  width: 4px;
+}
+
+.ec__items::-webkit-scrollbar-thumb {
+  background: #d8dce4;
+  border-radius: 2px;
+}
+
+.ec__items::-webkit-scrollbar-thumb:hover {
+  background: #c0c4cc;
+}
+
+.ec__items::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+/* ------------------------------ 单个条目 ------------------------------ */
+.ec__item {
+  position: relative;
+  flex: none;
+  display: flex;
+  align-items: center;
+  min-height: var(--ec-item-h);
+  padding: var(--ec-item-padding-y) var(--ec-item-padding-x);
+  border-radius: 4px;
+  background: var(--ec-item-bg);
+  /* 未显式配置文字色时沿用次要文字色；hover 回落到主文字色 */
+  color: var(--ec-item-text, var(--ec-text-secondary));
+  cursor: pointer;
+  transition: background-color 0.18s, color 0.18s, box-shadow 0.18s;
+}
+
+/* 注意：外层 .ec__items 有 overflow-x: hidden（滚动条需要），
+ * 所以 hover 不能用水平位移，否则会被裁切；这里改用内阴影。
+ * 悬浮背景 = 在底色上叠一层半透明白（--ec-item-hover-mask），自动调淡一档；
+ * 文字画在阴影之上，不受影响。item-bg-hover=false 时 mask 为透明。 */
+.ec__item:hover {
+  color: var(--ec-item-text, var(--ec-text));
+  box-shadow:
+    inset 0 0 0 9999px var(--ec-item-hover-mask, rgba(255, 255, 255, 0.18)),
+    inset 0 0 0 1px rgba(0, 0, 0, 0.08);
+}
+
+/* 渐变背景：纯色底上叠一层白色，默认上→下 */
+.ec__item.is-bg-gradient {
+  background-image: linear-gradient(
+    180deg,
+    rgba(255, 255, 255, 0.55) 0%,
+    rgba(255, 255, 255, 0.12) 46%,
+    rgba(255, 255, 255, 0) 74%
+  );
+}
+
+/* 渐变方向：左→右 */
+.ec__item.is-bg-gradient.is-bg-gradient-h {
+  background-image: linear-gradient(
+    90deg,
+    rgba(255, 255, 255, 0.55) 0%,
+    rgba(255, 255, 255, 0.12) 46%,
+    rgba(255, 255, 255, 0) 74%
+  );
+}
+
+.ec__item.is-colorful:hover {
+  background: var(--ec-item-accent-bg, var(--ec-item-bg));
+  color: var(--ec-item-text, var(--ec-item-accent, var(--ec-text)));
+  box-shadow:
+    inset 0 0 0 9999px rgba(255, 255, 255, 0.15),
+    inset 0 0 0 1px var(--ec-item-accent-bg, transparent);
+}
+
+.ec__item.is-disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.ec__item.is-disabled:hover {
+  box-shadow: none;
+}
+
+.ec__item-content {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.ec--item-center .ec__item {
+  justify-content: center;
+}
+
+.ec--item-center .ec__item-content {
+  align-items: center;
+  text-align: center;
+}
+
+.ec__item-label,
+.ec__item-address {
+  display: block;
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.ec__item-label {
+  font-size: 14px;
+  line-height: 16px;
+}
+
+.ec__item-label.is-long {
+  font-size: 12px;
+}
+
+.ec__item-address {
+  /* 名称与地址的行间距可配（item-line-gap） */
+  margin-top: var(--ec-item-line-gap, 2px);
+  font-size: 12px;
+  line-height: 16px;
+}
+
+/* 角标：贴在条目右上角，与设计图一致 */
+.ec__item-badge {
+  position: absolute;
+  top: 0;
+  right: 0;
+  padding: 0 4px;
+  border-radius: 0 4px 0 4px;
+  background: rgba(0, 0, 0, 0.06);
+  color: var(--ec-text-placeholder);
+  font-size: 12px;
+  line-height: 16px;
+  white-space: nowrap;
+  cursor: pointer;
+  /* 字号保持 12px 渲染，scale 倍率由配置 badge-scale 控制（默认 0.75）；
+   * 锚点在右上角，缩放后仍紧贴条目右上角，不占内容宽度 */
+  transform: scale(var(--ec-badge-scale, 0.75));
+  transform-origin: top right;
+  transition: filter 0.18s;
+}
+
+.ec__item-badge:hover {
+  filter: brightness(0.92);
+}
+
+/* 「还有 N 项」 */
+.ec__more {
+  flex: none;
+  padding: 2px 8px;
+  color: var(--ec-primary);
+  font-size: 12px;
+  text-align: center;
+  cursor: pointer;
+  border-radius: 4px;
+}
+
+.ec__more:hover {
+  background: var(--ec-primary-ghost);
+}
+
+/* ------------------------------ 空状态 ------------------------------ */
+.ec__empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 60px 20px;
+  color: var(--ec-text-placeholder);
+}
+
+.ec__empty-icon {
+  width: 56px;
+  height: 56px;
+}
+
+.ec__empty-text {
+  margin: 0;
+  font-size: 14px;
+}
+
+/* ==================================================================
+ * 切换动效
+ * 离场元素统一 absolute 脱离文档流，
+ * 这样舞台高度只由进场元素决定，两者可以同时播放动画。
+ * ================================================================== */
+.ec-fade-leave-active,
+.ec-zoom-leave-active,
+.ec-none-leave-active,
+.ec-slide-next-leave-active,
+.ec-slide-prev-leave-active,
+.ec-flip-next-leave-active,
+.ec-flip-prev-leave-active {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+}
+
+.ec-fade-enter-active,
+.ec-fade-leave-active,
+.ec-zoom-enter-active,
+.ec-zoom-leave-active,
+.ec-slide-next-enter-active,
+.ec-slide-next-leave-active,
+.ec-slide-prev-enter-active,
+.ec-slide-prev-leave-active,
+.ec-flip-next-enter-active,
+.ec-flip-next-leave-active,
+.ec-flip-prev-enter-active,
+.ec-flip-prev-leave-active {
+  transition:
+    transform var(--ec-duration) cubic-bezier(0.4, 0, 0.2, 1),
+    opacity var(--ec-duration) ease;
+  will-change: transform, opacity;
+}
+
+/* fade */
+.ec-fade-enter,
+.ec-fade-leave-to {
+  opacity: 0;
+}
+
+/* slide：向后翻从右侧进、向前翻从左侧进 */
+.ec-slide-next-enter {
+  opacity: 0;
+  transform: translateX(6%);
+}
+.ec-slide-next-leave-to {
+  opacity: 0;
+  transform: translateX(-6%);
+}
+.ec-slide-prev-enter {
+  opacity: 0;
+  transform: translateX(-6%);
+}
+.ec-slide-prev-leave-to {
+  opacity: 0;
+  transform: translateX(6%);
+}
+
+/* zoom */
+.ec-zoom-enter {
+  opacity: 0;
+  transform: scale(0.97);
+}
+.ec-zoom-leave-to {
+  opacity: 0;
+  transform: scale(1.03);
+}
+
+/* flip：带透视的 3D 翻页 */
+.ec--effect-flip .ec__stage {
+  perspective: 1600px;
+}
+.ec-flip-next-enter,
+.ec-flip-prev-enter,
+.ec-flip-next-leave-to,
+.ec-flip-prev-leave-to {
+  opacity: 0;
+}
+.ec-flip-next-enter {
+  transform: rotateY(9deg) translateX(5%);
+}
+.ec-flip-next-leave-to {
+  transform: rotateY(-9deg) translateX(-5%);
+}
+.ec-flip-prev-enter {
+  transform: rotateY(-9deg) translateX(-5%);
+}
+.ec-flip-prev-leave-to {
+  transform: rotateY(9deg) translateX(5%);
+}
+
+/* ------------------------- 单元格错峰入场 -------------------------
+ * 面板每次切月都是全新 DOM，CSS 动画会自动重放，无需额外 JS 触发。
+ * ---------------------------------------------------------------- */
+.ec--stagger .ec__cell {
+  animation: ec-cell-in 0.42s cubic-bezier(0.22, 1, 0.36, 1) both;
+  /* 按格子序号递增延迟，形成从左上到右下的波浪 */
+  animation-delay: calc(var(--ec-i, 0) * 12ms);
+}
+
+@keyframes ec-cell-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* ------------------------- 无动效 / 降级 ------------------------- */
+.ec--effect-none .ec__stage {
+  transition: none;
+}
+
+/* 系统开启「减少动态效果」时关闭全部动画 */
+@media (prefers-reduced-motion: reduce) {
+  .ec__stage,
+  .ec__item,
+  .ec__cell,
+  .ec__icon-btn,
+  .ec-fade-enter-active,
+  .ec-fade-leave-active,
+  .ec-zoom-enter-active,
+  .ec-zoom-leave-active,
+  .ec-slide-next-enter-active,
+  .ec-slide-next-leave-active,
+  .ec-slide-prev-enter-active,
+  .ec-slide-prev-leave-active,
+  .ec-flip-next-enter-active,
+  .ec-flip-next-leave-active,
+  .ec-flip-prev-enter-active,
+  .ec-flip-prev-leave-active {
+    transition: none !important;
+  }
+  .ec--stagger .ec__cell,
+  .ec__progress-inner {
+    animation: none !important;
+  }
+}
+
+/* ------------------------------ 响应式 ------------------------------ */
+@media (max-width: 768px) {
+  .ec__config-head {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+  .ec__config-actions {
+    width: 100%;
+  }
+  .ec__config-btn {
+    flex: 1;
+    min-height: 40px;
+  }
+  .ec__header {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 10px;
+  }
+  .ec__header-right {
+    justify-content: flex-end;
+  }
+  .ec__cell {
+    padding: var(--ec-cell-padding-mobile);
+  }
+  /* 角标在任何屏宽下都绝对定位、悬浮于条目右上角，不占内容宽度 */
+}
+</style>