logo
目录
快速开始
API 指南

motiff

以下为全局对象 motiff 提供的方法和属性。

General

apiVersion: ‘1.0.0’ [readonly]

插件所运行于的 Motiff API 版本号，可在 manifest.json 的 "api" 字段中指定。

fileKey: string | undefined [readonly]

插件所运行于的文档键（唯一标识）。

skipInvisibleInstanceChildren: boolean

启用后，所有节点属性和方法都会跳过实例内的不可见节点（及其后代）。 这将大大加快文档遍历等操作的速度。

currentPage: PageNode

用户当前查看的页面。 可将此值设置为某个页面节点，以切换页面。

root: DocumentNode [readonly]

整个 Motiff 文档的根节点。 此节点用于访问其它页面，其每个子节点都是一个 PageNode 。

ui: UIAPI [readonly]

motiff.showUI(...) 所创建的 UI 可通过此属性所包含的方法进行修改及通信。

showUI(html: string, options?: ShowUIOptions): void

用于渲染与用户交互的 UI，或仅为获得调用浏览器接口的能力。此方法会创建一个对话框， 其中的 <iframe> 标签的内容即为参数 html 。

参数

html：

待插入 iframe 的 HTML 代码，此处通常传入全局变量 __html__。

options：

包含以下可选参数的对象：

  • visible: 窗口对用户是否可见， 默认为 true 。后续可使用 motiff.ui.show() 和 motiff.ui.hide() 以令窗口对用户可见或隐藏。
  • width: UI 窗口的宽度。默认为 300，最小可为 70。后续可使用 motiff.ui.resize(width, height) 修改宽度。
  • height: UI 窗口的高度。 默认为 200，最小值为 0。后续可使用 motiff.ui.resize(width, height) 修改高度。
  • title: UI 窗口的标题，默认为插件名。
  • position: UI 窗口的位置，默认为浏览器窗口中心， 或是上次关闭插件时 UI 窗口的位置。如需指定窗口位置，则应传入画布空间的 X/Y 坐标 (例如某一图层的 <PluginNode>.x 和 <PluginNode>.y)。

viewport: ViewportAPI [readonly]

当前页的用户可视区域可通过此属性所包含的方法进行读写。

clientStorage: ClientStorageAPI [readonly]

此属性包含在用户本地计算机上存储持久数据的方法。

currentUser: User | null [readonly]

此属性包含有关当前用户的信息。

closePlugin(message?: string): void

关闭插件。当插件运行完毕后，应当总是调用此方法。调用此 API 之后，插件的 UI 窗口会被关闭，所有 setTimeout 或 setInterval 定时器都将被清除。

参数

message：

可选，插件关闭后，显示以 message 为内容的 toast

on

on(type: ArgFreeEventType, callback: () => void): void

on(type: 'run', callback: (event: RunEvent) => void): void

on(type: 'drop', callback: (event: DropEvent) => boolean): void

