跳转到内容
PlaidCloud

PlaidXL 自定义函数

PlaidXL 为 Excel 添加了可将 PlaidCloud 数据直接读入单元格的函数。在单元格中输入 =PLAIDXL.，Excel 的自动完成会列出这些函数，并附有每个参数的简短说明。

分组 函数 用途
列表 LIST_PROJECTS、TABLE.TBL_LIST、TABLE.GET_COLUMNS、DIMENSION.DIM_LIST 查看可用于构建的内容
表 TABLE.GET_TABLE 将整个表读入一个区域
层次结构 DIMENSION.GET_DIMENSION、DRILL 将维度的节点排布为报表行
值 CELL、CELLS 为任意节点组合计算汇总值
构建块 REPR.TABLE_REPR、REPR.MEASURE、REPR.MEASURES、REPR.MEASURE_TYPE、REPR.DIMENSION_REPR、REPR.DRILL_KEY 描述 CELL、CELLS 和 DRILL 所使用的表、度量值、聚合方式、节点和钻取深度

使用自定义函数构建报表展示了这些函数如何配合使用。

函数的工作方式

Section titled “函数的工作方式”
  • 先登录。 这些函数使用您的 PlaidCloud 登录信息读取数据，因此在使用之前请先在任务窗格中登录。
  • 从所选项目读取。 每个函数都从任务窗格中选定的项目读取数据。GET_TABLE、TBL_LIST 和 DIM_LIST 还接受一个可选的项目 ID，可在不更改所选项目的情况下读取另一个项目。所选项目由您打开的所有工作簿共用。
  • 结果会溢出。 返回列表或表的函数会填充其下方（或右侧）的单元格。请为结果留出空间；如果有内容挡住，Excel 会显示 #SPILL! 错误。
  • 重新计算以获取变更。 PlaidXL 公式在其某个参数变化时会重新获取数据。若要获取 PlaidCloud 中的新数据，或任务窗格中选定的另一个项目，请强制完全重新计算：在 Windows 上，按 Ctrl+Alt+F9。Refresh All Tables 刷新的是已检索的表，而不是公式。
  • 使用准确的名称。 输入的表、列、维度和节点名称必须与 PlaidCloud 中显示的完全一致。

方括号中的参数为可选参数。

列表

Section titled “列表”

LIST_PROJECTS

Section titled “LIST_PROJECTS”

=PLAIDXL.LIST_PROJECTS([horizontal])

列出您可以打开的项目名称，按名称排序。

  • horizontal — 设为 TRUE 时横向排列成一行。默认为 FALSE，即一列。

TBL_LIST

Section titled “TBL_LIST”

=PLAIDXL.TABLE.TBL_LIST([project_id], [horizontal])

列出项目中的表名称，按名称排序。

  • project_id — 要读取的项目。默认为任务窗格中选定的项目。
  • horizontal — 设为 TRUE 时横向排列成一行。默认为 FALSE，即一列。

GET_COLUMNS

Section titled “GET_COLUMNS”

=PLAIDXL.TABLE.GET_COLUMNS(table_name, [column_filter], [orientation])

列出所选项目中某个表的列名。

  • table_name — 表在 PlaidCloud 中的名称。
  • column_filter — 数据类型，例如 "text"，仅列出该类型的列。省略则列出所有列。
  • orientation — "vertical"（默认）表示一列，"horizontal" 表示一行。

DIM_LIST

Section titled “DIM_LIST”

=PLAIDXL.DIMENSION.DIM_LIST([project_id], [horizontal])

列出项目中的维度名称。

  • project_id — 要读取的项目。默认为任务窗格中选定的项目。
  • horizontal — 设为 TRUE 时横向排列成一行。默认为 FALSE，即一列。

表

Section titled “表”

GET_TABLE

Section titled “GET_TABLE”

=PLAIDXL.TABLE.GET_TABLE(table_name, [project_id], [limit])

返回表的行及标题行，从公式所在单元格开始溢出。空值以空白单元格返回。

  • table_name — 表在 PlaidCloud 中的名称。
  • project_id — 要读取的项目。默认为任务窗格中选定的项目。
  • limit — 最多返回的行数。默认为 1,048,575，即工作表在标题行之下最多可容纳的行数。

GET_TABLE 会返回所有列。若要选择列或筛选行，请改为在任务窗格中检索该表。

层次结构

Section titled “层次结构”

GET_DIMENSION

Section titled “GET_DIMENSION”

=PLAIDXL.DIMENSION.GET_DIMENSION(dimension_name, start_node, [hierarchy], [orientation], [generation_limit])

从 start_node 开始，沿其后代向下排布维度的节点。每一代比其父节点多缩进四个空格，并且可通过 Excel 分级显示组折叠和展开每个层级。

  • dimension_name — 维度的名称，或其在项目中的路径。
  • start_node — 起始节点，例如维度的根节点。
  • hierarchy — 要遵循的备用层次结构。默认为 "main"。
  • orientation — "vertical"（默认）表示沿列向下列出节点，"horizontal" 表示沿行向右列出节点。
  • generation_limit — 返回的代数，start_node 算第一代：2 返回起始节点及其子节点。省略则返回所有代。

DRILL

Section titled “DRILL”

=PLAIDXL.DRILL(dimension_name, start_node, drill_key, [hierarchy])

沿一列向下返回 start_node 以及 drill_key 所要求的其下节点，按代缩进并归入 Excel 分级显示组。

  • dimension_name — 维度的名称，或其在项目中的路径。
  • start_node — 钻取的起始节点。
  • drill_key — 钻取的深度，来自 DRILL_KEY：所有后代、仅叶节点，或指定的层数。
  • hierarchy — 要遵循的备用层次结构。默认为 "main"。

