@tuoyuan/module-page-select 1.1.2 → 1.1.4

package/README.md

@@ -7,18 +7,21 @@ Vue 3 组件：用于选择业务模块、对应页面，编辑页面自带配
 - ✅ 模块与页面二级联动选择
 - ✅ 支持模块、页面数据缓存
 - ✅ 基于 JSON Schema 的动态表单渲染
-- ✅ 区分移动端（mobile）和 Web 端（external）
-- ✅ 支持默认值回显
-- ✅ 自定义数据获取方法
-- ✅ 完整的 TypeScript 类型定义
+- ✅ 区分移动端（mobile）和 Web 端（pc）
+- ✅ v-model 双向绑定支持
+- ✅ 支持默认值回显与自动补全
+- ✅ 完整的错误处理
+- ✅ 支持横向/纵向/行内布局
+- ✅ 灵活的确认按钮显示控制
+- ✅ 自动触发 change 事件（无确认按钮模式）
 
 ## 安装
 
 ```bash
-npm install template-page-select
+npm install @tuoyuan/template-page-select
 ```
 
-## 使用
+## 基础使用
 
 ### 全局注册
 
@@ -37,10 +40,9 @@ app.mount('#app')
 ```vue
 <template>
   <ModulePageSelect
-    type="mobile"
-    :fetchModules="getModules"
-    :fetchPages="getPages"
-    @confirm="handleConfirm"
+    v-model="pageConfig"
+    @change="handleChange"
+    @error="handleError"
   />
 </template>
 
@@ -51,28 +53,17 @@ export default {
   components: {
     ModulePageSelect
   },
+  data() {
+    return {
+      pageConfig: {}
+    }
+  },
   methods: {
-    async getModules() {
-      // 返回模块列表
-      const res = await fetch('/api/modules')
-      return res.json()
-    },
-    async getPages(moduleId, pageType) {
-      // 返回页面列表
-      const res = await fetch(`/api/pages?moduleId=${moduleId}&type=${pageType}`)
-      return res.json()
+    handleChange(config) {
+      console.log('页面配置已更新:', config)
     },
-    handleConfirm(config) {
-      console.log('选中配置:', config)
-      // config 格式：
-      // {
-      //   module_id: "66613bff9aa40000",
-      //   module_name: "操作日志",
-      //   page_id: "6663c53083e40000",
-      //   page_name: "操作日志",
-      //   page_type: 1,
-      //   configJson: {}
-      // }
+    handleError(error) {
+      console.error('错误:', error)
     }
   }
 }
@@ -83,130 +74,190 @@ export default {
 
 ### Props
 
-| 参数 | 说明 | 类型 | 可选值 | 默认值 |
-|------|------|------|--------|--------|
-| type | 终端类型 | String | mobile / external | mobile |
-| defaultModuleId | 默认模块ID（用于回显） | String | - | '' |
-| defaultPageId | 默认页面ID（用于回显） | String | - | '' |
-| fetchModules | 自定义模块列表获取方法 | Function | - | null |
-| fetchPages | 自定义页面列表获取方法 | Function(moduleId, pageType) | - | null |
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| modelValue | v-model 绑定的值 | Object | {} |
+| moduleId | 模块ID（用于回显） | String | '' |
+| pageId | 页面ID（用于回显） | String | '' |
+| autoEcho | 是否在挂载时自动回显已有值 | Boolean | true |
+| showCancelButton | 是否显示取消按钮 | Boolean | false |
+| layout | 表单布局方式：`'vertical'` / `'horizontal'` / `'inline'` | String | 'vertical' |
+| confirmButton | 是否显示确认按钮 | Boolean | true |
 
 ### Events
 
 | 事件名 | 说明 | 回调参数 |
 |--------|------|----------|
-| confirm | 确认选择时触发 | config: PageConfig |
+| update:modelValue | v-model 值更新 | result: PageConfig |
+| change | 选择确认后触发 | result: PageConfig |
+| cancel | 取消选择时触发 | - |
 | error | 发生错误时触发 | { type: string, error: Error } |
 
-### 数据格式
-
-#### 模块数据格式
+### 输出数据格式
 
 ```javascript
 {
-  id: "66613bff9aa40000",
-  name: "操作日志"
+  module_id: "66613bff9aa40000",      // 模块ID
+  module_name: "操作日志",             // 模块名称
+  page_id: "6663c53083e40000",        // 页面ID
+  page_name: "操作日志",               // 页面名称
+  type: "mobile",                     // 页面类型：mobile 或 pc
+  config: {                           // 页面配置（可选）
+    field1: "value1",
+    field2: 123
+  }
 }
 ```
 
-#### 页面数据格式
+## 使用示例
 
-```javascript
-{
-  id: "6663c53083e40000",
-  name: "操作日志",
-  type: 1, // 0: 移动端, 1: Web端
-  options: {
-    // JSON Schema 格式的配置
-    properties: {
-      wechatId: {
-        type: "string",
-        title: "微信ID",
-        description: "请输入微信ID"
+### 示例 1：基础调用
+
+```vue
+<template>
+  <div>
+    <ModulePageSelect v-model="selectedPage" @change="onPageChange" />
+    <div v-if="selectedPage.page_id">
+      <p>选中模块: {{ selectedPage.module_name }}</p>
+      <p>选中页面: {{ selectedPage.page_name }}</p>
+    </div>
+  </div>
+</template>
+
+<script>
+import ModulePageSelect from 'template-page-select'
+
+export default {
+  components: { ModulePageSelect },
+  data() {
+    return {
+      selectedPage: {}
+    }
+  },
+  methods: {
+    onPageChange(config) {
+      console.log('页面已更改:', config)
+      // 在这里可以保存配置、触发页面跳转等
+    }
+  }
+}
+</script>
+```
+
+### 示例 2：回显已有配置
+
+```vue
+<template>
+  <ModulePageSelect
+    v-model="pageConfig"
+    :moduleId="form.moduleId"
+    :pageId="form.pageId"
+    @change="saveConfig"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      form: {
+        moduleId: '66613bff9aa40000',
+        pageId: '6663c53083e40000'
       },
-      groupName: {
-        type: "string",
-        title: "业务分组"
+      pageConfig: {
+        module_id: '66613bff9aa40000',
+        module_name: '操作日志',
+        page_id: '6663c53083e40000',
+        page_name: '操作日志'
       }
     }
+  },
+  methods: {
+    saveConfig(config) {
+      console.log('配置已保存:', config)
+    }
   }
 }
+</script>
 ```
 
-#### 输出配置格式
+### 示例 3：与表单集成
 
-```javascript
-{
-  module_id: "66613bff9aa40000",
-  module_name: "操作日志",
-  page_id: "6663c53083e40000",
-  page_name: "操作日志",
-  page_type: 1,
-  configJson: {
-    wechatId: "xxx",
-    groupName: "xxx"
+```vue
+<template>
+  <a-form @submit="handleSubmit">
+    <a-form-item label="页面选择">
+      <ModulePageSelect
+        v-model="form.page"
+        @error="handleError"
+      />
+    </a-form-item>
+    <a-form-item>
+      <a-button type="primary" html-type="submit">保存</a-button>
+    </a-form-item>
+  </a-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      form: {
+        page: {}
+      }
+    }
+  },
+  methods: {
+    handleSubmit() {
+      if (!this.form.page.page_id) {
+        this.$message.error('请选择页面')
+        return
+      }
+      console.log('提交表单:', this.form)
+    },
+    handleError(error) {
+      this.$message.error(`错误: ${error.type}`)
+    }
   }
 }
+</script>
 ```
 
-## 使用示例
-
-### 示例 1：基础通用调用
+### 示例 4：横向布局
 
 ```vue
 <template>
   <ModulePageSelect
-    type="mobile"
-    :fetchModules="fetchModules"
-    :fetchPages="fetchPages"
-    @confirm="handlePageConfirm"
+    v-model="pageConfig"
+    layout="horizontal"
+    @change="handleChange"
   />
 </template>
 
 <script>
 export default {
+  data() {
+    return {
+      pageConfig: {}
+    }
+  },
   methods: {
-    async fetchModules() {
-      // 实现模块获取逻辑
-      return [
-        { id: '1', name: '模块1' },
-        { id: '2', name: '模块2' }
-      ]
-    },
-    async fetchPages(moduleId, pageType) {
-      // 实现页面获取逻辑
-      return [
-        { 
-          id: '1', 
-          name: '页面1', 
-          type: pageType,
-          options: {
-            properties: {
-              field1: { type: 'string', title: '字段1' }
-            }
-          }
-        }
-      ]
-    },
-    handlePageConfirm(pageConfig) {
-      console.log('选中页面配置', pageConfig)
+    handleChange(config) {
+      console.log('页面配置:', config)
     }
   }
 }
 </script>
 ```
 
-### 示例 2：回显已有页面数据
+### 示例 5：隐藏确认按钮，选择后自动触发
 
 ```vue
 <template>
   <ModulePageSelect
-    type="external"
-    :defaultModuleId="form.moduleId"
-    :defaultPageId="form.pageId"
-    :fetchModules="fetchModules"
-    :fetchPages="fetchPages"
-    @confirm="savePageInfo"
+    v-model="pageConfig"
+    :confirm-button="false"
+    @change="handleAutoChange"
   />
 </template>
 
@@ -214,54 +265,228 @@ export default {
 export default {
   data() {
     return {
-      form: {
-        moduleId: '66613bff9aa40000',
-        pageId: '6663c53083e40000'
-      }
+      pageConfig: {}
+    }
+  },
+  methods {
+    handleAutoChange(config) {
+      console.log('自动触发 change 事件:', config)
+      // 不需要点击确认按钮，选择页面后自动触发
+    }
+  }
+}
+</script>
+```
+
+### 示例 6：行内布局 + 无确认按钮
+
+```vue
+<template>
+  <div class="page-selector-wrapper">
+    <span>快速选择：</span>
+    <ModulePageSelect
+      v-model="pageConfig"
+      layout="inline"
+      :confirm-button="false"
+      @change="handleQuickSelect"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      pageConfig: {}
     }
   },
   methods: {
-    async fetchModules() {
-      // 获取模块列表
-    },
-    async fetchPages(moduleId, pageType) {
-      // 获取页面列表
-    },
-    savePageInfo(data) {
-      // 存储选中的模块、页面及配置
-      this.form.moduleId = data.module_id
-      this.form.pageId = data.page_id
-      console.log('配置数据:', data.configJson)
+    handleQuickSelect(config) {
+      console.log('快速选择:', config)
+      // 适用于工具栏、筛选条等场景
+      this.$router.push({
+        name: 'PagePreview',
+        query: {
+          moduleId: config.module_id,
+          pageId: config.page_id
+        }
+      })
     }
   }
 }
 </script>
 ```
 
-## 核心功能说明
+## 数据接口说明
+
+### 模块列表接口
+
+默认调用 `/api/assembly-center.extend_module.list`
+
+**请求参数：**
+```javascript
+{
+  page_no: 1,
+  page_size: 1000
+}
+```
+
+**响应格式：**
+```javascript
+{
+  data: {
+    list: [
+      { id: "1", name: "模块1" },
+      { id: "2", name: "模块2" }
+    ]
+  }
+}
+```
+
+### 页面列表接口
 
-### 1. 模块与页面加载逻辑
+默认调用 `/api/assembly-center.extend_module.page_list`
 
-- 初始化优先读取模块缓存，无缓存再请求接口拉取模块列表
-- 切换模块清空旧页面数据，重新获取当前模块下所有页面并缓存
-- 选中页面：加载页面配置
-  - 有配置（非空对象）→ 渲染动态表单
-  - 无配置（null/{}）→ 不展示表单区域
+**请求参数：**
+```javascript
+{
+  module_id: "xxx",      // 可选，不传时返回全部
+  type: 2,               // 1: pc, 2: mobile
+  page_no: 1,
+  page_size: 1000
+}
+```
+
+**响应格式：**
+```javascript
+{
+  data: {
+    list: [
+      {
+        id: "1",
+        name: "页面1",
+        module_id: "1",
+        options: {
+          // JSON Schema 格式配置
+          properties: {
+            field1: {
+              type: "string",
+              title: "字段1",
+              description: "字段1说明"
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+```
 
-### 2. 动态表单渲染
+## 页面配置 Schema
 
 组件支持基于 JSON Schema 的动态表单渲染，支持以下字段类型：
 
-- `string` → 文本输入框
-- `number` / `integer` → 数字输入框
-- `enum` → 下拉选择框
+### 基础类型
+
+```javascript
+{
+  properties: {
+    // 文本输入
+    username: {
+      type: "string",
+      title: "用户名",
+      description: "请输入用户名"
+    },
+    // 数字输入
+    age: {
+      type: "number",
+      title: "年龄",
+      default: 18
+    },
+    // 下拉选择
+    gender: {
+      type: "string",
+      title: "性别",
+      enum: ["male", "female"],
+      enumDescriptions: ["男", "女"]
+    }
+  }
+}
+```
+
+### 嵌套对象
+
+```javascript
+{
+  properties: {
+    user: {
+      type: "object",
+      title: "用户信息",
+      properties: {
+        name: {
+          type: "string",
+          title: "姓名"
+        },
+        email: {
+          type: "string",
+          title: "邮箱"
+        }
+      }
+    }
+  }
+}
+```
+
+### 数组类型
+
+```javascript
+{
+  properties: {
+    tags: {
+      type: "array",
+      title: "标签列表",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string", title: "标签名" },
+          value: { type: "string", title: "标签值" }
+        }
+      }
+    }
+  }
+}
+```
+
+## 核心逻辑说明
+
+### 1. 数据加载流程
+
+1. **初始化**：组件挂载时检查 `autoEcho`
+   - 若为 true，自动回显 `modelValue` 或 `moduleId`/`pageId` 对应的数据
+   - 若为 false，等待用户交互
+
+2. **模块加载**：用户 focus 模块下拉框时
+   - 优先返回缓存数据
+   - 无缓存时调用接口 `/api/assembly-center.extend_module.list`
+
+3. **页面加载**：用户选择模块或 focus 页面下拉框时
+   - 优先返回该模块的缓存数据
+   - 无缓存时调用接口 `/api/assembly-center.extend_module.page_list`
+
+### 2. 事件触发时机
+
+| 事件 | 触发时机 |
+|------|--------|
+| `change` | 用户点击确认按钮后 |
+| `error` | 接口请求失败时 |
+| `update:modelValue` | 与 `change` 同时触发 |
 
-### 3. 配置使用规则
+### 3. 页面方向选择
 
-1. 前端用 `page_id` 绑定页面路由
-2. 后端解析只依赖 `module_id` 和 `page_id`，名称字段仅做展示
-3. 页面初始化读取 `configJson`，回填表单
-4. 根据 `page_type` 走不同端逻辑（0: 移动端, 1: Web端）
+- **竖向（portrait）**：默认选项，适合移动端竖屏显示
+- **横向（landscape）**：适合移动端横屏显示
+
+选中的方向会包含在返回的 `orientation` 字段中
 
 ## 开发
 
@@ -279,6 +504,27 @@ npm run build:lib
 npm run lint
 ```
 
+## 常见问题
+
+### Q: 如何自定义数据接口？
+
+A: 组件默认调用内置的两个接口。如需自定义，可以：
+
+1. 在外部获取数据后通过 `modelValue` prop 传入
+2. 或修改接口地址在 `fetchModulesFromAPI` 和 `fetchPagesFromAPI` 方法中
+
+### Q: 页面配置为空时会怎样？
+
+A: 若页面 `options` 为空对象或不存在，组件不会展示配置表单，直接显示确认按钮。
+
+### Q: 如何禁用确认按钮？
+
+A: 必须同时选择模块和页面，确认按钮才会启用。未选择时按钮自动禁用。
+
+### Q: 支持国际化吗？
+
+A: 当前版本不支持国际化，所有文本为硬编码。可在后续版本中扩展。
+
 ## License
 
-MIT
+MIT