English Version

元数据信息

元数据块是 WidgetScript 中用来描述组件的部分。它通常包含小组件的名称,图标,描述和其他一些相关参数。

WidgetScript 的元信息块使用多行注释以 // ==WidgetScript== 开头,并以 // ==/WidgetScript== 作为结束标志。

您应该将元数据块放在整个文件的开始部分。

元数据块的每一行均以 // @type value 开头,支持的类型和值的格式如下:

名称类型描述
nameString小组件的名称
descriptionString小组件的功能描述
iconString (ImageString)小组件的图标
iconBgColorString (Hex Color)小组件图标的背景颜色
versionString版本号
paramParam小组件的参数
screenshotString (URL)小组件的屏幕截图

name 是必填的,其他所有都是选填的。


图标 @icon

图标 @icon 标签的类型为 ImageString,使用的语法为 <type>:<value>

ImageString 类型:

  • Base64 编码的图片

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

注意:目前仅支持 PNG 和 JPEG格式的图片。不要使用 SVG 或其他格式的图片。
  • 系统符号 ( SF Symbols)

system:note.text

  • 文字(包括 Emoji)

text:👌


参数 @param

@param 标签提供了小组件参数的名称、类型和描述。

@param 标签需要您指定要记录的参数的名称,您也可以使用,用大括号括起来的参数类型和参数说明。

语法规则

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

其中paramName 是必填的,并且在小组件中必须为唯一值。

类型 type

<type> 是必填的,格式为 {type=defaultValue},例如: {string="default"}{bool=true}{number=0.1}

所有的 <type> 都必须设置一个“默认值”即 defaultValue

选项 options

numberenum 类型都需要 <options> 属性。

类型为 number 的对象需要具有 minmax, 和 step 属性。 例如: {"min": 6, "max": 42, "step": 0.1}

类型为 enum 的对象需要具有一系列可选的值。 例如: ["Safari", "Chrome", "Firefox"]

显示名称和显示描述 displayName and displayDescription

displayName 是必填的,但 displayDescription 是选填的。 在使用时displayName和displayDescription中间需要使用 - 进行连接。例如:应用名称 - 应用的相关描述

支持的类型

  • string - 渲染为单行文本输入框。以 string 类型传递给脚本。

    // @param fullName {string="Black Smith"} 名称 - 组件的全名
  • color - 渲染为拾色器。传递给脚本时类型为 string, 例如: #FFFFFF00#FFFFFF

    // @param stickerBgColor {color="#5263FF"} 背景色 - 便签的背景色
  • enum - 渲染为单选项。传递给脚本时类型为 string

    // @param openWithBrowser {enum="Safari"}["Chrome","Firefox","Safari"] 在浏览器打开 - 选择一个浏览器打开链接
  • number - 渲染为滑块。传递给脚本时类型为 number

    // @param fontSize {number=12}{"min": 6, "max": 42, "step": 0.1} 字体大小 - 显示字体大小
  • text - 渲染为多行输入。传递给脚本时类型为 string

    // @param contentText {text=""} 内容 - 要展示的内容
  • bool - 渲染为切换按钮。传递给脚本时类型为 boolean

    // @param showTitle {bool=false} 展示标题 - 展示便签的标题。
  • date - 渲染为日期选择器。 格式为 yyyy-MM-dd 传递给脚本时类型为 string,例如 2020-01-01

    // @param reminderDate {date="2022-01-01"} 提醒日期 - 显示提醒的日期

元数据块示例

// ==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==

脚本

WidgetScript 使用 WebKit 的 JavaScriptCore 作为其运行时,它支持所有 ECMAScript 6 (ES6) 语言规范中的新功能。

脚本块位于每个 WidgetScript 中的元信息块下方。

实际上,小组件本身就是一个函数。

在这个函数中,您可以接收用户配置的参数值,并执行各种操作,例如从 API 读取数据,对数据进行处理,进行一些计算等),最终调用 render 函数渲染小组件的布局。

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

parameterscontext 都是 JavaScript 对象。


Parameters

Parameters 是小组件的配置参数,该参数将结合元信息块中定义的参数和用户配置生成。

