开放平台文档

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

TAPD通用创建页逐步完善中，若接入遇到问题，或有相关建议，欢迎企微联系：rickhrhuang、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/create?hidden_left_side=true&hidden_top_side=true

# 参数列表

参数名	是否必填	默认值	可选值	含义	示例
workspace_id	否	最近一次创建使用的项目id	任意workspace id	select_workspace=false时此字段表示在哪个项目下创建工作项；select_workspace=true时此字段表示默认选中的项目	workspace_id=6996033
hidden_left_side	否	false	true\|false	隐藏TAPD左侧菜单	hidden_left_side=true
hidden_top_side	否	false	true\|false	隐藏TAPD顶部菜单	hidden_top_side=true
add_type	否	story\|bug\|task	[story \|bug \|task]	可以选择的业务对象类型	add_type=bug\|task
entity_type	否	`add_type`中的第一个	story\|bug\|task	默认选择的业务对象类型	entity_type=task
select_workspace	否	true	true\|false	是否可以选择项目，为false且不设置`workspace_id`参数时，使用上次创建的项目id，与TAPD主站共用缓存	select_workspace=true
disabled_modify	否	无	字段英文名，支持数组，用`\|`号分割	前端禁用指定字段编辑。获取字段英文参考：get_story_fields_lable 不支持禁用的字段：标题、类型为人名的字段、详细描述	disabled_modify=owner\|iteration_id
hide_footer	否	false	true\|false	隐藏底部“创建”、“取消”按钮	hide_footer=false
hide_horizontal_scroll	否	false	true\|false	强制隐藏字段配置区域x轴滚动条，某些场景下会出现意料之外的x轴滚动条，隐藏不影响功能	hide_horizontal_scroll=true
disable_small_project_select	否	false	true\|false	默认情况下，项目选择下拉框比较短。如果想使用正常高度，请将此参数设置为false	disable_small_project_select=true
enable_fold	否	false	true\|false	控制创建页是否允许折叠（默认值false，即不允许折叠且默认展开）	enable_fold=true
default_expand	否	false	true\|false	控制创建页是否默认展开	default_expand=true
[${field_name}=${value}]	否	无	字段应用填入的值	通过这个参数，可以为创建页内的字段传入默认值，其中`${field_name}`需要填入字段英文名，获取字段英文名可以参考：get_story_fields_lable ，或者触发一次提交试试看。`${value}`是真实的字段值，例如指定迭代的话，需要传入`iteration_id=1070119185002139295`。是的，对于这些值为id的字段，你需要自己想办法拿到id，如果有困难可以咨询rickhrhuang、raferzeng、jasperwei。传入默认标题的方式为：`name=hello%20world`	name=hello%20world
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
disabled_modify	否	无	[字段英文名]	禁止用户编辑指定的字段，一般搭配`${field_name}=${value}`设置字段默认值使用	disabled_modify=iteration_id&iteration_id=1070119185002139295
iframe_id	否	''	调用方自定义的iframe id	指定当前iframe id，当在同一个页面嵌入多个通用创建页时需要使用，用于区分来自不同创建页的消息事件。TAPD通用项目向外发出消息时会携带这个参数	iframe_id="create_task"

# 特定场景参数

# 自定义项目选取范围

默认情况下，当传递select_workspace=true时（默认情况），可选项目范围是所有用户有权限的项目。

在某些场景下，第三方系统可能要根据授权范围，控制用户可以选择的项目范围。例如智研交付流场景，只允许用户选择智研项目关联的TAPD项目下的业务对象。

custom_workspace_range，custom_workspace_range=true时，自定义项目选择范围，项目范围由available_workspace_id参数控制。
available_workspace_id，可选项目范围，每个项目的格式为{id}-{name}，多个项目间使用|分割。-${name}可选，name主要作用是无法获取此项目时回显name在选项中。

自定义项目选取范围

# 页面内缓存说明

# 项目选择

用户创建业务对象后，会记住此次创建的业务对象所对应的TAPD项目id，当下次进入后，默认选择该项目。

当url设置select_workspace=false且指定workspace_id=xxx后，不使用缓存，使用url指定的项目idxxx。

# 事件通信

message规范

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

1
2
3
4

# iframe发出的事件

当iframe内部发生了一些事件时，例如用户点击了创建按钮，或者全屏详细描述的编辑器等，会向父页面发出对应事件，通知父页面进行处理。

高度变化 (type: tapd-common-create-height)

携带参数：

{
  type: 'tapd-common-create-height';
  height: String; // 变化后的整体页面高度
  iframeId:  String; // url中指定的iframe id，用于区分来自不同iframe的消息
}

1
2
3
4
5

创建页高度会动态变化，例如展开收起字段输入区域时，高度会发生变化。如果调用方不希望展示TAPD创建页内部的滚动条，可以在监听到此事件后设置iframe高度，保证TAPD页面内高度是足够的，此时如果iframe高度超过调用方的容器高度，滚动条出现在调用方的容器。

