mg

下面给出的属性和方法可以通过全局对象 mg 来访问。

属性

apiVersion

  • Readonly: true
  • Type: string

运行插件的 MasterGo API 版本号,即定义在 manifest.json 中的 api 字段的值。

document

  • Readonly: true
  • Type: DocumentNode

MasterGo 文档的根节点,可以通过它来访问其他页面节点,或查找子代节点。例如,可以通过 document.currentPage 来访问当前页面节点。

documentId

  • Readonly: true
  • Type: number

当前文档的 ID。

ui

  • Readonly: true
  • Type:
interface UIAPI {
  show(): void;
  hide(): void;
  close(): void;

  postMessage(pluginMessage: any, options?: UIPostMessageOptions): void;
  onmessage:
    | ((pluginMessage: any, props: OnMessageProperties) => void)
    | undefined;
}

该属性是一个对象,包含了用来操作用户界面并与用户界面进行信息交流的接口。详情请查看 mg.ui

themeColor

  • Readonly: true
  • Type: 'dark' | 'light'

Master Go 系统的主题色, 值为 darklight

viewport

  • Readonly: true
  • Type:
interface ViewportAPI {
  center: Vector;
  zoom: number;
  readonly bounds: Rect;
}

该属性是一个对象,可以用来读取或设置当前页面的用户可视区(即画布的可见区域)。详情请查看 mg.viewport

clientStorage

  • Readonly: true
  • Type:
interface ClientStorageAPI {
  getAsync(key: string): Promise<unknown | undefined>
  setAsync(key: string, value: any): Promise<void>
}

该属性是一个对象,包含了用来在用户机器上完成数据本地持久化存储的方法。详情请查看 mg.clientStorage

方法

showUI

  • Type:
showUI(options?: ShowUIOptions): void
type ShowUIOptions = {
  width?: number
  height?: number
}

用来展示插件的用户界面,调用该方法会创建一个模态框。该模态框中会包含 <iframe> 标签,并加载由 manifest.json 中指定的 ui 字段所引用的 HTML 页面。

closePlugin

  • Type: closePlugin(): void

用来关闭由 showUI 创建的模态框,一旦关闭插件,所有的定时器或请求动画帧都将被清除或取消。

on

  • Type:
on(type: PluginEventType, callback: CallableFunction): void
type PluginEventType = 'selectionchange' | 'close'

on 方法允许注册特定事件的处理函数,当事件发生时会执行该回调函数:

  • 'selectionchange' 事件:当 currentPage.selection 变化时触发。回调参数 string[]
  • 'currentpagechange' 事件:当切换页面时触发,或插件修改 mg.document.currentPage 属性时触发。 回调参数 string
  • 'close' 事件:当调用 closePlugin 函数时,或用户通过插件 UI 的关闭按钮关闭插件时触发。回调参数 无
  • 'themechange'事件,当画布主题切换时触发。 回调参数 'dark' | 'light'

once

  • Type:
once(type: PluginEventType, callback: CallableFunction): void
type PluginEventType = 'selectionchange' | 'close'

once 方法允许注册特定事件的处理函数,当事件发生时会执行该回调函数。与 on 函数的区别在于,通过 once 函数注册的事件处理函数只会执行一次。

off

  • Type:
off(type?: PluginEventType, callback?: CallableFunction): void
type PluginEventType = 'selectionchange' | 'close'

移除事件处理函数。

  • 如果没有为 off 函数传递参数,将会移除所有事件的事件处理函数。
  • 如果只为 off 函数提供了事件名称,那么将移除该事件下的所有事件处理函数。
  • 如果既为 off 函数指定了事件名称,也为其指定了事件处理函数,则只有该指定的事件处理函数会被移除。

showGrid

  • Type: showGrid(show: boolean): void

画布的布局网格是否显示。

saveVersionHistoryAsync

  • Type: saveVersionHistoryAsync(desc: string): Promise<void>

添加历史版本。参数 desc 为对版本的描述。

notify

  • Type:
notify(message: string, options: NotifyOptions): void
interface NotifyOptions {
  position?: 'top' | 'bottom'
  type?: 'normal' | 'highlight' | 'error' | 'warning' | 'success'
}

