SupperGrid

一个轻量但功能完整的 Vue 表格组件，支持排序、筛选、分组、快速检索、底部统计与组尾统计等特性。

快速开始（本地开发）

<template>
  <SupperGrid
    :columns="columns"
    :data="rows"
    :statistics-scope="statisticsScope"
    :show-group-footer="statisticsScope === 'group'"
    :include-quick-search-in-statistics="true"
  />
</template>

<script setup lang="ts">
import SupperGrid from './src/components/SupperGrid.vue'
import { ref } from 'vue'

const columns = [
  { key: 'name', title: '姓名', statistics: { enabled: true, type: 'count', position: 'footer' } },
  { key: 'age', title: '年龄', statistics: { enabled: true, type: 'avg', position: 'both', label: '平均年龄' } },
  { key: 'salary', title: '薪水', statistics: { enabled: true, type: 'sum', position: 'both', label: '总薪水' } }
]

const rows = ref([
  { name: '张三', age: 28, salary: 12000 },
  { name: '李四', age: 32, salary: 15000 },
  { name: '王五', age: 24, salary: 9800 }
])

const statisticsScope = ref<'all' | 'page' | 'group'>('all')
</script>

统计与范围

• statisticsScope

  • all：对过滤后的全部数据进行统计；显示 Footer 统计行。
  • page：仅统计当前页（分页后的数据）；显示 Footer 统计行。
  • group：按分组计算每组的统计；不显示 Footer 统计，建议同时设置 :show-group-footer="true"。

• 统计位置（列级配置 statistics.position）

  • 可选：footer、groupFooter、both。
  • Footer 统计由 StatisticsRow 渲染；组尾统计由 GroupRenderer 渲染并与可见列对齐。

快速检索与统计

• includeQuickSearchInStatistics（默认 true）
  • 开启后，统计的数据源包含快速检索结果：
    • 当 statisticsScope='all' 时，统计使用快速检索后的过滤结果。
    • 当 statisticsScope='page' 时，统计使用分页数据（分页前已包含快速检索）。
    • 当 statisticsScope='group' 时，分组基于排序后的全量视图（已包含快速检索），显示每组汇总。
  • 关闭后，仅考虑筛选面板的过滤结果，不纳入快速检索。

搜索功能

• 快速检索（内置输入框与字段选择）

  • 右下角锚点输入框，默认占位提示含“ESC退出”；输入采用去抖（默认 300ms），支持一键清除。
  • 可在“搜索所有字段”和“自定义字段列表”间切换；仅包含 filterable !== false 的列参与搜索。
  • 数据流：在筛选结果上叠加快速检索，匹配任一所选字段即可保留该行。
    • 参考实现：src/composables/useQuickSearch.ts:28–43（quickFilteredData 计算）、src/composables/useQuickSearch.ts:45–52（onQuickSearch/onQuickSearchClear）。

• 树形检索模式（quickSearchTreeMode）

  • 'path'：仅保留“匹配节点所在路径”（祖先链 + 匹配节点），不包含不匹配的子孙。
  • 'pathWithSubtree'：在 'path' 的基础上，追加“匹配节点的整棵子树”。
  • 扁平树数据（无 children 数组）时，请同时配置 treeNodeIdField 与 treeNodeParentField，组件会回溯父链保留路径。
    • 参考实现：src/components/SupperGrid.vue:1249–1274（ID 映射与保留路径集合）。
  • 递归裁剪并写入层级（__sg_level），用于导出或缩进展示：src/components/SupperGrid.vue:1276–1298。

• 搜索时的展开行为

  • 搜索时自动展开到匹配路径，保证祖先节点可见；清空搜索后恢复此前的展开状态快照。
  • 参考实现：src/components/SupperGrid.vue:1322–1375。

• 与统计的联动

  • 通过 includeQuickSearchInStatistics 控制统计是否包含快速检索结果（默认包含）。

导出与搜索/筛选的关系

