UXP for Photoshop：manifestの作成

今回は公式ドキュメントに沿って、manifest周りを進める。

現状のmanifest.json

{
  "id": "Test-5jov8t",
  "name": "modelin UXP test1",
  "version": "1.0.0",
  "main": "index.html",
  "host": [
    {
      "app": "PS",
      "minVersion": "24.2"
    }
  ],
  "manifestVersion": 4,
  "entrypoints": [
    {
      "type": "panel",
      "id": "vanilla",
      "minimumSize": {
        "width": 230,
        "height": 200
      },
      "maximumSize": {
        "width": 2000,
        "height": 2000
      },
      "preferredDockedSize": {
        "width": 230,
        "height": 300
      },
      "preferredFloatingSize": {
        "width": 230,
        "height": 300
      },
      "icons": [
        {
          "width": 32,
          "height": 32,
          "path": "icons/icon_D.png",
          "scale": [
            1,
            2
          ],
          "theme": [
            "dark",
            "darkest"
          ],
          "species": [
            "generic"
          ]
        },
        {
          "width": 32,
          "height": 32,
          "path": "icons/icon_N.png",
          "scale": [
            1,
            2
          ],
          "theme": [
            "lightest",
            "light"
          ],
          "species": [
            "generic"
          ]
        }
      ],
      "label": {
        "default": "Starter Panel"
      }
    }
  ],
  "icons": [
    {
      "width": 23,
      "height": 23,
      "path": "icons/dark.png",
      "scale": [
        1,
        2
      ],
      "theme": [
        "darkest",
        "dark",
        "medium"
      ]
    },
    {
      "width": 23,
      "height": 23,
      "path": "icons/light.png",
      "scale": [
        1,
        2
      ],
      "theme": [
        "lightest",
        "light"
      ]
    }
  ]
}

最初にDevToolで設定した内容が並ぶ。DevTool使わずとも手で描いてもいいはず。manifestのバージョンは4らしい。5のドキュメントも存在したのでその詳細は後述する。

entrypoints設定はデフォルトの振る舞いでパネルが指定されている。ここをメニューとかにもできたはず。（AdobeXDでちょろっとだけUXPプラグイン作ったことがあるので多少知識がある。だいぶ忘れてるけど。）あとはドック時やフローティング時の好ましい大きさの設定と、最大最小サイズの設定。なんだ簡単じゃないか。

最後にUIのアイコン設定が２種類（UIのテーマ５つに2種類で対応、darkest、dark、medium、light、lightest）あるが、パネル表示やメニューの表示には見当たらなかった。どこに表示されるのだろうか。

アイコンファイルはテンプレートフォルダ内に存在して、2倍の46pxサイズを含めて4ファイル存在した。まあ今回アイコンをいじるつもりはない。自分で作る場合もデザイン上手いことして1つの見た目で済ませたい気もする。

ドキュメントの確認

manifest関連ドキュメントを確認して、メニューからの動作に書き換えてみる。それぞれドキュメントはざっくりまとめる。

UXP Manifest v4

このページの内容は、XDのプラグイン作成でも共通。

https://developer.adobe.com/photoshop/uxp/2022/guides/uxp_guide/uxp-misc/manifest-v4/

manifestにコード類は記載されない、メタデータ定義のみ。
サンプル内エントリーポイントにメニューコマンドが見当たる。
サンプル内にパネルとはまた別のアイコン定義が見当たる。
バージョン定義はx.y.z の形式で有効なのは0から99の数字のみ。
mainとしてはhtmlだけでなくjsも指定できる。（デフォルトはむしろjs。）

ホスト：maxVersion指定もできる。
ホスト：現在 "XD" または “PS” のみサポート。
アイコン：開発時はなくてもいい、公開時は必須。
アイコン：全部のテーマに1つのアイコンでまかなう場合はallとも書ける。
アイコン：スケール設定で、等倍、2倍は必須。
アイコン：スペース設定で使っていい場所（フォトショ内部やマケプレなど）を指定 "generic" でどこでもOKとなる。
アイコン：全体のアイコン設定は、パネルなどの設定で上書きできる。
エントリーポイント：コマンド定義またはパネル定義の配列を指定。
エントリーポイント：コマンドの場合ショートカット指定ができる。
エントリーポイント：サイズ系の指定が有効なのはパネルのみ。
エントリーポイント：パネルアイコン指定は公開する場合必須。
ラベルで指定しているテキストは辞書型にして多言語を含められる。

