npmapps 1.1.4 → 1.1.6

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

@@ -0,0 +1,1747 @@
+<template>
+  <div class="doc">
+    <!-- ============================ 页头 ============================ -->
+    <header class="doc__hero">
+      <h1 class="doc__hero-title">EventCalendar 日程日历</h1>
+      <p class="doc__hero-desc">
+        零第三方依赖的月历组件：月份自动补全、下拉切换、自动轮播、可配字段、插槽定制、骨架屏。
+        整个 <code>EventCalendar</code> 文件夹可直接拷贝到任意 Vue 2 项目使用。
+      </p>
+      <div class="doc__hero-tags">
+        <span v-for="t in heroTags" :key="t" class="doc__chip">{{ t }}</span>
+      </div>
+    </header>
+
+    <div class="doc__body">
+      <!-- ============================ 侧边目录 ============================ -->
+      <nav class="doc__toc">
+        <p class="doc__toc-title">示例目录</p>
+        <a
+          v-for="s in sections"
+          :key="s.id"
+          class="doc__toc-link"
+          :class="{ 'is-active': activeSection === s.id }"
+          href="javascript:void(0)"
+          @click="scrollTo(s.id)"
+        >{{ s.title }}</a>
+      </nav>
+
+      <!-- ============================ 示例主体 ============================ -->
+      <main class="doc__main">
+        <!-- ------------------------------------------------------------ -->
+        <!-- 1. 基础用法                                                    -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="basic" class="demo">
+          <h2 class="demo__title">1. 基础用法</h2>
+          <p class="demo__desc">
+            传入 <code>data</code> 即可渲染。默认一周从<strong>周日</strong>开始，
+            当月之外的补位日期自动置灰；每格里的条目就是设计稿中的「学校 + 角标」。
+          </p>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="basicData"
+              title="宣讲日历"
+              subtitle="更多场次陆续上线中，宣讲进程以实际安排为准"
+              active-month="2026-09"
+            />
+          </div>
+          <CodeBlock :code="code.basic" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 2. 异步数据 + 骨架屏                                            -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="async" class="demo">
+          <h2 class="demo__title">2. 异步数据与骨架屏</h2>
+          <p class="demo__desc">
+            数据由 <code>mockData.js</code> 通过 <code>setTimeout</code> 异步返回。
+            返回前 <code>loading</code> 为 <code>true</code>，组件渲染骨架屏，避免白屏和布局跳动。
+          </p>
+          <div class="demo__toolbar">
+            <button class="doc__btn" :disabled="asyncLoading" @click="loadAsync">
+              {{ asyncLoading ? '加载中…' : '重新加载（1.5s）' }}
+            </button>
+            <span class="doc__hint">骨架屏行数由 <code>skeleton-rows</code> 控制</span>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="asyncData"
+              :loading="asyncLoading"
+              :skeleton-rows="5"
+              title="宣讲日历"
+              subtitle="数据加载完成前展示骨架屏"
+            />
+          </div>
+          <CodeBlock :code="code.async" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 3. 多月份与下拉切换                                             -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="months" class="demo">
+          <h2 class="demo__title">3. 多月份与下拉切换</h2>
+          <p class="demo__desc">
+            后端返回多个月份时，右上角下拉框自动列出所有月份（下拉框为自研实现，支持键盘上下键与回车）。
+            打开 <code>show-arrows</code> 还能得到左右翻月按钮。当前月份可用
+            <code>v-model</code> 或 <code>:active-month.sync</code> 双向绑定。
+          </p>
+          <div class="demo__toolbar">
+            <span class="doc__hint">
+              当前绑定值：<code class="doc__code-inline">{{ monthsActive || '—' }}</code>
+            </span>
+            <button class="doc__btn doc__btn--ghost" @click="monthsActive = '2026-11'">
+              外部跳到 2026-11
+            </button>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              v-model="monthsActive"
+              :data="multiData"
+              :loading="multiLoading"
+              show-arrows
+              title="宣讲日历"
+              subtitle="下拉 / 箭头均可切换月份"
+              @month-change="onMonthChange"
+            />
+          </div>
+          <CodeBlock :code="code.months" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 4. 自动轮播                                                    -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="autoplay" class="demo">
+          <h2 class="demo__title">4. 自动轮播</h2>
+          <p class="demo__desc">
+            <code>autoplay</code> 开启轮播，<code>autoplay-interval</code> 配置间隔（毫秒）。
+            顶部细进度条展示距下次切换的剩余时间。以下情况会<strong>自动暂停</strong>并保留剩余时间：
+            鼠标悬停（<code>pause-on-hover</code>）、月份下拉展开、浏览器切到后台、点击暂停按钮。
+          </p>
+          <div class="demo__toolbar">
+            <span class="doc__hint">切换间隔：</span>
+            <button
+              v-for="opt in intervalOptions"
+              :key="opt.value"
+              class="doc__seg"
+              :class="{ 'is-active': autoplayInterval === opt.value }"
+              @click="autoplayInterval = opt.value"
+            >{{ opt.label }}</button>
+            <label class="doc__check">
+              <input v-model="autoplayLoop" type="checkbox" />
+              <span>循环（关闭则播到最后一个月停止）</span>
+            </label>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="multiData"
+              :loading="multiLoading"
+              autoplay
+              :autoplay-interval="autoplayInterval"
+              :loop="autoplayLoop"
+              pause-on-hover
+              title="宣讲日历"
+              subtitle="鼠标移上来试试，轮播会暂停"
+            />
+          </div>
+          <CodeBlock :code="code.autoplay" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 5. 切换动效                                                    -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="effect" class="demo">
+          <h2 class="demo__title">5. 切换动效</h2>
+          <p class="demo__desc">
+            提供 4 种月份切换动效，外加「单元格错峰入场」。动效可通过
+            <code>transition-effect="none"</code> 完全关闭，时长由
+            <code>transition-duration</code> 控制。
+            切换月份时行数可能从 5 行变 6 行，组件会同步做高度过渡，不会突然跳动。
+          </p>
+          <div class="demo__toolbar">
+            <span class="doc__hint">动效：</span>
+            <button
+              v-for="opt in effectOptions"
+              :key="opt.value"
+              class="doc__seg"
+              :class="{ 'is-active': effect === opt.value }"
+              @click="effect = opt.value"
+            >{{ opt.label }}</button>
+          </div>
+          <div class="demo__toolbar">
+            <label class="doc__check">
+              <input v-model="stagger" type="checkbox" />
+              <span>单元格错峰入场</span>
+            </label>
+            <span class="doc__hint">时长 {{ duration }}ms</span>
+            <input v-model.number="duration" type="range" min="0" max="1200" step="20" class="doc__range" />
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="multiData"
+              :loading="multiLoading"
+              :transition-effect="effect"
+              :transition-duration="duration"
+              :cell-stagger="stagger"
+              show-arrows
+              autoplay
+              :autoplay-interval="6000"
+              title="动效预览"
+              subtitle="每 6 秒自动切换一次，也可以点箭头手动切"
+            />
+          </div>
+          <CodeBlock :code="code.effect" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 6. 月份补全与跨年                                               -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="boundary" class="demo">
+          <h2 class="demo__title">6. 月份补全与跨年边界</h2>
+          <p class="demo__desc">
+            每月天数与「1 号是星期几」都不固定，组件会自动补齐首尾：
+            2026 年 2 月 1 号是<strong>周日</strong>，首行无需补位；2 月 28 号是<strong>周六</strong>，
+            末行也刚好排满；而 2026 年 1 月要往前补 <strong>2025 年 12 月</strong>的日期，
+            12 月则要往后补 <strong>2026 年 1 月</strong>——跨年由原生 <code>Date</code> 的进位机制保证正确。
+            切到 <code>2025-12</code> / <code>2026-01</code> 看看灰色补位格。
+          </p>
+          <div class="demo__toolbar">
+            <label class="doc__check">
+              <input v-model="showAdjacentItems" type="checkbox" />
+              <span>补位日期也显示条目（关闭后只留灰色日期）</span>
+            </label>
+            <label class="doc__check">
+              <input v-model="mondayFirst" type="checkbox" />
+              <span>一周从周一开始（first-day-of-week=1）</span>
+            </label>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="crossYearData"
+              :loading="crossYearLoading"
+              :active-month.sync="crossYearMonth"
+              :show-adjacent-items="showAdjacentItems"
+              :first-day-of-week="mondayFirst ? 1 : 0"
+              show-arrows
+              title="跨年场次"
+              subtitle="2025-12 / 2026-01 / 2026-02"
+            />
+          </div>
+          <CodeBlock :code="code.boundary" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 7. 自定义字段映射                                               -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="schema" class="demo">
+          <h2 class="demo__title">7. 自定义字段映射</h2>
+          <p class="demo__desc">
+            后端字段名和组件默认约定不一致时，<strong>不需要改数据</strong>，
+            传一个 <code>field-names</code> 即可。下面这份数据用的是
+            <code>ym / dateList / dayStr / activityList / schoolName / rawAddress</code>，
+            字段路径还支持 <code>'a.b.c'</code> 形式。
+          </p>
+          <div class="demo__cols">
+            <div class="demo__col">
+              <p class="demo__col-title">后端返回（片段）</p>
+              <CodeBlock :code="code.schemaData" always-open />
+            </div>
+            <div class="demo__col">
+              <p class="demo__col-title">映射配置</p>
+              <CodeBlock :code="code.schemaMap" always-open />
+            </div>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="schemaData"
+              :loading="schemaLoading"
+              :field-names="altFieldNames"
+              title="字段映射示例"
+              subtitle="数据字段全都不一样，组件照样认识"
+            />
+          </div>
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 8. 条目溢出与行高                                               -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="overflow" class="demo">
+          <h2 class="demo__title">8. 条目溢出与行高</h2>
+          <p class="demo__desc">
+            每天的条目数量不固定。<strong>行高由该行条目最多的那一天决定</strong>（CSS Grid 天然等高，无需 JS 计算）。
+            超过 <code>max-visible-items</code> 后有两种处理：
+            <code>scroll</code> 在格内出现细滚动条，<code>collapse</code> 折叠并显示「还有 N 项」（可监听
+            <code>more-click</code>）。
+          </p>
+          <div class="demo__toolbar">
+            <span class="doc__hint">溢出方式：</span>
+            <button
+              v-for="opt in overflowOptions"
+              :key="opt.value"
+              class="doc__seg"
+              :class="{ 'is-active': overflowMode === opt.value }"
+              @click="overflowMode = opt.value"
+            >{{ opt.label }}</button>
+            <span class="doc__hint">最多显示 {{ maxVisibleItems }} 条</span>
+            <input v-model.number="maxVisibleItems" type="range" min="1" max="6" step="1" class="doc__range" />
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="overflowData"
+              :loading="overflowLoading"
+              :max-visible-items="maxVisibleItems"
+              :overflow-mode="overflowMode"
+              :min-row-height="120"
+              title="溢出演示"
+              subtitle="部分日期故意放了 6 条数据"
+              @more-click="onMoreClick"
+            />
+          </div>
+          <CodeBlock :code="code.overflow" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 9. 插槽定制                                                    -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="slots" class="demo">
+          <h2 class="demo__title">9. 插槽定制</h2>
+          <p class="demo__desc">
+            左上角 <code>header-left</code>、单条 <code>item</code>、整格 <code>day</code>、
+            当天无数据时的 <code>day-empty</code> 等都可以自定义。
+            下面这个例子把左上角换成了统计卡片，把条目换成了「时间 + 学校 + 地点」的两行布局。
+          </p>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="multiData"
+              :loading="multiLoading"
+              :min-row-height="140"
+              :item-height="44"
+              :max-visible-items="3"
+            >
+              <!-- 左上角完全自定义 -->
+              <template #header-left="{ monthLabel, monthIndex, monthCount }">
+                <div class="custom-head">
+                  <div class="custom-head__badge">{{ monthLabel }}</div>
+                  <div class="custom-head__meta">
+                    <strong>校园招聘日程</strong>
+                    <span>第 {{ monthIndex + 1 }} / {{ monthCount }} 个月 · 共 {{ monthItemCount }} 场</span>
+                  </div>
+                </div>
+              </template>
+
+              <!-- 单条条目自定义 -->
+              <template #item="{ item, label, badge, type }">
+                <div class="custom-item" :class="'is-' + type">
+                  <div class="custom-item__row">
+                    <span class="custom-item__time">{{ item.startTime || '—' }}</span>
+                    <span class="custom-item__name">{{ label }}</span>
+                  </div>
+                  <div class="custom-item__row custom-item__row--sub">
+                    <span class="custom-item__addr">{{ item.address || '地点待定' }}</span>
+                    <span v-if="badge" class="custom-item__tag">{{ badge }}</span>
+                  </div>
+                </div>
+              </template>
+
+              <!-- 当天没有数据时的占位 -->
+              <template #day-empty="{ isCurrentMonth }">
+                <div v-if="isCurrentMonth" class="custom-empty">暂无安排</div>
+              </template>
+            </EventCalendar>
+          </div>
+          <CodeBlock :code="code.slots" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 10. 事件                                                       -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="events" class="demo">
+          <h2 class="demo__title">10. 事件</h2>
+          <p class="demo__desc">
+            点击<strong>格子空白处</strong>触发 <code>day-click</code>，点击<strong>条目</strong>触发
+            <code>item-click</code>，点击条目右上角<strong>角标</strong>触发 <code>tag-click</code>
+            （未监听 <code>tag-click</code> 时会退化成 <code>item-click</code>，避免「点了没反应」）。
+            回调都会带上完整的原始数据对象。
+          </p>
+          <div class="demo__cols demo__cols--events">
+            <div class="demo__stage demo__stage--flex">
+              <EventCalendar
+                :data="basicData"
+                active-month="2026-09"
+                title="点点看"
+                subtitle="日期格 / 条目 / 角标 都可点"
+                @day-click="onDayClick"
+                @item-click="onItemClick"
+                @tag-click="onTagClick"
+              />
+            </div>
+            <div class="event-log">
+              <div class="event-log__head">
+                <span>事件日志</span>
+                <button class="doc__btn doc__btn--ghost doc__btn--sm" @click="logs = []">清空</button>
+              </div>
+              <ul v-if="logs.length" class="event-log__list">
+                <li v-for="(log, i) in logs" :key="i" class="event-log__item">
+                  <span class="event-log__type" :class="'is-' + log.type">{{ log.type }}</span>
+                  <span class="event-log__text">{{ log.text }}</span>
+                </li>
+              </ul>
+              <p v-else class="event-log__empty">还没有事件，点左侧日历试试</p>
+            </div>
+          </div>
+          <CodeBlock :code="code.events" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 11. 主题与样式变体                                              -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="theme" class="demo">
+          <h2 class="demo__title">11. 主题与样式变体</h2>
+          <p class="demo__desc">
+            所有颜色走 CSS 变量，用 <code>theme</code> 传入即可换肤；
+            <code>type-colors</code> 可为业务类型指定配色；
+            <code>:colorful="false"</code> 会让角标回到中性灰（更贴近原始设计稿）。
+          </p>
+          <div class="demo__toolbar">
+            <button
+              v-for="t in themePresets"
+              :key="t.name"
+              class="doc__seg"
+              :class="{ 'is-active': themeName === t.name }"
+              @click="themeName = t.name"
+            >{{ t.label }}</button>
+            <label class="doc__check">
+              <input v-model="colorful" type="checkbox" />
+              <span>角标彩色（关闭 = 还原设计稿灰色）</span>
+            </label>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="basicData"
+              active-month="2026-09"
+              :theme="currentTheme"
+              :colorful="colorful"
+              :type-colors="typeColors"
+              title="主题预览"
+              :subtitle="'当前：' + themeName"
+            />
+          </div>
+          <CodeBlock :code="code.theme" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 12. 空状态                                                     -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="empty" class="demo">
+          <h2 class="demo__title">12. 空状态与无头部</h2>
+          <p class="demo__desc">
+            没有任何月份数据时展示空状态，文案由 <code>empty-text</code> 控制，
+            也可以用 <code>empty</code> 插槽整体替换。
+            <code>:show-header="false"</code> 可以隐藏整个顶部区域，把日历当作纯展示块嵌进别的容器。
+          </p>
+          <div class="demo__cols">
+            <div class="demo__col">
+              <p class="demo__col-title">空数据</p>
+              <div class="demo__stage">
+                <EventCalendar :data="[]" empty-text="本月暂无宣讲安排" :show-header="false" />
+              </div>
+            </div>
+            <div class="demo__col">
+              <p class="demo__col-title">持续加载中</p>
+              <div class="demo__stage">
+                <EventCalendar :data="[]" loading :skeleton-rows="4" :show-header="false" />
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 13. NodeQ 后端数据适配                                         -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="nodeq" class="demo">
+          <h2 class="demo__title">13. NodeQ 后端数据适配</h2>
+          <p class="demo__desc">
+            mock 响应先通过简单转换方法得到标准日历数据，再直接传给
+            <code>EventCalendar</code>。地址、居中和左右内边距均由组件原生支持。
+          </p>
+          <div class="demo__toolbar">
+            <span class="doc__hint">条目对齐：</span>
+            <button
+              v-for="opt in nodeqAlignmentOptions"
+              :key="opt.value"
+              class="doc__seg"
+              :class="{ 'is-active': nodeqAlignment === opt.value }"
+              @click="nodeqAlignment = opt.value"
+            >{{ opt.label }}</button>
+
+            <label class="doc__check">
+              <input v-model="nodeqNoHorizontalPadding" type="checkbox" />
+              <span>去除条目左右内边距</span>
+            </label>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="nodeqData"
+              :active-month.sync="nodeqActiveMonth"
+              :item-align="nodeqAlignment"
+              :item-horizontal-padding="nodeqNoHorizontalPadding ? 0 : 8"
+              :item-height="40"
+              :max-visible-items="5"
+              :min-row-height="142"
+              show-arrows
+              title="宣讲日历（NodeQ）"
+              subtitle="三个月模拟数据 · 每个有安排的日期 3～5 条"
+            />
+          </div>
+          <CodeBlock :code="code.nodeq" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- 14. 原生布局配置与 JSON 导出                                  -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="layout-config" class="demo">
+          <h2 class="demo__title">14. 原生布局配置与一键复制</h2>
+          <p class="demo__desc">
+            配置工具栏属于 <code>EventCalendar</code> 自身能力，按 P1～P14 排列常用项：
+            条目对齐、日期格/窄屏日期格内边距（各拆「上下 / 左右」两块）、条目边距与间距、
+            名称与地址间距、单格最多显示、条目高度、条目背景效果（纯色/渐变，方向可上下或左右）、
+            悬浮加深（可关闭）与条目背景/文字色；选定背景色后悬浮会自动调淡一档。
+            每张卡片右上角的「还原」可回到初始值，调整后点「复制配置」，JSON 直接进剪贴板，发给研发即可。
+            生产环境保持默认隐藏，开发配置时再传入 <code>show-config-toolbar</code>。
+          </p>
+          <div class="demo__toolbar">
+            <label class="doc__check">
+              <input v-model="layoutToolbarVisible" type="checkbox" />
+              <span>显示组件内配置工具栏</span>
+            </label>
+            <span class="doc__hint">
+              当前参数：<code>show-config-toolbar="{{ layoutToolbarVisible }}"</code>
+            </span>
+          </div>
+          <div class="demo__stage">
+            <EventCalendar
+              :data="nodeqData"
+              :active-month.sync="layoutActiveMonth"
+              v-bind="savedLayoutConfig"
+              :show-config-toolbar="layoutToolbarVisible"
+              :item-height="40"
+              :max-visible-items="5"
+              :min-row-height="142"
+              show-arrows
+              title="可配置宣讲日历"
+              subtitle="配置结果点「复制配置」，粘贴发给研发即可"
+            />
+          </div>
+          <CodeBlock :code="code.layoutConfig" />
+        </section>
+
+        <!-- ------------------------------------------------------------ -->
+        <!-- API                                                           -->
+        <!-- ------------------------------------------------------------ -->
+        <section id="api" class="demo">
+          <h2 class="demo__title">API</h2>
+
+          <h3 class="demo__sub">Props</h3>
+          <div class="doc__table-wrap">
+            <table class="doc__table">
+              <thead>
+                <tr><th>参数</th><th>说明</th><th>类型</th><th>默认值</th></tr>
+              </thead>
+              <tbody>
+                <tr v-for="row in apiProps" :key="row[0]">
+                  <td><code>{{ row[0] }}</code></td>
+                  <td>{{ row[1] }}</td>
+                  <td><span class="doc__type">{{ row[2] }}</span></td>
+                  <td><code>{{ row[3] }}</code></td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 class="demo__sub">Events</h3>
+          <div class="doc__table-wrap">
+            <table class="doc__table">
+              <thead>
+                <tr><th>事件名</th><th>说明</th><th>回调参数</th></tr>
+              </thead>
+              <tbody>
+                <tr v-for="row in apiEvents" :key="row[0]">
+                  <td><code>{{ row[0] }}</code></td>
+                  <td>{{ row[1] }}</td>
+                  <td><span class="doc__type">{{ row[2] }}</span></td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 class="demo__sub">Slots</h3>
+          <div class="doc__table-wrap">
+            <table class="doc__table">
+              <thead>
+                <tr><th>名称</th><th>说明</th><th>作用域参数</th></tr>
+              </thead>
+              <tbody>
+                <tr v-for="row in apiSlots" :key="row[0]">
+                  <td><code>{{ row[0] }}</code></td>
+                  <td>{{ row[1] }}</td>
+                  <td><span class="doc__type">{{ row[2] }}</span></td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 class="demo__sub">Methods（通过 ref 调用）</h3>
+          <div class="doc__table-wrap">
+            <table class="doc__table">
+              <thead>
+                <tr><th>方法</th><th>说明</th></tr>
+              </thead>
+              <tbody>
+                <tr v-for="row in apiMethods" :key="row[0]">
+                  <td><code>{{ row[0] }}</code></td>
+                  <td>{{ row[1] }}</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </section>
+      </main>
+    </div>
+  </div>
+</template>
+
+<script>
+/**
+ * EventCalendar 示例集合
+ * ------------------------------------------------------------------
+ * 按 UI 组件库文档的形式，把组件的每一项能力都单独做成一个可交互示例。
+ * 本文件同样不依赖第三方 UI 库，跟随组件文件夹一起拷走即可运行。
+ */
+import EventCalendar from './index.vue'
+import CodeBlock from './CodeBlock.vue'
+import {
+  SIMPLE_DATA,
+  ALT_FIELD_NAMES,
+  fetchCalendarData,
+  fetchCalendarDataV2,
+  fetchCrossYearData,
+  NODEQ_MOCK_RESPONSE
+} from './mockData'
+import { transformNodeqCalendarResponse } from './recruitmentAdapter'
+
+export default {
+  name: 'EventCalendarExample',
+
+  components: { EventCalendar, CodeBlock },
+
+  data() {
+    return {
+      heroTags: ['零依赖', '自动补月', '轮播动效', '字段可配', '布局配置', 'NodeQ 适配', '插槽定制', '骨架屏'],
+
+      sections: [
+        { id: 'basic', title: '1. 基础用法' },
+        { id: 'async', title: '2. 异步与骨架屏' },
+        { id: 'months', title: '3. 多月份切换' },
+        { id: 'autoplay', title: '4. 自动轮播' },
+        { id: 'effect', title: '5. 切换动效' },
+        { id: 'boundary', title: '6. 补全与跨年' },
+        { id: 'schema', title: '7. 字段映射' },
+        { id: 'overflow', title: '8. 溢出与行高' },
+        { id: 'slots', title: '9. 插槽定制' },
+        { id: 'events', title: '10. 事件' },
+        { id: 'theme', title: '11. 主题定制' },
+        { id: 'empty', title: '12. 空状态' },
+        { id: 'nodeq', title: '13. NodeQ 后端适配' },
+        { id: 'layout-config', title: '14. 布局配置与导出' },
+        { id: 'api', title: 'API' }
+      ],
+      activeSection: 'basic',
+
+      /* -------- 1. 基础 -------- */
+      basicData: SIMPLE_DATA,
+
+      /* -------- 2. 异步 -------- */
+      asyncData: [],
+      asyncLoading: true,
+
+      /* -------- 3/4/5/9. 多月份（共用一份数据） -------- */
+      multiData: [],
+      multiLoading: true,
+      monthsActive: '',
+
+      /* -------- 4. 轮播 -------- */
+      autoplayInterval: 10000,
+      autoplayLoop: true,
+      intervalOptions: [
+        { label: '5 秒', value: 5000 },
+        { label: '10 秒', value: 10000 },
+        { label: '30 秒', value: 30000 },
+        { label: '1 分钟', value: 60000 }
+      ],
+
+      /* -------- 5. 动效 -------- */
+      effect: 'slide',
+      duration: 420,
+      stagger: true,
+      effectOptions: [
+        { label: '滑动 slide', value: 'slide' },
+        { label: '淡入 fade', value: 'fade' },
+        { label: '缩放 zoom', value: 'zoom' },
+        { label: '翻页 flip', value: 'flip' },
+        { label: '关闭 none', value: 'none' }
+      ],
+
+      /* -------- 6. 跨年 -------- */
+      crossYearData: [],
+      crossYearLoading: true,
+      crossYearMonth: '2026-01',
+      showAdjacentItems: true,
+      mondayFirst: false,
+
+      /* -------- 7. 字段映射 -------- */
+      schemaData: [],
+      schemaLoading: true,
+      altFieldNames: ALT_FIELD_NAMES,
+
+      /* -------- 8. 溢出 -------- */
+      overflowData: [],
+      overflowLoading: true,
+      maxVisibleItems: 4,
+      overflowMode: 'scroll',
+      overflowOptions: [
+        { label: '滚动 scroll', value: 'scroll' },
+        { label: '折叠 collapse', value: 'collapse' }
+      ],
+
+      /* -------- 10. 事件 -------- */
+      logs: [],
+
+      /* -------- 13. NodeQ 后端形状 -------- */
+      nodeqData: transformNodeqCalendarResponse(NODEQ_MOCK_RESPONSE),
+      nodeqAlignment: 'left',
+      nodeqNoHorizontalPadding: false,
+      nodeqActiveMonth: '2026-09',
+      nodeqAlignmentOptions: [
+        { label: '靠左', value: 'left' },
+        { label: '居中', value: 'center' }
+      ],
+
+      /* -------- 14. 原生布局配置 -------- */
+      layoutToolbarVisible: true,
+      layoutActiveMonth: '2026-09',
+      savedLayoutConfig: {
+        itemAlign: 'left',
+        calendarMargin: 0,
+        calendarPadding: 0,
+        headerPadding: '4px 4px 16px',
+        cellPadding: '12px 10px',
+        mobileCellPadding: '8px 6px',
+        itemHorizontalPadding: 8,
+        itemVerticalPadding: 4,
+        itemGap: 6,
+        itemLineGap: 2,
+        itemBgGradient: false,
+        itemBgGradientDir: 'to-bottom',
+        itemBgHover: true,
+        itemTextColor: '',
+        itemBgColor: ''
+      },
+
+      /* -------- 11. 主题 -------- */
+      themeName: 'default',
+      colorful: true,
+      themePresets: [
+        { name: 'default', label: '默认蓝', vars: {} },
+        {
+          name: 'green',
+          label: '清新绿',
+          vars: {
+            primary: '#10a37f',
+            primaryGhost: 'rgba(16, 163, 127, 0.12)',
+            itemBg: '#f2f9f6',
+            cellHover: '#f7fcfa',
+            radius: '10px'
+          }
+        },
+        {
+          name: 'violet',
+          label: '典雅紫',
+          vars: {
+            primary: '#7c3aed',
+            primaryGhost: 'rgba(124, 58, 237, 0.12)',
+            itemBg: '#f6f4fd',
+            cellHover: '#faf9fe',
+            radius: '12px'
+          }
+        },
+        {
+          name: 'plain',
+          label: '素净灰',
+          vars: {
+            primary: '#4b5563',
+            primaryGhost: 'rgba(75, 85, 99, 0.1)',
+            itemBg: '#f4f4f5',
+            cellHover: '#fafafa',
+            radius: '4px'
+          }
+        }
+      ],
+      typeColors: {
+        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)' }
+      },
+
+      /* -------- 代码片段（纯字符串，不参与模板编译） -------- */
+      code: {
+        basic: `<EventCalendar
+  :data="data"
+  title="宣讲日历"
+  subtitle="更多场次陆续上线中，宣讲进程以实际安排为准"
+  active-month="2026-09"
+/>
+
+// data 结构
+[{
+  month: '2026-09',
+  monthLabel: '2026年9月',
+  days: [{
+    date: '2026-09-09',
+    items: [
+      { id: 'a1', label: '香港中文大学（深圳）', badge: '宣讲', type: 'talk' }
+    ]
+  }]
+}]`,
+
+        async: `<EventCalendar :data="data" :loading="loading" :skeleton-rows="5" />
+
+import { fetchCalendarData } from '@/components/EventCalendar/mockData'
+
+async created() {
+  this.loading = true
+  try {
+    this.data = await fetchCalendarData({ delay: 1500 })
+  } finally {
+    this.loading = false   // 放 finally，接口失败也要收掉骨架屏
+  }
+}`,
+
+        months: `<!-- v-model 与 :active-month.sync 等价，二选一 -->
+<EventCalendar
+  v-model="activeMonth"
+  :data="data"
+  show-arrows
+  @month-change="onMonthChange"
+/>
+
+onMonthChange(month, info) {
+  // info = { index, source, option, raw }
+  // source: 'select' | 'arrow' | 'autoplay' | 'prop' | 'api'
+  console.log(month, info.source)
+}`,
+
+        autoplay: `<EventCalendar
+  :data="data"
+  autoplay
+  :autoplay-interval="10000"
+  :loop="true"
+  pause-on-hover
+  :show-progress="true"
+  :show-autoplay-toggle="true"
+/>`,
+
+        effect: `<EventCalendar
+  :data="data"
+  transition-effect="slide"
+  :transition-duration="420"
+  :cell-stagger="true"
+/>
+
+<!-- 完全关闭动效 -->
+<EventCalendar :data="data" transition-effect="none" :cell-stagger="false" />`,
+
+        boundary: `<!-- 补位日期自动置灰；跨年由原生 Date 进位保证正确 -->
+<EventCalendar
+  :data="data"
+  :active-month.sync="month"
+  :show-adjacent-items="true"
+  :first-day-of-week="0"
+/>`,
+
+        schemaData: `[{
+  ym: '2026-09',
+  ymText: '9 月场次',
+  dateList: [{
+    dayStr: '2026-09-09',
+    activityList: [{
+      activityId: 1,
+      schoolName: '南方科技大学',
+      rawAddress: '深圳市南山区校区报告厅',
+      activityTypeName: '宣讲',
+      activityType: 'talk',
+      expired: false
+    }]
+  }]
+}]`,
+
+        schemaMap: `const fieldNames = {
+  month:        'ym',
+  monthLabel:   'ymText',
+  days:         'dateList',
+  date:         'dayStr',
+  items:        'activityList',
+  itemKey:      'activityId',
+  itemLabel:    'schoolName',
+  itemAddress:  'rawAddress',
+  itemBadge:    'activityTypeName',
+  itemType:     'activityType',
+  itemDisabled: 'expired'
+}
+
+<EventCalendar :data="data" :field-names="fieldNames" />`,
+
+        overflow: `<!-- 行高自动取该行条目最多的那一天，超出按 overflow-mode 处理 -->
+<EventCalendar
+  :data="data"
+  :max-visible-items="4"
+  overflow-mode="scroll"
+  :item-height="28"
+  :item-gap="6"
+  :min-row-height="120"
+  @more-click="onMoreClick"
+/>`,
+
+        slots: `<EventCalendar :data="data" :item-height="44" :max-visible-items="3">
+  <!-- 左上角：设计稿里的标题区，可放任意内容 -->
+  <template #header-left="{ monthLabel, monthIndex, monthCount }">
+    <div class="custom-head">…</div>
+  </template>
+
+  <!-- 单条条目：不传则用默认「学校名 + 右上角角标」 -->
+  <template #item="{ item, label, badge, type, day, index }">
+    <div class="custom-item">…</div>
+  </template>
+
+  <!-- 当天没有数据时 -->
+  <template #day-empty="{ isCurrentMonth }">
+    <div v-if="isCurrentMonth">暂无安排</div>
+  </template>
+</EventCalendar>`,
+
+        events: `<EventCalendar
+  :data="data"
+  @day-click="onDayClick"
+  @item-click="onItemClick"
+  @tag-click="onTagClick"
+/>
+
+onDayClick(scope, event) {
+  // scope = { day, date, dateKey, items, raw, isCurrentMonth, isToday, ... }
+}
+onItemClick(scope, event) {
+  // scope = { item, label, address, badge, type, index, day, dateKey }
+  // item 是后端返回的原始对象，字段齐全
+}
+onTagClick(scope, event) {
+  // 点角标；未监听时会自动退化成 item-click
+}`,
+
+        nodeq: `import EventCalendar from '@/components/EventCalendar/index.vue'
+import { fetchNodeqCalendarData } from '@/components/EventCalendar/mockData'
+import { transformNodeqCalendarResponse } from '@/components/EventCalendar/recruitmentAdapter'
+
+// 后端原始响应：response.data.nbcbRecAnnJourneyMaps
+const response = await fetchNodeqCalendarData()
+const data = transformNodeqCalendarResponse(response)
+
+<EventCalendar
+  :data="data"
+  item-align="center"
+  :item-horizontal-padding="0"
+  :item-height="40"
+/>
+// address 为空时，组件不会渲染地址行。`,
+
+        layoutConfig: `<!-- 默认不显示工具栏；建议只在开发环境开启 -->
+<EventCalendar
+  :data="data"
+  v-bind="layoutConfig"
+  :show-config-toolbar="isDevelopment"
+/>
+<!-- 工具栏里改完点「复制配置」，把 JSON 粘回来赋给 layoutConfig 即可 -->
+
+export default {
+  data() {
+    return {
+      isDevelopment: process.env.NODE_ENV !== 'production',
+      // 结构同工具栏「复制配置」得到的 JSON，可直接 v-bind 应用
+      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: ''
+      }
+    }
+  }
+}`,
+
+        theme: `<EventCalendar
+  :data="data"
+  :theme="{
+    primary: '#10a37f',
+    primaryGhost: 'rgba(16,163,127,.12)',
+    itemBg: '#f2f9f6',
+    radius: '10px'
+  }"
+  :type-colors="{ talk: { color: '#3d6cf0', bg: 'rgba(61,108,240,.1)' } }"
+  :colorful="true"
+/>`
+      },
+
+      /* -------- API 表格 -------- */
+      apiProps: [
+        ['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', '主题变量覆盖，如 { primary, radius, itemBg }', 'Object', '{}']
+      ],
+      apiEvents: [
+        ['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)']
+      ],
+      apiSlots: [
+        ['header-left', '顶部左侧（设计稿的标题区）', '{ month, monthLabel, monthIndex, monthCount, prev, next, goTo }'],
+        ['header-right', '顶部右侧，整体替换默认的按钮 + 下拉', '同上'],
+        ['weekday', '星期表头单元', '{ label, weekday, isWeekend, index }'],
+        ['day', '整个日期格子（覆盖所有默认内容）', '{ day, dateKey, items, raw, isCurrentMonth, isToday, label }'],
+        ['day-header', '格子里的日期行', '同 day'],
+        ['items', '格子里的条目列表区域', '同 day'],
+        ['item', '单个条目', '{ item, label, badge, type, disabled, index, day, dateKey }'],
+        ['day-empty', '当天无数据时的占位', '同 day'],
+        ['loading', '自定义骨架屏', '{ rows }'],
+        ['empty', '整体空状态', '—']
+      ],
+      apiMethods: [
+        ['prev()', '切到上一个月'],
+        ['next()', '切到下一个月'],
+        ['goTo(index)', '切到第 index 个月（从 0 开始）'],
+        ['setMonth(month)', '切到指定月份，如 setMonth("2026-10")'],
+        ['restartAutoplay()', '重置轮播计时'],
+        ['getLayoutConfig()', '获取可直接通过 v-bind 应用的当前布局配置']
+      ]
+    }
+  },
+
+  computed: {
+    currentTheme() {
+      const hit = this.themePresets.find((t) => t.name === this.themeName)
+      return hit ? hit.vars : {}
+    },
+
+    /** 插槽示例里用到的当月场次总数 */
+    monthItemCount() {
+      const month = this.multiData[0]
+      if (!month) return 0
+      return (month.days || []).reduce((sum, d) => sum + (d.items || []).length, 0)
+    }
+  },
+
+  created() {
+    this.loadAsync()
+    this.loadMulti()
+    this.loadCrossYear()
+    this.loadSchema()
+    this.loadOverflow()
+  },
+
+  mounted() {
+    window.addEventListener('scroll', this.handleScroll, true)
+  },
+
+  beforeDestroy() {
+    window.removeEventListener('scroll', this.handleScroll, true)
+  },
+
+  methods: {
+    /* ------------------------- 数据加载 ------------------------- */
+    async loadAsync() {
+      this.asyncLoading = true
+      try {
+        this.asyncData = await fetchCalendarData({ months: ['2026-09'], delay: 1500 })
+      } finally {
+        // 放 finally：接口失败也要收掉骨架屏，否则页面会一直卡在加载态
+        this.asyncLoading = false
+      }
+    },
+
+    async loadMulti() {
+      this.multiLoading = true
+      try {
+        this.multiData = await fetchCalendarData({
+          months: ['2026-09', '2026-10', '2026-11'],
+          delay: 1200
+        })
+      } finally {
+        this.multiLoading = false
+      }
+    },
+
+    async loadCrossYear() {
+      this.crossYearLoading = true
+      try {
+        this.crossYearData = await fetchCrossYearData({ delay: 1000 })
+      } finally {
+        this.crossYearLoading = false
+      }
+    },
+
+    async loadSchema() {
+      this.schemaLoading = true
+      try {
+        this.schemaData = await fetchCalendarDataV2({ months: ['2026-09', '2026-10'], delay: 1400 })
+      } finally {
+        this.schemaLoading = false
+      }
+    },
+
+    async loadOverflow() {
+      this.overflowLoading = true
+      try {
+        // density=1 + maxItems=6：让几乎每天都有数据，且部分日期超过 4 条
+        this.overflowData = await fetchCalendarData({
+          months: ['2026-09'],
+          delay: 800,
+          maxItems: 6,
+          density: 0.95
+        })
+      } finally {
+        this.overflowLoading = false
+      }
+    },
+
+    /* ------------------------- 事件回调 ------------------------- */
+    onMonthChange(month, info) {
+      this.pushLog('month', `切到 ${month}（来源：${info.source}）`)
+    },
+
+    onDayClick(scope) {
+      this.pushLog('day', `${scope.dateKey} · ${scope.items.length} 场`)
+    },
+
+    onItemClick(scope) {
+      this.pushLog('item', `${scope.dateKey} · ${scope.label}`)
+    },
+
+    onTagClick(scope) {
+      this.pushLog('tag', `${scope.label} 的角标「${scope.badge}」`)
+    },
+
+    onMoreClick(scope) {
+      this.pushLog('more', `${scope.dateKey} 共 ${scope.items.length} 场`)
+    },
+
+    pushLog(type, text) {
+      this.logs.unshift({ type, text })
+      if (this.logs.length > 12) this.logs.pop()
+    },
+
+    /* ------------------------- 目录导航 ------------------------- */
+    scrollTo(id) {
+      const el = document.getElementById(id)
+      if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      this.activeSection = id
+    },
+
+    /** 滚动时同步高亮左侧目录 */
+    handleScroll() {
+      const offset = 120
+      let current = this.sections[0].id
+      for (const s of this.sections) {
+        const el = document.getElementById(s.id)
+        if (el && el.getBoundingClientRect().top <= offset) current = s.id
+      }
+      this.activeSection = current
+    }
+  }
+}
+</script>
+
+<style scoped>
+/* ============================ 文档页外壳 ============================ */
+.doc {
+  padding: 24px;
+  background: #fafbfc;
+  color: #303133;
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.doc code {
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: #eef0f4;
+  color: #476582;
+  font-family: Consolas, Monaco, 'Courier New', monospace;
+  font-size: 0.92em;
+}
+
+/* ------------------------------ 页头 ------------------------------ */
+.doc__hero {
+  padding: 28px 32px;
+  margin-bottom: 24px;
+  border-radius: 14px;
+  background: linear-gradient(120deg, #eef3ff 0%, #f7f9ff 45%, #fdf6ff 100%);
+  border: 1px solid #e8ecf6;
+}
+
+.doc__hero-title {
+  margin: 0 0 10px;
+  font-size: 26px;
+  font-weight: 700;
+}
+
+.doc__hero-desc {
+  max-width: 860px;
+  margin: 0 0 16px;
+  color: #5c6478;
+}
+
+.doc__hero-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.doc__chip {
+  padding: 3px 12px;
+  border-radius: 999px;
+  background: rgba(61, 108, 240, 0.1);
+  color: #3d6cf0;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+/* ------------------------------ 主体布局 ------------------------------ */
+.doc__body {
+  display: flex;
+  align-items: flex-start;
+  gap: 24px;
+}
+
+.doc__toc {
+  position: sticky;
+  top: 16px;
+  flex: none;
+  width: 172px;
+  padding: 14px;
+  border-radius: 12px;
+  background: #fff;
+  border: 1px solid #ebeef5;
+}
+
+.doc__toc-title {
+  margin: 0 0 8px;
+  padding-left: 10px;
+  color: #909399;
+  font-size: 12px;
+}
+
+.doc__toc-link {
+  display: block;
+  padding: 6px 10px;
+  border-radius: 6px;
+  color: #606266;
+  font-size: 13px;
+  text-decoration: none;
+  transition: background-color 0.16s, color 0.16s;
+}
+
+.doc__toc-link:hover {
+  background: #f5f7fa;
+  color: #3d6cf0;
+}
+
+.doc__toc-link.is-active {
+  background: rgba(61, 108, 240, 0.1);
+  color: #3d6cf0;
+  font-weight: 600;
+}
+
+.doc__main {
+  flex: 1;
+  min-width: 0;
+}
+
+/* ------------------------------ 示例卡片 ------------------------------ */
+.demo {
+  padding: 24px;
+  margin-bottom: 24px;
+  border-radius: 12px;
+  background: #fff;
+  border: 1px solid #ebeef5;
+  scroll-margin-top: 16px;
+}
+
+.demo__title {
+  margin: 0 0 8px;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+.demo__sub {
+  margin: 22px 0 10px;
+  font-size: 15px;
+  font-weight: 600;
+  color: #303133;
+}
+
+.demo__desc {
+  margin: 0 0 16px;
+  color: #5c6478;
+}
+
+.demo__stage {
+  padding: 16px;
+  border-radius: 10px;
+  border: 1px solid #ebeef5;
+  background: #fff;
+}
+
+.demo__stage--flex {
+  flex: 1;
+  min-width: 0;
+}
+
+.demo__toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 14px;
+}
+
+.demo__cols {
+  display: flex;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.demo__cols--events {
+  align-items: stretch;
+  flex-wrap: nowrap;
+}
+
+.demo__col {
+  flex: 1;
+  min-width: 280px;
+}
+
+.demo__col-title {
+  margin: 0 0 8px;
+  color: #909399;
+  font-size: 13px;
+}
+
+/* ------------------------------ 控件 ------------------------------ */
+.doc__btn {
+  height: 32px;
+  padding: 0 14px;
+  border: 1px solid #3d6cf0;
+  border-radius: 8px;
+  background: #3d6cf0;
+  color: #fff;
+  font-size: 13px;
+  cursor: pointer;
+  transition: opacity 0.18s, background-color 0.18s;
+}
+
+.doc__btn:hover:not(:disabled) {
+  opacity: 0.88;
+}
+
+.doc__btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.doc__btn--ghost {
+  background: #fff;
+  color: #3d6cf0;
+}
+
+.doc__btn--ghost:hover {
+  background: rgba(61, 108, 240, 0.08);
+}
+
+.doc__btn--sm {
+  height: 24px;
+  padding: 0 10px;
+  font-size: 12px;
+}
+
+.doc__seg {
+  height: 30px;
+  padding: 0 12px;
+  border: 1px solid #dcdfe6;
+  border-radius: 8px;
+  background: #fff;
+  color: #606266;
+  font-size: 13px;
+  cursor: pointer;
+  transition: all 0.18s;
+}
+
+.doc__seg:hover {
+  border-color: #3d6cf0;
+  color: #3d6cf0;
+}
+
+.doc__seg.is-active {
+  border-color: #3d6cf0;
+  background: #3d6cf0;
+  color: #fff;
+}
+
+.doc__check {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: #606266;
+  font-size: 13px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.doc__check input {
+  cursor: pointer;
+}
+
+.doc__range {
+  width: 130px;
+  cursor: pointer;
+}
+
+.doc__hint {
+  color: #909399;
+  font-size: 13px;
+}
+
+.doc__code-inline {
+  color: #3d6cf0 !important;
+}
+
+
+/* ------------------------------ 事件日志 ------------------------------ */
+.event-log {
+  flex: none;
+  width: 280px;
+  display: flex;
+  flex-direction: column;
+  border: 1px solid #ebeef5;
+  border-radius: 10px;
+  background: #fbfcfe;
+  overflow: hidden;
+}
+
+.event-log__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 12px;
+  border-bottom: 1px solid #ebeef5;
+  font-size: 13px;
+  font-weight: 600;
+  color: #303133;
+}
+
+.event-log__list {
+  flex: 1;
+  margin: 0;
+  padding: 8px;
+  list-style: none;
+  overflow-y: auto;
+  max-height: 420px;
+}
+
+.event-log__item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 6px 4px;
+  border-bottom: 1px dashed #eef0f4;
+  font-size: 12px;
+}
+
+.event-log__item:last-child {
+  border-bottom: none;
+}
+
+.event-log__type {
+  flex: none;
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-size: 11px;
+  background: #eef0f4;
+  color: #606266;
+}
+
+.event-log__type.is-day { background: rgba(61, 108, 240, 0.12); color: #3d6cf0; }
+.event-log__type.is-item { background: rgba(16, 163, 127, 0.12); color: #10a37f; }
+.event-log__type.is-tag { background: rgba(224, 130, 27, 0.14); color: #e0821b; }
+.event-log__type.is-month { background: rgba(139, 92, 246, 0.12); color: #8b5cf6; }
+.event-log__type.is-more { background: rgba(107, 114, 128, 0.14); color: #6b7280; }
+
+.event-log__text {
+  color: #5c6478;
+  word-break: break-all;
+}
+
+.event-log__empty {
+  margin: 0;
+  padding: 40px 16px;
+  color: #c0c4cc;
+  font-size: 13px;
+  text-align: center;
+}
+
+/* ------------------------------ API 表格 ------------------------------ */
+.doc__table-wrap {
+  overflow-x: auto;
+  border: 1px solid #ebeef5;
+  border-radius: 10px;
+}
+
+.doc__table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+}
+
+.doc__table th,
+.doc__table td {
+  padding: 10px 14px;
+  text-align: left;
+  border-bottom: 1px solid #f0f2f5;
+  vertical-align: top;
+}
+
+.doc__table th {
+  background: #fafbfc;
+  color: #303133;
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.doc__table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.doc__table tbody tr:hover {
+  background: #fafbfd;
+}
+
+.doc__type {
+  color: #909399;
+  font-family: Consolas, Monaco, monospace;
+  font-size: 12px;
+}
+
+/* ==================== 插槽示例里的自定义样式 ====================
+ * 注意：scoped 样式默认不作用于插槽内容的子组件根节点之外，
+ * 但这些 DOM 是在本组件模板里写的，所以带的是本组件的 scopeId，样式生效。
+ * ============================================================== */
+.custom-head {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.custom-head__badge {
+  padding: 6px 14px;
+  border-radius: 10px;
+  background: linear-gradient(135deg, #3d6cf0, #6c8ff5);
+  color: #fff;
+  font-size: 14px;
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.custom-head__meta {
+  display: flex;
+  flex-direction: column;
+  line-height: 1.4;
+}
+
+.custom-head__meta strong {
+  font-size: 15px;
+}
+
+.custom-head__meta span {
+  color: #909399;
+  font-size: 12px;
+}
+
+.custom-item {
+  width: 100%;
+  min-width: 0;
+  padding: 2px 0;
+}
+
+.custom-item__row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.custom-item__row--sub {
+  margin-top: 2px;
+}
+
+.custom-item__time {
+  flex: none;
+  color: #3d6cf0;
+  font-size: 11px;
+  font-weight: 600;
+}
+
+.custom-item.is-fair .custom-item__time { color: #e0821b; }
+.custom-item.is-live .custom-item__time { color: #10a37f; }
+.custom-item.is-exam .custom-item__time { color: #8b5cf6; }
+
+.custom-item__name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-size: 12px;
+  color: #303133;
+}
+
+.custom-item__addr {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  color: #a8abb2;
+  font-size: 11px;
+}
+
+.custom-item__tag {
+  flex: none;
+  padding: 0 5px;
+  border-radius: 3px;
+  background: rgba(0, 0, 0, 0.05);
+  color: #909399;
+  font-size: 10px;
+}
+
+.custom-item__tag:empty {
+  display: none;
+}
+
+.custom-empty {
+  padding: 6px 0;
+  color: #dcdfe6;
+  font-size: 12px;
+  text-align: center;
+}
+
+/* ------------------------------ 响应式 ------------------------------ */
+@media (max-width: 1100px) {
+  .doc__toc {
+    display: none;
+  }
+  .demo__cols--events {
+    flex-wrap: wrap;
+  }
+  .event-log {
+    width: 100%;
+  }
+}
+
+@media (max-width: 768px) {
+  .doc {
+    padding: 12px;
+  }
+  .doc__hero {
+    padding: 20px;
+  }
+  .demo {
+    padding: 16px;
+  }
+}
+</style>