• 表格/分组导出遵循当前视图：包含筛选与快速检索后的数据。
  • 排序基于快速检索结果：src/components/SupperGrid.vue:665–667。
  • 行导出读取排序后的全量数据：src/components/SupperGrid.vue:2080–2082。
• 树视图导出忽略折叠与分页，导出“当前搜索裁剪后的整棵树”。
  • 根源数据由搜索裁剪生成：src/components/SupperGrid.vue:1235–1302。
  • 导出时无视展开状态并遍历完整子树：src/components/SupperGrid.vue:2027–2043、src/components/SupperGrid.vue:2069–2073。
  • 未搜索时导出完整树；'path' 与 'pathWithSubtree' 控制匹配节点是否包含整棵子树。

提示：筛选管道入口见 useFiltering（src/components/SupperGrid.vue:613），快速检索在筛选结果之上叠加（表格/分组模式）或匹配全部树节点（树模式）。

使用示例（树视图快速检索）

<template>
  <SupperGrid
    :columns="columns"
    :data="treeData"
    display-mode="tree"
    tree-node-id-field="id"
    tree-node-parent-field="parentid"
    :quick-search-tree-mode="'pathWithSubtree'"
    :include-quick-search-in-statistics="true"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const columns = [
  { key: 'name', title: '名称', filterable: true },
  { key: 'code', title: '编码', filterable: true }
]

const treeData = ref([
  { id: 'A', name: 'A', children: [
    { id: 'A-1', parentid: 'A', name: 'A-1' },
    { id: 'A-2', parentid: 'A', name: 'A-2', children: [
      { id: 'A-2-1', parentid: 'A-2', name: 'A-2-1' }
    ]}
  ]},
  { id: 'B', name: 'B' }
])
</script>

参与字段与行为细节

133→- 默认参与字段：所有 filterable !== false 的列；表格会自动映射到内部的检索字段列表。 134→- 匹配规则：对所选字段执行“包含”判断（区分大小写已统一为不区分，内部对比时降为小写）。 135→- 表格/分组模式的数据源：在筛选结果之上叠加快速检索，见 src/components/SupperGrid.vue:629–639。 136→- 树模式的数据源：对全部树节点执行匹配，随后按 'path'/'pathWithSubtree' 裁剪并写入层级，见 src/components/SupperGrid.vue:1235–1302。 137→- 触发与热键： 138→ - Ctrl+F 打开快速搜索；Esc 关闭。位置：src/components/SupperGrid.vue:1466–1486、src/components/SupperGrid.vue:133–142。 139→ - 打开后自动聚焦输入框，位置：src/components/SupperGrid.vue:1472–1474。 140→ - 在输入框中按 Esc 会清空搜索文本，位置：src/components/QuickSearch.vue:161–164；在叠加层按 Esc 会关闭叠加层，位置：src/components/SupperGrid.vue:133–142。 141→- 字段选择 UI： 142→ - QuickSearch 支持通过 showSearchFields 切换字段选择面板（默认展示）；SupperGrid 内置叠加层为紧凑布局，默认传入 false 隐藏字段列表，位置：src/components/SupperGrid.vue:133–142。 143→- 输入去抖与占位： 144→ - debounce 默认 300ms，位置：src/components/QuickSearch.vue:107–113；输入事件按去抖后触发搜索/清除，位置：src/components/QuickSearch.vue:145–159。 145→ - 默认占位符自动追加“ESC退出”提示，位置：src/components/QuickSearch.vue:128–133。

检索规则与数据类型

• 空值不参与匹配：null/undefined 直接跳过，位置：src/composables/useQuickSearch.ts:35–41。
• 非字符串值会被转换为字符串再匹配（数字、布尔等都可搜索）。
• 输入会执行 trim() 与小写化；多字段命中采用“任一字段命中即保留”的策略。

树模式显示行为示例

• 'path' 模式：
  • 数据：A → A-1, A-2 → A-2-1，搜索命中 A-2-1。
  • 视图：保留 A、A-2、A-2-1 路径；不显示 A-1。