在 UI 中展示一条通知消息。默认情况下,该通知会从页面的上方弹出。可以通过传递第二个参数并指定通知的类型和弹出位置,例如:

mg.notify("出错了", {
  type: "error", // type 选项会影响通知的样式
  position: "bottom", // 从页面的下方弹出
});

hexToRGBA

  • Type: hexToRGBA(hex: string) : RGBA

hex转rgba。

RGBAToHex

  • Type: RGBAToHex(rgba: RGBA): string

rbga转hex。

getTitleByFontFamilyAndStyle

  • Type: getTitleByFontFamilyAndStyle(fontFamily: string, fontStyle: string): FontAlias FontAlias

获取字体别名及样式别名。

commitUndo

  • Type: () => void

默认情况下,插件的操作不会提交到撤销(undo)历史记录中。可以通过 mg.commitUndo() 函数手动地将当前的插件操作提交到撤销(undo)历史记录中。

举个例子,假设我们的插件执行了两个操作,即创建了两个矩形:

mg.createRectangle(); // 创建第一个矩形
mg.createRectangle(); // 创建第二个矩形
mg.triggerUndo();

这时,当我们执行撤销动作时,会撤销全部两个矩形。如果我们在两个矩形创建动作之间调用 mg.commitUndo() 函数:

mg.createRectangle(); // 创建第一个矩形
mg.commitUndo(); // 添加撤销历史
mg.createRectangle(); // 创建第二个矩形
mg.triggerUndo();

这时,如果我们执行撤销动作,将只会撤销掉第二个矩形的创建。

triggerUndo

  • Type: () => void

触发撤销动作,将会恢复到最后一次 commitUndo() 的状态。

节点操作

getNodeById

  • Type: getNodeById(id: string): SceneNode | null

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

createRectangle

创建一个新的矩形图层,其行为等价于使用快捷键 R,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createLine

创建一个新的线段图层。其行为等价于使用快捷键 L,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createEllipse

创建一个新的椭圆图层。其行为等价于使用快捷键 O,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createPolygon

创建一个新的多边形图层。

createStar

创建一个新的星型图层。

createPen

  • Type: createPen(): PenNodePenNode

创建一个新的钢笔图层。其行为等价于使用快捷键 P,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createText

创建一个新的文本图层。其行为等价于使用快捷键 T,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createFrame

创建一个新的容器图层。其行为等价于使用快捷键 F,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createComponent

创建一个新的且空的组件图层。

createPage

创建一个新的页面。

createSlice

创建一个新的切图图层。其行为等价于使用快捷键 S,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createConnector

创建一个新的连接线图层。其行为等价于使用快捷键 X,接着点击画布。但与使用快捷键创建的图层不同,使用接口创建的图层不会处于选中状态。

createNodeFromSvgAsync

  • Type: createNodeFromSvgAsync(svg: string): Promise<FrameNode>FrameNode

从 SVG 字符串创建新的节点。等价于 MasterGo 的导入 SVG 功能。

group

  • Type: group(children: ReadonlyArray<SceneNode>): GroupNodeGroupNode

group 函数用来根据其参数中指定的节点创建一个组。

union

union 函数用来根据其参数指定的节点创建一个新的布尔组(联集)图层。

subtract

subtract 函数用来根据其参数指定的节点创建一个新的布尔组(减去顶层)图层。

intersect

intersect 函数用来根据其参数指定的节点创建一个新的布尔组(交集)图层。

exclude

exclude 函数用来根据其参数指定的节点创建一个新的布尔组(差集)图层。

样式

getStyleById

  • Type: (id: string) => Style | null, Style

根据给定的 id 查找对应的样式。如果没找到,则返回 null

createFillStyle

  • Type: (config: { id: string, name: string, description?: string }) => PaintStyle, PaintStyle

通过传入一个已知的Paint样式id来创建一个新的 Fill 样式。此类型的样式可能包含图片,且可用于背景、描边、填充等多个场景。因此我们叫它 Paint。

WARNING

注意:当TextNode的文字具有不同的填充时,createFillStyle只会为第一段填充创建style。

createStrokeStyle

  • Type: (config: { id: string, name: string, description?: string }) => PaintStyle, PaintStyle

