ONLYOFFICEバージョン8.0を使いこなす：Document Builder APIの新フォームメソッドを公開

<a href="https://www.onlyoffice.com/blog/ja/2024/02/documents-android-8-0?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener">バージョン8.0</a>の発表に伴い、一連の新しいDocument Builder APIメソッドが導入されました。この記事では、これらのメソッドのうち2つをピックアップし、それらを2つの新しいONLYOFFICEマクロに組み込み、フォームテンプレートでの作業を効率化する方法をご紹介します。

<img class="aligncenter wp-image-146283" src="https://static-blog.onlyoffice.com/wp-content/uploads/2024/02/12143559/new-methods.png" alt="Mastering ONLYOFFICE version 8.0: Unveiling new Document Builder API form methods" width="736" height="372" />
<!--more-->
<h2><strong>新しいメソッドについて</strong></h2>
<ul>
 	<li><strong>GetFormsData</strong></li>
</ul>
<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Word/ApiDocument/Methods/GetFormsData.md" target="_blank" rel="noopener"><em>GetFormsData</em></a>メソッドは、ドキュメント内のすべての<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Enumerations/FormData.md" target="_blank" rel="noopener">フォーム要素</a>のフォームデータを含む配列を取得します。
<pre class="theme:github font:monospace lang:js decode:true">expression.GetFormsData();</pre>
<em>expression</em>は<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Word/ApiDocument/ApiDocument.md" target="_blank" rel="noopener">ApiDocument</a>クラスを表す変数です。

このメソッドを利用することで、ドキュメント内のフォームから対象となるデータを取得することができ、フォームの型やプロパティに基づいて動的にフォームを変更することができます。
<ul>
 	<li><strong>SetFormsData</strong></li>
</ul>
先のメソッドとは逆に、<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Word/ApiDocument/Methods/SetFormsData.md" target="_blank" rel="noopener"><em>SetFormsData</em></a>はデータを返しません。しかし、フォーム要素の値を設定することができます。
<pre class="theme:github font:monospace lang:js decode:true">expression.SetFormsData();
</pre>
<em>expression</em>は<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Word/ApiDocument/ApiDocument.md" target="_blank" rel="noopener">ApiDocument</a>クラスを表す変数です。

メソッドのパラメータは、フォームのキーと値を指定する<a href="https://github.com/ONLYOFFICE/office-js-api/blob/master/Enumerations/FormData.md" target="_blank" rel="noopener">FormData</a>配列の形式で渡されます。さらに、フォームタイプを指定するオプションもあります。

このメソッドを使うことで、関連するすべてのフォーム要素のデフォルト値を簡単に定義し、動的なドキュメント編集を自動化することができます。
<h2>テキストフィールドを修正するマクロ：GetFormsData実装</h2>
この気の利いたマクロは、文書内のすべてのテキストフィールドを変更する機能を提供します。また、他のフォームタイプに変更を加えるためにカスタマイズすることもできます。

まず、アクティブなドキュメントを対象とします：
<pre class="theme:github font:monospace lang:js decode:true ">const oDocument = Api.GetDocument();</pre>
次に、ドキュメントに存在するすべてのフォーム要素を含む配列<em>(aForms)</em>を取得します。
<pre class="theme:github font:monospace lang:js decode:true ">const aForms = oDocument.GetAllForms();
</pre>
その後、ドキュメント内のすべてのフォームに関するデータを収集し、<em>formsData</em>変数に格納します：
<pre class="theme:github font:monospace lang:js decode:true ">const formsData = oDocument.GetFormsData();
</pre>
次に、配列の各フォーム要素を繰り返し処理するループを追加します：
<pre class="theme:github font:monospace lang:js decode:true ">for (let i = 0; i &lt; aForms.length; i++) {
}
</pre>
現在のフォームのタイプが「<em>text</em>」かどうかをチェックします。もし真であれば、続く行でフォーム要素に変更を加えます：
<pre class="theme:github font:monospace lang:js decode:true ">if (formsData[i]["type"] == "text") {
  //aForms[i].SetBackgroundColor(205, 0, 0); // &lt;---- Sets/Changes the Background Color of all the form elements.
  //aForms[i].SetBorderColor(205, 0, 0);       //&lt;---- Unccomment if you want to set/change the border color for all the form elements.
  //aForms[i].SetPlaceholderText("Placeholder Text");       //&lt;---- Unccomment if you want to set/change the Placeholder Text for all the form elements.
  //aForms[i].SetRequired(true);          //&lt;---- Unccomment if you want to set/change the 'required' property for all the form elements.
  //aForms[i].SetTipText("Tip Text");       //&lt;---- Unccomment if you want to set/change the Tip Text for all the form elements.
}
</pre>
ここでは、各行が実行するアクションの説明とともにコメントされています。

