SDK

小组件显示什么，由你的 API 返回的 JSON 决定，格式见 API 文档。协议本身很简单，但完全手写并不轻松：想用点阵显示一批文字，要自己把每个字拆成点、算好行列；想画一幅像素画，要逐格填颜色；想做一张图表，点阵要和曲线、坐标轴、标签等其他图层精确对齐，还要避开 App 渲染上的各种限制。这些都是和你的业务无关的重复劳动。

SDK 把这些工作封装成函数。你只需要从业务出发，说明要表达什么内容、用什么样式，调用对应的方法，就能得到符合协议的点阵或图层数据，无需自己拼像素点。

SDK 提供两个层次的能力：

• 基础绘制：Matrix 是一块可以自由绘制的点阵，提供画线、矩形、圆、多边形、像素文字、图片转点阵等方法；另有文字、图标、直线、形状、图片、曲线等图层的构造函数。它们对应协议里最基础的内容元素。
• 组件：SDK 把业务里最常见的内容形式做成现成的函数，本文称为组件，例如折线图、柱状图、进度条、进度环、状态条、热力图、指标卡片。一个组件由点阵、曲线和若干其他图层组合而成，你调用一次函数，就得到排好版的完整内容。组件不指向具体行业：展示的数据是销量、电量还是任务进度，由你决定。所以它比基础元素省事，又不像业务模板那样只适用于特定场景。

你的工作变成：调用 SDK 得到内容，把它放进 API 的响应体。

九种语言的 SDK 功能相同，并通过同一套跨语言测试。本页的代码卡片可以切换语言，选择会同步到整页并被记住。示例上方的效果图由 SDK 实际运行生成，渲染规则与 API 文档相同；点“输出 JSON”可以看到对应的响应。

TypeScript

包@glance-widgets/api-sdk

运行环境Node 20+，仅 ESM

Python

包glance-widgets-sdk（导入名 glance_widgets）

运行环境Python 3.9+

Go

包gitee.com/wml2025/glance-widgets-api-sdk/sdks/go

运行环境Go 1.21+

Java

包io.glancewidgets:api-sdk

运行环境Java 17+

C#

包GlanceWidgets.ApiSdk

运行环境.NET 8

PHP

包glancewidgets/api-sdk

运行环境PHP 8.1+

Ruby

包glance-widgets-sdk（导入名 glance_widgets）

运行环境Ruby 2.6+

Lua

包glance-widgets-api-sdk

运行环境Lua 5.4 + lua-cjson

C++

包仅头文件，include/glance_widgets

运行环境C++17

npm install @glance-widgets/api-sdk

先了解名称放在哪里，再看具体用法。SDK 主要包含三类可调用接口：Matrix、Box、PixelFont 等对象及其方法；文字、图表等内容构造函数；组合、输出、颜色等工具函数。图表和进度条这些“组件”通过函数创建，各语言的入口和命名方式如下。切换编程语言时，这里的说明、前后代码示例和完整类参考会一起更新。

import { Matrix, Box, toResponse } from '@glance-widgets/api-sdk';
import type { Canvas, MatrixOptions } from '@glance-widgets/api-sdk';

const canvas: Canvas = { width: 338, height: 158 };
const options: MatrixOptions = { default: 'empty' };

const matrix = new Matrix(8, 8, options); // 构造实例
matrix.set(0, 0, '#FF453A');             // 实例方法
const frame = Box.canvas(canvas).inset(0.08); // 静态方法 → 实例方法
const response = toResponse(matrix.toRoot()); // 顶层函数

选项中的协议字段保持原名，例如 dataPath、fontSizeRatio；函数名、方法名和原生类型成员按各语言习惯命名。上例展示导入、创建实例、调用实例方法、调用类或包入口，以及生成响应的基本写法；完整参数见完整类参考。

下面的程序生成一块显示 12:30 的像素时钟。它输出的就是一个完整、有效的响应。

import { pixelTextRoot, toResponse } from '@glance-widgets/api-sdk';

// Canvas of this request: gw_canvas_width_pt × gw_canvas_height_pt
const canvas = { width: 338, height: 158 };

const clock = pixelTextRoot('12:30', { canvas, theme: 'led', maxCellSize: 11.5 });
const response = toResponse(clock);

console.log(JSON.stringify(response));

程序只做了三件事：

• 确定尺寸。canvas 是小组件内容区域的大小，单位 pt。App 每次请求都会带上 gw_canvas_width_pt 和 gw_canvas_height_pt；不同机型、App 内预览和主屏幕的尺寸都可能不同，所以要按每次请求的值生成，不要写死。示例里的 338 × 158 是常见 iPhone 上的中尺寸。
• 生成内容。pixelTextRoot 用 5×7 像素字体排好文字，再算出合适的行列数，让点阵铺满整个小组件内容区域，文字在其中水平垂直居中；maxCellSize 限制像素点的大小，文字四周因此留出几圈熄灭的点，不会贴边；theme: 'led' 选择圆点发光的外观。
• 完成响应。toResponse 补全协议要求的字段并校验，得到的对象序列化成 JSON 就是响应体。

接入真实服务的写法见接入服务。

用 SDK 时会接触三种坐标，分别用在不同的地方。组件（如折线图）、图层（如文字）的位置都用 frame 或 Box 指定，比例相对于小组件的内容区域。

画布 canvas

单位pt

含义{ width, height }，小组件内容区域的大小，即请求里的 gw_canvas_width_pt / gw_canvas_height_pt。SDK 靠它得知内容区域真实的宽高比，才能让像素矩阵里的像素点保持正确的尺寸和布局，并让文字大小合适。