• 'pathWithSubtree' 模式：
  • 同上，并额外保留 A-2 的全部子孙（若有更多子节点，均包含）。

与分页/分组的联动

• 表体分页模式：当启用树形或显示模式为 tree 时，表体统一采用按组分页（避免按行分页破坏树路径），位置：src/components/SupperGrid.vue:1308–1316。
• 分组视图下，分页器与统计遵循当前视图；搜索在分组前叠加，位置：src/components/SupperGrid.vue:94–97（行为说明）。

性能与交互

• 性能：检索与排序会触发数据修订计数，用于缓存与渲染优化，见 src/components/SupperGrid.vue:695–699。
• 虚拟滚动：在非分组、未分页且数据量超阈值时自动开启，保障检索时的滚动性能，见 src/components/SupperGrid.vue:1381–1406。
• 展开策略：检索时自动展开到匹配路径；清空检索后恢复此前快照，见 src/components/SupperGrid.vue:1322–1375。

常见用法（包含统计）

<template>
  <SupperGrid
    :columns="columns"
    :data="rows"
    :include-quick-search-in-statistics="true"  
    :statistics-scope="'all'"
  />
</template>

• 'all' 范围：统计包含筛选+快速检索后的全量数据，见 src/components/SupperGrid.vue:1966。
• 'page' 范围：统计包含当前页（分页前已叠加快速检索）。
• 'group' 范围：统计基于排序后的分组视图（已包含快速检索），在各组显示组尾统计。

FAQ（搜索）

• 为什么树导出不是“当前页”的数据？
  • 树导出在设计上忽略折叠与分页，导出“当前搜索裁剪后的完整树”。若未搜索则导出完整树，见 src/components/SupperGrid.vue:2027–2043、src/components/SupperGrid.vue:2069–2073。
• 我希望导出仅匹配节点及其整棵子树，如何设置？
  • 将 quickSearchTreeMode 设为 'pathWithSubtree'，匹配节点的整棵子树将包含在视图与导出中。 195→- 扁平树数据需要如何配置？ 196→ - 请设置 treeNodeIdField 与 treeNodeParentField，组件会回溯父链保留匹配路径，见 src/components/SupperGrid.vue:1249–1274。 197→- 如何快速打开/关闭搜索？ 198→ - 使用 Ctrl+F 打开快速搜索；Esc 关闭叠加层。位置：src/components/SupperGrid.vue:1466–1486、src/components/SupperGrid.vue:133–142。 199→ - 打开后自动聚焦输入框（提高输入效率），位置：src/components/SupperGrid.vue:1472–1474。 200→ - 在输入框中按 Esc 会清空搜索文本并触发清除事件，位置：src/components/QuickSearch.vue:161–164。 201→- 如何选择参与字段？ 202→ - 默认参与搜索的列为所有 filterable !== false 的列；映射规则见 src/composables/useQuickSearch.ts:18–33。 203→ - 字段选择面板可通过 showSearchFields 控制（默认展示）；叠加层内置为紧凑模式，默认传入 false 隐藏字段列表，位置：src/components/SupperGrid.vue:133–142。 204→- 输入去抖与占位提示如何配置？ 205→ - 输入采用去抖，默认 debounce = 300ms；事件处理见 src/components/QuickSearch.vue:145–159，默认值位置：src/components/QuickSearch.vue:107–113。 206→ - 默认占位符会自动追加“ESC退出”提示，位置：src/components/QuickSearch.vue:128–133。

最小示例（热键与字段选择）

<template>
  <SupperGrid
    :columns="columns"
    :data="rows"
    :include-quick-search-in-statistics="true"
  />
</template>

<script setup lang="ts">
const columns = [
  { key: 'name', title: '名称', filterable: true },
  { key: 'code', title: '编码', filterable: true }
]
const rows = [
  { name: '张三', code: 'A-001' },
  { name: '李四', code: 'B-002' }
]
// 在表格中按 Ctrl+F 打开快速搜索；Esc 关闭叠加层；输入框内 Esc 清空文本
</script>

