前端JS-SDK能力说明
1. 概述
观远BI JS-SDK 是观远BI面向客户、合作伙伴提供的开放能力之一，便于其他系统通过JS代码的方式内嵌观远BI相关页面或者与观远BI系统进行通信。
此文档面向网页开发者介绍观远JS-SDK如何使用以及相关的注意事项。
JSSDK相关功能与早期提供的Web-SDK能力有一定重叠，建议未来使用全新的JS-SDK能力。
示例代码库：https://github.com/GuandataOSS/sdk-demo
注意：此功能自6.3版本开始生效。
2. JSSDK使用步骤
2.1. 步骤一：引入JS文件
在需要调用JS接口的页面引入如下JS文件：JS-SDK
2.2. 步骤二：按需参照技术说明文档使用JS-SDK中的能力
当前开放的能力如下：
frame模式内嵌仪表板
iframe模式内嵌卡片
联动内嵌仪表板筛选器（6.5.0之前不支持移动端联动）
联动内嵌卡片筛选器（6.5.0之前不支持移动端联动）
相关开放能力持续拓展中。 如有相关需求，欢迎通过观远数据技术支持、客户成功团队反馈。
3. 内嵌参数说明
3.1. 通用参数
属性 | 描述 | 是否必填 | 默认值 |
host | 观远BI 访问地址 如：https://demo.guandata.com | 是 | - |
domain | 域ID，默认值一般为 guanbi | 是 | - |
ssoToken | 免密登录Token | 是 | 参照sso 文档说明 |
theme | 主题 LIGHT: 朱鹭白 DARK: 月光蓝 | LIGHT （浅色主题） | |
ps | 内嵌模式指 | 参照此处说明 | |
width | 宽度 | 100% | |
height | 高度 | 300px | |
filters | 筛选条件 | JSON.stringify 之后的筛选数组（目前仅支持PC端卡片） | |
自定义访问属性 | 使用 data- 开头 | - |
自定义访问参数会转化为URL中的QueryString传递给观远BI系统。安全性起见，SSOToken的生产方式应该在后端完成，具体实现方式参考此处说明。
3.2. 场景化参数
卡片内嵌场景
属性 | 描述 | 是否必填 | 默认值 |
cdId | 卡片ID | 是 | - |
仪表板内嵌场景
属性 | 描述 | 是否必填 | 默认值 |
dashboardId | 仪表板ID | 是 | - |
4. 筛选器参数说明
4.1. 通用参数
属性 | 描述 | 是否必填 | 默认值 |
name | 筛选器名称 | 是 | - |
filterValue | [ '筛选值' ] | 是 | - |
filterType | 筛选类型 | 是 |
筛选类型和筛选值
filterType表示筛选类型，其中的值有如下可选。filterValue表示筛选值，必须是一个字符串数组，它根据filterType的不同表示筛选条件也不同。
IN：表示选择筛选，filterValue可以是多个值，表示选择多个筛选值。
EQ: 表示相等，filterValue只能是一个值。
NE: 表示不相等，filterValue只能是一个值。
CONTAINS: 表示包含，filterValue只能是一个值。
NOT_CONTAINS: 表示不包含，filterValue只能是一个值。
STARTSWITH: 表示以...开始，filterValue只能是一个值。
ENDSWITH: 表示以...结束，filterValue只能是一个值。
NOT_STARTSWITH: 表示不以...开始，filterValue只能是一个值。
NOT_ENDSWITH: 表示不以...结束，filterValue只能是一个值。
BT: 表示区间，filterValue只能是两个值，表示区间范围。
GT: 表示大于，filterValue只能是一个值。
GE: 表示大于等于，filterValue只能是一个值。
LT: 表示小于，filterValue只能是一个值。
LE: 表示小于等于，filterValue只能是一个值。
IS_NULL: 表示为空，filterValue中没有值。
NOT_NULL: 表示不为空，filterValue中没有值。
注意： 传入的筛选参数中的filterType和filterValue需要与所要匹配的内部筛选器相匹配。 比如内部筛选器为选择筛选器，则传入的filterType必须是“IN”。**
4.2. 场景化参数
卡片筛选器联动场景
属性 | 描述 | 是否必填 | 默认值 |
fdId | 字段ID | 是 | - |
仪表板筛选器联动场景
属性 | 描述 | 是否必填 | 默认值 |
cdId | 筛选器卡片id | 是 | - |
5. 使用示例
5.1. 内嵌一个仪表板
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<gd-dashboard
host="https://demo.guandata.com"
ssoToken="**********"
domain="demo"
dashboardId="k5ec1f12793f649c3960ec2a"
ps="iframe2"
></gd-dashboard>
</body>
<script src="js-sdk.js"></script>
</html>
5.2. 内嵌一个卡片
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<gd-card
host="https://demo.guandata.com"
ssoToken="**********"
domain="demo"
cdId="lf0c8ab616a394559b180529"
ps="embed"
></gd-card>
</body>
<script src="js-sdk.js"></script>
</html>
5.3. 内嵌仪表板并联动筛选器
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<gd-dashboard
id="custom-dashboard"
host="https://demo.guandata.com"
ssoToken="**********"
domain="demo"
dashboardId="k5ec1f12793f649c3960ec2a"
ps="iframe2"
></gd-dashboard>
</body>
<script>
const $dashboard = document.getElementById('custom-dashboard');
function setDashboardFilter () {
$dashboard.setAttribute('filters', JSON.stringify([{
cdId: 'q9db09a2e5b8b44a4a46b271',
name: '测试',
filterType: 'GT',
filterValue: ['2020-03-01']
}]));
}
</script>
<script src="js-sdk.js"></script>
</html>
5.4. 内嵌卡片并联动筛选器
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<gd-card
id="custom-card"
host="https://demo.guandata.com"
ssoToken="**********"
domain="demo"
cdId="lf0c8ab616a394559b180529"
ps="embed"
></gd-card>
</body>
<script>
const $card = document.getElementById('custom-card');
function setCardFilter () {
$card.setAttribute('filters', JSON.stringify([{
fdId: 'l72472c483a2742de81e9767',
name: '日期',
filterType: 'EQ',
filterValue: ['2020-01-01']
}]));
}
</script>
<script src="js-sdk.js"></script>
</html>