输出 Schema

描述步骤输出在构建器中的呈现方式

默认情况下，构建器将步骤的输出渲染为原始 JSON。你可以选择通过在动作或触发器上声明 outputSchema 来启用友好的、带标签的呈现方式。该 Schema 同时驱动智能输出查看器（测试步骤/运行详情）和数据选择器（变量选择器），为用户提供可读标签、格式化值以及嵌套/表格视图——同时不影响自动化中使用的表达式路径。

该 Schema 与从 @activepieces/pieces-framework 导出的 OutputSchema 类型完全类型检查。

声明 Schema

传递一个包含 fields 扁平列表的 outputSchema。每个字段映射到输出中的一个路径：

import { createAction } from '@activepieces/pieces-framework';

export const getEmail = createAction({
  name: 'get_email',
  displayName: '获取邮件',
  props: {},
  outputSchema: {
    fields: [
      { key: 'subject', label: '主题' },
      { key: 'from', label: '发件人', format: 'email' },
      { key: 'date', label: '接收时间', format: 'datetime' },
      {
        key: 'attachments',
        label: '附件',
        listItems: [
          { key: 'fileName' },
          { key: 'size', format: 'filesize' },
        ],
      },
    ],
  },
  run: async (context) => {
    /* ... */
  },
});

一个字段支持可选的 label、value 路径覆盖、format（email、url、date、datetime、number、boolean、image、html、currency、filesize、duration），以及用于嵌套对象和记录数组的 children / listItems。

为不透明键添加友好标签

当你的输出是由 UUID/别名键控的对象（dynamicKey: true）或记录数组（listItems）时，条目通常会显示为原始键或项目 1、项目 2……使用 labelKey 指向每个条目/项目中属性，其值将作为标签显示。

按 ID 键控的对象：

outputSchema: {
  fields: [
    {
      key: 'boards',
      label: '看板',
      dynamicKey: true,
      labelKey: 'name',
    },
  ],
},
// run() 返回：{ boards: { '3f2504e0-...': { name: '路线图', ... } } }

数据选择器和输出查看器将显示 路线图 而不是 UUID。插入的表达式仍然是 step_1['boards']['3f2504e0-...']。

记录数组：

outputSchema: {
  fields: [
    {
      key: 'items',
      label: '项目',
      labelKey: 'name',
      listItems: [{ key: 'id' }, { key: 'name' }],
    },
  ],
},

每个元素由其 name 标记，而不是 项目 1、项目 2。当项目没有 name（或为空）时，标签回退为 项目 N。

顶层数组输出

当你的动作返回顶层数组（例如搜索结果列表）时，Schema 的 fields 描述单个项目，并应用于数组的每个元素。使用可选的 itemLabel 模板为每个项目添加标签——{dotPath} 占位符将根据该项目解析：

outputSchema: {
  itemLabel: '{key}: {fields.summary}',
  fields: [
    { key: 'key', label: '键' },
    { key: 'summary', label: '摘要', value: 'fields.summary' },
    { key: 'status', label: '状态', value: 'fields.status.name' },
  ],
},
// run() 返回：[
//   { key: 'ADS-69', fields: { summary: '预订问题', status: { name: '待办' } } },
//   ...
// ]

每个项目显示为 ADS-69: 预订问题，并展开为带标签的字段。当模板解析为空字符串时，标签回退为 项目 N。项目的插入表达式仍然是其索引（step_1[0]），每个字段在其下解析（step_1[0]["fields"]["summary"]）。