> ## 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 的属性值都使用大驼峰；布尔值写 `True` / `False`，不是 `true` / `false`。\
本文集中列出所有枚举值、数字范围和默认值；组件页只说明该元素支持哪些属性。

## 通用节点属性

所有可视节点都支持：

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Target` | 任意唯一 identifier | — | 脚本定位键，不能与其它节点重复 |
| `Visible` | `True` / `False` | `True` | `False` 时不渲染，可由脚本切换 |
| `When` | 尺寸条件表达式 | — | 条件不满足时不渲染，见下方“尺寸条件” |

### 尺寸条件 `When`

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

| 字段 | 值 |
| :- | :- |
| `Size.Width` / `Size.Height` | 网格列数 / 行数 |
| `Size.PixelWidth` / `Size.PixelHeight` | 实际像素宽高 |
| 运算符 | `<`、`<=`、`>`、`>=`、`==`、`!=` |
| 连接词 | `and` / `or`，不支持括号 |

XML 属性中的 `<` 必须写成 `&lt;`，`<=` 写成 `&lt;=`。没有空格时也可以写 `Size.Width<=1`，但推荐保留空格。

## 布局

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Direction` | `Row` / `Column` | `Column` | 主轴方向 |
| `Align` | `Start` / `Center` / `End` / `Stretch` | — | 交叉轴对齐 |
| `Justify` | `Start` / `Center` / `End` / `Between` | — | 主轴对齐 |
| `Wrap` | `True` / `False` | `False` | 是否换行 |
| `Border` | `True` / `False` | `True` | 是否显示边框 |
| `Background` | `Transparent` / `Card` / `Muted` / `Primary` | `Card` | 背景样式 |
| `Radius` | `None` / `Sm` / `Md` / `Lg` / `Full` | `Lg` | 圆角 |
| `Gap` / `Padding` | 整数 `0`–`8` | `0` | 间距档位，不是像素 |
| `Columns` | 整数 `1`–`6` | `1` | `Grid` 列数 |
| `Grid.Row` / `Grid.Column` | 整数，0 起 | 自动 | `Grid` 内位置 |
| `Grid.RowSpan` / `Grid.ColumnSpan` | 正整数 | `1` | 跨行 / 跨列 |
| `Content` | `{PageName}` 或 `{Resources.PageName}` | — | 引用 Page；所有布局/容器、Dialog、Tabs、List 可用 |
| `UpdateTTL` | 秒 / `Default` / `Immediately` / `PreLaunch` / `PreLoad` / `None` | `Default` | 远程 XML 更新检查间隔 |
| `RefreshTTL` | 秒 / 同上 | `None` | 重新拉取数据的间隔，保留组件状态 |
| `ImageHosts` | 逗号分隔域名 / `*.example.com` / `*` | — | 动态 Image/Media 的 HTTPS 主机白名单 |

## 文本

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Size` | `Xs` / `Sm` / `Md` / `Lg` / `Xl` / `2Xl` | `Md` | 字号 |
| `Weight` | `Normal` / `Medium` / `Semibold` / `Bold` | `Normal` | 字重 |
| `Color` | `Default` / `Muted` / `Primary` / `Destructive` | `Default` | 文字颜色 |
| `Align` | `Start` / `Center` / `End` | — | 文本对齐 |
| `Clamp` | 整数 `1`–`6` | — | 最大行数 |

## 按钮与链接

| 属性 | 可选值 | 默认 | 适用 |
| :- | :- | :- | :- |
| `Size` | `Sm` / `Md` / `Lg` | `Md` | `Button` |
| `Variant` | `Default` / `Secondary` / `Outline` / `Ghost` / `Destructive` / `Link` | `Default` | `Button` |
| `OnClick` / `OnChange` / `Action` | 见[动作参考](https://docs.qomicex.top/guide/custom-widget/reference/actions.md) | — | 动作名 |
| `To` | `Instances` / `Downloads` / `Accounts` / `ResourceCenter` / `Settings` / `Connect` / `Running` | — | `Navigate` 目标 |
| `Folder` | `Game` / `Logs` / `Data` / `Screenshots` | — | `OpenFolder` 目标 |
| `Source` | `Curseforge` / `Modrinth` / `Ftb` | — | `Install` 来源 |
| `Category` | `Mod` / `Modpack` / `Shader` / `Resourcepack` / `Datapack` / `Save` | — | `Install` 分类 |
| `ShortcutKeys` | 一个或多个 `ShortcutKey Key="..."` | — | `Button` / `Link` 快捷键 |

`Size` 在 `Text` 和 `Button` 上不是同一组值：`Text` 支持 `Xs`–`2Xl`，`Button` 只支持 `Sm/Md/Lg`。

## Dialog

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Name` | identifier | 必填 | 供 `{Name.Show}` / `{Name.Hide}` 使用 |
| `Title` | string | — | 标题 |
| `Width` | `Sm` / `Md` / `Lg` / `Xl` / `Full` | `Md` | 对话框宽度 |
| `Size` | 同上 | `Md` | `Width` 别名 |
| `Content` | `{PageName}` 或 `{Resources.PageName}` | — | 引用 Page，不能与内联子元素同时使用 |

## Effects

| 元素 | 主要属性 | 说明 |
| :- | :- | :- |
| `ShadowEffect` | `Radius` / `Color` / `OffsetX` / `OffsetY` / `Spread` / `Inset` | 阴影，可堆叠 |
| `BlurEffect` | `Radius` | 模糊 |
| `OpacityEffect` | `Value` | 透明度 0–1 |
| `ScaleEffect` | `Value` | 缩放 |
| `RotateEffect` | `Angle` | 旋转角度 |

