用 AI 写网页，
一键打包成 App 从未如此简单

CatNative API 文档

CatNative 是 WebCatX 自研的安卓原生桥接框架：项目页面通过全局对象 window.webcat 直接调用安卓能力，预览与打包 APK 均支持，无需引入任何库。以下是 window.webcat 的完整 API 参考。

同步方法直接返回对象；异步方法返回 Promise，用 await 调用。失败时：同步返回 {ok:false,error}，异步 Reject（Error.message）。

window.webcat 由原生在页面开始 / 完成时异步注入，可能晚于 load 事件；建议在 DOMContentLoaded / load 之后再调用，若此时仍取不到，请重试或轮询 window.webcat 后再调用。

webcat.fs —— 私有文件（应用私有目录，两端一致）

webcat.ext —— 公开文件（target = "root" 全授权 / SAF handle）

target 取 "root"（需“所有文件访问”，path 为绝对路径）或 SAF handle（path 相对授权目录）。

webcat.media —— 媒体保存 / 选择

• data 支持：裸 base64 / data:image/png;base64,... / http(s) URL（自动下载）。
• path：省略 = 默认集合；非 / 开头 = 该集合下子目录（如 myapp/cards）；/ 开头 = 绝对路径写文件（需全盘权限）。
• format 默认 base64；uri 返回 content uri；path 尽力解析本地绝对路径，失败会提示改用 uri / base64。
• maxBytes 默认 15MB（仅 base64 上限），超限请改用 format=uri。

webcat.camera —— 相机

webcat.audio —— 音频播放

webcat.tts —— 文字转语音（无需权限）

webcat.record —— 录音（需打包勾选“录音 / 麦克风”）

webcat.scan —— 扫码（需打包勾选“相机”）

webcat.clipboard —— 剪切板（同步）

webcat.share —— 分享

webcat.app —— 应用

webcat.permission —— 权限

undeclared = 未声明权限（打包时未勾选 / 不支持）→ 应提示“打包时勾选”或“系统授予”。特殊权限 MANAGE 走 ext.requestFullAccess。

webcat.sys —— 系统信息（同步）

webcat.screen —— 屏幕（同步）

webcat.phone —— 电话短信（同步，免权限跳系统）

webcat.qq —— QQ 跳转（同步）

webcat.browser —— 系统浏览器（同步）

webcat.contacts —— 通讯录

webcat.location —— 定位

webcat.download —— 下载

webcat.network —— 原生网络（无 CORS 限制）

webcat.page —— 页面窗口

webcat.store —— 会话共享（同步，仅内存，App 退出即清）

webcat.statusBar —— 状态栏

默认状态下，状态栏 / 底部导航栏由原生自动避让，普通页面无需任何调用，也不要加 padding（会重复留白）。

statusBar.setAdaptive(true) 沉浸时原生不再避让、状态栏覆盖页面；仅当顶部有需要完整显示的内容（标题 / 按钮等）才加 padding，且 height 是设备 px，CSS 要用 height / density。

webcat.statusBar.setAdaptive(true);
const { height, density } = webcat.statusBar.height();
document.querySelector(".app-header").style.paddingTop = (height / density) + "px";

setAdaptive 作用于整个预览 / 打包窗口（含原生顶栏）；导航栏颜色始终跟随状态栏。

webcat.ui —— 提示（同步）

安全限制

• 网页不可访问 WebCatX 自身目录（/WebCatX/project、/WebCatX/cache）：ext.list 命中返回空列表，其余读 / 写 / 删 / 开 / 分享命中返回“路径受保护，不允许网页访问 WebCatX 目录”；SAF 授权目录不受限。

调用示例

// 私有文件
await webcat.fs.writeFile("data.json", JSON.stringify({a:1}));
const { content } = await webcat.fs.readFile("data.json");

// 压缩 / 解压（私有）
await webcat.fs.zip("js", "backup.zip");
await webcat.fs.unzip("backup.zip", "restore");

// 剪切板 / 系统信息（同步）
const { text } = webcat.clipboard.get();
const info = webcat.sys.info();

// 权限（异步）
const r = await webcat.permission.request(["android.permission.CAMERA"]);
if (r.undeclared.length) { webcat.ui.toast("该权限未在打包时勾选"); }

// 文字转语音
await webcat.tts.speak("你好，这是 WebCatX", { lang: "zh-CN" });

// 外部跳转
webcat.qq.openProfile("123456");
webcat.browser.open("https://example.com");

// 下载到私有目录
await webcat.download.download("https://x.com/a.png", "fs", "img/a.png");

// 通讯录 / 定位
const { contacts } = await webcat.contacts.list();
const loc = await webcat.location.get();

// 公开目录
if (webcat.ext.isFullAccess().granted) {
  await webcat.ext.writeFile("root", "/storage/emulated/0/Download/a.txt", "hi");
} else {
  webcat.ext.requestFullAccess();
}
const { handle } = await webcat.ext.pickDirectory();
await webcat.ext.writeFile(handle, "data.json", "{}");