# Fenix 8 V3 — Garmin 数据表盘

一款基于 Connect IQ 设计稿（`watchface-kit`）1:1 还原的多指标数据表盘。设计画布为 **500×500** 正方形，渲染时按屏幕宽度等比缩放，支持圆形 AMOLED（Fenix 8 / Enduro 3 / Epix 2）与圆屏 MIP（Fenix 7 / FR965 等）设备。

- **SDK**：Connect IQ SDK 9.1.0（`monkeyc` 9.1.0，API level `minSdkVersion="4.2.0"`）
- **语言**：Monkey C
- **类型**：`watchface`
- **应用 ID**：`f8a3c1b2c3d44e5f8a9b0c1d2e3f4a5b`

---

## 1. 布局还原（与设计稿基准）

所有坐标以 500×500 设计画布为基准，渲染时统一乘以缩放系数 `s = screenWidth / 500.0`（Enduro 3 屏宽 416px → `s≈0.832`）。下表中 `y` 为设计稿原始像素值。

| 区域 | 设计坐标（500 基准） | 内容 | 说明 |
|------|----------------------|------|------|
| 进度环 | 外半径 `rOut=249.5`，内半径 `rIn=231.5` | 四段进度弧 + 4 个锚点圆点 | 见 §2 |
| 电量 | `y=53.5`，电池框居中偏左 | 电池图标 + 百分比 | `System.getSystemStats().battery` |
| 上方双复杂功能 | 图标 `y=90`，数值 `y=130.5`；左侧 `x=156`，右侧 `x=343` | 天气温度 / 卡路里 / 步数 / 距离 / 楼层 / 电量 | 见 §4 |
| 中央时间 | `y=220`；小时 `x=211`（右对齐），分钟 `x=272`（左对齐） | `HH : MM`（12 小时制） | 冒号用两块矩形块，位于 `x=238` |
| 日期带 | 矩形 `y=286.5`，高 `44` | 蓝牙图标 + 星期 + 月日 + AM/PM | 蓝牙图标 `x=36.5`，星期 `x=177.5`，月日 `x=297.5` |
| 底部指标 | 数值 `y=366`，标签 `y=410.5` | 左侧距离（`DST`），右侧步数（`STEP`） | 距离单位 km |

进度环几何（取自设计稿 `rebuild.py`）：

- **顶弧**：22 根刻度，角度 `TOP = [2,6,…,86]`（步距 4），线宽 `13`，渐变停止点 9 个（`8→86`）。
- **底弧**：21 根刻度，角度 `BOT = [6,9,…,66]`（步距 3），线宽 `9`，渐变停止点 7 个（`7→47`）。
- **锚点圆点**：位于角度 `[0.0, 93.3, 180.0, 266.7]`，圆心半径 `240.5`，圆点半径 `9.5`。
- 刻度“点亮”数量按对应指标进度换算：`litTR/TL = progress × 22`，`litBR/BL = progress × 21`。

时间字体为 `FONT_NUMBER_HOT`（大号数字），其余为 `FONT_MEDIUM` / `FONT_SMALL`。

---

## 2. 七套主题（Themes）

颜色数据由 `watchface-tokens.json` 经 `gen_themes.py` 生成到 `source/Themes.mc`（**请勿手改**，改 tokens 后重新生成）。每套主题包含：顶/底弧渐变停止点、未点亮刻度色 `tickOff`、锚点色 `anchorDot`、日期带填充 `bandFill` / 文字 `bandText`、强调色 `accent`、主文字 `textPrimary`、冒号色 `colon`、小时 `hours`、分钟 `minutes`。

| # | 主题 | 主色调 | 分钟数字 | 日期带 |
|---|------|--------|----------|--------|
| 1 | Ember  | 橙红渐变（黄→红） | `0xFCA901` | 橙底黑字 |
| 2 | Aurora | 青绿渐变（黄绿→青） | `0xAAF701` | 深灰底白字 |
| 3 | Brass  | 金铜渐变 | `0xECCC93` | 深棕底白字 |
| 4 | Voltage | 蓝→黄渐变 | `0x52A8FD` | 蓝底黑字 |
| 5 | Reef   | 橙→青渐变 | `0xFC7801` | 青底黑字 |
| 6 | Acid   | 黄绿（近单色） | `0xC4F900` | 深灰底黑字 |
| 7 | Kelp   | 橙→绿渐变 | `0xF4880A` | 深灰底黑字 |

