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为自动填充到数据透视表中任何空单元格中的文本。请注意，如果设置为false ，则fillEmptyCells此值将保持不变，并且设置此值不会将该属性设置为 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>

行轴中构成要查找的值的数据透视项。

columnItems: Array<Excel.PivotItem | string>

列轴中构成要查找的值的数据透视项。

返回

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 的轴。必须为“行”或“列”。

cell: Excel.Range | string

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

返回

Excel.PivotItemCollection

用于计算指定行中值的数据透视项的 PivotItemCollection。

注解

getPivotItems(axis, cell)

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

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

参数

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

从中获取 PivotItems 的轴。必须为“行”或“列”。

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, sortBy)

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

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

参数

cell: Excel.Range | string

要使用的单个单元格获取应用自动排序的条件。

sortBy: "Ascending" | "Descending"

排序的方向。

返回

void

注解