API 方法
查看 MarkdownKasumi 前端桥接、文件、对话框、剪贴板、通知、权限、窗口和事件方法。
说明前端如何初始化 Kasumi 桥接并调用跨端原生能力。
本文档只描述前端可调用的方法和参数。命令契约以 protocol/commands.json 为准，Windows 与 Android 的具体实现不在前端直接暴露。
前端必须通过 KSM 根入口或 @kasumi/bridge 导出的 API 调用，不得直接访问 window.chrome.webview、WebViewCompat 或真实文件路径。
import { KSM, KSMWebMessageTransport } from '@kasumi/bridge';
KSM.initialize(new KSMWebMessageTransport());
const pong = await KSM.ping();
const capabilities = await KSM.capabilities();capabilities 返回当前宿主实际支持的命令和权限。WebView 重建后，前端必须重新调用 KSM.capabilities()。
const info = await KSM.app.getInfo();
await KSM.app.exit();app.getInfo 返回应用名、版本、平台和语言。app.exit 请求宿主退出应用。
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:// 的前缀时，必须先拒绝并返回参数或权限错误。
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'
});文件选择器返回虚拟文件句柄，不得向前端暴露宿主真实路径。
const clipboard = await KSM.clipboard.readText();
await KSM.clipboard.writeText('Kasumi');
await KSM.notification.show({
title: 'Kasumi',
body: '操作完成'
});Android 通知在首次使用前必须通过权限请求。
const result = await KSM.permission.request('notification.show');
if (result.granted) {
await KSM.notification.show({
title: 'Kasumi',
body: '已获得通知权限'
});
}权限必须由原生侧校验。用户拒绝后，相关命令必须返回 PERMISSION_DENIED。
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。
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。
KSM.initialize。protocol/commands.json。capabilities.query 返回该命令。app:// 虚拟路径。permission.request。
评论