SDK

ウィジェットの表示内容は、API が返す JSON で決まります。形式は API リファレンスを参照してください。プロトコルはシンプルですが、すべて手書きするのは大変です。文字をピクセルに分解して行列数を計算し、ピクセルアートの各マスに色を付け、グラフではマトリクスと曲線・軸・ラベルの位置を合わせる必要があります。アプリの描画上の制約にも対応しなければなりません。いずれも、表示したいデータそのものとは関係のない作業です。

SDK はこうした処理を関数として提供します。表示したい内容とスタイルを決め、対応する関数を呼び出すと、プロトコルに準拠したマトリクスやレイヤーのデータが得られます。ピクセルを手作業で組み立てる必要はありません。

SDK は、次の 2 段階の機能を提供します。

• 基本描画：Matrix は自由に描画できるピクセルの格子です。直線、矩形、円、多角形、ピクセル文字の描画や、画像からの変換に対応します。文字、アイコン、直線、図形、画像、曲線のレイヤーを作る関数もあり、プロトコルの基本的な表示要素に対応しています。
• コンポーネント：折れ線グラフ、棒グラフ、プログレスバー、円形プログレス、ステータス表示、ヒートマップ、指標カードなど、よく使う表示を関数として用意しています。マトリクスや曲線などのレイヤーを組み合わせ、1 回の呼び出しでレイアウト済みのデータを返します。売上、バッテリー残量、タスクの進捗など、表示するデータは自由です。用途を限定せず、基本要素から組み立てる手間を減らせます。

SDK で表示内容を生成し、API のレスポンス本文に入れれば準備完了です。

9 言語の 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

まず、各 API の配置を確認しましょう。SDK には、Matrix・Box・PixelFont などのオブジェクトとそのメソッド、文字やグラフを作る関数、合成・出力・色を扱うユーティリティがあります。グラフやプログレスバーなどのコンポーネントも関数で作成します。言語ごとのエントリーポイントと命名規則は以下のとおりです。プログラミング言語を切り替えると、この説明、コード例、API リファレンスがまとめて切り替わります。

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 のように元の名前を保ちます。関数名・メソッド名・ネイティブ型のメンバー名は各言語の慣習に従います。上の例では、インポート、インスタンス生成、インスタンスメソッド、クラスやパッケージの関数呼び出し、レスポンス生成の基本を示しています。全パラメーターは API リファレンスを参照してください。

次のプログラムは、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));

処理は次の 3 つです。

• サイズを指定する。canvas はウィジェットのコンテンツ領域のサイズで、単位は pt です。アプリは毎回のリクエストに gw_canvas_width_pt と gw_canvas_height_pt を含めます。機種、アプリ内プレビュー、ホーム画面でサイズが異なる場合があるため、固定値ではなく毎回のリクエスト値を使ってください。例の 338 × 158 は、一般的な iPhone の中サイズです。
• 内容を生成する。pixelTextRoot は 5×7 のピクセルフォントで文字を配置し、コンテンツ領域全体を埋める行列数を計算して、文字を上下左右の中央に置きます。maxCellSize でピクセルの大きさを制限すると、文字の周囲に消灯したピクセルの余白ができます。theme: 'led' は発光する丸いピクセルを選びます。
• レスポンスを完成させる。toResponse がプロトコルの必須フィールドを補完し、検証します。返されたオブジェクトを JSON にシリアライズすると、レスポンス本文になります。

実際のサービスへの組み込み方はサービスへの組み込みを参照してください。

SDK では用途に応じて 3 種類の座標を使います。グラフなどのコンポーネントや文字などのレイヤーの位置は、ウィジェットのコンテンツ領域に対する比率で表す 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.canvas(canvas) で作った Box にはその情報が含まれます。
• frame の幅・高さは 0.02〜1.5 の範囲です。0.02 未満なら中心を保って 0.02 に拡張されるため、高さ 0 の Box で水平線の位置を指定できます。

SDK の結果は 4 つの形式です。ルートマトリクス RootMatrix、未配置のマトリクス MatrixPart、レイヤー宣言とレイヤーオブジェクトをまとめた Composite、そしてレスポンス断片（Partial<Response>。レスポンスの構造に従う任意のオブジェクトで、手書きの { data } など）です。MatrixPart は先に place で配置する必要がありますが、それ以外の 3 つは merge で直接組み合わせ、最後に toResponse に渡せます。

MatrixPart は place してから合成すること、最後に必ず toResponse を通すこと。この 2 点を覚えておけば十分です。全体の例は複数コンポーネントの合成を参照してください。

