开放平台文档

若本地开发使用的是http协议，使用iframe接入TAPD页面时会被浏览器安全策略屏蔽，可以尝试使用火狐浏览器

若接入遇到问题，或有相关建议，企微联系：raferzeng、jasperwei

# 通用参数列表

通用参数是所有TAPD页面都支持的，即使这个页面没有在通用页面范围内。

参数名 是否必填 默认值 可选值 含义 示例
hidden_left_side 否 false true|false 隐藏TAPD左侧菜单，第三方接入时应该设置为true hidden_left_side=true
hidden_top_side 否 false true|false 隐藏TAPD顶部菜单，第三方接入时应该设置为true hidden_top_side=true
tapd_iframe_from 否 无 第三方系统名称 标识使用TAPD通用页面的第三方系统。这个参数可以帮助我们统计调用量等信息；如果后续调用方的需求很大，也有助于我们根据调用的来源，做一些特殊的性能优化处理。 tapd_iframe_from=iWiki

# TIPS

  • 一般情况下，如果某个url参数支持数组，多个值之间使用 | 号连接，例如workspace_id=45645|123131|345666。

# 基础接入

页面地址：https://tapd.woa.com/relate?hidden_left_side=true&hidden_top_side=true

# 参数列表

参数名 是否必填 默认值 可选值 含义 示例
workspace_id 否 最近一次选择的项目id 任意workspace id 要查询的TAPD项目id workspace_id=6996033
entity_type 否 story story|task|bug|iteration 查询的业务对象类型 entity_type=story
select_workspace 否 true true |false 是否出现项目选择下拉框 select_workspace=false
select_type 否 multi multi|single 多选/单选 select_type=single
hide_preview 否 false true|false select_type=multi情况下才需要配置，隐藏右侧预览区域 select_type=multi&hide_preview=true
display_mode 否 list tree|list 控制业务对象的展现形式，展示树形结构（父子需求），或平铺 display_mode=tree
select_entity 否 无 [${field_name}] 已选对象，传入任意字段，默认为 id，传入多个使用|号连接，例如 1069996033856116817|1069996033856019365。注意：传入的对象主要是用于回显，点击确认后postMessage传递出的对象信息并不会全部包含，只会包含页面上出现过的对象（例如，一个传入的对象在第二页，但是用户并没有翻页，那么这个对象的信息不会被传出，上游业务需要自己做好处理。一切以点击确认后收到的业务对象信息为准！！！） select_entity=1069996033856116817|1069996033856019365
disabled_entity 否 无 [${field_name}] 禁用编辑的对象，传入任意字段，默认为 id，例如 1069996033856116817|1069996033856019365，注意 disabled_entity 和 select_entity 如果包含同一个对象，那么该对象无法取消选中，在单选状态下，无法选中其他对象 disabled_entity=1069996033856116817|1069996033856019365
key 否 id 任意字段英文名 指定 select_entity 和 disabled_entity使用的字段名称，不传默认使用 id，如果使用短 id请传入 key=short_id。 key=short_id&disabled_entity=856019365
output_unseen_select 否 false true |false 这个配置只有在key=id，同时设置了select_entity=1069996033856116817|1069996033856019365的情况下有效。传入的id，即使没有在表格中出现过，也会被认为已经被用户选择（已经被取消选择的不会返回）。建议搭配hide_preview=true使用，否则右侧预览区域不会出现该对象，但是会返回，表现上不符合预期。2025年6月26日更新: 如果select_entity指定的为id，会自动回显在预览区域，可以不设置此参数 key=id&select_entity=1069996033856116817|1069996033856019365&hide_preview=true
workspace_select_type 否 tree flatten|tree 项目下拉框内使用树形列表还是平铺列表，树形列表会显示项目的父子关系。如果要自定义项目选择范围，只能使用平铺列表（workspace_select_type=flatten） workspace_select_type=flatten
custom_workspace_range 否 false true |false 是否开启自定义项目选择范围特性 custom_workspace_range=true
available_workspace_id 否 无 [${id}-${name}] 设置可选项目范围，以及项目不可用时的回显名称。每个项目的格式为{id}-{name}，多个项目间使用|分割。-${name}可选，name主要作用是无法获取此项目时回显name在选项中。自定义项目选取范围 custom_workspace_range=true&available_workspace_id=755-TAPD平台|69906033-jasper测试项目
filter[${字段名}]=${value} 否 无 \ 设置过滤器默认参数，目前仅支持设置部分字段。需求列表包括：status（状态）、owner（处理人）、iteration_id（迭代）；缺陷列表包括：status（状态）、owner（处理人）、iteration_id（迭代）；任务列表包括：status（状态）、owner（处理人）、iteration_id（迭代）;迭代列表包括：暂不支持 filter[owner]=当前登录用户
disable_workspace_select_cache 否 false true | false 默认情况，当select_workspace=true或者没有传入workspace_id时，会使用用户上次选择的项目（前端缓存），此时workspace_id参数即使设置了也会被忽略。如果需要使用select_workspace=true，并且指定默认workspace_id，需要将此参数设置为true disable_workspace_select_cache=true
skip_submit_validate 否 false true |false 正常情况下，点击提交按钮后会进行参数校验，校验不通过（例如没有选择业务对象）时，不会调用接口查询所选对象的详细信息。skip_submit_validate=true时，会跳过参数验证，直接调用接口，如果参数不满足的话，接口会报错 skip_submit_validate=true
show_fields 否 无 字段英文名数组 业务对象详细信息需要额外返回的字段
preview_fields 否 无 字段英文名数组，目前仅至支持了iteration 表格需要展示的额外字段，目前仅支持额外展示迭代信息 preview_fields=iteration
fix_filter_bar 否 false true |false 滚动时是否固定过滤器 fix_filter_bar=true
no_left_padding 否 true true |false 过滤器和表格内部是否有左边距 no_left_padding=false
filter_include_inprogress 否 false true |false 过滤器的状态选项，是否新增过滤进行中状态的选项 filter_include_inprogress=true
always_filter_status 否 无 workflow_done 当always_filter_status=workflow_done时，强行过滤已经结束的业务对象，这个会永远作为查询的默认条件，不显示在过滤器中，用户不可取消。此参数是为了支持智研某个子产品的场景，目前仅支持过滤workflow_done always_filter_status=workflow_done
height 否 596 数字 指定内容区域的高度，包括过滤器部分和表格部分，不包括底部按钮区域 height=596
hidden_footer 否 false true|false 隐藏底部按钮区域，即确认按钮 hidden_footer=false

