Excel. Worksheet class

例

// Get a Worksheet object by its name and activate it.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

プロパティ

autoFilter	ワークシートの `AutoFilter` オブジェクトを表します。
charts	ワークシートの一部であるグラフのコレクションを返します。
comments	ワークシート上のすべての Comments オブジェクトの集まりを返します。
context	オブジェクトに関連付けられている要求コンテキスト。これにより、アドインのプロセスが Office ホストアプリケーションのプロセスに接続されます。
enableCalculation	Excel が必要に応じてワークシートを再計算するかどうかを決定します。 True を指定すると、必要に応じてワークシートが再計算されます。 False を指定すると、Excel でシートが再計算されません。
freezePanes	ワークシート上の固定ウィンドウを操作するために使用できるオブジェクトを取得します。
horizontalPageBreaks	ワークシートの水平改ページをまとめて取得します。このコレクションには、手動の改ページのみが含まれます。
id	指定されたブックのワークシートを一意に識別する値を返します。この識別子の値は、ワークシートの名前を変更したり移動したりしても同じままです。
name	ワークシートの表示名。名前は 32 文字未満にする必要があります。
names	現在のワークシートにスコープされている名前のコレクション。
pageLayout	ワークシートの `PageLayout` オブジェクトを取得します。
pivotTables	ワークシートの一部になっているピボットテーブルのコレクション。
position	0 を起点とした、ブック内のワークシートの位置。
protection	ワークシートのシート保護オブジェクトを返します。
shapes	ワークシート上のすべての Shape オブジェクトをまとめて返します。
showGridlines	グリッド線をユーザーに表示するかどうかを指定します。
showHeadings	見出しをユーザーに表示するかどうかを指定します。
slicers	ワークシートの一部であるスライサーのコレクションを返します。
standardHeight	ワークシート内のすべての行の標準 (既定) の高さ (ポイント数) を返します。
standardWidth	ワークシート内のすべての列の標準 (既定) 幅を指定します。列幅の単位は、標準スタイルの 1 文字分の幅に相当します。プロポーショナルフォントでは、数字の 0 の幅が列幅の単位になります。
tabColor	ワークシートのタブの色。タブの色を取得するときに、ワークシートが非表示の場合、値は `null`されます。ワークシートが表示されていても、タブの色が auto に設定されている場合は、空の文字列が返されます。それ以外の場合、プロパティは #RRGGBB 形式 ("FFA500" など) の色に設定されます。色を設定するときは、空の文字列を使用して "自動" 色を設定するか、それ以外の場合は実際の色を設定します。
tables	ワークシートの一部になっているグラフのコレクション。
verticalPageBreaks	ワークシートの垂直改ページをまとめて取得します。このコレクションには、手動の改ページのみが含まれます。
visibility	ワークシートの可視性。

メソッド

