ericwyuan/fenix8v3-watchface
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d457f8244e342d64750d923c5da2cfb19d34b97d
fenix8v3-watchface/README.md
ericwyuan d457f8244e Add the on-device data field catalogue, always-on mode, and real icons 
Fields
  75 selectable fields across date/time, activity, body, system,
  environment, weather and custom text, numbered to match
  watchface.io/docs/datafields so the two catalogues line up.  All four
  slots (both top, both bottom) pick from the same table and the bottom
  captions follow the selection.  tools/gen_fields.py owns the table and
  emits FieldTable.mc, settings.xml and both languages' strings, so those
  cannot drift apart.

  Fields.Ctx fetches each API at most once per draw, and only if some slot
  asks -- the forecast, user profile and sensor history lookups are lazy.

  The rest of that catalogue is deliberately absent: OpenWeatherMap and
  StormGlass need network calls and user API keys, the per-sport weekly and
  28-day aggregates come from a phone-side Garmin Connect integration rather
  than any on-device API, and the app complications need those apps
  installed.  README section 7 lists what was left out and why.

Permissions
  UserProfile and SensorHistory are now declared; without them resting heart
  rate, VO2 max, pulse ox and body battery throw at runtime.  Sensor turns
  out to be rejected outright for type="watchface", so altitude and pressure
  read from Activity.Info instead.

Always-on display
  AMOLED devices need the lit-pixel count cut while asleep.  drawAmbient
  drops the band fill and the unlit ticks, dims what remains, hides the
  complications, and walks the layout within +/-4 px per minute so nothing
  burns in.  Gated on requiresBurnInProtection, so MIP devices are untouched.

Icons
  The comps' sunrise and weather icons have two- and three-pixel features.
  Rebuilding them from circles and lines looked right at 454 px and turned to
  mush at 280.  They are now rasterised from the design paths once per screen
  width and tinted with drawBitmap2(:tintColor) -- which needs
  packingFormat="png", since a palettised source is refused at runtime.
  Launcher icons are generated at the five sizes the devices ask for.

All 17 devices build; checked on fenix847mm and enduro3 in the simulator.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-09 23:53:18 +08:00

18 KiB
Raw Blame History

Fenix 8 V3 — Garmin 数据表盘

按 watchface-kit 设计稿 1:1 还原的多指标数据表盘。设计画布 500×500，渲染时按屏宽等比缩放 s = screenWidth / 500，支持圆形 AMOLED（Fenix 8 / Epix 2 / Venu 3 等）与圆屏 MIP（Fenix 7 / Enduro 3 / FR255 等）共 17 款设备。

  • SDK：Connect IQ SDK 9.1.0（monkeyc 9.1.0，minSdkVersion="4.2.0"）
  • 语言：Monkey C；界面文案含英文与简体中文
  • 类型：watchface
  • 应用 ID：f8a3c1b2c3d44e5f8a9b0c1d2e3f4a5b

设计稿本体（7 张 SVG + tokens + 逆向脚本）在 design/，是本仓库所有坐标与配色的唯一来源。

1. 目录结构

fenix8v3-watchface/
├── manifest.xml              # 应用清单（ID / 支持设备 / 语言）
├── monkey.jungle             # 构建配置
├── design/                   # ⭐ 设计稿原件（唯一事实来源）
│   ├── watchface-0N-*.svg    #    7 套主题的矢量还原稿
│   ├── watchface-tokens.json #    配色 token
│   └── rebuild.py            #    原作者从位图逆向出 SVG 的脚本（仅存档，不参与构建）
├── tools/
│   ├── gen_themes.py         #    design/*.svg  ->  source/Themes.mc
│   ├── gen_fields.py         #    字段表 -> FieldTable.mc + settings.xml + 两种语言文案
│   ├── gen_icons.py          #    design/*.svg  ->  各尺寸图标位图 + 启动图标
│   └── gen_preview_svg.py    #    source/Themes.mc -> preview-themes.svg + preview.html
├── source/
│   ├── Fenix8V3App.mc        #    应用入口
│   ├── Fenix8V3View.mc       #    渲染逻辑（含常亮模式）
│   ├── Fields.mc             #    75 项数据字段的取值与格式化
│   ├── FieldTable.mc         #    ⚠️ 自动生成：字段 id 表
│   └── Themes.mc             #    ⚠️ 自动生成：七套主题配色
├── resources/                #    英文文案 + 设置项定义（部分自动生成）
├── resources-chn/            #    简体中文文案
├── resources-icons-<宽度>/    #    ⚠️ 自动生成：按屏幕尺寸光栅化的图标
├── resources-launcher-<尺寸>/ #    ⚠️ 自动生成：各尺寸启动图标
└── bin/                      #    编译产物（已 gitignore）