导航栏与分组模式

• 默认行为：启用分组时不进行分页切片（展示完整分组视图），底部导航栏隐藏。
• showPagerInGroupView（默认 false）
  • 开启后，在分组视图下显示导航栏的分组模式：
    • 显示分组摘要信息：“共 N 组，合计 M 条记录”。
    • 翻页按钮禁用，页面大小选择与快速跳转隐藏，避免与分组视图不一致。
    • 非分组视图下，导航栏仍按常规分页显示与交互。

分页模式

• paginationMode（默认 'rows'）
  • 'rows'：按行分页（当前页数据 pagedData 切片；分组视图不切分分组）。
  • 'groups'：按组分页（对顶层分组进行切片；导航栏启用翻页控件；每页数量取自 pageSize）。
  • 注：组分页下，统计与分组汇总均基于筛选与排序后的分组结构进行；快速检索的纳入由 includeQuickSearchInStatistics 控制。

分组视图自动分页器

• 当 enablePagination=true 并拖动列到分组区域时，若未显式设置 paginationMode，自动启用 'groups' 模式，底部分页器出现。
• 若已设置 paginationMode='rows' 或 'groups'，则按设置执行，不做覆盖。
• 启用虚拟滚动时（virtualScrollEnabled=true），分页器隐藏以避免与滚动交互冲突。

常用属性

• statisticsScope?: 'all' | 'page' | 'group'（默认 all）
• showGroupFooter?: boolean（默认 false）
• includeQuickSearchInStatistics?: boolean（默认 true）
• showPagerInGroupView?: boolean（默认 false）
• paginationMode?: 'rows' | 'groups'（默认 'rows'）
• 其它：columns、data、enablePagination、pageSize、currentPage、sortMode、selectionMode 等。

行为说明

• 数据处理顺序：先筛选（含快速检索）→ 再排序 → 最后分组。
• 'page' 范围统计基于 pagedData（当前页），'all' 范围统计基于 filteredData（过滤结果）。
• 当选择 'group' 范围时，Footer 统计隐藏，转为每组展示组尾统计；建议将 showGroupFooter 与 statisticsScope === 'group' 联动。

示例页面

在 example/App.vue 中可体验：

• “统计包含快速检索”复选框（驱动 includeQuickSearchInStatistics）。
• “统计范围”下拉框（all/page/group），并在选择 group 时显示组尾统计。
• “分组视图显示导航栏”复选框（驱动 showPagerInGroupView）。
• “分页模式”下拉框（rows/groups），体验按组分页与按行分页切换。

通过 NPM 包使用（库模式）

安装并引入样式：

npm install supper-grid

在 ESM 环境中使用（推荐）

import { createApp } from 'vue'
import App from './App.vue'
import SupperGrid, { install as SupperGridPlugin } from 'supper-grid'
import 'supper-grid/style.css'

// 方式一：按需注册组件
createApp(App).component('SupperGrid', SupperGrid).mount('#app')

// 方式二：插件式安装（自动注册组件并可选应用默认/预设/自定义主题）
// createApp(App).use(SupperGridPlugin, { themeName: 'light' }).mount('#app')
// createApp(App).use(SupperGridPlugin, { theme: createTheme({ colors: { primary: '#2563eb' } }) }).mount('#app')

页面中使用：

<template>
  <SupperGrid :columns="columns" :data="rows" />
  <!-- 也可通过 :theme 或 :themeName 进行运行时切换 -->
</template>

构建产物说明：

• 组件入口：dist/index.js（ESM）、dist/index.cjs（CJS）
• 样式文件：dist/style.css（标注 sideEffects，避免被错误 tree-shake）
• 类型定义：dist/types/supperGrid.d.ts

在 CommonJS 环境中使用