activate()	Excel UI でワークシートをアクティブにします。
calculate(markAllDirty)	ワークシート上のすべてのセルを計算します。
copy(positionType, relativeTo)	ワークシートをコピーし、指定した位置に配置します。
copy(positionTypeString, relativeTo)	ワークシートをコピーし、指定した位置に配置します。
delete()	ブックからワークシートを削除します。ワークシートの可視性が "VeryHidden" に設定されている場合、削除操作は `InvalidOperation` 例外で失敗します。削除する前に、最初にその可視性を非表示または表示に変更する必要があります。
findAll(text, criteria)	指定した条件に基づいて指定された文字列のすべての出現箇所を検索し、1 つまたは複数の四角形の範囲を含む `RangeAreas` オブジェクトとして返します。
findAllOrNullObject(text, criteria)	指定した条件に基づいて指定された文字列のすべての出現箇所を検索し、1 つまたは複数の四角形の範囲を含む `RangeAreas` オブジェクトとして返します。
getCell(row, column)	行番号と列番号に基づいて、1 つのセルを含む `Range` オブジェクトを取得します。セルは、ワークシートのグリッド内に留まる限り、親範囲の範囲外にすることができます。
getNext(visibleOnly)	このワークシートに続くワークシートを取得します。このワークシートの後にワークシートがない場合、このメソッドはエラーをスローします。
getNextOrNullObject(visibleOnly)	このワークシートに続くワークシートを取得します。このワークシートの後にワークシートがない場合、このメソッドは `isNullObject` プロパティを `true` に設定したオブジェクトを返します。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getPrevious(visibleOnly)	このワークシートの前にあるワークシートを取得します。以前のワークシートがない場合、このメソッドはエラーをスローします。
getPreviousOrNullObject(visibleOnly)	このワークシートの前にあるワークシートを取得します。以前のワークシートがない場合、このメソッドは `isNullObject` プロパティを `true` に設定したオブジェクトを返します。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getRange(address)	アドレスまたは名前で指定された単一の四角形のセルブロックを表す、 `Range` オブジェクトを取得します。
getRangeByIndexes(startRow, startColumn, rowCount, columnCount)	特定の行インデックスと列インデックスから始まり、特定の数の行と列にまたがる `Range` オブジェクトを取得します。
getRanges(address)	アドレスまたは名前で指定された四角形の範囲の 1 つ以上のブロックを表す、 `RangeAreas` オブジェクトを取得します。
getUsedRange(valuesOnly)	使用範囲とは、値または書式設定が割り当たっているすべてのセルを包含する最小の範囲です。ワークシート全体が空白の場合、この関数は左上のセルを返します (つまり、エラーはスローされません )。
getUsedRangeOrNullObject(valuesOnly)	使用範囲とは、値または書式設定が割り当たっているすべてのセルを包含する最小の範囲です。ワークシート全体が空白の場合、このメソッドは `isNullObject` プロパティを `true` に設定したオブジェクトを返します。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
load(options)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
load(propertyNames)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
load(propertyNamesAndPaths)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
replaceAll(text, replacement, criteria)	現在のワークシート内で、指定された条件に基づき、指定された文字列を検索し、置換します。
set(properties, options)	オブジェクトの複数のプロパティを同時に設定します。適切なプロパティを持つプレーンオブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。
set(properties)	既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。
showOutlineLevels(rowLevels, columnLevels)	行グループまたは列グループをアウトラインレベル別に表示します。グループのアウトラインを作成し、ワークシート内のデータの一覧を要約します。 `rowLevels`パラメーターと `columnLevels` パラメーターは、アウトラインを表示するレベルの数を指定します。許容される引数の範囲は 0 ~ 8 です。値が 0 の場合、現在の表示は変更されません。現在のレベル数より大きい値は、すべてのレベルを表示します。
toJSON()	API オブジェクトが`JSON.stringify()`に渡されたときにより便利な出力を提供するために、JavaScript `toJSON()` メソッドをオーバーライドします。 (`JSON.stringify`、それに渡されるオブジェクトの `toJSON` メソッドを呼び出します)。元の `Excel.Worksheet` オブジェクトは API オブジェクトですが、 `toJSON` メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( `Excel.Interfaces.WorksheetData` として型指定) を返します。

イベント

onActivated	ワークシートがアクティブになったときに発生します。
onCalculated	ワークシートが計算されるときに発生します。
onChanged	特定のワークシートでデータが変更されたときに発生します。
onColumnSorted	1 つ以上の列を並べ替えたときに発生します。これは、左から右への並べ替え操作の結果として発生します。
onDeactivated	ワークシートが非アクティブ化されたときに発生します。
onFormatChanged	フォーマットが特定のワークシートで変更されたときに発生します。
onRowSorted	1 つ以上の行を並べ替えたときに発生します。これは、上から下に並べ替えを実行したときに発生します。
onSelectionChanged	特定のワークシートで選択内容が変更されたときに発生します。
onSingleClicked	ワークシートで左クリックまたはタップされたアクションが発生したときに発生します。このイベントは、次の場合にクリックしても発生しません。ユーザーはマウスをドラッグして複数選択します。数式参照でセル引数が選択されている場合、ユーザーはモードでセルを選択します。

プロパティの詳細

autoFilter

ワークシートの AutoFilter オブジェクトを表します。

