Adobe XDプラグインのソースコードの解説 #AdobeIO #XDPlugin #AdobeXD

新しい仕様をご確認ください

2019/3/8に本稿で紹介しているmanifest.jsonの仕様が新しくなりました。最新の仕様も合わせてご確認いただきますようお願いします。

新しい仕様を確認する

今回はAdobe XDのプラグインに含まれる manifest.json と main.js の構成と内容について解説します。
XDのプラグインをまだ開発されたことのない場合は、下記の記事でプラグインの開発の最初の手順をわかりやすく解説していますので、最初はこちらを読まれることをおすすめします。

• はじめてのAdobe XDプラグイン開発！定番のHello Worldを表示させてみよう #AdobeXD #AdobeMAX – Adobe Blog
• Adobe XDのプラグイン開発に役立つサイトのまとめ #AdobeIO #XDPlugin #AdobeXD – Adobe Blog

手元にプラグインのソースコードがない場合は、下記のサイトからプロジェクトテンプレートをダウンロードできます。

• Adobe I/O
  https://console.adobe.io/plugins
  Adobe IDを用いてConsoleにログインし、プラグイン名を入力後、Create Pluginを押した後に表示される「Download Starter Project」のリンクよりテンプレートをダウンロードできます。
• Adobe XD Official Github (quick-start)
  https://github.com/adobeXD/Plugin-samples
  quick start のフォルダが最小構成のテンプレートです。

プラグインに含まれる3つのファイル

プロジェクトテンプレートに含まれるファイルのうちプラグインに必須のファイルは下記の2つです。
icon.pngはなくても動作しますが、プラグインマネージャーでの配布やプラグインの管理等を考慮すると、ほぼ必須と言えるでしょう。

//*******Adobe XD Plugin File structure*******
AdobeXDPluginProject
├── images
│   └── icon.png
├── main.js
└── manifest.json

manifest.json

XDプラグインのメタデータ（プラグインID, プラグインの名前, プラグインのバージョン）とプラグインの「操作メニュー」の設定を記述したJSONファイルです。（manifest.jsonには実行可能なコードは含まれません）

main.js

全てのプラグインの処理のエントリーポイントとなるファイルです（main.js以外の名前にはできません）。
manifest.json の commandIdで指定された関数の処理を記述します。

icon.png

プラグインマネージャー（「プラグイン」> 「プラグインを管理」で起動します）に表示されるアイコン画像です。

それではそれぞれのファイルの内容と構成を確認しましょう。

manifest.jsonの設定値とプラグインマネージャーの表示項目、プラグインメニューの項目の関係

manifest.jsonはプラグインマネージャーの表示項目とプラグインメニューの項目を設定しますが、下記の図の様な関係になっています。

https://blogs.adobe.com/japan/wp-content/uploads/2019/01/manifest-json-preview-structure.png

プラグインマネージャーとmanifest.jsonとUIメニューの関係

上記のmanifest.jsonの内容

// ******manifest.json******
{
  "id": "abcd0123",
  "version": "1.0.0",
  "name": "Red square",
  "description": "Insert a square",
  "icons": [
    {
      "width": 96,
      "height": 96,
      "path": "images/icon.png"
    }
  ],
  "host": {
    "app": "XD",
    "minVersion": "13.0.0"
  },
  "uiEntryPoints": [
    {
      "type": "menu",
      "label": {
        "default": "Insert a square",
        "en": "Insert a square",
        "ja": "正方形を挿入する"
      },
      "shortcut": {
        "mac": "Cmd+alt+0",
        "win": "Ctrl+alt+0"
      },
      "commandId": "menuCommand"
    }
  ]
}
// ******manifest.json******

manifest.jsonのフィールドの説明

id (string)

プラグインのユニークIDです。他のプラグインと重複しないように、Adobe I/O Consoleで取得することをおすすめします。

version (string)

プラグインのバージョン番号です。 x.y.z の形式で入力しそれぞれの値が 0〜99 になるようにしてください。 例えば 1.10.34などセマンティックバージョニングを採用するとよいでしょう。バージョニング番号はプラグインマネージャーがアプリの更新を管理する際などに利用します。

name (string)

プラグインマネージャーに表示されるプラグインの名前です。プラグインの機能などが分かるような名称にしてください。また、Adobe XDのプラグインリスト （「プラグイン」>「プラグインを見つける」）で配布する場合はAdobe I/O Consoleで登録したプラグイン名と一致していなければいけません。

description (string)

プラグインマネージャー とプラグインリストに表示される「プラグインの説明」です。

※Adobe I/O Consoleにプラグインを登録し、XDのプラグインリストで公開する場合はname, descriptionは英数字だけにしてください。現在は日本語に対応しておりません。

icons (Array)

