@robot-admin/naive-ui-components 0.17.3 → 0.17.5

package/dist/verification.d.ts

@@ -77,19 +77,19 @@ declare const __VLS_export: vue.DefineComponent<CaptchaProps, {
   show: () => void;
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {} & {
   change: (valid: boolean) => any;
-  reset: () => any;
   success: (data: CaptchaSuccessPayload) => any;
+  reset: () => any;
+  "load-error": (error: unknown) => any;
   fail: (error: string) => any;
   "verify-error": (error: unknown) => any;
-  "load-error": (error: unknown) => any;
   "visible-change": (visible: boolean) => any;
 }, string, vue.PublicProps, Readonly<CaptchaProps> & Readonly<{
   onChange?: ((valid: boolean) => any) | undefined;
-  onReset?: (() => any) | undefined;
   onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
+  onReset?: (() => any) | undefined;
+  "onLoad-error"?: ((error: unknown) => any) | undefined;
   onFail?: ((error: string) => any) | undefined;
   "onVerify-error"?: ((error: unknown) => any) | undefined;
-  "onLoad-error"?: ((error: unknown) => any) | undefined;
   "onVisible-change"?: ((visible: boolean) => any) | undefined;
 }>, {
   disabled: boolean;

package/docs/guides/usage.en.md

@@ -403,12 +403,26 @@ function preview() {
 
 `setValues(values, shouldValidate = false)` delegates to the mounted form instance, or updates the bound model before mounting. `getValues()` returns a copy. `reset()` restores the current clean snapshot; `markAsClean()` updates that baseline. Supply a complete nested object when setting it, or call the instance's `setFieldValue('profile.email', value)` for one path.
 
+`useCForm().validate()` rejects before `formRef` is bound or after unmount. `submit()` returns `false` in that state. Draft `setValues()`, `getValues()`, and `reset()` remain available before mounting.
+
 Vue unwraps state exposed through a component template ref: scripts read `formRef.value?.isSubmitting`, `formRef.value?.isDirty`, and `formRef.value?.formModel` without a second `.value`. The helper's own `model`, `formRef`, and `bindings` remain Vue refs.
 
 Default, inline, and grid layouts are synchronous. Card, tabs, steps, dynamic, and custom layouts load on demand. Before an asynchronous layout mounts, `submit()` returns `false` and `validate()` rejects rather than accepting fields that have not rendered. Once ready, tab and step layouts mount fields across their panels, so full submission also validates unvisited panels. Async option requests are isolated per field; late responses from superseded requests cannot replace newer options.
 
+For `C_Tree`, read `tree.value?.selectedKeys`, `expandedKeys`, and `checkedKeys` directly as arrays with `ref<TreeExpose>()`. Prefer `v-model:*` for controlled state. The standalone `useTreeOperations()` composable retains internal refs.
+
+### Table editing validation
+
+`required` and `editProps.rules` share the same extraction and native validation semantics in modal, row, and cell editing. Use Naive `FormItemRule` entries such as `{ type: 'email', message: 'Invalid email' }`. Number and switch editors infer their basic type unless explicitly specified. Prefer Promise-based async rules; `asyncValidator` callbacks are supported too. Warning-level rules do not block saves.
+
+Selection, expansion, index, and action columns are automatically excluded from generated form fields. Read-only business columns remain excluded. Numeric field keys are converted to form field strings. Existing configuration and compatibility entries remain supported.
+
+Read `TimeExpose.startTime/endTime/singleTime` directly as numbers or null, and `MenuExpose.menuRef` directly as the native menu instance or null. Vue unwraps these top-level exposed refs.
+
 ### Table pagination, selection, and export
 
+`TableProps<Row>` includes `config`, `crud`, `remote`, and `virtualScrollX`; columns and data may be omitted when supplied by CRUD. Legacy edit, expansion, and selection prop types remain as compatibility declarations; component features belong in `config`.
+
 Use `config.pagination` for new pages. For remote tables, bind the `useTableQuery().bindings` shown above so pagination, totals, loading, and requests have one owner. The compatibility `:pagination="..."` prop delegates pagination to Naive UI. Explicitly passing that prop, including `false`, takes precedence over `config.pagination`; the component does not render a second pager. With native remote pagination, also pass `remote` and manage requests and native update events yourself.
 
 Local data is filtered and sorted before pagination. Remote mode displays the server's page without slicing it again. `crossPageSelection: true` retains selected row objects from visited remote pages; `selectAll()` only adds the currently loaded page and cannot represent unseen server records. Use `getSelectedRows()` or the row objects from `@selection-change` for batch work. Server-wide operations need an explicit query or a server-side task supplied by the application.
@@ -443,6 +457,8 @@ Dynamic add/copy operations must generate keys consistent with the table. Prefer
 
 ### Connect search to a remote table
 
+Select fields use the existing `list` and `attrs` entries. Set `attrs: { multiple: true }` with an array model for multiple selection. Option values support strings, numbers, and booleans; `false`, `0`, and empty values remain distinct. Search callbacks receive original business values without internal encoding. Standard `TableInstance<Row>` selection methods follow the active selection mode; nested `crossPageSelection.selectedCount` remains a ref and needs `.value`.
+
 Use `C_FormSearch` with `v-model`; legacy `formParams` remains supported. Put requests in `config.onSearch` and use `@search` for notification. Sending requests from both paths executes both application handlers. The following example gives a single table controller ownership of requests, pagination, and loading:
 
 ```vue

package/docs/guides/usage.md

@@ -464,16 +464,32 @@ function preview() {
 
 `setValues(values, shouldValidate = false)` 在挂载后直接调用表单实例，挂载前更新绑定模型；`getValues()` 返回副本。`reset()` 恢复当前干净快照，`markAsClean()` 可更新该基线。设置嵌套对象时传完整对象，或使用实例的 `setFieldValue('profile.email', value)` 修改单个路径。
 
+`useCForm().validate()` 必须在 `formRef` 绑定后调用；挂载前或卸载后会拒绝执行，不能将未校验视为通过。`submit()` 此时返回 `false`，挂载前仍可用 `setValues()`、`getValues()` 和 `reset()` 管理草稿。
+
 组件模板 ref 的公开状态已由 Vue 解包：脚本中读取 `formRef.value?.isSubmitting`、`formRef.value?.isDirty` 和 `formRef.value?.formModel`，无需再取一层 `.value`。助手返回的 `model`、`formRef`、`bindings` 本身仍是 Vue ref。
 
 普通、行内、网格布局同步提供；卡片、标签、步骤、动态和自定义布局按需加载。异步布局尚未挂载时，`submit()` 返回 `false`，`validate()` 拒绝执行，避免把未呈现的字段当成通过校验。标签和步骤布局就绪后会挂载各面板字段，整表提交也校验未访问的面板；异步选项请求按字段隔离，更新请求后晚到的旧结果不会覆盖新选项。
 
+`C_Tree` 的公开实例遵循同一规则：`ref<TreeExpose>()` 后直接读取 `tree.value?.selectedKeys`、`expandedKeys` 和 `checkedKeys` 数组，受控状态仍推荐通过 `v-model:*` 管理。独立 `useTreeOperations()` 返回的内部状态保持 Ref。
+
+### 表格编辑校验
+
+`required` 和 `editProps.rules` 在弹窗、行编辑、单元格编辑中使用同一口径。类型规则沿用 Naive 的 `FormItemRule`，例如 `{ type: 'email', message: '请输入正确邮箱' }`；数字与开关编辑器可推断基础类型，也可显式指定 `type`。异步规则推荐返回 Promise，`asyncValidator` 也支持 callback。警告级规则不阻止保存。
+
+选择、展开、序号和操作列自动排除于编辑字段，业务侧无需为它们额外声明 `editable: false`。`editable: false` 的业务列仍只读；字段键为数字时转换成表单字段字符串。校验规则属于 `rules`，编辑控件属性属于 `attrs`，组件内部统一完成转换。旧兼容入口按弃用说明继续保留。
+
+`C_Time` 的 `TimeExpose.startTime/endTime/singleTime` 直接读取数值或 null；`C_Menu` 的 `MenuExpose.menuRef` 直接读取原生菜单实例或 null，均无需第二层 `.value`。
+
 ### 表格分页、选择与导出
 
+`TableProps<Row>` 支持 `config`、`crud`、`remote` 与 `virtualScrollX`；CRUD 绑定已提供列和数据时不必重复传入。旧编辑、展开和选择属性类型仅保留兼容声明，组件功能统一放在 `config` 中。
+
 新页面统一通过 `config.pagination` 配置分页；远程表格直接使用上例 `useTableQuery().bindings`，分页、总数、loading 与请求只维护一份状态。兼容路径 `:pagination="..."` 由 Naive 原生分页负责；只要显式传入该 prop（包括 `false`），它就优先于 `config.pagination`，组件不会再显示第二个分页器。原生远程模式同时传 `remote` 并自行管理请求及原生更新事件。
 
 本地数据先筛选、排序，再分页；远程模式显示服务器返回的这一页，不再次切片。`crossPageSelection: true` 保留已访问远程页中选中的行对象；`selectAll()` 只追加当前加载页，不能代表选中尚未获取的全部服务器记录。批量操作用 `getSelectedRows()`／`@selection-change` 的行对象；需要服务器“全部命中”操作时由业务提供查询条件或服务端任务。
 
+`TableInstance<Row>` 的 `selectRow()`、`getSelectedRows()` 和 `clearSelection()` 会自动使用当前选择模式。需要响应式数量时读取 `table.value?.crossPageSelection.selectedCount.value`；嵌套对象的 Ref 不会被 Vue 顶层解包。`getManager()` 保留为高级兼容入口，常用操作不必依赖内部管理器。
+
 导出范围应显式选择：
 
 | `config.export` 配置      | 数据来源                                                   |
@@ -504,6 +520,28 @@ const fullExport = defineTableConfig({
 
 ### 搜索与远程表格连接
 
+选择字段沿用 `list` 和 `attrs`：多选只需 `attrs: { multiple: true }`，模型使用数组。`list.value` 支持字符串、数字和布尔值，展示适配由组件完成，`false`、`0` 和空值保持区分，搜索回调不会收到内部编码值。
+
+```ts
+const filters: SearchFormItem[] = [
+  {
+    type: 'select',
+    prop: 'roles',
+    attrs: { multiple: true },
+    list: [{ label: '管理员', value: 'admin' }],
+  },
+  {
+    type: 'select',
+    prop: 'enabled',
+    list: [
+      { label: '停用', value: false },
+      { label: '启用', value: true },
+    ],
+  },
+]
+// 对应模型：{ roles: ['admin'], enabled: false }
+```
+
 搜索表单使用 `C_FormSearch`，推荐 `v-model`；旧 `formParams` 继续兼容。业务请求放在 `config.onSearch`，`@search` 用于通知；两处同时发请求会由业务执行两次。下面将请求、分页和 loading 交给一份表格控制器：
 
 ```vue

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "基于 Naive UI 的 Vue 3 组件库",
   "packageManager": "bun@1.3.14",
   "engines": {
@@ -132,6 +132,7 @@
     }
   },
   "dependencies": {
+    "async-validator": "4.2.5",
     "@antv/x6": "^2.19.2",
     "@chenfengyuan/vue-barcode": "^2.0.2",
     "@fullcalendar/core": "^6.1.21",