readonly autoFilter: Excel.AutoFilter;

プロパティ値

Excel.AutoFilter

注釈

例

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

// This function adds a percentage AutoFilter to the active worksheet 
// and applies the filter to a column of the used range.
await Excel.run(async (context) => {
    // Retrieve the active worksheet and the used range on that worksheet.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const farmData = sheet.getUsedRange();

    // Add a filter that will only show the rows with the top 50% of values in column 3.
    sheet.autoFilter.apply(farmData, 3, {
        criterion1: "50",
        filterOn: Excel.FilterOn.topPercent
    });

    await context.sync();
});

charts

ワークシートの一部であるグラフのコレクションを返します。

readonly charts: Excel.ChartCollection;

プロパティ値

Excel.ChartCollection

注釈

comments

ワークシート上のすべての Comments オブジェクトの集まりを返します。

readonly comments: Excel.CommentCollection;

プロパティ値

Excel.CommentCollection

注釈

context

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

context: RequestContext;

プロパティ値

Excel.RequestContext

enableCalculation

Excel が必要に応じてワークシートを再計算するかどうかを決定します。 True を指定すると、必要に応じてワークシートが再計算されます。 False を指定すると、Excel でシートが再計算されません。

enableCalculation: boolean;

プロパティ値

boolean

注釈

freezePanes

ワークシート上の固定ウィンドウを操作するために使用できるオブジェクトを取得します。

readonly freezePanes: Excel.WorksheetFreezePanes;

プロパティ値

Excel.WorksheetFreezePanes

注釈

horizontalPageBreaks

ワークシートの水平改ページをまとめて取得します。このコレクションには、手動の改ページのみが含まれます。

readonly horizontalPageBreaks: Excel.PageBreakCollection;

プロパティ値

Excel.PageBreakCollection

注釈

id

指定されたブックのワークシートを一意に識別する値を返します。この識別子の値は、ワークシートの名前を変更したり移動したりしても同じままです。

readonly id: string;

プロパティ値

string

注釈

name

ワークシートの表示名。名前は 32 文字未満にする必要があります。

name: string;

プロパティ値

string

注釈

names

現在のワークシートにスコープされている名前のコレクション。

readonly names: Excel.NamedItemCollection;

プロパティ値

Excel.NamedItemCollection

注釈

[ API セット: ExcelApi 1.4 ]

pageLayout

ワークシートの PageLayout オブジェクトを取得します。

readonly pageLayout: Excel.PageLayout;

プロパティ値

Excel.PageLayout

注釈

pivotTables

ワークシートの一部になっているピボットテーブルのコレクション。

readonly pivotTables: Excel.PivotTableCollection;

プロパティ値

Excel.PivotTableCollection

注釈

[ API セット: ExcelApi 1.3 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  // Get the names of all the PivotTables in the current worksheet.
  const pivotTables = context.workbook.worksheets.getActiveWorksheet().pivotTables;
  pivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current worksheet:")
  pivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

position

0 を起点とした、ブック内のワークシートの位置。

position: number;

プロパティ値

number

注釈

例

// Set worksheet position.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.position = 2;
    await context.sync(); 
});

protection

ワークシートのシート保護オブジェクトを返します。

readonly protection: Excel.WorksheetProtection;

プロパティ値

Excel.WorksheetProtection

注釈

[ API セット: ExcelApi 1.2 ]

例

// Unprotecting a worksheet with unprotect() will remove all 
// WorksheetProtectionOptions options applied to a worksheet.
// To remove only a subset of WorksheetProtectionOptions use the 
// protect() method and set the options you wish to remove to true.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sheet1");
  sheet.protection.protect({
    allowInsertRows: false, // Protect row insertion
    allowDeleteRows: true // Unprotect row deletion
  });
});

shapes

ワークシート上のすべての Shape オブジェクトをまとめて返します。

readonly shapes: Excel.ShapeCollection;

プロパティ値

Excel.ShapeCollection

注釈

showGridlines

グリッド線をユーザーに表示するかどうかを指定します。

showGridlines: boolean;

