Excel JavaScript API を使用してブックを操作する

[アーティクル]
03/26/2024

この記事では、Excel JavaScript API を使用して、ブックでタスクを実行する方法のコードサンプルを示しています。オブジェクトがサポートする Workbook プロパティとメソッドの完全な一覧については、「 Workbook オブジェクト (JavaScript API for Excel)」を参照してください。この記事では、Application オブジェクトを使用して実行するブックレベルのアクションについても説明します。

Workbook オブジェクトは、Excel を操作するアドインのエントリポイントです。このオブジェクトは、Excel データのアクセスや変更に使用するワークシート、テーブル、ピボットテーブル、その他のコレクションを保持します。 WorksheetCollection オブジェクトは、個々のワークシートを使用して、ブックのすべてのデータにアドインからアクセスできるようにします。具体的には、アドインからワークシートの追加、ワークシート間の移動、ワークシートイベントへのハンドラーの割り当てができます。ワークシートへのアクセスと編集の方法については、「Excel JavaScript API を使用してワークシートを操作する」を参照してください。

アクティブセルまたは選択した範囲を取得する

Workbook オブジェクトには、ユーザーまたはアドインが選択したセルの範囲を取得する 2 つのメソッド getActiveCell() と getSelectedRange() があります。 getActiveCell() はブックからアクティブセルを Range オブジェクトとして取得します。次の例では、getActiveCell() を呼び出し、コンソールにセルのアドレスを表示します。

await Excel.run(async (context) => {
    let activeCell = context.workbook.getActiveCell();
    activeCell.load("address");
    await context.sync();

    console.log("The active cell is " + activeCell.address);
});

getSelectedRange() メソッドは現在選択されている単一の範囲を返します。複数の範囲が選択されている場合は、InvalidSelection エラーがスローされます。次の例では、getSelectedRange() を呼び出し、範囲の塗りつぶし色を黄色に設定します。

await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    range.format.fill.color = "yellow";
    await context.sync();
});

ブックを作成する

アドインでは、アドインが現在実行されている Excel のインスタンスとは異なる新しいブックを作成できます。 Excel オブジェクトには、この目的の createWorkbook メソッドがあります。このメソッドが呼び出されると、新しいブックが Excel の新しいインスタンスですぐに開いて表示されます。アドインは前のブックで開いて実行されたままになります。

Excel.createWorkbook();

createWorkbook メソッドは既存のブックのコピーの作成もできます。このメソッドは、オプションのパラメーターとして .xlsx ファイルの base64 エンコード文字列表現を受け取ります。文字列の引数は有効な .xlsx ファイルと見なされ、作成されるブックはそのファイルのコピーになります。

ファイルスライスを使用して、アドインの現在のブックを base64 でエンコードされた文字列として取得できます。次の例に示すように、FileReader クラスを使用して、ファイルを必要な base64 エンコード文字列に変換できます。

// Retrieve the external workbook file and set up a `FileReader` object. 
let myFile = document.getElementById("file");
let reader = new FileReader();

reader.onload = (function (event) {
    Excel.run(function (context) {
        // Remove the metadata before the base64-encoded string.
        let startIndex = reader.result.toString().indexOf("base64,");
        let externalWorkbook = reader.result.toString().substr(startIndex + 7);

        Excel.createWorkbook(externalWorkbook);
        return context.sync();
    });
});

// Read the file as a data URL so we can parse the base64-encoded string.
reader.readAsDataURL(myFile.files[0]);

既存のブックのコピーを現在のブックに挿入する

前の例は、既存のブックから作成された新しいブックを示しています。既存のブックの一部またはすべてを、アドインに関連付けられているブックにコピーすることもできます。 Workbook には、insertWorksheetsFromBase64ターゲットブックのワークシートのコピーをそれ自体に挿入するメソッドがあります。他のブックのファイルは、呼び出しと同様 Excel.createWorkbook に base64 でエンコードされた文字列として渡されます。

insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;

重要

