imean-service-engine-htmx-plugin 2.2.0 → 2.3.1

package/docs/README.md

@@ -69,16 +69,30 @@
 
 **适合**: 需要创建复杂交互式表单组件的开发者
 
-### 🔧 [JSX + Alpine.js 最佳实践](./jsx-alpine-best-practices.md)
+### 🎯 [Alpine.js 交互式组件开发指南](./alpinejs-interactive-components.md)
 
-JSX 和 Alpine.js 结合使用指南，包含：
-- 问题分析
-- 渲染策略对比
-- 动态列表处理
-- 最佳实践总结
-- 注意事项
+Alpine.js 交互式组件开发指南，包含：
+- 核心设计原则
+- 完整的开发步骤
+- 数据同步机制
+- 完整示例（字符串数组编辑器、Banner 编辑器）
+- 关键要点和常见问题
+- 检查清单
+
+**适合**: 需要开发交互式表单字段渲染器的开发者
+
+### ✨ [Hono HTML 模板字符串最佳实践](./hono-html-best-practices.md)
+
+Hono `html` 模板字符串使用指南，包含：
+- 为什么使用 Hono `html` 模板字符串
+- 核心原则和最佳实践
+- `x-data` 属性的正确处理
+- JavaScript 字符串值的安全插入
+- 避免字符串拼接错误
+- 完整示例和常见错误解决方案
+- 检查清单
 
-**适合**: 需要深入理解 JSX 和 Alpine.js 结合使用的开发者
+**适合**: 开发自定义表单字段渲染器的开发者
 
 ## 文档使用建议
 

package/docs/alpinejs-interactive-components.md

