Excel.WorksheetCollection class

ブックの一部であるワークシート オブジェクトのコレクションを表します。

Extends

注釈

[ API セット: ExcelApi 1.1 ]

プロパティ

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

items

このコレクション内に読み込まれた子アイテムを取得します。

メソッド

add(name)

新しいワークシートをブックに追加します。 ワークシートは、既存のワークシートの末尾に追加されます。 新しく追加したワークシートをアクティブ化する場合は、 を呼び出 .activate() します。

addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)

あるブックの指定されたワークシートを現在のブックに挿入します。

*: この API は現在、Windows および Mac 上の Office でのみサポートされています。 非推奨となりましたので、代わりに を使用 Workbook.insertWorksheetFromBase64 してください。

addFromBase64(base64File, sheetNamesToInsert, positionTypeString, relativeTo)

あるブックの指定されたワークシートを現在のブックに挿入します。

*: この API は現在、Windows および Mac 上の Office でのみサポートされています。 非推奨となりましたので、代わりに を使用 Workbook.insertWorksheetFromBase64 してください。

getActiveWorksheet()

ブックの、現在作業中のワークシートを取得します。

getCount(visibleOnly)

コレクションに含まれるワークシートの数を取得します。

getFirst(visibleOnly)

コレクション内の最初のワークシートを取得します。

getItem(key)

名前または ID を使用して、ワークシート オブジェクトを取得します。

getItemOrNullObject(key)

名前または ID を使用して、ワークシート オブジェクトを取得します。 ワークシートが存在しない場合、このメソッドは プロパティが に設定されたオブジェクトをisNullObjecttrue返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getLast(visibleOnly)

コレクション内の最後のワークシートを取得します。

load(options)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNames)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNamesAndPaths)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

toJSON()

API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドを JSON.stringify()オーバーライドします。 (JSON.stringifyさらに、渡される オブジェクトの メソッドを呼び出 toJSON します)。元 Excel.WorksheetCollection のオブジェクトは API オブジェクトですが、 toJSON メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト (として Excel.Interfaces.WorksheetCollectionData型指定) を返します。

イベント

onActivated

ブック内のワークシートがアクティブになると発生します。

onAdded

ブックに新しいワークシートが追加されたときに発生します。

onCalculated

ブック内のワークシートが計算されるときに発生します。

onChanged

ブックのワークシートが変更されたときに発生します。

onColumnSorted

1 つ以上の列を並べ替えたときに発生します。 これは、左から右に並べ替えを実行したときに発生します。

onDeactivated

ブック内のワークシートが非アクティブ化されたときに発生します。

onDeleted

ワークシートがブックから削除されたときに発生します。

onFiltered

ブック内でワークシートのフィルターが適用されたときに発生します。

onFormatChanged

ブック内のワークシートの書式が変更された場合に発生します。

onFormulaChanged

このコレクションの任意のワークシートで 1 つ以上の数式が変更されたときに発生します。 このイベントは、数式の計算結果のデータ値ではなく、数式自体が変更されたときに発生します。

onMoved

ワークシートがブック内で移動されたときに発生します。 このイベントは、ワークシートがブック内で直接移動されたときにのみトリガーされます。 このイベントは、新しいワークシートが挿入され、既存のワークシートが位置を変更する場合など、ワークシートの位置が間接的に変更された場合にはトリガーされません。

onNameChanged

ワークシートコレクションでワークシート名が変更されたときに発生します。

onProtectionChanged

ワークシートの保護状態が変更されたときに発生します。

onRowHiddenChanged

特定のワークシートで 1 つ以上の行の非表示状態が変更されたときに発生します。

onRowSorted

1 つ以上の行を並べ替えたときに発生します。 これは、上から下に並べ替えを実行したときに発生します。

onSelectionChanged

ワークシートで選択範囲を変更したときに発生します。

onSingleClicked

ワークシート コレクションで左クリックまたはタップ操作が行われると発生します。 このイベントは、次の場合にクリックしても発生しません。 - ユーザーはマウスをドラッグして複数選択します。 - 数式参照にセル引数が選択されている場合、ユーザーはモードでセルを選択します。

onVisibilityChanged

ワークシート コレクションでワークシートの表示設定が変更されたときに発生します。

プロパティの詳細

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

items

このコレクション内に読み込まれた子アイテムを取得します。

readonly items: Excel.Worksheet[];

プロパティ値

メソッドの詳細

add(name)

新しいワークシートをブックに追加します。 ワークシートは、既存のワークシートの末尾に追加されます。 新しく追加したワークシートをアクティブ化する場合は、 を呼び出 .activate() します。

add(name?: string): Excel.Worksheet;

パラメーター

name

string

