中文版

Metainfo

The metadata block is a section of a WidgetScript that describes the script. It usually contains the script name, namespace, description, and parameters of the widget.

WidgetScript use multiline comments starts with // ==WidgetScript== and ends with // ==/WidgetScript== as metainfo block.

You should put the metadata block at top of the file.

Each line of the metainfo starts with // @type value, the supported type and value formatted as below:

NameTypeDescription
nameStringName of the widget
descriptionStringDescribes what the widget do.
iconString (ImageString)Icon of the widget.
iconBgColorString (Hex Color)Background color of the icon.
versionStringVersion.
paramParamParameters of the widget.
screenshotString (URL)Screenshot of the widget.

name is required and all others are optional.


Icon

The @icon tag takes ImageString with syntax: <type>:<value>.

ImageString Types:

  • Base64 Image

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAFVBMVEUAAAD///////////////////////9Iz20EAAAABnRSTlMAf4CPkO9T4O/6AAAAjElEQVR42mKAAkC79W0gQRAAIbC/d2fyD/nd05qTkEC5/I350MaSrZb58LoFjMcDYwuYQAICAgICAgICAgICAgICAm8ICAgICAgICAjkbAKXJTAPVBhoWKBhgYYFGhZoWKBhgYYFGhZoWKBhgYYFGhZoWKBhgYYFGhZoWKBhgYYFmgsa9FWUBrIOCPgHpW+s0hbIerAAAAAASUVORK5CYII=

Notice: Currently only supports PNG and JPEG. DO NOT use SVG or any others formats.
  • System Symbols (aka. SF Symbols)

system:note.text

  • Text (Emojis included)

text:👌


Param

The @param tag provides the name, type, and description of a widget parameter.

The @param tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, usually enclosed in curly brackets, and a description of the parameter.

Syntax

@param paramName <type><options> displayName - displayDescription

paramName is required and must be unique within the same widget.

type

<type> is required and the format should be {type=defaultValue}, e.g. {string="default"}, {bool=true}, {number=0.1}.

A defaultValue must be set for all types.

options

<options> is required for the type number and enum.

Type number requires a object with min, max, and step properties. e.g. {"min": 6, "max": 42, "step": 0.1}.

Type enum requires a array of possible values. e.g. ["Safari", "Chrome", "Firefox"].

displayName and displayDescription

displayName is required and displayDescription is optional.

Supported types:

  • string - Render as a signle line input. Pass to the script as string.

    // @param fullName {string="Black Smith"} Name - Your full name
  • color - Render as a color picker. Pass to the script as string, e.g. #FFFFFF00 or #FFFFFF.

    // @param stickerBgColor {color="#5263FF"} Background Color - The background color of this sticker
  • enum - Render as a option picker. Pass to the script as string.

    // @param openWithBrowser {enum="Safari"}["Chrome","Firefox","Safari"] Default Browser - Which browser to open links with
  • number - Render as a slider. Pass to the script as number.

    // @param fontSize {number=12}{"min": 6, "max": 42, "step": 0.1} Font Size - The display font size
  • text - Render as a multiline input. Pass to the script as string.

    // @param contentText {text=""} Content - Content to show
  • bool - Render as a toggle. Pass to the script as boolean.

    // @param showTitle {bool=false} Show Title - Show title of the note
  • date - Render as a date picker. Formatted in yyyy-MM-dd format and passed to the script as a string, e.g. 2020-01-01.

    // @param reminderDate {date="2022-01-01"} Reminder Date - The date to show the reminder

Sample Metainfo Block

// ==WidgetScript==
// @name Market Ticker
// @description Watch price up and down
// @icon system:note.text
// @iconBgColor #5263FF
// @param symbol {string="bitcoin"} Symbol - Symbol of the ticker
// @version 1.0
// ==/WidgetScript==

Script

WidgetScript uses WebKit's JavaScriptCore as its runtime which supports all of the new features in the ECMAScript 6 (ES6) language specification.

The script block is placed below the metainfo block in each WidgetScript. In fact, the script itself just declares a function with several parameters. In the function, you can perform various actions (fetching data from URLs, processing the data, doing calculations, etc.) and render the widget layout according to your needs.

(parameters, context) => {
...
}

Both parameters and context are JavaScript objects.


Parameters

The parameters parameter is automatically derived from parameters defined in the metainfo block.

Sample Parameters

{
showTitle: false,
contentText: "This is a sample.",
fontSize: 12.8,
openWithBrowser: "Chrome"
}

Context

The context parameter provides the environment variables used by the widget when being rendered.

NameTypeDescription
family"small" | "medium" | "large"Template that the widget uses.
isPreviewBooleanWhether or not the widget is being rendered in the preview or widget gallery.
displaySize{ w: number; h: number }Size of the widget is being rendered in pixels.
colorScheme"light""dark"
{
family: "small" | "medium" | "large";
isPreview: boolean;
displaySize: {
w: number;
h: number;
}
colorScheme: "light" | "dark";
}

Components

