ONLYOFFICEデスクトッププラグインの開発とデバッグを有効にする

ONLYOFFICEデスクトップエディターでは、プラグイン開発用のスイッチを別途オンにする必要はありません。プラグインを作成し、.pluginプラグインマネージャーからパッケージをインストールし、--ascdesktop-support-debug-infoデバッグツールが必要なときにデスクトップアプリを起動してください。デスクトップエディターとWebエディターでは読み込み手順が異なるため、以下のデスクトップ固有のワークフローから始めてください。

小さなプラグインプロジェクトを準備する

これらの手順は、Windows、macOS、およびLinux上のONLYOFFICEデスクトップエディターに適用されます。最新のデスクトップインストールと、プレーンテキストファイル用のコードエディターを使用してください。公式ドキュメントでは、手動プラグインインストールと開発者デバッグを別々の機能として扱っています。ローカルプラグインの開発とテストにプラグインマーケットプレイスは必須ではありません。Hello Worldの例は、プラグインの読み込みをより複雑なサービスから分離できるため、最初のチェックとして役立ちます。

1. ソースフォルダを作成する

という名前のフォルダを作成しますhello-world-plugin。config.jsonマニフェストとindex.htmlエントリポイントを追加します。icon.pngマニフェストで画像が参照されている場合は、必要に応じて画像を追加します。ソフトウェアのアップデートによって作業ファイルが上書きされないように、フォルダはインストール済みアプリケーションディレクトリの外に置いてください。

Windowsのエクスプローラーで、hello-world-plugin開発フォルダー内にconfig.json、index.html、icon.pngが表示されている。 — プラグインのマニフェストファイルとそのエントリポイントとなるHTMLファイルを、同じ開発フォルダにまとめて保管してください。ローカルアイコンは任意です。

2. マニフェストを定義し、独自の GUID を生成します。

マニフェストは、ONLYOFFICE に読み込む HTML ファイルと、プラグインを実行できるエディターを指示します。次の例は、ドキュメントエディターをサポートしています。インストール前に、サンプル GUID を新しく生成した UUID に置き換えてください。Windows New-GuidPowerShell またはuuidgenmacOS または Linux で実行し、値をの形式でフォーマットしますasc.{YOUR-UUID}。各プラグインには、それぞれ固有の識別子が必要です。

{
  "name": "Hello World",
  "guid": "asc.{12345678-1234-1234-1234-1234567890AB}",
  "version": "1.0.0",
  "variations": [{
    "url": "index.html",
    "icons": ["icon.png"],
    "isViewer": false,
    "EditorsSupport": ["word"]
  }]
}

有効な JSON を使用してください。末尾にカンマを付けず、括弧を一致させ、参照するエントリポイントまたはアイコンごとに実際のファイルを使用してください。スプレッドシートまたはプレゼンテーションプラグインの場合は、ドキュメントEditorsSupport専用プラグインがどこにでも出現すると想定するのではなく、適切な値を使用してください。構造を公式のHello World クイックスタートと比較してください。

プラグインのconfig.jsonファイルを表示するコードエディタ。ファイルには名前、GUID、バージョン、エントリポイントURL、およびワードエディタのサポート情報が含まれています。 — config.json マニフェストはプラグインを識別し、そのプラグインがサポートするエディタに制限を設けます。

3. エントリポイントを実装する

ではindex.html、ONLYOFFICE プラグイン API ライブラリをロードし、ボタンを追加して、そのボタンがを呼び出すようにしますwindow.Asc.plugin.executeMethod("PasteText", ["Hello World!"])。メーカーのクイックスタート例には、完全な動作 HTML とライブラリ URL が記載されています。初期化や API 構文を推測するよりも、その例をコピーする方が安全です。ファイルを UTF-8 で保存します。オフラインで作業する場合は、オンライン URL からプラグインライブラリやその他のアセットをインポートするページは、それらのリソースをロードする必要があることに注意してください。

「Hello World」ボタンとPasteTextプラグインAPI呼び出しを備えたindex.htmlエントリポイントを表示するコードエディタ。 — エントリポイントファイルには、プラグインの実行時にエディタが使用するインターフェースとJavaScript呼び出しが含まれています。

開発プラグインをインストールして実行します

4. .pluginアーカイブを作成する

ソースフォルダ内のファイルを選択し、ZIPアーカイブに圧縮して、ZIP拡張子を.zipからに変更します.plugin。アーカイブのルートには、とが含まれておりconfig.json、index.html2つ目の囲みhello-world-pluginディレクトリは含まれていない必要があります。Windowsでは、誤ってを作成しないように、ファイルエクスプローラーでファイル名拡張子を有効にしてくださいhello-world.plugin.zip。公式のデスクトップエディターのインストール手順では、マーケットプレイスに接続せずに手動でインストールすることを明示的にサポートしています。

Windowsのエクスプローラーで、プラグインのソースファイルがZIPパッケージ用に選択され、hello-world.pluginアーカイブの横に表示されている。 — ZIPファイルの名前を.plugin拡張子に変更する前に、プラグインフォルダの内容のみをアーカイブしてください。外側のフォルダはアーカイブしないでください。

5. プラグインマネージャーからパッケージをインポートします。

ONLYOFFICEデスクトップエディターで編集可能なドキュメントを開きます。[プラグイン] > [プラグインマネージャー] > [マイプラグイン] > [プラグインを手動でインストール]を選択します。マネージャーの表示はリリースによって異なる場合がありますが、この操作がマニュアルに記載されている手動インストール手順です。これは、マーケットプレイスの開発者URL設定とは異なります。

