Adobe Photoshopの新しいスクリプト形式「PSJSファイル(.psjs)」の使い方を解説します。JavaScriptの基本がわかる方に向けて、最初のスクリプトを実行するところから、ドキュメントを操作して結果をファイルに保存するところまでを順番に紹介します。
Photoshopには、JavaScriptのファイルを1つ選ぶだけで処理を流せる「UXPスクリプト」という仕組みがあります。ファイルの拡張子は.psjsです。
効率化ツールを開発する途中で、Photoshopの挙動を確認する診断スクリプトをいくつも.psjsで書きました。プラグインを作るほどではない「ちょっと確認したい・ちょっと自動化したい」に、ちょうどよいツールです。

目次
- PSJSファイルとは
- PSJSファイルの実行に必要なもの
- 手順1: PSJSファイルを作成して実行する
- 手順2: ドキュメントを作成してレイヤーを追加する
- 手順3: DOMにない操作をbatchPlayで実行する
- 手順4: 結果をファイルに保存する
- 手順5: 後片づけとエラー処理
- PSJSファイルを書くときの注意点
- PSJSファイルでできること・できないこと
- PSJSファイルをデバッグする方法
- ExtendScript(.jsx)との違い
- まとめ
PSJSファイルとは
- PhotoshopがUXP(新しい拡張の仕組み)で実行する、JavaScriptの1枚のファイル。
- 昔からあるExtendScript(
.jsx)の後継にあたる。ExtendScriptは古いJavaScript(ES3)だが、UXPは新しい書き方(const・async/await・アロー関数など)が使える。 - プラグインと違って、
manifest.jsonもパネルも要らない。テキストファイルを1つ作るだけ。 - 書いたコードは、あとでプラグインにそのまま持っていける。
PSJSファイルの実行に必要なもの
| アプリ | 条件 |
|---|---|
| Photoshop | 23.5以降(Adobeの公式ドキュメントによる)。この記事のコードの元にしたスクリプトは、Photoshop 2025(26.1.0)・Windowsで動かしたもの |
| テキストエディタ | 何でもよい。文字コードはUTF-8で保存する |
| UXP Developer Tools | デバッグしたいときだけ。1.6以降。Creative Cloudのアプリから入れられる |
手順1: PSJSファイルを作成して実行する
テキストエディタで、次の内容のファイルを作り、hello.psjsという名前で保存します。
|
1 2 3 |
const { app } = require('photoshop'); await app.showAlert('こんにちは。Photoshop ' + require('uxp').host.version + ' です'); |
なお、1行目は空行にしてあります。公式ドキュメントのサンプルもそうなっていて、Photoshopがスクリプトの中身を包んで実行するための都合、と説明されています。
PSJSファイルを実行する3つの方法

