# 原生对话框

> 通过 chrovia.ui 显示浏览器原生提示、确认框和非模态通知。

Source: https://console.getchrovia.com/zh/docs/sdk-native-dialog

**能力：**`nativeDialog`。**API：**`chrovia.ui`。不需要 EP 配置。在 Provision Service Worker 使用；页面使用还需要 `unrestrictedApi`。

## 显示对话框

在浏览器窗口可用时，从插件的命令处理器调用：

```js
async function askToContinue() {
  const ui = globalThis.chrovia?.ui;
  if (!ui) {
    throw new Error('nativeDialog is required');
  }
  const accepted = await ui.confirm('SDK Example', 'Continue with this operation?');
  if (!accepted) {
    return false;
  }
  await ui.alert('SDK Example', 'The operation was confirmed.');
  return true;
}
```

## 方法与行为

| 方法 | 返回值 |
| --- | --- |
| `alert(title, message)` | 对话框结束后解析为 `undefined` 的 Promise |
| `confirm(title, message)` | 接受时为 `true`，其他结果为 `false` 的 Promise |
| `notify(title, message)` | 显示非模态通知；确认或关闭后 Promise 解析为 `undefined`，不是显示后立即解析 |

标题和消息是字符串，不是 HTML。提示与确认使用关联浏览器窗口的 Chromium 原生消息框。通知是非模态的，不返回用户批准结果。接口没有自定义按钮、复选框或 HTML 选项。

## 处理失败

事件处理器中应 await 或捕获 Promise；对话框服务不可用时调用可能被拒绝。没有合适浏览器窗口时，`alert()` 可能不显示任何内容就解析，`confirm()` 则解析为 `false`。Provision Service Worker 调用使用最近活动的普通浏览器窗口。不要依赖用户在 headless 或首个窗口打开前看到提示。用于请求确认时，注意[网络拦截的超时放行行为](https://console.getchrovia.com/zh/docs/sdk-network-intercept)：确认框超过请求超时仍未关闭，不会继续阻止该请求。

此 API 与 `window.alert`、扩展通知不同。如果缺少 `chrovia.ui`，检查 `nativeDialog` 和执行上下文。分别测试提示、接受与取消确认，以及通知行为。