Photoshop UXP manifest.json

UXP Manifestの概要

PhotoshopUXPではCEP同様manifestにパネルの主要な設定を宣言することになります。 但しCEPの時はxmlデータに記述していましたがUXPではjsonに記述するようになりました。 宣言する内容自体はCEPの時と似たような部分も多いです、とはいえ初見だとなかなかとっつきにくい ものでありますしUXPのコアになる部分なので避けて通れません。というわけで今回manifestについての記事になります。

基本的な情報

UXPには既存のPlugin自身のパネルの他にインストールされたPluginを表示するPluginパネルも存在します。 これは使用するプラグインを選ぶだけでなくここからコマンドの実行もできるためその機能面の設定も manifestで宣言する必要があります。

manifestにもバージョンがある

UXPよりmanifestにもバージョンがあります。PhotshopはXDより後発のせいか バージョン4から有効になっています。バージョンが上がる度に設定する項目が増えると 思いますので（実際バージョン5より増えた）状況に応じて情報を調べる必要があります。 バージョン4を基本に解説します。まずはトップレベルの主要な項目について

• manifestVersion

  先ほど述べたmanifestのバージョンです。Photoshopの場合4から有効になります。

• id

  pluginのidです。developerToolで設定したidがそのままここに反映されます。 マーケットプレイスで配布する場合はAdobe Developer Consoleのサイトからidを取得した方が 良いでしょう。

• name

  pluginの名前です。 3文字から45文字の文字数で決める必要があります。

• version

  pluginのバージョンです。

• main

  pluginのコアとなるファイルのパスです。developerToolで生成した場合 index.htmlがデフォルトの設定になっています。（jsファイルでも可らしい）

host

一部のプロパティにはArray型のオブジェクトが入りさらに複数の項目を設定します。まずはhostですが これはアプリケーションに関する項目になります。重要度の高い項目になります。

• app

  対応するアプリケーションの種類になります。2022年7月現在PhotoshopとXDと限られているので XDかPSのみ対応しています。

• minVersion

  プラグインが対応する最低限のアプリケーションのバージョンとなります。 Photoshopの場合UXPの対応が22からなので22より低いバージョンは指定できません。manifestのバージョンとの 組み合わせに気をつけてください。

• maxVersion

  プラグインがどこまで新しいバージョンに対応できるかの項目になります。

• data

  この項目はさらにオブジェクトが入りjsonの項目がさらに深くなります。

  • apiVersion

    まずここにはapiVersionです。これはJavaScriptのapiのバージョンです。 Photoshopのバージョンが22の場合は1,23の場合は2になります。

icons

アイコンの設定はいくつかあるのですがPluginパネル上に表示されるアイコンと パネルが格納された時に表示されるアイコンがあります。これは開発中は必須でもないのですが パッケージ化する時に設定していないと弾かれるので必ず必要になります。 まずはアイコンの共通の設定から解説します。

• width,height

  widthとheightはそれぞれアイコンの高さと幅のピクセルになります。

• path

  アイコン画像のフォルダーのパスになります。manifest.jsonから見て相対的なパスを 指定してください。

• scale

  アイコン画像の大きさを複数設定する場合の項目です。アイコン画像の後ろにpngファイルの場合@1x.png,@2x.pngと 大きさを指定することにより複数の大きさのアイコンを登録できます。モニターの種類なんかによって大きなサイズのアイコンが 表示されると思われます。

  

• theme

  PhotoshopのUIのテーマカラーによってアイコンの表示を変える設定です。Photoshop→環境設定→インターフェースで 選べられるUIの明るさの設定と連動しています。それぞれlightest, light, dark, darkestとなっていて一括して共通の アイコンを登録したい場合はallとします。（デフォルトはall）

• species

  おそらくアイコンのコピーライトに関する項目だと思います。アイコン自体の 著作権を主張しないのであればgenericで問題ないと思います。それ以外にもpluginListが指定できますが 何を意味しているのかちょっとわかりません。Adobeマーケットプレイスに登録する場合は 設定した方がいいと思います。

トップレベルのアイコンについて

