PlaygroundでONLYOFFICE APIをマスターする

2025年11月26日著者：Denis

ONLYOFFICE APIのテストと探索は、小さな実験ごとに完全なプラグインや自動化環境をセットアップしなければならない場合、困難になる可能性があります。ONLYOFFICE Docs APIのPlaygroundは、開発者がプログラム的にドキュメントと対話し、コマンドを試し、APIの動作をリアルタイムで理解できる専用スペースを提供します。

このガイドでは、Playgroundが開発をどのように加速させるか、実用的な例を紹介し、ニーズに適したAPIを選択するためのガイダンスを提供します。

Mastering ONLYOFFICE APIs with Playground

Playgroundが重要な理由

Playgroundは、次のことを望む開発者向けに設計されています:

  • ライブエディター環境でさまざまなAPIを実験する。
  • テキストまたはHTMLコンテンツをプログラム的に挿入および操作する。
  • ドキュメントイベントを監視し、応答する。
  • 完全なプラグインまたはコネクター環境をセットアップすることなく、エッジケース、大きな入力、または特殊文字をテストする。

プラグインまたは自動化ワークフローを構築する前にPlaygroundを使用することで、潜在的な問題を早期に発見し、API制約を理解し、開発プロセスを効率化できます。

利用可能なAPIの理解

Playgroundは3つの主要なAPIをサポートしています:

  1. Office JavaScript API：直接的なドキュメント構築と操作、スクリプト、ドキュメント生成、シンプルな自動化タスクに最適です。
  2. Plugin API：インタラクティブなONLYOFFICEプラグインの構築に使用されます。クリーンなコード実行と複雑な操作のためのasync/awaitパターンをサポートします。
  3. Automation API/Connector：外部システムがドキュメントにアクセスして変更するために使用され、統合と自動化のためのコールバックを使用します。

各APIは異なる目的を果たし、Playgroundを使用すると、それらを並べてテストして、ワークフローに最適なものを確認できます。

Playgroundスニペットの使用開始

以下は、各APIの使用方法を示す実用的な例です。Playgroundエディターにスニペットをコピーして、すぐに実行してください。

基本的なテキスト挿入

目的：3つすべてのAPIを使用して、現在のカーソル位置にテキストを挿入する方法を示します。

使用例：ドキュメントへのシンプルなテキスト挿入またはAPIの動作テスト。

//アプローチ1:Automation API(Connector)を使用

//外部ドキュメントアクセス用のコネクターで作業する場合に使用

connector.executeMethod(
  "PasteText",
  ["Hello from ONLYOFFICE Automation API!"],
  function() {
    console.log("Text inserted using Automation API");
  }
);
//アプローチ2:Editorヘルパーを使用したPlugin API

//プラグインを開発する場合に使用
(async function(){
  await Editor.callMethod("PasteText", ["Hello from ONLYOFFICE Plugin API!"]);
  console.log("Text inserted using Plugin API");
})();

//アプローチ3:Office JavaScript APIを直接使用
//直接的なドキュメント構築と操作に使用
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText("Hello from ONLYOFFICE Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Text inserted using Office JavaScript API");

開発者向けのヒント:メソッドを呼び出した直後に、常にコンソールでAPIレスポンスを確認してください。PasteTextやPasteHtmlのようなシンプルな操作でも、カーソル位置、選択、またはHTML構造によって動作が異なる場合があります。結果をログに記録することで、予期しない動作を早期に発見できます。

書式設定を含むHTMLコンテンツ

目的：見出し、リスト、カスタムスタイルを含むリッチHTMLコンテンツを挿入する方法を示します。

使用例：書式設定されたコンテンツのインポート、リッチテキストの貼り付け、またはセクションの動的生成。

//さまざまな書式設定要素を含むHTML文字列
const htmlContent = `
  <h2 style="color: #2E86C1;">Welcome to ONLYOFFICE</h2>
  <p>This is a <strong>bold text</strong> and this is <em>italic text</em>.</p>
  <ul>
    <li>First bullet point</li>
    <li>Second bullet point with <u>underlined text</u></li>
    <li>Third bullet point</li>
  </ul>
  <p style="color: #28B463;">This paragraph has custom color styling.</p>
`;

//アプローチ1:Automation API(Connector)を使用

//PasteHtmlメソッドは自動的にHTMLをドキュメント要素に変換します

connector.executeMethod(
  "PasteHtml",
  [htmlContent],
  function() {
    console.log("HTML content inserted using Automation API");
  }
);
//アプローチ2:Editorヘルパーを使用したPlugin API

(async function(){
  await Editor.callMethod("PasteHtml", [htmlContent]);
  console.log("HTML content inserted using Plugin API");
})();

ドキュメント変更のイベントリスナー

目的：選択の変更やコンテンツの更新などのドキュメントイベントを監視する方法を示します。

使用例：レスポンシブな機能の構築、ユーザーアクションの追跡、または外部システムとの同期。

