@ebiz/designer-components 0.1.79 → 0.1.81

package/src/components/EbizDetailView.md

@@ -1,439 +1,439 @@
-# EbizDetailView 详情页组件
-
-## 组件简介
-
-EbizDetailView 是一个功能强大的详情页组件，支持通过JSON配置的方式定义显示字段和字段类型。组件采用灵活的布局系统，支持多种字段类型渲染，并能对字段进行分组展示。
-
-## 功能特性
-
-- ✅ **JSON配置驱动**：通过JSON配置定义字段结构和显示方式
-- ✅ **多种字段类型**：支持文本、用户、文件、日期、状态、标签、链接、富文本等类型
-- ✅ **灵活布局**：支持水平/垂直布局，可调整显示列数
-- ✅ **字段分组**：支持按组名称对字段进行分组显示
-- ✅ **样式定制**：可自定义标签颜色、间距等样式属性
-- ✅ **事件支持**：支持文件下载、用户点击、链接点击等事件
-
-## 基础用法
-
-```vue
-<template>
-  <EbizDetailView 
-    :fields="fields" 
-    :data="data"
-    :columns="2"
-    layout="horizontal"
-    @download-file="handleDownloadFile"
-  />
-</template>
-
-<script setup>
-import { EbizDetailView } from '@ebiz/designer-components'
-
-const fields = [
-  {
-    key: 'name',
-    label: '姓名',
-    type: 'text',
-    group: '基本信息',
-    required: true
-  },
-  {
-    key: 'status',
-    label: '状态',
-    type: 'status',
-    group: '基本信息'
-  }
-]
-
-const data = {
-  name: '张三',
-  status: {
-    text: '在职',
-    status: 'success'
-  }
-}
-
-const handleDownloadFile = (file) => {
-  // 处理文件下载
-}
-</script>
-```
-
-## 字段类型说明
-
-### 1. 文本类型 (text)
-显示普通文本内容。
-
-```json
-{
-  "key": "name",
-  "label": "姓名",
-  "type": "text",
-  "group": "基本信息"
-}
-```
-
-### 2. 用户类型 (user)
-展示用户信息，包含头像、姓名、部门等。
-
-```json
-{
-  "key": "manager",
-  "label": "负责人",
-  "type": "user",
-  "group": "团队信息"
-}
-```
-
-数据格式：
-```json
-{
-  "manager": [
-    {
-      "id": "1",
-      "name": "张经理",
-      "department": "产品部",
-      "avatar": "https://example.com/avatar.jpg"
-    }
-  ]
-}
-```
-
-### 3. 文件类型 (file)
-展示文件列表，支持图片预览和文件下载。
-
-```json
-{
-  "key": "documents",
-  "label": "相关文档",
-  "type": "file",
-  "group": "附件"
-}
-```
-
-数据格式：
-```json
-{
-  "documents": [
-    {
-      "id": "1",
-      "name": "项目方案.pdf",
-      "size": 1024576,
-      "url": "https://example.com/doc.pdf"
-    }
-  ]
-}
-```
-
-### 4. 日期类型 (date)
-格式化显示日期。
-
-```json
-{
-  "key": "createTime",
-  "label": "创建时间",
-  "type": "date",
-  "group": "时间信息"
-}
-```
-
-### 5. 状态类型 (status)
-显示带样式的状态标签。
-
-```json
-{
-  "key": "status",
-  "label": "状态",
-  "type": "status",
-  "group": "基本信息"
-}
-```
-
-数据格式：
-```json
-{
-  "status": {
-    "text": "进行中",
-    "status": "success" // success | warning | error | info
-  }
-}
-```
-
-### 6. 标签类型 (tags)
-显示标签列表。
-
-```json
-{
-  "key": "tags",
-  "label": "标签",
-  "type": "tags",
-  "group": "分类信息"
-}
-```
-
-数据格式：
-```json
-{
-  "tags": ["前端", "Vue3", "组件库"]
-}
-```
-
-### 7. 链接类型 (link)
-显示可点击的链接。
-
-```json
-{
-  "key": "website",
-  "label": "官网",
-  "type": "link",
-  "group": "外部链接"
-}
-```
-
-数据格式：
-```json
-{
-  "website": {
-    "text": "访问官网",
-    "url": "https://example.com"
-  }
-}
-```
-
-### 8. 富文本类型 (html)
-渲染HTML内容。
-
-```json
-{
-  "key": "description",
-  "label": "详细描述",
-  "type": "html",
-  "group": "详细信息"
-}
-```
-
-## Props 参数
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| fields | Array | [] | 字段配置数组 |
-| data | Object | {} | 数据源对象 |
-| columns | Number | 2 | 显示列数，取值范围1-6 |
-| layout | String | 'horizontal' | 布局方式：horizontal/vertical |
-| gap | Number | 16 | 字段间距，单位px |
-| labelColor | String | '#666666' | 标签文字颜色 |
-
-## 字段配置说明
-
-每个字段配置对象包含以下属性：
-
-| 属性 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| key | String | ✅ | 字段键名，对应data中的属性 |
-| label | String | ✅ | 字段显示标签 |
-| type | String | ✅ | 字段类型 |
-| group | String | ❌ | 分组名称，用于字段分组 |
-| required | Boolean | ❌ | 是否必填，显示红色星号 |
-| description | String | ❌ | 字段描述文本 |
-| defaultValue | Any | ❌ | 默认值 |
-
-## Events 事件
-
-| 事件名 | 参数 | 说明 |
-|--------|------|------|
-| download-file | file | 点击文件下载时触发 |
-| user-click | user | 点击用户信息时触发 |
-| link-click | link | 点击链接时触发 |
-
-## 布局配置
-
-### 水平布局 (horizontal)
-标签和值在同一行显示，标签在左，值在右。
-
-```vue
-<EbizDetailView 
-  :fields="fields" 
-  :data="data"
-  layout="horizontal"
-  :columns="2"
-/>
-```
-
-### 垂直布局 (vertical)
-标签在上，值在下，垂直排列。
-
-```vue
-<EbizDetailView 
-  :fields="fields" 
-  :data="data"
-  layout="vertical"
-  :columns="3"
-/>
-```
-
-## 分组展示
-
-通过字段配置中的 `group` 属性可以对字段进行分组：
-
-```json
-[
-  {
-    "key": "name",
-    "label": "姓名",
-    "type": "text",
-    "group": "基本信息"
-  },
-  {
-    "key": "phone",
-    "label": "电话",
-    "type": "text",
-    "group": "联系方式"
-  }
-]
-```
-
-分组标题会自动显示，带有蓝色左侧边条装饰。
-
-## 样式定制
-
-### 自定义标签颜色
-```vue
-<EbizDetailView 
-  :fields="fields" 
-  :data="data"
-  labelColor="#333333"
-/>
-```
-
-### 自定义间距
-```vue
-<EbizDetailView 
-  :fields="fields" 
-  :data="data"
-  :gap="20"
-/>
-```
-
-## 完整示例
-
-```vue
-<template>
-  <EbizDetailView 
-    :fields="complexFields" 
-    :data="complexData"
-    :columns="2"
-    layout="horizontal"
-    :gap="16"
-    labelColor="#666666"
-    @download-file="handleDownloadFile"
-    @user-click="handleUserClick"
-    @link-click="handleLinkClick"
-  />
-</template>
-
-<script setup>
-import { EbizDetailView } from '@ebiz/designer-components'
-
-const complexFields = [
-  {
-    key: 'title',
-    label: '项目名称',
-    type: 'text',
-    group: '项目信息',
-    required: true
-  },
-  {
-    key: 'manager',
-    label: '项目经理',
-    type: 'user',
-    group: '项目信息'
-  },
-  {
-    key: 'status',
-    label: '项目状态',
-    type: 'status',
-    group: '项目信息'
-  },
-  {
-    key: 'documents',
-    label: '项目文档',
-    type: 'file',
-    group: '附件资源'
-  },
-  {
-    key: 'tags',
-    label: '项目标签',
-    type: 'tags',
-    group: '分类信息'
-  },
-  {
-    key: 'website',
-    label: '项目官网',
-    type: 'link',
-    group: '外部链接'
-  }
-]
-
-const complexData = {
-  title: 'TinyEngine 低代码平台',
-  manager: [
-    {
-      id: '1',
-      name: '李经理',
-      department: '产品部',
-      avatar: 'https://avatars.githubusercontent.com/u/1?v=4'
-    }
-  ],
-  status: {
-    text: '进行中',
-    status: 'success'
-  },
-  documents: [
-    {
-      id: '1',
-      name: '项目需求文档.docx',
-      size: 1024576,
-      url: 'https://example.com/docs/requirements.docx'
-    }
-  ],
-  tags: ['前端', '低代码', 'Vue3'],
-  website: {
-    text: 'TinyEngine 官网',
-    url: 'https://opentiny.design/tiny-engine'
-  }
-}
-
-const handleDownloadFile = (file) => {
-  // 实现文件下载逻辑
-  const link = document.createElement('a')
-  link.href = file.url
-  link.download = file.name
-  link.click()
-}
-
-const handleUserClick = (user) => {
-  // 处理用户点击事件
-  console.log('查看用户详情:', user)
-}
-
-const handleLinkClick = (link) => {
-  // 处理链接点击事件
-  window.open(link.url, '_blank')
-}
-</script>
-```
-
-## 注意事项
-
-1. **数据格式**：确保传入的data对象包含fields中定义的所有key
-2. **文件类型**：file类型字段的数据必须是数组格式
-3. **用户类型**：user类型字段的数据必须是数组格式，即使只有一个用户
-4. **状态类型**：status类型字段需要包含text和status两个属性
-5. **性能优化**：对于大量数据，建议使用虚拟滚动或分页
-
-## 浏览器兼容性
-
-- Chrome 60+
-- Firefox 55+
-- Safari 12+
+# EbizDetailView 详情页组件
+
+## 组件简介
+
+EbizDetailView 是一个功能强大的详情页组件，支持通过JSON配置的方式定义显示字段和字段类型。组件采用灵活的布局系统，支持多种字段类型渲染，并能对字段进行分组展示。
+
+## 功能特性
+
+- ✅ **JSON配置驱动**：通过JSON配置定义字段结构和显示方式
+- ✅ **多种字段类型**：支持文本、用户、文件、日期、状态、标签、链接、富文本等类型
+- ✅ **灵活布局**：支持水平/垂直布局，可调整显示列数
+- ✅ **字段分组**：支持按组名称对字段进行分组显示
+- ✅ **样式定制**：可自定义标签颜色、间距等样式属性
+- ✅ **事件支持**：支持文件下载、用户点击、链接点击等事件
+
+## 基础用法
+
+```vue
+<template>
+  <EbizDetailView 
+    :fields="fields" 
+    :data="data"
+    :columns="2"
+    layout="horizontal"
+    @download-file="handleDownloadFile"
+  />
+</template>
+
+<script setup>
+import { EbizDetailView } from '@ebiz/designer-components'
+
+const fields = [
+  {
+    key: 'name',
+    label: '姓名',
+    type: 'text',
+    group: '基本信息',
+    required: true
+  },
+  {
+    key: 'status',
+    label: '状态',
+    type: 'status',
+    group: '基本信息'
+  }
+]
+
+const data = {
+  name: '张三',
+  status: {
+    text: '在职',
+    status: 'success'
+  }
+}
+
+const handleDownloadFile = (file) => {
+  // 处理文件下载
+}
+</script>
+```
+
+## 字段类型说明
+
+### 1. 文本类型 (text)
+显示普通文本内容。
+
+```json
+{
+  "key": "name",
+  "label": "姓名",
+  "type": "text",
+  "group": "基本信息"
+}
+```
+
+### 2. 用户类型 (user)
+展示用户信息，包含头像、姓名、部门等。
+
+```json
+{
+  "key": "manager",
+  "label": "负责人",
+  "type": "user",
+  "group": "团队信息"
+}
+```
+
+数据格式：
+```json
+{
+  "manager": [
+    {
+      "id": "1",
+      "name": "张经理",
+      "department": "产品部",
+      "avatar": "https://example.com/avatar.jpg"
+    }
+  ]
+}
+```
+
+### 3. 文件类型 (file)
+展示文件列表，支持图片预览和文件下载。
+
+```json
+{
+  "key": "documents",
+  "label": "相关文档",
+  "type": "file",
+  "group": "附件"
+}
+```
+
+数据格式：
+```json
+{
+  "documents": [
+    {
+      "id": "1",
+      "name": "项目方案.pdf",
+      "size": 1024576,
+      "url": "https://example.com/doc.pdf"
+    }
+  ]
+}
+```
+
+### 4. 日期类型 (date)
+格式化显示日期。
+
+```json
+{
+  "key": "createTime",
+  "label": "创建时间",
+  "type": "date",
+  "group": "时间信息"
+}
+```
+
+### 5. 状态类型 (status)
+显示带样式的状态标签。
+
+```json
+{
+  "key": "status",
+  "label": "状态",
+  "type": "status",
+  "group": "基本信息"
+}
+```
+
+数据格式：
+```json
+{
+  "status": {
+    "text": "进行中",
+    "status": "success" // success | warning | error | info
+  }
+}
+```
+
+### 6. 标签类型 (tags)
+显示标签列表。
+
+```json
+{
+  "key": "tags",
+  "label": "标签",
+  "type": "tags",
+  "group": "分类信息"
+}
+```
+
+数据格式：
+```json
+{
+  "tags": ["前端", "Vue3", "组件库"]
+}
+```
+
+### 7. 链接类型 (link)
+显示可点击的链接。
+
+```json
+{
+  "key": "website",
+  "label": "官网",
+  "type": "link",
+  "group": "外部链接"
+}
+```
+
+数据格式：
+```json
+{
+  "website": {
+    "text": "访问官网",
+    "url": "https://example.com"
+  }
+}
+```
+
+### 8. 富文本类型 (html)
+渲染HTML内容。
+
+```json
+{
+  "key": "description",
+  "label": "详细描述",
+  "type": "html",
+  "group": "详细信息"
+}
+```
+
+## Props 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| fields | Array | [] | 字段配置数组 |
+| data | Object | {} | 数据源对象 |
+| columns | Number | 2 | 显示列数，取值范围1-6 |
+| layout | String | 'horizontal' | 布局方式：horizontal/vertical |
+| gap | Number | 16 | 字段间距，单位px |
+| labelColor | String | '#666666' | 标签文字颜色 |
+
+## 字段配置说明
+
+每个字段配置对象包含以下属性：
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| key | String | ✅ | 字段键名，对应data中的属性 |
+| label | String | ✅ | 字段显示标签 |
+| type | String | ✅ | 字段类型 |
+| group | String | ❌ | 分组名称，用于字段分组 |
+| required | Boolean | ❌ | 是否必填，显示红色星号 |
+| description | String | ❌ | 字段描述文本 |
+| defaultValue | Any | ❌ | 默认值 |
+
+## Events 事件
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| download-file | file | 点击文件下载时触发 |
+| user-click | user | 点击用户信息时触发 |
+| link-click | link | 点击链接时触发 |
+
+## 布局配置
+
+### 水平布局 (horizontal)
+标签和值在同一行显示，标签在左，值在右。
+
+```vue
+<EbizDetailView 
+  :fields="fields" 
+  :data="data"
+  layout="horizontal"
+  :columns="2"
+/>
+```
+
+### 垂直布局 (vertical)
+标签在上，值在下，垂直排列。
+
+```vue
+<EbizDetailView 
+  :fields="fields" 
+  :data="data"
+  layout="vertical"
+  :columns="3"
+/>
+```
+
+## 分组展示
+
+通过字段配置中的 `group` 属性可以对字段进行分组：
+
+```json
+[
+  {
+    "key": "name",
+    "label": "姓名",
+    "type": "text",
+    "group": "基本信息"
+  },
+  {
+    "key": "phone",
+    "label": "电话",
+    "type": "text",
+    "group": "联系方式"
+  }
+]
+```
+
+分组标题会自动显示，带有蓝色左侧边条装饰。
+
+## 样式定制
+
+### 自定义标签颜色
+```vue
+<EbizDetailView 
+  :fields="fields" 
+  :data="data"
+  labelColor="#333333"
+/>
+```
+
+### 自定义间距
+```vue
+<EbizDetailView 
+  :fields="fields" 
+  :data="data"
+  :gap="20"
+/>
+```
+
+## 完整示例
+
+```vue
+<template>
+  <EbizDetailView 
+    :fields="complexFields" 
+    :data="complexData"
+    :columns="2"
+    layout="horizontal"
+    :gap="16"
+    labelColor="#666666"
+    @download-file="handleDownloadFile"
+    @user-click="handleUserClick"
+    @link-click="handleLinkClick"
+  />
+</template>
+
+<script setup>
+import { EbizDetailView } from '@ebiz/designer-components'
+
+const complexFields = [
+  {
+    key: 'title',
+    label: '项目名称',
+    type: 'text',
+    group: '项目信息',
+    required: true
+  },
+  {
+    key: 'manager',
+    label: '项目经理',
+    type: 'user',
+    group: '项目信息'
+  },
+  {
+    key: 'status',
+    label: '项目状态',
+    type: 'status',
+    group: '项目信息'
+  },
+  {
+    key: 'documents',
+    label: '项目文档',
+    type: 'file',
+    group: '附件资源'
+  },
+  {
+    key: 'tags',
+    label: '项目标签',
+    type: 'tags',
+    group: '分类信息'
+  },
+  {
+    key: 'website',
+    label: '项目官网',
+    type: 'link',
+    group: '外部链接'
+  }
+]
+
+const complexData = {
+  title: 'TinyEngine 低代码平台',
+  manager: [
+    {
+      id: '1',
+      name: '李经理',
+      department: '产品部',
+      avatar: 'https://avatars.githubusercontent.com/u/1?v=4'
+    }
+  ],
+  status: {
+    text: '进行中',
+    status: 'success'
+  },
+  documents: [
+    {
+      id: '1',
+      name: '项目需求文档.docx',
+      size: 1024576,
+      url: 'https://example.com/docs/requirements.docx'
+    }
+  ],
+  tags: ['前端', '低代码', 'Vue3'],
+  website: {
+    text: 'TinyEngine 官网',
+    url: 'https://opentiny.design/tiny-engine'
+  }
+}
+
+const handleDownloadFile = (file) => {
+  // 实现文件下载逻辑
+  const link = document.createElement('a')
+  link.href = file.url
+  link.download = file.name
+  link.click()
+}
+
+const handleUserClick = (user) => {
+  // 处理用户点击事件
+  console.log('查看用户详情:', user)
+}
+
+const handleLinkClick = (link) => {
+  // 处理链接点击事件
+  window.open(link.url, '_blank')
+}
+</script>
+```
+
+## 注意事项
+
+1. **数据格式**：确保传入的data对象包含fields中定义的所有key
+2. **文件类型**：file类型字段的数据必须是数组格式
+3. **用户类型**：user类型字段的数据必须是数组格式，即使只有一个用户
+4. **状态类型**：status类型字段需要包含text和status两个属性
+5. **性能优化**：对于大量数据，建议使用虚拟滚动或分页
+
+## 浏览器兼容性
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
 - Edge 79+