> ## 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 XML 语法

## QWidget XML 语法

QWidget 是单文件 XML。根元素固定为 `Widget`，其余元素分为布局、控件、数据/资源、触发器、函数和嵌套引用。

## 根元素

```xml theme={null}
<Widget Name="每日新闻" Version="1.0.0" Author="示例"
        Description="可选说明"
        UpdateUrl="https://example.com/news.qwidget"
        LauncherVersion="1.4.0">
  ...
</Widget>
```

| 属性 | 必填 | 说明 |
| :- | :- | :- |
| `Name` | 是 | 组件显示名，≤64 字符 |
| `Version` | 是 | 组件版本，用于在线更新提示 |
| `Author` | 否 | 作者 |
| `Description` | 否 | 描述 |
| `UpdateUrl` | 否 | 更新源，必须 https:443；不写时使用导入 URL |
| `LauncherVersion` | 否 | 最低启动器版本，见[版本要求](https://docs.qomicex.top/guide/custom-widget/reference/version.md) |

## 命名

所有元素、属性、枚举值使用大驼峰：

* 元素：`Container`、`Text`、`TextBox`、`Widget.Using`
* 属性：`Value`、`Size`、`OnClick`、`EmptyText`
* 枚举：`Lg`、`Bold`、`Center`、`Json`、`Binary`

## 通用节点属性

除 `Widget` 根元素、`Data`、`Resources`、`Function`、`Triggers` 等非可视元素外，所有可视节点都支持：

| 属性 | 必填 | 说明 |
| :- | :- | :- |
| `Target` | 否 | 脚本定位键，整个组件内唯一；供 `Host.SetProperty` / `Host.GetProperty` / `Host.Invoke` 使用 |
| `Visible` | 否 | 默认 `True`；设为 `False` 时不渲染，可由脚本动态切换 |
| `When` | 否 | 尺寸条件，例如 `Size.Width &lt;= 1`；不满足时不渲染 |

`Target` 与输入控件的 `Name` 是两个独立命名空间：`Name` 仍用于 `{Inputs.Name}` 和 `Trigger Control="Name"`，`Target` 只用于脚本操作 UI。所有属性可选值见[属性值参考](https://docs.qomicex.top/guide/custom-widget/reference/values.md)。示例：

```xml theme={null}
<Text Target="Status" Value="待机" />
<Button Target="Refresh" Text="刷新" OnClick="CallFunction" Function="Refresh" />
<Text When="Size.Width &lt;= 1" Value="窄卡片" />
```

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

脚本示例见[函数与 TypeScript](https://docs.qomicex.top/guide/custom-widget/advanced/functions.md#host)。

## 三种等价写法

同一个属性支持属性语法、内容语法、属性元素语法，三者等价；同一属性被两种语法同时赋值会报错。

```xml theme={null}
<!-- 属性语法 -->
<Text Value="Hello" />

<!-- 内容语法（ContentProperty） -->
<Text>Hello</Text>

<!-- 属性元素语法 -->
<Text><Text.Value>Hello</Text.Value></Text>
```

ContentProperty 映射：

| 元素 | 内容对应属性 |
| :- | :- |
| `Text` | `Value` |
| `Button` / `Link` / `CheckBox` / `FilePicker` | `Text` |
| `TextBox` / `ColorPicker` / `Progress` / `Slider` | `Value` |
| `Select` | `Options`（JSON） |
| `Media` | `Source` |
| `Image` | `Src` |
| `Spacer` | `Size` |
| `Data` | `Url` |
| `String` / `Bool` / `Number` / `Binary` / `Resource` | 文本内容 |
| 容器类元素 | 子元素 |

属性元素可继续嵌套简单的属性赋值：

```xml theme={null}
<Text>
  <Text.Size>Lg</Text.Size>
  <Text.Weight>Bold</Text.Weight>
  Hello Qomicex
</Text>
```

### 附加属性

`Grid` 的直接子元素支持 `Grid.Row`、`Grid.Column`、`Grid.RowSpan`、`Grid.ColumnSpan`：

```xml theme={null}
<Grid Columns="2" Gap="2">
  <Button Grid.Column="1" Text="右侧" />
  <Button>
    <Grid.Row>1</Grid.Row>
    <Button.Text>下一行</Button.Text>
  </Button>
</Grid>
```

## 绑定

字符串属性都可以用 `{路径}` 插值；整个值就是一个绑定时保留原始类型。

| 命名空间 | 示例 | 说明 |
| :- | :- | :- |
| `Data` | `{Data.News.Title}` | 数据源，未命名源为 `{Data.Title}` |
| `Resources` | `{Resources.AppName}` | 命名资源 |
| `Inputs` | `{Inputs.Keyword}` | 控件当前值 |
| `Results` | `{Results.Search.Items}` | 函数/命令/插件 API 结果 |
| `Children` | `{Children.Weather.Inputs.City}` | 嵌套组件只读状态 |
| `State` | `{State.Loading}` / `{State.Error}` | 组件运行状态 |

详见[数据绑定](https://docs.qomicex.top/guide/custom-widget/reference/binding.md)。

## 元素总览

| 分类 | 元素 | 文档 |
| :- | :- | :- |
| 根 | `Widget` | [Widget](https://docs.qomicex.top/guide/custom-widget/reference/components/widget.md) |
| 契约 | `Widget.Inputs` `Widget.Outputs` | [Widget.Using](https://docs.qomicex.top/guide/custom-widget/reference/components/using.md#作为纯数据源) |
| 布局 | `Container` `Row` `Column` `Grid` | [布局组件](https://docs.qomicex.top/guide/custom-widget/advanced/layout.md) |
| 选项卡 | `Tabs` `TabItem` | [Tabs](https://docs.qomicex.top/guide/custom-widget/reference/components/tabs.md) |
| 列表 | `List` `ListItem` | [List](https://docs.qomicex.top/guide/custom-widget/reference/components/list.md) |
| 条件 | `If` | [If](https://docs.qomicex.top/guide/custom-widget/reference/components/if.md) |
| 分隔 | `Divider` `Spacer` | [Divider](https://docs.qomicex.top/guide/custom-widget/reference/components/divider.md) |
| 内容 | `Text` `Button` `Link` `Image` `Media` | [Text](https://docs.qomicex.top/guide/custom-widget/reference/components/text.md) |
| 输入 | `TextBox` `CheckBox` `Slider` `Select` | [TextBox](https://docs.qomicex.top/guide/custom-widget/reference/components/text-box.md) |
| 展示 | `Progress` `FilePicker` `ColorPicker` | [Progress](https://docs.qomicex.top/guide/custom-widget/reference/components/progress.md) |
| 数据 | `Data` | [Data](https://docs.qomicex.top/guide/custom-widget/reference/components/data.md) |
| 资源 | `Resources` `String` `Bool` `Number` `Binary` `Resource` | [Resources](https://docs.qomicex.top/guide/custom-widget/reference/components/resources.md) |
| 事件 | `Triggers` `Trigger` | [Triggers](https://docs.qomicex.top/guide/custom-widget/reference/components/triggers.md) |
| 函数 | `Function` `Struct` `Field` | [Function](https://docs.qomicex.top/guide/custom-widget/reference/components/function.md) |
| 嵌套 | `Widget.Using` | [Widget.Using](https://docs.qomicex.top/guide/custom-widget/reference/components/using.md) |

## 动作

按钮、链接和触发器通过 `OnClick` / `OnChange` / `Action` 调用动作：

`Launch`、`SetDefaultInstance`、`OpenInstance`、`Navigate`、`OpenUrl`、`OpenFolder`、`Copy`、`SelectAccount`、`Install`、`Refresh`、`CallFunction`、`RunCommand`、`PluginApi`。

参数与示例见[动作参考](https://docs.qomicex.top/guide/custom-widget/reference/actions.md)。

## 限制

* XML ≤256KB、深度 ≤16、元素 ≤1000。
* 数据源 ≤8 个；列表渲染 ≤200 项。
* 在线文本 ≤1MB、二进制 ≤8MB；本地二进制 ≤8MB。
* 嵌套深度 ≤5，单父组件 ≤20 个嵌套实例。
* 函数脚本 ≤64KB，超时默认 3 秒，最大 10 秒。
* 禁止 `DOCTYPE` / `ENTITY`；未知元素、未知属性、重复属性都会直接报错。


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