Excel. Pivot Layout class

示例

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

await Excel.run(async (context) => {
  // Set the alt text for the displayed PivotTable.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.altTextTitle = "Farm Sales PivotTable";
  pivotLayout.altTextDescription = "A summary of fruit sales. It is pivoted on farm name, and fruit type. The aggregated data is both the sums of crates sold at the farms and the sums of crates sold wholesale.";
  console.log("Adding alt text. Check the PivotTable settings to see the changes.");

  await context.sync();
});

altTextTitle

数据透视表的替换文字标题。

altTextTitle: string;

属性值

string

注解

autoFormat

指定在刷新时还是移动字段时自动设置格式设置格式。

autoFormat: boolean;

属性值

boolean

注解

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

emptyCellText

如果 fillEmptyCells == true，则自动填充到数据透视表中的任何空单元格中的文本。请注意，如果 fillEmptyCells 设置为 false，则此值会保留，并且设置此值不会将该属性设置为 true。默认情况下，这是一个空字符串。

emptyCellText: string;

属性值

string

注解

示例

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

await Excel.run(async (context) => {
  // Set a default value for an empty cell in the PivotTable. This doesn't include cells left blank by the layout.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.emptyCellText = "--";

  // Set the text alignment to match the rest of the PivotTable.
  pivotLayout.getDataBodyRange().format.horizontalAlignment = Excel.HorizontalAlignment.right;
  await context.sync();
});

enableFieldList

指定是否可以在 UI 中显示字段列表。

enableFieldList: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.10 ]

fillEmptyCells

指定是否应使用填充数据透视表中的 emptyCellText空单元格。默认值为 false。请注意，当此属性设置为 false时，emptyCellText的值将保留。

fillEmptyCells: boolean;

属性值

boolean

注解

示例

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

await Excel.run(async (context) => {
  // Toggle whether empty cells are filled with a default value.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.load("fillEmptyCells");
  await context.sync();

  let fillToSet = !pivotLayout.fillEmptyCells;
  console.log(`Filling empty cells? - ${fillToSet}`);

  pivotLayout.fillEmptyCells = fillToSet;
  await context.sync();
});

layoutType

此属性指示数据透视表上的所有字段的 PivotLayoutType。如果字段状态不同，则为 null。

layoutType: Excel.PivotLayoutType | "Compact" | "Tabular" | "Outline";

属性值

Excel.PivotLayoutType | "Compact" | "Tabular" | "Outline"

注解

[ API 集：ExcelApi BETA (仅预览版) ]

示例

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

await Excel.run(async (context) => {
  // Change the PivotLayout.type to a new type.
  const pivotTable = context.workbook.worksheets.getActiveWorksheet().pivotTables.getItem("Farm Sales");
  pivotTable.layout.load("layoutType");
  await context.sync();

  // Cycle between the three layout types.
  if (pivotTable.layout.layoutType === "Compact") {
    pivotTable.layout.layoutType = "Outline";
  } else if (pivotTable.layout.layoutType === "Outline") {
    pivotTable.layout.layoutType = "Tabular";
  } else {
    pivotTable.layout.layoutType = "Compact";
  }

  await context.sync();
  console.log("Pivot layout is now " + pivotTable.layout.layoutType);
});

pivotStyle

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

应用于数据透视表的样式。

readonly pivotStyle: Excel.PivotTableStyle;

属性值

Excel.PivotTableStyle

注解

preserveFormatting

指定在通过透视、排序或更改页字段项等操作刷新或重新计算报表时是否保留格式。

preserveFormatting: boolean;

属性值

boolean

注解

示例

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

await Excel.run(async (context) => {
  // Set whether the PivotTable keeps the established format after it is refreshed and recalculated.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.load("preserveFormatting");
  await context.sync();

  let preserveFormattingToSet = !pivotLayout.preserveFormatting;
  console.log(`Preserve the formatting PivotTable after a refresh? - ${preserveFormattingToSet}`);

  pivotLayout.preserveFormatting = preserveFormattingToSet;
  await context.sync();
});

showColumnGrandTotals

指定数据透视表是否显示列的总计。

showColumnGrandTotals: boolean;

属性值

boolean

注解

示例

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