プラグインマネージャーに表示されるアイコン画像の相対パスです。XDは画面密度に応じて、96px(2倍表示）と48px（等倍表示）でアイコン表示を切り替えますが、現在は96pxの画像を1つのみ指定してください。※現在は2つめの48pxの画像を指定することはできません。

host.app (string)

Adobe XDで動作することを示す設定です。 “XD”を指定してください。

host.minVersion (string)

Adobe XDプラグインが動作する最低のバージョン番号を指定してください。

x.y.z の3つのセグメントで、メジャーバージョン番号 ( x ) 以降は0を指定するだけでもよいです。（例： 13.0.0, 14.0.0など）

host.maxVersion (string)

（オプション項目）Adobe XDプラグインが動作する最高のバージョン番号を指定してください。minVersionと同様に3つのセグメントを指定してください。

uiEntryPoints (Array)

プラグインのメニューに表示される文言と実行する関数を宣言します。
次項を参照してください。
※UiEntryPointsのObjectは後述するMenuItemDefinitionまたはSubmenuDefinitionを宣言してください。

manifest.json の uiEntryPoints の設定項目

uiEntryPointsはMenuItemDefinition またはSubmenuDefinitionを要素に持つ配列で構成されます。MenuItemDefinitionが実行（選択）可能なメニューを定義し、SubmenuDefinitionがMenuItemDefinitionを子要素に持つサブメニューを定義します。

MenuItemDefinition.type (string)

エントリーポイントの種類を指定してください。現在は”menu”のみサポートされています。

MenuItemDefinition.label (string or Object)

プラグインのメニューに表示される文言を設定してください。ISO-639-1 のフォーマットに従って多言語対応が可能です。文言を規定する際はXD Plugin Experience Guidelines (XDPEGs)にしたがってください。
https://adobexdplatform.com/plugin-docs/xdpegs/5-ui.html#513-menus

MenuItemDefinition.commandId (string)

プラグインのmain.jsでexportされた識別子を設定してください。

MenuItemDefinition.shortcut (mac:string, win:string)

MacとWindowsで動作するショートカットキーを指定できます。下の「ショートカットキーの設定」の項を参照してください。

SubmenuDefinition.type (string)

MenuItemDefinition.type と同じように設定してください。

SubmenuDefinition.label (string or Object)

MenuItemDefinition.label と同じように設定してください。

SubmenuDefinition.menuItems (Array)

MenuItemDefinitionの配列を設定してください。SubmenuDefinition.menuItemsの中にSubmenuDefinitionを定義することはできません。
※サブメニューは1段階のみサポートされており、2段階目以降のサブメニューを定義することはできません。

サブメニューを設定した場合のuiEntryPointsの例

サブメニューを設定した場合、 uiEntryPointsは下記の様になります。
（manifest.jsonのuiEntryPointsの箇所だけ抜粋しております）

// ******manifest.json (excerpt) ******
"uiEntryPoints": [
  {
    "type": "menu",
    "label": {
      "default": "Insert a red square of arbitrary size...",
      "en": "Insert a red square of arbitrary size...",
      "ja": "任意のサイズの正方形を挿入する..."
    },
    "shortcut": {
      "mac": "Cmd+alt+0",
      "win": "Ctrl+alt+0"
    },
    "commandId": "menuCommand"
  },
  {
    "type": "menu",
    "label": {
      "default": "Insert a red square of fixed size",
      "en": "Insert a red square of fixed size",
      "ja": "規定のサイズの正方形を挿入する"
    },
    "menuItems":[ //サブメニューの表示設定
      {
        "type": "menu",
        "label": {
          "default": "Insert a red square of 100px",
          "en": "Insert a red square of 100px",
          "ja": "1辺100pxの正方形を挿入する"
        },
        "shortcut": {
          "mac": "Cmd+alt+1",
          "win": "Ctrl+alt+1"
        },
        "commandId": "menuCommand100"
      },
      {
        "type": "menu",
        "label": {
          "default": "Insert a red square of 200px",
          "en": "Insert a red square of 200px",
          "ja": "1辺200pxの正方形を挿入する"
        },
        "shortcut": {
          "mac": "Cmd+alt+2",
          "win": "Ctrl+alt+2"
        },
        "commandId": "menuCommand200"
      }
    ]
  }
]
// ******manifest.json (excerpt) ******

上記の様に manifest.json を設定すると、下記の様にサブメニューが表示されます。

Adobe XD プラグインのサブメニューの例

ショートカットキーの設定

ショートカットキーは1つ以上の修飾キーと英数字キーを “+” で組み合わせることによって設定されます。(Ctrl+Shift+J, Ctrl+Shift+W など）
ショートカットキーの「英数字キー」の指定は大文字と小文字の区別をしません。 “Cmd+P”と”Cmd+p”は同じ内容になります。
F1-F12などの他のキーはサポートされていません。

注意：ショートカットキーがXDまたは他のプラグインで設定されている場合は、プラグインの読み込み時にDeveloper Consoleにエラーが表示されます。

修飾キーの設定

Macの場合: Cmd, Ctrl, Opt / Alt, Shift を設定できます。Cmd または Ctrl を必ず含めてください。

Windowsの場合: Ctrl, Alt, Shift を設定できます。Ctrl を必ず含めてください。

main.jsの内容と構成

下記のようなソースコードを元に、プラグインのエントリーポイントとなるmain.jsについて説明します。
main.js は次の3つの要素で構成されています。

• require()でAdobe XD PluginのAPIをロードする
• module.exports.commands で manifest.json で宣言された関数とリンクする
• Adobe XDのデータを処理する部分 module.exports.commands で宣言された関数は selection と rootNodeという2つの引数が呼ばれます。利用しない場合、rootNodeの引数は省略してもかまいません。

// ******main.js******
const { Rectangle, Color } = require('scenegraph'); // APIの読み込み

function main(selection, rootNode) { //selection, rootNodeの引数
    // Go to Plugins > Development > Developer Console to see this log output
    console.log('No dialog is running!');

    // Insert a red square at (0, 0) in the current artboard or group/container
    const shape = new Rectangle();
    shape.width = 100;
    shape.height = 100;
    shape.fill = new Color('#f00');
    selection.insertionParent.addChild(shape); // 正方形を追加
}

module.exports = {
    commands: {
        menuCommand: main, //manifest.json の設定値
    },
};
// ******main.js******

Scenenodeの操作

Adobe XDプラグインでは、Adobe XDのデータの構造を scenegraphと呼びます。sceenegraphはartboardやgroupに含まれる要素の包含関係とオブジェクトの順序（前面・背面）を木構造(DOM tree)で表現したものです。scenegraphに含まれる要素、例えばrectangleのようなオブジェクトやグループをscenenodeと呼びます。なお、scenegraphの頂点には必ずrootnodeが存在し、artboardはrootnodeの直下に配置されます。なお、scenegraphにはpasteboardというscenenodeは存在しません。artboardを先祖ノードに持たないオブジェクト（つまり、rootnodeの直下にあるオブジェクト）が操作画面上のpasteboard上に表示されていることになります。

scenegraphの要素にアクセスするためにはmodule.exports.commands で宣言された関数の引数の selection （第1引数）と rootnode（第2引数）を利用します。selectionが選択中のオブジェクト、rootnodeがscenegraphのrootnodeです。
なお、14.0.42のアップデート後は、scenegraph apiよりアクセスすることも可能です。その場合は下記の様に宣言してください、selection, root(rootnode)を取得できます。

const { selection, root } = require('scenegraph');

Adobe XDプラグインはscenegraph APIを通してScenenodeの追加、削除、プロパティの更新ができます。また、scenegraphの構造の変化（グループ化・グループ解除、全面・背面への移動）はcommands APIを通じて行います。

scenegraphの例

require で利用できるAPI

requrieで利用できるAPIは下記のものがあります。詳細はAPIs · Adobe XD Plugin Reference をご覧ください

application require(‘application’)

XD, OSのバージョン、rendition の書き出し

scenegraph require(‘scenegraph’)

documentNode(Artboard, Rectange, Ellipse, Line, Path … など ）の参照、変更、追加、削除

commands require(‘commands’)

selection に含まれるオブジェクトへの操作group, ungroup, createMaskGroup, bringToFront

storage require(‘uxp’)

ローカルストレージへのアクセス

clipboard require(‘clipboard’)

現在は clipboard.copyText() のみ可能、clipboard からartboardへのペースト等はできません。

viewport require (‘viewport’)

XDのビューポート（表示領域）を変更することができます。
14.0.42以降のバージョンで利用可能です。（manifest.jsonのhost.minVersionに14.0.0を設定してください）

最後に

長くなってしまいましたが、Adobe XDプラグイン開発に欠かせない manifest.json と main.js について解説いたしました。
XDのアップデートに伴い、PluginのAPIも充実させていきますのでこれからもご期待ください。

また、開発に際して、「このAPIの使い方がわからない（もしくは動かない）」「こういうAPIがほしい！」と言ったことがありましたら、Adobe XD Plugin Developers のフォーラム（英語）への投稿をお願いいたします。

（本投稿は「はじめてのAdobe XDプラグイン開発」で発表した内容を元に編集しました。）

日本語の参考リンク

• #242 イベント生中継「はじめてのAdobe XDプラグイン開発」 – Adobe Blog #CCDojo
• はじめてのAdobe XDプラグイン開発！定番のHello Worldを表示させてみよう #AdobeXD #AdobeMAX – Adobe Blog
• Adobe XDプラグインの世界へようこそ! Adobe MAX 2018セッションレポート #XDPlugin #AdobeXD – Adobe Blog

英語の参考リンク

• AdobeXDプラグインのリファレンス
  • manifest.json · Adobe XD Plugin Reference
  • main.js · Adobe XD Plugin Reference
  • JavaScript support · Adobe XD Plugin Reference
  • API environment · Adobe XD Plugin Reference
• プロジェクトテンプレート
  • AdobeXD/plugin-samples: Adobe XD Plugin Samples
  • Adobe I/O Console