Widget.Using

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

签名

<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 引入时不会显示任何内容，但会正常拉取数据、执行触发器和函数。

输入契约

<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 传值：

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

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

输出契约

<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 的组件仍暴露旧的完整快照。

完整示例

<!-- 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，建议只对查询参数或路径段做参数化。纯数据源也受嵌套深度、实例数和数据源数量限制。

作用域

父组件只读：

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

示例

<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；父组件不能写。
远程子组件的数据域名在父组件编辑器确认。

启动器使用指引

插件开发

前置插件文档

插件商店使用

Widget.Using

签名

属性

内容

作为纯数据源

输入契约

输出契约

完整示例

作用域

解析

限制

示例

坑