await Excel.run(async (context) => {
  // Turn the grand totals on and off for the rows and columns.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.load(["showRowGrandTotals", "showColumnGrandTotals"]);
  await context.sync();

  let showColumnTotals = !pivotLayout.showColumnGrandTotals;
  let showRowTotals = !pivotLayout.showRowGrandTotals;
  console.log(`Show column grand totals? - ${showColumnTotals}`);
  console.log(`Show row grand totals? - ${showRowTotals}`);

  pivotLayout.showColumnGrandTotals = showColumnTotals;
  pivotLayout.showRowGrandTotals = showRowTotals;

  await context.sync();
});

showFieldHeaders

指定数据透视表是否) 显示字段标题 (字段标题和筛选器下拉列表。

showFieldHeaders: boolean;

属性值

boolean

注解

示例

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

await Excel.run(async (context) => {
  // Turn the field headers on and off for the row and column hierarchies.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;
  pivotLayout.load("showFieldHeaders");
  await context.sync();

  let showHeaders = !pivotLayout.showFieldHeaders;
  console.log(`Show field headers? - ${showHeaders}`);
  pivotLayout.showFieldHeaders = showHeaders;
  await context.sync();
});

showRowGrandTotals

指定数据透视表是否显示行的总计。

showRowGrandTotals: boolean;

属性值

boolean

注解

示例

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

await Excel.run(async (context) => {
  // Turn the grand totals on and off for the rows and columns.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.load(["showRowGrandTotals", "showColumnGrandTotals"]);
  await context.sync();

  let showColumnTotals = !pivotLayout.showColumnGrandTotals;
  let showRowTotals = !pivotLayout.showRowGrandTotals;
  console.log(`Show column grand totals? - ${showColumnTotals}`);
  console.log(`Show row grand totals? - ${showRowTotals}`);

  pivotLayout.showColumnGrandTotals = showColumnTotals;
  pivotLayout.showRowGrandTotals = showRowTotals;

  await context.sync();
});

subtotalLocation

此属性指示 SubtotalLocationType 数据透视表上所有字段的。如果字段具有不同的状态，则为 null。

subtotalLocation: Excel.SubtotalLocationType | "AtTop" | "AtBottom" | "Off";

属性值

Excel.SubtotalLocationType | "AtTop" | "AtBottom" | "Off"

注解

方法详细信息

displayBlankLineAfterEachItem(display)

设置是否在每个项目后显示空白行。这是在数据透视表的全局级别设置的，并应用于单个透视字段。此函数将数据透视表中所有字段的设置覆盖为参数的值 display 。

displayBlankLineAfterEachItem(display: boolean): void;

参数

display: boolean

如果为 True，则会打开空白行显示设置。 False 会将其关闭。

void

注解

[ API 集：ExcelApi BETA (仅预览版) ]

示例

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

await Excel.run(async (context) => {
  // Add a blank row after each PivotItem in the row hierarchy.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.displayBlankLineAfterEachItem(true);
  console.log("Setting `PivotLayout.displayBlankLineAfterEachItem` to true.");

  await context.sync();
});

getCell(dataHierarchy, rowItems, columnItems)

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

根据数据层次结构以及各自层次结构的行和列项，获取数据透视表中的唯一单元格。返回的单元格是给定行和列的交集，其中包含来自给定层次结构的数据。此方法与在特定单元格上调用 getPivotItems 和 getDataHierarchy 相反。

getCell(dataHierarchy: DataPivotHierarchy | string, rowItems: Array<PivotItem | string>, columnItems: Array<PivotItem | string>): Excel.Range;

参数

dataHierarchy: Excel.DataPivotHierarchy | string

提供 dataHierarchy 要查找的数据项的。

rowItems: Array<Excel.PivotItem | string>

构成要查找的值的行轴上的 PivotItems。

columnItems: Array<Excel.PivotItem | string>

构成要查找的值的列轴上的 PivotItems。

Excel.Range

指定包含指定值的单个单元格的区域。

注解

getColumnLabelRange()

返回数据透视表列标签所在位置的区域。

getColumnLabelRange(): Excel.Range;

Excel.Range

注解

getDataBodyRange()

返回数据透视表数据值所在位置的区域。

getDataBodyRange(): Excel.Range;

Excel.Range

注解

示例

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

await Excel.run(async (context) => {
    const pivotTable = context.workbook.worksheets.getActiveWorksheet().pivotTables.getItem("Farm Sales");

    // The layout controls the ranges used by the PivotTable.
    const range = pivotTable.layout.getDataBodyRange();

    // Get all the data hierarchy totals.
    const grandTotalRange = range.getLastRow();
    grandTotalRange.load("address");
    await context.sync();
    
    // Use the wholesale and farm sale totals to make a final sum.
    const masterTotalRange = context.workbook.worksheets.getActiveWorksheet().getRange("B27:C27");
    masterTotalRange.formulas = [["All Crates", "=SUM(" + grandTotalRange.address + ")"]];
    await context.sync();
});

getDataHierarchy(cell)

获取 DataHierarchy，它用于计算数据透视表中指定区域内的值。

getDataHierarchy(cell: Range | string): Excel.DataPivotHierarchy;

参数

cell: Excel.Range | string

数据透视表数据正文中的单个单元格。

Excel.DataPivotHierarchy

用于计算指定单元格中的值的 DataPivotHierarchy 对象。

注解

getFilterAxisRange()

返回数据透视表筛选区的区域。

getFilterAxisRange(): Excel.Range;

Excel.Range

注解

getPivotItems(axis, cell)

从构成数据透视表中指定区域内的值的轴获取 PivotItems。

getPivotItems(axis: Excel.PivotAxis, cell: Range | string): Excel.PivotItemCollection;

参数

axis: Excel.PivotAxis

要从中获取 PivotItems 的轴。必须为“row”或“column”。

cell: Excel.Range | string

数据透视表的数据正文中的单个单元格。

Excel.PivotItemCollection

用于计算指定行中的值的 PivotItemCollection。

注解

getPivotItems(axisString, cell)

从构成数据透视表中指定区域内的值的轴获取 PivotItems。

getPivotItems(axisString: "Unknown" | "Row" | "Column" | "Data" | "Filter", cell: Range | string): Excel.PivotItemCollection;

参数

axisString: "Unknown" | "Row" | "Column" | "Data" | "Filter"

要从中获取 PivotItems 的轴。必须为“row”或“column”。

cell: Excel.Range | string

数据透视表的数据正文中的单个单元格。

Excel.PivotItemCollection

用于计算指定行中的值的 PivotItemCollection。

注解

getRange()

返回存在数据透视表的区域，不包括筛选区。

getRange(): Excel.Range;

Excel.Range

注解

getRowLabelRange()

返回数据透视表行标签所在位置的区域。

getRowLabelRange(): Excel.Range;

Excel.Range

注解

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.PivotLayoutLoadOptions): Excel.PivotLayout;

