@icc-grow/web-components 1.0.0

package/dist/types/utils/dom.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DOM 测量工具函数
+ */
+/**
+ * 获取元素的行高（px）
+ * 如果 line-height 为 normal / 无法解析，返回 fallback 值
+ */
+export declare function getLineHeight(el: HTMLElement, fallback?: number): number;
+/**
+ * 获取元素的垂直内边距总和（paddingTop + paddingBottom）
+ */
+export declare function getVerticalPadding(el: HTMLElement): number;
+//# sourceMappingURL=dom.d.ts.map

package/dist/types/utils/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../src/utils/dom.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,SAAK,GAAG,MAAM,CAGpE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAG1D"}

package/dist/types/utils/get-by-path.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 嵌套字段路径工具函数
+ * 支持点号分隔的路径读写，如 'user.address.city'
+ */
+/**
+ * 根据路径从对象中取值
+ *
+ * @example
+ * getByPath({ user: { name: 'John' } }, 'user.name') // 'John'
+ * getByPath({ list: [{ id: 1 }] }, 'list.0.id')      // 1
+ */
+export declare function getByPath<T = unknown>(obj: Record<string, unknown>, path: string, defaultValue?: T): T;
+/**
+ * 根据路径向对象中设值
+ *
+ * @example
+ * const obj = { user: { name: 'John' } };
+ * setByPath(obj, 'user.name', 'Jane'); // obj.user.name === 'Jane'
+ */
+export declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+//# sourceMappingURL=get-by-path.d.ts.map

package/dist/types/utils/get-by-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-by-path.d.ts","sourceRoot":"","sources":["../../../src/utils/get-by-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAYtG;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAc1F"}

package/dist/types/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from './dom';
+export * from './get-by-path';
+export * from './install';
+export * from './z-index';
+export * from './throttle';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/types/utils/install.d.ts

@@ -0,0 +1,17 @@
+import { Plugin } from 'vue';
+type SFCWithInstall<T> = T & Plugin;
+/**
+ * 为组件添加 install 方法，使其可以通过 app.use() 全局注册
+ *
+ * @example
+ * // 按需导入
+ * import { IButton } from '@icc-grow/web-components'
+ *
+ * // 全局注册
+ * app.use(IButton)
+ */
+export declare function withInstall<T extends {
+    name: string;
+}>(component: T): SFCWithInstall<T>;
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/types/utils/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/utils/install.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,MAAM,EAAE,MAAM,KAAK,CAAC;AAGvC,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAMvF"}

package/dist/types/utils/throttle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 节流函数
+ * @param fn 需要节流的函数
+ * @param delay 延迟时间（毫秒）
+ */
+export declare function throttle<T extends (...args: unknown[]) => void>(fn: T, delay: number): T;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/types/utils/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../../src/utils/throttle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAuBxF"}

package/dist/types/utils/use-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 获取全局唯一的组件级 ID 标识符
+ * 优先采用 Vue 3.5+ 提供的内建 SSR 安全 `useId()`。
+ * 对于 Vue 版本较低或在非活跃组件实例外调用时，回退到内部计次以防环境崩溃或水合错误（虽然不支持降级版的完美 SSR，但能确保基础可用性）。
+ *
+ * @returns {string} 唯一 ID 字符串
+ */
+export declare function useId(): string;
+//# sourceMappingURL=use-id.d.ts.map

package/dist/types/utils/use-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-id.d.ts","sourceRoot":"","sources":["../../../src/utils/use-id.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAY9B"}

package/dist/types/utils/z-index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 全局 z-index 管理器
+ * 所有浮层组件（Popover / Tooltip / Dropdown / Modal 等）共用，
+ * 保证后打开的浮层始终在先打开的上方。
+ */
+/**
+ * 获取下一个 z-index（递增后返回）
+ * 每次打开浮层时调用，保证层叠顺序
+ */
+export declare function nextZIndex(): number;
+/**
+ * 获取当前 z-index（不递增）
+ * 用于查询当前最高层级
+ */
+export declare function currentZIndex(): number;
+/**
+ * 设置 z-index 起始值
+ * 允许业务侧自定义起始值，避免与宿主应用冲突
+ */
+export declare function setInitialZIndex(val: number): void;
+//# sourceMappingURL=z-index.d.ts.map