例如，=PLAIDXL.DRILL("Region", "Total", PLAIDXL.REPR.DRILL_KEY("leaves")) 会列出 Total，随后是其下的每个叶级区域。

功能区上的钻取命令可对您在两个单元格中输入的维度和节点执行同样的操作，无需编写公式。

值

Section titled “值”

CELL 和 CELLS 计算度量值（表中的数值列），并汇总到您在一个或多个维度中选定的节点。可将每次调用视为报表中的一个交叉点：收入在 EMEA 于 FY2026 的数值。

使用下面的构建块函数描述该交叉点，通常放在各自的单元格中，然后以任意顺序将这些单元格传递给 CELL 或 CELLS：

参数 构建方式 是否必需
要读取的表 TABLE_REPR 恰好一个
要聚合的列 CELL 使用 MEASURE，CELLS 使用 MEASURES 或多个 MEASURE 单元格 是
聚合方式 MEASURE_TYPE 否，默认为 sum
对某一列的筛选 DIMENSION_REPR 至少一个，每列一个

每个筛选器指定表中的一列和一个值。当该列已在 PlaidCloud 中链接到某个维度时，该值是一个节点，筛选器会包含在该维度主层次结构中汇总到该节点的所有内容。例如在链接到地理维度的 Region 列上，节点 EMEA 涵盖其下的每个国家。在未链接到维度的列上，筛选器按值精确匹配。

本页的示例使用一个 Region 和 Period 列已链接到维度的表。请使用您自己表的列名。

CELL

Section titled “CELL”

=PLAIDXL.CELL(table, measure, [measure_type], node, [node], ...)

返回一个数字：对属于您传入的每个节点之下的行聚合得到的度量值。

A1  =PLAIDXL.REPR.TABLE_REPR("Sales")
A2  =PLAIDXL.REPR.MEASURE("revenue")
A3  =PLAIDXL.REPR.MEASURE_TYPE("sum")
A4  =PLAIDXL.REPR.DIMENSION_REPR("Region", "EMEA")
A5  =PLAIDXL.REPR.DIMENSION_REPR("Period", "FY2026")
B1  =PLAIDXL.CELL(A1, A2, A3, A4, A5)

B1 显示 EMEA 在 FY2026 的总收入。

CELLS

Section titled “CELLS”

=PLAIDXL.CELLS(table, measures, [measure_type], node, [node], ...)

与 CELL 类似，但一次处理多个度量值。每个度量值返回一个数字，沿一列向下，顺序与您列出的顺序一致。

D1:F1  revenue | cost | units
D2     =PLAIDXL.REPR.MEASURES(D1:F1)
B2     =PLAIDXL.CELLS(A1, D2#, A3, A4, A5)

D2# 传递 MEASURES 的整个溢出结果。B2:B4 显示 EMEA 在 FY2026 的收入、成本和数量。

构建块

Section titled “构建块”

这些函数本身不读取数据。每个函数返回一小段文本，描述计算的某一部分，可传递给 CELL、CELLS 或 DRILL。请将它们放在被引用的单元格中，这样只需更改一处（例如换一个期间），所有使用它们的公式都会更新。

TABLE_REPR

Section titled “TABLE_REPR”

=PLAIDXL.REPR.TABLE_REPR(table_name)

CELL 和 CELLS 读取的表，以其在所选项目中的名称指定。

MEASURE

Section titled “MEASURE”

=PLAIDXL.REPR.MEASURE(column_name)

CELL 要聚合的数值列。

MEASURES

Section titled “MEASURES”

=PLAIDXL.REPR.MEASURES(column_names)

供 CELLS 使用的多个度量列，来自包含列名的单元格区域。结果每列溢出一个单元格；使用溢出运算符（例如 D2#）将其传递给 CELLS。

MEASURE_TYPE

Section titled “MEASURE_TYPE”

=PLAIDXL.REPR.MEASURE_TYPE(agg_function)

度量值的聚合方式。agg_function 为以下之一（小写）：

值 返回
sum 总和（未传入度量类型时的默认值）
mean 平均值
median 中位数
min 最小值
max 最大值
std 标准差
var 方差

DIMENSION_REPR

Section titled “DIMENSION_REPR”

=PLAIDXL.REPR.DIMENSION_REPR(dimension_name, start_node)

供 CELL 和 CELLS 使用的筛选器。每个要筛选的列传入一个。

  • dimension_name — 表中某一列的名称，即保存维度值的列，例如 "Region"。必须与列名完全一致；不在表中的列会返回错误。
  • start_node — 要汇总到的节点，例如 "EMEA"。在未链接到维度的列上，则为要匹配的值。

引用某个单元格作为节点即可构建网格：=PLAIDXL.REPR.DIMENSION_REPR("Region", $A7)。前导和尾随空格会被忽略，因此可以直接指向 DRILL 排布出的缩进节点名称。

DRILL_KEY

Section titled “DRILL_KEY”

=PLAIDXL.REPR.DRILL_KEY(d_key)

DRILL 在其起始节点之下钻取的深度。d_key 为纯文本：

d_key 钻取到
"all" 所有后代
"leaves" 仅叶节点，即其下没有任何节点的节点
"1 level"、"2 levels"、… 向下相应的代数

数字请使用阿拉伯数字：写 "2 levels"，而不是 "two levels"。开头的 drill 会被忽略，因此 "drill 2 levels" 同样有效。

在两层或更多层时，DRILL 一次列出一代，即先列出所有子节点，再列出所有孙节点，而不是将每个节点紧排在其父节点之下。若需要嵌套布局，请使用 "all"，或使用带有 generation_limit 的 GET_DIMENSION。

相关内容

Section titled “相关内容”