参数

options: Excel.Interfaces.PivotLayoutLoadOptions

提供要加载对象的属性的选项。

Excel.PivotLayout

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

propertyNames: string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

Excel.PivotLayout

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

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

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

Excel.PivotLayout

repeatAllItemLabels(repeatLabels)

设置数据透视表中所有字段的“重复所有项目标签”设置。

repeatAllItemLabels(repeatLabels: boolean): void;

参数

repeatLabels: boolean

如果为 True，则会打开标签重复显示设置。 False 会将其关闭。

void

注解

示例

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

await Excel.run(async (context) => {
  // Repeat the PivotItem labels for each row used by another level of the row hierarchy.
  const pivotTable = context.workbook.pivotTables.getItem("Farm Sales");
  const pivotLayout = pivotTable.layout;

  pivotLayout.repeatAllItemLabels(true);
  console.log("Setting `PivotLayout.repeatAllItemLabels` to true.");

  await context.sync();
});

set(properties, options)

同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。

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

参数

properties: Excel.Interfaces.PivotLayoutUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options: OfficeExtension.UpdateOptions

提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

void

set(properties)

基于现有的已加载对象，同时对对象设置多个属性。

set(properties: Excel.PivotLayout): void;

参数

properties: Excel.PivotLayout

void

setAutoSortOnCell(cell, sortBy)

将数据透视表设置为使用指定的单元格设置自动排序，以自动选择排序的所有条件和上下文。这与从 UI 应用自动排序的行为相同。

setAutoSortOnCell(cell: Range | string, sortBy: Excel.SortBy): void;

参数

cell: Excel.Range | string

一个单元格，用于获取用于应用自动排序的条件。

sortBy: Excel.SortBy

排序的方向。

void

注解

setAutoSortOnCell(cell, sortByString)

将数据透视表设置为使用指定的单元格设置自动排序，以自动选择排序的所有条件和上下文。这与从 UI 应用自动排序的行为相同。

setAutoSortOnCell(cell: Range | string, sortByString: "Ascending" | "Descending"): void;

参数

cell: Excel.Range | string

一个单元格，用于获取用于应用自动排序的条件。

sortByString: "Ascending" | "Descending"

排序的方向。

void

注解