典型场景每次收到请求，先读出这两个参数，再传给 pixelTextRoot、barChart 等函数。要把内容画在其中某一块局部区域，不用改 canvas，用 frame 指定。

frame / Box

单位小组件宽高的比例 0–1

含义组件或图层的位置和尺寸。left、width 相对小组件内容区域的宽度，top、height 相对高度。

典型场景想让折线图只占小组件的下半部分：frame: Box.canvas(canvas).sub(0, 0.4, 1, 0.6)；或者把标题文字放在左上角。

点阵坐标

单位像素点

含义Matrix 中的 (x, y)，即（列, 行），原点在左上角，从 0 开始。

典型场景画一幅 16 × 16 的像素画：art.circle(11, 3, 2, color) 在第 11 列、第 3 行画一个圆。

直接手写 frame 的数字很快就难以维护。Box 是一个布局盒：从整个小组件内容区域开始，逐步收边、切分，最后交给图层或组件。下图按“图层”一节示例的布局，一步步演示：

• Box 的方法都返回新的 Box，不会修改原来的对象。
• sub、inset、rows、columns 中的比例都相对当前这个 Box；insetPt、gapPt 以 pt 为单位，需要 Box 带有画布信息（Box.canvas(canvas) 创建的都带）。
• frame 的宽高限制在 0.02–1.5；小于 0.02 时，SDK 会以中心为基准扩大到 0.02，所以高度为 0 的 Box 正好是一条水平线的位置。

SDK 的结果有四种形式：根点阵 RootMatrix、尚未放置的点阵 MatrixPart、包含图层声明和图层对象的 Composite，以及响应片段（Partial<Response>，即符合响应结构的任意对象，例如手写的 { data }）。除 MatrixPart 需要先用 place 放置外，其余三种都可以直接用 merge 组合，最后交给 toResponse。

日常使用只需记住两条：MatrixPart 要先 place 才能合并；最终结果一定要经过 toResponse。完整的组合示例见组合多个组件。

要自己绘制点阵，使用 Matrix 类：new Matrix(columns, rows, options?) 创建一块 columns 列 × rows 行的点阵，此时所有像素点都还没有绘制；接着调用绘图方法作画，最后导出（见下文“导出为根点阵或图层”）。绘图方法超出范围的部分会被直接裁掉，不会报错。

第三个参数 options 可以省略。省略时，未绘制的像素点不显示，用一个颜色作画时画出的是白色、不透明的方形像素点。需要调整外观时，options 有三个字段：

• default：没有绘制的像素点显示什么，默认不显示（'empty'），也可以给一个颜色或样式，做出未点亮的底色。
• base：只写颜色作画时，其余样式（透明度、圆角、旋转、发光）取自这里。
• layout：像素点之间的间距、边缘留白和像素点的宽高比，字段含义见 API 文档的点阵布局。

这三项通常不需要自己写，直接套用主题即可，见下文“像素点样式与主题”。

import { Matrix, themes, themeOptions, toResponse } from '@glance-widgets/api-sdk';

const hills = [[0, 15], [0, 11], [5, 6], [9, 10], [12, 7], [15, 10], [15, 15]];

const art = new Matrix(16, 16, themeOptions(themes.lcd));
art
  .circle(11, 3, 2, '#FFD23F')
  .polygon(hills, '#3E6B33')
  .polygon(hills, '#9BFF6B', { fill: false })
  .text('HI', 1, 1, { font: '3x5', style: '#FFFFFF' });

const response = toResponse(art.toRoot());

绘图方法

set(x, y, style) · get(x, y)

设置或读取单个像素点；坐标越界时抛错。

fill(style) · clear()

填满或清空整个点阵。

line(x0, y0, x1, y1, style)

直线。

rect · roundRect · ellipse · circle

矩形、圆角矩形、椭圆和圆；传 { fill: false } 只画轮廓。

arc(cx, cy, r, start, end, style)

圆弧，0° 指向 12 点钟，顺时针；{ thickness } 设置宽度。

polygon(points, style)

多边形，points 为 [x, y] 列表。

floodFill(x, y, style)

从一个像素点开始向相连的同色区域填充。

text(content, x, y, options)

用像素字体写字，options 可指定 font 和 style。

blit(other, x, y)

把另一个 Matrix 贴到指定位置，空像素点不覆盖。

flipX · flipY · rotate90 · crop · clone

翻转、旋转、裁剪和复制，返回新的 Matrix，原来的不变。

绘图方法会修改当前的 Matrix 并返回它自己，所以可以像示例那样连续调用。

像素点样式与主题

style 可以只是一个颜色，也可以是部分像素样式 { color, opacity, cornerRadius, rotation, halo }，没写的字段取自主题中点亮像素点的样式。'empty' 表示显式留空，null 表示恢复成未绘制的默认像素点。

主题决定未点亮像素点的样子、点亮像素点的形状和像素点间距。内置五种主题，同一幅画的效果如下：

• led圆点、发光、间距宽

• lcd方格、间距窄；组件默认

• dot小圆点、间距很宽

• diamond旋转 45° 的菱形

• soft圆角方块、柔和发光

主题就是一套预先配好的 options：未点亮像素点的样子（default）、点亮时的基础样式（base）和布局（layout）。themeOptions(themes.led) 会得到 led 主题的 options，直接传给 Matrix。如果想在某个主题的基础上改一部分，把要改的内容作为第二个参数传入，例如 themeOptions(themes.led, { layout: { gapMode: 'near' } })：default 会整个替换，base 和 layout 只覆盖写了的字段，其余沿用主题。