- メニューから: [ファイル] > [スクリプト] > [参照…]で
.psjsを選ぶ。 - ドラッグ&ドロップ:
.psjsをPhotoshopのウィンドウの、ドキュメントが開いていない場所に落とす(MacはDockのアイコンでもよい)。 - アクションから: スクリプトの実行をアクションに記録して、アクションを再生する。
アラートが出れば成功です。
手順2: ドキュメントを作成してレイヤーを追加する
Photoshopを操作するコードは、require('photoshop')から取り出したappを起点に書きます。また、ほとんどの操作は非同期です。そのため、awaitを付けます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
const { app, core, constants } = require('photoshop'); async function main() { let doc = null; await core.executeAsModal(async () => { // 200×200 の透明なドキュメントを作る doc = await app.documents.add({ width: 200, height: 200, resolution: 72, mode: 'RGBColorMode', fill: 'transparent' }); // ピクセルレイヤーを 1 枚足す await doc.createPixelLayer({ name: 'はじめてのレイヤー', opacity: 100, blendMode: constants.BlendMode.NORMAL }); }, { commandName: 'ドキュメントを作る' }); await app.showAlert('ドキュメント「' + doc.name + '」を作りました'); } main(); |
executeAsModalについて
ドキュメントやPhotoshopの状態を変える操作は、core.executeAsModalの中で呼ぶ、というのがUXPの決まりです。commandNameは、処理が長引いたときに出る進行状況のバーに表示される名前です。
公式ドキュメントには「スクリプトはexecuteAsModalに似た状態で実行される」とあります。ただ、私が書いたスクリプトでは、上のように自分でexecuteAsModalに包む書き方で動かしました。ピクセルを読むimaging.getPixelsは、この中でしか呼べませんでした。プラグインに持っていくときもそのまま使えるので、包んでおくのが無難です。
手順3: DOMにない操作をbatchPlayで実行する
UXPのDOM(doc.createPixelLayerのような分かりやすい関数)には、まだ無い操作があります。たとえば「選択範囲を色で塗る」はDOMに見当たりませんでした。そういうときは、Photoshopの内部の命令をそのまま送るbatchPlayを使います。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
const { app, core, action, constants } = require('photoshop'); // 選択範囲を色で塗る(DOM に無いので batchPlay) const fillSelection = (r, g, b) => action.batchPlay([{ _obj: 'fill', using: { _enum: 'fillContents', _value: 'color' }, color: { _obj: 'RGBColor', red: r, grain: g, blue: b }, opacity: { _unit: 'percentUnit', _value: 100 }, mode: { _enum: 'blendMode', _value: 'normal' }, }], { synchronousExecution: false }); async function main() { await core.executeAsModal(async () => { const doc = await app.documents.add({ width: 200, height: 200, resolution: 72, mode: 'RGBColorMode', fill: 'transparent' }); await doc.createPixelLayer({ name: '赤い四角', opacity: 100, blendMode: constants.BlendMode.NORMAL }); // 四角く選択して、赤で塗って、選択を外す await doc.selection.selectRectangle({ left: 50, top: 50, right: 150, bottom: 150 }, constants.SelectionType.REPLACE, 0, false); await fillSelection(255, 0, 0); await doc.selection.deselect(); }, { commandName: '赤い四角を描く' }); } main(); |
このスクリプトを実行すると、次のようなドキュメントが作られます。

なお、grainは書き間違いではありません。batchPlayでは、緑のチャンネルをこの名前で指定します。
batchPlayの命令の形は、Photoshopで操作を記録して調べるのが近道です([プラグイン] > [開発] > [アクションコマンドを記録…])。
手順4: 結果をファイルに保存する
ただし、スクリプトは、好きな場所に勝手にファイルを書くことはできません。使えるのは次の2つです。
- 一時フォルダ:
getTemporaryFolder()で取れる、スクリプト用の作業場所 - ファイルを選ぶダイアログ: 利用者に保存先を選んでもらう
例えば、診断の結果を残すだけなら、一時フォルダが手軽です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
const { app } = require('photoshop'); const uxp = require('uxp'); // 一時フォルダにテキストを書いて、書いた場所(フルパス)を返す async function writeFile(name, text) { const folder = await uxp.storage.localFileSystem.getTemporaryFolder(); const file = await folder.createFile(name, { overwrite: true }); await file.write(text); return file.nativePath; } async function main() { const info = { photoshop: uxp.host.version, documents: app.documents.map((d) => d.name), date: new Date().toISOString(), }; const where = await writeFile('psjs-sample.json', JSON.stringify(info, null, 2)); await app.showAlert('保存しました:\n' + where); } main(); |
一時フォルダの場所は分かりにくいので、最後のアラートにnativePathを出すのがおすすめです。どこに保存されたかを毎回探さずに済みます。
手順5: 後片づけとエラー処理
スクリプトでドキュメントを作ったら、最後に閉じます。また、途中でエラーになっても閉じるように、try / finallyで囲みます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
async function main() { let doc = null; try { await core.executeAsModal(async () => { doc = await app.documents.add({ width: 200, height: 200, resolution: 72, mode: 'RGBColorMode', fill: 'transparent' }); // …ここで作業… }, { commandName: '作業' }); } catch (e) { await app.showAlert('エラー: ' + (e && e.message ? e.message : e)); } finally { if (doc) { try { await core.executeAsModal(async () => { await doc.closeWithoutSaving(); }, { commandName: '閉じる' }); } catch (e) { /* 閉じられなくてもよい */ } } } } |
利用者が開いているドキュメントには触らない、作ったドキュメントは保存せずに閉じる、の2つを守ると、安心して配れるスクリプトになります。
PSJSファイルを書くときの注意点
実際に診断スクリプトを書いていて、つまずいた点です。Photoshop 2025(26.1.0)・Windowsでの話です。
- Photoshopのバージョンは
app.versionでは取れなかった。require('uxp').host.versionで取れました。 - 1回の
executeAsModalに全部を詰め込むと、止まったように見えた。 18個の処理を1回の中で流したら、最初の処理のあと6分以上進まないことが2回ありました。処理ごとに短いexecuteAsModalに分けたら、最後まで流れました。 - 途中経過はファイルに書く。 止まったのか動いているのか、画面からは分かりません。進み具合を1行ずつ一時フォルダのファイルに書き足すようにしたら、どこで止まったかが分かるようになりました。
- 時間切れを自分で付ける。
Promise.raceで30秒の時間切れを付けると、1つの処理が固まっても次へ進めます。 - ピクセルを読んだら
dispose()。imaging.getPixelsで受け取ったimageDataは、使い終わったら自分で解放します。 awaitを忘れない。 付け忘れると、処理が終わる前に次へ進んだり、スクリプトが先に終わってダイアログが出なかったりします。

2〜4をまとめると、こういう形になります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
const withTimeout = (p, ms, label) => Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error('時間切れ: ' + label)), ms))]); const progress = []; async function note(msg) { progress.push(msg); await writeFile('progress.txt', progress.join('\n')); // 手順4の writeFile } // 処理ごとに、短い executeAsModal に分ける for (const step of steps) { await note('開始: ' + step.name); try { await withTimeout(core.executeAsModal(step.run, { commandName: step.name }), 30000, step.name); await note('完了: ' + step.name); } catch (e) { await note('失敗: ' + step.name + ' ' + (e && e.message ? e.message : e)); } } |
PSJSファイルでできること・できないこと
Adobeの公式ドキュメント(UXP Scriptingの「How it works」)に書かれている内容です。ドキュメントは初期のバージョンをもとにしているので、新しいPhotoshopでは変わっているかもしれません。
| できること | 補足 |
|---|---|
| Photoshopの操作 | UXPのDOMとbatchPlay |
| ダイアログを出す | スクリプトが終わると消える |
| 一時フォルダの読み書き | getTemporaryFolder()で取れる場所 |
| ファイルを選ぶダイアログでの読み書き | 利用者が選んだファイルだけ |
| フォントの一覧の読み取り | |
| クリップボードの読み書き |
| できないこと | 補足 |
|---|---|
| パネルを出す | 出せるのはダイアログだけ |
| ネットワーク通信 | スクリプトでは使えない |
| ほかのプログラムの起動 | 使えない |
| 好きな場所へのファイルの読み書き | 一時フォルダと、ファイルを選ぶダイアログだけ |
| スクリプトから別のスクリプトを呼ぶ | できない。同時に動くのは1本だけ |
| 権限の追加 | プラグインはmanifest.jsonで宣言するが、スクリプトはPhotoshopが決めた範囲だけ |
つまり、これで足りなくなったら、プラグインにする合図です。
PSJSファイルをデバッグする方法
console.logの出力を見たり、1行ずつ止めながら動かしたりするには、UXP Developer Toolsを使います。
- UXP Developer Toolsを起動する。
- Photoshopを起動する。「Connected Applications」にPhotoshopが出る。
- そのカードの「Debug Script」を押し、
.psjsを選ぶ。 - デバッガーが開く。ブレークポイントを置いて、1行ずつ進められる。
ExtendScript(.jsx)との違い
| ExtendScript(.jsx) | UXPスクリプト(.psjs) | |
|---|---|---|
| JavaScript | 古い書き方(ES3) | 新しい書き方(ES6以降) |
| 呼び出し | 同期(終わるまで画面が止まる) | 非同期(awaitで待つ) |
| Photoshopの操作 | 独自のDOM・ActionManager | UXPのDOM・batchPlay |
| ピクセルの読み取り | 手軽な方法が無い | imaging.getPixelsで読める |
| プラグインへの持ち込み | 書き直しが要る | そのまま使える |
なお、ExtendScript(.jsx)で書いたスクリプトの例は「Photoshopでテキストレイヤー名の自動更新を復元する方法」で紹介しています。また、最初の一歩はAdobeのQuickstart Guideも参考になります。
まとめ
.psjsは、テキストファイル1つでPhotoshopを動かせる、いちばん手軽なUXPの入り口です。- [ファイル] > [スクリプト] > [参照…]か、ウィンドウへのドロップで動きます。
- ドキュメントを変える操作は
executeAsModalに包み、DOMに無い操作はbatchPlayで補います。 - 結果は一時フォルダに書き、最後のアラートで保存先を知らせると、使う人が迷いません。
- 長い処理は短く分け、途中経過をファイルに残し、時間切れを付けておくと、止まったときに原因を追えます。
Note: この記事の内容について、次の点に注意してください。
- この記事のコードは、Photoshop 2025(26.1.0)・Windowsで動かした診断スクリプトの書き方を元にしています。ほかのバージョンやMacでは確認していません。
- 仕様と制限は、Adobeの公式ドキュメント(UXP for Adobe Photoshopの「UXP Scripting」)で最新の内容を確認してください。
[…] 詳しくは「Photoshop スクリプト: PSJSファイル(UXPスクリプト)の使い方」で解説しています。 […]