new Matrix(columns, rows, options?) で columns 列 × rows 行の未描画のマトリクスを作成します。描画メソッドで描き、後述の「ルートマトリクスまたはレイヤーとして出力」に従って出力します。描画が範囲を超えた部分は切り取られ、エラーにはなりません。

第 3 引数の options は省略できます。既定では未描画のピクセルは非表示で、基本スタイルは不透明な白い正方形です。外観を変えるときは、次の 3 フィールドを使います。

• 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)

1 ピクセルを設定・取得します。範囲外の座標はエラーになります。

fill(style) · clear()

マトリクス全体を塗りつぶす、または消去します。

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

直線を描きます。

rect · roundRect · ellipse · circle

矩形・角丸矩形・楕円・円を描きます。{ fill: false } で輪郭のみにできます。

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

12 時方向を 0° とし、時計回りに円弧を描きます。{ thickness } で太さを指定します。

polygon(points, style)

[x, y] のリスト points から多角形を描きます。

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 は未描画の既定状態に戻す指定です。

テーマは消灯時の表示、点灯時の形、ピクセル間隔を決めます。組み込みの 5 テーマで同じ絵を描くと、次のようになります。

• led発光する丸いピクセル、広めの間隔

• lcd正方形、狭い間隔。コンポーネントの既定テーマ

• dot小さな丸、大きな間隔

• diamond45° 回転したひし形

• soft柔らかく発光する角丸の正方形

テーマは、消灯時の表示（default）、点灯時の基本スタイル（base）、配置（layout）をまとめた options のプリセットです。themeOptions(themes.led) の結果を Matrix に渡すと led テーマを使えます。変更したい項目は第 2 引数に渡します。例：themeOptions(themes.led, { layout: { gapMode: 'near' } })。default は全体を置き換え、base と layout は指定したフィールドだけを上書きします。

コンポーネントでは theme: 'led' のように名前を直接指定できます。各テーマには palette もあり、on（点灯色）、off（消灯色）、dim（暗めの点灯色）、accent（強調色）を使えます。themes.led.palette.accent などを使うと、テーマに合う配色で描画できます。

ピクセルフォント

組み込みの 3x5・5x7 フォントには、印字可能な ASCII 文字と一般的な記号（° ± × ÷ € ← → ↑ ↓ など）が含まれます。正確なサイズは measureText(text, font) で取得してください。独自の字形を用意すれば、日本語や中国語なども描画できます。

文字幅と等幅表示

既定では字形ごとの幅で文字を配置します。たとえば 5x7 の 1 は 2 より細く、少ない列数で描くため、文字を詰めて表示できます。ただし時計やカウンターでは、文字数が同じでも数字が変わると全体の幅が変わり、表示位置が揺れることがあります。

幅を一定にするには monospace: true を指定します。5x7 では各文字が 5 列、3x5 では 3 列を使い、細い字形は中央に配置されます。空白や句読点も同じ幅です。既定値は false で、字形ごとの幅を使います。

Matrix.text・textMatrix・measureText・pixelTextRoot・pixelTextPanel が monospace に対応しています。計測してから描画するときは、両方で同じ設定を使ってください。等幅なら文字数が同じ 1 行の文字列は幅が安定しますが、文字の追加や改行では全体のサイズが変わります。

カスタムピクセルフォントの読み込み

カスタムフォントには SDK の FontDefinition 形式を使います。各文字をピクセルの行で定義し、# を点灯、. を空白とします。定義は JSON に保存でき、サービスで読み込んで解析してから SDK に渡します。次は「中」「文」の 2 文字だけを含む 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 の 1 文字で、同じ字形の各行は同じ幅である必要があります。

spacing · lineSpacing

spacing はフォント定義の既定の字間、lineSpacing は描画時の行間設定です。どちらも既定値は 1、単位はピクセルです。

descent

ベースラインより下の追加行数で、既定値は 0 です。1 字形は最大 height + descent 行まで。height 行に満たない場合は末尾に空行を補います。

advance

任意の共通文字送り幅です。省略した場合は、字形ごとに { rows, advance } を指定して個別に調整できます。

aliases

{ "a": "A" } のように既存の字形を再利用します。

fallback

未定義の文字に使う代替文字です。フォント内に字形が必要です。省略時に未定義の文字を描くとエラーになります。