组件的 theme 选项直接写主题名即可，例如 theme: 'led'。另外每个主题还带有一组配色 palette：on（点亮）、off（未点亮）、dim（较暗的点亮色）、accent（对比强调色）。绘图时取用 themes.led.palette.accent 这类颜色，画出的内容就能与主题协调。

像素字体

内置 3x5 和 5x7 两种字体，包含可打印的 ASCII 字符和常用符号（° ± × ÷ € ← → ↑ ↓ 等）。需要知道文字占多大时，用 measureText(text, font) 得到准确的宽高，不要估算。也可以提供自己的点阵字形，让 SDK 按指定字形绘制中文或其他文字。

字符宽度与等宽显示

默认情况下，像素文字会根据字符本身的宽窄分配空间。例如，5x7 字体中的 1 比 2 窄，占用的列数也更少，所以文字排列更紧凑。不过，在时钟、计数器等内容不断更新的场景中，即使字符数量没变，整段文字的宽度也可能随着数字变化，造成布局来回跳动。

需要保持宽度稳定时，可以设置 monospace: true，让每个字符占用相同的宽度。使用 5x7 字体时，每个字符都占 5 列，较窄的字符在其中居中显示；3x5 字体则每个字符占 3 列。空格和标点也按相同宽度占位。这个选项默认是 false，也就是按字符本身的宽度排列。

Matrix.text、textMatrix、measureText、pixelTextRoot 和 pixelTextPanel 都支持 monospace。如果先测量尺寸再绘制，两次调用要使用相同的设置。开启等宽后，字符数量不变的单行文字可以保持宽度稳定；增加字符或换行，整段文字的大小仍会变化。

加载自定义像素字体

自定义字体使用 SDK 的 FontDefinition 数据格式：为每个字符提供一组点阵行，# 表示点亮，. 表示留空。字体定义可以保存在 JSON 文件中，由你的服务读取并解析，再交给 SDK。下面是一份只包含“中”“文”两个字的 7 行字体，可以保存为 my-font.json：

{
  "name": "my-cn7",
  "height": 7,
  "spacing": 1,
  "glyphs": {
    "中": [
      "...#...",
      ".#####.",
      ".#.#.#.",
      ".#####.",
      "...#...",
      "...#...",
      "...#..."
    ],
    "文": [
      "...#...",
      "#######",
      ".#...#.",
      "..#.#..",
      "...#...",
      "..#.#..",
      "##...##"
    ]
  }
}

读取字体定义后，用 defineFont 注册，再把返回的字体对象或已注册的名称传给 font。下面的示例随本页编程语言选择切换；文件读取和 JSON 解析使用各语言的标准库，SDK 负责校验字形、排版和绘制点阵。

import { readFileSync } from 'node:fs';
import { defineFont, pixelTextRoot, toResponse } from '@glance-widgets/api-sdk';

// 服务初始化时读取并注册一次
const definition = JSON.parse(readFileSync('./my-font.json', 'utf8'));
const font = defineFont(definition);

// 每次请求传入当次画布尺寸；也可用 font: 'my-cn7' 引用已注册字体
const canvas = { width: 338, height: 158 };
const response = toResponse(pixelTextRoot('中文', { canvas, font }));

name · height · glyphs

必填：字体名称、基线上方的行数、字符到字形的映射。每个键是一个 Unicode 字符；同一字形中的各行必须等宽。

spacing · lineSpacing

spacing 是字体定义中的默认字距，默认 1；lineSpacing 是绘制时的排版选项，默认 1。单位均为像素点。

descent

字体基线下方的额外行数，默认 0。单个字形最多包含 height + descent 行；少于 height 行时，底部补空行。

advance

可选的统一字符前进量；省略时，也可以将单个字形写成 { rows, advance }，单独控制其前进量。

aliases

复用已有字形，例如 { "a": "A" }。

fallback

缺失字符时使用的替代字符，必须在字体中有字形。省略时，绘制字体未包含的字符会报错。

Matrix.text、textMatrix、pixelTextRoot、pixelTextPanel 和 measureText 都支持自定义字体；像素模式的 stat 使用 pixelFont 和 pixelUnitFont 分别设置数值与单位字体。字体也可以作为内联定义直接传入，无需注册；需要按名称复用时再注册。同名字体不能重复注册，通常在服务初始化时注册一次。最终返回给 App 的是像素数据，不需要在 App 中安装这份字体。

导出为根点阵或图层

toRoot()

得到RootMatrix

适合整个小组件就是一块点阵，例如时钟、像素画。

toPart()

得到MatrixPart

适合点阵只占一部分区域，或者要和文字、图表叠在一起。

图片转点阵

pixelate(image, { columns, rows }) 把图片缩成指定大小的点阵：每个像素点取原图中对应那一块的平均颜色，可以用 palette 限定颜色，用 alphaThreshold 跳过透明区域。它接收已经解码的 RGBA 像素 { width, height, data }，读取和解码图片文件需要你自己完成。

除了点阵，小组件还可以放文字、图标、直线、形状、图片和曲线图层。SDK 为每种图层提供一个构造函数，它会补全 App 默认值不直观的字段（例如文字的对齐方式、图标需要的字体信息），并统一颜色写法。