ONLYOFFICEデスクトップエディターのプラグインマネージャーで、「プラグインを手動でインストール」アクションが表示されている「マイプラグイン」 — ドキュメントを開き、「プラグイン」→「プラグインマネージャー」の順に選択し、「マイプラグイン」に切り替えると、手動インストール画面が表示されます。

6. ファイルを選択し、メニュー項目を確認します。

ファイルダイアログでアーカイブを選択してhello-world.plugin開きます。インストールされたプラグインが「プラグイン」タブに表示されます。表示されない場合は、アプリケーション設定を変更する前に、マニフェスト、GUID、サポートされているエディターの種類、およびアーカイブのルートを確認してください。インストール後にメニューがすぐに更新されない場合は、ドキュメントを再度開いてみてください。

Windowsの「開く」ダイアログで、プラグインファイルフィルターを使用してhello-world.pluginパッケージを選択します。 — ファイル選択ダイアログで.pluginアーカイブを選択してください。元のソースフォルダは選択しないでください。

7. 使い捨てドキュメントでプラグインをテストする

空白のテスト文書を開き、プラグインタブから「Hello World」を起動して、そのボタンをクリックします。文書に「Hello World!」という文字が表示されることを確認してください。これはインストールだけでなく、プラグインのインターフェースが読み込まれ、エディタAPI呼び出しが文書に到達したことも確認します。コンテンツを変更するプラグインは、取り返しのつかないファイルでテストしないでください。

ONLYOFFICEワードプロセッサにHello WorldプラグインパネルとHello Worldテキストがドキュメント内に表示されている — インストールしたプラグインを使い捨てのドキュメント内で実行し、生成されたドキュメントの内容を確認してください。

プラグイン開発のデバッグを有効にする

8. デバッグフラグを付けてデスクトップエディタを再起動します

ONLYOFFICE Desktop Editorsを完全に終了してから、公式デバッグフラグを付けてターミナルからアプリケーションを起動してください。お使いのオペレーティングシステムとインストール場所に応じて、以下のコマンドを使用してください。

Windowsコマンドプロンプト： "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
Linux（標準パッケージの場所）： "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
macOS: "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

上記のWindowsコマンドは、PowerShell構文ではなく、コマンドプロンプトの変数展開を使用しています。PowerShellでは、解決済みのフルパスを指定して実行可能ファイルを呼び出してください。アプリが標準以外の場所にインストールされている場合は、実際の実行可能ファイルのパスを指定してください。また、このフラグをWindowsデスクトップショートカットのターゲットフィールドに追加することもできます。プラットフォームの詳細については、ONLYOFFICEのデスクトップデバッグモードコマンドを参照してください。

ドキュメントを開いたら、編集領域をクリックしてF1 キーを押すか、編集可能なツールバーフィールドを右クリックして [要素を検証]を選択します。DevTools で、プラグインの iframe を選択して、プラグインのインターフェイスコードとログを検査します。渡されたコードはコンテキストcallCommand内で実行されるframeEditorため、必要に応じてフレームを切り替えてください。プラグインのデバッグリファレンスでは、この違いとブレークポイントの使用方法について説明しています。デバッグによってドキュメントの内容や実行時の詳細が明らかになる場合があります。生のログは確認せずに共有しないでください。

プラグインのiframeが選択された開発者ツールコンソールと、初期化ログエントリの例 — デバッグを有効にした後、DevToolsで該当するプラグインのiframeを調べてください。ここに示すコンソールメッセージは例示です。

組み込みプラグインを変更せずに編集・テストサイクルを短縮する

手動インストール後、ONLYOFFICEはプラグインをユーザープロファイルの下にあるGUID名のディレクトリにコピーします。ドキュメントに記載されている場所は、%LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\Windows、~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/macOS、 Linuxです。GUID名のフォルダには、マニフェストで使用されている~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/先頭の文字は含まれません。asc.

変更のたびに新しいアーカイブを作成するのを避けるため、開発者はアプリを閉じ、インストール済みのプラグインフォルダを作業用ソースフォルダへのシンボリックリンクに置き換え、編集後にドキュメントを再度開くことができます。これはオプションであり、正確なリンクコマンドはオペレーティングシステムによって異なります。実行する前に、公式のデスクトップ開発手順に従ってください。バンドルされている/デフォルトのプラグインフォルダを置き換えたり、macOSアプリパッケージを変更したりしないでください。ベンダーは、デフォルトのプラグインを削除するとパッケージの整合性が損なわれ、クラッシュが発生する可能性があると警告しています。

開発環境のセットアップを確認する

ワークフローの準備が整っているかどうかは、次の 3 つのチェックで確認できます。カスタムプラグインが[プラグイン]の下に表示されること、Hello World テストで新しいドキュメントにテキストが挿入されること、デバッグフラグを付けて起動すると DevTools が開くこと。インターフェースが空白の場合やインストールが失敗した場合は、マニフェストが JSON として解析されていること、GUID がで始まることasc.、index.html宣言された相対パスに存在すること、必要なリソースがすべて存在することを確認してください。これらの一般的なエラーについては、公式のプラグインエラーガイドを参照してください。インストールされたプラグインは、実装されているすべての機能が動作するという保証にはなりません。コードを変更するたびに、同じチェックを繰り返してください。