> ## 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.

# 布局组件

## 布局组件

QWidget 的布局全部由元素嵌套完成，没有 `Width` / `Height` / `Margin` 这类像素属性；尺寸由主页网格和布局容器决定。

## 容器类型

| 元素 | 作用 | 视觉 |
| :- | :- | :- |
| `Container` | 卡片/面板，支持边框、背景、圆角、内边距 | 有 |
| `Row` | 横向排列 | 无 |
| `Column` | 纵向排列 | 无 |
| `Grid` | 多列网格 | 无 |
| `Tabs` | 选项卡 | 页签栏 |
| `List` | 数组列表 | 由子项决定 |
| `If` | 条件渲染 | 无 |

## Container

```xml theme={null}
<Container Direction="Column" Padding="4" Gap="3"
           Border="True" Background="Card" Radius="Lg"
           Align="Stretch" Justify="Start">
  ...
</Container>
```

| 属性 | 取值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Direction` | `Row` / `Column` | `Column` | 主轴方向 |
| `Gap` | 0–8 | `0` | 子元素间距 |
| `Padding` | 0–8 | `0` | 内边距 |
| `Align` | `Start` / `Center` / `End` / `Stretch` | — | 交叉轴对齐 |
| `Justify` | `Start` / `Center` / `End` / `Between` | — | 主轴对齐 |
| `Border` | `True` / `False` | `True` | 是否显示边框 |
| `Background` | `Transparent` / `Card` / `Muted` / `Primary` | `Card` | 背景 |
| `Radius` | `None` / `Sm` / `Md` / `Lg` / `Full` | `Lg` | 圆角 |

`Container` 适合做卡片；只想排版不想加视觉时用 `Row` / `Column`。

## Row / Column

```xml theme={null}
<Row Gap="2" Align="Center" Wrap="True">
  <Button Text="A" />
  <Button Text="B" />
  <Button Text="C" />
</Row>
```

| 属性 | 取值 | 默认 |
| :- | :- | :- |
| `Gap` | 0–8 | `0` |
| `Padding` | 0–8 | `0` |
| `Align` | `Start` / `Center` / `End` / `Stretch` | — |
| `Justify` | `Start` / `Center` / `End` / `Between` | — |
| `Wrap` | `True` / `False` | `False` |

## Grid

```xml theme={null}
<Grid Columns="2" Gap="2" Padding="2">
  <Button Text="左上" />
  <Button Text="右上" />
  <Button Grid.Row="1" Grid.Column="0" Text="左下" />
  <Button Grid.Row="1" Grid.Column="1" Text="右下" />
</Grid>
```

| 属性 | 取值 | 说明 |
| :- | :- | :- |
| `Columns` | 1–6，必填 | 列数 |
| `Gap` | 0–8 | 行列间距 |
| `Padding` | 0–8 | 内边距 |
| `Align` / `Justify` | 同容器 | 对齐 |

子元素支持附加属性：

* `Grid.Row`：0 起
* `Grid.Column`：0 起
* `Grid.RowSpan`：默认 1
* `Grid.ColumnSpan`：默认 1

附加属性可写成属性或属性元素：

```xml theme={null}
<Button Grid.Row="1" Grid.Column="0" Text="A" />
<Button>
  <Grid.Row>1</Grid.Row>
  <Grid.Column>1</Grid.Column>
  <Button.Text>B</Button.Text>
</Button>
```

不写行列时按流式顺序自动填充。

## Tabs

```xml theme={null}
<Tabs Default="0">
  <TabItem Title="公告">
    <Text Value="公告内容" />
  </TabItem>
  <TabItem Title="快捷入口">
    <Grid Columns="2" Gap="2">
      <Button Text="启动" OnClick="Launch" />
      <Button Text="实例" OnClick="Navigate" To="Instances" />
    </Grid>
  </TabItem>