package/dist/types/utils/z-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"z-index.d.ts","sourceRoot":"","sources":["../../../src/utils/z-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAElD"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@icc-grow/web-components",
+  "version": "1.0.0",
+  "description": "ICC Grow 内部 Web 组件库",
+  "author": "ICC Grow",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "./dist/lib/index.cjs",
+  "module": "./dist/es/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/es/index.mjs",
+      "require": "./dist/lib/index.cjs"
+    },
+    "./style.css": "./dist/es/style.css",
+    "./tailwind-preset": "./tailwind-preset.ts"
+  },
+  "files": [
+    "dist",
+    "tailwind-preset.ts",
+    "src/styles/themes/",
+    "skills/"
+  ],
+  "sideEffects": [
+    "./dist/es/style.css"
+  ],
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.5",
+    "autoprefixer": "^10.4.27",
+    "cssnano": "^7.1.3",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^3.4.19",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.5.3",
+    "vue": "^3.5.30"
+  },
+  "dependencies": {
+    "@floating-ui/vue": "^1.1.11",
+    "async-validator": "^4.2.5",
+    "colord": "^2.9.3",
+    "dayjs": "^1.11.20"
+  },
+  "scripts": {
+    "build": "vite build",
+    "type-check": "vue-tsc --noEmit"
+  }
+}

