组件
    展示类

    描述列表

    描述列表用于键值对的呈现。

    代码演示

    如何引入

    <script setup lang="ts">
    import { Descriptions } from '@fibrous/semi-ui-vue';
</script>

    Descriptions.Item 也可以按名导入：DescriptionsItem。

    基本用法

    可以通过 data 以键值对 { key: value } 数组方式传入数据

    data 中的 key、value 只接受字符串或数字。需要自定义渲染时，使用作用域插槽 #itemKey、#value，参数为 { item, index }，其中 index 是该项在 data 中的位置（包含 hidden 的项）

    实际用户数量1,480,000
    7天留存
    98%
    安全等级3级
    垂类标签
    电商
    认证状态未认证
    代码
    <script setup lang="ts">
    import { IconArrowUp } from '@fibrous/semi-icons-vue';
    import { Descriptions, Tag } from '@fibrous/semi-ui-vue';

    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        { key: '7天留存', value: '98%' },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: '电商' },
        { key: '认证状态', value: '未认证' },
    ];
</script>

<template>
    <Descriptions :data="data">
        <template #value="{ item, index }">
            <div v-if="index === 1">
                98%
                <IconArrowUp size="small" :style="{ color: 'var(--semi-color-success)', marginLeft: '2px' }" />
            </div>
            <Tag v-else-if="index === 3" :style="{ margin: 0 }">电商</Tag>
            <template v-else>{{ item.value }}</template>
        </template>
    </Descriptions>
</template>

    设置对齐方式

    可以通过设置 align 值选择对齐方式，支持 center, justify, left, 和 plain。默认对齐方式为 center
    当 row 为 true 时，该配置无效
    left 指起始侧，在 RTL 下随页面方向镜像为靠右，与 center、justify 一致

    实际用户数量1,480,000
    7天留存98%
    安全等级3级
    垂类标签
    电商
    认证状态未认证
    实际用户数量1,480,000
    7天留存98%
    安全等级3级
    垂类标签
    电商
    认证状态未认证
    实际用户数量1,480,000
    7天留存98%
    安全等级3级
    垂类标签
    电商
    认证状态未认证
    实际用户数量:1,480,000
    7天留存:98%
    安全等级:3级
    垂类标签:
    电商
    认证状态:未认证
    代码
    <script setup lang="ts">
    import { Card, Descriptions, Tag } from '@fibrous/semi-ui-vue';

    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        { key: '7天留存', value: '98%' },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: '电商' },
        { key: '认证状态', value: '未认证' },
    ];
    const aligns = ['center', 'justify', 'left', 'plain'] as const;
</script>

<template>
    <div :style="{ display: 'flex', flexWrap: 'wrap' }">
        <Card v-for="align in aligns" :key="align" shadows="always" :style="{ margin: '10px' }">
            <Descriptions :align="align" :data="data">
                <template #value="{ item, index }">
                    <Tag v-if="index === 3" :style="{ margin: 0 }">电商</Tag>
                    <template v-else>{{ item.value }}</template>
                </template>
            </Descriptions>
        </Card>
    </div>
</template>

    Descriptions.Item 写法

    除了通过 data 声明数据外，还可以在默认插槽中写 Descriptions.Item 声明数据：key 通过 #itemKey 插槽传入，值写在默认插槽中。

    注意 Descriptions.Item 应当是 Descriptions 的直接子元素。

    实际用户数量 1,480,000
    7天留存 98%
    安全等级 3级
    垂类标签 电商
    认证状态 未认证
    代码
    <script setup lang="ts">
    import { Descriptions } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Descriptions>
        <Descriptions.Item>
            <template #itemKey>实际用户数量</template>
            1,480,000
        </Descriptions.Item>
        <Descriptions.Item>
            <template #itemKey>7天留存</template>
            98%
        </Descriptions.Item>
        <Descriptions.Item>
            <template #itemKey>安全等级</template>
            3级
        </Descriptions.Item>
        <Descriptions.Item>
            <template #itemKey>垂类标签</template>
            电商
        </Descriptions.Item>
        <Descriptions.Item>
            <template #itemKey>认证状态</template>
            未认证
        </Descriptions.Item>
    </Descriptions>
</template>

    设置布局模式

    可以通过 layout 设置布局模式，默认为 vertical 纵向布局 。

    抖音号:SemiDesign
    主播类型:自由主播
    安全等级:3级
    垂类标签:
    互联网资讯
    编程
    作品数量:88888888
    认证状态:这是一个很长很长很长很长很长很长很长很长很长的值
    代码
    <script setup lang="ts">
    import { Descriptions, Space, Tag } from '@fibrous/semi-ui-vue';

    const data = [
        { key: '抖音号', value: 'SemiDesign' },
        { key: '主播类型', value: '自由主播' },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: '互联网资讯 编程' },
        { key: '作品数量', value: '88888888' },
        { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
    ];