実行タイプはパネルかメニューコマンドしかないようだ。多言語は今回やらない。アイコンもデフォルトのまま拝借。パネルアイコンは最小化すると表示されるようだが手元のテンプレート実行する限り表示されてない。
ショートカット指定は他とかぶったらどうするのだろう。と思ったらまだ実装されていないらしい？（Shortcuts are not yet available for plugins.）

Photoshop Product specific manifest

ホストの定義の data セクションにPhotoshop独自の定義が2つほど設定できる。

https://developer.adobe.com/photoshop/uxp/2022/guides/uxp_guide/uxp-misc/manifest-v4/photoshop-manifest/

apiVersion： Photoshop 2021ではプラグイン同士で処理がかち合う事があった。
apiVersion：Photoshop 2022ではモーダルモードを用意した。処理のかちあいを回避できる。
apiVersion： apiVersion1がモーダルなし、2があり。互換性のために1が残っている。
apiVersion： apiVersion1はすでに非推奨、で新機能は2にしか乗らない。
apiVersion：デフォルト値はターゲットのフォトショップバージョンで変わる。 23.0.0未満の場合はapiVersion1がデフォルトになる。

loadEvent：Photoshop 23.1以降で指定可能。
loadEvent：いつプラグインを実体化するか定義できる。基本的には利用時に実体化する。
loadEvent：Photoshopのイベントを監視・定期的にサーバーと通信などするものはフォトショップ起動時に同時に実体化したい事がある。
有効な値は、”use” と ”startup”。デフォルトは use。

今回自分が作るものは自動的にapiVersion2設定になるのと常駐プラグインでもないので、ここで指定することは何もなさそう。

UXP Manifest v5

特定の機能を使うにはManifestのバージョンをv5にする必要があるようだ。ネットワーク、クリップボード、ファイルアクセス、プロセスの起動など。おやソケット通信以外でも外部アプリケーションが叩けるのか？

https://developer.adobe.com/photoshop/uxp/2022/guides/uxp_guide/uxp-misc/manifest-v5/

v5を使うと新しいパーミッションの仕組みと、モーダルダイアログでのwebviewが使える。
v5の利用にはPS 23.3.0以上が必要。（2022年春ごろのフォトショである模様。）
サンプルjsonから見て取れるv4との差はrequiredPermissionsセクション。
URLルールによるwebview起動許可設定や、スキームおよびファイル拡張子による他アプリ起動許可設定が見て取れる。

entrypointのメソッドにはv4からv5で変更点がある。
v4：エントリーポイント関数でPromiseを使えない、タイムアウト委設定ができない。
v5：上記が可能になる。パネルはイベントがたくさんあるのでいったん忘れて、コマンドではentrypoints.setupにてplugin.destroy（破棄処理？）を非同期で実装することもできる、ようだ。

パーミッション：requiredPermissionsセクションの下に機能種別ごとの設定を書く。
パーミッション：network 設定でアクセスを許可するドメインを指定する。これによりパネル状に外部イメージなどを置ける。
パーミッション：clipboard設定で読み書きor読むだけのクリップボードアクセス権限を得る。
パーミッション：localFileSystem設定でファイルの書き出し、読み込み権限を得る。この許可がなくても、plugin://, plugin-temp://, and plugin-data:// などにはアクセスできる模様。
パーミッション：launchProcess設定でopenPath および openExternal メソッドの実行許可が取れる。
- openExternal openPath情報は見つからない
パーミッション：ipc設定でプラグイン同士のやり取りが可能になる。プラグインIDで別プラグインを特定していく模様。
パーミッション：webviewでモーダル表示限定で、webviewへのアクセスが可能となる。

webview表示でアクセスするURLはnetwork 設定とは別なのだろうか。とりあえず今回自分が使うつもりはない。使う可能性があるのは、localhost指定でのnetworkまたはlaunchProcessでのプロセス起動、localFileSystemでの画像ファイル読み書き。