トップレベルのアイコンはPluginのパネル上に表示されるアイコンになります。

entryPoints

entryPointsは主にパネルと実際のコードを発火させる項目になります。この項目は大きく分けて commandとpanelがあるのですがcommandはCEPのようなパネルを作らずPluginパネルのボタンを押すとそのままコードを実行させます。 パネルに関してはメニュー、コマンドの設定といった パネルの機能を拡張するような項目が多いです。UXPよりplugin一つにつきパネルを複数管理できるようになりましたが Reactを使わない限りかなり難しいでしょう。詳しくはこちらの記事も参照してください。複数のパネルを作りたい場合のmanifestの設定自体は簡単でパネルの設定のオブジェクトを配列内に入れるだけです。 というわけでまずはcommandとpanelの共通項目から。

• id

  idです。これがそのままscriptで定義するパネル、コマンドのidと紐付けられます。

• type

  entrypointのタイプです。commandかpanelを指定します。 コマンドの場合はPluginパネル上のアイコン,メニューをクリックするとそのまま 関数が実行されます。パネルはそのままHTMLで作成されたパネルになります。

• label

  Pluginパネル、メニュー上に表示されるラベルになります。表示させたい名前等を入れるのですが オブジェクトを入れることにより他言語の設定も可能になります。例えばjaで日本語、frでフランス、deでドイツ といった具合でその他まとめて設定する場合はdefaultになります。

commandタイプ

PluginパネルPluginパネル、メニュー上から直接関数を発火させるタイプとなります。上記の共通の項目以外に 設定する項目も他にないのでmanifestとScriptのサンプルコードのみ載せておきます。

uxpモジュールを呼び出してentrypoints.setupメソッドでパネル環境をオブジェクト形式で渡します。今回commandsメソッドの中にidと同じプロパティとそのプロパティとして関数を渡しています。これで各種ボタンを押した時の関数が設定できます。以下実際に表示された時の画面。

パネルの設定

ここからパネルの設定です。commandに比べて項目が多いです。パネルの大きさなんかも設定します。

• icons

  これは前述のアイコンと全く同じ項目です。異なるのはこちらのアイコンはパネルが小さく格納された時に表示される アイコンというだけです。

  

• minimumSize

  パネルのサイズをユーザーが変える時に できる一番小さいサイズです。

• maximumSize

  ユーザーがパネルのサイズを伸ばした時にできる最大限のサイズです。

• preferredFloatingSize

  パネルが浮いているときに、つまり他のパネルとくっついない独立している時の 標準のサイズです。恐らくPluginを読み込んだ直後はこのサイズの状態でパネルが 表示されると思います。

• preferredDockedSize

  パネルが他のパネルとくっついている時（ツールバーとかアクションパネルとか）の標準となるサイズの はずなのですがどうあがいてもこのサイズにはなりませんでした。 正直どういった時にこのサイズの状態でパネルが表示されるのかよくわかっていません。

• Keyboard shortcuts

  一応公式のサイトに項目として載っていましたが現状何も使えないらしいです。 将来使用できるようになるのか？

commandの登録

commandの登録ですが具体的な関数の登録はJavaScriptファイル内にentrypoints.setupメソッドで 登録します。前述の通りidで紐づけて登録させることでボタンを押した時に関数を発火させます。

ここまでの内容を反映させたサンプルコードを以下に載せておきます。

manifest V5

Photoshopが23.3よりmanifes V5が使用できるようになりました。主にセキュリティー関連の項目が追加され、デフォルトだと V4でできたローカルファイルのアクセスがより厳しく制限されているのでV4からバージョンを上げる時は注意してください。

requiredPermissions

新しく設定するmanifestの項目は原則requiredPermissionsプロパティ内に書き込んでいきます。これはその名の通りプラグインの外部アクセスの許可を設定します。