メソッドはinsertWorksheetsFromBase64、Excel on the web、Windows、Mac でサポートされています。 iOS ではサポートされていません。さらに、Excel on the webでは、このメソッドはピボットテーブル、グラフ、コメント、またはスライサー要素を含むソースワークシートをサポートしていません。これらのオブジェクトが存在する場合、insertWorksheetsFromBase64メソッドはExcel on the webでエラーをUnsupportedFeature返します。

次のコードサンプルは、別のブックから現在のブックにワークシートを挿入する方法を示しています。このコードサンプルでは、最初にオブジェクトを含むブックファイルを FileReader 処理し、base64 でエンコードされた文字列を抽出してから、この base64 でエンコードされた文字列を現在のブックに挿入します。新しいワークシートは、 Sheet1 という名前のワークシートの後に挿入されます。 []は、InsertWorksheetOptions.sheetNamesToInsert プロパティのパラメーターとして渡されることに注意してください。つまり、ターゲットブックのすべてのワークシートが現在のブックに挿入されます。

// Retrieve the external workbook file and set up a `FileReader` object. 
let myFile = document.getElementById("file");
let reader = new FileReader();

reader.onload = (event) => {
    Excel.run((context) => {
        // Remove the metadata before the base64-encoded string.
        let startIndex = reader.result.toString().indexOf("base64,");
        let externalWorkbook = reader.result.toString().substr(startIndex + 7);
            
        // Retrieve the current workbook.
        let workbook = context.workbook;
            
        // Set up the insert options. 
        let options = { 
            sheetNamesToInsert: [], // Insert all the worksheets from the source workbook.
            positionType: Excel.WorksheetPositionType.after, // Insert after the `relativeTo` sheet.
            relativeTo: "Sheet1" // The sheet relative to which the other worksheets will be inserted. Used with `positionType`.
        }; 
            
         // Insert the new worksheets into the current workbook.
         workbook.insertWorksheetsFromBase64(externalWorkbook, options);
         return context.sync();
    });
};

// Read the file as a data URL so we can parse the base64-encoded string.
reader.readAsDataURL(myFile.files[0]);

ブックのシート構成を保護する

アドインでは、ブックのシート構成を編集するユーザーの機能を制御できます。 Workbook オブジェクトの protection プロパティは WorkbookProtection オブジェクトであり、protect() メソッドを備えています。次の例では、ブックのシート構成の保護を切り替える基本的なシナリオを示します。

await Excel.run(async (context) => {
    let workbook = context.workbook;
    workbook.load("protection/protected");
    await context.sync();

    if (!workbook.protection.protected) {
        workbook.protection.protect();
    }
});

protect メソッドは、オプションの文字列パラメーターを受け取ります。この文字列は、ユーザーが保護をバイパスしてブックのシート構成を変更するために必要なパスワードを表します。

保護は、不必要なデータ編集をできないようにするため、ワークシートレベルで設定することもできます。詳細については、「Excel JavaScript API を使用してワークシートを操作する」のデータの保護のセクションを参照してください。

注:

Excel のブックの保護の詳細については、「ブックを保護する」を参照してください。

ドキュメントプロパティへのアクセス

Workbook オブジェクトは、ドキュメントプロパティと呼ばれる Office ファイルのメタデータにアクセスできます。 Workbook オブジェクトの properties プロパティは、これらのメタデータ値の一部を含む DocumentProperties オブジェクトです。次の例は、プロパティを設定する方法を author 示しています。

await Excel.run(async (context) => {
    let docProperties = context.workbook.properties;
    docProperties.author = "Alex";
    await context.sync();
});

カスタムプロパティを定義することもできます。 DocumentProperties オブジェクトには custom プロパティが含まれていて、ユーザー定義プロパティのキー値のペアのコレクションを表します。カスタムプロパティの設定の例については、「アドインの状態と設定を保持する」の「Excel のカスタム XML データとWord」セクションを参照してください。

ドキュメント設定へのアクセス

ブックの設定は、カスタムプロパティのコレクションに似ています。設定は 1 つの Excel ファイルとアドインのペアリングに固有であるのに対して、プロパティはファイルに接続しているだけである点が異なります。次の例は、設定を作成してアクセスする方法を示しています。

