@a2simcode/ui 0.0.55 → 0.0.56

package/docs/components/input-rows.md

@@ -1,370 +1,370 @@
-# InputRows 行输入
-
-`j-input-rows` 用于维护“多行对象数组”类型的数据：每一行通过 `columns` 渲染若干输入控件，支持新增行、删除行，以及（可选）拖拽排序。
-
-## 基础用法
-
-通过 `columns` 属性定义列配置，`v-model` 绑定数据。
-
-<Demo :source-code="basicCode">
-  <template #source>
-    <basic />
-  </template>
-  <template #description>
-    使用 `j-input-rows` 创建一个可编辑的数据表格。每行包含多个字段，支持添加、删除行操作。
-  </template>
-</Demo>
-
-## 拖拽排序
-
-通过 `editConfig.drag` 属性启用拖拽排序功能。
-
-<Demo :source-code="dragCode">
-  <template #source>
-    <drag />
-  </template>
-  <template #description>
-    设置 `editConfig.drag` 为 `true` 启用拖拽排序功能，可以通过拖拽图标调整行的顺序。
-  </template>
-</Demo>
-
-## 嵌套表单
-
-支持在行内嵌套 `j-input-rows` 组件，实现多层级的数据录入。
-
-<Demo :source-code="nestedCode">
-  <template #source>
-    <nested />
-  </template>
-  <template #description>
-    示例展示在列配置中使用嵌套能力来录入多层级数据结构。
-  </template>
-</Demo>
-
-## API（表格）
-
-<ApiTable :data="inputRowsApi" componentName="input-rows" />
-
-## 1. 组件概述
-
-### 主要功能和用途
-
-- 行级数据维护：`modelValue` 为对象数组，每个对象代表一行。
-- 行内字段渲染：通过 `columns` 逐列渲染行内输入控件（内部使用 `j-comp` 动态渲染）。
-- 编辑能力：添加、删除、拖拽排序（由 `editConfig` 控制）。
-- 辅助展示：支持显示行序号（1,2,3...）或字母序号（A-Z 循环）。
-
-### 适用的业务场景和使用限制
-
-适用场景：
-
-- 表单里需要录入可变数量条目：如“联系人列表”“参数列表”“阈值配置”“规则列表”等。
-- 需要一个轻量的列表型编辑器，但又不想引入完整表格组件。
-
-限制/注意事项：
-
-- 组件会对数组进行就地修改（`push/splice`），并可能对每行对象补充唯一标识字段 `i`（UUID）。请避免把业务字段命名为 `i`。
-- 当 `modelValue` 为空数组时，组件会在初始化时触发一次 `update:modelValue([])`；后续新增/删除/排序主要依赖就地修改与 `change` 事件。
-- `change` 事件中的 `formData` 来自表单注入；不在 `j-form` 环境使用时，`formData` 可能为 `undefined`。
-
-## 2. 属性说明（Props）
-
-> 下文“类型/默认值”以组件源码为准。
-
-### 2.1 组件属性
-
-#### modelValue
-
-- 名称：`modelValue`
-- 类型：`Record<string, any>[]`
-- 默认值：`[]`
-- 是否必填：否（通常与 `v-model` 搭配）
-- 详细描述：行数据数组。每项是一个对象，字段写入到行对象上的 key 通常来自 `columns[*].id`，也可通过 `columns[*].config.valueRowKey` 指定。
-- 使用示例：
-
-```vue
-<template>
-  <j-input-rows v-model="rows" :columns="columns" />
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const rows = ref<Record<string, any>[]>([
-  { i: '1', name: '张三', age: 18 },
-  { i: '2', name: '李四', age: 20 },
-])
-</script>
-```
-
-#### columns
-
-- 名称：`columns`
-- 类型：`SchemaConfig[]`
-- 默认值：`[]`
-- 是否必填：是
-- 详细描述：列配置数组。每个列配置会被透传给 `j-comp` 渲染为具体输入控件。
-- 使用示例：
-
-```ts
-const columns = [
-  {
-    id: 'name',
-    type: 'j-input',
-    config: { label: '姓名', placeholder: '请输入姓名', defaultValue: '' },
-  },
-  {
-    id: 'age',
-    type: 'j-number',
-    config: { label: '年龄', placeholder: '请输入年龄', defaultValue: 0, min: 0, max: 150 },
-  },
-]
-```
-
-#### editConfig
-
-- 名称：`editConfig`
-- 类型：`EditConfigType`
-- 默认值：`{}`
-- 是否必填：否
-- 详细描述：编辑配置，控制添加/删除/只读/拖拽等行为。
-- 使用示例：
-
-```ts
-const editConfig = {
-  isAddBtn: true,
-  isRemoveBtn: true,
-  addBtnText: '添加一行',
-  buttonsAlign: 'left',
-  readonly: false,
-  drag: true,
-  isNullValue: true,
-}
-```
-
-#### isCompact
-
-- 名称：`isCompact`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否紧凑模式（行高与 padding 更小）。
-- 使用示例：`<j-input-rows v-model="rows" :columns="columns" is-compact />`
-
-#### showNum
-
-- 名称：`showNum`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否显示行序号（1,2,3...）。
-- 使用示例：`<j-input-rows v-model="rows" :columns="columns" show-num />`
-
-#### showChar
-
-- 名称：`showChar`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否显示字母序号（A-Z 循环）。
-- 使用示例：`<j-input-rows v-model="rows" :columns="columns" show-char />`
-
-#### isWrap
-
-- 名称：`isWrap`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否允许行内字段换行（`flex-wrap: wrap`）。
-- 使用示例：`<j-input-rows v-model="rows" :columns="columns" is-wrap />`
-
-#### id
-
-- 名称：`id`
-- 类型：`String`
-- 默认值：`''`
-- 是否必填：否
-- 详细描述：字段/组件 id。该值会原样透传到 `change` 事件的回调参数 `payload.id` 中，用于区分来源。
-- 使用示例：`<j-input-rows id="user-list" v-model="rows" :columns="columns" />`
-
-### 2.2 EditConfigType 说明
-
-#### isAddBtn
-
-- 名称：`isAddBtn`
-- 类型：`Boolean`
-- 默认值：`true`（逻辑为 `!== false` 即显示）
-- 是否必填：否
-- 详细描述：是否显示添加按钮。
-- 使用示例：`editConfig: { isAddBtn: false }`
-
-#### addBtnText
-
-- 名称：`addBtnText`
-- 类型：`String`
-- 默认值：`'添加'`
-- 是否必填：否
-- 详细描述：添加按钮文本。
-- 使用示例：`editConfig: { addBtnText: '新增条目' }`
-
-#### buttonsAlign
-
-- 名称：`buttonsAlign`
-- 类型：`'left' | 'center' | 'right'`
-- 默认值：`'left'`
-- 是否必填：否
-- 详细描述：底部操作区（添加按钮区域）对齐方式。
-- 使用示例：`editConfig: { buttonsAlign: 'right' }`
-
-#### isRemoveBtn
-
-- 名称：`isRemoveBtn`
-- 类型：`Boolean`
-- 默认值：`true`（逻辑为 `!== false` 即显示）
-- 是否必填：否
-- 详细描述：是否显示删除按钮。
-- 使用示例：`editConfig: { isRemoveBtn: false }`
-
-#### readonly
-
-- 名称：`readonly`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否只读。为 `true` 时隐藏添加/删除操作区；行内输入控件是否只读取决于列配置本身。
-- 使用示例：`editConfig: { readonly: true }`
-
-#### drag
-
-- 名称：`drag`
-- 类型：`Boolean`
-- 默认值：`false`
-- 是否必填：否
-- 详细描述：是否支持拖拽排序。开启后每行会显示拖拽手柄图标。
-- 使用示例：`editConfig: { drag: true }`
-
-#### isNullValue
-
-- 名称：`isNullValue`
-- 类型：`Boolean`
-- 默认值：`true`（逻辑为 `!== false` 即允许“可删到空”）
-- 是否必填：否
-- 详细描述：是否允许删除到空。当 `isNullValue === false` 时，仅当 `list.length > 1` 才显示删除按钮（禁止删除最后一行）。
-- 使用示例：`editConfig: { isNullValue: false }`
-
-## 3. 事件说明（Events）
-
-### update:modelValue
-
-- 事件名称：`update:modelValue`
-- 触发条件：初始化时 `modelValue` 为空数组会触发一次；其他场景通常依赖数组就地修改，不保证每次新增/删除/排序都触发该事件。
-- 回调参数：`value: Record<string, any>[]`
-
-### change
-
-- 事件名称：`change`
-- 触发条件：新增行、删除行、拖拽排序后触发。
-- 回调参数说明：
-
-```ts
-type InputRowsChangePayload = {
-  id: string
-  value: any
-  data: any
-  formData: Record<string, any> | undefined
-  tableData: Record<string, any>[]
-  type: 'add' | 'delete' | 'update' | 'sort'
-}
-```
-
-### rowChange
-
-- 事件名称：`rowChange`
-- 触发条件：行内字段变化时触发（由内部注入的 `rowChange` 回调触发）。
-- 回调参数说明：`data: Record<string, any>`（透传自内部 `j-comp` 的变更数据）
-
-## 4. 方法说明（Methods）
-
-- 当前版本未通过 `defineExpose` 暴露任何公共方法。
-
-## 5. 插槽说明（Slots）
-
-- 当前版本不支持插槽。
-
-## 6. 使用示例（进阶）
-
-### 6.1 新增行默认值（defaultValue）与字段落点（valueRowKey）
-
-```ts
-const columns = [
-  { id: 'name', type: 'j-input', config: { label: '名称', defaultValue: '未命名' } },
-  {
-    id: 'amount',
-    type: 'j-number',
-    config: { label: '金额', defaultValue: 0, valueRowKey: 'price' },
-  },
-]
-```
-
-点击“添加”后，新行会写入到行对象的 `price` 字段（而不是 `amount`），形如：`{ i: 'uuid', name: '未命名', price: 0 }`。
-
-### 6.2 不允许删到空（isNullValue: false）
-
-```vue
-<template>
-  <j-input-rows
-    v-model="rows"
-    :columns="columns"
-    :edit-config="{ isNullValue: false, isRemoveBtn: true }"
-  />
-</template>
-```
-
-当 `rows.length === 1` 时不显示删除按钮。
-
-## 7. 样式定制
-
-### 7.1 可自定义的 CSS 变量
-
-组件样式使用到以下 CSS 变量（来自主题系统）：
-
-- `--j-color-hover`
-- `--j-color-text-secondary`
-- `--j-color-text`
-- `--j-color-primary`
-- `--j-color-danger`
-
-### 7.2 样式覆盖指南
-
-组件关键类名：
-
-- 根容器：`.j-input-rows`
-- 单行容器：`.j-space` / `.j-space-compact`，并可叠加 `.j-space-wrap`
-- 序号/字母：`.j-input-rows-num` / `.j-input-rows-char`
-- 拖拽图标：`.j-input-rows-drag`
-- 删除图标：`.j-input-rows-delete`
-- 操作区：`.j-input-rows-actions`
-
-覆盖示例：
-
-```css
-.j-input-rows .j-space:hover,
-.j-input-rows .j-space-compact:hover {
-  background-color: rgba(0, 0, 0, 0.04);
-}
-
-.j-input-rows-actions {
-  margin-top: 12px;
-}
-```
-
-<script setup>
-import Basic from '../examples/input-rows/basic.vue'
-import Drag from '../examples/input-rows/drag.vue'
-import Nested from '../examples/input-rows/nested.vue'
-import inputRowsApi from './meta/input-rows'
-
-import basicCode from '../examples/input-rows/basic.vue?raw'
-import dragCode from '../examples/input-rows/drag.vue?raw'
-import nestedCode from '../examples/input-rows/nested.vue?raw'
-</script>
+# InputRows 行输入
+
+`j-input-rows` 用于维护“多行对象数组”类型的数据：每一行通过 `columns` 渲染若干输入控件，支持新增行、删除行，以及（可选）拖拽排序。
+
+## 基础用法
+
+通过 `columns` 属性定义列配置，`v-model` 绑定数据。
+
+<Demo :source-code="basicCode">
+  <template #source>
+    <basic />
+  </template>
+  <template #description>
+    使用 `j-input-rows` 创建一个可编辑的数据表格。每行包含多个字段，支持添加、删除行操作。
+  </template>
+</Demo>
+
+## 拖拽排序
+
+通过 `editConfig.drag` 属性启用拖拽排序功能。
+
+<Demo :source-code="dragCode">
+  <template #source>
+    <drag />
+  </template>
+  <template #description>
+    设置 `editConfig.drag` 为 `true` 启用拖拽排序功能，可以通过拖拽图标调整行的顺序。
+  </template>
+</Demo>
+
+## 嵌套表单
+
+支持在行内嵌套 `j-input-rows` 组件，实现多层级的数据录入。
+
+<Demo :source-code="nestedCode">
+  <template #source>
+    <nested />
+  </template>
+  <template #description>
+    示例展示在列配置中使用嵌套能力来录入多层级数据结构。
+  </template>
+</Demo>
+
+## API（表格）
+
+<ApiTable :data="inputRowsApi" componentName="input-rows" />
+
+## 1. 组件概述
+
+### 主要功能和用途
+
+- 行级数据维护：`modelValue` 为对象数组，每个对象代表一行。
+- 行内字段渲染：通过 `columns` 逐列渲染行内输入控件（内部使用 `j-comp` 动态渲染）。
+- 编辑能力：添加、删除、拖拽排序（由 `editConfig` 控制）。
+- 辅助展示：支持显示行序号（1,2,3...）或字母序号（A-Z 循环）。
+
+### 适用的业务场景和使用限制
+
+适用场景：
+
+- 表单里需要录入可变数量条目：如“联系人列表”“参数列表”“阈值配置”“规则列表”等。
+- 需要一个轻量的列表型编辑器，但又不想引入完整表格组件。
+
+限制/注意事项：
+
+- 组件会对数组进行就地修改（`push/splice`），并可能对每行对象补充唯一标识字段 `i`（UUID）。请避免把业务字段命名为 `i`。
+- 当 `modelValue` 为空数组时，组件会在初始化时触发一次 `update:modelValue([])`；后续新增/删除/排序主要依赖就地修改与 `change` 事件。
+- `change` 事件中的 `formData` 来自表单注入；不在 `j-form` 环境使用时，`formData` 可能为 `undefined`。
+
+## 2. 属性说明（Props）
+
+> 下文“类型/默认值”以组件源码为准。
+
+### 2.1 组件属性
+
+#### modelValue
+
+- 名称：`modelValue`
+- 类型：`Record<string, any>[]`
+- 默认值：`[]`
+- 是否必填：否（通常与 `v-model` 搭配）
+- 详细描述：行数据数组。每项是一个对象，字段写入到行对象上的 key 通常来自 `columns[*].id`，也可通过 `columns[*].config.valueRowKey` 指定。
+- 使用示例：
+
+```vue
+<template>
+  <j-input-rows v-model="rows" :columns="columns" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const rows = ref<Record<string, any>[]>([
+  { i: '1', name: '张三', age: 18 },
+  { i: '2', name: '李四', age: 20 },
+])
+</script>
+```
+
+#### columns
+
+- 名称：`columns`
+- 类型：`SchemaConfig[]`
+- 默认值：`[]`
+- 是否必填：是
+- 详细描述：列配置数组。每个列配置会被透传给 `j-comp` 渲染为具体输入控件。
+- 使用示例：
+
+```ts
+const columns = [
+  {
+    id: 'name',
+    type: 'j-input',
+    config: { label: '姓名', placeholder: '请输入姓名', defaultValue: '' },
+  },
+  {
+    id: 'age',
+    type: 'j-number',
+    config: { label: '年龄', placeholder: '请输入年龄', defaultValue: 0, min: 0, max: 150 },
+  },
+]
+```
+
+#### editConfig
+
+- 名称：`editConfig`
+- 类型：`EditConfigType`
+- 默认值：`{}`
+- 是否必填：否
+- 详细描述：编辑配置，控制添加/删除/只读/拖拽等行为。
+- 使用示例：
+
+```ts
+const editConfig = {
+  isAddBtn: true,
+  isRemoveBtn: true,
+  addBtnText: '添加一行',
+  buttonsAlign: 'left',
+  readonly: false,
+  drag: true,
+  isNullValue: true,
+}
+```
+
+#### isCompact
+
+- 名称：`isCompact`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否紧凑模式（行高与 padding 更小）。
+- 使用示例：`<j-input-rows v-model="rows" :columns="columns" is-compact />`
+
+#### showNum
+
+- 名称：`showNum`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否显示行序号（1,2,3...）。
+- 使用示例：`<j-input-rows v-model="rows" :columns="columns" show-num />`
+
+#### showChar
+
+- 名称：`showChar`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否显示字母序号（A-Z 循环）。
+- 使用示例：`<j-input-rows v-model="rows" :columns="columns" show-char />`
+
+#### isWrap
+
+- 名称：`isWrap`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否允许行内字段换行（`flex-wrap: wrap`）。
+- 使用示例：`<j-input-rows v-model="rows" :columns="columns" is-wrap />`
+
+#### id
+
+- 名称：`id`
+- 类型：`String`
+- 默认值：`''`
+- 是否必填：否
+- 详细描述：字段/组件 id。该值会原样透传到 `change` 事件的回调参数 `payload.id` 中，用于区分来源。
+- 使用示例：`<j-input-rows id="user-list" v-model="rows" :columns="columns" />`
+
+### 2.2 EditConfigType 说明
+
+#### isAddBtn
+
+- 名称：`isAddBtn`
+- 类型：`Boolean`
+- 默认值：`true`（逻辑为 `!== false` 即显示）
+- 是否必填：否
+- 详细描述：是否显示添加按钮。
+- 使用示例：`editConfig: { isAddBtn: false }`
+
+#### addBtnText
+
+- 名称：`addBtnText`
+- 类型：`String`
+- 默认值：`'添加'`
+- 是否必填：否
+- 详细描述：添加按钮文本。
+- 使用示例：`editConfig: { addBtnText: '新增条目' }`
+
+#### buttonsAlign
+
+- 名称：`buttonsAlign`
+- 类型：`'left' | 'center' | 'right'`
+- 默认值：`'left'`
+- 是否必填：否
+- 详细描述：底部操作区（添加按钮区域）对齐方式。
+- 使用示例：`editConfig: { buttonsAlign: 'right' }`
+
+#### isRemoveBtn
+
+- 名称：`isRemoveBtn`
+- 类型：`Boolean`
+- 默认值：`true`（逻辑为 `!== false` 即显示）
+- 是否必填：否
+- 详细描述：是否显示删除按钮。
+- 使用示例：`editConfig: { isRemoveBtn: false }`
+
+#### readonly
+
+- 名称：`readonly`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否只读。为 `true` 时隐藏添加/删除操作区；行内输入控件是否只读取决于列配置本身。
+- 使用示例：`editConfig: { readonly: true }`
+
+#### drag
+
+- 名称：`drag`
+- 类型：`Boolean`
+- 默认值：`false`
+- 是否必填：否
+- 详细描述：是否支持拖拽排序。开启后每行会显示拖拽手柄图标。
+- 使用示例：`editConfig: { drag: true }`
+
+#### isNullValue
+
+- 名称：`isNullValue`
+- 类型：`Boolean`
+- 默认值：`true`（逻辑为 `!== false` 即允许“可删到空”）
+- 是否必填：否
+- 详细描述：是否允许删除到空。当 `isNullValue === false` 时，仅当 `list.length > 1` 才显示删除按钮（禁止删除最后一行）。
+- 使用示例：`editConfig: { isNullValue: false }`
+
+## 3. 事件说明（Events）
+
+### update:modelValue
+
+- 事件名称：`update:modelValue`
+- 触发条件：初始化时 `modelValue` 为空数组会触发一次；其他场景通常依赖数组就地修改，不保证每次新增/删除/排序都触发该事件。
+- 回调参数：`value: Record<string, any>[]`
+
+### change
+
+- 事件名称：`change`
+- 触发条件：新增行、删除行、拖拽排序后触发。
+- 回调参数说明：
+
+```ts
+type InputRowsChangePayload = {
+  id: string
+  value: any
+  data: any
+  formData: Record<string, any> | undefined
+  tableData: Record<string, any>[]
+  type: 'add' | 'delete' | 'update' | 'sort'
+}
+```
+
+### rowChange
+
+- 事件名称：`rowChange`
+- 触发条件：行内字段变化时触发（由内部注入的 `rowChange` 回调触发）。
+- 回调参数说明：`data: Record<string, any>`（透传自内部 `j-comp` 的变更数据）
+
+## 4. 方法说明（Methods）
+
+- 当前版本未通过 `defineExpose` 暴露任何公共方法。
+
+## 5. 插槽说明（Slots）
+
+- 当前版本不支持插槽。
+
+## 6. 使用示例（进阶）
+
+### 6.1 新增行默认值（defaultValue）与字段落点（valueRowKey）
+
+```ts
+const columns = [
+  { id: 'name', type: 'j-input', config: { label: '名称', defaultValue: '未命名' } },
+  {
+    id: 'amount',
+    type: 'j-number',
+    config: { label: '金额', defaultValue: 0, valueRowKey: 'price' },
+  },
+]
+```
+
+点击“添加”后，新行会写入到行对象的 `price` 字段（而不是 `amount`），形如：`{ i: 'uuid', name: '未命名', price: 0 }`。
+
+### 6.2 不允许删到空（isNullValue: false）
+
+```vue
+<template>
+  <j-input-rows
+    v-model="rows"
+    :columns="columns"
+    :edit-config="{ isNullValue: false, isRemoveBtn: true }"
+  />
+</template>
+```
+
+当 `rows.length === 1` 时不显示删除按钮。
+
+## 7. 样式定制
+
+### 7.1 可自定义的 CSS 变量
+
+组件样式使用到以下 CSS 变量（来自主题系统）：
+
+- `--j-color-hover`
+- `--j-color-text-secondary`
+- `--j-color-text`
+- `--j-color-primary`
+- `--j-color-danger`
+
+### 7.2 样式覆盖指南
+
+组件关键类名：
+
+- 根容器：`.j-input-rows`
+- 单行容器：`.j-space` / `.j-space-compact`，并可叠加 `.j-space-wrap`
+- 序号/字母：`.j-input-rows-num` / `.j-input-rows-char`
+- 拖拽图标：`.j-input-rows-drag`
+- 删除图标：`.j-input-rows-delete`
+- 操作区：`.j-input-rows-actions`
+
+覆盖示例：
+
+```css
+.j-input-rows .j-space:hover,
+.j-input-rows .j-space-compact:hover {
+  background-color: rgba(0, 0, 0, 0.04);
+}
+
+.j-input-rows-actions {
+  margin-top: 12px;
+}
+```
+
+<script setup>
+import Basic from '../examples/input-rows/basic.vue'
+import Drag from '../examples/input-rows/drag.vue'
+import Nested from '../examples/input-rows/nested.vue'
+import inputRowsApi from './meta/input-rows'
+
+import basicCode from '../examples/input-rows/basic.vue?raw'
+import dragCode from '../examples/input-rows/drag.vue?raw'
+import nestedCode from '../examples/input-rows/nested.vue?raw'
+</script>