---

## 3. 可配置设置（Garmin Connect / 表盘设置）

通过 `resources/settings/` 暴露，键名与默认值见 `properties.xml`：

| 设置 | 键 | 可选值 | 默认 |
|------|----|--------|------|
| 主题 | `Theme` | 1–7（Ember…Kelp） | 1 |
| 顶右弧指标 | `RingTR` | 0 步数 / 1 卡路里 / 2 距离 / 3 楼层 / 4 动动条 | 0 |
| 顶左弧指标 | `RingTL` | 同上 | 1 |
| 底右弧指标 | `RingBR` | 同上 | 4 |
| 底左弧指标 | `RingBL` | 同上 | 3 |
| 左上复杂功能 | `LeftTop` | 0 天气 / 1 卡路里 / 2 步数 / 3 距离 / 4 楼层 / 5 电量 | 1 |
| 右上复杂功能 | `RightTop` | 同上 | 0 |
| 显示顶行 | `ShowTop` | 布尔 | true |
| 显示日期带 | `ShowBand` | 布尔 | true |
| 显示底行 | `ShowBottom` | 布尔 | true |

> 指标默认值对应设计稿：**顶右=步数、顶左=卡路里、底右=动动条、底左=楼层**；左上=卡路里、右上=天气。

### 指标进度换算规则（`metricProgress`）

| idx | 指标 | 进度分母 |
|-----|------|----------|
| 0 | 步数 Steps | `stepGoal`（目标步数） |
| 1 | 卡路里 Calories | 固定 2000 kcal |
| 2 | 距离 Distance | 10 km（1,000,000 cm） |
| 3 | 楼层 Floors | `floorsClimbedGoal`（默认 10） |
| 4 | 动动条 Move Bar | `moveBarLevel`（归一化 0–1） |

进度超出 1 会被钳制，弧长即“点亮”刻度数。

---

## 4. 数据源与已知偏差

| 元素 | 数据来源 | 备注 |
|------|----------|------|
| 步数 / 卡路里 / 距离 / 楼层 / 动动条 | `ActivityMonitor.getInfo()` | SDK 9.1.0 字段：`steps/stepGoal/calories/distance/floorsClimbed/floorsClimbedGoal/moveBarLevel` |
| 天气温度 | `Weather.getCurrentConditions().temperature` | 需手表已配对天气 |
| 电量 | `System.getSystemStats().battery` | 0–1 浮点，×100 显示 |
| 日期 / 时间 | `Time.Gregorian` | 12 小时制，带 AM/PM |
| 蓝牙图标 | `System.getDeviceSettings().phoneConnected`（仅取状态） | 见下方偏差 |

### ⚠️ 与设计稿的关键偏差

1. **“日出（sunrise）”元素 → 实时天气温度。** 设计稿顶部复杂功能中有一个日出图标及时间，但 `Weather.CurrentConditions` 在 SDK 9.1.0 **不暴露 sunrise 字段**。因此该位置改为显示**实时天气温度**（`NN°`），图标保留太阳造型。
2. **进度环为实时数据**，非设计稿中的静态填充演示值；四段弧指标可在设置中自由分配。
3. **蓝牙图标**目前按日期带文字色常显（未根据 `phoneConnected` 切换亮/暗），如需“未连接变暗”可后续在 `drawDateBand` 中据 `ds.phoneConnected` 调色。

---

## 5. 编译 / 构建

需安装 Connect IQ SDK（本文基于 9.1.0）并把 `monkeyc` 加入 PATH，且准备开发者密钥 `developer_key.der`（已在仓库内）。

