---
title: "API 方法"
description: "Kasumi 前端桥接、文件、对话框、剪贴板、通知、权限、窗口和事件方法。"
---


> 说明前端如何初始化 Kasumi 桥接并调用跨端原生能力。

## 模块边界

本文档只描述前端可调用的方法和参数。命令契约以 `protocol/commands.json` 为准，Windows 与 Android 的具体实现不在前端直接暴露。

前端必须通过 `KSM` 根入口或 `@kasumi/bridge` 导出的 API 调用，不得直接访问 `window.chrome.webview`、`WebViewCompat` 或真实文件路径。

## 初始化

```ts
import { KSM, KSMWebMessageTransport } from '@kasumi/bridge';

KSM.initialize(new KSMWebMessageTransport());

const pong = await KSM.ping();
const capabilities = await KSM.capabilities();
```

`capabilities` 返回当前宿主实际支持的命令和权限。WebView 重建后，前端必须重新调用 `KSM.capabilities()`。

## 应用

```ts
const info = await KSM.app.getInfo();
await KSM.app.exit();
```

`app.getInfo` 返回应用名、版本、平台和语言。`app.exit` 请求宿主退出应用。

## 文件系统

```ts
import { fs } from '@kasumi/bridge';

await fs.writeText({
  path: 'app://data/config.json',
  content: '{"ready":true}'
});

const text = await fs.readText({ path: 'app://data/config.json' });
const exists = await fs.exists({ path: 'app://data/config.json' });
await fs.remove({ path: 'app://data/config.json' });
```

支持的虚拟路径：

| 路径 | 用途 | 可写 |
|---|---|---|
| `app://data/**` | 应用私有数据 | 是 |
| `app://cache/**` | 缓存 | 是 |
| `app://tmp/**` | 临时文件 | 是 |
| `app://res/**` | 打包资源 | 否 |
| `app://assets/**` | 前端资源 | 否 |

`fs.readText` 返回 `string | { file: string }`。路径包含 `..`、`~`、空字节、绝对路径或不属于 `app://` 的前缀时，必须先拒绝并返回参数或权限错误。

## 对话框

```ts
await KSM.dialog.message({
  title: 'Kasumi',
  message: '操作完成'
});

const result = await KSM.dialog.confirm({
  title: '确认',
  message: '是否继续？'
});

const opened = await KSM.dialog.openFile({
  filters: ['.json', '.txt']
});

const saved = await KSM.dialog.saveFile({
  suggestedName: 'config.json'
});
```

文件选择器返回虚拟文件句柄，不得向前端暴露宿主真实路径。

## 剪贴板与通知

```ts
const clipboard = await KSM.clipboard.readText();
await KSM.clipboard.writeText('Kasumi');

await KSM.notification.show({
  title: 'Kasumi',
  body: '操作完成'
});
```

Android 通知在首次使用前必须通过权限请求。

## 权限

```ts
const result = await KSM.permission.request('notification.show');
if (result.granted) {
  await KSM.notification.show({
    title: 'Kasumi',
    body: '已获得通知权限'
  });
}
```

权限必须由原生侧校验。用户拒绝后，相关命令必须返回 `PERMISSION_DENIED`。

## 窗口与事件

```ts
await KSM.window.setTitle('Kasumi');
await KSM.window.minimize();
await KSM.window.maximize();
await KSM.window.close();

const off = KSM.events.on<{ width: number; height: number }>(
  'window.resized',
  ({ width, height }) => {
    console.log(width, height);
  }
);

await KSM.subscribe('window.resized');
off();
await KSM.unsubscribe('window.resized');
```

系统事件 `webview.reloaded` 不需要前端订阅。收到该事件后，前端必须重新查询能力并恢复所需事件订阅。

Windows 支持窗口标题、最小化和最大化；Android 对不支持的窗口操作返回 `NOT_SUPPORTED`。

## 错误和生命周期

```ts
try {
  await fs.readText({ path: 'app://data/config.json' });
} catch (error) {
  if (error instanceof Error && error.name === 'NOT_FOUND') {
    console.log('文件不存在');
  }
}

KSM.dispose();
```

每个请求只返回一次响应。超时返回 `TIMEOUT`，取消返回 `CANCELLED`，未注册命令返回 `UNKNOWN_COMMAND`，平台不支持返回 `NOT_SUPPORTED`。

## 排查路径

1. 确认已调用 `KSM.initialize`。
2. 确认命令存在于 `protocol/commands.json`。
3. 确认 `capabilities.query` 返回该命令。
4. 确认路径使用 `app://` 虚拟路径。
5. 确认权限已经通过 `permission.request`。
6. 根据错误码检查参数、权限、平台支持或请求生命周期。