Code Samples

manifestからんでたのでこれも。

https://developer.adobe.com/photoshop/uxp/2022/guides/code_samples/

ここで紹介しているコードはギハブにもある。
テーマのCSS色とかが var(–uxp-host-font-size) みたいにとれる。
manifestのID名のjs関数(async function)がメニュー押下時にキックされる。
メニューにたくさんコマンドを並べることもできる。
パネル定義した場合は、main項目として設定したhtml・jsが呼ばれる。
jsx を呼び出す場合にオンザフライで実行できる仕組みを用意しているよ。
（よくわからないが現状jsxファイルを用意して実行する必要がある場合があるのだろう。）
UIライブラリには、React・Vue・Svelteなどが使える。
（シングルページアプリになるという意味でもありそう。）
require(“photoshop”) でフォトショの機能を使うが、require(“uxp”) でUXPの共通機能が使える。これはアプリケーションが変わっても共通のコア機能である。
webリクエストあfetchメソッドで可能。詳しくは別ページ見て。
OAuth 認証できるよ。別ページ見て。
equire(“uxp”).host で現在動いているアプリケーション名がわかるので、一つのコードで複数のアプリで動くよなプラグイン開発が可能。詳しくは。
ExtendScriptのように外部のオブジェクトと連携はできない。（ExtendScriptを利用したアプリ同士が連携できることを言っている？）しかしwebsockets で外部アプリケーションや別プロセスとやり取りができる。以下のサンプルを見て。
- エレクトロンを使ったアプリとやり取りするサンプル
- webソケットで通信するサンプル（リンク切れしていたが多分これ）
WebAssembly もサポートするよ、サンプル。

やはり外部アプリ連携はwebソケット使えと言っている。

manifestの書き換え

ドキュメントを読んだ結果、manifest.jsonがこのように書き換わった。コマンド2つ設定、アイコンはダークテーマの物で全部まかなう、network・localFileSystem・launchProcessそれぞれのパーミッションを要求。

まだ動かしていないので間違っているかもしれない。

{
  "id": "Test-pfinim",
  "name": "modelin UXP test1",
  "version": "1.0.0",
  "main": "index.html",
  "host": [
    {
      "app": "PS",
      "minVersion": "24.2"
    }
  ],
  "manifestVersion": 5,
  "entrypoints": [
    {
      "type": "command",
      "id": "commandFn1",
      "label": {
        "default": "comamnd #1"
      }
    },
    {
      "type": "command",
      "id": "commandFn2",
      "label": {
        "default": "comamnd #2"
      }
    }
  ],
  "icons": [
    {
      "width": 23,
      "height": 23,
      "path": "icons/dark.png",
      "scale": [
        1,
        2
      ],
      "theme": [
        "all"
      ]
    }
  ],
  "requiredPermissions": {
        "network": {
            "domains": [
                "localhost",
            ]
        },
		"localFileSystem": "request",
        "launchProcess": { 
            "schemes":
                [ "https"]
        }
    }
}

まとめ

Manifestのバージョンは５にしないと便利機能が使えない。
使いたい機能をManifest内のrequiredPermissionsセクションに記述する。

サンプルはたくさんある。
https://github.com/AdobeDocs/uxp-photoshop-plugin-samples

NEXT TODO

今回はここまで。次回こそ手を動かす。かもしれない。

モーダル実行についてドキュメント確認。
https://developer.adobe.com/photoshop/uxp/2022/ps_reference/media/executeasmodal/
APIについて、とりあえずこのページだけ確認。
https://developer.adobe.com/photoshop/uxp/2022/ps_reference/
こっちのAPI一覧はざっくり必要そうな部分のみ確認。
https://developer.adobe.com/photoshop/uxp/2022/ps_reference/classes/photoshop/
webソケットサンプル確認する。
https://github.com/AdobeDocs/uxp-photoshop-plugin-samples/tree/main/io-websocket-example
メニューからコマンド実行させる。
レイヤー名で画像を書き出したい。

現状のmanifest.json