imean-service-engine-htmx-plugin 2.4.0 → 2.6.0

package/docs/custom-form-field-renderers.md

@@ -1,541 +0,0 @@
-# 自定义表单字段渲染器开发指南
-
-## 概述
-
-自定义表单字段渲染器允许您为复杂的表单字段创建交互式编辑组件。这些组件使用 Alpine.js 管理内部状态，并通过隐藏字段与表单系统同步数据。
-
-**推荐使用工具函数**：我们提供了 `createFormFieldXData` 和 `FormFieldWrapper` 工具函数，可以大大简化开发工作，减少样板代码。详见[使用工具函数](#方式-1使用工具函数推荐)部分。
-
-## 设计原则
-
-### 1. 组件自包含
-
-**核心原则**：自定义组件应该完全自包含，包括：
-- 自己的状态管理（Alpine.js）
-- 自己的隐藏字段（用于表单提交）
-- 自己的 UI 交互逻辑
-
-**为什么？**
-- **可复用性**：组件可以在任何地方使用，不依赖外部结构
-- **解耦**：不依赖 `form-page.tsx` 的 DOM 结构
-- **职责清晰**：组件负责自己的数据提交
-
-### 2. 状态管理分离
-
-- **Alpine.js**：管理组件的交互状态（如列表项、输入值等）
-- **隐藏字段**：同步状态到表单系统，用于提交
-
-### 3. 数据流向
-
-```
-用户操作 → Alpine.js 状态更新 → 更新隐藏字段 → 表单提交
-```
-
-## 组件接口
-
-### FormFieldRendererProps
-
-```typescript
-export interface FormFieldRendererProps<T = any> {
-  /** 字段定义 */
-  field: FormField;
-  /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
-  value: any;
-  /** 完整的初始数据 */
-  initialData?: Partial<T>;
-  /** 字段名（用于更新隐藏字段） */
-  fieldName: string;
-}
-```
-
-### 属性说明
-
-- **`field`**：字段的元数据（标签、类型、是否必填等）
-- **`value`**：当前字段的值，已经解析为 JavaScript 对象/数组（不是 JSON 字符串）
-- **`initialData`**：完整的表单初始数据（可用于访问其他字段的值）
-- **`fieldName`**：字段名，用于创建隐藏字段的 `name` 属性
-
-## 基本结构
-
-### 方式 1：使用工具函数（推荐）
-
-使用 `createFormFieldXData` 和 `FormFieldWrapper` 工具函数，可以大大简化代码：
-
-```tsx
-import { createFormFieldXData, FormFieldWrapper } from "../../src/utils/form-field-xdata";
-
-interface MyComponentProps {
-  field: any;
-  value: any;
-  initialData?: any;
-  fieldName: string;
-}
-
-export function MyComponent(props: MyComponentProps) {
-  const { value, fieldName } = props;
-  const initialValue = value || [];
-
-  // 使用工具函数创建 x-data
-  const xData = createFormFieldXData({
-    fieldName,
-    dataKey: "items",
-    defaultValue: [],
-    customMethods: {
-      "addItem()": `{
-        this.items.push({ name: '', value: '' });
-        this.updateHiddenField();
-      }`,
-      "removeItem(index)": `{
-        this.items.splice(index, 1);
-        this.updateHiddenField();
-      }`,
-    },
-  });
-
-  // 使用 FormFieldWrapper 包装组件
-  return (
-    <FormFieldWrapper
-      fieldName={fieldName}
-      initialValue={initialValue}
-      xData={xData}
-      autoSync={true}
-    >
-      {/* 组件 UI */}
-      {/* ... */}
-    </FormFieldWrapper>
-  );
-}
-```
-
-### 方式 2：手动编写（高级用法）
-
-如果需要更多控制，也可以手动编写：
-
-```tsx
-interface MyComponentProps {
-  field: any;
-  value: any;
-  initialData?: any;
-  fieldName: string;
-}
-
-export function MyComponent(props: MyComponentProps) {
-  const { value, fieldName } = props;
-  
-  // 1. 准备初始值
-  const initialValue = value || [];
-  const initialValueJson = JSON.stringify(initialValue);
-  
-  // 2. 定义 Alpine.js 数据和方法
-  const xData = `
-  {
-    items: [],
-    init() {
-      // 从 data 属性读取初始值
-      const dataAttr = this.$el.getAttribute('data-initial-value');
-      if (dataAttr) {
-        this.items = JSON.parse(dataAttr);
-      }
-      this.updateHiddenField();
-    },
-    updateHiddenField() {
-      // 更新隐藏字段
-      const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
-      if (hiddenInput) {
-        hiddenInput.value = JSON.stringify(this.items);
-      }
-    }
-  }`;
-  
-  // 3. 返回 JSX
-  return (
-    <div
-      x-data={xData}
-      data-initial-value={initialValueJson}
-      x-init="init()"
-    >
-      {/* 隐藏字段 */}
-      <input
-        type="hidden"
-        name={fieldName}
-        value=""
-        data-testid={`hidden-${fieldName}`}
-      />
-      
-      {/* 组件 UI */}
-      {/* ... */}
-    </div>
-  );
-}
-```
-
-### 2. 关键要素
-
-#### 隐藏字段
-
-```tsx
-<input
-  type="hidden"
-  name={fieldName}  // 必须与字段名一致
-  value=""
-  data-testid={`hidden-${fieldName}`}
-/>
-```
-
-**重要**：
-- 隐藏字段必须在 `x-data` 的根元素内
-- `name` 属性必须与 `fieldName` 一致
-- 初始 `value` 可以为空字符串，Alpine.js 会在初始化时更新
-
-#### Alpine.js 数据初始化
-
-```tsx
-const xData = `
-{
-  items: [],
-  init() {
-    // 从 data 属性读取初始值
-    const dataAttr = this.$el.getAttribute('data-initial-value');
-    if (dataAttr) {
-      this.items = JSON.parse(dataAttr);
-    }
-    // 初始化后立即更新隐藏字段
-    this.updateHiddenField();
-  },
-  // ... 其他方法
-}`;
-```
-
-**为什么使用 `data-initial-value`？**
-- 避免在模板字符串中嵌入 JSON（可能有转义问题）
-- 更清晰的数据传递方式
-- 便于调试
-
-#### 状态同步
-
-```tsx
-updateHiddenField() {
-  // 使用 this.$el 限定作用域，避免选择器冲突
-  const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
-  if (hiddenInput) {
-    hiddenInput.value = JSON.stringify(this.items);
-  }
-}
-```
-
-**关键点**：
-- 使用 `this.$el.querySelector` 而不是 `document.querySelector`，限定在组件作用域内
-- 每次状态变更后都要调用 `updateHiddenField()`
-- 使用 `JSON.stringify` 将状态序列化为字符串
-
-## 完整示例：Banner 编辑器
-
-```tsx
-/**
- * Banner 编辑器组件
- * 使用 Alpine.js 管理状态，支持动态添加/删除/排序
- */
-
-interface Banner {
-  url: string;
-  alt: string;
-  order: number;
-}
-
-interface BannerEditorProps {
-  field: any;
-  value: Banner[] | null;
-  initialData?: any;
-  fieldName: string;
-}
-
-export function BannerEditor(props: BannerEditorProps) {
-  const { value, fieldName } = props;
-  const initialBanners: Banner[] = value || [];
-  const bannersJson = JSON.stringify(initialBanners);
-
-  const xData = `
-{
-  banners: [],
-  init() {
-    const dataAttr = this.$el.getAttribute('data-initial-value');
-    if (dataAttr) {
-      this.banners = JSON.parse(dataAttr);
-    }
-    this.updateHiddenField();
-  },
-  addBanner() {
-    this.banners.push({
-      url: '',
-      alt: '',
-      order: this.banners.length
-    });
-    this.updateHiddenField();
-  },
-  removeBanner(index) {
-    this.banners.splice(index, 1);
-    // 重新排序
-    this.banners.forEach((banner, i) => {
-      banner.order = i;
-    });
-    this.updateHiddenField();
-  },
-  updateBanner(index, field, value) {
-    this.banners[index][field] = value;
-    this.updateHiddenField();
-  },
-  updateHiddenField() {
-    const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
-    if (hiddenInput) {
-      hiddenInput.value = JSON.stringify(this.banners);
-    }
-  }
-}`;
-
-  return (
-    <div
-      x-data={xData}
-      data-initial-value={bannersJson}
-      x-init="init()"
-      x-effect="updateHiddenField()"
-      className="space-y-4"
-    >
-      {/* 隐藏字段，由组件自己维护 */}
-      <input
-        type="hidden"
-        name={fieldName}
-        value=""
-        data-testid={`hidden-${fieldName}`}
-      />
-      
-      <div className="flex items-center justify-between">
-        <span className="text-sm text-gray-600">
-          共 <span x-text="banners.length">0</span> 个 Banner
-        </span>
-        <button
-          type="button"
-          x-on:click="addBanner()"
-          className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
-          data-testid={`${fieldName}-add-button`}
-        >
-          + 添加 Banner
-        </button>
-      </div>
-
-      {/* 使用 Alpine.js 的 x-for 动态渲染列表 */}
-      <div className="space-y-4" x-show="banners.length > 0">
-        <template x-for="(banner, index) in banners">
-          <div className="border border-gray-200 rounded-lg p-4 space-y-3 bg-white">
-            <div className="flex items-center justify-between">
-              <span className="text-sm font-semibold text-gray-700">
-                Banner <span x-text="index + 1"></span>
-              </span>
-              <button
-                type="button"
-                x-on:click="removeBanner(index)"
-                className="px-3 py-1 text-sm text-red-600 hover:bg-red-50 rounded"
-              >
-                删除
-              </button>
-            </div>
-
-            <div className="grid grid-cols-1 gap-3">
-              <div>
-                <label className="block text-xs font-medium text-gray-700 mb-1">
-                  图片地址 <span className="text-red-500">*</span>
-                </label>
-                <input
-                  type="url"
-                  x-model="banner.url"
-                  placeholder="https://example.com/image.jpg"
-                  required
-                  className="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm"
-                />
-              </div>
-
-              <div>
-                <label className="block text-xs font-medium text-gray-700 mb-1">
-                  图片描述 <span className="text-red-500">*</span>
-                </label>
-                <input
-                  type="text"
-                  x-model="banner.alt"
-                  placeholder="图片描述"
-                  required
-                  className="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm"
-                />
-              </div>
-            </div>
-          </div>
-        </template>
-      </div>
-
-      <div
-        x-show="banners.length === 0"
-        className="text-center py-8 text-gray-400 text-sm border border-dashed border-gray-300 rounded-lg"
-      >
-        暂无 Banner，点击"添加 Banner"按钮添加
-      </div>
-    </div>
-  );
-}
-```
-
-## 在 Feature 中注册
-
-```typescript
-// examples-v2/pages/destination-page.tsx
-import { BannerEditor } from "../components/banner-editor";
-
-export class DestinationPageModel extends PageModel {
-  constructor() {
-    super("destinations", DestinationSchema);
-    
-    this.features.create(
-      new DefaultCreateFeature({
-        permissionPrefix: "destinations",
-        createItem: destinationService.createDestination,
-        formFieldRenderers: {
-          banners: (props) => {
-            return <BannerEditor {...props} />;
-          },
-        },
-      })
-    );
-    
-    this.features.edit(
-      new DefaultEditFeature({
-        permissionPrefix: "destinations",
-        getItem: destinationService.getDestination,
-        updateItem: destinationService.updateDestination,
-        formFieldRenderers: {
-          banners: (props) => {
-            return <BannerEditor {...props} />;
-          },
-        },
-      })
-    );
-  }
-}
-```
-
-## 最佳实践
-
-### 1. 使用 `x-effect` 自动同步
-
-对于复杂的状态变更，使用 `x-effect` 自动同步：
-
-```tsx
-<div
-  x-data={xData}
-  x-effect="updateHiddenField()"  // 状态变更时自动调用
->
-```
-
-**注意**：`x-effect` 会在每次状态变更时触发，对于频繁更新的场景，可能需要防抖。
-
-### 2. 动态列表使用 `template` + `x-for`
-
-```tsx
-<template x-for="(item, index) in items">
-  <div>
-    {/* 列表项内容 */}
-  </div>
-</template>
-```
-
-**为什么？**
-- Alpine.js 完全控制渲染
-- 支持动态添加/删除，无数量限制
-- 符合 Alpine.js 最佳实践
-
-### 3. 使用 `x-bind` 动态属性
-
-```tsx
-<div x-bind:data-testid="`item-${index}`">
-  {/* 使用模板字符串 */}
-</div>
-```
-
-### 4. 测试属性
-
-为所有交互元素添加 `data-testid`：
-
-```tsx
-<button
-  x-on:click="addItem()"
-  data-testid={`${fieldName}-add-button`}
->
-  添加
-</button>
-```
-
-### 5. 错误处理
-
-```tsx
-init() {
-  const dataAttr = this.$el.getAttribute('data-initial-value');
-  if (dataAttr) {
-    try {
-      this.items = JSON.parse(dataAttr);
-    } catch (e) {
-      console.error('Failed to parse initial value:', e);
-      this.items = [];
-    }
-  }
-  this.updateHiddenField();
-}
-```
-
-## 常见问题
-
-### Q1: 为什么隐藏字段在组件内部？
-
-**A**: 组件应该自包含，不依赖外部结构。隐藏字段是组件的一部分，应该由组件自己维护。
-
-### Q2: 为什么使用 `this.$el.querySelector` 而不是 `document.querySelector`？
-
-**A**: `this.$el` 限定在组件作用域内，避免选择器冲突。如果页面上有多个相同组件，每个组件都能找到自己对应的隐藏字段。
-
-### Q3: 为什么使用 `data-initial-value` 而不是直接在 `x-data` 中嵌入？
-
-**A**: 
-- 避免 JSON 转义问题
-- 更清晰的数据传递方式
-- 便于调试（可以在 DOM 中直接查看）
-
-### Q4: 什么时候使用 `x-effect`？
-
-**A**: 
-- 简单场景：在方法中手动调用 `updateHiddenField()`
-- 复杂场景：使用 `x-effect="updateHiddenField()"` 自动同步
-
-**注意**：`x-effect` 会在每次状态变更时触发，对于频繁更新的场景，可能需要防抖。
-
-### Q5: 如何处理表单验证？
-
-**A**: 
-- HTML5 验证：在输入元素上使用 `required`、`pattern` 等属性
-- 自定义验证：在 `updateHiddenField()` 中检查数据有效性
-- 提交时验证：由后端 Zod schema 验证
-
-### Q6: 如何访问其他字段的值？
-
-**A**: 通过 `initialData` 参数：
-
-```tsx
-export function MyComponent(props: MyComponentProps) {
-  const { value, initialData, fieldName } = props;
-  
-  // 访问其他字段
-  const otherFieldValue = initialData?.otherField;
-  
-  // ...
-}
-```
-
-## 参考资源
-
-- [JSX + Alpine.js 最佳实践](./jsx-alpine-best-practices.md) - JSX 和 Alpine.js 结合使用的详细指南
-- [Alpine.js 文档](https://alpinejs.dev/) - Alpine.js 官方文档
-- [BannerEditor 示例](../../examples-v2/components/banner-editor.tsx) - 完整的实现示例