自定义表盘参考文档

本页面向新表盘设计师提供参考。本文将列出创建或制作动态表盘时可用的所有关键词和功能。

自定义表盘V2版本（Wear apk 3.3.0及以上）的新功能和按键详见此处

自定义表盘格式

自定义表盘是为AAPS设计的开放格式，关联至手表端新版”AAPS(自定义)”表盘。

表盘文件为简易zip压缩包，但需包含以下文件才能被识别为表盘文件：

一个名为CustomWatchface的图像文件（可为位图CustomWatchface.jpg、CustomWatchface.png或矢量图CustomWatchface.svg）。该文件是点击”加载表盘”按钮时用于选择表盘的小图标，同时也是AAPS Wear插件中显示的图像。
一个名为CustomWatchface.json的文件（参见下文JSON结构）。该核心文件包含设计表盘所需的全部信息。该json文件必须格式正确（在文本编辑器中手动编辑时最易出错，缺失或多一个逗号都会破坏json格式）。该JSON文件必须包含带非空"name"键的"metadata"区块。这将作为自定义表盘的名称（参见下文元数据设置）
该zip文件应尽可能小（建议小于500KB）。文件过大将被拦截，无法传输至手表。

zip文件还可包含额外资源文件：

表盘标准视图使用的硬编码图像文件名（如Background、CoverChart…参见下文硬编码资源文件列表）。所有文件均可采用jpg、png或svg格式。但多数情况下需使用支持透明度的png或svg格式（jpg体积虽小于png但不支持透明）。请注意，svg文件（矢量格式）通常能实现最佳画质与最小体积的结合。
可自由命名的附加资源文件。这些附加文件可为图像文件或字体文件（字体支持ttf和otf格式）。请注意，这些附加文件的文件名（不含扩展名）将作为JSON文件中的keyValue，用于指定其使用位置或时机。
- 图像文件常用作文本视图背景或动态动画素材（如电量从0%到100%的变化效果）
- 字体文件支持在表盘中使用定制字体

JSON 结构

JSON文件可通过记事本（或notepad++）文本编辑器编辑（推荐能识别JSON并支持彩色格式的notepad++）

文件包含字符串键"string_key":及键值，键值可为"key value"类字符串、整数、true/false布尔值或数据块。
各键值间用逗号,分隔
数据块以{开始，以}结束
json文件整体为数据块，以{起始、}结束，内部所有嵌套块均通过"key"关联（键名在块内须唯一）。
为提升json文件可读性，通常采用缩进格式（每个新键换行显示，每个新块向右缩进4个空格字符）

元数据设置

该区块是json文件中首个且必须包含的区块。该区块包含与此表盘相关的所有信息，如名称、作者、创建或更新日期、作者版本或插件版本。

以下是元数据区块示例：

"metadata": {
    "name": "默认表盘",
    "author": "我的名字", 
    "created_at": "2023年10月7日",
    "author_version": "1.0",
    "cwf_version": "1.0",
    "comment": "默认表盘模板，点击'导出表盘'按钮可生成"
},

请注意，日期中的/是特殊字符，需在前添加转义符\才能被json正确识别。

部分json文件中可能含额外键"filename"，该键会在自定义表盘加载至AAPS时自动生成或更新（用于在导出文件夹向用户显示zip文件名），因此可从元数据区块中删除此键。

常规参数设置

在首个元数据区块后，需设置常规参数（参见下文常规参数列表），用于配置图表颜色（碳水、大剂量、血糖值等）以及范围内/高/低血糖的默认颜色（血糖值及箭头的预设颜色）。

以下是常规参数示例：

"highColor": "#FFFF00",
"midColor": "#00FF00",
"lowColor": "#FF0000",
"lowBatColor": "#E53935",
"carbColor": "#FB8C00",
"basalBackgroundColor": "#0000FF",
"basalCenterColor": "#64B5F6",
"gridColor": "#FFFFFF",
"pointSize": 2,
"enableSecond": true,

ImageView 设置

自定义图像可通过匹配表盘布局中各ImageView的正确文件名进行调整，json区块仅用于定义位置、尺寸、可见性，并可选择性调整颜色：

以下是秒针(second_hand)的图像区块示例（此例zip未包含图像文件，将使用默认秒针图像但应用自定义颜色）：

"second_hand": {
    "width": 400,
    "height": 400,
    "topmargin": 0,
    "leftmargin": 0,
    "visibility": "visible",
    "color": "#BC906A"
}

To have second_hand colored with default BG color (lowRange, midRange or highRange), you just have to modify the latest line with the keyValue bgColor

    "color": "bgColor"

TextView 设置

文本视图(TexView)参数比图像视图更丰富：可调整旋转角度（整数值/度）、字号（整数值/像素）、对齐方式（默认居中，可选左/右对齐），并支持设置字体、字型、文字颜色及文本视图背景色。

"basalRate": {
    "width": 91,
    "height": 32,
    "topmargin": 133,
    "leftmargin": 249,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 23,
    "gravity": "center",
    "font": "default",
    "fontStyle": "bold",
    "fontColor": "#BDBDBD"
},

注意：若需隐藏表盘中的某个视图，除将"visibility"设为"gone"外，还需将其尺寸和位置调整至可视区域外，例如：

"second": {
    "width": 0,
    "height": 0,
    "topmargin": 0,
    "leftmargin": 0,
    "rotation": 0,
    "visibility": "gone",
    "textsize": 46,
    "gravity": "center",
    "font": "default",
    "fontStyle": "bold",
    "fontColor": "#BDBDBD"
},

若尺寸和位置位于可视区域内，表盘刷新时可能出现隐藏值的闪烁现象。

若需自定义文本视图背景图像，可使用键"background":并将zip内图像文件名设为键值，亦可直接通过"color:"键更改背景色。

"background": "fileName"

另有4个专用文本视图（命名为freetext1至freetext4），含特定参数"textvalue":，可用于设置标签等固定文本。

ChartView 设置

图表视图是特殊视图，可共享部分图像视图或文本视图的参数…

该视图的标准设置非常简单：

"chart": {
    "width": 400,
    "height": 170,
    "topmargin": 230,
    "leftmargin": 0,
    "visibility": "visible"
},

图表视图可添加的两个额外参数：通过"color"键设置背景色（默认透明），或通过"background"键设置背景图像。

如何构建/设计您的首个表盘

所需工具

文本编辑器：建议使用NotePad++（或同类工具），作为简易文本编辑器，其优势在于可显示带颜色标记的格式化文本，便于错误排查。任何简易文本编辑器均可胜任。因需调整json信息。
图像编辑器（位图/矢量图）
- 如果您使用位图
  - 图像编辑器需支持透明通道处理（背景上层图像均需此功能），若使用位图则需兼容png格式。
  - 背景图像可采用jpg格式（体积较png更小）。
  - 图像编辑器需支持以像素为单位测量图形对象（如简单方形）的坐标参数（顶部、左侧、宽度、高度）。
  - 图像编辑器需支持以十六进制RRVVBB代码显示颜色。
  - 图像编辑器需能将图像调整为400px×400px分辨率（此分辨率至关重要）。
- 如果您使用矢量图
  - 矢量图像应导出为svg格式。

获取模板以避免从零开始。

设计首个表盘时，最佳方案是从默认表盘开始（可确保获得含所有正确排序视图的最新版本）。

点击Wear插件中的”导出模板”按钮，即可在AAPS/exports文件夹获取zip文件。
请注意：需连接手表至AAPS才能显示自定义表盘按钮（调试、测试及调整自定义表盘时亦需保持连接）。

默认表盘极为简洁，zip文件仅包含以下两个文件：

CustomWatchface.png（用于表盘选择的默认表盘预览图）
CustomWatchface.json

在电脑中整理您的文件

最便捷的操作方式是将手机连接电脑，并专注于两个特定文件夹：

在专用文件夹（内含json文件、位图/矢量图、字体等所有素材）中打开资源管理器，并将CustomWatchface.zip文件置于其中。
同时打开另一个资源管理器（或调整导航树）以访问Phone/AAPS/exports文件夹。

如此操作极为简便：每次用文本编辑器修改json文件或用图像编辑器（位图/矢量图）调整图像后，仅需：

在各应用程序中保存修改内容。
将所有文件拖放至CustomWatchface.zip文件中。
将CustomWatchface.zip拖放至手机的AAPS/exports文件夹。
将CustomWatchface发送至手表以查看效果。

初始化表盘自定义设置

首先需定义表盘名称（便于测试时快速选择），并开始调整json文件开头的元数据键值。

随后需设定要显示的信息，即确定哪些视图应显示或隐藏。

是否启用秒针显示？
需设计模拟表盘、数字表盘或两者兼具？

现在您可通过修改json文件中的"visibility"键值来设定每个视图为"visible"（显示）或"gone"（隐藏）。

您还可先初步调整顶部、左侧边距及宽高数值来布局表盘（这些数值后续将通过图像编辑器精确校准）。

注：所有设计均在400px×400px矩形框内完成。因此所有元素均需在此尺寸范围内采用绝对坐标定位。

设计首个表盘时需注意：所有元素按从底层到顶层的顺序堆叠排列，因此每个视图（ImageView或TextView）都可能遮挡后方内容…

CustomWatchface layers