</script>

<template>
    <Descriptions align="plain" :column="4" :data="data" layout="vertical">
        <template #value="{ item, index }">
            <Space v-if="index === 3">
                <Tag color="amber" shape="circle" size="small">互联网资讯</Tag>
                <Tag color="violet" shape="circle" size="small">编程</Tag>
            </Space>
            <template v-else>{{ item.value }}</template>
        </template>
    </Descriptions>
</template>

    横向布局可设置 layout为 horizontal 。当设置 horizontal 时，可配合 column 指定每行最大列数

    抖音号:SemiDesign主播类型:自由主播安全等级:3级垂类标签:
    编程
    		作品数量:88888888
    认证状态:这是一个很长很长很长很长很长很长很长很长很长的值上次直播时间:2024-05-01 12:00:00
    代码
    <script setup lang="ts">
    import { Descriptions, Tag } from '@fibrous/semi-ui-vue';

    const data = [
        { key: '抖音号', value: 'SemiDesign' },
        { key: '主播类型', value: '自由主播' },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: '编程' },
        { key: '作品数量', value: '88888888' },
        { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
        { key: '上次直播时间', value: '2024-05-01 12:00:00', span: 3 },
    ];
</script>

<template>
    <Descriptions align="plain" :column="5" :data="data" layout="horizontal">
        <template #value="{ item, index }">
            <Tag v-if="index === 3" color="violet" shape="circle" size="small">编程</Tag>
            <template v-else>{{ item.value }}</template>
        </template>
    </Descriptions>
</template>

    双行显示

    可以通过设置 row 可选择双行显示，支持三种不同的大小：small, medium, large。默认大小为 medium，此时 align 配置不再生效

    实际用户数量1,480,000
    7天留存 98%
    安全等级3级

    实际用户数量1,480,000
    7天留存 98%
    安全等级3级

    实际用户数量1,480,000
    7天留存 98%
    安全等级3级
    代码
    <script setup lang="ts">
    import { IconArrowUp } from '@fibrous/semi-icons-vue';
    import { Descriptions } from '@fibrous/semi-ui-vue';

    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        { key: '7天留存', value: '98%' },
        { key: '安全等级', value: '3级' },
    ];
    const style = {
        boxShadow: 'var(--semi-shadow-elevated)',
        backgroundColor: 'var(--semi-color-bg-2)',
        borderRadius: '4px',
        padding: '10px',
        marginRight: '20px',
        width: '600px',
    };
</script>

<template>
    <div>
        <template v-for="size in ['small', 'medium', 'large'] as const" :key="size">
            <Descriptions :data="data" row :size="size" :style="style">
                <template #value="{ item, index }">
                    <span v-if="index === 1">
                        98%
                        <IconArrowUp size="small" :style="{ color: 'red', marginLeft: '4px' }" />
                    </span>
                    <template v-else>{{ item.value }}</template>
                </template>
            </Descriptions>
            <br v-if="size !== 'large'" />
        </template>
    </div>
</template>

    自定义 Key 样式

    可以通过 keyStyle 属性自定义 key 的样式，例如设置固定宽度实现对齐效果。该属性支持所有 CSS 样式，如 width、maxWidth、textAlign、color 等。

    用户名张三
    电子邮箱zhangsan@example.com
    联系电话138-0000-0000
    地址北京市朝阳区
    代码
    <script setup lang="ts">
    import { Descriptions, type DescriptionsData } from '@fibrous/semi-ui-vue';

    const keyStyle = { width: '100px', textAlign: 'right' } as const;
    const data: DescriptionsData[] = [
        { key: '用户名', value: '张三', keyStyle },
        { key: '电子邮箱', value: 'zhangsan@example.com', keyStyle },
        { key: '联系电话', value: '138-0000-0000', keyStyle },
        { key: '地址', value: '北京市朝阳区', keyStyle },
    ];
</script>

<template>
    <Descriptions align="center" :data="data" />
</template>

    也可以配合 Descriptions.Item 写法使用：

    姓名 李四
    年龄 28
    职业 前端工程师
    代码
    <script setup lang="ts">
    import { Descriptions } from '@fibrous/semi-ui-vue';

    const keyStyle = { width: '120px', color: 'var(--semi-color-primary)' };
</script>

