# GridFrom

**Repository Path**: wanghenan/grid-from

## Basic Information

- **Project Name**: GridFrom
- **Description**: 基于vue3、and design vue 技术栈实现表格样式表单
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GridForm

> 基于 Vue 3 + Ant Design Vue 4 开发的表格样式通用表单组件，支持单列、多列、单元格横向合并（`span`）、纵向合并（`rowSpan`）及无标签（`noLabel`）等灵活布局，内置多种输入控件、表单校验与焦点高亮效果。

---

## 效果预览

### 示例一：单列布局

![单列布局](./public/preview-demo1.png)

### 示例二：两列布局 + span 横向合并

![两列布局横向合并](./public/preview-demo2.png)

### 示例三：三列布局 + 多种控件类型

![三列布局多控件](./public/preview-demo3.png)

### 示例四：rowSpan 纵向合并 + noLabel 无标签字段

![纵向合并与无标签](./public/preview-demo4.png)

### 示例五：后端校验错误注入

![后端错误注入](./public/preview-demo5.png)

### 校验错误提示效果

#### 前端必填校验错误

![前端校验错误](./public/error-validation.png)

#### 后端错误注入（模拟服务端返回）

![后端错误注入](./public/error-backend.png)

---

## 技术栈

| 技术 | 版本 | 说明 |
|---|---|---|
| [Vue 3](https://vuejs.org/) | ^3.5 | Composition API + `<script setup>` |
| [Ant Design Vue](https://antdv.com/) | ^4.x | UI 组件库 |
| [Vite](https://vitejs.dev/) | ^5.x | 构建工具 |
| JavaScript (ES2020+) | — | 无 TypeScript 依赖，开箱即用 |

---

## 功能特性

- **多种布局模式**：单列、两列、三列及任意列数，通过 `columns` 属性控制
- **横向合并**：`span` 属性控制字段横跨列数
- **纵向合并**：`rowSpan` 属性控制内容单元格跨行
- **无标签字段**：`noLabel` 属性，内容列自动补满宽度
- **内置控件类型**：`input` / `textarea` / `number` / `select` / `date` / `date-range` / `radio` / `checkbox` / `switch` / `text`
- **表单校验**：内置必填校验 + 自定义 `validator` 函数，错误信息显示为输入框 placeholder 红色提示
- **焦点高亮**：获得焦点时整个单元格边框蓝色高亮 + 外发光效果
- **插槽扩展**：每个字段支持具名插槽自定义渲染
- **外部错误注入**：`setErrors()` 支持后端返回的字段级错误
- **双向绑定**：标准 `v-model` 支持

---

## 安装依赖

```bash
npm install
```

---

## 集成到已有项目

### 1. 安装依赖

确保项目中已安装 `ant-design-vue`：

```bash
npm install ant-design-vue@4
```

### 2. 注册 Ant Design Vue

在 `main.js` 中全局注册：

```js
import { createApp } from 'vue'
import Antd from 'ant-design-vue'
import 'ant-design-vue/dist/reset.css'
import App from './App.vue'

createApp(App).use(Antd).mount('#app')
```

### 3. 复制组件

将 `src/components/GridForm.vue` 复制到你的项目组件目录中即可直接使用，无需额外配置。

---

## 使用示例

### 示例一：单列布局

```vue
<template>
  <GridForm
    title="个人简介"
    :columns="1"
    :fields="fields"
    v-model="formData"
    label-width="90px"
  />
</template>

<script setup>
import { ref } from 'vue'
import GridForm from '@/components/GridForm.vue'

const fields = [
  { name: 'nickname', label: '昵称', required: true },
  { name: 'age',      label: '年龄', type: 'number', min: 1, max: 120 },
  { name: 'email',    label: '邮箱', required: true,
    validator: v => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) ? null : '邮箱格式不正确' },
  { name: 'bio',      label: '简介', type: 'textarea', rows: 3 },
]

let formData = ref({})
</script>
```

---

### 示例二：两列布局 + `span` 横向合并

```vue
<template>
  <GridForm
    ref="formRef"
    title="联系我们"
    :columns="2"
    :fields="fields"
    v-model="formData"
    label-width="100px"
  />
  <a-button type="primary" @click="formRef.validate()">发送</a-button>
</template>

<script setup>
import { ref } from 'vue'
import GridForm from '@/components/GridForm.vue'

const formRef = ref(null)

const fields = [
  { name: 'firstName', label: '姓',       required: true, span: 1 },
  { name: 'lastName',  label: '名',       required: true, span: 1 },
  // span=2：横跨两列，占满整行
  { name: 'email',     label: '电子邮箱', required: true, span: 2 },
  { name: 'subject',   label: '主题',     required: true, span: 2 },
  { name: 'message',   label: '消息正文', type: 'textarea', rows: 5, span: 2 },
]

let formData = ref({})
</script>
```

---

### 示例三：`rowSpan` 纵向合并 + `noLabel` 无标签字段

```vue
<template>
  <GridForm
    title="商品信息"
    :columns="2"
    :fields="fields"
    v-model="formData"
  />
</template>

<script setup>
import { ref } from 'vue'
import GridForm from '@/components/GridForm.vue'

/**
 * 布局示意：
 * ┌────────┬──────────┬────────┬──────────────┐
 * │ 商品名 │ [input]  │ 备注   │              │
 * ├────────┼──────────┤        │ [textarea]   │
 * │ 价格   │ [number] │ rowSpan│ rowSpan=3    │
 * ├────────┼──────────┤  =3    │              │
 * │ 品牌   │ [input]  │        │              │
 * ├────────┴──────────┴────────┴──────────────┤
 * │ [无标签，noLabel=true，span=2，跨满整行]   │
 * └───────────────────────────────────────────┘
 */
const fields = [
  { name: 'goodsName', label: '商品名', required: true, span: 1 },
  { name: 'remark',    label: '备注',   type: 'textarea', rows: 6, span: 1, rowSpan: 3 },
  { name: 'price',     label: '价格',   type: 'number', span: 1 },
  { name: 'brand',     label: '品牌',   span: 1 },
  // noLabel=true + span=2：无标签，内容跨满整行
  { name: 'desc', noLabel: true, type: 'textarea', rows: 2, span: 2,
    placeholder: '请输入商品详细描述' },
]

let formData = ref({})
</script>
```

---

### 示例四：后端错误注入

```vue
<template>
  <GridForm ref="formRef" :columns="2" :fields="fields" v-model="formData" />
  <a-button @click="handleSubmit">提交</a-button>
</template>

<script setup>
import { ref } from 'vue'
import GridForm from '@/components/GridForm.vue'

const formRef = ref(null)
const fields = [
  { name: 'username', label: '用户名', required: true },
  { name: 'email',    label: '邮箱',   required: true },
]
let formData = ref({})

async function handleSubmit() {
  if (!formRef.value.validate()) return
  // 模拟后端返回字段级错误
  formRef.value.setErrors({
    username: '用户名已被占用',
    email: '该邮箱已注册',
  })
}
</script>
```

---

## 字段配置（field）说明

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `name` | String | — | 字段键名（必填，唯一） |
| `label` | String | — | 标签文字 |
| `type` | String | `input` | 控件类型，见下表 |
| `required` | Boolean | `false` | 是否必填 |
| `requiredMessage` | String | — | 自定义必填错误提示 |
| `validator` | Function | — | 自定义校验 `(value) => errMsg \| null` |
| `placeholder` | String | — | 输入框占位提示 |
| `disabled` | Boolean | `false` | 是否禁用 |
| `defaultValue` | any | — | 重置时的默认值 |
| `options` | Array | — | select / radio / checkbox 选项 `[{label, value}]` |
| `rows` | Number | `4` | textarea 行数 |
| `min / max / step / precision` | Number | — | number 控件参数 |
| `format` | String | `YYYY-MM-DD` | date / date-range 格式 |
| `mode` | String | — | select 多选模式 `'multiple' \| 'tags'` |
| `maxlength` | Number | — | input / textarea 最大字符数 |
| **`span`** | Number | `1` | 横向合并：占几个逻辑列宽 |
| **`rowSpan`** | Number | `1` | 纵向合并：内容列跨几行 |
| **`noLabel`** | Boolean | `false` | 不渲染标签列，内容自动补满 |
| `labelWidth` | String | — | 单字段标签宽度（覆盖组件级设置） |
| `labelSpan` | Number | — | 标签列物理跨列数（高级） |
| `contentColSpan` | Number | — | 内容列物理跨列数（高级） |

### 支持的控件类型

| type | 控件 |
|---|---|
| `input`（默认） | 单行文本输入框 |
| `textarea` | 多行文本输入框 |
| `number` | 数字输入框 |
| `select` | 下拉选择框 |
| `date` | 日期选择器 |
| `date-range` | 日期范围选择器 |
| `radio` | 单选按钮组 |
| `checkbox` | 多选框组 |
| `switch` | 开关 |
| `text` | 纯文本展示（只读） |

---

## 组件 Props

| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `title` | String | `''` | 表单标题行 |
| `columns` | Number | `2` | 每行列数 |
| `fields` | Array | `[]` | 字段配置数组 |
| `modelValue` | Object | `{}` | 表单数据（v-model） |
| `width` | String | `'100%'` | 表格宽度 |
| `labelWidth` | String | `'100px'` | 标签列宽度 |

---

## 暴露方法（ref 调用）

| 方法 | 说明 | 返回值 |
|---|---|---|
| `validate()` | 执行表单校验 | `Boolean` |
| `clearValidate()` | 清除所有校验错误 | — |
| `resetFields()` | 重置表单数据为默认值 | — |
| `setErrors(map)` | 注入外部错误 `{ fieldName: errMsg }` | — |
| `formData` | 当前表单数据（ref） | `Ref<Object>` |

---

## 本地开发

```bash
# 克隆仓库
git clone https://gitee.com/wanghenan/grid-from.git
cd grid-from

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建
npm run build
```

---

## License

[MIT](./LICENSE)