json文件中所有视图均按从底层到顶层的顺序排列（便于您记忆各视图的遮挡关系…）

若首次设计或调整自定义表盘，建议从简单操作入手：更改部分视图的可见性、添加专属背景图（无需修改json文件）…

管理颜色

json文件中包含多个颜色设定键：视图的"color"、"fontColor"，以及"highColor"、"midColor"、"lowColor"等（详见通用参数列表）。

颜色通过以#开头的文本字段指定，后接十六进制格式的RRGGBB（红绿蓝）值：

"#FFFFFF"为白色，"#000000"为黑色，"#FF0000"为红色…

还可添加2位Alpha通道值来设定透明度（AARRGGBB格式）：

"#00000000"表示完全透明，"#FF000000"表示完全不透明（因此"#FF000000"等同于"#000000"）

您还可使用特定键值"bgColor"，根据血糖值自动调用通用参数中设定的"highColor"、"midColor"、"lowColor"：

"fontColor": "bgColor", 将根据血糖值自动设置视图的字体颜色
注意：sgv（血糖值）和direction（趋势箭头）视图会自动应用通用参数中的血糖颜色设置（若需为这两个视图设定不同颜色，需使用进阶的dynData功能配合单阶颜色…）

有关ImageView及"color":键的详细信息，请参阅下文调整图像颜色专章。

嵌入硬编码图像

调整表盘最便捷的方式是在zip文件中包含特定命名的图像（参见硬编码资源文件列表）

图像需采用.jpg、.png或.svg格式。但需注意：jpg格式不支持透明度，因此仅适用于背景图层。所有中间图层（如cover_chart、cover_plate、表针）请使用.png或.svg格式图像
若您使用矢量图像编辑器（如Illustrator），建议优先选择.svg格式，该格式能生成体积小巧的文本文件且画质最佳。
务必确保使用精确的文件名（含大小写敏感）。

若需定制背景图，只需在zip文件中添加名为Background.jpg的文件（无需修改其他内容）。将zip文件发送至手表并查看效果！

若需定制模拟表盘的时针、分针或秒针，只需添加HourHand.png（或HourHand.svg）、MinuteHand.png及SecondHand.png文件。

这些图像将自动绕其中心点旋转，因此图像需设置为00:00:00状态（若设计”全屏”模拟表盘，请使用400×400像素尺寸并定位在top 0 left 0位置）。

您还可在硬编码资源文件列表中注意到：每个图像视图均对应两个附加的硬编码文件名High和Low（例如可在zip文件中添加名为BackgroundHigh.jpg和BackgroundLow.jpg的其他图像）。图像将根据您的血糖水平（正常范围、高血糖或低血糖）自动切换。参见AIMICO表盘示例。

调整图像颜色

"color"键可用于调整默认图像颜色：

应用于背景视图时将设定背景色（默认为黑色）
应用于cover_plate（简易表盘）或表针时，将用指定颜色（含"bgColor"）替换默认图像（白色）

当您在位图图像（.jpg或.png）上应用"color"键时，颜色将对色彩饱和度产生独特效果。因此您仍可识别位图原貌。

最后，在.svg图像文件上，"color"键将不起作用，矢量文件的颜色被视为硬编码在图像中。若需更改颜色，需包含多个svg文件，并使用高级dynData功能进行切换

为TextView使用附加字体

穿戴应用已内置多种默认字体（参见键值章节中的字体键）。但若需使用非默认的附加字体，可在zip文件中添加字体文件：

支持的两种字体格式为.ttf和.otf文件
若在zip文件中添加自定义字体（例如名为myCustomFont.ttf的文件），则需在json文件中通过文件名指定TextView使用的字体：

"font": "myCustomFont",

请注意：部分字体文件体积较大（且zip文件存在大小限制）。因此若仅使用极少量字符（数字、.、,），可用免费工具剔除未用字符（例如此处），从而缩减字体体积。

高级功能

偏好设置功能

CustomWatchface可自动调整部分手表偏好设置，以确保表盘正确显示（前提是用户已在Wear偏好设置中授予权限）。

但此功能需谨慎使用。偏好设置与所有其他表盘共用。使用此功能需遵循以下规则：

切勿设置与隐藏视图相关的偏好设置
尽量最大化可见视图
可随意放大某些视图的宽度：
- TBR可显示为百分比（宽度较小）或绝对值（宽度较大）
- 含详细信息的delta或avg delta可设置较宽宽度
- iob2同理：该视图可显示总iob，若选择详细iob则文本可能极长

若仍需特定设置才能正确显示（如下例中详细iob空间不足时），可在元数据块中添加此类设置约束，例如将参数”强制”设为false

"metadata": {
    "name": "Default Watchface",
    "author": "myName",
    "created_at": "07\/10\/2023",
    "author_version": "1.0",
    "cwf_version": "1.0",
    "comment": "Default watchface, you can click on EXPORT WATCHFACE button to generate a template",
    "key_show_detailed_iob": false
},

若用户授权自定义表盘修改手表参数（通过Wear插件设置），则”显示详细iob”将被设为”禁用”状态并锁定（除非在Wear插件参数中撤销授权或切换其他表盘，否则无法修改此参数）

请注意：用户选择表盘时，可在选择界面查看”必要参数”的数量

下例中Gota表盘需配置1个必要参数。未获授权时该参数显示为白色；获授权后，参数将被设定并锁定（此时数字显示为橙色）

Required parameters

双视图功能

双视图功能可根据可见视图轻松调整视图位置。虽不具备完全由LinearLayout构建的布局功能，但能处理多数常见情况。

下例展示AAPS（驾驶舱）表盘：设置中所有视图均可见，以及关闭”显示设备电量”和”显示平均差值”后的同一表盘效果

Twin Views

可见当双视图之一隐藏时，另一视图会自动居中显示

本例中，"uploader_battery"区块通过"twinView":键指定"rig_battery"视图为配对对象，而"rig_battery"区块的"twinView":键则反向指定"uploader_battery"为配对视图。此外，"leftOffsetTwinHidden":键用于设定配对视图隐藏时本视图的像素左移量。

计算该数值时，可见双视图的leftMargin差值为50像素，故居中偏移量需按单方向差值的一半设定。

若双视图为垂直排列，则需改用"topOffsetTwinHidden":键

"uploader_battery": {
    "width": 49,
    "height": 30,
    "topmargin": 354,
    "leftmargin": 150,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 23,
    "gravity": "center",
    "font": "roboto_condensed_bold",
    "fontStyle": "bold",
    "fontColor": "#FFFFFF",
    "twinView": "rig_battery",
    "leftOffsetTwinHidden": 25
},
"rig_battery": {
    "width": 49,
    "height": 30,
    "topmargin": 354,
    "leftmargin": 200,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 23,
    "gravity": "center",
    "font": "roboto_condensed_bold",
    "fontStyle": "bold",
    "fontColor": "#FFFFFF",
    "twinView": "uploader_battery",
    "leftOffsetTwinHidden": -25
},

动态数据功能

DynData是最强大的功能，可根据内部数值（如血糖值、血糖水平、变化量、电池百分比等，可用数据列表见此处）为表盘添加动画效果。

为说明此功能，现以AAPS（蒸汽朋克）表盘为例：

CustomWatchface_4

该表盘需实现：右侧血糖值旋转（30度至330度）、平均差值动态范围（根据数值按5/10/20mgdl缩放）、指针旋转（需与刻度同步），以及各视图层级控制…

为配置此表盘，请参见压缩包内所有图片：

注：为展示透明度，所有图片均采用黄色背景并添加红色边框

Steampunk images

首行Background.jpg和CoverPlate.png将自动关联至对应视图（默认视图文件名），steampunk_pointer.png则由dynData控制
次行显示avg_delta动态范围的3种刻度，同样由dynData调控
第三行chartBackground.jpg将手动关联至图表视图，HourHand.png和MinuteHand.png文件则自动匹配对应视图

背景管理

首先，关于血糖值图像，此处别无选择——必须置于背景层（否则会遮挡图表视图导致不可见！）因此需将血糖值映射至背景层，再根据血糖值旋转背景图像。

在"background"区块中，我们将加入2个专用键实现旋转：

"background": {
    "width": 400,
    "height": 400,
    "topmargin": 0,
    "leftmargin": 0,
    "dynData": "rotateSgv",
    "rotationOffset": true,
    "visibility": "visible"
},

"dynData":键指定定义动画的区块（数值、范围、转换等），本例使用名为”rotateSgv”的区块（使用此功能时请选用明确名称）

"rotationOffset": true,声明该数值动画应为旋转效果。（若需创建滑动效果，还可使用"leftOffset"和"topOffset"键）

现在我们将跳转至文件末尾，最后一个视图之后：