重新生成全部派生文件：

python3 tools/gen_themes.py && python3 tools/gen_fields.py \
  && python3 tools/gen_icons.py && python3 tools/gen_preview_svg.py

三份渲染实现（表盘 / SVG 预览 / HTML 预览）只有 一份颜色数据：Themes.mc。预览脚本直接解析它，不会与固件漂移。字段表、设置项、两种语言的文案同样只有 tools/gen_fields.py 里那一张表。

2. 布局（500 基准，取自设计稿 SVG 路径的墨迹包围盒）

元素 位置 说明
进度环 内半径 231.09，外半径 249.10 见 §3
电量图标 x=192.70，cy=53.20，26.20×17.81 圆角外框 + 按电量填充 + 右侧触点
电量数值 左对齐 x=232.00 NN%
上方双数据 图标 cy=90，数值 cy=131.06；左 x=157.00，右 x=343.70 居中对齐
时间 cy=221.10；小时右对齐 x=211.40，分钟左对齐 x=276.02 竖向渐变，见 §4
冒号 x=237.88，24.24×21.30，y=183.68 / 234.57 两块矩形
日期带 y=286.30，高 44.19，文字 cy=308.10 蓝牙 cx=36.88、星期 cx=178.05、月日 cx=298.28、AM/PM 右对齐 465.89
底部数值 cy=366.76；距离右对齐 234.30，步数左对齐 267.40
底部标签 cy=410.88，同上对齐 跟随所选数据（DST / STEP / 距离 …）

字号按设计稿的**字面高度（cap height）**选取：日期带与电量 25.34、上方数据与底部行 31.50、时间 98.70。

3. 进度环

刻度是等角宽的环形扇区（fillPolygon 四点），不是径向线段。

  • 顶弧：21 根，角度 6.5 + 4.0k（k=0..20），角宽 3.108°
  • 底弧：21 根，角度 6.005 + 3.0k，角宽 2.086°
  • 四象限：右上 +a、左上 -a、左下 180+a、右下 180-a（角度为自 12 点起顺时针）
  • 锚点圆点：半径 9.00，位于圆心距 240.10、角度 0 / 93.15 / 180 / 266.85

点亮方向（与设计稿一致）：两条顶弧从 9 点 / 3 点一侧朝 12 点填充；两条底弧从 6 点朝两侧填充。

每根刻度的颜色是设计稿里逐根取样的实测值（Themes.RINGTOP[21] / RINGBOTTOM[21]），不是插值近似。

已知近似：设计稿中底弧最多只点亮 14/21 根，因此 RINGBOTTOM 的第 15–21 项无法实测，由 gen_themes.py 对最后 8 根做最小二乘线性外推得到。只有当指标超过约 67% 时才会显示这几根。

指标进度换算

idx 指标 分母
0 步数 stepGoal
1 卡路里 固定 2000 kcal
2 距离 10 km
3 楼层 floorsClimbedGoal（缺省 10）
4 动动条 MOVE_BAR_LEVEL_MAX（=5）

4. 时间数字的竖向渐变

设计稿的小时 / 分钟数字带竖向多段渐变（如 Ember 分钟由 #FEAA00 渐变到 #FF2600）。Monkey C 无法给文字直接填渐变，实现方式是同一串数字画 11 遍，每遍用 dc.setClip 限制在一条横向色带内，色带颜色取自 Themes.HOURS / Themes.MINUTES（各 11 个停止点，实测自设计稿的 linearGradient）。首尾两条色带向外延伸，保证字形不会有未绘制的缝隙。