• webview

  modal dialog内限定ですがUXPパネル内に外部サイトをブラウザのように表示します。”allow”を”yes”に、”domains”プロパティにarray形式で許可するサイトのアドレスを入れていきます。許可されたサイトのアドレスはwebviewのhtml要素として表示できます。以下サンプル。
  modal dialogを立ち上げると以下のように外部ウェブサイトを表示できます。

  

  注意。UXP7.4よりアドレスのトップレベルに*のワイルドカードが使えなくなりました。使用する場合はトップレベル以下で使ってください。https://www.*, https://kawano-shuji.*のようなドメイン指定は使えません。

• clipboard

  リップボードへのアクセスの許可になります。readAndWriteで読み込みも書き込みも許可します。 readで読み込みの許可を与えることもできます。

• localFileSystem

  ローカルファイルへのアクセスの許可を宣言します。 デフォルトだと従来のfs.getFileForSavingメソッドも使えないようになっているので従来のようにファイルアクセスを許可をする場合はrequestにします。 pluginという値もありますが上述通りfs.getFileForSavingメソッドを通じたファイルアクセスはできません。 pluginのsandbox（仮想環境?）にアクセスできるみたいな事は書かれていますがこの辺はちょっとよくわかっていません。 fullAccessという値も公式ドキュメントより確認できます。これはPhotoshop2023より追加された従来のExtendScript,CEPのようにローカルファイルにアクセスできるfsモジュールを使用するための値です。 fullAccessに限りこのモジュールを使用したファイルアクセスができるようになります。 この値を設定した場合Pluginのインストール前にユーザーがPluginからファイルアクセスへの許可を求られるらしいです。

• launchProcess

  UXPプラグインから外部サイトにアクセスしたりアプリケーションを立ち上げるshell.openExternal,shell.openPathメソッドの実行を許可する項目です。 値としてschemesとextensionsにarray型のstringを渡せます。 schemesがopenExternalで外部サイトにアクセスするドメインの種類、extensionsがshell.openPathでローカルのファイルにアクセスする時の拡張子の種類になります。

• allowCodeGenerationFromStrings

  allowCodeGenerationFromStringsにtrueを渡すとstring型で書かれたコードをjsとして実行できます。 サンプルではevalメソッドで実行していますが正直web方面だとセキュリティ関連の理由でほとんど使われていないのであまり馴染みがないと思います。

• ipc.enablePluginCommunication

  ipc通信、異なるplugin同士の通信の許可を設定します。trueでアクセスを許可します。 サンプルだとJaroslavBereza氏のalchemist pluginを立ち上げるコードになります。 以下のサンプルコードは実行前にalchemist pluginをインストールしてください。

• loadEvent

  これだけPhotoshop23.1より有効になリました。pluginが読み込まれるタイミングの項目です。 デフォルトはuseでpluginのパネルが表示された時、もしくはコマンドメニューから 関数が発火した時に読み込まれます。メモリの使用を最低限にするため原則これが勧められるみたいです。 startupはPhotoshopが立ち上がった時に同時にpluginが読み込まれます。Photoshopが立ち上がった時に pluginのイベントを有効にしたい時なんかはこっちの設定になります。 尚このloadEventのみhost,dataプロパティ内に書いてください。ユーザーの意思とは無関係にプラグインが立ち上がるので慎重に使用すべきでしょう。

• enableSWCSupport

  UXP7.2よりSpectrum Web Componentがサポートされたのでそれが使えるようにするための項目です。以下のようにセットしてください。
  詳しくはデザインの記事を参照してください。

• enableAlerts

  UXP7.4から今まで標準で使えたWindow.alert prompt confirmが標準で使えなくなります。そのままメソッドを実行してもundefinedしか返さないので manifestにenableAlertsのflagを立てる必要があります。以下のように加えてください。
  この変更によってUXP7.4以前に動いていたプラグインなどが動かなくるケースもあるので気をつけてください。

• GUID

  UXP v7.3よりGUIDの取得ができるようになりました。manifestにenableUserInfoの項目を追加します。
  その後、UXPモジュールのuserInfoより取得できます。

• enableMenuRecording

  Photoshop Action Recording関連です。manifest.jsonにenableMenuRecordingをセットするとPluginのcommandメニューから実行、登録した関数をアクションに記録させることができます。

最後に一連のmanifest V5のサンプルを以下に載せておきます。