```bash
# 单设备（Enduro 3 主产物）
monkeyc -o bin/Fenix8V3.prg -f monkey.jungle -y developer_key.der -d enduro3

# 导出调试资源（含 -settings.json，便于模拟器载入设置）
monkeyc -o bin/Fenix8V3.prg -f monkey.jungle -y developer_key.der -d enduro3 -x

# 多设备批量（已验证可编译）
for d in enduro3 fenix843mm fenix847mm fenix8pro47mm fenix8solar47mm \
         fenix8solar51mm epix2 epix2pro47mm epix2pro51mm fenix7 fenix7x \
         fenix7s fr965 fr265 fr255 venu3 vivoactive5; do
  monkeyc -o "bin/Fenix8V3_${d}.prg" -f monkey.jungle -y developer_key.der -d "$d" \
    && echo "[$d] OK" || echo "[$d] FAIL"
done
```

已验证编译通过的设备：`enduro3, fenix843mm, fenix847mm, fenix8pro47mm, fenix8solar47mm, fenix8solar51mm, epix2, epix2pro47mm, epix2pro51mm, fenix7, fenix7x, fenix7s, fr965, fr265, fr255, venu3, vivoactive5`。产物位于 `bin/`，每个设备对应一个 `.prg` 及 `.prg.debug.xml`（调试版含资源镜像）。

---

## 6. 模拟器与侧载

1. **Connect IQ Simulator**（Garmin 自带）：`File → Open App Project` 选本目录，选设备后 `Run`。在 `bin/*.prg.debug.xml` 旁会生成 `-settings.json`，可在模拟器菜单 `View → Settings` 载入并实时切换主题/指标验证。
2. **真机侧载（Garmin Connect / Garmin Express）**：
   - 用 Garmin Express 或 Connect 手机 App 的“侧载（sideload）”功能导入对应设备的 `bin/Fenix8V3_<device>.prg`；
   - 或把 `.prg` 拷入手表的 `/GARMIN/Apps/` 目录（需开发者模式 / WiFi 文件传输）。
3. 安装后在手表“表盘”列表选择 **Fenix 8 V3**，长按进入设置即可调主题与指标。

---

## 7. 目录结构

```
fenix8v3-watchface/
├── manifest.xml              # 应用清单（ID / 支持设备 / 语言）
├── monkey.jungle             # 构建配置（manifest + 源码/资源路径）
├── developer_key.der         # Connect IQ 开发者签名密钥
├── source/
│   ├── Fenix8V3App.mc        # 应用入口：getInitialView / onSettingsChanged
│   ├── Fenix8V3View.mc       # 表盘渲染主逻辑（onUpdate + 各 draw*）
│   └── Themes.mc             # ⚠️ 自动生成：7 套主题颜色（勿手改）
├── resources/
│   ├── strings/strings.xml   # AppName / 设置项 / 主题 / 指标 / 字段文案
│   └── settings/
│       ├── properties.xml   # 设置默认值
│       └── settings.xml      # 设置 UI 定义（列表/布尔）
└── bin/                      # 编译产物（.prg + 调试 xml + settings.json）
```

---

## 8. 二次开发与扩展

- **改主题配色**：编辑 `watchface-tokens.json`（设计稿目录下），运行 `gen_themes.py` 重新生成 `source/Themes.mc`。新增主题时同步在 `Themes.mc` 的 `ORDER` 数组、`settings.xml` 的 `Theme` 列表、`strings.xml` 的 `ThemeXX` 文案中登记。
- **加指标**：在 `metricProgress`（进度换算）与 `complicationValue`（复杂功能文本）两个方法里按 `idx` 分支扩展，并在 `settings.xml` / `properties.xml` 的列表项补充。
- **调布局**：所有坐标集中在 `Fenix8V3View.mc` 的 `draw*` 方法里，均为 “设计像素 × `s`” 形式，改一处即可全局缩放生效。

---

## 9. 设计稿来源

还原基准为 `watchface-kit.zip` 内的 8 张 SVG 变体 + `watchface-tokens.json`（配色）+ `watchface-spec.html`（像素测量规范）+ `rebuild.py`（几何常量）。本仓库为按该规范落地的 Monkey C 实现，设计版权归原作者所有。