描述列表 - Semi Design Next

代码演示

如何引入

import { Descriptions } from '@fibrous/semi-ui-react';

基本用法

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

key、value 均支持 ReactNode 类型，你可以传入字符串或更高自由度的 ReactNode 自由定制渲染效果

实际用户数量	1,480,000
7天留存	98%
安全等级	3级
垂类标签	电商
认证状态	未认证

代码

import { IconArrowUp } from '@fibrous/semi-icons-react';
import { Descriptions, Tag } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        {
            key: '7天留存',
            value: (
                <div>
                    98%
                    <IconArrowUp size="small" style={{ color: 'var(--semi-color-success)', marginLeft: '2px' }} />
                </div>
            ),
        },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: <Tag style={{ margin: 0 }}>电商</Tag> },
        { key: '认证状态', value: '未认证' },
    ];
    return <Descriptions data={data} />;
}

设置对齐方式

可以通过设置 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级

垂类标签:

电商

认证状态:未认证

代码

import { Descriptions, Tag, Card } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        { key: '7天留存', value: '98%' },
        { key: '安全等级', value: '3级' },
        { key: '垂类标签', value: <Tag style={{ margin: 0 }}>电商</Tag> },
        { key: '认证状态', value: '未认证' },
    ];
    const style = {
        margin: '10px',
    };
    return (
        <>
            <div style={{ display: 'flex', flexWrap: 'wrap' }}>
                <Card shadows="always" style={style}>
                    <Descriptions align="center" data={data} />
                </Card>
                <Card shadows="always" style={style}>
                    <Descriptions align="justify" data={data} />
                </Card>
                <Card shadows="always" style={style}>
                    <Descriptions align="left" data={data} />
                </Card>
                <Card shadows="always" style={style}>
                    <Descriptions align="plain" data={data} />
                </Card>
            </div>
        </>
    );
}

Descriptions.Item 写法

除了通过 props.data 声明数据外，还可以通过 Children JSX 写法声明数据

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

实际用户数量	1,480,000
7天留存	98%
安全等级	3级
垂类标签	电商
认证状态	未认证

代码

import { Descriptions } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    return (
        <Descriptions>
            <Descriptions.Item itemKey="实际用户数量">1,480,000</Descriptions.Item>
            <Descriptions.Item itemKey="7天留存">98%</Descriptions.Item>
            <Descriptions.Item itemKey="安全等级">3级</Descriptions.Item>
            <Descriptions.Item itemKey="垂类标签">电商</Descriptions.Item>
            <Descriptions.Item itemKey="认证状态">未认证</Descriptions.Item>
        </Descriptions>
    );
}

设置布局模式

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

抖音号:SemiDesign
主播类型:自由主播
安全等级:3级
垂类标签: 互联网资讯编程
作品数量:88888888
认证状态:这是一个很长很长很长很长很长很长很长很长很长的值

代码

import { Descriptions, Space, Tag } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data = [
        { key: '抖音号', value: 'SemiDesign' },
        { key: '主播类型', value: '自由主播' },
        { key: '安全等级', value: '3级' },
        {
            key: '垂类标签',
            value: (
                <Space>
                    <Tag size="small" shape="circle" color="amber">
                        互联网资讯
                    </Tag>
                    <Tag size="small" shape="circle" color="violet">
                        编程
                    </Tag>
                </Space>
            ),
        },
        { key: '作品数量', value: '88888888' },
        { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
    ];
    return (
        <>
            <Descriptions layout="vertical" align="plain" data={data} column={4} />
        </>
    );
}

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

抖音号:SemiDesign	主播类型:自由主播	安全等级:3级	垂类标签: 编程	作品数量:88888888
认证状态:这是一个很长很长很长很长很长很长很长很长很长的值			上次直播时间:2024-05-01 12:00:00

代码

import { Descriptions, Tag } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data = [
        { key: '抖音号', value: 'SemiDesign' },
        { key: '主播类型', value: '自由主播' },
        { key: '安全等级', value: '3级' },
        {
            key: '垂类标签',
            value: (
                <Tag size="small" shape="circle" color="violet">
                    编程
                </Tag>
            ),
        },
        { key: '作品数量', value: '88888888' },
        { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
        { key: '上次直播时间', value: '2024-05-01 12:00:00', span: 3 },
    ];
    return (
        <>
            <Descriptions layout="horizontal" align="plain" data={data} column={5} />
        </>
    );
}

双行显示

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

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

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

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

代码

import { IconArrowUp } from '@fibrous/semi-icons-react';
import { Descriptions } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data = [
        { key: '实际用户数量', value: '1,480,000' },
        {
            key: '7天留存',
            value: (
                <span>
                    98%
                    <IconArrowUp size="small" style={{ color: 'red', marginLeft: '4px' }} />
                </span>
            ),
        },
        { key: '安全等级', value: '3级' },
    ];
    const style = {
        boxShadow: 'var(--semi-shadow-elevated)',
        backgroundColor: 'var(--semi-color-bg-2)',
        borderRadius: '4px',
        padding: '10px',
        marginRight: '20px',
        width: '600px',
    };
    return (
        <div>
            <Descriptions data={data} row size="small" style={style} />
            <br />
            <Descriptions data={data} row style={style} />
            <br />
            <Descriptions data={data} row size="large" style={style} />
        </div>
    );
}

