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

package/docs/field-editor-best-practices.md

@@ -0,0 +1,320 @@
+# FieldEditor 开发最佳实践
+
+本文档旨在指导开发者如何正确开发和使用 FieldEditor 系列组件（如 `TagsEditor`、`StringArrayEditor`、`BannerEditor` 等）。
+
+## 核心设计原则
+
+### 1. 交互式输入控件不使用 `name` 属性
+
+**原则**：所有用于组件内部交互的输入控件（如添加、编辑）**不应该**使用 `name` 属性。
+
+**原因**：
+- FieldEditor 组件作为表单字段的编辑器，嵌套在通用表单中
+- 如果交互式输入控件设置了 `name`，会在表单提交时被后端接收
+- 通用表单难以排除这些临时交互字段
+- 使用 `hx-vals` 可以精确控制发送的参数，不影响表单提交
+
+**正确示例**：
+
+```tsx
+// ✅ 正确：使用 hx-vals 传递参数，不使用 name
+<input
+  type="text"
+  id={inputId}
+  hx-vals="js:{tagValue:this.value}"
+  hx-post={ctx.url("addTag", { fieldName, index: Date.now() })}
+  hx-trigger="keydown[key=='Enter']"
+/>
+
+// ❌ 错误：交互式输入控件使用 name
+<input
+  type="text"
+  name="tagValue"  // 这会在表单提交时被发送
+  hx-post={ctx.url("addTag")}
+/>
+```
+
+### 2. 表单提交数据使用隐藏字段
+
+**原则**：真正需要提交到后端的数据，使用 `hidden` 类型的 `input` 元素，并设置正确的 `name` 属性。
+
+**数组字段命名规范**：
+- 字符串数组：`${fieldName}[${index}]`
+- 对象数组：`${fieldName}[${index}].propertyName`
+- 参考 `form-data-processor.ts` 的解析规则
+
+**正确示例**：
+
+```tsx
+// ✅ 正确：使用 hidden input 存储表单数据
+<div data-tag-item>
+  <span>{value}</span>
+  <input 
+    type="hidden" 
+    name={`${fieldName}[${index}]`} 
+    value={value} 
+  />
+</div>
+
+// ✅ 正确：对象数组字段
+<div data-banner-item>
+  <input type="hidden" name={`${fieldName}[${index}].url`} value={banner.url} />
+  <input type="hidden" name={`${fieldName}[${index}].alt`} value={banner.alt} />
+  <input type="hidden" name={`${fieldName}[${index}].order`} value={banner.order} />
+</div>
+```
+
+### 3. 索引管理策略
+
+**原则**：
+- **初始渲染**：使用真实索引（0, 1, 2, ...），便于回填和验证
+- **动态添加**：使用时间戳作为索引（`Date.now()`），确保唯一且不连续
+- **优势**：`form-data-processor` 会自动压缩不连续的数组索引
+
+**实现示例**：
+
+```tsx
+// 初始渲染：使用真实索引
+{tags.map((tag, index) => (
+  <div key={index}>
+    {this.renderTag(ctx, fieldName, tag, index, false)}
+  </div>
+))}
+
+// 动态添加：使用时间戳
+hx-post={ctx.url("addTag", { 
+  fieldName, 
+  index: Date.now(),  // 使用时间戳确保唯一
+  // ...
+})}
+```
+
+### 4. OOB 交换的正确用法
+
+**原则**：
+- 使用 `hx-swap-oob="morph"` 而不是 `hx-swap-oob="true"`
+- 不要包裹多余的层级，保持 DOM 结构一致
+- 在 OOB 交换时设置 `value=""` 来置空输入框
+
+**正确示例**：
+
+```tsx
+// ✅ 正确：直接返回 input 元素，使用 morph 交换
+private renderAddInput(ctx, fieldName, inputId, tagsContainerId, isOob = false) {
+  return (
+    <input
+      type="text"
+      id={inputId}
+      value=""
+      hx-vals="js:{tagValue:this.value}"
+      {...(isOob ? { "hx-swap-oob": "morph" } : {})}
+      // ... 其他属性
+    />
+  );
+}
+
+// ❌ 错误：包裹多余的 div
+<div hx-swap-oob="true" id={inputId}>
+  <input type="text" id={inputId} />
+</div>
+```
+
+### 5. 纯 HTMX 实现，避免 JavaScript
+
+**原则**：
+- 尽量使用 HTMX 的原生功能（`hx-post`、`hx-get`、`hx-trigger` 等）
+- 使用内联 JavaScript 表达式（`hx-vals="js:{...}"`、`hx-on:click="..."`）
+- 避免使用 Alpine.js 和全局 script 代码块
+- 仅在必要时使用少量 JavaScript（如空状态更新）
+
+**正确示例**：
+
+```tsx
+// ✅ 正确：使用 HTMX 原生功能
+<input
+  hx-post={ctx.url("addTag", { fieldName, index: Date.now() })}
+  hx-target={`#${tagsContainerId}`}
+  hx-swap="beforeend"
+  hx-trigger="keydown[key=='Enter']"
+  hx-vals="js:{tagValue:this.value}"
+/>
+
+// ✅ 正确：使用内联 JavaScript 处理简单逻辑
+<button
+  {...({
+    "hx-on:click": `htmx.closest(this, '[data-tag-item]').remove(); updateTagsEmptyState('${ctx.instanceId}')`,
+  } as any)}
+>
+  删除
+</button>
+```
+
+## 组件结构规范
+
+### 方法职责划分
+
+1. **`@Method` 装饰的方法**：
+   - 处理 HTMX 请求
+   - 验证输入数据
+   - 返回 HTML 片段（用于 HTMX 交换）
+
+2. **`render*` 私有方法**：
+   - 渲染可复用的 UI 片段
+   - 不处理业务逻辑
+   - 接收 `RenderContext` 或 `ComponentContext`
+
+3. **`render` 保护方法**：
+   - 组件的入口渲染方法
+   - 初始化组件结构
+   - 调用其他 `render*` 方法
+
+### 错误处理
+
+**原则**：错误应该通过 HTMX 响应返回，而不是静默失败。
+
+**正确示例**：
+
+```tsx
+@Method({ method: "post" })
+async addTag(context: ComponentContext) {
+  const tagValue = String(body.tagValue || "").trim();
+  
+  if (!tagValue) {
+    // ✅ 正确：返回错误提示（使用 OOB 交换）
+    return (
+      <div
+        className="text-red-600 text-sm p-2"
+        hx-swap-oob="true"
+        id={`${inputId}-error`}
+      >
+        标签不能为空
+      </div>
+    );
+  }
+  
+  // 成功时返回新标签项
+  return this.renderTag(context, fieldName, tagValue, index, false);
+}
+```
+
+## 表单数据格式
+
+### 数组字段格式
+
+根据 `form-data-processor.ts` 的解析规则，数组字段应该使用以下格式：
+
+1. **字符串数组**：
+   ```
+   tags[0] = "标签1"
+   tags[1] = "标签2"
+   tags[100] = "标签3"  // 不连续索引会被自动压缩
+   ```
+
+2. **对象数组**：
+   ```
+   banners[0].url = "https://example.com/1.jpg"
+   banners[0].alt = "图片1"
+   banners[0].order = 0
+   banners[100].url = "https://example.com/2.jpg"
+   banners[100].alt = "图片2"
+   banners[100].order = 1
+   ```
+
+### Hidden 字段的位置
+
+**原则**：Hidden 字段应该放在对应的数据项容器内，确保删除项时一起删除。
+
+**正确示例**：
+
+```tsx
+<div data-tag-item>
+  <span>{value}</span>
+  <input type="hidden" name={`${fieldName}[${index}]`} value={value} />
+  <button hx-on:click="...">删除</button>
+</div>
+```
+
+## 代码审查清单
+
+在开发或审查 FieldEditor 组件时，请检查：
+
+- [ ] 交互式输入控件是否使用了 `hx-vals` 而不是 `name`？
+- [ ] 表单提交数据是否使用 `hidden` input 并设置了正确的 `name`？
+- [ ] 初始渲染是否使用真实索引，动态添加是否使用时间戳？
+- [ ] OOB 交换是否使用 `morph` 而不是 `true`？
+- [ ] OOB 交换是否没有包裹多余的层级？
+- [ ] 是否尽量使用 HTMX 原生功能，避免 JavaScript？
+- [ ] 错误处理是否通过 HTMX 响应返回？
+- [ ] 删除操作后是否更新了空状态显示？
+- [ ] Hidden 字段是否放在对应的数据项容器内？
+
+## 参考实现
+
+- `TagsEditor`：标签编辑器，字符串数组
+- `StringArrayEditor`：字符串数组编辑器
+- `BannerEditor`：Banner 编辑器，对象数组
+
+## 常见错误
+
+### ❌ 错误 1：交互式输入控件使用 name
+
+```tsx
+// ❌ 错误
+<input name="tagValue" hx-post={ctx.url("addTag")} />
+```
+
+**问题**：会在表单提交时被发送，干扰表单数据。
+
+**修复**：
+```tsx
+// ✅ 正确
+<input hx-vals="js:{tagValue:this.value}" hx-post={ctx.url("addTag")} />
+```
+
+### ❌ 错误 2：OOB 交换使用 true 并包裹 div
+
+```tsx
+// ❌ 错误
+<div hx-swap-oob="true" id={inputId}>
+  <input type="text" id={inputId} />
+</div>
+```
+
+**问题**：会导致焦点丢失，DOM 结构不一致。
+
+**修复**：
+```tsx
+// ✅ 正确
+<input
+  type="text"
+  id={inputId}
+  hx-swap-oob="morph"
+  value=""
+/>
+```
+
+### ❌ 错误 3：编辑输入框使用 name
+
+```tsx
+// ❌ 错误
+<input name="newValue" hx-post={ctx.url("updateTag")} />
+```
+
+**问题**：会在表单提交时被发送。
+
+**修复**：
+```tsx
+// ✅ 正确
+<input hx-vals="js:{newValue:this.value}" hx-post={ctx.url("updateTag")} />
+```
+
+## 总结
+
+FieldEditor 组件的核心是：
+1. **交互式控件**：使用 `hx-vals`，不使用 `name`
+2. **表单数据**：使用 `hidden` input，设置正确的 `name`
+3. **索引管理**：初始用真实索引，动态添加用时间戳
+4. **OOB 交换**：使用 `morph`，不包裹多余层级
+5. **纯 HTMX**：尽量使用原生功能，避免 JavaScript
+
+遵循这些原则可以确保组件既功能完整，又不会干扰表单提交。

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "imean-service-engine-htmx-plugin",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "HtmxAdminPlugin for IMean Service Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx examples-v2/index.ts",
+    "test": "vitest --run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --run --coverage",
+    "test:unit": "vitest --run --project unit",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "dev:component": "tsx src/component-system/test.ts",
+    "prepublishOnly": "npm run build && npm run test"
+  },
   "keywords": [
     "microservice",
     "hono",
@@ -38,16 +51,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx examples-v2/index.ts",
-    "test": "vitest --run",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --run --coverage",
-    "test:unit": "vitest --run --project unit",
-    "test:e2e": "playwright test",
-    "test:e2e:ui": "playwright test --ui",
-    "test:e2e:headed": "playwright test --headed"
   }
-}
+}