プロパティ値

boolean

注釈

[ API セット: ExcelApi 1.8 ]

例

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

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

    await context.sync();
});

showHeadings

見出しをユーザーに表示するかどうかを指定します。

showHeadings: boolean;

プロパティ値

boolean

注釈

[ API セット: ExcelApi 1.8 ]

slicers

ワークシートの一部であるスライサーのコレクションを返します。

readonly slicers: Excel.SlicerCollection;

プロパティ値

Excel.SlicerCollection

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-slicer.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Pivot");
    const slicer = sheet.slicers.add(
        "Farm Sales", /* The slicer data source. For PivotTables, this can be the PivotTable object reference or name. */
        "Type" /* The field in the data source to filter by. For PivotTables, this can be a PivotField object reference or ID. */
    );
    slicer.name = "Fruit Slicer";
    await context.sync();
});

standardHeight

ワークシート内のすべての行の標準 (既定) の高さ (ポイント数) を返します。

readonly standardHeight: number;

プロパティ値

number

注釈

standardWidth

ワークシート内のすべての列の標準 (既定) 幅を指定します。列幅の単位は、標準スタイルの 1 文字分の幅に相当します。プロポーショナルフォントでは、数字の 0 の幅が列幅の単位になります。

standardWidth: number;

プロパティ値

number

注釈

tabColor

ワークシートのタブの色。タブの色を取得するときに、ワークシートが非表示の場合、値は nullされます。ワークシートが表示されていても、タブの色が auto に設定されている場合は、空の文字列が返されます。それ以外の場合、プロパティは #RRGGBB 形式 ("FFA500" など) の色に設定されます。色を設定するときは、空の文字列を使用して "自動" 色を設定するか、それ以外の場合は実際の色を設定します。

tabColor: string;

プロパティ値

string

注釈

例

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

await Excel.run(async (context) => {
    const activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.tabColor = "#FF0000";

    await context.sync();
});

tables

ワークシートの一部になっているグラフのコレクション。

readonly tables: Excel.TableCollection;

プロパティ値

Excel.TableCollection

注釈

verticalPageBreaks

ワークシートの垂直改ページをまとめて取得します。このコレクションには、手動の改ページのみが含まれます。

readonly verticalPageBreaks: Excel.PageBreakCollection;

プロパティ値

Excel.PageBreakCollection

注釈

[ API セット: 読み取り可視性用の ExcelApi 1.1、設定用の 1.2。 ]

visibility

ワークシートの可視性。

visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";

プロパティ値

Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden"

注釈

メソッドの詳細

activate()

Excel UI でワークシートをアクティブにします。

activate(): void;

戻り値

void

注釈

例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

calculate(markAllDirty)

ワークシート上のすべてのセルを計算します。

calculate(markAllDirty: boolean): void;

パラメーター

markAllDirty: boolean

True を指定すると、すべてダーティとしてマークされます。

戻り値

void

注釈

[ API セット: ExcelApi 1.6 ]

copy(positionType, relativeTo)

ワークシートをコピーし、指定した位置に配置します。

copy(positionType?: Excel.WorksheetPositionType, relativeTo?: Excel.Worksheet): Excel.Worksheet;

パラメーター

positionType: Excel.WorksheetPositionType

新しく作成されたワークシートを配置するブック内の場所。既定値は "None" で、ワークシートの先頭にワークシートが挿入されます。

relativeTo: Excel.Worksheet

新しく作成されたワークシートの位置を決定する既存のワークシート。これは、 positionType が "Before" または "After" の場合にのみ必要です。

戻り値

Excel.Worksheet

新しく作成されたワークシート。

注釈

例

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

await Excel.run(async (context) => {

    let myWorkbook = context.workbook;
    let sampleSheet = myWorkbook.worksheets.getActiveWorksheet();
    let copiedSheet = sampleSheet.copy("End")

    sampleSheet.load("name");
    copiedSheet.load("name");

    await context.sync();

    console.log("'" + sampleSheet.name + "' was copied to '" + copiedSheet.name + "'")
});