5. 字号选择

Connect IQ 只暴露 getFontAscent / getFontDescent / getFontHeight，没有字面高度接口，而 ascent 里含有数字和大写字母用不到的变音符空间。因此代码用两个实测比例把 ascent 折算成 cap height：

文本字体（Roboto 系）  cap ≈ 0.76 × ascent
数字字体（Bionic 系）  cap ≈ 0.71 × ascent

比例是在模拟器里渲染后、从截图上量出墨迹得到的（fenix847mm：FONT_XTINY ascent 29 → 大写高 22px；FONT_NUMBER_MILD ascent 82 → 数字高 58px）。pickFont 取折算后最接近目标 cap height 的字体，而不是"最大且不超过"——后者会在设计尺寸落在两档字体之间时白白小一号。

各机型内置字体不完全相同（Roboto-Regular / RobotoCondensed-Bold / Yantramanav / 各机型位图字体），比例会有几个百分点误差。设计稿使用的是更粗更方的第三方字体，不随包分发，字形差异无法消除。

6. 七套主题

由 tools/gen_themes.py 从 design/watchface-0N-*.svg 生成。每套包含：顶/底弧各 21 根刻度色、未点亮刻度色、锚点色、日期带底/字色、冒号色、小时/分钟各 11 段渐变、强调色（图标与 DST/STEP 标签）、主文字色（各项数值）。

# 主题 主色调 强调色 日期带
1 Ember 黄 → 红 #FEAA05 橙底黑字
2 Aurora 黄绿 → 青 #ADABAE 深灰底白字
3 Brass 金铜 #B57E4B 深棕底白字
4 Voltage 蓝 → 黄 #ADABAE 蓝底黑字
5 Reef 橙 → 青 #FEAA05 青底黑字
6 Acid 黄绿（近单色） #C6FA03 深灰底黑字
7 Kelp 橙 → 绿 #34C294 深灰底黑字

改配色：编辑 / 替换 design/ 里的 SVG，然后

python3 tools/gen_themes.py && python3 tools/gen_preview_svg.py

新增主题需同步在 settings.xml 的 Theme 列表与 strings.xml（含 resources-chn/）中登记。

7. 可配置设置与数据字段

19 项设置，在 Garmin Connect 手机 App 的「表盘设置」里改（定义在 resources/settings/settings.xml，默认值在 properties.xml，两者由 tools/gen_fields.py 生成）。

设置 键 默认
主题 Theme 1 (Ember)
四段进度环指标 RingTR/TL/BR/BL 步数 / 卡路里 / 动动条 / 楼层
四个数据位 LeftTop RightTop BottomLeft BottomRight 日出 / 高低温 / 距离 / 步数
温度单位 TempUnit 跟随手表
第二时区 1 / 2 偏移（分钟） AltOffset1 AltOffset2 0
自定义文字 1 / 2 / 3 Custom1/2/3 空
显示顶行 / 日期带 / 底行 ShowTop ShowBand ShowBottom true

进度环指标：步数、卡路里、距离、楼层、动动条、活动分钟（对周目标）、身体电量。

数据字段

四个数据位共用一张 75 项 的字段表，编号沿用 watchface.io/docs/datafields，两边可以直接对照。底部两格的小标签跟随所选字段自动变化，不需要单独配置。

分类 字段
日期时间 时间、UTC 时间、第二时区 1/2、星期月日、星期日、月日、日、星期（简写/全称）、月份（名称/数字）、上午下午、周数（ISO / 日历）
活动 步数、步数取整、剩余步数、卡路里、活动卡路里、活动分钟（总/中强度/高强度/本周）、距离、上楼层数、下楼层数、爬升高度、推行距离、推行次数
身体 心率、静息心率、压力指数、血氧、呼吸频率、身体电量、活动条（正/反向）、体重、BMI、恢复时间、最大摄氧量（跑/骑）
系统 电量、剩余天数、电量+天数、闹钟、通知、勿扰、蓝牙、太阳能强度
环境 海拔、海平面气压、环境气压、日出、日落、下一太阳事件、距太阳事件、月龄、月球照明
天气 气温、最高/最低、体感、最高、最低、湿度、降水概率、风速、风向角、风向、更新时间
自定义 自定义文字 1 / 2 / 3