connector.attachEvent("onSelectionChanged", function(selectionInfo) {

  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
  //カーソル下の現在の単語を取得
  connector.executeMethod("GetCurrentWord", [], function(currentWord) {
    console.log("Current word:", currentWord);
  });

});

connector.attachEvent("onDocumentContentReady", function() {
  console.log("Document ready");
});
//アプローチ2:Plugin APIを使用

//イベントリスナーはAsc.plugin.attachEvent()で同様に機能します
Asc.plugin.attachEvent("onSelectionChanged", function(selectionInfo) {
  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
});
(async function(){

  let word = await Editor.callMethod("GetCurrentWord");
  console.log("Current word:", word);
})();

大規模でネストされたHTMLコンテンツ

目的：ネストされた要素とテーブルを含む複雑なHTML構造の処理をテストします。

使用例：レポートの生成、書式設定されたドキュメントの移行、または高度なレイアウトの作成。

const complexHtml = `
  <h1 style="color: #2C3E50; text-align: center;">Comprehensive Document Report</h1>
  
  <h2 style="color: #E74C3C;">1. Executive Summary</h2>
  <p>This report demonstrates the ONLYOFFICE API's capability to handle 
  <em>complex HTML structures</em> with <u>multiple levels of nesting</u>.</p>
  
  <h2 style="color: #E74C3C;">2. Key Features</h2>
  <ul>
    <li>Rich Text Formatting: Bold, italic, underline, and colors</li>
    <li>Hierarchical Lists: Nested bullet points
      <ul>
        <li>Sub-item level 1</li>
        <li>Sub-item level 2
          <ul>
            <li>Sub-item level 3 (deeply nested)</li>
          </ul>
        </li>
      </ul>
    </li>
    <li>Tables and Structures: Complex layouts</li>
  </ul>
  
  <h2 style="color: #E74C3C;">3. Data Presentation</h2>
  <table border="1" cellpadding="10" style="width: 100%; border-collapse: collapse;">
    <thead>
      <tr style="background-color: #3498DB; color: white;">
        <th>Feature</th>
        <th>Description</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Text Insertion</td>
        <td>Insert plain and formatted text</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>HTML Import</td>
        <td>Convert HTML to document elements</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>Event Handling</td>
        <td>Monitor document changes</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
    </tbody>
  </table>
  
  <h2 style="color: #E74C3C;">4. Conclusion</h2>
  <p style=" padding: 15px;">
    The ONLYOFFICE API successfully handles 
    <span style="background-color: #F39C12; color: white; padding: 2px 5px;">
    complex HTML content</span> with multiple levels of nesting.
  </p>
`;
//アプローチ1:Automation API(Connector)を使用
connector.executeMethod(
  "PasteHtml",
  [complexHtml],
  function() {
    console.log("Complex HTML inserted (" + complexHtml.length + " characters)");
  }
);
//アプローチ2:Editorヘルパーを使用したPlugin API

(async function(){
  await Editor.callMethod("PasteHtml", [complexHtml]);
  console.log("Complex HTML inserted using Plugin API");
})();

エッジケースを含むシンプルな最初のAPI呼び出し

目的：初心者にAPIの使用法、一般的なエッジケース、エラー処理パターンを紹介します。

使用例：Office JavaScript API、Plugin API、およびAutomation APIの基本を学習します。

//アプローチ1:Office JavaScript API
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText(" Hello from Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Content created with Office JavaScript API");

//エッジケース1:空またはnullテキストの処理
var oParagraph2 = Api.CreateParagraph();
var textToInsert = "";//空の文字列
if (textToInsert && textToInsert.trim().length > 0) {
  oParagraph2.AddText(textToInsert);
} else {
  oParagraph2.AddText("(Empty text was provided)");
}
oDocument.InsertContent([oParagraph2]);

//エッジケース2:特殊文字とUnicodeの操作
var oParagraph3 = Api.CreateParagraph();
oParagraph3.AddText("Special chars: © ® ™ € £ ¥ • · « » — 'quotes' 中文 العربية");
oDocument.InsertContent([oParagraph3]);

