> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# List

## List

按数组渲染列表。必须且只能包含一个 `ListItem` 作为项模板。

## 签名

```xml theme={null}
<List Items="{Data.News.Items}" As="Item" Gap="2" EmptyText="暂无内容">
  <ListItem>
    <Text Value="{Item.Title}" />
  </ListItem>
</List>
```

## 属性

| 属性 | 类型 | 必填 | 默认 | 说明 |
| :- | :- | :- | :- | :- |
| `Items` | path | 是 | — | 数组路径 |
| `As` | identifier | 否 | `item` | 项变量名 |
| `Gap` | 0–8 | 否 | `0` | 项间距 |
| `EmptyText` | string | 否 | — | 空数组提示 |

## 内容

* `ListItem` 必须且只能一个。
* `ListItem` 内必须且只能一个根元素。
* 项内可绑定 `{Item.*}` 与 `{Index}`。

```xml theme={null}
<List Items="{Data.News.Items}" As="News">
  <ListItem>
    <Container Padding="2" Gap="1">
      <Text Value="{News.Title}" Weight="Semibold" />
      <Text Value="{Index}" Size="Xs" Color="Muted" />
    </Container>
  </ListItem>
</List>
```

## 运行时行为

* 解析 `Items` 路径；非数组显示空态。
* 最多渲染 200 项，超出截断。
* 每项使用独立作用域，`Item`/`Index` 不污染外部。
* 列表项不提供选中/点击事件；需要点击时在项内放 `Button`/`Link`。

## 示例：新闻列表

```xml theme={null}
<List Items="{Data.News.Items}" As="Item" Gap="2" EmptyText="暂无新闻">
  <ListItem>
    <Row Gap="2" Align="Center">
      <Text Value="{Item.Title}" Size="Sm" Clamp="2" />
      <Button Text="阅读" Size="Sm" Variant="Ghost"
              OnClick="OpenUrl" Url="{Item.Url}" />
    </Row>
  </ListItem>
</List>
```

## 坑

* `Items` 必须指向数组；对象会显示空态。
* 列表项没有虚拟滚动；超过 200 项被截断。
* 项模板只能有一个根元素，多个元素请用 `Column`/`Row`/`Container` 包起来。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.