const lib = require('supper-grid')
require('supper-grid/style.css')
// 具名导出优先（如果存在）
const SupperGrid = lib.SupperGrid || lib.default
// Vue 3（CJS）
app.component('SupperGrid', SupperGrid)

提示：构建产物同时包含默认导出与具名导出，某些打包器在 CJS 下可能需通过 module.default 访问默认导出。若遇到相关提示，建议统一使用具名导出（如 lib.SupperGrid）。

主要特性总览

• 排序、筛选、快速检索、分组、统计（页脚与组尾）。
• 两种分页模式：rows（按行）与 groups（按组）。
• 两种显示模式：table 与 tree（树形展开）。
• 选择模式：none、single、multiple；可选显示选择列。
• 列拖拽重排、列宽拖拽调整；冻结列边界（树模式下遵循树显示列约束）。
• 导出工具：Excel（exceljs 或 xlsx）多视图导出。

Props 概览（节选）

以下为常用属性，完整列表请参考 src/types/supperGrid.d.ts：

• columns: Column[] 列配置（key、title、sortable、filterable、width 等）。
• data: Record<string, any>[] 表格数据。
• displayMode?: 'table' | 'tree' 显示模式（默认 table）。
• selectionMode?: 'none' | 'single' | 'multiple' 选择模式（默认 none）。
• showSelectionColumn?: boolean 是否显示多选模式下的选择列（默认关闭）。
• showSingleSelectionColumn?: boolean 单选模式是否也显示选择列（默认关闭）。
• statisticsScope?: 'all' | 'page' | 'group' 统计范围（默认 all）。
• showGroupFooter?: boolean 是否显示组尾统计（默认关闭）。
• includeQuickSearchInStatistics?: boolean 统计是否包含快速检索（默认 true）。
• quickSearchTreeMode?: 'path' | 'pathWithSubtree' 树形快速检索的显示模式（默认 'path'）。
• showPagerInGroupView?: boolean 分组视图下显示分页导航栏（默认 false）。
• paginationMode?: 'rows' | 'groups' 分页模式（默认 rows）。
• initialExpandStrategy?: 'firstPath' | 'firstGroupFully' | 'expandAll' | 'collapseAll' 初始分组展开策略。
• resolveRowId?: (row) => string 自定义行 ID 解析器，返回稳定唯一 ID。
• cellEditable?: boolean 全局单元格编辑开关（默认关闭）。

事件（常用）

• 行级事件：row-click、row-dblclick、row-contextmenu。
• 单元格事件：cell-click、cell-dblclick、cell-contextmenu、cell-edit。
• 分页事件：page-change（树模式下子项被截断时自动上报目标页）。
• 选择事件：selection-change。
• 分组事件：group-change、group-toggle、reorder-groups、update-group、group-clear、group-expand/collapse。
• 表头交互：header-click、filter-click、column-drag-start/drop、resize-start/move/end、toggle-select-all。

示例：

<SupperGrid @row-click="onRowClick" @cell-edit="onCellEdit" @page-change="onPageChange" />

导出工具（API）

库同时导出常用导出函数，可在 ESM 环境中使用：

import { exportDataFile, type ExportFileType } from 'supper-grid'

// 简单数据导出（xls/xlsx）
await exportDataFile(columns, rows, { fileName: '数据.xlsx', type: 'xlsx' })

提示：高级导出函数（如保留样式、分组/树视图导出）目前作为内部工具存在，未作为公共 API 暴露；后续版本将统一通过公共入口提供更丰富的导出选项。

调试与日志开关（仅开发环境）

为避免生产环境噪音，非错误级日志在生产环境默认关闭；以下开关仅在开发环境有效：

• 冻结调试：window.__SG_DEBUG_FREEZE__ = true
  • 控制 SupperGrid.vue 与 useFreeze.ts 中冻结相关的详细日志（列重排、边界更新等）。
• 样式调试：window.__SG_DEBUG_GRID_STYLES__ = true
  • 控制 useGridStyles.ts 中的网格样式输出（列模板与 parts）。
