# Yida Table Form

> 宜搭表格形态批量表单提交页面开发。支持动态增删行、行内编辑验证、Excel 粘贴导入、草稿暂存、批量 saveFormData 提交。适用于需要一次性录入多条表单数据的场景。

- Skill: `openyida/yida-table-form` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add openyida/yida-table-form`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openyida/yida-table-form/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: openyida (https://skillmd.com/u/openyida)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openyida/yida-table-form

---


# 宜搭自定义页面表格表单提交技能

## 严格禁止 (NEVER DO)

- 不要在前端做批量提交时使用串行（逐条等待），必须用 `Promise.all` 并发提交
- 不要在提交前跳过行验证，必须先 `validateRow` 再提交
- 不要硬编码 `FORM_UUID`，必须从 `project/config.json` 或用户提供的信息中获取
- 不要在提交成功后保留草稿，必须调用 `clearDraft()` 清除 localStorage
- 不要忽略提交失败的行，必须在 UI 上标红并提示用户修正后重新提交

## 严格要求 (MUST DO)

- **批量提交前必须确认**：执行批量提交前，必须向用户展示待提交数据的摘要（行数、关键字段），获得用户明确同意后再执行
- 必须在 `COLUMNS` 配置区定义所有列，字段 ID 从表单 Schema 中提取
- 必须实现草稿自动保存（`localStorage`），防止用户刷新丢失数据
- 必须在提交结果中区分成功/失败数量，失败行保留可编辑状态
- 批量提交必须使用 `Promise.all` 并发，不得串行等待

## 适用场景

| 用户意图 | 触发条件 |
|---------|---------|
| 批量录入同类数据 | "批量添加"、"批量录入"、"Excel 导入" |
| 行内编辑 + 批量保存 | "表格形式填写"、"多行同时编辑" |
| Excel 粘贴导入 | "从 Excel 粘贴"、"复制粘贴数据" |

## 触发条件

**正向触发**：
- "批量添加"、"批量录入"、"Excel 导入"
- "表格形式填写"、"多行同时编辑"
- "从 Excel 粘贴"、"复制粘贴数据"

> ⚠️ 表格表单在移动端体验差，移动端场景建议使用标准表单。

## 异常处理

| 异常场景 | 处理方式 |
|---------|----------|
| 批量提交部分失败 | 失败行在 UI 上标红，保留可编辑状态，提示用户修正后重新提交 |
| 提交前未验证 | 必须先 `validateRow` 验证所有行，再执行批量提交 |
| 提交成功后草稿未清除 | 必须调用 `clearDraft()` 清除 localStorage |
| 串行提交导致超时 | 必须使用 `Promise.all` 并发提交，不得串行等待 |
| FORM_UUID 硬编码 | 必须从 `project/config.json` 或用户提供的信息中获取，不得硬编码 |
| fieldId 不存在 | 先执行 `yida-get-schema` 获取真实 fieldId |
| 草稿恢复失败 | 提示用户 localStorage 可能被清空，重新录入数据 |
| 接口超时 | 减少单次提交条数（建议 ≤50 条），分批提交 |
| 数据量过大 | 建议分批录入，每批不超过 100 条 |

## Agent 错误处理策略

当 Agent 执行本技能遇到错误时，必须遵循以下默认行为：

| 错误类型 | 默认处理策略 |
|---------|-------------|
| 代码生成失败 | 停止执行，向用户展示错误信息，询问是否重试或调整需求 |
| 参数缺失（FORM_UUID/字段 ID 等） | 主动询问用户补充，或引导用户使用 `yida-get-schema` 获取 |
| 权限不足 / 登录态失效 | 停止执行，提示用户执行 `openyida auth status` 检查登录态 |
| 批量提交部分失败 | 展示失败行详情，保留可编辑状态，引导用户修正后重试 |
| 字段类型不支持 | 停止执行，提示用户该字段类型暂不支持，建议调整表单设计 |
| 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |

---


## 概述

在批量录入同类数据（如批量添加商品、批量录入考勤、批量创建任务）的场景下，标准表单页面每次只能提交一条记录，效率低下。本技能提供表格形式的批量表单提交方案，支持行内编辑、验证和批量提交。

---

## 何时使用

- 批量录入同类数据（如：批量添加商品、批量录入考勤）
- Excel 式数据编辑体验
- 行内编辑 + 批量保存

---

## 核心数据结构

```javascript
// 每行数据结构
{
  id: 'temp_' + Date.now(),   // 临时行 ID（提交后替换为 formInstId）
  fieldA: '',                  // 各字段值
  fieldB: '',
  _status: 'valid',            // 'valid' | 'invalid' | 'submitting' | 'submitted'
  _errors: {},                 // { fieldA: '必填', fieldB: '格式错误' }
}
```

---

## 实现内容

表格表单页面需要包含动态增删行、行内验证、Excel 粘贴导入、草稿暂存和批量提交；字段 ID 先从目标表单 Schema 获取，再写入列配置。
---

## 功能说明

### 动态增删行

- 点击「+ 添加行」在表格末尾新增空行
- 点击行末的 🗑 按钮删除该行（已提交成功的行不可删除）
- 表格始终保留至少一行

### Excel 粘贴导入

点击「📋 粘贴 Excel 数据」后，将从 Excel 复制的内容粘贴到剪贴板，系统自动按 Tab 分隔解析列，按换行分隔解析行，追加到现有数据后。

> **注意**：列顺序需与 `COLUMNS` 定义一致。

### 行内验证

提交前自动验证所有行：
- 必填字段为空 → 标红并显示错误信息
- 验证失败的行背景变为浅红色
- 全部通过后才发起提交请求

### 草稿暂存

每次修改单元格后自动将数据保存到 `localStorage`，key 为 `yida_table_form_draft_{formUuid}`。刷新页面后自动恢复草稿。提交全部成功后自动清除草稿。
### 批量提交

使用 `Promise.all` 并发提交所有行，每行独立调用 `saveFormData`：
- 提交中的行显示 loading 状态
- 提交成功的行背景变绿，显示 ✓
- 提交失败的行背景变红，显示错误信息，可修正后重新提交

## 自定义配置

修改文件顶部的配置区即可适配不同表单：

```javascript
var FORM_UUID = 'FORM-XXX';   // 替换为实际表单 UUID

var COLUMNS = [
  // type 支持：'text' | 'select' | 'date'
  { label: '字段名', field: 'fieldId_xxx', type: 'text', required: true },
  { label: '下拉字段', field: 'selectField_xxx', type: 'select', required: false,
    options: ['选项A', '选项B', '选项C'] },
];
```

---

## 注意事项

- **本技能不读写 memory**：表格表单的草稿数据通过 `localStorage` 在浏览器本地持久化，不依赖跨会话的 memory 状态