wukuang/低码移动端组件开发指南.md

# 低码移动端组件开发指南

## 概述

本文档介绍低码平台的移动端组件开发指南。移动端组件基于 Vue 进行开发，以 H5 形式运行，组件库采用 Vant。

**阅读前须知：** 在阅读本文档前，请先阅读《字段类型与物料组件开发指南.md》。移动端开发与浏览器端在整体设计、开发流程上保持一致，主要差异在于底层规划、文件目录、运行和初始化等差异。对于组件开发者，只需了按移动端的目录标准开发组件、配置组件即可。

本文档主要介绍移动端开发中的差异部分。关于功能开发的详细说明、开发标准与规范，请参考《字段类型与物料组件开发指南.md》。

## 目录结构

移动端组件的相关配置文件位于 `packages/widget-mobile/src/config` 目录下，主要包含以下文件：

```text
packages/widget-mobile/src/config/
├── index.ts                    # 配置入口文件，注册移动端设计器和预览器配置
├── Material.ts                 # 物料面板配置，定义组件在物料面板中的分类和展示
├── RegisterWidget.ts           # 组件注册配置，注册移动端组件的实现
├── RegisterWidgetHelper.ts     # 组件辅助工具注册配置
├── RegisterSettings.ts         # 组件设置配置
├── WidgetType.ts               # 组件类型枚举定义
├── widget/                     # 组件实现目录
│   ├── Root.vue                # 页面根容器组件
│   └── TestWidget.vue          # 测试组件示例
└── widget-helper/              # 组件辅助工具目录
    └── TestWidgetHelper.ts     # 测试组件辅助工具示例
```

### 主要文件说明

- **index.ts**: 配置入口，提供 `setMobileConfigAll()` 函数，用于注册设计器和预览器的配置。
- **Material.ts**: 定义组件在物料面板中的分类组织，通过 `getMaterialPanelConfig()` 返回物料配置数组。
- **RegisterWidget.ts**: 注册移动端组件的实现，将组件类型与对应的 Vue 组件进行映射。
- **WidgetType.ts**: 定义所有移动端组件的类型枚举，需要与后端定义的控件类型保持一致。

## 开发流程

添加一个新的移动端物料组件，需要完成以下 6 个步骤的配置。下面以 `TestWidget` 组件为例，详细说明每个步骤的操作。

### 步骤 1：添加组件类型枚举

在 `WidgetType.ts` 文件中添加组件类型枚举，枚举值需要与后端定义的控件类型保持一致。

```typescript
export enum WidgetType {
  // 测试组件
  TestWidget = "TEST_WIDGET",

  // 你的新组件
  // YourWidget = 'YOUR_WIDGET',
}
```

### 步骤 2：创建 Vue 组件

在 `widget/` 目录下创建组件的 Vue 文件，例如 `YourWidget.vue`。

```vue
<script setup lang="ts">
import { Rate } from "vant";
import { ref } from "vue";

const value = ref(3);
</script>

<template>
  <div class="your-widget-container">
    <!-- 组件内容 -->
    <Rate v-model="value" />
  </div>
</template>

<style lang="css" scoped>
.your-widget-container {
  /* 组件样式 */
}
</style>
```

**注意事项：**

- 组件使用 Vant 作为 UI 组件库
- 组件应支持响应式设计，适配移动端屏幕

### 步骤 3：创建 WidgetHelper 配置

在 `widget-helper/` 目录下创建 Helper 配置文件，例如 `YourWidgetHelper.ts`。

Helper 文件需要实现 `WidgetHelper` 接口，主要包含以下方法：

- `buildMaterialConfig()`: 定义组件在物料面板中的展示信息（图标、名称等）
- `buildSettings()`: 定义组件的设置面板配置（属性、样式、事件等）
- `buildWidget()`: 定义组件的默认 Schema 结构
- `buildSchemaController()`: 定义组件的 Schema 控制器方法

参考示例：

```typescript
import type { WidgetHelper } from "~@/types/WidgetHelper";
import { WidgetType } from "../WidgetType";

const config: WidgetHelper = {
  type: WidgetType.TestWidget,
  buildMaterialConfig() {
    // 返回物料配置
  },
  buildSettings(params) {
    // 返回设置面板配置
  },
  buildWidget(params) {
    // 返回组件默认 Schema
  },
  buildSchemaController() {
    // 返回 Schema 控制器方法
  },
  // 其他可选方法...
};

export default config;
```

