# 一次性数据请求

页面需要在刷新或搜索时获取一份数据，可以使用数据提供者。例如，天气卡片点击刷新时请求最新天气，后台返回结果，页面更新显示。

## 发起请求

页面调用 `FlyonDeckWidget.requestData(providerId, input)`。宿主找到该页面对应的已放置实例，确认提供者属于这个超级块类型，然后检查输入 Schema。

页面传入业务输入即可。设备、屏幕、块 ID 和实例配置由宿主补入后台请求，处理函数通过 `request.instance` 和 `request.settings` 读取。

## 处理与响应

宿主调用 `dataProviders[providerId](request, context)`。函数返回后，宿主按 `responseSchema` 和 `maxBytes` 检查结果，再把它发给原页面，完成对应 Promise。

返回值只属于这次请求。页面希望重新获取时，再发起请求；多个页面需要持续共享同一个当前值时，使用状态来源。

## 超时与错误

输入不合法、后台失败或请求超时时，页面 Promise 拒绝。页面可以在 `catch` 中显示失败状态，并让用户再次刷新。后台执行时间由提供者的 `timeoutMs` 设置，页面等待上限为 35 秒。

声明字段见 [dataProviders](../../reference/data-providers.md)，函数参数见 [DataProviderHandler](../../reference/node-sdk.md#dataproviderhandler)。