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

# createTask

创建任务。

## 使用限制

> \[!WARNING]
> **Android、iOS**：豆包 Android、iOS 仅支持 remote 任务，传入 local 无法按本地任务处理；调用方传入 local 时行为与预期不符。

## 支持版本

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

## 支持平台

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

## 使用说明

创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识
可用于幂等创建和后续业务关联。远端任务创建成功后，返回的 taskId 可用于查询或更新任务。

- 当前仅支持 taskType 为 remote 的远端任务；outTaskId 建议使用业务侧唯一标识以支持幂等创建。

## 调用方式

### 异步 API

```typescript
createTask(params: CreateTaskParams): Promise<CreateTaskResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>outTaskId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>开发者侧任务唯一标识，用于幂等和关联</td></tr>
<tr><td><code>taskDetail</code></td><td><code>TaskDetail</code></td><td>是</td><td>-</td><td>-</td><td>模板对应的数据，传入对象时会自动序列化为 JSON 字符串</td></tr>
<tr><td><code>taskDetail.display_data</code></td><td><code>TaskDisplayData</code></td><td>否</td><td>-</td><td>-</td><td>任务展示数据。</td></tr>
<tr><td><code>taskDetail.display_data.sub_title</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>任务副标题。</td></tr>
<tr><td><code>taskDetail.display_data.title</code></td><td><code>string</code></td><td>否</td><td>-</td><td>-</td><td>任务标题。</td></tr>
<tr><td><code>taskDetail.expire_in_sec</code></td><td><code>number</code></td><td>否</td><td>-</td><td>-</td><td>任务过期时间，单位：秒。任务创建后经过该时间将自动过期。</td></tr>
<tr><td><code>taskDetail.jump_page_data</code></td><td><code>JumpSchemaData</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击任务跳转的页面参数。</td></tr>
<tr><td><code>taskDetail.jump_page_data.path</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>跳转页面。</td></tr>
<tr><td><code>taskDetail.jump_page_data.query</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>页面参数，应用插件内消费时会自动 base64 url encode，需要 decode。</td></tr>
<tr><td><code>taskDetail.progress_data</code></td><td><code>TaskProgressData</code></td><td>否</td><td><code>-</code></td><td>-</td><td>任务进度数据。</td></tr>
<tr><td><code>taskDetail.progress_data.progress</code></td><td><code>number</code></td><td>否</td><td>-</td><td>-</td><td>任务进度值，如百分比 0-100。</td></tr>
<tr><td><code>taskDetail.progress_data.progress_text</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>进度描述文本，如&quot;正在处理中&quot;。</td></tr>
<tr><td><code>taskDetail.progress_data.remaining_seconds</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>-</td><td>预估剩余时间，单位：秒。</td></tr>
<tr><td><code>taskDetail.remove_data</code></td><td><code>TaskActionParams</code></td><td>否</td><td><code>-</code></td><td>-</td><td>移除任务时的操作参数。</td></tr>
<tr><td><code>taskDetail.remove_data.action_key</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>操作标识。</td></tr>
<tr><td><code>taskDetail.remove_data.page_param</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>页面参数。</td></tr>
<tr><td><code>taskTemplate</code></td><td><code>&quot;remote_normal_v1&quot;</code></td><td>是</td><td>-</td><td>-</td><td>任务样式模板，当前仅支持 remote_normal_v1</td></tr>
<tr><td><code>taskType</code></td><td><code>TaskType</code></td><td>是</td><td>-</td><td>-</td><td>任务类型，当前支持 local 和 remote。Android、iOS：豆包 Android、iOS 仅支持 remote 任务，传入 local 无法按本地任务处理。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { createTask } from '@doubao-dev/framework/api';

const result = await createTask({
  outTaskId: 'order-20260529-001',
  taskTemplate: 'remote_normal_v1',
  taskType: 'remote',
  taskDetail: {
    expire_in_sec: 3600,
    display_data: {
      title: '订单处理中',
      sub_title: '正在为你处理订单，请稍候'
    }
  }
});

console.log(result.taskId, result.token, result.expiresIn);
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>expiresIn</code></td><td><code>number</code></td><td>否</td><td>任务超时过期时间</td></tr>
<tr><td><code>taskId</code></td><td><code>string</code></td><td>是</td><td>任务 ID，后续可以使用这个 ID 更新任务</td></tr>
<tr><td><code>token</code></td><td><code>string</code></td><td>否</td><td>远端任务 token，后续使用 token 通过 OpenAPI 更新远端任务</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "taskId": "task_123",
  "token": "task-token",
  "expiresIn": 3600
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 104,
  "errMsg": "invalid parameter"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>taskType 不是 remote（如传入 local）</td><td>传入 remote 任务类型后重试。</td></tr>
<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>远端任务创建成功但返回数据为空或缺少 taskId</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- taskType 非 remote 返回 104；远端返回数据为空或缺少 taskId 返回 112；其他失败统一返回 102。
