fenix8v3-watchface/README.md

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（已在仓库内）。

# 单设备（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 实现，设计版权归原作者所有。