//エッジケース3:混合書式設定でコンテンツを作成
var oParagraph4 = Api.CreateParagraph();
var oRun1 = Api.CreateRun();
oRun1.AddText("This is bold ");
oRun1.SetBold(true);
oParagraph4.AddElement(oRun1);
var oRun2 = Api.CreateRun();
oRun2.AddText("and this is italic ");
oRun2.SetItalic(true);
oParagraph4.AddElement(oRun2);
var oRun3 = Api.CreateRun();
oRun3.AddText("and this is colored.");
oRun3.SetColor(220, 20, 60, false);//クリムゾン色
oParagraph4.AddElement(oRun3);
oDocument.InsertContent([oParagraph4]);
//エッジケース4:操作前にドキュメントが存在するか確認
if (oDocument) {
  var oParagraph5 = Api.CreateParagraph();
  oParagraph5.AddText("Document validation: OK");
  oDocument.InsertContent([oParagraph5]);
  console.log("Document exists and is accessible");
} else {
  console.log("ERROR: Document not accessible");
}
//アプローチ2:Editorヘルパーを使用したPlugin API(プラグイン開発用)
//エラー処理付きのasync/awaitパターンを使用
(async function(){
  try {
    //エディターバージョンを取得
    let version = await Editor.callMethod("GetVersion");
    console.log("Editor version:", version);

    //エッジケース1:エラー処理付きでHTMLを挿入
    await Editor.callMethod("PasteHtml", [
      "<p><b>Hello</b> from <i>Plugin API</i>!</p>"
    ]);
    console.log("Content inserted with Plugin API");
   
    //エッジケース2:メソッドがundefinedまたはnullを返すか確認
    let selectedText = await Editor.callMethod("GetSelectedText");
    if (selectedText) {
      console.log("Selected text:", selectedText);
    } else {
      console.log("No text selected or selection is empty");
    }
    //エッジケース3:Plugin APIでの特殊文字の処理
    await Editor.callMethod("PasteText", [
      "Special: © 2024 | €100 | 中文"
    ]);

    //エッジケース4:順次実行される複数の非同期操作
    await Editor.callMethod("PasteText", ["Line 1 "]);
    await Editor.callMethod("PasteText", ["Line 2 "]);
    await Editor.callMethod("PasteText", ["Line 3"]);
    console.log("Multiple operations completed");
  } catch (error) {
    console.log("ERROR in Plugin API:", error.message || error);
  }
})();

開発者向けのヒント：async/awaitでPlugin APIを使用する場合は、呼び出しをtry/catchブロックでラップしてください。これにより、未定義の選択やサポートされていないコンテンツなどのエラーがスクリプトを中断することを防ぎ、デバッグのための情報的なコンソールメッセージを提供できます。

//アプローチ3:Automation API(Connector-外部アクセス用)

//エラー処理付きのコールバックを使用

//エッジケース1:使用前にコネクターが存在するか確認

if (typeof connector !== 'undefined' && connector) {

  //コールバックエラー処理付きの基本的なテキスト挿入
  connector.executeMethod(
    "PasteText",
    ["Hello from Automation API!"],
    function(result) {
      if (result !== undefined) {
        console.log("Content inserted with Automation API");
      } else {
        console.log("Insert may have failed, result is undefined");
      }

      //エッジケース2:エラーチェック付きで複数の操作を連鎖
      connector.executeMethod("GetCurrentWord", [], function(word) {
        if (word && word.length > 0) {
          console.log("Current word:", word);
        } else {
          console.log("No word at cursor position");
        }
      });
    }
  );

  //エッジケース3:空または無効なHTMLの処理

  var htmlToInsert = "<p>Test</p>";
  if (htmlToInsert && htmlToInsert.includes("<")) {
    connector.executeMethod(
      "PasteHtml",
      [htmlToInsert],
      function() {
        console.log("HTML inserted successfully");
      }
    );
  } else {
    console.log("Invalid HTML content");
  }

  //エッジケース4:遅い操作のタイムアウト処理

  var operationTimeout = setTimeout(function() {

    console.log("WARNING: Operation taking longer than expected");

  }, 5000);
  connector.executeMethod(
    "PasteText",
    ["Async operation test"],
    function() {
      clearTimeout(operationTimeout);

      console.log("Operation completed in time");
    }
  );

} else {
  console.log("ERROR: Connector is not available");
}

使用手順とベストプラクティス

  • 競合を避けるため、スニペットを個別に実行してください。
  • ブラウザコンソールを使用して実行ログを表示し、結果をデバッグします。
  • 適切なAPIを選択してください：

ゼロからドキュメントを構築 → Office JavaScript API、

プラグインを開発 → Plugin API、

外部アプリと統合 → Automation API(Connector)。

  • 書式設定、HTML、イベントを実験して、APIの動作を徹底的に理解しましょう。

推奨される学習パス

  1. シンプルな最初のAPI呼び出しから始めて、アプローチを比較します。
  2. 基本的なテキスト挿入に進み、API間の違いを理解します。
  3. 書式設定とリッチコンテンツのためにHTML挿入をテストします。
  4. Automation APIとPlugin APIのイベントリスナーを探索します。
  5. 大規模でネストされた構造を処理するための複雑なHTMLコンテンツに進みます。

まとめ

ONLYOFFICE Playgroundは、API学習、テスト、プラグイン開発を加速するための強力なツールです。インタラクティブでサンドボックス化された環境を提供することで、開発者は安全に実験し、APIの動作を深く理解し、より効率的に堅牢なプラグインと自動化ワークフローを構築できます。

お役立ちリンク

Playgroundを始める

独自のプラグインを作成する方法

ONLYOFFICEのGitHub

ONLYOFFICEに貢献する

ONLYOFFICEの無料アカウントを登録する

オンラインでドキュメント、スプレッドシート、スライド、フォーム、PDFファイルの閲覧、編集、共同作業