• 数据库调试（Node/浏览器）：window.__SG_DEBUG_DB__ = true
  • 控制 src/utils/database.ts 中的数据库连接与检查日志；Node 环境在开发模式下默认输出，浏览器需显式开启。

保留错误日志（console.error）以便诊断，其他日志在开发模式且开关开启时才会输出。

后端 API 与数据库

示例项目包含一个可选的 API 与真实 SQLite 数据库，用于大数据量演示：

• API 基地址：通过环境变量 VITE_SG_API_BASE 配置（默认 http://127.0.0.1:3001）。
• 请求上限与超时：VITE_SG_API_LIMIT（默认 20000）、VITE_SG_API_TIMEOUT（默认 20000ms）。
• Node 环境真实数据库：example/test_database.db，由 better-sqlite3 读取。

常用脚本：

• server/api-server.js 启动本地 API（需 npm install 于 server/）。
• diagnose-database.js 用于诊断数据库连通性与表结构。
• example/scripts/maintain-db.js 数据库维护（WAL 合并、VACUUM、完整性检查）。

样式与主题

• 默认主题变量位于 src/style/theme.scss，全局样式在 src/style/global.scss。
• 组件样式已抽取至 dist/style.css，使用 npm 包时请显式引入：import 'supper-grid/style.css'。
• 可通过 ThemeSwitcher.vue 在示例中切换主题，或在应用中覆盖 CSS 变量实现自定义主题。

最小可运行示例（无需 Provider）

仅引入组件与样式即可渲染（缺少 Provider 时库在开发环境给出警告并自动使用默认主题）：

import { createApp } from 'vue'
import App from './App.vue'
import 'supper-grid/style.css'
import { SupperGrid } from 'supper-grid'

createApp(App).component('SupperGrid', SupperGrid).mount('#app')

正式接入示例（Provider 包裹与主题切换）

通过 Provider 显式注入主题，并支持 props 快速切换主题：

<template>
  <ThemeProvider>
    <SupperGrid :columns="columns" :data="rows" :themeName="themeName" />
  </ThemeProvider>
  <button @click="themeName = themeName === 'light' ? 'dark' : 'light'">切换主题</button>
</template>

<script setup lang="ts">
import { ThemeProvider, createTheme } from 'supper-grid'
import { ref } from 'vue'
const themeName = ref<'light' | 'dark'>('light')
// 也可通过 :theme 传入自定义主题对象（优先级最高）
// const custom = createTheme({ colors: { primary: '#2563eb' } })
</script>

主题优先级与传参说明：

• 主题应用优先级：props.theme > props.themeName > ThemeProvider（若存在）> 默认主题。
• themeName 支持两种传参：
  • 中文显示名，例如：'浅色主题'、'深色主题'、'默认主题'。
  • 预设键名，例如：'light'、'dark'、'default'、'blue' 等。
• 支持运行时动态切换：更新 :theme 或 :themeName 会立即生效（组件内部已监听并应用）。

插件式安装（可选一次性应用主题）：

import { install as SupperGridPlugin } from 'supper-grid'
// apply by preset key
app.use(SupperGridPlugin, { themeName: 'dark' })
// or apply by full object (highest priority)
// app.use(SupperGridPlugin, { theme: createTheme({ colors: { primary: '#2563eb' } }) })

主题与切换器（公开导出，>= 0.1.2）

从 0.1.2 版本起，库公开以下主题相关能力：

• 组件：ThemeProvider（主题上下文提供者）、ThemeSwitcher（可视化主题切换器）
• 钩子：useTheme、useThemeProvider
• 管理器与预设：ThemeManager、defaultTheme、presetThemes

用法示例：

<template>
  <ThemeProvider>
    <button class="button" @click="showTheme = true">切换主题</button>
    <SupperGrid :columns="columns" :data="rows" />

    <ThemeSwitcher v-if="showTheme" @close="showTheme=false" @theme-change="onThemeChange" />
  </ThemeProvider>
  <!-- 在入口处引入样式：import 'supper-grid/style.css' -->