示例:

// 创建页中
// window.parent.postMessage({ type: 'tapd-common-create-height', height }, '*'); 

// 使用iframe创建页的父页面
<iframe id="iframe0" width="100%" height="600px" src="https://tapd.woa.com/create?hidden_left_side=true&hidden_top_side=true"></iframe>

<script>
  const el = document.querySelector('#iframe0');  
  function handlePostMessage(e) {
    if(e.data.type === 'tapd-common-create-height') {
      // 高度监听start
      // 全屏不会接收到事件，由父页面控制
      const el = document.querySelector('#iframe0');
      const height = Math.min(maxHeight, e.data.height);
      console.log('@@@高度变化', {height});
      el.setAttribute('style', `height: ${height}px;`);
      // 高度监听end
    }
  }
  window.addEventListener('message', handlePostMessage); 
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

创建成功 (type: tapd-common-create)

携带参数：

{
  type: 'tapd-common-create';
  entity: Object; // 创建成功后的对象信息
  iframeId:  String; // url中指定的iframe id，用于区分来自不同iframe的消息
}

1
2
3
4
5

业务对象创建成功后发出此事件，entity包括业务对象的标题、优先级、类型等字段，以及业务对象id、项目id等信息。调用方可以拿到用户创建的对象信息，进行关联关系绑定等操作。

示例：

// 创建页中
// window.parent.postMessage({ type: 'tapd-common-create', entity }, '*'); 

// 使用iframe创建页的父页面
<iframe src="tapd.woa.com/create?hidden_left_side=true&hidden_top_side=true"/>

<script>
  function handlePostMessage(e) {
    if(e.data.type === 'tapd-common-create') {
      // 打印业务对象信息
      console.log(e.data.entity);
    }
  }

  window.addEventListener('message', handlePostMessage);
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

取消创建 (type: tapd-common-create-cancel)

携带参数：

{
  type: 'tapd-common-create-cancel';
  iframeId:  String; // url中指定的iframe id，用于区分来自不同iframe的消息
}

1
2
3
4

在iframe中，底部会渲染取消按钮，点击取消时，会向外抛出事件。父页面中可进行对应处理。

示例：

// 创建页中
// window.parent.postMessage({ type: 'tapd-common-create-cancel' }, '*');

// 使用iframe创建页的父页面
<iframe src="tapd.woa.com/create?hidden_left_side=true&hidden_top_side=true"/>
  
function handlePostMessage(e) {
  if(e.data.type === 'tapd-common-create-cancel') {
    // do sth
    console.log('cancel');
  }
}

window.addEventListener('message', handlePostMessage);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

详细描述部分编辑器全屏切换 (type: tapd-editor-fullscreen-change)

携带参数：

{
  type: 'tapd-editor-fullscreen-change';
  state: Boolean; // 编辑器全屏状态
  iframeId:  String; // url中指定的iframe id，用于区分来自不同iframe的消息
}

1
2
3
4
5

当用户点击编辑器的全屏按钮时会发出此事件，父页面此时可以将iframe全屏。

示例：

// 创建页中
// window.parent.postMessage({ type: 'tapd-common-create-cancel' }, '*');

// 使用iframe创建页的父页面
<iframe src="tapd.woa.com/create?hidden_left_side=true&hidden_top_side=true"/>
  
function handlePostMessage(e) {
  if(e.data.type === 'tapd-editor-fullscreen-change') {
    const state = e.data.state;
    console.log('@@@编辑器全屏状态:', state);
  }
}

window.addEventListener('message', handlePostMessage);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# iframe接收的消息

父页面可以主动向iframe传递消息，改变创建页内部的数据或者样式。

改变详细描述 (description: String)

父页面可以向iframe传递消息，改变详细描述的内容，使用方式：

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

<script>
  const el = document.querySelector('#iframe0');  
  setTimeout(() => {
     el.contentWindow.postMessage({
        description: '我是新的详细描述',
    }, '*');
  }, 3000);
</script>

1
2
3
4
5
6
7
8
9
10

切换全屏样式 (type: change-fullscreen-layout)

切换为全屏创建样式，注意切换成全屏样式后，页面会自适应iframe的高度，不会再发出tapd-common-create-height事件。使用方式：

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

<script>
  const el = document.querySelector('#iframe0');  
  setTimeout(() => {
     el.contentWindow.postMessage({
        type: 'change-fullscreen-layout'
        state: true,
    }, '*');
  }, 3000);
</script>

1
2
3
4
5
6
7
8
9
10
11

触发创建请求 (submit: '1')

父页面主动触发创建操作，等效于点击”创建“按钮，会触发对应的字段校验逻辑，不会直接提交。使用方式：

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

<script>
  const el = document.querySelector('#iframe0');  
  setTimeout(() => {
     el.contentWindow.postMessage({
        submit: '1',
    }, '*');
  }, 3000);
</script>

1
2
3
4
5
6
7
8
9
10

业务对象选择 →