**详细说明请参考：** `widget-helper/TestWidgetHelper.ts` 文件的完整实现。

### 步骤 4：注册组件

在 `RegisterWidget.ts` 文件的 `SYS_COMPS_MAP` 对象中添加组件映射。

```typescript
import TestWidget from "./widget/TestWidget.vue";
import { WidgetType } from "./WidgetType";

export const SYS_COMPS_MAP: Recordable<RegisterFormComponentOptions> = {
  [WidgetType.TestWidget]: {
    instance: TestWidget,
  },

  // 你的新组件
  // [WidgetType.YourWidget]: {
  //   instance: YourWidget,
  // },
};
```

### 步骤 5：注册 Helper

在 `RegisterWidgetHelper.ts` 文件的 `SYS_MOBILE_WIDGET_HELPERS` 数组中添加 Helper 的导入和注册。

```typescript
import TestWidgetHelper from "./widget-helper/TestWidgetHelper";

export const SYS_MOBILE_WIDGET_HELPERS = [
  TestWidgetHelper,

  // 你的新组件
  // YourWidgetHelper,
];
```

### 步骤 6：添加到物料面板

在 `Material.ts` 文件的 `getMaterialPanelConfig()` 函数中添加组件到物料面板配置。

```typescript
import { MaterialCollapseTypeEnum } from "~@/types/MaterialPanelType";
import { WidgetType } from "./WidgetType";

export function getMaterialPanelConfig() {
  return [
    {
      name: MaterialCollapseTypeEnum.Common, // 通用组件分类
      widgetTypeList: [
        WidgetType.TestWidget,
        // WidgetType.YourWidget, // 你的新组件
      ],
    },
  ];
}
```

**分类说明：**

- `MaterialCollapseTypeEnum.Common`: 通用组件
- 其他分类可根据组件特性选择合适的分类

### 完整开发清单

开发新组件时，请按以下清单逐项完成：

- [ ] 步骤 1：在 `WidgetType.ts` 中添加枚举
- [ ] 步骤 2：创建 `widget/YourWidget.vue` 组件文件
- [ ] 步骤 3：创建 `widget-helper/YourWidgetHelper.ts` Helper 文件
- [ ] 步骤 4：在 `RegisterWidget.ts` 中注册组件
- [ ] 步骤 5：在 `RegisterWidgetHelper.ts` 中注册 Helper
- [ ] 步骤 6：在 `Material.ts` 中添加到物料面板配置

### 参考示例

完整示例可参考 `TestWidget` 组件：

- 组件实现：`widget/TestWidget.vue`
- Helper 配置：`widget-helper/TestWidgetHelper.ts`
- 类型定义：`WidgetType.TestWidget`
- 组件注册：`RegisterWidget.ts` 中的 `SYS_COMPS_MAP[WidgetType.TestWidget]`
- Helper 注册：`RegisterWidgetHelper.ts` 中的 `SYS_MOBILE_WIDGET_HELPERS`
- 物料配置：`Material.ts` 中的物料面板配置

## BaseField / Field 三种使用方式说明

移动端字段容器在实际业务中有三种典型用法，本节重点说明 **`BaseField` 与 Vant `Field` 的配置与使用模式**。

整体上可以分为三种模式：

- **模式一：基础模式（只用 BaseField，完全由 Schema 驱动）**
- **模式二：插槽扩展模式（在 BaseField 上增加自定义插槽）**
- **模式三：完全自定义模式（基于 useField + Vant Field 自行开发）**

下面分别说明三种模式的使用方式与适用场景。

### 模式一：基础模式（只用 BaseField，零插槽开发）

**示例代码：**