自定义 Key 样式

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

用户名	张三
电子邮箱	zhangsan@example.com
联系电话	138-0000-0000
地址	北京市朝阳区

代码

import { Descriptions, type DescriptionsData } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    const data: DescriptionsData[] = [
        { key: '用户名', value: '张三', keyStyle: { width: 100, textAlign: 'right' } },
        { key: '电子邮箱', value: 'zhangsan@example.com', keyStyle: { width: 100, textAlign: 'right' } },
        { key: '联系电话', value: '138-0000-0000', keyStyle: { width: 100, textAlign: 'right' } },
        { key: '地址', value: '北京市朝阳区', keyStyle: { width: 100, textAlign: 'right' } },
    ];
    return <Descriptions data={data} align="center" />;
}

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

姓名	李四
年龄	28
职业	前端工程师

代码

import { Descriptions } from '@fibrous/semi-ui-react';

export default function DescriptionsDemo() {
    return (
        <Descriptions align="center">
            <Descriptions.Item itemKey="姓名" keyStyle={{ width: 120, color: 'var(--semi-color-primary)' }}>
                李四
            </Descriptions.Item>
            <Descriptions.Item itemKey="年龄" keyStyle={{ width: 120, color: 'var(--semi-color-primary)' }}>
                28
            </Descriptions.Item>
            <Descriptions.Item itemKey="职业" keyStyle={{ width: 120, color: 'var(--semi-color-primary)' }}>
                前端工程师
            </Descriptions.Item>
        </Descriptions>
    );
}

API 参考

Descriptions

Props

属性	说明	类型	默认值
align	对齐方式，可选 `center`、`justify`、`left` 或 `plain`，`left` 指起始侧；`row` 为 `true` 时无效。	`DescriptionsAlign`	`"center"`
children	`data` 为空时渲染的内容，通常为 `Descriptions.Item`。	`React.ReactNode`	-
className	根元素（`div`）的类名。	`string`	-
column	横向布局下每行的总列数。	`number`	`3`
data	列表显示的数据；为空时渲染 `children`。	`Data[]`	`[]`
layout	布局模式，可选 `vertical` 或 `horizontal`。	`DescriptionLayout`	`"vertical"`
ref	根元素（`div`）的引用。	`Type`	-
row	是否双行显示，为 `true` 时 `align` 无效。	`boolean`	`false`
size	双行显示时的尺寸，可选 `small`、`medium` 或 `large`。	`DescriptionsSize`	`"medium"`
style	根元素（`div`）的样式。	`React.CSSProperties`	-

className、style、ref 与原生属性（如 id、data-*、aria-*）落在 Descriptions 的根元素（div）上。

DataItem

属性	说明	类型	默认值
key	键值	ReactNode	-
value	属性值	ReactNode \| (() => ReactNode)	-
hidden	该数据是否需要展示	boolean	-
span	单元格应跨越的列数	number	1
keyStyle	key 的自定义样式，可用于设置宽度、对齐方式等	CSSProperties	-

DescriptionItem

Props

属性	说明	类型	默认值
children	值，可以是 `ReactNode`，也可以是渲染时调用的函数。	`Type`	-
className	纵向布局下外部 wrapper `tr` 的类名；横向布局下无效。	`string`	-
hidden	是否隐藏该项。	`boolean`	-
itemKey	键，可以是 `ReactNode`。	`React.ReactNode`	-
keyStyle	key 的自定义样式，可用于设置宽度、对齐方式等。	`React.CSSProperties`	-
ref	纵向布局下外部 wrapper `tr` 的引用；横向布局下无效。	`Type`	-
span	单元格跨越的列数，未设置时为 1。	`number`	-
style	纵向布局下外部 wrapper `tr` 的样式；横向布局下无效。	`React.CSSProperties`	-

纵向布局下，className、style、ref 与原生属性（如 id、data-*、aria-*）落在 Item 外部 wrapper tr 上；横向布局下 Item 只输出单元格，这些属性无处落点。

文案规范

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

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$font-descriptions-lineHeight	20px	文字行高
$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-paddingRight	48px	双行显示 item 右侧内边距 - 小尺寸
$spacing-descriptions_item_medium-paddingRight	60px	双行显示 item 右侧内边距 - 中尺寸
$spacing-descriptions_item_large-paddingRight	80px	双行显示 item 右侧内边距 - 大尺寸
$spacing-descriptions_key_medium-paddingBottom	$spacing-extra-tight	双行显示 key 底部内边距 - 中尺寸
$spacing-descriptions_key_large-paddingBottom	$spacing-extra-tight	双行显示 key 底部内边距 - 大尺寸
$color-descriptions_key-text-default	var(--semi-color-text-2)	key 文字颜色
$color-descriptions_value-text-default	var(--semi-color-text-0)	value 文字颜色
$spacing-descriptions_value_plain-paddingLeft	8px	普通显示 plain 模式下 value 左侧内边距
$spacing-descriptions_item_double-padding	0	双行显示右侧 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 文字大小 - 小尺寸