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

package/docs/hono-html-best-practices.md

@@ -1,509 +0,0 @@
-# Hono HTML 模板字符串最佳实践
-
-本文档介绍在 HtmxAdminPlugin 中使用 Hono `html` 模板字符串开发自定义表单字段渲染器的最佳实践。
-
-## 为什么使用 Hono `html` 模板字符串？
-
-### 优势
-
-1. **自动转义**：Hono 会自动转义 HTML 属性值，避免 XSS 攻击
-2. **类型安全**：TypeScript 提供类型检查和代码提示
-3. **语法高亮**：编辑器支持 HTML 语法高亮和格式化
-4. **避免字符串拼接错误**：不需要手动拼接字符串，减少错误
-5. **更好的可维护性**：代码结构清晰，易于理解和修改
-
-### 与字符串拼接的对比
-
-**❌ 错误：使用字符串拼接**
-
-```typescript
-const htmlContent = `
-  <div class="container">
-    <input name="${fieldName}" value="${value}" />
-  </div>
-`;
-return <div dangerouslySetInnerHTML={{ __html: htmlContent }} />;
-```
-
-**问题**：
-- 需要手动转义 HTML 特殊字符
-- 容易出错，特别是处理引号和特殊字符时
-- 失去类型检查和语法高亮
-- 代码可读性差
-
-**✅ 正确：使用 Hono `html` 模板字符串**
-
-```typescript
-import { html } from "hono/html";
-
-return html`
-  <div class="container">
-    <input name="${fieldName}" value="${value}" />
-  </div>
-`;
-```
-
-**优势**：
-- 自动转义，安全可靠
-- 类型检查和语法高亮
-- 代码清晰易读
-
-## 核心原则
-
-### 1. 使用 `html` 模板字符串生成所有 HTML
-
-所有 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>
-  `;
-}
-```
-
-### 2. `x-data` 属性的处理
-
-**重要**：不要使用 `raw()` 包装 `x-data` 属性值。
-
-**❌ 错误**：
-
-```typescript
-import { html, raw } from "hono/html";
-
-return html`
-  <div x-data='${raw(xDataContent)}'>
-    <!-- ... -->
-  </div>
-`;
-```
-
-**✅ 正确**：
-
-```typescript
-import { html } from "hono/html";
-
-const xDataContent = `{
-  items: [],
-  init() {
-    // ...
-  }
-}`;
-
-return html`
-  <div x-data="${xDataContent}">
-    <!-- ... -->
-  </div>
-`;
-```
-
-**原因**：Hono 会自动处理 `x-data` 属性值的转义，使用 `raw()` 会破坏转义机制。
-
-### 3. JavaScript 字符串值的处理
-
-在 `x-data` 中，使用 `JSON.stringify` 安全地插入字符串值：
-
-```typescript
-const xDataContent = `{
-  fieldName: ${JSON.stringify(fieldName)},
-  placeholder: ${JSON.stringify(placeholder)},
-  items: ${JSON.stringify(initialItems)},
-  init() {
-    // ...
-  }
-}`;
-```
-
-**为什么使用 `JSON.stringify`？**
-- 自动处理特殊字符（引号、换行符等）
-- 确保 JavaScript 语法正确
-- 避免手动转义错误
-
-### 4. HTML 属性值的自动转义
-
-Hono 会自动转义 HTML 属性值，直接使用原始值即可：
-
-```typescript
-return html`
-  <input
-    name="${fieldName}"
-    value="${value}"
-    data-testid="input-${fieldName}"
-  />
-`;
-```
-
-**不需要手动转义**：Hono 会自动处理 `&`、`<`、`>`、`"`、`'` 等特殊字符。
-
-### 5. 避免字符串拼接
-
-**❌ 错误：在函数中拼接 HTML 字符串**
-
-```typescript
-const generateFieldHTML = (field: ModelField): string => {
-  return `
-    <div class="field">
-      <label>${field.label}</label>
-      <input name="${field.name}" />
-    </div>
-  `;
-};
-```
-
-**✅ 正确：使用 `html` 模板字符串**
-
-```typescript
-const generateField = (field: ModelField) => {
-  return html`
-    <div class="field">
-      <label>${field.label}</label>
-      <input name="${field.name}" />
-    </div>
-  `;
-};
-```
-
-### 6. 条件渲染
-
-使用三元表达式进行条件渲染：
-
-```typescript
-return html`
-  <div>
-    ${field.required
-      ? html`<span class="text-red-500">*</span>`
-      : ""}
-    <input name="${field.name}" ${field.required ? "required" : ""} />
-  </div>
-`;
-```
-
-### 7. 数组渲染
-
-使用 `map` 配合 `html` 模板字符串：
-
-```typescript
-return html`
-  <select>
-    ${options.map(
-      (option) => html`
-        <option value="${option.value}">${option.label}</option>
-      `
-    )}
-  </select>
-`;
-```
-
-### 8. 插入已生成的 HTML
-
-如果必须插入已生成的 HTML 字符串，使用 `raw()`：
-
-```typescript
-import { html, raw } from "hono/html";
-
-const fieldsHTML = fields.map((field) => generateFieldHTML(field)).join("");
-
-return html`
-  <div>
-    ${raw(fieldsHTML)}
-  </div>
-`;
-```
-
-**注意**：只有在确实需要插入已生成的 HTML 字符串时才使用 `raw()`，优先使用 `html` 模板字符串。
-
-## 完整示例
-
-### 示例 1：字符串数组编辑器
-
-```typescript
-import { html } from "hono/html";
-
-export function StringArrayEditor(props: StringArrayEditorProps) {
-  const { value, fieldName, placeholder = "请输入内容" } = props;
-  const initialItems: string[] = value || [];
-  const initialValueJson = JSON.stringify(initialItems);
-
-  // 构建 x-data 字符串
-  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();
-    }
-  }`;
-
-  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"
-            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)"
-                class="flex-1 px-3 py-2 border rounded-lg"
-                x-bind:data-testid="fieldName + '-input-' + index"
-              />
-              <button
-                type="button"
-                x-on:click="removeItem(index)"
-                class="px-3 py-2 text-red-600"
-                x-bind:data-testid="fieldName + '-remove-button-' + index"
-              >
-                删除
-              </button>
-            </div>
-          </template>
-        </div>
-      </div>
-    </div>
-  `;
-}
-```
-
-### 示例 2：对象编辑器（动态生成字段）
-
-```typescript
-import { html } from "hono/html";
-
-export function ObjectEditor(props: ObjectEditorProps) {
-  const { value, fieldName, objectSchema } = props;
-  const fields = parseSchemaToFields(objectSchema);
-  const initialValueJson = JSON.stringify(value || {});
-
-  const xDataContent = `{
-    obj: {},
-    init() {
-      const dataAttr = this.$el.getAttribute('data-initial-value');
-      if (dataAttr) {
-        try {
-          this.obj = JSON.parse(dataAttr);
-        } catch (e) {
-          console.error('Failed to parse initial value:', e);
-          this.obj = {};
-        }
-      }
-      this.updateHiddenField();
-    },
-    updateHiddenField() {
-      const hiddenInput = this.$el.querySelector('input[name="${fieldName}"][type="hidden"]');
-      if (hiddenInput) {
-        hiddenInput.value = JSON.stringify(this.obj);
-      }
-    },
-    updateField(fieldName, value, fieldType, required) {
-      // 更新逻辑
-      this.updateHiddenField();
-    }
-  }`;
-
-  // 生成字段组件
-  const generateField = (field: ModelField) => {
-    const fieldId = `${fieldName}-${field.name}`;
-    const fieldNameVar = `obj.${field.name}`;
-    const fieldNameForJs = JSON.stringify(field.name);
-
-    return html`
-      <div class="space-y-2" data-testid="${fieldName}-field-${field.name}">
-        <label
-          for="${fieldId}"
-          class="block text-sm font-semibold text-gray-700"
-        >
-          ${field.label}
-          ${field.required ? html`<span class="text-red-500 ml-1">*</span>` : ""}
-        </label>
-        <input
-          type="text"
-          id="${fieldId}"
-          x-bind:value="${fieldNameVar} || ''"
-          x-on:input="updateField(${fieldNameForJs}, $event.target.value, 'text', ${field.required})"
-          class="w-full px-3 py-2 border rounded-lg"
-          data-testid="${fieldName}-input-${field.name}"
-          ${field.required ? "required" : ""}
-        />
-      </div>
-    `;
-  };
-
-  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="space-y-4">
-        ${fields.map((field) => generateField(field))}
-      </div>
-    </div>
-  `;
-}
-```
-
-## Alpine.js 表达式中的字符串拼接
-
-在 Alpine.js 表达式中（如 `x-bind:data-testid`），使用字符串拼接而不是模板字符串：
-
-**❌ 错误**：
-
-```typescript
-x-bind:data-testid="`${fieldName}-item-${index}`"
-```
-
-**✅ 正确**：
-
-```typescript
-x-bind:data-testid="fieldName + '-item-' + index"
-```
-
-**原因**：Alpine.js 表达式是 JavaScript 代码，模板字符串在运行时可能无法正确解析。
-
-## 常见错误和解决方案
-
-### 错误 1：在 `x-data` 中使用 `raw()`
-
-**错误**：
-```typescript
-return html`
-  <div x-data='${raw(xDataContent)}'>
-    <!-- ... -->
-  </div>
-`;
-```
-
-**解决方案**：直接使用，不要包装 `raw()`：
-```typescript
-return html`
-  <div x-data="${xDataContent}">
-    <!-- ... -->
-  </div>
-`;
-```
-
-### 错误 2：手动转义 HTML
-
-**错误**：
-```typescript
-const escapedValue = value.replace(/&/g, "&amp;").replace(/</g, "&lt;");
-return html`<input value="${escapedValue}" />`;
-```
-
-**解决方案**：让 Hono 自动转义：
-```typescript
-return html`<input value="${value}" />`;
-```
-
-### 错误 3：字符串拼接生成 HTML
-
-**错误**：
-```typescript
-const htmlContent = `<div class="${className}">${content}</div>`;
-return <div dangerouslySetInnerHTML={{ __html: htmlContent }} />;
-```
-
-**解决方案**：使用 `html` 模板字符串：
-```typescript
-return html`<div class="${className}">${content}</div>`;
-```
-
-### 错误 4：在 Alpine.js 表达式中使用模板字符串
-
-**错误**：
-```typescript
-x-bind:data-testid="`${fieldName}-item-${index}`"
-```
-
-**解决方案**：使用字符串拼接：
-```typescript
-x-bind:data-testid="fieldName + '-item-' + index"
-```
-
-## 检查清单
-
-在开发自定义表单字段渲染器时，请确保：
-
-- [ ] 使用 `html` 模板字符串生成所有 HTML
-- [ ] 不在 `x-data` 属性上使用 `raw()`
-- [ ] 在 `x-data` 中使用 `JSON.stringify` 插入字符串值
-- [ ] 不在 HTML 属性值上手动转义
-- [ ] 避免字符串拼接，使用 `html` 模板字符串
-- [ ] 在 Alpine.js 表达式中使用字符串拼接而不是模板字符串
-- [ ] 条件渲染使用三元表达式
-- [ ] 数组渲染使用 `map` 配合 `html` 模板字符串
-
-## 总结
-
-使用 Hono `html` 模板字符串的最佳实践：
-
-1. **始终使用 `html` 模板字符串**：避免字符串拼接
-2. **信任自动转义**：让 Hono 处理 HTML 转义
-3. **使用 `JSON.stringify`**：在 JavaScript 代码中安全插入字符串值
-4. **不要使用 `raw()`**：除非确实需要插入已生成的 HTML
-5. **保持代码清晰**：使用条件表达式和数组方法，而不是字符串拼接
-
-遵循这些最佳实践，可以编写出更安全、更易维护、更少错误的代码。