# 元数据列表

## 使用方法

`MetadataList` 排列一组标签和值。`MetadataListItem` 是其中一对。单列时标签在值旁边。多列或数字列数时，标签叠在值上面，轨道按列数重复。`columns="multi"` 使用 `repeat(auto-fill, minmax(280px, 1fr))`。

`orientation="horizontal"` 把每一对排成可换行的一行，并忽略 `columns`、`label` 和 `maxNumOfItems`。`maxNumOfItems` 把多出来的项收进「显示更多」。`label.width` 只在标签位于值旁边时生效。长标签和长值会在单词内部断开，避免把窄容器撑开。写在 `MetadataListItem` 上的其余属性，并排时落在 `dt` 上，标签叠在值上面时落在包住这一对的那一层上。

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList>
    <MetadataListItem label="名称">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="状态">
      使用中
    </MetadataListItem>
  </MetadataList>
</template>
```

## 建议

| 建议 | 做法 |
| --- | --- |
| 推荐 | 标签写短。读者要看的是值。 |
| 推荐 | 窄的详情栏用单列，宽度够放好几对时用 `multi`。 |
| 推荐 | 字段比页面一次能放下的多时，设置 `maxNumOfItems`。 |
| 避免 | 把一整句放进标签。标签轨道是按短名字留的。 |
| 避免 | 水平排列时还指望列数生效。水平布局会忽略列数。 |

### 结构

- **标题**: 元数据列表的可选标题。
- **标签**: 每条元数据的键名。
- **元数据**: 以各种格式显示的值。
- **展开控制**: 列表的收起和展开控件。

## 示例

### MetadataList — 基础

单列的键值元数据。

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList>
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — 可折叠

超过设定条数后，用「显示更多」把其余项收起来。

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList :max-num-of-items="3">
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
    <MetadataListItem label="Updated">
      Mar 26, 2026
    </MetadataListItem>
    <MetadataListItem label="Priority">
      Tier 1
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — 水平

水平排开，适合一行里放几项紧凑信息。

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
</script>

<template>
  <MetadataList orientation="horizontal">
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Type">
      Premium
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
  </MetadataList>
</template>
```

### MetadataList — 多列

多列网格，其中一项的值是标签。

```vue
<script setup lang="ts">
import { MetadataList, MetadataListItem } from '@astryx-vue/core/MetadataList'
import { HStack } from '@astryx-vue/core/Stack'
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <MetadataList columns="multi">
    <MetadataListItem label="Name">
      MetadataList
    </MetadataListItem>
    <MetadataListItem label="Status">
      Active
    </MetadataListItem>
    <MetadataListItem label="Owner">
      Joey
    </MetadataListItem>
    <MetadataListItem label="Created">
      Jan 15, 2026
    </MetadataListItem>
    <MetadataListItem label="Tags">
      <HStack :gap="1">
        <Token label="component" />
        <Token label="xds" />
      </HStack>
    </MetadataListItem>
    <MetadataListItem label="Priority">
      Tier 1
    </MetadataListItem>
  </MetadataList>
</template>
```

## 属性

### MetadataList

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `columns` | `'multi' \| 'single' \| number` | `'single'` | 单列时标签在值旁边。数字或 `multi` 把标签叠在值上面。`multi` 按至少 280px 的轨道自动填充。 |
| `label` | `{ position?: 'start' \| 'top', width?: number \| string }` | 单列在旁边，其余在上方 | `width` 决定标签轨道宽度，只在标签位于值旁边时生效。数字按像素计。 |
| `maxNumOfItems` | `number` | - | 超出这个数量的项收进「显示更多」。水平排列时忽略。 |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | 水平排列会换行，并忽略 `columns`、`label` 和 `maxNumOfItems`。 |
| `title` | `string` | - | 列表上方的纯文本标题。复杂内容用 `title` 插槽。 |

### MetadataListItem

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | - | 字段名。默认插槽是值。`icon` 插槽画在标签前面。 |

## 主题

`packages/core/styles/metadata-list.css` 读取语义 token。标签是 medium 字重的正文字号，颜色是次要文字。值是主要文字色。左右排列时行距 8px、列距 16px，值这一行至少 24px 高。上下堆叠时间距 2px。标题下方留 12px。「显示更多」使用强调色。

## 原生属性

其余属性落到根元素 `<dl>`，以及每一项的 `<dt>` 或包裹元素上。