auto-vue-manual 0.3.13 → 0.3.16

package/README.md

@@ -46,6 +46,27 @@ app.mount('#app');
 [UploadImage](#uploadimage)  
 [UploadImages](#uploadimages)
 
+## Storybook
+
+```bash
+npm run storybook         # 本地起 Storybook（http://localhost:6006）
+npm run build-storybook   # 产出静态站点到 storybook-static/
+```
+
+- **stories**：`package/**/*.stories.@(js|jsx|mjs|ts|tsx)`（如 `package/components/table/table.stories.tsx`，`title: 'Base/Table'`）
+- **配置**：`.storybook/main.ts` / `.storybook/preview.ts`
+
+### 接口全部走本地 mock（离线可用）
+
+stories 不依赖任何外部域名，数据由 `.storybook/mocks/*.json` 提供（`requestBaseUrl` 设为 `/api`）。
+
+- `.storybook/mock-api.ts` —— `createMockAdapter()` 查表返回 `{ code: 200, data, message: 'ok', status: 'success' }`；未登记的路径 `console.warn` 并返回 `data: null`。
+- 现有 fixture：`/api/menu/search`（分页，`{ list, total }`）、`/api/menu/list`（非分页，直接数组）、`/api/menu/summaries`（`SumResult[]`）、`/api/menu/change_status`。
+- **新增 fixture**：放 `.storybook/mocks/xxx.json` → 在 `MOCK_FIXTURES` 登记 `'/api/xxx'` → story 里写 `url: '/xxx'`。
+- 个别 story 想临时关掉 mock：在请求 config 里显式传 `adapter`（`mergeConfig` 会优先取请求侧）。
+
+> ⚠️ **必须在 axios 实例上装 adapter，不能只改 `axios.defaults`**：`axios.create()` 会把创建那一刻的 `axios.defaults.adapter`（默认 `['xhr','http','fetch']` 数组）快照进实例自己的 defaults；且实例是 `bind(Axios.prototype.request, context)` 出来的绑定副本，事后改原型也拦不住。而 `package/utils/request.ts` 的实例是**模块顶层**创建的，静态构建时还会更早求值 —— 所以 `request.ts` 导出该实例（`export { api }`），`preview.ts` 在模块体里 `installMockAdapter(api)`。机制细节与踩坑记录见 `workbench/docs/manual/components/ProTableList.md` 的「Storybook」一节。
+
 ## Button
 
 ### 组件列表
@@ -128,7 +149,7 @@ app.mount('#app');
 
 | 属性名           | 类型                                                                          | 说明                                                                | 默认值 |
 | ---------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------ |
-| **type**         | `string`                                                                      | 列类型, index / selection/ radio/ expand/ sort/ icon/ tag/ copy     | -      |
+| **type**         | `string`                                                                      | 列类型, index / selection / radio / expand / switch / status / tooltip / icon / tag / copy | -      |
 | **prop**         | `string`                                                                      | 列数据字段名                                                        | -      |
 | **label**        | `string`                                                                      | 列标题                                                              | -      |
 | **width**        | `number`                                                                      | 列宽                                                                | -      |
@@ -158,9 +179,22 @@ app.mount('#app');
 | **page-size**       | `number`                        | 列表页大小                                                            | 0      |
 | **row-h**           | `number`                        | 列表行高                                                              | 0      |
 | **ext-h**           | `number`                        | 列表额外高度                                                          | 0      |
-| **sum-url**         | `string`                        | 汇总接口url，仅 ProTableSummary 有效                                  |        |
-| **sum-text**        | `string`                        | 汇总文本，仅 ProTableSummary 有效                                     | Total  |
-| **sum-text-format** | `string`                        | 汇总文本格式，仅 ProTableSummary 有效                                 | \*     |
+| **sum-url**         | `string`                        | 汇总接口 url，仅 `ProTableSummary` 有效                               |        |
+
+> **`sumUrl` 的响应结构（`SumResult[]`）**
+>
+> 汇总接口的响应体固定为 `{ data: SumResult[] }`，元素结构为 `{ index: number; text: string }`：
+>
+> - `index` —— 该汇总值落在**第几列**（对应 `columns` 扁平化后的下标，与 `el-table` 的 `summary-method` 对齐）；
+> - `text` —— 该单元格显示的文本。
+>
+> ```json
+> { "data": [{ "index": 0, "text": "合计" }, { "index": 3, "text": "128,900" }] }
+> ```
+>
+> 请求参数为 `{ ...initParam, ...totalParam, page: 1, size: 1 }` —— 即当前查询条件，**不随分页变化**（汇总始终是全量口径）。
+>
+> **刷新时机**：随 `getTableList()` 一起刷新，因此首次加载、`search()`、`reset()`、翻页、改每页条数都会重取；请求失败会走 `requestError` 回调，并**保留上一次的汇总值**（不会闪成空白）。宿主也可通过 ref 主动调用 `getSummaries()` 读取当前汇总结果。
 
 #### Event 事件说明
 
@@ -177,6 +211,7 @@ app.mount('#app');
 | **@search**       | 搜索事件                               | `(searchParam?: Record<string, any>) => void` |
 | **@reset**        | 重置事件                               | `() => void`                                  |
 | **@getTableList** | 获取表格数据，不更新搜索参数及分页参数 | `() => void`                                  |
+| **@getSummaries** | 读取当前汇总结果（仅 `ProTableSummary`，返回按列 index 索引的文本数组） | `() => string[]` |
 
 #### 示例代码
 
@@ -222,7 +257,6 @@ app.mount('#app');
       label: '名称',
       width: 0,
       align: 'right',
-      search: { defaultValue: 'League' },
       headerRender: ({ column }: HeaderRenderScope<any>) => {
         return <span>headerRender: {column.label}</span>
       },
@@ -260,18 +294,22 @@ app.mount('#app');
 | ----------- | -------- | --------------------------------------------------------------------- | ------ |
 | **row-key** | `string` | 行数据的 Key，用来优化 Table 的渲染，当表格数据多选时，所指定的 id ） | id     |
 
-其余同 [ProTable](#protable--protablesummary)
+其余同 [ProTable](#protable--protablesummary)，但 **`hasPagination` 不在 `ProTableList` 的契约内**（`ProTableListProps extends Omit<BaseTableProps, 'hasPagination'>`）。
+
+> ⚠️ **Breaking change**：`ProTableList` 基于 `el-table-v2` 虚拟滚动，模板中不渲染分页器，取数固定为「一次拉全量」（`useTable` 以非分页模式调用，请求不带 `page` / `size`，响应直接读整个 `data` 而非 `data.list`）。历史上 `hasPagination` 会切换请求形态却画不出分页器，还会白扣 44px 高度，故已从契约中移除 —— 传入该 prop 不再生效（且会作为普通 attribute 透传到根元素）。需要分页请改用 `ProTable` / `ProTableSummary`。
 
 #### Event 事件说明
 
-| 事件名            | 说明                                                                              | 参数                                  |
-| ----------------- | --------------------------------------------------------------------------------- | ------------------------------------- |
-| **@row-click**    | 行点击事件，未排除 status / operation 列，需添加 e.stopPropagation() 阻止事件冒泡 | `({ row: any, column: any }) => void` |
-| **@row-dblclick** | 行双击事件，未排除 status / operation 列，需添加 e.stopPropagation() 阻止事件冒泡 | `({ row: any, column: any }) => void` |
+| 事件名            | 说明                                                          | 参数                                                     |
+| ----------------- | ------------------------------------------------------------- | -------------------------------------------------------- |
+| **@row-click**    | 行点击事件，已排除 status / operation 列（与 `ProTable` 一致） | `({ rowKey, rowData, rowIndex, event }: RowEventHandlerParams) => void` |
+| **@row-dblclick** | 行双击事件，已排除 status / operation 列（与 `ProTable` 一致） | `({ rowKey, rowData, rowIndex, event }: RowEventHandlerParams) => void` |
+
+> 与 `ProTable` 的 `(row, column, event)` 不同：`el-table-v2` 的行事件包装器只回传 `{ event, rowData, rowIndex, rowKey }`，**没有 `column`**。因此列过滤由组件内部完成 —— 用 `:cell-props` 给每个单元格打上 `data-column-key`，事件里从 `event.target.closest('[role="cell"]')` 反查（取的是列的 `key`，即 `item.key || item.prop`）。**载荷形状不受影响，宿主代码无需改动。**
 
 #### Expose 暴露方法说明
 
-与 ProTable 相同。
+与 ProTable 相同（含 `radio` —— `type: 'radio'` 单选列的选中值，与 v1 一样**不 emit**，经 `tableRef.value.radio` 读取）。
 
 #### 示例代码
 
@@ -290,7 +328,7 @@ app.mount('#app');
   import { ref, reactive } from 'vue'
 
   import { Plus } from '@element-plus/icons-vue'
-  import ProTableList from 'auto-vue-manual'
+  import { ProTableList } from 'auto-vue-manual'
 
   const proTableRef = ref<InstanceType<typeof ProTableList>>()
   const columns: ColumnProps[] = [
@@ -371,45 +409,59 @@ app.mount('#app');
 
 ### 通用 Props
 
-| 属性名            | 类型    | 说明                    | 默认值 |
-| ----------------- | ------- | ----------------------- | ------ |
-| visible           | boolean | 是否显示                | false  |
-| showClose         | boolean | 是否显示关闭按钮        | true   |
-| title             | string  | 标题                    | Title  |
-| width             | string  | 宽度                    | 520px  |
-| top               | string  | 顶部距离                | 15vh   |
-| dialogProps       | object  | 透传 Dialog/Drawer 属性 | {}     |
-| appendToBody      | boolean | 是否插入 body           | true   |
-| lockScroll        | boolean | 是否锁定滚动            | true   |
-| closeOnClickModal | boolean | 点击遮罩关闭            | false  |
+| 属性名            | 类型    | 说明                                          | 默认值                 |
+| ----------------- | ------- | --------------------------------------------- | ---------------------- |
+| modelValue        | boolean | 是否显示（配合 `v-model`）                    | false                  |
+| showClose         | boolean | 是否显示关闭按钮                              | true                   |
+| title             | string  | 标题（i18n key，经 `Translate()` 翻译）       | ''                     |
+| width             | string  | Dialog 宽度；Drawer 映射到 `el-drawer` 的 size | 520px                  |
+| top               | string  | 顶部距离（**仅 Dialog**）                     | 15vh                   |
+| center            | boolean | 头部/底部居中（**仅 Dialog**）                | true                   |
+| divider           | boolean | 正文顶部是否渲染 `el-divider`                 | Dialog `true` / Drawer `false` |
+| appendToBody      | boolean | 是否插入 body                                 | true                   |
+| lockScroll        | boolean | 是否锁定滚动                                  | true                   |
+| closeOnClickModal | boolean | 点击遮罩关闭                                  | false                  |
+
+> 除上表外的 Element Plus Dialog / Drawer 原生属性（`fullscreen`、`draggable`、`headerClass`、`beforeClose` 等）均通过 `v-bind` 直接透传。
+
+### 通用事件
+
+| 事件名            | 说明                                                     |
+| ----------------- | -------------------------------------------------------- |
+| update:modelValue | `v-model` 回写                                            |
+| close             | 关闭动画**开始**时触发（对应 Element Plus 的 `close`）    |
+| closed            | 关闭动画**结束**时触发（对应 Element Plus 的 `closed`）   |
 
 ### BasicDialog
 
 - 通用弹窗基类，支持所有通用 props 和事件。
-- 事件：`@update:visible`、`@closed`、`@submit`
+- 事件：`update:modelValue`、`close`、`closed`
+- 暴露（`defineExpose`）：`close()`、`dialogRef`（内部 `el-dialog` 实例）
 
 ### BasicDrawer
 
-- 通用抽屉基类，支持所有通用 props 和事件。
-- 事件：`@update:visible`、`@closed`
+- 通用抽屉基类，支持所有通用 props 和事件（无 `top` / `center`）。
+- 事件：`update:modelValue`、`close`、`closed`
+- 暴露（`defineExpose`）：`close()`、`drawerRef`（内部 `el-drawer` 实例）
 
 ### FormDialog
 
 - 基于 BasicDialog 扩展，内置底部按钮，适合表单场景。
-- 额外 props：`executing`（是否执行中）、`footer`（是否显示底部）、`btnSize`、`okText`、`cancelText`
-- 事件：`@submit`、`@closed`、`@before-close`
+- 额外 props：`executing`（是否执行中）、`btnSize`、`okText`、`okType`、`cancelText`、`cancelType`
+- 事件：`update:modelValue`、`close`、`closed`、`submit`
 
 ### TableDialog
 
 - 基于 BasicDialog 扩展，适合表格弹窗场景。
 - 额外 props：`requesting`（是否请求中）
+- 事件：`update:modelValue`、`close`、`closed`
 
 ### 示例代码
 
 ```vue
 <template>
   <OpenButton @open="visible = true" />
-  <BasicDialog :visible="visible" title="标题" width="520px" @update:visible="visible = $event" @closed="onClosed">
+  <BasicDialog v-model="visible" title="base.confirm" width="520px" @closed="onClosed">
     <template #default>内容区域</template>
   </BasicDialog>
 </template>
@@ -418,7 +470,7 @@ app.mount('#app');
   import { BasicDialog, OpenButton } from 'auto-vue-manual'
   const visible = ref(false)
   const onClosed = () => {
-    visible.value = false
+    /* 关闭动画结束后 */
   }
 </script>
 ```
@@ -428,7 +480,7 @@ app.mount('#app');
 ```vue
 <template>
   <OpenButton @open="visible = true" />
-  <FormDialog :visible="visible" title="表单弹窗" @update:visible="visible = $event" @submit="onSubmit">
+  <FormDialog v-model="visible" title="base.confirm" @submit="onSubmit">
     <template #default>
       <el-input v-model="form.name" placeholder="请输入名称" />
     </template>
@@ -457,7 +509,7 @@ app.mount('#app');
 | **avatar**   | `string`  | 头像地址     | -      |
 | **text**     | `string`  | 上传提示     | -      |
 | **path**     | `string`  | 保存路径     | -      |
-| **preview**  | `boolean` | 是否显示预览 | false  |
+| **preview**  | `boolean` | 是否显示预览 | true   |
 | **disabled** | `boolean` | 是否禁用     | false  |
 | **size**     | `number`  | 大小（KB）   | 5120   |