Tapd 开放平台提供基本的组件来完成第三方应用于 Tapd 系统的数据交互。
# 通信原理
目前业务扩展模块是基于Iframe网页嵌入，第三方应用与 Tapd 系统通过 postMessage (opens new window) 来实现数据交互。
# 通用能力
# 通信格式
{
event: "xxxx",
params: {},
code: "xxx",
}
2
3
4
5
调用事件样例
const config = {
event: event,
params: payload,
code: code,
};
window.parent.postMessage(config, '*');
2
3
4
5
6
7
接收事件样例
const handleMessage = (message) => {
const options = message['data'];
const eventType = options['event'];
const params = options['params'];
// 第三方业务逻辑
}
if (window.addEventListener) {
window.addEventListener("message", handleMessage);
} else {
window.attachEvent("onmessage", handleMessage);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
| 字段 | 描述 |
|---|---|
| event | 事件名称 |
| params | 事件参数 |
# 通信事件
Tapd 开放平台既接收第三方应用发起的事件，也支持主动发起事件推送给第三方应用。
# 接收事件
# 同步URL
名称： syncUrl
描述：Tapd 接收第三方同步 URL 的事件。在访问到第三方应用页面后，希望父窗体的地址栏跟随子窗体内部src，同时更新父窗体的地址栏，再刷新页面可以保持在当前访问的页面，同时可以分享链接。
弃用：建议不使用用，将会被启用，建议使用 routeChange
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| url | 是 | string | hash链接 |
| refresh | 否 | boolean | 是否强制刷新 |
# 同步URL （新）
名称： routeChange
描述： 当想要用户刷新页面之后访问同一个应用的同一页面时候使用。
注意： 目前只能在 app_for_project 使用，归来将会全插槽使用
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| url | 是 | string | 下次打开页面时给第三发应用的url，格式位完成url，格式同 （window.location）一致。 |
# 生成code用户授权码
名称：generateCode
描述：当第三方应用登录态丢失时，可以发起此事件调用生成新的用户授权码。当 Tapd 生成成功后会发起同步 code 事件推送给第三方。
参数：无
# 访问 Tapd 业务对象链接
名称：openObjURL
描述：Tapd 提供可以新页面直接打开业务对象详情页，避免第三方应用自己拼接URL。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entityType | 是 | string | 对象类型（story/bug/task） |
| entityId | 是 | string | 对象ID |
# 同步页面高度
名称：syncPageHeight
描述：根据第三方应用传递的页面高度来设置 iframe 的页面高度
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| height | 是 | number | iframe 页面高度 |
# 打开系统弹框
名称：showDialog
描述：第三方应用可以调用 Tapd 系统弹框，将相应的页面嵌入到弹框中，从而保证与 Tapd 系统交互一致性。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| title | 是 | string | 弹框标题 |
| url | 是 | string | 嵌入页面的 URL |
| height | 是 | number | 弹框高度（<= 1时为当前窗口宽度的比例值，设置值不能大于窗口宽度） |
| width | 是 | number | 弹框宽度（<= 1时为当前窗口高度的比例值，设置值不能大于窗口宽度） |
# 关闭系统弹框
名称：closeDialog
描述：第三方应用可以将打开的 Tapd 系统弹框进行关闭。例如第三方已经做完提交操作，可调用此事件关闭弹框。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | boolean | 操作状态 |
| params | 是 | object | 透传数据 |
# 打开确认框
名称：showConfirm
描述：调用 Tapd 系统确认框。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| content | 是 | string | 确认框内容 |
| data | 是 | object | 透传数据 |
# 同步页面事件数据
名称：syncPageEvent
描述：同一个页面中有多个入口挂载时，可通过此事件通知其他入口进行操作
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 扩展模块入口ID（例如业务对象tab页：app_for_obj_tab_story、app_for_obj_tab_bug、app_for_obj_tab_task） |
| data | 是 | object | 透传数据 |
# 刷新附件列表
名称：refreshAttachmentList
描述：当第三方应用在解除与tapd附件关联时，调用此方法可以刷新页面的附件列表
参数：无
# 刷新当前页面
名称：refreshCurrentPage
描述：当第三方API变更了TAPD字段时，需要及时显示，调用此方法可以刷新当前TAPD页面
参数：无
# 初始化完成应答事件
名称：asyncAnswerInitFinished
描述：当第三方应用初始化完成时响应
参数：无
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | number | 状态（0 失败， 1成功） |
| message | 是 | string | 提示信息 |
# 编辑器确认应答事件
名称：asyncAnswerToEditor
描述：当用户点击编辑器弹窗确认按钮时，编辑器会发送确认事件，第三方收到确认事件时需要应答此事件，以回传插入元素所需要的信息
参数：无
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| url | 是 | string | iframe指向的url地址 |
| name | 是 | string | 标题 |
| sub | 是 | string | 浮动显示标题（建议长度在5个字符以内） |
| extra_name | 否 | string | 右下角跳转显示的名称，默认为“打开【扩展名称】” |
| extra_url | 否 | string | 右下角跳转的地址，默认与url保持一致 |
# 推送事件
# 同步 code
名称： syncCode
描述：生成的新用户授权码推送给第三方应用。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| code | 是 | string | 用户授权码 |
# 弹框确认
名称： dialogYes
描述：当用户点击系统弹框的【确认】按钮时，触发此事件并推送给第三方应用。
参数：无
# 弹框取消
名称： dialogNo
描述：当用户点击系统弹框的【取消】按钮时，触发此事件并推送给第三方应用。
参数：无
# 弹框操作完成
名称： dialogOperateFinish
描述：当系统弹框关闭后，会触发此事件并推送给第三方应用，来通知原第三方应用页面已经完成弹框操作，这样可以进行下一步操作，比如：局部刷新等等。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | boolean | 操作状态 |
| params | 否 | object | 透传数据 |
# 确认框确认
名称： confirmYes
描述：当触发确认框调起之后，点击【确定】按钮时，触发此事件并推送给第三方应用。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| data | 否 | object | 透传数据 |
# 同步页面事件数据
名称：syncPageEvent
描述：同一个页面中有多个入口挂载时，可通过此事件通知其他入口进行操作
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 发送数据iframe的扩展模块ID（例如附件扩展模块：app_for_obj_attachment_story、app_for_obj_attachment_bug、app_for_obj_attachment_task） |
| data | 是 | object | 透传数据 |
# 编辑器toolbar触发事件
名称：syncFromEditorTriggerEvent
描述：当用户点击编辑器扩展模块图标时，tapd会调起弹窗加载用户配置的url，并且发送该事件通知应用进行初始化
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 扩展模块入口ID（例如业务对象编辑器toolbard入口ID：app_for_editor） |
| url | 是 | string | 嵌入页面的 URL |
# 生成code用户授权码
名称：generateCode
描述：当第三方应用登录态丢失时，可以发起此事件调用生成新的用户授权码。当 Tapd 生成成功后会发起同步 code 事件推送给第三方。
参数：无
# 访问 Tapd 业务对象链接
名称：openObjURL
描述：Tapd 提供可以新页面直接打开业务对象详情页，避免第三方应用自己拼接URL。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entityType | 是 | string | 对象类型（story/bug/task） |
| entityId | 是 | string | 对象ID |
# 同步页面高度
名称：syncPageHeight
描述：根据第三方应用传递的页面高度来设置 iframe 的页面高度
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| height | 是 | number | iframe 页面高度 |
# 打开系统弹框
名称：showDialog
描述：第三方应用可以调用 Tapd 系统弹框，将相应的页面嵌入到弹框中，从而保证与 Tapd 系统交互一致性。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| title | 是 | string | 弹框标题 |
| url | 是 | string | 嵌入页面的 URL |
| height | 是 | number | 弹框高度（<= 1时为当前窗口宽度的比例值，设置值不能大于窗口宽度） |
| width | 是 | number | 弹框宽度（<= 1时为当前窗口高度的比例值，设置值不能大于窗口宽度） |
# 关闭系统弹框
名称：closeDialog
描述：第三方应用可以将打开的 Tapd 系统弹框进行关闭。例如第三方已经做完提交操作，可调用此事件关闭弹框。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | boolean | 操作状态 |
| params | 是 | object | 透传数据 |
# 打开确认框
名称：showConfirm
描述：调用 Tapd 系统确认框。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| content | 是 | string | 确认框内容 |
| data | 是 | object | 透传数据 |
# 同步页面事件数据
名称：syncPageEvent
描述：同一个页面中有多个入口挂载时，可通过此事件通知其他入口进行操作
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 扩展模块入口ID（例如业务对象tab页：app_for_obj_tab_story、app_for_obj_tab_bug、app_for_obj_tab_task） |
| data | 是 | object | 透传数据 |
# 刷新附件列表
名称：refreshAttachmentList
描述：当第三方应用在解除与tapd附件关联时，调用此方法可以刷新页面的附件列表
参数：无
# 刷新当前页面
名称：refreshCurrentPage
描述：当第三方API变更了TAPD字段时，需要及时显示，调用此方法可以刷新当前TAPD页面
参数：无
# 初始化完成应答事件
名称：asyncAnswerInitFinished
描述：当第三方应用初始化完成时响应
参数：无
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | number | 状态（0 失败， 1成功） |
| message | 是 | string | 提示信息 |
# 编辑器确认应答事件
名称：asyncAnswerToEditor
描述：当用户点击编辑器弹窗确认按钮时，编辑器会发送确认事件，第三方收到确认事件时需要应答此事件，以回传插入元素所需要的信息
参数：无
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| url | 是 | string | iframe指向的url地址 |
| name | 是 | string | 标题 |
| sub | 是 | string | 浮动显示标题（建议长度在5个字符以内） |
# 推送事件
# 同步 code
名称： syncCode
描述：生成的新用户授权码推送给第三方应用。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| code | 是 | string | 用户授权码 |
# 弹框确认
名称： dialogYes
描述：当用户点击系统弹框的【确认】按钮时，触发此事件并推送给第三方应用。
参数：无
# 弹框取消
名称： dialogNo
描述：当用户点击系统弹框的【取消】按钮时，触发此事件并推送给第三方应用。
参数：无
# 弹框操作完成
名称： dialogOperateFinish
描述：当系统弹框关闭后，会触发此事件并推送给第三方应用，来通知原第三方应用页面已经完成弹框操作，这样可以进行下一步操作，比如：局部刷新等等。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| status | 是 | boolean | 操作状态 |
| params | 否 | object | 透传数据 |
# 确认框确认
名称： confirmYes
描述：当触发确认框调起之后，点击【确定】按钮时，触发此事件并推送给第三方应用。
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| data | 否 | object | 透传数据 |
# 同步页面事件数据
名称：syncPageEvent
描述：同一个页面中有多个入口挂载时，可通过此事件通知其他入口进行操作
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 发送数据iframe的扩展模块ID（例如附件扩展模块：app_for_obj_attachment_story、app_for_obj_attachment_bug、app_for_obj_attachment_task） |
| data | 是 | object | 透传数据 |
# 编辑器toolbar触发事件
名称：syncFromEditorTriggerEvent
描述：当用户点击编辑器扩展模块图标时，tapd会调起弹窗加载用户配置的url，并且发送该事件通知应用进行初始化
参数：
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| entranceId | 是 | string | 扩展模块入口ID（例如业务对象编辑器toolbard入口ID：app_for_editor） |
| url | 是 | string | 嵌入页面的 URL |