</Tabs>
```

* `Tabs.Default`：默认选中索引，0 起。
* `TabItem.Title`：页签标题，必填。
* 选中状态只存在内存，不持久化。
* 所有 `TabItem` 都会在挂载时解析；`Data` 也是预取的，切换页签不闪。

## List

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

* `Items`：数组路径，必填；可写 `{Data.Items}` 或 `Data.Items`。
* `As`：项变量名，默认 `item`（大小写敏感）。
* `ListItem`：必须且只能一个，内部只能有一个根元素。
* 项内可用 `{Item.Xxx}` 和 `{Index}`。
* 最多渲染 200 项；空数组显示 `EmptyText`。

## If

```xml theme={null}
<If Test="{State.Error}">
  <Text Value="加载失败" Color="Destructive" />
</If>
```

`Test` 为真值判断：`False` / 空字符串 / `0` / `null` / 空数组视为假。

## Divider / Spacer

```xml theme={null}
<Divider />
<Spacer Size="12" />
```

* `Divider`：1px 分隔线。
* `Spacer`：固定像素间距；内部实现同时设置宽高，横向/纵向都可使用。

## Page 内容

`Container`、`Row`、`Column`、`Grid`、`If`、`Tabs`、`TabItem`、`List`、`ListItem` 都可以用 `Content="{PageName}"` 引用 Page，替代内联子节点：

```xml theme={null}
<Resources>
  <Resource Type="Page" Name="InfoPage">
    <Text Value="来自 Page" />
  </Resource>
</Resources>

<Container Content="{InfoPage}" />
```

`Content` 与子元素互斥；详见 [Page 系统](https://docs.qomicex.top/guide/custom-widget/advanced/pages.md)。

## 自适应尺寸

自定义组件渲染在主页网格单元内，宽度和高度随用户拖动改变：

* 顶层 `Container` / `Row` / `Column` / `Grid` / `Tabs` / `List` 会拉伸到网格单元高度；`Text`、`Button` 等普通节点保持内容高度。
* 整个组件在内容超出网格单元时滚动；顶层 `List` 和 `Tabs` 的内容区会优先自己滚动。
* 用单个顶层 `Container` 或 `Column` 包住整张卡片，背景/边框才能铺满；多个顶层节点会按内容高度排列，底部可能留空。
* `Justify="Between"` 可把顶部和底部内容分开；`Row Wrap="True"` 适合宽度变窄时换行。
* `Grid` 的列数固定，不会随宽度自动改变；窄卡片请减少 `Columns` 或改用 `Row Wrap`。

### 声明式断点

```xml theme={null}
<Text When="Size.Width &lt;= 1" Value="窄" />
<Grid When="Size.Width &gt;= 2" Columns="2">...</Grid>
```

`When` 支持 `Size.Width` / `Size.Height` / `Size.PixelWidth` / `Size.PixelHeight`，运算符 `<`、`<=`、`>`、`>=`、`==`、`!=`，可用 `and` / `or` 连接。XML 属性里的 `<` 写成 `&lt;`。

### 脚本式断点

```xml theme={null}
<Triggers>
  <Trigger Event="Resize" Function="OnResize" />
</Triggers>

<Function Name="OnResize">
  <Function.Script><![CDATA[
    await Host.SetProperty("Title", "Visible", Size.Width > 1);
    await Host.SetProperty("InfoGrid", "Columns", Size.Width >= 3 ? 3 : 2);
    return {};
  ]]></Function.Script>
</Function>
```

`Resize` 在尺寸变化后防抖触发；首次布局可在 `Loaded` 函数里读取 `Size`。

## 常见布局

**左右分栏**

```xml theme={null}
<Row Gap="3">
  <Container Padding="3" Direction="Column">左侧</Container>
  <Container Padding="3" Direction="Column">右侧</Container>
</Row>
```

**两列卡片**

```xml theme={null}
<Grid Columns="2" Gap="2">
  <Container Padding="3"><Text Value="A" /></Container>
  <Container Padding="3"><Text Value="B" /></Container>
</Grid>
```

## 限制与坑

* 容器内容就是子元素；不要在容器里直接写裸文本。
* `Grid` 的附加属性只对直接子元素生效。
* 没有像素宽高，组件尺寸由主页网格的格子决定；需要内部滚动时由外层组件处理。
* 过深嵌套、大量列表项会拖慢渲染；单组件元素上限 1000。


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