> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# expiredWidget

更新过期的 Widget 为固定卡片。

## 扫码预览

![扫码预览 expiredWidget](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fexpired-widget%252Findex)

## 支持版本

前端库版本不低于 `0.0.27`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 接入准备

### 前置条件

- **Android**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId
- **iOS**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId

## 使用说明

用于将状态已经过期的 Widget 实例转换为固定卡片，用户点击后可跳转到指定页面。

`getWidgetInstanceId` 仅在卡片环境中有效，在应用插件页面中会返回 `undefined`。如果需要在页面中调用，
请在 `navigateTo` 时通过参数传递卡片实例 ID。

- 请在卡片状态过期后调用，将卡片转换为可点击跳转的固定卡片；建议使用 url 字段而非已废弃的 schema 字段。

## 调用方式

### 异步 API

```typescript
expiredWidget(params: ExpiredWidgetParams): Promise<object>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>detailText</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 detailText。</td></tr>
<tr><td><code>schema</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>已废弃：使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段。</td><td>点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 参数一致。</td></tr>
<tr><td><code>title</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 title。</td></tr>
<tr><td><code>url</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 URL 或 sslocal schema。应用插件页面 URL 格式与 navigateTo 的 url 参数一致。</td></tr>
<tr><td><code>widgetInstanceId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>卡片实例 ID。<br><br>在卡片环境可通过 `getWidgetInstanceId` 获取；在应用插件页面等非卡片环境需要通过传参或通信传递。</td></tr>
</tbody>
</table>

## 调用示例

```ts
import { expiredWidget } from '@doubao-dev/framework/api';
import { getWidgetInstanceId } from '@doubao-dev/framework';

expiredWidget({
  widgetInstanceId: getWidgetInstanceId(),
  url: '/pages/detail/index?key=value'
});
```

## 成功返回

无返回字段。