```vue
<script setup lang="ts">
import type { WidgetProps, WidgetSchema } from "~@/types/WidgetSchema";
import { computed, toRefs, useAttrs } from "vue";
import { usInitValueHook } from "~@/config/widget/utils/UseInitValueHook";
import { useCompEvent } from "~@/config/user-script/hooks/UseComp";
import BaseField from "../components/BaseField.vue";
import { useField } from "./hook/useField";

const props = defineProps<
  WidgetProps<WidgetSchema<any>> & {
    placeholder?: string;
  }
>();

const { schema, fieldPath, placeholder } = toRefs(props);
const attrs = useAttrs();
const { fieldProps, wrapperStyle, fieldSlots } = useField({
  schema,
  attrs,
  placeholder,
});

type ModelValue = string | undefined;
const value = defineModel<ModelValue>();
usInitValueHook(value, { schema, fieldPath });

const { handleBlur, handleFocus, handleValueChange } = useCompEvent(
  schema as any,
);

function setValue(nv: ModelValue) {
  value.value = nv;
  handleValueChange(nv);
}
</script>

<template>
  <BaseField
    v-bind="fieldProps"
    :style="wrapperStyle"
    :field-slots="fieldSlots"
    :model-value="value"
    @update:model-value="setValue"
    @focus="handleFocus"
    @blur="handleBlur"
  />
</template>
```

- **使用方式说明：**
  - 模板中直接使用 `BaseField`，传入由 `useField` 计算出的 `fieldProps` / `wrapperStyle` / `fieldSlots`；
  - 通过 `v-model` 和事件处理器完成双向绑定和事件派发；
  - `fieldProps` / `wrapperStyle` / `fieldSlots` 均由 `useField(schema, attrs, placeholder)` 等 Hook 计算而来。
- **字段配置来源：**
  - 标题、占位符、字数限制、校验规则、必填标记等，全部从 Schema（低码配置）中读取；
  - 开发者只需要通过 Helper 的 `buildSettings` / `buildWidget` 暴露字段配置即可。
- **适合场景：**
  - 只想快速用一个“通用输入组件”，只需要提供标准样式；

**总结：** 模式一中，`BaseField` 被看作“通用字段容器”，开发者只需要准备好 `fieldProps` / `fieldSlots`，绝大多数展示和行为由平台内置。

### 模式二：插槽扩展模式（BaseField + 自定义插槽）

**示例代码：**

```vue
<script setup lang="ts">
// ... script 部分与模式一相同，这里省略
</script>

<template>
  <BaseField
    v-bind="fieldProps"
    :style="wrapperStyle"
    :field-slots="fieldSlots"
    :model-value="value"
    @update:model-value="setValue"
    @focus="handleFocus"
    @blur="handleBlur"
  >
    <!-- 自定义标签区域 -->
    <template #label>
      <div class="custom-label">
        <span>自定义标签</span>
        <i class="help-icon" />
      </div>
    </template>

    <!-- 自定义左侧图标 -->
    <template #left-icon>
      <van-icon name="search" />
    </template>

    <!-- 自定义右侧图标 -->
    <template #right-icon>
      <van-icon name="clear" @click="handleClear" />
    </template>

    <!-- 自定义输入区域 -->
    <template #input>
      <input
        :value="value"
        @input="setValue(($event.target as HTMLInputElement).value)"
        class="custom-input"
      />
    </template>
  </BaseField>
</template>
```

- **使用方式说明：**
  - 继续使用 `BaseField` 作为外层容器，并保留基础属性和事件绑定；
  - 同时在 `<BaseField>` 内部编写插槽：
    - `#label`：自定义标签区域（可加入图标、说明、换行布局等）；
    - `#left-icon` / `#right-icon`：替换为自定义图标/按钮（如搜索图标、清空按钮等）；
    - `#input`：替换内部输入区域（可以是 `<input>`，也可以是更复杂的组合，如“区号 + 手机号”）。
- **与基础模式的关系：**
  - 仍然完全复用 BaseField 的：
    - 表单布局（label 区、内容区、错误提示等）；
    - 事件派发（focus / blur / valueChange）；
    - Schema 驱动的属性（`fieldProps` / `fieldSlots`）。
  - 只是把“局部渲染区域”交给业务组件来自定义。
- **适合人群/场景：**
  - 需要在标签上插入说明/图标，或改变标签的布局；
  - 需要在左右两侧放置单位、按钮、icon 等；
  - 需要对输入 DOM 做轻量改造，但又不希望重写整个 `Field` 逻辑。

**总结：** 模式二是在 **“不放弃 BaseField 能力”** 的前提下，通过插槽对部分区域进行增强，兼顾 **低码配置** 与 **少量编码定制**。