加字段：在 tools/gen_fields.py 的 FIELDS 表里加一行，跑一遍生成器，再到 source/Fields.mc 的 value() 里补一个分支。设置项、两种语言的文案、表盘标签会自动跟上。

⚠️ 没有实现的字段，以及原因

watchface.io 的完整目录约 300 项，本表只收了 手表本机能算出来的 那些。其余几类不是没做，是一个自包含的 Connect IQ 表盘做不了：

没做的 原因
OpenWeatherMap（约 30 项）、StormGlass.io（5 项） 需要 Communications.makeWebRequest + 用户自备 API key + 后台服务定时拉取与缓存。是另一个子系统，且要求用户自己去注册 key
各运动项目的 WTD / 近 7 天 / 本月 / 近 28 天 汇总（约 80 项） Connect IQ 不暴露按运动分类的历史累计。这些数据在 GreenBlack 那边是通过手机侧与 Garmin Connect 的集成同步来的，本机 API 只有 ActivityMonitor.getHistory() 的最近几天步数/卡路里/距离
第三方 App 复杂功能（CGM、Hydration、QuoteGlance 等 12 项） 需要用户装了对应的 App，并通过 Complications API 订阅
日历事件、计时器、倒计时 日历不对 CIQ 开放；表盘拿不到触摸输入，没法做启停
秒数 需要 onPartialUpdate 每秒重绘。技术上可行，但会明显吃电，暂未做
晨昏蒙影、黄金/蓝调时刻（约 14 项） 可以自己算太阳高度角推出来，只是还没写；月龄和月球照明已经是这样算的
睡眠得分、训练状态 ActivityMonitor.Info 上没有这两个字段（SDK 9.1.0 实测）
标记类字段（Marker，约 35 项） 那是给刻度型表盘做环形标记用的，本表盘的进度环用的是自己的指标体系

8. 数据来源与权限

元素 API
步数 / 卡路里 / 距离 / 楼层 / 动动条 / 活动分钟 / 呼吸 / 压力 / 恢复时间 ActivityMonitor.getInfo()
心率 Activity.getActivityInfo().currentHeartRate，回退 ActivityMonitor.getHeartRateHistory()
血氧 / 身体电量 SensorHistory（需 SensorHistory 权限）
静息心率 / 体重 / 身高 / 最大摄氧量 UserProfile.getProfile()（需 UserProfile 权限）
海拔 / 环境气压 / 海平面气压 Activity.getActivityInfo()
日出 / 日落 Weather.getSunrise/getSunset(location, time)，位置取 CurrentConditions.observationLocationPosition，回退 Activity.currentLocation
气温 / 体感 / 湿度 / 降水 / 风 Weather.getCurrentConditions()
最高 / 最低气温 Weather.getDailyForecast()[0]
电量 / 剩余天数 / 太阳能 System.getSystemStats()（battery 是 0–100 的百分比，不是 0–1）
闹钟 / 通知 / 勿扰 / 蓝牙 / 单位制 System.getDeviceSettings()
月龄 / 月球照明 自算（儒略日 + 朔望月 29.530588853 天）
周数 自算（ISO 8601 与日历周两种）

权限

manifest.xml 声明两项：UserProfile（静息心率、体重、VO2max）与 SensorHistory（血氧、身体电量）。用户安装时会看到授权提示。

Sensor 权限不能用于 type="watchface"（除非同时申请 Background），编译器会直接拒绝。所以海拔与气压走 Activity.Info 而不是 Sensor.getInfo()。

单位与制式跟随手表：is24Hour、distanceUnits、temperatureUnits（温度可用 TempUnit 覆盖）。天气与日出需手表已配对并同步过数据，否则显示 --。

8.2 常亮显示（AOD）

