ONLYOFFICEプラグインのデバッグ：実践ガイド

ONLYOFFICE プラグインの開発とデバッグはときに難しく感じることがありますが、適切なツールと手順を使えば大幅に簡単になります。本ガイドでは、さまざまな環境でプラグインを効果的にデバッグするためのステップをご紹介します。

ONLYOFFICEプラグインについて

ONLYOFFICEでは、プラグインによってエディターの機能を拡張できます。プラグインはHTMLページで構成され、エディター内部に埋め込まれ、APIを利用してエディターと連携します。プラグインの構造理解とデバッグ方法の把握は、開発成功の鍵となります。

プラグイン構造

一般的なONLYOFFICEプラグインは以下のファイルで構成されます。

• config.json：プラグインに関する基本情報を定義する設定ファイル。
• index.html：プラグインのメインHTMLページ。
• scripts：プラグインのロジックを実現するJavaScriptファイル群。

詳細な構造とサンプルはこちらから確認できます。

Web版エディターでのデバッグ

Web版ONLYOFFICEエディターでプラグインをデバッグするには、以下の手順に従います。

• スクリプト内に debugger コマンドを追加します。

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• F12 を押してブラウザの開発者ツールを開く。
• ONLYOFFICE エディターの「プラグイン」タブからプラグインを実行する。

注意：開発者ツールが開いていない場合、debugger コマンドは無視されます。詳細はこちらをご覧ください。

デスクトップエディターでのデバッグ

デスクトップ版 ONLYOFFICE エディターでデバッグするには、次の手順を使用します：

• –ascdesktop-support-debug-info フラグを付けてエディターを起動します。

• このフラグはデバッグに有益な追加情報の表示を有効にします。
• Web 版同様、コード内の任意の箇所に debugger; を挿入します。

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• F1 を押すとコンソールが開き、プラグインを実行できます。

指定フラグでエディターを起動した後、プラグインを開いてコード実行をトレースできます。

OS ごとの詳細手順はこちらをご覧ください。

スコープ管理

ONLYOFFICE プラグイン開発では、プラグインの UI（HTML 側）と、Document Builder API を実行するエディター側のスコープが異なるため、データの受け渡し方法を理解することが重要です。

よくある問題は、この 2 つのスコープ間のデータ受け渡しが正しく行われないことです。ONLYOFFICE では、Asc.scope オブジェクトを使うことで解決できます。

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        let text = "Hello from the plugin!";
        Asc.scope.dataForEditor = text;

        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText(Asc.scope.dataForEditor);
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

Asc.scopeを正しく使うことで複雑なプラグインでも安定してデータを連携できます。

よくある問題とトラブルシューティング

debugger が動作しない

• ブラウザ開発者ツール（F12）を先に開いているか確認。
• DevTools が開いていないと debugger は無視されます。

プラグインが読み込まれない / 表示されない

• config.json が正しい JSON 形式か確認。
• name、guid、baseUrl など必要項目が揃っているか確認。
• ブラウザコンソールでエラーを確認。
• プラグインが Plugins タブに正しくインストールされているか確認。
• .plugin ファイルを ZIP で手動インストール、または Asc.editor.installDeveloperPlugin() を使用。

CORS エラー

• ONLYOFFICE Docsをインストール。
• Web エディターでデバッグする場合、プラグインフォルダー内で http-server を起動。
• または installDeveloperPlugin() の config.json パスを調整。

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

ファイルを変更しても古いコードが実行される（Web）

• ローカルのプラグインファイルを変更した場合、ページとキャッシュをリロードする必要があります。
• ブラウザの更新ボタンを右クリック → 「キャッシュの消去とハード再読み込み」を選択。

デバッグは、ONLYOFFICE プラグイン開発を安定させるうえで欠かせません。ここで解説した手順を活用することで、問題を素早く特定し、コード品質とプラグイン性能を向上できます。

質問・提案・プラグインのアイデアがあれば、ぜひご連絡ください。あなたの取り組みを紹介できることを楽しみにしています。