マクロ全体のコードは以下の通りです：
<pre class="theme:github font:monospace lang:js decode:true">(function() {
  const oDocument = Api.GetDocument();
  const aForms = oDocument.GetAllForms();
  const formsData = oDocument.GetFormsData();

  for (let i = 0; i &lt; aForms.length; i++) {
    if (formsData[i]["type"] == "text") {
      // Uncomment the following lines based on your preferences:
      // aForms[i].SetBackgroundColor(205, 0, 0); // Sets/Changes the Background Color of all the form elements.
      // aForms[i].SetBorderColor(205, 0, 0);     // Uncomment if you want to set/change the border color for all the form elements.
      // aForms[i].SetPlaceholderText("Placeholder Text"); // Uncomment if you want to set/change the Placeholder Text for all the form elements.
      // aForms[i].SetRequired(true);        // Uncomment if you want to set/change the 'required' property for all the form elements.
      // aForms[i].SetTipText("Tip Text");   // Uncomment if you want to set/change the Tip Text for all the form elements.
    }
  }
})();
</pre>
<div style="text-align: center;"><iframe width="560" height="315" src="https://www.youtube.com/embed/H8_fURd4zpE?si=20Tzx6h8tZergfUE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" data-mce-fragment="1"></iframe></div>
<h2></h2>
<h2>フォームのデフォルト値を設定するマクロ：SetFormsDataの実装</h2>
2番目のマクロを使うことで、対象となるフォームの値を簡単かつシームレスに調整できます。このマクロはとてもシンプルで、わずかなステップで実行できます。

まず、アクティブなドキュメントを取得します：
<pre class="theme:github font:monospace lang:js decode:true ">const oDocument = Api.GetDocument();
</pre>
次に、<em>SetFormsData</em>メソッドを使用し、メソッドのパラメータ内で要素のキーと必要なデフォルト値を定義します：
<pre class="theme:github font:monospace lang:js decode:true ">oDocument.SetFormsData([
  {key: "CompanyName", value: "OnlyOffice"}
]);
</pre>
マクロコード全体は以下の通りです：
<pre class="theme:github font:monospace lang:js decode:true">const oDocument = Api.GetDocument();
oDocument.SetFormsData([
  {key: "CompanyName", value: "OnlyOffice"}
]);
</pre>
<div style="text-align: center;"><iframe width="560" height="315" src="https://www.youtube.com/embed/vv76mMKWHW4?si=okhuguDqpGdpcWJ0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" data-mce-fragment="1"></iframe></div>
ご紹介したメソッドやマクロが、ドキュメントのワークフローを効率化し、皆様のお役に立つことを願っています。マクロは強力なツールとして機能し、私たちの豊富なAPIライブラリは、さまざまなタスクを自動化するための無数の可能性を提供します。

ドキュメント処理の強力な機能を活用したパーソナライズされたマクロを作成し、APIを自由に掘り下げてください。あなたの革新的なアイデアを共有するために、お気軽に私たちに<a href="https://www.onlyoffice.com/ja/contacts.aspx?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener">ご連絡ください</a>。ディスカッションとコラボレーションを歓迎します。

<h3><strong>お役立ちリンク</strong></h3>
<a href="https://www.onlyoffice.com/ja/desktop.aspx?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener"><u>無料オフィス・スイート</u></a>

<a href="https://api.onlyoffice.com/docbuilder/textdocumentapi/apidocument/getformsdata?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener"><u>GetFormsDataメソッドについて</u></a>

<a href="https://api.onlyoffice.com/docbuilder/textdocumentapi/apidocument/setformsdata?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener"><u>SetFormsDataメソッドについて</u></a>

<a href="https://oforms.onlyoffice.com/ja?utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener"><u>OFORMSライブラリ</u></a>

<a href="https://www.onlyoffice.com/blog/ja/search?s=OFORM+マクロ&amp;utm_source=qiita&amp;utm_medium=article+&amp;utm_id=set_form_data_macro" target="_blank" rel="noopener"><u>その他の便利なマクロ</u></a>