import { Box, icon, text, horizontalLine, merge, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const [head, body] = Box.canvas(canvas).inset(0.08).rows([1, 2], { gapPt: 10 });

const response = toResponse(merge(
    icon({
      id: 'icon', frame: head.sub(0, 0, 0.1, 1),
      name: 'ph_lightning', style: { color: '#FFD23F' },
    }),
    text({
      id: 'title', frame: head.sub(0.13, 0, 0.87, 1), text: 'Solar output',
      style: { fontSizeRatio: 0.12, verticalAlignment: 'center', textOpacity: 0.72 },
    }),
    horizontalLine({
      id: 'rule', at: body.top, from: body.left, to: body.right,
      style: { strokeWidth: 1, opacity: 0.2 },
    }),
    text({
      id: 'value', frame: body, text: '12.6 kWh',
      style: { fontSizeRatio: 0.26, fontWeight: '600', verticalAlignment: 'center' },
    }),
));

构造函数生成的都是远程图层，即由 API 声明的 remote: 图层，id 缺少前缀时会自动补上。它们统一接受 { id, frame, dataPath?, zIndex?, rotation?, transform?, style? } 和各自的内容参数，frame 必填，可以直接传 Box。每个函数返回一个 Composite，即 { layers, data }：layers 中是图层声明，data 中是 dataPath 指向的图层对象，包含布局、内容和样式；省略 dataPath 时按 id 自动生成。单个图层用 toResponse(text(...)) 输出；多个图层或组件用 merge(text(...), icon(...), chart) 组合。

text

内容text

说明字号 fontSizeRatio 相对小组件内容区域的短边，不是图层高度。

icon

内容name、glyph 或 url

说明name 取自内置图标目录（约 5,300 个），名称不存在时直接报错。

horizontalLine · verticalLine

内容at、from、to

说明用小组件宽高的比例给出线的位置和两端，比手写 frame 直观。

line

内容direction

说明在 frame 内画一条水平或竖直的线。

shape

内容—

说明圆角矩形。App 中形状最小 24 pt，细条请用直线或点阵。

image

内容url

说明主屏幕上远程图片可能加载失败，小图优先用 Base64。

curve

内容data

说明原生曲线。画折线图时通常直接用图表组件。

各图层 style 中可用的字段与 API 文档的图层参考 相同。

组件把常见的数据展示做成一次函数调用：传入数据和小组件内容区域的尺寸，得到排好版的片段。

柱状图、进度条和进度环各有两种画法：barChart、progressBar、ringProgress 由原生图层绘制，圆头、半透明轨道，贴近 iOS 原生质感；pixelBarChart、pixelProgressBar、pixelRingProgress 由点阵像素点拼成，是 LED 点阵风格。battery 和 signal 只有原生图层的画法。

下面是所有组件在小尺寸上的样子，点击可以跳到对应的说明。

• barChart柱状图

• pixelBarChart点阵柱状图

• lineChart折线图

• areaChart面积图

• sparkline迷你趋势线

• labeledCalendarHeatmap日历热力图

• heatmap矩阵热力图

• progressBar进度条

• labeledPixelProgressBar点阵进度条

• ringProgress进度环

• labeledPixelRingProgress点阵进度环

• battery电池电量

• signal信号强度

• labeledStatusStrip状态条

• stat指标卡片

• pixelTextPanel像素文字

组件的命名有规律可循：

• pixelProgressBar、pixelRingProgress、statusStrip、heatmap、calendarHeatmap 返回 MatrixPart，需要用 place 放置。
• labeledXxx() 返回 Composite：点阵加文字标签，可以直接合并。因为要按 pt 排布文字，canvas 必填。
• 图表（barChart、lineChart 等）、progressBar、ringProgress、battery、signal 和 stat 也返回 Composite。

通用选项

canvas

小组件内容区域的尺寸（pt）。labeled*、图表、progressBar、ringProgress、battery、signal 和 stat 必填。

frame

组件绘制的区域，默认整个小组件内容区域；可以直接传 Box。

theme

点阵内容使用的主题名或主题对象，默认 lcd。barChart、progressBar、ringProgress、battery、signal 不含点阵，不接受此选项。

colors

组件配色。常规进度条和环使用 fill / track / label；点阵组件按各自选项使用 on / off 等键。

id

图层 id 的前缀。同一个响应里放两个同类组件时，必须给不同的 id。

path

组件中点阵图层的对象在 data 中的位置，默认 data.<id>；其余图层对象的位置按各自的 id 生成。barChart、progressBar、ringProgress、battery、signal 不含点阵，不接受此选项。

zIndex

组件所在的层级。

barChart · 柱状图

圆头柱状图；支持负值，默认值域包含 0。零值不绘制柱子，极小非零值至少显示一个圆头。barWidth 是 pt（0.5–8），默认每个槽宽的一半、最多 8。showBaseline 默认 true，fontSizeRatio 默认 0.06；categories 每个值对应一个标签，colors 为 positive / negative / baseline / label。

import { barChart, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const chart = barChart([3, 5, -2, 8, 6, 4, 7], {
  canvas,
  categories: ['M', 'T', 'W', 'T', 'F', 'S', 'S'],
});
const response = toResponse(chart);

pixelBarChart · 点阵柱状图

数值可以为负，零基线自动计算；categories 为每根柱子加一个标签。

import { pixelBarChart, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const chart = pixelBarChart([3, 5, -2, 8, 6, 4, 7], {
  canvas,
  categories: ['M', 'T', 'W', 'T', 'F', 'S', 'S'],
});
const response = toResponse(chart);

rows

默认值10

说明纵向像素点数，决定数值的精细程度。

barWidth · barSpacing

默认值1 · 1

说明每根柱子占几列，柱子之间空几列。

min · max

默认值包含 0 的数据范围

说明固定纵轴范围。

categories

默认值—

说明柱子下方的标签。

showValueLabels · showAxes

默认值true

说明左侧的最大值 / 0 / 最小值标签，坐标轴和零基线。

colors

默认值蓝 / 红

说明positive、negative、track（未点亮的像素点）、axis、label。

lineChart · areaChart · sparkline · 折线图

折线图使用 App 原生的曲线图层绘制，线条平滑。每个系列可以是一组数值，也可以是 { values, color } 或 { points: [[x, y], …] }；多个系列共用同一个坐标范围。

import { lineChart, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const visits = [12, 18, 15, 24, 21, 30, 27];
const orders = { values: [8, 10, 14, 12, 16, 15, 19], color: '#FF9F0A' };

const chart = lineChart([visits, orders], {
  canvas,
  xLabels: ['Mon', 'Wed', 'Fri', 'Sun'],
  markers: { last: true, labels: true },
});
const response = toResponse(chart);

markers

默认值—

说明{ last, min, max, labels, radius }：在最后一点、最低点、最高点画圆点，labels 显示数值。

xLabels

默认值—

说明底部标签，从左到右均匀分布。

min · max

默认值数据范围

说明固定纵轴范围。

interpolation

默认值monotone

说明曲线插值方式。

strokeWidth

默认值2

说明线宽，单位 pt。

grid

默认值false

说明背景像素网格，与绘图区对齐。

showAxes · showValueLabels

默认值true

说明坐标轴和左侧数值标签。

areaChart 是带半透明填充的折线图（fillOpacity 默认 0.3）。sparkline 是只有一条线、没有坐标轴的迷你趋势线，默认在最后一个点画圆点；不开 grid 时不需要 canvas。

labeledCalendarHeatmap · heatmap · 热力图

日历热力图每天一个像素点、每周一列，适合展示每日活跃度。start 是第一个值对应的日期，后面的值依次顺延一天。

import { Box, labeledCalendarHeatmap, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const days = [];
for (let i = 0; i < 140; i++) days.push((i * 37 + (i % 7) * 11) % 9);

const calendar = labeledCalendarHeatmap(days, {
  canvas,
  frame: Box.canvas(canvas).inset(0.06),
  start: '2026-06-01',
});
const response = toResponse(calendar);

start

默认值—

说明第一个值的日期，格式 YYYY-MM-DD，必填。

levels

默认值5

说明色阶数量。

scale

默认值主题的暗色 → 亮色

说明颜色停止点，至少两个。

min · max

默认值数据范围

说明对应第一个和最后一个颜色的数值。

startWeekday

默认值0

说明每周从哪一天开始，0 为周日。

orientation

默认值weekColumns

说明改为 weekRows 则每周一行。

missing

默认值'empty'

说明null 值的画法：留空，或指定一种颜色。

heatmap(rows) 接收二维数组，画普通的矩阵热力图，默认是连续色阶。两者都返回 MatrixPart。

progressBar · 进度条

圆头进度条，返回 Composite，直接合并即可。thickness 单位 pt，范围 0.5–8，默认 6；min / max 默认 0 / 100。orientation 默认 horizontal，vertical 从下往上填充，reverse 反转方向。label 默认关闭，true 显示百分比，字符串显示自定义文字；labelPosition 默认 end，fontSizeRatio 默认 0.07。colors 为 fill / track / label。

import { Box, progressBar, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const frame = Box.canvas(canvas).sub(0.08, 0.4, 0.84, 0.2);

const bar = progressBar(65, {
  canvas, frame, label: true, fontSizeRatio: 0.12,
});
const response = toResponse(bar);

pixelProgressBar · labeledPixelProgressBar · 点阵进度条

由点阵像素点组成的分段进度条。labeledPixelProgressBar 带百分比标签；pixelProgressBar 只有点阵，需要 place。

import { Box, labeledPixelProgressBar, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const frame = Box.canvas(canvas).sub(0.08, 0.4, 0.84, 0.2);

const bar = labeledPixelProgressBar(65, {
  canvas, frame, segments: 16, segmentSize: 2, fontSizeRatio: 0.12,
});
const response = toResponse(bar);

min · max

默认值0 · 100

说明数值范围。

segments

默认值10

说明分成几段。

segmentSize · segmentGap

默认值3 · 1

说明每段几个像素点，段与段之间空几个。

thickness

默认值让像素点成为正方形

说明横向的像素点数（进度条的粗细）。

orientation · reverse

默认值horizontal · false

说明方向；vertical 从下往上填充。

label · labelPosition

默认值百分比 · end

说明标签文字和位置（start 或 end）。

ringProgress · 进度环

图层进度环，居中放在 frame 内最大的正方形中。thickness 单位 pt，范围 0.5–12，默认直径的 10% 并限制在 3–12。startAngle 默认 0（12 点钟），counterClockwise 默认 false。label 默认 true，可设文字或 false；fontSizeRatio 默认按内孔适配、最多 0.28。colors 为 fill / track / label。圆弧由多个 curve 图层拼成，图层数随进度和起点变化。

import { Box, ringProgress, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 158, height: 158 };
const ring = ringProgress(72, {
  canvas,
  frame: Box.canvas(canvas).inset(0.1),
  thickness: 8,
});
const response = toResponse(ring);

pixelRingProgress · labeledPixelRingProgress · 点阵进度环

中间显示数值的进度环。像素点始终是正方形，环不会被拉伸。

import { Box, labeledPixelRingProgress, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 158, height: 158 };
const ring = labeledPixelRingProgress(72, {
  canvas,
  frame: Box.canvas(canvas).inset(0.1),
  theme: 'led',
});
const response = toResponse(ring);

diameter

默认值33

说明直径的像素点数，必须是奇数。

thickness

默认值4

说明环的宽度（像素点数）。

startAngle · counterClockwise

默认值0 · false

说明起点角度（0 为 12 点钟）和方向。

label

默认值百分比

说明中间的文字。

battery · signal · 电池与信号

battery 和 signal 返回 Composite，需要 canvas，可直接 merge，都靠 frame 左侧、垂直居中放置，min / max 默认 0 / 100。

battery 是半透明胶囊机身加端子和圆头电量条：height 5–12 pt（默认 12），width 默认高度的 2.3 倍；电量 ≤20% 红、≤40% 橙、其余绿；label 默认关闭，true 在右侧显示百分比，也可传文字；颜色键 fill / good / warn / bad / track / label。

signal 是仿状态栏的细长圆头信号条，高度从 35% 递增到 100%：bars 默认 4，height 默认取 frame 高度（最大 14 pt），barWidth 0.5–8 pt，默认高度的 26%；颜色键 fill / track。

import { Box, battery, signal, merge, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 160, height: 160 };
const [top, bottom] = Box.canvas(canvas).inset(0.125).rows(2, { gapPt: 8 });

const response = toResponse(merge(
  battery(80, { canvas, frame: top, label: true }),
  signal(60, { canvas, frame: bottom, bars: 4 }),
));

labeledStatusStrip · statusStrip · 状态条

一排状态像素点，适合展示服务可用性、任务记录。每个值是一个状态名，null 表示没有数据。

import { labeledStatusStrip, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 338, height: 158 };
const hours = [
  'ok', 'ok', 'ok', 'ok', 'warn', 'ok', 'ok', 'ok', 'ok', 'ok', 'down', 'down',
  'ok', 'ok', 'ok', null, 'ok', 'ok', 'ok', 'warn', 'ok', 'ok', 'ok', 'ok',
];
const strip = labeledStatusStrip(hours, {
  canvas,
  startLabel: '24h ago',
  endLabel: 'now',
  legend: true,
});
const response = toResponse(strip);

colors

默认值ok 绿 · warn 橙 · down 红

说明状态名到颜色的映射，可以加入自己的状态。

startLabel · endLabel

默认值—

说明状态条左下、右下的文字。

legend

默认值false

说明true 显示数据中出现过的状态的图例，也可以传状态名列表。

names

默认值—

说明图例中各状态显示的名称。

stat · 指标卡片

标签、大号数值、单位和变化量。变化量为正时显示绿色的上箭头；对于延迟、错误数这类越低越好的指标，设置 invertDelta: true。

import { Box, stat, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 158, height: 158 };
const card = stat(42.5, {
  canvas,
  frame: Box.canvas(canvas).inset(0.1),
  label: 'Power',
  unit: 'kW',
  delta: 3.2,
  deltaSuffix: '%',
});
const response = toResponse(card);

label · unit

默认值—

说明标签和单位。

delta

默认值—

说明变化量，决定箭头方向和颜色。

deltaSuffix · deltaDecimals

默认值— · 1

说明变化量的后缀（如 %）和小数位数；deltaText 可以直接替换整段文字。

invertDelta

默认值false

说明下降算作好事。

valueStyle

默认值text

说明改为 pixel 用像素字体显示数值。

align

默认值left

说明left 或 center。

decimals

默认值整数 0 位，否则 1 位

说明数值的小数位数。

pixelTextRoot · pixelTextPanel · 像素文字

用像素字体显示文字，自动选择像素点大小，让文字尽量铺满 frame 指定的区域。pixelTextRoot 生成根点阵，第一个响应里的时钟就是它；pixelTextPanel 生成 MatrixPart，可以放在任意区域，place 时使用同一个 frame。

font

默认值5x7

说明像素字体名称或字体定义。

theme · color

默认值lcd · 主题亮色

说明外观和文字颜色。

align · valign

默认值center

说明文字块在区域中的位置。

lineAlign

默认值同 align

说明多行文字之间的对齐。

monospace

默认值false

说明开启后所有字符（含空格和标点）使用字体的统一格宽，窄字形居中；5x7 固定为 5 格，适合时钟、计数器，等长文本更新时布局宽度不变。关闭时跟随字形宽度。

letterSpacing · lineSpacing

默认值字体默认

说明字距和行距（像素点数）。

unlit

默认值true

说明是否画出未点亮的像素点。

maxCellSize

默认值—

说明像素点的最大边长（pt），避免短文字变成巨大的方块。

实际的小组件通常由几部分组成。先用 Box 划分区域，再给每个组件传入各自的 frame 和 id，最后用 merge 合在一起：

import { Box, stat, sparkline, battery, merge, toResponse } from '@glance-widgets/api-sdk';

const canvas = { width: 320, height: 160 };
const [left, right] = Box.canvas(canvas).inset(0.125).columns([2, 3], { gapPt: 16 });
const [trendArea, batteryArea] = right.rows([3, 1], { gapPt: 8 });

const cpu = stat(42, { canvas, frame: left, id: 'cpu', label: 'CPU', unit: '%', delta: -3, invertDelta: true });
const trend = sparkline([30, 42, 38, 51, 47, 44, 42], { canvas, frame: trendArea, id: 'trend' });
const charge = battery(35, { canvas, frame: batteryArea });

const response = toResponse(merge(
  cpu,
  trend,
  charge,
  { data: { updatedAt: '12:30' } },
));

merge 的规则

data

对象逐层合并；同一路径上都是普通值或数组时，后面的覆盖前面的。

layers

按顺序拼接；id 相同时，后面的图层在原位置替换前面的。

根点阵

作为一个整体，后出现的整个替换前面的。

MatrixPart

不能直接合并，会报错，需要先 place。

发生覆盖通常意味着 id 或路径写重了。调试时可以用 merge(a, b, { onConflict: 'error' })，遇到覆盖直接报错并给出路径。merge 不会修改传入的对象。

前面的图层构造函数和组件生成的都是远程图层：图层由响应声明，位置、内容和样式全部来自 API。SDK 也可以为作者在 App 编辑器中添加的图层生成动态内容和样式。

编辑器图层的位置、内容和样式保存在小组件配置中。作者为它设置数据路径后，API 只需在这个路径返回一个图层对象：对象中给出的字段覆盖编辑器中的设置，没有给出的字段沿用编辑器的配置，详细规则见 API 文档的合并规则。编辑器图层不写入响应的 layers。

所以，为编辑器图层提供数据，就是用 SDK 构造出图层对象中需要更新的那部分，放到该图层的数据路径下：

• 内容：点阵用 Matrix.toPart()，结果就是 { content }，可以直接放入；图标用 iconGlyph(name) 得到 { icon, iconCodePoint, iconFont }，直接作为 content；曲线等其他类型可以调用对应的图层构造函数，从返回的 data 中只取出图层对象的 content；文字直接写 { content: { text: '128' } }。
• 样式：只写需要随数据变化的字段，例如 { style: { color: '#FF453A' } }。点阵图层没有 style 字段。
• 布局：需要由 API 改变位置或尺寸时，才返回 frame、zIndex、rotation、transform；frame 必须包含 width 和 height。

下面的示例中，作者在编辑器中添加了一个点阵图层，数据路径设为 data.badge。服务端用 Matrix 绘制图案，再把 toPart() 的结果放到 data.badge：

import { Matrix, themes, themeOptions, toResponse } from '@glance-widgets/api-sdk';

const heart = new Matrix(9, 9, themeOptions(themes.led)).circle(4, 4, 4, '#FF453A');

// The editor's matrix layer reads data.badge: send only the data
const response = toResponse({ data: { badge: heart.toPart() } });

响应没有返回布局字段，点阵保留编辑器中的位置和尺寸。toPart() 的结果总是带有 default 和 layout，它们会覆盖编辑器中设置的默认点样式和间距；想沿用编辑器的这两项设置，就把这两个字段删掉。

SDK 不处理 HTTP。在你的服务中，每次请求大致是这几步：

• 从查询参数读取 gw_canvas_width_pt 和 gw_canvas_height_pt（保留两位小数的字符串），确认它们是有效的正数；
• 如果在 App 中为 API 设置了密钥，用 verifySignature 校验请求签名；
• 读取业务数据，用 SDK 生成响应；
• 以 UTF-8 JSON 返回，带上 Content-Type: application/json。

import { ringProgress, toResponse } from '@glance-widgets/api-sdk';

// params: the request's query parameters
export function buildWidget(params) {
  const width = Number(params.gw_canvas_width_pt);
  const height = Number(params.gw_canvas_height_pt);
  if (!(width > 0 && height > 0)) throw new Error('missing canvas size');

  const ring = ringProgress(72, { canvas: { width, height } });
  return JSON.stringify(toResponse(ring));
}

// Send the string with Content-Type: application/json; charset=utf-8

校验请求签名

在 App 中为 API 设置密钥后，每个请求都会带上 X-GlanceWidgets-Timestamp 和 X-GlanceWidgets-Signature 两个请求头，密钥本身不会被发送。把这两个值和你保存的密钥交给 verifySignature：它会重新计算签名、以恒定时间比较，并拒绝与服务器时间相差超过 5 分钟（默认）的请求。返回 false 时，直接以 401 结束请求。

import { verifySignature, TIMESTAMP_HEADER, SIGNATURE_HEADER } from '@glance-widgets/api-sdk';

// headers: request headers with lower-cased names; secret: the key set in the App
const ok = verifySignature({
  timestamp: headers[TIMESTAMP_HEADER.toLowerCase()],
  signature: headers[SIGNATURE_HEADER.toLowerCase()],
}, secret);
if (!ok) {
  // respond 401 and stop
}

请求头常量 TIMESTAMP_HEADER 和 SIGNATURE_HEADER 可直接使用；签名算法与测试向量见 API 文档，各语言的完整签名见类参考。

toResponse 检查根点阵、远程图层声明及其引用的对象，包括字段类型、路径、尺寸与响应限制。不合法时抛出 GlanceValidationError，其中 path 指出出错的字段：

import { toResponse, GlanceValidationError } from '@glance-widgets/api-sdk';

try {
  toResponse({ pixels: [[{ color: '#12345' }]] });
} catch (error) {
  if (error instanceof GlanceValidationError) {
    console.error(error.path); // $.pixels[0][0].color
  }
}

手写的完整响应也可以调用 validate(response)。

toResponse 和 validate 只校验 layers 中声明的远程图层。编辑器图层不出现在 layers 中，SDK 不知道它的类型，所以不会校验为它准备的图层对象；需要时用 validateLayerNode(node, type) 单独校验，例如 validateLayerNode(response.data.badge, 'matrix')。它与编辑器图层的规则一致，允许省略布局、内容和样式字段。无效的图层对象会让 App 中的编辑器图层回退到保存的状态、远程图层不绘制，提前校验可以在上线前发现这类问题。各语言的函数签名和错误类型见完整类参考。

常见问题

颜色变成透明，或校验报错

8 位颜色是 #AARRGGBB，透明度在前，不是 CSS 的 #RRGGBBAA。

预览正常，主屏幕上错位或变形

两处的小组件内容区域尺寸不同。每次请求都按 gw_canvas_* 重新生成，不要缓存某个尺寸的结果。

远程图层不显示，或编辑器图层没有应用 API 数据

检查 dataPath 指向的是否是图层对象，远程图层的对象是否有包含 width、height 的 frame，content、style 中的字段是否属于该图层类型。编辑器中还要确认「当前预览」选的是「API 数据」。

点阵像素点被拉伸或错位

MatrixPart 组件构建时和 place 时用了不同的 frame。

右对齐的数字跑到了左上角

文字超出图层宽度时，App 会强制左上对齐。自己写 text 图层时要留足宽度；组件已按字宽留出余量。

字号比预期大或小

fontSizeRatio 相对小组件内容区域的短边，范围 0.02–0.28。

形状比设定的大

App 中 shape 最小 24 pt。细线用直线图层，细条用点阵。

根点阵上点亮的像素点有一圈白边

这是根点阵固有的效果，改用 toPart() 和 place 做成点阵图层。

数值异常或 App 崩溃

不要在 data 中放绝对值不小于 9.2 × 10¹⁸ 的整数。

组件参考

barChart

返回Composite

需要 canvas必填

图层数非零柱 + 可选基线 + 类别标签

progressBar

返回Composite

需要 canvas必填

图层数1–2 + 可选标签

ringProgress

返回Composite

需要 canvas必填

图层数多个圆弧 + 可选标签

battery

返回Composite

需要 canvas必填

图层数2–3 + 可选标签

signal

返回Composite

需要 canvas必填

图层数每根信号柱 1

pixelBarChart

返回Composite

需要 canvas必填

图层数1 + 坐标轴 2 + 数值标签 ≤ 3 + 每个类别 1

lineChart · areaChart

返回Composite

需要 canvas有坐标轴、标签或网格时必填

图层数每个系列 1 + 网格 ≤ 1 + 坐标轴 ≤ 2 + 数值标签 ≤ 2 + 每个 x 标签 1

sparkline

返回Composite

需要 canvas仅开启 grid 时

图层数1（网格 +1）

stat

返回Composite

需要 canvas必填

图层数≤ 5

labeledPixelProgressBar · labeledPixelRingProgress

返回Composite

需要 canvas必填

图层数2

labeledStatusStrip

返回Composite

需要 canvas必填

图层数1 + 首尾标签 ≤ 2 + 图例每个状态 2

labeledCalendarHeatmap

返回Composite

需要 canvas必填

图层数1 + 星期标签 ≤ 3 + 月份标签

pixelProgressBar · pixelRingProgress · statusStrip · heatmap · calendarHeatmap

返回MatrixPart

需要 canvas可选（给出时铺满 frame）

图层数放置后 1

pixelTextPanel

返回MatrixPart

需要 canvas必填

图层数放置后 1

pixelTextRoot

返回RootMatrix

需要 canvas必填

图层数0

下面按类和功能列出 SDK 的公开接口，包含构造方法、实例方法、函数、参数结构和常量。语言选择与前面的代码示例同步；可按名称或用途搜索，展开条目查看参数、返回值和相关类型。

Matrix.constructor(columns: number, rows: number, options?: MatrixOptions): Matrix

Matrix.contains(x: number, y: number): boolean

Matrix.get(x: number, y: number): PixelStyle | Empty

Matrix.isSet(x: number, y: number): boolean

Matrix.set(x: number, y: number, style: PixelInput): this

Matrix.fill(style: PixelInput): this

Matrix.clear(): this

Matrix.blit(other: Matrix, x: number, y: number): this

Matrix.line(x0: number, y0: number, x1: number, y1: number, style: PixelInput): this

Matrix.rect(x: number, y: number, width: number, height: number, style: PixelInput, options?: FillOptions): this

Matrix.roundRect(x: number, y: number, width: number, height: number, radius: number, style: PixelInput, options?: FillOptions): this

Matrix.ellipse(x: number, y: number, width: number, height: number, style: PixelInput, options?: FillOptions): this

Matrix.circle(cx: number, cy: number, radius: number, style: PixelInput, options?: FillOptions): this

Matrix.arc(cx: number, cy: number, radius: number, startAngle: number, endAngle: number, style: PixelInput, options?: ArcOptions): this

Matrix.polygon(points: ReadonlyArray<readonly [number, number]>, style: PixelInput, options?: FillOptions): this

Matrix.floodFill(x: number, y: number, style: PixelInput, options?: FloodFillOptions): this

Matrix.text(content: string, x: number, y: number, options?: DrawTextOptions): this

Matrix.clone(): Matrix

Matrix.flipX(): Matrix

Matrix.flipY(): Matrix

Matrix.rotate90(turns?: number): Matrix

Matrix.crop(x: number, y: number, width: number, height: number): Matrix

Matrix.toRoot(): RootMatrix

Matrix.toPart(): MatrixPart

pixelate(image: RgbaImage, options: PixelateOptions): Matrix