Excel.PivotLayout class

表示数据透视表的视觉布局。

扩展

注解

[ API 集:ExcelApi 1.8 ]

属性

altTextDescription

数据透视表的替换文字说明。

替换文字提供数据透视表中包含的信息的基于文本的替代表示形式。 此信息对于可能无法看到或理解表格的视力或认知障碍人士非常有用。 游戏可以读给残障人士,并用于确定是否要听到内容的说明。

altTextTitle

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

替换文字提供数据透视表中包含的信息的基于文本的替代表示形式。 此信息对于可能无法看到或理解表格的视力或认知障碍人士非常有用。 游戏可以读给残障人士,并用于确定是否要听到内容的说明。

autoFormat

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

context

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

emptyCellText

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

enableFieldList

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

fillEmptyCells

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

layoutType

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

preserveFormatting

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

showColumnGrandTotals

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

showFieldHeaders

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

showRowGrandTotals

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

subtotalLocation

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

方法

displayBlankLineAfterEachItem(display)

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

getColumnLabelRange()

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

getDataBodyRange()

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

getDataHierarchy(cell)

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

getFilterAxisRange()

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

getPivotItems(axis, cell)

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

getPivotItems(axisString, cell)

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

getRange()

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

getRowLabelRange()

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

load(options)

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

load(propertyNames)

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

load(propertyNamesAndPaths)

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

repeatAllItemLabels(repeatLabels)

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

set(properties, options)

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

set(properties)

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

setAutoSortOnCell(cell, sortBy)

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

setAutoSortOnCell(cell, sortByString)

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

toJSON()

重写 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (,反过来又调用toJSON传递给它的 对象的 方法。) 而原始 Excel.PivotLayout 对象是 API 对象,toJSON该方法返回一个纯 JavaScript 对象, (类型为 Excel.Interfaces.PivotLayoutData) ,该对象包含从原始对象加载的任何子属性的浅表副本。

属性详细信息

altTextDescription

数据透视表的替换文字说明。

替换文字提供数据透视表中包含的信息的基于文本的替代表示形式。 此信息对于可能无法看到或理解表格的视力或认知障碍人士非常有用。 游戏可以读给残障人士,并用于确定是否要听到内容的说明。

altTextDescription: string;

属性值

string

注解

[ API 集:ExcelApi 1.13 ]

示例

// 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

注解

[ API 集:ExcelApi 1.13 ]

autoFormat

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

autoFormat: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.9 ]

context

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

context: RequestContext;

属性值

emptyCellText

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

emptyCellText: string;

属性值

string

注解

[ API 集:ExcelApi 1.13 ]

示例

// 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

注解

[ API 集:ExcelApi 1.13 ]

示例

// 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 1.8 ]

示例

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

preserveFormatting

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

preserveFormatting: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.9 ]

示例

// 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

注解

[ API 集:ExcelApi 1.8 ]

示例

// 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

注解

[ API 集:ExcelApi 1.13 ]

示例

// 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

注解

[ API 集:ExcelApi 1.8 ]

示例

// 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"

注解

[ API 集:ExcelApi 1.8 ]

方法详细信息

displayBlankLineAfterEachItem(display)

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

displayBlankLineAfterEachItem(display: boolean): void;

参数

display

boolean

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

返回

void

注解

[ API 集:ExcelApi 1.13 ]

示例

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

getColumnLabelRange()

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

getColumnLabelRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.8 ]

getDataBodyRange()

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

getDataBodyRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.8 ]

示例

// 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

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

返回

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

注解

[ API 集:ExcelApi 1.9 ]

getFilterAxisRange()

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

getFilterAxisRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.8 ]

getPivotItems(axis, cell)

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

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

参数

axis
Excel.PivotAxis

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

cell

Excel.Range | string

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

返回

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

注解

[ API 集:ExcelApi 1.9 ]

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

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

返回

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

注解

[ API 集:ExcelApi 1.9 ]

getRange()

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

getRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.8 ]

getRowLabelRange()

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

getRowLabelRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.8 ]

load(options)

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

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

参数

options
Excel.Interfaces.PivotLayoutLoadOptions

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

返回

load(propertyNames)

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

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

参数

propertyNames

string | string[]

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

返回

load(propertyNamesAndPaths)

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

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

参数

propertyNamesAndPaths

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

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

返回

repeatAllItemLabels(repeatLabels)

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

repeatAllItemLabels(repeatLabels: boolean): void;

参数

repeatLabels

boolean

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

返回

void

注解

[ API 集:ExcelApi 1.13 ]

示例

// 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

注解

[ API 集:ExcelApi 1.9 ]

setAutoSortOnCell(cell, sortByString)

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

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

参数

cell

Excel.Range | string

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

sortByString

"Ascending" | "Descending"

排序的方向。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

toJSON()

重写 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (,反过来又调用toJSON传递给它的 对象的 方法。) 而原始 Excel.PivotLayout 对象是 API 对象,toJSON该方法返回一个纯 JavaScript 对象, (类型为 Excel.Interfaces.PivotLayoutData) ,该对象包含从原始对象加载的任何子属性的浅表副本。

toJSON(): Excel.Interfaces.PivotLayoutData;

返回