オプション。 追加するワークシートの名前。 指定した場合、名前は一意である必要があります。 指定されていない場合は、Excel が新しいワークシートの名前を決定します。

戻り値

注釈

[ API セット: ExcelApi 1.1 ]

await Excel.run(async (context) => { 
    const wSheetName = 'Sample Name';
    const worksheet = context.workbook.worksheets.add(wSheetName);
    worksheet.load('name');
    await context.sync();
    
    console.log(worksheet.name);
});

addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

あるブックの指定されたワークシートを現在のブックに挿入します。

*: この API は現在、Windows および Mac 上の Office でのみサポートされています。 非推奨となりましたので、代わりに を使用 Workbook.insertWorksheetFromBase64 してください。

addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: Excel.WorksheetPositionType, relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;

パラメーター

base64File

string

必須です。 ソース ブック ファイルを表す base64 でエンコードされた文字列。

sheetNamesToInsert

string[]

オプション。 挿入する個々のワークシートの名前。 既定では、ソース ブックのすべてのワークシートが挿入されます。

positionType
Excel.WorksheetPositionType

オプション。 現在のブック内の新しいワークシートが挿入されます。 詳細は「Excel.WorksheetPositionType」をご覧ください。 既定値は "Start" です。

relativeTo

Excel.Worksheet | string

オプション。 パラメーターに対して参照されている現在のブック内の positionType ワークシート。 既定値は であり null 、 に positionType基づいて、現在のブックの先頭または末尾にワークシートが挿入されます。

戻り値

新しく挿入された各ワークシートに対応する ID の配列。

注釈

[ API セット: ExcelApi BETA (プレビューのみ) ]

addFromBase64(base64File, sheetNamesToInsert, positionTypeString, relativeTo)

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

あるブックの指定されたワークシートを現在のブックに挿入します。

*: この API は現在、Windows および Mac 上の Office でのみサポートされています。 非推奨となりましたので、代わりに を使用 Workbook.insertWorksheetFromBase64 してください。

addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;

パラメーター

base64File

string

必須です。 ソース ブック ファイルを表す base64 でエンコードされた文字列。

sheetNamesToInsert

string[]

オプション。 挿入する個々のワークシートの名前。 既定では、ソース ブックのすべてのワークシートが挿入されます。

positionTypeString

"None" | "Before" | "After" | "Beginning" | "End"

オプション。 現在のブック内の新しいワークシートが挿入されます。 詳細は「Excel.WorksheetPositionType」をご覧ください。 既定値は "Start" です。

relativeTo

Excel.Worksheet | string

オプション。 パラメーターに対して参照されている現在のブック内の positionType ワークシート。 既定値は であり null 、 に positionType基づいて、現在のブックの先頭または末尾にワークシートが挿入されます。

戻り値

新しく挿入された各ワークシートに対応する ID の配列。

注釈

[ API セット: ExcelApi BETA (プレビューのみ) ]

getActiveWorksheet()

ブックの、現在作業中のワークシートを取得します。

getActiveWorksheet(): Excel.Worksheet;

戻り値

注釈

[ API セット: ExcelApi 1.1 ]

await Excel.run(async (context) => {  
    const activeWorksheet = context.workbook.worksheets.getActiveWorksheet();
    activeWorksheet.load('name');
    await context.sync();
    console.log(activeWorksheet.name);
});

getCount(visibleOnly)

コレクションに含まれるワークシートの数を取得します。

getCount(visibleOnly?: boolean): OfficeExtension.ClientResult<number>;

パラメーター

visibleOnly

boolean

オプション。 の場合 trueは、非表示のワークシートをスキップして、表示されているワークシートのみを考慮します。

戻り値

注釈

[ API セット: ExcelApi 1.4 ]

getFirst(visibleOnly)

コレクション内の最初のワークシートを取得します。

getFirst(visibleOnly?: boolean): Excel.Worksheet;

パラメーター

visibleOnly

boolean

オプション。 の場合 trueは、非表示のワークシートをスキップして、表示されているワークシートのみを考慮します。

戻り値

注釈

[ API セット: ExcelApi 1.5 ]

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

getItem(key)

名前または ID を使用して、ワークシート オブジェクトを取得します。

getItem(key: string): Excel.Worksheet;

パラメーター

key

string

ワークシートの名前または ID。

戻り値

注釈

[ API セット: ExcelApi 1.1 ]

getItemOrNullObject(key)

名前または ID を使用して、ワークシート オブジェクトを取得します。 ワークシートが存在しない場合、このメソッドは プロパティが に設定されたオブジェクトをisNullObjecttrue返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getItemOrNullObject(key: string): Excel.Worksheet;

パラメーター

key

string

ワークシートの名前または ID。

戻り値

注釈

[ API セット: ExcelApi 1.4 ]

getLast(visibleOnly)

コレクション内の最後のワークシートを取得します。

