开放平台文档

# 工作台-我的仪表盘

# 介绍

工作台-我的仪表盘页面扩展提供了工作台我的仪表盘卡片的扩展能力，如下图所示

图片描述

# 使用方式

图片描述

工作台-我的仪表盘页面扩展支持嵌入已有页面和开发新页面两种使用方式。
如果有现成的页面，推荐使用嵌入已有页面方式；如果页面还没开发，推荐使用开发新页面方式。

# 方式一：嵌入已有页面

# 页面配置

配置说明如下

配置名 格式 必填 示例 说明
扩展点名称 STRING (0,20] 是 Demo-迭代仪表 迭代仪表盘扩展标题
扩展点链接 URL 是 https://tapd.woa.com/open_demo/app_for_my_dashboard?workspace_id=$workspace.id$&obj_type=$object.type$&obj_id=$object.id$ 扩展的地址

配置示例

图片描述

# 上下文参数

支持业务对象级和项目级 上下文参数，可参考 通用说明-上下文参数 按需使用

# 事件通信

如果嵌入的页面需要和TAPD的页面进行通信，可参考 模块通信事件 和 事件通信示例 按需实现

# 方式二：开发新页面

使用开发新页面方式前需准备好开发环境，可参考 TAPD插件应用开发快速入门 配置，并且学习 TAPD插件应用开发必读，了解基础的开发知识

通过命令tplugin-cli resources,快速初始化一份Demo配置和代码,Demo内容如下:

# plugin.yaml 配置

在 app/resources 下加入以下配置

app:
  resources:
    - name: Demo-我的仪表盘卡片
      key: app_for_my_dashboard
      path: pages/app_for_my_dashboard
1
2
3
4
5

配置说明如下

配置名 说明 示例
name 仪表盘卡片标题 Demo-我的仪表盘卡片
key 扩展页面标识，每种扩展页面唯一，本页面扩展的标识是 app_for_my_dashboard app_for_my_dashboard
path 扩展页面代码的路径，相对于 resources 目录的路径 pages/app_for_my_dashboard
配置名 格式 必填 示例 说明
key fixed 是 app_for_my_dashboard 页面扩展标识，每种扩展页面唯一，本页面扩展的标识是 app_for_my_dashboard
path string 是 pages/app_for_my_dashboard 扩展页面代码的路径，相对于 resources 目录的路径
name string (0,20] 是 Demo-迭代仪表盘 仪表盘卡片标题

# 示例代码

在插件代码 resources/pages/ 目录下创建 app_for_my_dashboard 目录，并在该目录下创建 welcome.vue 和 index.js 两个文件

welcome.vue 示例代码


<template>
  <div class="wrapper">
    <t-form
        :data="formData"
        ref="form"
        @reset="onReset"
        @submit="onSubmit"
        :colon="true"
    >
      <t-form-item label="会议名" name='name'>
        <t-input v-model="formData.name" placeholder="请输入内容"></t-input>
      </t-form-item>
      <t-form-item label="会议描述" name='desc'>
        <t-input v-model="formData.desc" placeholder="请输入内容"></t-input>
      </t-form-item>
      <t-form-item label="会议时间" name='time'>
        <t-date-picker
            theme="primary"
            mode="date"
            format="YYYY-MM-DD HH:mm:ss"
            enableTimePicker
            v-model="formData.time"
        ></t-date-picker>
      </t-form-item>
      <t-form-item style="padding-top: 8px">
        <t-button theme="primary" type="submit" style="margin-right: 10px">提交</t-button>
      </t-form-item>
    </t-form>
  </div>
</template>

<script>
  import SDK from '@tencent/tapd-open-js-sdk'

  export default {
    data() {
      return {
        formData: {}
      };
    },
    async mounted() {
      // 初始化JS-SDK
      this.sdk = SDK();
      // 获取扩展点上下文数据
      const entranceData = await this.sdk.context.getEntranceData();
      // 组装表单数据，扩展对象类型（需求/缺陷/任务/迭代） + 扩展对象ID
      this.formData.name = entranceData.entityType + ' ' + entranceData.entityId;
      this.formData.time = new Date();

      this.isLoading = false;
    },
    methods: {
      onReset() {

      },
      onSubmit() {
        // 提交后关闭输入弹窗
        this.sdk.ui.closeDialog({status: true})
      }
    }
  };
</script>

<style lang="less">
  .wrapper {
    padding: 120px;
  }
</style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

tapd-open-js-sdk 参考 前端JSSDK

index.js 示例代码

import Vue from 'vue';
import welcome from './welcome.vue';
import tplugin from 'tdesign-vue/dist/tdesign.min.js';
import 'tdesign-vue/dist/tdesign.min.css';

Vue.use(tplugin);

// 渲染组件到#app
new Vue({
    el: '#app',
    render: h => h(welcome),
});
1
2
3
4
5
6
7
8
9
10
11
12

# 上下文参数

# 获取选择的列表数据