"second_hand": {
    "width": 120,
    "height": 120,
    "topmargin": 140,
    "leftmargin": 140,
    "visibility": "gone"
},
"dynData": {
    "rotateSgv": {
        "valueKey": "sgv",
        "minData": 30,
        "maxData": 330
    },

可见在末视图("second_hand")之后，我们新增了"dynData": { ... }区块以容纳所有动画配置：

"background"视图内定义的区块命名为"rotateSgv"，这正是"dynData"中的首个配置区块！

该区块配置简明：首先通过"valueKey":键指定关联的数值来源。此处"sgv"作为”keyValue”表示血糖值（注意多数情况下keyValue与显示该信息的视图同名）。

血糖值的默认最小数据设为39mgdl，最大数据设为400mgdl（所有可用keyValue及对应最小/最大数据值详见下方动态数据参考键值）。

在"rotateSgv"区块中，另两个键("minData":和"maxData":)用于将数据范围调整为30至330。通过这些最小和最大值，我们可以直接使用数据值（无需转换）来旋转背景（以度为单位）。在此设置下，所有高于330mgdl的血糖值都将被限制在图像上限330度。

图表管理

图表默认背景为透明，为遮盖背景图像中的血糖刻度，需添加专用背景图（该图含蒸汽朋克表盘的整体阴影效果）。通过"background":键关联charBackground.jpg文件

当然，视图的尺寸和定位必须精确到像素！

"chart": {
    "width": 216,
    "height": 107,
    "topmargin": 280,
    "leftmargin": 80,
    "visibility": "visible",
    "background": "chartBackground"
},

平均差值管理

为实现平均差值的动态范围调控，我们将使用四个自由文本视图。 freetext1用于调控刻度图像，freetext2至freetext4则根据刻度控制指针旋转。

freetext1

如前所述，自由文本视图位于图表和背景层之上，因此我们设置了透明区域（图像右侧和底部）以显示这些图像。

注意：这些图像被裁切的底部区域已用作图表背景，实现无缝融合效果。

"freetext1": {
    "width": 400,
    "height": 400,
    "topmargin": 0,
    "leftmargin": 0,
    "rotation": 0,
    "visibility": "visible",
    "dynData": "avgDeltaBackground"
},

该视图关联至另一个名为avgDeltaBackground的"dynData"区块。此区块将根据avgDelta值调控avgDelta刻度。

"avgDeltaBackground": {
    "valueKey": "avg_delta",
    "minData": -20,
    "maxData": 20,
    "invalidImage": "steampunk_gauge_mgdl_5",
    "image1": "steampunk_gauge_mgdl_20",
    "image2": "steampunk_gauge_mgdl_20",
    "image3": "steampunk_gauge_mgdl_10",
    "image4": "steampunk_gauge_mgdl_5",
    "image5": "steampunk_gauge_mgdl_5",
    "image6": "steampunk_gauge_mgdl_10",
    "image7": "steampunk_gauge_mgdl_20",
    "image8": "steampunk_gauge_mgdl_20"
},

"valueKey":将关联"avg_delta"数值
minData和maxData同时会将范围限制在该表盘支持的最大值区间（-20mgdl至20mgdl）。使用mmol单位的用户请注意：AAPS内部数值始终以mgdl为单位存储。

随后我们将在此说明如何根据数值动态管理背景图像。

"invalidImage":键用于管理数据无效（或缺失）时显示的图像。此处关联压缩包内含有5mgdl刻度的附加资源图像

随后我们将使用从"image1":到"image8":的系列图像。提供的图像数量将决定minData与maxData之间的分段阶数。

image1设定avg_delta等于或接近minData时显示的图像，编号最大的图像（此处为image8）则设定avg_delta等于或接近maxData时的显示图像
在-20mgdl至20mgdl范围内，总跨度为40mgdl，除以8（提供的图像数量）即得到8个5mgdl的递进步阶
现在根据avg_delta值映射背景图像：从最低值开始，-20至-15及-15至-10区间使用steampunk_gauge_mgdl_20刻度图，-10至-5区间用steampunk_gauge_mgdl_10，以此类推直至+15至+20区间再次使用steampunk_gauge_mgdl_20背景图

freetext2 到 freetext4

对于这些视图，我们将结合之前说明的动态图像与旋转功能：

"freetext2": {
    "width": 276,
    "height": 276,
    "topmargin": 64,
    "leftmargin": 64,
    "rotation": 0,
    "visibility": "visible",
    "dynData": "avgDelta5",
    "rotationOffset": true
},
"freetext3": {
    "width": 276,
    "height": 276,
    "topmargin": 64,
    "leftmargin": 64,
    "rotation": 0,
    "visibility": "visible",
    "dynData": "avgDelta10",
    "rotationOffset": true
},
"freetext4": {
    "width": 276,
    "height": 276,
    "topmargin": 64,
    "leftmargin": 64,
    "rotation": 0,
    "visibility": "visible",
    "dynData": "avgDelta20",
    "rotationOffset": true
},

此处每个视图对应特定刻度（故关联独立dynData区块），可注意到这3个视图启用了"rotationOffset":键。现在查看首个dynData区块：

"avgDelta5": {
    "valueKey": "avg_delta",
    "minData": -20,
    "maxData": 20,
    "rotationOffset": {
        "minValue": -120,
        "maxValue": 120
    },
    "invalidImage": "null",
    "image1": "null",
    "image2": "null",
    "image3": "null",
    "image4": "steampunk_pointer",
    "image5": "steampunk_pointer",
    "image6": "null",
    "image7": "null",
    "image8": "null"
},

此处尽管动态范围仅使用-5至+5的avg_delta数据，但必须保持-20至+20mgdl的整体范围，以确保指针在刻度切换时与背景同步。因此我们保持与avgDeltaBackground相同的整体范围和分段数量（8张图像）。

请注意："invalidImage"及部分"imagexx"使用了"null"键值（该值可为压缩包内不存在的任意字符串文件名）。当文件名未找到时，视图背景图像将显示为透明。该设置确保指针仅在阶数4和5（avg delta介于-5mgdl至+5mgdl）时显示，超出此范围则隐藏。

现在可见新增的"rotationOffset":区块，内含"minValue":和"maxValue":两个键。这些数值用于将内部数据（mgdl单位）转换为所需的指针旋转角度。

蒸汽朋克表盘设计为指针提供-30度至30度的最大旋转范围。因此根据当前刻度（此处为-5mgdl至5mgdl），这些数值将对应30度的旋转角度。由于minData与maxData范围扩大4倍，对应的minValue和maxValue也需乘以4倍，即-120度至+120度。但当旋转角度超出±30度范围时指针将隐藏（无图像显示），仅当数值处于-5至+5mgdl区间时指针可见。这完全符合此处设计预期。

其他dynData区块以相同方式定义，用于调整"avgDelt10"和"avgDelta20"。

loop视图

蒸汽朋克表盘中，状态指示的绿色/红色循环箭头被禁用，该功能同样通过关联循环视图的独立dynData区块实现。

    "loopArrows": {
        "invalidImage": "greyArrows",
        "image1": "greenArrows",
        "image2": "redArrows"
    }

由于该区块仅由循环视图调用，且该视图默认管理循环数据，故"valueKey":键可省略。

循环视图默认的minData和maxData设为0分钟和28分钟，使用两张图像时：低于14分钟的数据显示image1背景，高于14分钟则显示image2。 14分钟正是绿色箭头切换为红色箭头的临界值。

本例中，greyArrows、greenArrows和redArrows文件未包含在压缩包内，故这些箭头被移除（不可见），但若需用自定义背景图像调整状态箭头，可直接使用该区块配置。

rig电池与uploader电池视图

为完成dynData功能的概览，我们将查看电池管理部分。此处设计理念是根据电池电量（0%至100%）自定义文本颜色。

"uploader_battery": {
    "width": 60,
    "height": 28,
    "topmargin": 100,
    "leftmargin": 170,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 20,
    "gravity": "center",
    "font": "default",
    "fontStyle": "bold",
    "fontColor": "#00000000",
    "dynData": "batteryIcons",
    "twinView": "rig_battery",
    "topOffsetTwinHidden": -13
},
"rig_battery": {
    "width": 60,
    "height": 28,
    "topmargin": 74,
    "leftmargin": 170,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 20,
    "gravity": "center",
    "font": "default",
    "fontStyle": "bold",
    "fontColor": "#00000000",
    "dynData": "batteryIcons",
    "twinView": "uploader_battery",
    "topOffsetTwinHidden": 13
},

可见这两个视图共享名为batteryIcons的同一dynData区块。实现原理在于：默认关联视图自身数据（当batteryIcons区块未指定"valueKey":键时，将自动应用uploader_battery或rig_battery数据，具体取决于当前视图）。

请注意这两个视图还使用了此处说明的TwinView功能。

现在让我们查看dynData区块：

"batteryIcons": {
    "invalidFontColor": "#00000000",
    "fontColor1": "#A00000",
    "fontColor2": "#000000",
    "fontColor3": "#000000",
    "fontColor4": "#000000",
    "fontColor5": "#000000"        
},

此处采用与动态背景图像完全相同的逻辑，但使用专用键值（"invalidFontColor"及"fontColor1"至"fontColor5"来定义每20%为一个阶数的5个分段）。

"fontColor1"（深红色）将用于20%以下的所有数值，超过此阈值则使用白色。
若需将阈值降至”10%以下”，只需新增"fontColor6"至"fontColor10"五个键值，也可通过逐级调整颜色实现从绿色到黄色、橙色直至红色的渐变效果。

DynPref功能

在阅读本章前，需先掌握dynData的工作原理，因DynPref是其高级应用：现在您将能根据用户偏好设置来调整每个DynData区块：

为演示DynPref功能，我们将使用两个示例：

蒸汽朋克表盘（简易应用：通过同一表盘集成mgdl与mmol版本，根据aaps中选择的单位自动切换）。
AAPS V2表盘将结合多项偏好设置，实现根据暗色模式及匹配分隔线偏好来管理文本颜色与背景。

蒸汽朋克表盘中dynPref的简易应用

在蒸汽朋克表盘中，我们根据单位设置了两组图像：包含血糖刻度的background图像将随血糖值旋转。以及根据avgDelta值动态调整刻度的freeText1。为实现表盘自动显示正确单位，需根据所选单位切换对应图像。

为此，我们将在视图区块中用dynPref键替换dynData键：

 "background": {
    "width": 400,
    "height": 400,
    "topmargin": 0,
    "leftmargin": 0,
    "dynPref": "rotateSgv",
    "rotationOffset": true,
    "visibility": "visible"
},

dynPref键的用法与前一章所述dynData键高度相似

现在我们将查看json文件末尾，位于dynData区块之后的内容：

"dynData": {
    ...
},
"dynPref": {
    "rotateSgv": {
        "prefKey": "key_units",
        "true": {
            "valueKey": "sgv",
            "minData": 30,
            "maxData": 330,
            "invalidImage": "Background_mgdl",
            "image1": "Background_mgdl"
        },
        "false": {
            "valueKey": "sgv",
            "minData": 30,
            "maxData": 330,
            "invalidImage": "Background_mmol",
            "image1": "Background_mmol"
        }
    },
    ...
}

可见定义于background视图区块的dynpref键（"dynPref": "rotateSgv"）已存在于json文件末尾的dynPref区块中：

该区块必须包含"prefKey"键，用于指定需调用的偏好设置项。本示例中，键"key_units"关联手机端AAPS选择的单位，其值为"true"表示选择mgdl单位，"false"表示选择mmol单位。

随后您将看到两个采用”dynData”格式的json区块，系统将根据所选偏好设置调用对应区块。

请注意”HardCoded”背景图像文件名现已被动态图像替代（当key_units为”true”时使用Background_mgdl.png文件，为false时使用Background_mmol.png），同时添加了"invalidImage"键确保即使未收到手机数据也始终显示背景图像。

在AAPS V2中整合dynPref的多项偏好设置

多数情况下，设置偏好时并非为了获得”动态行为”，而仅是呈现所选结果——但在dynPref中，这被视为动态功能特性…

当dynData需要指定包含图像、字体颜色、颜色等参数的完整区块时，dynPref则能根据特定偏好设置逐项组合各参数。
此处将演示如何将分隔线偏好与暗色偏好关联：当启用时（true），暗色表盘（dark参数为true）显示黑底白字，浅色表盘（dark为false）则显示白底黑字…

首先查看json文件起始部分：

"dynPrefColor": "prefColorDark",
"pointSize": 2,
"enableSecond": false,
"background": {
    "width": 400,
    "height": 400,
    "topmargin": 0,
    "leftmargin": 0,
    "visibility": "visible",
    "dynPref": "dark"
},

"dynPrefColor": "prefColorDark"将指定视图外所有默认颜色的dynPref区块。这些颜色将根据"prefColorDark"中的dark参数进行调整：

最终在dynPref区块内，您会看到针对默认颜色的专属dynPref区块：

"prefColorDark": {
    "prefKey": "key_dark",
    "true": {
        "highColor": "#FFFF00",
        "midColor": "#00FF00",
        "lowColor": "#FF0000",
        "lowBatColor": "#E53935",
        "carbColor": "#FB8C00",
        "basalBackgroundColor": "#0000FF",
        "basalCenterColor": "#64B5F6",
        "gridColor": "#FFFFFF"
    },
    "false": {
        "highColor": "#A0A000",
        "midColor": "#00A000",
        "lowColor": "#A00000",
        "lowBatColor": "#E53935",
        "carbColor": "#D07C00",
        "basalBackgroundColor": "#0000A0",
        "basalCenterColor": "#64B5F6",
        "gridColor": "#303030"
    }
}

此dynPref区块与视图用标准区块的区别在于：此处未为"key_dark"参数的每个值配置dynData区块，仅列出主色列表（highColor、midColor等）

现在查看”分隔条”内的项目（如下例中关联"matchDivider" dynPref视图的"basalRate"视图）：

"basalRate": {
    "width": 90,
    "height": 32,
    "topmargin": 127,
    "leftmargin": 242,
    "rotation": 0,
    ...
    "leftOffsetTwinHidden": 33,
    "dynPref": "matchDivider"
},

在dynPref区块中可见分隔线参数（key_match_divider键）包含”true”和”false”两个区块，这两个区块仅用于定义视图将采用”dark”动态区块（与横幅外其他视图完全相同的背景和文本颜色），或采用”white”动态区块（为背景和文本设置相反颜色）…

"matchDivider": {
    "prefKey": "key_match_divider",
    "true": {
        "dynPref": "dark"
    },
    "false": {
        "dynPref": "white"
    }
},
"dark": {
    "prefKey": "key_dark",
    "true": {
        "color1": "#000000",
        "fontColor1": "#FFFFFF"
    },
    "false": {
        "color1": "#FFFFFF",
        "fontColor1": "#000000"
    }
},

请注意此处位于”dynData”区块内，因此定义颜色或字体颜色时需使用dynData（本文未具体说明），并采用单一步骤（使用"color1"和'fontColor1'）

除image外，所有参数的默认”无效值”（若未通过"invalidColor"或"invalidFontColor"键专门设置）将采用"color1"和"fontColor1"。

接着我们将看到第三个示例——iob视图（iob1和iob2），其中详细iob数据使用较小字体，总iob数据使用较大字体：

"iob1": {
    "width": 125,
    "height": 33,
    "topmargin": 168,
    "leftmargin": 275,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 19,
    ...
    "dynPref": "prefIob1"
},
"iob2": {
    "width": 125,
    "height": 33,
    "topmargin": 196,
    "leftmargin": 275,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 24,
    ...
    "leftOffsetTwinHidden": -10,
    "dynPref": "prefIob2"
},

在默认视图设置中可见文本大小（iob1为19，iob2为24），以及两个不同的dynPref区块：一个根据详细iob参数调整文本尺寸，另一个根据暗色参数调整颜色。

"prefIob1": {
    "prefKey": "key_show_detailed_iob",
    "true": {
        "dynPref": "dark",
        "textsize1": 24
    },
    "false": {
        "dynPref": "dark"
    }
},
"prefIob2": {
    "prefKey": "key_show_detailed_iob",
    "true": {
        "dynPref": "dark",
        "textsize1": 19
    },
    "false": {
        "dynPref": "dark"
    }
},

此处可见：根据详细iob参数（"key_show_detailed_iob"键），当其为”true”时，文本尺寸被固定设置为比默认值更大的数值（24替代19）——这是通过仅含单值的文本尺寸”阶梯”功能实现的…（注意：除图像外所有参数，若未设置invalidTextSize，则无效数据将使用textsize1）

随后”dark”动态偏好区块将用于设置颜色与字体颜色

本示例中，当详细IOB启用且暗色模式开启时，将调用以下dynData区块作用于iob1视图：

{
    "color1": "#000000",
    "fontColor1": "#FFFFFF",
    "textsize1": 24
},

因此文本将显示为黑底白字，且24号字体尺寸将替换视图中预设的19号默认尺寸。

当详细IOB禁用且暗色模式关闭时，作用于同一iob1视图的dynData区块为：

{
    "color1": "#FFFFFF",
    "fontColor1": "#000000"
},

此时文本将以白底黑字显示，并保持19号字体尺寸。

dynPref使用技巧

您可以组合任意数量的偏好设置，但需注意描述区块数量会呈指数级增长：若串联3个参数且需定义所有情形（假设每个参数仅有2种取值），则需描述8个区块…
注意避免构建”无限循环”（例如当dynpref1区块需由dynpref2区块补充，而dynpref2区块又需由dynpref1区块补充时…）。此时这些dynpref区块将被视为无效…
使用视图中的"textsize"键时，必须在dynPref值区块中使用"textsize1"（因其采用”dynData”格式，本例中仅关联单一步骤的值），切勿忘记在键名后添加数字索引。
每个视图仅应设置一个"valueKey"键，因此若最终dynData区块由多个dynPref区块构建时，切勿包含多个"valueKey"（及其关联的"minData"、"maxData"等参数）。

自定义表盘V2的新功能（适用于AAPS V3.3.0及以上版本）

请注意，使用这些新功能或视图的表盘需要基于AAPS 3.3.0版本构建的最新wear apk。

若在搭载CustomWatchface V1的手表上使用”v2”压缩包，表盘将出现信息缺失或内容错误。

自定义表盘V2包含以下新功能：

全新状态视图
全新临时目标视图
全新储药器余量视图
全新格式设置功能
Show External data for Follower (up to 3 set of data within one single Watchface, for AAPS, AAPSCLIENT and AAPSCLIENT2)

全新状态视图

该视图的键为"status"，其关联区块已自动包含在wear apk”自定义表盘V2”（基于AAPS 3.3.0及以上版本构建）导出的模板中。

该视图已内置在早期AAPS（无图表）、AAPS（大图表）和AAPS（大号）等现有表盘中，并包含由wear apk构建的字符串值。

AAPS 3.3.0版本中已移除这些旧表盘，替换为3款全新自定义表盘。

最低显示信息为IOB值（无论手表IOB参数如何设置始终可见）
若在偏好设置中启用，则显示详细IOB值（大剂量IOB|基础率IOB）
以及BGI值（同样需在偏好设置中启用）

该"status"视图通过"key_show_loop_status"键（位于dynPref内）关联，用于管理可见性。

该视图在V1版本中可通过"iob1"、"iob2"和"bgi"现有视图实现，但需配置复杂的dynPref设置来根据手表不同选项调节各信息间距。

全新临时目标视图

该视图的键为"tempTarget"，其关联区块已自动包含在由wear apk”自定义表盘V2”（基于AAPS 3.3.0及以上版本构建）导出的模板中。

表盘将显示以下内容：

配置文件目标值（单值或最小-最大目标范围）（默认白色显示）
闭环调整后的目标值（默认绿色显示）
用户设定的临时目标值（默认黄色显示）

该"tempTarget"视图通过"key_show_temp_target"键（位于dynPref内）关联，用于管理可见性。

动态数据键（关联颜色信息）为"tempTarget"（TempTarget视图默认关联的动态数据键）

动态数据值对应情况：

0（配置文件目标）
1（闭环目标）或
2（用户临时目标）

Note that this view is also available for external data (see below) with "tempTarget_Ext1" and "tempTarget_Ext2" keys (View and DynData)

全新储药器余量视图

该视图的键为"reservoir"，其关联区块已自动包含在由wear apk”自定义表盘V2”（基于AAPS 3.3.0及以上版本构建）导出的模板中。

该视图以白色（默认）显示储药器余量（单位U），警告级别为黄色，紧急级别为红色。

该"reservoir"视图通过"key_show_reservoir_level"键（位于dynPref内）关联，用于管理可见性。

储药器余量关联的动态数据键为：

"reservoir"（储药器余量视图默认动态数据键）关联胰岛素余量U
最小值为0.0单位
最大值为500.0单位
"储药器余量"
0（标准余量，默认白色显示）
1（警告余量，默认黄色显示）
2（紧急余量，默认红色显示）

Note that this view is also available for external data (see below) with "reservoir_Ext1", "reservoir_Ext2", "reservoirLevel_Ext1" and "reservoirLevel_Ext2" keys (View and DynData).

动态数据或动态偏好的新格式化功能

现在您可对手表接收的原始值进行自定义格式化，这些值已包含在下方的动态数据键值表中。

为说明该功能运作方式，现以AAPS（大号）表盘为例，根据”时间间隔值”及”status”视图显示状态展示效果：

AAPS (Large)

左侧首张截图中status视图可见（含IOB、详细IOB及BGI），故仅1/3行空间显示时间戳（极简格式如1'，上传器电量显示为U:55%）
右侧截图中status视图已通过手表参数隐藏，因此有充足空间完整显示时间戳及上传器电量信息（1分钟前和上传器：55%）
最右侧截图中手表设置完全相同，但时间戳数值已超过”1”。此时自定义表盘可显示经复数处理的更新标签（2分钟前）

下文将不赘述zip文件中视图的整体管理逻辑（不同设置下各视图的定位方式），仅重点解析AAPS（大号）表盘中格式化功能与关联动态值的实现方法。

该功能需配合”动态区块”使用（可以是dynData区块或dynPref区块）

在AAPS（大号）表盘中，我们需根据参数（如status视图显隐状态）切换短/长格式，因此采用了dynPref区块实现。

首先从视图结构讲起：

"uploader_battery": {
    "width": 200,
    "height": 50,
    "topmargin": 175,
    "leftmargin": 0,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 25,
    "gravity": "center",
    "font": "roboto_condensed_light",
    "fontStyle": "normal",
    "dynPref": "uploader",
    "dynValue": false,
    "fontColor": "#BDBDBD"
},

"timestamp": {
    "width": 200,
    "height": 50,
    "topmargin": 175,
    "leftmargin": 0,
    "rotation": 0,
    "visibility": "visible",
    "textsize": 25,
    "gravity": "center",
    "font": "roboto_condensed_light",
    "fontStyle": "normal",
    "dynPref": "timestamp",
    "dynValue": false,
    "fontColor": "#FFFFFF"
},

此处最关键的是"dynValue"键：通过该键信息可实现原始值的动态管理。后方布尔值（true/false）决定是否对数值进行”转换”

false：直接使用原始值，不做任何限制或转换
true：原始值将根据dynData区块中的minData和maxData键，以及dynData中定义的minValue和maxValue进行转换

该表盘直接使用原始值未作转换，故两个视图的"dynValue"键均设为false。

现在查看"dynPref"中定义的"uploader"区块：

"uploader": {
    "prefKey": "key_show_loop_status",
    "true": {
        "dynPref": "uploader_true_ago",
        "invalidTextvalue": "U: --",
        "textvalue1": "U: %.0f%%"
    },
    "false": {
        "dynPref": "uploader_false_ago",
        "invalidTextvalue": "Uploader: --",
        "textvalue1": "Uploader: %.0f%%"
    }
},

默认情况下"uploader_battery"视图已关联"uploader_battery"键，无需额外声明关联关系

"valueKey": "uploader_battery"（最小值0，最大值100，原始值为手机电量百分比）

格式化字符串包含在"textvalue1"键中（"textvalue1"、"textvalue2"等键与可置于view区块的"textvalue"键关联）

"textvalue"键可在视图区块中使用格式化信息（此时格式为静态，不受数值或设置影响）
若需根据设置或数值调整格式，可应用全部dynData功能，专用键为"invalidTextValue"（不含”格式化信息”因数值无效）及"textvalue1"、"textvalue2"…（可添加任意数量键值以管理minData与maxData间的分段）
额外"dynPref"键用于定义其他区块，以根据视图显隐、暗色模式及分界器设置调整定位与色彩

关于格式化字符串的语法规则如下：%[flags][width][.precision]f

%是格式化的起始符，f为结束符（专用于双精度浮点数转换）。
- 注意：若需在字符串中使用%字符，必须写成%%以表明此处为百分号而非格式化起始符。
[flag]为可选参数，常用+强制显示正负号，或用(使负值显示在括号内
[width]为可选参数，定义输出结果的最小字符数
[.precision]用于定义小数点后的位数。
- 注意：由于数值为双精度浮点型，建议始终设置精度（避免Kotlin精度导致小数点后出现过多字符）

因此上例中%.0f会将双精度值显示为整数

现在查看管理复数形式的timestamp动态参数区块：

"timestamp": {
    "prefKey": "key_show_loop_status",
    "true": {
        "dynPref": "timestamp_true_uploader",
        "invalidTextvalue": "U: --",
        "textvalue1": "%.0f'"
    },
    "false": {
        "dynPref": "timestamp_false_uploader",
        "minData": 0,
        "maxData": 3,
        "invalidTextvalue": "-- minute ago",
        "textvalue1": "%.0f minute ago",
        "textvalue2": "%.0f minutes ago"
    }
},

当status视图可见时（即"key_show_loop_satus"键为true），采用单一格式（"textvalue1"），以'作为单位符号
若status视图隐藏，则采用两种格式：0或1时使用单数形式，大于2时使用复数形式
- "minData"和"maxData"用于定义数值范围，确保单复数切换在1和2之间生效
- 注意："maxData"（整数值）设为3而非2，因系统处理的双精度数据并非整数，故略高于或低于1的值经四舍五入后可能仍为1，但需按单复数格式区分显示。
对于timestamp视图，必须将"dynValue"键设为false，否则因单复数格式化处理，所有大于3的值都会通过maxData转换被限制显示为3分钟前…

关于格式化功能的补充说明

请谨记：唯一可用的动态值仅为此处列出的参数
所有血糖值均以mg/dL为单位，若需通过格式化功能显示mmol/L单位，必须自行处理mg/dL与mmol/L的换算。在dynData或dynPref区块中，用于定义包含数值转换"minValue"和"maxValue"的子区块必须命名为"dynValue": { ... }。（参见动态数据键）
若需在视图中使用静态格式化字符串（通过"textvalue"键定义格式，"dynValue"键启用动态值），则必须同时声明"dynData"或"dynPref"区块（即使留空）以激活格式化功能。
"textvalue1"、"textvalue2"至textvaluen可不启用格式化功能，用于将数值分段替换为特定文本标签（例如配合"day_name"键值，通过七个分段定义星期几的自定义名称等）。
完整文档请参阅Formatter类

显示跟随者的外部数据

自定义表盘现在可同时显示最多3组数据：AAPS、AAPSCLIENT和AAPSCLIENT2

要使用此功能，您需要：

手机上需安装以下3个应用中的至少2个（AAPS、AAPSCLIENT、AAPSCLIENT2）
在AAPSCLIENT和/或AAPSCLIENT2中启用数据广播功能，将数据广播至用于与CustomWatchface同步的主应用（AAPS或AAPSCLIENT）
Use a CustomWatchface that implement Views with Key including _Ext1 or _Ext2 (see Key and KeyValue reference below)

请注意：若手机主应用为AAPSCLIENT且广播数据的次级应用为AAPSCLIENT2，当使用含标准视图及Ext1附加视图（Ext1关联AAPSCLIENT，Ext2关联AAPSCLIENT2）的表盘时，需在CustomWatchface专属参数中启用切换表盘外部数据选项。

新增三个视图（"patient_name"、"patient_name_Ext1"及"patient_name_Ext2"*），用于在表盘中自动显示患者姓名（通过AAPS偏好设置配置，参见下方示例）。

CustomWatchface_7

键与键值对照表

元数据键列表

标准信息元数据键列表

键	备注
`"name"`	自定义表盘名称
`"author"`	作者名称或笔名
`"created_at"`	创建（或更新）日期，注意：`/`是特殊字符，若用于日期显示需在前添加`\`转义
`"cwf_version"`	与您表盘设计兼容的表盘插件
`"author_version"`	作者可在此指定其表盘的版本号
`"comment"`	自由文本字段，用于说明当前表盘的功能信息或使用限制

偏好设置键

键	默认值与注释
`"key_show_detailed_iob"`	true将锁定视图`iob2`上的详细IOB数据，此时`iob1`（若可见且未被图标替换）将显示IOB总量。 false则会在`iob2`视图上锁定IOB总量显示。当`iob2`视图宽度过小无法正确显示详细IOB数据时可启用此选项
`"key_show_detailed_delta"`	false（仅当设计不兼容`delta`与`avg_delta`视图的详细差值宽度时使用）
`"key_show_bgi"`	若设计需要显示`bgi`信息则设为true
`"key_show_iob"`	若设计需要显示`iob1`或`iob2`视图则设为true
`"key_show_cob"`	若设计需要显示`cob1`或`cob2`视图则设为true
`"key_show_delta"`	若设计需要显示`delta`信息则设为true
`"key_show_avg_delta"`	若设计需要显示`avg_delta`信息则设为true
`"key_show_temp_target"`	若设计需要显示`tempTarget`信息则设为true
`"key_show_reservoir_level"`	若设计需要显示`reservoir`信息则设为true
`"key_show_uploader_battery"`	若设计需要显示`uploader_battery`（手机电量）信息则设为true
`"key_show_rig_battery"`	若设计需要显示`rig_battery`信息则设为true
`"key_show_temp_basal"`	若设计需要显示`basalRate`信息则设为true
`"key_show_direction"`	若设计需要显示`direction`信息（血糖变化箭头）则设为true
`"key_show_ago"`	若设计需要显示`timestamp`信息（最近血糖数据接收时间/分钟前）则设为true
`"key_show_bg"`	若设计需要显示`sgv`信息（血糖值）则设为true
`"key_show_loop_status"`	若设计需要显示`loop`信息（闭环状态及时间间隔）则设为true
`"key_show_week_number"`	若设计需要显示`week_number`信息（周数）则设为true
`"key_show_date"`	若设计需要显示`Date`、`Month`或`Day of the week`信息则设为true

内部键

键	注释
`"filename"`	此键将在表盘加载时自动创建（或更新），并包含导出文件夹中的本地zip文件名
`"cwf_authorization"`	此键将在表盘加载时创建，并在Wear设置中每次更改授权偏好时更新，用于同步授权至手表

通用参数列表

键	备注
`"highColor"`	`"#FFFF00"`（默认黄色）：当血糖值超过上限（高血糖）时，血糖值、趋势箭头及图表中血糖值的显示颜色
`"midColor"`	`"#00FF00"`（默认绿色）：当血糖值在范围内时，血糖值、趋势箭头及图表中血糖值的显示颜色
`"lowColor"`	`"#FF0000"`（默认红色）：当血糖值低于下限（低血糖）时，血糖值、趋势箭头及图表中血糖值的显示颜色
`"lowBatColor"`	`"#E53935"`（默认深红色）：当`uploader_battery`值过低（低于20%，待确认）时的显示颜色
`"carbColor"`	`"#FB8C00"`（默认橙色）：图表中碳水化合物数据点的显示颜色
`"basalBackgroundColor"`	`"#0000FF"`（默认深蓝色）：图表中TBR曲线的显示颜色
`"basalCenterColor"`	`"#64B5F6"`（默认浅蓝色）：图表中大剂量或超微大剂量数据点的显示颜色
`"gridColor"`	`"#FFFFFF"`（默认白色）：图表中线条和文本刻度的显示颜色
`"pointSize"`	2（默认值）：图表中数据点的大小（1为小点，2为大点）
`"enableSecond"`	false（默认值）：指定表盘是否在`time`、`second`或`second_hand`视图中处理秒数。必须确保视图可见性与该全局设置保持一致，该设置将允许每秒更新时间信息
`"dayNameFormat"`	“E”（默认值）：从”E”到”EEEE”指定星期名称格式（数字、简称、全称），待确认
`"monthFormat"`	“MMM”（默认值）：从”M”到”MMMM”指定月份格式（数字、简称、全称）

硬编码资源文件列表

对于大多数图像，High和Low后缀允许根据血糖水平（在范围内、高血糖或低血糖）调整图像

文件名	备注
CustomWatchface	用于表盘选择和在Wear插件中显示的图像
Background, BackgroundHigh, BackgroundLow	无（默认黑色）：背景图像。若无背景图像，则始终显示默认黑色背景。可修改颜色以适应表盘设计
CoverChart, CoverChartHigh, CoverChartLow	无（默认值）：图表前景图像（需保持透明度以确保底层图表可见），可用于限定图表边界
CoverPlate, CoverPlateHigh, CoverPlateLow	简易表盘（默认值）：所有文本值前方的图像。必须保持透明度以确保后方所有数值可见
时针、高血糖时针、低血糖时针	hour_hand（默认值）：时针图像。提供默认图像，可调整颜色以匹配模拟表盘设计。注意：旋转轴心为图像中心点
MinuteHand, MinuteHandHigh, MinuteHandLow	minute_hand（默认值）：分针图像。提供默认图像，可调整颜色以匹配模拟表盘设计。注意：旋转轴心为图像中心点
SecondHand, SecondHandHigh, SecondHandLow	second_hand（默认值）：秒针图像。提供默认图像，可调整颜色以匹配模拟表盘设计。注意：旋转轴心为图像中心点
ArrowNone	?? （默认值）：无有效箭头时显示的图像。
ArrowDoubleUp	↑↑（默认值）：双上箭头图像
ArrowSingleUp	↑（默认值）：单上箭头图像
Arrow45Up	↗（默认值）：45度上箭头图像
ArrowFlat	→（默认值）：水平箭头图像
Arrow45Down	↘（默认值）：45度下箭头图像
ArrowSingleDown	↓（默认值）：单下箭头图像
ArrowDoubleDown	↓↓（默认值）：双下箭头图像

上述每个文件名可使用.jpg、.png或.svg扩展名。但需注意，.jpg格式不支持透明度（因此多数文件应使用.png或.svg格式，避免遮挡后方视图…）

视图键列表

此列表按从背景到前景的顺序排列，在组织表盘时了解此顺序非常重要，因为某些图像或文本可能被其他图像遮挡。

注意：所有以_Ext1或_Ext2结尾的键都是新增的，专用于多用户表盘。

键	视图类型	关联数据	动态数据键
`"background"`	Image View
`"chart"`	Specific Chart View	Graphical curves
`"cover_chart"`	Image View
`"freetext1"`	Text View
`"freetext2"`	Text View
`"freetext3"`	Text View
`"freetext4"`	Text View
`"patient_name"` * `"patient_name_Ext1"` * `"patient_name_Ext2"` *	Text View	Patient Name
`"iob1"` `"iob1_Ext1"` * `"iob1_Ext2"` *	Text View	IOB label or IOB Total
`"iob2"` `"iob2_Ext1"` * `"iob2_Ext2"` *	Text View	IOB Total or IOB Detailed
`"cob1"` `"cob1_Ext1"` * `"cob1_Ext2"` *	Text View	Carb label
`"cob2"` `"cob2_Ext1"` * `"cob2_Ext2"` *	Text View	COB Value
`"delta"` `"delta_Ext1"` * `"delta_Ext2"` *	Text View	Short delta (5 min)	delta
delta_Ext1 delta_Ext2
`"avg_delta"` `"avg_delta_Ext1"` * `"avg_delta_Ext2"` *	Text View	Avg Delta (15 min)	avg_delta avg_delta_Ext1 avg_delta_Ext2
`"tempTarget"`* `"tempTarget_Ext1"` * `"tempTarget_Ext2"` *	Text View	BG Target (single value or min - max targets values)	tempTarget tempTarget_Ext1 tempTarget_Ext2
`"reservoir"`* `"reservoir_Ext1"` * `"reservoir_Ext2"` *	Text View	Reservoir level	reservoir reservoirLevel reservoir_Ext1 reservoirLevel_Ext1 reservoir_Ext2 reservoirLevel_Ext2
`"uploader_battery"`	Text View	phone battery level (%)	uploader_battery
`"rig_battery"` `"rig_battery_Ext1"` * `"rig_battery_Ext2"` *	Text View	rig battery level (%)	rig_battery rig_battery_Ext1 rig_battery_Ext2
`"basalRate"` `"basalRate_Ext1"` * `"basalRate_Ext2"` *	Text View	% or absolute value
`"bgi"` `"bgi_Ext1"` * `"bgi2_Ext2"` *	Text View	mgdl/(5 min) or mmol/(5 min)
`"status"` * `"status_Ext1"` * `"status_Ext2"` *	Text View	Synthesis of IOB (whatever IOB setting in watch), Detailed IOB (according to setting in watch and BGI (according to setting in watch)
`"time"`	Text View	HH:MM or HH:MM:SS
`"hour"`	Text View	HH
`"minute"`	Text View	MM
`"second"`	Text View	SS
`"timePeriod"`	Text View	上午/下午
`"day_name"`	Text View	name of the day (cf. dayNameFormat)	day_name
`"day"`	Text View	DD date	day
`"week_number"`	Text View	(WW) week number	week_number
`"month"`	Text View	month name (cf. monthFormat)
`"loop"` `"loop_Ext1"` * `"loop_Ext2"` *	Text View	上次运行至今的分钟数及状态（背景色箭头），可通过DynData调整箭头颜色	loop
`"direction"` `"direction_Ext1"` * `"direction_Ext2"` *	Image View	趋势箭头	direction
`"timestamp"` `"timestamp_Ext1"` * `"timestamp_Ext2"` *	Text View	integer (min ago)	timestamp
`"sgv"` `"sgv_Ext1"` * `"sgv_Ext2"` *	Text View	sgv value (mgdl or mmol)	sgv sgvLevel sgv_Ext1 sgvLevel_Ext1 sgv_Ext2 sgvLevel_Ext2
`"cover_plate"`	Image View
`"hour_hand"`	Image View
`"minute_hand"`	Image View
`"second_hand"`	Image View

*自定义表盘V2.0及以上版本新增视图（需AAPS 3.3.0 wear apk或更高版本支持）

Json键列表

公共键

可用于所有视图类型（文本视图、图像视图、图表视图）

键	类型	注释/值
`"width"`	int	视图宽度（像素）
`"height"`	int	视图高度（像素）
`"topmargin"`	int	上边距（像素）
`"leftmargin"`	int	左边距（像素）
`"rotation"`	int	旋转角度（度）
`"visibility"`	string	参见键值表
`"dynData"`	string	指定关联动态数据及动画效果（颜色、图像、位移、旋转）的键区块名称 `"dynData": "customName",`（见下文）
`"leftOffset"`	boolean	包含此键并设为true可启用基于dynData值的水平位移（正值或负值）
`"topOffset"`	boolean	包含此键并设为true可启用基于dynData值的垂直位移（正值或负值）
`"rotationOffset"`	boolean	包含此键并设为true可启用基于dynData值的旋转（正值或负值）
`"twinView"`	string	另一视图的键（通常该视图也包含twinView参数，其中引用了本视图的键）
`"topOffsetTwinHidden"`	int	若孪生视图隐藏时垂直位移的像素数（正值或负值） topOffsetTwinHidden = (孪生视图topOffset - 本视图topOffset)/2
`"leftOffsetTwinHidden"`	int	若孪生视图隐藏时水平位移的像素数（正值或负值） leftOffsetTwinHidden = (孪生视图leftOffset - 本视图leftOffset)/2
`"dynPref"`	string	指定关联动态偏好设置及动画效果（颜色、图像、位移、旋转）的键区块名称 `"dynPref": "customName",`（见下文）

文本视图键

键	类型	备注
`"textsize"`	int	字体大小（像素）（请注意字体可能包含上下边距，因此实际文本大小通常小于设定的像素值）。注意：字体大小应小于视图高度以避免被截断
`"gravity"`	string	参见键值表
`"font"`	string	可用字体参见键值表。也可使用zip包内字体文件名（不含扩展名）
`"fontStyle"`	string	参见键值表
`"fontColor"`	string	管理字体颜色 `"#RRVVBB"`：RVB格式色码（十六进制值，#FF0000为红色） `"#AARRVVBB"`：AA含透明度（00全透明，FF不透明） `"bgColor"`：键值bgColor可根据BG值自动选用highColor/midColor/lowColor
`"allCaps"`	boolean	若需文本大写（主要用于星期或月份名称）则设为true
`"background"`	string	`resource_filename` 可将资源图片设为文本视图背景（资源文件将按比例缩放以适应文本视图尺寸）。文本将显示在背景图前方。 - 注意：该键也可用于`图表`视图，为图表设置自定义背景（显示在背景图前方）
`"color"`	string	管理视图背景色或调整图像色彩（仅限位图） `"#RRVVBB"`：RVB格式色码（十六进制值，#FF0000为红色） `"#AARRVVBB"`：AA含透明度（00全透明，FF不透明） `"bgColor"`：键值bgColor可根据BG值自动选用highColor/midColor/lowColor - 默认嵌入图像（指针/表盘）将直接应用该色彩，位图（jpg/png）会叠加饱和度渐变滤镜 - 对svg文件无效（svg色彩不可修改） - 注意：该键也可用于`图表`视图，在背景图前方设置自定义图表背景
`"textvalue"`	string	布局中4个自由文本视图（从freetext1到freetext4）的专用键，用于设置要包含的文本（可以是标签，或仅`:`若需在小时视图和分钟视图间添加分隔符…）
自Custom Watchface插件v2（AAPS 3.3）起，textvalue可包含其他文本视图的格式字符串（需配合`dynValue`键及`dynData`或`dynPref`使用）。例如
`"dynValue"`*	boolean	若需包含原始数值（双精度型）则设为true 若需用特定格式显示数值，与`texvalue`键配合使用

*在自定义表盘V2.0或更高版本中添加了按键（适用于AAPS 3.3.0 wear apk或更高版本）

ImageView键

键	类型	备注
`"color"`	string	管理视图背景色或调整图像色彩（仅限位图） `"#RRVVBB"`：RVB格式色码（十六进制值，#FF0000为红色） `"#AARRVVBB"`：AA含透明度（00全透明，FF不透明） `"bgColor"`：键值bgColor可根据BG值自动选用highColor/midColor/lowColor - 默认嵌入图像（指针/表盘）将直接应用该色彩，位图（jpg/png）会叠加饱和度渐变滤镜 - 对svg文件无效（svg色彩不可修改） - 注意：该键也可用于`图表`视图，在背景图前方设置自定义图表背景

ChartView键

键	类型	备注
`"color"`	string	管理视图背景色或调整图像色彩（仅限位图） `"#RRVVBB"`：RVB格式色码（十六进制值，#FF0000为红色） `"#AARRVVBB"`：AA含透明度（00全透明，FF不透明） `"bgColor"`：键值bgColor可根据BG值自动选用highColor/midColor/lowColor - 默认嵌入图像（指针/表盘）将直接应用该色彩，位图（jpg/png）会叠加饱和度渐变滤镜 - 对svg文件无效（svg色彩不可修改） - 注意：该键也可用于`图表`视图，在背景图前方设置自定义图表背景
`"background"`	string	`resource_filename` 可将资源图片设为文本视图背景（资源文件将按比例缩放以适应文本视图尺寸）。文本将显示在背景图前方。 - 注意：该键也可用于`图表`视图，为图表设置自定义背景（显示在背景图前方）

键值

键值	键	备注
`"gone"`	可见性	视图隐藏
`"visible"`	可见性	表盘视图可见（但可通过参数启用或禁用可见性）
`"center"`	重力	文本在视图中垂直水平居中
`"left"`	重力	文本垂直居中但左对齐于视图
`"right"`	重力	文本垂直居中但右对齐于视图
`"sans_serif"`	字体
`"default"`	字体
`"default_bold"`	字体
`"monospace"`	字体
`"serif"`	字体
`"roboto_condensed_bold"`	字体
`"roboto_condensed_light"`	字体
`"roboto_condensed_regular"`	字体
`"roboto_slab_light"`	字体
`"normal"`	字体风格
`"bold"`	字体风格
`"bold_italic"`	字体风格
`"italic"`	字体风格

动态数据键

键	类型	备注
`"dynData"`	区块	定义视图将使用的所有动态数据区块通常在末视图后定义。本区块内所有键将作为视图区块的键值使用： `"dynData": { 动态数据区块 }` 每个区块通过自定义名称及内部多个键定义： `"customName": { 单个动态数据区块 }`
`"valueKey"`	string	使用的动态数据名称（通常与关联视图键同名）若不存在，则默认采用调用本区块的视图数值。例如可定义区块自定义电池百分比而不指定valueKey，随后复用该区块自定义上传器电池与设备电池
`"minData"`	int	设定AAPS数据的最小有效值：例如若数值为sgv（内部单位mgdl），当minData设为50时，所有低于50mgdl的血糖值将强制设为50 - 注意minData与maxData将用于计算动态值（像素或角度）
`"maxData"`	int	设定AAPS数据的最大有效值：例如若数值为sgv（内部单位mgdl），当maxData设为330时，所有高于330mgdl的血糖值将强制设为330。
`"leftOffset"`	区块	根据最小/最大值设定视图水平位移像素值 - 包含minValue键、maxValue键及invalidValue键（可选） - 若数据≤minData则视图位移至minValue像素，若数据≥maxData则位移至maxValue像素注意：需在视图中将`leftOffset`设为true方可生效
`"topOffset"`	区块	根据最小/最大值设定视图垂直位移像素值 - 包含minValue键、maxValue键及invalidValue键（可选） - 若数据≤minData则视图位移至minValue像素，若数据≥maxData则位移至maxValue像素注意：需在视图中将topOffset设为true方可生效
`"rotationOffset"`	区块	根据最小/最大值设定视图旋转角度值（单位：度） - 包含`minValue`键、`maxValue`键及`invalidValue`键（可选） - 若数据≤`minData`则视图旋转`minValue`度，若数据≥`maxData`则旋转`maxValue`度注意：需在视图中将`rotationOffset`设为true方可生效
`"dynValue"`*	区块	设定动态值转换规则：将数据范围映射为像素值范围 - 包含`minValue`键、`maxValue`键及`invalidValue`键（可选） - 若数据≤`minData`则输出minValue（转为双精度），若数据≥`maxData`则输出maxValue（转为双精度）注意：需在视图中启用`dynValue`键方可生效
`"minValue"`	int	应用于视图的最终数值（该键仅适用于leftOffset、topOffset或rotationOffset区块内）
`"maxValue"`	int	应用于视图的最终数值（该键仅适用于leftOffset、topOffset或rotationOffset区块内）
`"invalidValue"`	int	数据无效时应用于视图的最终数值（该键仅适用于leftOffset、topOffset或rotationOffset区块内）
`"invalidImage"`	string	数据无效时ImageView或背景TextView使用的`资源文件名`
image1_to_n	string	`资源文件名`图像用于从接近minData的`"image1"`到接近maxData的imagen之间的每个阶梯例如若设置5张图像（从image1到image5），minData与maxData之间的范围将被分为5个阶梯，根据数据值显示对应图像
`"invalidFontColor"`	string	管理数据无效时的字体颜色阶梯 `"#RRVVBB"`或`"#AARRVVBB"`：接收无效数据时使用的颜色（若AA=00可为透明色）
fontColor1_to_n	string	管理字体颜色阶梯 `"#RRVVBB"`或`"#AARRVVBB"`：从接近minData的`"fontColor1"`到接近maxData的fontColorn之间每个阶梯使用的颜色
`"invalidColor"`	string	管理数据无效时的背景色/图像颜色阶梯 `"#RRVVBB"`或`"#AARRVVBB"`：接收无效数据时使用的颜色（若AA=00可为透明色）
color1_to_n	string	管理背景色/图像颜色阶梯 `"#RRVVBB"`或`"#AARRVVBB"`：从接近minData的`"color1"`到接近maxData的colorn之间每个阶梯使用的颜色
`"invalidTextSize"`	int	管理数据无效时的文本字号阶梯
textsize1_to_n	int	管理文本字号阶梯：从接近minData的`"textsize1"`到接近maxData的textsizen之间每个阶梯使用的字号
`"invalidLeftOffset"`	int	管理数据无效时的水平位移阶梯
leftOffset1_to_n	int	管理水平位移阶梯：从接近minData的`"leftOffset1"`到接近maxData的leftOffsetn之间每个阶梯使用的位移值注：可与dynPref配合实现视图隐藏时的位移联动
`"invalidTopOffset"`	int	管理数据无效时的垂直位移阶梯
topOffset1_to_n	int	管理垂直位移阶梯：从接近minData的topOffset1到接近maxData的topOffsetn之间每个阶梯使用的位移值注：可与dynPref配合实现视图隐藏时的位移联动
`"invalidRotationOffset"`	int	管理数据无效时的旋转角度阶梯
rotationOffset1_to_n	int	管理旋转角度阶梯：从接近minData的rotationOffset1到接近maxData的rotationOffsetn之间每个阶梯使用的旋转角度
`"invalidTextvalue"`*	string	管理数据无效时的文本值
textvalue1_to_n *	string	管理文本值阶梯：从接近minData的textvalue1到接近maxData的textvaluen之间每个阶梯使用的文本值注：若在视图中启用`"dynValue"`键可包含格式化字符串

*在自定义表盘V2.0或更高版本中添加了按键（适用于AAPS 3.3.0 wear apk或更高版本）

动态数据键值

键值	键	备注
`"sgv"` `"sgv_Ext1"` * `"sgv_Ext2"` *	键值	默认minData = 39 mgdl 默认maxData = 400 mgdl - 注意实际maxData取决于传感器，且内部计算值单位始终为mgdl
`"sgvLevel"` `"sgvLevel_Ext1"` * `"sgvLevel_Ext2"` *	键值	默认minData = -1（低血糖）默认maxData = 1（高血糖）血糖在范围内 = 0
`"direction"` `"direction_Ext1"` * `"direction_Ext2"` *	键值	默认minData = 1（双下箭头）默认maxValue = 7（双上箭头）水平箭头数据 = 4 错误或缺失数据 = 0（??）
`"delta"` `"delta_Ext1"` * `"delta_Ext2"` *	键值	默认minData = -25 mgdl 默认maxData = 25 mgdl - 注意实际最小/最大值可能超出此范围，且内部计算值单位始终为mgdl
`"avg_delta"` `"avg_delta_Ext1"` * `"avg_delta_Ext2"` *	键值	默认minData = -25 mgdl 默认maxData = 25 mgdl - 注意实际最小/最大值可能超出此范围，且内部计算值单位始终为mgdl
`"tempTarget"`* `"tempTarget_Ext1"` * `"tempTarget_Ext2"` *	键值	默认minData = 0（配置文件目标）默认maxData = 2（临时目标）由闭环调整的目标 = 1 默认或缺失信息 = 0
`"reservoir"`* `"reservoir_Ext1"` * `"reservoir_Ext2"` *	键值	默认minData = 0单位默认maxData = 500单位
`"reservoirLevel"`* `"reservoirLevel_Ext1"` * `"reservoirLevel_Ext2"` *	键值	默认minData = 0（标准颜色）默认maxData = 2（紧急颜色）警告颜色 = 1
`"uploader_battery"`	键值	默认minData = 0% 默认maxData = 100%
`"rig_battery"` `"rig_battery_Ext1"` * `"rig_battery_Ext2"` *	键值	默认minData = 0% 默认maxData = 100%
`"timestamp"` `"timestamp_Ext1"` * `"timestamp_Ext2"` *	键值	默认minData = 0分钟默认maxData = 60分钟
`"loop"` `"loop_Ext1"` * `"loop_Ext2"` *	键值	默认minData = 0分钟默认maxData = 28分钟 - 注意：14分钟以下状态箭头显示绿色，14分钟以上显示红色。若设置2张图像，可使用自定义图像替换状态背景（保持默认min和maxData值）
`"day"`	键值	默认minData = 1 默认maxData = 31
`"day_name"`	键值	默认minData = 1 默认maxData = 7
`"month"`	键值	默认minData = 1 默认maxData = 12
`"week_number"`	键值	默认minData = 1 默认maxData = 53

*在自定义表盘V2.0或更高版本中添加了按键（适用于AAPS 3.3.0 wear apk或更高版本）

动态偏好键

键	类型	备注
`"dynPref"`	区块	定义视图将使用的所有动态偏好设置块。通常放置在最后一个视图或dynData块之后。本块内定义的所有键都将作为视图块中的键值使用： `"dynPref": { 动态偏好设置块 }` 每个块由自定义名称和若干内部键组成： `"自定义名称": { 单个动态偏好设置块 }`
`"dynPref"`	string	在视图块内指定使用的动态dynPref块名称（通常与关联视图键或关联偏好设置同名）。
`"dynPref"`	string	在包含于dynPref块的部分dynData块内指定用于补全dynData块的动态dynPref块名称。这允许您根据多项偏好设置来调整dynData块
`"dynPrefColor"`	string	此键专用于包含所有主颜色（高值颜色、中值颜色、低值颜色、图表颜色等）的主配置块。若需根据偏好设置调整主颜色时使用此键
`"prefKey"`	string	指定用于获取用户偏好的键值（参见下方PrefKey取值）。此键应在`dynPref`块中使用。根据偏好键的不同，`dynPref`块应包含与prefKey取值数量相同的键。注意多数情况下偏好为”布尔型”，因此dynPref块中通常包含这两个dynData块： `"true": { dynData块 },` `"false": { dynData块 }`
`"true"`	区块	大多数偏好设置将使用布尔值`"true"`或`"false"`。指定用户选择偏好为true时使用的dynData块。注意：若该块同时包含`"dynPref":`键，此dynData块将与其他块合并。这允许您根据一项偏好调整颜色，同时根据另一项偏好调整文本大小
`"false"`	区块	大多数偏好设置将使用布尔值`"true"`或`"false"`。指定用户选择偏好为false时使用的dynData块。注意：若该块同时包含`"dynPref":`键，此dynData块将与其他块合并。这允许您根据一项偏好调整颜色，同时根据另一项偏好调整文本大小

PrefKey取值

上文偏好设置键章节中包含的所有键都可用于调整视图参数

您还可以使用以下AAPS(自定义)专属参数中包含的附加键：

键	类型	备注
`"key_units"`	boolean	true: AAPS中选定单位为mgdl时 false: AAPS中选定单位为mmol时
`"key_dark"`	boolean	true: 使用深色背景 false: 使用浅色背景注：该参数常见于早期AAPS表盘（AAPS、AAPS V2等）中
`"key_match_divider"`	boolean	true: AAPS、AAPS v2表盘中的分隔线将不可见 false: AAPS、AAPS v2表盘中的分隔线将可见注：该设置常与深色偏好结合使用（通过在`dynData`块中使用`dynPref`键），以设置与深色参数相同或相反的文本颜色（及背景）…