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

The root element of a component. A `.qwidget` file can contain exactly one `Widget`.

## Signature

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

## Attributes

| Attribute | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `Name` | string | Yes | — | Display name, ≤64 characters |
| `Version` | string | Yes | — | Component version |
| `Author` | string | No | — | Author |
| `Description` | string | No | — | Description |
| `UpdateUrl` | https URL | No | Import URL | Online update source |
| `LauncherVersion` | semver | No | — | Minimum launcher version |
| `UpdateTTL` | seconds / `Default` / `Immediately` / `PreLaunch` / `PreLoad` / `None` | `Default` | Remote XML update check interval | |
| `RefreshTTL` | seconds / same | `None` | Data refetch interval; keeps component state | |

`UpdateTTL` / `RefreshTTL` constants:

* `Default`: launcher default (6 hours for updates; no automatic refresh)
* `Immediately`: on every component mount
* `PreLaunch`: once per launcher process
* `PreLoad`: on every dashboard switch/remount
* `None`: never
* Number: seconds, e.g. `30` = 30 seconds

## ImageHosts

Host allowlist for dynamic `Image` / `Media` sources and posters:

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

* Exact hosts, `*.example.com`, and `*` are supported
* The editor confirms `ImageHosts` once; images are not confirmed one by one
* Static URLs do not require confirmation
* `ImageHosts="*"` allows all HTTPS image/media hosts

## Child elements

Direct children of `Widget` can be:

* Layout/control nodes: `Container`, `Row`, `Column`, `Grid`, `Text`, `Button`, `Dialog`, and so on
* `Data`
* `Resources`
* `Triggers`
* `Function`
* `Widget.Using`
* `Widget.Inputs` / `Widget.Outputs` (widget contract)

`Data` can also appear inside any layout container; `Resources`, `Triggers`, and `Function` are only allowed at the root.

## Attribute elements

Root attributes also accept the attribute-element syntax:

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

## Runtime behavior

1. Parse and strictly validate the XML: unknown elements/attributes, duplicate attributes, and invalid URLs/enums are hard errors.
2. Parse `Data` and start fetching; parse `Resources`; parse `Function`/`Triggers`.
3. Run the `Loaded` trigger.
4. Render nodes; the parent reads the snapshot through `Children`; when `Widget.Outputs` is declared only `Children.<As>.Outputs` is exposed.
5. Online components check for updates on a 6-hour TTL.

## Limitations

* XML ≤256KB, depth ≤16, elements ≤1000.
* Data sources ≤8, nested instances ≤20.
* An unnamed data source is named `Data` by default.

## Related

* [QWidget XML syntax](https://docs.qomicex.top/en/guide/custom-widget/syntax.md)
* [Data binding](https://docs.qomicex.top/en/guide/custom-widget/reference/binding.md)
* [Version requirements](https://docs.qomicex.top/en/guide/custom-widget/reference/version.md)


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