await Excel.run(async (context) => {
    let settings = context.workbook.settings;
    settings.add("NeedsReview", true);
    let needsReview = settings.getItem("NeedsReview");
    needsReview.load("value");

    await context.sync();
    console.log("Workbook needs review : " + needsReview.value);
});

アプリケーションカルチャ設定にアクセスする

ブックには、特定のデータの表示方法に影響する言語とカルチャの設定があります。これらの設定は、アドインのユーザーがさまざまな言語やカルチャでブックを共有している場合にデータをローカライズするのに役立ちます。アドインでは、文字列解析を使用して、システムカルチャ設定に基づいて数値、日付、時刻の形式をローカライズし、各ユーザーが独自のカルチャの形式でデータを表示できるようにします。

Application.cultureInfo は、システムカルチャ設定を CultureInfo オブジェクトとして定義します。これには、数値の小数点や日付形式などの設定が含まれます。

一部のカルチャ設定は、Excel UI を使用して変更できます。システム設定はオブジェクトに CultureInfo 保持されます。ローカルの変更は、アプリケーションレベルのプロパティ (など Application.decimalSeparator) として保持されます。

次の例では、数値文字列の小数点文字を ',' からシステム設定で使用される文字に変更します。

// This will convert a number like "14,37" to "14.37"
// (assuming the system decimal separator is ".").
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let decimalSource = sheet.getRange("B2");

    decimalSource.load("values");
    context.application.cultureInfo.numberFormat.load("numberDecimalSeparator");
    await context.sync();

    let systemDecimalSeparator =
        context.application.cultureInfo.numberFormat.numberDecimalSeparator;
    let oldDecimalString = decimalSource.values[0][0];

    // This assumes the input column is standardized to use "," as the decimal separator.
    let newDecimalString = oldDecimalString.replace(",", systemDecimalSeparator);

    let resultRange = sheet.getRange("C2");
    resultRange.values = [[newDecimalString]];
    resultRange.format.autofitColumns();
    await context.sync();
});

計算の動作を制御する

計算モードを設定する

既定では、Excel は、参照されているセルが変更されたときに数式の結果を再計算します。この計算の動作を調整すると、アドインのパフォーマンス向上に役立つ場合があります。 Application オブジェクトには、CalculationMode 型のプロパティ calculationMode があります。次の値に設定できます。

automatic: 既定の再計算動作。関連するデータが変更されるたびに、Excel は新しい数式の結果を計算します。
automaticExceptTables: automatic と同様ですが、テーブル内の値に加えた変更は無視されます。
manual: ユーザーまたはアドインが要求した場合にのみ計算します。

計算タイプを設定する

Application オブジェクトは、強制的に即時再計算する方法を提供します。 Application.calculate(calculationType) は、指定した calculationType に基づいて手動再計算を開始します。次の値を指定できます。

full: 最後に再計算されてから変更されたかどうかに関係なく、開いているすべてのブックのすべての数式を再計算します。
fullRebuild: 最後に再計算されてから変更されたかどうかに関係なく、依存関係のある数式を確認してから、開いているすべてのブックのすべての数式を再計算します。
recalculate: すべてのアクティブなブックで、最後に計算されてから変更された数式 (またはプログラムで再計算用にマークされている数式)、およびそれに依存する数式を再計算します。

注:

再計算の詳細については、「数式の再計算、反復計算、または精度を変更する」を参照してください。

計算を一時的に中断する

Excel API では、アドインから RequestContext.sync() を呼び出すまで計算をオフにすることもできます。これは、suspendApiCalculationUntilNextSync() で実行できます。このメソッドは、アドインから大きな範囲を編集し、複数の編集の間でデータにアクセスする必要がない場合に使用します。

context.application.suspendApiCalculationUntilNextSync();

ブックのアクティブ化を検出する

アドインは、ブックがアクティブ化されたタイミングを検出できます。ユーザーが別のブック、別のアプリケーション、または (Excel on the webで) Web ブラウザーの別のタブにフォーカスを切り替えると、ブックが非アクティブになります。ユーザーがブックにフォーカスを返すと、ブックが アクティブになります 。ブックのアクティブ化では、ブックデータの更新など、アドインでコールバック関数をトリガーできます。