copy(positionTypeString, relativeTo)

ワークシートをコピーし、指定した位置に配置します。

copy(positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Excel.Worksheet): Excel.Worksheet;

パラメーター

positionTypeString: "None" | "Before" | "After" | "Beginning" | "End"

新しく作成されたワークシートを配置するブック内の場所。既定値は "None" で、ワークシートの先頭にワークシートが挿入されます。

relativeTo: Excel.Worksheet

新しく作成されたワークシートの位置を決定する既存のワークシート。これは、 positionType が "Before" または "After" の場合にのみ必要です。

戻り値

Excel.Worksheet

新しく作成されたワークシート。

注釈

delete()

ブックからワークシートを削除します。ワークシートの可視性が "VeryHidden" に設定されている場合、削除操作は InvalidOperation 例外で失敗します。削除する前に、最初にその可視性を非表示または表示に変更する必要があります。

delete(): void;

戻り値

void

注釈

例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.delete();
    await context.sync(); 
});

findAll(text, criteria)

指定した条件に基づいて指定された文字列のすべての出現箇所を検索し、1 つまたは複数の四角形の範囲を含む RangeAreas オブジェクトとして返します。

findAll(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

パラメーター

text: string

検索する文字列。

criteria: Excel.WorksheetSearchCriteria

検索がセル全体と一致する必要があるか、大文字と小文字が区別されるかなど、追加の検索条件。

戻り値

Excel.RangeAreas

検索条件に一致する 1 つ以上の四角形の範囲を含む RangeAreas オブジェクト。この条件を満たすセルがない場合は、 ItemNotFound エラーがスローされます。

注釈

findAllOrNullObject(text, criteria)

findAllOrNullObject(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

パラメーター

text: string

検索する文字列。

criteria: Excel.WorksheetSearchCriteria

検索がセル全体と一致する必要があるか、大文字と小文字が区別されるかなど、追加の検索条件。

戻り値

Excel.RangeAreas

検索条件に一致する 1 つ以上の四角形の範囲を含む RangeAreas オブジェクト。一致しない場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

注釈

例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const foundRanges = sheet.findAllOrNullObject("Complete", {
        completeMatch: true,
        matchCase: false
    });

    await context.sync();

    if (foundRanges.isNullObject) {
        console.log("No complete projects");
    } else {
        foundRanges.format.fill.color = "green"
    }
});

getCell(row, column)

行番号と列番号に基づいて、1 つのセルを含む Range オブジェクトを取得します。セルは、ワークシートのグリッド内に留まる限り、親範囲の範囲外にすることができます。

getCell(row: number, column: number): Excel.Range;

パラメーター

row: number

取得するセルの行番号。 0 を起点とする番号になります。

column: number

取得するセルの列番号。 0 を起点とする番号になります。

戻り値

Excel.Range

注釈

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const cell = worksheet.getCell(0,0);
    cell.load('address');
    await context.sync();

    console.log(cell.address);
});

getNext(visibleOnly)

このワークシートに続くワークシートを取得します。このワークシートの後にワークシートがない場合、このメソッドはエラーをスローします。

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

パラメーター

visibleOnly: boolean

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

戻り値

Excel.Worksheet

注釈

例

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

getNextOrNullObject(visibleOnly)

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

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

パラメーター

visibleOnly: boolean

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

戻り値

Excel.Worksheet

注釈

getPrevious(visibleOnly)

このワークシートの前にあるワークシートを取得します。以前のワークシートがない場合、このメソッドはエラーをスローします。

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

パラメーター

visibleOnly: boolean

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

戻り値

Excel.Worksheet

注釈

例

// 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;
    const currentSheet = sheets.getActiveWorksheet();
    const previousYearSheet = currentSheet.getPrevious();
    const currentTaxDueRange = currentSheet.getRange("C2");
    const previousTaxDueRange = previousYearSheet.getRange("C2");

    currentSheet.load("name");
    previousYearSheet.load("name");
    currentTaxDueRange.load("text");
    previousTaxDueRange.load("text");

    await context.sync();

    let currentYear = currentSheet.name.substr(5, 4);
    let previousYear = previousYearSheet.name.substr(5, 4);
    console.log("Two Year Tax Due Comparison", `Tax due for ${currentYear} was ${currentTaxDueRange.text[0][0]}\nTax due for ${previousYear} was ${previousTaxDueRange.text[0][0]}`)

    await context.sync();
});

