batchPlay は、UXP のスクリプトやプラグインから、Photoshop のコマンドを直接実行する仕組みです。
ExtendScript の executeAction にあたり、DOM で書けない操作に使います。
- 書き方：
require('photoshop').action.batchPlay([記述子], オプション)。Promise が返る - 記述子は _obj（コマンド）・_target（対象）・_ref（対象の指定）で書く
- apiVersion 2のプラグインでPhotoshopの状態を変えるなら executeAsModal の中で実行する
- コードは、アクションパネルの「Copy As JavaScript」で取れる（開発者モードのとき）
この記事は、Adobe の UXP for Photoshop の公式ドキュメント（developer.adobe.com と GitHub の AdobeDocs/uxp-photoshop、2026年9月29日に確認）にもとづいています。
2026年10月20日に、Photoshop 2026（27.11.0）とWindows 11 Proで、開発者モードの切り替え、「JavaScript としてコピー」（英語版の Copy As JavaScript）、［アクションコマンドを記録］と、取ったコードの実行を確かめました。
下の公式の例も、2026年10月19日に同じ環境で実行しています。
画面の名前は日本語版の表記で書き、英語版の名前は公式ドキュメントの表記を添えています。
プラグインとして読み込む方法と、UXP Developer Tool は確かめていません。
公式の例
選んでいるレイヤーを隠す、公式ドキュメントの例です。文書を開き、対象レイヤーを選択してから実行してください。例のresultはPromiseなので、後続処理で完了やエラーを扱う場合はawaitで待ちます。
const {app, action, core} = require('photoshop');
async function hideActiveLayer() {
return await action.batchPlay([{
_obj: "hide",
_target: [{_ref: "layer", _enum: "ordinal"},
{_ref: "document", _enum: "ordinal"}]
}], {});
}
let result = core.executeAsModal(hideActiveLayer, {commandName: "Hide Layer"});| キー | 意味 |
|---|---|
| _obj | 実行するコマンドの名前（hide など） |
| _target | 対象。具体的なもの（レイヤー）から順に、住所と逆の順で並べる |
| _ref | 対象の種類（layer・document など） |
_enum: "ordinal" | 今選んでいるもの |
2026年10月19日に、この例をそのまま拡張子 .psjs のファイルに保存し、［ファイル］→［スクリプト］→［参照］から実行しました。
選んでいたレイヤーだけが非表示になり、エラーの窓は出ませんでした。
このときは開発者モードはオフのままで、.psjs のスクリプトを動かすだけなら開発者モードは要りませんでした。
レイヤーを隠しただけなので、ヒストリーには何も増えませんでした。
executeAsModal
apiVersion 2のプラグインでPhotoshopの状態を変えるコマンドは、executeAsModal の中で実行します。.psjs単体のスクリプトとは実行環境を分けて考えてください。
commandName は必ず指定し、処理中のプログレスバーの上に表示されます。
上の例では処理が一瞬で終わったので、プログレスバーは見えませんでした。なお、batchPlayは例外を投げる場合だけでなく、返った配列に_obj: "error"などのエラー結果が入る場合もあります。エラーの窓が出なかったことだけで成功とせず、戻り値と文書の変化を確認してください。
2026年10月19日に、.psjs のスクリプトで executeAsModal を使わずにレイヤーを表示する batchPlay を実行したところ、エラーにならずに効きました。
この記録は.psjs単体での結果で、apiVersion 2のプラグインでもexecuteAsModalを省略できることを示すものではありません。プラグインへ移す場合は、公式の要件に従ってexecuteAsModal内で状態を変更し、awaitで完了を待ってください。今回はプラグインで再実行していません。
コードを取る方法
Copy As JavaScript
- ［編集］→［環境設定］→［プラグイン］で「開発者モードを有効にする」にチェックを入れて［OK］を押し、Photoshop を再起動する
- アクションパネルで、アクションか、その中の手順を選ぶ
- パネルの右上のメニューから「JavaScript としてコピー」（英語版は Copy As JavaScript）を選ぶ
- クリップボードに、executeAsModal と batchPlay の形のコードが入る
「Copy As JavaScript」は、開発者モードが有効なときだけメニューに出ます。
開発者モードを切り替えるのは、Photoshop の環境設定です。
チェックを入れて［OK］を押しただけでは効かず、同じ画面に「変更は Photoshop を再起動するまで有効になりません。」と出ます。
［ファイル］→［終了］で終了し、起動し直すと有効になりました。
2026年10月20日に、開発者モードで起動し直した Photoshop で、アクションパネルに「階調の反転」を1つだけ記録しました。
その手順を選んでパネルのメニューを開くと、「JavaScript としてコピー」がありました。
開発者モードをオフに戻して起動し直すと、手順を選んでもパネルのメニューにこの項目はありませんでした。
「JavaScript としてコピー」を選ぶと、クリップボードに次のコードが入りました。
async function actionCommands() {
let commands = [
// 反転
{
"_obj": "invert"
}
];
return await require("photoshop").action.batchPlay(commands, {});
}
console.log(
await require("photoshop").core.executeAsModal(actionCommands, {"commandName": "Action Commands"})
);記録した手順の名前（反転）がコメントで入り、executeAsModal の commandName は「Action Commands」でした。
最後の部分は、関数の外で await を使う書き方です。
このコードを拡張子 .psjs のファイルに保存し、［ファイル］→［スクリプト］→［参照］から実行すると、選んでいたレイヤーの色が反転しました。
エラーの窓は出ず、ヒストリーには「階調の反転」が1つ増えました。
console.log の結果は、［参照］からの実行では画面に何も出ませんでした。
練習用の文書はスクリプトで用意し、記録したアクションは確かめた後に削除しています。
Record Action Commands
開発者モードでは、［プラグイン］→［開発］→［アクションコマンドを記録…］（英語版は Plugins → Development → Record Action Commands…）で、画面の操作を記述子としてファイルに記録できます。
選ぶと保存の窓が開き、ファイルの種類は「アクション (*.JSON)」でした。
記録している間は、同じ場所の項目が［アクションの記録を停止］に変わります。
2026年10月20日に、記録している間にレイヤーパネルの目のアイコンで red-square を隠してから停止すると、ファイルには {"_obj":"hide","null":[{"_name":"red-square","_ref":"layer"}]} の1件が入っていました。
対象は _target ではなく null というキーに、レイヤーの名前（_name）で入っていました。
開発者モードがオフのときは、［プラグイン］メニューに［開発］がありませんでした。
通知を見張る
action.addNotificationListener(['all'], ...) で、実行されたコマンドを見張る方法も公式に載っています（開発者モードのときだけ動く）。
この方法は確かめていません。
Alchemist
記述子を調べるプラグインとして Alchemist がよく使われますが、Jaroslav Bereza さんが作ったもので、Adobe の公式のツールではありません。
オプション
| オプション | 働き |
|---|---|
| synchronousExecution | 終わるまでスクリプト全体を止めて値を返す（なるべく使わないよう案内） |
| continueOnError | エラーが出ても続ける（初期値 false） |
| immediateRedraw | 記述子をすべて実行した後にUIを更新する（初期値 false） |
| historyStateInfo | Photoshop 2022 で非推奨。executeAsModal の履歴の機能を使う |
記述子ごとの _options.dialogOptions では、ダイアログの出し方を "silent"（初期値）・"dontDisplay"・"display" から選べます。
ExtendScriptのコードとの対応
ExtendScript の ScriptingListener で取ったコード（charIDToTypeID・ActionDescriptor）は、そのままでは UXP で動きません。
UXP では、同じ操作を「Copy As JavaScript」で取り直すのが近道です。
ExtendScript 側のコードの読み方は、PhotoshopのAction Managerの読み方で紹介しています。
まとめ
- batchPlay は UXP から Photoshop のコマンドを直接実行する
- 記述子は _obj・_target・_ref。_target は具体的なものから
- apiVersion 2のプラグインで状態を変えるなら executeAsModal の中で。commandName は必須
- コードは「JavaScript としてコピー」（Copy As JavaScript）で取る。開発者モードは環境設定で入れ、再起動が要る
参考：Adobe batchPlay、executeAsModal。2026年10月24日に、戻り値のエラー・再描画のタイミング・awaitの案内を再確認しました。
よくある質問：PhotoshopのbatchPlay
batchPlayとは、何ですか？
UXPのスクリプトやプラグインから、Photoshopのコマンドを直接実行する仕組みです。ExtendScriptのexecuteActionにあたり、DOMで書けない操作に使います。
どう書きますか？
require('photoshop').action.batchPlay([記述子], オプション)のように書き、Promiseが返ります。
記述子は_obj（コマンド）・_target（対象）・_ref（対象の指定）で書きます。
_targetは、具体的なもの（レイヤー）から順に、住所と逆の順で並べます。
記事の公式の例では、選んでいるレイヤーを隠す（_objがhide、_refがlayer、_enum: "ordinal"で今選んでいるもの）を紹介しています。
executeAsModalは、なぜ必要ですか？
apiVersion 2のプラグインでPhotoshopの状態を変える場合に必要です。.psjs単体で省略して動いた過去の記録を、プラグインでも省略できる根拠にはしないでください。commandNameは必ず指定し、処理中のプログレスバーの上に表示されます。
batchPlayのコードは、どうやって取りますか？
アクションパネルのメニューの「JavaScript としてコピー」（英語版は Copy As JavaScript）で取れます。
先に［編集］→［環境設定］→［プラグイン］で「開発者モードを有効にする」にチェックを入れ、Photoshopを再起動します。
アクションの手順を選んでこの項目を選ぶと、クリップボードに、executeAsModalとbatchPlayの形のコードが入りました。
開発者モードがオフのときは、メニューにこの項目はありませんでした。
ほかに、コードを調べる方法はありますか？
開発者モードでは、［プラグイン］→［開発］→［アクションコマンドを記録…］で、画面の操作を記述子としてJSONファイルに記録できます。
action.addNotificationListener(['all'], ...) で、実行されたコマンドを見張る方法も公式に載っています（開発者モードのときだけ動く。この記事では確かめていません）。
記述子を調べるプラグインとしてAlchemistがよく使われますが、Jaroslav Berezaさんが作ったもので、Adobeの公式のツールではありません。
batchPlayのオプションには、何がありますか？
synchronousExecutionは、終わるまでスクリプト全体を止めて値を返します（なるべく使わないよう案内されています）。
continueOnErrorは、エラーが出ても続けます（初期値false）。
immediateRedrawは、記述子をすべて実行した後にUIを更新します（初期値false）。
historyStateInfoは、Photoshop 2022で非推奨で、executeAsModalの履歴の機能を使います。
記述子ごとの_options.dialogOptionsでは、ダイアログの出し方を "silent"（初期値）・"dontDisplay"・"display" から選べます。
ExtendScriptのScriptingListenerで取ったコードは、そのまま使えますか？
使えません。ExtendScriptのScriptingListenerで取ったコード（charIDToTypeID・ActionDescriptor）は、そのままではUXPで動きません。UXPでは、同じ操作を「Copy As JavaScript」で取り直すのが近道です。ExtendScript側のコードの読み方は、関連記事「PhotoshopのAction Managerの読み方」で紹介されています。
記事のコードは、実際のPhotoshopで確認されていますか？ 最新はどこで確認しますか？
はい。2026年10月19日〜20日に、Photoshop 2026（27.11.0）とWindows 11 Proで確かめました。
公式の例と「JavaScript としてコピー」で取ったコードを .psjs にして［ファイル］→［スクリプト］→［参照］から実行し、どちらも動きました。
プラグインとして読み込む方法、addNotificationListener、UXP Developer Tool、Mac版は確かめていません。
説明は、AdobeのUXP for Photoshopの公式ドキュメント（developer.adobe.comとGitHubのAdobeDocs/uxp-photoshop、2026年9月29日に確認）にもとづいています。
仕様は更新されるため、最新はAdobe公式の「batchPlay」「executeAsModal」のドキュメントで確認してください。
