Excel.WorksheetCollection class

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

context: RequestContext;

プロパティ値

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

readonly items: Excel.Worksheet[];

プロパティ値

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

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

パラメーター

返品

注釈

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);
});

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

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?: boolean): OfficeExtension.ClientResult<number>;

パラメーター

返品

注釈

API セット: ExcelApi 1.4

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

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

パラメーター

返品

注釈

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();
});

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

getItem(key: string): Excel.Worksheet;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-axis-formatting.yaml

function displayUnit(context: Excel.RequestContext) {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let chart = sheet.charts.getItem("SalesChart");
    let axis = chart.axes.valueAxis;
    axis.displayUnit = "Thousands";
}

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

getItemOrNullObject(key: string): Excel.Worksheet;

パラメーター

返品

注釈

API セット: ExcelApi 1.4

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/performance-optimization.yaml

/** Helper to create or recreate a worksheet. */
async function forceCreateSheet(workbook: Excel.Workbook, sheetName: string): Promise<Excel.Worksheet> {
  workbook.worksheets.getItemOrNullObject(sheetName).delete();
  await workbook.context.sync();
  return workbook.worksheets.add(sheetName);
}

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

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

パラメーター

返品

注釈

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();
});

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

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

パラメーター

返品

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

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

パラメーター

返品

例

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);
    }
});

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

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

パラメーター

返品

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

toJSON(): Excel.Interfaces.WorksheetCollectionData;

返品

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

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.");
});

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

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.");
});

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

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

イベントの種類

注釈

API セット: ExcelApi 1.8

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

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

イベントの種類

注釈

API セット: ExcelApi 1.9

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

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

イベントの種類

注釈

API セット: ExcelApi 1.10

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

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.");
});

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

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

イベントの種類

注釈

API セット: ExcelApi 1.7

ブック内のいずれかのワークシートの形式が変更されたときに発生します。

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

イベントの種類

注釈

API セット: ExcelApi 1.9

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

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

イベントの種類

注釈

API セット: ExcelApi 1.13

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

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

イベントの種類

注釈

API セット: ExcelApi 1.17

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

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

イベントの種類

注釈

API セット: ExcelApi 1.17

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

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

イベントの種類

注釈

API セット: ExcelApi 1.14

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

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

イベントの種類

注釈

API セット: ExcelApi 1.11

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

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

イベントの種類

注釈

API セット: ExcelApi 1.10

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

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

イベントの種類

注釈

API セット: ExcelApi 1.9

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

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

イベントの種類

注釈

API セット: ExcelApi 1.10

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

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

イベントの種類

注釈

API セット: ExcelApi 1.17

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-visibility.yaml

await Excel.run(async (context) => {
    // Register an event handler for visibility changes to any worksheet in the collection.
    context.workbook.worksheets.onVisibilityChanged.add(onWorksheetCollectionVisibilityChanged);

    await context.sync();
    console.log("Registered the worksheet collection visibility changed event handler.");
});

...

async function onWorksheetCollectionVisibilityChanged(args: Excel.WorksheetVisibilityChangedEventArgs) {
    console.log(`Worksheet collection event: Worksheet ${args.worksheetId} visibility changed from ${args.visibilityBefore} to ${args.visibilityAfter}.`);
}