Matrix.text・textMatrix・pixelTextRoot・pixelTextPanel・measureText はカスタムフォントに対応します。ピクセル表示の stat では pixelFont・pixelUnitFont で数値と単位のフォントを指定します。定義を直接渡す場合は登録不要です。名前で再利用するときだけ登録してください。同じ名前では重複登録できないため、通常はサービス起動時に一度だけ登録します。アプリにはピクセルデータが届くので、フォントのインストールは不要です。

ルートマトリクスまたはレイヤーとして出力

toRoot()

戻り値RootMatrix

用途時計やピクセルアートなど、ウィジェット全体を 1 つのマトリクスで表示する場合。

toPart()

戻り値MatrixPart

用途マトリクスを一部の領域に配置したり、文字やグラフと重ねたりする場合。

画像からマトリクスへの変換

pixelate(image, { columns, rows }) は、元画像の各領域の平均色から指定サイズのマトリクスを作ります。palette で色を制限し、alphaThreshold で透明部分を除外できます。入力はデコード済みの RGBA ピクセル { width, height, data } です。画像ファイルの読み込みとデコードはサービス側で行ってください。

ウィジェットにはマトリクスのほか、文字・アイコン・直線・図形・画像・曲線のレイヤーも配置できます。SDK の各レイヤー作成関数は、文字の配置やアイコンのフォント情報など、アプリの既定値が分かりにくいフィールドを補完し、色の表記も統一します。

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 に remote: 接頭辞がなければ自動で補われます。引数は { 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

内容—

説明角丸矩形です。アプリでは最小 24 pt なので、細い要素には直線やマトリクスを使ってください。

image

内容url

説明ホーム画面ではリモート画像の読み込みに失敗する場合があります。小さな画像には Base64 を推奨します。

curve

内容data

説明ネイティブの曲線レイヤーです。折れ線グラフには通常、グラフコンポーネントを使います。

style で使えるフィールドは、API リファレンスのレイヤー一覧と同じです。

コンポーネントなら、データとコンテンツ領域のサイズを渡すだけで、よく使う表示をレイアウト付きで生成できます。

棒グラフ・プログレスバー・円形プログレスには 2 種類の描き方があります。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 の接頭辞です。1 つのレスポンスに同種のコンポーネントを 2 つ置く場合は、異なる ID を指定してください。

path

コンポーネント内のマトリクスレイヤーのオブジェクトを置く data 内の位置で、既定は data.<id> です。ほかのレイヤーオブジェクトの位置は、それぞれの id から決まります。barChart・progressBar・ringProgress・battery・signal にはマトリクスがないため、このオプションは受け付けません。

zIndex

コンポーネントの重なり順です。

barChart · 棒グラフ

丸い端の棒グラフ。負の値に対応し、既定の範囲は 0 を含みます。ゼロの棒は描画せず、小さな非ゼロ値は丸い端の大きさを保ちます。barWidth は 0.5〜8 pt、既定はスロット幅の半分（最大 8）。showBaseline は true、fontSizeRatio は 0.06。categories は各値につき 1 つ指定します。色は 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

説明棒 1 本の列数と、棒の間の空き列数です。

min · max

既定値0 を含むデータ範囲

説明縦軸の範囲を固定します。

categories

既定値—

説明棒の下のラベルです。

showValueLabels · showAxes

既定値true

説明左側の最大値・0・最小値のラベル、座標軸、ゼロの基準線です。

colors

既定値青 / 赤

説明positive・negative・track（消灯ピクセル）・axis・label。

lineChart · areaChart · sparkline · 折れ線グラフ

折れ線グラフはアプリのネイティブ曲線レイヤーで滑らかに描画します。各系列には数値配列、{ 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 · ヒートマップ

カレンダーヒートマップは 1 日を 1 ピクセル、1 週間を 1 列で表し、日々の活動量などに適しています。start が最初の値の日付で、以降は 1 日ずつ進みます。

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

既定値テーマの暗色 → 明色

説明カラーストップ。2 つ以上必要です。

min · max

既定値データ範囲

説明最初と最後の色に対応する値です。

startWeekday

既定値0

説明週の開始曜日。0 は日曜日です。

orientation

既定値weekColumns

説明weekRows で 1 週間を 1 行にします。

missing

既定値'empty'

説明null の表示方法。空白にするか色を指定します。

heatmap(rows) は 2 次元配列から通常のマトリクスヒートマップを描き、既定では連続的な色階調を使います。どちらのヒートマップ関数も MatrixPart を返します。

progressBar · プログレスバー

丸い端のプログレスバー。Composite を返し、直接合成できます。thickness は 0.5〜8 pt、既定 6。min / max は 0 / 100。orientation は horizontal、vertical は下から上へ、reverse で反転します。label は既定で非表示、true で割合、文字列で任意の文字を表示。labelPosition は end、fontSizeRatio は 0.07。色は 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 は 0.5〜12 pt、既定は直径の 10% を 3〜12 に制限。startAngle は 0（12 時方向）、counterClockwise は false。label は true が既定で、文字列や false も指定可能です。fontSizeRatio は穴に合わせて最大 0.28。色は 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 · ステータス表示

サービスの稼働状況やタスク履歴を表す、1 列のステータス表示です。各値は状態名で、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 は 1 文字 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 は、作成者がアプリのエディターで追加したレイヤーに対する動的な内容と外観も生成できます。

エディターのレイヤーの配置・内容・外観は、ウィジェットの設定に保存されています。作成者がデータパスを設定すると、API はそのパスにレイヤーオブジェクトを 1 つ返すだけで済みます。オブジェクトに含まれるフィールドはエディターの設定を上書きし、含まれないフィールドはエディターの設定がそのまま使われます。詳しくは 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 が含まれ、エディターで設定したドットの既定スタイルと間隔を上書きします。この 2 項目にエディターの設定を使いたい場合は、2 つのフィールドを削除してください。

SDK は HTTP を処理しません。サービスでは毎回のリクエストで次の処理を行います。

• クエリパラメーターの gw_canvas_width_pt と gw_canvas_height_pt（小数点以下 2 桁の文字列）を読み取り、有効な正数か確認する。
• アプリで API のシークレットを設定した場合は、verifySignature でリクエスト署名を検証する。
• 必要なデータを取得し、SDK でレスポンスを生成する。
• Content-Type: application/json を付け、UTF-8 の 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

リクエスト署名を検証する

アプリで API にシークレットを設定すると、各リクエストに X-GlanceWidgets-Timestamp と X-GlanceWidgets-Signature の 2 つのヘッダーが付きます。シークレット自体は送信されません。2 つの値と保存しておいたシークレットを 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')。エディターのレイヤーと同じ規則で検証し、配置・内容・外観のフィールドの省略を認めます。不正なレイヤーオブジェクトがあると、アプリではエディターのレイヤーは保存済みの状態に戻り、リモートレイヤーは描画されません。事前に検証すれば、公開前にこうした問題を見つけられます。各言語のシグネチャとエラー型は完全なクラスリファレンスを参照してください。

よくある問題

色が透明になる・検証エラーになる

8 桁の色はアルファ値が先頭の #AARRGGBB です。CSS の #RRGGBBAA とは異なります。

プレビューは正常だがホーム画面でずれる・変形する

コンテンツ領域のサイズが異なります。特定サイズの出力を使い回さず、毎回の gw_canvas_* で再生成してください。

リモートレイヤーが表示されない、またはエディターのレイヤーに API データが適用されない

dataPath がレイヤーオブジェクトを指しているか、リモートレイヤーのオブジェクトに width と height を含む frame があるか、content と style のフィールドがそのレイヤーの種類に属しているかを確認してください。エディターのレイヤーでは、「現在のプレビュー」が「API データ」になっていることも確認してください。

マトリクスのピクセルが伸びる・ずれる

MatrixPart の生成時と place で異なる frame を使っています。

右揃えの数字が左上に表示される

文字がレイヤー幅を超えると、アプリは左上揃えに切り替えます。自作の text レイヤーでは十分な幅を確保してください。コンポーネントは字幅を考慮済みです。

文字が想定より大きい・小さい

fontSizeRatio はコンテンツ領域の短辺に対する比率で、範囲は 0.02〜0.28 です。

図形が指定より大きい

アプリの shape は最小 24 pt です。細い線には直線レイヤー、細いバーにはマトリクスを使ってください。

ルートマトリクスの点灯ピクセルに白い縁が付く

ルートマトリクス固有の表示です。toPart() と place でマトリクスレイヤーにしてください。

数値が異常になる・アプリがクラッシュする

絶対値が 9.2 × 10¹⁸ 以上の整数を data に入れないでください。

コンポーネントリファレンス

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

以下に、コンストラクター、インスタンスメソッド、関数、パラメーター型、定数をクラス・機能別にまとめています。言語選択は上のコード例と連動します。名前や用途で検索し、項目を開くとパラメーター・戻り値・関連型を確認できます。

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