<template>
    <Descriptions align="center">
        <Descriptions.Item :keyStyle="keyStyle">
            <template #itemKey>姓名</template>
            李四
        </Descriptions.Item>
        <Descriptions.Item :keyStyle="keyStyle">
            <template #itemKey>年龄</template>
            28
        </Descriptions.Item>
        <Descriptions.Item :keyStyle="keyStyle">
            <template #itemKey>职业</template>
            前端工程师
        </Descriptions.Item>
    </Descriptions>
</template>

    API 参考

    Descriptions

    Props

    属性说明类型默认值
    align对齐方式，可选 center、justify、left、plain；row 为 true 时无效。DescriptionsAlignsemiDefault("Descriptions", "align", "center")
    row是否双行显示。booleansemiDefault("Descriptions", "row", false)
    size双行显示时的尺寸，可选 small、medium、large。DescriptionsSizesemiDefault("Descriptions", "size", "medium")
    data列表显示的数据；为空时使用默认插槽中的 Descriptions.Item。DescriptionsData[]semiDefault("Descriptions", "data", [])
    layout布局模式，可选 vertical、horizontal。DescriptionsLayoutsemiDefault("Descriptions", "layout", "vertical")
    column横向布局下每行的总列数。numbersemiDefault("Descriptions", "column", 3)

    Events

    事件说明回调参数
    无

    Slots

    插槽说明作用域参数
    defaultDescriptions.Item 子节点，data 为空时使用；横向布局只识别直接子节点。any
    itemKey每个数据项的 key，默认渲染 item.key。DescriptionsSlotProps
    value每个数据项的值，默认渲染 item.value。DescriptionsSlotProps

    Exposes

    名称说明类型
    无

    class、style 与原生属性经 attrs 传入，落在 Descriptions 的根元素上。

    DataItem

    属性说明类型默认值
    key键值，自定义渲染使用 #itemKey 插槽string | number-
    value属性值，自定义渲染使用 #value 插槽string | number-
    hidden该数据是否需要展示boolean-
    span单元格应跨越的列数number1
    keyStylekey 的自定义样式，可用于设置宽度、对齐方式等StyleValue-

    DescriptionItem

    Props

    属性说明类型默认值
    hidden是否隐藏该项。booleanfalse
    span单元格跨越的列数。numberundefined
    keyStylekey 的自定义样式。StyleValueundefined

    Events

    事件说明回调参数
    无

    Slots

    插槽说明作用域参数
    default值。any
    itemKey键。any

    Exposes

    名称说明类型
    无

    纵向布局下，class、style 与原生属性经 attrs 落在 Item 外部 wrapper tr 上；横向布局下 Item 只输出单元格，attrs 无处落点。

    文案规范

    • 字段名和值都按 Sentence case 原则书写大小写

    设计变量

    下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。
    Sass 变量值用法
    $font-descriptions-lineHeight20px文字行高
    $font-descriptions_value-fontWeight$font-weight-bold双行显示 value 文字字重
    $spacing-descriptions_th-paddingRight$spacing-loose普通显示 key 右侧内边距
    $spacing-descriptions_item-paddingBottom$spacing-base-tight普通显示 item 底部内边距
    $spacing-descriptions_item_small-paddingRight48px双行显示 item 右侧内边距 - 小尺寸
    $spacing-descriptions_item_medium-paddingRight60px双行显示 item 右侧内边距 - 中尺寸
    $spacing-descriptions_item_large-paddingRight80px双行显示 item 右侧内边距 - 大尺寸
    $spacing-descriptions_key_medium-paddingBottom$spacing-extra-tight双行显示 key 底部内边距 - 中尺寸
    $spacing-descriptions_key_large-paddingBottom$spacing-extra-tight双行显示 key 底部内边距 - 大尺寸
    $color-descriptions_key-text-defaultvar(--semi-color-text-2)key 文字颜色
    $color-descriptions_value-text-defaultvar(--semi-color-text-0)value 文字颜色
    $spacing-descriptions_value_plain-paddingLeft8px普通显示 plain 模式下 value 左侧内边距
    $spacing-descriptions_item_double-padding0双行显示右侧 item 内边距
    $font-descriptions_key_small-fontSize$font-size-small双行显示 key 文字大小 - 小尺寸
    $font-descriptions_value_small-fontSize$font-size-header-6双行显示 value 文字大小 - 小尺寸
    $font-descriptions_key_medium-fontSize$font-size-regular双行显示 key 文字大小 - 小尺寸
    $font-descriptions_value_medium-fontSize$font-size-header-4双行显示 value 文字大小 - 小尺寸
    $font-descriptions_key_large-fontSize$font-size-regular双行显示 key 文字大小 - 小尺寸
    $font-descriptions_value_large-fontSize$font-size-header-2双行显示 value 文字大小 - 小尺寸