@ebiz/designer-components 0.1.21 → 0.1.22

package/src/components/EbizDetailView.md

@@ -0,0 +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+
+- Edge 79+