通过传入一个带有stoke样式的nodeId和自定义名称来创建一个新的 Stroke 样式。此类型的样式可能包含图片,且可用于背景、描边、填充等多个场景。因此我们叫它 Paint。

createEffectStyle

  • Type: (config: { id: string, name: string, description?: string }) => EffectStyle, EffectStyle

通过传入一个带有的特效的nodeId和自定义名称来创建一个新的特效样式。

createTextStyle

  • Type: (config: { id: string, name: string, description?: string }) => TextStyle, TextStyle

通过传入一个带有的文字样式的nodeId和自定义名称创建一个新的文字样式。

createGridStyle

  • Type: (config: { id: string, name: string, description?: string }) => GridStyle, GridStyle

通过传入一个带有的布局网格的nodeId和自定义名称创建一个新的布局网格样式。

getLocalPaintStyles

  • Type: getLocalPaintStyles(): PaintStyle[], PaintStyle

返回本地paint样式列表。

getLocalEffectStyles

  • Type: getLocalEffectStyles(): EffectStyle[], EffectStyle

返回本地effect样式列表。

getLocalTextStyles

  • Type: getLocalTextStyles(): TextStyle[], TextStyle

返回本地text样式列表。

getLocalGridStyles

  • Type: getLocalGridStyles(): GridStyle[], GridStyle

返回本地grid样式列表。

其它

listAvailableFontsAsync

  • Type: () => Promise<Font[]>, Font

返回当前可用字体列表。该列表与字体选择器中列出的字体列表相同。

loadFontAsync

  • Type: (fontName: FontName) => Promise<void>, FontName

当插件修改会影响文字节点渲染的属性时,如 .fonstSize.fontName 等,需要先确保字体可用。为此,在修改这些属性之前,需要先调用此函数加载对应的字体。

可以使用 listAvailableFontsAsync 的结果作为 loadFontAsync 的参数:

async function loadFont() {
  const fonts = await listAvailableFontsAsync();
  // 加载指定的字体
  await loadFontAsync(fonts[0].fontName);
}

createImage

  • Type: createImage(imageData: Uint8Array): Promise<Image>, Image

根据给定的图片数据(Uint8Array 格式)创建一个图片对象,该图片对象可以用于图层的填充, 支持类型: png | jpeg | gif | webp。下面是一个为图层设置图片填充的例子:

async function fillTheSelection() {
  // 获取当前选中的图层
  const node = mg.document.currentPage.selection[0];
  // 创建一个填充
  const paint = mg.createFillStyle();
  // 创建一个图片对象
  const imageHandle = await mg.createImage(
    new Uint8Array([
      137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0, 0, 5,
      0, 0, 0, 5, 8, 6, 0, 0, 0, 141, 111, 38, 229, 0, 0, 0, 28, 73, 68, 65, 84,
      8, 215, 99, 248, 255, 255, 63, 195, 127, 6, 32, 5, 195, 32, 18, 132, 208,
      49, 241, 130, 88, 205, 4, 0, 14, 245, 53, 203, 209, 142, 14, 31, 0, 0, 0,
      0, 73, 69, 78, 68, 174, 66, 96, 130,
    ])
  );

  // 设置图片填充
  node.fills = [
    {
      type: "IMAGE",
      scaleMode: "FILL",
      imageRef: imageHandle.href, // 将 href 作为图片填充的 imageRef
    },
  ];
}

getImageByHref

  • Type: (href: string) => Image

根据图片的 href 过去图片 Image 对象,通常用于从图片填充中读取图片数据,并做进一步处理:

async function convertImage() {
  // 获取当前选中的图层
  const node = mg.document.currentPage.selection[0];
  // 遍历该图层的所有填充
  node.fills.forEach(async (fill) => {
    // 过滤出图片填充
    if (fill.type === "IMAGE") {
      // 调用 mg.getImageByHref 根据图片 href 获取图片对象
      const imageHandle = mg.getImageByHref(fill.imageRef);
      // 配合图片对象的 getBytesAsync 方法,即可取得图片的数据
      const bytes = await imageHandle.getBytesAsync();

      console.log(bytes); // Uint8Array

      // 接下来可以根据图片数据做进一步处理......
    }
  });
}

getHoverLayer

返回当前鼠标正在hover的图层对象, 如果没有hover的图层,默认返回当前页面对象。

最后更新: