@a2simcode/ui 0.0.45 → 0.0.47

package/docs/components/input-rows.md

@@ -0,0 +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>

package/docs/components/input-tag.md

@@ -0,0 +1,50 @@
+# InputTag 输入标签
+
+用于输入并以标签形式展示内容的组件。
+
+## 基础用法
+
+<Demo :source-code="inputTagBasicCode">
+  <template #source>
+    <input-tag-basic />
+  </template>
+  <template #description>
+    使用 `v-model` 绑定一个逗号分隔的字符串。输入内容后按回车即可添加标签。
+  </template>
+</Demo>
+
+## 只读状态
+
+<Demo :source-code="inputTagReadonlyCode">
+  <template #source>
+    <input-tag-readonly />
+  </template>
+  <template #description>
+    设置 `readonly` 属性使组件处于只读状态，此时无法添加或删除标签。
+  </template>
+</Demo>
+
+## 自定义颜色
+
+<Demo :source-code="inputTagColorsCode">
+  <template #source>
+    <input-tag-colors />
+  </template>
+  <template #description>
+    通过 `colors` 属性传入颜色对象数组，可以自定义标签的样式。默认会循环使用这些颜色。
+  </template>
+</Demo>
+
+## API
+
+<ApiTable :data="inputTagApi" componentName="input-tag" />
+
+<script setup>
+import InputTagBasic from '../examples/input-tag/basic.vue'
+import InputTagReadonly from '../examples/input-tag/readonly.vue'
+import InputTagColors from '../examples/input-tag/colors.vue'
+import inputTagApi from './meta/input-tag'
+import inputTagBasicCode from '../examples/input-tag/basic.vue?raw'
+import inputTagReadonlyCode from '../examples/input-tag/readonly.vue?raw'
+import inputTagColorsCode from '../examples/input-tag/colors.vue?raw'
+</script>

package/docs/components/input.md

@@ -0,0 +1,129 @@
+# Input 输入框
+
+通过鼠标或键盘输入字符。
+
+## 基础用法
+
+<Demo :source-code="inputBasicCode">
+  <template #source>
+    <input-basic />
+  </template>
+  <template #description>
+    使用 v-model 实现双向数据绑定。
+  </template>
+</Demo>
+
+## 不同尺寸
+
+Input 组件提供三种尺寸。
+
+<Demo :source-code="inputSizeCode">
+  <template #source>
+    <input-size />
+  </template>
+  <template #description>
+    使用 size 属性改变输入框大小。除了默认大小外,还有另外两个选项: large, small。
+  </template>
+</Demo>
+
+## 禁用和只读
+
+通过 `disabled` 和 `readonly` 属性指定输入框的状态。
+
+<Demo :source-code="inputDisabledCode">
+  <template #source>
+    <input-disabled />
+  </template>
+  <template #description>
+    通过 disabled 属性指定是否禁用 input 组件,通过 readonly 属性指定是否只读。
+  </template>
+</Demo>
+
+## 可清除
+
+使用 `clearable` 属性即可得到一个可清除的输入框。
+
+<Demo :source-code="inputClearableCode">
+  <template #source>
+    <input-clearable />
+  </template>
+  <template #description>
+    设置 `clearable` 属性为 `true` 即可显示清除按钮。
+  </template>
+</Demo>
+
+## 密码框
+
+使用 `show-password` 属性即可得到一个可切换显示隐藏的密码框。
+
+<Demo :source-code="inputPasswordCode">
+  <template #source>
+    <input-password />
+  </template>
+  <template #description>
+    设置 `show-password` 属性为 `true` 即可显示密码切换图标。
+  </template>
+</Demo>
+
+## 字数统计
+
+设置 `show-word-limit` 属性来展示字数统计。
+
+<Demo :source-code="inputWordLimitCode">
+  <template #source>
+    <input-word-limit />
+  </template>
+  <template #description>
+    使用 `maxlength` 和 `show-word-limit` 属性来限制输入字数。通过 `word-limit-position` 可以设置字数统计的位置。
+  </template>
+</Demo>
+
+## 文本域
+
+用于输入多行文本信息可缩放的输入框。添加 `type="textarea"` 属性即可将输入框转换为文本域。
+
+<Demo :source-code="inputTextareaCode">
+  <template #source>
+    <input-textarea />
+  </template>
+  <template #description>
+    通过 `rows` 控制文本域行数，或使用 `autosize` 属性设置自适应高度。
+  </template>
+</Demo>
+
+## 带图标的输入框
+
+可以通过 `prefix-icon` 和 `suffix-icon` 属性在输入框中显示图标。
+
+<Demo :source-code="inputIconCode">
+  <template #source>
+    <input-icon />
+  </template>
+  <template #description>
+    使用 `prefix-icon` 设置前缀图标，使用 `suffix-icon` 设置后缀图标。
+  </template>
+</Demo>
+
+## API
+
+<ApiTable :data="inputApi" componentName="input" />
+
+<script setup>
+import InputBasic from '../examples/input/basic.vue'
+import InputSize from '../examples/input/size.vue'
+import InputDisabled from '../examples/input/disabled.vue'
+import InputClearable from '../examples/input/clearable.vue'
+import InputPassword from '../examples/input/password.vue'
+import InputWordLimit from '../examples/input/word-limit.vue'
+import InputTextarea from '../examples/input/textarea.vue'
+import InputIcon from '../examples/input/icon.vue'
+import inputApi from './meta/input'
+import inputBasicCode from '../examples/input/basic.vue?raw'
+import inputSizeCode from '../examples/input/size.vue?raw'
+import inputDisabledCode from '../examples/input/disabled.vue?raw'
+import inputClearableCode from '../examples/input/clearable.vue?raw'
+import inputPasswordCode from '../examples/input/password.vue?raw'
+import inputWordLimitCode from '../examples/input/word-limit.vue?raw'
+import inputTextareaCode from '../examples/input/textarea.vue?raw'
+import inputIconCode from '../examples/input/icon.vue?raw'
+</script>

package/docs/components/layer-form.md

@@ -0,0 +1,61 @@
+# LayerForm 弹窗表单
+
+通过点击按钮打开一个弹窗，在弹窗中通过 JSON Schema 配置渲染表单。
+
+::: warning 重要提示
+`j-layer-form` 组件不是单独使用的，需要结合 `j-form` 组件使用。`j-layer-form` 应该作为 `j-form` 的 `schema` 配置中的一项，通过 `type: 'j-layer-form'` 来指定。`j-layer-form` 依赖 `j-form` 提供的表单上下文（通过 `useFormInject` 获取），用于获取表单配置信息如 `labelWidth`、`labelPosition` 等。
+:::
+
+## 基础用法
+
+`j-layer-form` 需要作为 `j-form` 的 `schema` 配置中的一项使用。弹窗内的表单字段通过 `children` 配置。
+
+<Demo :source-code="layerFormBasicCode">
+  <template #source>
+    <layer-form-basic />
+  </template>
+  <template #description>
+    在 `j-form` 的 `schema` 中配置 `type: 'j-layer-form'`，弹窗内的表单字段通过 `children` 配置。`j-layer-form` 会自动继承 `j-form` 的表单配置（如 `labelWidth`、`labelPosition` 等），点击按钮打开弹窗进行表单填写。
+  </template>
+</Demo>
+
+## 自定义弹窗尺寸
+
+通过 `layerWidth` 和 `layerHeight` 属性自定义弹窗的宽度和高度。
+
+<Demo :source-code="layerFormSizeCode">
+  <template #source>
+    <layer-form-size />
+  </template>
+  <template #description>
+    在 `j-layer-form` 的 `config` 中设置 `layerWidth` 和 `layerHeight` 属性可以自定义弹窗的尺寸。
+  </template>
+</Demo>
+
+## 表单配置
+
+通过 `formConfig` 属性配置表单的布局、标签位置、大小等。`j-layer-form` 的 `formConfig` 会覆盖 `j-form` 的配置。
+
+<Demo :source-code="layerFormConfigCode">
+  <template #source>
+    <layer-form-config />
+  </template>
+  <template #description>
+    在 `j-layer-form` 的 `config` 中通过 `formConfig` 可以配置表单的 `labelWidth`、`labelPosition`、`size`、`gutter`、`span` 等属性。如果 `j-layer-form` 的 `formConfig` 中未指定某些属性，会自动继承 `j-form` 的配置。
+  </template>
+</Demo>
+
+## API
+
+<ApiTable :data="layerFormApi" componentName="layer-form" />
+
+<script setup>
+import LayerFormBasic from '../examples/layer-form/basic.vue'
+import LayerFormSize from '../examples/layer-form/size.vue'
+import LayerFormConfig from '../examples/layer-form/config.vue'
+import layerFormApi from './meta/layer-form'
+
+import layerFormBasicCode from '../examples/layer-form/basic.vue?raw'
+import layerFormSizeCode from '../examples/layer-form/size.vue?raw'
+import layerFormConfigCode from '../examples/layer-form/config.vue?raw'
+</script>