# 如何获取

  • url参数解析

    页面扩展支持使用url直接接入已经开发完成的第三方页面，可以通过在url中添加上下文变量，向页面传递TAPD信息。 页面扩展分为三类：业务对象级、系统级、项目级。

    假设你的入口地址是 https://demo.woa.com/path ，则：

    • 获取当前访问的用户ID：https://demo.woa.com/path?user_id=$system.user.id$
    • 获取当前访问的项目ID：https://demo.woa.com/path?project_id=$workspace.id$

    页面配置：

    页面配置url参数解析

  • 前端JS SDK读取上下文参数 目前支持npm的方式使用TAPD OPEN JS SDK

    npm i @tencent/tapd-open-js-sdk@latest
    1

    获取TAPD提供的上下文参数（只在页面被TAPD嵌入的情况下有效）

    // 初始化JS-SDK
this.sdk = SDK();
// 获取扩展点上下文数据
const entranceData = await this.sdk.context.getEntranceData();
    1
    2
    3
    4

    js sdk 获取上下文参数

  • handler被调用时接收上下文参数

    TAPD在调用handler时，会根据场景传递相关上下文参数（项目级、系统级、业务对象级），具体请查看每个模块关于上下文参数的说明，您也可以在开发阶段直接打印handler接收的参数，查阅上下文。

    handler被调用时接收上下文参数

# 系统级

系统级上下文参数支持所有扩展页面

参数名称 参数描述
system.user.id 当前登录用户id
system.user.nick 当前登录用户nick
system.user.name 当前登录用户名字
system.user.name_pinyin 当前登录用户拼音名
system.user.enabled 当前登录用户状态
system.user.status_name 当前登录用户是否在职
system.user.bu_id 当前登录用户bu_id
system.user.bu_name 当前登录用户bu_name
system.user.dept_id 当前登录用户dept_id
system.user.dept_name 当前登录用户dept_name
system.user.group_id 当前登录用户group_id
system.user.group_name 当前登录用户group_name
system.user.group_names 当前登录用户group_names
system.user.post_name 当前登录用户post_name

# 事件通信

如果嵌入的页面需要和TAPD的页面进行交互，可通过TAPD提供的JSSDK完成交互。

# 安装

# 使用

# SDK方法

# SDK-调用TAPDUI

  • 调用tapd的消息提示组件 .alert(message: string)

    sdk.ui.alert('Hello World')
    1

  • 调用TAPD侧的确认框 .confirm(message: string) => Promise

    sdk.ui.confirm('来个点赞3连？')
  .then(() => {
    alert('THX 😍')
  })
    1
    2
    3
    4

  • 调用TAPD侧弹框 .openDialog(params)

    sdk.ui.openDialog(params)
    1
    • 参数说明：
    title: string   (弹窗标题)
url: string   (弹窗URL)
height: number    (高度)
width: number   (宽度)
showBtn: boolean    (是否显示确认按钮)
btnYesText: string    (确认按钮文本)
btnNoText: string   (取消按钮文本)
    1
    2
    3
    4
    5
    6
    7

  • 关闭TAPD侧弹窗 .closeDialog()

    sdk.ui.closeDialog()
    1

  • 调整弹框大小 .resizeDialog(width: number, height: number)

    sdk.ui.resizeDialog(300, 400)
    1

  • 在tapd全屏显示图片预览 .showImage(data: string)

    注意： 需要安装3.25.0及以上版本的open-js-sdk。

    // url
