@cghbcf/xp-ui 1.1.0 → 1.3.0

package/README.md

@@ -9,7 +9,7 @@
 - 🎨 现代化设计风格，支持主题定制（浅色 / 暗黑双主题）
 - 🎛️ 可视化主题定制面板 —— 实时修改颜色、一键导出 JSON/CSS
 - 🌈 主色自动派生（-light / -dark / -bg / -border），无需手动配置
-- 🔧 丰富的组件库，覆盖常用场景（Button / Input / Dialog / Card / Icon / Tabs / Empty / Toast / ContextMenu 等 20+ 组件）
+- 🔧 丰富的组件库，覆盖常用场景（Button / Input / Select / Dialog / Card / Icon / Tabs / Table / Pagination / Empty / Toast / ContextMenu / Menu 等 27+ 组件）
 - 💎 完整的 CSS 变量（Design Tokens）系统，便于深度定制
 - 💾 主题配置自动持久化到 localStorage，刷新页面不丢失
 
@@ -76,7 +76,25 @@ initTheme()
 
 图标文件统一存放在 `src/components/icon/icons/` 目录下，组件在构建时通过 `import.meta.glob` 自动扫描该目录，**新增图标只需放入 `.svg` 文件**，即可用同名 `name` 直接引用（例如 `jiantou.svg` 对应 `name="jiantou"`）。
 
-图标内部硬编码的 `fill` / `stroke` 颜色（除 `none` 外）会被自动替换为 `currentColor`，因此 `color` 属性始终生效。当 `name` 不存在时，会展示占位符（`?`）便于排查。
+图标内部硬编码的 `fill` / `stroke` 颜色（除 `none` 外）会被自动替换为 `currentColor`，因此 `color` 属性始终生效。**未指定 `color` 时图标默认继承当前文字颜色，便于通过父元素着色（如按钮 hover 高亮）。** 当 `name` 不存在时，会展示占位符（`?`）便于排查。
+
+#### 内置图标
+
+下表为当前内置的 18 个图标（不含占位符）：
+
+| name | 视觉 | name | 视觉 |
+|------|------|------|------|
+| `back` 返回 | ← | `forward` 前进 | → |
+| `up` 上一级 | ↑ | `arrow-right` 右箭头 | →▸ |
+| `refresh` 刷新 | ⟳ | `chevron-up` 上箭头 | ∧ |
+| `chevron-down` 下箭头 | ∨ | `close` 关闭 | ✕ |
+| `folder` 文件夹 | 📁 | `folder-add` 新建文件夹 | 📁+ |
+| `list` 列表视图 | ☰ | `grid` 网格视图 | ▦ |
+| `settings` 设置 | ⚙ | `star` 星标 | ☆ |
+| `star-fill` 星标实心 | ★ | `upload` 上传 | ⇧ |
+| `home` 首页 | ⌂ | `jiantou` 箭头 | ◀ |
+
+> 图标总览见演示站 `Icon 图标` 页，点击图标可复制 `XpIcon` 代码。新增图标只需放入 `icons/` 目录即可自动出现。
 
 #### 基础用法
 
