@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/32-/346/211/253/347/240/201.md

@@ -0,0 +1,236 @@
+# 豆包应用插件的端能力 API: 扫码
+
+调起扫码并读取扫码结果。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [scanCode](#scancode) | 调起扫码能力。 |
+
+## API 详情
+
+<a id="scancode"></a>
+### scanCode()
+
+# scanCode
+
+调起扫码能力。
+
+## 扫码预览
+![扫码预览 scanCode](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fscan-code%252Findex)
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：双端对 scanType 的过滤支持不一致，部分取值可能不生效；依赖类型过滤的调用方可能扫出预期外的码型。
+
+## 支持版本
+
+前端库版本不低于 `0.0.25`。
+
+## 支持平台
+
+<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>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>系统权限</td><td>相机权限</td><td>必须</td><td>Android、iOS</td><td>从相机扫码需要系统相机权限</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- 首次调用会触发系统相机权限申请；用户拒绝后调用失败，需引导用户在系统设置中重新开启相机权限
+
+## 使用说明
+
+- onlyFromCamera 为 false 时允许从相册选择图片识别
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+scanCode(params?: ScanCodeParams): Promise<ScanCodeResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>onlyFromCamera</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>为 true 时不允许从相册选择图片识别</td><td>是否仅允许从相机扫码。</td></tr>
+<tr><td><code>scanType</code></td><td><code>ScanCodeType[]</code></td><td>否</td><td><code>允许全部支持的码型</code></td><td>-</td><td>允许的扫码类型。Android、iOS：双端对 scanType 的过滤支持不一致，部分取值可能不生效。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { scanCode } from '@doubao-dev/framework/api';
+
+const { result, scanType } = await scanCode({
+  onlyFromCamera: true,
+  scanType: ['qrCode']
+});
+
+console.log(result, scanType);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>characterSet</code></td><td><code>string</code></td><td>是</td><td>字符集。</td></tr>
+<tr><td><code>path</code></td><td><code>string</code></td><td>是</td><td>从扫码结果中解析出的页面路径。</td></tr>
+<tr><td><code>rawData</code></td><td><code>string</code></td><td>是</td><td>原始数据，通常为 Base64 字符串。</td></tr>
+<tr><td><code>result</code></td><td><code>string</code></td><td>是</td><td>扫码结果文本。</td></tr>
+<tr><td><code>scanType</code></td><td><code>ScanResultType</code></td><td>是</td><td>扫码结果类型。Android、iOS：双端对 scanType 的过滤支持不一致，部分取值可能不生效。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "characterSet": "utf-8",
+  "path": "",
+  "rawData": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
+  "result": "https://example.com",
+  "scanType": "QR_CODE"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 103,
+  "errMsg": "feature not support"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前豆包版本不支持扫码</td><td>升级至支持扫码能力的豆包版本后重试。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>iOS</td><td>扫码成功但未返回可用的扫码结果数据</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>
+
+## 相关类型
+
+<a id="scancodetype"></a>
+### ScanCodeType
+
+扫码类型。
+
+#### Type
+
+`'barCode' | 'qrCode' | 'datamatrix' | 'pdf417'`
+
+<a id="scanresulttype"></a>
+### ScanResultType
+
+扫码结果类型。
+
+#### Type
+
+`| 'QR_CODE'
+  | 'AZTEC'
+  | 'CODABAR'
+  | 'CODE_39'
+  | 'CODE_93'
+  | 'CODE_128'
+  | 'DATA_MATRIX'
+  | 'EAN_8'
+  | 'EAN_13'
+  | 'ITF'
+  | 'MAXICODE'
+  | 'PDF_417'
+  | 'RSS_14'
+  | 'RSS_EXPANDED'
+  | 'UPC_A'
+  | 'UPC_E'
+  | 'UPC_EAN_EXTENSION'
+  | 'WX_CODE'
+  | 'CODE_25'`
+
+<a id="scancodeparams"></a>
+### ScanCodeParams
+
+扫码请求参数。
+
+#### Properties
+
+• **onlyFromCamera?**: `boolean` - 是否仅允许从相机扫码
+• **scanType?**: `ScanCodeType[]` - 允许的扫码类型
+
+<a id="scancoderesult"></a>
+### ScanCodeResult
+
+扫码返回结果。
+
+#### Properties
+
+• **characterSet**: `string` - 字符集
+• **path**: `string` - 从扫码结果中解析出的页面路径
+• **rawData**: `string` - 原始数据，通常为 Base64 字符串
+• **result**: `string` - 扫码结果文本
+• **scanType**: `ScanResultType` - 扫码结果类型