WidgetScript provides built-in Components as functions for you to build customized widget interface.

General Props

Props

NameType
paddingNumber [Number] [Number] [Number]
cornerRadiusNumber
widthNumber
heightNumber
opacityNumber
borderColorcolorHexString
borderWidthNumber
opacityNumber
clipContentBoolean
alignment"leading" | "trailing" | "center" | "top" | "bottom" ...
shadowString (see details below)

shadow

The shadow prop formatted as x y blur color, e.g. 1 1 2 #00000033.

alignment

HStack

A view that arranges its children in a horizontal line.

HStack([componentA(), componentB()], props)

Props

NameType
verticalAlignment"top" | "center" | "bottom" | "firstTextBaseline" | "lastTextBaseline"
spacingNumber

VStack

A view that arranges its children in a vertical line.

VStack([componentA(), componentB()], props)

Props

NameType
horizontalAlignment"leading" | "center" | "trailing"
spacingNumber

ZStack

A view that overlays its children, aligning them in both axes.

ZStack([componentA(), componentB()], props)


Spacer

A flexible space that expands along the major axis of its containing stack layout, or on both axes if not contained in a stack.

VStack([componentA(), Spacer(), componentB()], props)


Color

Color(valueObject)

valueObject

NameRequiredType
hexYesString (Hex Color)

You can use Color with ZStack to create a colored background.

ZStack([
Color({ hex: "#000" }),
ComponentA(),
ComponentB()
])

LinearGradient

The gradient applies the color function along an axis, as defined by its start and end points. The gradient maps the unit-space points into the bounding rectangle of each shape filled with the gradient.

LinearGradient(valueObject)

valueObject

NameType
direction"to bottom" | "to bottom right" | "to bottom left" | "to top" | "to top left" | "to top left" | "to left" | "to right" |"x1,y1 x2,y2"
gradientString (see details below)

direction

Optional. Default to to bottom.

gradient

Required.

gradient supports two formats:

A. colorHexString joined with ,. e.g. #A82323,#000000.

Creates a gradient synthesizes its location values to evenly space the colors along the gradient.

B. colorHexString stopPosition joined with ,. e.g. #A82323 0.1,#000000 0.3.

Creates a gradient from the given colors and positions.


Text(valueObject, props)

Text

A view that displays one or more lines of read-only text.

Text(valueObject, props)

valueObject

NameRequiredType
textYesString

Props

NameType
foregroundColorString (Hex Color)
fontWeight"bold" | "normal" | "semibold" | "thin"
fontDesign"default" | "monospaced" | "rounded" | "serif"
font"body" | "largeTitle" | "title" | "headline" | "subheadline" | "callout" | "footnote" | "caption"
fontSizeNumber
fontStyleString (see details below)

fontStyle

The fontStyle prop formatted as styleA styleA, e.g. italic lowercaseSmallCaps. Available styles: bold, italic, smallCaps, lowercaseSmallCaps, uppercaseSmallCaps, monospacedDigit

Example

Text(
{ text: "Hello" },
{
foregroundColor: "#000",
fontWeight: "bold",
font: "body",
}
);

Image

Displays a Image.

Image(valueObject, props)

valueObject

NameRequiredType
systemIconNameNoString
imageUrlNoString

Props

NameRequiredType
heightNoNumber
widthNoNumber
scaleModeNo"fit" | "fill"
clipContentNoBoolean

Example

Image(
{ systemIconName: "person.crop.circle" },
{
width: 60,
height: 60,
}
);

Chart

Chart(valueObject, props)

valueObject

NameRequiredType
chartStyleNoline | bar
chartDataYes[Number]

Props

NameRequiredType
foregroundColorNoString (Hex Color)
backgroundColorNoString (Hex Color)
paddingTopPercentageNoNumber
paddingBottomPercentageNoNumber
Chart({
chartStyle: "line",
chartData: [1,2,3,4,5,4,3,2,1],
foregroundColor: "#04B921",
backgroundColor: "#fff",
})

API

Key-value Storage

WidgetScript's runtime provides an isolated key-value storage for each widget.

Like localStorage, WidgetScript's key-value storage stores keys and values as strings.

WidgetScript's key-value storage provides 4MB storage per widget.

The key-value storage is accessible by the global variable kvStore.

Set a value

const ok = kvStore.set("key", "value")
if (!ok) {
// invalid key or value or storage exceeded the size limitation
} else {
// value has been set
}

Get a Value

const value = kvStore.get("key")
if (value === null || value === undefined) {
// value does not exist
} else {
// value exists
}

Delete a key-value pair

kvStore.delete("key")

List all key-value pairs

const kvPairs = kvStore.list() // returns an object
Object.entries(kvPairs).forEach(([key, value]) => {
// ...
})

Wipe storage

This deletes all key-value pairs created by current widget.

kvStore.wipe()

Get storage usage

This returns current key-value storage's usage in bytes.

kvStore.usage()

Get storage limitation

This returns current key-value storage's size limitation in bytes.

kvStore.limitation()