getLast(visibleOnly?: boolean): Excel.Worksheet;

パラメーター

visibleOnly

boolean

オプション。 の場合 trueは、非表示のワークシートをスキップして、表示されているワークシートのみを考慮します。

戻り値

注釈

[ API セット: ExcelApi 1.5 ]

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

load(options)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(options?: Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.WorksheetCollection;

パラメーター

options

Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

読み込むオブジェクトのプロパティのオプションを提供します。

戻り値

load(propertyNames)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNames?: string | string[]): Excel.WorksheetCollection;

パラメーター

propertyNames

string | string[]

読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。

戻り値

await Excel.run(async (context) => { 
    const worksheets = context.workbook.worksheets;
    worksheets.load('items');
    await context.sync();
    
    for (let i = 0; i < worksheets.items.length; i++) {
        console.log(worksheets.items[i].name);
    }
});

load(propertyNamesAndPaths)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.WorksheetCollection;

パラメーター

propertyNamesAndPaths
OfficeExtension.LoadOption

propertyNamesAndPaths.select は、読み込むプロパティを指定するコンマ区切り文字列で propertyNamesAndPaths.expand 、読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。

戻り値

toJSON()

API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドを JSON.stringify()オーバーライドします。 (JSON.stringifyさらに、渡される オブジェクトの メソッドを呼び出 toJSON します)。元 Excel.WorksheetCollection のオブジェクトは API オブジェクトですが、 toJSON メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト (として Excel.Interfaces.WorksheetCollectionData型指定) を返します。

toJSON(): Excel.Interfaces.WorksheetCollectionData;

戻り値

イベントの詳細

onActivated

ブック内のワークシートがアクティブになると発生します。

readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.7 ]

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onActivated.add(onActivate);

    await context.sync();
    console.log("A handler has been registered for the OnActivate event.");
});

onAdded

ブックに新しいワークシートが追加されたときに発生します。

readonly onAdded: OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.7 ]

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

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

    await context.sync();
    console.log("A handler has been registered for the OnAdded event.");
});

onCalculated

ブック内のワークシートが計算されるときに発生します。

readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.8 ]

onChanged

ブックのワークシートが変更されたときに発生します。

readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.9 ]

onColumnSorted

1 つ以上の列を並べ替えたときに発生します。 これは、左から右に並べ替えを実行したときに発生します。

readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.10 ]

onDeactivated

ブック内のワークシートが非アクティブ化されたときに発生します。

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.7 ]

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onDeactivated.add(onDeactivate);

    await context.sync();
    console.log("A handler has been registered for the OnDeactivate event.");
});

onDeleted

ワークシートがブックから削除されたときに発生します。

readonly onDeleted: OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.7 ]

onFiltered

注意

この API は開発者向けにプレビューとして提供されており、寄せられたフィードバックにもとづいて変更される場合があります。 この API は運用環境で使用しないでください。

ブック内でワークシートのフィルターが適用されたときに発生します。

readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi BETA (プレビューのみ) ]

onFormatChanged

ブック内のワークシートの書式が変更された場合に発生します。

readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.9 ]

onFormulaChanged

このコレクションの任意のワークシートで 1 つ以上の数式が変更されたときに発生します。 このイベントは、数式の計算結果のデータ値ではなく、数式自体が変更されたときに発生します。

readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.13 ]

onMoved

ワークシートがブック内で移動されたときに発生します。 このイベントは、ワークシートがブック内で直接移動されたときにのみトリガーされます。 このイベントは、新しいワークシートが挿入され、既存のワークシートが位置を変更する場合など、ワークシートの位置が間接的に変更された場合にはトリガーされません。

readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.17 ]

onNameChanged

ワークシートコレクションでワークシート名が変更されたときに発生します。

readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.17 ]

onProtectionChanged

ワークシートの保護状態が変更されたときに発生します。

readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.14 ]

onRowHiddenChanged

特定のワークシートで 1 つ以上の行の非表示状態が変更されたときに発生します。

readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.11 ]

onRowSorted

1 つ以上の行を並べ替えたときに発生します。 これは、上から下に並べ替えを実行したときに発生します。

readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.10 ]

onSelectionChanged

ワークシートで選択範囲を変更したときに発生します。

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.9 ]

onSingleClicked

ワークシート コレクションで左クリックまたはタップ操作が行われると発生します。 このイベントは、次の場合にクリックしても発生しません。 - ユーザーはマウスをドラッグして複数選択します。 - 数式参照にセル引数が選択されている場合、ユーザーはモードでセルを選択します。

readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.10 ]

onVisibilityChanged

ワークシート コレクションでワークシートの表示設定が変更されたときに発生します。

readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;

イベントの種類

注釈

[ API セット: ExcelApi 1.17 ]