getPreviousOrNullObject(visibleOnly)

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

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

パラメーター

visibleOnly: boolean

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

戻り値

Excel.Worksheet

注釈

getRange(address)

アドレスまたは名前で指定された単一の四角形のセルブロックを表す、 Range オブジェクトを取得します。

getRange(address?: string): Excel.Range;

パラメーター

address: string

省略可能。範囲のアドレスまたは名前を表す文字列。たとえば、"A1:B2" です。指定されていない場合は、ワークシート全体の範囲が返されます。

戻り値

Excel.Range

注釈

例

// Use the range address to get the range object.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

特定の行インデックスと列インデックスから始まり、特定の数の行と列にまたがる Range オブジェクトを取得します。

getRangeByIndexes(startRow: number, startColumn: number, rowCount: number, columnCount: number): Excel.Range;

パラメーター

startRow: number

開始行 (インデックスが 0)。

startColumn: number

開始列 (インデックスが 0)。

rowCount: number

範囲に含める行の数。

columnCount: number

範囲に含める列の数。

戻り値

Excel.Range

注釈

getRanges(address)

アドレスまたは名前で指定された四角形の範囲の 1 つ以上のブロックを表す、 RangeAreas オブジェクトを取得します。

getRanges(address?: string): Excel.RangeAreas;

パラメーター

address: string

省略可能。コンマ区切りまたはセミコロンで区切られたアドレスまたは個々の範囲の名前を含む文字列。たとえば、"A1:B2、A5:B5" や "A1:B2;A5:B5" 指定しない場合は、ワークシート全体の RangeAreas オブジェクトが返されます。

戻り値

Excel.RangeAreas

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const specifiedRanges = sheet.getRanges("D3:D5, G3:G5");
    specifiedRanges.format.fill.color = "pink";

    await context.sync();
})

getUsedRange(valuesOnly)

使用範囲とは、値または書式設定が割り当たっているすべてのセルを包含する最小の範囲です。ワークシート全体が空白の場合、この関数は左上のセルを返します (つまり、エラーはスロー されません )。

getUsedRange(valuesOnly?: boolean): Excel.Range;

パラメーター

valuesOnly: boolean

省略可能。 true 場合は、値を持つセルのみを使用セルと見なします (書式設定は無視されます)。 [Api set: ExcelApi 1.2]

戻り値

Excel.Range

注釈

例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    const usedRange = worksheet.getUsedRange();
    usedRange.load('address');
    await context.sync();
    
    console.log(usedRange.address);
});

getUsedRangeOrNullObject(valuesOnly)

使用範囲とは、値または書式設定が割り当たっているすべてのセルを包含する最小の範囲です。ワークシート全体が空白の場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

パラメーター

valuesOnly: boolean

省略可能。値の入っているセルのみを使用セルと見なします。

戻り値

Excel.Range

注釈

[ API セット: ExcelApi 1.4 ]

load(options)

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

load(options?: Excel.Interfaces.WorksheetLoadOptions): Excel.Worksheet;

パラメーター

options: Excel.Interfaces.WorksheetLoadOptions

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

戻り値

Excel.Worksheet

load(propertyNames)

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

パラメーター

propertyNames: string | string[]

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

戻り値

Excel.Worksheet

例

// Get worksheet properties based on sheet name.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.load('position')
    await context.sync();
    
    console.log(worksheet.position);
});

load(propertyNamesAndPaths)

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Worksheet;

パラメーター

propertyNamesAndPaths: { select?: string; expand?: string; }

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

戻り値

Excel.Worksheet

replaceAll(text, replacement, criteria)

現在のワークシート内で、指定された条件に基づき、指定された文字列を検索し、置換します。

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

パラメーター

text: string