ブックがアクティブ化されたことを検出するには、ブックの onActivated イベントのイベントハンドラーを登録します。イベントのイベントハンドラーは、 onActivated イベントが発生したときに WorkbookActivatedEventArgs オブジェクトを受け取ります。

重要

onActivatedブックが開かれると、イベントは検出されません。このイベントは、ユーザーが既に開いているブックにフォーカスを切り替えたときにのみ検出されます。

次のコードサンプルは、イベントハンドラーを onActivated 登録し、コールバック関数を設定する方法を示しています。

async function run() {
    await Excel.run(async (context) => {
        // Retrieve the workbook.
        let workbook = context.workbook;
    
        // Register the workbook activated event handler.
        workbook.onActivated.add(workbookActivated);
        await context.sync();
    });
}

async function workbookActivated(event) {
    await Excel.run(async (context) => {
        // Retrieve the workbook and load the name.
        let workbook = context.workbook;
        workbook.load("name");        
        await context.sync();

        // Callback function for when the workbook is activated.
        console.log(`The workbook ${workbook.name} was activated.`);
    });
}

ブックを保存する

Workbook.save は、ブックを永続記憶装置に保存します。メソッドは save 、次のいずれかの値を指定できる単一の省略可能な saveBehavior パラメーターを受け取ります。

Excel.SaveBehavior.save (既定値): ファイル名や保存場所を指定するようにユーザーに促すダイアログは表示されず、そのままファイルが保存されます。ファイルが以前に保存されていない場合は、既定の場所に保存されます。ファイルが以前に保存されている場合は、同じ場所に保存されます。
Excel.SaveBehavior.prompt: ファイルが以前に保存されていない場合は、ファイル名や保存場所を指定するようにユーザーに促すダイアログが表示されます。ファイルが以前に保存されている場合、ファイルは同じ場所に保存され、ダイアログは表示されません。

注意

保存を促すダイアログが表示されたのにユーザーがその操作をキャンセルすると、save は例外をスローします。

context.workbook.save(Excel.SaveBehavior.prompt);

ブックを閉じる

Workbook.close は、ブックとそのブックに関連付けられているアドインを終了します (Excel アプリケーションは開いたまま)。メソッドは close 、次のいずれかの値を指定できる単一の省略可能な closeBehavior パラメーターを受け取ります。

Excel.CloseBehavior.save (既定値): ファイルは閉じる前に保存されます。そのファイルが以前に保存されていない場合は、ファイル名や保存場所を指定するようにユーザーに促すダイアログが表示されます。
Excel.CloseBehavior.skipSave: ファイルはそのまま閉じられ、保存されません。未保存の変更は失われます。

context.workbook.close(Excel.CloseBehavior.save);

次の方法で共有

Excel JavaScript API を使用してブックを操作する

アクティブセルまたは選択した範囲を取得する

ブックを作成する

既存のブックのコピーを現在のブックに挿入する

ブックのシート構成を保護する

ドキュメントプロパティへのアクセス

ドキュメント設定へのアクセス

アプリケーションカルチャ設定にアクセスする

計算の動作を制御する

計算モードを設定する

計算タイプを設定する

計算を一時的に中断する

ブックのアクティブ化を検出する

ブックを保存する

ブックを閉じる

関連項目

その他のリソース

次の方法で共有

Excel JavaScript API を使用してブックを操作する

アクティブ セルまたは選択した範囲を取得する

ブックを作成する

既存のブックのコピーを現在のブックに挿入する

ブックのシート構成を保護する

ドキュメント プロパティへのアクセス

ドキュメント設定へのアクセス

アプリケーション カルチャ設定にアクセスする

計算の動作を制御する

計算モードを設定する

計算タイプを設定する

計算を一時的に中断する

ブックのアクティブ化を検出する

ブックを保存する

ブックを閉じる

関連項目

その他のリソース

アクティブセルまたは選択した範囲を取得する

ドキュメントプロパティへのアクセス

アプリケーションカルチャ設定にアクセスする