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

## Widget.Using

Embeds another QWidget into the current widget as a node.

## Signature

```xml theme={null}
<Widget.Using Name="WeatherCard" As="Weather" />
<Widget.Using Url="https://example.com/weather.qwidget" As="Weather" />
<Widget.Using As="Weather">WeatherCard</Widget.Using>
<Widget.Using As="Weather">https://example.com/weather.qwidget</Widget.Using>

<Widget.Using Name="WeatherCard" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"city":"{Inputs.City}"}]]></Widget.Using.Arguments>
</Widget.Using>
```

## Attributes

| Attribute | Type | Description |
| :- | :- | :- |
| `Name` | string | Local widget name, exact match |
| `Url` | https URL | Remote widget |
| `As` | identifier | Alias of the child widget, unique among siblings |
| `Refresh` | 60–86400 | Remote cache TTL in seconds, default 6 hours |
| `Arguments` | JSON | Initial Inputs, supports binding interpolation |

`Name` and `Url` are mutually exclusive; the value can also be written as the tag body.

## Content

`Widget.Using` adds no extra container of its own; the child renders in place. The parent decides the outer size.

## As a pure data source

A widget can have no layout or visual nodes at all and contain only `Data`, `Resources`, `Function`, `Widget.Inputs`, `Widget.Outputs`, and `Triggers`. When embedded with `Widget.Using`, it renders nothing but still fetches data and runs triggers/functions.

### Input contract

```xml theme={null}
<Widget.Inputs>
  <Input Name="City" Type="String" Required="True" Default="Shanghai" />
  <Input Name="Limit" Type="Number" Default="10" />
</Widget.Inputs>
```

| Attribute | Description |
| :- | :- |
| `Name` | Unique input name, used as `{Inputs.Name}` |
| `Type` | `String` / `Number` / `Bool` / `DateTime` / `Json` / `Binary` |
| `Required` | Default `False` |
| `Default` | Used when absent; `Json` / `Binary` are parsed as JSON |

The parent passes values through `Widget.Using.Arguments`:

```xml theme={null}
<Widget.Using Name="Weather data" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"City":"Paris"}]]></Widget.Using.Arguments>
</Widget.Using>
```

* Unknown keys, type mismatches, and missing required inputs show an error placeholder.
* Changing `Arguments` updates child `Inputs`; child input controls can still change their own values.
* Widgets without `Widget.Inputs` keep the legacy behavior: `Arguments` go straight into `Inputs`.

### Output contract

```xml theme={null}
<Widget.Outputs>
  <Output Name="Weather" Type="Json" Source="{Data.Weather}" />
  <Output Name="Label" Type="String" Source="{Results.Summary.Text}" />
</Widget.Outputs>
```

| Attribute | Description |
| :- | :- |
| `Name` | Unique output name; parent reads `Children.<As>.Outputs.Name` |
| `Type` | Same type set; values are coerced/validated, invalid values become `undefined` |
| `Source` | Child scope path; may reference `Data` / `Results` / `Inputs` / `Resources` |

When `Widget.Outputs` is declared, only declared outputs are exposed to the parent; `Children.<As>.Data` and `Results` are no longer exposed, forming an output whitelist. Widgets without `Widget.Outputs` keep exposing the legacy full snapshot.

### Full example

```xml theme={null}
<!-- WeatherData.qwidget: a pure data-source widget with no visual nodes -->
<Widget Name="Weather data" Version="1.0.0">
  <Widget.Inputs>
    <Input Name="City" Type="String" Required="True" Default="Shanghai" />
  </Widget.Inputs>
  <Widget.Outputs>
    <Output Name="Weather" Type="Json" Source="{Data.Weather}" />
    <Output Name="Label" Type="String" Source="{Results.Summary.Text}" />
  </Widget.Outputs>
  <Data Name="Weather" Type="Json"
        Url="https://api.example.com/weather?city={Inputs.City}" />
  <Function Name="Summary">
    <Function.Output Type="String">Text</Function.Output>
    <Function.Script><![CDATA[
      return { Text: Data.Weather.temperature + "°C" };
    ]]></Function.Script>
  </Function>
  <Triggers>
    <Trigger Event="DataChanged" Data="Weather" Function="Summary" />
  </Triggers>
</Widget>

<!-- Parent: embed the data source and read its outputs -->
<Widget.Using Name="Weather data" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"City":"Paris"}]]></Widget.Using.Arguments>
</Widget.Using>
<Text Value="{Children.Weather.Outputs.Label}" />
<Text Value="{Children.Weather.Outputs.Weather.temperature}" />
```

`Data.Url` / `Data.Path` support `{Inputs.*}`. When inputs change, the old request is canceled and data is fetched again. The resolved URL must still be https:443 on a confirmed host; parameterize query values or path segments, not the host.

Pure data sources still count toward nesting depth, instance count, and data-source limits.

## Scope

The parent can only read:

```xml theme={null}
<Text Value="{Children.Weather.Data.Temp}" />
<Text Value="{Children.Weather.Inputs.City}" />
<Text Value="{Children.Weather.Results.Load.Items.0.Title}" />
```

`Children.<As>.State.Loading` / `.Error` are available too. Without `Widget.Outputs`, `.Data` / `.Results` are also exposed; with declared outputs, only `.Outputs` is exposed.

## Resolution

* Local `Name`: exact match against the custom widget list; a missing or duplicated name shows an error placeholder.
* Remote `Url`: fetched through the backend proxy, silently refreshed every 6 hours.
* Export does not inline dependencies; missing local widgets are reported before export.

## Limits

* Depth ≤5; self-references and A→B→A cycles are detected.
* At most 20 instances per parent widget.
* Duplicate aliases fail to parse.
* When the child unmounts, timers, script sandboxes, and blob URLs are cleaned up.

## Example

```xml theme={null}
<Row Gap="2">
  <Widget.Using Name="StatusCard" As="Players" />
  <Widget.Using Name="StatusCard" As="Tps">
    <Widget.Using.Arguments><![CDATA[{"mode":"tps"}]]></Widget.Using.Arguments>
  </Widget.Using>
</Row>
<Text Value="{Children.Players.Data.Value}" />
```

## Gotchas

* `Name` is the display name, not the file name.
* Children have their own Inputs/Data/Results; the parent cannot write them.
* Remote child data domains are approved in the parent widget's editor.


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