検索する文字列。

replacement: string

元の文字列を置き換える文字列。

criteria: Excel.ReplaceCriteria

追加の置き換え条件。

戻り値

OfficeExtension.ClientResult<number>

実行された置換の数。

注釈

set(properties, options)

オブジェクトの複数のプロパティを同時に設定します。適切なプロパティを持つプレーンオブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。

set(properties: Interfaces.WorksheetUpdateData, options?: OfficeExtension.UpdateOptions): void;

パラメーター

properties: Excel.Interfaces.WorksheetUpdateData

メソッドが呼び出されるオブジェクトのプロパティに等形的に構造化されたプロパティを持つ JavaScript オブジェクト。

options: OfficeExtension.UpdateOptions

properties オブジェクトが読み取り専用プロパティを設定しようとした場合にエラーを抑制するオプションを提供します。

戻り値

void

例

// Set the color and name of the current worksheet.
await Excel.run(async (context) => {
  const activeSheet = context.workbook.worksheets.getActiveWorksheet();
  activeSheet.set({
    tabColor: "yellow",
    name: "MySheet"
  });

  await context.sync();
});

set(properties)

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。

set(properties: Excel.Worksheet): void;

パラメーター

properties: Excel.Worksheet

戻り値

void

showOutlineLevels(rowLevels, columnLevels)

行グループまたは列グループをアウトラインレベル別に表示します。グループのアウトラインを作成し、ワークシート内のデータの一覧を要約します。 rowLevelsパラメーターと columnLevels パラメーターは、アウトラインを表示するレベルの数を指定します。許容される引数の範囲は 0 ~ 8 です。値が 0 の場合、現在の表示は変更されません。現在のレベル数より大きい値は、すべてのレベルを表示します。

showOutlineLevels(rowLevels: number, columnLevels: number): void;

パラメーター

rowLevels: number

表示するアウトラインの行レベルの数。

columnLevels: number

表示するアウトラインの列レベルの数。

戻り値

void

注釈

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

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

    // This shows the top 3 outline levels; collapsing any additional sublevels.
    sheet.showOutlineLevels(3, 3);
    await context.sync();
});

toJSON()

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

toJSON(): Excel.Interfaces.WorksheetData;

戻り値

Excel.Interfaces.WorksheetData

イベントの詳細

onActivated

ワークシートがアクティブになったときに発生します。

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>

例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onActivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The activated worksheet ID is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

onCalculated

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

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

イベントの種類

注釈

[ API セット: ExcelApi 1.8 ]

例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onCalculated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The worksheet has recalculated.");
            await context.sync();
        });
    });
    await context.sync();
});

onChanged

特定のワークシートでデータが変更されたときに発生します。

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

イベントの種類

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

注釈

OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>

例

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

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onChanged.add(onChange);
    await context.sync();

    console.log("Added a worksheet-level data-changed event handler.");
});

onColumnSorted

1 つ以上の列を並べ替えたときに発生します。これは、左から右への並べ替え操作の結果として発生します。

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

await Excel.run(async (context) => {
    console.log("Adding column handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a column has been moved as the result of a sort action.
    sheet.onColumnSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Column sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

onDeactivated

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

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onDeactivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The deactivated worksheet is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

onFormatChanged

フォーマットが特定のワークシートで変更されたときに発生します。

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>

onRowSorted

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

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

await Excel.run(async (context) => {
    console.log("Adding row handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a row has been moved as the result of a sort action.
    sheet.onRowSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Row sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

onSelectionChanged

特定のワークシートで選択内容が変更されたときに発生します。

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

イベントの種類

注釈

OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>

例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onSelectionChanged.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The selected range has changed to: " + event.address);
            await context.sync();
        });
    });
    await context.sync();
});

onSingleClicked

ワークシートで左クリックまたはタップされたアクションが発生したときに発生します。このイベントは、次の場合にクリックしても発生しません。

ユーザーはマウスをドラッグして複数選択します。
数式参照でセル引数が選択されている場合、ユーザーはモードでセルを選択します。

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

イベントの種類

注釈