参数示例

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

Context

Context 是小组件的运行环境参数,提供了展示时的上下文,其值和类型的格式如下:

名称类型描述
family"small" | "medium" | "large"小组件使用的模板。
isPreviewBoolean小组件在预览或在小组件库中显示。
displaySize{ w: number; h: number }小组件显示的尺寸大小。(以像素为单位)
colorScheme"light" "dark"小组件使用的配色方案。
{
family: "small" | "medium" | "large";
isPreview: boolean;
displaySize: {
w: number;
h: number;
}
colorScheme: "light" | "dark";
}

组件

WidgetScript 提供了内置的组件和功能,供您构建自定义的小组件界面。

通用组件属性

所有组件均可通过以下通用属性进行修饰。

属性

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

shadow

shadow 可以创建阴影效果,格式为 x y blur color,例如: 1 1 2 #00000033

alignment

HStack

HStack 可以创建将其子元素水平排列的视图。

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

Props

名称类型
verticalAlignment"top" | "center" | "bottom" | "firstTextBaseline" | "lastTextBaseline"
spacingNumber

VStack

VStack 可以创建将其子元素垂直排列的视图。

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

Props

名称类型
horizontalAlignment"leading" | "center" | "trailing"
spacingNumber

ZStack

ZStack 可以创建叠加的视图栈。

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


Spacer

一个在排版方向上(对于 VStack 而言是竖向,对于 HStack 而言是横向)伸展(类似 flex-grow)并填充空白的组件。

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


Color

Color(valueObject)

valueObject

名称必填类型
hexYesString (Hex Color)

您可以将 ColorZStack 配合使用来创建背景颜色,例如:

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

LinearGradient

线性渐变会沿由其定义的点和颜色应用颜色渐变。

LinearGradient(valueObject)

valueObject

名称类型
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 (请参阅下面的详细信息)

direction

direction 为选填项,默认值为 to bottom

gradient

gradient 为必填项。

gradient 支持两种格式:

  1. colorHexString 中可以使用 , 链接两个参数。 例如: #A82323,#000000

将根据设置的颜色按均等距离实现渐变效果。

  1. 也可以使用 , 附加 colorHexString stopPosition 参数。例如: #A82323 0.1,#000000 0.3

将按照指定的位置和颜色创建渐变。


Text

显示一行或多行只读文本。

Text(valueObject, props)

valueObject

名称必填类型
textYesString

Props

名称类型
foregroundColorString (Hex Color)
fontWeight"bold" | "normal" | "semibold" | "thin"
fontDesign"default" | "monospaced" | "rounded" | "serif"
font"body" | "largeTitle" | "title" | "headline" | "subheadline" | "callout" | "footnote" | "caption"
fontSizeNumber
fontStyleString (请参阅下面的详细信息)

fontStyle

fontStyle 可以指定字体的风格为 styleA styleA,例如 italic lowercaseSmallCaps。 可用样式有: bolditalicsmallCapslowercaseSmallCapsuppercaseSmallCapsmonospacedDigit

参数示例

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

Image

显示图片,支持系统图片及网络图片。

Image(valueObject, props)

valueObject

名称必填类型
systemIconNameNoString
imageUrlNoString

Props

名称必填类型
heightNoNumber
widthNoNumber
scaleModeNo"fit" | "fill"
clipContentNoBoolean

参数示例

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

API

KV 存储

WidgetScript 在运行时会为每个小组件提供独立隔离的 KV 存储。

localStorage 类似, WidgetScript 的 键值对会以文本的形式进行存储.

WidgetScript 为每个小组件提供 4MB 大小的 KV 存储空间。

您可以使用全局变量 kvStore 访问 KV 存储。

写入值

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

读取值

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

删除键值对

kvStore.delete("key")

列出全部的键值对

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

清除存储

删除当前小组件的所有键值对 。

kvStore.wipe()

获取存储用量

返回当前 KV 的存储使用情况(以字节为单位)。

kvStore.usage()

获取存储用量限制

返回当前 KV 存储的大小限制(以字节为单位)。

kvStore.limitation()