@@ -0,0 +1,653 @@
+# Alpine.js 交互式组件开发指南
+
+本文档介绍如何在 HtmxAdminPlugin 中开发使用 Alpine.js 的交互式表单字段渲染器组件。
+
+## 概述
+
+Alpine.js 交互式组件用于创建复杂的表单字段，如：
+- 动态列表编辑器（字符串数组、对象数组等）
+- 对象编辑器（根据 Zod schema 自动渲染）
+- 其他需要客户端交互的复杂表单控件
+
+## 核心设计原则
+
+### 1. 使用 Hono `html` 模板字符串
+
+**始终使用 Hono 的 `html` 模板字符串生成所有 HTML**，避免字符串拼接：
+
+```typescript
+import { html } from "hono/html";
+
+export function MyComponent(props: MyComponentProps) {
+  return html`
+    <div class="container">
+      <input name="${props.fieldName}" value="${props.value}" />
+    </div>
+  `;
+}
+```
+
+**优势**：
+- 自动转义 HTML，避免 XSS 攻击
+- 类型检查和语法高亮
+- 代码清晰易读
+
+### 2. 状态管理由 Alpine.js 负责
+
+所有交互状态都应该在 Alpine.js 的 `x-data` 中管理：
+
+```typescript
+const xDataContent = `{
+  items: [],
+  init() {
+    // 初始化逻辑
+  },
+  addItem() {
+    // 添加项逻辑
+  },
+  removeItem(index) {
+    // 删除项逻辑
+  }
+}`;
+```
+
+### 3. 渲染由 Alpine.js 的 `x-for` 负责
+
+对于动态列表，使用 Alpine.js 的 `template` + `x-for` 进行渲染：
+
+```typescript
+return html`
+  <div x-data="${xDataContent}">
+    <template x-for="(item, index) in items" x-bind:key="index">
+      <div class="item">
+        <!-- 项内容 -->
+      </div>
+    </template>
+  </div>
+`;
+```
+
+## 开发步骤
+
+### 步骤 1：定义组件接口
+
+```typescript
+export interface MyComponentProps {
+  /** 字段定义 */
+  field: any;
+  /** 当前值（已解析） */
+  value: any;
+  /** 完整的初始数据 */
+  initialData?: any;
+  /** 字段名（用于更新隐藏字段） */
+  fieldName: string;
+  /** 其他自定义属性 */
+  placeholder?: string;
+}
+```
+
+### 步骤 2：准备初始数据
+
+```typescript
+export function MyComponent(props: MyComponentProps) {
+  const { value, fieldName, placeholder = "请输入" } = props;
+  
+  // 处理初始值
+  const initialItems: string[] = value || [];
+  const initialValueJson = JSON.stringify(initialItems);
+  
+  // ...
+}
+```
+
+### 步骤 3：构建 `x-data` 字符串
+
+```typescript
+const xDataContent = `{
+  items: ${initialValueJson},
+  fieldName: ${JSON.stringify(fieldName)},
+  placeholder: ${JSON.stringify(placeholder)},
+  init() {
+    const dataAttr = this.$el.getAttribute('data-initial-value');
+    if (dataAttr) {
+      try {
+        const parsed = JSON.parse(dataAttr);
+        if (Array.isArray(parsed)) {
+          this.items = parsed;
+        } else {
+          this.items = [];
+        }
+      } catch (e) {
+        console.error('Failed to parse initial value:', e);
+        this.items = [];
+      }
+    }
+    this.updateHiddenField();
+  },
+  updateHiddenField() {
+    const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
+    if (hiddenInput) {
+      hiddenInput.value = JSON.stringify(this.items);
+    }
+  },
+  addItem() {
+    this.items.push('');
+    this.updateHiddenField();
+  },
+  removeItem(index) {
+    this.items.splice(index, 1);
+    this.updateHiddenField();
+  },
+  updateItem(index, value) {
+    this.items[index] = value;
+    this.updateHiddenField();
+  }
+}`;
+```
+
+**关键点**：
+- 使用 `JSON.stringify` 安全地插入字符串值
+- 在 `init()` 中从 `data-initial-value` 属性读取初始值
+- 每次数据变更后调用 `updateHiddenField()` 同步到隐藏字段
+
+### 步骤 4：使用 `html` 模板字符串生成 HTML
+
+```typescript
+return html`
+  <div
+    x-data="${xDataContent}"
+    data-initial-value="${initialValueJson}"
+    x-init="init()"
+    class="space-y-3"
+  >
+    <input
+      type="hidden"
+      name="${fieldName}"
+      value=""
+      data-testid="hidden-${fieldName}"
+    />
+    <div class="space-y-3">
+      <!-- 组件内容 -->
+    </div>
+  </div>
+`;
+```
+
+**关键点**：
+- **不要使用 `raw()` 包装 `x-data`**：直接使用 `${xDataContent}`
+- 使用 `data-initial-value` 属性传递初始值
+- 使用 `x-init="init()"` 初始化组件
+
+### 步骤 5：实现动态列表渲染
+
+```typescript
+return html`
+  <div x-data="${xDataContent}" data-initial-value="${initialValueJson}" x-init="init()">
+    <div class="space-y-2" x-show="items.length > 0">
+      <template x-for="(item, index) in items" x-bind:key="index">
+        <div class="flex items-center gap-2">
+          <input
+            type="text"
+            x-bind:value="items[index] || ''"
+            x-on:input="updateItem(index, $event.target.value)"
+            x-bind:data-testid="fieldName + '-input-' + index"
+          />
+          <button
+            type="button"
+            x-on:click="removeItem(index)"
+            x-bind:data-testid="fieldName + '-remove-button-' + index"
+          >
+            删除
+          </button>
+        </div>
+      </template>
+    </div>
+  </div>
+`;
+```
+
+**关键点**：
+- 使用 `template` + `x-for` 进行动态渲染
+- 在 Alpine.js 表达式中使用字符串拼接：`fieldName + '-input-' + index`
+- 不要使用模板字符串：`` `${fieldName}-input-${index}` ``
+
+## 完整示例
+
+### 示例 1：字符串数组编辑器
+
+```typescript
+import { html } from "hono/html";
+
+export interface StringArrayEditorProps {
+  field: any;
+  value: string[] | null;
+  initialData?: any;
+  fieldName: string;
+  placeholder?: string;
+  allowEmpty?: boolean;
+}
+
+export function StringArrayEditor(props: StringArrayEditorProps) {
+  const {
+    value,
+    fieldName,
+    placeholder = "请输入内容",
+    allowEmpty = false,
+  } = props;
+  const initialItems: string[] = value || [];
+  const initialValueJson = JSON.stringify(initialItems);
+
+  const xDataContent = `{
+    items: ${initialValueJson},
+    fieldName: ${JSON.stringify(fieldName)},
+    placeholder: ${JSON.stringify(placeholder)},
+    allowEmpty: ${allowEmpty},
+    init() {
+      const dataAttr = this.$el.getAttribute('data-initial-value');
+      if (dataAttr) {
+        try {
+          const parsed = JSON.parse(dataAttr);
+          if (Array.isArray(parsed)) {
+            this.items = parsed;
+          } else {
+            this.items = [];
+          }
+        } catch (e) {
+          console.error('Failed to parse initial value:', e);
+          this.items = [];
+        }
+      }
+      this.updateHiddenField();
+    },
+    updateHiddenField() {
+      const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
+      if (hiddenInput) {
+        hiddenInput.value = JSON.stringify(this.items);
+      }
+    },
+    addItem() {
+      this.items.push('');
+      this.updateHiddenField();
+      this.$nextTick(() => {
+        const inputs = this.$el.querySelectorAll('input[data-testid*="-input-"]');
+        if (inputs.length > 0) {
+          const lastInput = inputs[inputs.length - 1];
+          if (lastInput && lastInput.focus) {
+            lastInput.focus();
+          }
+        }
+      });
+    },
+    removeItem(index) {
+      this.items.splice(index, 1);
+      this.updateHiddenField();
+    },
+    updateItem(index, value) {
+      this.items[index] = value;
+      this.updateHiddenField();
+    }
+  }`;
+
+  return html`
+    <div
+      x-data="${xDataContent}"
+      data-initial-value="${initialValueJson}"
+      x-init="init()"
+      class="space-y-3"
+    >
+      <input
+        type="hidden"
+        name="${fieldName}"
+        value=""
+        data-testid="hidden-${fieldName}"
+      />
+      <div class="space-y-3">
+        <div class="flex items-center justify-between">
+          <span class="text-sm text-gray-600">
+            共 <span x-text="items.length">0</span> 项
+          </span>
+          <button
+            type="button"
+            x-on:click="addItem()"
+            class="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors text-sm font-medium"
+            data-testid="${fieldName}-add-button"
+          >
+            添加项
+          </button>
+        </div>
+
+        <div class="space-y-2" x-show="items.length > 0">
+          <template x-for="(item, index) in items" x-bind:key="index">
+            <div class="flex items-center gap-2">
+              <input
+                type="text"
+                x-bind:value="items[index] || ''"
+                x-on:input="updateItem(index, $event.target.value)"
+                x-bind:placeholder="placeholder + ' ' + (index + 1)"
+                class="flex-1 px-3 py-2 border border-gray-300 rounded-lg text-sm"
+                x-bind:data-testid="fieldName + '-input-' + index"
+                x-bind:required="!allowEmpty"
+              />
+              <button
+                type="button"
+                x-on:click="removeItem(index)"
+                class="px-3 py-2 text-sm text-red-600 hover:bg-red-50 rounded-lg"
+                x-bind:data-testid="fieldName + '-remove-button-' + index"
+              >
+                删除
+              </button>
+            </div>
+          </template>
+        </div>
+
+        <div
+          x-show="items.length === 0"
+          class="text-center py-8 text-gray-400 text-sm border border-dashed border-gray-300 rounded-lg"
+        >
+          暂无项，点击"添加项"按钮添加
+        </div>
+      </div>
+    </div>
+  `;
+}
+```
+
+### 示例 2：对象数组编辑器（Banner 编辑器）
+
+```typescript
+import { html } from "hono/html";
+
+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 initialValueJson = JSON.stringify(initialBanners);
+
+  const xDataContent = `{
+    banners: ${initialValueJson},
+    fieldName: ${JSON.stringify(fieldName)},
+    init() {
+      const dataAttr = this.$el.getAttribute('data-initial-value');
+      if (dataAttr) {
+        try {
+          const parsed = JSON.parse(dataAttr);
+          if (Array.isArray(parsed)) {
+            this.banners = parsed;
+          } else {
+            this.banners = [];
+          }
+        } catch (e) {
+          console.error('Failed to parse initial value:', e);
+          this.banners = [];
+        }
+      }
+      this.updateHiddenField();
+    },
+    updateHiddenField() {
+      const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
+      if (hiddenInput) {
+        hiddenInput.value = JSON.stringify(this.banners);
+      }
+    },
+    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();
+    }
+  }`;
+
+  return html`
+    <div
+      x-data="${xDataContent}"
+      data-initial-value="${initialValueJson}"
+      x-init="init()"
+      class="space-y-4"
+    >
+      <input
+        type="hidden"
+        name="${fieldName}"
+        value=""
+        data-testid="hidden-${fieldName}"
+      />
+      <div class="flex items-center justify-between">
+        <span class="text-sm text-gray-600">
+          共 <span x-text="banners.length">0</span> 个 Banner
+        </span>
+        <button
+          type="button"
+          x-on:click="addBanner()"
+          class="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors text-sm font-medium"
+          data-testid="${fieldName}-add-button"
+        >
+          + 添加 Banner
+        </button>
+      </div>
+
+      <div class="space-y-4" x-show="banners.length > 0">
+        <template x-for="(banner, index) in banners" x-bind:key="index">
+          <div
+            class="border border-gray-200 rounded-lg p-4 space-y-3 bg-white"
+            x-bind:data-testid="fieldName + '-item-' + index"
+          >
+            <div class="flex items-center justify-between">
+              <span class="text-sm font-semibold text-gray-700">
+                Banner <span x-text="index + 1"></span>
+              </span>
+              <button
+                type="button"
+                x-on:click="removeBanner(index)"
+                class="px-3 py-1 text-sm text-red-600 hover:bg-red-50 rounded transition-colors"
+                x-bind:data-testid="fieldName + '-remove-button-' + index"
+              >
+                删除
+              </button>
+            </div>
+
+            <div class="grid grid-cols-1 gap-3">
+              <div>
+                <label class="block text-xs font-medium text-gray-700 mb-1">
+                  图片地址 <span class="text-red-500">*</span>
+                </label>
+                <input
+                  type="url"
+                  x-model="banner.url"
+                  placeholder="https://example.com/image.jpg"
+                  required
+                  class="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                  x-bind:data-testid="fieldName + '-url-' + index"
+                />
+              </div>
+
+              <div>
+                <label class="block text-xs font-medium text-gray-700 mb-1">
+                  图片描述 <span class="text-red-500">*</span>
+                </label>
+                <input
+                  type="text"
+                  x-model="banner.alt"
+                  placeholder="图片描述"
+                  required
+                  class="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                  x-bind:data-testid="fieldName + '-alt-' + index"
+                />
+              </div>
+
+              <div>
+                <label class="block text-xs font-medium text-gray-700 mb-1">
+                  排序
+                </label>
+                <input
+                  type="number"
+                  x-model.number="banner.order"
+                  min="0"
+                  class="w-full px-3 py-2 border border-gray-300 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                  x-bind:data-testid="fieldName + '-order-' + index"
+                />
+              </div>
+            </div>
+
+            <div x-show="banner.url" class="mt-3">
+              <label class="block text-xs font-medium text-gray-700 mb-1">
+                预览
+              </label>
+              <div class="border border-gray-200 rounded-lg overflow-hidden">
+                <img
+                  x-bind:src="banner.url"
+                  x-bind:alt="banner.alt"
+                  class="w-full h-32 object-cover"
+                  onerror="this.style.display='none'"
+                />
+              </div>
+            </div>
+          </div>
+        </template>
+      </div>
+
+      <div
+        x-show="banners.length === 0"
+        class="text-center py-8 text-gray-400 text-sm border border-dashed border-gray-300 rounded-lg"
+      >
+        暂无 Banner，点击"添加 Banner"按钮添加
+      </div>
+    </div>
+  `;
+}
+```
+
+## 关键要点
+
+### 1. `x-data` 属性的处理
+
+**❌ 错误**：使用 `raw()` 包装
+```typescript
+import { html, raw } from "hono/html";
+return html`<div x-data='${raw(xDataContent)}'>...</div>`;
+```
+
+**✅ 正确**：直接使用
+```typescript
+import { html } from "hono/html";
+return html`<div x-data="${xDataContent}">...</div>`;
+```
+
+### 2. JavaScript 字符串值的安全插入
+
+使用 `JSON.stringify` 插入字符串值：
+
+```typescript
+const xDataContent = `{
+  fieldName: ${JSON.stringify(fieldName)},
+  placeholder: ${JSON.stringify(placeholder)},
+  items: ${JSON.stringify(initialItems)}
+}`;
+```
+
+### 3. Alpine.js 表达式中的字符串拼接
+
+在 Alpine.js 表达式中（如 `x-bind:data-testid`），使用字符串拼接：
+
+**❌ 错误**：
+```typescript
+x-bind:data-testid="`${fieldName}-item-${index}`"
+```
+
+**✅ 正确**：
+```typescript
+x-bind:data-testid="fieldName + '-item-' + index"
+```
+
+### 4. 数据同步机制
+
+每次数据变更后，必须调用 `updateHiddenField()` 同步到隐藏字段：
+
+```typescript
+updateItem(index, value) {
+  this.items[index] = value;
+  this.updateHiddenField(); // 必须调用
+}
+```
+
+### 5. 初始值处理
+
+在 `init()` 方法中从 `data-initial-value` 属性读取初始值：
+
+```typescript
+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();
+}
+```
+
+## 常见问题
+
+### Q: 为什么不能使用 `raw()` 包装 `x-data`？
+
+A: Hono 会自动转义 HTML 属性值，使用 `raw()` 会破坏转义机制，可能导致 JavaScript 语法错误。
+
+### Q: 为什么在 Alpine.js 表达式中不能使用模板字符串？
+
+A: Alpine.js 表达式是 JavaScript 代码，模板字符串在运行时可能无法正确解析。使用字符串拼接更可靠。
+
+### Q: 如何确保数据正确回填？
+
+A: 
+1. 在 `init()` 中从 `data-initial-value` 读取初始值
+2. 确保初始值格式正确（使用 `JSON.stringify`）
+3. 在 `x-data` 中提供默认值
+
+### Q: 如何调试 Alpine.js 组件？
+
+A:
+1. 在浏览器控制台检查 `x-data` 是否正确设置
+2. 检查 `data-initial-value` 属性的值
+3. 在 `init()` 方法中添加 `console.log` 调试
+4. 使用 Alpine.js DevTools（如果可用）
+
+## 检查清单
+
+开发 Alpine.js 交互式组件时，确保：
+
+- [ ] 使用 `html` 模板字符串生成所有 HTML
+- [ ] 不在 `x-data` 属性上使用 `raw()`
+- [ ] 在 `x-data` 中使用 `JSON.stringify` 插入字符串值
+- [ ] 在 `init()` 中从 `data-initial-value` 读取初始值
+- [ ] 每次数据变更后调用 `updateHiddenField()`
+- [ ] 使用 `template` + `x-for` 进行动态列表渲染
+- [ ] 在 Alpine.js 表达式中使用字符串拼接
+- [ ] 为所有交互元素添加 `data-testid` 属性
+- [ ] 处理空状态和错误情况
+
+## 相关文档
+
+- [Hono HTML 模板字符串最佳实践](./hono-html-best-practices.md) - 详细的 `html` 模板字符串使用指南
+- [自定义表单字段渲染器](./custom-form-field-renderers.md) - 表单字段渲染器的设计原则和接口说明