@@ -262,6 +280,54 @@ nextTick(() => {
 
 ---
 
+### Select 选择器
+
+下拉选择器，使用 Teleport 渲染浮层。支持键盘操作（Enter/Space 打开、上下键切换、Esc 关闭）、清空、尺寸与禁用态。
+
+#### 基础用法
+
+```vue
+<template>
+  <XpSelect v-model="city" :options="options" placeholder="请选择城市" @change="onChange" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const city = ref('shanghai')
+const options = [
+  { label: '北京', value: 'beijing' },
+  { label: '上海', value: 'shanghai' },
+  { label: '深圳', value: 'shenzhen' }
+]
+const onChange = (value) => console.log(value)
+</script>
+```
+
+> `options` 兼容纯值数组（如 `['北京', '上海']`），此时选中值即为该值本身。
+
+##### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| modelValue | string / number / boolean | '' | 当前选中值，支持 v-model |
+| options | array | [] | 选项列表：`{ label, value, disabled }` 或纯值 |
+| placeholder | string | 请选择 | 未选中时的占位文案 |
+| size | string | medium | 尺寸：small / medium / large |
+| disabled | boolean | false | 是否禁用 |
+| clearable | boolean | false | 是否可清空 |
+
+##### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:modelValue | 选中值变化（配合 v-model 使用） | (value) |
+| change | 选择某一项后触发 | (value) |
+| clear | 点击清空按钮时触发 | - |
+| visible-change | 浮层显隐变化 | (visible: boolean) |
+
+---
+
 ### Switch 开关
 
 表示两种相互对立的状态间的切换。
@@ -487,6 +553,7 @@ Tag 用于标记和分类；Badge 用于消息数量提示。
 | shape | string | circle | 形状：circle / square |
 | size | string | medium | 尺寸：small / medium / large |
 | icon | string | '' | 图标 |
+| colorful | boolean | false | 无图片时依据 alt 自动分配柔和主题色 |
 
 ##### Events
 
@@ -718,6 +785,190 @@ const active = ref('tab1')
 
 ---
 
+### Menu 菜单
+
+为页面提供导航的菜单列表。支持目录（子菜单）嵌套目录，层级不限制；提供「组装模式」（通过 XpSubMenu / XpMenuItem 组合）与「数据驱动模式」（传入 items 树自动生成）两种用法。
+
+#### 基础用法
+
+```vue
+<template>
+  <XpMenu v-model="active" @select="handleSelect">
+    <XpMenuItem index="dashboard">仪表盘</XpMenuItem>
+    <XpSubMenu index="system">
+      <template #title>系统管理</template>
+      <XpMenuItem index="system-users">用户管理</XpMenuItem>
+      <XpMenuItem index="system-settings" disabled>系统设置</XpMenuItem>
+    </XpSubMenu>
+  </XpMenu>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const active = ref('dashboard')
+
+const handleSelect = (index, item) => {
+  // index: 选中项完整 index；item: 数据驱动模式下对应的原始节点（组装模式为 null）
+}
+</script>
+```
+
+#### 多级嵌套（不限制层级）
+
+目录（XpSubMenu）内部可以继续放置目录，逐层展开：
+
+```vue
+<XpMenu v-model="active">
+  <XpSubMenu index="1">
+    <template #title>导航一</template>
+    <XpMenuItem index="1-1">选项一</XpMenuItem>
+    <XpSubMenu index="1-2">
+      <template #title>导航二（子目录）</template>
+      <XpSubMenu index="1-2-2">
+        <template #title>导航三（再嵌套）</template>
+        <XpMenuItem index="1-2-2-1">四级选项一</XpMenuItem>
+      </XpSubMenu>
+    </XpSubMenu>
+  </XpSubMenu>
+</XpMenu>
+```
+
+#### 数据驱动模式
+
+传入 `items` 树自动递归生成菜单，`children` 可无限嵌套。节点结构：
+`{ index, label, icon?, children?, disabled? }`，其中 `icon` 传内联 SVG 字符串（图标内部颜色使用 `currentColor` 便于跟随主题着色）。节点还可携带任意扩展字段（如 `path`），经 `select` 事件随原节点一并透出。深度嵌套时依赖插件全局注册（`app.use(XpUi)` 或逐一注册 XpSubMenu / XpMenuItem）。
+
+```vue
+<template>
+  <XpMenu :items="items" v-model="active" @select="handleSelect"></XpMenu>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const active = ref('system.system-users')
+
+const items = [
+  { index: 'dashboard', label: '仪表盘' },
+  {
+    index: 'system',
+    label: '系统管理',
+    children: [
+      { index: 'system-users', label: '用户管理' },
+      {
+        index: 'system-log',
+        label: '日志记录',
+        children: [
+          { index: 'system-log-login', label: '登录日志' },
+          { index: 'system-log-operation', label: '操作日志' }
+        ]
+      }
+    ]
+  }
+]
+</script>
+```
+
+> 激活项使用叶子节点的「完整 index」：数据驱动模式下 = 各级 `index` 以 `.` 拼接（如 `system.system-log.system-log-login`）；组装模式下直接使用各组件上声明的 `index`。
+
+#### 手风琴 & 多展开
+
+`uniqueOpen`（默认 `true`）开启手风琴：同一分支下仅保留一个展开的目录，其余自动收起；设为 `false` 可同时展开多个。
+
+#### 分组标题
+
+使用 `XpMenuGroup` 为相邻菜单添加分组说明（仅组装模式）：
+
+```vue
+<XpMenu v-model="active">
+  <XpMenuGroup title="导航">
+    <XpMenuItem index="home">首页</XpMenuItem>
+    <XpMenuItem index="news">消息</XpMenuItem>
+  </XpMenuGroup>
+</XpMenu>
+```
+
+#### 横向 / 折叠
+
+- `mode="horizontal"`：横向排列，一级目录悬停下拉弹出面板；
+- `collapse`（仅 vertical 生效）：折叠为仅图标模式，悬停一级目录在右侧弹出面板（面板内部仍支持无限嵌套）。折叠态下菜单宽度由外层容器控制（如 64px ~ 68px）。
+
+```vue
+<XpMenu mode="horizontal" :items="items" v-model="active"></XpMenu>
+<XpMenu :items="items" collapse v-model="active"></XpMenu>
+```
+
+#### 样式定制
+
+菜单使用 `--xp-menu-*` 系列 CSS 变量（默认对齐全局主题），可在使用处按需覆盖，例如深色侧边栏：
+
+```css
+.my-sidebar .xp-menu {
+  --xp-menu-text: rgba(226, 232, 255, 0.62);
+  --xp-menu-text-primary: rgba(236, 242, 255, 0.92);
+  --xp-menu-active: #fff;
+  --xp-menu-active-bg: rgba(64, 158, 255, 0.32);
+  --xp-menu-hover-bg: rgba(255, 255, 255, 0.04);
+  --xp-menu-panel-bg: #1c2333;
+  --xp-menu-disabled: rgba(226, 232, 255, 0.35);
+}
+```
+
+##### Menu Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| modelValue | string / number | '' | 当前激活项（叶子节点）的完整 index，支持 v-model |
+| mode | string | 'vertical' | 菜单方向：vertical / horizontal |
+| items | array | [] | 数据驱动模式的菜单树，children 可无限嵌套 |
+| collapse | boolean | false | 折叠为仅图标模式（仅 vertical 生效），悬停弹出面板 |
+| uniqueOpen | boolean | true | 手风琴模式，同一分支下仅展开一个目录 |
+| disabled | boolean | false | 是否禁用整个菜单 |
+
+##### Menu Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:modelValue | 选择菜单项时触发 | index |
+| select | 选择菜单项时触发 | (index, item)：item 为数据驱动模式下选中的原始节点，组装模式为 null |
+| open | 展开子菜单时触发 | index |
+| close | 收起子菜单时触发 | index |
+
+##### SubMenu Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| index | string / number | - | 必填，完整路径 index |
+| label | string | '' | 数据驱动模式下的标题文案 |
+| icon | string | '' | 数据驱动模式下的内联 SVG 图标 |
+| items | array | [] | 数据驱动模式下子级菜单树 |
+| disabled | boolean | false | 是否禁用 |
+
+> 标题内容也支持 `#title` 插槽，插槽优先级高于 label / icon。
+
+##### MenuItem Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| index | string / number | - | 必填，叶子节点完整 index |
+| disabled | boolean | false | 是否禁用 |
+| item | object | null | 数据驱动模式下对应的原始节点（随 select 事件透传） |
+
+##### MenuGroup Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | string | '' | 分组标题 |
+
+##### Slots
+
+| 插槽名 | 说明 |
+|--------|------|
+| default（Menu） | 组装模式：组合 XpSubMenu / XpMenuItem / XpMenuGroup |
+| default（SubMenu） | 子级菜单内容 |
+| title（SubMenu） | 子菜单标题内容 |
+
+---
+
 ### Dialog 对话框
 
 在保留当前页面状态的情况下，告知用户并承载相关操作。
@@ -847,6 +1098,194 @@ const handleCancel = () => { visible.value = false }
 
 ---
 
+### Pagination 分页
+
+分页条组件，展示数据总数与页码序列（首尾 + 当前页前后 2 页，跳跃处用省略号）。`total` 为 0 时不渲染。通过 `v-model:page` 双向绑定当前页，翻页成功后触发 `change` 事件；传入 `pageSizes` 会额外渲染每页条数选择器，配合 `v-model:page-size` 使用。
+
+#### 基础用法
+
+```vue
+<template>
+  <XpPagination v-model:page="page" :total="128" :page-size="10" @change="fetchPage" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const page = ref(1)
+const fetchPage = (n) => {
+  // 依据新页码 page 向后端拉取数据
+  console.log('当前页', n)
+}
+</script>
+```
+
+#### 每页条数选择
+
+```vue
+<template>
+  <XpPagination
+    v-model:page="page"
+    v-model:page-size="pageSize"
+    :total="186"
+    :page-sizes="[10, 20, 50]"
+    @change="fetchPage"
+    @size-change="fetchPage"
+  />
+</template>
+```
+
+##### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| total | number | 0 | 数据总条数（为 0 时不渲染分页条） |
+| page | number | 1 | 当前页码，从 1 开始，支持 v-model:page |
+| pageSize | number | 10 | 每页条数，支持 v-model:page-size |
+| pageSizes | array | [] | 可选的每页条数列表；为空时不渲染条数选择器 |
+
+##### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:page | 页码变化（配合 v-model:page 使用） | (page: number) |
+| update:pageSize | 每页条数变化（配合 v-model:page-size 使用） | (pageSize: number) |
+| change | 翻页成功 | (page: number) |
+| size-change | 每页条数变化 | (pageSize: number) |
+
+---
+
+### Table 表格
+
+列式定义表格：`XpTable` 负责整体渲染（含加载遮罩、空状态），通过子组件 `XpTableColumn` 声明列。支持字段自动渲染、自定义单元格/表头、排序、多选、斑马纹与边框、固定列，适用于各数据列表页面。
+
+#### 基础用法
+
+```vue
+<template>
+  <XpTable :data="list" row-key="id">
+    <XpTableColumn prop="name" label="姓名" />
+    <XpTableColumn prop="email" label="邮箱" />
+    <XpTableColumn prop="active" label="状态" width="100">
+      <template #default="{ row }">
+        <XpTag size="small" :type="row.active ? 'success' : 'info'">
+          {{ row.active ? '启用' : '禁用' }}
+        </XpTag>
+      </template>
+    </XpTableColumn>
+  </XpTable>
+</template>
+```
+
+##### XpTable Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | array | [] | 表格数据源 |
+| loading | boolean | false | 加载中状态，为真时显示加载遮罩 |
+| emptyTitle | string | 暂无数据 | 空状态标题 |
+| emptyHint | string | '' | 空状态提示文案 |
+| rowKey | string | id | 行唯一标识字段名，用于 :key 与多选标识；行数据缺失该字段时回退到行索引（多选/排序建议显式配置） |
+| stripe | boolean | false | 斑马纹：奇偶行交替背景色 |
+| border | boolean | false | 边框模式：单元格带纵向边框并整体加外框 |
+
+##### XpTableColumn Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| prop | string | '' | 对应数据行字段名，自动渲染 `row[prop]`；配合 formatter / #default 插槽时可不传 |
+| label | string | '' | 表头文案 |
+| type | string | default | 列类型：default 普通列 / selection 多选列 |
+| width | number / string | '' | 列宽（number 为 px）；**固定列必须显式指定** |
+| minWidth | number / string | '' | 最小列宽 |
+| align | string | left | 对齐方式：left / center / right |
+| sortable | boolean / string | false | 是否可排序：true 内置升/降序；'custom' 仅触发 sort-change 由外部处理 |
+| fixed | string | '' | 固定列位置：'left' / 'right'，需配合 width 使用 |
+| formatter | function | - | 单元格格式化：`(row, column, cellValue, index) => string` |
+| className | string | '' | 自定义列 class，同时作用于表头与单元格（如配合媒体查询隐藏整列） |
+
+##### XpTable Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| sort-change | 排序状态变化 | `{ column, prop, order }`，order 为 ascending / descending / null |
+| selection-change | 勾选集合变化 | `(rows: array)` 当前选中的行 |
+| select | 单个行勾选状态变化 | `(row, selected)` |
+| row-click | 点击行 | `(row, index)` |
+
+##### XpTable 实例方法
+
+| 方法名 | 说明 |
+|--------|------|
+| clearSelection | 清空所有勾选 |
+| toggleRowSelection(row, selected?) | 切换指定行勾选状态；selected 缺省时反转当前状态 |
+
+##### XpTable Slots
+
+| 插槽名 | 说明 |
+|--------|------|
+| default | 放置若干 `XpTableColumn`（列定义） |
+| empty | 自定义空状态内容（默认渲染 XpEmpty，由 emptyTitle / emptyHint 控制文案） |
+
+##### XpTableColumn Slots
+
+| 插槽名 | 说明 |
+|--------|------|
+| default | 自定义单元格内容，作用域暴露 `{ row, index }` |
+| header | 自定义表头内容，作用域暴露 `{ column }` |
+
+#### 排序
+
+```vue
+<XpTable :data="list" row-key="id" @sort-change="({ prop, order }) => onSort(prop, order)">
+  <XpTableColumn prop="name" label="姓名" sortable width="130" />
+</XpTable>
+```
+
+`sortable` 为 true 时表格内置升/降序（重复点击在升序 → 降序 → 复原间切换）；为 `'custom'` 时不排序，仅触发 `sort-change`，由外部维护排序后的数据。
+
+#### 多选
+
+```vue
+<template>
+  <XpTable ref="tableRef" :data="list" row-key="id" @selection-change="onSelectionChange">
+    <XpTableColumn type="selection" width="48" />
+    <XpTableColumn prop="name" label="姓名" />
+  </XpTable>
+</template>
+
+<script setup>
+const tableRef = ref(null)
+
+const onSelectionChange = (rows) => {
+  console.log(rows) // 选中的行数组
+}
+
+const clearAll = () => tableRef.value.clearSelection()
+</script>
+```
+
+多选通过与 `row-key` 对应的字段标识行，请确保数据包含该字段。
+
+#### 固定列
+
+```vue
+<XpTable :data="list" row-key="id">
+  <XpTableColumn type="selection" fixed="left" width="48" />
+  <XpTableColumn prop="name" label="姓名" fixed="left" width="110" />
+  <XpTableColumn prop="email" label="邮箱" />
+  <XpTableColumn label="操作" fixed="right" width="140">
+    <template #default="{ row }">
+      <XpButton size="small" type="primary" @click="onEdit(row)">编辑</XpButton>
+    </template>
+  </XpTableColumn>
+</XpTable>
+```
+
+`fixed="left"` / `fixed="right"` 将列冻结在容器两侧，表体可左右横向滚动（移动端同样生效）。固定列需显式传 `width`。
+
+---
+
 ### FileIcon 文件图标
 
 按文件类型展示对应的矢量图标，内置文件夹与常见文件类型，适用于文件管理器等场景。