组件
    展示类

    描述列表

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

    代码演示

    如何引入

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

    基本用法

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

    data 中的 key、value 只接受字符串或数字。需要自定义渲染时，传入 renderKey(item, index)、renderValue(item, index)，其中 index 是该项在 data 中的位置（包含 hidden 的项）；隐藏的项不调用它们。

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

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

const renderValue = (item: DescriptionsData, index: number) => {
    if (index === 1) {
        return (
            <div>
                {item.value}
                <IconArrowUp size="small" style={{ color: 'var(--semi-color-success)', 'margin-left': '2px' }} />
            </div>
        );
    }
    return index === 3 ? <Tag style={{ margin: '0' }}>{item.value}</Tag> : item.value;
};

export default function DescriptionsDemo() {
    return <Descriptions data={data} renderValue={renderValue} />;
}

    设置对齐方式

    可以通过设置 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 { For } from 'solid-js';
import { Card, Descriptions, type DescriptionsAlign, type DescriptionsData, Tag } from '@fibrous/semi-ui-solid';

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

const renderValue = (item: DescriptionsData, index: number) => (index === 3 ? <Tag style={{ margin: '0' }}>{item.value}</Tag> : item.value);

const aligns: DescriptionsAlign[] = ['center', 'justify', 'left', 'plain'];

const cardStyle = { margin: '10px' };

export default function DescriptionsDemo() {
    return (
        <div style={{ display: 'flex', 'flex-wrap': 'wrap' }}>
            <For each={aligns}>
                {(align) => (
                    <Card shadows="always" style={cardStyle}>
                        <Descriptions align={align} data={data} renderValue={renderValue} />
                    </Card>
                )}
            </For>
        </div>
    );
}

    Descriptions.Item 写法

    除了通过 data 声明数据外，还可以在 Descriptions 的子节点中写 Descriptions.Item 声明数据：itemKey 为键，子节点为值。

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

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

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, type DescriptionsData, Space, Tag } from '@fibrous/semi-ui-solid';

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

const renderValue = (item: DescriptionsData, index: number) =>
    index === 3 ? (
        <Space>
            <Tag size="small" shape="circle" color="amber">
                互联网资讯
            </Tag>
            <Tag size="small" shape="circle" color="violet">
                编程
            </Tag>
        </Space>
    ) : (
        item.value
    );

export default function DescriptionsDemo() {
    return <Descriptions layout="vertical" align="plain" data={data} column={4} renderValue={renderValue} />;
}

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

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

const data: DescriptionsData[] = [
    { 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 },
];

const renderValue = (item: DescriptionsData, index: number) =>
    index === 3 ? (
        <Tag size="small" shape="circle" color="violet">
            {item.value}
        </Tag>
    ) : (
        item.value
    );

export default function DescriptionsDemo() {
    return <Descriptions layout="horizontal" align="plain" data={data} column={5} renderValue={renderValue} />;
}

    双行显示

    可以通过设置 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-solid';
import { Descriptions, type DescriptionsData } from '@fibrous/semi-ui-solid';

const data: DescriptionsData[] = [
    { key: '实际用户数量', value: '1,480,000' },
    { key: '7天留存', value: '98%' },
    { key: '安全等级', value: '3级' },
];

const renderValue = (item: DescriptionsData, index: number) =>
    index === 1 ? (
        <span>
            {item.value}
            <IconArrowUp size="small" style={{ color: 'red', 'margin-left': '4px' }} />
        </span>
    ) : (
        item.value
    );

const style = {
    'box-shadow': 'var(--semi-shadow-elevated)',
    'background-color': 'var(--semi-color-bg-2)',
    'border-radius': '4px',
    padding: '10px',
    'margin-right': '20px',
    width: '600px',
};

export default function DescriptionsDemo() {
    return (
        <div>
            <Descriptions data={data} renderValue={renderValue} row size="small" style={style} />
            <br />
            <Descriptions data={data} renderValue={renderValue} row style={style} />
            <br />
            <Descriptions data={data} renderValue={renderValue} 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-solid';

const keyStyle = { width: '100px', 'text-align': 'right' } as const;

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

export default function DescriptionsDemo() {
    return <Descriptions data={data} align="center" />;
}

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

    姓名李四
    年龄28
    职业前端工程师
    代码
    import { Descriptions } from '@fibrous/semi-ui-solid';

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

export default function DescriptionsDemo() {
    return (
        <Descriptions align="center">
            <Descriptions.Item itemKey="姓名" keyStyle={keyStyle}>
                李四
            </Descriptions.Item>
            <Descriptions.Item itemKey="年龄" keyStyle={keyStyle}>
                28
            </Descriptions.Item>
            <Descriptions.Item itemKey="职业" keyStyle={keyStyle}>
                前端工程师
            </Descriptions.Item>
        </Descriptions>
    );
}

    API 参考

    Descriptions

    Props

    属性说明类型默认值
    align对齐方式，可选 center、justify、left、plain；row 为 true 时无效。DescriptionsAlign"center"
    column横向布局下每行的总列数。number3
    data列表显示的数据；为空时使用 Descriptions.Item 子节点。Data[]-
    layout布局模式，可选 vertical、horizontal。DescriptionsLayout"vertical"
    renderKey渲染 data 每一项的键，参数为 (item, index)，index 包含隐藏项；隐藏项不调用。不传时显示 item.key。Type(item: Data, index: number) => JSX.Element-
    renderValue渲染 data 每一项的值，参数为 (item, index)，index 包含隐藏项；隐藏项不调用。不传时显示 item.value。Type(item: Data, index: number) => JSX.Element-
    row是否双行显示。booleanfalse
    size双行显示时的尺寸，可选 small、medium、large。DescriptionsSize"medium"

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

    DataItem

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

    DescriptionItem

    Props

    属性说明类型默认值
    children值，可以是 JSX 元素，也可以是渲染时调用的函数。TypeJSX.Element | (() => JSX.Element)-
    hidden是否隐藏该项。boolean-
    itemKey键，可以是 JSX 元素。JSX.Element-
    keyStylekey 的自定义样式，可以是样式对象或字符串。JSX.CSSProperties | string-
    span单元格跨越的列数。number-

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

    文案规范

    • 字段名和值都按 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 文字大小 - 小尺寸