imean-service-engine-htmx-plugin 2.9.2 → 2.9.4

package/dist/index.js

@@ -436,7 +436,7 @@ function renderFormField(field, initialData, formFieldRenderers) {
             name: field.name,
             required: field.required,
             placeholder: fieldSchema.description || (isJsonString(value) ? "JSON \u683C\u5F0F\u6570\u636E" : ""),
-            rows: isJsonString(value) ? Math.max(10, value.split("\n").length) : Math.max(5, Math.ceil(value?.length || 0 / 100)),
+            rows: isJsonString(value) ? Math.max(10, value.split("\n").length) : Math.max(5, Math.min(Math.ceil(value?.length || 0 / 100), 10)),
             className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 resize-y font-mono text-sm",
             "data-testid": `input-${field.name}`,
             children: isJsonString(value) ? formatJsonString(value) : value
@@ -1449,7 +1449,23 @@ var DefaultCreateFeature = class extends BaseFormFeature {
     return basePath;
   }
   async getInitialData(context) {
-    return void 0;
+    const query = context.query || {};
+    const systemParams = /* @__PURE__ */ new Set(["dialog", "_t"]);
+    const filteredQuery = {};
+    for (const [key, value] of Object.entries(query)) {
+      if (!systemParams.has(key) && value !== void 0 && value !== null && value !== "") {
+        filteredQuery[key] = value;
+      }
+    }
+    if (Object.keys(filteredQuery).length === 0) {
+      return void 0;
+    }
+    const nestedData = parseNestedFormData2(filteredQuery);
+    const processedData = preprocessFormData(
+      nestedData,
+      this.schema
+    );
+    return processedData;
   }
   async handleSubmit(context, validatedData) {
     return await this.createItem(validatedData);

package/dist/index.mjs

@@ -434,7 +434,7 @@ function renderFormField(field, initialData, formFieldRenderers) {
             name: field.name,
             required: field.required,
             placeholder: fieldSchema.description || (isJsonString(value) ? "JSON \u683C\u5F0F\u6570\u636E" : ""),
-            rows: isJsonString(value) ? Math.max(10, value.split("\n").length) : Math.max(5, Math.ceil(value?.length || 0 / 100)),
+            rows: isJsonString(value) ? Math.max(10, value.split("\n").length) : Math.max(5, Math.min(Math.ceil(value?.length || 0 / 100), 10)),
             className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 resize-y font-mono text-sm",
             "data-testid": `input-${field.name}`,
             children: isJsonString(value) ? formatJsonString(value) : value
@@ -1447,7 +1447,23 @@ var DefaultCreateFeature = class extends BaseFormFeature {
     return basePath;
   }
   async getInitialData(context) {
-    return void 0;
+    const query = context.query || {};
+    const systemParams = /* @__PURE__ */ new Set(["dialog", "_t"]);
+    const filteredQuery = {};
+    for (const [key, value] of Object.entries(query)) {
+      if (!systemParams.has(key) && value !== void 0 && value !== null && value !== "") {
+        filteredQuery[key] = value;
+      }
+    }
+    if (Object.keys(filteredQuery).length === 0) {
+      return void 0;
+    }
+    const nestedData = parseNestedFormData2(filteredQuery);
+    const processedData = preprocessFormData(
+      nestedData,
+      this.schema
+    );
+    return processedData;
   }
   async handleSubmit(context, validatedData) {
     return await this.createItem(validatedData);

package/docs/AI-GUIDE.md

@@ -0,0 +1,1030 @@
+# imean-service-engine-htmx-plugin AI 使用指南
+
+本文档面向 AI 编码助手，指导如何使用 `imean-service-engine-htmx-plugin` 快速构建 HTMX 驱动的管理后台。
+
+## 安装
+
+```bash
+npm install imean-service-engine imean-service-engine-htmx-plugin
+```
+
+## 核心概念
+
+- **HtmxAdminPlugin**: 插件主类，负责配置和注册页面
+- **PageModel**: 页面模型，定义页面的名称、元数据和功能
+- **Feature**: 功能模块，如列表、详情、创建、编辑、删除、自定义
+- **Zod Schema**: 使用 Zod 定义数据结构，自动生成表单和验证
+
+## 快速开始
+
+```typescript
+import { Factory } from "imean-service-engine";
+import { z } from "zod";
+import {
+  HtmxAdminPlugin,
+  PageModel,
+  DefaultListFeature,
+  DefaultDetailFeature,
+  DefaultCreateFeature,
+  DefaultEditFeature,
+  DefaultDeleteFeature,
+  CustomFeature,
+} from "imean-service-engine-htmx-plugin";
+
+// 1. 定义 Zod Schema
+const ArticleSchema = z.object({
+  id: z.number().optional(),
+  title: z.string().min(1).describe("标题"),
+  content: z.string().describe("内容"),
+  status: z.enum(["draft", "published"]).describe("状态"),
+});
+
+// 2. 创建 PageModel
+class ArticlePageModel extends PageModel {
+  constructor() {
+    super("articles", {
+      title: "文章管理",
+      description: "管理文章内容",
+    });
+
+    // 注册列表功能
+    this.features.list(
+      new DefaultListFeature({
+        schema: ArticleSchema,
+        getList: async (params) => {
+          // 返回 { items, total, page, pageSize, totalPages }
+        },
+        fieldNames: ["title", "status"], // 列表显示的字段
+      })
+    );
+
+    // 注册详情功能
+    this.features.detail(
+      new DefaultDetailFeature({
+        schema: ArticleSchema,
+        getItem: async (id) => {
+          // 返回单条数据
+        },
+      })
+    );
+
+    // 注册创建功能
+    this.features.create(
+      new DefaultCreateFeature({
+        schema: ArticleSchema,
+        createItem: async (data) => {
+          // 创建并返回新数据
+        },
+      })
+    );
+
+    // 注册编辑功能
+    this.features.edit(
+      new DefaultEditFeature({
+        schema: ArticleSchema,
+        getItem: async (id) => {
+          // 获取数据
+        },
+        updateItem: async (id, data) => {
+          // 更新数据
+        },
+      })
+    );
+
+    // 注册删除功能
+    this.features.delete(
+      new DefaultDeleteFeature({
+        deleteItem: async (id) => {
+          // 删除数据，返回 boolean
+        },
+      })
+    );
+  }
+}
+
+// 3. 配置插件
+const adminPlugin = new HtmxAdminPlugin({
+  title: "管理后台",
+  prefix: "/admin",
+  homePath: "/admin/dashboard",
+  pages: [new ArticlePageModel()],
+  navigation: [
+    { label: "文章管理", icon: "📝", href: "/admin/articles/list" },
+  ],
+});
+
+// 4. 启动服务
+const { Microservice } = Factory.create(adminPlugin);
+const engine = new Microservice({ name: "my-admin", version: "1.0.0" });
+await engine.start(3000);
+```
+
+## Schema 定义最佳实践
+
+### 基本规范
+
+- **必须使用 `.describe()`**：设置字段的中文标签，用于表单和列表显示
+- **id 字段设为 optional**：创建时无 id，由后端生成
+- **枚举用 `z.enum()`**：自动生成下拉选项
+- **时间戳用 string**：便于展示和传输
+
+```typescript
+const ProductSchema = z.object({
+  id: z.number().optional(),
+  name: z.string().min(1).describe("商品名称"),
+  price: z.number().min(0).describe("价格"),
+  category: z.enum(["电子", "服装", "食品"]).describe("分类"),
+  description: z.string().optional().describe("描述"),
+  isActive: z.boolean().optional().describe("是否上架"),
+  tags: z.array(z.string()).optional().describe("标签"),
+  createdAt: z.string().optional().describe("创建时间"),
+});
+```
+
+### 复杂结构定义
+
+嵌套对象和数组可正常定义，配合自定义渲染器使用：
+
+```typescript
+const DestinationSchema = z.object({
+  id: z.number().optional(),
+  name: z.string().min(1).describe("名称"),
+  
+  // 嵌套数组对象
+  banners: z.array(z.object({
+    url: z.url().describe("图片地址"),
+    alt: z.string().describe("图片描述"),
+    order: z.number().int().min(0).describe("排序"),
+  })).default([]).describe("Banner图片"),
+  
+  // 嵌套对象
+  metadata: z.object({
+    timezone: z.string().optional().describe("时区"),
+    currency: z.string().optional().describe("货币"),
+    language: z.array(z.string()).optional().describe("语言"),
+  }).optional().describe("元数据"),
+});
+```
+
+### 筛选 Schema（独立定义）
+
+列表筛选字段可能与数据模型不完全对应，建议独立定义：
+
+```typescript
+const ArticleFilterSchema = z.object({
+  category: z.enum(["技术", "产品", "设计"]).optional().describe("分类"),
+  status: z.enum(["draft", "published"]).optional().describe("状态"),
+  author: z.string().optional().describe("作者"),
+});
+```
+
+## URL 路由规则
+
+每个 Feature 会自动生成对应的 URL 路由，规则如下：
+
+```
+{prefix}/{modelName}/{featurePath}
+```
+
+### 默认路由表
+
+| Feature | 方法 | 路径 | 示例（modelName="users"） |
+|---------|------|------|---------------------------|
+| list | GET | `/list` | `/admin/users/list` |
+| detail | GET | `/detail/:id` | `/admin/users/detail/123` |
+| create | GET | `/new` | `/admin/users/new` |
+| create | POST | `/new` | `/admin/users/new` |
+| edit | GET | `/edit/:id` | `/admin/users/edit/123` |
+| edit | POST | `/edit/:id` | `/admin/users/edit/123` |
+| delete | DELETE | `/delete/:id` | `/admin/users/delete/123` |
+| custom | 自定义 | 自定义 | `/admin/users/export` |
+
+### 弹窗模式（Dialog Mode）
+
+几乎所有页面都同时支持**整页渲染**和**弹窗渲染**，通过 URL 参数 `?dialog=true` 切换：
+
+```typescript
+// 整页模式
+/admin/users/detail/123
+
+// 弹窗模式（在当前页面弹窗中打开）
+/admin/users/detail/123?dialog=true
+```
+
+在列表页中，可以通过 `openMode` 配置各操作的默认打开方式：
+
+```typescript
+new DefaultListFeature({
+  openMode: {
+    create: "dialog",    // 新建在弹窗中打开
+    detail: "dialog",    // 详情在弹窗中打开
+    edit: "page",        // 编辑跳转整页
+  },
+});
+```
+
+### 跨模块链接
+
+利用路由规则，可以在不同业务模块间建立链接：
+
+```typescript
+// 在用户列表中添加"查看留言"链接
+new DefaultListFeature({
+  schema: UserSchema,
+  getList: userService.getList,
+  fieldNames: ["name", "email", "messageCount"],
+  fieldRenderers: {
+    messageCount: ({ value, item }) => (
+      <a
+        href={`/admin/messages/list?userId=${item.id}`}
+        hx-get={`/admin/messages/list?userId=${item.id}&dialog=true`}
+        class="text-blue-600 hover:underline"
+      >
+        {value} 条留言
+      </a>
+    ),
+  },
+});
+```
+
+## Schema 复用与扩展
+
+使用 Zod 的 `pick`、`omit`、`extend` 实现 Schema 复用：
+
+```typescript
+// 基础 Schema（完整数据结构）
+const UserBaseSchema = z.object({
+  id: z.number().optional(),
+  name: z.string().min(1).describe("姓名"),
+  email: z.string().email().describe("邮箱"),
+  phone: z.string().optional().describe("电话"),
+  avatar: z.string().optional().describe("头像"),
+  role: z.enum(["admin", "editor", "viewer"]).describe("角色"),
+  department: z.string().optional().describe("部门"),
+  createdAt: z.string().optional().describe("创建时间"),
+  updatedAt: z.string().optional().describe("更新时间"),
+});
+
+// 列表 Schema（仅显示关键字段）
+const UserListSchema = UserBaseSchema.pick({
+  id: true,
+  name: true,
+  email: true,
+  role: true,
+  createdAt: true,
+});
+
+// 创建表单 Schema（排除自动生成字段）
+const UserCreateSchema = UserBaseSchema.omit({
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+});
+
+// 详情 Schema（完整信息 + 关联数据）
+const UserDetailSchema = UserBaseSchema.extend({
+  messageCount: z.number().optional().describe("留言数"),
+  lastLoginAt: z.string().optional().describe("最后登录"),
+});
+
+// 筛选 Schema
+const UserFilterSchema = z.object({
+  role: z.enum(["admin", "editor", "viewer"]).optional().describe("角色"),
+  department: z.string().optional().describe("部门"),
+});
+```
+
+### 在 PageModel 中使用不同 Schema
+
+```typescript
+class UserPageModel extends PageModel {
+  constructor() {
+    super("users", { title: "用户管理" });
+
+    this.features.list(
+      new DefaultListFeature({
+        schema: UserListSchema, // 列表用精简 Schema
+        getList: userService.getList,
+        filterSchema: UserFilterSchema,
+        fieldRenderers: {
+          // 添加跨模块链接
+          name: ({ value, item }) => (
+            <a
+              href={`/admin/messages/list?userId=${item.id}`}
+              hx-get={`/admin/messages/list?userId=${item.id}&dialog=true`}
+              class="text-blue-600 hover:underline"
+            >
+              {value} 的留言
+            </a>
+          ),
+        },
+      })
+    );
+
+    this.features.detail(
+      new DefaultDetailFeature({
+        schema: UserDetailSchema, // 详情用扩展 Schema
+        getItem: userService.getDetail,
+      })
+    );
+
+    this.features.create(
+      new DefaultCreateFeature({
+        schema: UserCreateSchema, // 创建用精简 Schema
+        createItem: userService.create,
+      })
+    );
+
+    this.features.edit(
+      new DefaultEditFeature({
+        schema: UserCreateSchema, // 编辑复用创建 Schema
+        getItem: userService.get,
+        updateItem: userService.update,
+      })
+    );
+
+    this.features.delete(
+      new DefaultDeleteFeature({
+        deleteItem: userService.delete,
+      })
+    );
+  }
+}
+```
+
+## Feature 配置详解
+
+### DefaultListFeature
+
+```typescript
+new DefaultListFeature({
+  schema: ArticleSchema,
+  idKey: "id", // 主键字段，默认 "id"
+  getList: async (params) => { /* ListParams => ListResult<T> */ },
+  deleteItem: async (id) => { /* 可选，启用行内删除 */ },
+  
+  // 显示字段
+  fieldNames: ["title", "status", "createdAt"],
+  
+  // 筛选配置（可选，使用独立 Schema）
+  filterSchema: ArticleFilterSchema,
+  
+  // 打开方式配置
+  openMode: {
+    create: "dialog",    // 新建：弹窗
+    detail: "newWindow", // 详情：新窗口
+    edit: "page",        // 编辑：整页
+  },
+  
+  // 自定义字段渲染
+  fieldRenderers: {
+    status: ({ value }) => (
+      <span class={value === "published" ? "text-green-600" : "text-gray-600"}>
+        {value === "published" ? "已发布" : "草稿"}
+      </span>
+    ),
+  },
+  
+  // 自定义 Header
+  header: (context) => (
+    <div class="p-4">
+      <h2>自定义标题区域</h2>
+    </div>
+  ),
+});
+```
+
+### DefaultDetailFeature
+
+```typescript
+new DefaultDetailFeature({
+  schema: ArticleSchema,
+  getItem: async (id) => { /* 返回单条数据 */ },
+  
+  // 弹窗配置
+  dialogSize: "xl", // "sm" | "md" | "lg" | "xl" | "full"
+  closeOnBackdropClick: true,
+  
+  // 动态标题
+  title: (context, item) => item?.title || "详情",
+  description: (context, item) => `作者：${item?.author}`,
+  
+  // 显示字段
+  fieldNames: ["title", "content", "author", "status"],
+  
+  // 自定义字段渲染
+  fieldRenderers: {
+    content: ({ value }) => (
+      <div class="whitespace-pre-wrap">{value}</div>
+    ),
+  },
+});
+```
+
+### DefaultCreateFeature / DefaultEditFeature
+
+```typescript
+new DefaultCreateFeature({
+  schema: ArticleSchema,
+  createItem: async (data) => { /* 返回创建的数据 */ },
+  dialogSize: "xl",
+  closeOnBackdropClick: false, // 编辑表单建议禁用遮罩关闭
+  
+  // 自定义表单字段渲染器
+  fieldRenderers: {
+    tags: TagsEditor, // 使用内置的标签编辑器
+  },
+});
+
+new DefaultEditFeature({
+  schema: ArticleSchema,
+  getItem: async (id) => { /* 获取数据 */ },
+  updateItem: async (id, data) => { /* 更新数据 */ },
+  title: (context, item) => `编辑：${item?.title}`,
+});
+```
+
+### DefaultDeleteFeature
+
+```typescript
+new DefaultDeleteFeature({
+  deleteItem: async (id) => { /* 返回 boolean */ },
+});
+```
+
+### CustomFeature（自定义页面）
+
+```typescript
+new CustomFeature({
+  name: "dashboard",
+  routes: [{ method: "get", path: "" }],
+  render: async (context) => (
+    <div class="p-6">
+      <h1>仪表盘</h1>
+      <p>自定义页面内容</p>
+    </div>
+  ),
+});
+```
+
+## 表单处理机制（重要）
+
+表单处理是插件最复杂的部分，理解其原理对正确使用至关重要。
+
+### Schema 定义决定表单行为
+
+Schema 定义直接影响：
+1. **表单字段生成**：根据字段类型自动生成 input/select/textarea
+2. **必填校验**：非 optional 字段必须提供值，否则 Zod 校验失败
+3. **类型转换**：表单提交的字符串会根据 Schema 类型自动转换
+
+```typescript
+// 必填字段：表单必须提供值
+name: z.string().min(1).describe("名称"),
+
+// 可选字段：可以不填
+description: z.string().optional().describe("描述"),
+
+// 带默认值：不填时使用默认值
+status: z.enum(["draft", "published"]).default("draft").describe("状态"),
+```
+
+### 表单数据处理流程
+
+```
+FormData (扁平键值对)
+    ↓ 第一阶段：解析
+{ "title": "文章", "banners[0].url": "http://...", "banners[0].alt": "图片" }
+    ↓ 第二阶段：还原嵌套结构
+{ "title": "文章", "banners": [{ "url": "http://...", "alt": "图片" }] }
+    ↓ 第三阶段：类型转换（根据 Schema）
+{ "title": "文章", "banners": [{ "url": "http://...", "alt": "图片" }] }
+    ↓ 第四阶段：Zod 校验
+校验通过 → 调用 createItem/updateItem
+校验失败 → 返回错误信息，回填表单
+```
+
+### 数组字段的表单命名规则
+
+数组字段必须使用带索引的命名格式，系统会自动还原为数组结构：
+
+```html
+<!-- 简单数组：tags = ["技术", "前端"] -->
+<input name="tags[0]" value="技术" />
+<input name="tags[1]" value="前端" />
+
+<!-- 对象数组：banners = [{ url: "...", alt: "..." }] -->
+<input name="banners[0].url" value="http://example.com/1.jpg" />
+<input name="banners[0].alt" value="图片1" />
+<input name="banners[1].url" value="http://example.com/2.jpg" />
+<input name="banners[1].alt" value="图片2" />
+```
+
+**重要**：索引可以不连续（如删除中间项后变成 `[0], [2], [5]`），系统会自动压缩为连续索引 `[0], [1], [2]`。
+
+### 复杂表单的两种实践方式
+
+#### 方式一：拍平字段 + 专用表单 Schema（推荐用于固定结构）
+
+适用场景：嵌套对象结构固定，如用户资料中的地址信息。
+
+```typescript
+// 数据 Schema（包含嵌套对象）
+const UserSchema = z.object({
+  id: z.number().optional(),
+  name: z.string().describe("姓名"),
+  address: z.object({
+    province: z.string().describe("省份"),
+    city: z.string().describe("城市"),
+    street: z.string().describe("街道"),
+  }).describe("地址"),
+});
+
+// 表单 Schema（拍平结构）
+const UserFormSchema = z.object({
+  name: z.string().min(1).describe("姓名"),
+  "address.province": z.string().min(1).describe("省份"),
+  "address.city": z.string().min(1).describe("城市"),
+  "address.street": z.string().min(1).describe("街道"),
+});
+
+// 使用表单 Schema
+new DefaultCreateFeature({
+  schema: UserFormSchema, // 使用拍平的表单 Schema
+  createItem: async (data) => {
+    // 在 service 层还原嵌套结构
+    const user = {
+      name: data.name,
+      address: {
+        province: data["address.province"],
+        city: data["address.city"],
+        street: data["address.street"],
+      },
+    };
+    return userService.create(user);
+  },
+});
+```
+
+#### 方式二：自定义编辑器组件（推荐用于动态数组）
+
+适用场景：动态数组对象，如 banners、faqs 等可增删的列表。
+
+```typescript
+// 数据 Schema
+const DestinationSchema = z.object({
+  name: z.string().describe("名称"),
+  banners: z.array(z.object({
+    url: z.url().describe("图片地址"),
+    alt: z.string().describe("描述"),
+  })).default([]).describe("Banner图片"),
+});
+
+// 使用自定义编辑器
+new DefaultCreateFeature({
+  schema: DestinationSchema,
+  createItem: destinationService.create,
+  fieldRenderers: {
+    banners: BannerEditor, // 自定义编辑器负责生成正确的表单结构
+  },
+});
+```
+
+自定义编辑器必须：
+1. 使用 Alpine.js 管理动态状态
+2. 为每个字段生成正确命名的隐藏 input（如 `banners[0].url`）
+3. 处理增删操作时维护正确的索引
+
+### 常见问题
+
+#### 必填字段校验失败
+- 检查 Schema 定义，非 optional 字段必须提供值
+- 复杂嵌套字段如果必填，需要使用自定义编辑器确保数据完整
+
+#### 数组字段为空
+- 确保隐藏 input 使用了正确的数组索引格式：`fieldName[index]` 或 `fieldName[index].property`
+- 使用 Alpine.js 的 `x-for` 渲染列表时，隐藏字段的 name 需要动态绑定
+
+#### 类型转换错误
+- 数字字段：表单提交的是字符串，系统会自动转换为 number
+- 布尔字段：`"true"/"1"/"on"` → `true`，`"false"/"0"/"off"/""` → `false`
+- 如果转换失败，Zod 校验会报错
+
+## 认证与权限
+
+```typescript
+const authProvider = {
+  cookieKey: "auth_token",
+  loginUrl: "/admin/login",
+  logoutUrl: "/admin/logout",
+  
+  async tokenToUser(token, ctx) {
+    // 验证 token，返回用户信息
+    return {
+      id: 1,
+      name: "管理员",
+      permissions: ["articles.*", "deny:users.delete"],
+    };
+  },
+};
+
+const adminPlugin = new HtmxAdminPlugin({
+  authProvider,
+  // ...
+});
+```
+
+权限格式：
+- `articles.list` - 具体权限
+- `articles.*` - 通配符
+- `deny:articles.delete` - 明确禁止
+
+## 服务层接口
+
+### ListParams
+
+```typescript
+interface ListParams {
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: "asc" | "desc";
+  filters?: Record<string, any>;
+}
+```
+
+### ListResult
+
+```typescript
+interface ListResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+```
+
+## 通知系统
+
+在 Feature 的 handler 或 render 中使用 context 发送通知：
+
+```typescript
+render: async (context) => {
+  context.sendSuccess("操作成功", "数据已保存");
+  context.sendError("操作失败", "请检查输入");
+  context.sendWarning("警告", "该操作不可撤销");
+  context.sendInfo("提示", "处理中...");
+  
+  return <div>...</div>;
+};
+```
+
+## 重定向与刷新
+
+```typescript
+render: async (context) => {
+  // 重定向
+  context.redirect("/admin/articles/list");
+  
+  // 刷新当前页面
+  context.setRefresh(true);
+  
+  return <div>操作完成</div>;
+};
+```
+
+## 完整示例：只读页面
+
+```typescript
+class ArticleReadonlyPageModel extends PageModel {
+  constructor() {
+    super("articles-readonly", {
+      title: "文章查看",
+      description: "只读模式",
+    });
+
+    // 只注册列表和详情，不注册创建、编辑、删除
+    this.features.list(
+      new DefaultListFeature({
+        schema: ArticleSchema,
+        getList: articleService.getArticleList,
+        fieldNames: ["title", "author", "status"],
+      })
+    );
+
+    this.features.detail(
+      new DefaultDetailFeature({
+        schema: ArticleSchema,
+        getItem: articleService.getArticle,
+      })
+    );
+  }
+}
+```
+
+## 自定义字段渲染器
+
+### FieldRendererProps 类型
+
+所有渲染器接收统一的 props：
+
+```typescript
+interface FieldRendererProps<T = any> {
+  value: any;           // 当前字段值
+  item: Partial<T>;     // 完整数据项
+  field: FormField;     // 字段定义（含 name、label、type 等）
+}
+
+interface FormField {
+  name: string;
+  label: string;
+  type?: "text" | "textarea" | "select" | "date" | "number" | "email" | "url" | "checkbox";
+  required?: boolean;
+  options?: Array<{ value: string | number; label: string }>;
+}
+```
+
+### 展示性渲染器（用于列表/详情）
+
+用于自定义字段在列表列或详情页的展示方式：
+
+```typescript
+// 简单示例：评分渲染器
+function RatingRenderer(props: FieldRendererProps) {
+  const { value } = props;
+  if (value == null) return "-";
+  return <span>{Number(value).toFixed(1)} ⭐</span>;
+}
+
+// 使用
+new DefaultListFeature({
+  fieldRenderers: {
+    rating: RatingRenderer,
+    status: ({ value }) => (
+      <span class={value === "published" ? "text-green-600" : "text-gray-600"}>
+        {value === "published" ? "已发布" : "草稿"}
+      </span>
+    ),
+  },
+});
+```
+
+### 表单编辑器（用于创建/编辑）
+
+表单编辑器使用 Alpine.js 管理状态，通过隐藏字段同步数据到表单：
+
+```typescript
+function MyArrayEditor(props: FieldRendererProps) {
+  const { value, field } = props;
+  const name = field.name;
+  const initialItems = value || [];
+
+  // Alpine.js 状态初始化
+  const initialData = JSON.stringify({
+    items: initialItems,
+    newItem: "",
+  });
+
+  return (
+    <div x-data={initialData}>
+      {/* 输入框 */}
+      <input
+        type="text"
+        x-model="newItem"
+        x-on:keydown.enter.prevent="items.push(newItem); newItem = ''"
+        placeholder="输入后按回车添加"
+      />
+
+      {/* 列表渲染 */}
+      <template x-for="(item, index) in items" x-bind:key="index">
+        <div>
+          {/* 隐藏字段：用于表单提交 */}
+          <input
+            type="hidden"
+            x-bind:name={`'${name}[' + index + ']'`}
+            x-bind:value="item"
+          />
+          <span x-text="item"></span>
+          <button type="button" x-on:click="items.splice(index, 1)">删除</button>
+        </div>
+      </template>
+
+      {/* 空状态 */}
+      <div x-show="items.length === 0">暂无数据</div>
+    </div>
+  );
+}
+
+// 使用
+new DefaultCreateFeature({
+  fieldRenderers: {
+    tags: MyArrayEditor,
+  },
+});
+```
+
+### 复杂对象编辑器
+
+对于嵌套对象数组（如 banners），隐藏字段需使用点号路径：
+
+```typescript
+function BannerEditor(props: FieldRendererProps) {
+  const { value, field } = props;
+  const name = field.name;
+  const initialData = JSON.stringify({
+    banners: value || [],
+  });
+
+  return (
+    <div x-data={initialData}>
+      <button type="button" x-on:click="banners.push({ url: '', alt: '' })">
+        添加
+      </button>
+
+      <template x-for="(banner, index) in banners" x-bind:key="index">
+        <div>
+          <input type="text" x-model="banner.url" placeholder="图片地址" />
+          <input
+            type="hidden"
+            x-bind:name={`'${name}[' + index + '].url'`}
+            x-bind:value="banner.url"
+          />
+          
+          <input type="text" x-model="banner.alt" placeholder="描述" />
+          <input
+            type="hidden"
+            x-bind:name={`'${name}[' + index + '].alt'`}
+            x-bind:value="banner.alt"
+          />
+          
+          <button type="button" x-on:click="banners.splice(index, 1)">删除</button>
+        </div>
+      </template>
+    </div>
+  );
+}
+```
+
+### 内置编辑器
+
+插件提供以下内置编辑器：
+
+```typescript
+import {
+  TagsEditor,         // 标签编辑器（支持拖拽排序）
+  StringArrayEditor,  // 字符串数组编辑器
+  ObjectEditor,       // 对象编辑器（根据 Zod Schema 自动生成字段）
+} from "imean-service-engine-htmx-plugin";
+
+// 使用
+new DefaultEditFeature({
+  fieldRenderers: {
+    tags: TagsEditor,
+    highlights: (props) => <StringArrayEditor {...props} placeholder="输入亮点" />,
+    metadata: (props) => {
+      const metadataSchema = DestinationSchema.shape.metadata.unwrap();
+      return <ObjectEditor {...props} objectSchema={metadataSchema} />;
+    },
+  },
+});
+```
+
+## 常见用例
+
+### 1. 字段分组展示
+
+将表单或详情页字段分组显示：
+
+```typescript
+new DefaultDetailFeature({
+  schema: DestinationSchema,
+  getItem: destinationService.getDestination,
+  groups: [
+    { label: "基本信息", fields: ["name", "code", "type", "description"] },
+    { label: "媒体资源", fields: ["banners"] },
+    { label: "统计信息", fields: ["views", "rating"] },
+  ],
+});
+```
+
+### 2. 不同打开方式
+
+控制新建、详情、编辑的打开方式：
+
+```typescript
+new DefaultListFeature({
+  openMode: {
+    create: "dialog",    // 弹窗
+    detail: "newWindow", // 新窗口
+    edit: "page",        // 整页跳转
+  },
+});
+```
+
+### 3. 只读页面
+
+只注册列表和详情，不注册创建、编辑、删除：
+
+```typescript
+class ReadonlyPageModel extends PageModel {
+  constructor() {
+    super("readonly-articles", { title: "文章查看" });
+    this.features.list(new DefaultListFeature({ /* ... */ }));
+    this.features.detail(new DefaultDetailFeature({ /* ... */ }));
+    // 不注册 create、edit、delete
+  }
+}
+```
+
+### 4. 动态标题
+
+根据数据动态设置页面标题：
+
+```typescript
+new DefaultDetailFeature({
+  title: (context, item) => item?.title || "详情",
+  description: (context, item) => `作者：${item?.author}`,
+});
+
+new DefaultEditFeature({
+  title: (context, item) => `编辑：${item?.title}`,
+});
+```
+
+### 5. 防止表单误关闭
+
+编辑表单禁用点击遮罩关闭：
+
+```typescript
+new DefaultEditFeature({
+  dialogSize: "xl",
+  closeOnBackdropClick: false, // 只能通过关闭按钮关闭
+});
+```
+
+### 6. 自定义列表 Header
+
+完全自定义列表页的头部区域：
+
+```typescript
+new DefaultListFeature({
+  header: (context) => (
+    <div class="px-6 py-3 flex justify-between items-center">
+      <div>
+        <h2 class="text-lg font-semibold">📰 文章管理</h2>
+        <span class="text-sm text-gray-600">共 100 篇</span>
+      </div>
+      <button
+        class="px-4 py-2 bg-blue-600 text-white rounded"
+        hx-get={`${context.prefix}/articles/new?dialog=true`}
+      >
+        新建文章
+      </button>
+    </div>
+  ),
+});
+```
+
+## 导出的类型和工具
+
+```typescript
+import {
+  // 核心类
+  HtmxAdminPlugin,
+  PageModel,
+  
+  // Feature 类
+  DefaultListFeature,
+  DefaultDetailFeature,
+  DefaultCreateFeature,
+  DefaultEditFeature,
+  DefaultDeleteFeature,
+  CustomFeature,
+  
+  // 内置编辑器
+  TagsEditor,
+  StringArrayEditor,
+  ObjectEditor,
+  
+  // 类型
+  HtmxAdminPluginOptions,
+  PageMetadata,
+  FeatureContext,
+  ListParams,
+  ListResult,
+  UserInfo,
+  AuthProvider,
+  DialogSize,
+  OpenMode,
+  ActionButton,
+  FieldRendererProps,
+  FormField,
+  FieldGroup,
+  
+  // 工具函数
+  getUserInfo,
+  parseListParams,
+  checkUserPermission,
+} from "imean-service-engine-htmx-plugin";
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imean-service-engine-htmx-plugin",
-  "version": "2.9.2",
+  "version": "2.9.4",
   "description": "HtmxAdminPlugin for IMean Service Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",