所有可视节点都支持 `<节点.Effects>`；Trigger 的 `<Trigger.Effects>` 用 `Target` 指定目标。

## 输入控件

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Multiline` | `True` / `False` | `False` | `TextBox` 多行 |
| `Password` | `True` / `False` | `False` | 密码输入 |
| `ReadOnly` | `True` / `False` | `False` | 只读 |
| `Checked` | `True` / `False` | `False` | `CheckBox` 初始状态 |
| `MaxLength` | 整数 `0`–`10000` | — | 最大长度 |
| `Min` / `Max` | 数字 | `0` / `100` | `Slider` 范围 |
| `Step` | 数字 | `1` | `Slider` 步长 |
| `Value` | 数字 / `#RRGGBB` / string | 见组件页 | 初始值 |
| `Options` | JSON 数组字符串 | `[]` | `Select`，元素为 `{ "Label": "...", "Value": "..." }` |
| `Filter` | 扩展名列表 | — | `FilePicker`，如 `jar,zip` |

## 媒体

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Type` | `Audio` / `Video` | `Audio` | 媒体类型 |
| `Controls` | `True` / `False` | `True` | 显示播放控件 |
| `AutoPlay` | `True` / `False` | `False` | 自动播放 |
| `Loop` | `True` / `False` | `False` | 循环 |
| `Muted` | `True` / `False` | `False` | 静音 |
| `Volume` | 数字 `0`–`1` | `1` | 音量 |

## 数据与契约

| 属性 | 可选值 | 默认 | 适用 |
| :- | :- | :- | :- |
| `Type`（Data） | `Json` / `Text` / `Xml` / `Binary` | `Json` | `Data` |
| `Source`（Data） | `Url` / `File` | `Url` | `Data` |
| `Async` | `True` / `False` | `True` | `Data`；后台加载不阻塞渲染 |
| `Refresh` | 整数 `0`–`86400` 秒 | `3600` | `Data` / `Widget.Using` |
| `Type`（Resource） | `String` / `Bool` / `Number` / `Binary` / `Json` / `Page` | `String` | `Resource` |
| `Type`（Input/Output） | `String` / `Number` / `Bool` / `DateTime` / `Json` / `Binary` | 见组件页 | `Widget.Inputs` / `Widget.Outputs` |
| `Required` | `True` / `False` | `False` | `Input` |
| `Default` | 对应类型的字符串 | — | `Input` |

### Data.Status

```xml theme={null}
<Text Value="{Data.Status.News}" />
```

`Data.Status.News` 为 `Loading` / `Completed` / `Error`；`Async="True"` 时组件先渲染，数据完成后自动更新绑定。

## 触发器

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Event` | `Loaded` / `DataChanged` / `Click` / `Timer` / `Resize` | 必填 | 事件类型 |
| `Once` | `True` / `False` | `False` | Timer 是否只执行一次 |
| `Interval` | 整数 `1000`–`3600000` 毫秒 | `60000` | Timer 间隔 |
| `Function` | 当前 XML 中已定义的函数名 | — | 调用的函数 |
| `Control` | 已定义的控件 `Name` | — | Click 目标 |
| `Data` | 已定义的数据源 `Name` | — | DataChanged 目标 |

`Resize` 在网格或像素尺寸变化后防抖 150ms 触发；首次尺寸布局请使用 `Loaded`。

## Converter

| 属性 | 可选值 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Name` | identifier | 必填 | 绑定里通过 `Converter=Name` 引用 |
| `Type` | `String` / `Number` / `Bool` / `DateTime` / `Json` / `Format` / `Map` / `BoolToVisibility` / `Upper` / `Lower` / `Join` / `Script` | `String` | 转换类型 |
| `Format` | 字符串 | — | `Format` / `DateTime` 的默认格式 |
| `MapEntry.From` | 字符串 | 必填 | Map 源值 |
| `MapEntry.To` | 字符串 | 必填 | Map 目标值 |

绑定语法：

```xml theme={null}
<Text Value="{Binding Data.News.Title, Converter=Upper}" />
<TextBox Value="{Binding Inputs.Price, Converter=Money, Mode=TwoWay}" />
<Text Value="{MultiBinding Paths='Inputs.First|Inputs.Last', Converter=Join, ConverterParameter=' '}" />
```

## Animation

| 元素 | 主要属性 | 说明 |
| :- | :- | :- |
| `FadeIn` | `From` / `To` | 透明度进入 |
| `SlideIn` | `Direction` / `Distance` | 从方向滑入 |
| `ScaleTo` | `From` / `To` | 缩放到目标值 |
| `RotateTo` | `From` / `To` | 旋转到目标角度 |
| `Pulse` | — | 循环缩放 |
| `Spin` | — | 循环旋转 |

所有动画共用：`Duration`（毫秒，默认 300）、`Delay`（默认 0）、`Easing`（默认 `Ease`）、`Repeat`（数字或 `Infinite`，默认 1）、`Trigger`（`Loaded` / `Hover` / `Click`，默认 `Loaded`）。

## 属性写法

* 枚举值大小写敏感，必须使用本文的大驼峰写法。
* 数字范围属性写纯数字，不要带 `px`。
* `True` / `False` 不要写成 `true` / `false`。
* 字符串绑定写 `{路径}`，JSON 参数写 `Arguments` 或 `Options`。
* XML 属性中不能直接写 `<`，条件表达式要写成 `&lt;`。


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