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

package/docs/jsx-alpine-best-practices.md

@@ -1,197 +0,0 @@
-# JSX + Alpine.js 最佳实践
-
-## 问题分析
-
-### 当前实现的问题
-
-在 `BannerEditor` 组件中，我们遇到了一个设计问题：
-
-1. **状态管理在 Alpine.js**：`banners` 数组由 Alpine.js 的 `x-data` 管理
-2. **渲染在 JSX**：使用 React 的 `map` 渲染固定数量的占位符（最多10个）
-3. **问题**：
-   - 如果用户添加超过10个banner，后面的不会显示
-   - 混合了 React 的渲染逻辑和 Alpine.js 的状态管理
-   - 不够动态，需要预先知道最大数量
-
-### 正确的思路
-
-既然状态由 Alpine.js 管理，渲染也应该由 Alpine.js 负责。我们应该：
-1. 只提供一个模板
-2. 让 Alpine.js 的 `x-for` 动态渲染列表
-3. JSX 只负责提供静态结构
-
-## 解决方案
-
-### 方案 1：使用 `template` 标签 + `dangerouslySetInnerHTML`（推荐）
-
-在 JSX 中，我们可以使用 `dangerouslySetInnerHTML` 来插入包含 `template` 标签的 HTML：
-
-```tsx
-<div
-  x-data="..."
-  dangerouslySetInnerHTML={{
-    __html: `
-      <template x-for="(banner, index) in banners">
-        <div class="banner-item">
-          <!-- banner 内容 -->
-        </div>
-      </template>
-    `
-  }}
-/>
-```
-
-**优点**：
-- 完全由 Alpine.js 控制渲染
-- 支持动态添加/删除，无数量限制
-- 符合 Alpine.js 的最佳实践
-
-**缺点**：
-- 失去 JSX 的类型检查和语法高亮
-- 需要手动转义 HTML
-
-### 方案 2：使用包装容器 + Alpine.js 动态创建（当前实现）
-
-使用一个容器，在 Alpine.js 的 `init()` 方法中动态创建 DOM：
-
-```tsx
-<div
-  x-data="{
-    banners: [],
-    init() {
-      // 从 data 属性读取初始值
-      // 动态创建 DOM 元素
-    }
-  }"
->
-  {/* 空的容器，由 Alpine.js 填充 */}
-</div>
-```
-
-**优点**：
-- 保持 JSX 结构
-- 完全动态
-
-**缺点**：
-- 需要手动管理 DOM
-- 代码复杂度高
-
-### 方案 3：混合方案（当前实现，需要改进）
-
-使用 JSX 渲染固定数量的占位符，用 `x-show` 控制显示：
-
-```tsx
-{Array.from({ length: 10 }).map((_, index) => (
-  <div x-show={`banners.length > ${index}`}>
-    {/* 内容 */}
-  </div>
-))}
-```
-
-**优点**：
-- 保持 JSX 结构
-- 简单直接
-
-**缺点**：
-- 有数量限制
-- 不够动态
-- 混合了两种渲染逻辑
-
-## 推荐方案
-
-### 对于动态列表：使用 `template` + `dangerouslySetInnerHTML`
-
-```tsx
-export function BannerEditor(props: BannerEditorProps) {
-  const { value, fieldName } = props;
-  const initialBanners: Banner[] = value || [];
-  const bannersJson = JSON.stringify(initialBanners);
-
-  // 构建模板 HTML
-  const templateHTML = `
-    <template x-for="(banner, index) in banners" :key="index">
-      <div class="border border-gray-200 rounded-lg p-4 space-y-3 bg-white">
-        <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"
-          >
-            删除
-          </button>
-        </div>
-        <!-- 更多内容 -->
-      </div>
-    </template>
-  `;
-
-  return (
-    <div
-      x-data={`{
-        banners: [],
-        init() {
-          const dataAttr = this.$el.getAttribute('data-initial-value');
-          if (dataAttr) {
-            this.banners = JSON.parse(dataAttr);
-          }
-          this.updateHiddenField();
-        },
-        // ... 其他方法
-      }`}
-      data-initial-value={bannersJson}
-      x-init="init()"
-      x-effect="updateHiddenField()"
-    >
-      <div
-        className="space-y-4"
-        x-show="banners.length > 0"
-        dangerouslySetInnerHTML={{ __html: templateHTML }}
-      />
-    </div>
-  );
-}
-```
-
-### 对于简单交互：使用 JSX + Alpine.js 属性
-
-对于不需要动态列表的场景，直接在 JSX 中使用 Alpine.js 属性：
-
-```tsx
-<div x-data="{ count: 0 }">
-  <button x-on:click="count++">点击</button>
-  <span x-text="count"></span>
-</div>
-```
-
-## 最佳实践总结
-
-1. **状态管理**：
-   - 简单状态：使用 Alpine.js 的 `x-data`
-   - 复杂状态：考虑使用 Alpine.js 的 Store 或外部状态管理
-
-2. **渲染策略**：
-   - **动态列表**：使用 `template` + `x-for` + `dangerouslySetInnerHTML`
-   - **静态结构**：使用 JSX，配合 Alpine.js 属性（`x-show`, `x-model` 等）
-   - **条件渲染**：使用 `x-show` 或 `x-if`
-
-3. **数据传递**：
-   - 使用 `data-*` 属性传递初始值
-   - 在 `x-init` 中读取并初始化
-
-4. **属性命名**：
-   - JSX 中，包含点号的属性名需要使用方括号语法：`{...{ "x-model.number": value }}`
-   - 或者使用字符串作为属性名：`"x-model.number"={value}`
-
-5. **避免混合**：
-   - 不要同时使用 React 的 `map` 和 Alpine.js 的 `x-for`
-   - 选择一种渲染方式并保持一致
-
-## 注意事项
-
-1. **安全性**：使用 `dangerouslySetInnerHTML` 时，确保内容已转义，避免 XSS 攻击
-2. **性能**：对于大量数据，考虑虚拟滚动或分页
-3. **可维护性**：如果模板 HTML 很长，考虑提取到单独的函数或文件
-4. **类型安全**：使用 TypeScript 时，`dangerouslySetInnerHTML` 会失去类型检查，需要额外注意