AMOLED 机型在常亮模式下必须压低点亮像素，否则既费电又有烧屏风险，Garmin 上架审核也会卡。onEnterSleep / onExitSleep 切换到 drawAmbient()：

  • 不画日期带底色（整条亮橙色横幅是最费电的元素）
  • 进度环只画点亮的刻度，且整体压暗到 45%
  • 时间与日期压暗到 55%，其余数据位全部隐藏
  • 整个画面按分钟在 ±4px 内游走，避免固定像素长期点亮

只在 DeviceSettings.requiresBurnInProtection 为真时启用；MIP 机型（Fenix 7 / Enduro 3 等）不受影响，照常全量绘制。

模拟器可用 Settings → Display Mode 切换验证。

8.5 多语言

manifest.xml 声明了 eng 与 chn，两套文案分别在 resources/strings/ 与 resources-chn/strings/，由 monkey.jungle 的 base.resourcePath = resources;resources-chn 同时纳入编译（目录名的 -chn 后缀就是语言标记）。手表会按系统语言自动选择。

表盘上的文字也走资源，不是硬编码：

资源 英文 中文
DowNames SUN,MON,…,SAT 周日,周一,…,周六
MonNames JAN,FEB,…,DEC 1月,2月,…,12月
DateFormat $1$ $2$ → SEP 9 $1$$2$日 → 9月9日
Meridiem AM,PM 上午,下午
FieldLabels TEMP,KCAL,STEP,DST,… 气温,卡路里,步数,距离,…

逗号分隔的列表在 loadStrings() 里一次性读入并拆分（loadResource 每次调用开销不低，不宜放进 onUpdate）。

中文字形依赖手表固件里的 APAC 字体包（fontSet: apac_twcn / apac_chn）。国行机型自带；国际版若未安装中文字体包，会退回英文或显示方块。模拟器可用 Settings → Language → Chinese (Simplified) 验证。

9. 构建

需安装 Connect IQ SDK 9.1.0，monkeyc 在 PATH 中，并备好 developer_key.der（不在仓库内，需自行生成或提供）。

monkeyc -o bin/Fenix8V3.prg -f monkey.jungle -y developer_key.der -d fenix847mm

全部 17 款设备批量编译（已验证通过）：

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

屏幕分辨率跨度较大（fenix7s 240×240 至 fenix847mm / venu3 454×454），全部按 s = width/500 缩放。

10. 模拟器与侧载

connectiq &                                        # 启动模拟器
monkeydo bin/Fenix8V3_fenix847mm.prg fenix847mm    # 载入表盘

非 release 编译会同时产出 bin/*-settings.json，可在模拟器 View → Settings 载入以实时切换主题与指标。注意模拟器会持久化已保存的设置，改 properties.xml 的默认值对已运行过的实例不生效，需先重置应用数据。

真机侧载：用 Garmin Express 或 Connect 手机 App 导入对应机型的 bin/Fenix8V3_<device>.prg，或把 .prg 拷入手表 /GARMIN/Apps/。

11. 预览

python3 tools/gen_preview_svg.py

产出 preview-themes.svg（七套主题一览）与 preview.html（可切换主题的单页）。两者用网页字体渲染文字，几何与配色可信，字形不可信 —— 真机字形以模拟器截图为准。

12. 与设计稿的差异

  1. 字体。设计稿用的是一款更粗、更方的第三方字体；Garmin 只提供内置 Roboto / Bionic 系列，且各机型不同。字号按 cap height 对齐，字形无法一致。
  2. 图标。设计稿里的图标是位图描出的密集矢量路径（数百个点），不适合逐帧绘制；代码用圆、多边形、线段按实测的子形状位置重建了电量、日出/日落、多云三个图标。其余数据项（卡路里 / 步数 / 距离 / 楼层）设计稿未提供图标，为自绘。
  3. 底弧高段颜色为外推值，见 §3。
  4. 进度环是实时数据，设计稿中的是固定演示状态（右上 21/21、左上 10/21、右下 9/21、左下 14/21）。

13. 设计稿版权

design/ 内的 SVG、tokens 与 rebuild.py 来自 watchface-kit，版权归原作者所有。本仓库是按该设计稿实现的 Monkey C 表盘。

Reference in New Issue View Git Blame Copy Permalink