api
外部链接
查看 Markdown通过精确 origin 白名单打开系统浏览器。
将白名单中的 HTTP(S) 链接交给系统浏览器，不在 WebView 内直接执行外部页面。
shell 只负责把已经授权的绝对 http / https URL 交给操作系统浏览器。它不下载内容、不
返回浏览器后续页面，也不校验浏览器重定向后的 URL。
实现入口：
| 入口 | 责任 |
|---|---|
frontend/src/api/shell.ts | URL 守卫 |
windows/src/platform/ksm_windows_host_services.cpp | 精确 origin 白名单和 ShellExecuteW |
android/app/src/main/java/dev/kasumi/app/KSMAndroidHostServices.kt | 精确 origin 白名单和 ACTION_VIEW |
| 方法 | Windows | Android | 权限 |
|---|---|---|---|
KSM.shell.openExternal / shell.openExternal | 支持 | 支持 | shell.open |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 绝对 http:// 或 https:// URL |
返回 { opened: boolean }。true 表示宿主已提交打开动作，不代表浏览器窗口已成功显示。
宿主初始化时配置精确 origin 白名单，默认空白名单并拒绝所有调用。比较包含 scheme、host 和
显式端口；默认端口会规范化，例如 https://example.com:443 与
https://example.com 等价。
以下输入会被拒绝：
javascript:、file:、data:、intent: 和 content://。只校验调用时传入的 URL。系统浏览器后续重定向不经过 Kasumi，因此宿主必须信任浏览器自身的 安全边界。
import { KSM } from '@kasumi/bridge';
try {
const result = await KSM.shell.openExternal({
url: 'https://example.com/docs'
});
if (!result.opened) {
console.warn('系统没有可用的浏览器处理器');
}
} catch (error) {
if (error instanceof Error && error.name === 'PERMISSION_DENIED') {
console.warn('origin 未加入宿主白名单');
}
}| 情况 | 错误 |
|---|---|
| 非法 scheme、相对 URL、凭据、空主机 | INVALID_ARGS |
未授予 shell.open | PERMISSION_DENIED |
| origin 不在白名单 | PERMISSION_DENIED |
| 系统没有浏览器处理器 | 返回 { opened: false } 或 IO_ERROR |
| 宿主未配置 shell 服务 | NOT_SUPPORTED |
Windows 使用 ShellExecuteW，服务层会再次检查精确 origin；Android 使用 ACTION_VIEW，
不会把任意 content://、intent:// 或非 Web scheme 交给系统。两端默认白名单都为空，调用方
必须在宿主初始化时显式配置。
capabilities.permissions 包含 shell.open。{ opened: false } 时检查系统浏览器或默认处理器。
评论