package/skills/icc-web-components/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: icc-web-components
+description: >
+  ICC Web Components (Vue 3) 组件库使用指南。当用户需要用 Vue 3 构建中后台管理页面、
+  从 Figma 设计稿或截图生成页面代码时使用此 skill。当项目依赖了 @icc-grow/web-components，
+  或代码中出现 i-button、i-table 等 i- 前缀组件时，必须使用此 skill 确保正确的 API 用法。
+  适用于 CRUD 列表、表单详情、仪表盘等中后台业务页面的代码生成。
+  即使用户只说"做个用户管理页面"或"把这个截图转成代码"也应触发。
+---
+
+# ICC Web Components
+
+`@icc-grow/web-components` — Vue 3 企业级中后台组件库。
+
+## 技术栈
+
+- **框架**: Vue 3 Composition API (`<script setup lang="ts">`)
+- **样式**: Tailwind CSS v3，CSS 变量前缀 `--i-color-`
+- **组件前缀**: `i-`，BEM 类名 `.i-button`、`.i-button__icon`、`.is-disabled`
+- **包名**: `@icc-grow/web-components`
+- **导入方式**: `import { IButton, ITable } from '@icc-grow/web-components'`
+- **样式引入**: `import '@icc-grow/web-components/style.css'`
+- **Tailwind Preset**: 消费方需在 `tailwind.config.ts` 中使用 `presets: [iccPreset]`
+
+## 核心原则
+
+1. **优先使用组件** — 看到按钮用 `IButton`，不要写 `<button>`；看到空状态用 `IEmpty`，不要写自定义 div
+2. **使用语义 token** — 用 `bg-primary` / `text-danger` 等 Tailwind 主题色，禁止 `bg-blue-500` 等原生色
+3. **Pattern-First** — 先识别页面属于哪种模式（CRUD / 表单 / 弹窗），读模式骨架后修改生成
+4. **不随意新增颜色** — 所有颜色由 CSS 变量体系管理，遇到未定义颜色时请标记出来，不要自己新增颜色
+5. **间距用组件** — 使用 `ISpace` 组件处理间距，而不是手动添加 margin/padding
+
+## 页面模式选型
+
+在生成页面代码之前，**先识别设计稿属于哪种页面模式**，然后读取对应的 pattern 文件获取完整代码骨架。
+
+| 设计稿特征 | 模式 | 读取文件 |
+|-----------|------|---------|
+| 搜索条件区 + 数据表格 + 分页器 | CRUD 列表页 | → `patterns/crud-list.md` |
+| 整页表单 + 提交/返回按钮 | 表单页 | → `patterns/form-page.md` |
+| 弹窗或抽屉中包含表单 | 弹窗表单 | → `patterns/dialog-form.md` |
+| 左侧树形 + 右侧内容区 | 树形管理 | → `patterns/tree-manage.md` |
+| 顶部 Tabs 切换多个子页面 | 标签页 | → `patterns/tabs-page.md` |
+
+> 如果一个页面包含多种模式（如 tabs-page 里的每个 tab 是 crud-list），组合使用。
+
+## 组件选型速查
+
+看到设计稿中的 UI 元素时，用此表找到对应组件和 API 文件。
+
+> **"何时选"**列描述选型判断；API 细节在对应 `references/` 文件中。
+> 两个高频组合文件覆盖 80% 场景：`i-crud-page.md`（列表页）、`i-form.md`（表单页）。
+
+### CRUD 列表页组合 → `references/i-crud-page.md`
+
+| UI 元素 | 组件 | 何时选 |
+|--------|------|-------|
+| 页面骨架 | `IPageLayout` | **每个页面必用**。标题/搜索/主体/底部四区域 |
+| 搜索区 | `IPageSearch` | 搭配 IPageLayout 的 #search 插槽 |
+| 按钮 | `IButton` | 所有可点击操作。实心/描边/文字三种形态 |
+| 输入框 | `IInput` | 单行文本/密码输入 |
+| 下拉选择 | `ISelect` | 从固定选项中选一个或多个 |
+| 日期选择 | `IDatePicker` | 日期/周/月/年选择，可范围/多选 |
+| 表格 | `ITable` | 数据量 <500 行的常规表格 |
+| 分页 | `IPagination` | 表格/列表底部分页器 |
+
+### 表单组合 → `references/i-form.md`
+
+| UI 元素 | 组件 | 何时选 |
+|--------|------|-------|
+| 表单容器 | `IForm` | 包裹所有表单控件，提供校验/重置 |
+| 表单项 | `IFormItem` | 每个字段的 label + 校验展示容器 |
+| 输入框 | `IInput` | 单行文本/密码输入 |
+| 数字输入 | `IInputNumber` | 纯数字，步进/边界/精度 |
+| 多行文本 | `ITextarea` | 备注、描述输入 |
+| 下拉选择 | `ISelect` | 从固定选项中选一个或多个 |
+| 日期选择 | `IDatePicker` | 日期/周/月/年选择 |
+| 开关 | `ISwitch` | 二态切换（开/关） |
+| 复选框 | `ICheckbox` | 多选场景，单独或 Group 使用 |
+| 单选框 | `IRadio` | 单选，选项 ≤5 个时优先用 Radio |
+
+### 其他组件（按需读取对应文件）
+
+| UI 元素 | 组件 | 何时选 | API 文件 |
+|--------|------|-------|---------|
+| 图标 | `IIcon` | iconfont 或自定义 SVG | `i-icon.md` |
+| 标签 | `ITag` / `ITagGroup` | 状态标签、分类标签 | `i-tag.md` |
+| 角标 | `IBadge` | 右上角数字/红点 | `i-badge.md` |
+| 头像 | `IAvatar` / `IAvatarGroup` | 用户头像，可重叠 | `i-avatar.md` |
+| 过渡动画 | `ITransition` | v-if/v-show 过渡 | `i-transition.md` |
+| 树形选择 | `ITreeSelect` | 树形层级数据选择 | `i-tree-select.md` |
+| 时间选择 | `ITimePicker` | 时:分:秒 滚轮 | `i-time-picker.md` |
+| 颜色选择 | `IColorPicker` | 颜色值输入 | `i-color-picker.md` |
+| 文件上传 | `IUpload` | 文件/图片上传 | `i-upload.md` |
+| 大数据表格 | `IVirtualTable` | >500 行，虚拟滚动 | `i-virtual-table.md` |
+| 树形控件 | `ITree` | 层级数据展示/选择 | `i-tree.md` |
+| 卡片 | `ICard` | 内容分区容器 | `i-card.md` |
+| 图片 | `IImage` / `IImageGroup` | 图片展示 + 预览 | `i-image.md` |
+| 空状态 | `IEmpty` | 无数据占位。⚠️ 不要自己写 div | `i-empty.md` |
+| 进度条 | `IProgress` | 线性进度展示 | `i-progress.md` |
+| 对话框 | `IDialog` / `IDrawer` | 模态弹窗 / 侧边面板 | `i-dialog.md` |
+| 反馈服务 | `IConfirm` / `IMessage` / `INotification` | ⚠️ 服务调用，不是组件 | `i-feedback.md` |
+| 浮层提示 | `IPopover` / `ITooltip` | 弹出气泡 / 文字提示 | `i-popover.md` |
+| 加载中 | `ILoading` | v-loading 指令或服务 | `i-loading.md` |
+| 标签页 | `ITabs` | Tab 切换，数据驱动 | `i-tabs.md` |
+| 下拉菜单 | `IDropdown` | 按钮触发的操作菜单 | `i-dropdown.md` |
+| 步骤条 | `ISteps` | 多步骤流程引导 | `i-steps.md` |
+| 侧边菜单 | `IMenu` | 侧边栏导航 | `i-menu.md` |
+| 间距 | `ISpace` | 间距排列。⚠️ 不要手动 gap/margin | `i-space.md` |
+| 滚动条 | `IScrollbar` | 自定义美化滚动条 | `i-scrollbar.md` |
+| 虚拟列表 | `IVirtualList` | 海量列表渲染 | `i-virtual-list.md` |
+| 拖拽 | `IDraggable` / `ISortable` | 拖拽移动 / 排序 | `i-draggable.md` |
+
+## Critical Rules
+
+> 生成代码前必须过一遍此清单。详细的 Incorrect/Correct 代码对见各 rules/ 文件。
+
+### 样式红线 → `rules/styling.md`
+
+- ❌ 禁止硬编码颜色（`#xxx`、`rgb()`）和 Tailwind 原生色（`bg-blue-500`）→ 用 `bg-primary` 等语义 token
+- ❌ 禁止手动 `gap-*` / `mr-*` 做间距 → 用 `ISpace` 组件
+- ❌ 禁止自行新增 CSS 变量 → 遇到未定义颜色标记出来，不要自己新增
+- ❌ 禁止 `style` 内联写颜色
+
+### 表单红线 → `rules/forms.md`
+
+- ❌ 禁止裸用 `<input>` / `<select>` 等原生元素 → 用 `IInput` / `ISelect` 等组件
+- ❌ 禁止不包裹 `IForm` 直接用表单控件 → 整个表单区域用 `IForm` + `IFormItem`
+- ❌ 禁止手写搜索区布局 → 用 `IPageSearch` 组件
+- ❌ 表单输入框必须限制宽度（`w-[400px]` 等），不要全宽
+
+### 组合红线 → `rules/composition.md`
+
+- ❌ 禁止用 `IDialog` 做简单确认弹窗 → 用 `IConfirm` 服务调用
+- ❌ 禁止自己写 toast / message → 用 `IMessage.success()` 等
+- ❌ 禁止自己写空状态 div → 用 `IEmpty` 组件
+- ❌ 禁止自己写 loading 遮罩 → 用 `v-loading` 指令
+- ❌ 弹窗表单必须抽离为独立子组件，不要混在列表页中
+
+## 代码约定
+
+### 基本格式
+
+```vue
+<template>
+  <!-- 模板内容 -->
+</template>
+
+<script setup lang="ts">
+import { ref, reactive } from 'vue'
+import { IButton, ITable, IMessage } from '@icc-grow/web-components'
+import type { TableColumn } from '@icc-grow/web-components'
+
+// 类型定义
+interface UserItem {
+  id: number
+  name: string
+}
+
+// 响应式数据
+const loading = ref(false)
+const tableData = ref<UserItem[]>([])
+
+// 方法
+function handleSearch() {
+  // ...
+}
+</script>
+```
+
+### 关键约定
+
+- **组件全部按需导入**，不要整体导入
+- **类型使用 `import type`** 区分值/类型导入
+- **Props 类型从组件库导入**：`import type { TableColumn } from '@icc-grow/web-components'`
+- **服务型组件直接调用**：`IMessage.success('操作成功')`、`IConfirm({...})`
+- **v-model 双向绑定**：`v-model:visible`、`v-model:currentPage`
+- **表格列用 `columns` 数组配置**，不用子组件
+
+## 生成页面工作流
+
+> ⚠️ **不要一上来就读所有 references/ 文件**。patterns/ 骨架已包含最常见的组件用法，references/ 只在骨架不够时按需查阅。
+
+```
+1. 识别页面模式 → 查【页面模式选型】→ 读对应 patterns/ 骨架（主力文档，覆盖 80% 用法）
+2. 对照【组件选型速查】→ 确认骨架中没覆盖到的组件
+3. 仅当遇到骨架未涉及的组件或不常见的 Prop → 读 references/ 中对应分类文件（不要全读）
+4. 过一遍【Critical Rules】清单 → 有疑问时读 rules/ 详细正反例
+5. 生成 <script setup lang="ts"> 格式的 .vue 文件
+```
+