on(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void

on(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): void

on(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void

注册编辑器事件的回调。当前支持的事件如下：

  • 当前页的选区( currentPage.selection )发生变化。
  • 用户切换至其它页。
  • 文档的内容发生变更。
  • 外部对象被放置于 Motiff 的画布。
  • 插件开始运行。
  • 插件关闭。

once

once(type: ArgFreeEventType, callback: () => void): void

once(type: 'run', callback: (event: RunEvent) => void): void

once(type: 'drop', callback: (event: DropEvent) => boolean): void

once(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void

once(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): void To be implemented

once(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void To be implemented

与 on 类似，用于注册编辑器的事件回调，区别在于，通过 once 方法注册的事件回调只会执行一次。

off

off(type: ArgFreeEventType, callback: () => void): void

off(type: 'run', callback: (event: RunEvent) => void): void

off(type: 'drop', callback: (event: DropEvent) => boolean): void

off(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void

off(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): void To be implemented

off(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void To be implemented

移除通过 motiff.on 或 motiff.once 注册的事件回调

notify(message: string, options?: NotificationOptions): NotificationHandler

在窗口底部展示一个通知

参数

message：

通知消息的内容。

options:

可选，可配置消息通知的时长、样式等，参数如下：

interface NotificationOptions {
  timeout?: number;
  error?: boolean;
  onDequeue?: (reason: NotifyDequeueReason) => void
  button?: {
    text: string
    action: () => boolean | void
  }
}

  • timeout：保持通知展示的时长（毫秒），默认为 3 秒。

  • error：若为 true，则将通知显示为错误消息，并使用不同的颜色。

  • onDequeue: 通知退出队列时执行的回调。通知达到给定的展示时长，用户主动单击通知的按钮时， 通知退出队列。此回调应接收类型为 NotifyDequeueReason 的参数

    *type* NotifyDequeueReason = 'timeout' | 'dismiss' | 'action_button_click'

  • button: 通知右侧的按钮

    • text: 按钮的标题。
    • action: 用户单击按钮时调用的回调，单击将同时忽略此通知。

commitUndo(): void

提交操作至历史记录，且不触发 undo。

默认情况下，插件操作不会提交到撤消历史记录中。调用 motiff.commitUndo()，以便可分阶段撤销插件操作。

例如，运行以下插件代码后，第一次触发的撤消将同时撤消矩形和容器：

motiff.createRectangle();
motiff.createFrame();
motiff.closePlugin();

而若在两次图层创建之间调用 motiff.commitUndo() ，第一次触发的撤销仅会撤销容器的创建。

motiff.createRectangle();
motiff.commitUndo();
motiff.createFrame();
motiff.closePlugin();

triggerUndo(): void

触发一次撤销，将会恢复至上次 commitUndo() 的状态。

saveVersionHistoryAsync(title: string, description?: string): Promise<VersionHistoryResult>

保存文件的新版本并将其添加到文件的版本历史记录中，返回新版本 id。参数 description 为对版本的描述。

Nodes

此章节包含获取图层及创建图层的内容。

getNodeById(id: string): BaseNode | null

根据给定的 id 查找对应的节点。如果没有找到对应的节点，则返回 null。

每个节点都有一个 id 属性，该属性在文档内唯一。若 id 无效，或者无法找到节点（例如已删除），则返回 null。

createRectangle(): RectangleNode

新建一个矩形。其行为类似于使用快捷键 R ，并在画布内单击。

createLine(): LineNode

新建一个线段图层。

createEllipse(): EllipseNode

新建一个椭圆图层。其行为类似于使用快捷键 O，并在画布内单击。

createPolygon(): PolygonNode

新建一个多边形图层。

createStar(): StarNode

新建一个星型图层。

createVector(): VectorNode

新建一个空向量网络图层。

createText(): TextNode

新建一个空文本图层。

createFrame(): FrameNode

新建一个容器图层。其行为类似于使用快捷键 F，并在画布区单击。

createComponent(): ComponentNode

新建一个空组件图层。

createComponentFromNode(node: SceneNode): ComponentNode

从现有图层创建组件，保留其所有属性和子节点。此行为类似于使用工具栏中的**“创建组件”** 按钮**。**

createBooleanOperation(): BooleanOperationNode

已弃用：请使用 motiff.union , motiff.subtract ,motiff.intersect, motiff.exclude 代替。

createPage(): PageNode

新建一个的页面。

createSlice(): SliceNode

新建一个切片图层。

createNodeFromSvg(svg: string): FrameNode

根据传入的 SVG 字符串，新建一个图层。等价于编辑器中的 SVG 导入功能。

group(nodes: ReadonlyArray, parent: BaseNode & ChildrenMixin, index?: number): GroupNode

新建一个组，包含给定的nodes 。 无 createGroup 方法，请使用此方法。

union(nodes: ReadonlyArray, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

对 nodes 使用 UNION 操作，新建一个 BooleanOperationNode 图层。 union 的参数与 motiff.group 中的相同。

subtract(nodes: ReadonlyArray, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

对 nodes 使用 SUBTRACT 操作，新建一个 BooleanOperationNode 图层。 union 的参数与 motiff.subtract 中的相同。

intersect(nodes: ReadonlyArray, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

对 nodes 使用 INTERSECT 操作，新建一个 BooleanOperationNode 图层。 union 的参数与 motiff.intersect 中的相同。

exclude(nodes: ReadonlyArray, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

对 nodes 使用 EXCLUDE 操作，新建一个 BooleanOperationNode 图层。 union 的参数与 motiff.exclude 中的相同。

flatten(nodes: ReadonlyArray, parent?: BaseNode & ChildrenMixin, index?: number): VectorNode

将 nodes 展平为一个新的向量网络。

ungroup(node: SceneNode & ChildrenMixin): Array

解组给定组图层，将其所有子图层移动至给定组图层的父节点并删除该组图层。返回值为该组图层的子图层数组。

Styles

以下 APIs 可用于在当前文档中创建新样式和检索现有样式。 新创建的样式是当前文档的本地样式，且不包含默认属性（TextStyle 除外）。

getStyleById(id: string): BaseStyle | null

根据给定的 id 查找对应的样式。若无法找到，则返回 null。

createPaintStyle(): PaintStyle

新建一个颜色样式。此类型的样式可能包含图片，且可用于背景、描边、填充等多个场景。

createTextStyle(): TextStyle

新建一个文本样式。所新建的文本样式具有 Motiff 默认文本属性 (font family Inter Regular, font size 12)。

createEffectStyle(): EffectStyle

创建新的效果样式。

createGridStyle(): GridStyle

创建新的网格样式。

以下 API 可访问本地样式，且所返回样式的顺序与用户界面中显示的顺序一致。 仅返回本地样式，不包含团队组件库中的样式。

getLocalPaintStylesAsync(): Promise<PaintStyle[]>

返回本地颜色样式。

getLocalPaintStyles(): PaintStyle[]

返回本地颜色样式。

getLocalTextStylesAsync(): Promise<TextStyle[]>

返回本地文本样式。

getLocalTextStyles(): TextStyle[]

返回本地文本样式。

getLocalEffectStylesAsync(): Promise<EffectStyle[]>

返回本地效果样式。

getLocalEffectStyles(): EffectStyle[]

返回本地效果样式。

getLocalGridStylesAsync(): Promise<GridStyle[]>

返回本地网格样式。

getLocalGridStyles(): GridStyle[]

返回本地网格样式。

Team Library

以下 API 可用于获取来自团队组件库的组件与样式。访问组件库内数据所需的 key 可通过 conponent.key 或 style.key 获取

importComponentByKeyAsync(key: string): Promise<ComponentNode>

从团队组件库中导入组件。 若请求失败或无已发布的组件与给定的 key 关联，promise 将被 reject。

importComponentSetByKeyAsync(key: string): Promise<ComponentSetNode>

从团队组件库中导入组件集。 若请求失败或无已发布的组件集与给定的 key 关联，promise 将被 reject。

Others

listAvailableFontsAsync(): Promise<Font[]>

返回当前可用字体的列表。

loadFontAsync(fontName: FontName): Promise<void>

根据给定的字体名称，加载对应字体，以确保使用此字体的图层被正确展示。

createImage(data: Uint8Array): Image

根据来自文件的原始字节数据，创建图像对象。 图像对象并不是图层，而是 Motiff 所存储图像的句柄。 容器的背景或形状的填充可能包含图片。

createImageAsync(src: string): Promise<Image>

通过给定的图片哈希值 hash，获取对应的 Image 对象，若不存在给定哈希值的图片，则返回 null。哈希值可从图层的填充属性获得。

mixed: unique symbol [readonly]

某些图层属性会返回此常量，用以表示属性包含多个值。例如 font size ，一个文本图层内的不同字符可能具有不同字体大小。对于这类属性，需考虑到其值可能为 motiff.mixed 。

base64Encode(data: Uint8Array): string

返回 Uint8Array 数据的 base64 编码字符串。

base64Decode(data: string): Uint8Array

解码 base64 字符串数据，并返回 Uint8Array。