feat(descriptions): 新增 FaDescriptions 组件及示例

hooray · hooray · commit c0cd2ffc9f7c · 2026-06-10T18:27:21.000+08:00
diff --git a/apps/core-ant-design-vue/src/types/components.d.ts b/apps/core-ant-design-vue/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/core-antdv-next/src/types/components.d.ts b/apps/core-antdv-next/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/core-arco-design-vue/src/types/components.d.ts b/apps/core-arco-design-vue/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/core-naive-ui/src/types/components.d.ts b/apps/core-naive-ui/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/core-tdesign/src/types/components.d.ts b/apps/core-tdesign/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/core-vexip-ui/src/types/components.d.ts b/apps/core-vexip-ui/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/example/src/router/modules/component.example.ts b/apps/example/src/router/modules/component.example.ts
@@ -93,6 +93,14 @@ const routes: RouteRecordRaw = {
         title: '右键菜单',
       },
     },
+    {
+      path: 'descriptions',
+      name: 'componentExampleDescriptions',
+      component: () => import('@/views/component_example/descriptions.vue'),
+      meta: {
+        title: '描述列表',
+      },
+    },
     {
       path: 'divider',
       name: 'componentExampleDivider',
diff --git a/apps/example/src/types/components.d.ts b/apps/example/src/types/components.d.ts
@@ -29,6 +29,7 @@ declare module 'vue' {
     FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
     FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
     FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+    FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
     FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
     FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
     FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
@@ -86,6 +87,7 @@ declare global {
   const FaCheckboxGroup: typeof import('@fantastic-admin/components')['FaCheckboxGroup']
   const FaCollapsible: typeof import('@fantastic-admin/components')['FaCollapsible']
   const FaContextMenu: typeof import('@fantastic-admin/components')['FaContextMenu']
+  const FaDescriptions: typeof import('@fantastic-admin/components')['FaDescriptions']
   const FaDivider: typeof import('@fantastic-admin/components')['FaDivider']
   const FaDrawer: typeof import('@fantastic-admin/components')['FaDrawer']
   const FaDropdown: typeof import('@fantastic-admin/components')['FaDropdown']
diff --git a/apps/example/src/views/component_example/descriptions.vue b/apps/example/src/views/component_example/descriptions.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { descriptions } from '@fantastic-admin/components/examples'
+</script>
+
+<template>
+  <div>
+    <FaPageHeader title="描述列表" description="FaDescriptions" />
+    <FaPageMain
+      v-for="example in descriptions"
+      :key="example.title"
+      :code="example.componentRaw"
+      :title="example.title"
+    >
+      <component :is="example.component" />
+    </FaPageMain>
+  </div>
+</template>
diff --git a/packages/components/resolver.ts b/packages/components/resolver.ts
@@ -16,6 +16,7 @@ const BASIC_COMPONENT_NAMES = [
   'FaCheckboxGroup',
   'FaCollapsible',
   'FaContextMenu',
+  'FaDescriptions',
   'FaDivider',
   'FaDrawer',
   'FaDropdown',
diff --git a/packages/components/src/basic/descriptions/README.md b/packages/components/src/basic/descriptions/README.md
@@ -0,0 +1,55 @@
+# FaDescriptions 描述列表
+
+纯展示信息组件，用于详情页、资料卡片、审核信息等只读数据场景。支持横向与纵向布局、边框、跨列、具名插槽和单项扩展字段。
+
+## 使用场景
+
+- 用户、订单、商品等详情信息展示
+- 表单提交后的只读确认信息
+- 弹窗中的轻量信息摘要
+- 卡片内的结构化字段展示
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `items` | `DescriptionItem[]` | `[]` | 描述项配置 |
+| `column` | `number` | `3` | 每行展示的描述项数量 |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局方向 |
+| `border` | `boolean` | `false` | 是否显示边框和单元格分割线 |
+| `labelWidth` | `string \| number` | - | label 区域宽度，仅横向布局生效 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | 单元格密度 |
+| `emptyText` | `string` | `'-'` | value 为空时的占位文本 |
+| `class` | `HTMLAttributes['class']` | - | 根节点 class |
+| `labelClass` | `HTMLAttributes['class']` | - | 全局 label 单元格 class |
+| `valueClass` | `HTMLAttributes['class']` | - | 全局 value 单元格 class |
+
+## DescriptionItem
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 插槽标识。使用具名插槽时需要提供，组件不会自动转换 |
+| `label` | `string` | label 文本 |
+| `value` | `string \| number \| boolean \| null \| undefined` | value 文本 |
+| `span` | `number` | 占用几个描述项列，默认 `1` |
+| `class` | `HTMLAttributes['class']` | 当前项 label 和 value 的公共 class |
+| `labelClass` | `HTMLAttributes['class']` | 当前项 label 单元格 class |
+| `valueClass` | `HTMLAttributes['class']` | 当前项 value 单元格 class |
+
+`DescriptionItem` 支持扩展字段，扩展字段会原样保留在插槽参数的 `item` 中。
+
+## Slots
+
+| 名称 | 说明 | 作用域参数 |
+|------|------|------------|
+| `label-{key}` | 自定义指定项 label | `item`、`index`、`label`、`value` |
+| `value-{key}` | 自定义指定项 value | `item`、`index`、`label`、`value` |
+
+## 注意事项
+
+1. `key` 只用于生成具名插槽，不用于读取数据。
+2. `key` 不会自动转换，建议使用字母、数字、短横线和下划线。
+3. `value` 为 `null`、`undefined` 或空字符串时显示 `emptyText`；`0` 和 `false` 会正常显示。
+4. `span` 表示占用几个描述项列，超出 `column` 时会按 `column` 处理。
+5. 最后一行不足 `column` 时会自动补齐空单元格，保证边框网格完整。
+6. 组件不内置标题、空状态和点击事件，可与 `FaCard`、`FaEmpty` 等组件组合使用。
diff --git a/packages/components/src/basic/descriptions/_examples/_basic.vue b/packages/components/src/basic/descriptions/_examples/_basic.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// 组件实际使用时无需手动导入，框架会自动导入
+import FaDescriptions from '../index.vue'
+
+const items = [
+  { label: 'Username', value: 'kooriokami' },
+  { label: 'Telephone', value: '18100000000' },
+  { label: 'Place', value: 'Suzhou' },
+  { label: 'Remarks', value: 'School' },
+  { label: 'Address', value: 'No.1188, Wuzhong Avenue', span: 2 },
+]
+</script>
+
+<template>
+  <FaDescriptions :items="items" label-width="120px" />
+</template>
diff --git a/packages/components/src/basic/descriptions/_examples/_border.vue b/packages/components/src/basic/descriptions/_examples/_border.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// 组件实际使用时无需手动导入，框架会自动导入
+import FaDescriptions from '../index.vue'
+
+const items = [
+  { label: 'Username', value: 'kooriokami' },
+  { label: 'Telephone', value: '18100000000' },
+  { label: 'Place', value: 'Suzhou' },
+  { label: 'Remarks', value: 'School' },
+  { label: 'Address', value: 'No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province', span: 2 },
+]
+</script>
+
+<template>
+  <FaDescriptions :items="items" border label-width="120px" />
+</template>
diff --git a/packages/components/src/basic/descriptions/_examples/_slot.vue b/packages/components/src/basic/descriptions/_examples/_slot.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import type { DescriptionItem } from '../index.vue'
+// 组件实际使用时无需手动导入，框架会自动导入
+import FaIcon from '../../icon/index.vue'
+import FaTag from '../../tag/index.vue'
+import FaDescriptions from '../index.vue'
+
+type ProfileItem = DescriptionItem<{
+  icon: string
+  tagVariant?: 'default' | 'secondary' | 'destructive' | 'outline'
+}>
+
+const items: ProfileItem[] = [
+  { key: 'username', label: 'Username', value: 'kooriokami', icon: 'i-lucide:user' },
+  { key: 'telephone', label: 'Telephone', value: '18100000000', icon: 'i-lucide:smartphone' },
+  { key: 'place', label: 'Place', value: 'Suzhou', icon: 'i-lucide:map-pin' },
+  { key: 'remarks', label: 'Remarks', value: 'School', icon: 'i-lucide:notebook-text', tagVariant: 'outline' },
+  { key: 'address', label: 'Address', value: 'No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province', icon: 'i-lucide:building-2', span: 2 },
+]
+</script>
+
+<template>
+  <FaDescriptions :items="items" border label-width="200px">
+    <template #label-username="{ item, label }">
+      <div class="inline-flex gap-2 items-center">
+        <FaIcon :name="item.icon" class="size-4" />
+        <span>{{ label }}</span>
+      </div>
+    </template>
+
+    <template #label-telephone="{ item, label }">
+      <div class="inline-flex gap-2 items-center">
+        <FaIcon :name="item.icon" class="size-4" />
+        <span>{{ label }}</span>
+      </div>
+    </template>
+
+    <template #label-place="{ item, label }">
+      <div class="inline-flex gap-2 items-center">
+        <FaIcon :name="item.icon" class="size-4" />
+        <span>{{ label }}</span>
+      </div>
+    </template>
+
+    <template #label-remarks="{ item, label }">
+      <div class="inline-flex gap-2 items-center">
+        <FaIcon :name="item.icon" class="size-4" />
+        <span>{{ label }}</span>
+      </div>
+    </template>
+
+    <template #label-address="{ item, label }">
+      <div class="inline-flex gap-2 items-center">
+        <FaIcon :name="item.icon" class="size-4" />
+        <span>{{ label }}</span>
+      </div>
+    </template>
+
+    <template #value-remarks="{ item, value }">
+      <FaTag :variant="item.tagVariant">
+        {{ value }}
+      </FaTag>
+    </template>
+  </FaDescriptions>
+</template>
diff --git a/packages/components/src/basic/descriptions/_examples/_vertical.vue b/packages/components/src/basic/descriptions/_examples/_vertical.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 组件实际使用时无需手动导入，框架会自动导入
+import FaDescriptions from '../index.vue'
+
+const items = [
+  { label: '早餐', value: '苹果' },
+  { label: '早午餐', value: '苹果' },
+  { label: '午餐', value: '苹果' },
+  { label: '晚餐', value: '苹果' },
+  { label: '正餐', value: '苹果' },
+  { label: '夜宵', value: '苹果' },
+  { label: '早餐', value: '苹果' },
+  { label: '早午餐', value: '苹果', span: 2 },
+  { label: '晚餐', value: '苹果', span: 3 },
+]
+</script>
+
+<template>
+  <FaDescriptions :items="items" :column="6" direction="vertical" border />
+</template>
diff --git a/packages/components/src/basic/descriptions/_examples/index.ts b/packages/components/src/basic/descriptions/_examples/index.ts
@@ -0,0 +1,31 @@
+import Basic from './_basic.vue'
+import BasicRaw from './_basic.vue?raw'
+import Border from './_border.vue'
+import BorderRaw from './_border.vue?raw'
+import Slot from './_slot.vue'
+import SlotRaw from './_slot.vue?raw'
+import Vertical from './_vertical.vue'
+import VerticalRaw from './_vertical.vue?raw'
+
+export default [
+  {
+    title: '基础',
+    component: Basic,
+    componentRaw: BasicRaw,
+  },
+  {
+    title: '边框',
+    component: Border,
+    componentRaw: BorderRaw,
+  },
+  {
+    title: '纵向布局',
+    component: Vertical,
+    componentRaw: VerticalRaw,
+  },
+  {
+    title: '自定义插槽',
+    component: Slot,
+    componentRaw: SlotRaw,
+  },
+]
diff --git a/packages/components/src/basic/descriptions/index.vue b/packages/components/src/basic/descriptions/index.vue
diff --git a/packages/components/src/examples.ts b/packages/components/src/examples.ts
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
