开放平台文档

# 业务对象-更多操作(列表页)

# 介绍

业务对象-更多操作(列表页) 页面扩展提供了业务对象列表页面更多操作的扩展能力，如下图所示

图片描述

# 使用方式

图片描述

业务对象-更多操作(列表页)页面扩展支持嵌入已有页面和开发新页面两种使用方式。
如果有现成的页面，推荐使用嵌入已有页面方式；如果页面还没开发，推荐使用开发新页面方式。

# 方式一：嵌入已有页面

# 页面配置

配置说明如下

配置名 说明 格式 必填 示例
扩展点名称 Tab名称 STRING (0,20] 是 DemoTab
扩展点链接 扩展的地址 URL 是 https://tapd.woa.com/open_demo/app_for_list_tools?workspace_id=$workspace.id$&obj_type=$object.type$&obj_id=$object.id$
是否启用弹窗 选择「是」：则在点击扩展点后打开弹窗；选择「否」：则在点击扩展点后打开新的标签页。 BOOLEAN DEFAULT: 是 否
弹窗高度 生效时机：启用弹窗=“是” INTEGER (0,1080] DEFAULT:500 否
弹窗宽度 生效时机：启用弹窗=“是” INTEGER (0,1920] DEFAULT:800 否
隐藏弹窗按钮 生效时机：启用弹窗=“是”, 选择「是」：则隐藏弹窗底部按钮；选择「否」：则显示弹窗底部按钮。 BOOLEAN DEFAULT:false 否

配置示例

图片描述

# 上下文参数

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

# 事件通信

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

# 方式二：开发新页面

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

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

# plugin.yaml 配置

在 app/resources 下加入以下配置

app:
  resources:
    - key: app_for_list_tools
      name: Demo-列表更多操作拓展
      path: pages/app_for_list_tools_story
      tag: story
1
2
3
4
5
6

配置说明如下

配置名 格式 默认值 必填 示例 说明
key fixed 是 app_for_list_tools app_for_list_tools
tag enum 是 story 生效范围
story：需求
bug：缺陷
iteration：迭代
name string (0,20] 是 编辑关联Demo单 头部更多下拉菜单名
enable_dialog bool 否 DEFAULT: true true：则在点击扩展点后打开弹窗；
false：则在点击扩展点后打开新的标签页。
height int (0,1080] 否 DEFAULT:500
width int (0,1920] 否 DEFAULT:800
hidden_footer bool 否 DEFAULT:false 生效时机：启用弹窗=“是”, 选择「是」：则隐藏弹窗底部按钮；选择「否」：则显示弹窗底部按钮。

# 示例代码

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

welcome.vue 示例代码

<!--
 配置文档：http://o.tapd.woa.com/document/plugin-doc/learning/yaml/resources.html#app_for_list_tools
 -->
 <template>
  <div class="welcome">
    <t-upload 
      v-model="files" 
      :auto-upload="false"
    ></t-upload>  
  </div>
</template>

<script>
  // 前端JSSDK，具体文档参考：http://o.tapd.woa.com/document/plugin-doc/learning/fe-jssdk/
  import SDK from '@tencent/tapd-open-js-sdk';
  import { Upload as TUpload, MessagePlugin } from 'tdesign-vue';

  export default {
    data() {
      return {
        files: [],
      };
    },
    components: {
      TUpload
    },
    mounted() {
      this.sdk = SDK();

      // 监听弹窗确认事件，返回当前添加的图片
      this.sdk.events.on('dialogYes', async () => {
        if(!this.files.length) {
          MessagePlugin.info('请选择文件')
          return;
        }

        const file = this.files[0].raw;

        // 以下是勾选资源的信息
        const result = await this.sdk.events.send({event: 'getSelectedContext'});
        console.log(result);

        this.options = await this.sdk.handler('hello.workspaces', {
          file: file,
        }, {
          useFormData: true
        })

        console.log(this.options);
        this.sdk.ui.closeDialog({status: true})
      })
    }
  };
</script>

<style scoped>
  .welcome {
    padding: 30px;
  }
</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

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

# 上下文参数

# 获取选择的列表数据

  1. 使用TADP JSSDK 安装使用教程
  2. 获取选择的列表数据
// 特定的挂在点接受特定的事件，如下例子为列表更多操作拓展获取筛选条件、选中项目
const selected = await sdk.events.send({
  event: 'getSelectedContext',
})
1
2
3
4

# 如何获取

  • 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被调用时接收上下文参数

# 项目级

项目级上下文参数支持所有项目级扩展页面、业务对象级扩展页面

参数名称 参数描述
workspace.id 当前所在项目id
workspace.name 当前所在项目名称
workspace.pretty_name 当前所在项目英文名称
workspace.parent_id 当前所在项目父项目id
workspace.created 当前所在项目创建时间
workspace.creator 当前所在项目创建人
workspace.status 当前所在项目状态

# 系统级

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

参数名称 参数描述
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

← 业务对象-附加信息(详情页) →