この記事では、Excel 2016以降のアドインを作成するためのExcel JavaScript APIの使用方法を説明しています。APIの基本概念や、大規模な範囲の読み書き、セルの更新などの特定のタスクを実行する方法が紹介されています。Excel JavaScript APIは、ワークシートや範囲、テーブル、チャートなどにアクセスするための強く型付けされたオブジェクトを提供します。また、Common APIを使用して、UIやダイアログなどの共通機能にもアクセスします。範囲は連続したセルのグループであり、様々なデータ構造や視覚化を操作できます。

Excel JavaScript APIを使用したExcelアドインの構築

この文章では、Excel 2016以降で動作するアドインを構築するためのExcel JavaScript APIの使用法について説明します。APIを使用するための基本的な概念を紹介し、大規模な範囲の読み取りや書き込み、範囲内のすべてのセルの更新など、特定のタスクの実行方法についてのガイダンスを提供します。

Office.js API for Excel

Excelアドインは、Office JavaScript APIを使用してExcel内のオブジェクトと相互作用します。このAPIには、2つのJavaScriptオブジェクトモデルが含まれています。

• Excel JavaScript API: Office 2016で導入されたExcel JavaScript APIは、ワークシート、範囲、テーブル、チャートなどにアクセスするために使用できる型安全なExcelオブジェクトを提供します。

• Common API: Office 2013で導入されたCommon APIは、複数のOfficeアプリケーション間で共通の機能にアクセスすることを可能にしますが、Excelとのインタラクションの制限された機能はExcel JavaScript APIによって置き換えられました。

ほとんどの機能を開発する際はExcel JavaScript APIを使用しますが、Common API内のオブジェクトも使用します。例えば：

• Context: Contextオブジェクトは、アドインの実行環境を表し、APIの主要なオブジェクトへのアクセスを提供します。contentLanguageやofficeThemeなどのワークブック設定の詳細や、hostやplatformなどの実行環境に関する情報が含まれています。

• Document: Documentオブジェクトは、アドインが実行されているExcelファイルをダウンロードするために使用できるgetFileAsync()メソッドを提供します。

以下の画像は、Excel JavaScript APIやCommon APIを使用する際の例を示しています。

Excel特有のオブジェクトモデル

Excel APIを理解するためには、ワークブックのコンポーネントがどのように関連しているかを理解する必要があります。

• ワークブックは1つ以上のワークシートを含む。
• ワークシートは個々のシートに存在するデータオブジェクトのコレクションを含み、Rangeオブジェクトを介してセルにアクセスを提供する。
• Rangeは連続したセルのグループを表す。
• RangesはTables、Charts、Shapesなどのデータ視覚化または整理オブジェクトを作成するために使用される。
• ワークブックは、全体のワークブックに対してこれらのデータオブジェクト（例えばTables）のコレクションを含む。

Ranges

範囲は、ワークブック内の連続するセルのグループです。アドインは通常、A1スタイルの表記（例：B3は列Bの行3の単一セル、C2:F4は列CからF、行2から4のセル）を使用して範囲を定義します。

範囲には、3つの主要なプロパティがあります：values、formulas、およびformat。これらのプロパティは、セルの値、評価されるべき数式、およびセルの視覚的書式設定を取得または設定します。

Rangeサンプル

以下のサンプルは、販売記録を作成する方法を示しています。この関数では、Rangeオブジェクトを使用して値、数式、およびフォーマットを設定します。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // ヘッダーを作成し、目立つようにフォーマットします。
    let headers = [
        ["Product", "Quantity", "Unit Price", "Totals"]
    ];
    let headerRange = sheet.getRange("B2:E2");
    headerRange.values = headers;
    headerRange.format.fill.color = "#4472C4";
    headerRange.format.font.color = "white";

    // 商品データ行を作成します。
    let productData = [
        ["Almonds", 6, 7.5],
        ["Coffee", 20, 34.5],
        ["Chocolate", 10, 9.56],
    ];
    let dataRange = sheet.getRange("B3:D5");
    dataRange.values = productData;

    // 売上額を合計する数式を作成します。
    let totalFormulas = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    let totalRange = sheet.getRange("E3:E6");
    totalRange.formulas = totalFormulas;
    totalRange.format.font.bold = true;

    // 合計を米ドル額で表示します。
    totalRange.numberFormat = [["$0.00"]];

    await context.sync();
});

このサンプルを実行すると、現在のワークシートに次のデータが作成されます。

詳細については、Excel JavaScript APIを使用して範囲の値、テキスト、または数式を設定および取得するをご覧ください。

チャート、テーブル、およびその他のデータオブジェクト

Excel JavaScript APIは、Excel内のデータ構造や視覚化を作成および操作することができます。テーブルやチャートは一般的に使用されるオブジェクトですが、APIはPivotTables、図形、画像などもサポートしています。

テーブルの作成

データが満たされた範囲を使用してテーブルを作成します。書式設定やテーブルコントロール（フィルターなど）は範囲に自動的に適用されます。

以下のサンプルは、前のサンプルからの範囲を使用してテーブルを作成します。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.tables.add("B2:E5", true);
    await context.sync();
});

このサンプルコードを前のデータがあるワークシートで実行すると、次のようなテーブルが作成されます。

詳細については、Excel JavaScript APIを使用してテーブルと作業するをご覧ください。

チャートの作成

範囲内のデータを視覚化するためにチャートを作成します。APIは、多様なチャートの種類をサポートしており、ニーズに応じてカスタマイズできます。

以下のサンプルは、3つのアイテムのためのシンプルなコロンチャートを作成し、ワークシートの上部から100ピクセル下に配置します。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let chart = sheet.charts.add(Excel.ChartType.columnStacked, sheet.getRange("B3:C5"));
    chart.top = 100;
    await context.sync();
});

このサンプルを前のテーブルがあるワークシートで実行すると、次のようなチャートが作成されます。

詳細については、Excel JavaScript APIを使用してチャートと作業するをご覧ください。

参照

このガイドは、Excel JavaScript APIを使用してエレガントで機能的なアドインを作成するための出発点となることを願っています。さらに詳しい情報やリファレンスは、公式文書を参照してください。

————-

Excel JavaScript object model in Office Add-ins – Office Add-ins

Source link

The article provides an overview of how to use the Excel JavaScript API for building add-ins for Excel 2016 and later. It highlights core concepts essential for utilizing the API and offers guidance on specific tasks such as reading from and writing to ranges, updating cells, and more.

Key components include:

1. API Overview: It introduces two object models within the Office JavaScript API— the Excel JavaScript API, which allows for interaction with Excel-specific objects like worksheets and ranges, and the Common API, which offers access to features common across various Office applications.

2. Workbook Structure: Understanding that a Workbook contains multiple Worksheets, and each Worksheet holds collections of data through Range objects is fundamental. A Range represents a group of contiguous cells.

3. Ranges: Ranges are critical; they can define single or multiple cells using A1-style notation. Ranges have core properties such as values, formulas, and formatting that can be manipulated via the API.

4. Sample Use Cases: Examples include:

   • Setting up headers, product data, and applying formulas to calculate totals.
   • Creating tables from data ranges and adding charts to visualize data.
5. Tables and Charts: The article describes methods for creating tables that automatically apply formatting and controls and illustrates how to create various chart types to represent data visually.

Overall, the article serves as a foundational guide for developers looking to harness the Excel JavaScript API for creating effective Excel add-ins.