# 页面内缓存说明

缓存开启条件：url参数中没有禁用本地缓存（disable_workspace_select_cache=true） 且 （select_workspace=true），或url参数中没有禁用本地缓存（disable_workspace_select_cache=true） 且 url中没有指定workspace_id。

缓存启用后，用户在项目下拉框中手动切换项目，都会更新前端缓存。当用户下次进入页面后，会优先选择缓存项目。

# 项目选择

# 事件通信

message规范

{
  type: String; // 消息类型，TAPD根据这个判断如何进行后续处理
  [String]: String; // 消息携带的数据，参考具体的事件类型
}
1
2
3
4

# iframe发出的事件

  • 用户提交选择（type: tapd-common-relate）

    携带参数：

    {
   type: 'tapd-common-relate';
   entity: [Object];
   entityType: String;
}
    1
    2
    3
    4
    5

    用户点击确定按钮后，会向TAPD后台查询所选对象的详细信息，之后将信息传递给父页面。

    示例：

    // 引入iframe
<iframe src="https://tapd.woa.com/relate?hidden_left_side=true&hidden_top_side=true&workspace_id=20453566&entity_type=bug&select_workspace=false&select_type=single"/>


// 监听事件
function handlePostMessage(e) {
  if(e.data.type === 'tapd-common-relate') {
    console.log(e.data.entity);
  // entity返回数组，data中常用字段说明：
  // id：业务对象id（需求/缺陷/任务/迭代 ID）
  // name：需求标题/任务标题/迭代名称
  // title：缺陷标题
  // status：状态（需求、缺陷、任务、迭代
  // priority：优先级（需求、缺陷、任务
  }
}

window.addEventListener('message', handlePostMessage);
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

# iframe接收的消息

  • 触发确认操作（type: tapd-dialog-confirm）

    父页面主动触发确认操作，等效于点击”确认“按钮。例如url使用了hidden_footer=false参数时，提交操作由父页面控制。使用方式：

    <iframe id="iframe0" width="100%" height="600px" src="https://tapd.woa.com/relate?hidden_left_side=true&hidden_top_side=true"></iframe>

<script>
  const el = document.querySelector('#iframe0');  
  setTimeout(() => {
     el.contentWindow.postMessage({
        type: 'tapd-dialog-confirm',
    }, '*');
  }, 3000);
    1
    2
    3
    4
    5
    6
    7
    8
    9

  • 传递鼠标相关事件（type: out-mouse-event）

    iframe和父页面是完全独立的，父页面发生的鼠标事件iframe内部不会监听到。例如当在iframe中展开过滤器时，如果iframe内部其他区域发生点击事件后，过滤器会自动收起，但是点击父页面，过滤器并不会收起。这个事件是为了让iframe内部感知到父页面的鼠标事件，让父页面发生点击操作后，iframe里面的过滤器也自动收起。使用方式：

    <iframe id="iframe0" width="100%" height="600px" src="https://tapd.woa.com/relate?hidden_left_side=true&hidden_top_side=true"></iframe>

<script>
  const el = document.querySelector('#iframe0');
  window.addEventListener('mousedown', (event) => {
    el.contentWindow.postMessage({
        type: 'out-mouse-event',
        eventType: event.type,
    }, '*');
  });
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

    iframe内部实现方式：

    handlePostMessage(e) {
  if (e.data.type === 'out-mouse-event') {
    const eventType = e.data?.eventType;
    if (eventType)
      document.dispatchEvent(
        new MouseEvent(eventType, {
          bubbles: true,
          composed: true,
        }),
      );
  }
},
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
上次更新: 2025-06-30 18:22:56

← 业务对象详情 →