バージョン9.4のONLYOFFICEでは、統合、カスタムプラグイン、およびスプレッドシート自動化のための大幅なAPI改善が導入されました。この記事では、ONLYOFFICE Docs API、Plugins and Macros API、Office JavaScript APIの主要な更新について説明し、これらが開発者にとって何を意味するのかを解説していきます。
ONLYOFFICE Docs API 9.4
クロアチア語のサポート
クロアチア語（hr）がサポートされているインターフェース言語のリストに追加されました。クロアチア語を話すユーザーのためのローカライズされたアプリケーションを構築している場合、この言語を言語設定に簡単に含めることができます。
onStartFillingイベントにおける役割とユーザーデータ
onStartFillingイベントには、役割とユーザー情報を含むrolesパラメータが新たに追加されました。これにより、ユーザーを担当しているフィールドにルーティングしたり、フォームを記入しているユーザーの役割に基づいて条件付きロジックをトリガーしたりするなど、役割に配慮したフォーム記入体験を簡単に構築できます。
function onStartFilling(event) {
const roles = event.data;
console.log("Roles:", roles);
}
const config = {
// ...
events: {
onStartFilling,
},
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);
destroyEditorにおけるメモリリークの修正
destroyEditorメソッドにおけるメモリリークが修正されました。以前は、destroyEditorを呼び出しても、割り当てられたリソースが完全にクリーンアップされていませんでした。
アプリケーションがSPA設定やドキュメントプレビューのワークフローなどでエディタインスタンスを頻繁に作成・破棄する場合、この修正により統合のメモリフットプリントが時間とともに直接改善されます。
削除されたフィールド
廃止されたeditorConfig.customization.commentAuthorOnlyフィールドが削除されました。このパラメータを参照している統合がまだある場合、予期しない動作を避けるために削除する時期です。
プラグインコマンドのログ記録によるデバッグの容易化
プラグイン開発者にとって最も実用的な追加の1つは、プラグインコマンドのログ記録です。ブラウザのコンソールでプラグインコマンドのデバッグ出力を有効にします。
プラグインの動作をデバッグするのに時間を費やしたことがある場合、この機能はその摩擦を大幅に軽減します。独自のログを装備することなく、プラグインの実行フローを直接確認できます。
特定のプラグインを読み込み時にブロック
新しいeditorConfig.plugins.disableパラメータにより、エディタの初期化時に特定のプラグインの読み込みを防ぐことができるようになりました。
制御された環境にエディタを埋め込む際に、ユーザーに関連する機能のみを提供するために役立ちます。プラグインファイル自体を修正することなく、設定レベルでプラグインの表面を管理できるよりクリーンなアプローチです。
ONLYOFFICE Plugins and Macros API 9.4
新しいカーソル制御メソッド
ドキュメントAPI用のwindow.Asc.plugin.executeMethodに2つの新しいメソッドが追加されました。
- MoveCursorToField：特定のフォームフィールドにカーソルを移動します。
- MoveCursorOutsideField：現在のフィールドの外側の位置にカーソルを移動します。
Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);
Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);
これらは、ユーザーをフォームの完了へと導いたり、ドキュメント内でフィールドごとのナビゲーションを自動化したりするプラグインに特に便利です。ユーザーの操作に依存せずにフィールドを進められるため、プラグインがプログラム的にカーソルの位置を制御できます。
StartActionおよびEndAction制御の改善
StartActionメソッドは、2つの新しいパラメータを受け入れます。
| パラメータ | 説明 |
|---|---|
lockScroll |
マクロ実行中のスクロールをロック |
keepSelection |
ユーザーの選択を保持 |
EndActionメソッドにはscrollToTargetとcancelが追加されました。
これらにより、マクロ実行中のエディタ状態をプラグインがより細かく制御できるようになります。ユーザーの選択を保持したり、自動操作中に不要なスクロールを防いだり、アクションシーケンスをスムーズにキャンセルしたりすることができ、すべてがより安定した予測可能なプラグイン体験に寄与します。
🔗 Plugins and Macros APIの完全な変更履歴を確認する
Office JavaScript API 9.4
これは9.4リリースの中で最も広範な部分です。Office JavaScript APIは、ドキュメント操作、スプレッドシートデータ管理、フォームコントロールなどの新しい機能を獲得しました。
ドキュメントのマージ
新しいApi/MergeDocumentsメソッドがドキュメントAPIに追加されました。これにより、複数のドキュメントを1つに結合できます。レポート生成、契約書作成、バッチドキュメント処理などの自動化シナリオにおいて頻繁に要求されていた機能です。
すべてのエディタに対応した統一カラーAPI
Api/Colorメソッドは、ドキュメント・スプレッドシート・プレゼンテーション・PDF APIのすべてで使用可能になりました。
すべての4つのエディタタイプで一貫したカラーインターフェースを持つことで、さまざまなドキュメント形式にわたってスタイルを適用するコードが簡素化されます。形式ごとに色の扱いロジックを書き分ける必要がなくなります。
署名フォームのサポート
バージョン9.4では、ドキュメントAPIとフォームAPIの両方で利用できるApiSignatureFormクラスが導入されました。GetValueとSetValueメソッドにより、署名フィールドデータの読み取りと書き込みが可能です。
// ApiSignatureFormのGetValueメソッドは、フォーム内に保存された署名画像データを返します。
// 署名フォームを作成し、ドキュメントに追加してその現在の値を読む。
let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({
"key": "Signature",
"tip": "ここにサインしてください",
"required": true,
"placeholder": "署名"
});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("署名フォームの値：" + value);
doc.Push(paragraph);
また、新しいApi/CreateSignatureFormメソッドを使用することで、手動挿入に頼ることなく、コードを通じて署名フォームフィールドをゼロから作成できます。
フォーム状態の検出
ApiFormBase/IsFilledメソッドがドキュメントAPIとフォームAPIの両方に追加され、特定のフォームフィールドが記入されたかどうかを確認できるようになりました。バリデーションや提出ロジックにとって重要な追加機能です。フィールドコンテンツを直接解析せずに、フォームの完成状態を検査できます。
フォームハイライト検査
2つの新しいメソッドがドキュメントAPIとフォームAPIで利用可能です。
-
ApiDocument/GetFormsHighlight：フォームフィールドに適用される現在のハイライト設定を取得 -
ApiDocument/GetControlsHighlight：コンテンツコントロールに適用されるハイライト設定を取得
統合がフォーム表示設定を管理する場合や、外部UI要素にハイライト状態を反映する必要がある場合に、以前はなかった読み取りアクセスを提供します。
広範なスプレッドシートリストオブジェクトAPI
これは9.4で最も機能が充実した追加機能です。スプレッドシートAPIには、構造化されたテーブルオブジェクト（リストオブジェクト）を操作するためのフルApiListObjectクラスが追加されました。
主な機能：
| 機能 | メソッド/クラス |
|---|---|
| リストオブジェクトの作成と取得 |
ApiWorksheet/AddListObject、ApiWorksheet/GetListObjects
|
| テーブルプロパティの読み書き | 名前、表示名、代替テキスト、スタイル、ヘッダー、合計、自動フィルターなど |
| テーブル範囲へのアクセス | ヘッダー行、データ本体範囲、合計行 |
| 列と行の管理 |
ApiListColumn、ApiListRow（名前・インデックス・範囲・合計計算・削除） |
| 並べ替えのサポート |
ApiSort、ApiSortFields、ApiSortField（向き・大文字小文字・条件・優先順位） |
統合がスプレッドシート内での構造化データ管理を含む場合（データのインポート、動的なテーブル作成、レポート生成など）、この追加機能はユーザーに手作業でテーブルを操作させることなく、できることを大幅に拡大します。
新しいスプレッドシートフィルと数式メソッド
4つの方向へのフィルメソッドがApiRangeに追加されました。
FillDownFillUpFillRightFillLeft
これらはユーザーが手動でトリガーするスプレッドシートフィルの動作をプログラム的に実行できます。新しいApiRange/SetFormulaメソッドと組み合わせることで、数式駆動の範囲を動的に構築する自動化が実現できます。生成されたレポート、テンプレート化されたスプレッドシート、データ入力の自動化に役立ちます。
また、Api/GetDefNamesメソッドもスプレッドシートAPIに追加されており、ワークブック内の定義された名前（名前付き範囲）にアクセスできます。
テキストフォームのフォーマット制御
ApiTextFormクラスにドキュメントAPIとフォームAPIの両方で4つの新しいメソッドが追加されました。
| メソッド | 説明 |
|---|---|
GetFormat / SetFormat
|
テキストフィールドにフォーマットマスクを読み取り・適用 |
GetAllowedSymbols / SetAllowedSymbols
|
ユーザーが入力できる文字を制御 |
日付フォーマットの強制、数値文字への入力制限、電話番号やIDのカスタムマスクの適用など、バリデーションされたデータ入力フォームを作成するために不可欠な機能です。
段落プロパティの検査
ApiParaPrに対して一連のGetメソッドが追加されました。
境界プロパティ： 上、左、右、下、間
ページネーション：
GetKeepLinesGetKeepNextGetPageBreakBeforeGetWidowControl
その他：
-
GetNumPr（リスト） -
GetTabs（タブ） -
GetContextualSpacing（間隔）
これらは長年のギャップを埋めます。これらのプロパティの多くはプログラム的に設定できましたが、取得は常に可能ではありませんでした。作業回避策に依存することなく段落のフォーマットを検査できるため、ドキュメント分析ツールやテンプレート検証スクリプトに特に役立ちます。
コンテンツコントロールの色
ドキュメントAPIのApiInlineLvlSdtクラスは、SetColorとGetColorメソッドをサポートしています。インラインコンテンツコントロールのハイライト色を設定および読み取ることができ、視覚的に異なるフォーム体験を構築したり、状態に基づいてコントロールをハイライトする際に役立ちます。
// ドキュメント内のインラインコンテンツコントロールの色を変更する
// 特定のRGB色を適用して、ドキュメント内のコンテンツコントロールを視覚的に区別します。
let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("これは青いタグ色のインラインテキストコンテンツコントロールです。");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);