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

把另一个 QWidget 作为节点嵌入当前组件。

## 签名

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

## 属性

| 属性 | 类型 | 说明 |
| :- | :- | :- |
| `Name` | string | 本地组件名，精确匹配 |
| `Url` | https URL | 远程组件 |
| `As` | identifier | 子组件别名，同级唯一 |
| `Refresh` | 60–86400 | 远程缓存 TTL 秒，默认 6 小时 |
| `Arguments` | JSON | 初始 Inputs，支持绑定插值 |

`Name` 与 `Url` 二选一；也可以把值写在标签内容里。

## 内容

`Widget.Using` 本身不渲染额外容器，子组件内容按原位渲染。父组件决定外层尺寸。

## 作为纯数据源

组件可以没有任何布局或可视节点，只放 `Data`、`Resources`、`Function`、`Widget.Inputs`、`Widget.Outputs` 和 `Triggers`。这种组件被 `Widget.Using` 引入时不会显示任何内容，但会正常拉取数据、执行触发器和函数。

### 输入契约

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

| 属性 | 说明 |
| :- | :- |
| `Name` | 输入名，唯一，供 `{Inputs.Name}` / `{Inputs.City}` 使用 |
| `Type` | `String` / `Number` / `Bool` / `DateTime` / `Json` / `Binary` |
| `Required` | 必填，默认 `False` |
| `Default` | 缺省值；`Json` / `Binary` 按 JSON 解析 |

父组件通过 `Widget.Using.Arguments` 传值：

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

* 未声明的输入键、类型不匹配、缺少必填输入都会显示错误占位。
* `Arguments` 变化会更新子组件 `Inputs`；子组件内部输入控件仍可修改自己的值。
* 没有声明 `Widget.Inputs` 的旧组件保持原行为：`Arguments` 原样进入 `Inputs`。

### 输出契约

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

| 属性 | 说明 |
| :- | :- |
| `Name` | 输出名，唯一，父组件读 `Children.<As>.Outputs.Name` |
| `Type` | 同上，按类型校验/转换；不匹配时为 `undefined` |
| `Source` | 子组件作用域路径，可引用 `Data` / `Results` / `Inputs` / `Resources` |

声明 `Widget.Outputs` 后，父组件只能通过 `Outputs` 读取声明过的输出；`Children.<As>.Data` / `Results` 不再暴露，形成输出白名单。没有声明 `Widget.Outputs` 的组件仍暴露旧的完整快照。

### 完整示例

```xml theme={null}
<!-- WeatherData.qwidget：纯数据源，没有可视节点 -->
<Widget Name="天气数据" 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>

<!-- 父组件：引入数据源并读取输出 -->
<Widget.Using Name="天气数据" 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` 支持 `{Inputs.*}` 插值；`Inputs` 变化会重新拉取，旧请求会被取消。URL 的协议/主机仍必须是确认过的 https:443，建议只对查询参数或路径段做参数化。

纯数据源也受嵌套深度、实例数和数据源数量限制。

## 作用域

父组件只读：

```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` 也可用。未声明 `Widget.Outputs` 时还可读 `.Data` / `.Results`；声明后只暴露 `.Outputs`。

## 解析

* 本地 `Name`：从自定义组件列表精确匹配；缺失/重名显示错误占位。
* 远程 `Url`：后端代理拉取，6 小时 TTL 静默更新。
* 导出不内联依赖；本地缺失时导出前提示。

## 限制

* 深度 ≤5；检测自引用和 A→B→A 循环。
* 单父组件 ≤20 个实例。
* 别名重复解析失败。
* 子组件卸载时清理计时器、脚本沙箱、Blob URL。

## 示例

```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}" />
```

## 坑

* `Name` 是显示名，不是文件名。
* 子组件有独立 Inputs/Data/Results；父组件不能写。
* 远程子组件的数据域名在父组件编辑器确认。


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