</template>

<script setup lang="ts">
import SupperGrid, { ThemeProvider, ThemeSwitcher, useTheme } from 'supper-grid'
import 'supper-grid/style.css'
import { ref } from 'vue'

const columns = [
  { key: 'name', title: '姓名' },
  { key: 'age', title: '年龄' }
]
const rows = ref([
  { name: '张三', age: 28 },
  { name: '李四', age: 32 }
])

const showTheme = ref(false)
const { theme } = useTheme()
const onThemeChange = (name: string) => {
  console.log('当前主题：', name)
}
</script>

开发、构建与测试

• 开发：npm run dev
• 构建（库模式）：npm run build，输出 dist/index.js 与 dist/style.css。
• 测试：npm test（Vitest + Vue Test Utils + JSDOM）。

提示：构建过程中可能看到 Sass 的“legacy JS API”弃用警告，源自上游工具链；不影响功能。可在未来升级到 Sass 2.0 后移除该警告。

另外：若在工程日志中看到 “defineProps is a compiler macro and no longer needs to be imported”，请移除对该宏的 import（Vue 3 编译器宏无需导入）。

常见问题（FAQ）

• 为什么分组视图下分页器不可点击？
  • 当 paginationMode='rows' 且启用分组时，分页器默认隐藏；启用 showPagerInGroupView 后显示分组摘要，但不提供行分页。若需按组分页，请设置 paginationMode='groups'。
• 树视图下冻结行为与表格有何不同？
  • 树模式下冻结遵循“树显示列优先”策略：若未建立冻结边界，会以树显示列作为起始边界，仅更新边界而不对树显示列重排。
• 我在生产环境看不到调试日志？
  • 非错误日志默认关闭，仅在开发环境且显式开启相关开关时输出；错误日志保持输出以便诊断。

版本与兼容性

• 运行环境：Vue 3、现代浏览器；Node 16+（示例/工具脚本）。
• 构建目标：ESM（dist/index.js）。

截图与动图（自动采集）

为方便在 README 展示效果，项目提供自动抓取示例页面截图与帧序列的脚本：

1. 启动本地开发服务器：
   • npm run dev（默认 http://localhost:5173/，若端口占用将自动切换到 5174）
2. 安装依赖（仅首次）：
   • npm i -D playwright
3. 采集截图/帧序列：
   • npm run demo:capture（默认从 http://localhost:5173/ 抓取）
   • 或 npm run demo:capture:url（从 http://localhost:5174/ 抓取）
   • 输出位置：docs/assets/suppergrid-basic.png 与 docs/assets/frames/frame-***.png
4. 合成动图（需本机安装 ffmpeg）：
   • npm run demo:gif
   • 生成：docs/assets/suppergrid-demo.gif

完成后，可在 README 中引用如下资源（生成后可见）：

变更日志

0.1.1

• 修复：在 SupperGrid.vue 中将主题相关的 onMounted 与 watch 逻辑移动到 defineProps 之后，避免对未初始化 props 的访问（修复 ReferenceError: Cannot access 'props' before initialization）。
• 优化：完善 README 文档（主题优先级、themeName 支持中文/英文、运行时动态切换、ESM/CJS 用法说明）。
• 提示：构建输出可能提示“同时使用默认和具名导出”，CommonJS 用户可通过 module.default 访问默认导出，或统一使用具名导出以避免困惑。

参与贡献

欢迎通过 PR 或 Issue 参与改进。请参考 CONTRIBUTING.md。

如需更详细的 API 说明或扩展示例，请查看 src/types/supperGrid.d.ts 与示例目录下各组件的用法。

• 示例与本地 API 仅用于开发与演示，配置位于 .env.local；该文件已加入 .gitignore，不会随包发布。
• 对外发布的库仅暴露 SupperGrid 组件与数据导出工具，不依赖本地服务或环境变量。