@tplc/business/components/FORM_KEY_USAGE.md

# FormKey 功能使用说明

## 功能概述

该功能允许 `lcb-form` 组件将表单数据通过 `formKey` 注册到页面上下文 (`PAGE_PROVIDE_KEY`) 中，然后 `lcb-button` 组件可以通过指定 `formKeys` 在发送请求时自动携带对应表单的数据。

## 使用方法

### 1. 在 lcb-form 中设置 formKey

```vue
<lcb-form 
  :fields="formFields"
  formKey="userForm"
  v-model="formData"
/>
```

- `formKey`: 表单的唯一标识符，可以是任意字符串
- 设置 `formKey` 后，表单数据会自动注册到 `PAGE_PROVIDE_KEY` 中

### 2. 在 lcb-button 中关联 formKeys

#### 方式一：直接在 button 上设置 formKeys

```vue
<lcb-button
  text="提交"
  :formKeys="['userForm']"
  :action="{
    jumpType: 17,
    requestInfo: {
      requestUrl: '/api/user/submit',
      requestParams: {
        type: 'create'
      }
    }
  }"
/>
```

#### 方式二：在 action 的 requestInfo 中设置 formKeys

```vue
<lcb-button
  text="提交"
  :action="{
    jumpType: 17,
    requestInfo: {
      requestUrl: '/api/user/submit',
      requestParams: {
        type: 'create'
      },
      formKeys: ['userForm']
    }
  }"
/>
```

### 3. 关联多个表单

一个按钮可以同时关联多个表单：

```vue
<lcb-button
  text="提交"
  :formKeys="['userForm', 'addressForm']"
  :action="{
    jumpType: 17,
    requestInfo: {
      requestUrl: '/api/user/submit',
      requestParams: {
        type: 'create'
      }
    }
  }"
/>
```

或在 requestInfo 中：

```vue
<lcb-button
  text="提交"
  :action="{
    jumpType: 17,
    requestInfo: {
      requestUrl: '/api/user/submit',
      requestParams: {
        type: 'create'
      },
      formKeys: ['userForm', 'addressForm']
    }
  }"
/>
```

## 数据合并规则

当按钮发送请求时，数据合并顺序为：

1. 先使用 `requestParams` 中的原始参数
2. 然后依次合并 `formKeys` 对应的表单数据
3. **formKeys 的数据会覆盖 requestParams 中的同名字段**

### 示例

假设有以下配置：

```javascript
// 表单数据
formData = {
  name: '张三',
  age: 25
}

// requestParams
requestParams = {
  type: 'create',
  age: 20
}
```

最终发送的请求参数为：

```javascript
{
  type: 'create',  // 来自 requestParams
  name: '张三',    // 来自 formKeys
  age: 25          // 来自 formKeys，覆盖了 requestParams 中的 age: 20
}
```

## 完整示例

```vue
<template>
  <view>
    <!-- 用户信息表单 -->
    <lcb-form 
      :fields="userFields"
      formKey="userForm"
      v-model="userData"
    />
    
    <!-- 地址信息表单 -->
    <lcb-form 
      :fields="addressFields"
      formKey="addressForm"
      v-model="addressData"
    />
    
    <!-- 提交按钮，同时提交两个表单的数据 -->
    <lcb-button
      text="提交"
      :formKeys="['userForm', 'addressForm']"
      :action="{
        jumpType: 17,
        requestInfo: {
          requestUrl: '/api/user/submit',
          requestParams: {
            submitType: 'complete'
          }
        }
      }"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'

const userData = ref({})
const addressData = ref({})

const userFields = [
  // ... 表单字段配置
]

const addressFields = [
  // ... 表单字段配置
]
</script>
```

## 注意事项

1. **无需表单验证**: 按钮发送请求时不会触发表单验证，直接提交数据
2. **formKey 必须唯一**: 在同一个页面中，不同表单的 `formKey` 应该保持唯一
3. **数据覆盖**: formKeys 的数据会覆盖 requestParams 中的同名字段
4. **formKeys 优先级**: 如果 button 和 requestInfo 中都设置了 formKeys，button 的 formKeys 会传递给 requestInfo
5. **数组类型**: formKeys 统一使用数组类型，即使只绑定一个表单也需要使用数组：`['formKey']`