# QuartzPage 应用适配配置文档
> 适用版本：文档-HTML上传应用协议 2.0
---
## 目录
1. [导入 HTML 应用](#1-导入-html-应用)
2. [运行时环境](#2-运行时环境)
3. [样式接口总览](#3-样式接口总览)
4. [CSS 变量详解](#4-css-变量详解)
5. [三种显示模式的适配](#5-三种显示模式的适配)
6. [主题包下的行为](#6-主题包下的行为)
7. [JavaScript 主题接口](#7-javascript-主题接口)
8. [适配检查清单](#8-适配检查清单)
9. [完整示例：番茄钟](#9-完整示例番茄钟)
10. [示例解析](#10-示例解析)
---
## 1. 导入 HTML 应用
### 1.1 操作步骤
1. 打开 QuartzPage →「设置」→「应用」标签页
2. 在「上传 HTML 应用」区域填写：
- **应用名称**：显示在桌面/任务栏上的名字
- **应用图标**：一个图片 URL（可留空）
3. 点「选择文件」，选一个 `.html`
4. 保存后应用会出现在「我的应用」列表，可添加到桌面或任务栏
### 1.2 文件要求
| 项目 | 要求 |
|---|---|
| 扩展名 | `.html`（也接受 `text/html`） |
| 结构 | 完整的 HTML 文档，含 `` |
| 外部资源 | 可用 HTTPS 链接（CDN 字体、图标库等） |
| ` →
```
---
## 10. 示例解析
### 10.1 为什么用双色而不是跟随强调色
```css
--pomo-work: #E5484D; /* 专注 —— 红 */
--pomo-break: #14A37A; /* 休息 —— 绿 */
```
番茄钟的语义依赖颜色区分状态（红=专注，绿=休息）。
如果跟随强调色，用户把主题改成红色时，「休息」也会变红，语义就废了。
**这类「有语义的颜色」应该写死**，而**装饰性颜色**才用变量。
本例中 `--text` / `--glass` 走变量，红绿写死——这是正确的取舍。
### 10.2 为什么容器要透明
```css
html,body{ background: transparent; }
.pomo{ /* 自己不设背景 */ }
```
拟雾动效下，`.window-content` 背景是 `rgba(0,0,0,.06)`，透出壁纸。
如果应用根元素设了不透明背景，壁纸就被完全挡住了，拟雾效果消失。
这是**最常见的适配错误**。
### 10.3 局部变量 `--pomo-current-rgb`
```js
document.getElementById('pomo').style.setProperty('--pomo-current-rgb', MODES[mode].rgb);
```
把「当前模式色」存成局部 CSS 变量，好处是：
- 进度环、按钮、圆点、模式标签全部引用同一个变量
- 切换模式时只改一个值，所有元件自动过渡
- 不需要 JS 逐个改样式
这是 CSS 变量的经典用法，值得学。
### 10.4 `stroke-dashoffset` 做进度环
```js
var CIRC = 2 * Math.PI * 44; // r=44 的周长 = 276.46
$bar.style.strokeDashoffset = CIRC * (1 - ratio);
```
圆环「空多少」由偏移量控制。配合 `transition: stroke-dashoffset .35s linear`，
每秒走一格时动画是平滑的，不会一跳一跳。
### 10.5 为什么作用域要加 `.pomo`
`.btn`、`.dot`、`.time` 这些 class 名非常通用。
如果不加前缀，QP 自己如果有同名 class，就会互相污染。
本例所有组件都写在 `.pomo` 内部，且选择器来自 `.pomo .btn` 这样的嵌套结构
（HTML 结构上就在 `.pomo` 里），所以天然隔离。
### 10.6 深浅色都不额外写规则的原因
本例**没有**为深色/浅色写任何专门规则，只在拟雾下加了个 `backdrop-filter`。
因为它用的是 `--text` / `--text-faint` / `--glass` / `--glass-border`
这些「已经感知模式」的变量。模式切换时 QP 会改变量值，应用自动跟随。
**能不用 class 判断就不用**——变量优先是适配的原则。
### 10.7 空格键为什么判断 `e.target === document.body`
应用是内联注入的，`document` 是共享的。
如果不判断目标，用户在主界面其他窗口按空格也会触发番茄钟。
```js
if(e.code === 'Space' && e.target === document.body){ … }
```
同理，`notify()` 用 `window.parent.postMessage` 而不是直接调 QP 函数，
避免与应用脚本作用域耦合。
---
## 附：常见问题
**Q：应用打开后是灰底方块，没有我的样式？**
`