# 桌面开发

## 功能
`bt-app` 是 BT 官方提供的桌面应用运行时和打包工具。它可以读取开发目录、独立 `.btr` 软件或 exe 尾部内嵌资源中的 `app.json`，创建桌面窗口，并按配置加载本地页面、本地 BT 服务地址或远程 Web 地址。

开发者可以用 `HTML/CSS/JavaScript` 或任何 `前端框架` 编写界面，用 BT 编写本地逻辑、Web 服务或可被前端调用的函数。`bt-app` 负责窗口、资源协议、BTR/单 exe 构建、图标、元信息和前端 `window.bt` 桥接。`.btr` 只包含软件配置和资源，不重复携带 bt-app 运行时，适合让多个小工具共用一个已安装的运行时。

## 适用场景
- HTML前端开发人员，快速编写页面。
- BT 本地服务加 Web 前端的桌面软件。
- 将远程 Web 应用一键打包为桌面窗口。
- 需要单文件分发的 Windows 桌面应用。
- 需要把多个 BT 小工具发布为轻量 `.btr`，由通用工具条或系统文件关联启动。

## 和 Web 项目的区别
- 普通 Web 项目运行在浏览器中，页面默认不能直接调用 BT 本地函数。
- `bt-app` 运行在桌面 WebView 中，并注入 `window.bt`，页面可以通过 `bt.call()` 调用 `main.bt` 中的 BT 语言函数，也可以通过桌面 API 控制窗口、托盘、剪贴板、屏幕吸管、框选截图、全局快捷键、通知和系统对话框。

## 和普通桌面软件的区别
传统桌面软件通常直接使用原生 UI。`bt-app` 使用 Web 技术绘制界面，用 BT 负责本地逻辑或服务，适合已有 Web 前端经验的开发者。

## 基本运行思路
1. 双击启动 `bt-app.exe` 或执行命令 `./bt-app.exe run`。
2. `bt-app run app.btr` 或 `bt-app app.btr` 从指定 BTR 读取资源；带内嵌资源的独立 exe 从自身读取；否则运行指定目录或当前目录。
3. 所有来源都先读取并校验 `app.json`；开发目录没有 `app.json` 但存在 `index.html` 时，会自动生成默认配置后运行。
4. `static` 模式，窗口加载 `app.entry` 指定的 `HTML` 文件。
5. `server` 模式，执行 `server.bt`，窗口加载 `app.entry` 指定的本地服务地址。
6. `remote` 模式，直接加载 `app.entry` 指定的网址。

## 文档目录
- [快速开始](/zh-hans/docs/bt-app/quick-start)
- [app.json 配置](/zh-hans/docs/bt-app/app-json)
- [入口配置](/zh-hans/docs/bt-app/entry)
- [运行模式](/zh-hans/docs/bt-app/mode)
- [bt:// 协议](/zh-hans/docs/bt-app/protocol)
- [桌面 API](/zh-hans/docs/bt-app/api)
- [打包构建](/zh-hans/docs/bt-app/build)
- [发布分发](/zh-hans/docs/bt-app/release)
- [完整示例](/zh-hans/docs/bt-app/examples)
- [常见问题](/zh-hans/docs/bt-app/faq)