sdk.ui.showImage('https://file.tapd.woa.com/xxxxxx/files/get_logo/xxxxxx.jpg')
// base64
sdk.ui.showImage('data:image/png;base64,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
    1
    2
    3
    4

# SDK-调用插件handler

  • function调用 .handler(handlerName: string, params = {}) => Promise <res>
    sdk.handler('story', {id: 'tsets'});
    1
    • 参数说明：
    handlerName: 接口名
params: 传递给接口的参数。只支持普通对象
    1
    2

# SDK-调用navigator

  • 于TAPD侧打开调用sdk的嵌入应用新的页面。url 为嵌入应用的路由 .openAppIndex(url: string)

    sdk.navigator.openAppIndex('/about')
    1

  • 打开TAPD业务对象的详情页（目前只支持需求，任务，缺陷）.openObjectWindow(params: { entityType: string, entityId: string })

    sdk.navigator.openObjectWindow({entityType: 'story', entityId: '123'})
    1

  • 更新当前浏览器的路由，一般用于同步嵌入应用路由与浏览器路由 .syncUrl(options: {url: string, refresh: bolean})

    sdk.navigator.syncUrl({url: 'exmaple.com', refresh: true})
    1
    • 参数说明：
    url: 目标路由
refresh： 更新路由后是否刷新页面
    1
    2

  • 更新Tab页扩展模块的数值 .updateTabCount({count: number, refresh: bolean})

    sdk.navigator.updateTabCount({count: 100, refresh: false})
    1
    • 参数说明：
    count: 数值
refresh： 更新路由后是否刷新页面(默认为false)
    1
    2

  • 详情页Tab切换（目前只支持需求，任务，缺陷详情页） .openObjectTab({tabName: string})

    sdk.navigator.openObjectTab({tabName: '变更历史'})
    1
    • 参数说明：
    tabName: Tab名称
    1

# SDK-获取context

  • 获取当前页面嵌入TAPD的配置信息 .getEntranceData() => Promise <entranceConfigs >

    const entranceConfigs = await sdk.context.getEntranceData() // return {appId, entranceId, code}
    1
    • 返回值说明：
    返回 entranceConfigs
appId: 应用ID
code: tapd Token
entranceId: 挂载点ID
    1
    2
    3
    4

  • 更新tapd授予码code，一般用于授权码过期 .refreshCode() => Promise <code>

    const newCode = await sdk.context.refreshCode()
    1

# SDK-iframe通信

  • 当在TAPD的页面中有多个挂载点页面，可以通过这个方法在不同挂载点间通信 .syncPageEvent(params: {entranceId: string, data: any}) => Promise

    sdk.iframe.syncPageEvent({
  entranceId: 'app_for_obj_detail_bottom_card',
  data: {
    msg: '下次一定'
  }
})
    1
    2
    3
    4
    5
    6

  • 调整应用在TAPD侧的高度 .setPageHeight(height: number)

    sdk.iframe.setPageHeight(400)
    1

# SDK-调用command

  • 当嵌入应用页面在tapd的业务对象（需求，任务，缺陷）详情页面，将更新页面里的附件列表 .refreshAttachmentList()

    sdk.command.refreshAttachmentList()
    1

  • 当嵌入应用页面在tapd的业务对象（需求，任务，缺陷）详情页面, 可以唤起挂在类型为 app_for_obj_detail_bottom_card 的挂载页面 .showObjDetailBottomCard()

    sdk.command.showObjDetailBottomCard()
    1

# SDK-调用request

  • 调用tapd侧的人名搜索接口 .getUserListByKeyWords(params: {key_word: string, workspace_id: string, per_page: number}, configs: {timeout: number }) => Promise <response>

    sdk.request
  .getUserListByKeyWords({
    key_word: 'tom',
    workspace_id: '1'
  })
  .then((response) => {
    console.log(response)
  })
    1
    2
    3
    4
    5
    6
    7
    8
    • 参数说明：
    keyword: String (搜素的关键字)
workspace_id: String (TAPD项目ID)
    1
    2
    • 返回值说明：
    返回 response
data: Array (用户列表)
    1
    2

  • 调用TAPD侧获取项目下人员名单接口 .getWorkspaceMemberList(params: {workspace_id: string,page_size: number, page: number }) => Promise<response>

    sdk.request
  .getWorkspaceMemberList({
    page_size: 100,
    workspace_id: '1',
    page: 1
  })
  .then((response) => {
    console.log(response)
  })
    1
    2
    3
    4
    5
    6
    7
    8
    9
    • 参数说明：
    page_size: Number (每页条数)
workspace_id: String (TAPD项目ID)
page: Number (第几页)
    1
    2
    3
    • 返回值说明：
    返回 response
data: Array (用户列表)
count: String (总人数)
    1
    2
    3

  • 获取对象相关成员名单 .getAllRelateMember(params: object}) => Promise

    sdk.request.getAllRelateMember({
  workspace_id: '755',
  entity_type: 'bug',
  entity_id: '1000000755089798713',
  include_self: 1
  include_relate_story_member: 0
  include_sub_story_member: 0
})
.then((response) => {
console.log(response)
})
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    • 参数说明：
    workspace_id: String (TAPD项目ID)
entity_type: String (资源类型: story|bug|task)
include_self: Number (是否包括用户: 0 | 1)
include_relate_story_member: Number (是否包含关联需求: 0 | 1)
include_sub_story_member: Number (是否包含子需求: 0 | 1)
    1
    2
    3
    4
    5
    • 返回值说明：
    返回 response
data: Array (用户列表)
    1
    2

# SDK-event监听

  • 监听来着TAPD侧的事件 .on(event: string, cb: data => res, config: {once: bolean})

    sdk.events.on('ConfirmYes', function() {
  return {
    id: 'target Objct ID'
  }
}, {
  once: true
})
    1
    2
    3
    4
    5
    6
    7
    • 参数说明：
    event: 事件名
cb: 回调函数，参数为接受的数据，当在函数中返回数据时，将会把返回的数据发回给TAPD
once: 是否只监听一次
    1
    2
    3

  • 发送事件给TAPD侧 .send({event: string, params: obj})

    // 特定的挂在点接受特定的事件，如下例子为列表更多操作拓展获取筛选条件、选中项目
const selected = await sdk.events.send({
  event: 'getSelectedContext',
})
    1
    2
    3
    4
    • 参数说明：
    event: 事件名
    1
上次更新: 2025-06-17 18:48:37

← 查询过滤-更多操作 →