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

# Widget

## Widget

组件根元素。一个 `.qwidget` 文件只能有一个 `Widget`。

## 签名

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

## 属性

| 属性 | 类型 | 必填 | 默认 | 说明 |
| :- | :- | :- | :- | :- |
| `Name` | string | 是 | — | 显示名，≤64 字符 |
| `Version` | string | 是 | — | 组件版本 |
| `Author` | string | 否 | — | 作者 |
| `Description` | string | 否 | — | 描述 |
| `UpdateUrl` | https URL | 否 | 导入 URL | 在线更新源 |
| `LauncherVersion` | semver | 否 | — | 最低启动器版本 |
| `UpdateTTL` | 秒 / `Default` / `Immediately` / `PreLaunch` / `PreLoad` / `None` | `Default` | 远程 XML 更新检查间隔 | |
| `RefreshTTL` | 秒 / 同上 | `None` | 重新拉取数据的间隔；保留组件状态 | |

`UpdateTTL` / `RefreshTTL` 常量：

* `Default`：使用启动器默认值（更新 6 小时；刷新不自动）
* `Immediately`：每次组件挂载时执行
* `PreLaunch`：每次启动器进程只执行一次
* `PreLoad`：每次切换到主页/重新挂载时执行
* `None`：不自动执行
* 数字：秒数，例如 `30` 表示 30 秒

## ImageHosts

动态 `Image` / `Media` 的图片、音视频和 poster 域名白名单：

```xml theme={null}
<Widget ImageHosts="*.example.com,cdn.example.net" ...>
```

* 支持精确域名、`*.example.com` 和 `*`
* 编辑器只需确认一次 `ImageHosts`，不需要逐张图确认
* 静态 URL 不要求确认
* `ImageHosts="*"` 表示允许所有 HTTPS 图片/媒体主机

## 子元素

`Widget` 的直接子元素可以是：

* 布局/控件节点：`Container`、`Row`、`Column`、`Grid`、`Text`、`Button`、`Dialog` 等
* `Data`
* `Resources`
* `Triggers`
* `Function`
* `Widget.Using`
* `Widget.Inputs` / `Widget.Outputs`（组件契约）

`Data` 也可以出现在任意布局容器内；`Resources`、`Triggers`、`Function` 只允许放在根下。

## 属性元素

根属性也适用属性元素语法：

```xml theme={null}
<Widget>
  <Widget.Name>示例</Widget.Name>
  <Widget.Version>1.0.0</Widget.Version>
  <Text Value="Hello" />
</Widget>
```

## 运行时行为

1. 解析并严格校验 XML：未知元素/属性、重复属性、非法 URL/枚举直接报错。
2. 解析 `Data` 并开始拉取；解析 `Resources`；解析 `Function`/`Triggers`。
3. 执行 `Loaded` 触发器。
4. 渲染节点；父组件通过 `Children` 读取快照；声明了 `Widget.Outputs` 时只暴露 `Children.<As>.Outputs`。
5. 在线组件按 6 小时 TTL 检查更新。

## 限制

* XML ≤256KB、深度 ≤16、元素 ≤1000。
* 数据源 ≤8、嵌套实例 ≤20。
* 未命名数据源默认名为 `Data`。

## 相关

* [QWidget XML 语法](https://docs.qomicex.top/guide/custom-widget/syntax.md)
* [数据绑定](https://docs.qomicex.top/guide/custom-widget/reference/binding.md)
* [版本要求](https://docs.qomicex.top/guide/custom-widget/reference/version.md)


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