---
name: deppon-pro-form
description: >-
    使用 Vue 3 script setup、@deppon/deppon-template 的 ProForm 与 @deppon/deppon-ui
    生成或改写表单页。在用户需要新建/编辑表单、ProForm columns、校验规则、actions 插槽，
    或提到 ProForm、表单页、deppon-template 表单 时应用。
---

# deppon-pro-form：ProForm 页面（私有 npm）

## 依据来源（私有 npm）

-   **`deppon-npm-private-registry`**：外仓安装 `@deppon/*` 与文档位置。
-   **`@deppon/deppon-template`**：`ProForm` — `node_modules` 内 README、`VITE_USAGE.md`、`USAGE.md`、`es/**/*.d.ts`。
-   **`@deppon/deppon-ui`**：`ElButton`、`ElMessage`、`ElCard` 等。
-   专项索引：**`deppon-npm-skills`**。不默认读取 `deppon-npm` 的 `site/`；若用户工作区为该 monorepo 且要求对齐内部 demo，再查阅其本地示例。

## 必须遵守的栈与风格

-   Vue 3：`script setup`，组件从模板里用到的再 `import`。
-   表单：`import { ProForm } from '@deppon/deppon-template'`。
-   UI：`import { ElButton, ElMessage, ElCard, ... } from '@deppon/deppon-ui'`（与包文档一致；勿混用未约定包除非项目已采用）。
-   样式：`scoped` + `lang="less"` 时与项目及组件库要求一致。

## 页面骨架（常见布局）

```vue
<template>
    <div class="xxx">
        <el-card>
            <template #header><span>标题</span></template>
            <pro-form
                ref="formRef"
                :columns="columns"
                :mode="isReadonly ? 'read' : 'edit'"
                :label-width="'120px'"
                :cols="2"
                :initial-values="formData"
                @submit="handleSubmit"
                @values-change="handleValuesChange"
            >
                <template #actions="{ form }">
                    <div class="form-actions">
                        <el-button type="primary" @click="form.submit()">提交</el-button>
                        <el-button @click="form.reset()">重置</el-button>
                    </div>
                </template>
            </pro-form>
        </el-card>
    </div>
</template>
```

-   只读默认：表单级 `:mode="'read'"` 或字段 `mode: 'read'` → **纯文本无边框**（历史样式）。
-   需要带框时：加 `:read-style-as-edit="true"` → **与详情相同左对齐布局**，控件有边框且 disabled。
-   编辑态左对齐：加 `:edit-style-as-readonly="true"`（默认关闭，与 `read-style-as-edit` 同为显式开启）。

## columns 字段约定（ProForm）

每条 column 常见键：

-   `name`：字段名，对应 `initial-values` / 提交对象中的 key。
-   `label`：标签文案。
-   `valueType`：`text` | `textarea` | `select` | `dateTime` 等（以 **`ProForm` 列配置文档/类型** 为准）。
-   `required`：布尔；可与 `rules` 并用。
-   `fieldProps`：传给内部输入组件的属性（`placeholder`、`clearable`、`maxlength`、`rows` 等）。
-   `options`：`{ label, value }[]`，用于 `select`。
-   `rules`：Element Plus 风格校验数组；复杂逻辑用 `validator`。
-   `warningTooltip`：必填警示提示（可选）。
-   自定义组件：`component: 'el-input-number'` + `componentProps: { ... }`（以包内可注册组件名为准）。

内联查询表单：给 `pro-form` 增加 `:inline="true"`，并缩小 `label-width`（模式对齐 **`deppon-pro-page-query-table-form`** 顶部查询条）。

## 脚本状态约定

-   `const formRef = ref(null);`
-   `const formData = ref({});` 或与业务字段对齐的初始对象。
-   `const columns = ref([...])` 或 `computed(() => [...])`（依赖字典时用 `computed`）。
-   `handleSubmit`：接入真实 API 时 `async`，成功/失败用 `ElMessage`。
-   `handleValuesChange`：需要联动、清空关联字段时同步 `formData` 或记录上一次关键字段（适用于「主键字段 blur/清空联动」等模式）。

## actions 区样式（可选）

```less
.form-actions {
    margin-top: 20px;
    padding-top: 20px;
    border-top: 1px solid #ebeef5;
    display: flex;
    gap: 12px;
    justify-content: flex-end;
}
```

## 生成清单（交付前自检）

-   [ ] `name` 与 `initial-values` / 提交 payload 键一致。
-   [ ] 选择类字段有 `options` 或远程搜索占位说明。
-   [ ] 必填在业务上是否同时需要 `rules`（与项目表单规范一致）。
-   [ ] 是否需要 `cols`、`colSpan`（textarea 常 `colSpan: 2`）。