package/skills/icc-web-components/patterns/crud-list.md

@@ -0,0 +1,195 @@
+# Pattern: CRUD 列表页
+
+> 搜索条件区 + 数据表格 + 分页器
+
+## ⚠️ 类型文件要求
+
+**所有 TS 类型（`interface`、`type`、常量映射）必须新建 `types.ts` 文件**，与 `.vue` 文件同目录放置。禁止在 `.vue` 文件中内联定义业务类型。
+
+```
+views/
+  your-page/
+    index.vue        ← 页面组件
+    types.ts         ← 业务类型定义
+```
+
+### types.ts 骨架
+
+```typescript
+// ---- 搜索查询参数 ----
+export interface XxxListQuery {
+  pageIndex: number;
+  pageSize: number;
+  name?: string;
+  status?: number;
+}
+
+// ---- 列表行数据 ----
+export interface XxxListVO {
+  id: number;
+  name: string;
+  status: number;
+  createdAt: string;
+}
+
+// ---- 常量映射（使用 as const 保证类型安全） ----
+export const STATUS_MAP = {
+  1: '启用',
+  0: '禁用',
+} as const;
+```
+
+---
+
+## 完整骨架（index.vue）
+
+```vue
+<template>
+  <IPageLayout title="Xxx管理">
+    <!-- 标题栏右侧操作 -->
+    <template #header-action>
+      <IButton icon="icon-add" @click="handleAdd">新增</IButton>
+    </template>
+
+    <!-- 搜索区 -->
+    <template #search>
+      <IInput v-model="searchQuery.name" placeholder="名称" clearable />
+      <ISelect v-model="searchQuery.status" :options="statusOptions" placeholder="状态" clearable />
+      <IButton @click="handleSearch">查询</IButton>
+      <IButton type="black" plain @click="handleReset">重置</IButton>
+    </template>
+
+    <!-- 表格 -->
+    <ITable v-loading="loading" :data="tableData" :columns="tableColumns" row-key="id">
+      <!-- 操作列 -->
+      <template #action="{ row }">
+        <ISpace :size="4">
+          <IButton text @click="handleEdit(row)">编辑</IButton>
+          <IButton text type="danger" @click="handleDelete(row)">删除</IButton>
+        </ISpace>
+      </template>
+    </ITable>
+
+    <!-- 分页 -->
+    <template #footer>
+      <IPagination
+        v-model:current-page="searchQuery.pageIndex"
+        v-model:page-size="searchQuery.pageSize"
+        :total="pageTotal"
+        @change="fetchList"
+      />
+    </template>
+  </IPageLayout>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, onMounted } from 'vue';
+import { IPageLayout, ITable, IPagination, IButton, IInput, ISelect, ISpace, IConfirm, IMessage } from '@icc-grow/web-components';
+import type { ConfirmResult, TableColumn } from '@icc-grow/web-components';
+import type { XxxListQuery, XxxListVO } from './types';
+import { STATUS_MAP } from './types';
+
+// ---- 选项数据（从映射对象自动生成） ----
+const statusOptions = Object.entries(STATUS_MAP).map(([value, label]) => ({
+  label,
+  value: Number(value),
+}));
+
+// ---- 总数 ----
+const pageTotal = ref(0);
+
+// ---- 搜索条件（使用泛型约束） ----
+const searchQuery = reactive<XxxListQuery>({
+  pageIndex: 1,
+  pageSize: 20,
+  name: '',
+  status: undefined,
+});
+
+// ---- 表格 ----
+const loading = ref(false);
+const tableData = ref<XxxListVO[]>([]);
+
+const tableColumns: TableColumn<XxxListVO>[] = [
+  { label: '名称', prop: 'name' },
+  {
+    label: '状态',
+    prop: 'status',
+    formatter: (_row, _col, cellValue) => STATUS_MAP[cellValue as keyof typeof STATUS_MAP] || '未知',
+  },
+  { label: '创建时间', prop: 'createdAt' },
+  { label: '操作', prop: 'action', fixed: 'right' },
+];
+
+// ---- 方法 ----
+/** 获取列表数据 */
+async function fetchList() {
+  loading.value = true;
+  try {
+    // TODO: 替换为真实 API 调用
+    const res = await api.getList(searchQuery);
+    tableData.value = res.list;
+    pageTotal.value = res.total;
+  } catch (error) {
+    console.error(`获取列表失败: ${error}`);
+  } finally {
+    loading.value = false;
+  }
+}
+
+/** 搜索（重置页码为 1） */
+function handleSearch() {
+  searchQuery.pageIndex = 1;
+  fetchList();
+}
+
+/** 重置搜索条件 */
+function handleReset() {
+  Object.assign(searchQuery, {
+    name: '',
+    status: undefined,
+  });
+  handleSearch();
+}
+
+function handleAdd() {
+  // TODO: 打开新增弹窗
+}
+
+function handleEdit(row: XxxListVO) {
+  // TODO: 打开编辑弹窗
+}
+
+function handleDelete(row: XxxListVO) {
+  IConfirm.error({
+    title: '确认删除',
+    content: `确定删除「${row.name}」吗？删除后不可恢复。`,
+  })
+    .then(async (value: ConfirmResult) => {
+      if (value === 'confirm') {
+        // TODO: 替换为真实 API 调用
+        await api.delete(row.id);
+        IMessage.success('删除成功');
+        fetchList();
+      }else{
+        IMessage.error('删除失败');
+      }
+    })
+}
+
+onMounted(() => fetchList());
+</script>
+```
+
+## 关键要点
+
+1. **类型拆分**：所有 `interface`、`type`、常量映射必须放在同目录的 `types.ts` 中，`.vue` 文件通过 `import type` 引入
+2. **IPageLayout** 提供插槽：`#header-action` / `#search` / `default` / `#footer`
+3. **常量映射 → 选项**：使用 `as const` 定义映射对象，通过 `Object.entries()` 自动生成下拉选项，避免手动维护两份数据
+4. **列格式化**：枚举值展示优先使用 `TableColumn.formatter`，避免为简单映射单独写 `<template #slot>` 插槽；仅当需要渲染组件（如 `ITag`、`IButton`）时才使用插槽
+5. **搜索条件**：`searchQuery` 使用 `reactive<QueryType>()` 泛型约束，确保类型安全
+6. **分页属性**：使用 `v-model:current-page` / `v-model:page-size`（kebab-case）
+7. **表格操作列**：使用 `text` 按钮 + `ISpace :size="4"` 间隔
+8. **删除确认**：使用 `IConfirm.error()` + `.then(value => if(value === 'confirm'))` 模式，搭配 `.catch()` 处理取消
+9. **重置按钮**：使用 `type="black" plain` 样式，重置时将 `pageIndex` 重置为 1
+10. **API 占位**：使用 `// TODO: 替换为真实 API 调用` 标注，禁止在模板中编写 mockApi