### 模式三：完全自定义模式（useField + Vant Field）

**示例代码：**

```vue
<script setup lang="ts">
import type { WidgetProps, WidgetSchema } from "~@/types/WidgetSchema";
import { Field } from "vant-cisdi";
import { toRefs, useAttrs } from "vue";
import { usInitValueHook } from "~@/config/widget/utils/UseInitValueHook";
import { useCompEvent } from "~@/config/user-script/hooks/UseComp";
import { useField } from "./hook/useField";

const props = defineProps<
  WidgetProps<WidgetSchema<any>> & {
    placeholder?: string;
  }
>();

const { schema, fieldPath, placeholder } = toRefs(props);
const attrs = useAttrs();
const { fieldProps, wrapperStyle, fieldSlots } = useField({
  schema,
  attrs,
  placeholder,
});

type ModelValue = string | undefined;
const value = defineModel<ModelValue>();
usInitValueHook(value, { schema, fieldPath });

const { handleBlur, handleFocus, handleValueChange } = useCompEvent(
  schema as any,
);
</script>

<template>
  <Field
    v-model="value"
    v-bind="fieldProps"
    :style="wrapperStyle"
    @update:model-value="handleValueChange"
    @focus="handleFocus"
    @blur="handleBlur"
  >
    <!-- 根据 fieldSlots 数据动态渲染标签 -->
    <template v-if="fieldSlots.hasLabelSlot" #label>
      <div
        v-if="fieldSlots.labelData?.value?.showLabel"
        class="van-field__label-wrapper"
      >
        <label :style="{ width: fieldSlots.labelData?.value?.labelWidth }">
          <span :style="fieldSlots.labelData?.value?.customLabelStyle">
            自定义 + {{ fieldSlots.labelData?.value?.label }}
          </span>
          <i
            v-if="fieldSlots.labelData?.value?.required"
            class="van-badge__wrapper van-icon__wrap mbicon mbicon-Required van-field__required-mark"
          />
        </label>
      </div>
    </template>

    <!-- 根据 fieldSlots 数据动态渲染左侧图标 -->
    <template v-if="fieldSlots.hasPrepend" #left-icon>
      {{ fieldSlots.prependContent }}
    </template>

    <!-- 根据 fieldSlots 数据动态渲染右侧图标 -->
    <template v-if="fieldSlots.hasAppend" #right-icon>
      {{ fieldSlots.appendContent }}
    </template>
  </Field>
</template>
```

- **使用方式说明：**
  - 不再使用 `BaseField`，直接使用 Vant 的 `Field` 组件：
    - `v-model="value"`：字段双向绑定；
    - `v-bind="fieldProps"`：透传由 `useField` 计算出的属性（如 placeholder、校验相关 props 等）；
    - `:style="wrapperStyle"`：应用统一样式；
    - `@update:model-value="handleValueChange"`、`@focus="handleFocus"`、`@blur="handleBlur"`：自行接入事件。
  - 使用 `fieldSlots` 提供的数据决定是否渲染 label / icon 等：
    - `fieldSlots.hasLabelSlot` + `fieldSlots.labelData?.value` 控制标签显隐、宽度、样式、必填星号等；
    - `fieldSlots.hasPrepend` / `fieldSlots.hasAppend` + 内容字段控制左右自定义区域。
- **与前两种模式的区别：**
  - 布局与 DOM 结构完全由业务组件掌控；
  - 只复用数据与配置层能力（`fieldProps` / `fieldSlots` / 事件 Hook），不复用 BaseField 的 UI 结构。
- **适合人群/场景：**
  - 对 DOM 结构、动画、样式有强定制需求；
  - 由前端开发者主导开发，低码配置主要提供字段元数据与校验规则；

**总结：** 模式三是 **“只拿 Schema & Hook，不拿默认 UI”** 的高级用法，保留低码平台的数据/事件体系，同时对视觉与交互做彻底自定义。

---

**建议实践：**

- 通用表单场景优先使用 **模式一（基础模式）**；
- 需要少量 UI 扩展时优先考虑 **模式二（插槽扩展模式）**；
- 仅在前两种模式无法满足需求时，再采用 **模式三（完全自定义模式）**，以控制维护成本。