---
url: "https://docs.succapp.com/v5/guide/README.md"
htmlUrl: "https://docs.succapp.com/v5/guide"
title: "山川软件产品体系"
---
---
order: 1
navTitle: 关于山川软件
indexTitle: 快速了解
---
# 山川软件产品体系
山川软件专注于打造优秀的BI、报表和低代码产品，产品线包括：SuccBI一站式大数据分析平台、SuccCI企业级报表报送平台、SuccAP模型驱动的低代码开发平台。\
依托这些产品山川软件将帮助更多客户敏捷、高效、低成本的交付各类企业级数据应用，持续为客户创造最大价值。
## SuccBI{#SuccBI}
SuccBI是一站式大数据分析平台，融合了数据汇集、加工、智能调度、自助分析可视化、中国式报表等功能，为企业提供一站式的大数据分析处理能力。
|效果|设计器|
| --- | --- |
|||
|||
更多功能：
- [数据加工](./data-process/README.md)
- [调度管理](./schedule/README.md)
- [数据管理](./data-gov/README.md)
- [可视化](./data-viz/dash/README.md)
- [报表](./report/new-report.md)
DEMO演示：[SuccBI](https://demo.succbi.com/v5/)
## SuccCI{#SuccCI}
SuccCI是企业级报表报送平台，擅长类Excel报表的多级填报和汇总，提供了纯Web的Excel风格的报表填报设计器、让业务用户可以零编码、快速构建各类报表填报系统，如集团年报月报系统、财务预算报表等。
## SuccAP{#SuccAP}
SuccAP是模型驱动的低代码开发平台，不同于表单驱动型低代码产品，SuccAP擅长敏捷构建企业级业务应用、移动App。可以以周、天为单位交付企业级应用，大大缩短开发周期，极大的降低项目交付的成本。
更多功能：
- [低代码概述](./app/overview.md)
- [应用设计器](./app/app-designer.md)
- [移动APP](./app/mobile/README.md)
- [SuperPage了解](./app/superpage/README.md)
- [工作流](./app/workflow/README.md)
- [二次开发](./dev/README.md)
DEMO演示：[SuccAP](https://demo.succbi.com/v5/demo-spg/案例)
[//]: # "**SuccBI**是一站式大数据分析应用平台，致力于**让BI真正的应用起来**。融合了数据加工、调度、可视化、报表、低代码应用等，帮助企业敏捷分析数据、创建业务应用。"
[//]: # "1. 连接各类分散的数据并进行加工、清洗、调度、元数据管理，帮助企业轻松汇集、管理和共享数据资产。"
[//]: # "2. 所见即所得的仪表板、大屏、报表等功能，帮助业务用户自助的完成美观的图表、中国式报表。"
[//]: # "3. 简单易用的表单流程能力，帮助用户自助搭建小业务应用。"
[//]: # "4. 企业级的报表填报能力，帮助企业和政府部门轻松采集报表数据。"
[//]: # "5. 灵活强大的SuperPage功能，可视化的制作个性化的业务应用页面。"
[//]: # "6. 低代码搭建个性化的业务应用能力，通过可视化设计+低代码开发的形式，低成本、低风险、高质量、敏捷交付复杂业务项目。"
---
url: "https://docs.succapp.com/v5/guide/whatsnew/README.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew"
title: "版本更新"
---
---
order: 1
navTitle: 版本更新
---
# 版本更新
!!!children (guide/whatsnew) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.6.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.6.x"
title: "5.6.x版本发行日志"
---
---
order: 93
navTitle: 5.6.x
---
# 5.6.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.6.x，本系列最新版本为[5.6.46](#5.6.46)。
## 版本详情{#release-detail}
### 5.6.46{#5.6.46}
> 发布于：2026年8月6日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DdcgWt8Q3O-gChjDtqoGIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DRJHQVwQ3O-gChi2r6oGIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccBI**：
- 支持了交叉浮动报表的展开收起功能
**产品平台能力**：
- 解决了表达式输入框函数列表为空的问题
### 5.6.45{#5.6.45}
> 发布于：2026年7月28日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DQUFS8UQ3O-gChid8qkGIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DQ-Ycd0Q3O-gChig8qkGIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 解决了下拉框查询异常，QUERY函数无法正常查询的问题
**产品平台能力**：
- 升级漏洞依赖并修复运行时兼容问题
### 5.6.44{#5.6.44}
> 发布于：2026年7月21日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DYsI4hQQ3O-gChjXtakGIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DZcuLTsQ3O-gChjZtakGIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccBI**：
- 解决了交叉浮动报表纵向主浮动单元格设置排序，报表分页后排序未生效的问题
- 解决了报表编译信息不稳定的问题
**SuccCI**：
- 解决了半年报，单元格使用pre函数取上期报错的问题
- 解决了表单左侧树查询为空的问题
**产品平台能力**：
- 解决了Oracle加工union字符集不匹配的问题
- 解决了模型上设置动态排序降序和生效条件不生效的问题
### 5.6.43{#5.6.43}
> 发布于：2026年7月3日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单修改数据提交保存显示成功但实际未更新的问题
- 解决了设置数据范围后普通用户勾选单个填报单位解锁未生效的问题
**SuccAP**：
- 解决了菜单项执行交互时计算当前行的逻辑错误问题
**产品平台能力**：
- 解决了微信小程序登录登录第一条件设置为小程序用户ID报错的问题
### 5.6.42{#5.6.42}
> 发布于：2026年6月23日
此版本解决了如下问题：
**SuccAP**：
- 解决了4.x版本元数据升级到5.x数据交互属性未正确升级的问题
- 上传附件补充钩子函数，可用于压缩附件
- 解决了步骤条动态项切换报错的问题
- 解决了门户节点使用缩略图设置图片时，保存刷新后失效的问题
**产品平台能力**：
- 解决了mysql上单点登录出现code失效的问题
### 5.6.41{#5.6.41}
> 发布于：2026年6月5日
此版本解决了如下问题：
**SuccCI**：
- 解决了工作流撤回后，流程实例最近处理结果未更新的问题
**SuccAP**：
- 解决了签名图片导出为PDF不显示的问题
- 解决了输入框为空时，实际写表写入了null值的问题
- 解决了ios移动端路由返回可能不对的问题
- 解决了ocr获取不到已存入表中附件的问题
**产品平台能力**：
- 解决了数据源连接异常导致系统自动备份失败的问题
### 5.6.40{#5.6.40}
> 发布于：2026年5月15日
此版本解决了如下问题：
**SuccBI**：
- 解决了集群节点下报表编译信息可能不稳定的问题
**SuccAP**：
- 解决了移动端返回效果不对的问题
- 解决了下级菜单设置交互报错的问题
**产品平台能力**：
- 解决了附件数据加工后无法在页面中预览的问题
- 解决了达梦数据库下未作用项目设置中null值排在最后的问题
### 历史版本{#old-version}
::: details 更多版本
**5.6.39**
> 发布于：2026年4月30日
此版本解决了如下问题：
**SuccBI**：
- 解决了地图区块图层设置了悬停样式和阴影后渲染效果不对的问题
- 解决了地图区块标签报错的问题
**SuccAP**：
- 删除数据支持select函数
- 支持OCR识别
**产品平台能力**：
- 解决了查询条件使用数组过滤时，生成sql错误的问题
- 解决了加工汇总，内部引用不同表的同名字段时生成sql不对的问题
- 解决了不提取加工中有字段存在对应国际化字段时出现空指针异常的问题
- 解决了使用计算字段作为文字字段报错的问题
- 解决了数据库扩展无法编辑的问题
**5.6.38**
> 发布于：2026年4月16日
此版本解决了如下问题：
**SuccCI**：
- 解决了填报单位对应的维表主键字段为整型时，点击填报单位列表报错的问题
- 解决了填报单位列表没有勾选框列时对应的勾选相关菜单选项没有自动隐藏的问题
**SuccAP**：
- 支持了扫码交互
- 支持了日期组件手动输入
- 解决了流程数据源对话框设置显示错误问题
- 解决了对话框内组件依据对话框外组件内容设置显示条件不生效的问题
- 解决了上传附件校验样式错误的问题
**产品平台能力**：
- 支持了数据后端脚本模型
- 解决了用户组管理应用中，提交保存后切换页面仍会提示修改未保存的问题
- 解决了kingbase9在pg模式连接时提示空指针的问题
**5.6.37**
> 发布于：2026年3月27日
此版本解决了如下问题：
**SuccCI**：
- 解决了批量校验时反复校验同一条错误的数据时会导致校验结果表内容被删除的问题
- 解决了带下级按钮的按钮本身交互不生效的问题
- 解决了批量导入表单数据时报违反查询约束错误的问题
**产品平台能力**：
- 支持了TiDB数据库
- 解决了插入语句中使用单行数据集字段报错的问题
- 解决了任务模块删除内容报错的问题
- 解决了数据提取设置更新已有数据时，设置的更新忽略字段不生效的问题
- 解决了加工字段出现字段别名重复的问题
**5.6.36**
> 发布于：2026年3月5日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单单元格没有绑定字段时，允许多选不生效的问题
**产品平台能力**：
- 解决了oracle11g作为默认数据库启动不成功的问题
**5.6.35**
> 发布于：2026年2月6日
此版本解决了如下问题：
**SuccBI**：
- 解决了图形设置排序规则下钻后排序规则不生效的问题
- 解决了地图散点图层选择经纬度字段后无法显示标签的问题
**SuccAP**：
- 解决了打开链接交互链接输入框按回车键会报错的问题
- 解决了以只更新已存在数据的方式导入数据时，数据结果错误的问题
**产品平台能力**：
- 解决了系统内多处国际化错误问题
- 解决了权限界面修改密码后账号无法登录的问题
- 解决了华为云clickhouse加工总行数查询异常的问题
**5.6.34**
> 发布于：2026年1月23日
此版本解决了如下问题：
**SuccCI**：
- 解决了表格滚动不合法时渲染效果错误的问题
**SuccBI**：
- 解决了Activedoc中图形不展示的问题
**SuccAP**：
- 解决了程序流修改后执行的还是修改前内容的问题
- 解决了上传附件预览ppt效果不对的问题
- 解决了树搜索过程中切换搜索模式报错的问题
**产品平台能力**：
- 解决了修改密码后一直提示密码错误的问题
- 解决了达梦库type字段提示找不到字段的问题
- 解决了系统创建的ck数据表，写入数据，查看只有一半数据的问题
**5.6.33**
> 发布于：2026年1月8日
此版本解决了如下问题：
**SuccCI**：
- 解决了缓慢变化的填报单位切换数据期后表单仍展示当期不存在的填报单位数据的问题
- 解决了汇总的单元格触发了计算的问题
**SuccBI**：
- 解决了缓存导致的报表计算字段计算异常的问题
- 解决了仪表板下拉框设置隐藏统计数为0的项后效果不对的问题
**SuccAP**：
- 解决了TOINT中使用参数的计算字段循环计算导致报错的问题
- 解决了隐藏的附件组件提交报错的问题
**5.6.32**
> 发布于：2025年12月19日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单查询流程任务id时未带入流程id条件导致的报错问题
**SuccBI**：
- 解决了仪表板分组表表达式中输入层次本级或下级报错的问题
- 解决了自动过滤指定数据集选择全部编译报错的问题
- 解决了单元格表达式编辑栏编辑后回车效果不对的问题
**SuccAP**：
- 列表组件支持上传附件、图片属性设置
- 解决了列表下拉框搜索时失焦后值没有设置到单元格中的问题
- 解决了移动应用跳转到其他应用时可能无法返回的问题
**产品平台能力**：
- 解决了下载维表的请求里没有对field参数转义导致HTTP报400错误的问题
- 解决了执行大量sql时确认对话框样式错误的问题
- 解决了使用日期角色字段创建计算字段后查询报错的问题
- 解决了权限资源树名称列显示不全的问题
**5.6.31**
> 发布于：2025年12月5日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单填报单位树无法展开的问题
- 解决了删除浮动行后影响了无关的计算内容的问题
**SuccAP**：
- 解决了列表标题适用表达式时组件大纲树搜索报错的问题
**产品平台能力**：
- 支持保密字段查询时无法返回
**5.6.30**
> 发布于：2025年11月20日
此版本解决了如下问题：
**SuccCI**：
- 解决了上级单位汇总数据时产生多余空行的问题
- 解决了表单导出数据偶发导出其他单位或数据期的数据的问题
**SuccAP**：
- 隐藏了门户上尚未支持的消息中心设置
**产品平台能力**：
- 解决了ADDDATE函数计算时引用参数生成sql错误的问题
**5.6.29**
> 发布于：2025年11月3日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单跨表计算引用未实时刷新的问题
**SuccBI**：
- 解决了点击气泡图层图标以及气泡出现报错的问题
**SuccAP**：
- 列表组件支持选择面板选项配置
- 解决了在菜单组件中设置打开链接传参不生效的问题
**产品平台能力**：
- 选择计划时支持搜索
- 解决了系统设置的HTTPClient设置未生效的问题
- 解决了模型属性的过滤条件使用判断表达式查询数据有误的问题
**5.6.28**
> 发布于：2025年10月17日
此版本解决了如下问题：
**SuccCI**：
- 解决了浮动区域前存在隐藏的固定行时，导入效果不对的问题
- 解决了工具栏字段过滤组件显示标题不生效的问题
- 支持计算时仅计算部分工作表
- 解决了浮动行添加行行高不一致的问题
**SuccBI**：
- 解决了缓慢变化的维表以更粗的时间粒度查询时结果不对的问题
**SuccAP**：
- 解决了列表中按钮显示异常的问题
- 解决了复制数据加工模型设置使用加工的聚集字段来过滤出现异常的问题
**产品平台能力**：
- 支持数据库事务函数
- 解决了计划设置中依赖计划设置保存刷新后变成id的问题
- 解决了加工物理表节点添加数据库表来源表匹配出现的空指针问题
- 查询数据支持记录系统日志
- 解决了数据加工脚本节点不支持动态参数实时查询的问题
**5.6.27**
> 发布于：2025年9月28日
此版本解决了如下问题：
**SuccCI**：
- 解决了报表填报应用中修改前端脚本，元数据差异对比中没有显示修改内容的问题
- 解决了上级单位不允许上报数据时，工具栏保存按钮没有隐藏的问题
**SuccAP**：
- 解决了模型字段关联自身后，在列表中展示结果错误的问题
- 解决了绿色首页门户修改后排版出错导致标题重叠的问题
- 解决了暂存数据
**产品平台能力**：
- 解决了华为Hive模型字段长度获取问题
**5.6.26**
> 发布于：2025年9月18日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单带行表条件的浮动数据汇总结果不对的问题
**SuccBI**：
- 解决了仪表板使用渐变色时导出ppt以及pdf会报错的问题
- 解决了分组表设置标题行宽度范围无效的问题
- 解决了echarts移动端提示信息位置不正确的问题
- 解决了报表查询等待时未出现等待动画的问题
- 解决了报表浮动区域设置排序在某些场景下会错乱的问题
- 解决了报表查询数据为空时报错的问题
**SuccAP**：
- 解决了复制数据交互报字段不存在的问题
**产品平台能力**：
- 解决了vertica数据库在加工中使用参数创建计算字段后在页面中查看时会报错的问题
**5.6.25**
> 发布于：2025年9月5日
此版本解决了如下问题：
**SuccCI**：
- 解决了脚本批量导出导致内存溢出的问题
**SuccBI**：
- 解决了鸿蒙5.1系统下移动端内容超长没有显示滚动条的问题
- 解决了报表报错显示字段不存在的问题
**SuccAP**：
- 解决了GIS地图散点图层不显示提示信息的问题
- 解决了GIS地图散点图层放大到特定大小后部分散点不显示的问题
- 解决了下拉框内容变化后设置参数值未生效的问题
- 解决了列表中下拉框引用维键时使用数据集已有项报错的问题
**产品平台能力**：
- 完善了系统登录日志
- 解决了模型未提示与物理表字段差异的问题
- 解决了脱敏正则表达式效果与预期不符的问题
- 解决了外部用户管理界面刷新会报404错误的问题
- 解决了数据加工关联出现异常报错的问题
**5.6.24**
> 发布于：2025年8月22日
此版本解决了如下问题：
**SuccCI**：
- 解决了跨表引用有一致性维度的浮动单元格，在工作表未打开过时计算结果不对的问题
**SuccBI**：
- 解决了报表下拉框组件的一处空指针异常问题
- 解决了仪表板中隐藏的组件自动过滤仍生效的问题
**SuccAP**：
- 解决了spg调用上传附件组件的上传方法失效的问题
- 解决了修改参数或加工ActiveDoc未更新的问题
**产品平台能力**：
- 解决了模型表中多个字段关联同一维表，显示的结果不对的问题
- 优化了OEM包升级提示信息
- 解决了加工的输出节点，字段列表物理字段中下拉显示为空的问题
- 解决了Vertica数据库自动生成的父子维字段内容不对的问题
**5.6.23**
> 发布于：2025年8月8日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单修改数据不生效的问题
**SuccBI**：
- 解决了报表模型过滤OR条件sql翻译不正确的问题
**SuccAP**：
- 解决了spg在Chrome浏览器下打印分页内容会产生重叠的问题
**产品平台能力**：
- 解决了达梦数据库下部分不是关键字的字段被设置为了关键字的问题
- 解决了clob字段内容导出为Excel时显示为空的问题
- 解决了系统未记录页面查看日志的问题
**5.6.22**
> 发布于：2025年7月25日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单切换下拉框选项保存后选项内容变更为切换前选项的问题
- 解决了数据期列表未引用索引表时编译出错的问题
**SuccBI**：
- 报表支持topN筛选功能
- 解决了表格突出显示没有设置字体大小的图片图标不显示的问题
- 解决了仪表板组件标记区拖入字段报错的问题
**SuccAP**：
- 解决了移动应用标题显示错误的问题
**产品平台能力**：
- 适配了presto数据库
- 解决了有权限的用户无法修改组件风格的问题
**5.6.21**
> 发布于：2025年7月16日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单浮动行列的导出条件不生效的问题
- 解决了浮动行校验错误过多时，校验面板渲染缓慢的问题
**SuccBI**：
- 解决了报表中使用PRE函数计算报错的问题
**SuccAP**：
- 打开链接的面包屑支持国际化配置
- 支持按照条件控制字段过滤组件的候选字段是否显示
- 解决了门户图标大小设置不生效的问题
- 解决了门户设置logo字体效果异常的问题
- 解决了树组件设置单选但仍能多选的问题
**产品平台能力**：
- 解决了计划任务未按照设置的时间周期正常执行的问题
- 解决了达梦数据库下查看计划日志报错的问题
**5.6.20**
> 发布于：2025年7月4日
此版本解决了如下问题：
**SuccCI**：
- 支持标签页切换显示名称和描述
- 解决了mysql下无填报单位的报表填报应用锁定数据报更新函数校验错误的问题
- 解决了单元格内容变化后取数交互未正常执行的问题
**SuccBI**：
- 解决了仪表板中无维表的分组字段点击后错误触发下钻的问题
- 解决了报表浮动行列导出条件无效的问题
- 解决了报表嵌套交叉浮动时，内部存在单独的子浮动不交叉的情况下表样渲染结果不对的问题
**SuccAP**：
- 支持将列表中图片列内容导出到xlsx和pdf中
- 解决了设置组件属性交互第二次点击未生效的问题
- 解决了目标表字段过多时导入数据后部分字段内容会缺失的问题
**产品平台能力**：
- 解决了Hive数据库使用ADDDATE函数时，使用负数参数时报错的问题
- 解决了达梦数据库创建表，设置注释出现无效的列名的问题
- 解决了数据集加工全连接生产的sql不对的问题
- 解决了加工中字段使用ADDDATE函数sql翻译错误的问题
- 解决了打开链接到当前容器中时，切换语言会导致页面空白的问题
**5.6.19**
> 发布于：2025年6月25日
此版本解决了如下问题：
**SuccCI**：
- 解决了导入时维项过滤获取不到下拉框选项的问题
- 解决了导入时下拉框存在层级依赖导入效果不对的问题
**SuccBI**：
- 解决了使用ROW\_NUMBER函数计算的序号在列头排序后效果不对的问题
- 解决了报表单元格动态背景图片导出是重复图片的问题
- 解决了复制粘贴报表数据到文本输入组件时空白字符被更改的问题
- 解决了交互的事件表达式获取不到内容的问题
**SuccAP**：
- 解决了程序流复制数据写入的最后修改人内容不对的问题
- 解决了查询过慢时未显示等待动画的问题
- 解决了快速切换标签页会导致系统卡死的问题
**产品平台能力**：
- 解决了恢复备份时，备份包有内容的情况下文件内容被置为空的问题
- 解决了切换模型对话框，过滤条件字段有时候识别不出来的问题
- 解决了加工中同时去重和汇总生成sql不对的问题
- 解决了后端脚本方法sys.exeScriptAsync和sys.schedule报错的问题
**5.6.18**
> 发布于：2025年6月12日
此版本解决了如下问题：
**SuccCI**：
- 完善补足逻辑，当切换到当前工作表时才会补足当前页面内容
- 解决了跨表引用单元格.字段进行计算时，内容变化时不会实时触发计算的问题
- 解决了多个浮动取同一个表的数据时，取数表与填报表粒度相同时数据填充效果不对的问题
- 解决了单元格被过滤条件引用时，初次打开表单无法正常装载数据的问题
- 解决了维项增量查询时字段顺序改变导致维项显示异常的问题
**SuccBI**：
- 解决了报表多模型分组查询，动态字段，根据参数计算为常量字段，出现空指针的问题
- 解决了仪表板分组表链接出现空指针报错的问题
- 解决了报表自动撑大列宽效果不对的问题
- 解决了报表查询时化简连续join的sql时多生成了查询字段的问题
- 解决了仪表板交互设置生效条件为叶子节点时不起作用的问题
- 解决了隐藏组件自动过滤仍生效的问题
- 解决了报表更新数据后为保持滚动位置的问题
**SuccAP**：
- 解决了门户设置logo字体设置会相互重置的问题
- 解决了多字段层次树展示的值不对的问题
- 解决了提交可编辑表格，其中下拉框数据可能丢失的问题
- 解决了维项查询时超过默认限制行数会导致重复查询的问题
**产品平台能力**：
- 解决了表达式编辑框在搜索框中输入中文回车字符会导致填入重复内容的问题
**5.6.17**
> 发布于：2025年5月29日
此版本解决了如下问题：
**SuccCI**：
- 解决了报表填报应用没有适配主题风格的问题
- 解决了拖拽单元格行高后，在行显示隐藏状态发生变化后可能导致页面渲染效果错误的问题
- 解决了下拉框选项过滤结果不对的问题
- 解决了浮动表新增行序号列未正常计算的问题
**SuccBI**：
- 支持对仪表板图形刻度值设置最小最大刻度区间
- 解决了分组表中多模型分组查询时，分组字段是常量计算字段会导致报错的问题
- 解决了仪表板表格序号列、合计小计行列上触发交互不能获取列名和数据行的问题
- 解决了仪表板KPI组件在未设置交互的情况下鼠标移入仍显示手形的问题
- 解决了表格设置文本超出显示省略号导致撑大行高失效的问题
- 解决了嵌入报表组件导出方法设置参数无效的问题
- 解决了报表下拉框切换报错的问题
- 解决了报表点击列头排序会重置横向滚动条的问题
- 解决了报表拖拽包含特殊字符的字段到单元格中时会报错的问题
**SuccAP**：
- 解决了打开链接显示为对话框位置居右/居中查看时闪烁不能正常显示的问题
- 解决了计算器死循环导致的页面一直加载不出来的问题
**产品平台能力**：
- 解决了未在计划任务中执行过备份恢复，自动清理程序不会正确清理过期备份包的问题
- 解决了Hive加工嵌套子sql没有别名，执行有异常的问题
- 解决了加工查询结果使用的字段原始名而非quota字段名，导致的UI渲染错位的问题
- 解决了列加工面板切换时加工步骤列表显示为空的问题
- 解决了字段面板和数据面板的右键菜单选项不同的问题
**5.6.16**
> 发布于：2025年5月14日
此版本解决了如下问题：
**SuccCI**：
- 解决了获取表单生成的html较慢且无加载动画的问题
- 解决了带数据期的报表填报应用批量导入报错的问题
**SuccBI**：
- 解决了仪表板滑动面板过滤效果不对的问题
- 解决了仪表板以对话框形式跳转链接，未加载完成时快速关闭对话框会导致报错的问题
- 解决了表格冻结区域边界的边框效果不对的问题
- 解决了报表页面血统分析提供的sql查询与报表实际页面显示数据不一致的问题
**SuccAP**：
- 解决了日期框选择范围时国际化效果不对的问题
- 解决了字段过滤的子组件过滤时，过滤内容包含下划线会导致过滤结果不对的问题
- 解决了字段过滤组件的多值过滤结果不对的问题
- 解决了百分比大小设置的对话框在窗口变化后未随之缩放的问题
**产品平台能力**：
- 解决了在模型字段列表搜索字段名，快速连续切换到其他模型有几率出现报错的问题
**5.6.15**
> 发布于：2025年4月30日
此版本解决了如下问题：
**SuccCI**：
- 解决了提交表单报错“数据源有太多未关闭的连接”的问题
- 支持粘贴数据时触发默认值计算
**SuccBI**：
- 解决了报表多模型查询动态分组字段报没有一致性维度错误的问题
- 解决了topN动态排序排序方式没有生效的问题
- 解决了枚举数据集右键点击编辑出现报错的问题
- 解决了仪表板打开链接交互的link与样式脚本文件的link混乱冲突的问题
- 解决了扩展地图和渐变色图标的导出异常问题
- 解决了图标组件样式失真的问题
- 解决了面板标题风格样式界面显示空白的问题
- 解决了仪表板分组表交互执行异常的问题
- 支持了设计器非模型字段维项可以搜索查询
**SuccAP**：
- 解决了列表查询报数据缺失或不合法错误的问题
- 解决了组件默认值未按逻辑正常计算的问题
**产品平台能力**：
- 支持了为各个文件模块分配血统分析权限
- 解决了请求资源没有释放导致容器堵塞的问题
- 解决了系统设置显示执行sql关闭之后未生效的问题
**5.6.14**
> 发布于：2025年4月18日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单导入部分wps制作的xlsx表样会报错的问题
**SuccBI**：
- 解决了报表查看数据量与预览sql不一致的问题
- 解决了报表单元格中数值与其血统分析sql查询的数值不一致的问题
- 支持了明细表的双击、移入和移出的交互触发方式
- 解决了having退化维条件生成错误的问题
- 解决了最新版谷歌浏览器地图气泡图层无法显示图标的问题
- 解决了世界地图不显示散点的问题
**SuccAP**：
- 优化了列表多级表头拖拽列宽的体验效果
- 解决了引用表组件设置根路径为表达式后报错的问题
- 支持条件指示器子组件显示操作符
- 解决了列表交互传给页面参数后，菜单组件调整链接传递该参数未生效的问题
**产品平台能力**：
- 解决了数据量过大的模型显示层次报错的问题
- 解决了导出加工数据为Excel报错的问题
- 解决了周期快照节点计算将系统日期表跨源关联错误的问题
- 解决了OceanBase配置getTableComments模板错误导致报错字段不存在的问题
- 解决了分析模块展示了不该出现的脚本文件的问题
- 解决了项目标题过长会出现系统顶部标签向右延申导致其他模块无法正常显示的问题
- 解决了系统初始化提取计划执行失败且未输出日志的问题
**5.6.13**
> 发布于：2025年4月4日
此版本解决了如下问题：
**SuccCI**：
- 暂存交互支持确认提示框设置
- 解决了单元格中显示表达式字符串的问题
- 解决了粘贴浮动主单元格到另外一个浮动区域报错的问题
**SuccBI**：
- 支持报表冻结行列后滚动到尾部行列不允许继续滚动设置
- 解决了仪表板下拉框选择一项单位报错，选择多项不报错
- 解决了仪表板有自动滚动的明细表时，打开链接交互打开的对话框会自动关闭的问题
- 解决了对话框形式打开报表时，调整浏览器窗口大小时对话框不会自动居中的问题
- 支持组件设置中数据集字段下拉框，默认显示搜索框
- 解决了模型表关联自己后，spg里表达式对话框里编辑过滤条件报错死循环的问题
- 多度量饼图支持中心显示合计值的同时图例显示分组标签数值
- 解决了仪表板文本框样式风格设置无法正常配置的问题
- 解决了报表下钻丢失参数栏参数的问题
- 解决了报表交叉浮动合计行数据错位的问题
**SuccAP**：
- 解决了列表勾选框的颜色主题不生效的问题
- 流程重启支持通过后端脚本调用
**产品平台能力**：
- 解决了mac绿色版安全告警无法启动问题
- 解决了登录界面记住密码选项控制问题以及cookie登录记录日志
- 解决了跨源关联时，前序节点增加了计算字段后，未自动同步临时表的问题
- 解决了两个物理表节点跨源关联，未自动生成临时表的问题
- 解决了SQL节点修改字段别名后出现元数据错误的问题
**5.6.12**
> 发布于：2025年3月27日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单中选择面板单元格不会自动撑大行高的问题
- 填报单位列表支持使用索引表字段进行过滤
**SuccBI**：
- 新增时间轴组件
- 解决了报表使用的事实表字段与关联维表主键字段类型不一致时，补全维项查不出数据的问题
- 解决了GaussDB(DWS)下做浮动查询，多个查询指标，给不同的条件，生成sql异常的问题
- 解决了仪表板表格组件在屏幕设置有缩放时滚动抖动
- 解决了设置组件属性切换标签页选项不生效的问题
- 解决了组合图风格中的圆角设置不正确
- 解决了字段数值相同时，条形图右标签无法正常显示的问题
- 解决了报表维表关联时字段类型不同导致导出时无法转文字
- 解决了仪表板中嵌入报表适配效果不好的问题
**SuccAP**：
- 解决了pg12下使用复制数据交互报数据库表不存在的问题
- 解决了移动端上传附件报错的问题
- 解决了上传附件后，附件无法删除的问题
- 解决了spg附件设置不允许下载后预览界面仍显示下载按钮的问题
- 解决了切换多页面版后列表的宽度不正确的问题
- 解决了门户缩放后滚动条消失的问题
- 解决了流程数据源设置根据流程设置显示隐藏或禁用输入项后会报错的问题
- 解决了在弹出菜单上设置显示消息框的交互不能传参的问题
**产品平台能力**：
- 支持适配华为GaussDB(DWS)
- 新增华为MRS中ClickHouse连接器，支持Kerberos认证
- 数据加工支持加工和脱敏
- 解决了字段对应的文字字段修改名称后没有自动识别的问题
- 解决了加工跨源提取到不能流式加载数据的数据库时，清空数据默认使用truncate导致可能出现查询到空白数据问题
- 解决了oracle11g查询数据表数据，出现数组越界异常的问题
- 解决了数据集设置启用脚本查询后编译异常的问题
- 解决了rawsql函数无法正常使用的问题
- 解决了sql查询模型使用的不是默认数据源时，在BI中进行引用会报错“数据库表不存在”
**5.6.11**
> 发布于：2025年3月10日
此版本解决了如下问题：
**SuccBI**：
- 解决了固定维计算yoy多模型复合运算时出现oom的问题
- 解决了报表下拉框全选后回车只显示部分被选中的问题
- 解决了分组表过滤后自适应高度效果不对的问题
- 解决了仪表板进度环设置系列标签样式为渐变色时效果不对的问题
- 解决了报表嵌套浮动外层浮动效果不对的问题
**SuccAP**：
- 解决了模型字段设置隐藏时，使用组件展示字段列表仍能展示隐藏组件的问题
- 解决了树组件设置条件样式后每刷新一次样式就有变化的问题
- 解决了连续快速点击可下钻列时会出现报错的问题
- 解决了多主键维表引入下拉框存在空指针异常的问题
**产品平台能力**：
- 支持适配ClickHouse数据库
- 解决了新建查询、加工或空白模型时点击其他已有模型会额外新建一个空白模型的问题
- 解决了修改被调用action.ts后需要重新保存一下webApi.action.ts才会生效的问题
**5.6.10**
> 发布于：2025年2月18日
此版本解决了如下问题：
**SuccCI**：
- 优化了校验面板展示逻辑，展示参数时默认使用参数名称
- 解决了应用设置中勾选填报明细后取消勾选设置仍生效的问题
- 解决了工具栏字段过滤配置允许多选不生效的问题
- 解决了工具栏维项过滤引用参数时编译出错的问题
- 解决了固定区域无绑定字段时取数结果不对的问题
- 解决了表单修改保存后需要清空系统缓存才能看到最新效果的问题
**SuccBI**：
- 解决了分组表年周条件查询的sql不正确的问题
- 解决了仪表板图形轴标签显示格式效果不对的问题
- 解决了条形图滚动效果不对的问题
- 解决了通过交互设置日期组件的属性不生效的问题
**SuccAP**：
- 解决了Excel列表图片列未显示图片的问题
- 解决了输入组件添加更多校验时报错的问题
**产品平台能力**：
- 解决了配置内网代理内容会报错的问题
- 解决了Oracle数据库下导出数据报错的问题
- 解决了删除未被引用的模型时仍弹出了引用关系对话框的问题
- 解决了扩展配置主体的colortheme未生效的问题
- 解决了资源管理页面增删文件刷新效果不正确
- 解决了distinct函数无法使用
**5.6.9**
> 发布于：2025年1月21日
此版本解决了如下问题：
**SuccCI**：
- 解决了单元格中下拉框图标上下空白区域也能触发下拉选项的问题
- 解决了手动取数没有重新发起查询的问题
- 解决了导入耗时过长的问题
- 解决了多个浮动单元格设置合并单元格，保存数据时报错的问题
**SuccBI**：
- 解决了过滤条件中存在多个条件引用字段相同时合并逻辑错误的问题
- 解决了移动端图形提示框总是显示的问题
- 解决了地图提示框样式风格设置不生效的问题
- 解决了嵌套交叉浮动横向无数据时填充报错的问题
**SuccAP**：
- 解决了ActiveDoc切换参数后绕排样式不正确的问题
- 解决了在应用文件下保存模型时取消会导致页面一直加载的问题
- 解决了字段过滤组件新增下级字段后继续操作会报错的问题
**产品平台能力**：
- 解决了人大金仓作为默认库更新异常的问题
- 解决了HANA只读数据库联合、新建拼接字段报错的问题
- 解决了列加工节点没有开放显示隐藏字段按钮的问题
- 解决了删除资源中被引用的参数时，确认对话框中的内容未国际化完全的问题
- 支持了打印预览，预览时可提供选项调整打印效果
- 解决了脚本节点无法在脚本中取模型参数的问题
**5.6.8**
> 发布于：2025年1月3日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单字段汇总方式为自动时编译出错的问题
- 解决了填报单位列表通过填报单位维展示单位属性结果不对的问题
- 解决了表单删除浮动行影响其他有一致性维度的浮动导致的报错问题
- 解决了表单粘贴数据报错的问题
**SuccBI**：
- 解决了固定维相同字段上既有动态条件又有固定条件时查询结果不对的问题
- 解决了固定维内存计算的超大数精度丢失的问题
**SuccAP**：
- 解决了列表展示动态列时冻结列比总列数多会报错的问题
- 解决了字段过滤组件表达式编译报错的问题
**产品平台能力**：
- 支持HANA数据库作为默认库
- 支持后端脚本使用runNodeJs运行前端脚本
**5.6.7**
> 发布于：2024年12月25日
此版本解决了如下问题：
**SuccCI**：
- 解决了提交后刷新页面，下拉框再次校验显示不在可选项范围内的问题
**SuccBI**：
- 解决了报表工作表导出条件未正常计算的问题
- 解决了报表允许手动设置冻结窗格无效的问题
- 解决了报表下钻丢失了全局参数的问题
- 解决了仪表板使用YOY函数计算同环比生成的sql不对的问题
- 解决了仪表板地图气泡图层设置的切换多页面板交互不生效的问题
- 解决了仪表板添加筛选条件查询结果异常的问题
- 解决了移动端ios系统下打开仪表板报错的问题
**SuccAP**：
- 解决了多页面板未显示页存在错误设置时提交表单不生效的问题
- 解决了上传附件设置填充报错的问题
- 解决了富文本组件设置点击交互未生效的问题
**产品平台能力**：
- 工作流文件支持国际化配置
- 解决了修改应用名称导致数据库死锁的问题
- 解决了将国际化语言指定为'zh(中文)'时，没有加载简体中文国际化文字的问题
- 解决了上传图片获取不到高宽时报错的问题
- 解决了给用户分配权限时数据范围不生效的问题
- 解决了引用用户表新增字段的数据范围权限不生效的问题
**5.6.6**
> 发布于：2024年12月13日
此版本解决了如下问题：
**SuccCI**：
- 解决了表单未锁定单位时，勾选单位删除数据提示数据已锁定的问题
- 解决了打回流程时未按照最新的处理人设置分配任务的问题
- 解决了保存表单后刷新页面浏览器提示更改未保存的问题
- 解决了导入时没有受到单元格计算条件影响导致部分数据在不满足计算条件可以输入时没有成功导入的问题
**SuccBI**：
- 解决了仪表板模版预览效果不正确的问题
**SuccAP**：
- 解决了粘贴数据交互设置属性效果不对的问题
**产品平台能力**：
- 解决了密码最长无修改天数判断错误导致无法登录的问题
- 解决了全局的批处理脚本任务无法删除的问题
- 解决了设计器脚本编辑器放大后按快捷键保存报错的问题
- 解决了脚本sourcemap行号错位的问题
**5.6.5**
> 发布于：2024年12月6日
此版本解决了如下问题：
**SuccCI**：
- 优化了报表填报应用构造编译信息耗时
- 支持了手动按指定数据集取数
- 支持通过脚本实现锚点菜单
- 流程退回意见框支持限制最大长度
- 解决了切换国际化后，导出的文件不能再导入进来的问题
- 解决了填报单位过滤后，刷新填报单位列表提示无权限的问题
- 解决了表单未锁定数据时删除单位数据报数据已锁定无法删除的问题
- 解决了浮动表按维项补足后，浮动行排序效果不对的问题
- 解决了表单浮动行有计算条件时，不计算的行无法正常导入数据的问题
**SuccBI**：
- 解决了下钻报表求PRE函数时链接条件导致的一致性维度问题
- 解决了报表点击链接交互后切换工作表报错的问题
- 解决了报表冻结窗格后单元格框选出现空白以及焦点不对的问题
- 解决了地图区块图层无数据时未生成样式导致的空指针异常问题
- 解决了重叠柱形图设置滚动指标会错位的问题
- 解决了仪表板移动端会同时出现多个提示信息的问题
- 解决了散点图状态样式设置显示格式报错的问题
- 解决了报表执行脚本交互传递参数提示缺少操作符的问题
- 解决了报表报无法识别的标识符问题
**SuccAP**：
- 解决了使用复制数据交互时报Column name duplicates异常的问题
- 解决了地图放大到一定程度后散点无法显示的问题
- 解决了缩放地图后散点图层不显示提示的问题
- 解决了地图缩放或拖拽后提示显示位置不对的问题
- 解决了切换着色图层筛选时，散点图层闪动的问题
- 解决了浅色门户下设置标签页会同时显示左侧树的问题
- 解决了门户中钻取子页面后刷新返回上页后再次刷新仍然是钻取页面的问题
- 解决了组件默认提示风格为空的问题
- 解决了列表更新数据后分页跳转异常的问题
**产品平台能力**：
- 支持了模型动态排序设置
- 解决了打开物理表后再打开任意模型报错的问题
- 解决了批处理保存时路径错误的问题
- 解决了程序流执行后端脚本传递参数提示缺少操作数的问题
**5.6.4**
> 发布于：2024年11月29日
此版本解决了如下问题：
**SuccCI**：
- 解决了流程审批意见输入框不能自适应对话框大小的问题
- 优化了流程图中审批意见的显示逻辑，默认能展示更多内容，空间不够能显示全部并允许粘贴
- 在没有设置填报单位时隐藏了多余的基层数据期列表设置
- 解决了导入Excel时，工作表名称包含特殊字符会导致无法识别的问题
- 解决了导入有换行符时导出Excel后再导入可能无法正常导入的问题
- 解决了表格滚动在焦点单元格是日期输入时会丢失焦点的问题
- 解决了无填报单位且展示数据期列表时，关闭表单没有返回数据期列表的问题
- 解决了表单锁定解锁对话框在只有单个单位的情况下设置交互不弹出确认对话框没有效果的问题
- 解决了下拉框展示下拉面板后快速切换其他单元格报错的问题
- 解决了表单使用$page变量切换到嵌入报表时会报错的问题
- 支持了多工作共用行表模型时，未提交过的工作表在当前单位已有数据的情况下也能算默认值
- 解决了表单添加行后指标表达式重构不正确的问题
**SuccBI**：
- 解决了报表查询结果查到了选定日期范围外的数据的问题
- 解决了计算countd时，当取值条件是多选时固定维计算生成的sql不对的问题
- 解决了数据期条件作用到了不需要作用的模型导致报错缺少关联关系的问题
- 解决了仪表板截图报错的问题
- 解决了仪表板地图提示图层未勾选显示提示时切换数据期会报错的问题
- 解决了kpi、里程表由于显示格式导致的空指针异常问题
- 解决了报表浮动排序报错的问题
- 解决了报表使用PRE(单元格)报错信息不友好且无法打开编辑器的问题
**SuccAP**：
- 解决了列表设置动态列后勾选列和序号列无法显示的问题
- 解决了SuperPage导出pdf效果不对的问题
- 解决了门户切换到已经打开过的页面时，丢失了选中状态的问题
- 解决了复制数据交互报字段不存在异常的问题
- 解决了IOS系统切换日期范围时无法切换年月的问题
- 解决了列表异常渲染问题导致的提交报错
- 解决了预览文件交互自定义文件名称设置效果不对的问题
- 解决了前端日期维计算层次字段值失败导致过滤结果为空的问题
**产品平台能力**：
- 支持了华为Hive
- 解决了脚本导出功能报错的问题
- 解决了查看模型sql报504错误的问题
- 解决了国际化设置面板筛选后复制粘贴效果不对的问题
- 解决了计算字段引用参数会导致总行数sql执行出错的问题
- 解决了日志级别为DEBUG时保存数据会写大量日志导致超时的问题
**5.6.3**
> 发布于：2024年11月15日
此版本解决了如下问题：
**SuccCI**：
- 支持右键查看单元格的引用关系
- 支持不限制每一期数据的填报开始时间
- 解决了表单查看时报超过了最大解析次数错误的问题
- 解决了脚本导入xlsx文件读取异常问题
- 解决了表单工具栏下拉框无法设置自定义显示格式的问题
- 解决了报表填报应用数据提交后，嵌入的报表未刷新的问题
**SuccBI**：
- 解决了F函数取一致性维度的浮动数据结果不对的问题
- 解决了日期组件设置高度效果不对的问题
- 解决了下拉框为空时过滤全部和选择所有选项过滤全部得到的结果不一致的问题
- 解决了仪表板浮动面板过滤TOPN结果不对的问题
- 解决了固定维报表显示结果和sql查询结果不一致的问题
**SuccAP**：
- 可编辑列表支持多行输入方式
**产品平台能力**：
- 解决了数据加工脚本节点返回sql时查看模型输出节点报错的问题
- 解决了直接在模型中修改数据确认修改时报错的问题
- 解决了人大金仓作为默认库初始化和更新后，抛出ALL\_MVIEWS不存在异常的问题
**5.6.2**
> 发布于：2024年11月6日
此版本解决了如下问题：
**SuccCI**：
- 解决了取数功能查询耗时较长的问题
- 支持了在报表填报应用设计器中以图标来区分不同类型的工作表
- 支持了在报表填报应用设计器中以特殊样式显示有设置隐藏或显示条件的行列头
- 解决了表单更新条件有维属性过滤和字段过滤时，生成的SQL中的字段没有加上正确别名导致报错的问题
- 解决了浮动区域主表存在主键字段在从表中没有时，该字段在行表条件中使用，浮动区域设置补足会导致报错的问题
- 解决了表单撤回流程后单元格编辑报错的问题
- 解决了浮动行表导出后再次导入数据错位的问题
**SuccAP**：
- 解决了用户存在多个数据范围权限时，编辑修改多行列表数据后保存数据会丢失的问题
- 解决了目标表有数据范围时复制数据交互SQL异常的问题
- 解决了加工的模型输出节点修改物理字段名与数据来源的物理字段名一致时复制数据交互SQL异常的问题
- 3D地图脱离了高德依赖，支持了扩展地图、扩展图层并优化了地图渲染效率
- 解决了点击字段过滤组件的清除按钮会错误触发修改数据事件的问题
- 解决了字段过滤组件的字段标题国际化未生效的问题
**产品平台能力**：
- 解决了数据加工连续联合节点生成的SQL不对的问题
- 解决了设置了数据保密的字段查询时返回了数据的问题
**5.6.1**
> 发布于：2024年10月29日
此版本解决了如下问题：
**SuccCI**：
- 解决了浮动表取前期数据时，浮动区域内有其他自定义取数公式取当期数据查询sql不对的问题
- 解决了有枚举数据集的报表填报应用发起流程会报错的问题
- 解决了浮动区域左侧有隐藏列时导入会出现错位的问题
- 优化了表单列数较多时的表格渲染效率
- 解决了单元格绑定内部加工时会导致删除数据报错的问题
- 支持了浮动区域填报多个模型的数据
- 优化了表单设计器加载效率，避免单元格和表达式过多时无法打开设计器
- 解决了切换视图后打开表达式对话框，对话框标题错误的问题
- 解决了浮动区域有行表条件时默认取前期结果不对的问题
- 优化了取数条件继承逻辑，支持单元格继承外层条件单元格上使用的取数条件
- 解决了导入或粘贴浮动表数据时默认值uuid未计算的问题
**SuccBI**：
- 解决了报表直接使用维表层次浮动时设置补足维报计算违反约束错误的问题
- 解决了没有一致性维度和关联关系的表查询报错提示不友好的问题
- 解决了报表查询使用UNION求文本出现字段缺失的问题
- 解决了仪表板散点图设置条件样式报错的问题
- 解决了仪表板布局组件设置条件样式报错的问题
- 解决了仪表板词云图应用渐变色色板效果不对的问题
- 支持仪表板富文本组件设置过滤器
- 解决了嵌套交叉报表查询卡住的问题
- 解决了报表过滤数据为空时，用于占位的空行显示了展开收起图标的问题
**SuccAP**：
- 解决了applyFilter函数多值退化维层级过滤异常的问题
- 解决了只有部分权限的用户使用复制数据交互报错的问题
- 解决了附件列表查询较慢的问题
- 解决了程序流中从模型获取字段内容不对的问题
- 解决了SuperPage设计器保存时偶发报错的问题
- 解决了字段过滤组件标题设置不对的问题
- 解决了标签页状态样式效果不对的问题
- 解决了富文本工具栏图层显示错误的问题
- 解决了嵌入文档无法正常滚动查看的问题
- 解决了发送用户消息交互设置参数报错的问题
**产品平台能力**：
- 优化了表达式对话框拾取逻辑
- 优化了表达式对话框输入内容提示，支持同时提示标题和id
- 解决了修改密码对话框清空密码框后编辑会出现提示错误的问题
- 支持了元数据文件通过API获取项目上配置的默认缩略图
- 解决了表达式对话框中帮助文档没有在新窗口打开的问题
- 解决了定时计划执行完成后手动执行可能会导致后续无法继续自动定时执行的问题
- 解决了DEMO试用版偶现启动异常问题
- 解决了多值字段翻译错误导致的过滤异常的问题
**5.6.0**
> 发布于：2024年10月18日
此版本增加了如下特性：
**新功能**
- activedocs功能重构，支持插入word原生图表、取数能力增强等
- Dash表格支持组件整体的条件样式
- 数据加工支持创建为普通视图和物化视图
- 新增$page全局变量，支持通过$page.activeSheet获取当前激活的工作表
- 枚举数据集、表达式数据集等数据管理列表支持修改物理字段名
**增强**
- Dash表格支持组件整体的条件样式
- 打开链接交互以对话框方式打开链接时支持不显示标题
- 表单复制粘贴支持复制显示隐藏条件
- 多个浮动区域支持一致性维度取数计算
- 模型上选择物理字段下拉选项优化
- 数据加工节点备注对话框UI优化
**修复**
- 修复了一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.5.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.5.x"
title: "5.5.x版本发行日志"
---
---
order: 94
navTitle: 5.5.x
---
# 5.5.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.5.x，本系列最新版本为[5.5.1](#5.5.1)。
## 版本详情{#release-detail}
### 5.5.1{#5.5.1}
> 发布于：2024年09月29日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/Dc2kbwIQ3O-gChiZttgFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DV2bPFEQ3O-gChjhktYFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 支持了链接单元格，可链接到其他工作表或外部链接等
- 解决了移动端填报效果不对以及不支持保存的问题
- 解决了存在交叉行表条件区域的表单自动汇总结果不对的问题
- 解决了切换工作表时计算单元格样式显示异常的问题
- 解决了固定区域部分有行表条件部分没有的情况下单元格装载数据可能不对的问题
- 解决了删除表格中完整的合并行后单元格边框效果异常的问题
- 解决了序列填充向右拖拽扩大范围时可能会出现报错的问题
- 解决了单元格内容未超出单元格范围时双击编辑会错误的扩大单元格范围的问题
- 解决了隐藏的单元格属性处理逻辑不完善导致计算后提交可能丢失数据的问题
**SuccBI**：
- 解决了报表设置折叠展开时会出现多余的空行的问题
- 解决了矩阵图双击下钻报错的问题
- 解决了仪表板导出csv数据没有实际下载文件的问题
- 解决了浏览器页面缩放后，图标组件没有重新渲染图片图标大小的问题
- 解决了地图使用枚举数据集字段类型没有生效的问题
- 解决了组件风格样式设置中缺少部分配置属性的问题
- 解决了仪表板表格无法使用ROW\_NUMBER的计算字段来显示序号列的问题
- 解决了报表query一致性维度hlevel分组查询文本字段没有增加max导致查询报错的问题
- 解决了表单全选单元格复制粘贴时页面会卡死的问题
- 解决了组件提示信息高频闪动导致无法看清的问题
- 解决了报表查询包含pre函数计算时，对计算字段列头排序sql异常的问题
**SuccAP**：
- 解决了applyFilter计算不带别名的维条件时出现空指针异常的问题
- 解决了字段过滤组件切换过滤条件操作符报错的问题
- 解决了下拉框多选设置默认值后取消勾选默认的选项会报错的问题
- 解决了使用对话框加载当前行数据第二次显示时无法正常加载的问题
- 解决了列表删除数据行后点击按钮弹出对话框编辑其他行无法正常加载数据的问题
- 解决了删除数据交互在模型有删除标记字段时设置物理删除不生效的问题
- 解决了拖拽组件到大纲树会报错的问题
- 解决了列表组件勾选和序号列显示条件不生效的问题
- 解决了复制数据交互合并模式无法使用的问题
- 解决了对话框形式打开链接时大小自动模式下没法纵向滚动对话框内容的问题
- 解决了组件大纲上点击对话框组件无法定位的问题
- 解决了缓慢变化维作为可选项时没有自动带上缓慢变化条件的问题
**产品平台能力**：
- 模型字段支持自定义汇总方式设置
- 解决了消息模版中定义的参数在模版配置中引用失效的问题
- 解决了达梦数据库clob字段显示不对的问题
- 解决了数据加工清洗功能提取数字结果不对的问题
- 解决了mysql数据库下导出系统内文件没反应的问题
- 解决了取消“允许用户同时多次登录”设置后账号仍可同时在多地登录的问题
- 解决了系统以默认方式备份会备份业务数据的问题
### 5.5.0{#5.5.0}
> 发布于：2024年09月12日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DfhFPgAQ3O-gChjottQFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DWFLfNAQ3O-gChjyttQFIAA)(提取码:SuccBI)
此版本增加了如下特性：
**新功能**
- 5.0支持rawsql函数
- 5.0缓慢变化支持兼容4.0等版本的格式
- 柱形图等图形组件支持标签遮挡优化
- 模型支持存储引擎、数据存储方式、数据存储方式配置
**增强**
- 数据加工提取支持重建主键和索引
- 棱形门户扩展支持语言切换功能
- 门户跳转到新页面支持自动带上语言参数
- 复杂交叉表装载效率优化
**修复**
- 修复了一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.4.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.4.x"
title: "5.4.x版本发行日志"
---
---
order: 95
navTitle: 5.4.x
---
# 5.4.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.4.x，本系列最新版本为[5.4.3](#5.4.3)。
## 版本详情{#release-detail}
### 5.4.3{#5.4.3}
> 发布于：2024年09月06日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DWNLNm0Q3O-gChiO99QFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DdALaCcQ3O-gChiQ99QFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 支持了整表取前期数据设置
- 支持在提交的数据行表条件不完整的情况下能报错提示具体错误位置
- 解决了明细填报点击序号列标题会报错的问题
- 解决了浮动行表仅修改浮动主单元格内容会导致提交没效果的问题
**SuccBI**：
- 解决了KPI自定义风格修改时页面中没有实时渲染的问题
- 解决了KPI样式风格中单位属性的配置无法保存的问题
- 解决了KPI样式风格中指标值显示格式属性无法使用的问题
- 解决了仪表板画布背景图片填充效果不对的问题
- 解决了按钮图标设置不生效的问题
- 解决了时间戳格式在报表中自动显示格式错误的问题
**SuccAP**：
- 解决了应用门户中不能导入分析和数据模块资源的问题
- 解决了门户跳转时没有传递国际化语言参数的问题
- 解决了富文本输入提交的图片没有转成持久化内容的问题
- 解决了富文本资源下载请求时上下文重复两遍的问题
**产品平台能力**：
- 解决了4.x版本的模型导出后导入到5.x版本数据无法正常导入的问题
- 解决了ymatrix数据库下创建的报表填报应用提交会报错的问题
### 5.4.2{#5.4.2}
> 发布于：2024年08月30日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DS7PTmAQ3O-gChjN99MFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DczgBoAQ3O-gChjT99MFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 解决了FGET函数在获取浮动表数据时，条件参数使用AND会计算错误的问题
- 解决了sheet名称中存在特殊字符时，表达式拾取会无法识别的问题
- 解决了筛选单元格无法自定义图标显示位置的问题
- 解决了浮动行表补足维只会提交有修改的行的问题
**SuccBI**：
- 解决了快速切换饼图图例设置会报错的问题
- 解决了有合并单元格的报表导出边框效果不对的问题
- 解决了明细表表格条件样式渲染异常的问题
- 解决了表格字体大小变小行高反而变大的问题
- 解决了表格标题行配置还原默认配置未生效的问题
- 解决了打开链接交互的参数列表选择参数时没有显示参数名称的问题
**SuccAP**：
- 解决了门户切换国际化语言刷新页面会失效的问题
- 解决了门户切换页面条件样式效果不对的问题
- 解决了可输入列表列输入方式设置为下拉框时选择模式属性没有选项的问题
**产品平台能力**：
- 支持工作流发起时添加更多用户，退回后这些用户可以重新修改任务
- 解决了项目脚本在非应用中的设计器中无法获取脚本参数名的问题
- 解决了脚本中动态引用第三方脚本会报404加载错误的问题
- 解决了增加计划的对话框没有滚动条的问题
### 5.4.1{#5.4.1}
> 发布于：2024年08月23日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DZpJJW4Q3O-gChj37dIFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DdNuQvMQ3O-gChj67dIFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 支持了浮动表数据的排序设置
- 支持了区域粘贴
- 支持了导入Excel生成表样时能选择只导入部分sheet来生成
- 解决了浮动表排序设置的对话框错误显示标签页的问题
- 解决了单元格中设置交互条件无法直接引用当前sheet中单元格的问题
- 解决了有条件样式的表单导出效果不对的问题
- 解决了表单工具栏设置中按钮设置属性不对的问题
- 解决了行表部分数据装载为空值时会触发计算的问题
- 解决了嵌入报表时，参数设置没有候选项的问题
- 解决了单元格使用小键盘输入数字必须双击才能生效的问题
- 解决了绑定相同模型的浮动行表汇总错误的问题
- 解决了浮动行表汇总出现了多余的空行的问题
- 解决了英语环境下新建报表填报应用的对话框布局错误的问题
**SuccBI**：
- 解决了通过调用组件方法导出分组表得到的文件名称不对的问题
- 解决了仪表板饼图图里点击报错的问题
- 解决了获取文本时没有总是返回字符串的问题
- 解决了进度环组件图片填充使用条件获取图片动态url不生效的问题
- 分组表中计算字段暂不支持列头排序，隐藏相关设置
- 隐藏了尚未完全支持的导出所有页功能入口
**SuccAP**：
- 解决了程序流复制数据节点字段映射对话框可选择字段没有立即刷新的问题
- 解决了调用程序流交互的确认对话框设置没有生效的问题
- 解决了切换国际化语言后跳转到其他门户没有自动同步切换后的语言的问题
- 解决了嵌入iframe无法通过门户切换语言的问题
- 解决了富文本组件中缩略图预览效果不对的问题
- 解决了列表多级表头最外层表头无法设置对齐方式的问题
- 解决了列表默认对齐方式效果不对的问题
- 解决了按钮组件设置选中不生效的问题
**产品平台能力**：
- 优化了维属性计算查询合并逻辑，提高查询性能
- 所有模型都提供了自由查询功能入口
- 解决了内嵌加工解析不完备的问题
- 解决了修改模型后更新代码重启不会自动同步物理表的问题
- 解决了浮动展示树控件时，滚动后自适应宽度变宽后滚动回去宽度会变小的问题
- 解决了数据集行数字段不是整型的问题
### 5.4.0{#5.4.0}
> 发布于：2024年08月16日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DQmJEtAQ3O-gChjyqtAFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DSGiLPcQ3O-gChj2qtAFIAA)(提取码:SuccBI)
此版本增加了如下特性：
**新功能**
- 5.0模型支持自由查询
- 表单填报界面支持鼠标右键复制粘贴
- 页面数据集支持维度和度量互相转换
- superpage列表支持选中模式、默认选中项
- 审批通过后支持重启流程
**增强**
- 完善doris和startRocks的流式导入功能
- 分页导航组件优化默认行数显示
- 视频组件的视频来源支持数据库表字段
- 富文本内图片支持点击预览放大
**修复**
- 修复了一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.3.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.3.x"
title: "5.3.x版本发行日志"
---
---
order: 96
navTitle: 5.3.x
---
# 5.3.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.3.x，本系列最新版本为[5.3.2](#5.3.2)。该版本在[5.2.x](./5.2.x.md)版本基础上主要修复使用中的一些bug问题，提升版本整体的稳定性。
## 版本详情{#release-detail}
### 5.3.2{#5.3.2}
> 发布于：2024年08月02日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DZRrPhcQ3O-gChjh7M8FIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DWPFTPgQ3O-gChjj7M8FIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 单元格中支持了多行输入方式
- 修复了合并连续单元格的校验空值错误问题
**SuccBI**：
- 解决了图形组件标签自定义的富文本中不支持引用字段值的问题
- 解决了图形组件标签属性设置后显示异常的问题
**SuccAP**：
- 修复了移动端字段过滤组件设置下拉框选项过滤会导致报错的问题
- 修复了标签栏门户切换语言报错的问题
- 修复了提示风格在门户中不存在对应风格时会导致查看报错的问题
**产品平台能力**：
- 对脚本执行query的查询过程进行了优化减少整体耗时
- 修复了数据加工节点过滤条件错误显示以及覆盖的问题
### 5.3.1{#5.3.1}
> 发布于：2024年07月26日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DeNnyP0Q3O-gChib6s4FIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DbyUZjEQ3O-gChie6s4FIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了报表填报应用补足维项设置无法选择维键的问题
**SuccBI**：
- 修复了仪表板组件风格对话框无法正常设置的问题
- 修复了仪表板定时刷新没有生效的问题
- 修复了交叉表色阶条件样式配置属性重复的问题
- 修复了设计器中双击富文本显示的富文本编辑效果不对的问题
- 修复了面板条件样式未正常生效的问题
**SuccAP**：
- 支持了门户应用的水印设置
- 修复了列表组件列上设置显示格式不生效的问题
**产品平台能力**：
- 修复了系统语言为英文时，查看模型表属性设置会报错的问题
- 支持了在消息模版中获取CI流程的填报单位以及数据期信息
- 支持了docker部署
### 5.3.0{#5.3.0}
> 发布于：2024年07月13日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DQnTpcgQ3O-gChiF3MwFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DbofenkQ3O-gChiA-ssFIAA)(提取码:SuccBI)
此版本增加了如下特性：
**新功能**
- 表单支持禁止复制剪切粘贴
- 系统支持自定义扩展表达式
- 5.0适配人大金仓KingbaseES V8数据库
- 进度日志支持动态变化日志
- 门户支持左侧树单节点时配置隐藏、显示、折叠
**增强**
- 仪表板条形图支持x坐标轴位置居上显示
- superpage树组件支持统计数
- Doris和StartRocks支持流式数据导入
- 列表、浮动面板组件表达式支持获取行选中状态、行勾选状态
- 数值输入、文本输入组件支持匹配模式
- 系统属性栏重构优化
- 列表标题支持设置动态表达式
**修复**
- 修复了一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.2.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.2.x"
title: "5.2.x版本发行日志"
---
---
order: 97
navTitle: 5.2.x
---
# 5.2.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.2.x，本系列最新版本为[5.2.7](#5.2.7)。该版本在[5.1.x](./5.1.x.md)版本基础上主要修复使用中的一些bug问题，提升版本整体的稳定性。
## 版本详情{#release-detail}
### 5.2.7{#5.2.7}
> 发布于：2024年08月08日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/Dbw4OOoQ3O-gChiC49AFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/Dcw54k0Q3O-gChiE49AFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了mysql下表单特例校验填写说明后提交会报程序流执行错误的问题
**SuccBI**：
- 修复了报表查询因为窗口函数没有嵌套而报错的问题
**产品平台能力**：
- 修复了压缩包解压脚本在只有一个文件时无法正常解压到文件夹的问题
- 修复了数据加工跨源提取时通过脚本调用提取会报错的问题
### 5.2.6{#5.2.6}
> 发布于：2024年07月19日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DZwuwTMQ3O-gChj2xM0FIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DW56-ycQ3O-gChj4xM0FIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了报表填报应用嵌入浮动报表报错的问题
- 修复了报表填报应用权限控制未生效的问题
- 支持了清空工作表交互，默认可选择清空当前或是所有页
**SuccBI**：
- 修复了仪表板编辑图形字段过滤条件报错的问题
**SuccAP**：
- 修复了复制数据交互对富文本附件提示使用系统证书解密失败的问题
- 修复了列表中快速点击按钮打开对话框会报错的问题
**产品平台能力**：
- 修复了项目logo和缩略图上传后保存会相互覆盖的问题
- 修复了配置redis哨兵模式提示连接不上sentinels的问题
- 修复了脚本提取数据时提示参数不合法的问题
### 5.2.5{#5.2.5}
> 发布于：2024年07月01日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DRzDIvAQ3O-gChjgtcoFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DZP5QRkQ3O-gChj2g8oFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了无填报单位无明细数据的报表填报应用无法锁定数据的问题
- 修复了表单浮动表新增行后会滚动到第一行的问题
**SuccAP**：
- 修复了移动端浮动面板会渲染出重复内容的问题
- 修复了执行流程交互属性名的错误国际化问题
- 修复了富文本中上传的图片、附件无法正常访问的问题
- 修复了ActiveDoc导出报错的问题
**产品平台能力**：
- 修复了移动端访问脚本地址报错的问题
- 修复了导入文件到数据不支持清空策略的问题
- 修复了系统证书无法正常展示的问题
- 修复了数据加工没有正确按主键合并追加的问题
- 修复了计划运行时重启会导致该计划始终显示执行且无法取消的问题
- 修复了企业微信PC端单点登录不可用问题
### 5.2.4{#5.2.4}
> 发布于：2024年06月14日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DXGOTK0Q3O-gChiB18cFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DQIoTt0Q3O-gChio38YFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了未填写的数据期显示所有填报单位已提交的问题
- 修复了表单工具栏更多按钮在提交按钮前面时会导致提交失败的问题
- 修复了表单引用不落地加工模型做计算时会导致查看界面报错的问题
- 修复了报表填报应用找不到脚本文件时设计器无法打开的问题
- 修复了明细填报勾选“提交后自动锁定”会报错的问题
- 修复了下拉框维项过滤后自动选中第一项不能正常触发影响计算的问题
- 修复了表单工具栏关闭按钮无法设置显示标题的问题
- 修复了明细填报表单工具栏的锁定按钮无法正常生效的问题
- 修复了导入带缩进的表样时，缩进会丢失的问题
- 修复了上传附件的单元格生成的字段没有附件角色的问题
- 修复了导入带公式的表样时会丢失部分公式的问题
- 修复了明细列表不支持展开收起的问题
**SuccBI**：
- 修复了报表单元格中拖入图片组件会报错的问题
- 修复了交叉浮动一个排序一个不排序会导致查询报错的问题
**SuccAP**：
- 修复了浮动面板中设置参数交互只有第一次能获取隐藏组件值的问题
- 修复了删除数据后回填数据进行检查修改导致的异常报错的问题
**产品平台能力**：
- 修复了修改项目描述会导致环境崩溃的问题
- 修复了用户组管理未打开用户标签页时修改用户组ID会丢失原先设置的用户的问题
### 5.2.3{#5.2.3}
> 发布于：2024年05月31日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DWGXVioQ3O-gChju6sUFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DfOULDwQ3O-gChj06sUFIAA)(提取码:SuccBI)
此版本解决了如下问题：
**SuccCI**：
- 修复了单元格图片填充未设置图片时保存会被还原成无填充的问题
- 修复了Excel浮动表数据没有正常导入的问题
- 修复了从零开始新建报表填报应用并配置流程发布后提交数据会报错的问题
- 修复了非管理用户编辑流程处理人以及行表条件会报错的问题
- 修复了创建信息管理应用报错的问题
- 修复了F函数引用自身时会导致提交卡死的问题
- 修复了表单补全维项，提交时会丢失缩进的问题
- 修复了冻结线范围设置没有自动重构的问题
- 报表填报应用支持了对当前表单做校验
**SuccBI**：
- 修复了报表补全年月数据错误的问题
- 修复了报表中使用相对层次浮动报错的问题
- 修复了报表嵌套浮动内层浮动无法取消的问题
- 修复了报表行列动态隐藏时，多次切换参数报表没有正常渲染的问题
- 修复了报表血统分析执行其他数据源sql报错的问题
**SuccAP**：
- 修复了spg拖字段到画布，生成的输入组件没有带上绑定字段的问题
**产品平台能力**：
- 修复了权限管理处新建用户后导出用户表为csv报错的问题
- 修复了汇总节点取年月字段报错的问题
- 修复了汇总节点取同环比相关指标，sql计算错误的问题
- 修复了汇总节点删除分组字段时，未将字段从数据列表中删除的问题
- 修复了汇总节点选择多个维键分组，添加后面的字段会导致前面的字段内容变成代码值的问题
- 修复了sqlserver获取表占用空间大小问题
### 5.2.2{#5.2.2}
> 发布于：2024年05月24日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DVWekaUQ3O-gChi528QFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DZ7PAFUQ3O-gChi728QFIAA)(提取码:SuccBI)
此版本解决了如下问题：
- 修复了表单信息管理应用嵌入spg提交数据会导致左侧树失焦的问题
- 修复了报表填报应用跨浮动区域合并单元格输入内容报错的问题
- 修复了报表填报应用分级小计校验异常的问题
- 修复了数据加工中编辑计算公式的偶发报错问题
- 修复了报表填报应用导入表样数据时没有忽略sheet名称大小写的问题
- 优化了系统用户组管理的使用体验，支持编辑分组
- 修复了分页打印时后几页没有标题的问题
- 修复了填报单位列表搜索不能定位以及报错的问题
- 支持了表单填报单位树的展开收起功能
- 修复了当表单数据列表缺少一些非必要的系统字段会导致报错的问题
- 修复了报表填报应用sheet名称与模型名称同名会导致变量识别错误的问题
- 修复了一处表达式计算报错的问题
### 5.2.1{#5.2.1}
> 发布于：2024年05月17日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DUIoC_UQ3O-gChjkwsMFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DcTB8aYQ3O-gChjqwsMFIAA)(提取码:SuccBI)
此版本解决了如下问题：
- 修复了报表对加密字段求max无法自动解密的问题
- 修复了往表单下拉框中粘贴数据报无权限的问题
- 修复了带有换行符的Excel表单复制到Excel中换行符被替换为空格的问题
- 修复了导入表单数据后，表单页面移入位置会变成空白的问题
- 修复了下载单个文件，文件名未按设置正常生成的问题
- 修复了单元格内设置换行符导出Excel未正常换行的问题
- 修复了Excel日期型数据导入到表单文本型单元格数据错误的问题
### 5.2.0{#5.2.0}
> 发布于：2024年05月11日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DdzgfS8Q3O-gChjTusIFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DVMCf7gQ3O-gChjYusIFIAA)(提取码:SuccBI)
此版本增加了如下特性：
**新功能**
- 可编辑列表支持从Excel粘贴数据
- 报表支持文本组件
- spg、dash等文件支持元数据标签
- 校验交互支持跨计算区域校验
- 产品logo等图片系统属性设置支持重置
- 5.0支持低代码工作流
**增强**
- 段落组件支持滚动到顶部固定
- 系统表主键优化
- 页面数据集维度字段支持汇总属性设置
**修复**
- 修复了一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.1.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.1.x"
title: "5.1.x版本发行日志"
---
---
order: 98
navTitle: 5.1.x
---
# 5.1.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.1.x，本系列最新版本为[5.1.1](#5.1.1)。该版本在[5.0.0](./5.0.x.md)版本基础上主要修复使用中的一些bug问题，提升版本整体的稳定性。
## 版本详情{#release-detail}
### 5.1.1{#5.1.1}
> 发布于：2024年04月26日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DQ1kBrMQ3O-gChjG_L8FIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DQj72mgQ3O-gChjIrb4FIAA)(提取码:SuccBI)
此版本解决了如下问题：
- 修复了sql-server数据库contains函数错误配置问题
- 修复了表单导入10万行数据量文件时会导致浏览器无响应的问题
- 修复了权限管理界面，勾选父节点没有自动勾选子节点的问题
- 修复了表单数据列表查询逻辑，以业务表作为主表查询
- 修复了系统环境备份报错的问题
- 修复了sql-server数据库作为默认库环境初始化创建表时抛出异常的问题
- 修复了加工源头是缓慢变化模型时，引入该加工作为数据源时会自动带上缓慢变化条件的问题
- 修复了用户有“权限管理”的权限但是不具备权限应用的权限时会出现权限异常的问题
- 修复了表单单位树中按钮与工具栏按钮元数据id一致的问题
### 5.1.0{#5.1.0}
> 发布于：2024年04月12日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/DRgLSbIQ3O-gChjZoLwFIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/Db9aenEQ3O-gChjaoLwFIAA)(提取码:SuccBI)
此版本增加了如下特性：
**新功能**
- 仪表板增加[段落布局组件](./5.0.x.md#section)
- 适配MaxCompute导入数据和DDL功能
- 单元格支持显示占位符
- 模型支持数据序号管理
- SQL数据源支持传入数组作为多值过滤
- 表单支持条件样式
**增强**
- 系统初始化欢迎界面和进度界面优化
- 完善了GIS地图中2D图层的显示效果
**修复**
- 修复了BI、AP、CI的一些bug问题
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/whatsnew/5.0.x.md"
htmlUrl: "https://docs.succapp.com/v5/whatsnew/5.0.x"
title: "5.0.x版本发行日志"
---
---
order: 99
navTitle: 5.0.x
---
# 5.0.x版本发行日志
## 版本说明{#release-notes}
欢迎使用SuccBI 5.0.x，本系列最新版本为[5.0.0](#5.0.0)。该版本进行了较大的架构调整优化，同时支持了全新的企业级数据采集平台（SuccCI）以及全面的国际化功能、数据源扩展等，[点击查看详情](#New-features)。
## 版本详情{#release-detail}
### 5.0.0{#5.0.0}
> 发布于：2024年03月01日 **下载**：[DEMO体验版](https://www.jianguoyun.com/p/De5bstEQ3O-gChiy4v0EIAA)(提取码:SuccBI) | [WAR包](https://www.jianguoyun.com/p/DTZWmVAQ3O-gChiZ5ooFIAA)(提取码:SuccBI)
此版本增加了如下特性：
- [SuccCI-企业级数据采集平台](#ci)
- [SuccBI-一站式大数据分析平台](#bi)
- [仪表板](#dashboard)
- [坐标轴图形组件支持滚动](#scroll)
- [饼图、象形图、矩阵图等支持多系列](#multi-series)
- [仪表盘组件增强](#gauge)
- [图形组件支持设置系列背景](#series-background)
- [仪表板支持3D地图](#3d-gis)
- [仪表板支持嵌入更多系统资源](#embedded-components)
- [仪表板新增布局组件-滑动面板](#sliderpanel)
- [仪表板表格组件增强](#table)
- [图片组件支持获取存储在数据库中的图片](#db-pic)
- [页面指标合并计算优化查询性能](#merge-calculations)
- [仪表板布局、缩放体验优化](#layout-scale)
- [提示信息支持嵌入页面、HTML](#htmlbi-tooltips)
- [报表](#report)
- [报表查看界面支持多Sheet页](#multi-sheets)
- [报表支持字段过滤组件](#field-filter)
- [报表支持按照层次折叠展开](#rpt-collapse)
- [SuccAP-低代码开发平台](#ap)
- [设计器](#designer)
- [崭新的设计器UI](#new-designer-ui)
- [Superpage页面支持缩放](#spg-scale)
- [数据集](#ds)
- [新增枚举数据集](#enum-ds)
- [新增表达式数据集](#exp-ds)
- [新增脚本数据集](#script-ds)
- [组件](#component)
- [新增布局组件-段落](#section)
- [浮动面板支持卡片布局](#floatpanel-card)
- [容器组件支持固定位置布局](#fixed)
- [列表组件功能增强](#list)
- [新增表达式输入组件](#exp-input)
- [新增管理引用表组件](#datasources)
- [日期输入组件优化](#datecombobox)
- [下拉框组件优化](#combobox)
- [新增支持时间输入组件](#timecombobox)
- [标签页支持动态选项](#tabbar)
- [快速搜索支持配置搜索规则](#searchbox)
- [上传附件输入配置简化](#upload)
- [功能](#ap-function)
- [组件状态属性与触发机制完善](#component-status)
- [数据集支持前端预加载](#ds-pre-load)
- [数据集支持灵活的排序设置](#ds-sort)
- [主从表增删改体验改善](#master-slave-curd)
- [自动过滤支持设置数据集范围](#auto-filter-range)
- [交互]()
- [新增交互-设置组件选中](#setting-component-selected)
- [新增交互-粘贴数据](#paste-data)
- [预览文件支持导航切换](#preview-file)
- [删除数据支持级联删除](#delete-data)
- [产品平台能力](#platform)
- [全面支持国际化](#i18n)
- [数据源支持扩展](#ds-extension)
- [数据期支持自定义扩展](#period-extension)
- [表达式函数优化](#exp)
- [数据管理](#data-mgr)
- [支持基于缓慢变化表的数据留痕功能](#data-traces)
- [去重组件支持按字段去重](#distinct)
- [汇总组件增强](#agg)
- [周期快照组件支持自定义周期范围](#snapshot)
- [列加工组件清洗功能支持提取日期](#extract-date)
- [数据角色新增支持地址角色](#address-role)
- [模型关联关系新增主从关系](#master-slave-rel)
- [模型缓存支持前端预加载](#model-pre-load)
- [模型数据行权限过滤支持指定权限字段](#row-permission-restriction)
- [模型层支持数据假删](#delete)
## 版本新特性{#New-features}
### SuccCI-企业级数据采集平台{#ci}
新版本提供了CI模块，补齐了原先4.x版本最为欠缺的Excel表格填报能力。CI是专用于应对各种企业级数据采集场景的产品，可广泛应用于各种财务、生产、管理、网络直报等数据采集的情况，最为常见的应用场景是按照一定周期定期的往指定单位上报数据的场景，如集团企业的财务年报，要求各分子公司每年末都需要上报各自公司的财务数据；卫健委需要每家医疗机构每年上报自己收治病人的情况。
CI整体提供类Excel式的设计以及填报体验，降低用户的学习成本；提供了多种取数计算逻辑帮助用户从多方面获取数据来源；与工作流高度集成，通过可视化配置的方式能够十分轻松的为数据上报搭配审批流程；采集得到的数据可直接用于系统其他模块进行分析，同时CI也与其他模块高度集成，支持嵌入报表以及低代码页面，能够提供更多丰富的页面效果。
更多功能介绍可参考文档：[报表填报概述](../ci/README.md)
产品DEMO可参考：[山川CI](https://demo.succbi.com/v5/ci/basic)
### SuccBI-大数据分析平台{#bi}
#### 仪表板{#dashboard}
##### 坐标轴图形组件支持滚动{#scroll}
在4.x版本中，坐标轴的维项过多时全部显示出来会非常拥挤，只能通过脚本实现显示固定个数并滚动轮播。
在新的版本中，坐标轴图形组件支持了滚动显示，可以通过配置轻松实现自动或手动滚动，不再需要脚本定制。
具体可参考DEMO：[柱形图滚动](https://demo.succbi.com/v5/bi/column-chart)
##### 饼图、象形图、矩阵图等支持多系列{#multi-series}
在新的版本中，对饼图、象形图、矩阵图支持了多系列指标，可以做出更丰富的图形效果。
具体可参考DEMO：[多系列饼图](https://demo.succbi.com/v5/bi/pie)、[多系列象形图](https://demo.succbi.com/v5/bi/pictorialbar)、[多系列矩阵图](https://demo.succbi.com/v5/bi/treemap)
##### 仪表盘组件增强{#gauge}
在新的版本中，对仪表盘组件做了增强，比如支持设置表盘形状、进度样式、指针形状等，可以实现更丰富的仪表盘效果。
具体可参考DEMO：[仪表盘](https://demo.succbi.com/v5/bi/gauge)
##### 图形组件支持设置系列背景{#series-background}
在4.x版本中，使用柱形图等展示百分比统计效果时通常希望柱子有灰色背景效果，但是只能通过多系列柱子设置成叠加来实现，如果是多系列的百分比指标分析则无法实现柱子带背景。
在新的版本中，对柱形图、条形图等支持了直接设置系列背景。
具体可参考DEMO：[柱形图背景](https://demo.succbi.com/v5/bi/column-chart)
##### 仪表板支持3D地图{#3d-gis}
在新的版本中，地图组件支持了3D地图，你可以在3D的立体空间中对地图自由的进行视角变换，俯视、仰视等，同时支持了3D的区块图层和棱柱图层，可以根据数据指标的大小控制区块或棱柱的显示高度。
具体可参考DEMO：[3D区块图层](https://demo.succbi.com/v5/bi/district-layer_1)
##### 仪表板表格组件增强{#table}
在新的版本中，对仪表板的表格组件做了比较大的增强，主要是如下4点：
1. 仪表板新增了分组表组件，与交叉表区分开，分组表中支持多级指标，即嵌套浮动时也支持显示上级的指标数据。
2. 分组表支持按照层次折叠展开。
3. 表格的背景填充支持横向填充、纵向填充、区域填充。
4. 支持更灵活的多级表头设置。
具体可参考DEMO：[表格](https://demo.succbi.com/v5/bi/grouptable)
##### 仪表板支持嵌入更多系统资源{#embedded-components}
在新的版本中，仪表板支持直接嵌入SuperPage、表单、数据模型、报表等各种系统资源，同时也支持嵌入网页、自定义HTML等，可以更轻松的与其他模块进行融合。
##### 仪表板新增布局组件-滑动面板{#sliderpanel}
在新的版本中，仪表板新增支持了滑动面板布局组件。滑动面板可以在同一个页面切换展示不同的面板，同时滑动面板自带轮播效果，可以使用不同的方式自动轮播切换页面内容。比如可以使用滑动面板轮播切换统计图表、电影海报、滚动播报新闻条等。
具体可参考DEMO：[滑动面板](https://demo.succbi.com/v5/bi/slider-panel)
##### 图片组件支持获取存储在数据库中的图片{#db-pic}
在新的版本中，图片支持支持新的图片来源方式，即数据表字段，可以方便的将存储在DB中的图片展示出来。
具体可参考DEMO：[动态图片](https://demo.succbi.com/v5/bi/film1)
##### 页面指标合并计算优化查询性能{#merge-calculations}
在4.0版本中，每个图形组件都会独立发起数据查询请求，当一个仪表板页面有很多组件时，会导致往后端发起过多的请求，带来性能问题。
在新的版本中，如果页面内组件的统计维度相同、过滤条件相同，则会被自动合并到一个查询请求，以避免产生过多的数据查询请求。
具体可参考DEMO：[合并计算](https://demo.succbi.com/v5/bi/mergequery)
##### 仪表板布局、缩放体验优化{#layout-scale}
在新的版本中，仪表板的布局、缩放体验做了如下优化：
1. 仪表板页面布局支持给一种类型的设备添加多种尺寸的布局。
2. 仪表板在不同分辨率设备上查看时自适应的算法进行了优化。
3. 优化了文字的缩放体验，所有组件的文字都可以进行缩放。
##### 提示信息支持嵌入页面、HTML{#bi-tooltips}
在4.x版本中，提示信息只支持富文本，没法做到更丰富的提示效果。
在新的版本中，提示信息可以支持嵌入任何系统内的资源，同时可以对嵌入页面进行动态传参，以及嵌入自定义的HTML页面。
具体可参考DEMO：[提示信息](https://demo.succbi.com/v5/bi/%E6%8F%90%E7%A4%BA%E4%BF%A1%E6%81%AF)
#### 报表{#report}
##### 报表查看界面支持多Sheet页{#multi-sheets}
在4.x版本中，报表查看界面不能显示多sheet页，只能配合选择面板来实现动态显示某个sheet。
在新的版本中，报表查看界面支持查看、切换多sheet页。
具体可参考DEMO：[报表多SHEET页](https://demo.succbi.com/v5/bi/%E5%88%87%E6%8D%A2%E5%A4%9ASheet)
##### 报表支持字段过滤组件{#field-filter}
在新的版本中，报表支持了字段过滤组件，可以更方便的实现灵活查询报表。
具体可参考DEMO：[灵活查询报表](https://demo.succbi.com/v5/bi/%E7%81%B5%E6%B4%BB%E6%9F%A5%E8%AF%A2%E6%8A%A5%E8%A1%A8)
#### 报表支持按照层次折叠展开{#rpt-collapse}
在新的版本中，报表支持按照指定的维度层次折叠展开查询报表。
具体可参考DEMO：[折叠展开报表](https://demo.succbi.com/v5/bi/%E6%8C%89%E6%95%B0%E6%8D%AE%E7%BA%A7%E6%AC%A1%E5%B1%95%E5%BC%80%E6%8A%98%E5%8F%A01)
### SuccAP-低代码开发平台{#ap}
#### 设计器{#designer}
##### 崭新的设计器UI{#new-designer-ui}
在新的版本中，对应用设计器的体验做了如下改善：
1. 将SuccBI、SuccCI、SuccAP三个产品及产品设计器页面进行颜色和logo的分类，让产品类别更明确
2. 将原本在一个树上的`文件`、`数据`、`API`、`设置`等大类分离出来，增强应用设计器的逻辑层次
3. 改善新建入口，由原来的通过下拉菜单新建改为直接从顶部新建，页面新建更便捷
4. 简化设计器多层边框，让界面UI更简洁干净
##### Superpage页面支持缩放{#spg-scale}
在4.x版本中，Superpage没有缩放功能，按照固定尺寸制作的页面给终端用户使用时，页面内容无法根据不同屏幕尺寸进行自动缩放。
在新的版本中，Superpage支持了缩放功能：
1. 设计器界面可以手动调整缩放比例，方便放大查看局部细节，缩小纵观整体布局。
2. 查看界面，可以根据浏览器尺寸自动计算缩放系数进行内容缩放。
#### 数据集{#ds}
##### 新增枚举数据集{#enum-ds}
在4.x版本中，下拉框、选择面板等只能通过在组件内部添加枚举项产生对象内临时的数据选项，组件内部的枚举项定义无法在其他地方复用。
在新的版本中，新增支持了枚举数据集，将枚举项融入到数据集的概念中，不仅在下拉框等数据组件内部可随时构造枚举数据集，同时也可以在页面全局添加可复用的枚举数据集。枚举数据集可以定义任意的字段属性，不再局限于代码、名称，同时枚举数据集还可以作为制作模板页面时的示例数据来源。
具体可参考DEMO：[枚举定义静态选项](https://demo.succbi.com/v5/ap/enum-select)
##### 新增表达式数据集{#exp-ds}
在新的版本中，新增支持了表达式数据集，可以灵活的、动态的将按约定格式计算返回的数据解析成数据集提供给页面组件使用，目前支持解析分隔文本、一维数组、二维数组、JSON格式的数据。比如：在问卷调查中可以根据上一个问题的选择动态生成下一个问题的选项列表。
具体可参考DEMO：[表达式构造动态数据集](https://demo.succbi.com/v5/ap/enum-dynamic)
##### 新增脚本数据集{#script-ds}
在新的版本中，新增支持了页面内的脚本数据集。使用脚本数据集能更灵活的从任意的来源获取数据，比如可以调用外部api获取并解析数据、调用内部接口获取到页面的运行状态、表单校验信息、资源的元数据信息等。
#### 组件{#component}
##### 新增布局组件-段落{#section}
在4.x版本中，制作有导航栏或有不同宽度段落的网页式页面时，需要面板层层嵌套，面板组件层次深，还需要反复设置每个面板的宽高属性，页面布局效率低下。
在新的版本中，新增了`段落`布局组件，可以更便捷设计页面布局。
##### 浮动面板支持卡片布局{#floatpanel-card}
在4.x版本中，浮动面板实现卡片布局的效果，设置很麻烦，同时如果最后一行数据不齐整时，效果有很大的缺陷。
在新的版本中，浮动面板新增支持了卡片布局方式，通过简单的设置即可呈现卡片布局的效果，数据不齐整时也不会有缺陷问题。
具体可参考DEMO：[卡片布局](https://demo.succbi.com/v5/ap/floatpanel-card)
##### 容器组件支持固定位置布局{#fixed}
在新的版本中，容器组件支持固定位置布局(fixed)，可以方便页面实现基于浏览器的浮动框效果，并且不随页面滚动。比如公司官网的咨询条、广告条等。
##### 列表支持直接编辑{#list}
在4.x版本中，列表组件只支持查询，需要修改数据时只能通过弹对话框编辑表单的方式来修改。
在新版本中，在列表组件上支持了类似Excel表格式的编辑体验，支持了自动计算，数据校验，新增行列，复制粘贴等新功能。
具体可参考：[可编辑列表](https://demo.succbi.com/v5/ap/editOperations)
##### 新增表达式输入组件{#exp-input}
在4.x版本中，没有提供可输入表达式的输入组件，在数据资产管理、数据治理等应用场景，需要在应用的查看界面由用户手动定义数据的校验规则等，只能通过脚本定制来实现。
在新的版本中，新增支持了表达式输入组件，将表达式规则的定义和管理引入到用户界面。在表达式计算规则的定义中还可以通过[管理引用表组件](#datasources)引入更多的模型表，比如业务用户可以引用多个来源表来定义指标的取数口径、取数条件等。
具体可参考DEMO：[表达式输入](https://demo.succbi.com/v5/ap/expinput)
##### 新增管理引用表组件{#datasources}
同[表达式输入组件](#exp-input)，在新的版本中，新增支持了管理引用表组件，主要与表达式输入组件配合使用，可以动态添加可使用的模型，并管理模型的过滤条件、关联关系等。
##### 新增支持时间输入组件{#timecombobox}
在新的版本中，将4.x中的日期输入组件中的时分秒等时间类型的输入方式拆分为新的时间输入组件，与日期输入区分开来。
具体可参考DEMO：[时间输入](https://demo.succbi.com/v5/ap/timecombobox)
##### 日期输入组件优化{#datecombobox}
在新的版本中，日期输入组件不支持输入时间，而是由[时间输入](#timecombobox)接替，另外，日期输入中的日期类型支持选择扩展的自定义数据期，具体见[数据期支持自定义扩展](#period-extension)。
具体可参考DEMO：[日期输入](https://demo.succbi.com/v5/ap/datecombobox)
##### 下拉框组件优化{#combobox}
在新的版本中，对下拉框组件做了一些体验优化，具体如下：
1. 可选项中选择维度时支持展开数据集选择维键字段
2. 选择维键时，可以控制数据来源于关联表还是数据集已有项
3. 增加了选择模式，多选时可以控制父子节点的选中是否联动
4. 下拉树展开时支持增量加载，即仅加载当前层级节点的数据，优化超大维表加载时的性能
具体可参考DEMO：[下拉框](https://demo.succbi.com/v5/ap/combobox)
##### 标签页支持动态选项{#tabbar}
在4.x版本中，标签页的选项只能是提前定义好的静态选项，不能随着数据的变化进行动态变化。
在新的版本中，标签页支持动态选项，可以通过数据集驱动显示动态的标签选项。
具体可参考DEMO：[标签页](https://demo.succbi.com/v5/ap/tabbar)
##### 快速搜索支持配置搜索规则{#searchbox}
在4.x版本中，快速搜索只能简单配置几个搜索字段导致搜索时会对所有搜索字段做like查询，数据量大时性能不好。
在新版本中，支持了搜索规则的配置，能对搜索内容做更精细化的控制，比如判断输入的是11位数字时可以只对手机号做完全匹配，极大的优化大数据量下的查询性能。
##### 上传附件输入配置简化{#upload}
在4.x版本中，上传附件的设置比较繁琐，每次都需要设置附件标题大小等字段。
在新版本中，附件的设置统一在模型字段上设置，上传附件只需要确定绑定的是哪个附件字段即可。
#### 功能{#ap-function}
##### 组件状态属性与触发机制完善{#component-status}
在4.x版本中，组件的状态支持的不好，如选中、悬停，有些组件有，有些组件没有，父容器选中触发子组件选中等，也缺乏统一的产品机制。
在新的版本中，对组件的状态属性与机制进行了完善，主要是如下几点：
1. 对容器、按钮等组件的属性中统一增加状态相关属性设置
2. 增强状态触发机制，子组件的状态可以由父容器状态触发，比如鼠标移入父容器同时自动触发文本子组件的悬停状态
3. 可以将多个独立的组件，比如多个KPI等进行分组选中切换
具体可参考DEMO：[组件选中和鼠标悬停交互](https://demo.succbi.com/v5/ap/component-status)
##### 数据集支持前端预加载{#ds-pre-load}
在4.x版本中，页面查询数据时总是会往后端服务器发送数据查询请求，比如修改下过滤条件，即使是模型数据量比较小，也没有办法将数据下载到前端计算，在高并发场景下，容易出现性能问题。
在新的版本中，数据集支持前端预加载，当选择`允许全量预加载`时，查询数据集时系统会自动忽略数据集上的动态条件（固定条件始终不会忽略，比如：`用户=$user`）后将数据一次性都下载到前端，此时页面再切换选项过滤时总是在前端过滤，不会往后端服务器发送数据查询请求。
##### 数据集支持灵活的排序设置{#ds-sort}
在4.x版本中，数据集不能设置排序方式，只能依赖原始模型的排序规则以及结合页面内的排序交互来实现数据的动态排序。
在新的版本中，在数据集上支持定义数据查询时的排序规则，包括自动、不排序、指定字段排序、动态字段排序。
##### 自动过滤支持设置数据集范围{#auto-filter-range}
#### 交互{#action}
##### 新增交互-设置组件选中{#setting-component-selected}
新版本支持了设置组件选中交互，主要用于通过交互触发组件的选中、取消选中、切换选中项等。比如在浮动的数据面板列表中，通过上一个、下一个切换选中数据项。
##### 新增交互-粘贴数据{#paste-data}
新版本支持了粘贴数据交互，主要用于将列表或数据集中的批量数据粘贴到对象列表中，比如从企业列表中挑选一批企业来填写他们的监管情况。
##### 预览文件支持导航切换{#preview-file}
在新版本中，在文件预览界面支持导航切换预览的文件。
##### 删除数据支持级联删除{#delete-data}
在4.x版本中，主从表的数据删除只能通过认为添加多个删除交互来分别删除主表以及从表的数据。
在新版本删除数据交互上支持了级联删除设置，支持在删除主表数据时，将设置范围内的从表数据同步删除。
### 产品平台能力{#platform}
#### 全面支持国际化{#i18n}
在新的版本中产品平台全面支持国际化，可以任意扩展配置国际化语言，支持将系统界面、用户业务界面以及业务数据等配置国际化信息，不同语言的人访问应用时可以使用自己的语言查看页面，也可以通过语言切换按钮一键切换语言。
具体可参考[国际化DEMO](https://demo.succbi.com/v5/DEMO/app/i18n.app?:id=ci&:orgId=010301&:dataPeriod=202401&:sheet=%E5%9B%BA%E5%AE%9A%E8%A1%A8)。
#### 数据源支持扩展{#ds-extension}
在4.x版本中连接一个SuccBI原生不支持的数据库时总是需要产品研发团队来修改原生代码来支持，遇到不支持的数据库时非常不方便。
在新的版本中数据源实现了插件化扩展，如果内置的数据库连接器无法满足特定的数据库连接需求，也可以通过扩展方式创建新的数据库连接器。
详细介绍请参考文档：[dbConnector扩展点](../dev/extension/extension-points/dbConnector/README.md)
#### 数据期支持自定义扩展{#period-extension}
在4.x版本中，系统自带了年月、年月日、年季等常见数据期，但是没有支持年周、年旬，且不能扩展。
在新的版本中，增强了数据期的扩展能力，可以根据实际需求自定义一个数据期类型，并在数据模型上的日期角色、页面的日期输入组件、表单的填报周期中进行选择使用。扩展数据期时具有如下特性：
1. 给已有的数据期类型扩展新的值格式，比如可以给年月日数据期扩展yyyy.mm.dd的值格式
2. 扩展实体数据期维，不同于系统自带的虚拟数据期维，实体数据期维等同于普通维表，有数据存储在对应的数据库表中
#### 表达式函数优化{#exp}
在新版本中，对表达式函数做了如下优化：
1. 索引下标统一从1开始，包括：FIND、SEARCH、MID、SUBSTR、SEEK等
2. 表达式中过滤层次数据需要包含下级时，在4.x版本中表达式可以写`[维键]='xxx'`，在5.0中区分了层次和字段的概念，需要写`[维键].[层次]='xxx'`，具体请参考文档：[操作符](../exp/operators.md#arithmetic)
#### 数据管理{#data-mgr}
##### 支持基于缓慢变化表的数据留痕功能{#data-traces}
在新的版本中，完善了基于缓慢变化模型的数据留痕功能，主要具有如下特性：
1. 系统自动识别缓慢变化模型，数据进行增删改时，自动维护缓慢变化起止时间
2. 支持补录，新增、修改、删除时都能指定发生日期
3. 支持批量维护缓慢变化数据，比如通过复制数据、导入数据等交互批量进行修改缓慢变化数据
4. 支持具有层次的缓慢变化模型的管理，比如父子层次的行政区划
##### 汇总组件增强{#agg}
在新的版本中，汇总组件在功能上做了如下增强：
1. 支持全表汇总，没有设置分组字段时即可汇总全表数据
2. 汇总方式支持第一条、最后一条，并支持排序设置
##### 周期快照组件支持自定义周期范围{#snapshot}
在4.x版本中，周期快照组件只能按照自然时间来界定周期范围，比如年月就必须从每个月1号开始，最后一天结束，不支持非标准周期范围。
在新的版本中，周期快照组件支持自定义周期范围，比如定义每月15号到下月15号作为当月的统计周期。
##### 去重组件支持按字段去重{#distinct}
在4.x版本中，去重组件只能分组去重，在新的版本中，去重组件支持了按照字段去重，等价于数据库中的DISTINCT去重。
##### 列加工组件清洗功能支持提取日期{#extract-date}
在新的版本中，列加工组件新增提取日期清洗方式，可以自动的从一段文本内容中将日期提取出来。
##### 数据角色新增支持地址角色{#address-role}
在新的版本中，字段角色新增了地址角色，用于标识字段数据的地理位置信息。比如给`企业ID`赋予地址角色属性，在GIS地图中展示企业分布的散点信息时可以直接拖入企业ID字段，系统能自动获取到企业的地理位置信息。
##### 模型关联关系新增主从关联{#master-slave-rel}
模型关联关系管理中支持主从关联，方便系统识别业务应用中实体模型之间的关系，并自动处理级联更新、级联删除等逻辑。
##### 模型缓存支持前端预加载{#model-pre-load}
在4.x版本中，页面加载维表数据时总是全量加载，如果维表数据量很大时会有性能问题。
在新的版本中，模型缓存中新增前端预加载配置，当设置成`按需加载`时，查询维表数据时可以按照展开层级增量加载。
##### 模型数据行权限过滤支持指定权限字段{#row-permission-restriction}
在有些业务场景下，事实表模型可能存在多个数据范围维度字段，可以通过指定数据范围对应的权限字段消除歧义。比如服饰销售表里有导购员、收银员，都属于员工维。当导购员张三查询数据时，需要使用导购员字段进行数据范围过滤。
##### 模型层支持删除标记{#delete}
在业务系统中删除数据时，通常是假删，即在模型上用删除标记字段来标识数据是否被删除。在新的版本中，模型层面支持了删除标记属性。当模型设置了删除标记字段后，在系统中删除数据，系统会自动处理维护删除标记字段。
## 语义化版本{#semantic-version}
SuccBI的版本号有3位数字构成:**`X`.`Y`.`Z`**，遵循[语义化版本规则](https://semver.org/lang/zh-CN/)：
1. `X`是主版本号，表示产品有结构性的变化和升级，不向前兼容。
2. `Y`是子版本号，表示产品有新功能和升级，向前兼容。
3. `Z`是阶段版本号，表示只有BUG解决，向前兼容。
---
url: "https://docs.succapp.com/v5/guide/data-connect/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-connect"
title: "连接数据"
---
---
order: 3
navTitle: 数据连接
indexTitle: 连接数据
---
# 连接数据
数据加工和分析需要连接已存在的数据，通常是业务系统的数据或文件数据，业务系统数据一般存储在关系型数据库中。对于存储在json文件中的，也可以通过[脚本数据加工](../data-process/transform/script.md)的方式获取数据。
在数据模块下，点击**新建**，可以选择不同的连接方式：
1. [数据库连接](#连接关系型数据库)
2. [上传数据文件](#上传数据文件)
## 连接关系型数据库{#connect-database}
数据存储在关系型数据库时，用此方式连接关系型数据库，即先在系统中建立一个到数据库的数据源配置，建立之后可随时对该数据库中的物理表进行加工处理。
切换至**数据**页，点击**新建**>**数据库连接**，在弹出框中新建数据库连接，详见[数据源管理](./datasources.md)。连接建立后，可在数据源列表中选中该数据库，用户可查看库中的物理表，并对其进行加工或导入等操作。详见[引入待加工数据](../data-process/add-data.md)。
若之前已建立过该数据库连接（可在**项目设置**中查看，详见[数据源管理](./datasources.md)），则无需重复建立，只需要在项目设置中设置项目可以使用该数据源即可，设置方式详见[项目数据管理设置](../project-manage/data-mgr-setting.md#data-sources)。
## 上传数据文件{#upload-data-file}
用于将本地的excel/csv等存储的数据文件上传到系统中作为数据源，如果文件较大还可以压缩成zip或rar格式上传。
1. **数据**>**新建**>**上传数据文件**，点击**上传**按钮选择文件或者直接把文件拖入。
2. 上传完成的文件存储在文件数据源目录下，用户可对其进行加工。详见[引入待加工数据](../data-process/add-data.md)
## 连接任意位置的数据或文件{#connect-any-data}
对于存储在非关系型数据库的数据，比如存储nosql数据、ldap数据、json数据或者在互联网网页上的数据，可以编写脚本代码获取这些数据（详见[数据加工脚本组件](../dev/script/backend/etl-script-node.md)）。以下两种方式最为常见：
[解析json数据](#解析json数据)
[爬取网页数据](#爬取网页数据)
### 解析json数据{#parsing-json}
数据是json格式的，可以使用[脚本](../data-process/transform/script.md)的方式解析json数据用于可视化分析。例如文件中电影的男女主角姓名、演员姓名等信息就是以json的形式储存的，通过脚本解析后就可以输出为易于分析的数据。
示例地址：[脚本组件](https://demo.succbi.com/v5/DEMO/data?:open=YuDsNh6mhFIA7ol1XHXuUD&:expandIds=KRSzynxUulEotgoUevK4sB%3BIqAQaqJPUmKsDd2XUtHtJE)
### 爬取网页数据{#crawling-web-data}
需要定时从互联网网页上获取数据，可以使用脚本的方式爬取。例如从丁香医生网页上每天爬取最新的疫情数据，并存储到本地数据库中。
示例地址：[爬取全球疫情数据](https://demo.succbi.com/v5/DEMO/data?:open=Cc5RIVUAw8BJdBAeQSePF&:expandIds=IqAQaqJPUmKsDd2XUtHtJE)
---
url: "https://docs.succapp.com/v5/guide/data-connect/datasources.md"
htmlUrl: "https://docs.succapp.com/v5/data-connect/datasources"
title: "数据源管理"
---
---
order: 1
navTitle: 数据源管理
---
# 数据源管理
数据源是SuccBI读取数据和存储数据的数据库连接，系统的元数据、日志、权限、用户信息、表单提交的数据会存储到数据源，报表、仪表板等对象的查询分析统计也需要用到数据源。
SuccBI的数据源是多[项目](../project-manage/README.md)共享的。
在**项目列表**中的**数据源**模块下，可对数据源进行管理。点击右上角的眼睛按钮，可以查看数据源的更多属性，如**数据库版本号**、**数据库版本信息**、**JDBC驱动信息**等，勾选即可显示对应属性。
## 新建数据库连接{#create-datasource}
点击**新建**，`连接数据库`窗口中展示了SuccBI支持的所有数据库类型，可通过顶部标签页按[数据库用途类型](../devops/install/database/README.md)进行筛选，同时也支持在搜索框中搜索指定名称的数据库类型
选择数据库类型后，点击**下一步**，配置[数据库连接属性](#properties-setting)，在**数据库配置**中填写数据源名称、用途和地址等必填信息，按需在**连接池配置**来设置最大连接数等高级属性
数据库连接属性配置完成后，点击**连接测试**，测试通过后点击`确定`即可完成数据库连接。连接成功后该数据库会出现在**项目**>**项目设置**>**数据**中的允许使用数据源中，选择该数据源后，才会在项目中能够使用，详见[项目数据管理设置](../project-manage/data-mgr-setting.md)
::: tip
若测试失败，仍可继续保存，后续修改后可继续测试。
:::
### 数据库连接属性设置{#properties-setting}
连接属性设置包含基础配置和高级配置，基础配置是必填项，高级配置是选填项。
**数据库配置**
- **名称**：项目中引用数据源时显示的名称（引用方式详见[项目数据管理设置](../project-manage/data-mgr-setting.md)），用户可自定义，新建后不能修改
- **描述**：描述该数据源的业务用途
- **用途**：根据权限不同，分为只读和可写。只读只允许读取数据，可写允许对数据和表结构进行修改。如果用户只有只读权限，但是用途设置为可写，数据库仍然能连接，但是写入数据时会提示用户没有权限，无法写入数据。
- **地址**：输入数据库地址和端口号，若输入的地址IP中带有端口号和数据库名，系统会自动识别填充
- **数据库名**：需要连接的物理数据库名称
- **JDBC URL**：数据库连接时，用来连接到指定远程数据库标识符。用户输入ip、数据库名和数据库类型后会自动生成一个JDBC URL。反之，输入JDBC URL也会自动生成ip、数据库名和数据库类型
- **用户名**：连接数据库用到的账户
- **密码**：连接数据库用到的密码
**连接池配置**
- **最大连接数**：数据库连接池的最大连接数，设置为100就是同时只能有100个连接在执行sql，若超过100个系统就会报错并显示超过最大连接数
- **等待超时（秒）**：数据库连接的最大等待时间，若数据库连接超过设置的时间，数据库会强行断开已有的连接
- **连接最大空闲时长（秒）**：数据库连接的最大空闲时间，当连接长时间未使用后将被关闭。连接池中的连接在长时间不使用时可能会由于某种原因而失效，但连接池并不知道，此时可以设置此选项，以丢弃长时间未使用的连接
- **连接最大使用时长（秒）**：数据库连接的最大使用时间，当连接自最初创建到现在的时间长度超过了这个最大使用时间，那么连接会被销毁（物理关闭），重新获取新的连接，保持连接池连接的新鲜度。主要为了解决长时间持有连接，可能出现的各种问题。
- **连接超时（毫秒）**：此设置是应用发起一个新的数据库连接时的超时，有时候不同的网络设置，可能某些数据库无法连接时会等待很长时间，此设置可以确保最多等待指定的时间，如果还未完成连接则抛出超时错误。
- **网络通信超时（毫秒）**：此设置是应用和数据库之间的网络通信读写超时，比如应用端从数据库段读取数据，如果超过这个时间没有返回任何数据则出现超时错误。
- **连接有效性检查**：用于获取连接时检查连接是否有效
- **启用健康检查**： 启用时将会定时检查连接池的状态，包括数据库是否能连接，自动侦测是否存在连接漏洞并自动回收。
- **镜像库**：启用镜像库功能，镜像库是数据库本身的能力，系统可以利用数据库的镜像能力做到读写分离和分散查询压力，增加系统的承压能力
- **镜像库URL**：启用镜像库功能后，需要配置镜像库的地址
- **镜像同步延迟时间**：设置一个镜像库延迟读取时间，用于修改模型数据后，是否延迟读取镜像库数据。单位秒，默认0，表示不延迟，可以直接查镜像库。比如：期望修改后5分钟内，只查主库，则设置为300
- **高级属性**：用于数据源的特定参数，详见[数据源自定义属性](#custom-properties)
### 数据源自定义属性{#custom-properties}
有些数据库要设置特定的属性，用于指定在数据源中管理表时的默认属性或者用于优化性能。这些属性通常是来自数据库内部的定义，也有产品内置的属性。在自定义属性框中以名值对的形式设置属性，如`databaseStatisticsSchedule=true`，不同的数据库类型设置的属性也不一样，可参考[jdbc配置文件格式](/dev/meta/jdbc-conf)。
## 编辑数据库连接属性{#edit-properties}
点击**操作**中的**编辑**，可修改该数据源的连接属性设置，**修改后无需重启服务**。修改页面与[新建数据库连接](#新建数据库连接)页面相同。
::: tip
由于default库是元数据数据源，因此只能点击**操作**中的**查看**来查看该数据源详细的连接属性信息，但无法编辑。
:::
## 删除数据库连接{#delete}
点击**操作**中的**删除**，再勾选**我确认删除数据源**进行确认后，可删除该数据源。数据源删除后，可从回收站恢复或者重新连接，**恢复后的数据源与删除前相同**。
## 刷新数据库连接状态{#refresh}
当数据源状态发生变化，例如数据库出现异常后运维工程师在后台修复，此时点击**操作**中的**刷新**，可刷新数据源状态，验证是否成功连接
## 默认数据库{#defdb}
默认数据库用来存储系统表和元数据，比如**default库**，除迁移环境时需要修改默认数据库以外，其它情况下不建议直接修改默认数据库，修改默认数据源时，修改的数据源属性会保存到工作目录的jdbc.conf文件中。详见[工作目录和默认数据库配置](../devops/install/basic-install/workdir-and-defdb.md)
## 分组管理数据源连接{#datasources-group}
当数据源很多时，可以根据业务分类对数据源进行分组管理，在**高级属性**处使用`group`属性定义分组。详见[jdbc配置文件格式](/dev/meta/jdbc-conf/)
---
url: "https://docs.succapp.com/v5/guide/data-connect/dbtable-mgr.md"
htmlUrl: "https://docs.succapp.com/v5/data-connect/dbtable-mgr"
title: "数据库表管理"
---
---
order: 2
navTitle: 数据库表管理
---
# 数据库表管理
系统提供了数据库表的管理功能，在[数据模块](../data-gov/README.md)下的**数据源**中，可以查看各个数据源的数据库表，右键选中的数据库表，可对其进行操作管理，如[导入为模型](../data-gov/import-table.md#data-table-import)、[查看数据](#view-information)、[导入数据库表](#import)、[导出数据库表](#export)、[血统分析](../data-gov/model/README.md#pedigree-analysis)以及其他[通用文件操作](../project-manage/file-mgr.md#operate)等，如下图所示：
## 查看数据库表信息{#view-information}
右键数据库表，弹出的菜单选项中，提供了多个查看快捷选项，如下所示：
- **新建查询**：打开[SQL查询窗口](../data-gov/sql-model.md#datasources-sql)并默认输入当前表的查询语句
- **查看数据**：打开数据列表查看页面，可分页查看表中的数据
- **查看结构**：打开字段列表页面，可查看数据库表的字段定义
- **查看DDL**：打开SQL页面，显示当前数据库表的创建语句
## 数据库表操作{#operate}
数据库表也可以像系统资源文件一样进行[导入和导出](../project-manage/file-mgr.md#import-export)、[复制](../project-manage/file-mgr.md#copy)、[重命名](../project-manage/file-mgr.md#rename)、[刷新](../project-manage/file-mgr.md#refresh)等操作。具体如下所示：
### 导入数据库表{#import}
数据源中也可以导入数据库表，点击**导入为物理表**选项即可，支持多种格式的导入，如xls、xlsx、csv、dbf、szdb等，大文件或包含同类数据的文件夹建议压缩成zip或rar文件后上传：
如果目标表存在，则需要选择处理方式以及文件编码：
- **处理方式**：
- 创建新表：导入的数据库表将重新创建一张新表，名称自动重命名，与同名文件共存，重命名的表尾部加入后缀1，默认为该选项
- 覆盖同名物理表：删除已存在的表，然后重新新建一张数据库表
- 清空同名物理表并插入数据：清空已存在的表数据，再重新写入导入的表数据，此时不允许增加字段，如果导入的数据库表字段比当前的多或名称不符，则会出现错误提示
- **文件编码**：可选择UTF-8或GB18030，默认为UTF-8
### 导出数据库表{#export}
如果备份少量表数据或者将表数据用作其他地方，则可以将数据进行导出，点击**导出表数据**选项即可，导出数据时可设置文件名称、导出格式、CSV编码等信息：
- **文件名称**：默认为数据库表名称，可自定义导出文件名称
- **导出格式**：可将数据导为CSV文件、EXCEL以及SZDB（兼容大字段）
- **CSV编码**：导出格式为CSV文件时，可设置其编码为GB18030（兼容excel）或UTF-8
- **压缩为zip**：勾选后，导出的数据文件为压缩包
:::tip
按住ctrl选中多个数据库表文件，可直接将多个文件导出为压缩包。
:::
### 复制数据库表{#copy}
数据库表可以像系统资源一样进行复制，且可以进行跨源复制，在**目标数据源**中切换成其他数据源即可。
复制数据库表时，目标数据库表如果已经存在，则会提示并且需要进行冲突处理，可以在对话框中修改**目标数据表**的名称，相当于自定义名称创建新表；也可以在**处理方式**中选择**创建新表**或者**追加数据到目标同名表**等，可参考[导入数据库表](#import)的处理方式。
---
url: "https://docs.succapp.com/v5/guide/data-connect/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-connect/faq"
title: "常见问题"
---
---
order: 9
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/data-connect/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/data-connect/errcode"
title: "数据库错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 数据库错误提示排查
## 数据源配置{#ds-config}
### 连接数据库失败{#err.db.connectionFail}
与数据库管理员确认，配置正确的[数据源属性](../datasources.md#properties-setting)。
### 数据源连接数量超过上限{#err.db.poolFull}
当系统在线用户增多时，对数据库的访问量也会增大，数据源默认有连接数限制，建议增大[数据源属性](../datasources.md#properties-setting)中的`最大连接数`，或者部署[集群](../../devops/cluster/README.md)分担压力。
## 数据库错误{#db-error}
### 该数据库无法流式写入数据{#err.db.cantBulkLoad}
提取文件数据源数据需要使用`LOAD DATA INFILE`语句，Mysql默认未启用，联系数据库管理员在[Mysql配置文件](../../devops/install/database/MySQL.md)中添加`loose-local-infile=1`，并重启Mysql服务。在数据库服务器启用后，若仍然出现该异常，则确认[数据源属性](../datasources.md#properties-setting)的`URL`中是否存在`allowLoadLocalInfile=true`。
### 数据库函数不存在{#err.db.functionNotExist}
**可能原因：**
1. 当前数据库版本不支持使用该函数，或用户没有该存储过程的执行权限。
**解决方法：**
1. 使用SuccBI提供的[函数](../../exp/func/README.md)时出现该异常：低版本数据库未支持窗口函数，与数据库管理员确认数据库版本是否符合[推荐版本](../../devops/install/database/README.md)中的要求，例如Mysql8+、Oracle9+。
2. 使用[SQL直通函数](../../exp/func/others/RAWSQL_STR.md)时出现该异常：与数据库管理员确认，使用的自定义函数是否已在数据库正确创建。
### 数据已存在{#err.db.duplicateKey}
**可能原因：**
1. 该问题可能由于插入数据的主键已经在目标表中存在，不允许再次插入。
**解决方法：**
1. 数据加工时出现该异常：解决主键数据重复问题，可使用加工中的[去重](/data-process/daduplicated)节点。
2. SuperPage新增数据时出现该异常：确认绑定主键的输入组件值不重复；例如新增ID，可将对应输入组件默认值设置为[UUID()](../../exp/func/string/UUID.md)。
### 缺少执行权限{#err.db.routineDenied}
**可能原因：**
1、没有该存储过程或自定义函数的执行权限。
**解决方法：**
1. 若调用存储过程、自定义函数时出现该异常，请确认当前数据源用户是否拥有该存储过程或自定义函数的执行权限。
2. 若调用数据库常见函数时出现该异常，检查函数调用是否存在拼写错误、数据源的数据库版本是否支持此函数。
### 无权限访问数据库或表{#err.db.commandDenied}
与数据库管理员确认，当前数据源用户的权限设置是否符合需求。
### 数据长度超出字段的最大长度{#err.db.columnValueTooLong}
**可能原因：**
1. 插入的数据某个字段过长，超过了表字段的最大限制长度。
**解决方法：**
1. 确认超长的数据是否正确。
2. 数据正确的情况下，增大异常字段的长度以满足插入数据的要求。
### 数据类型与字段的类型不一致{#err.db.columnTypeDisaccord}
1. 确认插入的数据类型是否正确。
2. 数据正确的情况下，修改异常字段类型与数据一致。
### 表名长度超过数据库允许最大长度{#err.db.tableNameOutOfBounds}
**可能原因**
1. 跨库复制数据表时，不同数据库表名长度限制不一样，目标数据库的表名长度限制小于来源库
2. 重命名物理表时，输入的表名超过数据库表名长度限制
**解决方法：**
1. 复制数据表时，修改目标物理表表名，缩小表名的长度
2. 重命名物理表时，缩小输入的表名的长度
### 对象不存在{#err.db.objectNotFound}
1. 数据库表被重命名或删除，恢复或重新创建数据库表。
2. 数据库失效，与数据库管理员确认后，修改[数据源属性](../datasources.md#properties-setting)指向有效数据库。
### 非空字段或主键字段不允许提交空值{#err.db.notAllowNull}
1. 补充该字段的值，使该值不为null。
2. 或是根据业务需求，修改表结构，将字段设置成可以为空。
### 数据类型转换错误{#err.db.invalidNumber}
**可能原因：**
1. 可能是因为关联字段的数据类型不一致，如整型字段与非整型字段进行比较或关联。
**解决方法：**
1. 确认关联的字段类型是否一致。
2. 将字段转成相同类型再进行比较，如使用[TOSTR(1.2345,"0.000")="1.235"](../../exp/func/transform/TOSTR.md),把其他类型转成str类型再进行比较。
3. 或调整表格字段类型，做到类型一致。
### 无法将不同类型的数据进行比较转换{#err.db.differentTypeConvent}
**可能原因：**
1. 该问题出现在vertica数据库中，原因可能是将两个不同类型的数据进行比较或是关联导致。
**解决方法：**
1. 请确认进行比较或关联的字段的类型是否一致，如果不一致可以使用[TOSTR(1.2345,"0.000")="1.235"](../../exp/func/transform/TOSTR.md)等函数转成一致。
2. 或调整表格字段类型，做到类型一致。
### 无法join多个其他表{#err.db.notAllowedJoin}
**可能原因：**
1. 可能是由于项目设置中Oracle使用Join语句选项被取消。若想继续使用join多个其他表，建议勾选。
**解决方法：**
1. 打开 [项目设置>数据](../../project-manage/data-mgr-setting.md)。
2. 勾选 Oracle是否使用join语法，点击保存。
### SQL语法错误{#err.db.sqlSyntax}
**可能原因：**
1. 使用了当前数据库不支持的语法。
2. 类型转换函数，格式不对。
3. 加工的sql组件、sql数据源、raw函数、直接sql查询等都可能导致sql语法错误。
**解决办法：**
1. 检查语法，使用符合当前数据库的语法。
### 行长超过最大限制{#err.db.rowSizeOutOfBounds}
**可能原因：**
1. MySQL数据库限制了行的最大长度（不包括BLOB和TEXT），在MySQL 8.x中，最大不能超过65535字节
**解决办法：**
1. 检查数据模型中字符字段的长度，缩短长度为合理值
2. 对于字符长度很大的字段，将其类型修改为CLOB
### GROUP\_CONCAT超过最大限制{#err.db.groupConcatRowOutOfBounds}
**可能原因：**
1. MySQL数据库通过参数`group_concat_max_len`限制了`GROUP_CONCAT`函数返回的最大长度，默认为`1024`。
2. 对于Oracle数据库，SuccBI中的`GROUP_CONCAT`函数翻译为Oracle中的`listagg`，`listagg`使用时结果长度超过`4000`会报错
**解决办法**
1. 在MySQL配置文件(linux/mac下是my.cnf，windows下是my.ini)的`[mysqld]`下修改参数设置为`group_concat_max_len=102400`，`102400`具体的值可以根据实际情况调整。
2. 对于Oracle数据库，可以在SuccBI的`GROUP_CONCAT`函数中给`maxlength`参数指定一个大于`4000`的值来解决，具体参见[GROUP\_CONCAT函数的使用](../../exp/func/analysis/GROUP_CONCAT.md)。
---
url: "https://docs.succapp.com/v5/guide/data-process/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process"
title: "数据加工介绍"
---
---
order: 4
navTitle: 数据加工
indexTitle: 概述
---
# 数据加工介绍
数据加工（也叫ETL，英文Extract-Transform-Load的缩写）是将业务系统中已存在的数据抽取（extract）、转换（transform）、加载（load）至数据仓库的过程。
SuccBI提供了图形化的自助式数据加工，通过简单的、拖拽式的可视化操作，业务用户也能轻松的完成数据的处理加工。
## 所见即所得加工数据{#see-is-get}
SuccBI提供了图形化的数据加工设计器，降低项目实施中的数据加工技术门槛，同时让业务用户可以自助加工数据，摆脱对IT部门的依赖。
1. **简单易用**
- 无需DBA、SQL技能，可视化拖拉拽操作
- 拖拉拽操作，每次操作都能看到结果
- 支持Undo、Redo
2. **普通的实施工程师也能建模**
- 项目实施过程无需大量的数据库工程师
- 实施工程师更多关注业务本身
3. **业务用户自助加工数据**
- 摆脱对IT部门的依赖
- 激活业务用户使用数据的热情
## 全方位洞察加工数据{#comprehensive-insight}
SuccBI的数据加工提供了多种协同视图，让你在任何加工步骤都能及时观察和掌控数据处理流程、输出结果数据、输出字段情况、加工SQL逻辑。
1. **加工流程视图**
- 图形化展示，加工过程一目了然
- 任意切换节点，轻松来回调试
2. **数据列表视图**
- 查看节点输出的字段和数据，可快速搜索定位字段
- 自动将编码转为文本，用业务话的语言展示数据
3. **字段列表视图**
- 可查看、编辑节点字段的属性，包括字段的类型、长度、关联表、默认值等
- 快速查看维度和度量的数目
4. **SQL逻辑视图**
- 预览运行在数据库上的加工SQL逻辑，便于理解和定位数据问题
## 轻松加工异构数据{#df-heterogeneous-data}
SuccBI支持超过25种类型的数据源连接，包括常用的关系型数据库，国产数据库，大数据，及Excel、csv、xml等数据文件，打通数据孤岛，将分散在不同类型数据库和文件的数据快速连接、探查、加工、建模。
1. **对用户透明**
- 不必关心数据来自哪个库
- 也不必关系数据是否在文件上
- 位于不同库、不同文件的数据可自由关联加工
2. **智能数据关联算法**
- 自动切换InDB与InMem
- 高效率的、并发的流式数据迁移算法
- 条件下沉，只获取需要用到的数据
## 丰富的数据加工组件{#rich-df-components}
数据加工提供经过精心设计的、丰富的加工组件，可以满足绝大部分加工需求，同时支持第三方扩展。
1. **丰富的内置加工组件**
- 关联（Join）、联合（union）、更新（update）、汇总、去重、行转列、列转行等
- 大量常用的列加工功能：拆分字段、大小写转换、删除标点、字母、特殊字符、提取数字、文本转ID等
- SQL和脚本组件可以实现任意位置需求
2. **第三方扩展新的加工组件**
- 第三方开发者可以使用扩展开发功能实现新的加工组件
- 普通用户使用时扩展组件和产品内置组件没有任何区别
## 实时预览加工结果{#real-time-preview}
数据加工支持在任意节点或步骤预览结果数据，无论你是创建计算字段、添加加工节点、修改字段类型、关联、汇总等，所做任何操作都可以在[数据列表](../data-gov/model/README.md#model-data)中立即查看到操作后的结果。
1. **便捷调试**
- 所有组件节点都能直接查看加工步骤的结果数据，无需使用SQL调试中间结果
- 随时修改，随时预览数据
2. **极速预览**
- 支持多种采样方式，百万、千万级别的数据也能极速预览
## 字段级血统追溯，掌握企业数据脉络{#field-lineage-analsis}
SuccBI的数据加工支持字段级别的血统追溯，你能够迅速洞察加工流程中数据的来龙去脉，掌控数据的影响范围，帮助你发现、管理和解决数据问题。
1. **追查数据的最源头**
- 了解数据从何而来
- 了解数据的最新状态
2. **掌握数据的影响范围**
- 数据发生修改和变化将会影响那些其他数据和分析结果
3. **简单易用**
- 无需IT部门协助
- 无需管理员在后台执行SQL
## 集成六大性能优化策略{#integrate-optimization-strategy}
结合10年以上的数据仓库建设实施经验，提炼一线项目的优化策略，SuccBI的数据加工中集成了六大性能优化策略，高效提升加工与分析查询性能。
1. **简单易用**
- 通过可视化的UI配置即可完成，无需写数据库SQL
- 屏蔽数据库层的差异，减少对不同类型数据库DBA的需求
2. **多维度、智能**
- 除了传统的数据库层优化，还可以进行模型层、数据架构层的优化
- 聚集、子集等支持自动导航，无需应用做任何修改
## 无人值守智能调度{#intelligent-schedule}
SuccBI的数据加工从加工源头记录了字段级别的数据血统，理解数据脉络，智能调度数据。
1. **减轻IT部门和实施人员负担**
- 成千上万模型的调度非常复杂
- “理解”数据血统，智能安排调度
2. **缩短调度时间窗口**
- 智能并发调度
- “关键且阻塞”的数据优先调度
3. **可视化监控**
- 可视化效果查看调度过程
- 发现错误可自动通知运维人员
## 一站式建设企业级数据仓库{#one-stop-edw}
SuccBI的数据加工是基于元数据的架构之上进行管理，融合了数据加工、模型管理等能力，简化数据仓库管理，支持分级数据仓库管理，使业务用户自助管理数据仓库成为可能。
1. **简化数据仓库管理**
- 加工数据的过程中已经完成了数据建模、元数据管理、调度策略等
- 做到自助数据仓库管理
- 支持分级数据仓库管理
2. **支持个人、部门、中央3级数据仓库管理**
- 个人模型只是个人使用
- 部门模型部门内部使用
- 中央数据仓库共集团共用
- 每级数据仓库可以各自分散管理，不必都依赖IT部门
---
url: "https://docs.succapp.com/v5/guide/data-process/create-dataflow.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/creat-dataflow"
title: "新建数据加工"
---
---
order: 2
---
# 新建数据加工
新建一个数据加工的步骤如下：
1. 进入项目的**数据**模块
2. 点击**新建**，选择**数据加工**菜单，此时即出现了一个新的数据加工标签页
3. 接下来可以添加模型及加工节点对数据加工进行编辑，可参考：[绘制加工流程图](./build-data-flow/README.md)
4. 最后点击**保存**按钮保存新建的数据加工，并点击**提取数据**执行数据提取
---
url: "https://docs.succapp.com/v5/guide/data-process/designer.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/designer"
title: "数据加工设计器"
---
---
order: 3
---
# 数据加工设计器
数据加工设计器是用来编辑数据加工的可视化工具，提供图形化的界面，以及丰富多样的加工组件，可以方便直观地定义整个加工过程，数据加工设计器界面如下图所示：
可以将其划分为如下几个区域：
1. 工具栏：工具栏提供了数据加工所需的加工组件，以及对数据加工进行保存及提取数据、查看数据提取日志等操作。
2. 加工流程图：此区域用于绘制加工流程图，对数据加工进行编辑，添加加工节点及模型输出等。可参考：[绘制加工流程图](./build-data-flow/README.md)
3. 数据面板：用于展示表中的数据，每一个加工步骤下，数据都将进行一次刷新。可点击数据面板上方工具栏中的按钮，切换数据面板中的显示内容为：数据列表、字段列表，以及预览SQL。
4. 属性面板：属性面板中会显示各加工节点下对应的加工步骤及相关属性设置。
---
url: "https://docs.succapp.com/v5/guide/data-process/add-data.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/add-data"
title: "引入待加工数据"
---
---
order: 4
---
# 引入待加工数据
开始一个数据加工时，我们需要将已有的待加工的数据连接到数据加工中作为加工的素材，SuccBI支持多种将数据连接入数据加工的方法：
\[\[toc]]
## 连接数据仓库中已有的模型数据进行加工{#connect-model}
可以是经过加工后的模型表或者ODS模型表，从左侧资源面板**模型**中选择需要进行加工的模型，拖至加工流程图区域
## 直接使用业务系统的物理表或视图进行加工{#use-table}
1. 直接连接业务系统的数据库，在资源面板**数据源**中选择对应数据源下需要进行加工的数据库表，拖至加工流程图区域。若未添加对应业务系统的数据库，可参考文档[数据连接-数据库连接](../data-connect/README.md#upload-data-file)
2. 使用SQL查询数据库表，参考文档[SQL](./transform/sql.md)
## 使用来自文件中的数据进行加工{#use-data-file}
从**文件数据源**当中拖入需要进行加工的数据文件，上传数据文件可参考文档[数据连接-上传数据文件](../data-connect/README.md#upload-data-file)
## 使用SQL调用存储过程进行加工{#use-stored-procedure}
添加**SQL**组件，在SQL编辑器中调用存储过程中的数据进行加工，参考文档[SQL](./transform/sql.md)
## 引入节点属性设置{#setting}
引入的来源表节点可以在[数据加工设计器](./designer.md)的左下角进行相关属性设置。
### 预览数据集{#debugdatasets}
**预览数据集**查询时只查询抽样数据，常用来提升查询性能，具体可参考[预览数据集](./optimization/README.md#debugdatasets)文档。
### 提取前检查{#check-before-extraction}
**提取前检查**是指数据加工在执行数据提取到目标库前对来源表进行的检查，加工中只有所有来源表都满足提取前检查时，才会真正执行数据的提取。[全量提取](./data-output/README.md#extractmethod)时，系统会先清空目标表再提取数据，这样可能会导致数据仓库数据丢失，为了保证数据的安全性，可以在提取前先进行检查，如果发现错误就不提取，主要有以下两种情况：
- 避免上游数据错误时（比如来源表中数据被清空）执行提取，导致数据仓库数据丢失
- 避免上游数据结构变化时导致提取错误
**提取前检查**支持三个属性条件来检查来源表数据：
- **表存在，且所需字段都存在**：默认为勾选状态，检查加工输入表是否还存在，同时检查加工中引用该输入节点的字段在来源表中是否存在
- **表中必须存在至少N行数据**：可以检查来源表数据行数，当行数大于等于N时满足条件，N可以指定，默认为空
- **表中数据必须比上次抽取多N行数据**：可以检查对比上次从该来源表抽取的数据和现在该来源表的数据行数，N可以指定，默认为空
当不满足任一勾选的检查条件时，无论是手动点击，还是计划调度，都不会进行数据的提取，同时会显示相应的错误信息，主要内容如下：
- **手动点击提取数据按钮**：弹出对话框显示“提取前检查失败”的错误日志信息，并取消当前执行的加工
- **通过计划执行提取数据**：日志中显示任务为取消状态，计划为失败状态
---
url: "https://docs.succapp.com/v5/guide/data-process/build-data-flow/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/build-data-flow"
title: "绘制加工流程图"
---
---
order: 5
navTitle: 绘制加工流程图
indexTitle: 绘制加工流程图
---
# 绘制加工流程图
加工流程图描述了一个数据加工的内部过程，图中的每个节点可能代表一个表、加工转换或关联等，数据加工的过程其实就是不断的“绘制”这个加工流程图的过程，一个典型的数据加工流程图示例如下：
绘制加工流程图主要分为以下几个步骤：
\[\[toc]]
## 拖入数据源到加工流程图区域{#drag-data}
新建数据加工后，通过拖拽的方式从左侧资源树下将模型、数据库表或文件拖入至右侧数据加工区域，即可进行数据加工操作，参考文档[新建数据加工](../create-dataflow.md)
在加工过程中，我们还能拖入其他的模型、数据库表或文件至加工界面，实现对目标表的替换，或者将被拖入表和目标表进行关联或联合。
### 替换加工节点{#replace}
将被拖入表拖拽至目标表**上方**即可用被拖入表替换目标表。
### 添加表关联（JOIN）节点{#join}
将被拖入表拖拽至目标表**右方**可实现被拖入表和目标表的关联，该操作也可通过添加**关联**节点实现，参考文档[关联](../transform/join.md)
### 添加联合（UNION）节点{#union}
将被拖入表拖拽至目标表**下方**可实现被拖入表和目标表的关联，该操作也可通过添加**联合**节点实现，参考文档[联合](../transform/union.md)
## 使用下拉菜单添加加工组件{#menu}
添加表后，我们可以点击右侧的+号，在弹出的节点菜单中通过汇总、关联等各加工组件对其进行加工。各节点的功能和操作方式可参考文档[清洗和加工数据](../transform/README.md)
### 添加分支节点{#branch}
如果不同的加工流程里面有部分的加工逻辑和操作是相同的，为避免重复操作，我们可以通过添加分支来复用相同部分。参考文档[添加加工流程分支](./new-branch.md)
## 从工具栏拖入节点{#toolbar-node}
除了可以在节点菜单中选择节点之外，我们还可以在**工具栏**中拖入我们所需的节点对数据进行加工处理。
## 从其它加工流程图复制节点{#copy}
当我们的加工流程会复用另外一个加工流程的某一部分时，我们可以通过`Ctrl+C`，`Ctrl+V`对所需的加工部分进行复制，从而提高工作效率。
## 模型输出与数据提取{#data-output}
加工流程图最后必须有一个**模型输出**的节点，通过点击+号按钮，在下拉菜单中选择**模型输出**即可添加，**模型输出**的节点代表整个加工流程输出的结果，在**模型输出**的节点上可以进行更多模型相关的属性设置，可参考文档[输出加工结果](../data-output/README.md)
## 查看数据提取日志{#log}
在[模型属性](../../data-gov/model/model-settings.md#extract-data)下勾选**提取数据**后，保存加工流程，点击工具栏的**提取数据**按钮，数据提取完成后，可以点击每个加工节点查看当前节点的数据查询日志，以及在工具栏上点击**查看日志**按钮，查看最近一次的提取日志。
---
url: "https://docs.succapp.com/v5/guide/data-process/build-data-flow/new-branch.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/new-branch"
title: "添加加工流程分支"
---
---
order: 1
---
# 添加加工流程分支
添加分支用于在已有数据加工流程中添加另一个加工分支，复用相同的加工部分。添加分支后可以在新分支上继续对数据进行加工处理，完成后可以使用[表输出](../transform/table-output.md)生成物理表。
如对销售单位汇总表添加分支，输出物理表：
示例地址：[添加分支](https://demo.succbi.com/v5/DEMO/data?:open=VbAZDOeuqyKE1OaeCu8RFG)
## 操作步骤
**添加分支**操作的方式有2种：
方式一：\
点击加工节点右侧的加号，选择**添加分支**，系统会默认添加**列加工**节点作为分支的初始节点。
方式二：\
右键点击加工节点，选择**添加分支**，我们可以自定义分支的初始节点。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/transform"
title: "清洗和加工数据"
---
---
order: 6
navTitle: 清洗和加工数据
indexTitle: 清洗和加工数据
---
# 清洗和加工数据
SuccBI数据加工提供了多种方法和组件，帮助用户快速的对数据进行清洗和加工处理：
!!!children (guide/data-process/transform/) !!!
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/calc-field.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/calc-field"
title: "添加计算字段"
---
---
order: 1
---
# 添加计算字段
当表中已有的字段无法满足用户所需，需要根据已有的字段构造出的新的字段列时，可以**添加计算字段**，即**新增字段**。若只需在已有字段上进行修改，可直接**转成计算字段**，参考文档[转成计算字段](./convert-to-calc-field.md)。
如根据字段【租金（美元）】新增计算字段【租金（人民币）】
示例地址：[新增字段](https://demo.succbi.com/v5/DEMO/data?:open=FR5Mrzslx1EkuxsfUhAZrD)
**操作步骤**
添加计算字段需要以下2个步骤：
- [添加计算字段](./calc-field.md)
- [创建计算字段](#create-field)
- [编辑字段](#edit-field)
## 创建计算字段{#create-field}
创建计算字段有2种方式：
1. 选择**数据面板**上方的**工具栏**>**新增字段**
2. 在数据面板中选择字段列名，如【租金（美元）】，在下拉菜单中选择**创建计算字段**
## 编辑字段{#edit-field}
在弹出创建计算字段会话框中编辑字段名称及表达式
1. 名称：**租金（人民币）**
2. 表达式：`[租金（美元）]*7`
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/calc-group-field.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/calc-group-field"
title: "添加分组字段"
---
---
order: 2
---
# 添加分组字段
分组字段，是对数据表中字符型或者日期型的数据重新分类，根据两级层次结构生成一个新的分组。
::: tip
对于数值型的数据，做分类处理时可以创建分段字段，参考[添加分段字段](./calc-section-field.md)
:::
## 创建分组字段{#create-field}
在数据加工的任意组件节点处均可以创建分组字段。选中某个组件节点，在**数据列表**或**字段列表**视图下，选中某个字符型或日期型字段，鼠标右键即可创建分组字段。如需要根据需求将电影类型重新分组，操作步骤如下：
1. **创建分组：** 在**数据列表**或**字段列表**中右键点击【中文名称】，选择【创建分组】，并在**字段名称**处命名为【类型分组】，字段名称不能和数据表中的字段名重名
2. **添加分组：** 选中`恐怖片`维项，点击**分组**或者右键点击选择**分组**，添加一个分组项并重名为`惊悚刺激`
3. **添加组成员：** 选中`惊悚片`选择**添加到** `惊悚刺激`分组项下，或者点击**添加到**添加至`惊悚刺激`分组项下
4. **合并其他数据：** 按照需求设置好新的分组后，还有部分维项是不属于任何分组的，如果需要归类到其他，可以勾选**合并其他数据**
5. **生成分组字段：** 点击确定，数据加工中生成了【类型分组】字段
::: tip
当想要取消分组或者移除分组项中的数据，可以在分组编辑框中点击以下属性按钮：
- **取消分组：** 取消分组项，选中分组项可以点击**取消分组**按钮或者右键点击分组项选择**取消分组**
- **移除：** 将已经分组的数据从分组项中移除，右键点击分组中的数据选中**移除**，可以将数据从分组项中移除
如果已经勾选了**合并其他数据**，这时取消或者移除其他分组，都会自动归类到其他下面
:::
示例地址：[数据分组](https://demo.succbi.com/v5/DEMO/data?:open=dakdYxAQDKZVwKQvRGQug&)
## 编辑分组字段{#edit-field}
对已经保存的分组字段进行编辑操作，有多种进入编辑框的方式：
- 在**数据列表**或者**字段列表**中右键点击分组生成的字段，点击**编辑分组**进入到编辑框
- 在列加工步骤中选中分组步骤，右键选择**编辑**进入分组字段的编辑框
## 删除分组字段{#delete-field}
加工步骤中，不需要分组字段时可以删除，有多种删除方式：
- 选中分组字段步骤鼠标右键，选择**删除**将字段移除
- 列加工步骤中右键**删除**
- 选中步骤右侧会显示×按钮，将分组字段从数据加工中移除
删除后，在界面没有刷新前，可以通过撤销找回被删除的分组字段。移除分组字段后，不会对分组字段之前的加工节点造成影响，但是会影响后面引用此分组字段的节点，会生成**无法识别的变量**。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/calc-section-field.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/calc-section-field"
title: "添加分段字段"
---
---
order: 3
---
# 添加分段字段
分段字段，是将数据表中数值型的数据进行分段处理，生成新的数据分组字段。
::: tip
对于字符型或日期型的数据，做分类处理时可以创建分组字段，参考[添加分组字段](./calc-group-field.md)
:::
## 创建分段字段{#create-field}
在数据加工的任意组件节点处均可以创建分段字段。选择某个组件节点，在**数据列表**或**字段列表**视图下，选择某个数值型字段，鼠标右键即可创建分段字段。如根据需求将电影预算进行分段，操作步骤如下：
1. **创建分段：** 在**数据列表**或者**字段列表**中右键点击【预算】，选择**创建分段**，并在**字段名称**处命名为【预算分区】，字段名称不能和数据表中的字段名重名
2. **添加分段：** 在**区间值**处填写`60000000`，然后在**分段名称**处输入`低于6千万`,再点击右上方的蓝色 **+号**，添加新的区间，根据需求填入相应数据，并选择是**包含最大值**，可以点击右边的 **×键**取消此分区，系统默认最小分段区间为两个，且不能删除
3. **生成分段字段：** 点击确定，数据加工生成了【预算分区】字段
示例地址：[数据分段](https://demo.succbi.com/v5/DEMO/data?:open=0bWDb8qHSH6SnpmYutEXoA)
## 编辑分段字段{#edit-field}
对已经保存的分段字段进行编辑操作，有多种进入编辑框的方式：
- 在**数据列表**或者**字段列表**中右键点击分段字段，进入到编辑框
- 在列加工步骤中选中分段步骤，右键选择**编辑**进入到分段字段的编辑框
## 删除分段字段{#delete-field}
加工步骤中，不需要分段字段时可以删除，有多种删除方式：
- 选择分段字段鼠标右键，选择**删除**将字段移除
- 列加工步骤中右键选择**删除**
- 选中步骤右侧会显示×按钮，将分组字段从数据加工中移除
删除后，在界面没有保存刷新前，可以通过撤销找回被删除的分段字段。移除分段字段后，不会对分段字段之前的加工节点造成影响，但是会影响后面引用此分段字段的节点，会生成**无法识别的变量** 。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/convert-to-calc-field.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/convert-to-calc-field"
title: "转成计算字段"
---
---
order: 4
---
# 转成计算字段
当只需要修改表中的字段表达式内容，而不需要保留原有字段时，可以使用**转成计算字段**。
如将电影时长从分钟改为小时进行计量：
示例地址：[转成计算字段](https://demo.succbi.com/v5/DEMO/data?:open=FR5Mrzslx1EkuxsfUhAZrD)
**操作步骤**
转成计算字段需要进行以下2个操作：
1. **数据面板**>**数据列表**下选择需要操作的字段列（如【影片长度】），点击列头的下拉按钮或右键，选择**转成计算字段**
2. 在弹出的编辑字段会话框中编辑字段表达式，如`[影片长度]/60`
## 添加计算字段与转成计算字段{#create-convert}
**添加计算字段**与**转成计算字段**都是基于表中已有的字段进行操作：
- 添加计算字段：即新增字段，字段数量增加，与原有字段是2个独立的字段。参考文档[添加计算字段](./calc-field.md)
- 转成计算字段：在原有的字段上进行修改，直接修改的原字段的内容，字段数量不变。对原字段修改时，**转成计算字段**可以省去**新增字段**>**重命名字段**>**删除字段**
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/column-processing/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/column-processing"
title: "列加工"
---
---
order: 5
navTitle: 列加工
indexTitle: 列加工
---
# 列加工
列加工提供了简单的数据加工方式，对表中的指定的列进行数据的清洗（如提取数字、转大写）、转换、拆分、替换或文字转ID等操作，如图是一个简单的列加工节点示例：
## 使用列加工{#columns}
当数据需要进行清洗加工时，可以点击节点后面的+号，选择菜单栏中的**列加工**，此时即新增了一个列加工节点，在列加工节点下，可对数据列进行不同的列加工操作
列加工操作可分为3类：
1. [替换](#replace)
2. [拆分](#split)
3. [清洗](#clean)
### 替换{#replace}
将字段里面的部分内容替换为指定内容。如将指标内的字符串`惠来县`，替换为`**县`
示例地址：[替换](https://demo.succbi.com/v5/DEMO/data?:open=o1EDhmA6Q5ES5IkSUT4fRC&:tblview=modelData)
**操作步骤**
1. 右键点击需要进行加工的列，选择**替换**，跳出替换弹窗
2. 在**字符串**栏里输入被替换字符串`惠来县`，在**替换为**栏里输入替换字符串`**县`，点击确认按钮，完成替换操作
3. 在左侧的列加工步骤里可以看到新增了一条**替换**操作记录
::: tip
如需使用正则表达式进行匹配替换，勾选**使用正则表达式**复选框，在**字符串**输栏中输入正则表达式，系统将按照设置的正则语法规则执行匹配替换。
:::
### 拆分{#split}
将数据表中的某一列按照指定分隔符拆分成N列。如演员列里存储的数据为`演员1,演员2`，我们可以按照分隔符`,`进行拆分,将字段里存储的多个演员id拆分为多个独立的列
将字段【演员】列按照分隔符`,`进行拆分
**操作步骤**
1. 右键点击需要进行加工的字段列，如【演员】，选择拆分，弹出拆分会话框：
1. 在**分隔符**栏里输入进行拆分的分割符号`,`，
2. **拆分策略**选择**全部**
3. 默认选择**拆分为多列**
2. 点击**确定**按钮，字段【演员】即被拆分为多个字段，在左侧的属性面板中同时新增了一条列加工步骤**拆分**
### 清洗{#clean}
清洗掉某列数据中不需要的字符，如清洗空数据、截取字符、提取数字等
将年份字段如`2017年`截取前4位，形成新的字段年份`2017`
示例地址：[清洗](https://demo.succbi.com/v5/DEMO/data?:open=FfxpJPcRpiw1HEI7kSEcA)
**操作步骤**
1. 右键点击需要进行加工的字段列，选择拆清洗，选择具体的清洗操作，如【截取字符】
2. 完成具体的清洗操作之后，在左侧的属性面板中同时新增了一条列加工步骤，名称与具体清洗操作相对应
#### 数据清洗操作{#data-cleaning}
清洗的操作有13个：
- 转为小写：将该列的大写字母字符全部转化为小写字母
- 转为大写：将该列的小写字母字符全部转化为大写字母
- 删除空格：删除该列数据中指定位置的空格
- 删除数字：删除该列数据中包含的所有数字字符
- 删除字母：删除该列数据中包含的所有字母字符
- 删除标点：删除该列数据中包含的所有标点符号
- 删除特殊字符：删除指定的特殊字符
- 排除空数据：排除该列数据中存在的所有空数据
- 提取数字：将该列数据中的数字字符提取出来，替换该列原来的数据
- 提取日期：将该列数据中指定日期格式的字符提取出来，替换该列原来的数据
- 截取字符：截取该列数据指定位置的字符串，替换该列原来的数据，截取弹框里可以设置截取位置
- 文本转ID：将文本转化成文本对应的ID，详情可参考文档[文本转ID](./text-to-id.md)
- 加密解密：将该列数据按指定算法加密/解密，详情可参考文档[数据安全-加密](../../../data-gov/model/data-security.md#encryption)
## 列加工步骤列表{#column-list}
列加工的所有操作记录都被记录在数据表左侧的列加工步骤列表里。列加工步骤列表里还提供了列加工步骤编辑和删除操作。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/column-processing/text-to-id.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/text-to-id"
title: "文本转ID"
---
# 文本转ID
将列表中的文本转为文本对应的ID，进行转换的文本和ID必须有维表对其进行关联。
如将食品名称转化为对应的食品ID
示例地址：[文本转ID](https://demo.succbi.com/v5/DEMO/data?:open=xXDJ6XbZuPETjDZbXULbb)
**步骤**
1. 右键点击需要进行文本转ID操作的列名【食品名称】，右键清洗->文本转ID，弹出文本转ID会话框
2. 在**映射表路径**栏里添加关联了文本字段和ID字段的维表路径`/DEMO/data/tables/行业/其它数据/食品数据/sp_dim_spfl_map.tbl`，在**文本字段**栏里选择需要进行转换的文本名称`MC`，在**ID字段**栏里选择文本对应的ID字段`ID`
3. 勾选**转为新的字段**，点击确定按钮
4. 左侧列加工栏里新增一条文本转ID的列加工记录
::: tip
在维表里为文本字段配置同义词后，文本转ID时系统会自动识别并处理数据。例如，在维表中`水产制品`的同义词列对应的数据为`水产品,水产品A,水产品B`，系统会自动将`水产品`、`水产品A`或`水产品B`识别为`水产制品`的同义词，并映射到相同的ID`122`上。
:::
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/join.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/join"
title: "加工组件：关联"
---
---
order: 6
navTitle: 关联
---
# 加工组件：关联
关联用于获取来自其他表的数据，类似于SQL里的join。如【门店月度进销计划表】与【门店月销汇总表】表关联，从而获得产品每月的零售总金额、交易总金额等数据
示例地址：[关联](https://demo.succbi.com/v5/DEMO/data?:open=yUECyvH2HIKx5h3rn3jpIB)
## 操作步骤{#steps}
添加**关联**组件的方式有2种：
方式一：\
将需要关联的表拖拽至原查询下方，如将表**门店月销汇总表**拖至节点**汇总**下方，这种方式下，系统默认将原查询作为主表：
方式二：\
点击原查询右侧的加号，选择**关联**，将表**门店月销汇总表**拖拽至**关联**节点上，这种方式下，系统默认将原查询作为主表：
## 关联方式{#association}
根据功能不同，关联方式分为如下3种：
1. 左连接：数据表关联后的结果集保留的是主表的所有数据行，以及副表中与主表匹配的数据行，两张表的列都保留
2. 内连接：数据表关联后的结果集保留的是两张表的交集，两张表的列都保留
3. 全连接：数据表关联后的结果集保留的是两张表的并集，两张表的列都保留
:::tip
MySQL数据库不支持全连接，系统默认当左连接处理
:::
## 主查询{#main-query}
主查询表用于控制多表之间的查询顺序，一般在进行左连接时使用。在下拉列表中选择对应的表名设置为主查询表。
也可以通过**调整其他查询顺序**来调整表的查询顺序，拖动列表中的表名以调整顺序。其中，主查询表的顺序默认为第一个，当调整其他表的顺序为第一个时，此时主查询表也会对应修改。
## 连接条件{#connection-conditions}
数据表进行关联时的匹配条件，系统默认的连接条件规则如下：
1. 如果设置了全局关联关系，系统自动采用全局的关联关系，见文档：[关联关系](../../data-gov/model/model-relations.md)
2. 如果没有设置全局关联关系，系统默认根据主表和副表相同的字段名称设置连接条件，默认最多显示5条连接条件
3. 当默认连接条件不满足时，可以点击添加连接条件，如添加关联条件为：`进销存月`.`销售单位`=`月销汇总表`.`销售单位`
## 跨源关联{#cross-source}
不同数据源的表支持关联操作，但在执行跨数据源关联操作时，需注意跨数据源关联的本质是将不同数据源的数据暂时迁移至同一数据源中进行关联。此迁移过程将在[项目默认数据库](../../project-manage/data-mgr-setting.md#default)中生成临时表。
例如，若[项目默认数据库](../../project-manage/data-mgr-setting.md#default)设置为`succbiyw`，在该项目中使用`Kingbasepg`数据源表与`SQLServer`数据源表关联时，两张跨源表会在`succbiyw`中生成两张临时表，实际关联操作是基于这两张临时表。
在预览阶段，临时表仅支持存储不超过1万条数据，若希望获取全量数据，需点击**提取数据**。因此，跨数据源关联的数据加工建议设置[提取](../../data-gov/model/model-settings.md#extract)，最终以提取后[模型输出节点](./model-output.md)的数据为准。预览阶段的中间节点数据仅供参考。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/data-filter.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/data-filter"
title: "数据加工-过滤数据"
---
---
order: 7
navTitle: 过滤
---
# 数据加工-过滤数据
**过滤**用于对加工节点的结果数据进行筛选。数据加工的每个节点上都可以进行**过滤**。
如筛选出【电影评级】等于G，【影片长度】大于等于1.5的数据：
示例地址：[过滤](https://demo.succbi.com/v5/DEMO/data?:open=FR5Mrzslx1EkuxsfUhAZrD)
**操作步骤**
1. 选择**数据面板**上方的**工具栏**>**过滤**
2. 添加过滤条件：
- [**字段过滤条件**](../../data-viz/dash/design/data/data-filter/README.md#field-filtering)：【电影评级】等于**G**
- [**表达式**](../../data-viz/dash/design/data/data-filter/README.md#expression-filtering)：`【影片长度】>=1.5`
## 自定义过滤条件{#custom-filter}11
- [过滤](./data-filter.md)
- [自定义过滤条件](#custom-filter)
- [添加过滤条件](#add-filter)
- [启用](#enable-filter)
### 添加过滤条件{#add-filter}
当有多个过滤条件时，有2种条件关系可供选择：
- 包含以下所有条件：多个条件间是and关系，过滤后的数据满足设置的所有条件
- 包含以下任意条件：多个条件间是or关系，过滤后的数据满足设置的任意一个条件
过滤条件支持2种类型：
- 字段过滤条件：选择字段和操作符设置过滤条件，操作符根据选择的字段自动生成，选择的过滤字段类型不一样，可选择的操作符也不一样
- 表达式：
用于字段间较复杂的过滤条件，通过输入[表达式](../../exp/README.md)，经常搭配[函数](../../exp/func/README.md)或[参数](../setting-params.md)使用
### 启用{#enable-filter}
表示设置的过滤条件是否需要生效，默认勾选
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/union.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/union"
title: "加工组件：联合"
---
---
order: 8
navTitle: 联合
---
# 加工组件：联合
联合用于合并两个或多个数据表中的数据，将各表中列名相同的数据合并到一起。若某列数据只存在于部分表中，那么联合结果中其他表对应的该列数据为空。
如将2016年指标、2017年指标及2018年指标的数据进行联合：
示例地址：[联合](https://demo.succbi.com/v5/DEMO/data?:open=g2r5yHmdSJDE4RMc2ShFnE)
## 操作步骤
添加**联合**节点的方式有2种：
方式一：\
将需要联合的表拖拽至原表**下方**，如将表**2017年指标**拖至表**2016年指标**下方：
方式二：\
点击原表右侧的加号，选择**联合**，将表**2017年指标**拖拽至**联合**节点上
## 联合方式
根据功能不同，联合方式分为4种，这4种联合方式的差异如下：
| 联合方式 | 数据处理方式 | 不同数据 | 相同数据 |
| :---------| :-------- |:-------- | :-------- |
| Union | 并集（去除重复） | 保留 | 只保留一条 |
| Union All | 并集 | 保留 | 保留所有 |
| Minus | 差集 | 保留主查询表中与其它表不同的数据，其余所有数据均删除 | 删除 |
| Intersect | 交集 | 删除 | 保留主查询表中与其它表相同的数据 |
:::tip
MySQL，Hive和SQL Server 2005之前的版本不支持Minus和Intersect
:::
## 主查询
主查询表用于控制多表之间的查询顺序，一般在进行Minus或Intersectl联合操作时使用。在下拉列表中选择对应的表名设置为主查询表。
也可以通过**调整其他查询顺序**来调整表的查询顺序，拖动列表中的表名以调整顺序。其中，主查询表的顺序默认为第一个，当调整其他表的顺序为第一个时，此时主查询表也会对应修改。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/update.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/update"
title: "加工组件：更新"
---
---
order: 9
navTitle: 更新
---
# 加工组件：更新
更新用于根据一定的条件，对原始数据表中已有字段的数据进行修改，相当于sql语句中的update。当最终输出表的一部分字段数据不是存在业务表中，需要通过与相应的数据表关联来获取的时候，可以使用**更新**。
如就业人员平均工资表缺少【2018年】数据，需要用另外一个存储了2018年平均工资的业务表去更新这个字段：
示例：[更新](https://demo.succbi.com/v5/DEMO/data?:open=fgtdGt3PTUBfG1y2rwTMUE)
**操作步骤**
1. 点击**按行业分城镇单位就业人员平均工资**右侧的+号，在弹出的节点菜单中选择**更新**
2. 拖拽中间表**按行业分城镇单位就业人员平均工资** **(2018年)** 到**更新**节点
3. 选中**更新**节点，设置[更新字段](#更新字段)，点击**添加**>**字段更新**，左边选择【2018年】，右边选择**按行业分城镇单位就业人员平均工资** **(2018年)** 的【2018年】字段
4. 设置[更新条件](#更新条件)，**添加**>**字段更新条件**，左边选择【行业】，右边选择**按行业分城镇单位就业人员平均工资** **(2018年)** 的【行业】字段
### 更新方式
根据数据是否来源于其他数据表，更新的方式分为以下2种：
1. **单表更新**：数据来源为常量或者当前数据表的其他字段
2. **关联更新**：数据来源为其他数据表的某个字段
### 更新字段
更新字段指的是数据表中需要更新的字段，可以选择多个字段，字段可以是维度或度量。根据数据来源的不同，可选**字段更新**和**数值更新**。
两者的使用场景和表达式列表规则如下：
| 更新字段 | 使用场景 | 表达式左侧列表 | 表达式右侧列表 |
| :---------| :-------- |:-------- | :-------- |
| 字段更新 | 数据来源为当前或其他数据表的的某个字段 | 主表的字段列表 | 可选主表或副表的字段 |
| 数值更新| 数据来源为常量 | 主表的字段列表 | 表达式编辑框 |
### 更新条件
更新条件是对需要更新的数据进行过滤，可以设置多个条件，条件可以是维度或度量。根据数据来源/**更新字段**的不同，更新条件分为3种，这3种的使用场景如下：
| 更新条件 | 使用场景 |
| :---------| :-------- |:-------- | :-------- |
| 字段更新条件 | 用于进行字段更新时，设置两表之间字段的关联条件 |
| 数值更新条件| 用于更新条件为一个常量数值或者字符时 |
| 表达式| 用于更新条件比较复杂，上面2种条件无法实现，如涉及到字段运算或是参数时|
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/agg.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/agg"
title: "加工组件：汇总"
---
---
order: 10
navTitle: 汇总
---
# 加工组件：汇总
汇总的作用是根据所选分组字段对数据进行分类汇总（分组），相当于sql语句中的group by。
如将销售明细数据按照销售单位、产品及销售月份分组对销售数量及销售金额等进行汇总：
示例：[汇总](https://demo.succbi.com/v5/DEMO/data?:open=TsNamubgd4INU5JPF7xYYG)
**操作步骤**
1. 添加**汇总**节点
2. 添加**分组字段**，分别添加【销售单位】、【产品】、【销售月份】3个分组字段
### 分组字段{#grouping-field}
可选一个或多个维度和度量，将查询结果按所选分组字段进行分组，字段值相同的为一组
### 汇总方式{#summary-method}
汇总节点会自动对数值字段求合计，并隐藏非数值字段
汇总方式可选**合计**、**计数**、**平均值**、**最大值**、**最小值**、**计数(不同)**、**第一条**、**最后一条**
### 添加汇总字段{#summary-field}
如销售明细表中的数据有销售日期，销售金额、成本价格及销售数量等字段，汇总时想要按照月份汇总销售单位的销售利润，可以新增字段【销售月份】、【利润】，参考文档《[添加计算字段](./calc-field.md)》
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/deduplicated.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/deduplicated"
title: "加工组件：去重"
---
---
order: 11
navTitle: 去重
---
# 加工组件：去重
去重是数据处理中的一个重要步骤，它的目的是消除数据集中的重复项，比如希望在存储了企业多年年报的表中去重查询获取企业最新的年报信息、产品销售表中去重查询每个店铺销售过的产品等。系统里去重加工支持[按字段去重](#distinct)和[分组排序去重](#group-sort)两种方式。
## 按字段去重{#distinct}
**按字段去重**是按照所选的输出字段去重，所有字段值相同时保留其中一行，相当于SQL语句中的distinct。
例如，产品销售明细表中包含了销售的产品信息，需要去重查询所有销售的产品及其分类信息，可以通过**按字段去重**的方式，选择产品大类、产品小类、产品名称字段进行去重查询。
示例：[按字段去重](https://demo.succbi.com/v5/DEMO/data?:open=RJUUO1fpEVFJSzmsQ9QvIB&:expandIds=KRSzynxUulEotgoUevK4sB&:tblview=modelData)
## 分组排序去重{#group-sort}
**分组排序去重**是字段按照指定的分组字段进行分组，每组内的数据行将按照**组内排序字段**进行排序后只保留第一行数据返回，其他行都丢弃，通常用于获取组内最新或最大的数据行。
例如企业年报表里存储了企业每年的年报信息，现在需要获取企业最新的年报信息，可以通过**分组排序去重**的方式，按企业ID进行分组，年报年份降序排序进行去重查询获取最新年报信息。
示例：[分组排序去重](https://demo.succbi.com/v5/DEMO/data?:open=RJUUO1fpEVFJSzmsQ9QvIB&:expandIds=KRSzynxUulEotgoUevK4sB&:tblview=modelData)
1. **分组字段**：确定用于区分数据行是否重复的字段或字段组合。
2. **组内排序字段**：确定具有相同键值的行集合分组内部进一步排序的字段或字段组合。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/table-output.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/table-output"
title: "加工组件：表输出"
---
---
order: 12
navTitle: 表输出
---
# 加工组件：表输出
当一个加工流程需要生成多张物理表时，可以使用表输出。
如将月销汇总表中对省份汇总后，对此表进行表输出：
示例：[表输出](https://demo.succbi.com/v5/DEMO/data?:open=VbAZDOeuqyKE1OaeCu8RFG)
**操作步骤**
方法一：
当选择的加工组件后面已有其他的组件，选中组件右键选择**添加分支**>**表输出**
方法二：
当选择的组件后面没有组件，点击+号，选择**表输出**
::: tip
1. 当添加**表输出**后，点击保存，输出的物理表会被生成或修改。
2. 保存模型时，若不添加**模型输出**组件，将无法进行保存。
:::
## 物理表属性设置
### 物理表名称
设置物理表的存储名称，规则如下：
1. 输入的表名不存在时，存储为新的物理表，且物理表名称不允许以数字开头。
2. 输入的表名已存在时，覆盖已有的物理表。
### 物理表路径
路径从左至右分别为数据源、数据模式、数据表名，
通过修改面包屑路径，可修改物理表的存储路径，当需要查询输出的物理表时，复制物理表名在右侧数据源区域中进行粘贴搜索即可。
### 允许修改表结构
勾选**允许修改表结构**，则输出的物理表结构可以被修改，如增加或删除字段、修改字段类型等。
1. 物理表不存在：按需求勾选**允许修改表结构**即可。
2. 物理表已存在：
1. 勾选：覆盖已有物理表
2. 不勾选：
- 相同结构：正常输出物理表数据
- 不同结构：比如增加了某列数据，系统会在新的数据行上出现红色感叹号提示，且提取数据时新增的数据无法提取。
## 表输出与模型输出区别
1. **表输出**后还可以继续加工，当需要多个物理表输出时，则使用[添加分支](../build-data-flow/new-branch.md)。
2. [模型输出](./model-output.md)是数据加工的完成节点，整个加工流程中有且仅有一个，若不提取数据，则不会存储到物理表中。
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/rowtocol.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/rowtocol"
title: "加工组件：行转列"
---
---
order: 13
navTitle: 行转列
---
# 加工组件：行转列
行转列，可以将行上的指标转换到列上。
如，将产品处理表中【产品版本】这一行数据的中8个版本的指标数据，转换为8个列进行存储：
转换前:
转换后：
示例地址：[示例](https://demo.succbi.com/v5/DEMO/data?:open=NC2YywOwRwGPfEX4TVunqg)
## 操作步骤
1. 在输入表左侧点击+号，选择添加**列转行**组件
2. **转换条件字段**：下拉选择【产品版本】
3. **转换指标字段**：下拉选择【当前\_值】
4. **其他保留字段**：下拉选择【产品指标代码】、【年月】、【组织机构】
5. 在转换列表，分别将【目标字段】根据【产品版本】进行**重命名**
## 转换条件字段
将行转换为列的字段。
## 转换指标字段
转换新增度量的数据来源字段。
## 其他保留字段
其他需要保留在数据列表中的字段。
## 转换列表
转行列表一共有三列，选择转换条件字段和转换指标字段后，自动生成。
1. 第一列表示要转换的字段的所有不重复数据，作为新的一列
2. 第二列是转换指标字段，也是新的一列的数据
3. 第三列是给生成的列命名，可以手动输入
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/coltorow.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/coltorow"
title: "加工组件：列转行"
---
---
order: 14
navTitle: 列转行
---
# 加工组件：列转行
列转行可以把一系列相关的字段（列）转化成目标表中的行。
如项目达标信息表中，每一年的项目总数、达标数、未达标数、达标比例均分为12个度量存储（1-12月的数据存在12个列中）总共48个度量（48列）。通过列转行，将每一年的项目总数12个度量转换到1个度量（1行数据存储1列数据），以此类推分别将达标数、未达标数、达标比例进行列转行操作。同时将月份作为一个新的维度字段，用于区分这4个度量的时间范围。48个度量转换成了1个维度，4个度量：
转换前：
转换后：
示例地址：[列转行](https://demo.succbi.com/v5/DEMO/data?:open=yrsIW7JQN60LAFrDDR4Ww)
## 操作步骤{#steps}
可以通过手动拖拽的方式将多列数据拖入到一行中或者通过系统内嵌的[智能推荐](#智能推荐)功能达到列转行的效果。
手动进行列转行的操作步骤如下：
1. 在输入表左侧点击+号，选择添加**列转行**组件
2. 点击**添加**按钮，选择添加行，一共添加12行，在转换列表的**描述列**字段列手动输入**1-12月份**
3. 点击**添加**按钮，选择添加数据列，添加3个新的**数据列**，并将第一个和新增三个数据列依次重名为【项目数量】、【达标数】、【未达标数】、【达标比例】
4. 依次将**可用字段**中1-12月份的中【项目数量】、【达标数】、【未达标数】、【达标比例】拖入到4个**数据列**中
## 智能推荐{#recommendation}
系统提供了智能的列转行推荐，可以一键式的实现列转行。
智能推荐是对源表的字段名称进行分析，根据字段名称的前缀、后缀或者中间部分相同的规则，推荐出用户可能用到的行列选项，选择后，属性栏显示具体的选项设置，数据列表能看到转换后的效果。当智能推荐不满足实际需要时，可以设置属性栏自定义转换的行列。
## 可用字段{#available-field}
可作为转换的可选字段，默认是源表所有度量以及维度。选择好的字段会在右侧的转换列表中显示
## 转换列表{#conversion-list}
默认有2列：
1. 编码列：即**字段**列，将选择的字段名称作为描述列的数
2. 数据列：即**值**列，表示字段列该行维度对应的数据。\
这两列将作为字段，显示在数据列表中，没有添加的其他可选字段保留。
需要添加编码列或数据列时可点击**添加**按钮，可添加**行**、**数据列**、**编码列**
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/snapshot-period.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/snapshot-period"
title: "加工组件：周期快照"
---
---
order: 15
navTitle: 周期快照
---
# 加工组件：周期快照
周期快照组件是将随着时间变化的数据表，转换成以具有规律性的时间周期（如日、月等）来记录事实的快照表。
::: tip
使用周期快照组件时，数据加工的输入表必须是缓慢变化的表。
:::
**适用场景**：当事实表数据可能每天发生变化时，为了记录这些变更，方便查询历史数据，一般会做成缓慢变化表。当需要对事实表根据时间进行趋势分析时，可以使用周期快照。
如将缓慢变化的人口抽样表转换成以年为周期的表，便于查看每年不同性别不同婚姻状况下的人数：
示例：[周期快照](https://demo.succbi.com/v5/DEMO/data?:open=LWJ1JJJ33eMCkyprkEPSmB)
**操作步骤**
1. 点击**人口抽样数据**右侧的+号，选择**转换**>**周期快照**
2. [有效期起字段](#有效期字段)：下拉选择【开始时间】
3. [有效期止字段](#有效期字段)：下拉选择【结束时间】
4. [周期粒度](#周期粒度)：下拉选择**年**
## 有效期字段{#period-field}
1. 有效期起字段：源表中每个业务周期的开始时间，数据开始变化的时间字段，如缓慢变化的事实表中的【开始时间】。
2. 有效期止字段：源表中每个业务周期的结束时间，数据结束变化的时间字段，如缓慢变化的事实表中的【结束时间】。
## 周期粒度{#snapshot-grain}
目标表中有规律性的时间周期，如：年、年季、年月、日期，当设置周期粒度后，数据则会按照周期粒度进行分组聚合，比如缓慢变化粒度是天，周期粒度设置为月，数据则会按照粒度到月的时间进行分组聚合。
## 限定最大数据期{#restrict-max-dataPeriod}
限定最大数据期为当前时间对应的数据期。
1. 数据中存在有效期止时间为2299年12月31日时，为避免产生过多无效数据，应勾选此选项
2. 数据中不存在无限期的缓慢变化，为避免今日之后的数据期被过滤，应取消勾选此选项
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/script.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/script"
title: "加工组件：脚本"
---
---
order: 16
navTitle: 脚本
---
# 加工组件：脚本
脚本组件是使用脚本进行加工一些难以用SQL实现的逻辑，实现对数据表的转换。
如将JSON格式的数据转化为多个字段：
示例地址：[脚本](https://demo.succbi.com/v5/DEMO/data?:open=YuDsNh6mhFIA7ol1XHXuUD)
```ts
/**
* 脚本返回类型，必须定义，后台会根据返回结果做不同处理
* 1. Table，在物理表基础上再做加工
* 2. Sql，在sql基础上再做加工
* 3. Stream，流式加工数据
* 4. None，无结果
*/
function getReturnType(): ScriptNodeDataType {
return ScriptNodeDataType.Stream;
}
/**
* 脚本节点的执行入口。下面几种情况会触发脚本节点的执行：
* 1. 后端定时调度加工模型
* 2. 用户手工调度加工模型
* 3. 前端用户预览脚本节点的数据
*/
function onProcessScriptNode(context: IDataFlowScriptNodeContext): void {
//在这里输入脚本节点的业务逻辑代码
let inputData = context.getInput();
let outputData = context.getOutput();
// 可直接将前序节点的字段设置到输出字段中,然后将多的给删掉
outputData.setFields(inputData.getFields());
outputData.removeField("TITLE");
outputData.removeField("CAST");
// 可直接传入值
outputData.addField("cast_id", FieldDataType.I);
outputData.addField("character");
// 可传入一个json
outputData.addField({ name: "gender", dataType: FieldDataType.I });
outputData.addField({ name: "credit_id" }, 3);
// 可添加多个字段
outputData.addFields([{ name: "name" }, { name: "order", dataType: FieldDataType.I }]);
// 先将所有的字段顺序定下来，避免存储数据时重复查找字段
let fields: DbFieldInfo[] = outputData.getFields() || [];
let fieldCount = fields.length;
// 定义在这里，复用一个行对象，节省内存
let outRow: any[] = new Array(fieldCount);
// 读取前2行数据进行转换,测试
for (let i = 0; i < 2; i++) {
let srcRow = inputData.nextRow();
let castObj = JSON.parse(srcRow[2]);
castObj.forEach(data => {
outRow[0] = srcRow[1];
for (let j = 1; j < fieldCount; j++) {
outRow[j] = data[fields[j].name];
}
outputData.writeRow(outRow);
});
}
}
```
更多脚本及实例可参考：[数据加工脚本组件](../../dev/script/backend/etl-script-node.md)
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/sql.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/sql"
title: "加工组件：SQL"
---
---
order: 17
navTitle: SQL
---
# 加工组件：SQL
通常使用数据加工处理数据并不需要手动编写SQL语句，但数据加工仍然支持通过添加**SQL组件**来使用SQL的方式加工数据，在实现一些复杂或数据库中特有语法逻辑时可以使用，比如[调用数据库存储过程](./stored-procedure.md)、删除数据或更新数据等。
按照使用场景，SQL组件可以**作为输入节点**和**作为加工节点**添加。
::: warning 警告
SuccBI中不建议使用SQL进行数据处理，原因如下：
1. 系统不能自动分析模型与SQL中引用表的依赖关系，需要手动进行设置，参考[管理存储过程的血统](./stored-procedure.md#mgr-pedigree)
2. SQL的语法在各数据库中均有差异，不利于数据库之间的迁移
:::
## SQL作为输入节点{#input-node}
在数据加工界面的顶部工具栏中点击**组件** > **SQL**添加，如下：
示例地址：[SQL节点-输入节点](https://demo.succbi.com/v5/DEMO/data?:open=tQLsZJOLARHBtIrd6K5zc)
添加的**SQL组件**将作为一个输入节点，可以在下方的SQL输入区域中输入一个或多个SQL(多个SQL用分号`;`分隔，可以包含符合当前数据库语法的任何语句，如创建表、插入、更新、删除等)，此时作为数据来源通常需要以查询语句（`SELECT语句`）作为最后一条SQL语句，查询出来的结果集将向后传递，并在模型输出节点中可落地为数据库表。
::: tip 提示
1. SQL作为输入节点也可以只对已存在的数据库表进行更新、删除等操作，而不生成新的表，其后序节点是一个数据库表节点（引用的表是SQL中进行处理的表），模型输出中选择[使用上游节点表](../data-output/README.md#use-upstream-table)，使用方式参考[调用数据库存储过程](https://demo.succbi.com/v5/DEMO/data?:open=tQLsZJOLARHBtIrd6K5zc)。
:::
## SQL作为加工节点{#dataflow-node}
在数据加工的**表输出**节点后作为**后序节点**添加，如下：
示例地址：[SQL节点-表输出后序节点](https://demo.succbi.com/v5/DEMO/data?:open=P1R1K7HjmNDT0zGa7YzJeE)
添加的**SQL组件**通常用来对**表输出**中落地的数据库表进行更新或删除，此时可以编写SQL进行更新或使用[更新组件](./update.md)更新。
::: tip 提示
1. 除了表输出，SQL节点在其他组件的后序节点下拉列表中是灰色的，不可添加
2. 加工中通过SQL或更新组件对数据库中已存在的数据库表进行处理后，又需要将该表作为加工的模型输出表，需要使用到提取数据的[使用上游节点表的机制](../data-output/README.md#use-upstream-table)
:::
## SQL中输入使用参数{#ref-variables}
SQL节点可以通过`${参数名}`的方式引用模型中定义的参数，需要注意的是，SQL中的引用参数会忽略参数的类型，直接采用`文本替换`的方式生成SQL，所以需要区分数据类型进行处理，如下：
1. 如果字段是字符型，则需要左右添加单引号引用
```sql
SELECT RXDID AS 日销单ID,
MD AS 门店,
SPSJ AS 商品数量
YSSJ AS 交易时间
FROM ODS_FS_RXD
WHERE RXDID = '${日销单ID}'
```
2. 如果字段是数值型，则无需单引号
```sql
SELECT RXDID AS 日销单ID,
MD AS 门店,
SPSJ AS 商品数量
YSSJ AS 交易时间
FROM ODS_FS_RXD
WHERE SPSJ > ${商品数量}
```
3. 如果字段是日期型，则需要先使用数据库函数转为日期类型
```sql
SELECT RXDID AS 日销单ID,
MD AS 门店,
SPSJ AS 商品数量
YSSJ AS 交易时间
FROM ODS_FS_RXD
WHERE YSSJ > TO_DATE('${日期}','yyyymmdd')
```
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/stored-procedure.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/stored-procedure"
title: "加工组件：存储过程"
---
---
order: 18
navTitle: 存储过程
---
# 加工组件：存储过程
通常使用数据加工处理数据不需要使用存储过程，但如果数据库中已经有存储过程了，数据加工支持通过SQL组件调用存储过程。
示例地址：[调用存储过程](https://demo.succbi.com/v5/DEMO/data?:open=UMERuvWbQBNqgFzrKasP5F)
::: details 点击查看如何创建存储过程
可在SQL查询（参考文档：[SQL查询](../../data-gov/sql-model.md)）中执行存储过程定义语句来创建存储过程，语法如下：
```sql
-- 以MySQL数据库语法为例
create procedure 过程名称(参数)
BEGIN
过程体
END
```
在MySQL数据源中新建SQL查询窗口，输入存储过程定义语句并执行，如下：
::: tip 提示
1. 使用`drop procedure 过程名`删除存储过程
2. 使用`delimiter`来定义语句的结束符
:::
## 在加工中调用存储过程{#call-procedure}
在数据加工中可添加一个SQL组件节点，在SQL组件中使用`call`命令调用存储过程。\
### 调用方法{#call-method}
`call 存储过程名(参数)`
### 调用示例{#call-examples}
示例存储过程`p_quality_customers`定义如下：
```sql
-- 三个参数在过程体中设置了默认值
CREATE PROCEDURE `p_quality_customers`(
IN min_monthly_purchases int
, IN min_dollar_amount_purchased DECIMAL(10,2)
, IN tjyf VARCHAR(6)
)
```
- 不带参数调用\
`call p_quality_customers()`
- 带参数调用\
`call p_quality_customers(3,30,'200508')`
:::tip 提示
一般数据库的存储过程参数类型分为IN（输入）、OUT（输出）、INOUT（输入输出），目前数据加工中调用时只支持IN参数。
:::
## 将存储过程的输出表作为模型输出{#output-table}
在数据管理中，数据加工与物理表一般是一对一的关系，且每个数据加工必须以模型输出节点作为流程图结束的节点，在模型输出节点来指定目标物理表。
在调用存储过程处理数据的场景下，情况有所不同，目标物理表在存储过程中已经处理好了，只需要将存储过程的输出表（表名为FACT\_DVD\_VIP\_CUST）设置为模型输出。
### 设置步骤{#setting-steps}
1. 在调用存储过程的**SQL节点**后添加**物理表**节点
2. **物理表**节点中指定物理表为存储过程的输出表（`FACT_DVD_VIP_CUST`）
3. **物理表**节点后添加**模型输出**，模型输出的提取数据设置为**使用上游节点的表**
## 管理存储过程的血统{#mgr-pedigree}
存储过程加工模型的逻辑位于产品环境外部（数据库服务器中），此时数据加工不能自动解析出输出表的血统关系，只能通过手工编辑字段的`取数公式`或`取数条件`来管理模型的血统。
### 操作步骤{#mgr-pedigree-steps}
1. 在模型输出的字段列表上编辑取数公式\
2. 取数公式的表达式对话框中添加引用表\
引入存储过程加工中使用到的模型
3. 输入取数口径表达式
---
url: "https://docs.succapp.com/v5/guide/data-process/transform/model-output.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/model-output"
title: "加工组件：模型输出"
---
---
order: 19
navTitle: 模型输出
---
# 加工组件：模型输出
模型输出用于输出数据加工的最终结果，一个模型表只能有一个模型输出节点，在模型节点上可以设置整个模型表的属性。
如将销售明细数据完成加工后，将结果输出并保存模型：
**操作步骤**
选中加工流程的最后节点，如“更新”，点击+号，选择**模型输出**。
模型输出组件在输出加工结果的同时，也提供了相应的属性设置，如下：
- 可在**数据面板**>**模型属性**设置加工模型的相关属性，如主键、数据期等，参考文档[模型属性设置](../../data-gov/model/model-settings.md)
- 在模型输出节点，可以对模型进行性能优化，有效提升自助加工的查询速度，参考文档[性能优化](../optimization/README.md)
- 当数据加工完成后需要将数据提取到物理表中，可设置定时提取以及提取范围，参考文档[输出加工结果](../data-output/README.md)
---
url: "https://docs.succapp.com/v5/guide/data-process/optimization/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/optimization"
title: "性能优化"
---
---
order: 7
navTitle: 性能优化
indexTitle: 性能优化
---
# 性能优化
在使用数据加工过程中，遇到大数据量表、字段个数过多表、多表关联或复杂加工逻辑等情况时，可能会遇到加工组件使用不流畅、数据刷新时间长等性能问题，导致严重影响自助加工的使用体验，而其中大多数情况是可以通过良好的使用技巧来避免的。
下面介绍下几种能有效提升自助加工体验的使用技巧：
- [预览数据集](#预览数据集)
- [去掉不必要的字段](#去掉不必要的字段)
- [减少大表关联个数](#减少大表关联个数)
- [提前过滤数据](#提前过滤数据)
## 预览数据集{#debugdatasets}
数据加工的输入表支持设置预览数据集。预览数据集用来按照某种方式抽样数据，让数据加工的后续制作流程中，数据加工逻辑结果的预览在该抽样数据上进行，用来提升加工使用流畅性，尤其是对涉及到多个大表的复杂加工流程时非常有效。
- **预览数据集**：预览数据集支持两个方式来抽样数据
- **只查询固定行数**: 可设置只查询当前表的前N行，N可以指定，默认为10000
- **只查询指定条件**: 可自定义表的过滤条件
- **预览数据开关**: 决定本加工内所有输入节点上设置的预览数据集过滤条件是否生效
- **项目设置**: 在项目设置中设置[默认查询预览数据](../../project-manage/data-mgr-setting.md#default-query)，初次打开数据加工时会自动开启**预览数据开关**
## 去掉不必要的字段{#removefields}
数据仓库中的模型字段个数一般比较多，上百个都是比较常见的。显示过多的字段非常影响数据加工使用的性能，尤其是对于列式数据库，查询不必要的字段带来的性能衰减非常明显。
在输入表模型中可以通过选择字段按钮来勾选只显示必要的字段：
## 减少大表关联个数{#reducetablejoin}
对于Vertica列式数据库，一般超过两个大表的不同字段关联会导致性能低下，且难以优化。加工过程中需要考虑遇到此类情况，尽量建立中间宽表模型来解决，将三张大表的关联，用中间宽表模型转换为两两关联。
1. 三张大表的关联
2. 创建中间宽表模型
3. 转换为两表关联
## 提前过滤数据{#advancefilter}
如果数据加工需要在输入表上过滤数据，则将过滤条件设置尽可能的靠前。对于数据库，部分数据库优化器比较智能能自动将过滤条件下沉，但是也存在数据库的优化器不够智能而无法提前过滤数据，扫描不必要的数据行，导致额外的资源开销。另外，在某些跨源加工中，比如跨源表关联、跨源增量提取，系统会将跨源的表先提取到目标数据源的临时表中再进行处理，如果在跨源提取时能提前过滤数据将能极大提升加工执行性能。
---
url: "https://docs.succapp.com/v5/guide/data-process/setting-params.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/setting-params"
title: "设置动态加工参数"
---
---
order: 8
---
# 设置动态加工参数
动态加工参数是指从仪表板、报表、SuperPage等外部应用中传递参数值给[不提取的数据加工](./data-output/README.md#virtual)来动态获取一个查询结果集。
有些特殊的场景下，需要在数据加工逻辑中提前使用动态参数过滤数据，比如加工的来源表数据量大需提前过滤优化性能、动态统计缓慢变化表中某个时点的数据。
通常情况下，查询条件比较简单时只需要在仪表板、报表、应用等[引入的数据模型中设置过滤条件](../data-viz/dash/design/datasource.md#filter)即可实现动态查询而不需要通过创建不提取的数据加工来传递动态参数，比如在[企业信息自助查询](https://demo.succbi.com/v5/demo-spg/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E5%88%86%E7%B1%BB%E6%B5%8F%E8%A7%88)时根据选择的企业动态的传递企业ID值给钻取的企业一户式页面进行过滤，传递不同的企业ID便可以看到不同的企业一户式信息。
## 提前过滤动态参数条件{#pre-filter}
当数据加工逻辑较复杂且来源表数据量很大时应尽可能将过滤条件提前设置以提升SQL执行性能（详细参见：[性能优化-提前过滤数据](./optimization/README.md#advancefilter)），尤其是加工逻辑中有汇总节点时，应先过滤后再对过滤后的结果集汇总而不是全表汇总。
示例地址：[动态查询指定月份的销售完成情况](https://demo.succbi.com/v5/DEMO/data?:open=RYh2RP7zKyCYBiQsyKjezD)
示例加工用来从[门店月销汇总表](https://demo.succbi.com/v5/DEMO/data?:open=fcby8R17NfCga3tclsn2lB)和[门店月度进销计划表](https://demo.succbi.com/v5/DEMO/data?:open=NZVs56VSxqCo7vue3xI4pB)中查询指定月份的服饰销售完成情况指标数据，具体加工步骤如下：
1. 添加`门店月销汇总表`输入节点，并提前过滤截止【查询月份】本年的数据。
2. 计算【本月实际销售数量(件)】、【本月实际零售总额(元)】、【本年实际累计销售数量(件)】、【本年实际累计零售金额(元)】，计算后过滤出本月数据。
3. 对过滤后的本月门店月销汇总结果集再按照【月份】进行汇总。
4. 添加`门店月度进销计划表`输入节点，并提前过滤【查询月份】所属年份的数据。
5. 对过滤后的门店月度进销计划结果集按照【年份】汇总，计算【全年计划销售数量(件)】、【全年计划零售总额(元)】。
6. 最后再进行关联，即可获取指定【查询月份】的销售完成情况指标数据。
以上加工过程均将要查询的月份数据尽可能提前过滤出来再进行加工，避免了对全表进行汇总，可以提升查询性能。
## 动态统计缓慢变化表中某个时点的数据{#statis-slowchg}
示例地址：[SQL动态参数](https://demo.succbi.com/v5/DEMO/data?:open=tQLsZJOLARHBtIrd6K5zc)
示例加工中，传入动态参数【查询日期】，按照【经济户口类别】分组查询统计截止指定的【查询日期】时当年累计的新设企业数量，SQL实现时应按照如下思路先过滤再分组统计而不能先统计再过滤（缓慢变化表先统计时同一个企业可能会存在多条数据，造成统计异常）：
1. 根据传入的动态参数【查询日期】，先从[企业信息缓慢变化表](https://demo.succbi.com/v5/DEMO/data?:open=O20vb6tsc4BF2i7PKKZFPB&:tblview=modelData)中使用【有效期起】和【有效期止】两个字段过滤出该日期时点的企业快照信息。
2. 再使用【成立日期】范围过滤出截止【查询日期】当前的新设企业信息。
3. 最后使用【经济户口类别】进行分组统计新设企业数量。
---
url: "https://docs.succapp.com/v5/guide/data-process/data-output/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/data-output"
title: "输出加工结果"
---
---
order: 9
navTitle: 输出加工结果
indexTitle: 输出加工结果
---
# 输出加工结果
默认情况下，每个数据加工模型都会输出一个[数据库表](../../data-gov/GLOSSARY.md#data-table)（通过加工流程图最后的[模型输出](../transform/model-output.md)节点），可以把这个输出的[数据库表](../../data-gov/GLOSSARY.md#data-table)看成是一个数据仓库中的[事实表](../../data-gov/GLOSSARY.md#fact-table)或[维表](../../data-gov/GLOSSARY.md#dimension-table)，加工输出的数据库表和数据加工是一一对应的，数据加工被报表或仪表板引用时其数据即来源于对应的数据库表。
## 输出虚拟的数据表{#virtual}
当有动态参数（可参考文档[设置动态加工参数](../setting-params.md)）或者需要查询实时数据时，可以不勾选提取数据。不提取数据时，数据加工可以看成一张的虚拟表，类似数据库中的视图，查询时直接执行加工逻辑的SQL语句。
## 输出物化的数据表{#materialized}
勾选**提取数据**时，可以将加工的数据输出到一张[目标数据库表](../../data-gov/model/model-settings.md#dest-table)中，通常用于数据仓库系统中将来源业务库的表加工后提取到目标数据库中时设置，与[虚拟数据表](#virtual)相比，查询时的性能会更好。
提取数据的数据加工有两个基本的特征：
- 每个数据加工对应一个数据库表
- 数据加工对应的数据库表是加工流程图最后的模型输出节点中设置的目标数据库表
实际使用中，提取数据分为两种场景：[提取到指定表](#extract-spec-table)和[使用上游节点的表](#use-upstream-table)。
### 提取到指定表{#extract-spec-table}
在**模型输出**节点下，选择**数据面板**>**模型属性**，勾选**提取数据**：
示例地址：[门店月销汇总表](https://demo.succbi.com/v5/DEMO/data?:open=fcby8R17NfCga3tclsn2lB&:expandIds=aqphlalN1SEgYW8sP8ZKjD)
勾选后，出现的下拉框中默认会选中**提取到指定表**，即将加工数据提取到一个指定的数据库物理表中，具体设置介绍见[模型属性-提取数据](../../data-gov/model/model-settings.md#extract-data)，该方式在提取数据时是最常见的，适用于先对来源数据进行清洗加工最后再输出加工结果数据的场景。
### 使用上游节点的表{#use-upstream-table}
通常数据加工过程都是先加工最后再输出数据的，此时采用[提取到指定表](#extract-spec-table)方式即可，但是实际应用时有些特殊的场景下目标数据已经在前面的加工流程中落地到数据库表中了，而不希望在模型输出节点的属性上重新指定新的数据库表，则可以选择使用**使用上游节点的表**，主要对应如下几种使用场景：
1. 加工数据已经在加工流程图的表输出节点中落地输出到数据库表，需要进一步对该数据库表的某些字段进行更新
示例地址：[更新](https://demo.succbi.com/v5/DEMO/data?:open=fgtdGt3PTUBfG1y2rwTMUE)
示例加工中主要包含如下三个步骤：
- 将来源文件源中城镇单位就业人员历年的平均工资（其中缺乏2018年的数据）使用[表输出](../transform/table-output.md)节点提取到数据库表中。
- 将2018年的就业工资数据更新到上一步输出的数据库表字段中。
- 模型输出节点选择使用上游节点的表，目标数据库表自动设置为前序节点-[更新节点](../transform/update.md)中的更新主表。
2. 数据库表是在加工过程中使用SQL组件调用数据库存储过程中生成的，需要将外部生成的数据库物理表直接作为数据加工模型的目标数据库表
示例地址：[调用存储过程](https://demo.succbi.com/v5/DEMO/data?:open=UMERuvWbQBNqgFzrKasP5F)
示例加工中主要包含如下三个步骤：
- 在SQL组件中调用数据库存储过程加工数据，存储过程处理好数据后会输出到一张目标表（表名：`fact_dvd_vip_cust`）中。
- 在SQL节点添加一个后序节点-数据库表，并引入存储过程中输出的数据库表`fact_dvd_vip_cust`。
- 数据库表节点后序节点添加模型输出，并设置为使用上游节点的表，即将`fact_dvd_vip_cust`直接作为当前数据加工模型的目标数据库表。
::: tip 提示
1. 选择**使用上游节点的表**的**前提条件**是目标数据库表在前面的加工流程图中已经存在或者生成，鉴于这样的应用场景，数据加工中限制只有当模型输出的前序节点是**更新**、**表输出**、**数据库表**、**模型表**四种节点时，模型输出上才能选择**使用上游节点的表**。
2. 通常数据加工模型对应的目标数据库表的属性，比如字段类型、长度等是直接在模型输出节点上管理的，但是对于**使用上游节点的表**时需要遵循一个原则：**数据库表在哪里产生其物理层信息（如主键、字段类型、长度）就在哪里管理**，同时数据加工也做了如下的强制限制：
- 模型输出节点的字段列表上禁用了字段类型、长度等选项。
- 模型属性的主键设置只能从数据库表读取，手动设置的主键不能往数据库表中同步。
- 模型属性的**性能优化** > **索引管理**标签页被隐藏，其中有个特殊情况是，如果数据库表是在加工流程中的表输出节点生成的，那么允许在模型输出节点的索引管理中管理索引信息，主要原因是表输出节点不具备索引管理能力，需要模型输出节点赋予该项能力。
:::
### 数据提取方式{#extractmethod}
将数据更新到目标数据库表的方式，支持以下六种类型的提取方式：
1. 重建表
2. 全量覆盖
3. 清空旧数据并插入新数据
4. 按主键合并追加
5. 只追加
6. 插入缓慢变化数据并自动更新起止时间
可根据实际的使用场景进行选择，详细的使用介绍请查看[模型属性-提取方式](../../data-gov/model/model-settings.md#extract-mode)。
---
url: "https://docs.succapp.com/v5/guide/data-process/data-output/increment-output.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/increment-output"
title: "增量数据提取"
---
---
order: 1
---
# 增量数据提取
增量提取是指提取数据时只提取新增和修改的数据到目标表中，而不对目标表中存量未发生变化的数据进行处理。相对**全量覆盖**提取而言，因新增和修改的数据一般较少，所以增量提取往往具备更好的提取性能。
加工模型支持以下三种方式的增量提取：
\[\[toc]]
## 清空旧数据并插入新数据{#overwriteinc}
清空旧数据并插入新数据指的是根据设置的**清空范围**先删除目标表中的旧数据，再将当前加工结果数据全部插入。清空旧数据并插入新数据常用于能按照固定时间周期去增量更新目标表数据的场景，如日报表、月报表、年报表的数据提取。
示例说明：按月增量提取销售月报表
具体操作步骤如下：
1. 将加工数据过滤为当月的数据\
2. 设置提取方式为清空旧数据并插入新数据，并设置清空范围为清空当月数据\
执行提取时，先按照清空范围删除销售月报表（xsybb）的当月数据，再将当前加工结果数据全部插入（当前加工在步骤1中已过滤为当月数据）。
::: tip 提示
清空旧数据并插入新数据提取方式中插入的新数据指的是模型输出前序节点输出的数据，如果你想只插入增量数据，则需要在模型输出之前先过滤出增量数据。考虑到数据提取的性能，建议尽可能早的进行增量数据过滤，尤其是在跨源提取时，跨源数据会先落地到目标数据源的临时表中，如果只落地增量部分数据，则会极大提升提取性能，详见[提前过滤数据](../optimization/README.md#advancefilter)。
:::
## 按主键合并追加{#merge}
按主键合并追加指的是将目标表和当前加工结果中主键相同的数据进行合并，再将当前加工结果中有而目标表中没有的数据追加至目标表中。
其中合并的方式根据**更新已有数据**勾选项来确定：
- 勾选：使用当前加工结果数据更新目标表数据
- 未勾选：跳过目标表和当前加工结果中主键相同的数据，不做任何修改
::: tip 注意
合并过程依赖于模型主键，所以此提取方式的前提是模型必须设置主键。如果未设置主键，保存会报异常。
:::
按主键合并追加常用于不能删除历史数据但是可以更新历史数据的场景，比如企业年报表，在年报截止日前，企业被允许多次修改已填报的年报数据，数据提取时可以用每日年报的数据来更新企业年报表。
示例说明：用还款信息ODS表的当日数据增量更新数据仓库中的合同还款计划信息表
具体步骤如下：
1. 过滤还款信息ODS表的当日变更数据（包括新增合同和发生还款业务的合同）\
2. 目标表设置主键
3. 设置提取方式为按主键合并追加
执行提取时，先根据主键更新目标表中已有合同的还款信息，如客户罚息、实收利息，再将新增的合同还款数据插入目标表中。
::: tip 提示
按主键合并追加是对目标表不进行任何删除操作前提下更新数据的提取方式。考虑到数据提取的性能，同样需要在模型输出节点前尽可能早的过滤出增量或变更部分的数据，详见[提前过滤数据](../optimization/README.md#advancefilter)。
:::
## 只追加{#append}
只追加指不对目标表数据做任何处理，直接将当前加工结果全部插入目标表。此方式适用于记录流水数据的场景，如将新产生的日志数据追加到日志表中。
示例说明：将每日操作流水日志保存到历史操作日志表中
执行提取时，直接将当前加工结果数据全部插入目标表。
---
url: "https://docs.succapp.com/v5/guide/data-process/data-output/slowchange-output.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/slowchange-output"
title: "缓慢变化数据提取"
---
---
order: 2
---
# 缓慢变化数据提取
数据仓库中一般使用缓慢变化表来记录数据随着时间的流失发生的缓慢变化过程，加工模型支持直接使用当前快照数据更新缓慢变化表的提取方式，即**插入缓慢变化数据并自动更新起止时间**。
示例说明：企业信息缓慢变化表的增量提取
具体操作步骤如下：
1. 输入表为当前全量的企业快照数据
2. 设置目标表的主键和数据期类型
3. 设置提取方式为插入缓慢变化数据并自动更新起止时间
## 处理规则{#processrules}
**插入缓慢变化数据并自动更新起止时间**是特定的用于目标表是缓慢变化表的增量数据提取方式，其具体含义是将当前加工结果与目标表（缓慢变化中当前数据）按照主键（除去缓慢变化起、止字段）进行数据比对， 并依据如下规则进行处理：
1. 如果指定的**记录变化**的字段中有任意一个发生了修改，则视为数据发生变化，系统将目标表中对应数据的缓慢变化止时间修改为当前加工结果对应数据的缓慢变化起时间-1。
2. 如果指定的**记录变化**的字段中没有任何字段发生修改，则将不做任何处理。
3. 如果数据在目标表中有而当前加工结果没有，则视为数据被删除，系统将目标表中对应数据的缓慢变化止时间更新为当前时间-1
4. 如果数据在当前加工结果中有而目标表有效数据中没有，则视为新增数据，直接将当前加工结果中对应的数据插入到目标表中。
::: tip 注意
- 插入缓慢变化数据并自动更新起止时间是针对于缓慢变化特有的方式，故提取方式中能选择该方式的前提是模型属性中已经设置了模型的[数据期类型](../../data-gov/model/model-settings.md)为**缓慢变化**且指定了**缓慢变化起**和**缓慢变化止**字段。
- 数据比对过程依赖模型主键，所以模型必须要设置有主键。如果未设置主键，提取会报未设置主键的错误。
- 因处理规则3，故要求当前加工的结果数据必须是目标模型在当前时刻的全量快照数据，否则会被标记为删除。
- 因缓慢变化提取依赖主键进行逻辑处理，当前加工的结果快照数据必须是主键唯一的，否则会导致提取过程报错或造成目标表数据混乱。
:::
## 记录变化{#recordchanges}
**记录变化**用来设置哪些字段将被纳入缓慢变化中，只有纳入缓慢变化中的字段发生了修改，才会被认定数据发生缓慢变化。该下拉框中可选用三种方式之一来指定记录变化的字段：
- 所有字段的变化
- 指定字段的变化
- 忽略指定字段的变化
只有**所有字段的变化**不需要再通过**指定字段**下拉框设置字段。
---
url: "https://docs.succapp.com/v5/guide/data-process/timed-refresh.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/timed-refresh"
title: "定时刷新加工结果"
---
---
order: 10
---
# 定时刷新加工结果
加工模型定义好之后，我们通常需要模型能定时更新为最新的数据，及时反应业务变化，此时可以设置模型的**定时提取**功能，每隔固定的时间间隔，系统自动执行一次**提取数据**。
:::tip
1. **定时提取**需要勾选**提取数据**将加工结果输出到物理表中，也可设置目标物理表、全量提取/增量提取等属性，参考文档[输出加工结果](./data-output/README.md)。
2. **定时提取**需要结合**计划**执行，定时提取下拉框的选项为项目中的计划，系统默认内置的**计划**为**早上5点**、**晚上12点**和**系统初始化提取**，也可在**计划**中新增**计划**或是修改已有的**计划**，参考文档[计划]()。
3. 在自动执行**提取数据**时，系统会自动分析加工模型之间的依赖关系并自动编排调度顺序，保证在最短的时间内完成数据调度。
:::
如每天晚上12点抽取数据：
**操作步骤**
1. 在**模型输出**节点下，选择**数据面板**>**模型属性**，勾选**提取数据**
2. 在**定时提取**下拉框中选择**晚上12点**
---
url: "https://docs.succapp.com/v5/guide/data-process/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/faq"
title: "常见问题"
---
---
order: 11
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/data-process/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/data-process/errcode"
title: "数据加工错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 数据加工错误提示排查
---
url: "https://docs.succapp.com/v5/guide/schedule/README.md"
htmlUrl: "https://docs.succapp.com/v5/schedule"
title: "调度管理"
---
---
order: 5
navTitle: 调度管理
indexTitle: 调度管理
---
# 调度管理
调度管理（计划任务）负责定时执行系统中的各种类型的任务，包括数据提取任务、定时计算任务，数据质量较验任务、甚至一些脚本开发的个性化的业务逻辑任务。
## 计划管理{#manage-schedule}
一个计划表示一个定时执行的“批次”，同时也是调度功能中的一个管理单元。每个计划都可以配置独立的调度策略（如执行频率、并发度等），系统会根据这些策略自动调度和执行计划内的所有任务。通过计划，用户可以将具有相似业务属性或执行要求的任务组织在一起，实现任务的统一管理和自动化执行。
### 增删计划{#add-remove-schedule}
1. **新建计划**：在**计划**页面，点击**新建**，在打开的二级页面中设置计划相关属性后，点击**保存**按钮
2. **删除计划**：勾选计划，点击左上角的**删除**按钮，需要注意的是**计划被删除后，不能撤销**
计划上的属性设置分类三类：基本、任务、高级，具体如下：
**基本**
- **启用**：默认勾选，表示计划创建后系统会开始按时间设定进行调度，如果希望创建的计划先不要开始定时调度，那么可以取消勾选
- **名称**：计划的名称
- **详细信息**：计划的详细描述信息
- **类型**：计划中可以添加哪些类型的任务，可选数据提取、订阅、数据检测，订阅类任务和数据提取类任务不能共存于一个计划
- **所属文件夹**：计划所属的分类，方便用户管理，使用`/`作为分隔符可以实现多级分类，如`/test/plan1`。可参考[计划分组显示](#schedule-group)
- **并行执行**：默认为串行，表示计划内多个任务间的执行关系，是并行还是串行，若为并行，还需要输入并行度，即并行的任务的个数，建议参考服务器性能设置
- **并行度**：当计划的并行执行为并行时，需要设置并行度，即同时执行的任务个数
- **执行策略**：并行执行时用于控制不同优先级之间分层执行顺序的策略，可选值为：
- **高优先级优先开始**：优先级高的任务先执行，有多余线程时也会同时执行低优先级任务
- **高优先级必须先执行完**：优先级高的任务先执行，有多余线程时也必须先等高优先级执行完后再开始低优先级任务
- **高优先级必须先成功执行完**：优先级高的任务先执行，有多余线程时也必须先等高优先级成功执行完后再开始低优先级任务。如果有高优先级的任务执行失败，则整个计划会终止执行，低优先级的任务都不会执行。
- **时间设置**：计划自动执行的时间，系统提供了如下图所示丰富的时间选项，可以选择执行一次，或者间隔固定时间执行，以及自定义设置
- **执行条件**：计划调度的前提条件，不满足调度条件的计划将不会执行，比如 `TOSTR(TODAY(),'dd') = '01'` 表示计划只在每个月1号执行
- **计划超时时间**：计划的整体超时设置，单位为秒。用于控制计划的整体执行时间不超过多长时间，当超过执行时间时，剩余的任务将不会被执行，计划会直接退出，但已经开始的还是会继续执行，主要用于避免因为网络阻塞等问题导致计划执行时间超过预期的执行时间窗口。
**任务**
给计划内的所有任务设置的默认属性。
- **任务默认优先级**：任务的默认优先级，优先级范围是0～100，任务可以有各自不同的优先级。若不考虑依赖关系，优先级高的任务将总是优先执行。数值越大，优先级越高。
- **任务默认超时时间**：任务执行的最长时间，单位为秒，任务执行超时将被终止，并根据失败重试规则决定是否重新尝试执行。主要用于防止在某些网络阻塞的情况下导致任务长时间阻塞。
- **失败重试**：任务执行失败时可以给不同类型的错误设置不同的重试策略。
- **匹配错误**：系统预置了几种类型错误可以直接选择，如**默认**、**网络错误**、**任务执行超时**、**数据未就绪**，也可以输入任务执行错误日志的关键词进行匹配。
- **重试间隔（秒）**：任务执行失败后，重试的间隔时间，单位为秒。
- **最大重试次数**：任务执行失败后，最大重试的次数，超过最大重试次数后，任务将不再重试。
- **最长重试时间**：任务执行失败后，最大重试总时长，单位为秒，超过最长重试时间后，任务将不再重试。
**高级**
- **全局参数**：计划内的全局参数，会根据同名传递规则自动传递给计划内的所有任务（前提是任务定义的同名参数），比如计划内多个任务都接受数据期参数进行增量提取，默认都是提取当月数据，当需要统一重新提取指定期的数据时，可以在计划全局参数中定义参数`数据期=2024`，那么计划内可以接收数据期参数的增量提取任务都会按照2024年的数据进行提取。
- **依赖计划**：计划准备执行时，若依赖的计划正在执行，会等待这些计划执行完毕后才开始执行当前计划。
- **指定集群节点**：集群环境下，指定计划在选择的节点列表上执行，系统将按照列表顺序选择第一个可用的节点执行，如果选择的节点都不可用，则计划不会执行；系统提供了可视化页面查看集群节点的状态，参考[集群状态](../sys-settings/performance/cluster.md#集群状态)
- **结果通知**：计划执行完成后是否通知用户，可选择**不通知**、**总是通知**或者**出错时通知**。
- **消息模板**：选择发送结果通知使用的[消息模板](https://docs.succapp.com/v5/sys/settings/co)，也可以选择添加模板来创建一个消息模板。
- **接收用户**：接收结果通知的用户，通知用户支持输入用户的ID，邮箱地址或者手机号码，用户将在计划执行完成后收到结果通知。使用通知功能前，需要在[外部服务](../sys-settings/more/remote-services/README.md)按需配置好[邮件服务](../sys-settings/more/remote-services/email.md)、[短信服务](../sys-settings/more/remote-services/message.md)。
### 执行计划{#run-schedule}
计划如果设置了定时执行时间，系统会自动按照时间调度执行计划（前提是计划处于**启用**状态），也可以手动勾选一个或多个计划，点击左上角的**立即执行**按钮，即可执行勾选的计划。
计划执行时，查看计划的执行进度有两种方式：
1. 在计划列表上的**最近执行状态**中查看执行进度
2. 在[最近调度](#latest-log)界面可以查看计划执行的进度日志
计划支持在指定的集群节点上执行，常用于控制节点间的负载均衡，可以按照节点的执行能力强弱分配计划，在[新增计划](#add-remove-schedule)界面，在**指定集群节点**属性可以设置计划在指定节点上执行，执行结束后，在[所有调度](#计划日志状态)页面，在状态列鼠标移入日志行后，点击**查询计划日志**图标按钮，可以查看计划实际执行的节点。
:::warning
为了确保数据的一致性，计划不能多人同时执行，如果同时执行一个正在执行的计划，系统会提示`计划正在执行中`。
:::
### 中止计划{#halt-schedule}
可以通过如下方式停止正在运行的计划：
1. 在计划列表中勾选需要中止的计划
在计划列表勾选一个或多个正在执行的计划，点击左上角的**中止**按钮，系统会取消计划中还未开始的任务，停止正在执行的任务，对于已经执行完成的任务不会回滚。
2. 在计划调度日志界面停止计划
计划正在执行时，在调度日志界面会显示计划的执行进度条，点击进度条右侧的**停止**按钮，系统也会自动停止计划的执行。
### 批量启用和停用计划{#toggle-schedule}
运维升级时需要停用启用计划，当计划很多时一个个点进去操作很麻烦，可以勾选多个计划，批量的启用或者停用计划，操作如下：
1. 在**计划**页面勾选需要启用或者停用的计划
2. 点击工具栏的**启用**或者**停用**按钮
::: warning
1. 为了确保计划调度的稳定性，停用计划不会取消正在执行的计划，当正在执行的计划完成后，才会被停用
2. 批量停用时，如果选择的计划包括已经停用的计划，点击停用时会自动排除该计划，启用时选择了已经启用的计划也是一样
:::
### 计划分组显示{#schedule-group}
在大型项目中，尤其是数据中台、数据资产管理类系统，会涉及到大量定时的数据归集、推送任务，需要创建很多计划来管理。
在计划的[属性设置](#add-remove-schedule)中，可以通过设置**所属文件夹**属性，将计划进行业务分类，方便查看和管理，如下图：
## 计划内的任务管理{#manage-scheduleTask}
任务是计划的基本组成部分，一个任务通常是一个加工模型、批处理脚本、[系统备份](../sys-settings/project/backup.md#auto)任务或[日志清理任务]()等。
### 在模型表属性中设置定时提取{#set-timedDispatch}
在**模型属性**中设置[定时提取](../data-process/data-output/README.md)时系统会自动在对应的计划中添加一个任务，取消设置后也会同步删除该任务。
### 批量增删任务{#add-remove-tasks}
如果已经存在大量的模型需要都加入到计划内，一个一个添加会比较繁琐，可以进行任务的批量操作，如下：
1. 在**计划**页面，点击计划的名称，进入**任务列表**
2. 在**任务列表**点击**添加**按钮，对话框中选择需要执行数据提取的模型，添加成功后，上方会出现成功添加任务提示
3. 同样的，批量删除任务点击**移除**按钮即可
### 批量移动任务{#move-tasks}
在**任务列表**页面，勾选需要移动的任务，点击**移动**按钮，默认不勾选**在计划中保留任务**。勾选后，移动的任务会保留在原计划中，类似于复制到另一个计划的操作。
### 查看任务{#observe-tasks}
在计划列表点击**名称**列，即可跳转到该计划的**任务列表**页面，提供了两种查看模式：
- 默认以任务列表视图展示该计划内的所有任务及任务的属性
- 点击**流向图**按钮，可切换至[流向图视图](#flow-diagram)，此时以可视化的方式展示任务执行的依赖关系和数据流向
| 列表视图 | 流向图视图 |
|------|------|
|  |  |
当计划内任务需要按照分类管理或分层调度时，可以点击列表视图中的**展开分类**按钮，在展开的左侧树中进行[任务分类管理](#task-category)。
#### 任务属性{#task-properties}
在任务列表视图中，鼠标移入**任务**列，点击显示在任务名称右侧的**设置**按钮，可以在弹出的对话框中可以给任务设置如下执行属性：
- **优先级**： 任务的默认优先级，优先级范围是0～100，任务可以有各自不同的优先级。若不考虑依赖关系，优先级高的任务将总是优先执行。数值越大，优先级越高。
- **依赖**：同模型上的[依赖](../data-gov/model/model-settings.md#depends)设置，通常不需要设置，当任务之间存在循环依赖或系统无法自动识别依赖关系时需要手动介入设置。
- **超时时间**：任务执行的最长时间，单位为秒，任务执行超时将被终止，并根据失败重试规则决定是否重新尝试执行。主要用于防止在某些网络阻塞的情况下导致任务长时间阻塞。
- **错误重试**：任务执行失败时可以给不同类型的错误设置不同的重试策略。同[计划属性](#add-remove-schedule)上的**错误重试**。
- **执行条件**：任务执行的前提条件，不满足执行条件的任务将不会执行，依赖此任务的其他任务不受影响，依然会正常运行，比如 `TOSTR(TODAY(),'dd') = '01'` 表示任务只在每个月1号执行
- **指定集群节点**： 默认情况下，任务会按照集群的负载均衡策略自动选择节点执行，如果希望指定任务在某个节点上执行，可以设置此属性。通常是因为任务需要访问某些特殊的数据库而访问到那个数据库需要在某一个节点上才能访问，此时需要指定执行节点。
- **允许执行时间**：设置任务只允许在指定日期时间（精确到小时）执行，其他时间会忽略执行任务，依赖此任务的其他任务不受影响，依然会正常运行。比如在一个每天执行的计划中，可能有个别任务只在月末或月初执行，此时就可以给任务设置允许执行时间。
- **开始执行时间**：设置任务只能在指定时间之后开始运行，如果时间还没到，此任务会一直等到时间才会启动，依赖此任务的其他任务也会一起等待。主要用于抽取数据时指定从上游业务库抽取数据的时间窗口起始时间。
- **任务分类**：可以将任务进行业务类别划分，详细请参考[任务分类管理](#task-category)
- **参数**：当任务可以接受动态参数时用于给任务进行传参，如果计划上设置了[全局参数](add-remove-schedule)，也会按照同名传递的规则自动传递给任务。
::: tip
在计划内有三个地方都可以给任务设置属性：[计划属性设置](#add-remove-schedule)、[任务分类目录属性设置](#task-category)、**任务属性设置**，任务在执行时会按照`任务属性设置 > 任务分类目录属性设置 > 计划属性设置`的优先级使用。
:::
在两种视图下，右键点击任务/任务所在目录，可进行如下操作：
- **设置**：单独设置任务的[任务属性](#任务属性)
- **定位到**：定位到对应的任务页面，其中提取任务跳转到模型，备份任务跳转至**系统设置** > **项目** > **备份**页面
- **查看**：查看该任务相关的[流向图](#flow-diagram)，可选择只查看当前任务的来源、只查看当前任务的影响或者查看当前任务的来源和影响
- **执行**：可以根据需要选择仅[执行](#run-tasks)当前任务的数据提取，或者执行当前任务的所有来源、执行当前任务的所有影响、执行当前任务的所有来源和影响
### 任务分类管理{#task-category}
在任务列表中，点击**展开分类**按钮，可以在展开的左侧树中对任务进行分类管理，系统提供了三种分类管理视图：
- **任务类别**：给任务设置类别，通常用于[数据仓库的分层调度](#warehouse-layered-scheduling)，将任务划分到不同层级，结合任务的优先级实现分层调度
- **元数据目录**：显示任务的元数据目录层级，方便按照元数据目录进行分类管理
- **任务优先级**：按照执行优先级分类展示任务，方便用户查询任务之间的执行先后顺序
### 执行任务{#run-tasks}
在计划内支持手动选择单个的或者多个任务立即执行，往往用于某个任务执行失败需要重新执行，在**任务列表**勾选需要执行的任务，点击左上角的**立即执行**，也可以通过右键菜单执行，执行后会自动跳转至[最新日志](#latest-log)界面，监控本次计划执行情况。
### 批处理{#batch-process}
批处理本质上是一种服务端[脚本](../data-process/transform/script.md)，常用于实际生产环境的二次开发，比如通过脚本调用copytables批量进行跨库迁移，调用gis服务更新地图信息等，在**任务**页面，点击**批处理**，进入批处理页面，页面提供如下操作：
- **新增批处理**：点击**新建脚本**按钮，在脚本编辑器页面编写自定义脚本，编写完成后可以**格式化**下脚本，保存后点击**执行**，可在进度对话框查看脚本的执行情况
- **删除批处理**：选中需要删除的批处理，点击工具栏的**删除**按钮，即可删除
- **查询批处理**：在顶部工具栏右边的搜索框中直接输入想要搜索的内容即可
- **编辑批处理属性**：点击**编辑**按钮，弹出设置批处理的对话框，可设置
- **名称**：批处理的名称
- **计划**：批处理所在的计划，如果希望批处理定时调度，那么可以将批处理添加至指定计划
- **依赖**：批处理依赖的模型，可设置批处理在指定模型调度完成后执行
## 日志{#log}
计划或者任务执行的详细日志，包括执行SQL，提取的数据行数、异常报错等信息
### 最近一次执行的任务日志{#latest-log}
**最新日志**页面可显示最近一次执行的任务日志（包括正在执行），正在执行时的日志界面如图：
- **执行进度**：显示计划的执行进度及预计剩余完成时间
- **停止按钮**：点击中止计划执行
- **任务筛选**：按照执行状态、任务名称筛选列表中的任务，便于出现问题时的异常跟进
- **视图切换**：
- 支持切换显示表格视图、树视图，默认状态下为表格视图
- 点击[流向图](#flow-diagram)可查看该计划内各个任务间的依赖关系及数据流向
- **任务列表**：
- 列表的列头支持排序
- 以瀑布图形式展示每个任务的执行顺序和执行耗时
- 点击任务名称，可以跳转到对应的任务页面
- 点击日志列的查看按钮，可以查看和复制某个任务的执行过程及具体SQL，出现异常的任务还会显示具体的异常信息，方便用户排查问题
- 点击**操作**>**日志**，可以查看任务的执行日志
### 计划的历史执行日志{#history-log}
在计划列表的**操作**列中，点击某一条计划的**日志**，进入**所有日志**页面
- 过滤筛选栏：支持在日志列表中，对计划执行的开始、结束时间，耗时范围及执行状态进行筛选
- 点击**操作**>**日志**，可以查看本次执行计划级别的日志
- 点击**操作**>**查看**或双击行，查看当时计划执行的任务的日志信息，整体界面与[最近一次执行的任务日志](#最近一次执行的任务日志)相同
### 日志状态{#log-status}
日志的状态包括计划日志状态和计划任务日志状态。
#### 计划日志状态
进入[所有日志](#history-log)页面，在状态栏可以查看计划日志的状态，计划日志状态包括：
- **成功**：执行一次计划，计划中的任务要么执行成功要么因为不满足**调度条件**而取消，不存在异常的任务
- **失败**：执行一次计划，计划中部分任务执行出现异常
- **取消**：执行计划过程中，用户取消了计划的执行
- **正在执行**：计划正在执行
#### 计划任务日志状态
进入[最新日志](#latest-log)页面，在状态栏可以查看计划任务日志的状态，计划任务日志状态包括：
- **成功**：计划任务执行成功
- **失败**：计划任务执行出现异常
- **取消**：计划任务被取消
- **正在执行**：计划任务正在执行
- **等待**：计划任务等待被调度
::: tip
计划的**调度条件**包括[提取前检查](/howto/4dfd7483#提取前检查)设置的条件以及[任务属性](#任务属性)设置的条件。
:::
## 流向图{#flow-diagram}
流向图展示了计划内各个任务间的依赖关系，在计划执行过程中，也可以在流向图中看到模型执行的顺序，数据流向等。
### 查看流向图{#observe-flow-diagram}
在**计划**页面点击计划名称，在左侧导航栏选择`流向图`标签，查看最新执行任务流向图。
鼠标移动到流向图的模型上，会浮动出模型的名称、路径、最新调度等信息；右键出现的菜单选项中提供如下操作：
1. **定位到**：系统会定位到当前任务对应的模型中，点击浏览器的返回按键可以回到流程图界面
2. **查看**：当流向图展示的任务太多时，可以选择只查看当前任务的来源、只查看当前任务的影响或者查看当前任务的来源和影响
3. **执行**：可以根据需要选择仅执行当前任务的数据提取，或者执行当前任务的所有来源、执行当前任务的所有影响、执行当前任务的所有来源和影响
## 应用场景{#use-case}
### 数据仓库分层调度{#warehouse-layered-scheduling}
在数据仓库建设中，原始数据通常来源于不同的上游系统，比如CRM、OA、ERP等，抽取到数据仓库后需要进一步进行清洗、转换、建模等，对于大型数据仓库项目的数据ETL过程通常分为多个层次：
1. ODS层：原始数据层，保存原始数据，不做任何处理
2. DIM层：公共维度层，保存公共维度数据，比如时间维度、地区维度等
3. DWD层：明细数据层，保存明细数据，比如用户行为数据、订单明细数据等
4. DWS层：汇总数据层，保存汇总数据，比如按照地区、时间等维度汇总的订单数据
5. ADS层：应用数据层，保存应用数据，比如报表数据、大屏数据等
将以上所有层次的加工任务都添加到同一个计划中，默认情况下系统会按照任务的依赖关系这么去调度，这样可以确保在最短的时间窗口内完成调度。但有些情况下可能希望在调度过程中任务执行的层次分明，比如DWD层需要等待ODS和DIM层调度完成后才能开始调度，DWS层需要等待DWD层调度完成后才能开始调度，这时候需要进行分层调度配置。
示例地址：[服饰数仓分层调度]()
在系统的调度管理中可以通过**任务类别**结合**优先级**的方式实现分层调度，以服饰数据仓库为例，要实现分层调度，需要按照如下步骤配置计划：
1. 新建计划并设置计划的执行策略属性为**高优先级必须先成功执行完**（也可以按需改成其他策略）
2. 切换到任务列表视图->展开分类，分别创建ODS、DIM、DWD、DWS、ADS五个任务类别，并分别设置优先级，比如90、80、70、60、50
3. 点击任务类别，分别将任务添加到对应的任务类别下
系统在调度该计划时，会优先调度高优先级的任务，高优先级的任务执行完成后再调度低优先级的任务，因为在2中给任务类别设置了优先级，所以调度时会按照任务类别的优先级顺序进行调度，即ODS->DIM->DWD->DWS->ADS的顺序执行。
---
url: "https://docs.succapp.com/v5/guide/schedule/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/schedule/faq"
title: "常见问题"
---
---
order: 9
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/schedule/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/schedule/errcode"
title: "调度管理错误提示排查"
---
---
order: 1
navTitle: 错误提示排查
---
# 调度管理错误提示排查
---
url: "https://docs.succapp.com/v5/guide/data-gov/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov"
title: "数据管理介绍"
---
---
order: 6
navTitle: 数据管理
indexTitle: 概述
---
# 数据管理介绍
SuccBI的数据管理包括数据的接入、建模、元数据管理、加工、调度、数据权限管理等等，用户使用SuccBI时只需要通过SuccBI提供的数据管理功能就能轻松管理企业数据仓库，避免了操作多种数据库管理工具，也无需DBA技能。
\[\[toc]]
## 快速连接业务系统数据
政府机构和企业在信息化发展过程中建设了很多相互独立的业务系统，这些业务系统经过多年的运转沉淀了很多数据，这些数据像是一个个孤岛，难以被统一的连接和管理。SuccBI支持快速的连接这些数据孤岛，并将其定时或实时的提取到数据仓库中。有些历史数据或导出的数据可能存放在某种格式(如xls、csv、json等)的文件中，SuccBI也支持快速连接智能识别并将其导入数据仓库。
[更多SuccBI的数据连接功能介绍>>](../data-connect/README.md)
## 自助数据加工
业务部门在产生数据分析或报表制作的需求时，因数据处理的门槛高，非技术人员难以掌握，所以往往首先需要由业务人员向IT部门提出数据提取的需求，当IT人员将数据准备好后，再由业务人员使用。这种配合方式，不仅会让业务部门对数据的应用过度依赖于IT部门，而且当数据情况复杂时，双方的沟通成本非常高，数据的价值难以被充分利用。\
基于这样的场景，SuccBI提供了自助式数据加工，其支持图形化拖拉拽的操作方式，用户无需DBA及SQL技能，即可使用数据加工来进行数据处理。降低了处理数据的门槛，业务人员也能轻松的完成数据加工，摆脱对IT部门的依赖，充分发掘出数据蕴含的价值。\
[更多SuccBI的数据加工功能介绍>>](../data-process/README.md)
## 轻松管理企业数据仓库
SuccBI将数据仓库的数据连接、加工、模型、调度、聚集、优化、元数据等融为有机的整体，由系统集中管控，提供给用户简单易懂的操作界面和查看管理视图。
1. 系统通过元数据管理的方式，提供给用户所有界面，用户只用操作逻辑层部分，屏蔽了物理层的技术实现，让用户更加易懂。
2. 集中管控数据权限，可以将数据只授权给需要查看和使用的人员，让数据的使用更加安全。
3. 提供数据资产管理视图，让用户轻松管理企业的主数据、数据元及数据标准
4. 用业务语言描述数据，让用户轻松浏览和查询数据
5. 无需人工介入，SuccBI支持智能并发调度，自动识别模型的依赖关系
## 数据管理功能列表
可以点击如下链接了解具体的功能操作：
!!!children (guide/data-gov) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/data-gov/GLOSSARY.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/glossary"
title: "数据管理相关概念和术语"
---
---
order: 1
navTitle: 术语解释
---
# 数据管理相关概念和术语
\[\[toc]]
## 数据源{#data-source}
数据源（data source）是数据的来源，指的是SuccBI中所使用的数据库或者数据库服务器连接。数据源中存储了所有建立数据库连接的信息，数据源管理即对这些数据库连接进行管理。
## 数据模型{#data-model}
数据模型（data model）也叫模型（model）、模型表（model table），一张模型表可以是一张[数据表](#data-table)，可以是一个SQL，也可以是一个数据加工。当讨论到数据建模、[星型模型](#star-schema)等数据仓库建设和规划的概念时，我们会统称为模型。
## 数据表{#data-table}
数据表（data table）也叫数据库表模型，是指在SuccBI中已经管理好元数据的、可以直接为数据分析和查询使用的“表”，数据表是一个逻辑层的概念，一个数据表总是对应一个物理数据库中的物理表或者视图，或者直接连接业务数据库中的物理表。
## 数据集{#data-set}
数据集（data set）是[数据模型](#data-model)的一种，是在数据表、数据加工或者SQL的基础上过滤、排序、选择字段后形成的子集，是一个接近业务化的数据集合。
## 数据库表{#database-table}
数据库表（database table）是指数据库中的物理表。
## 事实表{#fact-table}
事实表（fact table）是由[度量](#measure量)和[维度](#dimension-key)构成的一个[数据表](#data-table)。一个事实表通常会存储一些列随时间变化的数据，如销量表、库存变化表、订单表等，事实表内存在多个[维度](#dimension-key)，维键会关联[维表](#dimension-table)形成[星型模型](#star-schema)
了解更多：
## 维表{#dimension-table}
维表（dimension table）即我们通常说的“代码表”、“字典表”，与[事实表](#fact-table)典型区别是，维表通常不存储随时间变化的业务数据，维表通常存储的是一个业务单元的文本数据，如“产品维表”存储的是产品的ID、名称、颜色、尺码等。
了解更多：
## 字段{#filed}
一个数据表/数据库表的一列。
## 度量{#measure}
度量（measure）是事实表中的用于表示数值的字段，度量的数据往往是连续的，并带有单位（如元、户数、吨等），度量往往可以进行汇总或求平均值。
## 维度{#dimension-key}
维度（dimension key）也叫维键，是事实表中的用于表示数据属性的字段，维键通常会关联外部的一个[维表](#dimension-table)，比如“行政区划”维键会关联“行政区划维表”，有些维键也可能没有关联维表，比如订单号、年份。
## 数据角色{#data-role}
数据角色表示一个[字段](#filed)的“技术类型”，比如日期、经度维度、行政区划……。更多关于数据角色的介绍可以查看文档[字段角色](./model/field-role.md)。
## 数据元{#data-element}
数据元（data element）是元数据管理中的一个概念，通过数据元定义、数据元标识、数据元表示以及数据元允许值等一系列属性描述的数据单元。在特定的语义环境中被认为是不可再分的最小数据单元。
相比于[数据角色](#data-role)，数据元是有具体的业务意义的，比如“发货地址”和“收获地址”属于同一个数据角色，但是却不是同一个数据元，一个[字段](#filed)可以关联一个数据元。
了解更多：
## 星型模型{#star-schema}
星型模型（star schema）是多维的数据关系，它由多个事实表（fact table）和维表（dimension table）组成，一个事实表及其相关联的维表在模型关联关系图上看起来像一个星星（一个事实表周围围着几个维表）所以形象的称之为“星型模型”。星形模型可以认为是[雪花模型](#snowflake-model)的一种特例，比雪花模型在查询方面更有效率。
了解更多：
## 雪花模型{#snowflake-model}
雪花模型是在[星型模型](#star-schema)的基础上，维表又关联有其它的维表，在模型关联关系图上看起来像一个雪花，所以形象的称之为“雪花模型”。星形模型可以认为是[雪花模型](#snowflake-model)的一种特例，但比雪花模型在查询方面更有效率。
了解更多：
---
url: "https://docs.succapp.com/v5/guide/data-gov/import-table.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/import-table"
title: "导入数据库模型"
---
---
order: 2
navTitle: 敏捷建模
---
# 导入数据库模型
在SuccBI中数据库物理表不能直接被系统的可视化分析、表单、应用等模块使用，它必须先转换为逻辑模型(如数据加工、APP模型)后再进行应用。相比物理表，逻辑模型能更好的、统一的管理模型的信息，比如可以给模型和字段设置业务化的名称、管理模型的关联关系、管理模型的聚集、子集、索引性能优化信息等。
数据模块中提供了导入数据库表模型的功能，可以便捷、灵活的将存储在外部数据库中的物理表导入为逻辑模型，并进行加工或查询分析。
## 操作步骤{#steps}
示例地址：[导入数据库模型](https://demo.succbi.com/v5/DEMO/data?:open=S47AQMDcqhBS9lyYPzMDEF)
1. 新建：在项目的数据模块中，点击**新建** > **数据库表模型**
2. 选择表：在选择表对话框中选择需要导入的表，可以结合`Ctrl`或`Shift`快捷键多选
3. 模型名称：设置导入后生成模型的名称
4. 模型描述：设置导入后生成模型的名称
5. 提取目标表名：导入的数据加工模型的目标数据库表名，仅在[提取数据](#extract-data)连接模式下可见并可修改，默认在**数据库表/视图**的基础上增加前缀`ods_`
6. 导入目录：下拉目录树中选择导入模型的资源存储路径，默认为项目的根目录，如果导入时已经在模型资源导航树上选中了目录，则默认为选中的目录
7. 连接方式：连接方式分为**实时连接(只读数据)**、**实时连接(读写模式)**、**提取数据**，选择**提取数据**，具体详见[实时连接与提取数据](#connect-method)
8. 定时调度：仅在连接方式为**提取数据**时可以设置，为导入的数据加工模型直接指定一个已存在的[调度计划](../schedule/README.md)，用来定时更新模型数据。
9. 提取数据：数据库表导入为模型后，在弹出的提取数据对话框中点击**确定**，可立即提取模型表的数据
### 数据表导入模型{#data-table-import}
除了通过新建数据库表模型的方式导入外，还可以在项目的数据源中选择物理表后在右键菜单中选择**导入为模型**来导入。
::: tip 提示
数据库物理表导入为模型使用后，如果后续物理表发生了变化，可以通过[物理模型与逻辑模型差异同步](./model/README.md#sync-table)按钮进行同步
:::
## 实时连接与提取数据{#connect-method}
### 实时连接{#connect-realtime}
当需要基于来源表进行实时的数据查询分析或需要更新来源表的结构或数据时，选择实时连接方式，具体又分为**实时连接(只读模式)**与**实时连接(读写模式)**。
#### 实时连接(只读模式){#read-only}
实时连接(只读模式)主要用于实时的数据分析，导入后的模型是只读的[APP模型](./model/model-data-type.md#app)，不能修改表的结构和数据。
::: tip 提示
以实时连接(只读模式)方式导入后，在模型的基本属性栏中，去掉[只读数据](./model/model-settings.md#read-only)的勾选，可转换为[实时连接(读写模式)](#read-write)。
:::
#### 实时连接(读写模式){#read-write}
实时连接(读写模式)主要用于需要在应用中更新来源表的数据或结构的场景，导入后的模型是可读可写的[APP模型](./model/model-data-type.md#app)。
::: tip 提示
1. 以实时连接(读写模式)方式导入后，在模型的基本属性栏，勾选[只读数据](./model/model-settings.md#read-only)，可转换为[实时连接(只读模式)](#read-only)。
2. 当来源表数据源与[项目的默认数据库]()相同时，默认为该连接方式
:::
### 提取数据{#extract-data}
**提取数据**模式通常用于将上游数据库的表归集到数据仓库中，导入后的模型是[数据加工模型](./model/model-data-type.md#dataflow)。
::: tip 提示
当来源表数据源与[项目的默认数据库]()不相同时，默认为该连接方式
:::
---
url: "https://docs.succapp.com/v5/guide/data-gov/sql-model.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/sql-model"
title: "SQL查询"
---
---
order: 4
---
# SQL查询
SQL查询可以执行SQL语句，语法和数据库语法一致。当需要自定义SQL查询数据，或者已有加工模型的SQL逻辑需要进行执行验证时，可以不用转换成加工而直接使用SQL查询实现。
\[\[toc]]
## 新建SQL查询{#new-sql}
点击顶部导航栏的**数据**，左上角点击**新建**>**SQL查询**，即可打开SQL查询界面。其中默认查询的数据源是**项目设置**>**数据**中设置的**默认数据库**（参考文档：[项目数据管理设置](../devops/project-manage/data-mgr-setting.md/#default))。
除此之外，系统支持以下2种不同的新建SQL查询入口：
1. 使用连接的数据源进行SQL查询
2. 在数据加工过程中进行SQL查询
### 使用连接的数据源进行SQL查询{#datasources-sql}
1. 当用户有数据源的查看权限时，可以直接选中数据源来查询该数据源下所有的物理表数据。点击切换到**数据源列表**，选择对应的数据源，右键菜单中选择**新建SQL查询**，默认查询的数据源为选择的列表中的数据源。
2. 也可以选中物理表进行快速查询。在数据源列表下方的物理表列表中，选择一张物理表，右键菜单中选择**新建查询**，默认查询的数据源是选择的物理表所在的数据源，同时，SQL编辑区域中会自动带上查询语句。
### 在数据加工过程中进行SQL查询{#data-process-sql}
在制作数据加工过程中，或者已有的数据加工模型中的某个组件，想要通过SQL查询去验证数据是否正确时，可以切换到**SQL面板**，然后点击工具栏中的**SQL查询**，会切换到SQL查询的标签页，并且组件的SQL语句会自动复制到SQL查询标签页的编辑区域。
::: tip 提示
新建的SQL查询不会自动查询数据，只有点击**执行**按钮后才会进行查询。若SQL查询并未保存，查询出的数据无法进行任何操作；保存为SQL模型后，可以右键点击字段进行重命名、字段类型转换或设置主键等操作，但无法对字段进行排序和拖拽移动。
:::
## 保存模型{#save-model}
点击保存按钮，即可将SQL查询保存为数据模型，操作和数据加工输出模型操作一致，可以参考文档：[输出加工结果](../data-process/data-output/README.md)。保存后的模型可以进行模型管理，可以参考文档：[模型管理](./model/README.md)。
## 界面操作介绍{#operate}
新建的SQL查询页签上方提供了SQL查询中需要用到的按钮，来实现SQL执行、中止等功能。
- 格式化：将输入的SQL语句按照标准的格式显示。
- 执行：支持**部分语句执行**和**全部语句执行**两种执行方式。
- 部分语句执行：鼠标选中需要执行的部分语句，点击**执行**按钮。
- 全部语句执行：直接点击**执行**按钮，或者全选所有语句，再点击**执行**按钮。
- 中止：在SQL语句执行过程中，查询耗时较长时，可以点击**中止**按钮，停止执行；如果有update、insert或者delete语句时，中止后，数据会回滚，与数据库操作一致。
- 切换数据源：当需要查询的物理表路径与页签左上角面包屑路径不一致时，可以通过点击页签左上角的面包屑来切换对应的数据源和数据库在查询的表名前面加上数据源名称前缀。
:::tip 提示
新建的SQL查询，查询物理表所在的数据源只有与页签左上角的面包屑路径一致时，才能查询出数据，否则会提示查询的物理表不存在。
:::
### 将查询结果复制到目标数据库表中{#copy-data-to}
将SQL查询保存为数据模型后，会在SQL查询页签上方增加**复制到**按钮，点击**复制到**按钮可以将查询到的数据复制到数据库表中，复制分为以下两种情况：
1. 目标数据表不存在，直接创建新的数据库表。
2. 目标数据表已存在，则会提示表已存在并需要进行冲突处理，可以在对话框中修改数据库表名；也可以在**处理方式**中选择**创建新表**、**覆盖同名表**、**清空同名表数据并插入数据**或**追加数据到同名表**四种处理方式进行处理。
- **创建新表**：查询到的数据将重新创建一张新表，名称自动重命名为同名表，并在重命名的表尾部加入后缀1，默认为该选项。
- **覆盖同名表**：删除已存在的表，然后重新新建一张数据库表。
- **清空同名表数据并插入数据**：清空已存在的表数据，再重新写入查询到的表数据，如果查询的数据库表字段比目标表多或名称不符，则会出现错误提示。
- **追加数据到同名表**：直接在数据库表中追加查询到的数据，如果查询的数据库表字段比目标表多或者名称不符，则会出现错误提示。
### 执行危险SQL{#dangerous-sql}
在SQL查询时有时候也会执行`update`、`delete`、`drop`等修改数据或表结构的危险SQL，一旦执行错误，可能会导致业务应用报错或者数据丢失。因此在执行下列危险SQL前会弹出警告对话框进行提示确认，确认无误后才会执行操作。
1. 执行`update`和`delete`命令时没带where条件。
2. 使用`truncate`命令删除表数据。
3. 使用`drop`命令删除数据库表。
4. 对数据库表进行重命名。
5. 修改数据库表结构，如增加、删除、修改字段属性等。
## SQL查询中使用参数{#sql-parameter}
SQL查询除了基本的查询语句，还支持传递动态参数，如接收来自仪表板或者报表中定义的参数，用于sql查询的输入参数。在SQL语句中，用`${参数名}`来引用定义好的参数（定义动态参数可参考文档：[设置动态加工参数](../data-process/setting-params.md)）。
## SQL查询和数据加工中SQL组件的区别{#difference}
1. sql查询通常是一个select语句，用于查询数据，查询的结果可以保存为数据模型。如果sql中包含insert，update，createtable等语句时，系统会提示不能保存，只能作为一个临时查询操作。
2. 数据加工的SQL组件，一般作为加工的输入表组件，是加工的一部分，可能有insert、update、createtable等语句。
---
url: "https://docs.succapp.com/v5/guide/data-gov/input-model-data.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/input-model-data"
title: "录入数据"
---
---
order: 5
---
# 录入数据
除了从数据库中导入模型外，系统提供了录入数据的功能，常用于维度模型的创建。如添加一个存储学历的数据表。
示例地址：[录入数据](https://demo.succbi.com/v5/DEMO/data?:open=soQvga1HSseil7F5Nw8sQ&:tblview=modelData)
**操作步骤**
1. 新建空白模型：在数据页面，点击**新建**按钮，下拉菜单中选择**空白模型**，新建的空白模型默认有5个维度，且数据空白
2. 修改字段名称：鼠标左键双击字段列表的列头，进入编辑字段名称的状态，输入新的字段名称“代码”、“学历”
3. 删除多余行列：点击页签上面的**删除列**按钮，删除多余的3列
4. 录入数据：数据输入，有以下两种方式：
- 鼠标左键双击单元格，可以进入输入状态，填写数据
- 复制excel或者其他地方的数据，到空白模型选中的单元格中
5. 设置主键：鼠标右键需要设置为主键的字段列头，如“代码”，下拉菜单中选择**设置为主键**
6. 保存模型：点击页签上方的**保存**按钮，即可保存为数据模型
:::tip
1. 新建空白模型，如果有空白的行没有删除，直接保存后，数据模型会自动删除空白的行。
2. 新建空白模型默认有5个维度，当数据表需要有度量时，可以进行维度与度量间的转换，参考文档：[模型管理](./model/README.md)。
:::
## 保存模型{#save-model}
点击保存按钮，即可将空白模型保存为数据模型，操作和数据加工输出模型操作一致，可以参考文档：[输出加工结果](../data-process/data-output/README.md)。保存后的模型可以进行模型管理，可以参考文档：[模型管理](./model/README.md)。
## 修改数据{#modify data}
保存后的空白模型，当需要修改数据时，可以在数据列表页面的左上角，点击**修改数据**按钮，进入数据编辑页面，数据的修改录入与新建空白模型时数据录入的体验一致。
:::tip
空白模型保存后，点击**修改数据**按钮后，页面没有新增列和删除列的按钮，如果需要新增列，可以在字段列表，右键字段名称，菜单选项中选择**新增字段**，即可在数据模型中新增一列。
:::
## 属性介绍{#attribute}
新建空白模型时，可以通过按钮组来增删模型字段和数据。
- 增加行：点击**增加行**，会在数据列表的最后一行增加一行空行
- 删除行：先点击需要删除的单元格，然后点击**删除行**，该行会被删除
- 增加列：点击**增加列**，会在数据列表的最后一列增加一个字段，默认是度量、字符型，字段长度为50，可以切换到**字段列表**中进行修改
- 删除列：先点击需要删除的字段列头或者单元格，然后点击**删除列**，该字段会被删除
- 指定位置增加行列：鼠标右键单元格，菜单中提供了**在左侧插入列**、**在右侧插入列**、**在上方插入行**、**在下方插入行**等选项来实现单元格指定位置的增加行列需求
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/model"
title: "模型管理"
---
---
order: 6
navTitle: 模型管理
indexTitle: 模型字段管理
---
# 模型管理
使用数据加工生成的模型或导入已有的模型，在模型管理中可以设置模型属性和模型字段属性等内容。在**数据**模块的**模型**列表下，可查看当前项目中的数据模型，选中对应模型名称即可在右侧查看模型的相关信息。
在模型输出节点包括数据列表、字段列表、加工中的SQL语句、关联关系、树形结构、性能优化、血统分析、模型属性等，同时每个加工节点也提供了相关的属性设置。
## 模型类型{#type}
按照使用场景提供了多种模型类型，包括新建[空白模型](../input-model-data.md)，[数据加工](../../data-process/create-dataflow.md)模型等，模型分类及使用场景参考文档[模型分类](./model-data-type.md)。
## 查看模型数据{#model-data}
在**数据列表**下可查看模型数据，包括模型中显示的所有字段以及数据内容。选中对应字段名称点击下拉按钮或者**右键**可对字段进行相关操作：
- 重命名：对字段名称进行重命名
- 字段类型：设置或修改字段的字段类型，包括字符型，浮点，整型，日期型，时间类型等
- [字段角色](#字段角色)：当字段的数据为时间、日期、行政区划代码或文件类型时，设置字段角色后可在可视化分析中进行相关的分析
- 显示格式：设置字段中的数据展示的格式，以及在可视化分析中的显示格式，显示格式类型可参考文档[显示格式](../../data-viz/dash/design/data/displayformat.md)
- 转换成维度/度量：当字段为度量且需要转换成维度时，点击转换成维度即可，反之当字段是维度时，点击转换成度量即可转换成度量。
- 隐藏：当模型表字段较多且字段的数据不需要时，可以隐藏字段，当字段隐藏后，可以勾选工具栏上方的**显示隐藏的字段**进行查看。
- 字段标签：用于对字段进行标识，可用于通过标签对字段进行过滤等
- 从主键中移除/设置为主键：当字段需要设置为主键时选择**设置为主键**，或者将主键字段取消
:::tip
- 在每个加工节点都提供了数据列表可以查看数据
- 点击**显示行数**可以查看数据总行数，并进行跳转翻页查看
- 数据量较大时可以通过设置分页栏的**每页行数**进行分页查看，默认为每页100行
:::
## 查看模型字段{#model-field}
在字段列表可以查看和修改模型的字段属性，默认展开的字段属性包括：
- 名称：物理字段名对应的名称（comments），如果数据库中有comments，则为字段的comments。如果没有comments，则与物理字段名一致。一般用于对字段数据的业务描述，支持中文
- 类型：设置或修改字段的字段类型，包括字符型，浮点，整型，日期型，时间类型等
- 原始字段：只有加工后的模型表有此属性，表示该字段对应的输入模型表及字段名称
- 物理字段名：视图或者数据库表中存储的字段名
- 关联表：当字段为维度时，可[设置关联表](#设置关联表)
- 显示格式：设置字段中的数据展示的格式，以及在可视化分析中的显示格式，显示格式类型可参考文档[显示格式](../../data-viz/dash/design/data/displayformat.md)
- 字段长度：设置字段的字段长度
- 小数位数：当字段为浮点型或其他类型时，设置小数位数
- 业务含义：对字段的业务化描述
其他字段属性息可以通过**更多**>**显示字段属性**[查看更多字段属性](#field-properties)
### 搜索字段{#search-field}
在**数据列表**或**字段列表**界面，点击工具栏上的放大镜按钮，可搜索当前模型中的字段，搜索范围为：字段名称，原始字段，物理字段名进行搜索，不区分大小写。选中搜索结果会在列表中定位并高亮显示。
### 切换字段显示模式{#switch-display}
在**数据列表**或**字段列表**页面，点击工具栏上方的三个点按钮，可切换字段显示模式及查看更多字段属性，分为以下几类：
- 显示格式
- 原值：在数据库中数据默认存储的格式，勾选为原值时，无法修改字段的显示格式
- 自动：当设置了显示格式后，数据会显示为设置了显示格式后的数据格式，默认为自动
:::tip
1. 工具栏上的显示格式菜单，不会影响到仪表板或其他页面中的数据展示，属于视图切换。
2. 字段上设置的显示格式，保存后会影响，即在仪表板或其他页面中会按照设置的显示格式展示。
3. 工具栏上的显示格式菜单优于字段设置，即工具栏上设置了显示**原值**，数据面板中一定会显示原值，无视字段设置。工具栏为**自动**，即为按照字段设置显示。
:::
- 字段布局：只有字段列表下可设置字段布局
- 分栏：将字段按照维度和度量进行分栏显示
- 平铺：按照模型里字段的存储顺序列举出模型中的所有字段，平铺时可在字段名称，字段类型，物理字段名上点击列头进行排序
- 查询
- 自动查询数据：选中加工节点后自动刷新数据。
- 预览数据：开启预览数据后，会查询预览数据集中的数据。
- 显示字段属性：即[查看更多字段属性](#field-properties)，通过勾选的方式选择在字段列表下需要显示或者隐藏的字段属性
- 动作
- 缩写物理字段：根据物理字段名的中文首字母缩写，重新生成字段名，设置后会对模型有影响和调整，需要保存和重新提取数据等操作
- 匹配数据元：当字段名称与数据元表（`/sysdata/data/tables/meta/META_ELEMENTS.tbl`）中的数据元字段一致时，点击**匹配数据元**可查询数据元匹配结果，当鼠标停留在数据元上方时，可查看数据元的业务意义描述，以方便用户判断自动匹配结果是否正确。点击下拉可切换数据元名称
### 查看更多字段属性{#field-properties}
在字段列表可查看更多属性字段，并设置字段属性的显示隐藏，**更多**>**显示字段属性**：
- 文字字段：当字段的数据为编码类，可设置对应的文字字段
- 数据元：表示可管理的最小的数据单元，用来描述数据的定义如长度、类型、规范等，数据元信息记录在`/sysdata/data/tables/meta/META_ELEMENTS.tbl`中
- 标签：用于对字段进行标识，可用于通过标签对字段进行过滤等
- 取数公式：从其他模型中取数时的公式或表达式，如`[销售汇总表].[成本价格]=[月销汇总表].[零售价格]`
- 取数条件：结合**取数公式**使用，表示满足一定条件时取数公式才生效。如果没有设置此属性，但是设置了**取数公式**属性，那么将总是按**取数公式**进行取数
- 默认值表达式：字段的默认值，支持表达式。当插入数据时，如果该字段为空，则取默认值写入。如获取当前写入时间`now()`
:::tip
**名称**属性必须显示，不能设置为隐藏
:::
### 设置关联表{#associated-table}
关联表是模型的一个字段属性，通常用于给代码字段设置关联的文字说明信息，如企业ID字段关联企业基本信息表、行业代码字段关联行业代码表、行政区划字段关联行政区划表，被关联的表通常称为[维表](../GLOSSARY.md#维表)，代码字段一般不具可读性，关联维表后系统会自动显示代码对应的文字描述信息。
在**数据模型**的**字段列表**界面，可以设置字段的**关联表**属性。
下拉选项：
- 无：默认
- 自定义：点击后弹出模型选择对话框，可以选择一个模型作为该字段的维表
字段设置关联表后，除了能显示代码字段的文字描述信息外，还能带来如下的好处：
- 字段过滤时下拉框以维表的默认树形结构显示下拉树，方便筛选过滤
- 可通过**维键.维表字段**的方式访问维表的字段
## 管理字段{#filed-management}
### 创建字段{#creat-field}
当模型中已有的字段无法满足用户所需，需要根据已有的字段构造出的新的字段列或者对字段进行修改时，可以创建字段，包括[创建计算字段](../../data-process/transform/calc-field.md)，[创建分段](../../data-process/transform/calc-section-field.md)，[创建分组](../../data-process/transform/calc-group-field.md)。
### 删除字段{#delete-field}
删除字段有3种方式：
1. 单个字段的隐藏：当字段不需要时，可以对字段进行**隐藏**
2. 多字段批量隐藏：对于加工中的加工过程节点，可以选中待加工的模型表，**工具栏**>**选择字段**，选择加工中需要使用的字段，当字段列表较多时，只选择需要的字段可以优化加工中的数据查询时间
- 全选：选中所有字段，取消全选即全都不选，默认为全选
- 反选：选择未选中的的其他字段
3. 单个字段的移除：使用[列加工](../../data-process/transform/column-processing/README.md)组件，对字段进行**移除**
:::tip
1. **隐藏**的字段，可以勾选工具栏上方的**显示隐藏的字段**进行查看，在隐藏的字段上右键可以设置字段**显示**
2. 使用[列加工](../../data-process/transform/column-processing/README.md)**移除**的字段，可在**列加工步骤**中删除该条加工步骤即可恢复字段
3. 移除操作只发生在字段产生的节点，比如，新建的计算字段，在本节点上可以移除，但是在后续节点上就只能隐藏。移除是加工步骤，隐藏是全局的操作。
:::
### 修改字段{#modify-field}
在**数据列表**上选中字段下拉或者右键，及在**字段列表**界面可修改字段信息，如重命名、设置字段类型、字段角色等。
### 查看字段血统分析{#pedigree-analysis}
对于数据加工中的模型，可查看字段的血统分析，血统分析有2种方式：
**字段血统分析**
在字段上下拉或者右键，选择血统分析：
- 全局血统分析：即当前模型表及字段来源于项目数据模型中的哪些表及对应的字段，以及该表加工后用于哪些对象，包括加工对象和分析对象，**全局血统分析**即进入到**血统分析**标签页
- 加工内血统分析：即当前字段来源于加工内的哪些模型以及加工路径，进行血统分析时，会高亮显示对应的模型表及加工路径，点击右上角的**退出血统分析**即可隐藏。
**全局血统分析**
点击工具栏切换到**血统分析**标签页，可切换显示或隐藏血统字段或者显示模式：
提供了3种显示模式：
- 默认：该模型表的来源表及用于的加工对象
- 分析对象：该模型表用于的分析对象，包括报表、仪表板等
- 全部：该模型表的来源表及用于的加工对象和分析对象
### 字段角色{#field-role}
[字段角色](./field-role.md)即数据角色，是对数据概念的业务归类，比如“日期"、"手机号码”，“身份证号”。系统中的字段角色可以分为以下几类：
- 地理角色：用于将地区相关的维度字段的值与一个经纬度值关联，从而在地图上显示对应的位置，因此地图控件的位置字段必须是设置了地理角色的数据字段。地理角色分为中国行政区划与国家地理信息
- 日期角色：日期角色包含日期部分如下：年、年月、日期
- 文件：文件角色分为图片、文档、附件
- 其他：其他类型的数据角色，如HTML、多值等
当需要添加自定义的字段角色时，可参考文档[如何配置数据角色](../faq/howto-custom-data-role.md)。
### 字段存储设置{#field-storage-settings}
在模型的数据列表选中字段并点击右键，在弹出菜单中可选择**字段存储设置**，如下：
示例地址：[企业主要人员-职务](https://demo.succbi.com/v5/DEMO/data?:open=EKvWWzx8DSEpHk1HSZOZOF)
在示例的`企业主要人员表`中，一个员工在企业中可能任职多个职务，可以将多个职务使用逗号隔开存储在该员工的职务字段中，并在字段存储设置中勾选**存储多个**。
字段存储设置仅对字符型字段可用，主要用来设置字段存储多个数据项等存储属性，通常用于[事实表](../GLOSSARY.md#fact-table)中设置了[关联表](#associated-table)的字段存储多个关联表的主键值时使用，比如企业人员表中一个人员担任多个职务，电影信息表中一部电影包含多个主演；也常用在业务应用中上传多个附件到一个字段中存储，比如[提交商品评价](https://demo.succbi.com/v5/demo-spg/%E9%99%84%E4%BB%B6)中一次评价提交多个截图。
字段存储设置对话框中可设置如下属性：
- 存储多个：默认不勾选，勾选后可设置分隔符。
- 分隔符：默认为逗号`,`。
::: tip 提示
当字段设置为[文件角色](./field-role.md#file)时可以设置更多的存储属性，详细介绍请参考[文件角色](./field-role.md#file)。
:::
### 同步物理表结构{#sync-table}
**逻辑模型与物理模型结构不一致**
当模型结构（包括空白模型与数据加工模型）与输出的物理表结构不一致时，刷新按钮上会有红色感叹号标记，点击刷新按钮可查看模型表与物理表的差异，并勾选需要修改的差异信息同步物理表结构。
处理方式：
- 将勾选的差异同步到数据库表：将勾选的差异信息同步到物理表里，即按照模型表的设置
- 将勾选的差异同步到模型表：将勾选的差异信息同步到模型表里，即按照数据库表的设置
**输入节点与来源表结构不一致**
当数据加工的输入节点的模型表发生字段修改时，系统可以侦测到源头表的结构变化，在输入表上会显示一个黄色M标记，可点击刷新查看字段差异并更新字段结构：
处理方式：
- 将差异信息同步到输入节点：即同步来源表的物理表结构并更新数据，在后续加工节点中也会同步修改
- 不同步：即不同步修改
## 模型属性设置{#properties}
在模型属性节点可设置模型属性，如主键，数据期类型，提取数据，目标物理表等，可参考文档[模型属性](./model-settings.md)。
## 模型关联关系管理{#model-relations}
在**关联关系**标签页下，可查看当前模型表与其他模型的关联关系，当鼠标方式对应模型名称上，可查看模型的信息，包括模型路径与描述，可参考文档[关联关系设置](./model-relations.md)。
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/model-data-type.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/model-data-type"
title: "模型分类"
---
---
order: 2
---
# 模型分类
## ODS模型{#ods}
直接连接第三方数据库，可能提取也可能没提取。
操作型数据存储(Operational Data Store)，人们对数据的处理行为可以划分为操作型数据处理和分析型数据处理，操作型数据处理一般放在传统的数据库(Database,DB)中进行，分析型数据处理则需要在数据仓库(Data Warehouse,DW)中进行。
使用场景：
1. 实时查询业务库数据。
2. 提取业务库数据到分析仓库。
## APP模型{#app}
报表填报应用、流程应用所使用的模型，这类模型的数据和结构是我们系统或我们系统的用户维护的。
使用场景：
1. 用户在系统内创建的事实表、维表。
2. 报表填报应用、流程应用产生的模型
## 数据加工模型{#dataflow}
一个流程加工的结果作为一个模型，可能提取也可能没提取。
使用场景：
1. ETL建模。
2. 数据探查分析。
## SQL查询模型{#sql}
一个SQL的输出结果作为一个模型，可能提取也可能没提取。
使用场景：
1. 自定义SQL查询。
## 关联查询模型{#relation-query}
多个模型表关联的结果作为一个模型，可能提取也可能没提取。
使用场景：
1. 方便对数据做查询，可以对数据做分组、过滤、排序，并且可以基于关联查询再次做查询和分析。侧重于数据的展示，而不像dashboard同时兼顾数据和展示效果。
## 数据子集模型{#dataset}
基于数据模型表和数据加工表，进行过滤、排序、选择字段后的子集。
使用场景：
1. 子集是一个更接近具体的业务的数据集合，子集将对数据的过滤和筛选等操作抽象到了一个对象上，避免了superage中大量的组建都要实现数据取数的麻烦。
## 指标库定义模型{#dim-indicator}
用于定义指标库，即指标编码、指标口径等指标的元数据，技术上类似一个维表。
## 指标库存储模型{#indicator}
用于定义指标存储，用于分期分单位存储指标定义库中定义的若干指标，技术上类似一个事实表。
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/data-hierarchy.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/data-hierarchy"
title: "数据级次"
---
---
order: 3
navTitle: 数据级次
---
# 数据级次
通常模型中的数据都是单级的，没有层次结构，当我们需要新建一个带有上下级关系的数据模型时，如`行政区划`，就需要用到数据级次属性。
数据级次又称数据层次，代表的数据之间的层次关系，如分段层次、父子层次等。建立一个规范的数据层次，便于快速完成带有上下级关系的数据分析需求，可运用于钻取、汇总等场景，如：在分省销售报表中从省级钻取到市级、汇总显示车企的整体销量。
## 支持的层次类型{#properties}
为适应不同的字典数据，[数据模型](./README.md)提供了三种层次类型：分段层次、父子层次、多字段层次，它们分别有相应的数据要求。
### 分段层次{#sections}
分段层次按照规整的、非空的唯一编码来确定分段的层次关系，编码字段通常为[模型主键](./model-settings.md#主键)。
以`2-2-2`的分段模型为例进行说明，该字段长度是6位，规则如下：
- 前2个字符是第一级编码，中间2个字符是第二级编码，最后2个字符是第三级编码
- 对应分段内的编码为0，则代表该节点为上一级节点，例如`110000`表示该值为根节点
以`行政区划`分段层次为例，该模型按照业务层次`省-市-区`分为3级：
- `北京市 110000`：按照`2-2-2`的分段模式分解为`11`、`00`、`00`，该编码前一段有值而后两段为`00`，则为第一级机构
- `北京市市辖区 110100`：按照`2-2-2`的分段模式分解为`11`、`01`、`00`，该编码前两段有值而后一段为`00`，则为第二级机构，挂在第一段编码为`11`的第一级机构下，故`北京市市辖区`挂在`北京市`下
- 同理，`东城区 110101`挂在`北京市市辖区`下
示例：[分段层次](https://demo.succbi.com/v5/DEMO/data?:open=aAsBvjxgEUGGwZi76f3IyF&:tblview=modelDataTree)
### 父子层次{#paternity}
父子层次按照模型中的父子映射逻辑来确定层次关系，它的数据要求是：
- 子字段必须保证非空且唯一，一般为[模型主键](./model-settings.md#主键)
- 除第一级的子字段外，都需要有对应的父字段值
- 需设置[主键](./model-settings.md#主键)，用于与业务模型的字段关联，[主键](./model-settings.md#主键)与子字段可以为不同字段
以`行政区划`父子层次为例，该模型按照业务层次`省-市-区`分为3级：
- `北京市市辖区`的子字段`行政区划代码`为`110100`，父字段`PID`为`110000`，系统会自动根据父字段的值来查找符合的子字段，子字段为`110000`的机构为`北京市`，故`北京市市辖区`会挂在`北京市`下
- 同理父字段为`110100`的机构，会挂在`北京市市辖区`下
示例：[父子层次](https://demo.succbi.com/v5/DEMO/data?:open=JNim5L6UWlBLivKoX0LagC&:tblview=modelDataTree)
### 多字段层次{#multifields}
多字段层次是按照模型中不同的字段来确定层次关系，它的数据要求是：
- 下级节点的数据行中需要包含上级节点的层次字段信息
- 需设置[主键](./model-settings.md#主键)，用于与业务模型的字段关联，[主键](./model-settings.md#主键)与层次字段没有必然联系
因此它的数据特点为：下级节点的上级层次字段信息是冗余的。
以`行业代码`多字段层次为例，该模型按照业务层次`门类代码-大类代码-中类代码-小类代码`分为4级：
- `农、林、牧、渔业`数据行中包含门类代码信息，其他类的信息为空，故`农、林、牧、渔业`为第一级
- `农业`数据行中包含门类代码、大类代码信息，其他类的信息为空，故`农业`为第二级，挂在对应的门类下，即`农、林、牧、渔业`下
- 同理，`谷物种植`挂在`农业`下
示例：[多字段层次](https://demo.succbi.com/v5/DEMO/data?:open=F40qCBDDh2BxoiVE6mehdC&:tblview=modelDataTree)
## 新建层次{#new-level}
选中[数据模型](./README.md)或[数据加工](../../data-process/README.md)输出节点，在右上角的属性中选择**树形结构**，在工具栏中点击**新建层次**（如果已有建好的层次，在**更多**按钮中，进行数据层次的新建、编辑、删除操作），即可在对话框中选择三种[层次类型](#properties)。一个数据模型可新建多个数据层次，但父子层次只能创建一个，且支持创建后的模糊查询操作。
### 新建分段层次{#new-sections}
新建分段层次，主要进行以下三个设置：
- **分段字段**：模型会依据该字段生成树形结构的数据
- **分段**：将分段字段的数据按照分段结构进行拆分，每段之间使用`-`分隔。例如`2-2-2`表示前2个字符是第一级，中间2个字符是第二级，最后2个字符是第三级
- **分段描述**：分段结构的每段描述，需要以`-`分隔，如`省-市-区`
### 新建父子层次{#new-paternity}
新建父子层次在选择对应的**父字段**及**子字段**后，还需要生成一些必要的业务字段，具体如下：
- **更新层次数据**：默认勾选，与**业务层次**选项的**自动新建层次字段**配合使用，一般用于从零生成一个父子层次，当业务层次字段来源于数据表已有的字段时不勾选
- **业务层次**：记录节点的层次信息，与模型的层级数一一对应，如业务层次为`省-市-区`时，则会记录该节点的所在省、所在市、所在区的信息。业务层次可选择已有的字段，也可以自定义或自动生成新的层次字段
- **自动新建层次字段**：点击可自动分析父子字段的值并生成层次数据，如业务层次为`省-市-区`三级时，默认的字段名按顺序分别为：`SZ_PID0`、`SZ_PID1`、`SZ_PID2`且不会发生改变，如果模型中已有该字段名则会自动引用
- **层级字段**：记录节点在树形层次中处于第几层级，根节点从`0`开始。层级字段可自定义，默认为`SZ_LEVEL`，如果模型中已有该字段名则默认为`SZ_LEVEL1`。当模型数据中已有该信息的记录时，也可选择已有的字段
- **是否叶子节点**：记录节点在树形层次中是否为叶子节点，`0`代表否，`1`代表是。层级字段可自定义，默认为`SZ_LEAF`，操作及生成规则与**层级字段**相同
- **子代码包含父代码**：在涉及到与父子层次相关的数据查询时使用，可以提升查询性能，前提条件是子字段的前缀带有父字段的代码
### 新建多字段层次{#new-multifields}
新建多字段层次只需点击**添加**按钮并选择层次字段，即可新增相应的**业务层次**，系统会自动按照添加的顺序依次分为第一层级、第二层级...
## 编辑和删除层次{#editlevel}
针对已创建的层次，系统提供了**编辑**及**删除**的功能:
- **编辑**：点击模型工具栏中的**更多**按钮，可进行层次编辑操作，操作与[新建层次](#new-level)一致
- **删除**：删除当前选择的层次，点击后会弹出确认对话框，通过弹出框中**详细信息**可查看引用该层次的元数据
## 应用{#scenarios}
在完成模型的数据层次构建后，可便捷应用于多种开发场景：
- **关联维表**：字段关联了带有数据层次的模型时，可直接引用业务层次字段进行数据分析
- **汇总与下钻**：在制作[报表](../../report/README.md)或[仪表板](../../data-viz/dash/README.md)的表格时，拖入数据层次字段至单元格中，系统会自动汇总下级数据，还可以为单元格添加[下钻](../../data-viz/dash/design/action/drill-down.md)交互
- **组件关联**：使用[下拉框组件](../../app/superpage/components/input/combobox.md)、树组件关联带有数据层次的模型，可直接生成树形结构
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/model-settings.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/model-settings"
title: "模型属性"
---
---
order: 6
---
# 模型属性
模型设置中可以设置模型的主键、数据期、提取设置、查询设置等，主要分为**基本**、**提取**、**特殊字段**、**查询**、**缓存**、**高级**几个方面的属性设置。
## 基本{#basic}
### 主键{#primaryKeys}
主键由一个或多个字段组成，用来唯一标识一行数据，也常用于模型之间的关联，通常每个模型必须设置主键。同时系统可依据模型主键的设置自动识别[数据集类型](../../data-viz/dash/design/datasource.md#dataset-type)。
当模型具有目标数据库表的写权限或修改表结构权限时，设置的主键会在数据库物理表中创建主键约束，否则，主键只作为模型的逻辑属性。
通常，手动创建的空白模型或数据加工模型在保存时默认都会在数据库物理表上自动创建主键约束，而从外部第三方数据库导入的模型默认是直接读取物理表中的主键信息。
::: tip 提示
1. 对于[数据加工模型](./model-data-type.md#dataflow)，只有[允许修改表结构](#restrictAlterDbTable)中勾选**约束**时系统才能自动将模型上的主键设置同步到数据库物理表中。
2. 出于数据库性能的考虑，主键字段个数越少越好，主键字段的长度越短越好。通常为[APP模型](./model-data-type.md#app)创建的主键字段可设置为整型的自**增长字段**或者使用[SEQNUM函数](../../exp/func/string/SEQNUM.md)生成唯一的序列号。
:::
### 业务键{#businessKeys}
由一个或多个具有实际业务意义的属性组成，和主键一样，可以唯一标识一行数据。主键对应数据库物理表中的主键约束，通常是一个技术性ID，采用MD5、序列号等生成，比如员工ID，而业务键是具有实际业务含义的字段，比如员工工号或员工身份证号。
[工作流](../../app/workflow/README.md)中只能使用一个字段进行业务表之间的关联，当模型主键有多个字段时，此时需要设置一个业务键。
### 指标代号{#indicatorCodes}
如果一个模型存储的是行表指标数据，那么主键其实是由三个部分组成的：数据期字段、指标所属实体编码和指标的代号字段，数据期字段可能是一个字段也可能是缓慢变化起止字段，指标所属实体编码字段通常代表比如人、单位、产品等，指标代号字段通常只有一个字段，但也可以是多个，例如医院的科室、产品的尺码等。
指标代号目前仅用于表单[批量校验](../../ci/design-fapp/validate.md#batch-valid)的场景，系统根据指标代码进行行间校验公式的计算。其他场景下不需要设置指标代号。
### 数据期类型{#periodType}
数据期类型用来表示模型的分类，可以帮助系统更准确的判断模型的使用方式和应用场景，系统也能根据模型类型自动进行一些逻辑处理，比如可以自动根据**固定周期**模型的数据期字段进行**同比**、**环比**的计算。
1. **固定周期**
数据按固定的时间周期，一期一份，比如月度数据，一个单位一月有一行数据，通常用于存储数仓的事实表数据或低代码填报中的周期填报数据。选择该类型后，需要在[数据期字段](#periodField)中指定存储数据周期的字段，如按照**年月**汇总的[门店月销汇总表](https://demo.succbi.com/v5/DEMO/data?:open=fcby8R17NfCga3tclsn2lB&:viewer=settings)
2. **缓慢变化**
每条数据用起和止两个字段标识数据的有效性，通常用于那些需要记录修改历史的维表数据，比如员工花名册，每个员工从入职开始时所有的历史时刻的数据都会有记录，直到离职。
缓慢变化类型需要先在模型中定义**起止时间字段**来标记数据的发生时间区间，并需要将**起止时间字段**分别设置为[缓慢变化起](#periodFieldStart)和[缓慢变化止](#periodFieldEnd)，如记录企业变化信息的[企业基本信息缓慢变化表](https://demo.succbi.com/v5/DEMO/data?:open=O20vb6tsc4BF2i7PKKZFPB&:tblview=modelData)
3. **实时记录**
每条数据通常都有创建时间字段，通常用于记录交易型的、日志型的数据，如订单表。选择该类型后，需要在[创建时间](#createTimeField)指定数据的创建时间字段。
4. **无**
默认值，其他不明确的类型都可以设置为无，通常是维表、加工中的临时表等
### 数据期字段{#periodField}
[数据期类型](#periodType)选择为**固定周期**时必填，指定周期快照表中存储周期粒度的字段，通常是日期或时间戳类型的字段，也可以是设置为[日期角色](./field-role.md#date)的字段。
### 缓慢变化起{#periodFieldStart}
[数据期类型](#periodType)选择为**缓慢变化**时必填，指定**缓慢变化**中数据的起始时间的字段，通常是日期或时间戳类型的字段，也可以是设置为[日期角色](./field-role.md#date)的字段。
### 缓慢变化止{#periodFieldEnd}
[数据期类型](#periodType)选择为**缓慢变化**时必填，指定**缓慢变化**中数据的截止时间的字段，通常是日期或时间戳类型的字段，也可以是设置为[日期角色](./field-role.md#date)的字段。
### 记录变化{#slowChangeMethod}
[数据期类型](#periodType)选择为**缓慢变化**时必填，记录变化用来设置哪些字段将被纳入缓慢变化中，只有纳入缓慢变化中的字段发生了修改，才会被认定数据发生缓慢变化。
::: tip 提示
对于[业务应用](../../app/overview.md#what-is-lowcode)使用的**缓慢变化**类型的[APP模型](./model-data-type.md#app)，如果没有设置为记录变化的字段发生了修改，会直接修改最新的那条数据。
:::
记录变化可以选择如下方式中选择一种：
1. 所有字段的变化，默认值
2. 指定字段的变化
3. 忽略指定字段的变化
### 只读数据{#dataReadonly}
只读数据用于[APP模型](./model-data-type.md#app)控制SuccBI对数据的使用方式和安全性，通常导入的第三方已存在的数据模型默认设置为只读，而系统内部自建的业务应用类的数据模型默认是读写的。
勾选时，不允许修改数据库物理表的结构及数据。
## 提取{#extract}
仅[数据加工](./model-data-type.md#dataflow)模型有**提取**属性。
### 提取数据{#extractTargetType}
用于设置模型提取数据的方式，有如下选项：
- **不提取(实时查询)**：查询模型时总是基于加工逻辑生成的SQL实时查询数据，适合需要获取实时数据、加工逻辑简单且数据量较小的情况。
- **提取到数据库表**：提取数据并存储到指定的物理表中，查询模型时直接查询提取后的表，通常配合定时调度来定期提取。
- **创建普通视图**：将加工逻辑创建为数据库视图表，查询模型时总是基于视图表进行实时查询，相比于不提取时，可以简化查询SQL。
- **创建物化视图**：将加工逻辑创建为数据库物化视图，拥有与物理表查询相同的性能，同时可以结合物化视图的查询重写特性实现自动查询导航。
- **使用上游节点表**：通常用于目标表已经存在或在前面的节点已经创建，不需要再重新生成一个物理表的情况。详细使用见[使用上游节点表机制](../../data-process/data-output/README.md#use-upstream-table)。
### 目标数据库表{#extractDataToTable}
提取数据时的目标数据库物理表按照如下几种方式确定：
1. 如果不关心模型的物理层信息，可以不用手动指定，在保存模型时，系统将自动生成。
2. 如果需要给目标数据库表指定表名时，可以点击**选择**按钮，并点击对话框中左下角的**创建数据库**按钮输入表名。
3. 如果需要把数据提取到一个已存在的数据库物理表中时，可以点击**选择**按钮，手动选中一个已存在的数据库表。
另外，与[数据加工模型](./model-data-type.md#dataflow)不同的是，[APP模型](./model-data-type.md#app)中该属性是在**基本属性**分类下。
### 存储引擎{#storageEngine}
存储引擎用于创建目标数据库表时指定物理表的存储引擎，未设置时按照数据库默认存储引擎创建。
不同的数据库可使用的存储引擎不同，比如mysql支持的引擎有innodb（支持事务的高并发读写，适用于电商、金融等事务型系统）、myisam（不支持事务，适合以查询为主的场景，比如新闻网站等）等。选择存储引擎时需要根据模型的使用场景结合数据库官方对存储引擎的特性的介绍来进行选择。
### 数据存储方式{#storageType}
数据存储方式用于创建目标数据库表时指定物理表的数据存储组织方式，未设置时按照数据库默认的存储方式创建。
通常有如下三种存储方式：
- **行存储**：表示数据库表的数据按行存储，适合事务为主的场景，比如CRM系统、订单库存管理系统。
- **列存储**：表示数据库表的数据按列存储，适合分析为主的场景，列存储能有效提升统计查询性能，比如BI系统的报表、仪表板查询统计分析。
- **混合存储**：数据表既可以按照行存储，同时也能按照列存储，一般只有少数支持混合存储的数据库支持。
不同的数据库可选择的存储方式不同，取决于数据库的特性。
### 数据分布方式{#distributionMode}
数据分布方式用于支持分布式存储的数据库在创建目标数据库表时指定物理表的数据分布方式，未设置时按照数据库默认的存储方式创建。
数据分布方式通常有如下几种：
- **复制冗余存储**：每个分布方式节点都有标的全量数据，通常适用于维表。
- **随机分布式存储**：表的每行会被轮番发送到不同的节点存储，数据在集群节点中分布均匀。
- **按字段分布式存储**：按指定字段的哈希值分布到不同节点，查询使用性能最好，但是数据分布可能发生倾斜。
### 刷新范围{#mvRefreshMode}
当[提取数据](#extracttargettype)设置为**创建物化视图**时，**刷新范围**用于在创建物化视图表时指定刷新范围，物化视图在刷新时会按照创建时设置的刷新范围进行刷新。未设置时按照数据库默认的刷新范围创建。
不同的数据库可选择的刷新范围不一样，取决于数据库的特性，一般有如下几种刷新范围：
- **默认**：使用数据库默认刷新方式
- **自动**：数据库自动判断是否满足增量刷新要求，满足则增量刷新；否则全量刷新
- **全量**：每次刷新都重新生成物化视图的数据。
- **增量**：只更新自上次刷新以来有变化的数据，需要满足数据库对增量刷新的要求，比如oracle数据库要求创建增量刷新的物化视图前必须对其引用的来源表都先创建物化视图日志表
- **不刷新**：只在创建时进行刷新，并在创建后不允许再次刷新，手动调用刷新也没用。
### 刷新时机{#mvRefreshType}
当[提取数据](#extracttargettype)设置为**创建物化视图**时，**刷新时机**用于在创建物化视图表时指定刷新方式。未设置时按照数据库默认的刷新方式创建。
不同的数据库可选择的刷新时机不一样，取决于数据库的特性，一般有如下几种刷新时机：
- **默认**：使用数据库默认刷新方式。
- **实时刷新**：当基表的数据发生变化，在事务提交时数据库自动执行刷新。实时刷新对数据库的性能会有影响，对于更新频繁、数据量大的表不建议使用实时刷新。
### 查询导航{#mvRewrite}
当[提取数据](#extracttargettype)设置为**创建物化视图**时，**查询导航**用于在创建物化视图表时指定是否启用查询重写。未设置时按照数据库默认的方式创建。
启用查询导航时，数据库会自动使用物化视图替代原始查询进行查询重写以优化性能。
### 允许修改表结构{#restrictAlterDbTable}
用来控制数据加工对[目标数据库表](#extractDataToTable)结构的操作限制，这里的数据库表结构信息指的是**字段**、**索引**、**约束**。
- **字段**：表示数据库表的字段结构信息
- **索引**：表示数据库表的索引信息
- **约束**：表示数据库表的主键信息
通常当数据加工将数据提取到指定的第三方数据库表时，默认不允许SuccBI修改表的结构信息，防止对第三方数据库表结构的误修改。
### 提取方式{#extractMethod}
设置数据加工以哪种方式把数据提取到[目标数据库表](#extractDataToTable)中，系统提供了五种提取方式：
#### 重建表{#extract-mode-recreate}
提取时创建新的数据库表，并通过交换表名的方式替换原表，替换过程中原数据库表会被短暂的删除，所以只适合用于在业务运行时间窗口之外小数据量表的快速全量数据更新。
::: tip 提示
重建表后原来的旧表及数据不会立即删除，会自动保留一段时间。
:::
#### 全量覆盖{#extract-mode-overwriteall}
默认的提取方式，先清空[目标数据库表](#extractDataToTable)的数据，再插入加工结果数据，适合小数据量表的全量更新。
与[重新建](#extract-mode-recreate)不同的是，全量覆盖不会删除表，在有些环境下出于安全的考虑不允许执行删除表操作或者没有删除权限时，可以选择**全量覆盖**替代[重新建](#extract-mode-recreate)来执行全量提取。
另外，全量覆盖方式下可以通过勾选[重建索引和主键](#rebuildIndexAndKey)来提高提取性能。
#### 清空旧数据并插入新数据{#extract-mode-overwriteinc}
根据设置的[清空范围](#incrementRange)先删除目标表中的旧数据，再将当前加工结果数据全部插入，是一种增量提取数据的方式。清空旧数据并插入新数据常用于能按照固定时间周期去增量更新目标表数据的场景，如服饰销售日报表、月报表、年报表的数据提取。
#### 按主键合并追加{#extract-mode-merge}
按主键合并追加指的是将目标表和当前加工结果中主键相同的数据进行合并，再将当前加工结果中有而目标表中没有的数据追加至目标表中。
主要用于如下场景：
1. 当对大表需要进行增量更新，但又没法确定明确的增量范围时，适合使用按主键合并追加进行增量更新。
2. 只想把来源数据中有而目标表中没有的数据追加到目标表。
::: tip 提示
1. 选择**按主键合并追加**后，模型必须要设置主键才能成功保存。
2. 选择**按主键合并追加**时，默认只按主键追加不合并已有数据，可以通过[更新已有数据](#mergeData)和[更新忽略字段列表](#mergeIgnoreFields)两个设置项来设置合并策略。
:::
#### 只追加{#extract-mode-append}
只追加是指不对目标表数据做任何处理，直接将当前加工结果全部插入到目标表中。只追加模式下主键一般是使用[UUID](../../exp/func/string/UUID.md)等函数自动生成。
### 清空范围{#incrementRange}
在[提取方式](#extractMethod)为**清空旧数据并插入新数据**时必须设置一个或多个条件，数据提取时会先按照**清空范围**的条件删除目标数据库表的旧数据再插入新数据。
### 支持回滚{#rollbackEnabled}
默认不勾选，当支持回滚时，数据如果提取失败会恢复到提取前的状态，不支持回滚可以带来更好的提取性能，但在提取过程中目标数据库表的数据可能会被清空或出现抖动，同时如果提取失败则可能丢失数据。
数据仓库系统的模型加工中通常不建议勾选该选项，大数据量下会导致严重的性能问题。必要情况下，仅应用于核心的、小数据量表的数据提取中。
另外，[提取方式](#extractMethod)设置为[重建表](#extract-mode-recreate)时，不支持回滚。
### 重建索引和主键{#rebuildIndexAndKey}
仅用于提取方式为[全量覆盖](#overwrite-all)时，系统通过先删除表中索引和主键，待提取完成后，再创建的方式来提升数据提取的整体性能，默认勾选。
勾选时，系统会自动校验[允许修改表结构](#restrictAlterDbTable)是否勾选了**索引**和**约束**，若没有勾选，属性框下会有异常提示。
在提取方式为[全量覆盖](#overwrite-all)模式下，通常都会勾选，当数据源中没有修改数据库表索引和约束的权限时，则需要去掉勾选才能正常提取数据。
### 更新已有数据{#mergeData}
用于[按主键合并追加](#extract-mode-merge)提取方式下设置合并策略，默认不勾选，当你需要对已存在的旧数据更新时需要勾选。
勾选后，合并更新时会更新除[更新忽略字段列表](#mergeIgnoreFields)选项勾选之外的所有字段。
### 更新忽略字段列表{#mergeIgnoreFields}
提取方式为[按主键合并追加](#extract-mode-merge)且勾选了[更新已有数据](#update-exists-data)时，用来设置需要忽略更新的字段，默认更新全部字段。
通常用于合并更新时保留数据第一次插入到表中的某些字段信息，比如数据推送场景下，通常模型中会使用【插入时间】字段记录数据行的首次入库时间，在之后的增量推送过程中，只会更新数据行的其他业务字段，而不会修改【插入时间】字段。
### 定时调度{#schedule}
用于需要定时更新模型数据的场景，如数据仓库系统中，通常需要在每天晚上定时更新模型中的数据。定时调度可以给数据加工设置一个或多个计划调度，在计划运行时可自动执行数据加工提取，详细请参考[调度管理](../../schedule/README.md)。
### 依赖{#depends}
在[定时调度](#schedule)中指定了计划调度后，可选择一个或多个数据加工作为依赖模型。
通常该选项不需要设置，系统会自动分析依赖关系，只有在如下几种特殊情况下才需要手动设置：
1. 添加到同一计划的数据加工存在循环引用，比如智能调度分析出的数据加工的引用关系为A依赖B、B依赖C、C依赖A，可手动设置A依赖C化解循环引用。
2. 有些使用脚本、SQL等方式的数据加工，系统不能自动识别依赖关系，需要手动设置。
设置后，当[计划](../../schedule/README.md)在执行时，加工将在指定的依赖模型执行完成后才开始提取数据。
## 特殊字段{#specialFields}
### 创建时间{#createTimeField}
指定一个日期型或时间戳类型字段，用来标识数据行的创建时间。
在低代码应用中，表单在提交数据时系统会自动修改该字段的值，不需要表单主动提交这个字段。
### 创建人{#creatorField}
指定一个字段，用来标识数据行的创建人。
在低代码应用中，表单在提交数据时系统会自动修改该字段的值，不需要表单主动提交这个字段。
### 最后修改时间{#lastUpdateTimeField}
指定一个日期型或时间戳类型字段，用来标识数据行的最后修改时间。
在低代码应用中，表单在修改数据时系统会自动修改该字段的值，不需要表单主动提交这个字段。
### 最后修改人{#lastUpdateUserField}
指定一个字段，用来标识数据行的最后修改人。
在低代码应用中，表单在修改数据时系统会自动修改该字段的值，不需要表单主动提交这个字段。
### 删除状态{#deleteFlagField}
指定一个字段，用来标识数据行在业务上是否被删除，如果删除标记为1，否则标记为0。
实际的生产业务中，出于数据安全的考虑，用户删除数据时通常不会直接从物理层上删除，而是修改数据的删除状态为1，系统在查询和分析时也会自动过滤掉已标记为删除的数据。
在低代码应用中，页面在删除数据时系统会自动维护该字段的值，不需要在页面交互逻辑上手动管理删除状态字段的值。
### 序号字段{#indexField}
指定一个字段，用来标识数据行的序号。
在低代码应用中，列表等组件在管理数据时可能会调整数据行的顺序，系统会自动维护该字段的值，不需要组件主动提交这个字段。
### 校验状态{#checkErrorStateField}
指定记录数据校验结果的字段，当数据行满足所有校验规则时为1，否则为0。
常用于在应用中批量导入Excel等数据时记录导入数据的校验结果情况，例如：批量导入[人员采样信息](https://demo.succbi.com/v5/demo-spg/%E6%A8%A1%E5%9E%8B%E6%95%B0%E6%8D%AE%E6%A0%A1%E9%AA%8C)时，可以先将所有数据导入到[人员采样信息-临时表](https://demo.succbi.com/v5/DEMO/data?:open=AUh0ZzdlTDGB59KthlYpmE&:expandIds=aqphlalN1SEgYW8sP8ZKjD&:tblview=modelData)中，在临时表中记录导入数据的校验结果，并选择把校验成功的数据复制到最终的人员采样信息表中。
### 数据行权限过滤{#dataRangeDimFilterMode}
根据当前用户的[数据范围权限](../../permission/grant/datarange.md)，限制用户可以查询到的数据行。
- **自动**：系统自动匹配模型中的数据范围维度权限字段并进行过滤
- **禁用**：不限制数据行范围，允许用户查看所有数据
- **自定义**：当模型中存在多个数据范围维度字段或需要按照数据范围维度的维属性过滤时需要自定义指定权限字段
### 预聚集维度字段{#preAggDimensionFields}
用于标识已经存储了上级汇总数据的维度，便于报表、仪表板等直接查询上级汇总数据而无需从下级汇总统计。
通常情况下，模型事实表中不会存储维度的上级汇总数据，而是在统计查询时按照维度的层次进行汇总查询，以下几种情况可能需要设置`预聚集维度`字段：
- 在集团企业采集填报中，上级机构需要上报数据时会在表中生成汇总数据并上报，这时候需要将`填报单位`作为预聚集维度字段。
- 下级节点多、数据量非常大，实时汇总性能比较差时，可以通过数据加工将数据提前汇总，以便提升查询性能。
## 查询{#query}
### 排序方式{#sortsType}
指定模型查询时的排序方式，有以下几种：
- **自动排序**：通常按主键排序，对于Elasticsearch等检索数据库，按照相关性进行排序
- **按字段排序**：按指定的字段排序方式进行排序
- **按序号字段排序**：若设置了[序号字段](#indexField)则根据序号字段排序
- **不排序**：总是不排序，可提升大数据量表的查询性能
当前端页面中也设置了排序方式时，比如在[数据集中指定排序字段](../dataset.md#sort-fields)、[在仪表板中指定排序](../../data-viz/dash/design/data/data-sort.md)，则此处设置的排序方式将会被覆盖。
### 过滤条件{#dataFilter}
模型表的全局过滤条件，当对模型进行加工或分析查询时，始终会带上该过滤条件进行查询。通常用于直接连接业务库的实时查询分析中，例如大屏实时分析展示电商平台的成交订单情况时，会先导入电商业务库的订单表为模型并设置全局过滤条件过滤出有效订单数据。
### 默认抽样条件{#defSampleCondition}
当数据表数据量比较大时，为了避免在被其他加工引用时，因为一个简单的操作，导致查询速度非常缓慢，可以设置数据表的默认抽样条件。设置后，当模型被其他加工引用时，默认抽样条件会默认被设置为引用节点的[预览数据集](../../data-process/optimization/README.md#debugdatasets)中的**只查询指定条件**。
如销售明细表记录了近20年上亿条数据，在对这个表进行加工时，数据查询速度很慢，可以先在销售明细表的**模型属性** > **默认抽样条件**中设置【销售年份】为`2020`，预览数据时只查询2020年的数据，提升查询速度。
::: tip 过滤条件和默认抽样条件的区别
1. 过滤条件：过滤条件是模型的全局过滤条件，在任何地方查询模型时都会带上该过滤条件
2. 默认抽样条件：默认抽样条件只在模型被其他数据加工引用且打开了[预览数据](../../data-process/optimization/README.md#debugdatasets)时生效，作为预览数据时的默认过滤条件。
:::
## 缓存{#cache}
### 启用查询缓存{#enableQueryCache}
查询缓存用于系统自动缓存数据到内存或临时文件，以提升系统效率。
当多次或并发查询某个相同模型或页面的数据时，如果模型数据没有发生过变化，使用模型缓存可以避免系统向数据库重复发起相同的查询，而是直接从上一次的查询结果缓存文件中加载数据，可以用来提升系统的并发查询性能和吞吐量。
查询缓存适用于数据更新频次低的应用，例如数据仓库模型通常都是按日进行定期更新的，所以数据仓库模型非常适合使用模型缓存；而对于高并发的业务应用，则通常只应该对维表或字典表启用查询缓存，而**频繁更新的业务表则必须禁用模型缓存**！
::: warning 警告
频繁更新的业务表为何要禁用模型缓存？业务表发生数据更新时，为了确保查询时数据的一致性，缓存文件会被标记为过期状态，而频繁更新业务表会导致系统陷入缓存文件过期、重新生成缓存文件、缓存文件再次过期的循环中，严重降低系统运行性能，在高并发下甚至可能导致系统瘫痪。
:::
在系统内部进行的模型数据修改，如重新提取数据、使用表单修改数据，系统能自动侦测并使模型缓存文件过期，但如果使用的是第三方工具如PL/SQL Developer、Navicat等直接修改了表的数据，系统是不能侦测到数据变化的，此时必须在系统设置中清空Query缓存（可参考文档：[缓存管理](../../sys-settings/performance/README.md)）或在此处取消勾选**查询查询**来直接向数据库查询最新的数据，否则会导致查询数据不一致。
### 集群共享缓存{#cacheClusterShare}
启用后数据缓存文件将存储在集群共享文件夹下，各个集群节点可以共享，当集群节点很多时（比如大于10台）启用集群共享缓存可以避免多个集群节点并发同时查询数据库，降低数据库压力。
### 设置缓存有效期{#enableCacheAge}
启用后可以设置缓存的有效时间，在有效期内，即便数据被修改了系统还是可以继续使用之前的缓存，减少数据库查询和网络流量。此选项通常用于海量用户（如千万级别以上）访问一些公共的数据，且用户能接受不立即看到最新数据的场景。
### 缓存有效时长(秒){#cacheMaxAge}
设置缓存从创建时开始，多少秒之后失效，此选项和[缓存失效时间](#cacheExpiredTime)必须设置其中一个。
### 缓存失效时间{#cacheExpiredTime}
指定一个时间点，每天这个时间以后缓存都会失效，此选项和[缓存有效时长](#cacheMaxAge)必须设置其中一个。
### 前端预加载数据{#downloadAllDataMode}
用于控制前端如何获取模型数据，优化数据加载和查询的效率。根据业务需求，用户可以选择不同的加载模式：
- **默认**：未设置时使用默认逻辑，当模型数据量小于等于[前端自动缓存数据阈值](../../sys-settings/security/securityconf.md#cache-size)时，允许下载全量数据到前端。
- **允许全量加载**：在数据量小于等于[前端缓存数据最大行数](../../sys-settings/security/securityconf.md#cache-size)的前提下，允许下载全量数据。
- **按需加载**：只允许下载条件范围内的数据。
常见的使用前端预加载的场景：
1. 前端页面有省、市、县三个下拉框控件，并且之间存在联动和过滤，此时可以设置为**允许全量加载**，一次下拉选项时系统会一次性下载所有省市县数据，避免频繁发起查询请求。
2. 按大区、年份过滤汇总统计各省份的服装销售情况时，以往根据页面的年份下拉框、大区下拉框动态过滤查询汇总数据，此时也可以设置为**允许全量加载**，系统会忽略下拉框动态条件，一次性下载所有到省份的汇总数据，切换下拉框条件时便不会发起新的查询请求，而是在前端内存中汇总计算。
## 高级{#advanced}
### 启用脚本{#scriptType}
数据加工支持使用脚本个性化处理数据查询、数据更新、数据调度等逻辑，下拉框可选择：
1. 不启用：默认值
2. 前端脚本：仅[APP模型](./model-data-type.md#app)才有该选项，运行在客户端
3. 后端脚本：运行在服务端
关于前端脚本和后端脚本的详细介绍参见[脚本开发](../../dev/script/README.md)。
### 指定脚本位置{#assignScriptPath}
在[启用脚本](#scriptType)中选择了前端或后端脚本的一种后，默认系统会自动将脚本存储到约定位置，使用者无需关心，可以**勾选**此选项来给脚本指定一个存储路径。另外，点击按钮**定位到脚本位置**可跳转到对应的脚本资源界面。
### 隐藏流程图{#flowHidden}
仅数据加工有该选项，表示隐藏数据加工流程图，默认不勾选。
### 模型扩展属性{#extend-properties}
除了上述的基本属性外，系统还提供了具备一定的扩展能力的自定义属性，当用户需要按照自己的需求给模型添加其他的属性时，可以设置模型的自定义属性，如添加一个属性**模型业务描述**，以便知道模型的具体业务意义，具体步骤可参考文档：[如何设置模型的自定义属性](../faq/howto-custom-model-property.md)。
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/model-relations.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/model-relations"
title: "关联关系"
---
---
order: 7
---
# 关联关系
关联关系是指在数据模型中各个实体或对象之间的相互联系。例如，在员工信息管理中，员工与部门之间的关系、员工与报销单之间的关系等，都体现了这些实体之间的关联关系。这些关系可以通过不同的[关联关系类型](#relation-types)（如维表关联、主从关联等）来描述，从而帮助我们理解系统模型之间的关系和数据的流动。
## 自动发现关联关系{#auto-discovery}
系统在需要关联关系时，会优先使用模型上显式设置的关联关系，如果没有设置关联关系，系统还会使用[一致性维度](./conformed-dimension.md)来自动发现关联关系。主要用于如下场景：
1. 数据加工中自动推测关联关系
数据加工使用关联节点关联两个模型时，如果没有设置关联关系，系统会自动根据一致性维度来推测关联关系，示例参考：[数据加工关联查询](#df-relation)。
2. 跨表汇总分析查询时自动发现关联关系
模型上设置的关联关系通常主要用于原始明细行的查询，在跨表按维度汇总统计时需要把不同表的汇总结果集关联起来展示，此时系统会根据一致性维度来发现关联关系，示例参考：[跨源分组汇总查询](#cross-group-query)。
## 关联关系类型{#relation-types}
模型上显式设置的关联关系根据关联类型分为三种：
- **事实表间关联**：[事实表](../GLOSSARY.md#fact-table)之间通过关联关系表达式进行关联，通常会使用多个字段并可以设置关联方向
- **维表关联**： 主表中的一个维键字段与[维表](../GLOSSARY.md#dimension-table)的主键对应，类似数据库的外键关联
- **主从关联**：主表主键与从表外键相关联，主要用于主从表提交、级联更新、删除。
示例地址：[关联关系-企业基本信息](https://demo.succbi.com/v5/DEMO/data?:open=UGOACvvHdkCmkIY51oQCyE&:tblview=modelRelations)
## 设置关联关系{#oper-steps}
设置关联关系的操作步骤：
1. **打开关联关系设置对话框：** 从左侧资源树中定位到加工模型，右键并选中关联关系菜单，弹出关联关系对话框。更多入口参考[关联关系管理入口](#mgr-entry)
2. **添加关联关系：** 点击添加，选择一个与主表关联的表，系统会自动识别两个表的关联类型，你也可以手动切换关联类型，并设置具体的关联方式
### 关联关系管理入口{#mgr-entry}
|模型关系面板|元数据右键菜单|全局关联关系|
| ---- | ---- | ---- |
||||
1. **关联关系面板：** 数据管理界面中打开目标模型的编辑器，从中部工具栏切换到关联关系面板，右键当前模型节点，选中**管理关联关系**
2. **元数据树右键菜单：** 数据管理界面中手动展开或通过元数据搜索框定位到目标模型，右键选择**关联关系**
3. **全局关联关系视图：** 数据管理界面中切换到[全局关联关系视图](#global-relations-view)，通过一级级展开目录找到目标模型，右键目标模型的节点，选中**管理关联关系**
## 关联关系设置对话框{#dialog}
关联关系对话框用于管理当前模型（下图“企业基本模型”）与其他模型的关联关系。
1. **关系列表：** 列举了与本表关联的所有关联关系。鼠标移动到列表项上，可以点击**垃圾桶图标**删除该项。下方**添加**按钮可以添加新的关联关系
2. **关联类型：** 关联类型分为事实表关联和维表关联，不同的类型对应的**关联设置**不同
3. **关联设置：**
1. 事实表间关联
1. 关联模型：事实表间关联中，关系列表选中关系对应的另一模型（非当前模型）
2. 连接条件：事实表间关联中，可以设置表达式或字段对应关系，来表示两个事实表如何关联到一起
3. 更多事实表关联设置参考[Join关联](../../data-process/transform/join.md)
2. 维表关联
1. 主表：维表关系中，事实表的一方
2. 关联维表：维表关系中，维表表的一方
3. 主表维键：维表关系中，事实表的某一个字段
4. 维表关联的关联条件是**事实表的维键=维表的主键**，维表关联会自动同步到[字段的关联表属性](./README.md#associated-table)
3. 主从关联
1. 主表：主从关系中，主表的一方，比如员工基本信息表
2. 从表：主从关系中，从表的一方，比如员工职业经历表
3. 从表外键：主从关系中，从表用于关联主表的外键字段，比如员工职业经历表中的员工ID
## 关联关系图{#relations-graph}
1. 关联关系图的节点
- 显示所有与当前模型（上图：“企业基本信息”）有关系的模型，鼠标移动到节点上会显示模型的具体的路径
- 右键非当前模型，可以定位到关联模型的编辑界面
2. 关联关系图的连线
- 绿色连线代表事实表关联，蓝色连线代表维表关联
- **1-N**代表靠近**1**端的表的一行数据对应另一端表的多行数据
- 未标明**1-N**，表示系统不能根据模型结构自动识别数据对应关系
## 全局关联关系视图{#global-relations-view}
全局关联关系视图用于展示整个项目中各个模块或目录之间的关联关系。在**数据>右上方**视图，切换到**关联关系**视图。
1. 视图的窗口控制
- 通过鼠标滚轮、触摸板双指缩放，可以控制视图的窗口缩放
- 点击自适应按钮，会自动调整窗口大小以刚好将所有节点显示在窗口中
2. 目录的导航
- 双击目录节点或右键菜单展开目录
- 右键收起，将与右键节点的所有同级节点收起，显示它们的父节点
- 展开全部、收起全部按钮可以展开所有目录或返回顶级目录
3. 查看、管理目录之间的关联关系
- 查看目录之间的关系
- 管理某个模型的关联关系
4. 全局关联关系视图与模型关系面板视图的区别
- 全局关联关系显示整个项目的关联关系，而模型关系面板只显示当前模型相关的关联关系
## 应用场景{#scenes}
### 数据加工关联查询{#df-relation}
通常如果两个业务表间的关系是明确的，可以提前设置好关联关系方便更快、更准备的在数据加工中进行关联查询数据。如果没有提前设置关联关系，系统会自动发现关联关系。
比如在数据加工中拖入`企业基本信息表`和`企业投资关系表`进行关联查询时，系统会自动优先使用设置的关联关系，如果没有就会根据一致性维度自动推测。
### 跨源明细查询{#cross-detail-query}
在Superpage嵌套浮动中，下级浮动数据集会自动根据上级浮动数据集的关联关系自动查询数据。
比如企业信息查询中，以卡片的形式展示企业的基本信息，同时在卡片底部通过关联关系从`企业主要人员表`中查询展示该企业的主要人员列表。
示例地址：[卡片展示企业](https://demo.succbi.com/v5/DEMO/app/ap.app/case/company-query/index.tpg?:id=%E5%8D%A1%E7%89%87%E5%B1%95%E7%A4%BA%E4%BC%81%E4%B8%9A)
### 跨源分组汇总查询{#cross-group-query}
在报表统计查询中，在一个分组浮动区域查询多个表指标时，会使用[一致性维度](./conformed-dimension.md)来发现关联关系并汇总查询结果。
比如分析服饰销售计划完成情况时，需要按照大区和价格档次分组统计查询`销售明细表`中的`实际销售数量`、`实际销售金额`以及`进销计划表`中的`计划销售数量`和`计划销售金额`，并汇总在一个报表中计算最终的完成率。
示例地址：[跨源分组统计报表](https://demo.succbi.com/v5/bi/%E8%B7%A8%E6%BA%90%E5%88%86%E7%BB%84%E6%8A%A5%E8%A1%A8)
### 主从表管理{#master-salve-mgr}
在低代码搭建的主从表数据管理中，系统会使用主从表关联关系来进行数据的插入、级联删除、级联更新。
比如在员工信息管理中，员工基本信息表是主表，员工教育经历表、员工职业经历表都是从表，主表与从表之间在模型上设置了[主从关系](#relation-types)，在员工信息维护的过程中会使用主从关系来进行数据的增删改处理，具体如下：
- 新增员工时会在一个页面同时新增员工基本信息和教育经历、职业经历信息，在提交数据时系统自动会把新增员工生成员工ID作为从表的外键自动提交到从表中，而不需要在从表中主动配置提交该字段。
- 少数情况需要修改主表的主键时，在更新数据交互上配置[级联更新策略](../../app/superpage/design/action/update-data.md)，具体可参考[级联更新DEMO](https://demo.succbi.com/v5/ap/update-data)
- 删除员工时，系统会自动级联删除从表中的数据，而不需要在删除交互中手动维护从表数据。(注：如果业务上是假删，需要在模型上配置[删除标记](./model-settings.md#deleteflagfield)字段，级联删除时系统也会自动根据模型的设置记录删除状态)
示例地址：[主从表管理](https://demo.succbi.com/v5/ap/%E4%B8%BB%E4%BB%8E%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/field-role.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/field-role"
title: "字段角色"
---
---
order: 8
---
# 字段角色
字段角色又称数据角色，表示一个字段的扩展属性，比如日期、经度纬度、行政区划等。设置了角色的字段，可以帮助你更准确的判断这个字段的使用方式和使用场景。
系统内置的字段角色，分为五大类：`日期`、`地理`、`文件`、`比率`、`其他`。
## 日期{#date}
日期类型用来定义字段的数据类型，而日期角色用来表示字段存储的是日期信息数据。可以对任何存储日期数据的字段设置为日期角色，这些字段的数据类型既可以是日期类型，也可以是字符型。
示例地址：[销售月份](https://demo.succbi.com/v5/DEMO/data?:open=fcby8R17NfCga3tclsn2lB)
日期角色分为三类：
- **年：** 表示字段存储的是年份信息
- **年月：** 表示字段存储的是年月信息
- **日期（年月日）：** 表示字段存储的是年月日信息
正常情况下，如果字段的`数据类型`是`日期型`或`时间戳类型`，系统会自动设置日期角色。如果字段是`字符型`，但是数据存储的是日期数据，如`2020`、`202011`、`20201111`，则可以分别设置其字段角色为`年`、`年月`、`年月日`。
字段设置日期角色后，通过表达式访问角色的扩展属性，如`年月`角色，可以访问`月份`、`季度`、`年季`等
## 地理{#geo}
地理角色表示字段数据包含了地理信息，地理信息可以是行政区域或地理坐标。
地理角色分为五类：
- **中国行政区划：** 表示字段存储的是中国行政区划编码，该编码需在系统内置的[中国行政区划表](https://demo.succbi.com/v5/DEMO/data?:open=dbtable%40default%3Ademo4%3Acn_adcode&:tblview=modelData)定义范围内，比如：北京的行政区划编码为`110000`。如果数据编码在内置表定义之外，该条数据将无法在GIS地图中定位。
- **国家地理信息：** 表示字段存储的是世界国家编码，该编码需在系统内置的[国家地理信息表](https://demo.succbi.com/v5/DEMO/data?:open=dbtable%40default%3Ademo4%3Acountriesgeo&:tblview=modelData)定义范围内。比如：中国的编码为`China`。如果数据编码在内置表定义之外，该条数据将无法在GIS地图中定位。
- **湖北自贸区：** 表示字段存储的是湖北自贸区行政区划信息，本质是`中国行政区划`的子集，该字段数据同样需在系统内置的[中国行政区划表](https://demo.succbi.com/v5/DEMO/data?:open=dbtable%40default%3Ademo4%3Acn_adcode&:tblview=modelData)定义范围内。
- **经度：** 表示字段存储的是地理坐标中的经度
- **纬度：** 表示字段存储的是地理坐标中的纬度
示例地址一：[销售单位行政区划](https://demo.succbi.com/v5/DEMO/data?:open=fcby8R17NfCga3tclsn2lB&:expandIds=ecOKQrFaRlSdCNrQ6oSipw)
`中国行政区划`、`国家地理信息`、`湖北自贸区`三种是区域型地理角色，主要用于标识数据的区域范围，方便基于GIS地图可视化分析时自动显示相应的底图。\
示例地址二：[企业经纬度](https://demo.succbi.com/v5/DEMO/data?:open=UGOACvvHdkCmkIY51oQCyE)
`经度`、`纬度`是地理坐标型角色，主要用来标识字段存储的是经纬度信息，当字段类型为数值型时可以进行设置。\
通常原始的经纬度是浮点型数据，为了提升经纬度分组统计的效率，可以将浮点型经纬度数据乘以`100000`后存储在整型字段中（如示例地址二）并设置为经纬度角色，系统将能自动识别并正确应用。
示例地址三：[便民服务网点聚合经纬度](https://demo.succbi.com/v5/DEMO/data?:open=iPJqC2IYyiIUbAnDxvHCeB)
除此外，设置经纬度角色后，还可以设置属性`经纬度精度`，经纬度精度主要用于优化散点图、热力图的渲染效率。当图中点的数量非常多且密集时，会下载过多的数据，导致加载效率慢。设置了经纬度精度后，会按照设置的精度先将范围内的点进行聚集再下载和渲染，这样在地图较小时看不出与原始数据的区别，但是加载效率会快很多。
## 文件{#file}
文件角色表示字段以某种形式存储了文件信息，通过文件角色字段，系统可以正确的识别、预览和下载文件。
字段角色选择的是文件类型角色时会自动弹出字段存储设置对话框，如下：
示例地址：[企业logo图片](https://demo.succbi.com/v5/DEMO/data?:open=UGOACvvHdkCmkIY51oQCyE)
文件角色分为三种：**图片**、**文档**、**附件**，前两者明确了文件的类型，便于理解字段的使用方式和场景，而**附件**是各种文件的一个统称。当字段只存储一种类型的文件，比如只存储了图片时，字段角色可设置为**图片**，当字段中存储了多种类型的文件或除图片、文档外的其他文件时则字段角色应设置为**附件**。
选择文件角色时，还可以在弹出的[字段存储设置]()对话框中继续设置文件的存储类型和属性，如下：
- **文件存储类型**
文件存储类型分为四种，具体如下：
1. **默认文件存储服务**：通用的附件存储服务，SuccBI自动管理附件在系统中的存储与读取，使用者无需关心，字段中记录的是文件在系统内部的ID值。通常用于业务应用系统中上传附件到系统中存储和使用，比如个人中心上传个人图像。
2. **默认文件存储服务(去重)**：与默认文件存储服务基本相同，唯一区别是上传的相同文件在存储时会自动忽略只保存一次并在字段中记录同一个文件ID值。通常在海量附件存储场景时，可以节省文件的存储空间开销，比如在核酸检测人员采样中同一个家庭的人可以使用同一个身份证登记，上传相同身份证图片时系统只存储一份。
3. **工作目录路径**：字段存储的是相对于[工作目录](../../devops/install/basic-install/workdir-and-defdb.md#dir)下的`clusters-share`目录的路径。通常用于将本地已存在的附件或批量附件读取到系统中使用，比如本地已经有整理好的所有企业图标附件，将附件存放在工作目录的`clusters-share`目录下后，可以在[企业基本信息表](https://demo.succbi.com/v5/DEMO/data?:open=UGOACvvHdkCmkIY51oQCyE)中的【企业图标】字段中存储图标的工作目录路径为`dw-attachments/DEMO/picture/companies-logo/武汉奇普微半导体有限公司.png`。
4. **外部链接**：文件来自于互联网，如`http://www.succsoft.com/path/to/image1.png`，通过web接口应当可以获取到文件。当文件很大时，比如100M+，多个用户同时访问或下载时会大量占用系统的网络带宽从而导致系统整体的网络响应故障，解决这个问题的方案通常是将大文件使用第三方的互联网存储服务通过外部链接访问。比如，一个软件产品的社区网站通常也会发布视频课程，而这些视频课程的视频文件通常并不是存储在自身网站系统内，而是存储在第三方的视频服务网站，比如哔哩哔哩、腾讯视频、萤石云等，播放视频课程时实际上是通过外部链接跳转到对应第三方服务网站上播放的。
- **存储多个**
字段是否存储多个数据项，详细介绍请参考[字段存储设置](./README.md#field-storage-settings)。
- **存储附件属性**
当**文件存储类型**不是**外部链接**时可以设置文件的属性，具体如下：
- **文件名字段：** 指定一个字段存储文件的文件名信息，可用于下载附件时设置下载文件的名称。
- **文件大小字段：** 指定一个字段存储文件的文件大小信息。
- **文件修改时间字段：** 指定一个字段存储文件的文件修改时间信息。
设置后，上传附件时系统会自动将当前上传文件的名称、大小、修改时间信息记录在设置的字段中。
## 比率{#rate}
比率角色主要用来标识字段存储的是比率数据，数值型字段可以设置该角色。
比率角色字段，比如毛利率，在分析应用中能自动显示为百分比格式。
## 其他{#others}
### HTML{#html}
HTML角色表示字段内容是HTML，在应用中被显示时可以当做HTML来渲染。
例如，文章详情、产品介绍、个人简历等可以存储HTML信息在字段中并设置为HTML角色。
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/model-index.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/model-index"
title: "索引管理"
---
---
order: 9
navTitle: 索引管理
---
# 索引管理
索引管理是指在模型的**性能优化** > **索引**中创建并管理其对应数据库表的[索引](../../perf/db-pref.md#index)。当模型的数据量较大，而查询的结果集很小时（数据量一般小于原表10%），通常可以根据查询的过滤条件创建数据库索引优化性能。
::: tip 提示
索引管理是基于数据库索引机制的优化策略，通常用于传统的关系型数据库，如MySQL、Oracle，而对于分析的列式数据库(如vertica)、NoSQL(Mongodb、Elasticsearch)数据库等则没有索引的概念。
:::
## 新建索引{#create-index}
在[企业信息自助查询](https://demo.succbi.com/v5/demo-spg/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E6%9F%A5%E8%AF%A21)中，常需要通过【统一社会信用代码】来从`企业基本信息表`中查询一户企业，这时可以给【统一社会信用代码】添加索引。
在模型管理的**性能优化** > **索引**标签页下**新建索引**，如下：
示例地址：[企业基本信息表](https://demo.succbi.com/v5/DEMO/data?:open=UGOACvvHdkCmkIY51oQCyE)
1. 在`企业基本信息表`中切换至**性能优化** > **索引**
2. 新建索引：点击**新建索引**，弹出对话框
3. 名称：输入名称`INX_TYSHXYDM`
4. 添加字段：点击`+`，选择字段【统一社会信用代码】
5. 保存：点击**确定**后，再点击模型的**保存**按钮
## 索引列表{#index-list}
### 索引列表属性{#index-property}
索引列表展示已经创建的索引的信息，具体属性如下：
1. **索引名称**：创建索引时设置的**名称**
2. **字段**：创建索引时选择的字段的**物理字段名**列表
3. **字段名称**：创建索引时选择的字段的**名称**列表
4. **唯一索引**：创建索引时勾选了**高级选项**下的**作为唯一索引**后显示**是**，否则显示**否**
5. **操作**：
- 删除：删除当前索引
- 编辑：弹出[索引编辑对话框](#index-dialog)，可以修改索引的设置，修改后需要重新保存模型表索引才生效
- 启用/禁用：[启用和禁用子集](#index-enabled)
### 启用和禁用索引{#index-enabled}
可以单个或批量启用和禁用索引：
- 单个启用/禁用：在索引列表的**操作**列中点击**启用/禁用**按钮来控制对应的索引可用状态
- 批量启用/禁用：在索引列表的下方点击**全部启用/全部禁用**按钮来批量控制索引的可用状态
::: tip 提示
1. 索引目前采用模型的元数据管理机制，**启用/禁用**都需要保存模型才能生效，保存时会先弹出[差异同步对话框](./README.md#sync-table)，对话框中显示当前模型与数据库物理表的索引差异，以确定是否需要同步。
2. 索引被禁用后会从数据库物理表中直接删除，启用后重新创建。
3. 在[数据加工](./model-data-type.md#dataflow)的提取属性中若勾选了[重建索引和主键]()，在提取过程中，也会先把索引删除，数据提取完后再创建索引，以此来提升加工提取的性能。
:::
### 索引对话框属性{#index-dialog}
- **名称**：索引在模型元数据中的存储的逻辑名称，创建在数据库物理表上的真实索引名是系统自动生成的
- **字段**：从当前模型的字段列表中选择
- **排序**：默认为**升序**，绝大部分索引都是升序的，仅当需要模型按照某个字段进行倒序排序时才可能需要创建倒序索引
- **作为唯一索引**：点击**显示高级选项**，可选择勾选**作为唯一索引**，勾选后表示该索引的字段组合在模型的数据中是唯一的
- **移动字段**：可以拖动字段前面的**滑动图标**来调整索引中多个字段的顺序
::: tip 为什么需要调整字段顺序？
传统关系型数据库均是**最左前缀匹配**机制，即索引有多个字段时，必须按照字段顺序从左到右匹配。
举个例子，如果在`企业基本信息表`中创建了索引`(登记机关,成立日期)`，当你执行如下查询时：
- `[登记机关]='湖北省武汉市工商行政管理局' AND [成立日期]='2020-01-08'`，可以使用索引 :heavy\_check\_mark:
- `[登记机关]='湖北省武汉市工商行政管理局'`，最左前缀匹配，先匹配【登记机关】，可以使用索引 :heavy\_check\_mark:
- `[成立日期]='2020-01-08'`，必须先匹配【登记机关】，不可以使用索引 :x:
:::
## 正确的使用索引{#using-index-correctly}
实际项目中索引的优化分析比较复杂，但是从中我们总结出了一些通用的经验或规则，能让普通的业务人员也能正确的使用索引。
::: tip 使用索引的前提条件
只有当查询的数据集是原表的一小部分（通常要10%以下）时，数据库才能使用索引提升性能。
:::
在熟知**使用索引的前提条件**后，在创建索引时请遵循如下经验规则：
1. 对于频繁进行更新的[APP模型](./model-data-type.md#app)，索引的个数尽量不要超过5个，否则会影响数据插入和更新事务的性能
2. 模型的[维键]()通常需要创建索引，模型的主键数据库会自动创建唯一索引
3. A表关联B表，通常需要在B表的关联字段上创建索引
4. 索引键的长度越短性能越好，不要在大文本字段上创建索引
5. 创建复合索引时，需要将最常用来过滤的字段放在最前面
6. 索引应该创建在经常用于过滤且选择性高的字段上
7. `不等于`、`不包含`、`不为空`等非运算不能使用索引
8. `为空`、`包含`、`结尾是`不能使用索引，`开头是`可以使用索引
9. 过滤字段的数据类型与要过滤的值的数据类型不一致时，不能使用索引
10. 字段被函数或表达式引用时不能使用索引
::: tip 提示
部分数据库支持定义函数索引，目前SuccBI的索引管理中暂未支持
:::
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/data-security.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/data-security"
title: "数据安全"
---
---
order: 16
navTitle: 数据安全
---
# 数据安全
**数据脱敏**、**数据加密**是系统中保证数据安全使用的两种方法，在数据模型中进行设置，可以提高数据的安全性和私密性，其效果如下：
## 脱敏{#desensitization}
**数据脱敏**是对敏感数据进行遮盖处理，将敏感的信息部分或全部替换为\*号或其他字符，例如身份证遮掩中间出生年月信息。数据脱敏不会修改数据库中物理表数据，只影响内容显示，不影响存储。
在数据列表下，选择对应模型表字段，**右键**点击**脱敏与加密**，勾选**启用脱敏**，设置**脱敏规则**即可对数据进行脱敏处理：
- **脱敏规则**：当前系统中内置的脱敏规则有`身份证号`、`手机号`、`姓名`、`地址`、`Email`、`年龄`、`银行卡`、`公司`、`数值`等
- **脱敏方式**：当前系统有`掩码`数据脱敏和`正则表达式`数据脱敏两种方式，可根据需求使用不同方式自定义规则，相关设置参考文档[数据脱敏](../../sys-settings/security/securityconf.md#desensitization)
## 加密{#encryption}
**数据加密**是指通过加密密钥和加密函数将数据转换成无业务意义的密文，接收者通过解密函数和解密密钥将密文还原成明文。数据加密会修改数据库中物理表数据，会将原始数据替换为加密后的密文，同时影响显示和存储，可以防止数据在存储和传输过程中失密。
在数据列表下，选择对应模型表字段，**右键**点击**脱敏与加密**，勾选启用**启用加密**，设置**提取时加密**即可对数据进行加密处理：
- **提取时**：启用后，数据加工在执行提取时会按照选定的算法对数据进行加密或解密
- **加密算法**：当前系统中内置的加密算法有`SM4`和`AES`，用户可根据需求进行选择，相关设置参考文档[数据加密](../../sys-settings/security/securityconf.md#data-encryption)
- **自动解密**：查询数据时，会自动解密
::: tip 提示
1. 加密提取时，由于加密后字段长度会增长，若字段长度不足，需要增大字段长度。
2. 加密之后，若要在第三方系统使用，需要使用密钥进行解密。
:::
## 应用{#scenarios}
脱敏与加密常用于密码加密、合同信息保密、敏感个人信息遮盖等场景。例如在展示企业基本信息时，对企业主要成员姓名使用\*号进行遮挡处理，见以下示例：
示例地址：[卡片展示企业信息](https://demo.succbi.com/v5/demo-spg/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E5%8D%A1%E7%89%87%E5%B1%95%E7%A4%BA%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF)
---
url: "https://docs.succapp.com/v5/guide/data-gov/model/conformed-dimension.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/conformed-dimension"
title: "一致性维度"
---
---
order: 30
---
# 一致性维度
一致性维度是数据仓库建模中的一个重要概念，一致性维度是在多个不同的事实表(数据表)中拥有一样的业务意义的维度字段，如`客户ID`、`产品类型`、`数据期`等，通过一致性维度的规范约束，使数仓事实表之间有了一种天然的“联系"，使数仓模型之间变得更有条理更清晰。
一致性维度在系统的功能使用方面也发挥着重要作用，主要包括:
1. 自动作用条件
系统可以通过一致性维度在页面内或页面间自动进行上下文维度条件的传递，比如[数据范围权限过滤](#permission-cond)、[下拉框跨源过滤数据](#cross-filter)、[页面内条件传递](#within-page-cond)、[页面间跳转条件传递](#drill-down-cond)。
2. 发现关联关系
在涉及2个表的关联查询或者跨表汇总查询时，系统会自动根据一致性维度规则发现关联关系，具体请参考[自动发现关联关系](./model-relations.md#auto-discovery)。
## 一致性维度规则{#rules}
系统会使用一系列的规则判断2个模型之间的一致性维度，用户在新建或修改模型时只要遵守一些简单的规则即可满足一致性维度的规范要求:
1. 拥有相同的维表：模型的字段中都设置了相同的[关联表](./README.md#associated-table)。
2. 拥有关联关系：模型之间设置了[关联关系](./model-relations.md)。
3. 拥有相同的字段名称：模型的[字段名称](\(/data-gov/model/#field-properties\))或物理字段名相同。
系统在获取一致性维度时，会使用 `拥有相同的维表` > `拥有关联关系` > `拥有相同的字段名称` 的优先级顺序进行判断。
::: warning 注意
系统仅在需要获取一致性维度进行`自动作用条件`和`发现关联关系`的局部上下文中才会使用以上规则，而不是总是应用规则。常见的使用场景请参考下方的[应用场景](#scenes)。
:::
## 应用场景{#scenes}
### 数据范围权限过滤{#permission-cond}
不同权限用户查看同一个页面时需要显示不同的数据，如湖北省的用户只能查看湖北地区的数据，湖南省的用户只能查看湖南地区的数据。
在权限管理时会使用`行政区划维`作为[数据范围维度](../../project-manage/data-permission-setting.md)来给用户分配能查看的数据范围。系统在查询页面数据时会自动将当前用户的数据范围权限条件通过一致性维度规则找到要查询模型的一致性维度字段并作用到查询条件中。
示例地址：[总体经营情况](https://demo.succbi.com/v5/DEMO/app/%E6%9C%8D%E9%A5%B0%E9%94%80%E5%94%AE%E9%A9%BE%E9%A9%B6%E8%88%B1.app?:id=%E6%80%BB%E4%BD%93%E7%BB%8F%E8%90%A5%E6%83%85%E5%86%B5) （湖北用户：hb01/123456，湖南用户：hn01/123456）
### 下拉框跨源过滤数据{#cross-filter}
在仪表板中经常会使用到不同的图表组件从多个模型中查询展示数据，同时在页面顶部会放置多个下拉框设置不同的维度条件进行动态查询，系统可以通过一致性维度将下拉框维度条件自动作用到所有数据集中过滤。
如下图仪表板，左侧柱形图是从`门店销售汇总表`中查询统计，而右侧KPI、矩阵图从`门店销售明细表`中查询统计，顶部的日期和省份下拉框过滤条件通过一致性维度自动作用到所有数据集中。
示例地址：[跨表过滤-自动过滤](https://demo.succbi.com/v5/bi/%E8%B7%A8%E8%A1%A8%E8%BF%87%E6%BB%A4-%E8%87%AA%E5%8A%A8%E8%BF%87%E6%BB%A4)
### 页面内条件传递{#within-page-cond}
与[下拉框跨源过滤数据](#cross-filter)类似，在仪表板页面内可以在画布上设置全局过滤条件，下级组件会自动根据一致性维度将过滤条件作用到查询中。同样，在报表的[工作表过滤器](../../report/design/properties/README.md)中可以设置sheet的全局过滤条件，也可以把单元格设置为条件单元格并框选一片作用区域，系统也会自动通过一致性维度将条件到设定范围内的所有模型查询中。
示例地址：[跨源过滤-条件传递](https://demo.succbi.com/v5/bi/%E8%B7%A8%E8%A1%A8%E8%BF%87%E6%BB%A4-%E6%9D%A1%E4%BB%B6%E4%BC%A0%E9%80%92)
### 页面间跳转条件传递{#drill-down-cond}
在页面间可以通过[打开链接](../../app/superpage/design/action/linkto.md)的方式跳转到下级页面，下级页面会自动根据一致性维度将上级页面的过滤条件作用到下级页面的查询中。
如下图，在展示各省份服装销售情况的报表中，可以点击`湖北省`的`销售数量`单元格下钻到子报表中查询。在下钻单元格通过[打开链接交互设置自动传递过滤条件](../../app/superpage/design/action/linkto.md)，系统会自动根据一致性维度将`年月`、`省份`条件作用下子报表的查询模型中，而无需主动传递。
示例地址：[页面间下钻条件传递](https://demo.succbi.com/v5/bi/zzbxz)
---
url: "https://docs.succapp.com/v5/guide/data-gov/dataset.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/dataset"
title: "dataset"
---
---
order: 7
navTitle: 数据集
---
# 数据集
数据集（dataset）是一个页面（如报表、仪表板或SuperPage等页面）内部的一个数据集合概念，是页面查询、提交和修改数据的入口。数据集是一个抽象的概念，它有多种体现，本文将讲述如何在页面中引入、新建和管理数据集。
如上图所示，数据模型是存在于数据仓库中的数据表，这些表可以给很多页面使用。当需要在某个页面中使用这些模型时，我们可以直接引入一个模型，也可以选择把模型查询过滤和分组后的查询结果引入到模型来，为了完成页面所需的业务化查询需求，我们甚至可以在页面的内部新建一个临时的数据加工，所有的这些数据来源引入到页面后都统称为数据集，一个页面可以包含多个数据集。
## 数据集类型{#dataset-type}
为了方便页面获取和修改各类数据，系统提供了多种数据集类型，包括**枚举数据集**、**JSON数据集**、**脚本数据集**等等，通过设计器的菜单可以很方便的创建各类数据集：
- [数据模型数据集](#data-model)：直接将全局模型表引入后形成数据集
- [查询数据集](#query-dataset)：将模型进行过滤、分组、排序后的结果作为数据集
- [内嵌数据加工](#dataflow)：新建一个当前对象内部的数据加工
- [枚举数据集](#enumerate-dataset)：通过手动录入数据的方式，定义常量类数据集
- [JSON数据集](#json-dataset)：通过表达式返回约定格式结果并自动解析生成动态数据集
- [脚本数据集](#script-dataset)：通过脚本灵活的获取数据并返回一个动态结构的数据集
- [系统数据集](#system-dataset)：引用系统数据作为当前页面的数据集，如用户、机构等
- [流程数据集](#process-form-data)：引用流程数据作为当前页面的数据集，如我的待办、我的已办等
### 数据模型数据集{#data-model}
**数据模型**是指将已经建模好的[全局模型](./model/model-data-type.md)引入到当前页面内形成的**数据集**。
直接引入已有的数据模型是一种最便捷的使用数据的方式，引入后可以继续设置[过滤](#filter)、[排序](#sort-fields)、新增[计算字段](#calc-field)等。在低代码页面中也可以通过**数据模型**数据集进行修改和提交数据。在仪表板和报表中，系统会根据具体引用字段的表达式和组件，自动构造查询请求，支持各种复杂查询、关联查询、分组查询等。但在低代码SuperPage页面中，只能做明细查询。如果需要做复杂查询，需要使用[查询数据集](#query-dataset)或[内置数据加工](#dataflow)。
**数据模型**数据集和[查询数据集](#query-dataset)相似，但也有区别，主要的区别是[查询数据集](#query-dataset)可以做数据分组和筛选；如果做了分组查询，[查询数据集](#query-dataset)是**只读**的，在低代码应用中无法进行数据修改和提交。
将**数据模型**添加到页面中，系统提供了两种添加方式：
- 在**数据栏**中点击**添加**按钮，在弹出框中通过搜索或直接在其所在目录下选中该模型，点击确定。
- 点击**数据按钮**>**选择数据模型**，在对话框中通过搜索或直接在其所在目录下选中该模型，点击确定。
**数据模型**常用操作如下：
| 序号 | 操作 | 作用 |
| :--------: | :--------: | :-------- |
| 1 | 打开 | 在当前页面内部打开模型，查看模型数据及结构 |
| 2 | 定位 | 新开浏览器标签页，并在数据模块打开并选中引用的数据模型 |
| 3 | [重新选择](#replace-dataset) | 将当前的**数据模型**替换为其他新的模型 |
| 4 | [查看引用](#view-references) | 查看当前**数据模型**是否被其他组件引用 |
### 查询数据集{#query-dataset}
**查询数据集**是基于已经建模好的[全局模型](./model/model-data-type.md)进行数据过滤、分组、字段筛选后形成的一个查询子集。
与模型数据集相比，**查询数据集**也可以[过滤](#filter)和[排序](#sort-fields)，但还可以进行**分组**和**筛选**，在设置**查询数据集**的过程中，可以即时的看到数据查询结果。另外，**查询数据集**支持在数据集中设定需要输出的字段，这样就可以只把需要用到的数据显示在页面中，简化后续页面制作中字段选择的过程。在低代码页面中对于不分组的查询数据集，也支持数据的**提交**和**修改**。
新建**查询数据集**，可以点击**数据按钮**>**新建数据集**，在对话框内进行新建，新建数据集需要以下几个步骤：
1. 设置数据集名称：输入一个合理且有意义的名称，不能为空
2. 引入数据模型：数据集是基于模型表的子集，使用下拉的方式引入数据模型，添加后模型数据会在右侧的[数据列表](#dataset-field)中展示
3. [查询数据集属性设置](#dataset-properties)：为数据集进行过滤、添加分组或排序字段
4. 保存：保存当前数据集，保存后的数据集用法和引入的数据模型用法一致，在数据模型下可以查看数据集中的字段，在控件的数据中即可引用该数据集
**查询数据集**常用操作如下：
| 序号 | 操作 | 作用 |
| :--------: | :--------: | :-------- |
| 1 | 过滤条件 | 对**查询数据集**中引入的数据模型数据进行过滤，可参考[过滤](#filter) |
| 2 | 分组字段 | 设置**查询数据集**的分组字段，设置后查询结果会根据分组字段进行分组 |
| 3 | [字段管理](#dataset-field) | 当引入的数据模型中已有的字段无法满足所需，需要根据已有的字段构造出的新的字段列或者对字段进行修改时，可以**新建字段**，或数据量较大且有些字段不需要时，可通过**选择字段**勾选需要的字段，提高数据查询效率 |
| 4 | 字段属性 | 设置**查询数据集**中字段的**字段类型**、**文字字段**等属性，具体操作可参考[管理字段](./model/README.md#filed-management) |
| 5 | 同步差异 | 当**查询数据集**的结构与引用模型表结构不一致时，数据集对话框中的**刷新**按钮会有黄色标记提示，点击**刷新**按钮可查看模型表与物理表的差异，并勾选需要修改的差异信息同步到数据集 |
### 内嵌数据加工{#dataflow}
**内嵌数据加工**数据集是在当前页面内部新建的一个只供当前页面使用的数据加工模型。
1. 当需要对页面进行较复杂的查询（如关联、联合、数据清洗等），且这个查询只有当前页面会用到，不需要建立全局的数据模型时，可以使用**内嵌数据加工**
2. **内嵌数据加工**是存储于当前页面内部的，它不会影响全局模型，如果以后有其他页面也有可能需要用到同样加工逻辑时，我们就需要从全局数据仓库建模管理的角度去考虑是否需要新建一个全局的数据模型，只有确定这个加工逻辑确实比较个性化，只有这个页面使用时才使用内嵌加工，当然，如果以后需要，也支持将当前页面的内嵌数据加工保存到全局
3. 内嵌加工相当于一个数据视图，它的加工结果是不会存储的，每次查询时都会实时查询，这也就意味着，内嵌加工数据集是只读的，不能用于低代码**提交**和**修改**
新建页面内数据加工，可以点击**数据源按钮**>**数据加工**，加工操作参考文档[新建数据加工](../data-process/create-dataflow.md)。
当前页面内新建的数据加工，如果需要保留到全局使用，可以右键模型选择**转换为全局模型**，再在对话框中确定模型**名称**、**描述**以及**目录**，这样就可以将当前页面内的数据加工保存到指定目录下，供全局使用。
### 枚举数据集{#enumerate-dataset}
**枚举数据集**是存储在当前页面内的一个小的、静态数据集合。
1. **枚举数据集**常用作给当前页面提供一些静态数据，比如为**下拉框**的下拉选项、**多选面板**的枚举值等
2. **枚举数据集**是存储在当前页面的只读数据集，不能用于低代码的**提交**和**修改**
3. 通常使用**枚举数据集**的地方也可以使用一个小的**维表**替代，在页面内新建**枚举数据集**更快捷一些，但**枚举数据集**不具备和数据模型关联的能力，如果枚举项存在和其他模型表数据的维键关联的情况，那么应该新建**维表**而不是**枚举数据集**
4. **枚举数据集**是一种**前端数据集**，所以无法使用一些**汇总**、**分组**等后端查询方式，仅仅只能用作于明细查询
**枚举数据集**中录入的数据的方式，可以参考[创建空白模型](./input-model-data.md)。
### JSON数据集{#json-dataset}
**JSON数据集**是一个JSON数据包（来自表达式函数计算、或JS、Web API等）转换为一个数据集。
1. 利用**JSON数据集**的灵活运算能力，从而实现将一行数据拆分成多行，可参考[表达式拆分多行数据集](https://demo.succbi.com/v5/demo-spg/表达式拆分多行数据集)。或根据表达式动态生成数据集数据，并提供给其他组件使用，可参考[表达式定义动态数据集](https://demo.succbi.com/v5/demo-spg/表达式定义动态数据集)
2. 调用JS函数来获取任意API的返回结果数据，并解析成数据集供当前页面使用，可参考[调用JS函数获取API数据](https://demo.succbi.com/v5/demo-spg/调用JS函数获取API数据)
系统支持通过表达式返回如下几种约定格式的值：
1. 分割文本
2. 一维数组
3. 二维数组
4. JSON（仅支持简单JSON格式）
### 脚本数据集{#script-dataset}
todo
### 系统数据集{#system-dataset}
**系统数据集**可以让用户使用系统内部的系统表。
系统内部有很多系统数据表、比如机构表、部门表等，通常用户没有权限直接访问这些表的数据（存在安全隐患），而通过**系统数据集**去访问这些数据可以更方便更安全。
**系统数据集**目前提供了如下系统表的访问能力：
- 用户数据集：将系统用户表引入到当前页面，可以设置一些限制条件，也可以设置自定义过滤条件
- 限制显示当前部门用户：过滤掉当前登录用户的同部门用户
- 限制显示上级部门用户：过滤掉当前登录用户的上级部门用户
- 限制显示指定部门数据：过滤掉指定部门的用户
- 限制显示指定用户组用户：过滤掉指定用户组的用户
- 部门数据集：将系统部门表引入到当前页面，可以自定义过滤条件
- 机构数据集：将系统机构表引入到当前页面，可以自定义过滤条件
### 流程数据集{#process-form-data}
**流程数据集**允许用户引用流程相关的数据集。
通过引用不同的**流程数据集**，可以快速配置出不同类型的任务列表、表单页面等流程相关的业务页面。
系统提供如下几种**流程数据集**：
- [流程状态数据](#process-status)
- [流程任务信息](#task-img)
- [流程表单数据](#page-img)
### 流程状态数据{#process-status}
当需要制作待办或已办等展示流程任务数据的列表时，可以在页面中引入[流程任务表](../dev/sys-tables/README.md#flow_tasks)，用户可直接将其引入或通过加工关联上业务表数据后再引入，再根据需求设置对应的**过滤条件**。基于上述设置，在**流程数据集**中提供了**我的待办**、**我的已办**等快捷设置方式，本质上还是引入了[流程任务表](../dev/sys-tables/README.md#flow_tasks)，但对引入的数据源会有默认的过滤条件，例如**我的待办**会在[流程任务表](../dev/sys-tables/README.md#flow_tasks)中过滤出属于当前用户的活动中的任务数据，具体设置如下：
- 选择要获取的数据：可在此设置中切换成其他类型的工作流数据源
- 关联表单数据一起：流程的任务数据是不包含业务数据的，当用户希望查询的任务列表能带上一些业务数据的信息时，比如需要查询出请假申请的请假人和请假天数，此时可以勾选关联表单数据一起并选择一个业务表作为关联对象，系统会自行将选择的业务表与流程任务表通过业务代码进行关联
- 自定义过滤条件：勾选后，在默认的过滤条件基础上课额外添加过滤条件
系统目前已经支持如下几种流程状态数据：
- 我的待办事项
- 我的申请事项
- 我的已办事项
- 我的所有事项
- 我的未读消息
- 我的已读消息
- 我的所有消息
### 流程任务信息{#task-img}
当需要在页面中获取到当前正在处理的流程任务的相关信息时，比如当前任务处于流程的哪个环节，需要引入**流程任务信息**，**流程任务信息**的来源也是[流程任务表](../dev/sys-tables/README.md#flow_tasks)，不同于**我的待办**，**流程任务信息**总是单行的，通过数据源设置上的**任务ID**来自动过滤[流程任务表](../dev/sys-tables/README.md#flow_tasks)来得到唯一行的任务数据，具体设置如下：
- 选择要获取的数据：可在此设置中切换成其他类型的**工作流数据源**
- 任务ID：通常是输入一个参数或一个实际的任务ID，通过有效的任务ID能在[流程任务表](../dev/sys-tables/README.md#flow_tasks)中过滤出对应的任务信息
### 流程表单数据{#page-img}
**流程表单数据**指的是工作流中使用的业务表，如请假申请表或报销申请表等。工作流中的相关操作**提交表单**、**执行流程**等都需要借助**流程表单数据**的作用来达到效果。具体设置如下：
- 选择要获取的数据：可在此设置中切换成其他类型的**工作流数据源**
- 选择工作流：只能在工作流文件中选择，用于确定是哪个工作流中的业务数据
- 选择表单：只能在选定的工作流的业务数据中选择，多张业务表需要同时使用时，要添加多个**流程表单数据**
- 任务ID：通常是输入一个参数或一个实际的任务ID，通过有效的任务ID可以得到指定的业务表数据
- 根据流程设置显示隐藏或禁用输入项：勾选后，所有绑定当前**流程表单数据**的输入组件会自动根据[节点数据权限设置](../app/workflow/datapermissions.md)来控制显示和禁用情况
:::tip
**流程表单数据**就是对工作流中的业务表加上了一层定义，代表选出来的业务表是工作流中的表。不同于直接引入这些业务表，引入这个定义是为了方便系统能默认提供一些流程上的设置：
- [提交表单](../app/superpage/design/action/submit-data.md#start-flw)交互只有往**流程表单数据**中新增数据时才会自动生成流程任务数据
- 通过**流程表单数据**可以获取到[节点数据权限](../app/workflow/work-with-spg.md#read-and-write)，根据设置能自动控制绑定了**流程表单数据**中字段的输入组件的显示和禁用
- 根据提供的**任务ID**能快速过滤出当前处理的业务数据并装载到业务表单上
:::
## 数据集属性{#dataset-properties}
系统提供数据集属性管理，可以为数据集设置如下属性：
- [过滤](#filter)：在数据集上设置过滤条件，将数据先进行一次过滤
- [排序](#sort-fields)：在数据集上设置排序字段，将查询出来的数据先进行排序
- [参数](#params)：更改数据集参数值
- [补足](#supplement)：对数据结果进行补足
- [安全](#permission)：限制数据集读写、导出、查询等权限
- [查询](#query)：设置数据集查询属性，如分页、查询行数等
- [缓存](#cache)：设置数据集缓存，如是否查询缓存等
- [高级](#senior)：设置数据集高级设置，比如数据集数据粒度
### 过滤{#filter}
当可视化分析内所有的组件具有相同的取数口径时，可以通过右键点击模型，选择**设置**>**过滤**，在数据集上设置全局过滤，过滤条件会影响所有使用该数据集的控件，这样就无需为组件一一设置过滤。可以使用**参数**或者根据[输入组件](../data-viz/dash/components/input/combobox.md)的值进行过滤。过滤条件的编写可参考文档[过滤](../data-viz/dash/design/data/data-filter/README.md)。
### 排序{#sort-fields}
在**设置**>**排序**中，可以为数据集添加一个或多个排序字段并指定排序方式。通常用于需要按照某种顺序显示数据的场景，比如销售数据按照【销售数量（件）】降序显示，并且数据集中指定排序字段的优先级高于[数据模型中指定排序字段](./model/model-settings.md#sort-fields)。默认按照数据集上排序设置或者主键进行排序。
### 排序方式{#sort-order}
**排序**中提供多种排序选择：
- 自动：使用模型排序的设置，或模型的主键进行排序
- 不排序：总是不排序，可以较大提升查询效率
- 指定字段：选择固定的字段进行排序
- 动态排序：通过配置项，动态设置排序方式
### 参数{#params}
若分析页面使用的数据集设置了参数，而分析时需要对参数进行更改时，可以在分析页面右键点击该数据集，选择**设置**>**参数**，对参数进行更改，并传递给该数据集，得到新的数据处理结果，无需重新在数据集中更改参数，参考文档[设置动态加工参数](../data-process/setting-params.md)
::: tip
数据集上如果没有参数，那么设置中会自动隐藏参数设置项
:::
### 补足{#supplement}
当页面中的数据行数不符合业务期望时，可以考虑使用**补足**属性，对数据结果进行补足，使其符合一定的行数规则。右键数据集**设置**>**补足**，勾选**启用补足后**，可以设置相应的补足规则，具体如下：
- 补足方式：系统提供**补空白行**、**补维项**、**补已有数据**和**合并其他数据集**四种补足方式
1. 补空白行：当行数不足时，补空白行。勾选后，需要配置**期望行数**。这样设置后，如果数据不足指定行数，那么将字段补上空白行
2. 补维项：按主键字段关联的维表，补足维表中的数据。勾选后，需要配置用来关联的**维键字段**。同时支持**按其他模型补足**，勾选后，可以指定其他模型用来关联补足
3. 补已有数据：从当前数据集中取已存在的数据进行补足。勾选后，可以设置过滤条件，这样可以将过滤后的数据不足到当前数据行中
4. 合并其他数据集：将另外一个数据集的查询结果合并过来。勾选后，需要配置指定**数据集**。支持**自动映射同名字段**，也可以手动**自定义字段映射**
- 仅初始化时补足：勾选后，仅在未提交数据时补足，提交数据后总是装载数据
::: tip
**补足**属性对单行数据集无效。
:::
### 安全{#permission}
当需要限制用户的读写权限时，或者允许用户查看脱敏前的明文数据时，可以右键数据集**设置**>**安全**中进行设置，提供如下安全设置：
- 限制读：勾选后，可以限制用户读取数据的权限，可以指定用户或者通过表达式动态筛选用户，默认不勾选
- 限制导出：勾选后，可以限制用户导出数据的权限，可以指定用户或者通过表达式动态筛选用户，默认不勾选
- 允许脚本查询：默认的只有数据集被引用了之后才能被查询，允许脚本查询后系统将总是允许浏览器发起查询，默认不勾选
- 按需查询字段：默认的系统会一次性查询所有被引用的字段数据。当字段很多且有一些字段一开始并不显示，可以勾选**按需查询字段**，此时系统值按需查询当前需要显示出来的字段，默认不勾选
- 允许查看明文：勾选后，忽略字段上的脱敏设置，允许用户查询明文数据，默认不勾选
- 允许导出明文：勾选后，忽略字段上的脱敏设置，允许用户导出明文数据，默认不勾选
### 查询{#query}
当使用到列表展示数据且需要分页展示，或者需要限制用户的最大查询行数时，可以右键数据集**设置**>**查询**中进行设置，提供如下查询设置：
- 分页：当数据集被查询明细的组件使用时，比如列表、明细表、浮动面板等，可以启用分页。提供**自动**、**启用**、**禁用**三个选项，默认为**自动**
- 每页行数：设置分页后每页查询行数，当**分页**勾选了**自动**或**启用**时，可设置**每页行数**
- 最大查询行数：限制一次查请求最大的查询数据量，避免页面加载过多的数据导致浏览器崩溃，默认查询10000行数据
- 手动刷新：当过滤条件或参数引用的内容发生变化时是否需要手动刷新数据，默认自动刷新会驱动相关的可视化组件刷新。勾选后，需要通过**刷新**交互主动刷新，默认不勾选
- 初始时不查询：勾选后，页面一开始显示时不自动查询，需要用户使用**刷新**交互查询数据，默认不勾选
- 自动更新影响的指标：当前数据集被修改后，自动更新影响的其他数据表的指标，被影响的数据表的指标需要定义正确的取数口径，默认不勾选
- 启用增量加载：勾选后，系统将按照模型上设置的最后修改时间增量加载数据，把上次加载后有变化的数据增量加载到当前数据集中，默认不勾选
- 启用查询条件：勾选后，可以编写查询条件，当查询条件返回true时才会真正的发起数据库查询，默认不勾选
### 缓存{#cache}
系统提供缓存机制的相关设置，可以按需控制是否通过缓存来进行数据的查询，可以右键数据集**设置**>**缓存**中进行设置，提供如下缓存设置：
- 前端预加载数据：提供**继承数据表**、**允许全量加载**、**按需加载**三种预加载方式，默认**继承数据表**
- 继承数据表：继承数据表的设置进行预加载
- 允许全量加载：尽量从后端获取足够的数据，然后在浏览器进行分组、过滤和排序，减少对后端数据库的查询频率
- 按需加载：只允许查询条件范围内的数据
- 优化合计行查询：勾选后，尽量基于已有的查询在浏览器端完成合计行计算，如一个报表，浮动行下面有一个合计行（不分页），此时合计行可以直接基于浮动行在前端计算，默认勾选
- 启用查询缓存：提供**自动**、**启用**、**禁用**三种缓存查询设置
- 自动：自动使用查询中的主查询明细的设置，默认选择此项
- 启用：自动缓存数据到临时文件，以提升系统效率，如果模型的数据经常修改，通常不建议启用缓存
- 禁用：禁用查询缓存数据
- 集群共享缓存：当启用查询缓存后，可以设置是否在集群间共享缓存。启用后，查询缓存文件将存储在集群共享文件夹下，各个集群节点可以共享，当集群节点很多时（比如大于10台）启用集群共享缓存可以避免多个集群节点并发同时查询数据库，降低数据库压力
- 设置缓存有效期：当启用查询缓存后，可以设置缓存的有效时间，在有效期内，即便数据被修改了系统还是可以继续使用之前的缓存，减少数据库查询和网络流量。此选项通常用于海量用户（如千万级别以上（访问一些公共数据，且用户能接受不立即查询到最新的数据）
### 高级{#senior}
数据集提供更高级的设置，如**数据集数据粒度设置**。
### 数据集数据粒度{#dataset-granularity}
数据集数据粒度表示一个数据集查询返回的结果集的最细粒度，有**单行**、**单主键**和**普通数据集**三种，可以右键数据集**设置**>**高级**中进行设置，系统提供如下设置项：
- **自动时别**：默认为**自动识别**，表示会根据当前表自动判断数据集类型
- **单行**：返回数据结果只有一行并不一定就是单行数据集，单行数据集是对结果集的一种确定性约束，不论数据行数如何变化，结果都只会有一行，比如按照模型的所有主键字段过滤，则就是单行结果集，如果对所有数据汇总那么也会是单行结果集，但如果使用某个过滤条件导致数据此时是只返回一行数据，但是随着来源数据的变化有可能返回不是一行，那么这不能称之为单行数据集。单行结果集是一种根据模型的主键或者加工的逻辑理论上推测出来的返回结果最多只有一行的结果集。
- **单主键**：指数据集只有一个字段作为逻辑主键，当为**单主键**类型时，需要设置**主键字段**
:::tip
**单行**和**单主键**是特殊情况，有时候比较复杂，无法自动识别，需要手动设置类型
:::
## 数据集字段管理{#field-management}
系统提供数据集的字段管理，比如可以[新建计算字](#calc-field)、[创建分组字段](#calc-group-field)等等。
### 数据集字段列表{#dataset-list}
数据集引入后，系统会自动解析数据集结构。解析后，会将数据集中的**维度**、**度量**这些数据集字段分为两部分展示出来。同时系统也会提供**度量名称**、**字段名称**、**度量值**和**总行数**这四个系统字段。
- 度量名称：维度字段，记录模型表中的所有维度字段，通常与**度量值**一起配合使用
- 字段名称：维度字段，记录模型表中的所有字段，通常结合[输入控件](../data-viz/dash/components/input/README.md)进行数据过滤
- 度量值：度量字段，记录模型表中的所有度量字段，通常与**度量名称**一起使用，返回的是对度量值的sum值。
- 总行数：度量字段，模型表中的数据总行数
### 新建计算字段{#calc-field}
当数据集中已有的字段无法满足用户所需，需要根据已有的字段构造出的新的字段时，可以使用新增计算字段方式实现。新增计算字段的操作方式和**数据模型**上的一致，参考文档[新增计算字段](../data-process/transform/calc-field.md)。新增计算字段的方式有两种：
| 方法一 | 方法二 |
| :--------: | :--------: |
|  |  |
1. 点击**数据栏**>维度行旁边的**箭头**>**新增计算字段**，在编辑框中通过函数、参数等构造新的字段
2. 选中某一字段，右键选择**创建**>**计算字段**，此时编辑框中会出现选中的字段，可在该字段的基础上构造新字段
### 创建分组字段{#calc-group-field}
如需对某一维度的数据按不同类型进行划分，可通过创建分组的方式，右键点击对应的维度字段，选择**创建**>**分组**，创建分组的操作方式和数据模型上的一致，参考文档[创建分组字段](../data-process/transform/calc-group-field.md)。
### 创建分段字段{#calc-section-field}
如需对某一度量的数据按不同范围进行划分，可通过创建分段的方式，右键点击对应的度量字段，选择**创建**>**分段**，创建分段的操作方式和数据模型上的一致，参考文档[创建分段字段](../data-process/transform/calc-section-field.md)。
### 设置字段属性{#field-properties}
数据集列表中可以针对不同字段设置不同的属性，比如：[地理角色](#set-geo)、[显示格式](#set-display-format)、[聚合方式](#set-sum)等等。
### 设置地理角色{#set-geo}
todo
### 设置显示格式{#set-display-format}
用于设置数据在组件中的显示格式，比如设置为显示整数、百分比等。右键点击字段，选择**显示格式**中进行设置，参考文档[显示格式](../data-viz/dash/design/data/displayformat.md)。
### 设置合计方式{#set-sum}
系统提供了部分常用的合计方式，通过选择相应方式即可便捷对数据进行合计，如计数、平均值、最大值、最小值等。右键点击**度量字段**>**合计**，选择对应的合计方式即可，当字段拖入控件中后，数据会以选择的合计方式进行合计。
### 设置汇总方式{#set-group}
系统提供了部分常用的汇总方式，用于在[表格控件](../data-viz/dash/components/table/README.md)中求合计值时对数据的汇总。通过选择相应方式即可对数据快速进行合计、最大值等计算。右键点击**度量字段**，选择**汇总方式**即可。
### 替换字段引用{#replace-field}
当数据集发生调整，需要将某个字段的引用全部修改为新增字段时，可以使用替换字段的方式一键替换所有该字段的引用。比如右键点击【色系】，选择**替换引用**，在弹出框中选择【价格档次】，点击确定，控件中【色系】就会被替换为【价格档次】。
## 数据集管理{#dataset-management}
### 查看引用{#view-references}
系统提供追溯字段是否被引用的的功能，提供两种查看引用的方式：
| 指定字段引用 | 数据集字段引用 |
| :--------: | :--------: |
|  |  |
1. 指定字段引用：查看数据集中指定字段的引用关系。右键指定字段，选择**查看引用**即可查看当前字段是否被页面中组件引用。
2. 模型集字段引用：查看数据集中所有字段是否被引用。右键指定数据集，选择**查看引用**即可查看当前数据集中所有字段的引用情况。
### 设置别名{#rename}
为数据集重命名，右键点击数据集，选择**设置别名**，在对话框中输入名称即可。当修改别名后，组件中的字段引用的数据集或字段名称会同步修改。
### 替换已有数据集{#replace-dataset}
若原有数据集被删除或因为需求变更等原因不再使用时，可以重新选择其他数据集进行替换。右键点击数据集，选择**重新选择**，在弹出框中选择新的模型，新选择的模型会替换原有模型，组件中所使用的原数据集字段也会替换为新数据集中所对应的字段。
- 保留设置内容（过滤条件、计算字段）：勾选后，可以保留原有数据集上的过滤条件和计算字段，默认勾选
::: tip
若某些数据字段只存在于原数据集中，那么替换后引用这些数据字段的控件会提示相应字段不存在
:::
### 刷新模型{#refresh-dataset}
制作可页面的过程中，若所使用的数据集的结构发生了修改，可以通过右键点击数据集，选择**刷新**来刷新数据集、同步修改。
### 克隆数据集{#clone-dataset}
克隆数据集会复用原数据集的所有操作，包括新建的计算字段、过滤条件、字段显示方式等，右键点击数据集，选择**克隆**即可克隆该数据集，克隆数据集的命名规则是在原数据集名字的后面加数字，数字从1开始依次累加，比如**销售明细表**第一次克隆产生的新表为**销售明细表1**，第二次克隆产生的新表为**销售明细表2**，克隆后的模型支持[设置别名](#rename)。
### 删除数据集{#delete-dataset}
右键点击数据集，选择**删除**，如果该数据集没有被使用到，则会直接删除。如果有组件引用了该数据集，则会弹出提示框显示当前页面中有哪些组件引用了当前数据集。
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/faq"
title: "常见问题"
---
---
order: 9
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/howto-custom-data-role.md"
htmlUrl: "https://docs.succapp.com/v5/howto/ef90c932"
title: "如何配置数据角色"
---
---
order: 1
---
# 如何配置数据角色
数据角色，也叫字段角色，是对数据概念的业务归类，比如“日期"、"手机号码”，“身份证号”。
用户可以将自定义角色添加到[自定义字段角色表](https://demo.succbi.com/v5/sysdata/data?:open=dTacAXC52LCmEn3p3IIKbB)(/sysdata/data/tables/dw/DW\_FIELD\_CUSTOM\_ROLES.tbl)，表中定义的属性是系统内置属性，设置之后会在系统中自动发挥作用，包括：
1. 数据脱敏，用户设置了该角色，且包含这个属性，所有明细查询都会自动返回数据脱敏后的结果。
2. 是否合法，业务模块在过滤时可以作为过滤条件进行过滤。
3. 数据校验信息，数据校验不合法时可以在界面上提示用户。
4. 是否匹配，搜索时可根据该属性判断是否要搜索这个字段。
5. 是否为空。
除此之外，用户可以定义个性化的属性在角色的关联维表中，这些属性可以在表达式和过滤条件中使用，使用方法和维项表达式相同。
元数据格式即维表的json结构，需要添加主键作为映射字段名，同时添加自定义计算字段，这些计算字段可以作为属性在模型中使用，可以是有实体的维表，也可以是个虚拟维表。
下面以一个身份证号的字段角色作为例子：
```json
{
"version": "4.0.0",
"properties": {
"modelDataType": "App",
"primaryKeys": ["ID"]
},
"dimensions": [{
"name": "ID", // 主键必需，其他属性可以用这个主键进行表达式判断
"dataType": "C",
"length": 20,
"decimal": 0,
"isDimension": true,
"isPrimaryKey": true,
"originalField": "ID"
}, {
"name": "数据脱敏", // 设置了这个属性，查询明细数据时会自动返回脱敏后的结果
"dataType": "C",
"length": 50,
"decimal": 0,
"isDimension": true,
"originalField": "MASK",
"exp": "CONCAT(LEFT([ID], 3), '****', RIGHT([ID], 4))"
}, {
"name": "是否合法",
"dataType": "I",
"length": 2,
"decimal": 0,
"isDimension": true,
"originalField": "ISVALID",
"exp": "IF(LEN([ID])=18 or LEN([ID])=15, 1, 0)" // 表达式可以自定义修改
}, {
"name": "是否为空",
"dataType": "I",
"length": 2,
"decimal": 0,
"isDimension": true,
"originalField": "ISNULL",
"exp": "[ID] is null"
}, {
"name": "数据校验信息",
"dataType": "C",
"length": 64,
"decimal": 0,
"isDimension": true,
"originalField": "AUDITMSG",
"exp": "'身份证号不合法'"
}],
"measures": []
}
```
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/howto-custom-field-property.md"
htmlUrl: "https://docs.succapp.com/v5/howto/156a72ff"
title: "如何使用字段的自定义属性"
---
---
order: 2
---
# 如何使用字段的自定义属性
模型的字段属性应该要具备一定的扩展能力，能够按照用户自己的需求给字段添加设置属性，方便用户对模型的使用。例如：需要给字段添加一个属性“业务含义”，以便知道该字段的具体业务。
设置自定义属性的主要步骤：在系统字段表上添加字段，即为新增的字段自定义属性；这些新增的属性会展示在模型的字段列表中，手动编辑即可设置字段的自定义属性
## 设置方法
1. 添加自定义属性：**系统数据**>**字段模型表**>**编辑**>**增加列**，增加自定义属性字段：【数值型自定义属性】、【字符型自定义属性】、【日期型自定义属性】、【有关联维表的属性】
2. 选择模型表，如**QYFR\_ZWLX**，在**数据面板**>**字段列表**，对自定义属性列进行查看
3. 编辑自定义属性。数值型属性支持输入数值，字符型属性支持输入字符，日期型属性支持下拉框选择日期，有关联维表的属性支持下拉框选择维表字段。
1. 数值型自定义属性：输入**123**
2. 字符型自定义属性：输入**字符属性**
3. 日期型自定义属性：下拉选择日期为20200212
4. 有关联维表的属性：下拉选择维表字段【资源id】
4. 保存后，系统字段表会更新字段的自定义属性。
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/howto-custom-model-property.md"
htmlUrl: "https://docs.succapp.com/v5/howto/dd4d6634"
title: "如何设置模型的自定义属性"
---
---
order: 3
---
# 如何设置模型的自定义属性
模型的属性应该要具备一定的扩展能力，能够按照用户自己的需求给模型添加设置属性，方便用户对模型的使用。例如：需要给模型添加一个属性“模型业务描述”，以便知道模型的具体业务意义。
设置自定义属性的主要步骤：在数据表信息表上添加字段，即为新增的模型自定义属性；这些新增的属性会展示在模型的属性列表中，手动编辑即可设置模型的自定义属性
## 设置方法
1. 添加自定义属性：**系统数据**>**数据表信息表**>**编辑**>**增加列**，增加自定义属性字段：【数值属性】、【字符属性】、【日期属性】、【时间属性】、【带维表的属性】
2. 选择模型表，如**QYFR\_JYZT**，在**数据面板**>**属性列表**>**展示自定义属性**对自定义属性列进行查看
3. 编辑自定义属性。数值型属性支持输入数值，字符型属性支持输入字符，日期型属性支持下拉框选择日期，有关联维表的属性支持下拉框选择维表字段。
1. 字符属性：输入**字符属性**
2. 数值属性：输入**123**
3. 日期属性：下拉选择日期为20200218
4. 时间属性：下拉选择日期为15:08:26
5. 带维表的属性：下拉选择维表字段【计划id】
4. 保存后，系统数据表信息表会更新模型的自定义属性。
## 模型的自定义属性如何支持单选框和多选框
1. 添加字段的拓展属性showType：**系统数据**>**字段模型表**>**编辑**>**增加列**，增加字段：【showType】
2. **系统数据**>**数据表信息表**>**字段列表**，设置模型自定义属性字段【性别】和【服装类型】的showType和关联维表。
模型的自定义属性有关联维表时，会根据showType决定用什么控件展示属性
1. 为空或"combobox"： 下拉框
2. "selectpanel"： 单选框
3. "checkbox"： 多选框
4. 选择模型表，如**QYFR\_JYZT**，在**数据面板**>**属性列表**>**展示自定义属性**对自定义属性列进行查看
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/howto-disable-query-cache.md"
htmlUrl: "https://docs.succapp.com/v5/howto/da897d15"
title: "如何禁用模型查询的缓存"
---
---
order: 4
---
# 如何禁用模型查询的缓存
为了有更好的数据查询性能，在仪表板、报表等对象中查询模型表数据的时候会自动缓存已经查询过的数据。
当侦测到模型表的数据发生变化时（如重新提取了数据、使用报表填报应用修改了数据……）SuccBI会自动查询最新的数据。但是当使用系统外的工具修改了数据时（如直接使用数据库工具用SQL修改了表数据）那么SuccBI不会侦测到数据的变化，此时可以在系统设置中清空Query缓存，也可以通过本文的方法禁用模型的查询缓存功能。
禁用模型缓存后，用户查看报表、仪表板等等需要数据的页面时系统都会用SQL直接找数据库查询，不会提供应用层的缓存了。
## 数据模型禁用缓存{#global}
模型属性提供了禁用模型缓存的属性，勾选后，将直接向数据库查询最新的数据而忽略已缓存的内容，设置方法如下：
进入数据表模型界面，切换到**模型属性**选项页，勾选**禁用查询缓存**。更多关于该属性的说明可以查看文档[禁用模型缓存](../model/model-settings.md#disable-model-cache)。
## 页面禁用缓存{#page}
模型上的禁用缓存设置是全局的，如果只希望某个查询页面总是查询数据库中最新的数据，则可以在单个页面中设置禁用缓存，以SuperPage设计器为例，设置方法如下：
在设计器的数据列表里选中模型，右键选择**设置**，在弹出的对话框切换到**高级**选项页，设置**查询缓存**为`禁用`。
---
url: "https://docs.succapp.com/v5/guide/data-gov/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/data-gov/errcode"
title: "数据管理错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 数据管理错误提示排查
## 模型配置
### 缺少一致性维度{#err-dw-noConformedDim}
**可能原因：**
当一个模型的维度条件，期望作用到目标模型时，如果目标模型存在相同维度，则此条件会直接用目标模型维度字段进行过滤。如果目标模型不存在此维度，且两个模型也没有定义关联关系时，则会提示缺少一致性维度。
**解决方法：**
1. 确认目标模型上是否存在相同维度的字段，该字段是否设置了和条件中模型字段相同的维表。
2. 如果确实没有一致性维度字段，条件又期望作用，则需要将两个表关联起来。
---
url: "https://docs.succapp.com/v5/guide/data-viz/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-viz"
title: "可视化"
---
---
description: SuccBI的数据分析和可视化功能的使用帮助，包括仪表板、图分析等
order: 7
navTitle: 可视化
---
# 可视化
!!!children (guide/data-viz) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash"
title: "仪表板概述"
---
---
order: 1
navTitle: 仪表板
indexTitle: 仪表板概述
---
# 仪表板概述
SuccBI提供了自助式仪表板，可轻松完成数据的可视化分析。
- [极致易用，10分钟制作美观仪表板](#极致易用10分钟制作美观仪表板)
- [炫酷的可视化大屏展示](#炫酷的可视化大屏展示)
- [丰富的交互体验，快速洞察数据](#丰富的交互体验快速洞察数据)
- [手机、平板和电脑自适应显示](#手机平板和电脑自适应显示)
- [无失真导出ppt](#无失真导出ppt)
- [高性能并行计算引擎](#高性能并行计算引擎)
## 极致易用，10分钟制作美观仪表板
提供易用的所见即所得的仪表板设计器，用户通过拖拉拽等操作方式，10分钟制作美观仪表板。
## 炫酷的可视化大屏展示
仪表板提供了柱形图、线性图、KPI指标、饼图、地图等丰富的可视化组件，用户通过拖入组件即可快速实现比较美观的可视化效果，更多个性化的图形可以通过扩展的方式快速支持。
仪表板提供了丰富的，经过精心设计的主题模板，且支持主题风格和模板的便捷切换，用户可借此实现美观的视觉效果。
可以将仪表板发布到多终端，包括手机、平板等，方便用户随时随地方便查看分析结果。
## 丰富的交互体验，快速洞察数据
用户使用仪表板可以方便定义钻取、过滤、高亮等交互式操作，让数据灵动起来，加快从数据中提取有效信息，辅助业务决策。
## 手机、平板和电脑自适应显示
SuccBI提供了多设备模拟器，可以通过更改预览设备快速模拟仪表板在不同设备上的展示效果。能做到自适应各类终端设备，包括手机、平板和大屏等。
## 无失真导出ppt
SuccBI支持将仪表板的内容无失真导出ppt，不会丢失页面风格、色彩，且能确保图片、文字等内容的缩放效果。
## 高性能并行计算引擎
SuccBI采用并发内存计算架构，借助高速内存、聚集导航等，能够极速呈现海量数据的分析结果。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/new-dash.md"
htmlUrl: "https://docs.succapp.com/v5/dash/new-dash"
title: "新建仪表板"
---
---
order: 2
---
# 新建仪表板
新建一个仪表板的步骤如下：
1. 进入项目的**分析**模块，点击**新建**，选择**仪表板**
2. 在新建对话框中可以选择内置的大屏模板，也可以选择空白模板，进入[仪表板设计器](./designer.md)界面
3. 接下来点击左上角**数据**按钮添加数据模型，然后在页面中拖入组件进行布局和编辑
4. 最后点击**保存**，在命名对话框中输入合适且有意义的名称，选择保存的父目录即可
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/designer.md"
htmlUrl: "https://docs.succapp.com/v5/dash/designer"
title: "仪表板设计器界面介绍"
---
---
description: 仪表板设计器
order: 3
navTitle: 仪表板设计器
---
# 仪表板设计器界面介绍
仪表板设计器是一个所见即所得的进行数据分析和可视化的工具，仪表板设计器界面如下图所示：
可以将其划分为如下几个区域：
1. **组件区**：提供了丰富的可视化组件，如表格、图形、输入组件等，可以使用拖拽的方式从组件下拉面板中将组件快速添加到画布
2. **数据源**：数据源区域列出了可以用于可视化分析的可用数据模型，也可以添加数据模型、添加表内数据加工、定义模型间的关联关系、增加计算字段、删除数据模型等
3. **属性栏**：显示画布中当前选中组件的可配置属性，包括：当前组件、样式、交互等
4. **画布**：画布是可视化组件布局的区域，可以在画布中添加任意组件，并通过拖拽的方式，任意布局组件的位置
5. **工具栏**：工具栏中提供的是对仪表板的全局设置，如缩放、视图等
## 设计器快捷键{#shortcut-keys}
设计器快捷键：
| 功能 | Windows/Linux | macOS |
| ---------- | :---- | :---- |
| 剪切 | `Ctrl + X` | `Command + X` |
| 复制 | `Ctrl + C` | `Command + C` |
| 粘贴 | `Ctrl + V` | `Command + V` |
## 查看引用{#view-reference}
使用查看引用可以快速查看以及定位当前模型表、组件或参数在页面中被引用的地方。在设计器中，选中模型表或组件，点击鼠标右键，在弹出的菜单中选择**查看引用**选项即可查看引用列表，点击内容，可定位到对应组件或数据源，如下所示：
设计器中支持查看引用的内容如下：
- **数据模型查看引用**：可以查看模型或字段被哪些组件属性引用
- **组件查看引用**：可以查看选中组件被其他组件或数据源引用情况
- **参数查看引用**：可以查看引用该参数的组件或数据源列表
### 快速修改引用错误{#modify-reference-errors}
删除被引用的模型表、组件以及参数时，会弹出引用该内容的列表，当强制删除后，被引用的地方出现报错。同时右上角信息处会显示错误提示，点击可快速定位错误，也就是删除内容被引用的地方。
## 调整组件图层{#adjust-layer}
在制作仪表板过程中，同一个区域中拖入较多组件会存在组件之间互相覆盖情况，可通过**选中组件**>**右键菜单**>**排列**，点击**上移一层**、**下移一层**等选项去调整组件图层层次的顺序，上层的组件会覆盖下面的组件。具体可操作选项如下：
- **上移一层**：将组件在图层中向上移动一层
- **下移一层**：将组件在图层中向下移动一层
- **置于顶层**：将组件置于图层最上面一层
- **置于底层**：将组件置于图层最下面一层
:::tip 技术原理
- 这里的**图层**，对应`z-index`属性
- [固定宽度](./design/layout/README.md#fixwidth)布局是一种流式布局，如果需要调整组件在图层中的顺序，则需要组件**脱离网格**
:::
## 组件大纲树{#outline-tree}
在设计器中拖入组件制作内容时，会依据拖入顺序以及包含关系自动生成组件大纲树，点击右上角**视图**即可查看。借助大纲树有以下优点：
- 快速定位组件在画布中的位置
- 能清楚看到组件之间的包含关系，快速调整布局
- 右键弹出菜单可对其进行快捷操作
## 快速预览{#query}
仪表板的[组件](./components/README.md)每次取数时，都会发起一次数据的查询请求，当数据量较大时，一定程度上会影响**编辑**仪表板时的性能，通过启用快速预览，在**工具栏**>**视图**>**快速预览**中设置，启用**快速预览**限制查询的数据行数，即限制仪表板**设计器**查询数据时，最多只能查询5000行数据：
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/components"
title: "仪表板组件"
---
---
order: 4
navTitle: 仪表板组件
---
# 仪表板组件
仪表板提供了丰富的组件，使用拖拉拽的方式可以快速实现美观可视化效果：
!!!children (guide/data-viz/dash/components) 3 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/layout/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/layout"
title: "布局组件"
---
---
order: 1
navTitle: 布局
---
# 布局组件
仪表板提供了多种布局组件，可以拖入仪表板中的任何组件到布局组件中，用于仪表板的快速布局：
!!!children (guide/data-viz/dash/components/layout) 1 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/layout/panel.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component-panel"
title: "仪表板组件-面板"
---
---
order: 1
navTitle: 面板
---
# 仪表板组件-面板
面板是用于放置其它组件的布局组件，可以任意组合组件形成一个数据卡片。如展示全国的折扣率以及相关指标内容：
## 使用面板组件{#start}
面板操作步骤如下：
1. **选择面板组件：** 将**布局**>**面板**组件拖入到画布中
2. **将组件拖入到面板中：** 将环形占比图，文本组件和KPI组件分别从组件区拖入到面板中，并根据拖入组件所展示内容进行适当位置调整：
- 环形占比图的取数和样式设置参考[环形占比图](../chart/percentring.md)文档
- KPI取数参考[KPI](../chart/kpi.md)文档
- 文本组件设置参考[文本](../more/text.md)
## 属性介绍{#properties}
### 网格{#grid}
布局组件内部是由一个个“网格”组成的，行数和列数决定了有多少个“网格”，网格的尺寸决定了仪表板组件移动的最小值。可以理解为在仪表板组件不脱离网格前提下，使用鼠标移动仪表板组件一次的距离就是一个“网格”的距离。
布局组件的网格同画布网格的设置及功能是一致的，用于设置组件内的行数和列数，以及行列间距，从而达到布局的功能。网格的设置可以在面板组件的**样式**>**网格**中进行设置，具体操作可以参考[布局组件](./README.md)文档。
### 条件样式{#condition-style}
当面板自身需要标注或者动态改变外观时，可在**样式**>**组件**处设置条件样式，如突出显示、悬停、选中和按下。具体操作可参考[条件样式](../../design/type/condition-style.md)文档。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/layout/panelbook.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/panelbook"
title: "仪表板组件-多页面板"
---
---
order: 2
navTitle: 多页面板
---
# 仪表板组件-多页面板
多页面板可以根据需求新增多个面板页面，每一页面板都可以任意组合组件形成一个数据卡片，一般与选项卡配合使用，同时只能显示一页面板的内容。如使用选项卡切换疫情指标，展示选中指标随时间的变化趋势：
示例地址：[多页面板](https://demo.succbi.com/v5/bi/tabs)
## 使用多页面板组件{#start}
多页面板用于多页面展示相关业务，通常配合标签页切换页面展示。以标签页demo中的按事件源序号来切换多页面板为例，如下是操作步骤：
1. **将多页面板组件拖入到画布中：** 将**布局**>**多页面板**组件拖入到画布中
2. **添加面板页面：** 选中上一步拖入的多页面板组件，在该组件右上角下拉列表中点击添加，点击两次即可。由于拖入的面板默认提供了两个面板页，所以这里只需要再添加两个。这里的四个页面分别展示疫情四个指标（确诊、疑似、治愈、死亡）随时间变化趋势
3. **每个面板页面填充内容：** 选中组件右上角下拉分别依次选中对应面板页面设置内容，可以参考[面板](./panel.md)：
- 折线图的取数和样式设置参考[折线图](../chart/line-chart.md)
- 标签页的设置参考[标签页](../input/tabbar.md)
## 属性介绍{#properties}
### 默认页{#default}
默认页，即第一次查看时显示的面板页面。选中多页面板组件，键盘上按一次ESC键，可以设置**默认页**内容。提供了两种设置方式：
- **选择固定值：** 点击下拉框的箭头，在下拉列表中选择需要默认显示的页面
- **动态显示默认面板：** 点击下拉框的箭头，编辑条件进行动态显示。动态值支持写面板名称或序号，例如根据用户所在用户组决定显示哪个页面。名称表达式为
`IF([用户].[部门]=[用户组名],'panel1','panel2')`。序号从1开始，序号表达式为`IF([用户].[部门]=[用户组名],'1','2')`。
### 名称{#name}
面板页面的名称，可以修改。切换到需要修改名称的面板页面，在**面板**>**高级**>**名称**重命名，名称是唯一的，不能重复。
### 面板页面管理{#manage}
多页面板的添加，删除，复制和移动面板页面功能，选中多页面板，在左侧组件菜单中进行相关操作。
#### 添加{#add}
添加新的面板页面，点击左侧菜单中的添加按钮，即可添加一个新的面板页面。新的面板页面的命名是根据系统中生成的页面顺序自动在panel后面+1，且名称是当前面板中唯一的。
#### 删除{#delete}
删除选中页面，点击左侧列表选中页面后面的删除按钮，即可删除当前选中页面，可以通过撤销键撤销此操作。
#### 复制{#copy}
复制选中页面，点击左侧页面后面的复制按钮，即可复制当前选中页面。复制的页面的命名是根据系统中生成的页面顺序自动在panel后面+1，且名称是当前面板中唯一的，并排序在所复制页面的后面。
#### 移动{#move}
移动选中的页面，鼠标左键按住页面前面的移动按钮，将其移动到期望位置。
### 样式{#style}
多页面板可以整体设置多页面板风格，每个子面板也可以单独设置容器风格
::: tip
当多页面板中的面板没有被组件占满时，点击面板的空白处即选中多页面板，此时多页面板的右上角处会出现页面管理菜单，点击下拉框箭头即可进入。再按一次ESC键可以进入到多页面板的**默认页**编辑处。
如果多页面板中的面板被组件占满时，点击面板中的组件时，此时需要按一次ESC键才能返回到多页面板的页面管理菜单，点击下拉框箭头即可进入。再按一次ESC键可以进入到多页面板的**默认页**编辑处。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/layout/floatpanel.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/floatpanel"
title: "仪表板组件-浮动面板"
---
---
order: 3
navTitle: 浮动面板
---
# 仪表板组件-浮动面板
浮动面板可以根据数据浮动出多个面板来，面板横向排列并可以自动绕排，形成一个个数据卡片，如下图：
示例地址：[浮动面板](https://demo.succbi.com/v5/bi/floatpanel)
| 单指标浮动 | KPI+环形图组合浮动 |
| :---------| :-------- |
|  |  |
## 使用浮动面板组件{#use}
浮动面板是根据维度的维项个数浮动出多个子面板，再在子面板中拖入组件进行使用。以显示各价格档次的销售数量为例说明，如下是操作步骤：
1. 在布局中将仪表板拖入到画布中
2. 浮动区域的浮动维度取数：从数据模型中将【价格档次】字段拖入到**浮动面板**>**数据**>**字段**
3. 将图形组件拖入到子面板：将KPI组件拖入到浮动面板的子面板中，再将【销售数量】字段拖入到KPI组件中，具体操作可参考[KPI](../chart/kpi.md)文档完成取数，子面板布局调整可参考[面板](./panel.md)
## 属性介绍{#attribute}
### 组成部分{#component}
浮动面板是根据维度的维项个数浮动出多个子面板，包括：
- 子面板：子面板中可以拖入组件，进行展示。子面板的数量由浮动维度的**查询数据量**而定。子面板的功能与面板功能一致，具体可参考[面板](./panel.md)
- 浮动区域：浮动区域就是浮动面板容器，用于浮动子面板的容器组件
### 查询数据量{#query}
查询数据量，是用于控制子面板显示的个数，默认为10，和浮动出的数据量关系如下：
- 当浮动字段数据小于设置值时，查询的数据量按照浮动字段的数据量
- 当浮动字段数据大于设置值时，按照设置值进行查询
可以在**浮动面板**>**样式**>**高级**>**查询数据量**中进行设置。
### 内部布局{#inside}
选中浮动区域，拖入浮动字段至**数据**>**字段**，**浮动面板**>**样式**中会出现内部布局属性，用于设置子面板的布局方式等。当未拖入浮动字段时，此选项为隐藏状态，内部布局提供了五个属性设置，分别如下：
- 方向：设置子面板排列方向。提供了两个选项包括纵向和横向。纵向表示纵向浮动子面板，横向表示横向浮动子面板
- 横向对齐：设置子面板横向对齐方式。提供了五个选项，包括左对齐、右对齐、居中、两端对齐、均匀分散
- 纵向对齐：设置子面板纵向对齐方式。提供了五种选项，包括拉伸、顶端对齐、底端对齐、居中、基线对齐（组件中第一行文字的基线对齐）
- 滚动条：设置子面板的滚动条，当子面板数量过多时，可以设置滚动条来进行显示
- 绕排：设置子面板的排列是否绕排。提供了两种选项，包括绕排、不绕排
::: tip
当浮动出的子面板占据空间位置超出了浮动面板的大小，建议设置绕排或者添加滚动条的方式，让超出部分绕排显示或者滚动方式查看。
:::
## 常见问题{#faq}
### 如何控制浮动出的子面板个数？{#how}
有两种设置方式，如下：
- 在**浮动面板**>**数据**>**过滤器**/**筛选器**中，设置数据过滤，控制浮动出的数据量，以此来控制子面板的显示数量
- 在**浮动面板**>**样式**>**高级**>**查询数据量**下设置查询数据的数量，以此来控制子面板的显示数量
其中**筛选器**的优先级大于**查询数据量**。
### 子面板布局技巧{#skill}
浮动面板中的组件布局可以参看[面板](./panel.md)进行布局。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/table/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/table"
title: "表格组件"
---
---
order: 2
navTitle: 表格
---
# 表格组件
仪表板提供了表格组件，表格是最常用的数据展示组件：
!!!children (guide/data-viz/dash/components/table) 1 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/table/columntable.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/columntable"
title: "仪表板组件-明细表"
---
---
order: 1
navTitle: 明细表
---
# 仪表板组件-明细表
明细表展示数据表中最细粒度的数据，显示的每条数据都对应于数据库表原始行的一条数据。如展示企业的基本信息：
示例：[明细表(企业基本信息表)](https://demo.succbi.com/v5/bi/%E6%98%8E%E7%BB%86%E8%A1%A8\(%E4%BC%81%E4%B8%9A%E5%9F%BA%E6%9C%AC%E4%BF%A1%E6%81%AF%E8%A1%A8\))
## 使用明细表组件{#start}
将需要展示的字段拖入到明细表中进行展示
**操作步骤**
1. 双击或拖入【统一社会信用代码】、【企业名称】、【法定代表人】等6个维度字段、和度量字段【实缴资本(万元)】到**数据**
2. 右键【成立日期】，选择[排序](../../design/data/data-sort.md)>，指定字段为【成立日期】，选择排序方式为**升序**
3. 在**基本**中，设置分页的每页行数
4. 可为明细表添加条件样式，设置[数据条](../../../../report/design/style/condition-style.md)，[突出显示](../../../../report/design/style/condition-style.md#highlight)和[色阶](../../../../report/design/style/condition-style.md#color-scale)等
通过上述4个步骤，即可快速实现企业基本信息并按照成立日期进行升序排列。
## 属性介绍{#properties}
明细表整体由几部分组成，每一个部分属性都是需要独立设置，大致区域划分如下图：
根据各个区域的属性不同，又分为
- [组件属性](#table-properties)
- [分页栏](#paging)
- [标题行](#header-row)
- [数据行](#data-row)
- [数据列](#datas-column)
## 组件属性{#table-properties}
设置表格通用样式和属性等，如分页、布局、冻结线、边框样式等。
组件属性大致分为：
- [序号列](#number)
- [列头排序](#sort)
- [滚动](#roll)
- [冻结](#freeze)
- [行高/列宽](#rowheight-columnwidth)
- [边框](#border)
### 序号列{#number}
明细表提供默认显示序号的功能，通过序号列可以让用户更好判断当前明细表页面展示的数据数量，以及帮助用户更好区分不同行数据之间的差异。
勾选**明细表**>**基本**>**显示序号**即可自动展示序号，默认不勾选。
在**样式**>**表格**>**序号列**中，可以调整明细表的序号列的样式。具体如下：
- **标题**：设置序号列标题内容和序号的显示格式，可参考[显示格式](../../design/data/displayformat.md)
- **字体**：设置明细表的数据行字体，包括**字体**、**字号**、**位置**
- **单元格填充**：统一设置明细表数据行每个单元格的背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **背景填充**：设置整个序号列的背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **内边距**：设置明细表序号列的内边距，可参考[内边距](../../design/type/basic/padding.md)
- **列宽**：设置明细表序号列的宽度，提供**自适应**和固定值两种宽度大小
- **伸缩**：序号列会根据数据内容，进行自适应伸缩，伸缩的大小会根据**宽度范围**的值进行限制。**伸缩**提供**是**、**否**和**自定义**三种选项
- **宽度范围**：限制序号列的伸缩宽度，当**列宽**选择了固定值时，**宽度范围**的最大默认值默认为**列宽**选择的固定值（支持手动修改）。
- **空间剩余时，按比例放大**：当**伸缩**选择为自定义时，可以设置数据内容的单元格存在空余空间时，按照多大的比例进行放大
- **空间不足时，按比例缩小**：当**伸缩**选择为自定义时，可以设置数据内容的单元格空间不足时，按照多大的比例进行缩小
::: tip
序号列无法参与条件样式的设置，如果需要将序号列设置成不同的样式，可以在模型中新增一个排序字段，将排序字段拖入到明细表中后，针对这个排序字段进行相关条件样式设置。
排序表达式参考如下：
- [RANK](../../../../exp/func/analysis/RANK.md)：返回排序字段值的标准竞争排名
- [RANK\_DENSE](../../../../exp/func/analysis/RANK_DENSE.md)：返回排序字段值的密集排名
- [RANK\_MODIFIED](../../../../exp/func/analysis/RANK_MODIFIED.md)：返回排序字段值调整后的竞争排名
- [ROW\_NUMBER](../../../../exp/func/analysis/ROW_NUMBER.md)：返回排序字段值的唯一排名
:::
### 列头排序{#sort}
列头排序是能够根据某列的内容对表格数据进行排序。
勾选**明细表**>**基本**>**点击列头排序**，即可在列表中点击任意列头进行排序，可选**升序**和**降序**两种默认排序方式，默认勾选**升序**排序。
同时勾选**明细表**>**基本**>**允许无排序**，可以在列头点击排序后，切换到无排序效果，默认不勾选。
### 滚动{#roll}
明细表本身是自带纵向滚动条的。但是当页面需要放置在大屏上展示时，此时由于无法人为在大屏上进行键鼠操作，所以明细表的内容应该进行自动滚动展示数据。
勾选**明细表**>**基本**>**自动滚动**，即可自动将明细表内容滚动显示，默认不勾选。
### 冻结{#freeze}
在查看明细表时，尝尝会遇到列数很多、很宽的明细表。在屏幕无法显示全部自动列时，为了浏览不能显示的字段列，需要使用横向滚动条。但是使用横向滚动条，则会造成明细表最前面的主要字段尤其是关键字段无法看到，从而影响了数据的查看。同时数据行过多时，使用纵向滚动条也会导致无法查看字段列名进行区分，那么通过明细表的冻结功能即可解决上诉问题。
### 冻结列{#freezing-columns}
勾选**明细表**>**基本**>**冻结列**，即可设置明细表的冻结列，也可以在**列数**中设置冻结的列数，默认不勾选。冻结线样式需要在**样式**>**组件**>**冻结线**中调整。
### 冻结行{#freeze-rows}
明细表设置的冻结行后，将会将标题行冻结。纵向滚动时，标题行将滚动不跟随滚动条进行滚动。
在**样式**>**组件**>**冻结线**中设置冻结线后，明细表会自动添加一个标题行的冻结线。如果需要设置冻结列，需要再回到**基本**>**冻结列**中进行设置。
### 行高/列宽{#rowheight-columnwidth}
**布局**中可以对明细表所有列和行先进行统一的样式设置，包括**列宽**、**行高**、**自动撑大行高**等属性，具体如下：
- 列宽：即设置每列的宽度
- 等分列宽：即每列宽度一致，为等分表格组件的宽度
- 适应内容：即根据文字长度与文字大小撑大列宽
- 行高：即设置每行的高度
- 适应容器：即每行高度等分表格的高度
- 适应内容：即高度根据文字大小的倍数设置，单位为px，输入大于0的数字即可
- 自定义：自定义**标题行高**和**内容行高**，单位为px，输入大于0的数字即可
- 自动撑大行高：根据内容自动撑大数据行高度
- 允许用户调整列宽：勾选后，用户可以在查看页面自定义拖拽调整每列的列宽
- 自动调整组件高度：根据当前数据总行数的数量，自动调整组件的高度
### 边框{#border}
明细表的边框分为**组件边框**、**表格外框**和**网格线**三部分组成.
具体设置如下：
- **组件边框**：设置明细表组件的外边框，可以设置边框位置和线型。具体可参考[边框](../../design/type/basic/border.md)
- **表格外框**：设置明细表表格的外框，可以设置边框的位置和线型。具体可参考[边框](../../design/type/basic/border.md)
- **网格线**：设置明细表表格内部直接的网格线，可以设置网格线的位置和线型。具体可参考[边框](../../design/type/basic/border.md)
## 分页栏{#paging}
当数据行较多时，可设置分页为显示，并通过分页栏进行翻页查看数据。
当**显示**分页时提供以下属性设置：
- 每页行数：设置表格每页显示的数据行数
- 位置：分页栏相对于表格的位置，可设置在表格的**顶部**或**底部**，默认为**底部**
- 对齐：设置分页栏在表格内的对齐方式，可选**居左对齐**、**居中对齐**、**居右对齐**、**两端对**齐，默认为**居中对齐**
- 页码样式：设置页码数字的样式，可选**无边框**、**方框**、**实心方框**，只有勾选**页码翻页**后才有此属性
- 页码翻页：默认勾选，勾选后可点击对应页码数字跳转到对应页。取消勾选后不会显示页码，只能通过**首页**、**上一页**、**下一页**或**末页**进行翻页
- 跳转翻页：勾选后会可通过页码输入框跳转到指定页，默认不勾选
- 显示总行数：显示数据总行数，默认勾选
## 标题行{#header-row}
明细表标题分为三种：
1. [组件标题](#component-title)
2. [标题行](#header-rows)
3. [列标题](#column-header)
### 组件标题{#component-title}
组件是指仪表板中每一个图形化功能的载体，它类似于是每个图形化功能的父容器，所以组件本身存在一些通用的属性，比如**组件标题**、**边框线**、**内边距**等
在**样式**>**标题**中可以设置标题的显示与隐藏，样式等。
设置明细表组件的标题样式，具体如下：
- **布局**：设置明细表标题是否显示，默认不勾选**显示**
- **字体**：设置组件标题字体，包括**字体**、**字号**、**位置**和**是否换行**
- **图标**：设置组件标题的前后缀图标
- **填充**：设置组件标题的背景填充，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **边框**：设置组件标题的边框样式，可参考[边框](../../design/type/basic/border.md)。默认无边框
- **内边距**：设置组件标题的内边距，可参考[内边距](../../design/type/basic/padding.md)。默认内边距为10px
- **阴影**：设置组件标题的文字阴影，可参考[阴影](../../design/type/basic/shadow.md)。默认无阴影
### 标题行{#header-rows}
在**样式**>**表格**>**标题行**中，可以调整明细表的标题行的样式。具体如下：
- **布局**：设置明细表的标题行是否显示，默认勾选**显示**
- **字体**：设置明细表的标题行字体，包括**字体**、**字号**、**位置**
- **单元格填充**：统一设置明细表标题行每个单元格的背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**颜色填充**
- **背景填充**：设置整个标题行的背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **横向填充**：以标题行的每个横向单元格为整体，进行横向的填充
- **纵向填充**：以标题行的每个纵向单元格为整体，进行纵向的填充
- **区域填充**：以标题行整体为单位，进行填充
| 纵向填充 | 横向填充 | 区域填充 |
| :---------| :-------- | :-------- |
|  |  |  |
- **内边距**：设置明细表标题行的内边距，可参考[内边距](../../design/type/basic/padding.md)。默认内边距为10px
### 列标题{#column-header}
在**样式**>**标题行**中，可以对每一列的标题行进行样式调整，具体如下：
- **字体**：设置具体列标题的字体，包括**字体**、**字号**、**位置**
- **自动换行**：当文字长度较长时，可设置换行显示，默认不勾选。勾选后行高会根据字体长度自动撑大
- **单元格填充**：设置明细表具体列的标题背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **内边距**：设置明细表指定列的内边距，可参考[内边距](../../design/type/basic/padding.md)
- **列宽**：设置明细表标题行的列宽，提供**自适应**和固定值两种宽度大小
- **分组标题**：针对多个列设置同一个**分组标题**，可以在被设置列的列标题上生成一个分组标题，具体如下：
- **还原默认设置**：将指定列的标题样式还原成默认设置
## 数据行{#data-row}
在**样式**>**表格**>**数据行**中，可以调整明细表的数据行的样式。具体如下：
- **字体**：设置明细表的数据行字体，包括**字体**、**字号**、**位置**
- **单元格填充**：统一设置明细表数据行每个单元格的背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **隔行换色**：勾选后数据行的背景将会奇偶行颜色各异显示，若**样式**>**数据行**>**单元格填充**设置了背景，这里设置的优先级大于**隔行换色**的优先级，然后**隔行换色**的优先级大于**样式**>**表格**>**数据行**>**单元格填充**的优先级
- **背景填充**：设置整个数据行的背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **横向填充**：以数据行的每个横向单元格为整体，进行横向的填充
- **纵向填充**：以数据行的每个纵向单元格为整体，进行纵向的填充
- **区域填充**：以数据行整体为单位，进行填充
- **内边距**：设置明细表数据行的内边距，可参考[内边距](../../design/type/basic/padding.md)
## 数据列{#datas-column}
在**样式**>**数据行**中，可以对每一列的数据列进行样式调整，具体如下：
- **字体**：设置具体列的数据内容字体，包括**字体**、**字号**、**位置**
- **单元格填充**：设置具体列的数据内容列的背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **背景填充**：设置具体列的数据内容列的背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **图标**：设置具体列的数据内容的前后缀图标，默认无图标
- **内边距**：设置具体列的数据内容内边距
- **合并单元格**：将具体列中相同内容的单元格进行合并
- **合并依据**：设置单元格合并的依旧，可以自定义合并依据
- **还原默认设置**：将指定列的数据列内容的样式还原成默认设置
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/table/grouped-table.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/grouptable"
title: "仪表板组件-分组表"
---
---
order: 2
navTitle: 分组表
---
# 仪表板组件-分组表
分组表可以将数据以分组的形式展现，展示各个分组的总体数据。如按照不同省份来展示全国的销售情况。
示例地址：[分组表(全国销售情况表)](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E5%85%A8%E5%9B%BD%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5%E8%A1%A8\))
## 使用分组表组件{#start}
根据需求将分组字段拖和指标字段拖入到分组表的**数据**区域即可。
**操作步骤**
1. 双击或拖入目标字段
2. 可为分组表添加条件样式，设置[数据条](../../../../report/design/style/condition-style.md#databar)，[突出显示](../../../../report/design/style/condition-style.md#highlight)和[色阶](../../../../report/design/style/condition-style.md#color-scale)等
通过上述2个步骤，即可快速为分组表进行取数。
## 属性介绍{#properties}
分组表整体由几部分组成，每一个部分属性都是需要独立设置，大致区域划分如下图：
根据各个区域的属性不同，又分为
- [组件属性](#table-properties)
- [分页栏](#paging)
- [标题行](#header-row)
- [数据行](#data-row)
- [数据列](#datas-column)
- [维度/指标](#dimension-target)
- [合计行](#total)
- [小计行](#subtotal)
## 组件属性{#table-properties}
设置表格通用样式和属性等，如分页、布局、冻结线、边框样式等。
组件属性大致分为：
- [序号列](#number)
- [列头排序](#sort)
- [滚动](#roll)
- [冻结](#freeze)
- [行高/列宽](#rowheight-columnwidth)
- [边框](#border)
### 序号列{#number}
分组表提供默认显示序号的功能，通过序号列可以让用户更好判断当前分组表页面展示的数据数量，以及帮助用户更好区分不同行数据之间的差异。
勾选**分组表**>**基本**>**显示序号**即可自动展示序号，默认不勾选。
在**样式**>**表格**>**序号列**中，可以调整分组表的序号列的样式。具体可参考明细表[序号列](./columntable.md#number)。
### 列头排序{#sort}
列头排序是能够根据某列的内容对表格数据进行排序。
勾选**分组表**>**基本**>**点击列头排序**，即可在列表中点击任意列头进行排序，可选**升序**和**降序**两种默认排序方式，默认勾选**升序**排序。
同时勾选**分组表**>**基本**>**允许无排序**，可以在列头点击排序后，切换到无排序效果，默认不勾选。
### 滚动{#roll}
分组表本身是自带纵向滚动条的。但是当页面需要放置在大屏上展示时，此时由于无法人为在大屏上进行键鼠操作，所以分组表的内容应该进行自动滚动展示数据。
勾选**分组表**>**基本**>**自动滚动**，即可自动将分组表内容滚动显示，默认不勾选。
### 冻结{#freeze}
在查看分组表时，尝尝会遇到列数很多、很宽的分组表。在屏幕无法显示全部自动列时，为了浏览不能显示的字段列，需要使用横向滚动条。但是使用横向滚动条，则会造成分组表最前面的主要字段尤其是关键字段无法看到，从而影响了数据的查看。同时数据行过多时，使用纵向滚动条也会导致无法查看字段列名进行区分，那么通过分组表的冻结功能即可解决上诉问题。
### 冻结列{#freezing-columns}
勾选**分组表**>**基本**>**冻结列**，即可设置分组表的冻结列，也可以在**列数**中设置冻结的列数，默认不勾选。冻结线样式需要在**样式**>**组件**>**冻结线**中调整。
### 冻结行{#freeze-rows}
分组表设置的冻结行后，将会将标题行冻结。纵向滚动时，标题行将滚动不跟随滚动条进行滚动。
在**样式**>**组件**>**冻结线**中设置冻结线后，分组表会自动添加一个标题行的冻结线。如果需要设置冻结列，需要再回到**基本**>**冻结列**中进行设置。
### 行高/列宽{#rowheight-columnwidth}
**布局**中可以对分组表所有列和行先进行统一的样式设置，包括**列宽**、**行高**、**自动撑大行高**等属性，具体可参考明细表[行高/列宽](./columntable.md#rowheight-columnwidth)。
### 边框{#border}
分组表的边框分为**组件边框**、**表格外框**和**网格线**三部分组成.
具体可参考明细表[边框](./columntable.md#border)。
## 分页栏{#paging}
当数据行较多时，可设置分页为显示，并通过分页栏进行翻页查看数据。具体可参考明细表[分页栏](./columntable.md#paging)。
## 标题行{#header-row}
明细表标题分为三种：
1. [组件标题](#component-title)
2. [标题行](#header-rows)
3. [列标题](#column-header)
### 组件标题{#component-title}
组件是指仪表板中每一个图形化功能的载体，它类似于是每个图形化功能的父容器，所以组件本身存在一些通用的属性，比如**组件标题**、**边框线**、**内边距**等
在**样式**>**标题**中可以设置标题的显示与隐藏，样式等。具体可参考明细表[组件标题](./columntable.md#component-title)。
### 标题行{#header-rows}
在**样式**>**表格**>**标题行**中，可以调整分组表的标题行的样式。具体可参考明细表[标题行](./columntable.md#header-rows)。
### 列标题{#column-header}
在**样式**>**标题行**中，可以对每一列的标题行进行样式调整。具体可参考明细表[列标题](./columntable.md#column-header)。
## 数据行{#data-row}
在**样式**>**表格**>**数据行**中，可以调整分组表的数据行的样式。具体可参考明细表[数据行](./columntable.md#data-row)。
## 数据列{#datas-column}
在**样式**>**数据行**中，可以对每一列的数据列进行样式调整。具体可参考明细表[数据列](./columntable.md#datas-column)。
## 维度/指标{#dimension-target}
分组表中的分组字段一般取自模型表中的维度字段，而指标则取自模型表中的度量字段。在**样式**>**表格**>**维度/指标**中，可以统一对维度列（分组字段列）和指标列进行样式调整。具体如下：
- **单元格填充**：设置维度/指标列的数据内容列的背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **背景填充**：设置维度/指标列的数据内容列的背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **内边距**：设置维度/指标列数据内容在单元格内与四周边框的内边距大小
## 合计行{#total}
在分组表中可以直接统计每一个指标列的数据，并单独生成一个**合计行**供用户参考。
其他设置如下：
- **显示**：设置分组表是否启用合计行，默认不启用
- **位置**：设置合计行显示位置，提供**底部**和**顶部**两个位置，默认**底部**
- **字体**：设置合计行的数据内容字体，包括**字体**、**字号**、**位置**
- **单元格填充**：设置合计行的数据内容背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **背景填充**：设置合计行的数据内容背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **内边距**：设置合计行的数据内容在单元格内与四周边框的内边距大小
## 小计行{#subtotal}
分组表中存在两个及两个以上分组字段时，可以启用**小计行**对每一个分组进行一次数据合计。
其他设置如下：
- **显示**：设置分组表是否启用小计行，默认不启用
- **位置**：设置小计行显示位置，提供**底部**和**顶部**两个位置，默认**底部**
- **字体**：设置小计行的数据内容字体，包括**字体**、**字号**、**位置**
- **单元格填充**：设置小计行的数据内容背景填充样式，填充方式包括**无填充**、**颜色填充**、**图片填充**和**动效填充**。默认**无填充**
- **背景填充**：设置小计行的数据内容背景填充，填充方式包括**无**、**横向填充**、**纵向填充**和**区域填充**。如果选择了填充方式，会自动显示背景填充选项，背景填充包括**无填充**、**颜色填充**和**图片填充**。默认填充方式为**无**
- **内边距**：设置小计行的数据内容在单元格内与四周边框的内边距大小
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/chart"
title: "图形组件"
---
---
order: 3
navTitle: 图形
---
# 图形组件
仪表板提供了丰富的图形组件，用户通过拖入图形组件可快速实现比较美观的可视化效果：
!!!children (guide/data-viz/dash/components/chart) 1 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/column-chart.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/column-chart"
title: "仪表板组件-柱形图"
---
---
order: 1
navTitle: 柱形图
---
# 仪表板组件-柱形图
柱形图是使用宽度相同的柱子的高度来表示数据多少，用于两个或以上的数值对比，进行比较各组数值之间的差别。如使用柱形图展示各大区的销售数量对比：
示例地址：[柱形图](https://demo.succbi.com/v5/bi/column-chart/play)
## 使用柱形图组件{#start}
柱形图的**X轴**上至少取1个维度，如省份，产品类型等；**Y轴**上至少取1个度量，如销售数量，利润金额等
**操作步骤：**
1. 双击或拖入维度【大区】到**X轴**
2. 双击或拖入度量【销售数量】到**Y轴**
3. 点击大区右侧的下拉按钮，选择**排序**，选择**指定字段**，点击右上角加号，按照**销售数量**>**降序**进行排序
4. 在**属性栏**>**样式**>**系列**下可设置柱子的**宽度**，范围为**1~100%**
通过上述4个步骤即可快速实现展示各大区的销售数量，且按销售数量降序显示。
## 属性介绍{#properties}
### 填充与背景{#background}
柱形图可以通过**填充**和**背景**分别控制柱形图柱子填充方式以及柱子背景填充方式，在**样式**>**系列**中进行设置。
- **填充**：柱子数据部分的填充，可以设置为**自动**、**颜色填充**、**图片填充**或**图片填充**等
- **背景**：整个柱子的背景填充，可以设置为**颜色填充**、**图片填充**或**图片填充**等
### 滚动{#scroll}
柱形图支持滚动条，可以设置滚动条显示方式、当前页展示数据量、是否循环滚动等，在**组件**>**滚动**中进行设置。
- **滚动条**：设置是否显示滚动条，支持以下三种方式：
- 自动：根据内容自动判断是否显示滚动条，如有滚动条，需在查看界面移入组件才显示
- 显示：显示滚动条
- 无：不显示滚动条
- **展示数据量**：设置当前页显示多少数据，可以通过以下四种方式设置
- 轴刻度宽度：通过设置`X轴刻度宽度`控制当前页显示数据量，`X轴刻度宽度`为X轴相邻刻度之间的宽度
- 固定值：显示固定条数的数据
- 百分比：显示全部数据的百分比
- 累计值：显示数据随着滚动进行累加，与循环滚动搭配使用
- 起始值：初始时显示数据的条数
- **循环滚动**：柱形图自动滚动展示，当滚动到最后一条数据时，从头开始滚动
- 滚动模式：支持以下两种模式：
- 逐条滚动：滚动时以条为单位，每次滚动一条数据
- 逐页滚动：滚动时以页为单位，每次滚动一页数据
- 滚动间隔：滚动的时间间隔，以秒为单位
## 更多效果{#scenarios}
可以自定义柱形图的取数和样式实现不同效果的柱形图。
|多系列柱形图|堆积柱形图|柱子颜色各异|自动轮播柱形图|
| ---- | ---- | ---- | ---- |
|||||
### 多系列柱形图{#multiple}
多系列柱形图可以用来同时展示多个指标，比较不同指标之间的数量大小。
**实现方式**
将多个度量一一拖入到**y轴**上，如【零售总金额】、【交易总金额】
**设置多系列柱形图的布局方式**
当柱形图为多系列时，可以设置各个系列之间的**布局方式**，在**属性栏**>**样式**>**柱形图**>**系列布局**，有2种布局方式：
|并排|重叠|
| ---- | ---- |
|不同指标的柱子不交叉的排列在x轴上|多个指标的柱子重叠在一起，柱子的高度为数量大的系列指标值|
|||
:::tip
**并排**时柱子排列的前后顺序、及**重叠**时柱子的上下顺序与**y轴**下拖入的度量值的排列顺序一致。
:::
多指标系列设置为**并排**排列时，可以设置多系列柱子之间的宽度，在**属性栏**>**样式**>**柱形图**>**布局**>**柱间间距**，范围为**0~100%**：
### 双轴显示多系列{#y2}
多系列柱形图设置为**并排**排列时，若希望展示不同量级的数据，可以设置双轴显示。
**操作步骤：**
1. 选中柱形图，在**属性栏**>**样式**>**系列**中展开【销售数量】，设置**布局**>**绘制轴**的值为`y2轴`
2. 轴标签：在**样式**>**坐标轴**中，展开y1轴，设置**标签**与**轴标题**为`显示`，y2轴同样设置
:::tip 更多设置
将y2轴的显示类型设置为其他类型，例如线型，可以使用[组合图](./dcombo.md)。
:::
### 堆积柱形图{#stack}
堆积柱形图可以直观展示每个分组的值，以及反映出系列的总和。可以使用堆积柱形图展示各大区的销售数量总和以及各价格档次的比重，如下图所示：
**实现方式**
拖入一个维度【价格档次】到**y轴**系列值下的[颜色](../../design/data/data-style/color.md)，即可实现按价格档次维度展示各大区的销售情况
### 柱子颜色各异{#difference}
柱形图同一系列内的柱子颜色是相同的，我们可以使用[颜色](../../design/data/data-style/color.md)来实现同一系列的柱子颜色各异。
|连续|离散|
| ---- | ---- |
|按照色阶进行颜色标记|按照色板值进行颜色标记|
|||
**实现方式**
将度量【票房】拖到**y轴**系列值下的[颜色](../../design/data/data-style/color.md)，**右键**选择**连续**或**离散**
### 对数变换{#logarithm}
在柱形图中数据差异过大时，不考虑数据填充的高度比例且对美观度有要求的情况下，可以使用对数标度进行数据变换填充。
**实现原理：** 类似于对数计算公式y=loga x，其中a为我们设置的底数，x为我们实际数据，计算出的y就是填充在柱形图高度的数据。
**实现方式**
在**样式**>**坐标轴**>**y轴**>**标度**中选择**对数**标度，再根据实际情况设置**底数**大小即可。
### 设置柱形图的标签倾斜换行{#incline}
当图形的轴标签文字多长时，可以设置文字倾斜显示，如下截图所示：
**实现思路**：在样式>坐标轴>x轴处，设置标签的间隔属性选择为显示全部，系统会自动根据位置计算倾斜角度。
### 设置柱形图的标签竖排展示{#vertical}
当柱形图的X轴标签内容较多时，可以设置文字竖排展示，如下截图所示：
|效果图|属性配置图|
| ---- | ---- |
|||
**实现方式**
在**样式**>**坐标轴**>**x1轴**>**轴标签**中勾选**显示标签**，**间隔**设置为自适应、**每行最大字数**设置为1。
### 自动轮播{#rotation}
当柱形图的X轴标签内容较多，无法在屏幕上全部显示时，可以设置柱形图自动轮播。
示例地址：[自动轮播柱形图](https://demo.succbi.com/v5/bi/column-chart/play)
**实现方式**
在**样式**>**组件**>**滚动**中勾选**循环滚动**，再根据需求设置**展示数据量**、**滚动模式**等即可。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/bar-chart.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/bar"
title: "仪表板组件-条形图"
---
---
order: 2
navTitle: 条形图
---
# 仪表板组件-条形图
条形图与柱形图类似，都是使用宽度相同柱子的长短来表示数据的多少，柱形图的柱子为纵向放置，条形图的柱子为横向放置。用于2个或2个以上的数值对比，如使用条形图展示各大区的销售数量对比、展示各款式的零售总额对比等：
示例地址: [条形图](https://demo.succbi.com/v5/bi/bar)
## 使用条形图组件{#start}
条形图的**x轴**上至少取1个度量，如销售数量，利润金额；**Y轴**上至少取1个维度，如省份，大区名称等。
**操作步骤**
1. 双击或拖入度量【销售数量】到**X轴**。
2. 双击或拖入维度【大区】到**Y轴**。
3. 点击大区右侧的下拉按钮，选择**排序**，选择**指定字段**，点击**添加**，按照【销售数量】>【降序】进行排序。
4. 在**属性栏**>**样式**>**系列**下可设置柱子的**宽度**，范围为1~100%。
通过上述4个步骤即可快速实现展示各大区的销售数量，且按销售数量降序显示。
## 属性介绍{#properties}
### 滚动{#scroll}
条形图支持滚动条，可以设置滚动条显示方式、当前页展示数据量、是否循环滚动等，在**样式**>**组件**>**滚动**设置图形的滚动选项，可参考[滚动](./column-chart.md#scroll)。
### 填充与背景{#background}
条形图可以通过**填充**和**背景**分别控制条形图柱子填充方式以及柱子背景填充方式，在**样式**>**系列**中设置，可参考[填充与背景](./column-chart.md#background)。
## 更多效果{#scenarios}
可以通过自定义条形图的取数和样式来实现不同效果的条形图。
| [多系列堆积条形图](#multiple) | [向左朝向条形图](#left)| [柱子颜色各异](#difference)| [自动轮播](#rotation)|
| -------- | -------- |-------- |-------- |
||| ||
### 多系列堆积条形图{#multiple}
多系列条形图可以展示不同的指标，堆积条形图可以展示维项的分布并反映出该指标的总和。组合在一起可以实现多系列堆积条形图，如同所示展示的各大区不同价格档次的折后总额分布和各大区的零售总额情况：
**实现方式**
1. 拖入2个度量【折后总额】、【零售总额】到**X轴**
2. 拖入一个维度【价格档次】到**Y轴**系列值下【折后总额】的**颜色**
通过以上2个步骤，即可实现按价格档次维度展示各大区的折后总额和各大区零售总额情况。
### 向左朝向条形图{#left}
条形图的朝向默认是朝右，可以设置坐标轴的显示位置来改变条形图的朝向。
**实现方式**
1. 在**属性栏**>**样式**>**坐标轴**>**显示位置**，可以选择条形图坐标轴的朝向，**居左**或**居右**显示
### 柱子颜色各异{#difference}
条形图内同一系列内的柱子颜色是相同的，我们可以使用颜色来实现同一系列的柱子颜色各异。
|按照色阶进行颜色标记| 按照色板值进行颜色标记|
| :---------:| :--------: |
| | |
**实现方式**
将度量【票房】拖到**x轴**系列值下的[颜色](../../design/data/data-style/color.md)，右键**颜色**，选择**色阶**或**色板**。
### 自动轮播{#rotation}
当条形图的Y轴标签内容较多，无法在屏幕上全部显示时，可以设置[滚动](#scroll)实现自动轮播的效果。
**实现方式**
1. 双击或拖入度量【销售数量】到**X轴**。
2. 双击或拖入维度【销售日期】到**Y轴**。
3. 在**样式**>**组件**>**滚动**中设置滚动条**显示**或者**自动**，设置**展示数据量**为**固定值**`10`。
4. 勾选**循环滚动**，根据实际需求设置滚动模式和滚动间隔。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/dcombo.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/dcombo"
title: "仪表板组件-组合图"
---
---
order: 3
navTitle: 组合图
---
# 仪表板组件-组合图
组合图展示的是同一维度下多个指标系列的数据变化。组合图支持双轴展示不同量级数据，并在单边下支持常规线性图、柱形图、面积图组合、堆积混合等复杂场景展示。
|柱形图和线性图组合|线性图和面积图组合|多系列柱形图和线性图组合|
| -------- | -------- |-------- |
||||
示例地址：[组合图](https://demo.succbi.com/v5/bi/dcombo)
## 使用组合图组件{#start}
组合图的**x轴**上至少取1个维度，如大区名称等；**Y轴**上至少取两个度量，如销售金额、销售数量等。
**操作步骤**
1. 双击或拖入维度【大区名称】到**X轴**
2. 双击或拖入度量【销售金额】、【销售数量】到**Y轴**
3. 选择【销售数量】>右键>[快速分析](../../design/data/data-analysis/rapid-analysis.md)>**增幅**
通过上述3个步骤即可展示不同大区的服装销售金额和销售数量的增幅变化情况。
## 属性介绍{#properties}
### 显示类型{#display}
组合图可以设置指标的显示类型，在**属性栏**>**组合图**>**显示类型**中进行设置。
- 柱形：设置系列为柱形，相当于[柱形图](./column-chart.md)
- 线性：设置系列的绘制图形为线性，相当于[折线图](./line-chart.md)
- 面积：设置系列的绘制图形为[面积图](./area.md)
:::tip
- 默认组合为**柱形**+**线性**，即拖入多个度量字段时，第一个系列为**柱形**，其他系列为**线性**。
- [柱形图](./column-chart.md)、[折线图](./line-chart.md)等基础图表也支持单轴和双轴的展示，但双轴组合图可以使用不同的图形来展示不同量级数据。
:::
### 背景{#background}
组合图可以通过**背景**控制柱形指标柱子的背景填充方式，在**样式**>**系列**>**背景**中进行设置。组合图与柱形图的背景属性定义一致，具体属性设置可查看[填充与背景](./column-chart.md#background)。
### 滚动{#scroll}
组合图支持滚动条，可以设置滚动条显示方式、当前页展示数据量、是否循环滚动等，在**组件**>**滚动**中进行设置。。组合图与柱形图的滚动属性定义一致，具体属性设置可查看[滚动](./column-chart.md#scroll)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/pictorialbar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/pictorialbar"
title: "仪表板组件-象形柱形图"
---
---
order: 4
navTitle: 象形柱形图
---
# 仪表板组件-象形柱形图
象形柱形图属于[柱形图](./column-chart.md)的一种，与柱形图的区别在于象形柱形图能够自定义柱子形状。如使用象形柱形图展示各大区销售情况：
示例地址：[象形柱形图](https://demo.succbi.com/v5/bi/pictorialbar)
## 使用象形柱形图组件{#start}
象形柱形图的制作方法与[柱形图](./column-chart.md)类似。在**X轴**上至少取1个维度，如省份、产品类型等；**Y轴**上至少取1个度量，如销售数量、利润金额等。
**操作步骤**
1. 双击或拖入维度【大区】到**X轴**
2. 双击或拖入度量【销售数量】到**Y轴**
3. 在**数据**>**x轴**，点击大区右侧的下拉按钮，选择**指定字段**进行**排序**并添加排序依据，对【销售数量】进行降序排序
通过上述3个步骤即可快速实现展示各大区的销售数量，且销售数量降序显示。
## 属性介绍{#properties}
### 柱间间距{#space}
象形柱形图支持自定义柱间距，柱子之间的间距在**样式**>**组件**>**布局**>**柱间间距**中进行设置。单系列与多系列下间距设置不同，具体如下：
- 单系列：设置每个柱子间间距
- 多系列：设置不同系列同一个标签上柱子的间距
### 形状{#shape}
象形柱形图能够自定义柱子的形状，以及柱子是否由形状堆叠构成、间隔、高度、宽度是多少等，在**样式**>**系列**>**销售数量**>**形状**可以设置。象形柱形图与象形条形图的**形状**属性定义一致，具体属性设置可查看[形状](./hpictorialbar.md#layout)。
### 填充{#fill}
象形柱形图可以通过**填充**属性控制柱子的填充方式，在**样式**>**系列**>**销售数量**>**填充**中进行设置。象形柱形图与象形条形图的**填充**属性定义一致，具体属性设置可查看[填充](./hpictorialbar.md#fill)。
## 更多效果{#scenarios}
### 多系列象形柱形图{#multiple}
多系列象形柱形图可以用来同时展示多个指标，比较不同指标之间的数量大小，体验类似柱形图，但每个系列都可以单独设置形状等属性。
**实现方式**
将多个度量一一拖入**y轴**上，如【折后总额】、【成本总额】
### 图标背景{#background icon}
象形柱形图还可以添加背景的灰色图标，用来更清晰的展示占比情况，可以自定义设置背景图标的形状、颜色等属性。
**实现方式**
- **添加两个系列**：新建一个值为1的字段，依次拖入该字段和销售数量
- **设置样式**：
- 形状大小和间距设置成一样的，在**样式**>**系列**>**值为1**>**形状**处，设置合适的形状，调整宽高，层叠设置为是
- 图标背景设置成灰色，在**样式**>**系列**>**值为1**>**填充**设置
- **设置重叠**：在**样式**>**组件**>**布局**处，把柱间间距调整为-100%。然后将值为1的字段，在**样式**>**系列**>**值为1**>**布局**设置为绘制轴的**y2轴**，与销售数量字段的**y1轴**区分开。
:::tip
1. y轴设置多个度量时，下面的字段会显示在页面的最上层
2. 设置重叠时，如果是显示百分比就不用设置两个轴显示
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/hpictorialbar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/hpictorialbar"
title: "hpictorialbar"
---
---
order: 5
navTitle: 象形条形图
---
# 仪表板组件-象形条形图
象形条形图是[条形图](./bar-chart.md)的一种，与条形图的区别在于象形条形图能够自定义柱子形状。
示例地址：[象形条形图](https://demo.succbi.com/v5/bi/hpictorialbar)
## 使用象形条形图组件{#start}
象形条形图的制作方法与[条形图](./bar-chart.md)类似。在**X轴**上至少取1个维度，如销售数量等；**Y轴**上至少取1个度量，如大类名称等。
**操作步骤**
- 双击或拖入度量【销售数量】到**X轴**
- 双击或拖入维度【大类名称】到**Y轴**
- 鼠标右键**Y轴**的【大类名称】，选择**指定字段**进行**排序**，点击**添加**，按照【销售数量】>降序进行排序
通过上述3个步骤即可快速实现展示各大类的销售数量，且按销售数量降序显示。
## 属性介绍{#properties}
### 柱间间距{#space}
象形条形图支持自定义柱间距，柱子之间的间距在**样式**>**组件**>**布局**>**柱间间距**中进行设置。单系列与多系列下间距设置不同，具体如下：
- 单系列：设置每个柱子间间距
- 多系列：设置不同系列同一个标签上柱子的间距
### 形状{#shape}
象形条形图支持自定义柱子形状，以及设置柱子是否由形状层叠构成、间隔多少、高度宽度等，在**样式**>**系列**>**销售数量**>**形状**中进行设置。
- **形状设置**：在**形状**>**图标**处可设置柱子的形状
- **宽度**：可以设置像素或者百分比，百分比是单个图形宽度相对于基准柱宽度的比例，如50%表示`宽度=基准柱宽度*50%`
- **高度**：可以设置像素或者百分比，百分比是单个图形高度相对于基准柱宽度的比例，如50%表示`高度=基准柱宽度*50%`
- **层叠设置**：在**形状**>**层叠**处可选择是否层叠，选择`是`用多个相同的形状堆叠表示柱子的长度；选择`否`用一个图形表示柱子长度。系统默认选择`是`，选择层叠时显示间隔属性
- **间隔**：表示同一柱子中，各图形之间的间距
- **水平偏移**：水平方向上进行左右平移
- **垂直偏移**：垂直方向上进行上下平移
:::tip
象形条形图可以被想象为：它首先是一个条形图，只是条形图的柱子不显示。这些柱子我们称为基准柱。
:::
### 填充{#fill}
通过**填充**可以控制象形条形图柱子的填充方式，在**样式**>**系列**>**销售数量**>**填充**中进行设置。
填充：柱子数据部分的背景填充。有以下几个选项：
- 自动：与柱子颜色一致
- 无填充：不设置形状背景
- 颜色填充：自定义背景颜色
- 图片填充：自定义图片进行填充
## 更多效果{#scenarios}
### 多系列象形条形图{#multiple}
多系列象形条形图可以用来同时展示多个指标，比较不同指标之间的数量大小，体验类似条形图，但每个系列都可以单独设置形状等属性。
**实现方式**
将多个度量一一拖入**x轴**上，如【折后总额】、【成本总额】
### 图标背景{#background icon}
象形条形图还可以添加背景的灰色图标，用来更清晰的展示占比情况，可以自定义设置背景图标的形状、颜色等属性。
**实现方式**
- **添加两个系列**：新建一个值为1的字段，依次拖入该字段和销售数量
- **设置样式**：
- 形状大小和间距设置成一样的，在**样式**>**系列**>**值为1**>**形状**处，设置合适的形状，调整宽高，层叠设置为是
- 图标背景设置成灰色，在**样式**>**系列**>**值为1**>**填充**设置
- **设置重叠**：在**样式**>**组件**>**布局**处，把柱间间距调整为-100%。然后将值为1的字段，在**样式**>**系列**>**值为1**>**布局**设置为绘制轴的**x2轴**，与销售数量字段的**x1轴**区分开。
:::tip
1. x轴设置多个度量时，下面的字段会显示在页面的最上层
2. 设置重叠时，如果是显示百分比就不用设置两个轴显示
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/pyramidchart.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/pyramidchart"
title: "仪表板组件-双向条形图"
---
---
order: 6
navTitle: 双向条形图
---
# 仪表板组件-双向条形图
双向条形图又称金字塔图，一般用于对比相同维度下不同指标数据的表现情况。如各大区中档服饰和低档服饰的销售数量对比：
示例地址：[双向条形图](https://demo.succbi.com/v5/bi/pyramidchart/play)
## 双向条形图的制作{#two-way}
双向条形图的**X轴**上至少取一个度量，如销售数量、销售金额等；**Y轴**上至少取一个维度，如大区、省份等
**操作步骤：**
1. 双击或拖入度量【销售数量】到**X轴**
2. 双击或拖入维度【大区】到**Y轴**
3. 将【价格档次】加入到**过滤器**中，选择低档和中档，也可根据需要自行调整
4. 拖入一个维度【价格档次】到**X轴**系列值下的[颜色](../../design/data/data-style/color.md)，即可实现按价格档次维度双向展示各大区的销售情况
通过以上4个步骤即可快速实现展示各大区在低档和中档两个档位的销售数量。
## 更多效果{#more}
可以自定义双向条形图的样式来实现不同效果的双向条形图。
|[系列标签位置](#label-location)|[轴标签位置](#location)|
| ---- | ---- |
|||
### 系列标签位置{#label-location}
可以自定义双向条形图标签的位置，如标签在两边，标签在内部等。
**实现方式**
在**属性栏**>**样式**>**系列**>**销售数量**>**标签**，选择**位置**，可选项有：
- 自动：标签自动调整显示位置，默认显示在柱子的上方
- 上方：显示在每一行柱子的上方
- 下方：显示在每一行柱子的下方
- 柱外顶侧：显示在每一行柱子的外侧，默认为柱外顶侧
- 内部居中：显示在每一行柱子内部的中间
- 内部底侧：显示在每一行柱子内部的最里侧
- 内部顶侧：显示在每一行柱子内部的最外侧
:::tip
需要先设置标签**显示**，才可设置标签的显示位置。
:::
### 轴标签位置{#location}
双向条形图的轴标签默认显示在图形左侧，可以调整轴标签位置在双向柱子中间或者图形右侧：
**实现方式**
在**属性栏**>**样式**>**坐标轴**>**Y轴**>**轴标签**，设置轴标签**显示**，设置**位置**为**中间**，可选项有：左侧，中间，右侧，选择位置为自动时默认显示在左侧。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/horizbar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/horizbar"
title: "仪表板组件-条形占比图"
---
---
order: 7
navTitle: 条形占比图
---
# 仪表板组件-条形占比图
条形占比图以条形的分段长度来表示各部分数据的占比情况，与[饼图](./pie-chart.md)类似，数据可以是百分比或者数值。比如以百分比展示不同大区的销售数量占比：
示例地址：[条形占比图](https://demo.succbi.com/v5/bi/occupancy)
## 条形占比图制作{#make}
条形占比图的**指标**上至少取1个度量，如销售数量等；取一个维度到[颜色](../../design/data/data-style/color.md)进行分组，如大区等，条形占比图中要绘制的数值大小不能含有负值。
**操作步骤：**
1. 双击或拖入度量【销售数量】到**指标**
2. 拖入维度【大区】到指标系列下的颜色
3. 点击**颜色**，选择其他色板，可以切换条形占比图不同柱形的颜色
4. 设置标签为占比：点击**属性栏**>**数据**>**销售数量**>[快速分析](../../design/data/data-analysis/README.md)，选择百分比
通过上述操作即可实现各大区的销量占比，以及使用了不同的颜色标记各大区。
## 属性介绍{#attribute}
### 外部标签{#external-label}
**外部标签和标签区分**
- [标签](../../design/data/data-style/label.md)可以设置显示与隐藏两种状态。隐藏状态标签直接被隐藏不显示，显示时可以设置位置、角度和样式。
- **外部标签**也可以设置显示和隐藏两种状态。当隐藏状态时，外部标签直接被隐藏不显示。当显示状态时，可以对以下属性进行设置来改变外部标签的样式和显示位置：
- **显示内容**：设置外部标签的显示内容为指标系列下的颜色、标签或提示中对应的数据，如果指标系列下只有颜色标记有数据，切换为提示标签内容不会改变
- **外部标签位置**：可以设置外部标签在条形占比图的底部或者顶部显示，默认为底部
- **内部标签到外部显示**：将条形占比图内部标签的内容替换外部标签并显示
- **标签错位显示**：将外部标签显示位置错位，比如当标签比较密集时，可以使用错位的方式
- **隐藏外部标签线**：隐藏外部标签与条形占比图之间的连接线
- **标签文字颜色同色块**：将外部标签文字的颜色与条形占比图各区块的颜色保持一致，勾选后，在字体处修改外部标签的颜色对标签文字不起作用，此条件优先级更高
- **标签线颜色同色块**：将外部标签线的颜色与条形占比图各区块的颜色保持一致，勾选后，在字体处修改外部标签的颜色对标签线不起作用，此条件优先级更高
- **外部标签文字和线的设置**：可以设置外部标签的文字样式，其中线的颜色同文字颜色。当不勾选**标签文字颜色同色块**和**标签线颜色同色块**时有效。
### 条形样式{#conditional-style}
可以通过修改**条形样式**来改变不同占比的柱形形状。可以选择的形状有**柱形**、**五边形**、**圆弧形**，默认为**柱形**。
不同形状的效果展示：
柱形效果图：
五边形效果图：
圆弧形效果图：
在选择五边形时，会出现一个**锐度**，可以对锐度数值进行调整来改变五边形右侧角的尖锐程度，当锐度为0时，角没有锐度，会呈现为柱形；当锐度值越大时，角越尖锐，但是当锐度取到一定值时会不再发生改变，这取决于图形的大小程度。
### 宽度{#width}
可以通过设置**宽度**来设置条形占比图柱子的宽度。
### 圆角{#round}
可以设置条形占比图的柱子为**圆角**，只有条形形状为柱形时生效。
**仅限外角**：勾选仅限外角，则只使条形占比图最左右的四角呈现**圆角**；不勾选，则每一个占比柱形形状都会呈现**圆角**。两者对比如下：
勾选仅限外角效果：
不勾选仅限外角效果：
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/line-chart.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/line-chart"
title: "仪表板组件-折线图"
---
---
order: 11
navTitle: 折线图
---
# 仪表板组件-折线图
折线图是将值标注成点，并通过连线将这些点按照某种顺序连接起来形成的图形，用于展示数值所占大小随时间或有序类别而变化的趋势。比如展示不同月份下服装销售数量的变化趋势：
示例地址：[折线图](https://demo.succbi.com/v5/bi/line)
## 使用折线图组件{#start}
折线图的**X轴**上至少取1个维度，如月份、大区等；**Y轴**上至少取1个度量，如销售数量、销售金额等。
**操作步骤：**
1. 双击或拖入维度【月份】到**X轴**
2. 双击或拖入度量【销售数量】到**Y轴**
3. 在**属性栏**>**样式**>**系列**>**连接线**，勾选**曲线**，则曲线将每个值点连接起来形成折线图
4. 还可以设置**连接线**的线型为**虚线**，用虚线将每个值点连接起来形成折线图
通过上述4个步骤即可快速实现展示销售数量随时间变化的一个趋势，且可以切换连接线状态。
## 属性介绍{#properties}
### 系列{#series}
折线图支持设置连接线、散点的样式，在**样式**>**系列**中进行设置。
- **连接线**：可以设置连接线形状、颜色、粗细等，并可设置连接线以曲线平滑连接
- **描边**：可以设置散点形状、颜色、大小等样式，并可对散点进行描边，设置散点边框的形状、颜色、粗细
### 滚动{#scroll}
折线图支持滚动条，可以设置滚动条显示方式、当前页展示数据量、是否循环滚动等，在**组件**>**滚动**中进行设置。折线图与柱形图的滚动属性定义一致，具体属性设置可查看[滚动](./column-chart.md#scroll)。
## 更多效果{#scenarios}
可以自定义折线图的取数和样式来实现不同效果的折线图。
| [多系列折线图](#multiple) | [堆积折线图](#stack) |[散点大小折线图](#scatter) |
| -------- | ----- | ----- |
|  |  | |
### 多系列折线图{#multiple}
多系列折线图可以用来同时展示多个指标，比较不同指标之间的走势趋向。
**实现方式**
将多个度量一一拖入到**Y轴**上，如【零售总金额】、【交易总金额】。
### 堆积折线图{#stack}
堆积折线图可以直观展示每个分组的走势趋向，以及反映出该系列的一个波动范围。可以使用堆积折线图展示不同价格档次的销售数量随时间的走向和该时间段内的波动范围，如下图所示：
**实现方式**
拖入一个维度【价格档次】到**Y轴**系列值下的[颜色](../../design/data/data-style/color.md)，即可实现按价格档次维度展示各月份的销售数量走势波动。
### 散点大小折线图{#scatter}
散点大小折线图使用散点的大小表示指标数据的大小，如下图所示利用散点大小展示不同地区折扣率的大小：
**实现方式**
将拖入**Y轴**的度量【折扣率】再拖入到到**Y轴**系列值下的[大小](../../design/data/data-style/size.md)，即可实现用图形的大小展示各大区的折扣率的大小。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/area.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/area-chart"
title: "仪表板组件-面积图"
---
---
order: 12
navTitle: 面积图
---
# 仪表板组件-面积图
面积图是将值标注成点，并通过连线将这些点连接起来，起点和终点与坐标轴连接，形成一个面积范围，用于展示数值大小随时间或有序类别变化的范围。比如展示不同月份下服装销售数量的变化：
示例地址：[面积图](https://demo.succbi.com/v5/bi/area/play)
## 使用面积图组件{#start}
面积图的**X轴**上至少取1个维度，如省份，销售月份等；**Y轴**上至少取1个度量，如销售数量，销售金额等。
**操作步骤**
1. 双击或拖入维度【月份】到**X轴**
2. 双击或拖入度量【销售数量】到**Y轴**
通过上述2个步骤即可快速实现展示不同月份下服装销售数量的变化。
## 属性介绍{#properties}
### 填充{#fill}
面积图可设置填充效果，定义不同的颜色，在**样式>系列>填充**中进行设置。
### 滚动{#scroll}
面积图支持滚动效果，可以设置滚动条显示方式、当前页展示数据量、是否循环滚动等，在**样式>组件>滚动中**设置，可参考[滚动](./column-chart.md#scroll)。
## 更多效果{#scenarios}
可以自定义面积图的取数和样式来实现不同效果的面积图。
| [多系列面积图](#multiple)| [堆积面积图](#stack)| [标记最大值最小值面积图](#sign)| [自动轮播面积图](#rotation)|
| -------- | -------- |-------- |-------- |
|||| |
### 多系列面积图{#multiple}
多系列面积图可以用来同时展示多个指标，比较不同指标之间的变化范围。
**实现方式**
1. 双击或拖入度量【月份】到**X轴**
2. 双击或拖入维度【零售总金额】和【交易总金额】到**Y轴**
通过以上2个步骤，即可实现不同月份零售总金额和交易总金额的变化，展示零售总金额和交易总金额的情况。
### 堆积面积图{#stack}
堆积面积图可以直观展示每个分组的走势趋向，以及反映出该系列的一个波动范围。可以使用堆积面积图展示不同价格档次的销售数量随时间的走向和该时间段内的波动范围，如下图所示：
**实现方式**
拖入一个维度【价格档次】到**Y轴**系列值下的[颜色](../../design/data/data-style/color.md)，即可实现按价格档次维度展示各月份的销售数量走势波动。
### 标记最大值和最小值面积图{#sign}
通过对面积图进行设置最大最小值标注，可以直观了解销量最佳和销量最低的月份。
**实现方式**
在**面积图**>**添加分析**，分别选择**最大值**和**最小值**，即可实现最大最小值标注，可参考文档[参考分析-最大/最小值](../../design/data/data-style/reference-line.md#max-min)。
### 自动轮播{#rotation}
当面积图的X轴标签内容较多，无法在屏幕上全部显示时，可以设置面积图自动轮播。
**实现方式**
在**样式**>**组件**>**滚动**中勾选**循环滚动**，再根据需求设置**展示数据量**、**滚动模式**即可。其他实现方式可参考柱形图中[自动轮播](./column-chart.md#rotation)的设置。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/radar-map.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/radar-map"
title: "仪表板组件-雷达图"
---
---
order: 13
navTitle: 雷达图
---
# 仪表板组件-雷达图
雷达图又称蜘蛛网图，它从一个中心点向外辐射出多条坐标轴，每一个维项数据都占有一条数据坐标轴。使用雷达图，可以快速找到具有相似值的维项、以及是否存在异常维项值。如使用雷达图展示各大区销售情况：
示例地址：[示例地址](https://demo.succbi.com/v5/bi/radar)
## 使用雷达图组件 {#start}
雷达图的**指标**上至少取一个度量，如销售数量；取一个维度到**维度**进行分组，如大类名称等。
**操作步骤**
1. 将**图形**>**雷达图**拖入到画布中
2. 双击或拖入维度【大类名称】到**维度**
3. 双击或拖入度量【销售数量】到**指标**
4. 设置**标签**样式及内容，可参考[标签](../../design/data/data-style/label.md)
5. 修改雷达图形状：默认显示为多边形，可以在**样式**>**极轴**>**布局**>**形状**中修改为圆形
## 属性介绍{#properties}
### 系列{#series}
雷达图支持在**样式**>**系列**处设置雷达面的样式，包括雷达面的节点形状，连接线、填充等
- **标签**：设置指标标签的显示隐藏、位置、角度、阴影等样式
- **形状**：设置指标节点的形状，并可对选择的形状图表进行描边
- **连接线**：设置指标节点之间的连接线
- **填充**：设置指标节点构成的雷达面的填充效果
- **阴影**：设置雷达面的阴影
### 极轴{#radaraxis}
雷达图支持在**样式**>**极轴**处设置雷达图极轴的样式，如极轴的轴线、分割区域、标签等。
- **布局**：可设置极坐标轴的形状、半径、起始角度、分割段数
- **形状**：设置极坐标轴的形状，可选择多边形和圆形
- **半径**：设置极坐标轴的半径
- **起始角度**：设置极坐标轴水平面的起始角度，默认为90度
- **分割段数**：设置极坐标轴分为几段，默认为5
- **轴线**：即极坐标轴，轴线条数为维度分组个数
- **轴标签**：类似于坐标轴的刻度标签，轴标签为极坐标轴的分段标签，支持设置显示格式、样式、角度、以及显示隐藏
- **轴标题**：即维度的标签，支持设置显示格式、样式、角度、以及显示隐藏
- **刻度值**：设置极坐标轴的最大值最小值，最小值默认指标值中的最小值；最大值默认指标值中的最大值。极坐标轴将根据刻度值的区间，按照**分割段数**进行等分
- **分割区域**：每个刻度之间构成的区域，支持设置填充效果
- **分割线**：极坐标轴每条轴线在同一刻度上的连线
## 更多效果{#scenarios}
可以自定义雷达图的样式实现不同效果的雷达图。
|[渐变色雷达图](#渐变色雷达图)|[圆点连接线雷达图](#圆点连接线雷达图)|
| ---- | ---- |
|||
### 渐变色雷达图{#gradient-color}
雷达图中的颜色填充为渐变色填充
**实现方法**
在**样式**>**系列**>**填充**中选择颜色填充，再设置相应的渐变色
### 圆点连接线雷达图{#dot-connector}
雷达图中的连接点设置为圆点连接
**实现方法**
在**样式**>**系列**>**形状**中中选择圆形，也可以根据需求选择其他图形、颜色和大小
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/scatter.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/scatter"
title: "仪表板组件-散点图"
---
---
order: 18
navTitle: 散点图
---
# 仪表板组件-散点图
散点图是指回归分析中，数据点在直角坐标系平面上的分布图，表示的是因变量随自变量变化的大致趋势。如使用散点图展示各商品类别销售计划和实际销售金额的变化趋势等：
示例地址：[散点图](https://demo.succbi.com/v5/bi/scatters-and-bubbles/play)
## 使用散点图组件{#start}
在散点图的**X轴**和**Y轴**上各取一个度量，如销售计划、销售金额、销售数量等
**操作步骤**
1. 双击或拖入度量【销售计划】到**X轴**
2. 双击或拖入度量【销售数量】到**Y轴**
3. 拖入一个维度【大区】到[颜色](../../design/data/data-style/color.md)，实现不同颜色的散点区分大区
4. 拖入一个维度【省】到**其他**，以大区的颜色展示不同省份的变化趋势
通过上述4个步骤即可实现展示各大区下各省份的销售数量随销售计划增大而变化的大致趋势。
## 属性介绍{#properties}
### 形状{#shape}
散点图可以自定义散点的形状，颜色和大小，可根据需要，进行调整。在**样式>系列>形状**中设置
## 更多效果{#scenarios}
可以设置参考线和引入其他表示大小的变量实现不同效果的散点图。
|[设置参考线](#reference-line)|[气泡图](#bubble-chart)|
| ---- | ---- |
|||
### 设置参考线{#reference-line}
在散点图中，可以根据坐标点的分布，判断各商品类别的实际销售金额与销售计划之间存在的关联关系或总结坐标点的分布模式。下图中三条参考线分别代表实际销售金额完成率70%、80%、95%，通过参考线可以看出各个省份的销售完成情况处于哪个区间。
**实现方式**
在**散点图**>**添加分析**中选择**比率线**，分别设置比率为0.7、0.8、0.95，即可实现按不同比率展示销售完成情况的区间，可参考文档[参考分析-比率线](../../design/data/data-style/reference-line.md#ratio-line)。
### 气泡图{#bubble-chart}
在气泡图中，不仅可以直观地看到各省份的零售金额与成本金额之间的相关关系，还可以根据气泡的大小来直观地看出各省份的零售利润，从而获取到零售金额、成本金额和零售利润之间的关系。
**实现方式**
将度量【利润】拖入到**数据**>**大小**，即可实现按气泡大小直观展示各省份的零售利润。
### 波士顿矩阵图{#boston-matrix}
波士顿矩阵分析图通过分析市场引力和企业实力两个因素，来分析决定企业的产品结构。
**实现方式**
1. 双击或拖入度量【市场增长率】到**X轴**
2. 双击或拖入度量【销售增长率】到**Y轴**
3. 拖入一个维度【小类名称】到[颜色](../../design/data/data-style/color.md)
4. 设置两条平均线，值分别设置为【市场增长率】和【销售增长率】
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/pie-chart.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/pie-chart"
title: "仪表板组件-饼图"
---
---
order: 22
navTitle: 饼图
---
# 仪表板组件-饼图
饼图是以扇形区域大小表示每一个数值相对于总数值的占比。比如展示不同价格档次的销售数量占比：
示例地址：[饼图](https://demo.succbi.com/v5/bi/pie)
## 使用饼图组件{#start}
饼图的**指标**上至少取1个度量，如销售数量；取一个维度到[颜色](../../design/data/data-style/color.md)进行分组，如价格档次等。饼图中要绘制的数值大小不能含有负值。
**操作步骤**
1. 双击或拖入度量【销售数量】到**指标**
2. 双击或拖入维度【价格档次】到**颜色**
通过上述2个步骤，即可展示不同价格档次的服装销量占比。
## 属性介绍{#properties}
### 布局{#layout}
在**样式**>**系列**>**布局**>处，可对饼图的内外半径、起始角度、增长方向进行设置。
- **内半径**：设置饼图当前系列的内半径，默认为0%，最大值为99%
- **外半径**：设置饼图当前系列的外半径，默认为0%，最大值为100%
- **起始角度**：设置饼图的起始角度，默认为90度
- **顺时针增长**：设置饼图中扇形数据是否顺时针增长，默认勾选
- **通过半径展示数据大小**：设置饼图是否通过半径展示数据大小。默认不勾选，勾选后出现属性**通过圆心角展示数据百分比**，该属性可设置饼图当前系列是否通过圆心角展示数据百分比。这两个属性可实现玫瑰图的效果
## 更多效果{#scenarios}
可以通过自定义饼图的取数和样式来实现不同效果的饼图。
| [玫瑰图](#玫瑰图) | [断开环形饼图](#断开环形饼图)| [多系列饼图](#多系列饼图) | [圆角饼图](#多系列饼图)|
| -------- | -------- | -------- | -------- |
|||||
### 玫瑰图{#rose}
玫瑰图通过半径大小和圆心角的占比来展示数据的大小和占比。
**实现方式**
玫瑰图有2种形式：
1. 在**样式**>**系列**>**布局**，勾选**通过半径展示数据大小**
2. 在**样式**>**系列**>**布局**，勾选**通过圆角展示数据百分比**
:::tip
- 通过半径展示数据大小：各个区域的圆心角角度一致，半径长度不一致
- 通过圆角展示数据百分比：各个区域的圆心角不一致，只有先勾选**通过半径展示数据大小**才可实现**通过圆角展示数据百分比**
:::
### 断开环形饼图{#break}
断开环形饼图可以通过设置边框线的颜色与背景色一致，来实现断开环形饼图的效果。
**实现方式**
1. 在**样式**>**系列**>**布局**，设置内半径和外半径属性达到控制圆环的宽度，实现环形效果
2. 在**样式**>**系列**>**边框**，选择边框线，**颜色**设置为白色，对边框线的粗细进行调节，可调节断开区域的大小
通过以上2个步骤，即可实现按价格档次维度展示销售数量的占比。
### 多系列饼图{#series}
多系列饼图通过控制多个系列的外半径以及填充颜色的不同，来实现对应的效果。
**实现方式**
1. 在**数据**>**指标**处引入两个度量，在**数据**>**标记区**，拖入维度设置多系列的**颜色**填充，并在**标签**处拖入所需要的标签字段
2. 在**样式**>**系列**>**布局**>**外半径**，设置内部系列的外半径小于外部系列的外半径，以便区别不同系列。当外部系列的内半径大于内部系列的外半径时为同心环效果
| 内层系列设置 | 内层系列设置| 内层系列设置（同心环）|
| -------- | -------- | -------- |
||||
:::tip
添加多个指标时，**数据**>**指标**处下方指标的效果会叠加在上方指标效果上，因此建议将上方的字段当做外部系列，下方的字段当做内部系列，以防止遮挡。
:::
### 圆角饼图{#border-radius}
可以通过设置饼图的圆角属性，来实现圆角饼图的效果。
**实现方式**
1. 在**样式**>**系列**>**边框**，选择边框线，**颜色**设置为白色，对边框线的粗细进行调节，可调节断开区域的大小
2. 在**样式**>**系列**>**圆角**，设置圆角数值，可调节圆角大小
通过以上2个步骤，即可实现圆角饼图的效果。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/sunburst.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/sunburst"
title: "仪表板组件-旭日图"
---
---
order: 23
navTitle: 旭日图
---
# 仪表板组件-旭日图
旭日图也称为太阳图，是一种圆环镶接图。在旭日图中，每个级别的数据都是旭日图中的一个圆环。越靠近内圈的圆环代表的数据级别越高，越往外，级别越低，分类越细。因此，旭日图既能像饼图一样表现局部和整体的占比，也能像[矩阵图](./treemap.md)一样表现数据的层次关系。
| 系列颜色 | 标签旋转 |
| :---------: | :--------: |
|  |  |
## 使用旭日图组件{#start}
在旭日图中的**维度**选项中，按照旭日图从内到外、分类级别从高到低的顺序，依次将模型中的维度字段拖入，再将度量字段拖入到旭日图的**指标**中即可。
1. 依次拖入【门店.门店级别】、【上下装】、【价格档次】拖入到旭日图的**维度**中
2. 将【销售数量（件）】字段拖入到旭日图的**指标**中
3. 分别设置【上下装】、【价格档次】字段属性，设置**颜色**为**继承上级**，**不透明度**设置为**70%**
## 属性介绍{#properties}
### 颜色
在旭日图组件的字段属性中，可以设置**维度**字段的颜色填充方式，提供7种颜色填充方式：
- **自动**：自动选择当前页面主题的第一个色板颜色进行填充，默认选择
- **无填充**：不进行颜色填充
- **颜色填充**：自定义颜色进行填充，可以选择纯色或渐变色进行填充
- **色板**：选择当前主题中的其他色板颜色进行填充，可以为特殊值设置指定颜色，但选择了**色板**填充时，需要拖入一个维段到**颜色**作为颜色填充依据。一级维度选择**色板**填充后，默认选择第二级字段作为颜色填充依据（可以手动更换成其他字段），二级及以下字段会自动选择自己本身作为颜色填充依据。如果当前旭日图只选择了一个维度，即默认选择自己本身作为颜色填充依据
- **色阶**：选择当前主题中的色阶渐变色进行填充，可以为不同数据范围区间设置指定的色阶变化范围。但选择了**色阶**填充时，需要拖入一个字段到**色阶**作为颜色填充依据。每个维度字段选择**色阶**时，默认将自己本身作为颜色填充依据（可以手动更换成其他字段）
| 色板填充 | 色阶填充 |
| :---------: | :--------: |
|  |  |
- **继承上级**：二级及以下的维度字段，会自动继承上级的颜色，可以设置**不透明度**用于区分上下级数据
- **继承上级-渐变**：二级及以下的维度字段，会在自动继承上级的颜色情况下，自动形成同上级一个色系内颜色，从而形成整体的渐变色效果，支持设置**不透明度**
| 继承上级 | 继承上级-渐变 |
| :---------: | :--------: |
|  |  |
在**样式**>**系列**>**填充**中，也可以针对指定系列进行颜色样式的填充设置。
### 布局
在**样式**>**组件**>**布局**中，可以设置旭日图的**外半径**、**内半径**、**起始角度**和**顺时针增长**。
旭日图内外半径效果，可参考下图：
- **外半径**：以整个旭日图为整体，设置旭日图的外半径大小，默认75%
- **内半径**：以整个旭日图为整体，设置旭日图的内半径大小，默认为0%
- **起始角度**：设置旭日图的起始角度，默认为90°
- **顺时针增长**：设置旭日图中扇形数据是否顺时针增长，默认勾选
在**样式**>**系列**>**布局**中，可以单独以每一个系列为一个饼图，设置独自的内外半径大小。默认只有**外半径**选项，当设置了**外半径**后，自动显示**内边距**选项供用户设置。
::: tip
**样式**>**系列**>**布局**中内外半径的优先级高于**样式**>**组件**>**布局**中内外半径优先级。
:::
### 标签
在旭日图组件的字段属性中，可以设置**标签**的样式，具体可参考[标签](../../design/data/data-style/label.md)。
在**样式**>**系列**>**布局**中，可以单独以每一个系列设置标签样式。
| 径向旋转 | 切向旋转 | 固定角度（45°） |
| :---------: | :--------: | :--------: |
|  |  |  |
提供如下属性：
- **显示**：设置各个系列标签是否显示，默认显示标签
- **位置**：设置各个系列标签的显示位置，提供**内部居中**、**外部**两个位置显示，默认**内部居中**
- **选择**：设置标签显示的旋转方式，提供**径向旋转**、**切向旋转**和**固定角度**三种旋转方式，选择**固定角度**后，可以在**角度**中设置固定的旋转角度，默认**径向旋转**
- **隐藏微小标签**：设置各个系列标签的隐藏规则，当系列中的指标数据小于所设置范围时，该指标对应的维度标签就会自动隐藏，默认5%
- **字体**：设置标签内容字体，包括**字体**、**字号**、**斜体**、**颜色**
- **文字阴影**：设置标签内容的阴影，默认**无阴影**
### 边框
在**样式**>**系列**>**边框**中，单独为每一个系列设置边框，可以设置边框位置和线型。具体可参考[边框](../../design/type/basic/border.md)。
### 圆角
在**样式**>**系列**>**圆角**中，单独为每一个系列设置圆角。具体可参考[圆角](../../design/type/basic/border-radius.md)。
### 阴影
在**样式**>**系列**>**阴影**中，单独为每一个系列设置阴影。具体可参考[阴影](../../design/type/basic/shadow.md)。
## 应用场景{#scenarios}
### 多环形嵌套
多环形嵌套效果，可以使旭日图整体布局效果更加明朗，更好的从视觉角度分析各级别数据的分布情况。
**实现方式**
通过给每个系列设置单独的内外半径，从内到外依次增大内外半径差，从而形成环形效果。上图效果设置参数如下：
- 【门店.门店级别】：**外半径**-40%，**内半径**-0%
- 【上下装】：**外半径**-70%，**内半径**-45%
- 【价格档次】：**外半径**-100%，**内半径**-75%
### 立体效果
立体阴影效果的旭日图，让图形的展示更加立体化，饱满化。更适合一些需要特殊炫酷效果的场景。
**实现方式**
通过给每个系列设置阴影效果，从而达到立体化的效果。上图效果设置参数如下：
- 【门店.门店级别】：无阴影
- 【上下装】：选择全阴影效果，**X**为0，**Y**为0，**模糊**为20，**扩展**为1，颜色透明度为34%（默认颜色）
- 【价格档次】：选择全阴影效果，**X**为0，**Y**为0，**模糊**为20，**扩展**为1，颜色透明度为20%（默认颜色）
### 圆角效果
圆角效果可以使旭日图的分布带有散点分布的特点，从而可以利用散点分布的密集程度，分析出各级数据的占比情况。
**实现方式**
通过给每个系列设置合适的**圆角**即可快速实现上图效果。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/treemap.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/treemap"
title: "仪表板组件-矩阵图"
---
---
order: 26
navTitle: 矩阵图
---
# 仪表板组件-矩阵图
矩阵图是用来显示数据的占比关系，矩阵的空间根据数据的分组被分为多个矩形，矩形大小反应数据占比大小，如各省销售占比：
示例地址：[示例地址](https://demo.succbi.com/v5/bi/treemap)
**操作步骤**
1. 将**图形**>**矩阵图**拖入到画布中
2. 双击或拖入维度【大区】到**颜色**
3. 双击或拖入度量【销售数量】到**指标**
4. 拖入维度【省】到**标签**
5. 在**样式**>**矩阵树图**>**矩阵间距**中将矩阵间距调整为1
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/sankey.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/sankey"
title: "仪表板组件-桑基图"
---
---
order: 27
navTitle: 桑基图
---
# 仪表板组件-桑基图
桑基图，也叫做桑基能量分流图或者桑基能量平衡图。桑基图是一种较为特定类型的流程图，图中延伸的分支的宽度对应数据流量的大小，并且所有主支宽度的总和应与分流的分支宽度总和相等，保持流量平和，所以桑基图非常适用于用户流量的数据的可视化分析。
示例地址：[桑基图](https://demo.succbi.com/v5/bi/sankey-diagram)
## 使用桑基图组件{#start}
将桑基图中数据流动的起点、经过点、终点的维度字段拖入到组件的**维度**中，数据流字段拖入到**指标**中即可。
**操作步骤：**
1. 双击或拖入维度【国家】、【行业】、【公司】到桑基图的**维度**中
2. 双击或拖入度量【估值（亿美元）】到桑基图的**指标**中
## 属性介绍{#properties}
### 组成{#composition}
桑基图是由**起点**、**经过线**、**终点**和**连接线**组成，一个完整的桑基图最少需要一个**起点**字段和一个**终点**字段，**经过点**可以无数个或者0个，连接线只能取一个字段。
拖入到**维度**的字段就是桑基图的**起点**、**经过线**、**终点**，拖入到**指标**的字段就是桑基图的**连接线**。
其中桑基图**起点**、**经过点**、**终点**的顺序是由拖入到**维度**中的字段顺序决定的。也可以在**维度**手动拖动更改字段顺序，从而改变桑基图的**起点**、**经过点**、**终点**。
### 颜色{#colour}
在**维度**中，可以更改**维度**对应的字段在桑基图中的颜色填充，默认为**自动**,**自动**使用主题色板中颜色进行填充，也提供**无填充**、**颜色填充**、**色板**和**色阶**填充。
也支持将模型中的字段拖入到**颜色**，利用字段值的不同，进行相对于的颜色填充。
### 布局{#layout}
**样式**>**组件**>**布局**中允许用户设置整体排列方向，具体效果如下图：
| 水平排列 | 垂直排列 |
| :---------: | :--------: |
|  |  |
**布局**具体提供如下属性：
- **排列方式**：设置桑基图的排列方向，提供**水平**和**垂直**两种属性，默认**水平**
- **节点宽度**：设置**起点**、**经过点**和**终点**的宽度，默认20px
- **节点间隔**：设置**起点**、**经过点**和**终点**的间隔距离，默认10px
- **可拖动节点**：允许拖动**起点**、**经过点**和**终点**，默认不勾选，具体效果如下图：
### 连接线{#connecting-line}
**样式**>**组件**>**连接线**中可以设置连接线的相关属性，具体如下：
- **颜色**：设置**连接线**颜色样式，提供如下属性：
- **继承源节点**：桑基图的整体流行是从左到右或者从上到下。如果选择**继承源节点**，那么**连接线**就会继承左边或者上面节点颜色设置
- **自定义**：自定义**连接线**的颜色填充
- **不透明度**：设置**连接线**颜色的透明度，设置的值越小，颜色越透明，取值范围0-1，默认0.4
- **曲度**：设置**连接线**弯曲程度，设置的值越大，弯曲程度越大，取值范围0-1，默认0.5
### 高亮区块{#highlight}
**样式**>**组件**>**高亮区块**中可以设置鼠标放入到各节点或**连接线**上的高亮样式，具体属性如下：
- **高亮显示内容**：设置触发高亮的内容区域，具体如下：
- **默认**：当鼠标移入在某个节点上，将会高亮当前节点前后节点以及高亮前后**连接线**，此时**连接线**的颜色是带有**连接线**颜色设置中透明度设置属性；当鼠标移入在某个**连接线**上，将会高亮当前**连接线**前后节点，此时**连接线**的颜色是不会带有**连接线**颜色设置中透明度设置属性
- **仅节点或边**：设置此属性后，鼠标移入到节点或**连接线**时，只会将高亮当前鼠标移入的节点或**连接线**，不会再同时高亮相邻的节点或**连接线**
| 鼠标放入节点 | 鼠标放入连接线 |
| :---------: | :--------: |
|  |  |
- **颜色**：设置高亮区块颜色，默认无
- **边框**：设置高亮区块边框样式
- **外阴影**：设置高亮区块阴影样式，默认无阴影样式
### 系列{#series}
**样式**>**系列**中可以单独各个节点的样式，具体提供如下属性：
- [标签](#label)
- [填充](#fill)
- [边框](#frame)
- [阴影](#shadow)
### 标签{#label}
设置桑基图对应节点上的标签样式，提供如下属性：
- **显示**：设置对应节点上标签是否显示，默认**显示**
- **字体**：设置标签内容字体，包括**字体**、**字号**、**斜体**、**颜色**
- **文字阴影**：设置标签内容的阴影，默认**无阴影**
- **位置**：设置对应节点上标签的显示位置，提供**自动**、**上方**、**下方**、**内部居中**、**左侧**和**右侧**，默认**自动**
- **角度**：设置对应节点上标签的旋转角度，提供**0**和**90**，也可以手动输入其他度数，默认**0**
### 填充{#fill}
设置桑基图对应节点以及该节点右侧或下方**连接线**的颜色填充，提供**自动**、**无填充**和**颜色填充**三种填充方式，默认自动。
::: tip
如果在**样式**>**组件**>**连接线**中可以将**连接线**的填充方式设置成**自定义**，那么这里的颜色设置将不会作用到指定节点右侧或下方的**连接线**上，即**连接线**本身的样式设置优先级最高。
:::
### 边框{#frame}
设置桑基图对应节点边框样式，提供四种边框样式，具体如下图，默认**无**。
### 阴影{#shadow}
设置桑基图对应节点阴影样式，默认**无**阴影样式。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/databar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/databar"
title: "databar"
---
---
order: 30
navTitle: 数据条
---
# 仪表板组件-数据条
数据条以进度填充的方式，显示处理任务的速度、完成度、剩余未完成任务量的大小。
示例地址：[进度条](https://demo.succbi.com/v5/bi/data-bar)
## 使用数据条组件{#start}
数据条的**数据**指标上只能取一个1个度量，用一个0~1之间的小数表示进度的百分比，如`下装销售额占比`。当**数据**处指标为负数时，数据条无填充，指标大于1时，数据条完全填充。
**操作步骤：**
1. 双击或拖入度量【下装销售额占比】到**数据**
2. 根据需求调整数据条的布局：切换到**样式>进度**属性，设置圆角为：`10`。设置颜色填充为渐变色，设置角度为`90`
## 属性介绍{#properties}
在**样式>进度**中可以对**进度**的样式进行设置，包括目标值、标签、填充、边框、圆角、阴影：
- **目标值**：数据条最终展示的进度是通过**数据**属性处引入的度量除以目标值计算得出，目标值默认为1
- **标签**：设置数据条标签的显示与隐藏，选择显示标签时，可以设置标签显示的**位置**、**大小**、**颜色**等属性，在属性栏**数据>标签>标签值**处可以对标签的文本进行修改
- **填充**：设置进度的填充效果，包括**进度填充**和**背景填充**
- **进度填充**：数据条数据部分的填充
- **背景填充**：数据条的背景填充
- **边框**：设置进度的边框
- **圆角**：设置进度的圆角
- **阴影**：设置进度的阴影
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/iconbar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/iconbar"
title: "仪表板组件-图标条"
---
---
order: 31
navTitle: 图标条
---
# 仪表板组件-图标条
图标条以图标的填充显示处理任务的速度、完成度、剩余未完成任务量的大小。
示例地址：[图标条](https://demo.succbi.com/v5/bi/data-bar)
:::tip
图标条与[数据条](./databar.md)的用法类似，只是UI显示不同
:::
## 使用图标条组件{#start}
图标条的**数据**指标上只能取一个1个度量，用一个0~1之间的小数表示进度的百分比，如`空气湿度`。当**数据**处指标为负数时，图标条无填充，指标大于1时，图标条完全填充。
- 双击或拖入度量【空气湿度】到**数据**
- 在**样式>图标条>图标**处选择**图形**，图形的**大小**，图标条的**图标总数**
## 属性介绍{#properties}
在**样式>进度**处可以设置图标条的目标值以及图标的图形、总数、大小等：
- **布局**：设置图标条的目标值以及图标总数
- **目标值**：图标条最终展示进度的是通过**数据**属性处引入的度量除以目标值计算得出，目标值默认为1
- **图标总数**：构成图标条的图标个数，如选中图标个数为`5`那整个图标条将由五个图标构成，图标条会按照**数据**与**目标值**的比例进行填充
- **图标**：设置图标条的图标以及图标大小
- **图标**：构成图标条的图标图形
- **大小**：构成图标条的图标大小
- **标签**：设置数据条标签的显示与隐藏，选择显示标签时，可以设置标签显示的**位置**、**大小**、**颜色**等属性，在属性栏**数据>标签>标签值**处可以对标签的文本进行修改
- **填充**：设置进度的填充效果，包括**进度填充**和**背景填充**
- **进度填充**：图标条数据部分的填充
- **背景填充**：图标条的背景填充
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/gauge.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/gauge"
title: "仪表板组件-仪表盘"
---
---
order: 32
navTitle: 仪表盘
---
# 仪表板组件-仪表盘
仪表盘是模仿汽车速度表的一种图表，可以简单、直观地展示某个指标值所在的范围，比如用来反映预算完成率、收入增长率等比率性指标。
## 使用仪表盘组件{#start}
仪表盘组件的使用只需要一个度量作为指标，如销售数量。在**样式**>**表盘**>**刻度值**处可设置度量所在的数据区间。
**操作步骤**
1. 双击或拖入【销售数量】到指标，并右键指标，选择**度量**>**平均值**
2. 在**样式**>**进度**处设置标签隐藏
## 属性介绍{#properties}
### 表盘{#axis}
表盘即指标所在坐标轴。在**样式**>**表盘**处可设置表盘的样式，包括表盘的半径、区间着色、刻度值、刻度线等内容。
- **布局**：可设置表盘半径、以及起始角度、结束角度、是否顺时针增长以及两端是否显示圆角等内容
- **半径**：设置表盘半径，最大值为100%
- **圆形**：**起始角度**与**结束角度**的快捷选项，根据选中值形成对应起始角度与结束角度。可选项包括满圆、半圆、多半圆、自定义。
- **起始角度**：表盘的起始角度，最大值为360度。起始角度为0度指起始点从右侧水平开始
- **结束角度**：表盘的结束角度，最大值为360度
- **顺时针增长**：设置表盘数据是否顺时针增长，默认勾选，当该属性发生变化时，角度也会对应改变
- **两端显示圆角**：设置表盘的两端是否显示圆角，默认不勾选
- **轴线**：可设置轴线的区间着色，以及轴线的宽度
- **区间着色**：默认五个区间，颜色为所选色板的前五个颜色，可自行调整区间个数及颜色
- **宽度**：设置轴线的宽度
- **轴标签**：即分割线的标签。可设置轴标签的显示隐藏、距轴线的距离、字体的大小颜色等样式
- **刻度值**：设置轴线的最大值与最小值
- **刻度线**：即轴线的刻度线，可设置刻度线的线条样式、长度、刻度数量以及刻度线与轴线的距离
- **分割线**：即轴线的分割线，可设置分割线的线条样式、长度、分割段数以及分割线与轴线的距离
### 进度{#progress}
进度是以进度条的形式在表盘上展现的指标数值。当显示时，会直接叠加在表盘上，如果只想保留进度，可调整表盘轴线的不透明度为0%，在**样式**>**进度**处可设置进度是否显示、进度的标签、进度的填充、边框阴影等内容。
- **布局**：设置进度是否显示，以及进度两端是否显示圆角
- **标签**：设置进度标签的显示隐藏、字体的大小颜色等样式
- **填充**：设置进度条的填充色
- **边框**：设置进度条的边框
- **阴影**：设置进度条的阴影
### 指针{#pointer}
类似于时钟的指针，仪表盘的指针指向当前数值。在**样式**>**指针**处可设置指针的形状、长度、宽度、填充等样式。
- **指针**：设置指针的形状、长度、宽度
- **指针**：可选择形状为刀型针、线型针、水滴针、自定义或无。选择无即不显示指针
- **长度**：设置指针的长度，最大值为100%
- **宽度**：设置指针的宽度，最大值为100
- **填充**：设置指针的填充色
- **边框**：设置指针的边框
- **外阴影**：设置指针的外阴影
## 更多效果{#scenarios}
可以通过自定义表盘、进度、指针来实现不同效果的仪表盘。
| 多色仪表盘 | 渐变仪表盘 | 圆形仪表盘|
| -------- | -------- | -------- |
||||
| 间隔仪表盘 | 自定义指针| 半圆占比图 |
| -------- | -------- | -------- |
||||
### 多色仪表盘{#multicolour}
**实现方式**
1. 在**样式**>**表盘**>**轴线**设置合适的区间填充色
2. 在**样式**>**表盘**>**轴标签**处显示轴标签
3. 在**样式**>**进度**>**标签**处设置合适的标签颜色
4. 在**样式**>**指针**>**填充**处设置指针的填充颜色
| 表盘设置 | 进度设置| 指针设置 |
| -------- | -------- | -------- |
||||
### 渐变仪表盘{#gradient}
**实现方式**
1. 在**样式**>**表盘**>**轴线**设置一个区间，区间颜色为渐变色。根据需求设置合适的区间填充色
2. 在**样式**>**表盘**>**轴标签**处显示轴标签
3. 在**样式**>**指针**>**填充**处设置指针的填充颜色
| 表盘设置 | 指针设置 |
| -------- | -------- |
|||
### 圆形仪表盘{#circle}
**实现方式**
1. 在**样式**>**表盘**>**布局**设置合适**起始角度**和**结束角度**，调整至目标形状
2. 在**样式**>**表盘**>**轴线**处设置对应的区间数以及填充色
3. 在**样式**>**表盘**>**轴标签**处显示轴标签
4. 在**样式**>**表盘**>**刻度值**处设置表盘的区间范围
5. 在**样式**>**指针**>**指针**处设置指针形状，**样式**>**指针**>**填充**处设置指针的填充颜色
| 表盘设置 | 指针设置 |
| -------- | -------- |
|||
### 间隔仪表盘{#interval}
**实现方式**
1. 在**样式**>**表盘**>**轴线**设置区间数以及填充色
2. 在**样式**>**表盘**>**刻度线**处使用刻度线分割表盘
3. 在**样式**>**指针**>**填充**处设置指针的填充颜色
| 表盘设置 | 指针设置 |
| -------- | -------- |
|||
### 自定义指针{#custom}
**实现方式**
1. 在**样式**>**表盘**调整表盘样式，如在**轴线**处区间填充色，在**刻度线**处调整刻度线，在**分割线**处调整分割线
2. 在**样式**>**指针**>**指针**处设置自定义指针，选择图标库图标或者上传图标
3. 在**样式**>**指针**>**填充**处设置自定义指针的填充色
| 表盘设置 | 指针设置 |
| -------- | -------- |
|||
### 半圆占比图{#semicircle}
**实现方式**
1. 在**样式**>**表盘**>**布局**>**圆形**设置表盘为半圆，根据需要勾选**两端显示圆角**
2. 在**样式**>**表盘**>**轴线**设置区间填充色为统一背景色
3. 在**样式**>**表盘**>**刻度线**处隐藏刻度线，在**样式**>**表盘**>**分割线**处隐藏分割线
4. 在**样式**>**进度**>**布局**处显示进度，根据需要勾选**两端显示圆角**
5. 在**样式**>**指针**>**指针**处设置指针为无
| 表盘设置 | 进度设置| 指针设置 |
| -------- | -------- | -------- |
||||
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/kpi.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/kpi"
title: "仪表板组件-KPI"
---
---
order: 33
navTitle: KPI
---
# 仪表板组件-KPI
KPI即关键绩效指标，通常用来展示一个或多个指标数据，如全国销售数量指标情况：
|单指标KPI|多指标KPI横向布局|多指标KPI纵向布局|
| ---- | ---- | ---- |
||||
示例地址：[单指标KPI](https://demo.succbi.com/v5/bi/kpi_1)
## 使用KPI组件{#start}
KPI的指标上至少取1个度量，如销售数量，销售金额等。
**操作步骤**
1. 双击或拖入度量【销售数量】到**指标**
2. 根据需求调整KPI的布局：切换到**样式**>**组件**>**布局**属性，设置如下属性
- **标题位置**：下拉选择**左侧**
- **指标对齐**：下拉选择**居左**
3. 设置KPI图标：设置**图标**位置为**左侧**，并选取一个图标，具体图标操作可参考[图标](../more/icon.md)
4. 设置KPI指标信息的单位：切换到**样式**>**指标**中，选择**销售数量**>**单位**，手动输入单位**件**
5. 如需多指标展示，可以在**数据**>**指标**再拖入其他指标
## 属性介绍{#properties}
### 布局{#layout}
布局是设置KPI组件的图标、指标标题、指标值和单位的位置和对齐方式。
- **排列方向** ：2个以上指标时设置有效，用于设置多指标的排列方式，包括**纵向**、**横向**
- **标题位置** ：标题相对于指标显示位置，包括**上方**、**下方**、**左侧**、**右侧**，选择不同的标题位置，下方会生成不同的指标对齐方式
- **指标对齐**：用于控制指标值与指标标题的对齐方式。**指标对齐**的选项说明如下
- **标题位置**选择**上方**、**下方**时，对齐方式可选择**居左**、**居中**和**居右**
- **标题位置**选择**左侧**、**右侧**时，对齐方式可选择**默认**与**两端对齐**，默认即居左对齐
- 2个以上指标**排列方式**为**横向**、标题位置为**左侧**、**右侧**时，不可设置该属性
- **值对齐** ：当**标题位置**选择**左侧**、**右侧** 激活此选项，控制值的对齐方式，包括**居左**、**居中**和**居右**，并且显示标题自动换行按钮，可以勾选激活此功能
- **整体对齐** ：图标、指标标题、指标值构成整体的横向对齐方式，包括**居左**、**居中**、**居右**
### 指标样式{#index-style}
标题、指标和单位的样式编辑。
- **标题** ：编辑指标标题的字体、字号、颜色等样式，指标标题默认以指标自身的名称生成标题，也可手动编辑指标标题
- **值** ：编辑指标值的字体、字号、颜色等样式
- **单位** ：指标的单位，编辑指标单位的字体、字号、颜色等样式，单位缺少状态下是空值，可以根据指标的计量单位输入内容
## 更多效果{#scenarios}
可以通过指标的布局属性组合设置，实现不同的布局显示效果。
|横向布局|纵向布局|两端对齐
| ---- | ---- | ---- |
||||
**实现方式**
- 将双指标拖入到**指标**中
- 横向布局： **指标布局**选择**横向**，**标题位置**选择**下侧**，**对齐方式**选择**居左**
- 纵向布局： **指标布局**选择**纵向**，**标题位置**选择**左侧**，**值对齐**选择**居左**
- 两端对齐： **指标布局**选择**纵向**，**标题位置**选择**左侧**，**指标对齐**选择**两端对齐**
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/odometer.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/odometer"
title: "仪表板组件-里程表"
---
---
order: 34
navTitle: 里程表
---
# 仪表板组件-里程表
里程表类似KPI，常用来展示一个指标数据，类似汽车里程表。如展示2010年的总销售金额：
示例地址：[里程表](https://demo.succbi.com/v5/bi/kpi-scene)
## 使用里程表组件{#start}
里程表的**指标**上取一个度量，如销售数量、销售金额等。
**操作步骤：**
1. 双击或拖入度量【销售数量】到**指标**
2. 点击**属性栏**>**样式**>**指标**>**填充**，切换背景为其他颜色
3. 点击**属性栏**>**样式**>**指标**>**符号**，切换符号为其他颜色
通过上述三个步骤即可快速实现展示出总销售数量以及样式改变。
## 属性介绍{#properties}
### 间距{#padding}
里程表支持设置指标数字之间的间距，在**属性栏**>**样式**>**指标**>**布局**>**间距**处进行设置。**间距**默认值为3。
### 溢出时缩排{#indent}
当显示数据长度超出里程表边框时会溢出到里程表控件之外，可以设置溢出时缩排，在**属性栏**>**样式**>**指标**>**字体**处，勾选**溢出时缩排**，此时会自动调整缩小字体、间距使数据全部显示在里程表控件中。**溢出时缩排**默认勾选。
### 指标样式{#index-style}
可分别设置数字与符号的样式，如字体大小，背景颜色等，得到不同样式的显示效果。
- **符号**：设置指标符号的字体，字号、颜色等样式
- **填充**：设置里程表的背景填充
- **边框**：设置里程表的边框
- **圆角**：设置里程表的圆角
- **阴影**：设置里程表的阴影
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/percentring.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/percentring"
title: "仪表板组件-进度环"
---
---
order: 35
navTitle: 进度环
---
# 仪表板组件-进度环
进度环图以空心的圆环表示某项指标分类的占比分布情况。如使用进度环展示各大区销售金额的占比：
示例地址：[进度环图](https://demo.succbi.com/v5/bi/kpi-scene)
## 使用进度环组件{#start}
进度环的**指标**上取一个度量，如折扣率、销售占比等。进度环中要绘制的数值大小不能为负值。
**操作步骤**
1. 双击或拖入度量【华南销售数量占比】到指标
2. 右击指标在【华南销售数量占比】**显示格式**>**百分比**中设置字段显示格式
通过上述2个步骤即可实现使用进度环展示华南销售数量占比。
## 属性介绍{#properties}
### 布局{#layout}
进度环可以自定义目标值、半径、圆环宽度、起始角度、顺时针增长和两端显示圆角等图形属性，实现个性化的效果，在**样式**>**系列**>**布局**中进行设置。
- **目标值**：进度环的目标值默认为1，由于进度环最终展示的比率数据是通过拖入指标数值大小除以目标值计算出来的，如果拖入的是数值而非比率数据，则需要按需修改目标值
- **半径**：可以自定义设置圆环半径，不得小于0，不得超过100%。默认为80%
- **圆环宽度**：可以自定义设置圆环的宽度，不得小于0，不得超过100%。默认为20%
- **起始角度**：可以自定义起始角度，默认为90°，
- **顺时针增长**：勾选时增长方向为顺时针增长，不勾选时按照逆时针增长。默认勾选
- **两端显示圆角**：勾选后圆环两端显示圆角。默认不勾选
### 填充{#background}
进度环可以通过**进度填充**和**背景填充**分别控制进度环圆环的填充方式以及圆环背景填充方式，在**样式**>**系列**>**填充**中设置，可参考[填充与背景](./column-chart.md#background)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/waterpercent.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/waterpercent"
title: "仪表板组件-水位图"
---
---
order: 36
navTitle: 水位图
---
# 仪表板组件-水位图
水位图类似KPI，常用来展示一个指标数据。如销售完成情况：
|圆形图标水位图|圆形水位图|菱形指标水位图|
| ---- | ---- | ---- |
||||
示例地址：[水位图](https://demo.succbi.com/v5/bi/water-percent)
## 使用水位图组件{#start}
水位图的**指标**上取一个度量，如完成率等。
**操作步骤**
1. 设置指标：双击或拖入度量【完成率】到**指标**
2. 选择形状：在**样式**>**系列**>**布局**中进行设置，默认为**圆形**，可以选择其他形状，具体样式可参考[布局](#layout)
3. 设置波浪颜色：在**样式**>**系列**>**填充**中对两层波浪进行自定义颜色设置
4. 如需设置图标，可将**更多**>**图标**拖入到水位图，具体可参考[图标](../more/icon.md)
## 属性介绍{#properties}
水位图提供了容器的设置选项，包含：
- [布局](#layout)
- [标签](#label)
- [波浪](#wave)
- [边框](#border)
### 布局{#layout}
水位图可以设置目标值、显示形状、水位图在组件内的填充半径以及内部距离
- **目标值** ：设置水位图撑满时需要达到的目标值
- **形状** ：水位图的显示形状，可设置如下样式
|圆形|正方形|圆角正方形|菱形|针形|箭头|撑满容器|
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
||||||||
- **半径** ：设置水位图在组件内的填充半径
- **内部距离** ：设置水位图中内边框和外边框的距离
### 标签{#label}
水位图可以设置是否显示标签，并且可以通过**浸入颜色**控制当水位浸没标签时显示颜色
### 波浪{#wave}
水位图提供两层波浪，且可以分别设置每层波浪的颜色。提供了波动特效设置，默认是选中状态，如果不需要可以勾选取消波动特效
- **波浪1颜色**：顶层波浪颜色，可以设置纯色和渐变色
- **波浪2颜色**：底层波浪颜色，可以设置纯色和渐变色
- **背景填充**：最底层背景颜色设置
- **波动**：勾选后启用波动动效
### 边框{#border}
水位图的最外层包含了外边框和内边框，且可以分别设置内外边框的线条样式、颜色和线条的粗细
- **外边框**：设置水位图外边框的线条样式、颜色和粗细
- **内边框**：设置水位图内边框的线条样式、颜色和粗细
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/wordcloud.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/wordcloud"
title: "仪表板组件-词云图"
---
---
order: 44
navTitle: 词云图
---
# 仪表板组件-词云图
词云图是由词汇组成类似云的彩色图形，能够直观的显示词频，常用来做一些用户的画像和用户的标签。词云图不仅能够展示大量文本数据，还能通过字体大小体现词汇的重要性。如使用词云图展示各产品的销量情况：
示例地址:[词云图](https://demo.succbi.com/v5/bi/wordcloud)
## 使用词云图组件{#start}
词云图的**维度**上取一个维度，如产品名称、颜色等，**大小**上取一个度量，如销售数量、销售金额等。
**操作步骤**
1. 双击或拖入维度【颜色】到**维度**
2. 拖入维度【颜色】到[颜色](../../design/data/data-style/color.md)，实现不同颜色区分不同的颜色产品
3. 拖入度量【销售数量】到[大小](../../design/data/data-style/size.md)，通过字体大小体现产品销售数量的多少
通过上述3个步骤即可实现使用词云图展示各颜色产品及对应的销量情况。
## 属性介绍{#properties}
### 设置形状{#shape}
在词云图中，文本默认朝中间聚集，形状与词云图组件框形状一致。通过设置形状，使词汇的聚集样式多样化，一般由关键词的内容来选择合适的形状。在**样式**>**系列**>**布局**中选择形状，也可以在形状菜单栏中上传自定义图标形状。
### 设置文本角度{#textangle}
在词云图中，文本默认为水平显示。通过设置文本角度，使各词汇的展示更错落有致：
- 设置间距：在**样式**>**系列**>**间距**中调整各词汇间的距离
- 设置文本角度：在**样式**>**系列**>**文本角度**中选择合适的角度
文本角度提供了三种选项可供选择：
- 水平：所有文字横向显示
- 水平+垂直：部分词汇横向显示，部分词汇竖向显示
- 水平+垂直+45度角：部分词汇横向显示，部分词汇竖向显示，部分词汇斜45度角显示
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/chart/gis-map.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/gismap"
title: "仪表板组件-GIS地图"
---
---
order: 48
navTitle: GIS地图
---
# 仪表板组件-GIS地图
当数据和地理位置有关系时，可以使用GIS地图展示地理空间数据。通过地图的空间数据分布快速获取信息，例如：
- 哪个省份的销售数量最佳
- 哪些城市的疫情最严重
- 全国便民服务网点的分布情况，哪些区域的分布比较密集，哪些区域的分布比较稀疏
## 使用地图组件{#component}
制作基本地图至少需要1个维度且设置了[地理角色](#geographical)，如省份字段；至少取1个度量信息，如销售数量指标，用于展示各省的销售数量分布。
示例地址：[区块图层地图](https://demo.succbi.com/v5/bi/district-layer_1)
操作步骤：
1. **拖入GIS地图**：从**组件区>图形**处将GIS地图拖入到画布中
2. **制作区块图层地图**：选中拖入的GIS地图，在**组件工具条**处，切换至**区块图层**
1. **设置位置**：双击或拖入维度【省】到**位置**属性。地图组件会根据数据粒度自动变更地图底图，更多说明可以查看[地图底图设置](#basemap)
2. **使用颜色标记**：双击或拖入度量【销售数量】到**颜色**
3. **设置地图的图例**：在**区块图层>样式>图例**下，在显示的下拉列表中选择【销售数量】指标，也可以按需选择其他选项
4. **删除不需要的图层**：系统自带添加了**底图图层**，如果不需要可以在**组件工具条**中删除该图层
:::tip
地图图层**数据**下的**位置**属性、**经度**和**纬度**属性,需要设置了地理角色的字段才能拖入到这几个属性中，地图的数据绑定就是通过地理角色来处理的。
:::
## 地图底图设置{#basemap}
拖入的地图组件默认使用的是中国地图作为地图的底图，也可以根据需求选择底图，设置操作步骤如下：
1. 在组件工具条上切换至**区块图层**
2. 在**样式**>**基本**>**底图**属性，下拉选择合适的底图
系统内置了如下底图内容：
- **自动**：默认是自动的模式，会根据拖入到位置的数据粒度自动变更底图。例如数据粒度是全国各省，则拖入的地图组件底图会自动变更为中国
- **中国**：包含了中国地图以及各省市地图，可以手动选择中国地图或者固定的省市地图
- **中国各市**：地图的边界显示为全国各地市的行政区域边界
- **湖北各县**：显示为湖北地图，且地图边界显示为湖北省各区县的行政区域边界
- **湖北自贸区**：包含了湖北省各自贸区的地图， 为自定义地图
- **世界**：世界地图，且边界显示为各国行政区域边界
### 自定义地图底图{#basemap-customize}
如果需要新的地图，如某经济开发区地图、某地级市地图，可以使用扩展方式实现新的地图底图，可以参考文档：[增加新的地图底图](#new-map)
## 地理角色设置{#geographical}
为字段分配了地理角色后，才能使用GIS地图展示地理信息数据。在为字段分配了地理角色后，系统会自动关联内置的数据，从而为每个数据关联上经度和纬度数据，实现在地图上精准定位数据。
地理角色的设置有两种途径：
- **在模型表中设置**：选中字段**右键>字段角色>地理**，按需选择
- **在仪表板中设置**：在数据列表中，选中模型字段，**右键>字段角色>地理**，按需选择
更多关于地理角色的介绍，请参考文档：[字段角色](../../../../data-gov/model/field-role.md)
## 地图图层{#layer}
地图由图层组成，图层可以单独使用，也可以组合构建酷炫的地图效果。提供了9个图层可供选择，包括：地图容器、底图图层、区块图层、散点图层、气泡图层、飞线图层、背景图层、热力图层、提示信息图层。其中:
- **地图容器**：该图层是内置图层，一个地图只能有一个地图容器图层且不允许删除，提供了地图通用属性的设置
- **其他图层**：可以无限制增加和删除，选中GIS地图在组件工具条处可以增加、复制和删除图层
### 带电子底图的地图{#baselayer}
地图设置了电子底图，可以显示除所选区域地图外其它区域的骨架脉络，如下图所示：
示例地址：[带电子底图的地图](https://demo.succbi.com/v5/bi/base-layer_1)
操作步骤：
1. **设置底图**：切换到**底图图层**，在左侧的属性栏中选择合适的底图样式
2. **设置蒙版**：可以在底图上添加一层蒙版，并设置蒙版的**颜色**和**透明度**。
#### 底图图层属性
在**样式>基本**下提供了底图图层的属性设置。系统内置了多个底图图层样式可供选择，也可以为底图加一层蒙版，以及设置底图的透明度和滤镜效果：
- **蒙版**：是指在底图之上加一层遮罩，可以设置蒙版的**颜色**和**透明度**
- **透明度**：设置底图的**透明度**
- **滤镜**：和ps的滤镜用法一致。默认是无滤镜，选择自定义启用滤镜，提供滤镜的样式设置
### 区块填充地图{#rectlayer}
区块填充地图是使用区块颜色深浅标识数据大小。制作区块填充地图是使用颜色标记来实现的，将度量数据拖入到颜色标记上即可实现：
示例地址：[区块填充图层-渐变](https://demo.succbi.com/v5/bi/district-layer_1)
操作步骤：
1. **添加地理数据**：切换到区块图层，双击或拖入维度【省】到**位置**
2. **添加颜色标记**：双击或拖入度量【销售数量】到**颜色**
上述操作实现的是连续的颜色填充底图，也可以实现分段颜色填充底图，该效果要求拖入到颜色中的字段是设置了数值分段的字段，操作步骤如下：
示例地址：[区块填充图层-分段](https://demo.succbi.com/v5/bi/district-layer_1)
操作步骤：
1. **准备数值型分段度量**：在[模型上设置分段](../../../../data-process/transform/calc-section-field.md)，或者在[仪表板内模型上分段](../../design/datasource.md#创建分段字段)都可以
2. **添加颜色标记**：将分段好的度量拖入到**颜色**中，右键该度量选择**离散**。可以选择默认的色板颜色标记，也可以根据数据规则自定义每个区间段的颜色
::: tip
颜色的设置提供了**离散**和**连续**两种模式，默认为连续的设置，连续适合度量数据，离散要求度量为数值型分段指标才可以使用
:::
#### 区块图层属性
在**样式>基本**下提供了区块图层的属性设置，可以设置区块的样式等内容，如下：
- **底图设置**：在[地图底图设置](#basemap)中已经介绍
- **标签**：设置地图区块上的标识，可以在**数据>标签**中设置，也可以在这里设置
- **区块**：提供了区块缺省**颜色填充**，**区块的内/外边框**，以及**内/外阴影**
- **高亮样式设置**：当鼠标移至区块时的样式，包括**标签**和**区块**的设置
- **高亮标签**：标签的样式设置包括**字体**和**文字阴影**设置
- **高亮区块**：区块的样式设置包括**颜色**、**边框**和**阴影**设置
### 散点地图{#scatterlayer}
散点地图是在地图区块上以点或图标形式展示，点的位置是使用经度和纬度在地图区块上标注的。其中经度和纬度的数据来源在[地理角色](#geographical)中有介绍。
示例地址：[普通散点](https://demo.succbi.com/v5/bi/scatter-layer_1)
操作步骤：
1. **添加地理数据**：添加散点图层，将【省】拖入到**位置**
2. **设置标记**：
1. **设置大小标记**：将【销售数量】拖入到**大小标记**，并在**样式>基本>形状**属性中，自定义形状**大小**和**颜色**
2. **设置颜色标记**：使用指标标记形状的**颜色**，将对应指标拖入到**颜色标记**中即可
::: tip
散点也支持通过**经度**和**纬度**来定位，将对应的字段双击或拖入到**经度**和**纬度**即可。
:::
#### 散点图层属性
在**样式>基本**下提供了散点图层的属性设置。
- **标签设置**：当散点图层的标签设置为显示时，标签文字和散点可能会有重叠，可以在**标签标记**中设置标签的**位置**和**显示角度**，其中标签的位置是相对散点的位置。
- **形状设置**：散点图可以自定义形状，可以在**样式>基本>形状中**进行设置，包括**形状**、形状的**颜色**和**大小**。同时也可以设置点的**边框线颜色**和**粗细**等。
- **散点的偏移设置**：在偏移属性中提供了**水平**和**垂直偏移**，偏移量参照[地理角色](#geographical)关联的经纬度进行计算
### 海量散点地图{#scatterlayer-volume}
当需要在地图上展示海量的数据（如网点位置）时，可以使用海量散点图。原理是通过经纬度来确定点位，在地图上展示出海量的散点。
示例地址：[海量散点](https://demo.succbi.com/v5/bi/scatter-layer_1)
操作步骤：
1. 添加散点图层，将【经度】、【纬度】字段拖到对应的位置上即可
### 气泡地图{#bubblelayer}
与散点地图的使用场景基本一致，相比于散点图层，气泡图层侧重于动态效果的展示。
示例地址：[自定义气泡特效](https://demo.succbi.com/v5/bi/bubble-layer_1)
操作步骤：
1. **添加地理数据**：添加气泡图层，将【省】拖入到**位置**
2. **设置标记**：
1. **设置大小标记**：将【销售数量】拖入到**大小标记**，并在**样式>基本>形状**属性中，自定义形状**大小**和**颜色**
2. **设置颜色标记**：使用指标标记形状的**颜色**，将对应指标拖入到**颜色标记**中即可
3. **添加动效**：在**样式>基本>动画效果**中更改动画效果，默认是**涟漪-线**，可以改为呼吸动效等其他效果
#### 气泡图层属性
在**样式>基本**下提供了气泡图层的属性设置：
- **气泡形状**：内置了样式，也可以选择系统自带的图片库或定义上传图片。同时可以设置气泡的颜色和大小等样式
- **动画效果**：内置了多种动效可供选择
- **动效速度**：动画效果的播放速度，范围为0-1。 设置为1时动画的播放速度为每秒一次。播放速度越小，动画播放越慢
- **不透明度**：气泡渐隐时的不透明度。**渐隐渐现**的特有属性，范围为0-1
- **动效范围**：气泡放大的范围。**呼吸动效**的特有属性，范围为1-3
- **偏移**：调整气泡位置，可以分别调整**水平**和**垂直**方向上的位置。偏移量参照地理角色关联的经纬度进行计算
### 流向地图{#flowlayer}
当需要展示数据的流动情况，如人口流向时，可以使用流向地图。原理是通过流出地和流入地的行政区划代码确定起点和终点的点位，然后通过飞线连接起来。
示例地址：[分散流向图](https://demo.succbi.com/v5/bi/flow-layer_1)
操作步骤：
1. **添加地理数据**：添加**飞线图层**，拖入维度【武汉】-【行政区划代码】到**起点**，拖入维度【城市】-【行政区划代码】到**终点**
2. **设置飞线样式**：在**样式>线条**中调整线条的**颜色**和**粗细**等，也可以设置特效的**显示**及特效**动画**等
#### 飞线图层属性
在**样式>基本**下提供了飞线图层的属性设置：
- **线条**：设置飞线样式，包括飞线**线型**、**颜色**和**粗细**
- **显示曲线**：勾选后飞线以曲线的形式展现，否则以直线的形式展现
- **曲度**：勾选显示曲线后出现该属性，用来调整飞线的弯曲程度
- **显示箭头**：勾选后飞线末端显示箭头
- **特效**：设置飞线的特效样式
- **图标**：设置飞线特效中显示的图标**样式**、**颜色**和**大小**
- **动画时间**：设置动画的播放完成时间，单位为秒，时间越短，播放速度越快
- **显示尾迹**：勾选后，动画播放过程中，图标末端显示运动轨迹
- **尾迹长度**：图标末端显示的运动轨迹的长度
### 带3D背景的地图{#imagelayer}
当需要让地图看起来更有立体感时，可以使用带3D背景的地图。叠层的阴影是通过背景图层实现的，在区块下面叠加一层颜色较深的地图图片，并进行偏移。这样能使整个地图看起来有“厚度”，从而呈现出3D的效果。
示例地址：[3D背景地图](https://demo.succbi.com/v5/bi/3d-map)
操作步骤：
1. **设置背景图层图片**：添加**背景图层**，在**样式**中设置图片填充，图片库选取产品自带的中国地图背景图层或自定义上传
2. **调整坐标参考系**：调整坐标参考系的**x、y坐标**，具体的参考下面的[背景图层属性](#背景图层属性)介绍
#### 背景图层属性
背景图层提供了背景图片的填充和透明度的设置：
- **填充设置**：在**样式>填充**中可以选择内置的地图背景图片图层或上传本地提前准备好的图片
- **透明度设置**：背景图层的透明度，范围为0-1。
背景图层还需要设置**坐标参考系**，才能达到较好的3D效果。在**样式>坐标参考系**中可以设置相关属性：
- **x、y坐标**：用来定位背景图层的位置，不同的地图坐标也是不同的，计算方式可以参考下文
**坐标参考系：EPSG3857**
EPSG3857是一种地图坐标系，其实就是地图的边界的经纬度，可以通过左下角和右上角的X、Y坐标，来调整背景层的位置。其中X坐标的取值范围为\[-180，180]，Y坐标的取值范围为\[-90，90]。坐标参考系根据不同的地图（如中国地图/湖北省地图/武汉市地图等）采用不同的坐标参考系。可参考：[中国各个省市经纬度坐标范围](https://doc.xuehai.net/be478d6223eade9a5ef88aa9d.html)
以中国地图为例，我们只需要通过中国地图的边界经纬度就可以确定背景图层左下角及右上角（如下图所示） ，由此就可以将中国地图的背景图层相对较好的卡在中国gis地图的下方。可以参考下图：
### 热力地图{#heatmaplayer}
当需要分析分析目标客户物理位置分布和分布密度时，可以选择热力地图。原理与散点地图类似，根据经纬度确定热力点位，根据权重值大小自动从设置好的渐变色中获取色值。
示例地址：[热力地图](https://demo.succbi.com/v5/bi/heatmap-layer_1)
操作步骤：
1. **添加数据**：添加**热力图层**，拖动字段【纬度】到**纬度**，拖动字段【经度】到**经度**，拖动字段【实缴资本（万元）】到**权重**
2. **设置热力点样式**：在**样式**中设置热力点**颜色**、**半径**和**透明度**属性
#### 热力图层属性
在**样式>基本**下提供了热力图层的属性设置。
- **颜色**：热力点的颜色，只能使用渐变色。热力点的颜色根据权重值自动从渐变色中获取对应的颜色
- **半径**：热力点的半径
- **透明度**：热力点的透明度
### 带TopN提示信息的地图{#tooltiplayer}
当需要在地图上展示TopN地区的指标详情时，可以使用带TopN提示信息的地图。原理是在地图区块上增加一层提示信息图层，通过设置过滤条件来筛选出符合条件的提示信息点位，展现在地图上。
示例地址：[带TopN提示信息的地图](https://demo.succbi.com/v5/bi/tooltip-layer_1)
操作步骤：
1. **添加地理数据**：添加**提示信息图层**，拖入字段【省】到**位置**上
2. **添加过滤条件**：拖入字段【销售数量排名】到**筛选器**，输入筛选条件**等于1**
3. **设置提示信息样式**：在**样式**中调整提示信息的样式属性
如果想要展示多个不同样式的提示信息，可以按照以上步骤设置多个提示信息图层。
#### 提示信息图层属性
提示信息图层，最关键的是设置显示在地图上的信息，提供了如下属性设置：
- **提示内容**：即显示在地图上的**标注信息**，可以写表达式，可以插入模型字段和参数等
- **引线样式设置**：即地图区块和提示信息之间的连线样式设置，可以选择**直线**、**折线**或**不显示**
- **直线**：可以设置线的**长度**和**显示方向**，以及线的**类型**、**粗细**和**颜色**
- **折线**：折线分为2段，可以分别设置每段的**长度**，以及线的**类型**、**粗细**和**颜色**
- **端点**：设置标注信息点的**图标**、**颜色**和**大小**
## 带时间轴的地图{#timeline}
当需要在地图上展示按时间动态变化的数据时，可以使用带时间轴的地图。时间轴地图的原理是：
1. 定义一个全局参数，在时间轴上设置这个全局参数的交互，即可实现时间轴带动了全局参数的变化
2. 地图上使用全局参数设置过滤条件，这样参数变化时，地图数据也随之动态变化
示例地址：[带时间轴的地图](https://demo.succbi.com/v5/DEMO/app/DEMO.app/%E5%9C%B0%E5%9B%BE%E4%B8%93%E9%A2%98.tpg?id=%E5%B8%A6%E6%97%B6%E9%97%B4%E8%BD%B4%E7%9A%84%E5%9C%B0%E5%9B%BE)
操作步骤：
1. **设置参数**：参数名称为`日期`，参数表达式为起始日期`20200124`
2. **设置时间轴组件**：
1. 拖入时间轴组件并添加数据
2. 在时间轴组件的**交互**中添加**改变参数值**
3. 点击**编辑参数**，设置参数名称为`日期`，数据来源为`日期`，值为`原值`
3. **设置地图组件**
1. 将**gis地图**切换到区块图层并添加数据
2. 拖入字段【日期】到**过滤器**，设置过滤条件为【日期】等于参数`日期`
## 地图交互设置{#interaction}
地图除了支持丰富的图层，还可以设置多种交互，比如过滤数据、打开链接、层层下钻等。
### 过滤数据{#filteringdata}
当需要通过点击地图区块来刷新页面其他组件的数据时，可以设置过滤数据的交互。过滤数据的原理是：
1. 点击地图区块后，系统会自动获取区块对应的行政区划代码
2. 系统计算其他组件的数据时，会自动将获取到的行政区划代码附加到查询条件中
示例地址：[地图交互\_过滤数据](https://demo.succbi.com/v5/bi/%E5%9C%B0%E5%9B%BE%E4%BA%A4%E4%BA%92)
操作步骤：
1. **设置参数**：参数名称为`省份`，表达式为`全国`，用于插入到其他组件的标题中
2. **拖入并设置条形图和柱形图并添加数据**
3. **拖入并设置gis地图**
1. 切换到区块图层，添加数据
2. 在**交互**中点击**添加动作**>[过滤数据](../../design/action/filter-data.md)
3. 在**交互**中点击**添加动作**>**设置参数值**，参数名称为`省份`，数据来源为`省`，值为`显示值`
### 打开链接{#openlinks}
当需要实现点击地图区块，跳转到其他页面来展示所选区域的详细数据时，可以设置打开链接的交互。打开链接的原理如下：
1. 点击地图打开链接时将某些过滤条件（如省份、时间等）传递到子页面
2. 子页面设置对应的参数来获取传递过来的值，并且对数据进行过滤
示例地址：[地图交互\_跳转页面](https://demo.succbi.com/v5/DEMO/app/DEMO.app/%E5%9C%B0%E5%9B%BE%E4%B8%93%E9%A2%98.tpg?id=%E5%9C%B0%E5%9B%BE%E4%BA%A4%E4%BA%92_%E8%B7%B3%E8%BD%AC%E9%A1%B5%E9%9D%A2)
操作步骤：
1. 切换到区块图层，添加数据
2. 点击**交互**>**添加动作**>[打开链接](../../design/action/linkto.md)>**编辑链接**
3. 设置[相关属性](/dash/action/openlink/#property)和需要传递的过滤条件，设置完成后点击**确定**
### 层层下钻{#drilldown}
点击地图某个区块后可以层层下钻到下一级区域地图，通过设置下钻交互即可实现。使用下钻交互的前提条件是，拖入到**位置**属性的字段需要关联带有层次的维表。层层下钻的原理如下：
在地图上设置下钻交互，点击地图区块时，系统会自动根据关联的行政区划维表的层级关系，钻取到下一层级。
示例地址：[地图下钻](https://demo.succbi.com/v5/bi/%E5%9C%B0%E5%9B%BE%E4%BA%A4%E4%BA%92)
操作步骤：
1. 切换到区块图层，拖入字段【省】到**位置**上
2. 点击**交互**>**添加动作**>[下钻](../../design/action/drill-down.md)
## 属性介绍{#property}
除了上述介绍的每个图层的特有属性，不同的图层还有一些通用的属性：
### 地图缩放级别设置{#zoom}
地图可以设置缩放级别，提供了最大和最小级别的缩放设置：
- **最小缩放级别**：当前图层支持缩放的最小级别，当地图缩放级别小于最小缩放级别时，隐藏当前图层
- **最大缩放级别**：当前图层支持缩放的最大级别，当地图缩放级别大于最大缩放级别时，隐藏当前图层
### 图例设置{#legend}
在**样式>图例**下可以设置图例的显示，并提供了图例的属性设置：
- **显示**：控制图例是否显示，以哪种维度显示
- **位置**：图例显示的位置
- **对齐**：图例的对齐方式，图例位置不同时，对齐方式的选项也不同
- **滚动翻页**：勾选后图例会分页显示，可以滚动翻页来切换查看未显示的图例
## 自定义地图{#customize}
目前系统自带了全国-各省-各市三级层次的地图，基本满足项目的地图区块展示、下钻等需求。在某些情况下，还可以自定义地图来达到期望的效果，如：
1. 从某市下钻到某区
2. 需要满足能够按照区域来划分区块的场景，比如华中华南等地区
3. 地图新增功能区，如开发区/自贸区等
### 增加乡镇/街道区块{#villages}
系统自带的地图只到市级地图中查看各区的情况，若需要下钻查看区县地图，即在地图上通过省市县下钻到县级后，能够以区块显示乡镇街道信息，则需要在系统内置的地图包中增加需要下钻的位置地址，以增加湖北省武汉市江汉区下街道区块为例，步骤如下：
1. **基于已有地图制作新的区块**：由于系统自带的扩展是不可修改的，所以需要点击[下载](https://www.jianguoyun.com/p/Da65xRsQz--gChjnkKwE)（提取码：SuccBI）原地图扩展包，并在此基础上制作新的地图。在示例扩展包中，每个省都有一个json文件用来存放该省下所有市的信息，每个市下有一个json文件用来存放该市中所有区的信息，因此我们补充的是每个区下所有的街道信息，即每补充一个区的街道信息，都需要新建一个json文件
2. **新增区块**：在目录下创建`420103.json`文件用来存放江汉区街道区块的信息，可以在[阿里地图DATAV](http://datav.aliyun.com/tools/atlas/#\&lat=30.332329214580188\&lng=106.72278672066881\&zoom=3.5)上搜索目标地区，若能够找到目标地区，且该地区上区块绘制完整，则直接下载该json文件即可；若没有现成的区块json文件，如搜索江汉区，仅展示了江汉区完整的区块，没有对街道的划分，则需要手动绘制其内部边界
1. 将网页中的json内容复制到[绘制网站](http://geojson.io/#map=9/31.1223/113.9502)中，在地图右侧可使用多边形绘制工具绘制江汉区内部的各个街道的区块边界，在右边json中加上每个区块的中心点位置、名称以及adcode等
2. 由于是在江汉区地图的基础上绘制其内部区块，所以json中包含了“江汉区”的信息，这时需要在json中删除“江汉区”的代码，仅保留各街道信息，再将所有代码复制到目录文件夹下`江汉区xx街道.json`中，该json文件的名称与第三步中添加的街道编码一致
3. **确认系统表的数据**：确认系统[cn\_adcode](https://demo.succbi.com/v5/DEMO/data?:open=WjHI0Q2yNkCJPshiQli9uE&:tblview=modelData)表中的信息与新增的区划信息是否对应，若对应不上，则按照新的区划信息进行修改
4. **确认行政区划维表数据**：检查行政区划维表中是否包含街道信息，若没有，同步骤3一样需要增加对应的信息
5. **添加层级关系**：修改`package.json`文件，在**武汉市**的下方新增`items`，用来存放武汉市下各区信息，可参考文档[map-地图拓展](../../../../dev/extension/extension-points/map.md#package.json)
6. 将上述步骤制作完成的文件上传至系统中使用，主要有以下几个步骤
1. **删除系统自带的地图扩展包**：在服务器端将系统自带的**中国地图**，即在系统ROOT.war（或其他名称）包，把`\ROOT\dist\extension\extensions`路径下的`succ-map-china`文件夹删掉
2. **导入新的扩展包**：启动系统后，将上述步骤制作的整个`succ-map-china`文件夹压缩，通过[扩展](../../../../devops/extension-manage/README.md)上传至系统中
3. **确认扩展包是否上传成功**：在**系统数据**>**资源**>**extensions**文件夹下确认导入的文件是否正确，若在**extensions**的下级目录中存在`succ-map-china`文件夹，则表示扩展上传成功，此时该扩展文件会自动替换原`succ-map-china`扩展包的作用，如下图所示：
4. **使用新的地图扩展包**：在GIS地图组件中设置**区块图层**底图为**自动**，即可实现下钻的效果
上述步骤中涉及到了`区块json`和`package.json`两类json文件，可以简单的理解为：`区块json`是用来描绘地图区块形状的，而`package.json`是用来记录区块之间上下级关系的。
:::tip
1. 点击**市**下钻到**区**时，若不需要显示其内部的区域划分，则可以不绘制内部边界。将[阿里地图DATAV](http://datav.aliyun.com/tools/atlas/#\&lat=30.332329214580188\&lng=106.72278672066881\&zoom=3.5)中导出的json文件放在与**市**平级的目录下，并在`package.json`文件添加该市对应的下级信息即可
2. 在**区块图层**的**中国**底图中确认新加的区块是否在列表中存在，若存在，表示区块新增成功。[下钻](../../design/action/drill-down.md)交互在使用时需要勾选**允许下钻末级节点**，若勾选后还无法下钻到新增的区块，则需要确认新增区块是否有数据
3. 若下钻后发现区块边缘不齐，高亮的区块与实际展示的边界不一致，则可以判定是下层区块的边界经纬度与上层json文件中记录的边界经纬度不同导致的，如在`420100.json`中记录了武汉市的下级区块江汉区的经纬度，与新增的`420103.json`中记录的经纬度不同，此时可以用`420100.json`中江汉区的经纬度去替换`420103.json`中的经纬度信息，保证其上下级的边界经纬度一致，使区块边缘对齐
4. 若下钻到区级后，散点没有在区级地图中显示或显示在区块外部，则需要检查该散点的经纬度是否在对应的区块经纬度范围内
5. json文件在编辑时，可以使用编译软件，或在系统的**应用**中，新建一个后缀为json的文件，将代码复制进去并格式化，方便阅读和编辑，完成修改后再将代码复制到目标区块json文件中
:::
### 自定义大区区块{#block}
系统内置地图根据地理位置划分为八个大区，分别是东北、华东、华中、华北、华南、港澳台、西北、西南。当需要调整大区划分或增加新的大区时，可以在系统自带的[行政区划](https://demo.succbi.com/v5/DEMO/data?:open=JNim5L6UWlBLivKoX0LagC&:tblview=modelData)维表中修改大区字段数据即可。
### 增加新的地图底图{#new-map}
增加新的地图底图即不使用系统自带的地图形状和维表，与[增加乡镇/街道区块](#villages)、[自定义大区区块](#block)是对原有的文件进行修改不同，新增[地图底图](#basemap)不仅需要对地图中的区块重新绘制，还需要按照新地图制作一张新的维表，也就是说需要完整的制作一个地图扩展包。最终通过导入地图扩展包的形式导入至系统中使用，简版示例可点击[下载](https://www.jianguoyun.com/p/DZgbRCYQz--gChiKkawE)（提取码：SuccBI），具体步骤如下：
1. 新建文件夹，该文件夹下包含`地区.json`、`package.json`文件，若希望上传的拓展包有缩略图，还可以包含一个`thumbnail.jpg`缩略图文件
2. 地区json的绘制与[下钻到乡镇区块](#villages)中介绍如何绘制json文件一致，绘制完成后将json数据从网页上拷贝至json文件中即可
3. `package.json`的内容可参考文档[map-地图拓展](../../../../dev/extension/extension-points/map.md#package.json)
以武汉市地图为例模板如下
```json
{
"name": "succ-map-wuhan",
"displayName": "武汉地图",
"categories": ["datav"],
"version": "1.0.0",
"compatibilities": {
"platform": "^4.0.0"
},
"author": {
"name": "xx"
},
"thumbnail": "thumbnail.jpg", //若上传了缩略图则包含该属性
"contributes": {
"map": {
"hierarchies": {
"id": "420100",
"caption": "武汉市"
}
}
}
}
```
4. 将文件夹进行压缩，并通过[扩展](../../../../devops/extension-manage/README.md)导入至系统中
5. 在系统内部新建一张地理维表，新建维表可参考文档[录入数据](../../../../data-gov/input-model-data.md)，维表中至少要包括**行政区划代码**字段，建议新增行政区划名称字段用来中文展示该区块的名字，其他字段如中心点、简称等按照需求进行添加，若希望该地图支持下钻，还需要为该维表设置层次，具体可参考文档[数据级次](../../../../data-gov/model/data-hierarchy.md)，维表制作完成后在数据表中关联该表
6. 切换**GIS地图**控件的图层至**区块图层**，**底图**属性中选择上传的新地图即可使用
## 案例-地图下钻与动态图层{#use-case}
GIS地图时常会出现多个图层搭配使用的场景，如：
1. 在全国地图上显示数据的流向情况，当下钻到省级地图时，显示该区域中各机构的分布情况
2. 省级、市级、区级用户在查看页面时，只能展示其所属区域的数据等
为了更快速的理解和使用GIS地图组件，下面以一个具体的案例来介绍在GIS地图中，多个图层如何交叉使用。
### 业务介绍{#description}
案例实现的效果如下：
1. 用户区分为全国、省级、市级用户，不同用户组的用户只能查看其权限范围内的数据，如全国用户可以查看所有省份的数据，省级用户查看其对应省份的数据，市级用户查看对应城市的数据等
2. 图层效果：
1. 在全国地图上展示数据的流向情况，如从湖北省流向其他省份等
2. 当地图下钻到xx省后，在区级地图上展示机构的分布情况
3. 点击地图的区块时，自动过滤仪表板内其他的图形数据
根据上述业务的需求，我们可以初步判断配置页面时，需要从**数据的准备**、**权限**、**地图配置**这几个方面入手，下述是详细步骤。
### 数据准备{#prepare}
- **地图数据要求**：为了能在**GIS地图**组件中使用数据，数据中必须包含**行政区划**字段，并且需要关联[行政区划维表](https://demo.succbi.com/v5/DEMO/data?:open=JNim5L6UWlBLivKoX0LagC&:tblview=modelData)，有如下几点需要注意：
- SuccBI系统的**default**库中已经存在其所对应的物理表，名称为`gen_dim_xzqhfz`，可以将[数据表导入模型](../../../../data-gov/import-table.md#data-table-import)后，再在业务表上关联该维表
- 数据表导入为模型后，需要为其设置父子层次，具体介绍可参考文档[数据级次](../../../../data-gov/model/data-hierarchy.md)，或者仿照[行政区划维表](https://demo.succbi.com/v5/DEMO/data?:open=JNim5L6UWlBLivKoX0LagC&:tblview=modelData)的层次进行设置
示例地址：[按行政区划层级下钻](https://demo.succbi.com/v5/demo/按行政区划层级下钻/play)
- **流向数据要求**：
- 在**GIS地图**上配置[飞线图层](#flowlayer)来表示流向信息，由于**GIS地图**中每个图层是单独取数的，每一行数据对应一条飞线，所以**流向数据**可以与**业务数据**在同一张模型表内，也可以与**业务数据**分离
- **飞线图层**的取数不仅支持使用**行政区划**字段，还可以通过**起点**和**终点**的**经纬度**来进行设置，若使用**经纬度**，则需要在模型上对**经度**和**维度**字段设置对应的[字段角色](../../../../data-gov/model/field-role.md)
示例地址：[人口流向图](https://demo.succbi.com/v5/bi/%E5%9F%8E%E5%B8%82%E4%BA%BA%E5%8F%A3%E6%B5%81%E5%90%91)
### 地图配置{#settings}
- **地图下钻的取数**：地图的下钻取数，需要在[区块图层](#rectlayer)中设置，有以下两点需要注意：
- 在**区块图层**>**样式**>**布局**中设置**底图**为**自动**（该选项为默认项）
- 区块图层位置属性设置：
- 若地图初始显示为**全国**地图，则需要将【行政区划】字段的【省】拖拽到**位置**属性中
- 若地图初始显示为**xx省**地图，则需要将【行政区划】字段的【市】拖拽到**位置**属性中
示例地址：[按行政区划层级下钻](https://demo.succbi.com/v5/demo/按行政区划层级下钻/play)
- **地图图层效果设置**：根据业务的需求，在**全国**地图上展示数据的流向，下钻后不再展示飞线，当钻取到**省级**地图后显示该区域的机构分布情况，示例地址：[飞线和散点图层的显示与隐藏](https://demo.succbi.com/v5/demo/飞线和散点图层的显示与隐藏/play)，详细步骤如下：
- **地图下钻取数设置**：在**区块图层**上取数为【行政区划】字段下的【省】
- **飞线图层设置**：
- 取数设置：添加**飞线图层**和**散点图层**并根据数据分别取数（行政区划字段/经纬度）
- 图层显示条件设置：在**飞线图层**>**数据**>**高级**中设置**显示**属性为**条件**，并输入表达式`[gisMap1].[下钻级次]=0`，表示gisMap1组件不下钻时，显示**飞线图层**
- **散点图层设置**：在**散点图层**>**数据**>**高级**中设置**显示**属性为**条件**，并输入表达式`[gisMap1].[下钻级次]!=0`，表示只要gisMap1组件下钻后，就显示**散点图层**
- **根据不同权限用户定位地图**：由于该地图需要支持下钻，而下钻的**区块图层**取数需要具体取到【行政区划】字段的【省】、【市】等这种层级字段，所以需要根据不同权限的用户，展示不同的地图，即**全国**用户查看的地图取数为【省】，**省级**用户查看的地图取数为【市】，这要借助[多页面板](../layout/panelbook.md)组件，并在**多页面板**组件的不同页面分别制作上述的两个地图，可参考DEMO[总体经营情况](https://demo.succbi.com/v5/bi/%E6%80%BB%E4%BD%93%E7%BB%8F%E8%90%A5%E6%83%85%E5%86%B5)
- 在**多页面板**的每一页中配置不同的**GIS地图**组件
- 在**多页面板**>**数据**>**默认页**中设置为**动态页**，并输入表达式判断不同权限的用户展示不同的页面，如`IF([用户].[部门] like '80%' AND [用户].[部门] != "800000",'panel2','panel1')`表示以部门编号以80开头且编号不为800000的用户（即分公司用户）在打开仪表板时，查看panel2的内容（即xx省的地图），否则查看panel1的内容（即全国地图）。这里根据业务需要，使用`IF(USER_INGROUP('省级'),'panel2','panel1')`表示当用户属于省级用户组时，查看panel2的内容，否则查看panel1的内容
- **过滤数据**：
- **过滤同一模型表数据**：在**区块图层**上配置[过滤数据](../../design/action/filter-data.md)交互
- **过滤不同模型表数据**：有两种方式
- 定义全局参数，通过点击区块为参数赋值，并在模型表上通过参数设置过滤条件，可参考文档[参数](../../design/data/param.md)
- 在组件中[过滤](../../design/data/data-filter/README.md)数据
- **页面美化**：仪表板中自带了需要**样式设置**，如**风格**、**背景**等，可按照需求对图形的样式进行调整，具体的介绍可以参考文档[美化](../../../../../getstarted/SuccBI/dashboard/beautify-dashboard.md)
### 权限配置{#permission}
省级、市级用户登录系统后显示对应区域的地图，并展示该区域的数据，这涉及到为用户分配数据范围，可参考文档[数据级次权限](../../../../permission/grant/datarange.md)，具体思路如下：
1. **区分用户**：在业务上为不同权限用户分类，在系统中则需要借助[用户组](../../../../permission/groups.md)把这些用户区分开来
2. **设置数据范围**：业务上一般以用户所属行政区划来判断其查看某地的数据权限，可根据文档[数据级次权限](../../../../permission/grant/datarange.md)进行设置
3. **用户组权限分配**：区分了不同用户后，需要为**用户组**设置具体的权限，如查看某页面的权限、查看某页面时的数据范围等，可参考文档[权限操作说明](../../../../permission/grant/operations.md)
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/input"
title: "输入组件"
---
---
order: 4
navTitle: 输入
---
# 输入组件
仪表板提供了丰富的输入组件，每一个输入组件都可以当作一个输入参数，常用于仪表板数据的筛选过滤：
!!!children (guide/data-viz/dash/components/input) 1 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/combobox.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/combobox"
title: "仪表板组件-下拉框"
---
---
order: 1
navTitle: 下拉框
---
# 仪表板组件-下拉框
下拉框使用下拉菜单展示或选择内容，用于过滤数据。如下拉框选择不同的颜色来过滤数据：
示例地址：[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用下拉框组件过滤数据{#filter}
使用下拉框过滤数据有**使用枚举值**和**使用模型数据**两种方式。
### 使用枚举值过滤数据{#enum}
当下拉框的列表数据未与模型表的数据关联时，可以在**可选项>列表数据**属性中选择`枚举值`，手动添加枚举值，并对其他组件设置[过滤](../../design/data/data-filter/README.md)条件来达到过滤数据的效果，具体设置可以参考[选择面板](../layout/panel.md)文档。
### 使用模型数据过滤数据{#table}
当下拉框的下拉列表来自模型数据时，可以使用自动过滤功能进行数据过滤。需要将某个维度字段拖入到**属性栏>数据>字段**中，之后属性栏会出现**过滤**的属性设置，提供了如下选项设置：
- **自动过滤**：拖入模型字段到**数据>字段**后，这里是默认勾选的，表示会按照选择的内容自动过滤其它组件数据。如果需要手动过滤数据，可以取消勾选，在过滤器中设置[过滤条件](../../design/data/data-filter/README.md)。
- **为空时包含所有值**：默认勾选，即下拉框没有选择任何内容的时候，查询所有内容
- **影响范围**：设置过滤影响哪些组件，默认是全部，也可以根据情况筛选过滤的组件，在下拉列表中选择即可
- **作用数据源**：默认为当前数据源，下拉列表提供了如下两种选项
- **当前数据源**：自动过滤当前数据源，即拖入的字段所属的数据模型
- **关联数据源**：自动过滤当前数据源和关联数据源，关联数据源即其他关联同一维表的数据模型
以使用【颜色】字段过滤仪表板的数据为例，具体操作步骤如下：
1. **使用下拉框组件**：在组件区>输入中将下拉框组件拖入到画布中
2. **拖入模型字段并设置相关属性**：把【颜色】拖入到**数据>字段**内，勾选**允许清空**，**搜索**设置为`不显示`
## 下拉列表为维度字段{#dimension}
当下拉列表的数据在已有模型中存在时，可以将所需的**维度**字段拖入到**下拉框>数据>字段**中，**可选项>列表数据**属性选择**维表**，下拉列表会显示相应字段的数据。
### 下拉内容设置{#field}
用户可以在**可选项>列表数据**属性中自行选择下拉列表的显示内容，分为以下两种情况：
- 如果拖入的字段没有层次，**列表数据**选择`维表`，则下列选项为单级列表
- 如果拖入的字段是[层次字段](../../../../data-gov/model/data-hierarchy.md)，**列表数据**则提供了多个选项，会显示在模型表中已经添加的层次，选择`维表`则下拉列表为显示所有层次的多级树形结构，也可以按需选择某一层次，比如拖入【门店】字段，可以选择`大区门店`或者`省市县门店`等层次：
:::tip
**可选项>列表数据**中的`字段值去重`选项是按照维度字段去重显示，即在下拉列表中去掉重复的字段值。
:::
### 根节点设置{#root}
当拖入的字段为多层次字段时，可以设置显示哪些根节点，以及是否显示根节点，具体可以参考SuperPage下拉框[根节点设置](../../../../app/superpage/components/input/combobox.md#root)。
### 显示最大级次{#max}
当在下拉列表中显示的是一个带有层次的数据时，可以设置显示最大级次属性，限制树形显示到哪一个级次。该属性只能输入数字，即0、1、2...，其中0表示最大级次。
### 维项过滤设置{#dimension-filter}
**可选项>维项过滤**属性是一个过滤条件，可以过滤哪些字段不显示，更多规则可以参考SuperPage下拉框[维项过滤设置](../../../../app/superpage/components/input/combobox.md#model-filter)。
## 下拉框默认值设置{#default}
设置了下拉框的数据来源之后，默认不进行过滤，如果需要设置默认的字段值过滤，需要在**输入>默认值**中选择某一节点，支持写表达式。
## 下拉框搜索设置{#search}
当下拉框的数据较多时，支持进行搜索，在**数据>搜索**中设置，默认为`8`，即下拉选项个数超过8就显示搜索框，**可选项>搜索**属性下拉框另外还提供了`显示`、`不显示`、`12`和`15`四个选项，可以按照需要进行选择。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/selectpanel.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/selectpanel"
title: "仪表板组件-选择面板"
---
---
order: 2
navTitle: 选择面板
---
# 仪表板组件-选择面板
**选择面板**组件用来平铺展示多个选项，不仅可以切换[多页面板](../layout/panelbook.md)的页面，还可以通过选择不同的选项展示不同的数据。如使用选择面板展示表格中不同范围的数据：
示例地址：[字段灵活查询](https://demo.succbi.com/v5/bi/%E5%AD%97%E6%AE%B5%E7%81%B5%E6%B4%BB%E6%9F%A5%E8%AF%A2)
:::tip
**选择面板**与[下拉框](./combobox.md)都可以实现**选择**的功能，与下拉框不同的是，选择面板以选项的形式实现交互，适合单级维；若数据具有层次，建议使用下拉框的方式。
:::
## 使用选择面板切换多页面板{#switch}
**选择面板**搭配[切换多页面板](../../design/action/switch-panelbook.md)交互使用时，可以切换[多页面板](../layout/panelbook.md)的页面，具体步骤如下：
1. **制作多页面板**：预先将多页面板制作完成
2. **设置选择面板选项**：选中**选择面板**组件，在**数据**>**可选项**>**列表数据**中选择**枚举值**，并添加五条枚举值，分别对应多页面板的5个页面
3. **设置选择面板默认值**：为选择面板添加默认值为`涟漪（线）`，表示默认展示多页面板中名称为`涟漪（线）`的页面
4. **添加切换多页面板交互**：在**选择面板**的**交互**栏中添加**切换多页面板**交互，设置目标对象为`多页面板1`，目标面板为`事件源序号`，切换多页面板的具体介绍可参考文档[切换多页面板](../../design/action/switch-panelbook.md)交互。
示例地址：[自定义气泡动效](https://demo.succbi.com/v5/bi/bubble-layer_1)
## 使用选择面板过滤数据{#filter}
### 使用枚举值过滤数据{#enum}
**选择面板**组件的选项是**枚举值**类型时，可以通过对其他组件设置过滤条件来达到过滤数据的效果，如选择面板中提供`全国`、`湖北省`、`武汉市`三个选项，实现如下功能：
- 当选中`全国`时，仪表板中展示的是全国的数据
- 选中`湖北省`时，仪表板中展示的是湖北省的数据
- 选中`武汉市`时，仪表板中展示的是武汉市的数据
具体实现步骤如下：
1. **设置选择面板选项**：选中**选择面板**组件，在**数据**>**可选项**>**列表数据**中选择**枚举值**，并添加三条枚举值，值与描述分别是：
1. `420100`，`武汉市场主体查询`
2. `420000`，`湖北省市场主体查询`
3. `*`，`全国范围搜索`
2. **设置选择面板默认值**：为选择面板添加默认值为`武汉市场主体查询`，表示默认展示武汉市的数据内容
3. **在其他组件中对数据进行过滤**：选中明细表，在过滤器中添加一条过滤表达式`[企业基本信息].[登记机关]=[选择面板1].[值]`
示例地址：[字段灵活查询](https://demo.succbi.com/v5/bi/%E5%AD%97%E6%AE%B5%E7%81%B5%E6%B4%BB%E6%9F%A5%E8%AF%A2)
### 使用模型数据过滤数据{#table}
**选择面板**组件的选项来自**模型数据**时，可使用**选择面板**组件自带的**自动过滤**功能对其他组件的数据进行过滤，只需在**数据**>**过滤**中勾选自动过滤，并设置**影响范围**和**作用数据源**即可，具体的介绍可参考文档[下拉框](./combobox.md#table)。
示例地址：[全国学生分布概览](https://demo.succbi.com/v5/bi/%E5%85%A8%E5%9B%BD%E5%AD%A6%E7%94%9F%E5%88%86%E5%B8%83%E6%A6%82%E8%A7%88)
## 选项数据{#data}
**选项**是**选择面板**组件使用的基础，**数据**>**可选项**>**列表数据**属性提供了设置选项的入口，一般区分为两种：
1. **枚举值**：一一列举每一种选项，需要在**数据**>**可选项**>**枚举值**中打开**编辑枚举值**对话框进行设置
2. **来自模型数据**：需要提前在**数据**>**字段**中引用模型表的某个字段，然后在**列表数据**的下拉列表中进行选择，设置与下拉框组件相似，可参考文档[下拉框](./combobox.md)
选择面板还允许同时勾选多个选项，在**数据**>**可选项**中勾选**允许多选**即可。
## 属性介绍{#property}
### 排列方式{#arrange}
**选择面板**的选项支持设置排列方向，可选项有**横向**、**纵向**，在**样式**>**布局**>**排列方式**中选择。
### 绕排{#winding}
**选择面板**排列方式为**横向**时，还支持设置是否绕排，当设置为自动绕排后，选项一行显示不下时，会自动换行排列，此时可以勾选**按列对齐**，即按列自动对齐排列，并设置**固定列数**，表示一行显示几列，需要输入大于0的整数，如2表示显示2列。
### 启用展开收起{#expand-collapse}
当选项较多时，可以收起部分选项，需要在**样式**>**布局**中勾选**启用展开收起**。可以设置默认是收起的效果，勾选**默认收起**属性即可，可设置收起时默认的**显示行数**，即收起时显示的选项行数，默认为1，即只显示一行。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/inputbox.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/inputbox"
title: "仪表板组件-输入框"
---
---
order: 3
navTitle: 输入框
---
# 仪表板组件-输入框
输入框可以对输入的字段进行筛选。如表格和输入框搭配使用，实现对企业名称的筛选。
示例地址：[输入框](https://demo.succbi.com/v5/bi/%E6%98%8E%E7%BB%86%E8%A1%A8\(%E4%BC%81%E4%B8%9A%E5%9F%BA%E6%9C%AC%E4%BF%A1%E6%81%AF%E8%A1%A8\))
## 输入框实现 {#achieve}
输入框的**字段**取一个维度或度量，如企业名称、经营范围等。
**操作步骤**
1. 拖入输入框，将【企业名称】字段双击或拖入到**属性栏**>**数据**中，默认勾选自动过滤
2. **匹配模式**设置：输入框会根据输入的字段类型进行模式匹配。当输入框中的字段类型为字符型时，对字段进行模糊[匹配](#匹配模式)；当输入框中输入的字段类型为数值型时，对字段进行数值大小[匹配](#匹配模式)
通过上述2个步骤，即可实现输入框对企业名称进行筛选。
## 输入框属性{#attribute}
可以对输入框的默认值、输入提示、自动过滤等进行设置，此外，还可以对**字体**、**背景**、**内边距**等样式进行自定义。
- **默认值**：默认的筛选条件设置，可以写固定值或者表达式
- **输入提示**：对输入框中的文字提示进行设置。当输入框内容为空时，显示输入提示信息。
- **自动过滤**：勾选后可通过输入的内容对组件的数据进行过滤，默认勾选。自动过滤可以设置**影响范围**、**作用数据源**和**匹配模式**。若不勾选**自动过滤**，则可以在需要进行数据过滤的组件中，添加[过滤](../../design/data/data-filter/README.md)条件
- **影响范围**：影响范围可设置为全部或者指定的图表
- **作用数据源**：作用数据源可设置为当前数据源或者关联数据源
### 匹配模式{#match}
勾选**自动过滤**之后，可以对输入框的匹配模式进行设置。输入框的匹配模式和输入框中的字段类型有关，字符型和数值型对应不同的匹配模式。
- 当输入框中输入的字段类型为字符型时，对字段进行模糊匹配，有以下几种方式：
- **包含**：匹配出包含输入框中内容的数据，字符型时的默认匹配方式为**包含**
- **开头为**：匹配出开头为输入框中内容的数据
- **结尾为**：匹配出结尾为输入框中内容的数据
- **精确匹配**：匹配出和输入框中内容完全一致的数据
- 当输入框中输入的字段类型为数值型时，对字段进行数值大小匹配，有以下几种方式：
- **等于**：匹配出等于输入框中内容的数据，数值型时的默认匹配方式为**等于**
- **大于**：匹配出大于输入框中内容的数据
- **小于**：匹配出小于输入框中内容的数据
### 多行输入{#multiline}
当输入的文字内容较多时，可设置多行输入，超过宽度的文字会换行显示。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/date.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/date"
title: "仪表板组件-日期"
---
---
order: 4
navTitle: 日期
---
# 仪表板组件-日期
日期组件用于过滤数据，筛选出指定时间范围内的数据。
示例地址：[日期](https://demo.succbi.com/v5/bi/waterfall)
## 使用日期组件{#use}
日期组件选择的数据类型只能是对应日期的**日期型**或者**字符型**，在字段下拉框里选择相应的日期字段，如【年月】。
**操作步骤**
1. **引入日期字段**：双击或拖入维度字段【FACT\_JHWCB.年月.年】到**数据**>**字段**
2. **设置默认值**：**输入**属性处设置**默认值**为`2017年`
3. **设置选择范围**：**可选项**属性处设置**类型**为`年`、**最早**为`2017`、**最晚**为`2018`
## 属性介绍{#attribute}
可以通过属性设置日期组件的默认值、日期类型等。
### 默认值{#value}
想要控制日期组件的默认值，在**输入**>**默认值**处进行设置。默认值的选择粒度受[可选项](#choose)>**类型**的影响，当日期类型为年时，默认值也只能根据年进行选择。默认值的设置类型有4类：**指定**、**范围**、**相对**、**表达式**，详细定义可见[日期](../../../../app/superpage/components/input/datecombobox.md#settings)。
### 可选项{#choose}
在**可选项**属性处可设置选择日期时的**类型**，如年、月、日等。也可以设置勾选项**只选择已有日期**、**允许选择范围**、**允许选择相对值**、**允许清空**。
- **类型**：类型处的选择用于控制时间组件的选择粒度。如类型选择`年`，则时间组件也只能根据年进行选择。日期类型包含**自动**、**年月日**、**年月**、**年**、**半年**、**年季**、**年月旬**、**年周**、**时分秒**、**时分**、**小时**、**日期+时间**。当类型选择为`自动`时，即默认为字段数据的类型。选择非自动的类型后，会出现**最早**、**最晚**两个属性
- **最早**：控制日期组件可选择的最早时间，支持表达式书写
- **最晚**：控制日期组件可选择的最晚时间，支持表达式书写
- **只选择已有日期**：勾选表示只能选择数据字段中已有的日期
- **允许选择相对值**：系统默认勾选，勾选表示日期组件中允许选择日期的相对值作为日期组件的值，如`一天前`，勾选后**输入**>**默认值**的设置会增加**相对**这一类型
- **允许选择范围**：系统默认勾选，勾选表示日期组件中允许选择日期范围作为值，勾选后**输入**>**默认值**的设置会增加**范围**这一类型
- **允许清空**：勾选表示允许清空日期组件的选中项
:::tip
当数据字段为字符型时，必须为该字段设置[日期角色](../../../../data-gov/model/field-role.md#date)，选择非自动的**类型**数据过滤才能生效。
:::
## 移动端展示效果{#mobile}
仪表板支持设置移动端布局，移动布局下日期组件的设置与PC端一致，更多移动设置可见[移动](../../design/mobile/README.md)文档。日期组件在移动布局中的展示效果如下：
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/searchbox.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/searchbox"
title: "仪表板组件-快速搜索"
---
---
order: 5
navTitle: 快速搜索
---
# 仪表板组件-快速搜索
快速搜索是一个辅助输入组件，帮助用户在大量的数据中快速定位并选择一条需要的数据，通常用于搜索那些无法全部列出供用户选择的数据，这些数据可能数据量很大、也可能由于安全考虑不希望一次性显示给用户，比如企业名称、疾病编码等，以下方搜索企业名称为例：
示例：[快速搜索组件](https://demo.succbi.com/v5/bi/%E5%BF%AB%E9%80%9F%E6%90%9C%E7%B4%A2%E4%BC%81%E4%B8%9A)
## 使用快速搜索{#use}
使用快速搜索组件时，需要添加**搜索字段**，并搭配展示数据的组件一起使用。如通过企业名称筛选出该企业的基本信息，实现步骤如下：
1. **拖入快速搜索组件**：在**组件区**>**输入**中将**快速搜索**组件拖入到画布中
2. **设置数据**：拖入`企业名称`字段到**属性栏**>**数据**>**字段**中，拖入`企业内部序号`到**属性栏**>**数据**>**搜索字段**中，右键`企业内部序号`，在显示的菜单中，取消**列表中显示**属性的勾选
## 属性介绍{#attribute}
在**属性栏**>**数据**中引入需要的字段信息，即可简单实现快速搜索。下面是对**属性栏**>**数据**处的一些属性介绍：
- **字段**：主要用于自动过滤。只支持拖入一个指标，启用自动过滤后，会以**字段**的值作为过滤参数进行数据过滤，在过滤数据时会作用到所有引用了指标的组件。拖入**字段**中的指标会默认同步到**搜索字段**中，可自行去掉
- **搜索字段**：搜索时用于匹配关键字的字段，支持拖入多个指标，为空时默认搜索**字段**中的指标。拖入到**搜索字段**中的指标右键显示的菜单中，增加了**可搜索**，**列表中显示**两个菜单选项，如下
- **可搜索**：默认勾选，表示搜索可用于匹配关键字
- **列表中显示**：默认勾选，表示在搜索时该指标的信息会显示在搜索结果列表内
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/input/tabbar.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/tabbar"
title: "仪表板组件-标签页"
---
---
order: 6
navTitle: 标签页
---
# 仪表板组件-标签页
标签页组件可以根据需求新增多个标签选项，可以结合多页面板使用，通过切换标签选项控制切换多页面板页面的显示；也可以切换标签页过滤图表组件。如使用标签页切换疫情指标，展示选中指标随时间的变化趋势：
示例地址：[标签页](https://demo.succbi.com/v5/bi/tabs)
## 使用标签页组件{#use}
标签页组件可以根据需求新增多个标签选项，可以结合多页面板使用，如下是操作步骤：
1. **设置标签页数据**：在**属性栏**>**数据**>**列表数据**，下拉选择**枚举值**，并点击**枚举值**在对话框中添加4条枚举值
2. **设置标签页默认值**：**属性栏**>**数据**>**默认值**，下拉选择**确诊**
3. **添加交互**：**属性栏**>**交互**>**切换多页面板**，多页面板的制作可参考文档[多页面板](../layout/panelbook.md)
1. 目标对象：**多页面板1**
2. 目标面板：**事件源序号**
## 标签页属性{#attribute}
在**属性栏**>**样式**>**标签页**中可设置整个标签页组件的属性和样式。
### 切换选中动画{#switch}
勾选**启用**后，可以设置动画属性，即选中时标签页选项下线条标记的样式：
- 选中线条颜色：设置线条的颜色，可设置为纯色和渐变色
- 选中线条宽度：设置线条占其对应选项的占比，100%即为线条与选项等宽
- 选中线条高度：设置线条的高度，最小为1，最大为10
### 条件样式{#conditional-style}
用于标注标签页的特殊值，或者设置鼠标在标签页上进行操作时，标签页的状态样式，主要有以下几种类型：
- 突出显示：设置当标签页的值为某个特殊值时，选项的显示样式，参考文档[突出显示](../../../../report/design/style/condition-style.md#highlight)
- 标签页状态样式：当鼠标**悬停**、**选中**或**按下**时标签页及选项的样式效果，参考文档[标签页状态样式](../../design/type/condition-style.md#effect-style)
### 滚动到顶部时固定{#top-fix}
可以在**属性栏**>**数据**>**高级**中设置**滚动到顶部时固定**，勾选后，当标签页滚动到页面顶部时会固定显示并切换其他页面展示。例如移动设备上展示时可以不必回到顶部就可以切换选项卡，示例地址：[疫情动态](https://demo.succbi.com/v5/demo/mobile/%E5%90%84%E5%9C%B0%E5%AE%9E%E5%86%B5%E5%9B%BE%E6%9E%90)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/more"
title: "更多组件"
---
---
order: 6
navTitle: 更多
---
# 更多组件
仪表板提供了文本、多媒体组件等，可以展示文字、图片、视频信息等数据：
!!!children (guide/data-viz/dash/components/more) 1 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/text.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/text"
title: "仪表板组件-文本"
---
---
order: 1
navTitle: 文本
---
# 仪表板组件-文本
文本组件一般用于解释说明文字，或插入指标制作图文报告等。如使用文本组件插入指标制作服饰销售报告：
示例地址：[服饰销售报告](https://demo.succbi.com/v5/bi/%E6%9C%8D%E9%A5%B0%E9%94%80%E5%94%AE%E6%8A%A5%E5%91%8A)
## 使用文本组件{#use}
拖入文本组件，双击即可在富文本编辑框中编辑文本内容，并调整文本样式。
### 在文本中插入指标{#insert-index}
- 获取字段值：将指标字段，可以是维度或者度量，拖拽至**数据**>**指标**，文本中即可获取字段的值。维度默认为**计数**，度量默认为**sum**求和，可以修改**汇总方式**或者编辑取值表达式，及修改**显示格式**，如获取销售数量top1及对应的省份名称，分别设置汇总方式为**最大值**，显示格式为**标题**
- 获取组件值或参数值：双击文本组件，在富文本编辑框中点击**插入**，选择组件或参数对应的属性值即可
## 文本属性{#attribute}
设置文字的字体、样式对齐方式等。
- 字体：设置文字的字体样式、颜色及大小等
- 文字阴影：设置文字的阴影效果，与组件阴影类似，可参考文档[阴影](../../design/type/basic/shadow.md)
### 文字调整{#character}
当文字内容较多可能会超出组件大小时，可设置文字调整的方式，比如换行显示或者一行显示。提供了以下几种调整方式：
- 不调整：即默认展示在一行，超过长度的内容会以省略号显示
- 自动换行：当文字内容较长超出一行的长度时，自动进行换行，一般是文字较多需要多行显示的说明性文字等
- 溢出时缩排：当文字内容超过文本组件的大小且需要在一行中显示时，勾选后，会自动将文字缩放排列，一般用于固定宽度的布局中
### 文本对齐{#alignment}
设置文字在横向及纵向上的对齐方式。
- 横向对齐：左对齐、居中、右对齐、两边对齐、自动对齐（默认为左对齐）
- 纵向对齐：垂直居上对齐、垂直居中对齐、垂直居下对齐
:::tip
在富文本编辑框中也可设置文字的字体样式及对齐方式，两者之间是同步的，无优先级顺序。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/image.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/image"
title: "仪表板组件-图片"
---
---
order: 2
navTitle: 图片
---
# 仪表板组件-图片
仪表板提供了**图片**组件，可以显示上传的静态图片或指定路径的图片。
示例地址：[数字媒体组件](https://demo.succbi.com/v5/bi/library)
## 使用图片组件{#use}
仪表板中的图片组件，支持使用URL，以展示上传的静态图片为例，操作步骤如下：
1. **拖入图片组件**：将**组件区>更多>图片**组件拖入到目标面板中
2. **设置图片内容**：**图片来源**选择默认的`静态图片`，在**图片库**中选择一张图片
3. **设置填充方式**：**填充方式**选择`原始大小`
## 图片来源{#source}
仪表板图片组件提供了`静态图片`和`URL`两种可选来源，具体可以参考SuperPage[图片来源](../../../../app/superpage/components/common/image.md#source)文档中的**静态图片**和**路径**。
## 填充方式{#fill}
仪表板图片组件提供了五种填充方式，包括**原始大小**、**拉伸**、**充满容器**、**适合于容器**和**平铺**，表示图片在容器组件里的显示方式，具体可以参考SuperPage[填充方式](../../../../app/superpage/components/common/image.md#fill)文档。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/icon.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/icon"
title: "仪表板组件-图标"
---
---
order: 3
navTitle: 图标
---
# 仪表板组件-图标
仪表板组件提供了图标组件，可以显示系统自带的、用户上传的或者使用URL的图标：
示例地址：[数字媒体组件](https://demo.succbi.com/v5/bi/library)
## 使用图标组件{#use}
使用图标组件时可以按照需要选择相应的图标，并且可以自定义图标的颜色和大小：
1. **拖入图标组件**：将**组件区>更多>图标**拖入到目标面板中
2. **选择图标并自定义图标的颜色和大小**：在**数据>基本>图标**中分别设置
## 图标来源{#source}
仪表板提供了**图标库**、**页面内图标**、**主题图标**和**URL**四种可选来源，可以参考SuperPage[图片来源](../../../../app/superpage/components/common/image.md#source)文档中的**静态图片**和**路径**。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/video.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/video"
title: "仪表板组件-视频"
---
---
order: 4
navTitle: 视频
---
# 仪表板组件-视频
仪表板提供了**视频**组件，可以显示上传的视频或网络上的视频。
示例地址：[汛情监控视频](https://demo.succbi.com/v5/bi/%E6%B1%9B%E6%83%85%E9%98%B2%E6%8E%A7%E6%8C%87%E6%8C%A5%E4%B8%AD%E5%BF%83)
## 使用视频组件{#start}
拖入视频组件，在**基本**属性处设置视频来源，并设置视频播放选项：
- **拖入视频组件**：将**组件区>嵌入>视频**组件拖入到目标面板中
- **设置视频来源**：在属性栏**视频**>**基本**>**视频来源**中选择**URL** ，粘贴地址`https://www.bilibili.com/video/BV1Vu411m7vE/`
## 视频来源{#from}
仪表板视频组件提供了`静态视频`和`URL`两种可选来源：
- **静态视频**：在悬浮框中选择静态视频，可以获取对象内的视频和视频库的视频
- 对象内视频：用户可自定义上传视频，上传在对象内的视频存储于当前页面对象中，在其他页面中的对象内不可见
- 视频库：显示系统视频库中的视频，支持自定义上传视频。上传的视频存储于当前项目中的公开视频库，同一个项目中的不同页面视频库内容是一致的
- **URL**：在URL中直接写入视频的路径即可，分为以下几种情况
- 使用外网路径，如`https://www.bilibili.com/video/BV1Vu411m7vE/`
- 系统内部视频地址，如系统公共目录下的视频`/DEMO/public/videos/mov_bbb.mp4`
## 属性介绍{#properties}
对视频的基础播放属性设置可以在**视频**处设置：
- **自动播放**：勾选表示打开仪表板页面后，自动播放视频
- **循环播放**：勾选表示循环播放视频
- **显示工具栏**：系统默认勾选，显示视频播放的工具栏，包括音量调节，播放暂停等工具
- **锁定高宽比**：系统默认勾选，表示锁定原视频的宽高比，不勾选表示充满视频组件
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/iframe.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/iframe"
title: "仪表板组件-IFrame"
---
---
order: 5
navTitle: IFrame
---
# 仪表板组件-IFrame
IFrame即嵌入网页组件，可以将系统内部的[元数据文件](/dev/meta/file-exts)如报表、SuperPage等嵌入到仪表板中展示，也可以将系统外部页面嵌入展示。
示例地址：[嵌入报表](https://demo.succbi.com/v5/bi/%E5%B5%8C%E5%85%A5%E6%8A%A5%E8%A1%A8\(%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5%E8%A1%A8\))
## 使用IFrame{#use}
使用IFrame时，只需要拖入IFrame组件，并设置带嵌入的路径即可，以嵌入报表为例：
- **拖入IFrame组件**： 在**组件区**>**更多**分组下将IFrame组件拖入到仪表板设计器中
- **设置路径**：在**属性栏**>**数据**>**基本**中将路径设置为`/DEMO/ana/报表/分组报表/钻取子表/数值分段表.rpt?p_y=${[日期1].[值]}&xs=${[xs]}`
:::tip
若想实现仪表板中的指标过滤嵌入的内部元数据，以报表为例：
1. 在仪表板中设置一个全局参数，如`p_y`
2. 在报表中使用这个参数对数据进行过滤,如`销售日期属于[p_y]`
3. 仪表板嵌入报表的URL后加上参数的赋值情况，格式为`?参数=${值}`，若有多个用`&`连接。如上述路径中的`?p_y=${[日期1].[值]}&xs=${[xs]}`
:::
## 嵌入系统外页面{#web}
在仪表板中嵌入系统外的页面，只需要拖入IFrame组件，并设置外部网页路径。具体步骤如下：
- **拖入IFrame组件**： 在**组件区**>**更多**分组下将IFrame组件拖入到仪表板设计器中
- **设置路径**：在**属性栏**>**数据**>**基本**中将路径设置为`https://www.bilibili.com/video/BV1Vu411m7vE/`
:::tip
IFrame组件可嵌入内部元数据和外部页面，设置规则与SuperPage组件-嵌入网页的一致，具体设置可参考[网页路径设置](../../../../app/superpage/components/embed/embedwebview.md#url)。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/button.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/button"
title: "仪表板组件-按钮"
---
---
order: 6
navTitle: 按钮
---
# 仪表板组件-按钮
**按钮**组件通过点击来执行操作，需要搭配交互使用。如点击按钮可以将分组表导出为Excel文件：
示例地址：[占比图](https://demo.succbi.com/v5/bi/occupancy)
## 使用按钮组件{#use}
使用按钮组件时，可以自定义按钮的标题和样式，也可以添加交互设置，以点击按钮导出Excel表为例，具体操作步骤如下：
1. **拖入按钮**：将**组件区>更多>按钮**组件拖入到目标界面
2. **设置标题**：在**属性栏>按钮>标题**中，自定义按钮标题为`导出`
3. **添加交互并配置交互属性**：添加`调用组件属性`交互，**选择组件**选择`分组表1`，**方法**选择`导出Excel`
## 属性介绍{#properties}
### 启用切换{#switch}
启用切换用来标注按钮是否被选中了，需要提前设置好按钮在点击前与点击后的文字内容以及页面交互效果，更多说明可以参考SuperPage中[启用切换](../../../../app/superpage/components/common/button.md#switch)文档。
### 条件样式{#condition-style}
用于动态改变按钮组件的样式，或者设置鼠标在按钮组件上进行操作时按钮的样式，分为两种类型：
- **条件样式**：支持设置**突出显示**，即按钮在满足条件时，显示不同的样式，更多规则参考[条件样式介绍](../../design/type/condition-style.md#condition-style)文档
- **状态样式**：禁用按钮或者鼠标执行悬停、选中、按下时按钮的样式效果，更多规则参考[状态样式介绍](../../design/type/condition-style.md#effect-style)文档
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/components/more/videogroup.md"
htmlUrl: "https://docs.succapp.com/v5/dash/component/videogroup"
title: "仪表板组件-视频组"
---
---
order: 8
navTitle: 视频组
---
# 仪表板组件-视频组
仪表板提供了**视频组**组件，可以显示存储在数据表中的一个或多个视频数据。
示例地址：[数字媒体组件](https://demo.succbi.com/v5/bi/library)
## 使用视频组组件{#use}
拖入视频组组件，并设置视频来源及视频播放选项：
- **拖入视频组组件**：将**组件区>更多>视频组**组件拖入到目标面板中
- **设置视频组数据**：将`视频地址`字段拖入**数据**属性栏
- **设置视频组每行显示视频个数**：在**样式**>**布局**>**每行数量**处选择自定义，个数设置为`3`
:::tip
视频组的播放设置在**数据**>**高级**处可以设置，包含**自动播放**、**循环播放**、**显示工具栏**、**锁定宽高比**四个设置，详情请查看[视频](./video.md#setting)。
:::
## 视频组数据设置{#data}
视频组是通过模型表中视频的存储路径来读取视频的，无论模型表中的地址字段存储的是外网地址，还是系统内部地址都可以识别：
- 系统外地址，如`https://www.bilibili.com/video/BV1Vu411m7vE/`
- 系统内地址，如通过SuperPage[上传附件](../../../../app/superpage/components/input/upload.md)组件上传到系统内的视频，无论以`默认文件存储服务`、`默认文件存储服务(去重)`、`工作目录路径`、`外部链接`中哪种方式存储，系统都可以识别其地址。文件的存储类型设置详细见文档：[存储类型](../../../../data-gov/model/field-role.md#file)
## 视频组布局设置{#layout}
由于浏览器限制，视频组最多只能同时显示16个视频，多余的不显示。在**样式**>**布局**处可以设置视频组显示的基本布局：
- **每行数量**：视频组组件容器内每行显示的视频个数，有以下两个选项：
- 自动：视频个数小于2时，显示1行；小于8时，显示两行；小于15时显示3行；等于16时显示4行
- 自定义：自定义视频组容器内每行显示个数。**每行数量**处选择自定义后，会出现**个数**的属性设置可调节个数
- **视频间距**：视频组组件内每个视频的间距
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/design"
title: "设计仪表板"
---
---
order: 5
navTitle: 仪表板制作
---
# 设计仪表板
[//]: # "介绍一下一个仪表板制作的总体思路，业务设计、布局、取数、美化，BI-33362"
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/datasource.md"
htmlUrl: "https://docs.succapp.com/v5/dash/datasource"
title: "为仪表板添加数据"
---
---
order: 1
navTitle: 引入数据
---
# 为仪表板添加数据
数据即仪表板组件的取数来源。添加的数据可以是数据模型、临时数据加工或数据集，添加到数据中的模型即可用于可视化取数。
- [引入数据模型](#add-model)：直接将全局模型表引入
- [新建数据加工](#creat-dataflow)：新建一个当前对象内部的数据加工
- [新建数据集](#creat-dataset)：新建一个当前对象内部的数据集
## 引入数据模型{#add-model}
仪表板所需模型已经在数据模块中准备好，可以将对应模型表添加到数据模型中。提供了两种添加方式：
- 在**数据栏**中点击**添加**按钮，在弹出框中通过搜索或直接在其所在目录下选中该模型，点击确定。
- 点击**数据按钮**>**引入数据模型**，在对话框中通过搜索或直接在其所在目录下选中该模型，点击确定。
:::tip
在弹出的选择数据模型对话框中按住`ctrl`键可以多选，按住`shift`键可连续选择，这样可以一次引入多个模型表。
:::
**模型字段列表中的一些特殊字段**
模型表添加成功后，在左侧的数据模型面板会显示当前选中的数据模型下所有的字段，包括维度和度量，其中也包含了一些特殊的字段：
- 度量名称：维度字段，记录模型表中的所有维度字段，通常与**度量值**一起配合使用
- 字段名称：维度字段，记录模型表中的所有字段，通常结合[输入控件](../components/input/README.md)进行数据过滤
- 度量值：度量字段，记录模型表中的所有度量字段，通常与**度量名称**一起使用，返回的是对度量值的sum值。
- 总行数：度量字段，模型表中的数据总行数
- 经度/纬度：度量字段，若模型表中的地区字段设置了[地理角色](../../../data-gov/model/field-role.md)，则数据模型中会有经度、纬度2个字段
**快速打开引用模型**
添加的数据模型，在使用过程中如果需要查看数据或模型结构属性时，可以选中数据模型名称，使用鼠标右键方式选择**打开**或者**定位**查看数据模型信息，操作的区别在于：
- 打开：在仪表板内打开模型查看
- 定位：新开浏览器标签页，并在数据模块打开并选中引用的数据模型
::: tip
只有通过**添加数据模型**添加的数据模型能进行**打开**和**定位**。
:::
### 新建计算字段{#calc-field}
当表中已有的字段无法满足用户所需，需要根据已有的字段构造出的新的字段时，可以使用新增计算字段方式实现。新增计算字段的操作方式和数据模型上的一致，参考文档[新增计算字段](../../../data-process/transform/calc-field.md)。新增计算字段的方式有两种：
1. 点击**数据栏**>维度行旁边的**箭头**>**新增计算字段**，在编辑框中通过函数、参数等构造新的字段
2. 选中某一字段，右键选择**创建**>**计算字段**，此时编辑框中会出现选中的字段，可在该字段的基础上构造新字段
### 创建分组字段{#calc-group-field}
如需对某一维度的数据按不同类型进行划分，可通过创建分组的方式，右键点击对应的维度字段，选择**创建**>**分组**，创建分组的操作方式和数据模型上的一致，参考文档[创建分组字段](../../../data-process/transform/calc-group-field.md)。
### 创建分段字段{#calc-section-field}
如需对某一度量的数据按不同范围进行划分，可通过创建分段的方式，右键点击对应的度量字段，选择**创建**>**分段**，创建分段的操作方式和数据模型上的一致，参考文档[创建分段字段](../../../data-process/transform/calc-section-field.md)。
### 设置字段属性{#field-properties}
**地理角色**
用于将地区相关的**维度字段**的值与一个经纬度值关联，从而在地图上显示对应的位置，因此地图控件的位置字段必须是设置了地理角色的数据字段。右键点击所需字段，比如国家、行政区划等，选择**地理角色**，若是中国的省市县数据，则设置为**中国行政区划**；若是世界各国数据，则设置为**国家地理信息**，参考文档[地理角色](../../../data-gov/model/field-role.md)。
**显示格式**
用于设置数据在控件中的显示格式，比如设置为显示整数、百分比等。右键点击字段，选择**显示格式**中进行设置，参考文档[显示格式](./data/displayformat.md)。
**聚合方式**
系统提供了部分常用的聚合方式，通过选择相应方式即可便捷对数据进行聚合，如计数、平均值、最大值、最小值等。右键点击**度量字段**>**聚合**，选择对应的聚合方式即可，当字段拖入控件中后，数据会以选择的聚合方式进行聚合。
**汇总依据**
系统提供了部分常用的汇总方式，用于在[表格控件](../components/table/README.md)中求合计值时对数据的汇总。通过选择相应方式即可对数据快速进行合计、最大值等计算。右键点击**度量字段**，选择**汇总依据**即可。
### 替换字段引用{#replace-field}
当模型发生调整，需要将某个字段的引用全部修改为新增字段时，可以使用替换字段的方式一键替换所有该字段的引用。比如右键点击【价格档次】，选择**替换字段**，在弹出框中选择【销售季节】，点击确定，控件中价格档次就会被替换为销售季节。
### 设置别名{#rename}
为数据模型重命名，右键点击模型，选择**设置别名**，在对话框中输入名称即可。当修改别名后，控件中的字段引用的模型表或字段名称会同步修改。
## 新建数据加工{#creat-dataflow}
当已有数据模型无法满足当前页面的分析需求，需要对其进行加工处理，而加工结果其它页面不会用到，只会在该分析内部使用时，可通过这里的**新建数据加工**的方式进行加工，这里新建的数据加工只会保存到当前页面内部，不会影响全局模型表。点击**数据源按钮**>**数据加工**，加工操作参考文档[新建数据加工](../../../data-process/create-dataflow.md)。
## 新建数据集{#creat-dataset}
数据集（data set）是对已有的模型表进行过滤、关联、分组、字段筛选后形成的一个子集，这个子集更符合当前仪表板的使用需要。数据集对数据的加工能力没有数据加工强，但易于操作，在[SuperPage](../../../app/superpage/README.md)中，数据集也可以用来进行数据提交。点击**数据按钮**>**新建数据集**，在对话框内进行新建，新建数据集需要以下几个步骤：
1. 设置数据集名称：输入一个合理且有意义的名称，不能为空
2. 引入数据模型：数据集是基于模型表的子集，使用下拉的方式引入数据模型，添加后模型数据会在右侧的[数据列表](#dataset-field)中展示。
3. [数据集属性设置](#dataset-properties)：为数据集进行过滤、添加分组或排序字段
4. 选择[数据集类型](#dataset-type)：设置数据集的类型，可选单主键、单行、自动识别，默认为自动识别，表示会根据当前表自动判断数据集类型
5. 保存：保存当前数据集，保存后的数据集用法和引入的数据模型用法一致，在数据模型下可以查看数据集中的字段，在控件的数据中即可引用该数据集
### 数据集属性设置{#dataset-properties}
- 读写类型：数据集的读写权限，分为**只读**、**只追加写**、**可读可写**，此属性只在[SuperPage](../../../app/superpage/README.md)中有效
- 设置过滤条件：对数据集中引入的数据模型数据进行过滤，可参考[过滤](#filter)
- 设置分组字段：即根据所选分组字段对数据进行分类汇总（分组），相当于sql语句中的group by，可基于分组后的结果设置筛选条件
- 设置排序：对数据集中的数据根据排序字段进行**升序**或**降序**排列，可参考[排序字段](#sort-fields)
- [字段管理](../../../data-gov/model/README.md#filed-management)：当引入的数据模型中已有的字段无法满足所需，需要根据已有的字段构造出的新的字段列或者对字段进行修改时，可以**新建字段**，数据量较大且有些字段不需要时，可通过**选择字段**勾选需要的字段，提高数据查询效率
- 设置变量：即设置参数，可通过定义变量对数据集模型进行过滤等，并传递给该模型，得到新的数据处理结果，可参考文档[设置动态加工参数](../../../data-process/setting-params.md)。设置变量后在模型设置中的参数中
### 数据字段管理{#dataset-field}
在右侧的数据列表中选中对应字段名称点击下拉按钮或者**右键**可对字段进行相关操作：
- 重命名：对字段名称进行重命名
- 显示格式：设置字段中的数据展示的格式，以及在控件中数据的显示格式，显示格式类型可参考文档[显示格式](./data/displayformat.md)
- 删除字段：在数据集中删除该字段，不会删除数据模型中的字段，删除的字段可以通过[同步数据集结构](#sync-dataset)还原
### 排序字段{#sort-fields}
在左侧的排序属性中可添加一个或多个排序字段并指定排序方式。通常用于需要按照某种顺序显示数据的场景，比如企业的基本信息按照【成立日期】降序显示，最新成立的企业信息显示在最上面，并且数据集中指定排序字段的优先级高于[数据模型中指定排序字段](../../../data-gov/model/model-settings.md#sort-fields)。
### 数据集类型{#dataset-type}
数据集类型表示一个数据集查询返回的结果集的类型，有**单行**、**单主键**和**普通数据集**三种，不同类型的数据集的表达式引用规则不同：
- **自动时别**：默认为**自动识别**，表示会根据当前表自动判断数据集类型
- **单行**：返回数据结果只有一行并不一定就是单行数据集，单行数据集是对结果集的一种确定性约束，不论数据行数如何变化，结果都只会有一行，比如按照模型的所有主键字段过滤，则就是单行结果集，如果对所有数据汇总那么也会是单行结果集，但如果使用某个过滤条件导致数据此时是只返回一行数据，但是随着来源数据的变化有可能返回不是一行，那么这不能称之为单行数据集。单行结果集是一种根据模型的主键或者加工的逻辑理论上推测出来的返回结果最多只有一行的结果集。
- **单主键**：指数据集只有一个字段作为逻辑主键，当为**单主键**类型时，需要设置**主键字段**
- **普通结果集**：即多行多主键
:::tip
**单行**和**单主键**是特殊情况，有时候比较复杂，无法自动识别，需要手动设置类型
:::
### 同步数据集结构{#sync-dataset}
当数据集的结构与引用模型表结构不一致时，数据集对话框中的**刷新**按钮会有黄色标记提示，点击**刷新**按钮可查看模型表与物理表的差异，并勾选需要修改的差异信息同步到数据集。
## 替换已有模型{#replace-model}
若原有模型被删除或因为需求变更等原因不再使用时，可以重新选择其他模型进行替换。右键点击模型，选择**重新选择**，在弹出框中选择新的模型，新选择的模型会替换原有模型，控件中所使用的原模型字段也会替换为新模型中所对应的字段。
::: tip
1. 若某些数据字段只存在于原模型中，那么替换后引用这些数据字段的控件会提示相应字段不存在
2. 系统默认保留设置内容，若不勾选，原模型设置的过滤条件、计算字段等不会复用到新模型中
:::
## 数据模型设置{#model-settings}
在仪表板内添加的数据模型会在左侧**数据**面板显示，选中对应的数据模型**右键**可对数据进行设置，如过滤条件、设置参数、权限等。
### 过滤条件{#filter}
当可视化分析内所有的控件具有相同的取数口径时，可以通过右键点击模型，选择**设置**>**过滤条件**，在模型表上设置全局过滤，过滤条件会影响所有使用该数据模型的控件，这样就无需为控件一一设置过滤。可以使用[全局参数](#params)或者根据[输入组件](../components/input/combobox.md)的值进行过滤。
比如想分析2010年2月河北省高档服饰的销售情况，可在过滤中进行设置，参考文档[过滤](./data/data-filter/README.md)。
### 参数{#params}
若仪表板使用的数据模型设置了参数，而分析时需要对参数进行更改时，可以在可视化分析页面右键点击该模型，选择**设置**>**参数**，对参数进行更改，并传递给该模型，得到新的数据处理结果，无需重新在模型中更改参数。
如原参数是北京市，这样模型中只有北京市的数据，若想分析河北省的数据，可将参数设置为河北省，参考文档[设置动态加工参数](../../../data-process/setting-params.md)
::: tip
只有设置了参数的SQL模型才能在分析内部更改参数。
:::
### 权限{#permission}
通过右键点击模型名称，选择**设置**>**权限**，可以为不同的\[用户]、用户组设置对该模型的操作权限。
- **继承页面的权限设置**：默认勾选，表示当前登录用户对该仪表板拥有的权限会继承到该模型上
- **限制读权限**：限制该模型的读取权限
- 禁止：禁止该模型的读取权限
- 仅允许指定的用户：通过设置表达式，仅允许匹配的用户拥有该模型的读权限
- 仅允许指定的用户组：通过设置表达式，仅允许匹配的用户组拥有该模型的读权限
- **限制导出权限**：限制该模型的导出权限
::: tip
1. 拥有对该可视化分析页面编辑权限的用户才可设置模型权限
2. 内部的权限是额外添加的权限，在**权限模块**的基础上
:::
### 高级{#more}
通过右键点击模型，选择**设置**>**高级**，可以设置高级选项
- **每页行数**：设置分页数，设置的分页会自动作用到影响的组件上，默认是100行
- **最大查询行数**：限制一次查询请求最大的查询数据量，防止数据被非法导出，默认是10000行
- **立即刷新**：系统默认勾选此项，勾选后，当模型表的数据发生更新时，页面中引用了该模型表的内容会自动刷新数据，同时驱动相关的可视化组件刷新。不勾选时，需要通过“刷新”交互主动刷新
- **初始时不查询**：默认不勾选，勾选后，页面不会自动查询该模型的数据，需用户使用“刷新数据”交互查询数据
- **按需查询字段**：默认的系统会一次性查询所有被引用的字段数据。当字段很多且有一些字段一开始并不显示，可以勾选“按需查询字段”，此时系统只查询当前需要显示出来的字段
- **最后修改人字段**：系统会在每次提交数据时将最后修改人修改为当前用户
- **最后修改时间字段**：系统会在每次提交数据时将最后修改时间修改为当前时间
- **禁用字段高亮**：搜索时字段数据中匹配的字符串默认会高亮显示，勾选后，禁用高亮
- **全文检索**：用于全文检索的模型，通常都是外部模型，而且配置了es存储，如果勾选此选项，那么对此模型的查询都会交给es处理
- **数据集类型**：即数据集上的设置的类型，当此处修改了数据集类型后，数据集对话框中也会同步修改
## 其他操作{#other-settings}
### 刷新模型{#refresh-model}
制作可视化分析的过程中，若所使用的模型表发生了修改，且没有在高级中勾选**立即刷新**时，可以通过右键点击模型，选择**刷新**来刷新模型、同步修改。
### 克隆模型{#clone-model}
克隆模型会复用原模型的所有操作，包括新建的计算字段、过滤条件、字段显示方式等，右键点击模型，选择**克隆**即可克隆该模型，克隆模型的命名规则是在原模型名字的后面加数字，数字从1开始依次累加，比如**销售明细表**第一次克隆产生的新表为**销售明细表1**，第二次克隆产生的新表为**销售明细表2**。
### 删除模型{#delete-model}
右键点击模型，选择**删除**，如果该模型没有被使用到，则会直接删除。如果有控件引用了该模型，则会弹出提示框删除模型后使用该模型数据的控件都会失效，提示使用该模型的控件。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/layout/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/layout"
title: "仪表板布局"
---
---
order: 2
navTitle: 布局
---
# 仪表板布局
仪表板布局支持各种灵活的布局方式，通过调整布局的各种属性，可以适配于各种终端，同时也可以实现各种页面效果，比如：
| 大屏监控式布局 | 瀑布式报告布局 | 移动端布局 |
| ---| --- | --- |
|  |  |  |
## PC端布局方式{#pc}
PC端布局方式是系统默认选择的布局，PC端布局可以通过调整**大小**属性从而达到不同的布局效果。具体布局效果包括：
- **整个视图**：满屏的弹性布局，适用于大屏制作，具体设置方法可见[整个视图](#fullscreen)
- **固定宽度**：定宽布局，适用于图文报告制作，具体设置方法可见[固定宽度](#fixwidth)
- **固定大小**：固定页面大小的布局，适用于制作多屏页面，具体设置方法可见[固定大小](#fixsize)
| 整个视图 | 固定宽度 | 固定大小 |
| ---| --- | --- |
|  |  |  |
### 整个视图{#fullscreen}
**整个视图**布局是一种满屏的弹性布局方式，此种布局下页面的组件大小和文字大小都会随浏览器的缩放自动缩放，该属性适用于大屏展示的场景。
**设置方法**：
1. 点击左侧**布局**选项
2. 在**大小**下拉框中选择**整个视图**
### 固定宽度{#fixwidth}
**固定宽度**布局是一种可以自定义设置页面宽度的布局方式，这种布局方式可以使布局内容无限纵向延伸。在这种布局下，我们可以很轻松的制作一些定宽页面，比如图文报告。
**设置方法**：
1. 点击左侧**布局**选项
2. 在**大小**下拉框中选择**固定宽度**
**固定宽度**布局中，允许用户去设置页面缩放情况下**最小/最大宽度**，具体如下：
- **最小宽度：** 当浏览器缩小时，页面能缩小到的最小宽度
- **最大宽度：** 当浏览器放大时，页面能放大到的最大宽度
### 固定大小{#fixsize}
**固定大小**布局是一种用户自定义页面**宽度**和**高度**的布局方式。由于**宽度**和**高度**是固定值，此种布局方式更加适合去制作宽屏或多屏的页面。
**设置方法**：
1. 点击左侧**布局**选项
2. 在**大小**下拉框中选择**固定大小**
**固定大小**布局除了提供**宽度**和**高度**设置外，也允许用户通过设置**缩放**来实现页面的自动缩放。
- **宽度：** 设置页面在浏览器上的宽度，单位为像素（px）
- **高度：** 设置页面在浏览器上的高度，单位为像素（px）
- **缩放：** 控制页面是否随浏览器的大小进行等比例缩放，提供如下两个设置，
- **不缩放：** 勾选后，页面的宽和高就跟上面设置的宽/高值保持一致，不会随浏览器的缩放而变化
- **适用于容器：** 勾选后，当页面进行缩放时，该页面的大小就会根据宽/高设置值与浏览器窗口大小之间的比例，进行等比例缩放
## 移动端布局方式{#mobile}
设置了**移动端布局**后，在移动设备打开页面时，会自动导航为移动端布局效果，这种布局方式可以很快捷地满足用户的移动端需求。
|指标看板|高校师生情况|中国经济变化|
| --- | --- | --- |
||||
**设置方法**
1. 新增设备：点击**布局**>**预览设备**
2. 选择设备：在设备选择栏**类型**中选择想要展示的设备，系统提供多个选项可供选择，包括默认、桌面、手机-竖屏、手机-横屏、平板-竖屏、平板-横屏
3. 设置尺寸：在**尺寸**中选择页面展示尺寸，各种设备都有属于自己的一套尺寸大小供选择
4. 添加布局：**类型**和**尺寸**选择完毕后，点击**添加布局**按钮，即可将自己设置好的移动端布局效果添加到左侧的布局列表中
### 锁定移动屏幕方向{#direction}
当我们希望制作的移动端布局方向不被用户移动端自身的屏幕方向影响时，即制作的是竖屏移动端布局，放在横屏移动端上时，仍然保持为竖屏的状态可以勾选**锁定**属性即可。
**设置方法**：
1. 添加移动端布局，可参考上述移动端添加步骤
2. 勾选**锁定**
::: tip 提示
PC端的布局和移动端的布局是相互独立的，可以在移动端的布局上将不需要展示的组件删除，这样操作后是不会影响到PC端上组件的正常展示。
:::
## 布局属性{#properties}
布局提供辅助用户实施或查看的功能性属性，如文字查看时自动缩放、实施时画布网格数量编辑、辅助放大编辑页面等。
### 文字自动缩放设置{#self-adaption}
当客户端浏览器经常需要进行缩放，或者页面展示终端的分辨率大小不定时，页面文字字号大小也可以随着页面缩放的实际大小进行自适应缩放。这样可以避免组件缩放后，文字不缩放遮挡组件的情况。
**设置方法**：
1. 点击左侧**布局**选项
2. 勾选**文字缩放以适应大小**，该属性仅支持在[整个视图](#fullscreen)和[固定宽度](#fixwidth)两种布局下使用
**文字缩放以适应大小的计算规则**：系统会自动计算页面页面缩放系数从而使字体自动缩放至对应大小，当字体大小小于浏览器设置的12px（默认）就会显示成12px。具体计算逻辑可参考如下公式：`缩放大小=字体设置大小×缩放系数，缩放系数=当前屏幕大小÷默认缩放基准（1366*768）`。
::: tip 解除浏览器最小字体显示方法
1. Chrome浏览器：设置>外观>自定义字体>最小字号
2. Firefox浏览器：设置>字体>高级>最小字号
3. Edge浏览器：设置>外观>字体>自定义字体>最小字号
:::
### 网格设置{#grid}
**画布**和布局组件上存在网格的属性，**画布**和布局组件内部都是由多个**网格**组成的，行数和列数决定了有多少个**网格**，网格的尺寸决定了仪表板组件移动的最小值。可以理解为在仪表板组件不脱离网格前提下，使用鼠标移动仪表板组件一次的距离就是一**网格**的距离。
网格具有如下设置项：
- **行/列数：** 设置纵向/横向网格数。当页面需要进行小距离调整时，可以适当增加行/列数，从而达到缩小网格大小，进行微调的效果
- **行/列间距：** 设置网格之间的间距。当组件与组件直接间距过大/过小时，可以通过调整画布或容器组件的行/列间距来调整组件之间间距
### 工具栏隐藏技巧{#toolbar}
仪表板**画布**布局中提供工具栏属性，可以为用户提供编辑、刷新、分析、评论等功能。系统默认勾选，勾选后，用户可以在**查看**页面调出辅助工具栏。
### 设计器缩放技巧{#scaling}
当制作宽屏效果时，而技术人员笔记本尺寸较小的情况下，需要对组件距离、大小进行微调时，可以通过**缩放**进行调整。在这里调整的大小并不会影响页面在展示时候的实际大小，功能类似于放大镜，只是用来辅助实施工作的。
## 组件大纲树{#tree}
**组件大纲树**会将整个仪表板页面中组件以树的形式展示出来，其中包括组件之间的嵌入关系。通过**组件大纲树**，我们可以快速定位页面中的组件，也可以快速将需要的组件拖入到布局组件中。
::: tip 提示
**组件大纲树**内只能将组件拖拽到其他布局组件中，平级的组件在大纲树上调整顺序并不会影响页面组件摆放顺序。
:::
## 布局组件{#assembly}
布局组件也叫容器组件，布局组件内部可以摆放其他组件（**画布**本质上也是一个布局组件），布局组件具有内部布局属性设置，可以决定内部组件的布局方式。其中主要包括**面板**、**多页面板**、以及**浮动面板**三类。布局组件主要是用来给**画布**划分区域的，把**画布**根据不同的内容划分为各自独立的区域，再在各自独立的区域中进行内容制作。通常情况下是，一个**画布**中放置多个容器组件，这样就可以组合出一个丰富内容的页面。布局组件各自的大致功能如下：
| 面板 | 多页面板 | 浮动面板 |
| ---| --- | --- |
|  |  |  |
- **面板：** 当我们需要将局部组件组合成卡片式布局时，可以使用**面板**组件来实现，具体可参考[面板](../../components/layout/panel.md)
- **多页面板：** **多页面板**可以根据需求新增多个面板页面，每一页面板都可以任意组合组件形成一个数据卡片，一般与选项卡配合使用，同时只能显示一页面板的内容。具体可参考[多页面板](../../components/layout/panelbook.md)
- **浮动面板：** 浮动面板可以根据数据源行数浮动出多个面板，浮动出的面板功能和面板一致，具体可参考[浮动面板](../../components/layout/floatpanel.md)
## 常用布局{#scene}
### 横向三段式布局{#layout1}
| 横向三段式布局 | 市场信息监管 | 设置方法 |
| ---| --- | --- |
|  |  |  |
- 应用场景：适合总体概览的驾驶舱，内容全面，对全盘的总结概览
- 实现思路：在**画布**拖入三个**面板**组件，然后选中三个面板组件右键选择**对齐**>**水平填充**即可横向均分画布。这时就可以在各个模板中放入对应组件即可
::: tip 提示
使用横向三段式布局的思路，可以变化成其他的布局方式，比如[横向卡片式布局](#layout2)、[大标题风格布局](#layout3)。
:::
### 横向卡片式布局{#layout2}
| 横向卡片式布局 | 销售指标看板 | 设置方法 |
| ---| --- | --- |
|  |  |  |
### 大标题风格布局{#layout3}
| 大标题风格布局 | 中国近十年经济 | 设置方法 |
| ---| --- | --- |
|  |  |  |
### 纵向三段式布局{#layout4}
| 纵向三段式布局 | 销售完成率分析 | 设置方法 |
| ---| --- | --- |
|  |  |  |
- 应用场景：适合对专题的分析，逻辑结构划分清晰
- 实现思路：实现这类布局效果，有以下两种方式：
1. 在**画布**拖入三个**面板**组件，然后选中三个面板组件右键选择**对齐**>**垂直填充**即可横向均分画布。这时就可以在各个模板中放入对应组件即可
2. 在**布局**>**大小**中选择**固定宽度**也可实现这类布局效果
::: tip 提示
使用纵向三段式布局的思路，可以变化成其他的布局方式，比如[右侧卡片式布局](#layout5)。
:::
### 右侧卡片布局{#layout5}
| 右侧卡片布局 | 新冠疫情分析 | 设置方法 |
| ---| --- | --- |
|  |  |  |
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data"
title: "组件数据介绍"
---
---
order: 3
navTitle: 取数
indexTitle: 组件数据介绍
---
# 组件数据介绍
在不同组件中数据的展示及要求是不一样的
## 数据类型
组件的数据要求可以分7类：
- 数据（明细表）：可以选择**维度**或者**度量**
- 行维度（分组表）：只能选择**维度**，且至少添加一个**维度**
- 列维度（分组表）：只能选择**维度**，可以选择不添加
- 指标（分组表）：只能选择**度量**，且至少添加一个**度量**
- x轴：x轴选择的数据一般都是**维度**，数量可以是一个或者多个
- y轴：y轴选择的数据一般都是**度量**，数量可以是一个或者多个\
在[散点图](../../components/chart/scatter.md)，[条形图](../../components/chart/bar-chart.md)中X轴数据是度量，y轴数据是维度
- 指标：可以选择**维度**或**度量**，当指标为**维度**时，一般是使用**count()**函数对**维度**进行计数。**指标**数量可以为一个或者多个
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/param.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/param"
title: "参数"
---
---
order: 2
navTitle: 参数
---
# 参数
参数是当前页面的一组变量，改变参数的值可以触发引用了参数的组件刷新或引用了参数的数据集刷新。参数的值可以通过URL参数传递、也可以通过交互([设置参数值](../action/set-param-value.md))修改，使用参数可以方便的实现各种灵活交互效果，如点击进度环华中大区，折扣率标题前会加上华中名称，点击不同大区，标题也会随之对应改变：
## 使用参数{#use-param}
1. 点击页面工具栏中的**参数**按钮，弹出[参数](#settings)对话框
2. 点击`+`，弹出**新增参数**对话框，名称输入`dq`，描述为`大区`，点击确定即可
## 参数{#settings}
- **名称**：参数的名称，一般使用简洁易懂的小写英文字母，如`dq`
- **默认值**：参数未传递明确的值时会使用默认值，仅在初始时计算一次作为参数的初始内容，后续参数的修改与默认值无关
- **数据类型**：用于限制参数的数据类型，如字符型、整形、日期型等，参数的值会自动按设置的类型进行转换，无法转换的值认为是不符合期望的，比如给日期类型的参数传递的值是“1”，会在查看界面使用到该参数的组件上给出错误提示信息
- **描述**：参数的业务描述，如“身份证号”
- **包含多值**：勾选后参数支持传递“多个值”，此时当参数用在查询或修改数据时都会匹配多条数据。通常用逗号分隔的字符串表示多值，具体可参考文档[多个数值匹配](../../../../exp/types.md#multi-number)
- **禁止外部传入**：勾选后，将自动忽略外部传入的参数
- **操作按钮**：
- 添加：新增参数
- 重命名：可修改参数名称
- 查看引用：查看该参数在当前页面中被引用的地方，可以点击引用进行定位，具体可查看文档[查看引用](../../designer.md#view-reference)
- 删除：删除参数。如果参数被引用了，点击删除时会给出友好提示；若强制删除，引用的表达式会报错，通过点击右上角红色报错数字，可快速定位问题位置
## 应用场景{#application}
参数只能在当前页面被使用，部分交互或组件可以获取到其他页面传递过来的参数值，并使用参数作为数据传递的桥梁，实现对其他页面的数据过滤。参数使用场景通常有以下几种：
1. [通过参数改变组件的数据，如改变组件的标题](#change-param)
2. [通过参数过滤数据，如打开链接获取参数进行数据过滤](#filter-data)
3. [通过参数判定组件的显示与隐藏](#display-hide)
4. [通过地址栏修改URL传递参数](#url-param)
### 通过参数改变组件数据{#change-param}
当点击不同数据时，想要标题也随所点击的数据发生改变，则可以使用**参数**与[设置参数值](../action/set-param-value.md)交互搭配使用，根据数据不同改变参数的值，然后将参数填写在想要改变数据的地方即可。如点击环形占比图不同的大区，其他图形上方标题会同步显示对应的大区名称，实现思路如下：
1. 在当前页面设置参数`dq`
2. 添加**设置参数值**交互，点击**编辑参数**，**参数名称**选择`dq`，**值**选择`当前值`即可，具体可查看文档[设置参数值](../action/set-param-value.md)交互
3. 在标题处添加参数即可，如`${[dq]}折扣率`
### 通过参数过滤数据{#filter-data}
点击数据打开目标页面时，想要在当前页面点击不同的数据，打开的目标页面就自动过滤数据，则可以在[打开链接](../action/linkto.md)交互中获取目标页面的参数，使用参数传递数据，从而达到过滤数据的效果。如点击`各类别产品销量`，能根据环形占比所选的大区查看对应大区的销售详情数据，实现思路如下:
1. 在打开链接目标页面中设置参数，即在销售详情页面设置参数`dq`
2. 在`各类别产品销量`条形图设置打开链接交互，**参数名**中能自动识别到目标页面中的参数，选择`dq`，参数值设置当前页面的参数`dq`即可
3. 在目标页面的模型表上添加参数过滤条件即可实现过滤数据，如`[dq]=[门店销售明细表].[区域编码].[大区]`
### 通过参数显示隐藏组件{#display-hide}
想要组件能实现动态的显示隐藏效果，也可以使用动态参数来控制，比如[设置参数值](../action/set-param-value.md)交互或者[打开链接](../action/linkto.md)传递不同的参数值来动态改变参数，最后在组件的**显示**属性中写入参数的表达式即可。如点击`隐藏`按钮，可以隐藏说明文字，点击`显示`可以显示说明文字，实现思路如下：
1. 设置参数`xs`，并设置默认值为`1`
2. 改变参数值
- 在`隐藏`按钮上添加**设置参数值**交互，将参数值改为`0`，启用条件设置为`[xs]=1`
- 再添加一个**设置参数值**交互，将参数值改为`1`，启用条件设置为`[xs]=0`
3. 在想要动态显示隐藏的组件**显示**属性中选择**条件**，并写入表达式，如`[xs]=1`，即可动态显示组件
### 地址栏修改URL传递参数{#url-param}
通过在URL后面传递参数也能给参数设置初始值，常用于[将页面嵌入到第三方系统](../../../../dev/integrate/embed-into-3rd.md)中。
需要注意的是URL的参数名是使用页面中定义好的参数的参数ID，即**参数名称**；参数值需要符合URL参数的编码规范，示例如下：
1. 参数值为数字：`https://demo.succbi.com/v5/DEMO/ana/report/float/float/自定义分组表.rpt?p_y=2018`
2. 参数值为中文，需要将中文进行编码：`https://demo.succbi.com/v5/DEMO/ana/report/float/float/自定义分组表.rpt?dq=%E5%8D%8E%E4%B8%AD`
3. 多个参数值，以`&`符连接：`https://demo.succbi.com/v5/DEMO/ana/report/float/float/自定义分组表.rpt?p_y=2018&dq=%E5%8D%8E%E4%B8%AD`
[点击此处体验](https://demo.succbi.com/v5/DEMO/ana/report/float/float/自定义分组表.rpt?p_y=2018)
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/interval-refresh.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/interval-refresh"
title: "定时刷新"
---
---
order: 3
navTitle: 定时刷新
---
# 定时刷新
**定时刷新**可以根据一定的时间间隔，刷新仪表板中展示的数据，一般用于对数据实时性要求比较高的**大屏展示**。如每隔三秒刷新一次超市数据：
示例地址：[超市零售大屏](https://demo.succbi.com/v5/bi/超市零售大屏/play)
## 设置方法{#how-to-use}
仪表板的**定时刷新**功能，是指重新发起一次数据的查询请求，当查询到的数据发生变化时，图形中的数据就能随之发生改变，需要在[仪表板设计器](../../designer.md)的**文件**中进行设置：
1. **打开定时刷新设置对话框**：在仪表板左上角的**文件**中，选中**定时刷新**按钮
2. **设置刷新范围**：设置定时刷新`年度汇总表`的数据，具体可参考[刷新范围](#range)
3. **启用定时刷新**：勾选`年度汇总表`的启用勾选框，并设置间隔时间为3秒
### 刷新范围{#range}
启用**定时刷新**时，可以指定刷新整个仪表板还是某个数据模型的数据，有以下几种范围：
- **无**：不进行定时刷新，默认勾选
- **整个仪表板**：定时刷新整个仪表板，即刷新仪表板内引用的所有数据模型，勾选后需要设置**间隔**时间
- **指定数据模型**：定时刷新该仪表板中指定的[数据模型](../../../../data-gov/GLOSSARY.md#data-model)，需要勾选**启用**并设置刷新的**间隔**时间
## 定时刷新的数据要求{#demand}
**定时刷新**一般使用在对数据的实时性要求比较高的仪表板中，这对仪表板引用的数据有一定的要求，即该模型的数据也需要实时更新，根据仪表板中引用的数据模型类型不同，区分为[引入数据表](#data-table)和[引入数据加工](#dataflow)。
### 引入数据表{#data-table}
若数据库中的物理表数据不需要进行任何处理即可用于分析，则在仪表板使用该数据之前，需要做如下两步操作：
1. **导入数据库模型**：将**数据源**中的物理表在系统中导入为**数据库模型**，**连接方式**选择**实时连接**，具体可见[导入数据库模型](../../../../data-gov/import-table.md)，此时在仪表板内引入模型时，选择对应的**数据库模型**即可
2. **禁用查询缓存**：在[模型属性](../../../../data-gov/model/model-settings.md)中勾选[禁用模型缓存](../../../../data-gov/model/model-settings.md#disable-model-cache)
### 引入数据加工{#dataflow}
若分析使用到的数据需要进行一定的加工处理，则引入到仪表板的模型是[数据加工](../../../../data-process/README.md)，对于加工数据的实时刷新，一般有两种方案：
1. **数据刷新的频率较高，则数据不落地**：若数据需要在较短的时间间隔内就刷新一次，可以采取**加工数据不落地**的方式，此时数据加工可以看成一张虚拟表，类似数据库中的视图，查询时直接执行加工逻辑的SQL语句，以保证数据的实时性，需要在加工的**输出节点**>**模型属性**中做如下设置：
1. 在**提取**中取消勾选**提取数据**
2. 在**查询**中勾选**禁用查询缓存**
2. **数据刷新的频率较低时，使用定时提取**：若**数据加工**的[数据提取到了物理表](../../../../data-process/data-output/README.md)，则需要设置定时刷新该加工后的结果，具体可参考文档[定时刷新加工结果](../../../../data-process/timed-refresh.md)。值得注意的是，若设置的**定时提取**的频率较高，则在一定程度上会影响到系统的查询速度
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-sort.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/data-sort"
title: "排序"
---
---
order: 4
---
# 排序
排序是将一组“无序”的维度数据按照一定的规则顺序排列，支持按照指标的降序或者升序排列。如按照销售数量降序展示各类别产品的销售情况：
示例地址：[柱形图](https://demo.succbi.com/v5/bi/column-chart/play)
## 设置排序{#sort}
1. 选中柱形图，**属性栏**>**柱形图**>**X轴**，选中维度字段【大区】，点击下拉按钮选择**排序**
2. 在下拉框选择[排序方式](#sortby)
- 设置排序为**指定字段**
- 设置排序字段为【销售数量】
- 设置排序方式为**降序**
- 设置排序字段聚集方式为**总计**，字段的聚集方式可根据实际需求进行选择
通过以上2个步骤，即可实现大区按照销售数量降序排列，且在维度字段上可看到排序的标记。
:::tip 排序说明
[图形组件](../../components/chart/README.md)及[分组表](../../components/table/grouped-table.md)中只能在维度上设置，[明细表](../../components/table/columntable.md)中可以在维度或度量字段上设置
:::
## 排序方式{#sortby}
排序方式是指定维度字段按照哪个方式进行排序的排序规则，提供了以下4个属性设置：
- **排序**：选择字段排序方式，分为自动排序、不排序、指定字段、动态字段等。
- 自动排序：按照分组字段自动排序，如果分组字段是维键，则按照对应的关联维表设置的排序方式排序
- 不排序：字段不排序
- 指定字段：根据固定字段进行排序，当有多个排序字段时会按照从上到下的顺序依次进行排序，如同时添加【销售数量】和【销售金额】作为排序依据，会在【销售数量】排序的基础上再按照【销售金额】排序
- 动态字段：设置字段表达式进行排序
- **字段**：选择排序字段
- **排序类型**：升序或降序，默认为降序
- **聚集方式**：设置字段的聚集方式，根据聚集之后的结果进行排序，如总计、计数、计数（不同）、平均值、最大值、最小值等。
- 总计：返回分组数据的合计值，同[SUM](../../../../exp/func/aggregate/SUM.md)函数
- 计数：返回分组数据的计数值，同[COUNT](../../../../exp/func/aggregate/COUNT.md)函数
- 计数（不同）：返回分组数据的去重计数值，同[COUNTD](../../../../exp/func/aggregate/COUNTD.md)函数
- 平均值：返回分组数据的平均值，同[AVG](../../../../exp/func/aggregate/AVG.md)函数
- 最大值：返回分组数据的最大值，同[MAX](../../../../exp/func/aggregate/MAX.md)函数
- 最小值：返回分组数据的最小值，同[MIN](../../../../exp/func/aggregate/MIN.md)函数
::: tip 排序说明
1. 新增排序字段时会默认使用组件中已添加的第一个度量字段作为排序字段
2. 设置排序后，若同时在筛选器中设置了TopN，会先将数据筛选出TopN后，再将数据进行排序
:::
## 表格排序{#table-sort}
表格排序有2种方式：
- 在设计器中设置排序，方法如上[设置排序](#sort)，在设计器中设置排序后，每次查看仪表板时组件中的数据始终是按照当前设置排序显示
- 预览时，点击列头，可设置排序，仅在当前预览页面生效，下一次预览或刷新仪表板，仍然无排序。点击不同列头，可以切换排序列，排序依据是自身
:::tip 排序说明
[明细表](../../components/table/columntable.md)在字段上设置排序时，选择排序类型后，排序依据是自身
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/display.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/display"
title: "显示条件"
---
# 显示条件
**显示条件**设置用于控制组件的显示与隐藏，只有满足当前的显示条件时，组件内容才会显示。
## 设置组件的显示条件{#setting}
选中组件，在**图标**>**显示**属性中可以设置组件的显示与隐藏。当需要动态设置组件的显示隐藏时，可以选择`条件`，并在**显示条件**中设置表达式内容，如`[企业内部序号] !=''`，企业内部序号不为空时，该组件显示。
:::tip
在仪表板中，使用[显示隐藏交互](../action/switch-visible.md)控制组件的显示与隐藏时，该交互优先级更高
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/displayformat.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/display-format"
title: "显示格式"
---
---
order: 5
---
# 显示格式
**显示格式**设置用于将数据（包括数字、日期、字符串等）按照指定格式显示出来，类似Excel的单元格格式设置，更加方便用户多方面的使用。
## 如何设置{#setting}
### 设置数据模型的显示格式{#data-model}
数据模型处选择对应的字段，如【销售数量】，右键>**显示格式**
### 设置单元格的显示格式{#cells}
选中单元格，如单元格B4【销售数量】，**属性栏**>**样式**>**字体**>**显示格式**
### 设置组件数据的显示格式{#control-data}
选中组件KPI，如【成本价格】，右键>**显示格式**
## 属性介绍{#attribute}
### 表达式{#expression}
**表达式**指通过输入一段表达式内容，将计算结果作为显示结果输出。
如图为添加显示格式**格式化人民币（大写）**：
### 管理显示格式{#manage}
点击**管理显示格式**弹出管理显示格式对话框，可以对手动添加的显示格式进行管理。
具体的规则和语法参考文档[显示格式](../../../../exp/display-format.md)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-analysis/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/data-analysis"
title: "添加分析"
---
---
order: 6
navTitle: 添加分析
indexTitle: 添加分析
---
# 添加分析
分析用于对图表中的指标进行计算，比如计算数据占比、平均值等，一般可以通过新建计算字段的方式实现。而一些常用的计算方式比如占比、增幅或排名等支持通过选择相应的分析方式快速实现。添加分析包括以下三种方式：
- [添加分析](#add-analysis)
- [添加快速分析](#add-quick-analysis)
- [自定义分析](#custom)
## 添加分析{#add-analysis}
系统提供了部分常用的分析方式，可以通过选择所需分析方式实现相应计算，详见[常见分析方式](./rapid-analysis.md)。指标的表达式在添加分析后会发生变化，用户可以通过编辑该指标进行查看或编辑，若在编辑页面对表达式进行了修改，之前添加的分析不会再选中。
**操作步骤**
1. 选中控件，在**分组表**栏下，右键点击**销售金额**指标，选择**添加分析**
2. 在弹出框中设置**计算类型**为**数据期值**，相对于**去年同期**，点击**确定**，数据栏上的指标会显示对应的分析名称，即**上期统计值(销售金额)**
示例：[全国销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E5%85%A8%E5%9B%BD%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5%E8%A1%A8\)/play)
::: tip
鼠标移至已添加分析的字段，系统会弹出分析的详细信息
:::
### 编辑分析{#edit}
只有在添加分析后，才可以编辑分析。若用户需要修改已有分析方式，比如更换分析类型，更改汇总方式或数据期等，可以通过编辑分析进行修改，操作如下：
选中控件，在数据栏下，右键点击已经添加过分析方法的指标，选择**编辑分析**，操作页面和操作方式与[添加分析](#add-analysis)相同。
### 清除分析{#delete}
只有在添加分析后，才可以清除分析。当不需要分析时，可以清除分析方式，还原至初始数据，右键点击已设置分析方式的指标，选择**清除分析**即可。
::: tip
用户也可以在该指标的编辑页面通过编辑表达式的方式将表达式清除，或者使用模型上指标直接替换原有指标。
:::
## 添加快速分析{#add-quick-analysis}
快速分析是[添加分析](#add-analysis)的快捷方式，分析方式（详见[常见分析方式](./rapid-analysis.md)）采用添加分析的默认设置，可以快速进行分析，若需自定义分析内容，可在[添加分析](#add-analysis) 中操作。
**默认分析方式**
| 方式 | 默认 |
| :---------| :-------- |
| 累计汇总 | 累计汇总，分组依据为该控件的维度字段 |
| 增幅 | 同比增幅 |
| 增减额 | 同比增减额 |
| 数据期值 | 同比数据期值 |
| 百分比 | 分组依据为该控件的维度字段 |
| 累计百分比 | 分组依据为该控件的维度字段，排序方式与该控件的维度字段一致 |
| 排名 | 采用竞争排序降序排列，分组依据为该控件的维度字段 |
::: tip
若当前选中的控件没有维度，比如KPI控件，那么累计汇总、百分比、累计百分比和排名等需要计算依据的分析方式无法使用。
:::
## 自定义分析{#custom}
添加分析的实质是系统自动添加了分析函数，若添加分析提供的函数不能满足需求，可以通过**数据**>**维度**>**新建计算字段**的方式实现。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-analysis/rapid-analysis.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/rapid-analysis"
title: "常见分析方式"
---
---
order: 1
navTitle: 常见分析方式
---
# 常见分析方式
在[添加分析](./README.md)中，系统提供了一些常用的分析方式，包括：
- 常见分析方式
- [累计汇总](#sum)
- [增幅](#add)
- [增减额](#addcount)
- [数据期值](#data)
- [百分比](#percent)
- [累计百分比x](#sumpercent)
- [排名](#prize)
## 累计汇总{#sum}
返回某个区域数据的累计合计值，即[RUNNING\_SUM](../../../../../exp/func/analysis/RUNNING_SUM.md)函数，可设置计算类型、分组依据和排序依据。系统默认的计算类型是求和，以该图表的维度字段作为分组依据和排序依据，即快速分析中的累计汇总。
若要了解湖北省2010年各月份的累计销售数量，即将每月的销售数量累加至本年度已经发生月份的销售数量，可对【销售数量】进行累计汇总，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【销售数量累计】字段。
- 计算类型：**默认为求和**，可设置为求数据的平均值、最小值和最大值
- 平均值：返回某个区域数据的平均值，可设置分组依据，即[WINDOW\_AVG](../../../../../exp/func/analysis/WINDOW_AVG.md)函数
- 最小值：返回某个区域数据的最小值，可设置分组依据，即[WINDOW\_MIN](../../../../../exp/func/analysis/WINDOW_MIN.md)函数
- 最大值：返回某个区域数据的最大值，可设置分组依据，即[WINDOW\_MAX](../../../../../exp/func/analysis/WINDOW_MAX.md)函数
- 分组依据：***partitionfield*** 参数，即分组字段，支持多个，默认是该图表的维度字段，若想将非图表维度字段设置为分组依据，可将该字段拖入至**其他**中
- 排序依据：***orderfield*** 参数，即排序字段，默认按该图表维度字段的排序方式进行排序，可自定义排序
- 自定义排序：自定义排序依据和排序方式（升序或降序），排序依据可选择所使用模型表的任意字段，可设置多个排序依据
::: tip
1. 分组表无法根据标记的维度进行拆分，只能使用该表的维度字段作为分组依据
2. 若分组依据或排序依据只有一个字段，则系统默认以该字段作依据，和勾选与否无关
:::
## 增幅{#add}
计算增幅，可设置数据期。系统默认为求同比增幅，及快速分析中的增幅。
若要了解湖北省2010年各月份销售数量相比去年同期的变化率，分析每月销售数量的年同比波动情况，可对【销售数量】计算同比增幅，数据期设置为去年同期，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【同比】字段。
- 数据期：**默认为去年同期**，可设置为上一期、本年年初或者指定期
- 去年同期：计算同比增幅，即[YOY](../../../../../exp/func/analysis/YOY.md)函数
- 上一期：计算环比增幅，即[MOM](../../../../../exp/func/analysis/MOM.md)函数
- 本年年初：本期数据与本年年初数据的量的变化率，即`(本期数-本年年初数)/本年年初数×100%`
- 指定期：可自定义时间，比如计算当前时间数据相较于2019年10月份数据的增幅，数据期选择**指定期**后，在输入框内输入`201910`即可
## 增减额{addcount}
计算增减额，可设置数据期。系统默认为求同比增减额，即快速分析中的增减额。
若要了解2010年1月份各省份销售数量相比2009年1月份增长或减少的具体值，可对【销售数量】计算同比增减额，数据期设置为去年同期，详见[全国销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E5%85%A8%E5%9B%BD%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5%E8%A1%A8\))中的【去年同期增减额】字段。
- 数据期：**默认为去年同期**，可设置为上一期、本年年初或者指定期
- 去年同期：计算同比增减额，即[YOY\_VALUEY](../../../../../exp/func/analysis/YOY_VALUE.md)函数
- 上一期：计算环比增减，即[MOM\_VALUEY](../../../../../exp/func/analysis/MOM_VALUE.md)函数
- 本年年初：本期数据与本年年初数据的量的变化值，即`本期数-本年年初数`
- 指定期：可自定义时间，比如计算当前时间数据相较于2019年10月份数据的增减额，数据期选择**指定期**后，在输入框内输入`201910`即可
## 数据期值{#data}
计算上期的统计数值，即[PRES](../../../../../exp/func/analysis/PRES.md)函数，可设置数据期。系统默认为求去年同期的数据值，即快速分析中的数据期值。
若要将湖北省2010年各月份的销售数量与其前一个月的销售数量进行对比，分析波动情况，可对【销售数量】计算数据期值，数据期设置为上一期，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【前期值】字段。
- 数据期：即 ***offset*** 数据偏移参数，**默认为去年同期**，可设置为上一期、本年年初或者指定期
::: tip
使用增幅、增减额和数据期值时，需要确认使用的模型已经指定了数据期类型和数据期字段（在模型上设置，详见[模型属性](../../../../../data-gov/model/model-settings.md)，且提前设置某一时间作为本期时间。
:::
## 百分比{#percent}
返回某个区域数据的占比，即[WINDOW\_WEIGHT](../../../../../exp/func/analysis/WINDOW_WEIGHT.md)函数，可设置分组依据。系统默认以该图表的维度字段作为分组依据计算占比，即快速分析中的百分比。
若要了解湖北省2010年各月份的销售数量占全年销售数量的占比，分析销售的淡旺季，可对【销售数量】计算百分比，以【年月】作为分组依据，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【占比】字段。
- 分组依据：***partitionfield*** 参数，即分组字段，支持多个，默认是该图表的维度字段，若想将非图表维度字段设置为分组依据，可将该字段拖入至**其他**中
## 累计百分比{#sumpercent}
返回某个区域数据的累计占比，即[RUNNING\_WEIGHT](../../../../../exp/func/analysis/RUNNING_WEIGHT.md)函数，可设置分组依据和排序依据。系统默认以该图表的维度字段作为分组依据和排序依据，即快速分析中的累计百分比。
若要了解湖北省2010年各月份的销售数量的累计，即该月和本年度已经发生月份的销售数量的累加值占全年销售数量的占比，可对【销售数量】计算累计百分比，并按【月份】升序，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【累计占比】字段。
- 分组依据：***partitionfield*** 参数，即分组字段，支持多个，默认是该图表的维度字段，若想将非图表维度字段设置为分组依据，可将该字段拖入至**其他**中
- 排序依据：***orderfield*** 参数，即排序字段，默认按该图表维度字段的排序方式进行排序，可自定义排序
- 自定义排序：自定义排序依据和排序方式（升序或降序），排序依据可选择所使用模型表的任意字段，可设置多个排序依据
## 排名{#prize}
计算各项数据的排名，可设置排序方式、排序类型和分组依据。系统默认按竞争排序降序排列，以该图表的维度字段作为分组依据，即快速分析中的排名。
若要了解湖北省2010年各月份的销售数量的排名，可对【销售数量】进行排名，排序类型选择竞争排序，详见[按月查询销售情况表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))中的【销售年度排名】字段。
- 排序方式：***ordertype*** 参数，指定排序类型，默认为降序排列，可设置为升序
- 排序类型：**默认是竞争排序**，可设置为调整后竞争排序、密集排序或唯一排序
- 分组依据：***partitionfield*** 参数，即分组字段，支持多个，默认是该图表的维度字段，若想将非图表维度字段设置为分组依据，可将该字段拖入至**其他**中
| 排序类型 | 描述 | 举例 |\
| :---------| :-------- | :-------- |
| 竞争排序 | 即[RANK](../../../../../exp/func/analysis/RANK.md)函数，为相同值分配相同的排名，均为第一个相同值的排名，后面的数据继续排名 | (6, 9, 9, 14) 按升序排列为 (1, 2, 2, 4)|
| 调整后竞争排序 | 即[RANK\_MODIFIED](../../../../../exp/func/analysis/RANK_MODIFIED.md)函数，为相同值分配相同的排名，均为最后一个相同值的排名，后面的数据继续排名 | (6, 9, 9, 14) 按升序排列为 (1, 3, 3, 4) |
| 密集排序 | 即[RANK\_DENSE](../../../../../exp/func/analysis/RANK_DENSE.md)函数，为相同值分配相同的排名，均为第一个相同值的排名，后面的数据把重复值当成单个值继续排名 | (6, 9, 9, 14) 按升序排列为 (1, 2, 2, 3) |
| 唯一排序 | 即[ROW\_NUMBER](../../../../../exp/func/analysis/ROW_NUMBER.md)函数，为相同值分配不同的排名 | (6, 9, 9, 14) 按升序排列为 (1, 2, 3, 4) |
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/name.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/name"
title: "组件名称"
---
# 组件名称
每个组件都有一个唯一的标识ID和显示名称，**名称**会用在大纲树、表达式对话框的提示列表和表达式变量的标题上。选中组件，在**数据**>**高级**分组下可以设置，操作步骤如下：
1. **ID**：组件的引用名称，是系统根据选中组件自动生成的，带编号值
2. **名称**：缺省状态下为`组件类型`+`编号`，可以根据实际业务修改，给组件自定义业务别名，例如`企业关键字`，在表达式中可以直接引用
:::tip ID应用场景
**ID**会用在页面渲染时的DOM元数据的id属性上
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-filter/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/data-filter"
title: "仪表板组件数据过滤设置"
---
---
order: 7
navTitle: 过滤
indexTitle: 数据过滤
---
# 仪表板组件数据过滤设置
过滤是对组件中计算的数据进行限制和筛选，将满足过滤条件的数据显示到计算结果中。提供了2种过滤类型：
- 过滤器：对原始数据行进行过滤，过滤出符合条件的数据，类似于SQL中的where条件
- 筛选器：对结果集进行筛选，类似于SQL中的having条件，只能对组件内存在的分组字段进行筛选
如在柱形图中展示的是2010年10月销售数量Top10产品：
示例地址：[首页看板](https://demo.succbi.com/v5/DEMO/ana?:open=gtnQ2JTPUwLEX7QoKfonOG&:play=true)
**操作步骤**
1. **查看2020年10月份的数据：** 参考文档[柱形图](../../../components/chart/column-chart.md)完成对柱形图的取数，再将【销售日期】字段中【年月】拖入到**属性栏**>**数据**>**过滤器**中，选择【2010年10月】
2. **显示销售数量前10的产品大类：**在**属性栏**>**数据**中，【大类名称】数据字段右键或点击下拉选项选择**添加到筛选器**。在筛选器页面选择**前N个**，根据【销售数量】的总计降序，筛选**前10个**
## 过滤器{#filter}
**过滤器**是对原始数据行进行过滤，过滤出符合条件的数据，类似于SQL中的where条件。使用过滤器进行过滤时，提供了2种方式：
1. [字段过滤](#%e5%ad%97%e6%ae%b5%e8%bf%87%e6%bb%a4)
2. [表达式过滤](#%e8%a1%a8%e8%be%be%e5%bc%8f%e8%bf%87%e6%bb%a4)
### 字段过滤{#field-filtering}
字段过滤，是对数据模型字段的过滤，将符合过滤条件的数据保留。数据字段添加到字段过滤中，有三种操作方式：
- 将组件内引用的数据字段或数据区的数据字段直接拖拽到过滤器区域中
- 在数据模型字段上右键选择**添加到过滤器**
- 在数据模型字段上点击下拉选项选择**添加到过滤器**
在过滤器中，选择字段和操作符设置过滤条件，在过滤器选择框中可以通过点击下拉选项来切换其他字段，过滤器选择框的各个功能如下：
- 字段选择框：提供了当前选择字段所在数据模型的字段列表，可以选择模型中的其它字段
- 操作符选择框：可以通过点击的方式，切换操作符。操作符会根据选择的字段自动生成，选择的过滤字段类型不一样，可选择的操作符也不一样
- 条件编辑框：可以下拉选择或者手动输入的方式，编辑条件结果。如果这两种方式不能满足需求，也可以通过表达式的方式编辑条件结果，同时可引用当前仪表板中定义的参数，可参考[完成率分析](https://demo.succbi.com/v5/DEMO/app/%E6%9C%8D%E9%A5%B0%E9%94%80%E5%94%AE%E9%A9%BE%E9%A9%B6%E8%88%B1.app?id=%E5%AE%8C%E6%88%90%E7%8E%87%E5%88%86%E6%9E%90)（可参考该demo中本年度销售计划的过滤器），表达式具体操作可参考[表达式](../../../../../exp/README.md)
各类型数据可选择操作符如下：
| 数据类型 | 可用操作符 |
| :---------| :-------- |
| 字符型 | 属于、不属于、等于、包含、匹配、为空、不为空、开头是、结尾是、不等于、不包含、不匹配、前N个（升序）、后N个（升序） |
| 时间型 | 属于、不属于、包含、小于、小于等于、大于、大于等于、范围、排除、为空、不为空、前N个（升序）、后N个（升序） |
| 数值型 | =、<、<=、>、>=、范围、为空、不等于、不为空、前N个（升序）、后N个（升序） |
| 表达式 | 当操作符不能满足需求时，可以通过表达式进行编辑，具体操作参考[表达式](../../../../../exp/README.md) |
### 表达式过滤{#expression-filtering}
表达式过滤，用于字段间较复杂的过滤条件，通过输入表达式，经常搭配函数或参数使用。通过点击过滤器操作区域的下拉箭头，选择**表达式**进行表达式输入，具体表达式操作可参考[表达式](../../../../../exp/README.md)。
## 筛选器{#过滤器}
**筛选器**是对结果集进行筛选，类似于SQL中的having条件，只能对组件内存在的分组字段进行筛选。将数据字段添加到筛选器，提供了3种操作方式：
1. 将组件内引用的数据字段直接拖拽到筛选器区域中
2. 在数据字段上右键选择**添加到筛选器**
3. 在数据字段点击下拉选项选择**添加到筛选器**
筛选器提供了三种操作方式，这三种方式的设置之间是and关系：
1. [常规](#常规)
2. [分组筛选](#分组筛选)
3. [前N个](#前N个)
### 常规{#routine}
快速对数据字段筛选，通过勾选（可多选）的方式，决定数据字段中某些数据的保留或排除，如果选择的字段有层次，当选择父层次时，这时的选择类似于SQL中的匹配like；如果选择的是叶子节点或字段无层次，这时的选择类似于SQL中的in，多种选择是or的关系。
常规筛选器主要属性功能如下：
- 为空时包含所有：此功能主要针对常规选择框未勾选任何数据的情况下。当没有勾选数据项时，勾选该属性表示包含了所有的数据项；不勾选则显示出空值数据。
- 排除：勾选该属性后，表示将已经勾选的数据项排除
### 分组筛选{#group-filtering}
使用**分组筛选**功能，筛选出符合分组条件的数据，可以添加多个分组条件，类似于SQL中先group by再having。
**分组筛选**提供了设置多个条件的计算关系设置属性：
- 包含以下所有条件：多个条件之间的关系是and
- 包含以下任意条件：多个条件之间的关系是or
### 前N个{#top-n}
使用**前N个**功能，可以根据筛选依据筛选出前N条或前N%条数据。类似于SQL中的order by。
**前N个**提供了多个操作属性：
- 筛选前：控制筛选数量。单位为**个**或 **%**，可手动输入数字或者表达式
- 依据：进行筛选的条件，通过选择模型中的字段，然后系统根据所选字段的类型智能生成相应的操作符供选择，最后选择降序或升序对数据进行排序。多个筛选依据的关系为and关系
## 继承关系{#inheritance-relationship}
组件与画布之间过滤筛选条件，当前组件上的条件应该覆盖画布上同样的条件，如果两者条件不同，那么两者的过滤筛选条件为and关系。画布与组件的**过滤器**、**筛选器**区别如下：
1. 画布：画布上的过滤筛选，作用于整个画布中的组件
2. 组件：组件中的过滤筛选，作用自身组件中数据过滤筛选。部分组件有所区分，详细区分如下：
- 布局：布局中只有浮动面板具有**过滤器**、**筛选器**功能，作用范围可作用于自身及浮动面板中组件
- 表格：所有表格都具有**过滤器**、**筛选器**功能，作用范围仅作用于自身组件
- 图形：所有图形都具有**过滤器**、**筛选器**功能，作用范围仅作用于自身组件
- 输入组件：输入组件没有**过滤器**和**筛选器**功能
三者优先级关系为（从高到低）：自身组件>画布。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/style"
title: "标记"
---
---
order: 8
navTitle: 标记
---
# 标记
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/color.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/color"
title: "颜色"
---
---
order: 1
---
# 颜色
颜色标记是[条件样式](./README.md)的一种，可以使[图形控件](../../../components/chart/README.md)看起来颜色更加丰富或者使用颜色来凸显出某些数据。颜色中有多种颜色效果，如[颜色填充](#colorfill)、[色阶](#colorscale)、[色板](#colorboard)等。本文以[柱形图](../../../components/chart/column-chart.md)为例，介绍如何给图形控件设置颜色标记。
| 颜色填充 | 色阶 | 色板 |
| -------- | -------- | -------- |
||||
## 使用方法{#start}
在**属性栏**>**柱形图**>**字段**>**颜色**，设置当前系列的颜色标记，或者将字段拖到**颜色**中即可。颜色标记有6种类型：
- [自动](#automatic)
- [无填充](#null)
- [颜色填充](#colorfill)
- [色阶](#colorscale)
- [色板](#colorboard)
- [图片填充](#imagefill)
### 自动{#automatic}
**自动**填充根据当前**文件**设置的主题对柱形图柱子进行颜色填充。
### 无填充{#null}
**无填充**不进行填充，无显示效果。
### 颜色填充{#colorfill}
同一个系列的样式一般都是同种颜色进行填充，如两个系列柱形图中，零售总金额使用蓝色柱子进行填充，交易总金额使用橙色柱子进行填充。若需要修改柱子的颜色，可以通过修改颜色来设置柱子的颜色。**柱形图**点击字段下的**颜色**>**颜色填充**，在取色器中选取颜色即可。
### 色阶{#colorscale}
- **色阶**
- 原理：根据数据区间范围大小，进行色阶填充
- 适用场景：**连续**效果，指标数据，例如销售数量越高颜色越深，销售数量越低颜色越浅
色阶标记可以让图形控件展现出渐变的颜色效果，我们可以将作为依据的度量拖拽到**颜色**上，此时系统会根据每个系列的度量值大小来自动分配色阶颜色。
点击**颜色**按钮，弹出色阶标记对话框，可设置最大最小值点及中间值点的颜色，从而通过这三点形成一条色阶，点击**确定**后即可将当前的颜色设置作用于控件上。
- **倒序**：勾选后，将最小最大点的颜色倒序
- **重置**：点击后将恢复默认的色阶设置
- **应用**：点击后将按照当前的设置作用于控件上
### 色板{#colorboard}
- **色板**
- 原理：通过将数据分类，然后使用色板根据数据分类结果进行颜色填充
- 适用场景：**离散**效果，维度数据，不同的值使用不同的颜色，颜色会根据色板颜色进行填充。例如销售数量按照款式类别进行分类色板填充
色板是由一组不同的颜色组成的一条彩色图板，通过色板标记可以让图形显示出不同的颜色，如柱形图的每个柱子按照色板上的颜色实现柱子颜色各异，将度量字段**销售数量**拖到**颜色**，设置为**色板**，此时系统会根据色板上的颜色数量自动给每个柱子分配色板上的颜色，当指标数量多于色板上的颜色数量时，会按照色板颜色进行循环。
点击**颜色**按钮，弹出色板标记对话框，下拉选择主题色板，或者可以根据自定义设置特殊值的颜色。
### 图片填充{#imagefill}
**图片填充**可以手动选择**图片来源**和**填充方式**对当前柱形图的柱子进行填充
## 应用场景{#scene}
颜色标记不仅可以修改系列的颜色，实现系列中的颜色各异，还有更多的应用场景，如[堆积图](#stackingmap)、[地图颜色分段](#colorsegmentation)等。
### 堆积图{#stackingmap}
使用颜色标记，可以实现图形堆积，使用堆积图可以直观展示每个分组的值，以及反映出系列的总和。如使用[堆积柱形图](../../../components/chart/column-chart.md#stack)展示各大区的销售数量总和以及各价格档次的比重：
**实现方式**
将维度字段如【价格档次】拖到颜色中即可，并可通过[色板](#colorboard)标注不同分组的颜色。
### 地图颜色分段{#colorsegmentation}
在使用色板标记时，可设置特殊值自定义不同的颜色标注，如[疫情地图](https://demo.succbi.com/v5/bi/%E5%85%A8%E5%9B%BD%E6%96%B0%E5%9E%8B%E5%86%A0%E7%8A%B6%E7%97%85%E6%AF%92%E6%84%9F%E6%9F%93%E6%83%85%E5%86%B5%E5%88%86%E6%9E%90)中，根据确诊人数分段设置区块地图的颜色分段：
**实现方式**
1. 创建分段字段【确认人数分段】，可参考文档[添加分段字段](../../../../../data-process/transform/calc-section-field.md)
1. 将字段【确诊人数分段】拖到地图的**区块图层**>**颜色**中，点击颜色根据分段名称设置颜色特殊值
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/label.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/lable"
title: "标签"
---
---
order: 2
---
# 标签
标签的作用是在[图形控件](../../../components/chart/README.md)上显示出度量值、维度值等内容。
|默认提示信息 |自定义提示信息 |
| :---------| :-------- |
| ||
## 默认标签规则
统计图的标签默认不显示，标签默认值为度量值。统计图的标签提供了两个设置入口：
1. 在**数据**栏下，展开需要显示标签的字段，点击**标签**按钮，勾选**显示标签**（默认不勾选）
2. 在**样式**>**系列**下展开需要显示标签的字段，点击标签下拉框，选择**显示**（默认隐藏）
## 自定义标签信息
添加更多信息到标签的操作步骤如下：
1. 拖入没有引用的字段：在**数据**栏下，展开需要显示标签的字段，点击**标签**按钮，勾选**显示标签**（默认不勾选），将需要在标签里显示的字段【销售金额占比】拖到**标签**按钮上，此时显示的标签信息为拖入的字段值
2. 编辑标签内容：点击**文本**框里的铅笔按钮可以打开富文本编辑框，对标签字段进行编辑，调整标签信息的顺序
::: tip
拖入字段在标签中显示的规则为：第一个拖入的字段会覆盖默认标签信息，后续拖入的的字段会依次追加在前一个字段后。将新字段拖到已有字段上，可以替换该字段。默认标签被覆盖后可以在富文本编辑框里重新插入
:::
## 属性介绍
点击标签按钮，可以看到标签属性栏如下：
- 显示标签：勾选后在柱形图上显示标签，默认不勾选显示标签
- 文本属性：
1. 富文本编辑：点击铅笔按钮后打开富文本编辑框，可以对标签内容进行编辑。默认为图形控件使用的度量名称和维度值。详细使用方法参考文档[富文本编辑框](../../../../../app/superpage/components/input/richtextinput.md)
2. 其他属性：参考[字体属性栏](./other.md)文档
- 文字阴影：可以设置文字阴影，包括阴影类型、颜色、方向、模糊和扩展。参考文档[阴影](../../type/basic/shadow.md)
- 位置：标签显示的位置，包括自动（根据图形控件类型自适应位置，柱形图中默认为内部）、顶部、底部、内部、左侧和右侧
- 角度：标签显示的角度，包括水平和90°
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/size.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/size"
title: "大小"
---
---
order: 3
---
# 大小
大小标记是[标记](./README.md)的一种，可以在折线图、组合图、散点图以及地图散点图层中被使用，它能将数据的多与少通过点的大与小清楚的展现出来。比如可以在折线图中使用大小来表现各大区的折扣率情况：
## 使用方法{#method}
在**属性栏**>**组合图**>**大小**，设置当前系列的大小标记，或者将字段拖入到**大小**中即可。大小标记使用有两种情况：
- [直接设置散点大小](#direct)：不拖入任何字段到大小中
- [指标设置散点大小](#index)：拖入字段到大小中
### 直接设置散点大小{#direct}
不拖入模型字段到大小标记中，可以使用滑动数据条直接调节散点大小，改变的是所有散点的大小，且大小是一致的。
### 指标设置散点大小{#index}
当拖入字段到大小标记中时，此时系统也会以不同点的大小来展现拖入字段中指标数据的大小。
## 应用场景{#application-scenario}
大小标记不仅可以修改系列的大小，实现系列中的大小不同，还有更多的应用场景，如[气泡图](#bubble-chart)、[地图散点大小](#map-scatter)等。
### 气泡图{#bubble-chart}
使用大小标记，可以实现不同大小的点展示不同数据的大小。如使用[气泡图](../../../components/chart/scatter.md#bubble-chart)，便可以根据气泡的大小直观看出各省份的零售利润：
### 地图散点大小{#map-scatter}
地图散点图层是大小标记应用场景之一，使用不同点的大小来表示不同省份数据的大小，比如可以在[散点地图](../../../components/chart/gis-map.md#scatterlayer)中的散点图层使用大小来直观表现出销售数量在全国各省的分布情况：
**实现方式**
地图选择**散点图层**，将度量字段【销售数量】拖入到**数据**>**大小**即可。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/tooltip.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/tooltip"
title: "提示"
---
---
order: 4
---
# 提示
提示的作用是在预览和查看页面，将鼠标移动到或点击组件时，弹出系列名、维度值等内容。
|默认提示信息 |自定义提示信息 |
| :---------| :-------- |
| ||
## 默认提示规则{#default}
在**数据**栏下，展开需要设置提示信息的字段，点击**提示**按钮，默认勾选**显示提示**，此时显示默认的提示信息。规则如下：
1. 默认提示信息为统计图里引用的所有数据字段：【省】、【销售金额】
2. 提示信息的默认显示顺序为：该系列所在的维度值、系列值
3. [图形](../../../components/chart/README.md)组件（[KPI](../../../components/chart/kpi.md)、[里程表](../../../components/chart/odometer.md)、步行图除外）默认勾选**显示提示**，[表格](../../../components/table/README.md)组件默认不勾选**显示提示**
示例：[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 自定义提示信息{#custom}
将组件中没有引用到的字段加入到提示信息中，操作如下：
1. 拖入没有引用的字段：将需要设置为提示信息的字段【完成率】拖到**数据**栏下的**提示**按钮上
2. 编辑提示内容：点击**文本**框里的铅笔按钮可以打开富文本编辑框，对提示字段进行编辑，包括调整提示的顺序，修改提示的文字信息或者删除提示内容
示例：[柱形图](https://demo.succbi.com/v5/bi/column-chart)
### 提示顺序规则{#sequence}
提示信息为拖入的提示字段以及统计图里引用的所有数据字段，提示信息的默认显示顺序为：
1. 维度
2. 度量
3. 拖入的提示字段。拖入的提示字段会按照拖入先后顺序依次显示
## 属性介绍{#property}
- 显示提示：勾选后显示提示信息
- 文本：点击铅笔按钮可以打开富文本编辑框，对提示信息内容进行删除、插入操作
- 字体：设置文字的字体类型、颜色、大小等
- 触发方式：提示信息的触发方式
- 鼠标移动：鼠标移动到图形组件系列上即显示提示信息
- 边框：提示信息边框样式，包括线型、颜色和线宽
- 背景填充：提示信息的背景填充颜色
- 阴影：提示信息框的阴影样式，包括阴影位置、颜色、X、Y、模糊和扩展
- 圆角：提示信息框圆角设置，可分别设置左上、左下、右上、右下4个外角
- 内边距：提示信息框内的边距大小
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/other.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/other"
title: "其它"
---
---
order: 5
---
# 其它
**其它**标记是特殊标记，常用于该组件下其它属性的引用，包括[标签](./label.md)标记属性、[提示](./tooltip.md)标记属性、[条件样式](../../type/condition-style.md)及[图例](../../type/legend.md)等。例如，标签和提示信息中都需要用到【零售总额】指标，则可以将该字段拖入到**其它**标记中。操作步骤如下：
1. 拖入字段到其它标记：选中组件，在引入的数据模型中，将【零售总额】字段拖入到**数据**>**其它**标记中
2. 在提示信息中加入该字段：点击**提示**标记，在弹出的选择面板中，点击**文本**属性旁的铅笔按钮，在弹出的编辑器中修改标记。点击右上角**插入**按钮，在下拉列表中点击【零售总额】，即可将该字段加入到提示信息中
3. 在标签中加入该字段：操作同第二步
::: tip
在其它标记中加入的字段，在图例中也可以引用，通过这种方法可以实现自定义图例。例如饼图图例中带有指标占比数据，具体可以参考文档[自定义图例](../../type/legend.md#setting)
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/data-style/reference-line.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/reference-line"
title: "参考分析"
---
---
order: 6
---
# 参考分析
参考分析是在统计图中添加作为数据参考的辅助线或辅助点等。只有带有轴线的统计图（如柱形图、折线图、散点图等）有此功能。
参考分析有以下几种类型：
| 参考点 | 参考线 | 参考区间 |
| ------ | ------ | -------- |
||||
示例地址：[参考线](https://demo.succbi.com/v5/bi/column-chart)
- [参考点](#reference-point)
- [参考线](#reference-line)
- [参考区间](#reference-interval)
## 添加参考分析{#reference-analysis}
### 默认参考指标{#default-reference}
在**属性栏**>**数据**，展开系列名称，如销售数量，点击**添加分析**，选择对应的参考类型，如**平均值**，并设置了部分属性后，点击**确定**即可看到统计图上增加了一条值为销售数量平均值的参考线。
### 自定义参考指标{#defined-reference}
从**数据模型**中拖入度量字段，如销售计划（万元）至**属性栏**>**数据**系列名称下的**其它**中，点击**添加分析**，选择对应的参考类型，在**值**下拉列表中选择**销售计划（万元）**，点击**确定**即可看到统计图上增加了一条值为销售计划（万元）平均值的参考线，可以查看哪些大区的实际销售大于销售计划平均值。
:::tip
1. 当统计图中存在多个指标时，可以在**值**下拉列表中选择作为参考的指标
2. 拖入到颜色，标签，提示，其它下的指标字段，均可以作为参考指标，即在**值**的下拉列表中会出现选项，选择对应指标即可
:::
## 参考点{#reference-point}
在统计图当中添加一个辅助参考点进行标注，一般用于突出标注某个特殊值，当有多个指标字段时，可选择参考的系列指标。
- 值：下拉选择参考的系列指标，值的选项有平均值、最大值、最小值
- 形状：用于设置参考点的标注形状
:::tip
最大值点与最小值点也可在**添加分析**中直接选择[快捷方式](#shortcut)**最大值**、**最小值**
:::
## 参考线{#reference-line}
在统计图当中添加一个辅助线，用于对比大于某个值的指标，如添加一条平均线，查看哪些数据大于平均值，当有多个指标字段时，可选择参考的系列指标。
- 值：下拉选择参考的系列指标，值的选项有平均值、最大值、最小值
- 线：用于设置参考线的线型、颜色及粗细
:::tip
- 当选择平均线时可在**添加分析**中直接选择快捷方式**平均线**
- [常量线](#constant-line)与[比率线](#ratio-line)是2种特殊的参考线
:::
## 参考区间{#reference-interval}
根据开始值与结束值，以一段区间作为辅助区间，如查看哪些指标的数据位于平均值至最大值之间。
- 区域开始：设置区域开始的度量值，当有多个字段时，可选择参考的指标，值可选平均值、最大值、最小值
- 区域结束：设置区域结束的度量值，当有多个字段时，可选择参考的指标，值可选平均值、最大值、最小值
- 填充：用于设置参考区间的背景颜色
- 边线：用于设置区间的边框线型
## 快捷方式{#shortcut}
添加参考线或参考点时，为值的分析提供了快捷方式，分为以下几种：
- [常量线](#constant-line)
- [比率线](#ratio-line)
- [平均线](#average-line)
- [最大/最小值](#max-min)
:::tip
使用快捷方式时，默认指定的是当前指标，如果需要切换其它指标，应该从**添加分析**的入口中选择对应的参考类型
:::
### 常量线{#constant-line}
参考线的一种特殊情况，即值为常量的参考线。其中，**值**属性是输入一个固定值，可选择线的方向为**横线**或者**竖线**。
:::tip
当数据显示在横坐标轴上时，一般选择**竖线**；当数据显示在纵坐标轴上时，一般选择**横线**。
:::
### 比率线{#ratio-line}
比率线是一条一元一次方程(y=ax+b)的直线，a代表比率，b代表偏移量。
如图为3条完成率为不同比率的参考线：
示例地址：[比率线](https://demo.succbi.com/v5/bi/scatters-and-bubbles)
### 平均线{#average-line}
一条值为当前指标的平均值的直线
### 最大/最小值{#max-min}
最大/最小值的参考点，以当前指标作为参考度量
示例地址：[参考点](https://demo.succbi.com/v5/bi/line)
## 属性介绍{#attribute-introduction}
### 标签{#label}
用于设置在参考点或参考线上的标签信息，与统计图的[标签](./label.md)信息的作用是一致的。
- 值
- 无：即无标签信息
- 值：即标签信息为当前指标的计算值
- 描述：即参考线或参考点的值的选项，参考线的值为最大值，则标签为最大值
- 位置：标签的显示位置，在不同的分析类型中可选位置不一致
- 参考点：上侧、下侧、内部中间、内部上侧、内部下侧
- 参考线：起始、结束
- 参考区间：上侧、下侧、内部中间、内部上侧、内部下侧
### 形状{#shape}
在参考线中为参考线的终点的形状标注，在参考点中为参考点的标注形状。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/data/fill-dimension.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/fill-dimension"
title: "fill-dimension"
---
---
order: 9
navTitle: 补全维项
---
# 补全维项
**补全维项**可以将没有数据的维项也在图表中展示出来。例如事实表中只有`上装`和`下装`的销售数据，没有`套装`的数据，希望在图表中将所有类型都显示出来，就可以用**补全维项**将所有维项展示。以柱形图展示上下装类型补齐为例介绍：
- **选择数据**：将【上下装】拖入**x轴**，将【销售数量】拖入**y轴**
- **设置补全维项**：选中组件，在**数据**>**x轴**处右键`上下装`，选择中的**补全维项**
## 过滤不在维项中的数据{#dim}
**过滤不在维项中的数据**可以过滤掉维表中不存在的维项数据。例如事实表的【上下装】字段中，有编码为`02`和`99`的数据，但在上下装维表中不存在编码为`99`的维项，如果只希望展示维表中存在的维项，就可以使用该功能过滤掉不在维表中的数据。
:::tip 说明
**补全维项**是从原数据行上补齐事实表中没有的数据，**补全维项**和**过滤不在维项中的数据**只能针对设置了[关联表](../../../../data-gov/model/README.md#associated-table)的[维度](../../../../data-gov/GLOSSARY.md#dimension-key)。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/type"
title: "组件样式设置"
---
---
order: 4
navTitle: 样式
---
# 组件样式设置
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/basic"
title: "组件基本属性介绍"
---
---
order: 1
navTitle: 组件基本属性
indexTitle: 组件基本属性
---
# 组件基本属性介绍
仪表板组件的基本属性：
!!! children !!!
## 如何设置
组件**属性栏**>**样式**>，点击组件名称：
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/colorPalette.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/colorPalette"
title: "图表"
---
---
navTitle: 图表
---
# 图表
## 色板{#swatches}
色板属性是用来设置图形的颜色，以达到更加美观的展示效果。当图形中有多个系列时，系列颜色会按照该属性中选择的色板来填充。
柱形图、条形图、组合图、折线图、面积图、雷达图具有色板属性。
### 示例{#example}
该统计图中有3个系列，每个系列的颜色根据色板的颜色显示
示例地址:[条形图](https://demo.succbi.com/v5/bi/bar/play)
### 如何设置{#how-to-settings}
每种主题都内置了多种不同效果的色板，包括纯色和渐变色。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/barlayout.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/barlayout"
title: "布局"
---
---
navTitle: 布局
---
# 布局
柱形图、条形图、组合图具有系列布局属性，当图形中有多个系列时，需要设置系列的布局类型。表格具有布局属性，可以设置表格的行高和列宽显示方式及行高列宽的数值大小。
## 图形布局{#figure}
| 并排 | 重叠 |
:-------------------------:|:-------------------------:
 | 
### 如何设置{#setting}
组件属性栏**样式**>**组件**>**布局**
## 表格布局{#table}
| 适应内容 | 适应容器 | 自定义 |
:-------------------------:|:-------------------------:|:-------------------------:
 | | 
### 如何设置{#settings}
组件属性栏**样式**>**组件**>**布局**
- 布局：设置表格显示的布局
- 列宽：设置表格列的宽度，有以下选择：
1. 等分列宽：按照表格的宽度等分列宽
2. 适应内容：表格的列宽根据字段内容自行调整
- 行高：设置表格行的高度，有以下选择：
1. 适应容器：根据容器大小自动调整行高
2. 适应内容：根据字段内容自动调整行高
3. 自定义：手动设置行高数值大小
- 自动撑大行高：自动按照内容撑大行的高度
- 允许调整列宽：自动按照内容调整列宽
- 自动调整组件高度：自动按照内容调整组件高度
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/style.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style"
title: "风格"
---
---
order: 1
---
# 风格
风格是组件的所有属性样式的集合，每一个组件都可以保存多个风格，通过风格的使用可以做到多个组件一起快速的切换外观风格、也可以做到修改风格后所有的组件的外观一起变化。
在设计仪表板时可以随时对风格进行应用、更新、编辑、重命名和删除的操作。本文将讲解风格的管理和使用。
## 管理风格{#manage}
我们可以通过新增风格、应用风格、更新风格、编辑风格、重命名和删除来对组件的风格进行管理。
- 新增风格：当已有的风格都无法满足我们的需求时，我们可以通过点击风格列表右上角的＋号来新增风格。新增的风格默认为图表当前样式风格。
- 应用风格：当我们需要快捷设置组件样式的时候，可以应用风格，一键设置组件的样式。
- 更新风格：当我们想要将当前样式覆盖到当前风格中时，可以更新风格。
- [编辑风格](#edit)：编辑风格适用于需要手动调整风格的情况。点击编辑风格按钮可以打开风格管理，在风格管理中对当前风格进行编辑。
- 重命名：对当前选中风格进行重命名。
- 删除：删除当前选中风格。
### 编辑风格{#edit}
编辑风格适用于需要手动调整风格的情况。点击编辑风格按钮可以打开风格管理，在风格管理中对当前风格进行编辑。
风格管理中包含该组件的所有可以修改的属性。各个属性描述可以在对应图表文档中进行查看。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/basicSetting.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/title"
title: "标题"
---
---
order: 2
navTitle: 标题
---
# 标题
标题属性分为[布局选项](#layout)和[标题样式](#style)。布局选项主要用来控制是否显示标题，标题样式主要用来设置标题的相关属性。本文主要介绍这两种组件选项的使用方法。
## 布局选项{#layout}
输入组件和非输入组件均有该属性，在**样式**>**标题**>**布局**，点击**显示标题**勾选框控制标题的显示隐藏，同时标题有自己独立的风格存储，可以单独切换组件的标题风格样式。
除此之外，输入组件可以在[布局选项](#layout)选择标题的位置，包括`左侧`，`右侧`，`上侧`三个方位，[布局选项](#layout)也可以设置标题的宽度，当设置宽度为自适应时根据标题内容自动调整宽度，设置宽度为像素则可以手动选择像素的值，选择任意一种方式均可以设置宽度的最大值最小值。
## 标题样式{#style}
### 字体{#typeface}
标题的**字体**在**样式**>**标题**>**字体**中进行设置。可以设置标题文字的字体，颜色，大小，对齐方式及文字调整方式。文字调整默认为不调整，当选择自动换行时标题过长则会自动换行显示。
### 图标{#shape}
标题的**图标**默认与标题风格一致，同时也可以自定义选择图标，可以在右侧输入框手动调整图标的大小。
### 填充{#fill}
标题的**填充**方式默认为无填充，可以在下拉框手动选择填充方式，具体属性设置可查看[填充](../../../components/chart/hpictorialbar.md#layout)。
### 边框{#frame}
标题的**边框**默认为无边框显示，可以在下拉框手动选择标题的边框线条，具体属性设置可查看[边框](./border.md)。
### 内边距{##padding}
标题**内边距**可以在下拉框选择数值，默认四个方位内边距大小一致，也可以手动设置**内边距**大小。具体属性可查看[内边距](./padding.md)
### 阴影{#shadow}
标题的**阴影**可以设置文字阴影，颜色及范围大小，文字阴影和颜色都默认为无，其他设置选项默数值为0，可以在下拉框手动选择颜色和文字阴影样式以及设置数值大小。具体属性可查看[阴影](./shadow.md)
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/background.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/backgroud"
title: "背景"
---
---
order: 5
---
# 背景
背景属性是用来设置画布或控件的背景色或背景图片，以达到更加美观的展示效果。
## 示例{#example}
该超市大数据分析平台仪表板的背景为动效填充：
示例地址：[超市大数据分析平台](https://demo.succbi.com/v5/bi/%E8%B6%85%E5%B8%82%E9%9B%B6%E5%94%AE%E5%A4%A7%E5%B1%8F)
## 属性介绍{#attribute}
**背景**有4种填充方式：
- 无填充：即无背景
- 颜色填充：可选择**纯色**填充或**渐变色**填充，渐变色的设置可以查看[渐变色填充设置](#gradient)说明
- 图片填充：选择图片填充时，可选择系统图片库中的图片，也可上传自定义图片，可参考文档[图片](../../../components/more/image.md)
- 动效填充：背景以动态的效果展示，系统中同样也提供了多种动效
### 渐变色填充设置{#gradient}
若希望背景实现渐变色的效果，可以在颜色填充中选择**渐变色填充**，具体操作步骤如下：
1. 选中画布、组件或需要设置渐变色的内容，在**属性栏**>**样式**>**填充**中选择`颜色填充`
2. 点击`颜色填充`下方显示的当前填充颜色，选择**渐变色**，调整**角度**，**角度**设置为`90°`时颜色横向渐变，设置为`180°`时颜色纵向渐变
3. 使用两边的拾色器进行颜色的拾取，可在**主题色板**和**更多颜色**中进行不同颜色的拾取
:::tip 多色渐变
在两个拾色器中间左键单击，可以添加拾色器，进行多种颜色组合的渐变色设置。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/border.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/border"
title: "边框"
---
---
order: 6
---
# 边框
边框属性用来设置控件的外部边框。
## 属性介绍
- 边框位置：外部边框、上边框、右边框、下边框、左边框
- 线型：虚线、实线、点线、无
1. 设置为虚线、实线、点线时，可设置边框线的颜色及线条宽度
2. 设置为**无**时即无边框
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/shadow.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/shadow"
title: "阴影"
---
---
order: 7
---
# 阴影
阴影用于给控件的边框添加阴影效果。
## 示例
## 属性介绍
- 样式：根据上、下、左、右4个方向有9种组合样式
- 颜色：设置阴影的颜色
- X偏移：阴影水平偏移量
- Y偏移：阴影垂直偏移量
- 模糊半径：将模糊效果由边缘向两端延伸
- 扩展半径：增加阴影的尺寸
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/border-radius.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/border-radius"
title: "圆角"
---
---
order: 8
---
# 圆角
圆角是用一段与角的两边相切的圆弧替换原来的角，圆角的大小用圆弧的半径表示。
## 如何设置
控件中有2处地方具有圆角属性：
1. 用于设置整个控件的外角：控件属性栏**样式**>**圆角**，参考[控件基本属性](./README.md)
2. 柱状图(如柱形图、条形图、条形占比图等)中，设置柱子的外角：**样式**>**系列**>**圆角**
## 属性介绍
- 设置控件的圆角：可分别设置**左上**、**左下**、**右上**、**右下**4个外角
- 设置柱形图中柱子的圆角：
1. 大小输入框：输入数字时同时设置柱子的4个角
2. 仅限外角：指柱子离坐标轴较远的2个角，是一个勾选框，默认不勾选
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/basic/padding.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/padding"
title: "内边距"
---
---
order: 9
---
# 内边距
内边距用于设置控件边框与控件内容之间的空白区域，数值越大，内容与边框距离越远。
## 属性介绍
可同时设置4个方向的内边距，也可分别设置**上**、**下**、**左**、**右**4个方向
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/Axis.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/Asix"
title: "坐标轴"
---
---
order: 2
---
# 坐标轴
**坐标轴**从x轴，y轴两个角度将数据直观的呈现在用户面前。只有[柱形图](../../components/chart/column-chart.md)，[条形图](../../components/chart/bar-chart.md)，[散点图](../../components/chart/scatter.md)等具有轴线的统计图才有坐标轴。
## 属性{#attribute}
坐标轴的轴属性如下：
- [轴标题](#title)
- [刻度值](#value)
- [轴标签](#label)
- [轴线](#axis)
- [刻度线](#scale)
- [分割线](#divider)
### 轴标题{#title}
控制**轴标题**的显示与隐藏，显示位置，轴标题内容，轴线距离，以及字体。
### 刻度值{#value}
- 刻度值：选择线性时，刻度值为线性值；选择对数时，刻度值为10的幂方数。
- 最小值：选择固定值时，可以设置最小值的数值；选择偏移值时，可以选择最小值的偏移百分比。
- 最大值：同最小值。
- 固定值：设置最大值和最小值的数值。
### 轴标签{#label}
控制**轴标签**的显示与隐藏，显示格式，角度，以及轴标签的字体。
- 显示格式：选择自动时，显示格式为字段自身格式；选择百分比时，显示格式为所占百分比格式。
- 角度：选择相应角度则对应坐标轴的轴标签以该角度倾斜显示。
### 轴线{#axis}
设置**轴线**的显示效果，颜色以及宽度。
### 刻度线{#scale}
设置**刻度线**的显示效果，颜色以及宽度。
### 分割线{#divider}
设置**分割线**的显示效果，颜色以及宽度。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/legend.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/legend"
title: "图例"
---
---
order: 4
---
# 图例
图例是对统计图上各种符号和颜色所代表内容与指标的说明。
## 属性介绍{#attribute}
图例具有以下属性：
- 布局：设置图例显示的布局
- 图例：设置图例的显示内容，有以下选择：
1. 自动：默认设置为自动，显示的内容为所有系列
2. 系列：显示为系列的值
3. 隐藏：隐藏图例
4. 引用的模型表指标：显示为指标的值。
- 位置：设置图例在统计图中的显示位置，分别为**顶部**、**底部**、**左边**、**右边**
- 对齐：设置图例的对齐方式，分别为**居左对齐**、**居中对齐**、**居右对齐**
- 滚动翻页：可以设置图例翻页显示，一般当用于统计图中系列较多时
- 字体：设置图例内容的字体，参考文档[字体](../../../../dev/extension/extension-points/font.md)
- 边框：设置图例的边框，参考文档[边框](./basic/border.md)
- 内边距：设置图例中每个系列内容的间的边距，参考文档[内边距](./basic/padding.md)
## 自定义图例{#setting}
在图例属性中，除了自带的选项外，也可以自定义图例显示的内容，例如饼图展示各价格档次的销量分布，图例显示为价格档次+销量占比，如`高档 10.62%`：
- 拖入`销量占比`字段到**数据**>**其他**，编辑字段内容为`CONCAT(([门店销售明细表].[价格档次].[名称]),' ',CONCAT((ROUND(WINDOW_WEIGHT([门店销售明细表].[销售数量(件)])*100, 2),'%')))`，编辑标题为`价格档次+销量占比`
- 在**样式**>**图例**>**布局**>**图例**中选择`价格档次+销量占比`
:::tip
1. 模型表拖入**数据**>**其他**的指标，会出现在**样式**>**图例**>**布局**>**图例**的下拉框中
2. [WINDOW\_WEIGHT](../../../../exp/func/analysis/WINDOW_WEIGHT.md) 函数用于返回某个区域数据的占比，想要快速求某个区域数据的占比也可在快速分析中直接设置百分比，详细介绍见文档：[快速分析](../data/data-analysis/README.md)
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/target.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/target"
title: "指标"
---
---
order: 7
---
# 指标
指标属性用于设置KPI控件和里程表控件的数据样式。
## 属性介绍
- 标题
- 值
- 单位
- 符号
### 标题
设置KPI和里程表指标数据的标题是否显示,可设置标题的字体样式
### 值
指标中显示的数值的字体样式,里程表中还可设置背景
### 单位
在KPI中可给指标增加单位,输入内容即可
### 符号
设置里程表中的符号的样式
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/condition-style.md"
htmlUrl: "https://docs.succapp.com/v5/dash/data/condition-style"
title: "条件样式"
---
---
navTitle: 条件样式
---
# 条件样式
在仪表板中可以通过条件样式来标注符合规则的组件或动态更改表格单元格的外观，例如：
- 使用红色文字标注表格中同比增幅小于10%的省份
- 使用不同的图标标注表格中的计划完成情况，绿色图标表示完成度超过90%
也可以使用状态样式来实现鼠标悬停、选中、按下等状态效果，例如：
- 鼠标滑动到按钮或KPI上时有阴影效果
- 选中标签页的选项后有高亮效果
## 条件样式介绍{#condition-style}
仪表板中设置条件样式的入口在左侧属性栏的样式栏下，下面在分组表中以具体的操作来展示条件样式的用法：
- 将销售数量使用**数据条**来展示
- 同比则使用**突出显示**来标注，同比大于0时显示为绿色字体和绿色箭头，同比小于0则是红色
关于条件样式的详细介绍可查看[报表条件样式](./condition-style.md)。
示例地址：[条件样式](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))
1. **选择组件**：选择需要添加条件样式的组件，即分组表
2. **添加条件样式**：在**属性栏-样式-分组表-条件样式**下点击**添加**按钮，添加一个**数据条**的条件样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择`销售数量`
- **设置样式**：修改正值填充的颜色，并设置宽度为`45%`，设置边框为`无`
- **重命名**：将条件样式重命名为`数据条`
3. **添加第二个条件样式**：点击设置面板左上角的**添加**按钮，添加一个**突出显示**的条件样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择`同比`
- **设置规则**：设置规则为**当前值-大于-0**
- **设置样式**：选择**样式**下的**主题**风格`大于0`
- **重命名**：将条件样式重命名为`同比大于0`
4. **添加第三个条件样式**：再添加一个**突出显示**的条件样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择`同比`
- **设置规则**：设置规则为**当前值-小于-0**
- **设置样式**：选择**样式**下的**主题**风格`小于0`
- **重命名**：将条件样式重命名为`同比小于0`
5. **保存条件样式设置**：点击对话框中的确定按钮保存当前条件样式设置
## 状态样式介绍{#effect-style}
状态样式的入口同条件样式，下面以添加标签页**选中**的状态样式为例来介绍下具体操作步骤，关于状态样式的详细介绍可查看[SPG的状态样式](../../../../app/superpage/design/style/condition-style.md#use)。
示例地址：[状态样式](https://demo.succbi.com/v5/bi/%E7%8A%B6%E6%80%81%E6%A0%B7%E5%BC%8F)
1. **选择组件**：选择需要添加状态样式的组件，即标签页
2. **添加条件样式**：在**属性栏-样式-标签页-条件样式**下点击**添加**按钮，添加一个**选中**的状态样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择即为当前`标签页`
- **设置样式**：选择样式风格`选中-圆角`
3. **保存条件样式设置**：点击对话框中的确定按钮保存当前条件样式设置
## 支持使用条件样式和状态样式的组件{#arrange}
组件|状态样式|条件样式|
-|-|-|
表格|不支持|突出显示、最前最后、数据条、步进器、色阶、图标集
图形（除地图和图标条外）|选中、悬停、按下|突出显示
输入-下拉框、输入框、日期、快速搜索|不支持|突出显示
输入-选择面板、标签页|选中、悬停、按下|突出显示
更多-按钮|选中、悬停、按下、禁用|突出显示
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/table/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/table"
title: "表格属性介绍"
---
---
order: 5
navTitle: 表格
indexTitle: 表格属性
---
# 表格属性介绍
设置明细表和分组表的基础属性，例如边框、间距、隔行换色、滚动方式、分页等
## 属性介绍
- 表格选项：设置表格是否显示序号，参考文档[组件选项](../basic/basicSetting.md)
- 间距：设置表格的列宽、行高
1. 列宽可设置**适应内容**或**等分列宽**，**适应内容**下能够指定**最大宽度**
2. 当内容长度大于最大宽度时，可勾选**自动换行**实现表格内容自动换行；
3. 行高可设置**适应内容**、**适应容器**及**自定义**
- 表格外框：设置表格外边框的样式、颜色、宽度
- 网格线：设置表格内部网格线的样式、颜色、宽度
- 隔行换色：设置表格隔行换色的颜色，包括纯色和渐变色
- 冻结：设置冻结列，勾选后能够指定前n列在表格横向滚动时固定显示
- 分页：选择**显示**后，能够在展开项中对分组表每页行数、分页栏的位置、样式、显示信息及翻页方式进行设置
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/type/table/ranks.md"
htmlUrl: "https://docs.succapp.com/v5/dash/style/ranks"
title: "行列基本属性"
---
---
order: 2
---
# 行列基本属性
表格控件可以设置行或列的内容的基本样式，如字体样式，背景填充与对齐方式等。\
只有[表格](../../../components/table/README.md)控件中有行列基本属性。分组表中为行列，明细表中为列。
## 示例{#examples}
该分组表中调整年月内容背景色为蓝色，对齐方式为居中
示例地址：[行列基本属性](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E6%8C%89%E6%9C%88%E6%9F%A5%E8%AF%A2%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5\))
## 如何设置{#how-to-setting}
1.表格完成取数后，点击样式，行列，选中需要设置样式的维度或度量（如年月）\
2.在字体、背景、对齐方式中做需要的修改
## 属性介绍{#introduction}
行列中具有4个属性
- 字体：可设置指标字体类型、字体颜色、字体大小与是否加粗，斜体或加划线
- 背景：为行列添加背景，具体参考[背景](../basic/background.md)
- 对齐方式：默认为自动，可选择居中、居左与居右显示指标内容
- 还原默认设置：默认为禁用状态，行列属性存在修改时可一键还原为初始状态
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action"
title: "仪表板组件的交互概述"
---
---
order: 5
navTitle: 交互
indexTitle: 概述
---
# 仪表板组件的交互概述
交互是指用户的一个“操作”，如鼠标点击一个按钮、改变一个下拉框的值等，如以下所示：
- 点击图形查看明细数据需要使用[打开链接](./linkto.md)动作
- 点击图形为参数赋值需要使用[设置参数值](./set-param-value.md)动作
- 切换不同的展示内容需要使用[切换多页面板](./switch-panelbook.md)动作
- 点击按钮将整个页面导出为PDF等文件需要使用[导出仪表板](./export-dash.md)动作
:::tip 交互与动作的关系
交互是由动作组成的，可在交互中添加一个或多个动作。
:::
## 设置动作的生效条件{#condition}
每个动作均可设置生效条件，在**生效条件**属性中设置即可，提供了如下选项：
- **启用**：默认为**启用**，将等待上一个动作正常执行完成后执行
- **禁用**：禁用该动作，通常用于调试
- **叶子节点**：只在叶子节点时生效
- **非叶子节点**：只在非叶子节点时生效
- **条件**：需要满足某种条件后再执行动作，同时需要对**等待执行**、**等待状态**和**启用条件**进行设置。动作在执行前先进行等待，等待结束后根据**启用条件**判断是否执行
- **等待执行**：
- 上一个动作：上一个动作，默认为该选项
- 立即执行：立即执行该动作，与上一个动作并行执行
- 其他可选动作列表：除了当前动作之外的所有动作列表，按动作设置顺序显示
- **等待状态**：
- 完成：等待的动作执行成功
- 失败：等待的动作执行失败，需要依据动作的类型才会有失败的状态，例如[执行脚本](https://docs.succapp.com/v5/dash/action/script)动作
- 结束：等待的动作执行结束（包括成功和失败）
- **启用条件**：输入表达式对动作的使用条件进行限制，当表达式返回`true`时动作生效，否则动作不生效，如等待**上一个动作完成**，**启用条件**为`[参数1]=1`，表示等待上一个动作正常执行完成后，判断参数1的值是否等于1，该动作方可执行
:::tip 更多说明
使用**叶子节点**与**非叶子节点**选项时，前提条件为添加交互的载体组件中所使用的维度字段设置了[数据级次](../../../../data-gov/model/data-hierarchy.md)。
:::
## 设置动作的触发事件{#trigger}
每个动作均可设置生效的前置触发事件，在**触发事件**属性中设置即可。输入组件与非输入组件添加的动作触发事件不同，可分为两类，如下所示：
- **非输入组件**：
- **单击**：鼠标左键单击或移动端进行点击
- **双击**：鼠标左键双击
- **右键单击**：鼠标右键单击
- **移入**：鼠标移动到该组件时，就触发动作
- **移出**：鼠标光标从该组件上移开时，触发该动作
- **输入组件**：输入分组下的组件
- **内容变化**：输入框内容发生变化触发动作
- **输入**：输入内容时触发该动作。值得注意的是，**正在输入**的时候不是**内容变化**，输入完成并失去焦点后，才是内容变化
- **回车**：按回车时触发动作
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/set-param-value.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/set-param-value"
title: "仪表板交互-设置参数值"
---
---
order: 1
navTitle: 设置参数值
---
# 仪表板交互-设置参数值
**设置参数值**交互将当前点击的对象所关联的数据设置给指定的参数，参数收到数据变化后，所有引用了参数的可视化组件都将自动更新参数值。如点击饼图的销售大区，所有图表标题里的大区名称都会变成对应大区名称：
示例地址：[设置参数值](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用设置参数值{#start}
使用设置参数值交互，需要提前设置[全局参数](../data/param.md)。以点击饼图的销售大区，图表标题里的大区名称会变成对应大区名称为例，操作步骤如下：
1. **设置全局参数：** 点击左上角[参数](../data/param.md)，弹出全局参数对话框，新增参数，如名称为`dq`，描述为`大区`
2. **添加交互并编辑参数：**
1. 选中`各大区销售数量占比`饼图组件，添加**设置参数值**交互
2. 在交互中，点击**编辑参数**，进入参数对话框，**参数名称**选择`dq`，**参数值**写为`[区域编码.大区].标题`
3. **引用参数：** 双击打开条形图标题，在标题处引用该参数，如`${[dq]}`，同理将其他图形标题中也引入参数
## 编辑参数{#set-param}
在交互中点击**编辑参数**后，会弹出参数设置对话框，可选择参数名称、以及设置参数值，如下所示：
- **参数名称**：选择参数名称，该下拉列表中的参数需提前在[全局参数](../data/param.md)中添加
- **参数值**：设置参数值的内容，可动态写入参数值如模型字段、组件等
## 应用场景{#application}
### 通过KPI切换多页面板默认页{#kpi}
在仪表板的制作中，用户经常有这样的需求：点击仪表板中某个KPI，统计图的内容发生变化。
例如
- 点击【累计销售额】，右侧统计图刷新为销售额的相关信息
- 点击【累计销量】，右侧统计图刷新为销量的相关信息
实现步骤如下：
- 定义全局参数：在**设计器工具栏**>**参数**中定义一个变量，用于交互时传递参数使用
- 设置**全局变量**为`type`，**描述**为`销量和销售额的切换`
- 在KPI组件中设置交互：在**KPI组件**>**交互**中添加**设置参数值**，其他需要交互的组件进行类似操作
- 生效条件及触发事件默认
- 在**参数**中点击**编辑参数**，设置**参数名称**为`type`，**参数值**设置为该KPI数据对应的销售指标类型，如销售额，即为`1`
- 设置多页面板动态页：选中需要切换的多页面板，将**数据**>**默认页**设置为`动态页`，动态显示表达式为`IF([type]=1,'销售额','销量')`。这里的销售额和销量分别是指面板的名称，也就是当`type`值为`1`时，显示销售额面板，当`type`值为`2`时，显示销量面板
通过以上3个步骤即可实现点击KPI切换多页面板默认页。
示例地址：[完成率分析](https://demo.succbi.com/v5/bi/%E5%AE%8C%E6%88%90%E7%8E%87%E5%88%86%E6%9E%90)
::: tip
以上是使用动态显示多页面板的页面，来变相实现动态改变图形的指标展示，也可以使用[动态指标](../type/target.md)的方式，来动态控制图形的指标变化，大概思路如下：
1. 定义一个参数用来显示指标名称
2. 在图形的指标上写表达式，例如`case when`或者`if`条件，具体写法可以参考示例中柱形图的展示
示例地址：[指标看板](https://demo.succbi.com/v5/bi/%E6%8C%87%E6%A0%87%E7%9C%8B%E6%9D%BF)
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/set-component-property.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/set-component-property"
title: "仪表板交互-设置组件属性"
---
---
order: 2
navTitle: 设置组件属性
---
# 仪表板交互-设置组件属性
本文介绍仪表板通过设置组件属性交互中可以设置的所有组件的属性。通过设置组件属性，可以改变组件的状态，如地图的缩放级别、选项卡的当前选项等。
\[\[toc]]
## 通用属性
|属性|描述|适用范围|
|-|-|-|
|drillLevel|钻取级次|可执行下钻交互的组件|
|drillId|钻取节点id|可执行下钻交互的组件|
|drillCaption|钻取节点标题|可执行下钻交互的组件|
|drillIsLeaf|钻取节点是否是叶子节点|可执行下钻交互的组件|
|drillField|钻取节点的字段名称|可执行下钻交互的组件|
## GIS地图
|属性|描述|
|-|-|
|zoom|缩放系数|
|center|中心点。返回格式为一个\[纬度, 经度]的二维数组，如\[116.405285, 39.904989]|
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/invoke-component-method.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/invoke-component-method"
title: "仪表板交互-调用组件方法"
---
---
order: 3
navTitle: 调用组件方法
---
# 仪表板交互-调用组件方法
本文介绍仪表板通过调用组件方法交互中可以调用的所有组件的方法。通过调用组件方法，可以调用组件上的功能，如播放视频、最大化、导出数据等。
\[\[toc]]
## 通用方法
### **rollup()** - 上卷
**适用组件**：可执行下钻交互的组件，如柱形图，分组表等。
下钻的反向操作，返回数据下钻之前的层级。
### **exportExcel()** - 导出excel数据
**适用组件**：在数据标签中定义了数据字段的组件，如柱形图、分组表等。
导出excel格式的数据。第一行是字段名，第二行开始是数据。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/linkto.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/linkto"
title: "仪表板交互-打开链接"
---
---
order: 4
navTitle: 打开链接
---
# 仪表板交互-打开链接
打开链接和[下钻](./drill-down.md)的使用场景类似，打开链接是钻取到其他对象，支持系统内部对象及外部链接，可以以对话框框或页面的方式展示。如点击条形图，查看销售详情：
示例地址:[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用打开链接{#start}
1. **添加目标页面**：需提前新建好目标页面
2. **添加交互并设置属性**：
1. 在`各省份销售金额`条形图中添加**打开链接**交互
2. 在交互中，点击**编辑链接**属性，弹出编辑对话框，目标类型为**文件**，并在**链接到**属性中选择目标页面`各省销售详情`
3. 将**显示方式**设置为`当前容器`，同时将**面包屑路径**设置为`隐藏`
## 链接设置{#link}
**打开链接**交互的**链接**属性对话框中，可以设置目标对象的类型、路径、标题、传递参数等，具体可查看SuperPage中关于[链接部分的设置](../../../../app/superpage/design/action/linkto.md#link)。
除以上设置外，仪表板还可以设置是否**自动传递过滤条件**，仅目标类型为**文件**时有该选项，默认勾选，点击**查看条件**按钮可查看当前自动传递的过滤条件。
如点击条形图中的省份，钻取到目标页面中，能自动过滤当前省份的数据。这里目标页面分组表与条形图使用的是同一个模型，自动过滤生效的规则如下：
1. **点击组件和钻取的目标页面组件使用的是同一个模型时：** 所有过滤条件都会自动传递，包括页面中的[输入组件过滤](../../components/input/combobox.md#autofilter)、[过滤器](../data/data-filter/README.md)以及所点击的维度字段
2. **点击的组件和钻取的目标页面组件使用的不是同一个模型时：**
1. 维度自动过滤：两个模型表中关联同一个维表，且维表参与过滤，则会将过滤自动带入到目标页面，此外组件上如果有维度字段，也会将维度字段带入目标页面进行过滤
2. 字段自动过滤：两个模型表中有相同的[物理字段名](../../../../data-gov/model/README.md#model-field)，并且带有该字段的过滤，则会将过滤自动带入到目标页面，如输入组件以及[过滤器](../data/data-filter/README.md)中的过滤条件等
## 显示方式设置{#display}
打开链接支持对话框、新浏览器标签页面、替换当前浏览器页面以及当前容器四种显示方式，具体可查看文档[显示方式设置](../../../../app/superpage/design/action/linkto.md#how-to-show)。可在交互中**显示方式**属性中进行设置。
| 方式 | 描述 |
| :---------- | :---- |
| 对话框 | 在当前页面弹出一个对话框 |
| 新浏览器标签页面 | 打开一个新的浏览器标签页 |
| 替换当前浏览器页面 | 在浏览器当前页面打开目标页面 |
| 当前容器 | 当前页面展示在门户或其他页面容器中，新页面打开时也将显示在该容器内部 |
当显示方式选择对话框时，配置项底部会出现一个**显示标题**的勾选项，用于控制对话框标题的显示与否，只有取消勾选**显示标题**时，标题才会被隐藏；否则，将显示默认标题。对话框的默认标题为元数据的描述或名称（若打开的是url，默认标题则为url的域名）。
### 移动端的打开链接交互{#mobile}
移动端的打开链接交互与PC端基本一致，主要区别在于目标页面展示的效果不同，具体可查看文档[移动端的打开链接交互](../../../../app/superpage/design/action/linkto.md#mobile)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/drill-down.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/drill-down"
title: "仪表板交互-下钻"
---
---
order: 5
navTitle: 下钻
---
# 仪表板交互-下钻
下钻是按[维键层次](../../../../data-gov/model/data-hierarchy.md)下钻，是对数据的纵向剖析，并且可以继续钻取，直到钻取到维键的最末级层次，每次钻取都是在当前页面打开，下钻后可返回上一级。如以下销售详情表，可由**省**下钻到**市**，**市**下钻到**区县**：
示例地址:[分组表](https://demo.succbi.com/v5/bi/%E5%88%86%E7%BB%84%E8%A1%A8\(%E5%85%A8%E5%9B%BD%E9%94%80%E5%94%AE%E6%83%85%E5%86%B5%E8%A1%A8\))
## 使用下钻{#start}
使用下钻交互，必须先设置数据层次，以各省销售详情表按照省市县层层下钻为例，操作步骤如下：
1. **设置下钻字段的数据层次：** 需要提前设置`行政区划`的父子层次，可参考文档[数据级次](../../../../data-gov/model/data-hierarchy.md)
2. **添加交互并设置属性：**
1. 选中`各省销售详情`分组表，添加**下钻**交互即可
2. 可依据需求勾选`允许下钻末级节点`，则点击末级节点时能只保留自身节点的数据
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/switch-panelbook.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/switch-panelbook"
title: "仪表板交互-切换多页面板"
---
---
order: 6
navTitle: 切换多页面板
---
# 仪表板交互-切换多页面板
**切换多页面板**配合[标签页](../../components/input/tabbar.md)、[选择面板](../../components/input/selectpanel.md)、[下拉框](../../components/input/combobox.md)组件，可以实现[多页面板](../../components/layout/panelbook.md)中多个子页面之间的动态切换。如下可动态切换行政区划和产品类别：
示例地址：[完成率分析](https://demo.succbi.com/v5/bi/%E5%AE%8C%E6%88%90%E7%8E%87%E5%88%86%E6%9E%90)
## 使用切换多页面板{#start}
使用切换多页面板交互，需要在该页面中提前设置好[多页面板](../../components/layout/panelbook.md)组件内容，并通过**目标对象**属性选择需要切换的多页面板。以使用**标签页**组件为例，点击标签页选项切换多页面板中的多个子页面，具体步骤如下：
1. **添加组件：** 在页面中分别添加**多页面板**和**标签页**组件，并设置内容
2. **添加交互并设置属性：**
1. 选中**标签页**组件，添加**切换多页面板**交互
2. 在交互中，**目标对象**属性选择需要切换的`多页面板1`，目标面板为`事件源序号`，更多切换规则可查看[设置切换多页面板的规则](#rules)
## 设置切换多页面板的规则{#rules}
切换多页面板，提供了四种切换规则，可在**目标面板**属性中进行设置，具体规则内容可查看[设置切换多页面板的规则](../../../../app/superpage/design/action/switch-panelbook.md#rules)。
:::tip
多页面板配合下拉框组件，不使用切换多页面版交互也可以实现动态切换，可参考[多页面板-默认页](../../components/layout/panelbook.md##default)设置。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/maximize.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/maximize"
title: "仪表板交互-最大化"
---
---
order: 7
navTitle: 最大化
---
# 仪表板交互-最大化
使用**最大化**交互，可以将目标组件放大或全屏显示。如点击**放大**按钮，可将地图组件在浏览器窗口内全屏显示，按**ESC**或点击**右上角关闭按钮**即可退出全屏：
示例地址：[地图交互](https://demo.succbi.com/v5/bi/%E5%9C%B0%E5%9B%BE%E4%BA%A4%E4%BA%92)
## 使用最大化{#start}
**最大化**交互通常搭配[按钮](../../components/more/button.md)组件使用，以点击放大按钮，放大地图组件为例，具体步骤如下：
1. **添加组件**：添加`放大`按钮
2. **添加交互并设置属性**：选中`放大`按钮，添加**最大化**交互，目标组件选择`GIS地图1`即可
## 设置全屏属性{#fullscreen}
勾选**全屏**属性可以实现目标组件在**浏览器界面**全屏显示。如果不勾选，目标组件只在**浏览器窗口内**全屏显示，仍然会显示浏览器url地址栏。
全屏后的内容，可以**按ESC**或者点击右上角的**关闭按钮**退出全屏。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/switch-visible.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/switch-visible"
title: "仪表板交互-显示/隐藏组件"
---
---
order: 8
navTitle: 显示/隐藏组件
---
# 仪表板交互-显示/隐藏组件
**显示/隐藏组件**交互用于实现组件的动态显示与隐藏效果，与SuperPage的[显示/隐藏组件](../../../../app/superpage/design/action/show-component.md)交互效果类似。
## 使用显示组件{#show-component}
使用**显示组件**交互，可以将隐藏的组件显示。根据不同的[启用条件](./README.md#condition)，可以实现组件的动态显示。
## 切换显示和隐藏{#switch}
利用显示组件交互可以实现动态显示效果，需要在**显示组件**交互中勾选**切换显示和隐藏**属性，勾选后，无论组件的初始状态为显示或隐藏，每当[触发事件](./README.md#trigger)发生一次，就可动态切换一次状态。如下图所示：
**实现方式**
1. **添加组件：** 在页面中添加`显示/隐藏`按钮
2. **添加交互并设置属性：** 选中`显示/隐藏`按钮，添加**显示组件**交互，**目标组件**选择`各价格档次销售情况`面板，勾选**切换显示和隐藏**
## 使用隐藏组件{#hide-component}
**隐藏组件**交互的用法与**显示组件**交互一致，但作用相反，具体使用可查看[使用显示组件](#show-component)交互。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/filter-data.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/filter-data"
title: "仪表板交互-过滤数据"
---
---
order: 9
navTitle: 过滤数据
---
# 仪表板交互-过滤数据
**过滤数据**是按照组件中拖入的维度字段，对其影响范围内的所有组件进行数据过滤，可实现联动刷新图表数据效果。如点击饼图上的大区，页面所有组件会根据大区对数据进行过滤：
示例地址：[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用过滤数据{#start}
1. **设置过滤数据组件**：添加`各大区销售数量占比`饼图，并以`大区`区分颜色
2. **添加交互并设置属性**：
1. 选中`各大区销售数量占比`饼图，添加**过滤数据**交互
2. **影响范围**为`全部`，**作用数据源**为`当前数据源`即可
## 设置过滤数据范围{#set-filter-range}
在**影响范围**和**作用数据源**属性中可设置过滤数据的范围，具体设置如下：
- **影响范围**：设置过滤影响哪些组件，下拉框中会显示画布中所有的图表组件，默认为全部。也可以根据情况筛选过滤的组件，在下拉列表中选择即可。
- **作用数据源**：影响范围中勾选的组件需要依据**作用数据源**进行自动过滤，默认为当前数据源。下拉列表提供了如下两种选项：
- 当前数据源：将过滤条件作用于当前数据源，当前数据源有以下两种情况均可自动过滤：
- 目标组件中使用的模型表和添加过滤数据交互的载体组件使用的是**同一个模型表**
- 目标组件中使用的模型表和载体组件中的模型表**设置了关联关系**，关联关系设置可参考文档[关联关系](../../../../data-gov/model/model-relations.md#oper-steps)
- 关联数据源：将过滤条件作用于当前数据源和关联数据源，关联数据源即目标组件中的模型表和载体组件中的模型表不同，关联数据源有以下两种情况均可自动过滤：
- 目标组件的模型表中存在字段和载体组件中所使用的维度字段**关联了相同维表**，目标组件中是否使用该维度字段均可过滤，关联表设置可查看文档[设置关联表](../../../../data-gov/model/README.md#associated-table)
- 目标组件的模型表中存在维度[物理字段名](../../../../data-gov/model/README.md#model-field)和载体组件中所使用的**维度物理字段名相同**，目标组件中是否使用该维度字段均可过滤，如主表与明细表之间，存在相同的物理字段名即可自动过滤
:::tip 注释说明
- 目标组件：即过滤数据交互能影响的组件
- 载体组件：即添加过滤数据交互的组件
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/export-data.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/export-data"
title: "仪表板交互-导出数据"
---
---
order: 10
navTitle: 导出数据
---
# 仪表板交互-导出数据
**导出数据**交互可以将当前页面查询出的数据导出为Excel或csv数据文件，常与[按钮](../../components/more/button.md)搭配使用。如点击导出按钮，将企业主要人员信息导出为Excel文件：
示例地址：[导出当前查询页面](https://demo.succbi.com/v5/bi/%E5%AF%BC%E5%87%BA%E5%BD%93%E5%89%8D%E6%9F%A5%E8%AF%A2%E9%A1%B5%E9%9D%A2)
## 使用导出数据{#start}
使用**导出数据**交互，需要在该页面提前设置好查询数据的表格类组件，并通过**数据组件**属性选择需要导出的数据。以使用[明细表](../../components/table/columntable.md)、导出企业变更信息数据为例，具体操作步骤如下：
1. **添加组件**：在页面中添加`企业主要人员`明细表，并添加`导出`按钮
2. **添加交互并设置属性**：
1. 选中`导出`按钮，添加**导出数据**交互
2. 在交互中，**数据组件**选择`明细表1`，**文件名字段**设置为`自定义`，名称为`企业主要人员表`即可
:::tip
导出数据的组件仅支持**表格类**组件，如[明细表](../../components/table/columntable.md)和[分组表](../../components/table/grouped-table.md)。
:::
## 导出文件属性设置{#property}
在导出数据交互中，可以设置导出文件的**名称**、**格式**以及**导出数据量**。对于这些设置系统有如下两种导出方式：
1. 点击按钮直接以默认设置的属性导出文件
2. 点击按钮弹出导出文件属性设置对话框，在对话框中自定义属性导出文件
### 直接导出文件{#direct-export}
点击按钮直接导出文件，需要在导出数据交互中，设置**文件名字段**、**导出格式格式**以及**导出页**属性。具体设置可查看[设置导出文件默认属性](../../../../app/superpage/design/action/export-data.md#property)。
### 自定义属性导出文件{#custom-export}
在查看界面，用户通过弹出的导出数据对话框，可以自定义导出文件的名称、格式和数据量。需要勾选**弹出导出选项对话框**属性，并对应设置**允许选择导出页**与**允许选择导出格式**等属性即可。具体设置可查看[设置允许用户选择导出文件属性](../../../../app/superpage/design/action/export-data.md#custom)。
:::tip
使用弹出对话框自定义属性导出文件时，如果也设置了[直接导出文件](#direct-export)方式，则对话框中的属性默认值为[直接导出文件](#direct-export)方式中属性设置的值。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/returnto.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/returnto"
title: "仪表板交互-返回上页"
---
---
order: 11
navTitle: 返回上页
---
# 仪表板交互-返回上页
**返回上页**交互用于打开链接后，返回上一次打开的页面。如点击各省份销售金额条形图查看该省份下门店详情，再点击返回上页按钮，即可返回图形页面：
示例地址：[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用返回上页{#start}
使用**返回上页**交互，一般需要搭配[按钮](../../components/more/button.md)组件以及[打开链接](./linkto.md)交互使用。以打开链接返回上一次打开的页面为例，具体步骤如下：
1. **添加组件：** 在打开链接目标页面中添加`返回上页`按钮
2. **添加交互：** 选中`返回上页`按钮，添加**返回上页**交互即可
:::tip
只有使用**打开链接**交互打开目标页面后，在目标页面中点击**返回上页**，才能成功返回上一次页面；如果直接打开目标页面，则点击不生效。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/action/export-dash.md"
htmlUrl: "https://docs.succapp.com/v5/dash/action/export-dash"
title: "仪表板交互-导出仪表板"
---
---
order: 13
navTitle: 导出仪表板
---
# 仪表板交互-导出仪表板
**导出仪表板**交互可以将当前仪表板页面导出为图像、PPT以及PDF文件，可用于交流或演示，导出的PPT文件可二次修改。如点击导出按钮，将当前页面导出为矢量PPT文件，可对数据以及图形进行编辑：
示例地址：[图形交互](https://demo.succbi.com/v5/bi/%E5%9B%BE%E5%BD%A2%E4%BA%A4%E4%BA%92)
## 使用导出仪表板{#start}
使用导出仪表板交互，需要在页面中添加[按钮](../../components/more/button.md)组件，并在交互中设置对应属性即可。具体操作步骤如下：
1. **添加组件**：在页面中添加`导出`按钮
2. **添加交互并设置属性：**
1. 选中`导出`按钮，添加**导出仪表板**交互
2. 在交互中，勾选**弹出导出选项对话框**属性即可，更多属性设置见[导出文件属性设置](#property)
## 导出文件属性设置{#property}
在导出仪表板交互中，可以设置导出文件的**名称**和**格式**。对于这些设置系统有如下两种导出方式：
1. 点击按钮直接以默认设置的属性导出文件
2. 点击按钮弹出导出仪表板属性设置对话框，在对话框中设置属性后再导出文件
### 直接导出文件{#direct-export}
点击按钮直接导出文件，需要在导出仪表板交互中，设置**文件名字段**和**导出格式**属性。具体设置如下：
- **文件名**：导出的仪表板文件名称
- 默认：导出的文件名称与仪表板同名，默认设置
- 自定义：自定义导出文件名称，支持填写[表达式](../../../../exp/func/README.md)
- **导出格式**：支持**图像**、**PPT**和**PDF**三种格式，默认为图像
:::tip 更多说明
当**导出格式**设置为PPT时，在查看界面点击按钮导出，会弹出对话框，显示PPT的相关属性设置，具体可查看[自定义选择导出文件](#custom-export)。
:::
### 自定义选择导出文件{#custom-export}
在查看界面，用户通过弹出的导出仪表板对话框，可以自定义导出文件的名称和格式。需要在设计器的交互设置中勾选**弹出导出选项对话框**属性，并在**可选格式**属性中勾选对应格式即可，包含图像、PPT、PDF以及全部选项。
当选择导出文件为PPT时，会显示相关设置，如下所示：
- **幻灯片大小**：支持宽屏16:10、宽屏16:9、标准4:3以及可自定义宽度和高度，默认为宽屏16:10
- **导出原生统计图**：可对导出PPT中的统计图进行编辑，默认勾选
- **导出矢量地图**：可对导出的PPT中的地图进行编辑，默认勾选
:::tip 更多说明
使用弹出对话框自定义属性导出文件时，对话框中的属性内容为[直接导出文件方式](#direct-export)中属性设置的值。
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/mobile/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/mobile"
title: "移动端设计指南"
---
---
order: 7
navTitle: 移动
---
# 移动端设计指南
SuccBI支持在移动端展示仪表板：
|指标看板|高校师生情况|中国经济变化|
| --- | --- | --- |
||||
移动仪表板既可以基于移动模板新建，也可以在已有仪表板上增加移动端视图，有如下区别：
- **基于模板新建**：若当前仪表板仅需要在移动端进行展示，则可以在创建仪表板时选择**移动模板**来新建一张移动仪表板，具体介绍可参考[新建移动仪表板](#new)
- **在已有仪表板上增加移动布局**：若需要在多终端如PC或移动设备上访问同一张仪表板时，可以在已有的仪表板中新增**移动布局**，具体介绍可参考[添加移动布局](#add)
## 新建移动仪表板{#new}
在新建仪表板时，选择移动模板即可创建一个移动仪表板。当该页面的内容制作完成后，还可以将页面加入到[移动APP](../../../../app/mobile/README.md)内进行查看。
## 添加移动布局{#add}
SuccBI支持根据设备的不同自适应调整仪表板的展示效果，只需为仪表板添加不同的[布局](../layout/README.md)。当仪表板创建为**PC端**时，若为其添加**移动**布局，即可使该仪表板在移动端打开时展示为移动效果。添加移动布局的具体步骤如下：
1. 在[仪表板设计器](../../designer.md)的**数据源**区，切换到**布局**栏
2. 在**布局**栏中点击**预览设备**按钮
3. 在[仪表板设计器](../../designer.md)的**画布**区域的左上方，在**类型**中选择**手机竖屏**
1. 选择**类型**时，可根据需要选择其他样式的移动端布局，如：手机横屏、平板竖屏、平板横屏等
2. 更多布局设置可以查看文档[布局](../layout/README.md)
4. **布局**类型选择完成后，点击右侧的**添加**布局按钮，将布局添加至**数据源**区域的**布局栏**中
5. 在**布局栏**中选择已有布局，可以编辑查看不同布局下的效果
:::tip
移动布局下组件的使用方法不会发生变化，可以拖拽组件调整其顺序、位置及大小，并且各布局之间图形的摆放位置、大小等样式互不影响。值得注意的是，不同布局之间的**样式**虽然并不共用，但取数相同，若在任意一个布局中改变了组件的取数，另一布局下该组件的数据也随之产生变化。
:::
### PC端与移动端布局{#pc-mobile}
仪表板的移动端页面不是一个“全新”的仪表板，他与PC端页面存放在一个仪表板内部，用不同的**布局**加以区分，如仪表板默认为PC端布局，添加一个[移动布局](#add)后，在PC端的[门户页面](../../../../app/portal-page/README.md)中打开该页面，则仪表板展示为PC端效果，若在[移动APP](../../../../app/mobile/README.md)中打开该页面，则仪表板展示为移动端效果。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/design/preview/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/preview"
title: "预览"
---
---
order: 7
navTitle: 预览
---
# 预览
仪表板在制作过程中可以通过[预览](#preview)快速浏览目前制作的效果；可以通过[查看日志](#log)调试执行效率等。
## 预览{#preview}
点击仪表板设计器页面左上方的**预览**按钮，可以在编辑过程中预览目前制作的效果，上方提供预览功能设置。
- 导出PowerPoint：将当前仪表板预览的效果[导出为PowerPoint](../../browse.md#export)
- 二维码：仪表板[添加移动布局](../mobile/README.md#add)后，可以通过移动设备扫描二维码查看移动端效果，移动端视图配置可参考[移动端设计指南](../mobile/README.md)
- 预览数据：启用后可[限制查询的数据行数](../../designer.md)
- 关闭：退出预览并返回仪表板编辑页
:::tip 查看
预览界面的效果可能与实际有所偏差，最终效果以[查看](../../browse.md#check)界面为准
:::
## 查看日志{#log}
当需要了解仪表板页面运行性能进行[性能优化](../../../../perf/optimize.md)，或者希望[查看组件运行SQL](#sql)时，有两种方式可以查看日志：
- 在项目列表的**系统设置**>[技术日志](../../../../sys-settings/performance/console.md)中查看系统输出的日志信息
- 在仪表板的播放或查看页面查看日志
- [播放](../../browse.md#play)仪表板时，点击上方的功能选项中的**查看日志**按钮
- [查看](../../browse.md#check)仪表板时，点击右上角**更多**按钮，在显示的菜单中选择**查看日志**
日志列表中展示了详细的执行信息，从打开仪表板到最终的结果展示，中间的执行过程按照执行的**开始时间**进行排序展示。
- 执行的基本信息：最细粒度是每个组件的执行状态，可以通过**瀑布图**查看各进程执行时间的演变过程、通过**开始时间**与**耗时**查询执行时间信息
- 查看组件运行详细信息：点击组件名称+查询构成的**描述**，可以查看组件的**查询信息**与**查询结果**，在**查询结果**中可以[查看组件运行SQL](#sql)
### 查看组件运行SQL{#sql}
日志列表中点击由组件名称+查询构成的**描述**，显示对应组件的**查询信息**与**查询结果**：
- 查询信息：数据查询请求的请求体信息
- 查询结果：响应体信息，可以查看对应组件运行的SQL语句
:::tip 显示执行SQL
在**项目设置**>**安全**>**安全设置**>**安全等保**中勾选[显示执行SQL](../../../../sys-settings/security/securityconf.md#display-sql)，将在**查询结果**中输出SQL、查询的Query等信息
:::
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/manage-themes/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/themes"
title: "README"
---
---
order: 6
navTitle: 仪表板主题
indexTitle: 主题管理
---
# 仪表板主题管理
使用主题可以制作美观仪表板，切换不同主题可以实现同一个仪表板展示不同的效果，满足在多个场景下的应用。例如：浅色更适合日常的工作，不那么容易产生视觉疲劳，深色则更适合演示汇报，更加炫酷能够吸引注意力。
仪表板主题分项目主题和系统主题：
- 项目主题：仅用于当前项目下的仪表板文件，相关文件是存储在`当前项目-资源-settings-themes-dash`下
- 系统主题：可用于当前系统中所有项目下的仪表板文件，相关文件是存储在`系统数据-资源-settings-themes-dash`下
## 系统自带主题模板{#system-theme}
系统自带多个美观的主题，这些主题都是经过设计师精心设计的，直接选择即可复用样式，用户可以借助主题风格制作出美观的仪表板。且主题之间都是可以相互切换的，点击仪表板编辑界面左上角的`文件-切换主题`，即可弹出**选取主题**的对话框，可在此处选取切换不同的主题。
不同主题下组件的风格是通过风格名称来对应切换的，例如：
- **柱形图**在**绿色主题**下应用的是`图表风格3`，则切换主题后，**组合图**则是应用的**海洋王国**下的`图表风格3`
- 如果**海洋王国**中的组合图没有命名为`图表风格3`的风格，那么他会自动选用组合图风格列表中的第一个
示例地址：[切换主题风格](https://demo.succbi.com/v5/bi/%E6%80%BB%E4%BD%93%E7%BB%8F%E8%90%A5%E6%83%85%E5%86%B5)
:::tip
为什么我们的可视化页面可以轻松的做到无缝切换多个主题都那么好看呢？感兴趣的话一起来[组件风格规范](../components/chart/README.md)看看吧，等你哟~
:::
## 新增主题{#custom-theme}
如需自行新增一个主题，按照如下步骤操作即可：
1. **增加新主题**：有两种方式
- 通过复制已有主题的方式新增一个主题，具体操作见[管理主题-复制主题](#copy)
- 在`项目-资源-settings-themes-dash`下导入所需的主题文件，点击[此处](https://www.jianguoyun.com/p/DboY7t0Qz--gChickawE)下载**空的主题文件**
2. **重命名**：新增了一个主题后，可以再次修改主题名称。具体操作见[管理主题-重命名](#rename-delete)
3. **修改主题色板/风格**：自定义色板颜色及组件风格，具体操作见[管理主题-修改主题](#modify-theme)
4. **更新主题缩略图**：新增了自定义的主题后还需要有一张缩略图来示意主题的色调，更新缩略图的具体操作见[管理主题-更新缩略图](#thumbnail)
:::tip
空的主题文件是指，只包含色板颜色、及组件默认风格，不带任何图片、图标的主题文件。
:::
## 管理主题{#manage-theme}
用户可以对已有的主题进行[复制](#copy)、[修改主题色板及组件风格](#modify-theme)、[重命名和删除](#rename-delete)和[更新缩略图的操作](#thumbnail)。
### 复制主题{#copy}
复制主题有两个入口，分别是在仪表板的编辑界面和资源目录下：
- **入口一**：直接在仪表板编辑界面的**选取主题**对话框中选中一个主题，右键后选择功能菜单中的**复制主题**即可复制出一个新的主题
- **入口二**：在`项目-资源-settings-themes-dash`下选中某个主题文件后，右键复制到当前的dash目录下即可
选取主题的对话框中|资源目录下
-|-|
|
### 修改主题{#modify-theme}
主题文件目录下一般包含如下内容：
- **icons**：存储主题相关的图标
- **images**：存储主题相关的图片
- **theme.json**：以json的形式记录主题色板、组件风格等内容
- **thumbnail**：即主题缩略图
修改主题包含两部分内容，分别是修改主题色板和修改组件风格：
1. 修改主题色板：如需修改主题的基础色调，即主题色板，需修改主题的`theme.json`文件，具体操作见[仪表板主题制作](./制作自己的主题.md#modify-style)
2. 修改组件风格：如需调整组件风格，可以直接在界面上对组件风格进行**更新**或**新增**，具体操作见[风格](../design/type/basic/style.md)
:::tip
同一时间建议只能有一个人修改主题风格，多人同时修改时会相互覆盖，可能导致部分内容丢失，所以建议指定一人维护。
:::
### 重命名和删除{#rename-delete}
重命名和删除都有两个入口，分别是在仪表板的编辑界面和资源目录下：
- **入口一**：仪表板编辑界面，点击页面左上角的`文件-切换主题`，弹出**选取主题**对话框后，选择其中一个主题右键**重命名**或**删除**即可
- **入口二**：在`主题所在项目-资源-settings-themes-dash`下选中某个主题文件后，右键**重命名**或**删除**即可
选取主题的对话框中|资源目录下
-|-|
|
### 更新缩略图{#thumbnail}
主题缩略图是用来示意当前主题的基础色调，用户可根据缩略图初步对主题进行筛选使用。此处以更新**系统主题**缩略图为例演示具体操作，更新后的缩略图效果仍是在选取主题的对话框中查看。
1. **在本地准备好缩略图文件**：将设计师处理好的缩略图文件（大小要求为`416*234`、命名要求为`thumbnail`），缩略图的格式可以是`jpg`也可以是`png`
2. **进入资源目录**：系统数据-资源-settings-themes-dash
3. **删除旧文件**：删除相应主题文件夹下的`thumbnail.png`文件
4. **导入新文件**：选中当前主题文件目录，右键导入本地准备好的缩略图文件即可
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/manage-themes/系统自带的主题.md"
htmlUrl: "https://docs.succapp.com/v5/dash/chart-style"
title: "系统自带的主题"
---
---
order: 2
navTitle: 系统自带的主题
---
# 系统自带的主题
产品自带多个美观的主题，直接选择即可复用它的样式。主题文件中包含了[色板](./制作自己的主题.md#themecolor1)、[色阶](./制作自己的主题.md#color-scale)、[组件风格](../design/type/basic/style.md)、[条件样式](../design/type/condition-style.md#condition-style)等内容。组件风格中则是存储了组件的字体、颜色、填充、边距、阴影等样式属性。每个组件都有自己的风格列表，系统自带的主题中给每个组件都预设了一些风格，每个风格都可以让组件呈现不同的效果。
下面将以几个比较有代表性的组件为例来介绍系统组件风格的规范以及组件风格搭配使用的小技巧。通过本篇文档的学习，您可以了解到系统自带的主题里组件都有哪些风格，又是如何通过这些风格去美化仪表板的。
## 标题风格{#title-style}
虽然标题风格有单独的风格列表，但标题风格是包含在组件风格中的。
所有的图形、表格、布局组件，以及下拉框、选择面板、日期等输入组件，还有文本、图片、视频等更多组件均有标题风格，且输入组件的标题风格和其他组件的标题风格是不共用的，具体共用情况见[组件风格列表共用情况](./制作自己的主题.md#standard)。
### 输入组件标题风格{#input-style}
输入组件的标题一般不会有太复杂的设置，系统自带的主题中，参数组件的标题风格列表中均只预存了一个`默认输入标题风格`，对文字和内边距做了简单的设置，但基本能够满足各个场景下的应用。
输入组件的标题风格中可包含**字体**、**图标**、**填充**、**边框**、**内边距**、**文字阴影**这些样式属性。
### 非输入组件标题风格{#other-style}
除输入组件外，其他所有组件的标题都是共用同一个风格列表的，每个主题下均预设了6个风格，风格名称按序号递增，即默认标题风格、标题风格1、标题风格2...... 非输入组件的标题风格中可包含**字体**、**图标**、**填充**、**边框**、**内边距**、**文字阴影**这些样式属性。
每个标题风格均用于搭配不同的图形风格，以风格名称为准与组件风格一一对应，例如：`图表风格1`与`标题风格1`搭配使用、`网格线风格`与`标题风格4`搭配使用、`无背景风格`与`标题风格5`搭配使用，具体效果见[图表风格](#chart-style)。
## 图表风格{#chart-style}
柱形图、条形图、面积图、组合图等图形共用同一个图表风格列表，详见[组件风格列表共用情况](./制作自己的主题.md#standard)，系统自带的每个主题的图表风格均有6种，依次为默认图表风格、图表风格1、图表风格2、图表风格3、网格线风格、无背景风格。图表风格中存储除组件的**动画**、图例的**布局**以外的所有样式属性，每个风格都有其特点。
前五组风格是通过不同的颜色、背景等样式设置展示不同的组件效果，可以根据自己的喜好选择使用：
- **默认图表风格**：图表背景为颜色填充且颜色取自色板，对应的标题风格为`默认标题风格`，系列的颜色取自色板1
- **图表风格1~3**：对应的标题风格依次为`标题风格1`、`标题风格2`、`标题风格3`，系列的颜色依次取自色板6、色板9、色板9。这三组风格均是通过不同的背景填充呈现不同的图表效果
- **网格线风格**：显示了X轴和Y轴的`分割线`和`标签`，对应的标题风格为`标题风格4`，系列的颜色取自色板1
最后一个风格，即`无背景风格`，顾名思义，组件的背景为无填充，对应的标题风格为`标题风格5`，系列的颜色取自色板6。主要有两个常见的使用场景：
- 一是和带背景的容器配套使用
- 二是需要突出画布背景，弱化组件边界时使用
下面以柱形图为例来看下各个图表风格的效果：
|海洋王国|浅蓝主题|绿色主题|印刷杂志|
-|-|-|-|
||||
|蓝色主题|深蓝主题|紫色浪潮|黑金主题|
-|-|-|-|
||||
## 容器风格{#container-style}
系统自带的每个主题中都预设了6个容器风格，依次是默认容器风格、容器风格1、容器风格2、容器风格3、容器风格4、无背景风格。容器风格中可包含**填充**、**边框**、**圆角**、**内边距**、**阴影**这些样式属性。各个容器风格主要是设置了不同的背景图片填充，它与图表风格是一一对应的，例如：默认图表风格与默认容器风格的背景设置是相同的，标题样式也是相同的。
下面以`蓝色主题`为例看下图表风格和容器风格的对应关系：
|容器风格|图表风格|
-|-|
||
之所以按此规律预设容器的风格，是为了能够跟其他图表配套使用，如下大屏中的环形占比图和仪表盘是两个相关的指标，需要作为一个整体，这时就需要用到容器。为了保证与其他图表的风格样式保持一致，那么容器也需要使用相同的边框背景，这时相同的名称规律可以让用户更快的找到需要用到的风格。
[示例地址](https://demo.succbi.com/v5/bi/%E8%B6%85%E5%B8%82%E9%9B%B6%E5%94%AE%E5%A4%A7%E5%B1%8F)
## 表格风格{#table-style}
表格分为明细表和分组表两种，它们的风格是分开存储的。
### 明细表{#table1-style}
系统自带的每个主题中都预设了3个明细表风格，风格名称依次为默认明细表风格、明细表风格1、明细表风格2。明细表风格存储除明细表的布局，表格下的**选项**、**布局**、**冻结**，**标题行**的**布局**，**列**的**填充**外所有的样式属性。每个明细表风格都有其特点：
- **默认明细表风格**：有网格线，表格外框与网格线透明度为50%，隔行换色的颜色透明度为8%（色板第四个颜色）
- **明细表风格1**：无网格线，隔行换色的颜色透明度为8%（色板第五个颜色）
- **明细表风格2**：背景为图片填充
|印刷主题|深蓝主题|
-|-|
||
|紫色浪潮|黑金主题|
-|-|
||
### 分组表{#table2-style}
系统自带的每个主题中都预设了3个分组表风格，风格名称依次为默认表格风格、表格风格1、表格风格2。分组表和明细表虽然没有共用同一个风格列表，但所存储的风格样式是完全一样的，具体见[明细表](#table1-style)。
## 指标类风格{#index-style}
系统内置了丰富的指标类组件，且风格基本都是分开存储的，但大体规则跟上述组件类似，以下仅以KPI为例来介绍指标组件风格。KPI是我们使用频率最高的指标类组件，它有自己单独的风格列表，不与其他组件共用。系统自带的每个主题中都预设了7个KPI风格，依次是默认指标风格、指标风格1、指标风格2、序号依次递增至指标风格6。指标风格中存储除KPI的**布局**、**图标**以外的所有样式属性。每个指标风格都有其特点：
- **默认指标风格**：背景为无填充，指标字体颜色取自色板的第二个颜色
- **指标风格1~6**：这六组风格均是通过不同的背景、字体、颜色使其展示不同的效果
默认指标风格是最常使用的风格，之所以把默认风格设置为无背景的，是因为KPI大多数情况下是和其他组件组合使用的。如下示例：
|示例1|示例2|
-|-|
||
## 文本风格{#text-style}
系统自带的每个主题中文本都预设了**正文**、**大标题**、**小标题**、**说明**这四个文本风格，个别主题会有两个大标题风格。文本风格中可包含除**布局**以外的所有样式属性。每个风格的使用场景都可通过标题看出来，根据场景选用即可。
- **正文**：文本组件的默认风格即为正文，用于一般性的文字描述
- **大标题**：用于制作整个仪表板的大标题
- **小标题**：用于制作某个章节的小标题
- **说明**：用于说明性文字
## 不同主题下组件风格对应规则{#rule}
组件风格对应规则：
- 切换主题时按照风格名称对应切换，如**蓝色主题**下柱形图选用的`图表风格2`，则切换到**黑金主题**时也会对应使用`图表风格2`
- 如果找不到则使用默认风格，如蓝色主题下柱形图选用的`自定义风格`，则切换到没有该风格的**黑金主题**时会使用`默认图表风格`
在[主题管理](./README.md)中介绍到我们可以通过切换不同的主题实现同一个仪表板展示不同的效果，且不同主题下的效果都较为美观，之所以能达到这样的效果，就是因为上述组件风格的灵活应用。
通过上述的介绍也不难发现我们的风格的名称都是有一定的规范的，所有组件的第一个风格都是`默认XX风格`，然后是`XX风格1`、`XX风格2`、`无背景风格`之类的，且每个主题下的风格名称都是保持一致的。这也就保证了在切换主题的时候组件能够匹配到与当前主题下的风格对应的另一个主题的风格。
## 共用风格列表的影响{#public-style}
组件风格列表共用情况详见[仪表板主题制作-相关规范](./制作自己的主题.md#standard)，当多个组件共用同一个风格列表时，如果他们有相同的样式属性，调整其中一个组件的风格时是会影响其他组件的。例如，柱形图、条形图、组合图都是共用的图表风格，如果修改了柱形图的内边距并更新了风格，那么条形图和组合图使用该风格时内边距也会受到影响，如果调整了条形图的背景，并更新风格，那么柱形图和组合图使用该风格时背景也会受到影响。
:::tip
具体哪些属性会相互影响需根据组件而定，此处不做详细说明，但一般来说，会相互影响的都是组件整体的样式属性，例如组件的边框、圆角、内边距、阴影等。
:::
## 系统主题自带的图片库{#picture-library}
系统主题里除了组件风格中存储的图片之外，还有很多其他可用的主题图片，都是设计师设计好之后预存进主题中的。下面看看如何在仪表板中使用图片库中的图片资源：
操作步骤：
1. 在调整组件**样式-填充**时，选择`图片填充`
2. 图片来源选择`静态图片`（具体介绍见[图片来源](../../../app/superpage/components/common/image.md#source)
3. 单击选取，切换至`主题图片`
4. 根据需求选用之后，设置图片的**填充方式**（具体介绍见[填充方式](../../../app/superpage/components/common/image.md#fill)
## 使用主题风格优化页面{#use-style}
可视化界面的优化有两个重点，一是布局，二是样式。页面的布局处理好之后，整个美化的工作就完成了一半，然后再使用系统自带的风格来调整样式，美化也就完成了剩下的一半。以下就从这两个方面来学习如何去美化一张仪表板。
### 布局{#layout}
布局不仅仅是简单的位置摆放，还要考虑到各个指标之间的业务联系、哪些内容是比较重要的、哪些内容是次要的，了解以上这些相关的问题之后才可以开始布局的工作。常用的布局包括`左中右`、`左右`、`内外`、`上下`这几种，或者是其中两种混合使用，如下几个示例：
|示例1|示例2|示例3|示例4
-|-|-|-|
|||
- **左中右**：最为常用，重要内容放中间，如总体指标、地图等，次要内容放左右两侧，如示例1
- **左右**：重要内容放左侧，次要内容放右侧，如示例2
- **内外**：重要内容放页面正中央，次要内容在周边环绕，如示例3
- **上下**：重要内容放上侧，次要内容放下侧，如示例4
### 样式{#style}
布局调整完成后，即可进行样式的设置，系统给每个组件都提供了丰富的样式属性，但如果没有UI设计师的帮助，用户自己去制作一张美观的仪表板是非常困难且效率很低的。基于这个场景，使用产品自带的主题风格就能够解决以上问题，产品自带的风格都是设计师提前设计好之后存储在主题中的，用户直接选择就可以复用样式。大多数情况下，用户可以直接根据风格名称进行风格的配套使用，例如标题风格1、图标风格1、容器风格1搭配使用，当然也可以根据自己的需求选择不同的风格搭配使用。
### 应用{#application}
一起来看下如何灵活运用布局和主题风格来美化如下图所示的仪表板吧！在调整过程中也是需要不断尝试的，没办法一蹴而就哦，下述步骤仅作为操作指引。
|优化前|优化后|
-|-|
||
操作步骤：
1. **第一步：分析业务**
- 整个页面中最重要的内容是通过地图展示的各个省份的销量分布情况，其次是销量和销售额两个指标，再次是饼图、条形图等其他组件展示的业务
2. **第二步：调整布局**
- 使用常规的左中右的布局，中间是地图和两个指标，左右两边按需分布饼图、条形图、柱形图等其他组件，考虑添加一个大标题
3. **第三步：选择合适的主题**
- 按需选择即可，此处选择**深蓝主题**
4. **第四步：使用主题风格**
- 选择系统主题自带的风格进行样式优化
5. **第五步：细节调整**
- 调整颜色、边距、标签、提示信息等细节
!!! bilibili BV1dG4y1t7rX 7 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/manage-themes/制作自己的主题.md"
htmlUrl: "https://docs.succapp.com/v5/dash/new-theme"
title: "仪表板主题制作"
---
---
order: 3
navTitle: 制作自己的主题
---
# 仪表板主题制作
以创建BLUE-蓝色测试主题为例，仪表板主题，需要在可视化界面上按照下述介绍进行操作。
## 检查主题规范文件{#inspect}
设计师提供的主题规范，需要确认包含如下内容：
1. 主题色板10个颜色
2. 主题渐变10个颜色
3. 另外6个指定的主题颜色
4. 5组主题风格（不限于5组）
5. 4组色阶（不限于4组）
## 导入空主题并做处理{#import}
1. 在“系统数据”项目里，在【资源】-【settings】-【themes】-【dash】目录下导入空的主题文件，点击[此处](https://www.jianguoyun.com/p/DboY7t0Qz--gChickawE)下载
2. 修改主题名称为“red”，描述为“红色主题”。注意这里的**主题名称**只能用英文
## 修改json{#modify}
需要进入主题的json文件中，修改对应位置颜色的十六进制值，相关修改规则如下
### 主题色板10个颜色（前3个）{#themecolor1}
是主题下的控件背景、文字颜色和画布背景的默认颜色配置，在json文件中通过快捷键“CTRL+F”搜索*defaultProperties*找到对应的位置，修改其中bgcolor1、fontcolor和bgcolor2这三个属性对应的色值
```json
"defaultProperties": {
"lineColor": "#D5D5D5",
"panelBgColor": "#FFFFFF",
"panelFontColor": "#000000",
"highlightBgColor": "#419CFF",
"highlightFontColor": "#FFFFFF",
"fontColor2": "#5C6E80",
"bgColor1": "#FFFFFF",
"fontColor": "#324150",
"bgColor2": "#F5F5F5",
"colorTheme": "oceanKingdom"
}
```
### 主题色板10个颜色（后7个）{#themecolor2}
该主题的主色调，在json文件中通过快捷键“CTRL+F”搜索*paletteColors*找到对应的位置，根据主题规范替换7个颜色的色值即可
```json
"paletteColors": ["#4194FF", "#27C6DA", "#7460EE", "#75F0FF", "#FC6D87", "#FF9480", "#7DDA9B"]
```
### 主题渐变10个颜色{#gradient}
主题色板中包含的10个渐变色，可通过搜索*gradientColors* 找到对应的json，其中color后面的0和1分别代表颜色的位置，可在0-1中间取值
```json
"gradientColors": [{
"type": "linearGradients",
"deg": 180,
"value": [
[{"color": "#FF9695"}, 0],
[{"color": "#FF3F40"}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
[{"color": "#FFBEDC"}, 0],
[{"color": "#EA3D90"}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
[{"color": "#FFE041"}, 0],
[{"color": "#FF7200"}, 1]
]
}
......
```
### 另外6个指定的主题颜色{#specify-color}
也是主题下的默认颜色配置，同样是在*defaultProperties*下，从lineColor到fontColor2这6个色值
```json
"defaultProperties": {
"lineColor": "#D5D5D5",
"panelBgColor": "#FFFFFF",
"panelFontColor": "#000000",
"highlightBgColor": "#419CFF",
"highlightFontColor": "#FFFFFF",
"fontColor2": "#5C6E80",
"bgColor1": "#FFFFFF",
"fontColor": "#324150",
"bgColor2": "#F5F5F5",
"colorTheme": "oceanKingdom"
}
```
### 5组主题风格{#theme-style}
仪表板中可用于快速更换统计图颜色的几组色板，不限于5组，可根据实际需求增减，可通过搜索*marks* 快速定位对应json的位置；这里的色板分3种，纯色色板、渐变色板、带透明度的渐变色板，分别对应如下代码中的色板1、色板2、色板3；其中opacity就是对颜色透明度的设置，可取0-100之间的值
:::tip
此处应注意，caption需命名为色板1、色板2、色板3、色板4...... id为default1、default2、default3、default4......
:::
```json
"marks": {
"palette": {
"defaultPalette": "default",
"items": [{
"id": "default1",
"caption": "色板1",
"paletteData": ["#27C6DA", "#FF9480", "#7DDA9B", "#4194FF", "#75F0FF","#7460EE"]
}, {
"id": "default2",
"caption": "色板2",
"paletteData": [{
"type": "linearGradients",
"deg": 180,
"value": [
["#88FFF0", 0],
["#0D967D", 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#7DC2E9", 0],
["#397AE2", 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#ADE4FF", 0],
["#44ACF8", 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#B5C9F3", 0],
["#546DEB", 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#ACF1E7", 0],
["#2AD5B5", 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#FBD245", 0],
["#F5A621", 1]
]
}]
}, {
"id": "default3",
"caption": "色板3",
"paletteData": [{
"type": "linearGradients",
"deg": 180,
"value": [
["#7DC2E9", 0],
[{
"color": "#478FCF",
"opacity": 0
}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#73DFCB", 0],
[{
"color": "#73DFCB",
"opacity": 0
}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#ADE4FF", 0],
[{
"color": "#75C5FF",
"opacity": 0
}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#B5C9F3", 0],
[{
"color": "#7E99E4",
"opacity": 0
}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#FBBABB", 0],
[{
"color": "#F58485",
"opacity": 0
}, 1]
]
}, {
"type": "linearGradients",
"deg": 180,
"value": [
["#FBD245", 0],
[{
"color": "#F5A621",
"opacity": 0
}, 1]
]
}]
}
}]
}]
```
### 4组色阶{#color-scale}
需要修改的色值可通过搜索*gradation* 来定位，然后根据主题规范替换色值即可
:::tip
此处应注意，caption需命名为渐变1、渐变2、渐变3、渐变4...... id为gradation1、gradation2、gradation3、gradation4......
:::
```json
"items": [{
"id": "gradation1",
"caption": "渐变1",
"minPointColor": "#B0E7FF",
"maxPointColor": "#4194FF",
"opacity": 100
}, {
"id": "gradation2",
"caption": "渐变2",
"minPointColor": "#C0F8FF",
"maxPointColor": "#27C6DA",
"opacity": 100
}, {
"id": "gradation3",
"caption": "渐变3",
"minPointColor": "#D3DAFF",
"maxPointColor": "#7460EE",
"opacity": 100
}, {
"id": "gradation4",
"caption": "渐变4",
"minPointColor": "#FFCFC6",
"maxPointColor": "#FF9480",
"opacity": 100,
"reverse": false
}, {
"id": "gradation5",
"caption": "渐变5",
"minPointColor": "#EBCAFF",
"maxPointColor": "#C76FFF",
"opacity": 100
}
```
## 增加/修改主题中组件风格{#new-style}
### 根据仪表板设计规范增加/修改组件风格{#modify-style}
1. 主题内，同类组件的风格需要保持一致，例如面板、多页面板、浮动面板，第一个风格都是颜色填充，标题的样式也都一致
2. 仪表板规范如下图
1. 具体操作见[仪表板主题制作入门视频](../../../../videos/README.md)
### 相关规范{#standard}
1. 上传图片的相关规范
- 确保上传的每张图片的格式都是`png`，且图片大小不超过200k
- 该主题的图片，**应上传至“主题图片”中**，上传到该目录下的图片，其他仪表板只有在使用该主题时，才可以使用
- 主题风格中需要用到的图片，或者多个仪表板都需要用到的图片上传到“主题图片”中，其它的上传到“对象内”
- 当需要替换图片或者去掉多余的图片时，需要在界面上做删除操作，而不是在vscode中，且需要检查对应的meta文件中的内容是否正确
2. 图片名称的命名规则（如下是图片类型的命名前缀，同一类型的有多张图片，可在后面依次加上序号）
背景图片类型 | 图片命名 | 规格说明
-|-|-|
画布背景 | bg\_canvas |
面板背景 | bg\_panel |
图表背景 | bg\_chart |
标题背景 | bg\_title |
KPI背景 | bg\_kpi |
仪表盘背景 | bg\_guage |
表格背景 | bg\_table |
里程表背景 | bg\_odometer |
地图容器 | bg\_canvas\_map |
背景图层 | bg\_shape\_map |
区块图层 | bg\_tile\_map |
提示信息背景图片 | bg\_point |
svg图片 | svg |
主题缩略图 | thumbnail | W: 316px ，H: 196px
图标 | icon |
其他 | picture | 小于200k
示例：有两张不同的图表背景图片，则分别命名为bg\_chart1,bg\_chart2
3. 组件风格命名规范
- 若是系统主题，则第一个是“默认xx风格”，接着是xx风格1、xx风格2...使用系统默认风格名称
- 若是项目主题，则根据每个风格的特点命名即可
4. 风格列表共用情况
图表类型 | 共用风格
-|-|
面板 | 面板风格
多页面板 | 多页面板风格
浮动面板 | 浮动面板风格
明细表 | 明细表风格
分组表 | 分组表风格
条形(柱形图、条形图、组合图、象形柱形图、象形条形图、双向条形图、条形占比图)| 图表风格
折线(折线图、面积图、雷达图、时间轴) | 图表风格
散点图、饼图、矩阵树图、环形占比图、水位图、步行图、词云图 | 图表风格
仪表盘 | 仪表盘风格
KPI | KPI风格
里程表 | 里程表风格
数据条 | 数据条风格
图标条 | 图标条风格
地图 | 根据每个图层的名称命名，例如：地图容器-容器风格、区块图层-区块风格
下拉框、输入框、日期、快速搜索 | 输入风格
选择面板 | 选择面板风格
标签页 | 标签页风格
线条 | 线条风格
文本 | 文本风格
图片 | 图片风格
图标 | 图标风格
视频、视频组 | 视频风格
IFrame | IFrame风格
按钮 | 按钮风格
轮播图 | 轮播图风格
参数控件的标题 | 输入标题风格
图表控件的标题 | 标题风格
## SuperPage图片命名规范{#picture}
背景图片类型 | 图片命名 | 规格说明
-|-|-|
画布背景 | bg\_canvas |
面板背景 | bg\_panel |
文本背景 | bg\_text |
对话框背景 | bg\_dialog |
svg图片 | svg |
主题缩略图 | thumbnail | W: 316px ，H: 196px
图标 | icon |
其他 | picture |
- 以上图片大小均需小于200k
- 同一类型的有多张图片，可在后面依次加上序号，如bg\_text1、bg\_text2...
## 测试主题{#test-theme}
1. 测试时可新建一个仪表板切换到需要测试的主题风格，将所有的图表拖拽出来，以查看它的默认风格样式是否美观
2. 测试时可进入到其他已经做好的仪表板中，将风格切换至对应的需要测试的主题，确保主题适用于所有的仪表板
3. 测试主题时，可使用服饰行业的Demo进行测试，确保几个页面在切主题之后都有比较美观的效果
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/manage-themes/图片&图标类别与标签.md"
htmlUrl: "https://docs.succapp.com/v5/dash/picture-rule"
title: "类别与标签"
---
---
order: 4
navTitle: 图片&图标类别与标签
---
# 类别与标签
仪表板内图片以及图标可通过类别和标签进行管理，在给组件设置图片填充时，系统会自动根据组件属性、图片标签等信息进行智能推荐。
## 类别{#category}
**类别**可以用来统一管理图片和图标，而且每个图片以及图标有且只有一个**类别**。
### 图片类别{#picture-category}
图片目前已有的**类别**如下：
| 类别 | 适用范围 |
| :--------: | :-------- |
| 背景 | 组件背景类图片，此分类下一般为画布背景、组件背景以及单元格背景类的图片。 |
| 占位 | 此分类下一般为缺省类的占位图片，如异常信息提示图片。 |
| 插图 | 插图类图片，一般为美化类的图片，起到美化页面的作用。 |
| 装饰 | 组件装饰类图片，用于美化各个组件也可以同其他类图片叠加起到美化作用。 |
| 纹理 | 纹理类图片一般用于容器的背景填充。 |
| 图标 | 图标类图片，一般用于地图散点背景或者其他信息类图标。 |
| 其他 | 其他无明显类别的图片。 |
### 图标类别{#icon-category}
图标目前已有的**类别**如下：
| 类别 | 适用范围 |
| :--------: | :-------- |
| 图表 | 图标类图标，可用于各种图表组件。 |
| 功能 | 功能类图标，包括功能操作，交互动作等图标。 |
| 资源 | 资源类图标，包括各行业、各类目的图标，如人物、生物、交通工具等图标。 |
| 标记 | 标记类图标，用于各种场景、各种形式的标记图标，如箭头、形状、GIS等图标。 |
| 其他 | 其他无明显类别的图标。 |
::: tip
**类别**是系统自带的属性，用户无法自行添加或者修改！
:::
## 标签{#label}
图片以及图标可设置描述更为精准的**标签**来区分各个图片或图标的作用，用户也可以自行添加新的标签进行使用。每个图片或图标均可设置多个标签，但是多个标签的前后顺序是需要按照重要程度进行设置。排在第一位的标签，为主标签。**在图片中，系统会根据图片的主标签来进行推荐**。
### 图片标签{#picture-label}
图片目前已有的**标签**如下：
| 标签 | 适用范围 | 标签 | 适用范围 |
| :-------- | :-------- | :-------- | :-------- |
| 画布背景 | 仪表板画布背景图片，默认充满容器填充。 | 单元格背景 | 单元格背景图片，默认切片填充。 |
| 边框背景 | 边框类背景。适用于巨大多数组件的背景，默认切片填充。 | 数字背景 | 里程表组件中指标的背景图片，默认适合于容器填充。 |
| 纹理背景 | 纹理类图片，默认平铺填充。 | 提示框背景 | 适用于地图提示信息图层背景以及各种组件提示信息背景，默认适合于容器填充。 |
| 大标题 | 适用于大标题背景填充，默认适合于容器填充。 | 小标题 | 适用于小标题背景填充，默认适合于容器填充。 |
| 底座 | KPI装饰类图片，默认适合于容器填充。 | 容器底座 | 容器装饰类图片，默认适合于容器填充。 |
| 容器装饰 | 容器装饰类图片，默认适合于容器填充。 | 图形装饰 | 圆形类背景图片，适用饼图，水位图背景填充，默认适合于容器填充。 |
| 图表装饰 | 图表装饰类图片，默认适合于容器填充。 | 线条装饰 | 组件边框线条装饰类图片，默认切片填充。 |
| 单元格装饰 | 单元格装饰类图片，如序号列背景图片等，默认适合于容器填充。 | KPI装饰 | KPI装饰类图片，默认适合于容器装饰。 |
| 地图装饰 | 地图装饰类图片，默认适合于容器填充。 | 地图背景 | 地图背景图片，默认充满容器填充。 |
| 地图纹理 | 地图纹理类图片。默认平铺填充。 | 系列纹理 | 条形图、柱形图系列背景填充图片，默认适合于容器填充。 |
| 动效 | 动态类图片。 | 缺省 | 系统默认占位类提示信息图片，默认适合于容器填充。 |
| 图标 | 图标类图片，默认适合于容器填充。 | 插图 | 插图类装饰图片，默认适合于容器填充。 |
| 信息 | 系统异常信息类图片。 | 圆形 | 圆形类图片。 |
| 色系 | 各色系类图片。 |
### 图标标签{#icon-label}
图标目前已有的**标签**如下：
| 标签 | 适用范围 | 标签 | 适用范围 |
| :-------- | :-------- | :-------- | :-------- |
| 新增 | 新增操作类图标，代表各种新增操作。 | 箭头 | 箭头类图标。 |
| 物品 | 物品类图标。 | 附件 | 附件类图片，如上传附件、下载附件类。 |
| 看板 | 仪表板可视化图标，用于代表某个可视化页面。 | 品牌 | 商业品牌类图标。 |
| 建筑 | 建筑类图标。 | 商业 | 商业类图标。 |
| 计算 | 计算类图标，如加、减、乘、除等 | 时钟 | 时钟类图标。 |
| 组件 | 组件类图标，用于代表某个可视化组件。 | 控制 | 控制类图标，如快进、暂停、播放等。 |
| 复制 | 复制类图标，代表复制操作。 | 数据库 | 数据库图标，用于代表各种数据库。 |
| 装饰 | 装饰类图标。无具体含义，仅仅装饰用。 | 删除 | 删除操作类图标，代表各种删除操作。 |
| 动态 | 动态类图标。 | 编辑 | 编辑操作类图标，代表各种编辑操作。 |
| 教育 | 教育类图标，代表各种教育资源。 | 导出 | 导出操作类图标，代表各种导出操作。 |
| 面型 | 面型类图标，代表各种以面型为特点的图标。 | 文件 | 文件类资源图标，代表各种文件资源。 |
| 过滤 | 过滤操作类图标，代表各种过滤操作。 | GIS | GIS图标，可用于GIS地图中散点图层。 |
| 图形 | 图形类图标，适用于各种可视化图标资源。 | 层次 | 层次图标，代表各种层次。 |
| 图标集 | 图标集图标，适用柱形图、条形图的系列填充。 | 导入 | 导入类操作图标，代表各种导入操作。 |
| 首页 | 首页类资源图标，适用各种首页入口处。 | 生活 | 生活类资源图标，适用各种生活物品等。 |
| 线型 | 线型类图标，适用于各种具有线型特点的图标。 | 链接 | 链接类图标，适用于各种显示链接的业务场景。 |
| 地图 | 地图类图标，适用于各种地图标识等。 | 多媒体 | 多媒体资源图标，适用于各种多媒体MP3、MP4等。 |
| 医疗 | 医疗类资源图标，适用于各种医疗资源、医疗标识等。 | 信息 | 信息类资源图标，适用于各种信息资源，如警告、提示等。 |
| 更多 | 更多类操作图标，代表各种更多操作。 | 多色 | 多色图标，适用于各种色系图标。 |
| 导航 | 导航类操作图标，代表各种导航操作。 | 生物 | 生物类图标，适用于各种生物，如动物，植物等。 |
| 布局 | 布局类图标，代表各种布局类组件以及布局操作。 | 人物 | 人物类图标，适用于各种人物、职业等。 |
| 打印 | 打印类操作图标，代表各种打印操作。 | 流程 | 流程类图标，代表各种系统流程标识。 |
| 查询 | 查询类操作图标，代表各种查询操作。 | 刷新 | 刷新类操作图标，代表各种刷新操作。 |
| 保存 | 保存类操作图标，代表各种保存操作。 | 搜索 | 搜索类操作图标，代表各种搜索操作。 |
| 安全 | 安全类图标，代表各种安全标识。 | 选择 | 选择类操作图标，代表各种选择操作。 |
| 设置 | 设置类操作图标，代表各种设置操作。 | 形状 | 形状类图标，如方形，圆形等。 |
| 社交 | 社交类图标，可用于各种社区场景。 | 排序 | 排序类操作图标，代表各种排序操作。 |
| 符号 | 符号类图标，适用于各种符号，如数学符号、金融符号等。 | 系统 | 系统类资源图标，代表各种系统资源。 |
| 表格 | 表格类资源图标，代表各种类型的表格资源。 | 交通 | 交通类资源图标，代表各种交通标识。 |
| 重做 | 重做类操作图标，代表各种重做操作。 | 查看 | 查看类操作图标，代表各种查看操作。 |
| 天气 | 天气类图标，代表各种天气情况。 | 缩放 | 缩放类操作图标，代表各种缩放操作。 |
| 3D | 3D类图标 |
## 推荐规则{#rule}
系统会自动根据组件属性、图片标签等信息进行智能推荐。
### 图片推荐
系统会优先根据图片的**首位标签**进行智能推荐，具体推荐规则如下：
| 组件 | 推荐标签 | 组件 | 推荐标签 |
| :-------- | :-------- | :-------- | :-------- |
| 画布 | 画布背景 | 布局组件 | 边框背景、容器装饰、线条装饰、插图 |
| 大标题 | 大标题 | 小标题 | 小标题 |
| 表格背景 | 边框背景 | 表格单元格 | 单元格背景 |
| 柱形图背景 | 边框背景 | 柱形图系列 | 系列纹理 |
| 条形图背景 | 边框背景 | 条形图系列 | 系列纹理 |
| 条形图背景 | 边框背景 | 条形图系列 | 系列纹理 |
| 象形柱形图背景 | 边框背景 | 象形柱形图系列 | 系列纹理 |
| 象形条形图背景 | 边框背景 | 象形条形图系列 | 系列纹理 |
| 双向条形图背景 | 边框背景 | 双向条形图系列 | 系列纹理 |
| 条形竞赛图背景 | 边框背景 | 条形竞赛图系列 | 系列纹理 |
| 折线图 | 边框背景 | 散点图 | 边框背景 |
| 面积图背景 | 边框背景 | 面积图系列 | 系列纹理 |
| 雷达图背景 | 边框背景 | 雷达图系列 | 系列纹理 |
| 饼图背景 | KPI装饰、底座、图表装饰 | 饼图系列 | 系列纹理 |
| 旭日图背景 | KPI装饰、底座、图表装饰 | 矩阵图背景 | 边框背景 |
| 桑葚图 | 边框背景 | 数据条背景 | 边框背景 |
| 数据条进度 | 系列纹理 | 仪表盘背景 | 边框背景 |
| 仪表盘进度 | 系列纹理 | KPI背景 | KPI装饰、底座、图表装饰、 |
| 里程表背景 | 边框背景 | 里程表指标 | 数字背景 |
| 进度环背景 | 边框背景 | 进度环系列 | 系列纹理 |
| 水位图 | 边框背景 | 词云图 | 边框背景 |
| GIS地图组件背景 | 边框背景 | 地图区块图层 | 地图背景、地图纹理 |
| 地图图片图层 | 地图装饰、地图背景 | 地图提示信息图层 | 提示框背景 |
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/browse.md"
htmlUrl: "https://docs.succapp.com/v5/dash/browse"
title: "browse"
---
---
order: 6
navTitle: 浏览仪表板
---
# 浏览仪表板
仪表板制作完成，可以通过以下几种方式将其分发给用户进行浏览：
- [播放](#play)：在元数据目录，通过单击或者右键播放仪表板
- [查看](#check)：在元数据目录，通过右键查看结果页面
- [门户查看](#portal)：已有仪表板资源在门户中展示
## 播放{#play}
播放模式，又称幻灯片模式，单击仪表板或鼠标右键选择**播放**进入该模式。播放模式下可以将当前目录下所有的资源文件以幻灯片的方式进行轮询播放，播放时可以手动切换**上一页**/**下一页**，也可以启用**自动播放**模式。
在播放模式下，页面顶部提供了工具栏设置，包括[编辑](#edit)、[刷新](#refresh)等[功能选项](#tools)与**二维码**、**自动播放**等播放功能设置。
- 二维码：仪表板[添加移动布局](./design/mobile/README.md#aadd)后，可以通过移动设备扫描二维码查看移动端效果，移动端视图配置可参考[移动端设计指南](./design/mobile/README.md)
- 上一页：播放元数据目录当前仪表板的上一个仪表板
- 下一页：播放元数据目录当前仪表板的下一个仪表板
- 自动播放：设置时间后，系统将按照指定时间按顺序自动播放元数据目录的仪表板，默认为`停止`
- 固定/取消固定：默认固定工具栏，播放模式下，建议设置为取消固定工具栏
- 关闭：退出播放界面，返回元数据目录
:::tip 通用幻灯片模板
门户应用中提供了【通用幻灯片模板】，如果希望播放不同目录下的资源，可以使用该模板，选用方法可参考[门户模板选择](../../app/portal-page/new-portal.md#template)
:::
## 查看{#check}
分析模块右键点击仪表板选择[查看](../../devops/extension-manage/README.md)，或者点击缩略图右上角**更多**按钮选择[查看](../../devops/extension-manage/README.md)，全屏展示仪表板，页面的**更多**按钮提供[功能选项](#tools)。
## 门户查看{#portal}
我们可以将一系列相关的内容按照自定义的方式集成到[门户](../../app/portal-page/new-portal.md)中，形成一个完整的业务应用框架。已有的仪表板资源可以通过[添加资源到门户页面](../../app/portal-page/new-portal.md#add)进而在门户中展示。在门户查看仪表板时，页面同样提供[功能选项](#tools)。
## 功能选项{#tools}
仪表板在[查看](#check)、[播放](#play)、[门户查看](#portal)模式下，都提供了[功能选项](#tools)，如[编辑](#edit)、[导出](#export)等。
这里工具栏中各[功能选项](#tools)的显示与[权限分配](../../permission/grant/README.md#single-user)有关，例如只为当前用户分配了资源的[查看权限](../../permission/grant/operations.md#view)时，工具栏的[编辑](#edit)、[分享](#share)等操作按钮将不可见。
:::tip 更多菜单
- 仪表板编辑页面，在画布属性栏的**样式**>**布局**中勾选**显示功能按钮**，仪表板[查看](#check)页面与[门户查看](#portal)仪表板页面的右上角将显示**更多**按钮。未勾选时，可通过快捷方式**显示更多菜单**
- 在项目工具栏的**更多**>**项目设置**>**分析**中勾选了**显示更多菜单**，查看页面可以使用Ctrl+Alt+鼠标右键快速弹出菜单
:::
### 编辑{#edit}
进入仪表板的设计器界面，对仪表板进行修改，样式设置等操作。
### 刷新{#refresh}
刷新当前仪表板的数据，查看最新分析结果。当多个用户修改仪表板组件的数据时，可以通过**刷新**将其余用户修改的数据同步，展示最新的分析结果。
[//]: # "### 视图：原始视图{#view}"
### 分享{#share}
[分享](https://docs.succapp.com/v5/co/share)可以将我们认为优质、有趣、实用的仪表板分享给他人。我们提供了[邮件](https://docs.succapp.com/v5/co/share#email-share)、[微信](https://docs.succapp.com/v5/co/share#wshare)、[链接](https://docs.succapp.com/v5/co/share#link-share)三种分享方式。
### 收藏{#collect}
我们可以使用[收藏]()功能，在查看仪表板时，将我们认为有价值，或者将来会使用到的仪表板收藏起来，以便再次寻找时可以在元数据界面右上角的五角星图标中快速定位。
### 导出{#export}
**导出**可以将当前仪表板大屏保存为**图像**、**PowerPoint**或者**PDF**。导出为**PowerPoint**时，导出的PowerPoint是矢量的，可以继续对其图形数据、文字等进行修改。
### 评论{#comment}
[评论](https://docs.succapp.com/v5/getstarted/bi/co-comment)可以让我们针对仪表板的内容发表自己的观点，[评论](https://docs.succapp.com/v5/getstarted/bi/co-comment)支持多种操作。
- [添加评论](https://docs.succapp.com/v5/getstarted/bi/co-comment#add)：可将文字、图片等添加到一条评论
- [修改评论](https://docs.succapp.com/v5/getstarted/bi/co-comment#edit)：如果评论的内容存在错别字或不通顺的文字，则可通过编辑评论，对评论内容进行修改
- [回复评论](https://docs.succapp.com/v5/getstarted/bi/co-comment#respond)：如果针对评论内容希望发表自己的观点，可以回复评论
- 删除评论：如果评论内容有误，可以点击**删除**将该评论删除
- 截图：添加、编辑、回复评论时，支持添加系统截图
- 可见范围：支持设置评论的可见范围。可以设置为`公开的`、`本级可见`、`本级及下级可见`、`@用户可见`
- 点赞：可以对满意的评论进行点赞支持
### 显示组件工具栏{#toolbar}
在仪表板[查看](#check)页面勾选右上角**更多**菜单中的**显示组件工具栏**选项，勾选后，选中组件，右上角显示的**最大化**和**更多**按钮分别可以将某些图形重点展示、查看和导出组件使用的数据。
---
url: "https://docs.succapp.com/v5/guide/data-viz/dash/manage-templates/README.md"
htmlUrl: "https://docs.succapp.com/v5/dash/templates"
title: "仪表板模板介绍"
---
---
order: 8
navTitle: 模板管理
indexTitle: 模板管理
---
# 仪表板模板介绍
仪表板模板是为了用户在制作仪表板时，能在已有仪表板的基础上进行增删改等操作，避免用户做每个仪表板都从零开始。
用户在新建仪表板时，可在新建对话框中选择已有模板：
模板选择截图todo
## 创建模板
当已有的仪表板模板不能满足用户的需求，那么用户可以按照自己的需求，创建或修改仪表板模板。
动图todo
操作步骤
1. 参考文档[柱形图](../components/chart/column-chart.md) ，完成仪表板的制作
2. 点击汉堡菜单，选择保存为模板，弹出保存模板对话框
3. 名称
1. 输入不存在的名称，新增一个自定义模板
2. 下拉选择已有的名称，修改原有的模板
4. 保存数据，是否将数据模型保存到模板
## 模板管理
当模板名称和内容不相匹配，或已有模板太多，或部分模板不再需要了，那么用户可以通过模板管理对已有模板进行重命名和删除操作。
动图todo
操作步骤
1. 点击汉堡菜单，选择管理模板，弹出管理模板对话框，模板以缩略图的形式显示在对话框中
2. 鼠标移动某个模板，模板右上角出现三个点小图标，点击后，可选择重命名、删除
3. 选择重命名，在缩略图下方输入新命名即可
4. 选择删除，模板从对话框中消失
---
url: "https://docs.succapp.com/v5/guide/data-viz/viz-best-practice/README.md"
htmlUrl: "https://docs.succapp.com/v5/viz-best-practice"
title: "概述"
---
---
order: 2
navTitle: 数据可视化最佳实践
indexTitle: 概述
---
# 概述
在当前的市场中，数据可视化已经成为了传播数据信息的标准和载体。从商业智能BI到新闻媒体行业，处处都存在着数据可视化的影子，它帮助了我们更好的理解数据和交流数据中传达出的信息。研究表明，大脑对于可视化呈现出来的信息更加容易接受，相比较于传统电子表格，人更容易接受和理解可视化图表中传递的数据信息。目前常见的数据可视化效果如下：
| 市场销售指标大屏 | 普通高等学校和师生情况 | 商店销售小程序 |
| ---| --- | --- |
|  |  |  |
## 数据可视化最佳实践{#step}
SuccBI提供了自助式仪表板，利用仪表板提供的丰富组件、灵活交互、多端展示等功能，即可以快速制作出一张数据可视化页面。那么如何使页面的效果更加完美，可参考下方两种最佳实践思路：
### PC&移动最佳实践{#pc}
通常在PC&移动端制作数据可视化效果时，追求最方便、最快速而且还能达到一个最好的效果。按照这种思路进行制作，我们通常会先去寻找现成的[可视化模板](#template)进行参考使用。如果可视化模板无法满足需求时，就需要从零开始搭建。这两种方式的使用场景和操作步骤存在着一定的差异，选择最适合的方式即可。
1. 使用可视化模板：选择系统提供的现成可视化模板，替换数据即可快速完成一个美观的页面。相关制作步骤，具体可见[可视化模板](#template)
2. 从零开始可视化：当可视化模板无法满足用户的要求时，我们可以从零开始搭建，搭建时按照**确定页面布局**、**选择页面主题**和**切换组件风格**三步即可快速搭建一个美观的页面。相关制作步骤，具体可见[从零开始可视化](#start)
### 大屏最佳实践{#dash}
数据大屏一般是展示在比较重要的场合中，比如大型展览、高级会议或者办公大厅中的。所以此类大屏需要具有较强视觉冲击力，同时将一些关键指标炫酷的进行展示。这种情况下，页面的炫酷效果就更加重要。所以我们需要在制作页面前，先做好设计再进行制作。大屏最佳实践，可参加下面三步：
1. 原型设计：需要对页面中各个数据指标、各种组件和相关元素进行合理性规划的步骤。首先需要开展业务需求调研、依据业务场景提取重要指标数据，最后根据调研结果产出原型设计图，整个过程是需要项目经理参与进来
2. 可视化效果设计：设计师通过项目经理提供的原型设计图，设计出美观、炫酷的设计稿。经过讨论确认无误后，即可产出UI设计图、切图以及切图规范等产物相关人员进行制作
3. 页面制作：相关人员根据设计师提供的UI设计图和切图等资源，进行页面制作
相关制作步骤，具体可见[数据大屏最佳实践](./lsd.md)。
## 从零开始可视化{#start}
从零开始可视化思路如下：
!!! bilibili BV1Vu411m7vE 5 !!!
1. 确定页面布局：根据仪表板面向的对象，选择适合的布局方案
2. 选择页面主题：选择符合业务需求的主题样式
3. 切换组件风格：切换适合的组件风格
从入门到精通主题，可以查看视频系统学习：[玩转主题](https://www.bilibili.com/video/BV1dG4y1t7rX/?spm_id_from=333.999.0.0\&vd_source=a50dfccdd7de258ff7a1fc895aed5fcc)。
## 布局{#layout}
做好可视化数据必不可少排版布局，优秀的可视化都需要进行精心的设计，排版合理且主次分明，用户才更容易抓住关键信息、清晰有效的获取和理解数据。
仪表板的布局还需要考虑终端设备类型，不同类型设备对页面的要求是有所不同的。例如在个人笔记本上查看的可视化页面，可以考虑页面排版丰满；而移动端则需要简明扼要，保留关键指标信息。
| PC大屏式布局 | PC长图式布局 |
| --- | --- |
|  |  |
| PC宽屏式布局 | 移动端布局 |
| --- | --- |
|  |  |
- **PC大屏式布局**：此种布局以大屏为载体，直观呈现数据可视化状态；同时在视觉上可以更加清晰的向用户传递数据价值，让用户快速洞悉业务数据变化。在使用对象上，大屏式布局有助于领导层面进行信息决策。相关属性以及具体设置方式，可见[整个视图](../dash/design/layout/README.md#fullscreen)
- **PC长图式布局**：即定宽式布局，这种布局可以无限制向下滚动展示数据。长图式布局的体验类似于在阅读微信长图，可以更加丰富的展示数据，不被用户的显示器大小所限制。通过长图式布局，我们可以制作类似图文报告类的需求。相关属性以及具体设置方式，可见[固定宽度](../dash/design/layout/README.md#fixwidth)
- **PC宽屏式布局**：即多屏联动式布局。此类布局可以将多个页面的内容拼接到一个页面中共同展示，因此此类布局中可以存在多个需要突出显示的主要指标。通过宽屏式布局，我们可以在监控室或者战略指挥时，用此类布局页面来辅助用户做出决定。相关属性以及具体设置方式，可见[固定大小](../dash/design/layout/README.md#fixsize)
- **移动端布局**：仪表板提供移动端视图，通过增加移动端视图，可以使仪表板的移动端布局和PC端布局共用一套。当使用移动端查看页面时，系统会自动切换成移动端的布局效果进行展示。相关属性以及具体设置方式，可见[移动端布局方式](../dash/design/layout/README.md#mobile)
## 主题&风格{#themes-style}
在确定好布局后，可以通过仪表板自带的主题或风格快速美化组件UI效果，同时也支持自定义组件的样式。
### 主题{#themes}
使用主题可以制作美观仪表板，切换不同主题可以实现同一个仪表板展示不同的效果，满足在多个场景下的应用。例如：浅色更适合日常的工作，不那么容易产生视觉疲劳，深色则更适合演示汇报，更加炫酷，更能吸引用户注意力，主题相关属性，可见[主题管理](../dash/manage-themes/README.md)。
#### 使用主题{#use-themes}
确认好页面组件布局后，我们可以选择符合当前页面需求的主题。切换主题步骤如下：
#### 系统主题{#sys-themes}
仪表板提供了9种主题供用户选择使用，目前系统自带如下主题：
| 默认主题 | 绿色主题 | 海洋王国 | 蓝色主题 |
| --- | --- | --- | --- | --- |
|  |  |  |  |
| 深蓝主题 | 印刷杂志 | 红色主题 | 紫色浪潮 | 黑金主题 |
| --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |
#### 自定义主题{#new-themes}
仪表板提供自定义主题入口，用户可以根据自己实际的需求，制作一套全新的主题，具体可参考：
- 文档地址：[仪表板主题制作](../dash/manage-themes/制作自己的主题.md)
- 视频地址：[玩转主题](https://www.bilibili.com/video/BV1BU4y177zP/?spm_id_from=333.999.0.0)
### 风格{#style}
风格是组件的所有属性样式的集合，每一个组件都可以保存多个风格，通过风格的使用可以做到多个组件一起快速的切换外观风格、也可以做到修改风格后所有的组件的外观一起变化。风格相关属性，可见[系统自带的主题](../dash/manage-themes/系统自带的主题.md)。
#### 使用风格{#use-style}
确认页面主题后，我们可以直接对各个组件及组件标题切换风格，系统是默认提供了几套风格，我们可以直接切换使用。切换风格步骤如下：
#### 自定义风格{#new-style}
在设计仪表板时，可以随时对风格进行应用、更新、编辑、重命名和删除的操作。
一般当我们多个页面的组件风格样式都是一致的情况下，我们可以将其中一个页面中组件的风格保存为一个新的风格。这样其他页面的组件，都可以一键切换到我们自定义的风格样式。风格相关属性，可见[管理风格](../dash/design/type/basic/style.md#manage)。
### 背景{#backgroud}
画布和组件提供了背景属性配置，可以自定义填充颜色和图片，以达到美观的效果。背景属性提供了四种填充方式：
1. 无填充：即无背景。组件放置于布局组件中或者面板中，父容器设置了背景填充时，可以直接将组件背景设置为无填充
2. 颜色填充：可选择纯色填充或渐变色填充，多用于KPI组件，通过不同背景颜色的填充，从而突出显示KPI数据
3. 图片填充：选择图片填充时，可选择系统图片库中的图片，也可上传自定义图片。图片背景填充可以使组件样式更加炫酷，多用于面板、布局组件的背影优化
4. 动效填充：背景以动态的效果展示，系统中同样也提供了多种动效。相比较图片填充，页面效果更加炫酷，多用于大屏制作的场景
背景相关属性，可见[背景](../dash/design/type/basic/background.md)。
| 无填充 | 颜色填充 | 图片填充 | 动效填充 |
| --- | --- | --- | --- |
|  |  |  |  |
#### 自定义背景{#use-backgroud}
系统各个主题中都自带了许多图片，可以直接使用系统提供的图片作为组件背景。如果系统的图片无法满足需求时，可以自定义上传图片作为组件背景。操作步骤如下：
1. 图片来源：系统提供**默认**、**静态图片**、**URL**三种来源方式，具体可参考[图片来源](../../app/superpage/components/common/image.md#source)
2. 填充方式：系统提供**原始大小**、**拉伸**、**充满容器**、**适用于容器**、**切片**、**平铺**五种填充方式，具体可参考[填充方式](../../app/superpage/components/common/image.md#fill)
### 字体{#font}
统一页面的字体大小，可以使页面更加美观协调。不同文本内容可参考下方示例，也可以根据实际场景、主题自行更改字体、颜色等属性，具体可参考[编辑风格](../dash/design/type/basic/style.md#manage)。
以下为系统中推荐的各种文字标题的字体大小：
其他字体的排查规范如下：
1. **字体**
- 标题字体、中文字体、英文字体是否统一，是否与规范一致
- 是否使用了特殊字体
2. **字号**
- 文字字号是否与规范一致
- 重点文字和辅助文字的大小对比比例是否与规范一致
3. **粗细**
- 是否突出主要内容，弱化次要内容
4. **字间距/行间距**
- 是否使用了适当的字间距和行间距
5. **信息层级**
- 是否符合视觉浏览路径（从上到下，从左到右）
- 是否重点层次分明
### 颜色{#color}
仪表板可以直接取用主题色板中的颜色，也可以通过颜色的十六进制代码取自定义颜色值。如需修改主题色板可见[制作自己的主题](../dash/manage-themes/制作自己的主题.md)。
在可视化页面中，尽量不要在一个页面中设置过多的颜色，建议是5种颜色以内。常用预警色如下：
其他颜色的排查规范如下：
1. **文字颜色**
- 文字颜色是否统一
- 重点文字和辅助文字颜色是否产生对比
2. **图形颜色**
- 标准色是否统一
- 用色是否过多
3. **表格颜色**
- 表头颜色、表头背景、边框颜色、内容文字颜色、隔行换色颜色、表格背景颜色是否与规范一致
4. **地图颜色**
- 地图颜色、阴影颜色、阴影透明度、叠加层颜色、选择地区颜色是否按热度分级颜色
## 各组件适用场景{#scene}
页面的美化，需要通过不同组件的相互组合，从而达到一种协调美。不同组件也有适合自己的业务场景，所以了解各组件的适用场景也是让页面更加协调的途径之一。
参考安德鲁·阿伯拉（Andrew Abela）制作的《这份指南》（This Guide），我们可以将仪表板中的组件大致分为：
- [页面布局](#page-layout)
- [数据比较](#data-comparison)
- [数据分布](#data-distribution)
- [数据构成](#data-composition)
具体可参加下图：
### 页面布局{#page-layout}
此类组件可以辅助快速布局，也可嵌入第三方页面进行布局。
**布局组件**：此类组件，可以辅助我们将页面划分成各自独立的区域，这样可以更好的规划页面的业务分布。其中**标签页**可以搭配**多页面板**中进行页面切换。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 面板 | 面板是用于放置其它组件的布局组件，可以任意组合组件形成一个数据卡片 | [面板](../dash/components/layout/panel.md) |
| 多页面板 | 多页面板可以根据需求新增多个面板页面，每一页面板都可以任意组合组件形成一个数据卡片，一般与选项卡配合使用，同时只能显示一页面板的内容 | [多页面板](../dash/components/layout/panelbook.md) |
| 浮动面板 | 浮动面板可以根据数据浮动出多个面板来，面板横向排列并可以自动绕排，形成一个个数据卡片 | [浮动面板](../dash/components/layout/floatpanel.md) |
| 标签页 | 标签页组件可以根据需求新增多个标签选项，可以结合多页面板使用，通过切换标签选项控制切换多页面板页面的显示；也可以切换标签页过滤图表组件 | [标签页](../dash/components/input/tabbar.md) |
**第三方页面嵌入**：在页面中快速嵌入第三方页面，比如系统内报表、仪表板、第三方系统等等。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| IFrame | IFrame即嵌入网页组件，可以将系统内部的元数据文件如报表、SuperPage等嵌入到仪表板中展示，也可以将系统外部页面嵌入展示 | [IFrame](../dash/components/more/iframe.md) |
### 数据比较{#data-comparison}
此类组件主要用于对于数据，突出数据之间的差异、数据的发展趋势、以及各类数据的所在比重。所以此类组件又可大致分为:
- [数据对比](#data-compare)
- [数据趋势](#data-trends)
- [数据占比](#proportion)
- [数据汇总](#data-summary)
#### 数据对比{#data-compare}
通过可视化的效果，将数据直接展示，对比显示数据之间的差异。
**2~3维度指标对比**：引用多个维度，将多个维度的数据进行展示，对比出多个维度数据差异。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 柱形图 | 柱形图是使用宽度相同的柱子的高度来表示数据多少，用于两个或以上的数值对比，进行比较各组数值之间的差别 | [柱形图](../dash/components/chart/column-chart.md) |
| 条形图 | 条形图与柱形图类似，都是使用宽度相同柱子的长短来表示数据的多少，柱形图的柱子为纵向放置，条形图的柱子为横向放置。用于2个或2个以上的数值对比 | [条形图](../dash/components/chart/bar-chart.md) |
| 双向条形图 | 双向条形图又称金字塔图，一般用于对比不同维项下两个不同指标数据的表现 | [双向条形图](../dash/components/chart/pyramidchart.md) |
**单维度指标对比**：引用引用单个维度指标，对比展示维度中各维项之间的数据差异。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 象形柱形图 | 象形柱形图属于柱形图的一种，与柱形图的区别在于象形柱形图能够自定义柱子形状 | [象形柱形图](../dash/components/chart/pictorialbar.md) |
| 象形条形图 | 象形条形图是条形图的一种，与条形图的区别在于象形条形图能够自定义柱子形状 | [象形条形图](../dash/components/chart/hpictorialbar.md) |
**按时间对比**：以时间为维度，对比各时间段时间之间的数据差异。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 条形竞赛图 | 条形竞赛图是一种特殊的条形图，主要以时间维度展示数据直接差异 | |
#### 数据趋势{#data-trends}
**多维度指标趋势**：引用多个维度，将多维度的数据趋势进行展示，辅助用户快速判断数据发展趋势。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 折线图 | 折线图是将值标注成点，并通过连线将这些点按照某种顺序连接起来形成的图形，用于展示数值所占大小随时间或有序类别而变化的趋势 | [折线图](../dash/components/chart/line-chart.md) |
| 面积图 | 面积图是将值标注成点，并通过连线将这些点连接起来，起点和终点与坐标轴连接，形成一个面积范围，用于展示数值大小随时间或有序类别变化的范围 | [面积图](../dash/components/chart/area.md) |
| 组合图 | 组合图展示的是同一维度下多个指标系列的数据变化。组合图支持双轴展示不同量级数据，并在单边下支持常规线性图、柱形图、面积图组合、堆积混合等复杂场景展示 | [组合图](../dash/components/chart/dcombo.md) |
#### 数据占比{#proportion}
通过可视化的展示，展示出单维度或多维度直接数据占比比重。
**单度量百分比占比**：引用单度量数据，计算出该数据所占比重并以百分比的形式进行展示。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 数据条 | 数据条以进度填充的方式，显示处理任务的速度、完成度、剩余未完成任务量的大小 | [数据条](../dash/components/chart/databar.md) |
| 仪表盘 | 仪表盘是模仿汽车速度表的一种图表，可以简单、直观地展示某个指标值所在的范围 | [仪表盘](../dash/components/chart/gauge.md) |
| 环形占比 | 环形占比图以空心的圆环表示某项指标分类的占比分布情况 | [环形占比](../dash/components/chart/percentring.md) |
| 水位图 | 水位图类似KPI，常用来展示一个指标数据 | [水位图](../dash/components/chart/waterpercent.md) |
| 图标条 | 图标条以图标的填充显示处理任务的速度、完成度、剩余未完成任务量的大小 | [图标条](../dash/components/chart/iconbar.md) |
**维项数据多少**：通过数据填充后，以文字或者方块大小的形式，展示数据多少。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 词云图 | 词云图是由词汇组成类似云的彩色图形，能够直观的显示词频，常用来做一些用户的画像和用户的标签。词云图不仅能够展示大量文本数据，还能通过字体大小体现词汇的重要性 | [词云图](../dash/components/chart/wordcloud.md) |
| 矩阵图 | 矩阵图是用来显示数据的占比关系，矩阵的空间根据数据的分组被分为多个矩形，矩形大小反应数据占比大小 | [矩阵图](../dash/components/chart/treemap.md) |
**多维度数据**：将多维度数据进行展示，以网状放射的形式，展示各维度数据的比重。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 雷达图 | 雷达图又称蜘蛛网图，它从一个中心点向外辐射出多条坐标轴，每一个维项数据都占有一条数据坐标轴。使用雷达图，可以快速找到具有相似值的维项、以及是否存在异常维项值 | [雷达图](../dash/components/chart/radar-map.md) |
**维项数据占比**：展示维项数据，通过百分比的形式展示出各维项数据的占比。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 饼图 | 饼图是以扇形区域大小表示每一个数值相对于总数值的占比 | [饼图](../dash/components/chart/pie-chart.md) |
| 条形占比图 | 条形占比图以条形的分段长度来表示各部分数据的占比情况，与饼图类似，数据可以是百分比或者数值 | [条形占比图](../dash/components/chart/horizbar.md) |
**多维度占比**：展示多维度数据，显示出多维数据各自的数据占比。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 旭日图 | 旭日图也称为太阳图，是一种圆环镶接图。旭日图中每个级别的数据通过1个圆环表示，离原点越近代表圆环级别越高，最内层的圆表示层次结构的顶级，然后一层一层去看数据的占比情况。越往外，级别越低，且分类越细。 | [旭日图](https://demo.succbi.com/v5/bi/sunburst) |
#### 数据汇总{#data-summary}
展示指标数据的汇总值。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| KPI | KPI即关键绩效指标，通常用来展示一个或多个指标数据 | [KPI](../dash/components/chart/kpi.md) |
| 里程表 | 里程表类似KPI，常用来展示一个指标数据，类似汽车里程表 | [里程表](../dash/components/chart/odometer.md) |
### 数据分布{#data-distribution}
通过可视化的方式，展示数据分布的密度，从而体现数据分布情况。
**数据按地图分布**：通过GIS地图组件，展示数据在地图上的分布情况。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| GIS地图 | 当数据和地理位置有关系时，可以使用GIS地图展示地理空间数据，通过地图的空间数据分布快速获取信息 | [GIS地图](../dash/components/chart/gis-map.md) |
**数据按度量分布**：将度量数据作为坐标系内X、Y轴的数据，从而定位出维度数据的分布情况。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 散点图 | 散点图是指回归分析中，数据点在直角坐标系平面上的分布图，表示的是因变量随自变量变化的大致趋势 | [散点图](../dash/components/chart/scatter.md) |
**数据按时间分布**：以时间为维度单位，展示数据在各个时间节点上的分布情况。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 时间轴 | 绑定时间数据，实现根据时间字段滚动显示，同时也可以同其他组件联动刷新数据 | [时间轴](https://demo.succbi.com/v5/demo/%E6%97%B6%E9%97%B4%E8%BD%B4/play) |
**数据流向**：展示数据流动方向。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 步行图 | 步行图也称瀑布图、阶梯图，通常用于经营分析和财务分析 | |
| 桑葚图 | 桑基图，即桑基能量分流图，也叫桑基能量平衡图。它是一种特定类型的流程图，右图中延伸的分支的宽度对应数据流量的大小，通常应用于能源、材料成分、金融等数据的可视化分析 | [桑葚图](https://demo.succbi.com/v5/bi/sankey-diagram) |
**个性化数据分布**：上传SVG图片，将数据填充至SVG图片中，展示数据展示SVG图片中分布情况。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 动态SVG | 将数据填充到SVG图片中，实现数据展示 | [动态SVG](https://demo.succbi.com/v5/demo/%E5%8A%A8%E6%80%81SVG%E5%9B%BE/play) |
### 数据构成{#data-composition}
此类组件，重点在于**数据过滤**、**多媒体数据**、**表格数据**的展示。
**数据过滤**：即数据交互类组件。可以根据选项的选择对页面或指定组件的数据进行筛选或过滤。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 下拉框 | 下拉框使用下拉菜单展示或选择内容，用于过滤数据 | [下拉框](../dash/components/input/combobox.md) |
| 选择面板 | 选择面板组件用来平铺展示多个选项，不仅可以切换多页面板的页面，还可以通过选择不同的选项展示不同的数据 | [选择面板](../dash/components/input/selectpanel.md) |
| 输入框 | 输入框可以对输入的字段进行筛选 | [输入框](../dash/components/input/inputbox.md) |
| 日期 | 日期组件用于过滤数据，筛选出指定时间范围内的数据 | [日期](../dash/components/input/date.md) |
| 快速搜索 | 快速搜索是一个辅助输入组件，帮助用户在大量的数据中快速定位并选择一条需要的数据，通常用于搜索那些无法全部列出供用户选择的数据，这些数据可能数据量很大、也可能由于安全考虑不希望一次性显示给用户，比如企业名称、疾病编码等 | [快速搜索](../dash/components/input/searchbox.md) |
**多媒体数据**：仪表板提供一些多媒体组件，通过字、影、音、图等形式，展示更多形式下的数据。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 文本 | 文本组件一般用于解释说明文字，或插入指标制作图文报告等 | [文本](../dash/components/more/text.md) |
| 图片 | 图片组件可以显示上传的静态图片或指定路径的图片 | [图片](../dash/components/more/image.md) |
| 图标 | 图标组件可以显示系统自带的、用户上传的或者使用URL的图标 | [图标](../dash/components/more/icon.md) |
| 视频 | 视频组件可以显示上传的视频或网络上的视频 | [视频](../dash/components/more/video.md) |
| 按钮 | 按钮组件通过点击来执行操作，需要搭配交互使用 | [按钮](../dash/components/more/button.md) |
| 轮播图 | 轮播图组件，可以同时展示多张图片，也支持图片的自动轮播 | [轮播图](https://docs.succapp.com/v5/dash/component/carousel) |
| 视频组 | 视频组组件可以显示存储在数据表中的一个或多个视频数据 | [视频组](../dash/components/more/videogroup.md) |
**表格**：表格类组件，通过类Excel表的形式展示数据，通常用于展示明细数据。
| 名称 | 描述 | 文档地址 |
| --- | --- | --- |
| 明细表 | 明细表展示数据表中最细粒度的数据，显示的每条数据都对应于数据库表原始行的一条数据 | [明细表](../dash/components/table/columntable.md) |
| 分组表 | 分组表可以将数据以分组的形式展现，展示各个分组的总体数据 | [分组表](../dash/components/table/grouped-table.md) |
## 可视化模板{#template}
仪表板提供多种数据展示目标，用户只需要替换掉目标中的数据、重新取数后即可快速实现一张炫酷的大屏页面了。目前系统共提供如下8个模板：
| 印刷杂志 | 海洋王国 | 绿野仙踪 | 碧空万里 |
| --- | --- | --- | --- |
|  |  |  |  |
| 幽兰一隅 | 靛蓝万象 |紫色浪潮 |子夜星辰 |
| --- | --- | --- | --- |
|  |  |  |  |
更多炫酷大屏技巧，可以查看视频：[10分钟搭建炫酷可视化大屏](https://www.bilibili.com/video/BV1LT411w7gf/?spm_id_from=333.999.0.0\&vd_source=a50dfccdd7de258ff7a1fc895aed5fcc)。
---
url: "https://docs.succapp.com/v5/guide/data-viz/viz-best-practice/lsd.md"
htmlUrl: "https://docs.succapp.com/v5/lsd"
title: "大屏设计指南"
---
---
order: 2
navTitle: 数据大屏最佳实践
---
# 大屏设计指南
---
url: "https://docs.succapp.com/v5/guide/data-viz/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/data-viz/faq"
title: "常见问题"
---
---
order: 6
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/data-viz/faq/如何调整浏览器字体大小设置.md"
htmlUrl: "https://docs.succapp.com/v5/data-viz/font-size"
title: "如何调整浏览器字体大小限制"
---
---
order: 3
navTitle: 如何调整浏览器字体大小限制
---
# 如何调整浏览器字体大小限制
制作好的数据看板投放到电脑或大屏上时，会根据终端屏幕的分辨率自动缩放。当数据看板通过浏览器进行缩放展示时，可能存在字体大小缩放到一定程度后不再缩小的情况。
这是因为浏览器设置了最小字号限制，如Google Chrome与Microsoft Edge的最小字号默认设置为12px，只需要在浏览器中将该设置调整，即可实现在缩放时继续缩小字体。
下面分别介绍在[Google Chrome浏览器](#chrome)、[Firefox浏览器](#firefox)、[Microsoft Edge浏览器](#edge)中，如何调整浏览器最小字号的限制。
## Google Chrome浏览器{#chrome}
谷歌浏览器可以通过**设置**>**外观**>**自定义字体**>**最小字号**修改最小字号。
## Firefox浏览器{#firefox}
火狐浏览器可以通过**设置**>**常规**>**字体**>**高级**>**最小字号**修改最小字号。
## Microsoft Edge浏览器{#edge}
微软浏览器可以通过**设置**>**外观**>**字体**>**自定义字体**>**最小字号**修改最小字号。
---
url: "https://docs.succapp.com/v5/guide/data-viz/faq/manual-query.md"
htmlUrl: "https://docs.succapp.com/v5/data-viz/manual-query"
title: "如何手动查询页面数据"
---
---
order: 4
navTitle: 如何手动查询页面数据
---
# 如何手动查询页面数据
通常数据的条件发生变化后，系统会自动刷新页面的数据。但是有些场景下希望条件修改后，需要手动点击查询按钮后才刷新数据。比如当一个页面顶部有多个过滤筛选条件时，希望把多个条件设置好后再执行查询数据，而不是每次修改一个条件，系统就自动查询数据，这样也可以避免系统发起不必要的查询请求。
下面分别介绍在[报表手动查询](#report-forms)、[仪表板手动查询](#instrument-panel)中，如何手动查询页面数据。
## 报表手动查询{#report-forms}
报表可以在参数栏的属性中控制修改参数时不查询数据，同时再配合查询按钮来实现手动刷新页面数据，给按钮添加查询交互来实现手动查询页面数据，此处以**各地区销售情况表**为例手动查询页面数据。
[点击此处体验](https://demo.succbi.com/v5/bi/%E6%89%8B%E5%8A%A8%E6%9F%A5%E8%AF%A2%E9%A1%B5%E9%9D%A2%E6%95%B0%E6%8D%AE)
实现报表手动查询的具体操作步骤如下：
1. 勾选下拉框的‘自动过滤’属性，点击**查询日期**>**数据**>**自动过滤**，**大区**设置同**查询日期**的设置，可以设置**查询日期**与**大区**的默认值
2. 点击**参数栏**>**高级**>勾选>**初始化查询**，启用初始化查询后，修改参数时查询默认不勾选
3. 给**查询**按钮设置交互，点击**查询**>**交互**>添加>**查询**，保存后点击查询按钮进行页面数据手动查询
## 仪表板手动查询{#instrument-panel}
仪表板手动查询页面数据主要有2种方式：
- [通过刷新数据交互手动刷新](#interactive)：通过设置数据刷新交互控制手动查询，过滤组件去掉自动过滤。
- [通过交互手动传递过滤条件](#parameters)：设置参数对数据进行手动查询，参数设置方法参考[设置参数](../dash/design/data/param.md#settings)，用参数来隔离过滤组件，数据集上使用参数过滤，过滤组件的值修改后，通过按钮将过滤组件的值设置到数据集的过滤参数上过滤。
[点击此处体验](https://demo.succbi.com/v5/bi/%E6%89%8B%E5%8A%A8%E6%9F%A5%E8%AF%A2%E9%A1%B5%E9%9D%A2%E6%95%B0%E6%8D%AE_1)
### 通过刷新数据交互手动刷新{#interactive}
将过滤条件全部采用全局参数控制实现手动查询页面数据具体步骤如下：
1. **查询日期**和**大区**下拉框取消勾选`自动过滤`，下拉框>**过滤**>**自动过滤**
2. 明细表所在的数据源勾选`手动刷新`与`初始时不查询`，**门店销售明细表**>右键设置>**查询**，勾选`手动刷新`与`初始时不查询`
3. 明细表所在的数据源添加过滤条件，依据下拉框选项进行过滤，**门店销售明细表**>右键设置>**过滤**
4. 给查询按钮设置交互，点击按钮添加**刷新数据**交互，具体设置参考[设置交互](https://docs.succapp.com/v5/rpt/action/invoke-component-method)
### 通过交互手动传递过滤条件{#parameters}
通过交互手动传递过滤条件具体操作如下：
1. 设置**参数**，添加**cxrq**和**dq**两个参数，无需设置默认值
2. **查询日期**和**大区**下拉框取消勾选`自动过滤`，下拉框>**过滤**>**自动过滤**
3. 设置数据集**过滤**条件，**门店销售明细表**>右键设置>**过滤**，添加**cxrq**和**dq**参数的过滤条件
4. 设置数据集**查询**条件，**门店销售明细表**>右键设置>**查询**，取消勾选**手动刷新**和**初始时不查询**
5. 给查询按钮设置交互，点击按钮添加**设置参数值**交互
---
url: "https://docs.succapp.com/v5/guide/data-viz/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/data-viz/errcode"
title: "数据可视化错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 数据可视化错误提示排查
---
url: "https://docs.succapp.com/v5/guide/report/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/overview"
title: "报表概述"
---
---
order: 8
navTitle: 报表
---
# 报表概述
!!!children (guide/report) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/report/new-report.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/new-rpt"
title: "新建报表"
---
---
order: 2
---
# 新建报表
新建一个报表步骤如下：
1. 进入项目的**分析**模块，点击**新建**，选择**报表**
2. 在新建对话框中可以选择内置的报表模板，也可以选择空白模板，进入[报表设计器](./designer.md)界面
3. 接下来点击左上角**添加**按钮添加数据模型，然后拖入维度、度量字段至相应的单元格，设置样式
4. 最后点击**保存**，在命名对话框中输入合适且有意义的名称即可
---
url: "https://docs.succapp.com/v5/guide/report/designer.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/designer"
title: "报表设计器界面介绍"
---
---
order: 3
navTitle: 报表设计器
---
# 报表设计器界面介绍
报表设计器是用来设计报表的可视化工具，使用类Excel的、基于单元格的、所见即所得的方式设计报表，报表设计器界面如下图：
报表设计器主要包括如下功能板块：
1. **数据源**：数据源区域列出了可以用于报表中的数据，可以增加数据模型、添加表内数据加工、定义数据间的关联关系、增加计算字段和删除数据模型
2. **组件区**：组件区提供了丰富的输入组件和媒体组件。输入组件主要是参数过滤用途，媒体组件包含富文本，图标，图片等
3. **参数栏**：将组件拖入至参数栏，用于对报表数据进行筛选或者进行查询、导出等操作
4. **工具栏**：工具栏通过选中单个单元格或多个单元格并点击相应的工具按钮，可实现插入行、插入列、删除行、删除列、设置单元格等功能。通过点击下拉面板中的选项可设置表格样式和条件样式
5. **表格区**：类似Excel的Sheet页面，对加入报表表格内容进行编辑，通过拖拽或双击的方式添加数据源中的维度和度量至单元格中，同时支持书写固定文本及表达式
- 列表头：选择列表头上的字母即可全选整列，如点击`D`，可选中该列单元格进行批量操作
- 行表头：选择行表头上的数字即可全选整行，如点击`6`，可选中该行单元格进行批量操作
6. **属性栏**：显示当前表格区或参数栏中选中对象的属性项和属性值，并可以对属性值进行修改，包括：数据、样式、交互等
## 报表设计器快捷键{#hotkey}
设计器快捷键：
| 功能 | Windows/Linux | macOS |
| ---------- | :---- | :---- |
| 保存 | `Ctrl + S` | `Command + S` |
| Undo | `Ctrl + Z` | `Command + Z` |
| Redo | `Ctrl + Y` | `Command + Y` |
| 复制 | `Ctrl + C` | `Command + C` |
| 剪切 | `Ctrl + X` | `Command + X` |
| 粘贴 | `Ctrl + V` | `Command + V` |
| 加粗 | `Ctrl + B` | `Command + B` |
| 斜体 | `Ctrl + I` | `Command + I` |
| 下划线 | `Ctrl + U` | `Command + U` |
| 当前行上面插入一行 | `Alt + Up` | `Alt + Up` |
| 当前行下面插入一行 | `Alt + Down` | `Alt + Down` |
| 当前列左边插入一列 | `Alt + Left` | `Alt + Left` |
| 当前列右边插入一列 | `Alt + Right` | `Alt + Right` |
| 当前列右边插入一列 | `Alt + Right` | `Alt + Right` |
| 垂直居上 | `Alt + T` | `Alt + T` |
| 垂直居中 | `Alt + M` | `Alt + M` |
| 垂直居下 | `Alt + B` | `Alt + B` |
| 删除行 | `Alt + R` | `Alt + R` |
| 删除列 | `Alt + C` | `Alt + C` |
| 合并单元格 | `Ctrl + M` | `Command + M` |
| 拆分单元格 | `Ctrl + P` | `Command + P` |
## 查看引用{#view-reference}
使用查看引用可以快速查看以及定位当前[模型表](./design/datasourse.md)、[组件](./components/input/input-box.md)、[参数](../data-viz/dash/design/data/param.md)以及[单元格](./design/data/README.md)在页面中被引用的地方。在设计器中，选中模型表或组件等对象，点击鼠标右键，在弹出的菜单中选择**查看引用**选项即可查看引用列表，点击内容，可定位到对应组件、单元格或数据源引用的位置，如下所示：
设计器中支持查看引用的内容如下：
- **数据模型查看引用**：可以查看模型或字段被哪些组件属性、单元格以及参数引用
- **组件查看引用**：可以查看选中组件被其他组件、数据源以及单元格引用情况
- **参数查看引用**：可以查看引用该参数的组件、数据源以及单元格列表
- **单元格查看引用**：可以查看引用该单元格的其他单元格、组件以及数据源引用情况
:::tip 引用单元格写法说明
- 单元格被组件等引用：在表达式中写法为工作表名+具体单元格，如`main.A4`
- 单元格被其他单元格引用
- 同一个工作表：可以直接写单元格名称，如`A4`
- 不同工作表：工作表名+具体单元格，如`main.A4`
:::
### 快速修改引用错误{#modify-reference-errors}
删除被引用的模型表、组件、参数以及单元格时，会弹出引用该内容的列表，当强制删除后，被引用的地方出现报错。同时右上角信息处会显示错误提示，点击可快速定位错误，也就是删除内容被引用的地方。
---
url: "https://docs.succapp.com/v5/guide/report/components/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/components"
title: "报表组件"
---
---
order: 4
navTitle: 报表组件
---
# 报表组件
---
url: "https://docs.succapp.com/v5/guide/report/components/input/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/input"
title: "输入组件"
---
---
order: 1
navTitle: 输入
---
# 输入组件
---
url: "https://docs.succapp.com/v5/guide/report/components/input/input-box.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/inputbox"
title: "输入框"
---
---
order: 1
---
# 输入框
输入框常用于手动输入参数，通过输入的内容对数据进行筛选。
## 示例
该示例展示的是通过输入框输入华北进行筛选，展示了华北地区销售数量情况：
## 取数
输入框的**字段**只能取一个维度或度量，如【大区】、【销售数量】等
### 操作步骤
1. 从**组件区**拖拽**输入框**组件至**参数栏**
2. 设置**字段**为**月销汇总表.销售单位.大区**
## 属性介绍
- 显示条件：设置输入框在满足一定条件时显示，参考[显示条件](#)
- 自动过滤：表示是否自动应用输入框中输入的内容对报表进行过滤，即筛选当选择的字段值等于输入框中输入的值。
---
url: "https://docs.succapp.com/v5/guide/report/components/input/combobox.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/combobox"
title: "下拉框"
---
---
order: 2
---
# 下拉框
下拉框主要用于显示维表（代码表、字典表等，如行政区划、产品类别等）数据，可以是单级列表或多级树形层次。
## 示例
|多级下拉框|单级下拉框|
|:-:|:-:|
|||
## 取数设置
下拉框的数据来源有两种，来自维表和用户自定义的[枚举值](#)
- 来自维表的数据在下拉框的**字段**中取一个维度，如【销售单位】、【颜色】等
- 用户自定义的下拉数据为常量时，直接点击**编辑枚举值**
## 属性介绍
下拉框具有以下基本属性：
- 数据格式：设置下拉框中的数据的显示格式，可选**标题**、**值**、**标题-值**
- 只选叶子节点：勾选后，只能下拉选择叶子节点，不能选择父节点。例如**颜色**字段，未勾选前，可以选择黄色系，即父节点，勾选后，只能选择黄色系下的颜色
- 为空时包含所有值：默认勾选，当下拉框的值为空时，默认不根据所选**字段**过滤
---
url: "https://docs.succapp.com/v5/guide/report/components/input/selectpanel.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/selectpanel"
title: "选择面板"
---
---
order: 3
---
# 选择面板
选择面板可以根据相应维度，对数据进行筛选
## 示例
选择面板组件里选择**上下装**，可以筛选出对应**上下装**的销售数据
## 取数设置
在数据里的字段下拉框，选择需要进行筛选的维度字段，如【大区】、【价格档次】
## 操作步骤
1. 从**组件区**拖拽**选择面板**至**参数栏**
2. 设置**字段**为【月销汇总表.上下装】
## 属性介绍
### 排列方式
可以设置面板中的数据为**横向**排列或**纵向**排列，默认为**横向**排列
---
url: "https://docs.succapp.com/v5/guide/report/components/input/date.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/date"
title: "日期"
---
---
order: 4
---
# 日期
日期组件可以对报表里的数据按照时间进行过滤，筛选出指定时间段内的数据。
## 示例
点击查询月份下拉框，选择月份，可以筛选出对应月份的销售数据
示例地址：[单向浮动表](https://demo.succbi.com/v5/DEMO/app/DEMO.app?id=%E5%8D%95%E5%90%91%E5%88%86%E7%BB%84)
## 取数设置
日期组件选择的数据类型只能是日期型，在字段下拉框里选择相应的日期字段，如【销售月份】
## 操作步骤
1. 下拉选择日期**字段**：【月销汇总表.销售月份.年月】
2. 设置**日期类型**为**年月**
3. 设置**默认值**为**2010年10月**
## 属性
### 默认值
默认值的单位受日期类型的影响，当日期类型为年时，默认值也只能选择年。默认值的设置类型有4类：
- 指定：选择指定的时间段为默认值
- 范围：自定义一个时间范围作为默认值
- 相对：设置一个时间锚点，选择该锚点前后一段时间作为默认值
- 表达式：设置表达式的计算结果作为默认值
### 日期类型
选择日期类型的单位为年，月，天等，日期的可选类型有8种：
- 自动：时间单位精确到日
- 年月日:时间单位精确到日
- 年月：时间单位精确到月
- 年：时间单位精确到年
- 半年：时间单位精确到半年
- 年季：时间单位精确到季度
- 年月旬：时间单位精确到月份的上中下旬
- 年周：时间单位精确到月份的第几周
### 最早/最晚
设置日期可选择的最早及最晚日期
### 允许选择相对值
勾选**允许选择相对值**后，可以设置**锚点日期**，并进行日期的偏移：
### 允许选择范围
勾选**允许选择范围**后，可以选择2个日期，作为起止日期范围：
---
url: "https://docs.succapp.com/v5/guide/report/components/input/button.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/component/button"
title: "按钮"
---
---
order: 5
---
# 按钮
按钮参数组件，一般用于需要有点击事件的情况下，如需要给报表添加一个查询按钮。\
**按钮**配合交互事件使用。
## 示例{#examples}
点击查询按钮计算报表：
示例地址：[查询](https://demo.succbi.com/v5/demo/%E6%A8%AA%E5%90%91%E5%B5%8C%E5%A5%97%E5%88%86%E7%BB%84)
## 操作步骤{#steps}
1. 从**组件区**拖拽**按钮**组件至**参数栏**
2. 修改按钮**内容**为**查询**
3. 添加交互：**交互**>**添加动作**>**查询**
## 更多{#more}
报表中提供了快捷的**导出**、**查询**组件，添加组件至参数栏，交互中自动添加了对应的**导出**或**查询**动作
### 导出{#export}
**导出**就是将报表导出为Excel文件至本地，在本地查看报表数据。
### 查询{#query}
**查询**组件用于计算报表结果，如切换报表筛选条件后，点击查询对报表结果重新计算。
### 设置方法{#setting-method}
#### 方法一{#method1}
1. 从**组件区**拖拽**导出**或**查询**组件至**参数栏**
#### 方法二{#method2}
1. 从**组件区**拖拽**按钮**组件至**参数栏**
2. 修改按钮**内容**为**导出**或**查询**
3. 添加交互：**交互**>**添加动作**>**导出**或**查询**
---
url: "https://docs.succapp.com/v5/guide/report/design/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/design"
title: "设计报表"
---
---
order: 5
navTitle: 报表制作
---
# 设计报表
---
url: "https://docs.succapp.com/v5/guide/report/design/datasourse.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/datasourse"
title: "为报表添加数据"
---
---
order: 1
navTitle: 引入数据
---
# 为报表添加数据
数据是报表页面中单元格以及组件的取数来源。添加的数据可以是**数据表**、**临时数据加工**以及**查询数据集**，添加到数据中的模型表即可用于单元格和组件取数。基于添加的模型可新建计算字段，以及模型设置，如过滤条件、参数设置、权限设置等。报表中添加数据模型及模型设置的方式与仪表板中一致， 可参考文档[为仪表板添加数据](../../data-viz/dash/design/datasource.md)。
---
url: "https://docs.succapp.com/v5/guide/report/design/data/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/set-data"
title: "单元格取数"
---
---
order: 2
navTitle: 单元格取数
---
# 单元格取数
在报表设计器中引入[数据模型](../../../data-gov/GLOSSARY.md#data-model)后，就可以正式开始制作报表了。报表最核心功能是将[数据表](../../../data-gov/GLOSSARY.md#data-table)的数据以表格的形式展示出来，接下来本文将重点围绕取数来介绍。
## 浮动单元格{#set-float}
在报表中使用浮动设置将[数据表](../../../data-gov/GLOSSARY.md#data-table)中满足条件的数据展示在结果页面，数据表返回的结果集是一个二维数组，该数组中的每一个元素对应报表结果页面的一个单元格。
浮动有如下几个概念需要了解：
- **浮动主单元格**：浮动主单元格是浮动的核心，浮动的设置是在该单元格上设置的。例如展示各个省份的销售数量，则这里的`省份`为浮动主单元格
- **浮动方向**：浮动的方向分为两个，分别是向下扩展和向右扩展。向下扩展即为纵向浮动，向右扩展为横向浮动
- **浮动区域**：浮动的扩展范围。在浮动区域内的行列，会跟随浮动主单元格一起根据浮动方向扩展。在**浮动主单元格**上设置的过滤条件，浮动区域内的单元格均会继承该过滤设置
浮动设置可以做分组查询和明细数据查询，两者区别如下：
- [分组查询](#float)：将满足条件的数据按照浮动维度进行分类汇总，相当于sql语句中的group by
- [明细数据查询](#queryselect)：查询结果的每条数据，均对应于数据库表原始行的一条数据。适用于查询数据清单场景
如何设置分组查询和明细数据查询，可以查看如下章节内容。
### 查询分组{#float}
以制作各省销售情况表为例，操作步骤如下：
示例地址：[单向浮动表](https://demo.succbi.com/v5/demo/单向分组)
- **设置浮动主单元格和浮动方向**：
- 方法一：从数据模型列表处，展开【门店】，将【省】拖拽到`A5`单元格中。通过该方法设置的浮动单元格，会根据当前设计器的表格布局自动设置浮动方向，浮动范围为整行
- 方法二：选中单元格`B5`，点击**工具栏**>**浮动**下拉选择`纵向浮动`
- **改变浮动范围**：选中浮动主单元格`A5`后，橙色边框圈出了浮动区域，鼠标移至橙色边框处，会出现箭头图标，拖动即可修改浮动范围
:::tip 浮动更多说明
- 浮动主单元格有一个蓝色箭头图标，箭头的方向即为浮动方向
- 当拖入维度到报表设计器中时，系统会根据拖入目标单元格的上侧/左侧单元格设置情况，来决定是否自动将目标单元格设置浮动主单元格及浮动范围。
:::
### 查询明细数据{#queryselect}
查询数据清单时可以使用查询明细数据功能，设置后显示的每条数据都对应于数据库表原始行的一条数据。查询明细数据和分组表查询的区分在于二者对计算结果的处理规则不同：
- **查询明细数据**：将满足条件的原始行数据全部显示出来
- **分组查询**：将满足条件的数据按照浮动维度进行分类汇总，相当于sql语句中的group by
如展示企业基本信息列表，操作步骤如下：
1. 选中[浮动单元格](#set-float)，如`B4`
2. 在右侧**属性栏**>**单元格**>**浮动**分组下，勾选**查询明细**即可实现
示例地址：[明细分页表](https://demo.succbi.com/v5/DEMO/app/DEMO.app?id=%E6%98%8E%E7%BB%86%E5%88%86%E9%A1%B5%E8%A1%A8&:play=true)
### 设置合并连续单元格{#merge-cell}
示例地址：[合并连续单元格](https://demo.succbi.com/v5/demo/合并连续单元格)
### 补全维项{#fill-dimension}
补全维项可以将没有数据的维项也在报表中展示出来。例如事实表中只有`上装`、`下装`的销售数据，没有`套装`的数据，希望在报表中将所有类型都显示出来，就可以用补全维项将所有维项展示。**补全维项**只能在[浮动主单元格](#set-float)上进行设置。
1. 选中上下装指标的单元格
2. 在**单元格**-**浮动**处勾选**补全维项**
### 过滤不在维项中的数据{#filter-dimension}
过滤不在维项中的数据可以过滤掉维表中不存在的维项数据。例如事实表的【上下装】字段中，有编码为`02`和`99`的数据，但在上下装维表中不存在编码为`99`的维项，如果只希望展示维表中存在的维项，就可以使用该功能过滤掉不在维表中的数据。**过滤不在维项中的数据**只能在[浮动主单元格](#set-float)上进行设置。
## 条件单元格{#conditioncell}
当设置某个单元格为条件单元格后，在固定范围内的其他单元格均会继承其在过滤器上设置的过滤条件。设置操作步骤如下：
示例地址:[分省销售情况表](https://demo.succbi.com/v5/DEMO/ana/报表/分组报表/固定分组交叉.rpt?:edit=true)
1. 选中需要设置的单元格，如`E4`
2. 点击**工具栏**>**条件**图标，按需调整固定范围
3. 在过滤器中按需添加过滤条件，如价格档位为`高档`
::: tip 条件单元格说明
- **条件单元格标识**：`E4`单元格有一个漏斗图标，表示`E4`单元格为**条件单元格**，固定范围是从`E4-E6`（橙色边框高亮出这片区域）
- **过滤条件继承**：`E4`单元格上有过滤条件，则该固定范围内的单元格均会继承该过滤条件
:::
## 过滤{#filter}
过滤是对报表中计算的数据进行限制和筛选，将满足过滤条件的数据显示到计算结果中。当选中某个单元格或工作表后可对其设置过滤条件和筛选条件。提供了2种过滤类型：
- 过滤器：对原始数据行进行过滤，过滤出符合条件的数据，类似于SQL中的where条件
- 筛选器：对结果集进行筛选，类似于SQL中的having条件，只能对[浮动主单元格](#set-float)进行筛选
示例地址：[数值分段表](https://demo.succbi.com/v5/DEMO/ana/报表/分组报表/钻取子表/数值分段表.rpt?:edit=true)
过滤条件存在继承关系，如下设置中，由上到下依次继承：
- **模型表**：右键模型表可对模型表设置过滤条件，作用范围为所有引用模型表的地方
- **工作表**：选中空白处可设置工作表的过滤条件，作用范围为整个工作表
- **浮动主单元格**：选中[浮动主单元格](#set-float)可设置浮动的过滤条件，作用范围为整个浮动
- **条件主单元格**：选中[条件主单元格](#conditioncell)可设置条件单元格的过滤条件，作用范围为整个条件范围
- **单元格**：选中单独的单元格可设置单元格的过滤条件，作用范围为单个单元格
::: tip
报表的过滤设置与仪表板的过滤设置操作基本一致，具体设置可查看[过滤](../../../data-viz/dash/design/data/data-filter/README.md)文档，但报表中不支持拖拽字段到[过滤器](../../../data-viz/dash/design/data/data-filter/README.md#过滤器)或[筛选器](../../../data-viz/dash/design/data/data-filter/README.md#筛选器)中
:::
[//]: # "选中单元格，在**单元格**中设置过滤器和筛选器。需要说明单元格、固定、浮动、工作表等条件的继承关系。"
## 排序{#sort}
报表提供了排序的功能，可以按照指定字段排序展示数据，以按各省销量降序展示销售情况为例，操作如下：
选中`A5`单元格，在右侧**属性栏**>**单元格**>**排序**下， 点击**添加**按钮，在弹出的排序对话框中按需添加排序字段
1. 点击**添加**按钮下拉选择`字段`选项
2. 分别选择`销售数量`、`降序`、`总计`
即可实现按`销售数量`降序展示数据。可以设置多个字段的排序，排序优先级是根据排序字段添加顺序依次生效，按照上述步骤继续添加字段即可实现。
示例地址：[单向分组排序表](https://demo.succbi.com/v5/demo/单向分组)
### 排序属性介绍{#sort-attr}
在弹出的排序对话框中，可以指定多个字段依次，也可以添加动态表达式：
- **字段**：
- 排序依据：选择数据模型中的字段作为排序字段
- 排序方式：按照排序依据选择字段进行`升序`或者`降序`排列数据
- 聚合方式：指定排序依据字段的聚合方式。当为\[明细查询]{#query-select}时，不能指定聚合方式
- **表达式**：可以编写表达式作为数据的排序依据，如`${[下拉框2].[值]} ${[选择面板1].[值]}` 第一个值为排序依据，第二个值是排序字段
- 分组表：需要三个动态参数，分别为排序依据、排序字段、聚合方式
- 明细表：需要两个动态值，分别为排序依据、排序字段
示例地址：[表达式动态排序](https://demo.succbi.com/v5/DEMO/ana/%E6%8A%A5%E8%A1%A8/%E6%B8%85%E5%8D%95%E6%8A%A5%E8%A1%A8/%E6%98%8E%E7%BB%86%E5%88%86%E9%A1%B5%E8%A1%A8.rpt?:edit=true)
### 点击列标题排序{#sort-title}
报表中也可以在单元格列标题上设置排序，即可在查看界面点击列标题上的**排序按钮**，使当前列的指标数据在升序、降序或不排序三种状态之间切换。排序按钮以图标形式显示当前排序状态。
只需在设计器选中对应列标题，在**属性栏**>**单元格**>**排序**中勾选**点击列头排序**，并设置相关属性即可：
- **排序单元格**：
- 自动：按照正下方浮动区域的单元格排序，若有嵌套浮动，则按照最上层单元格排序
- 自定义：可手动输入浮动区域的单元格进行排序，如`B5`
- **默认排序**：设置点击排序按钮后首次的排序方式，提供**升序**、**降序**两个选项
- **允许无排序**：不勾选，排序按钮只会在升序、降序两种状态间切换，勾选后，会增加**不排序**状态，即在三种状态之间切换
:::tip 更多说明
1. 列标题排序只会让浮动区域的单元格生效，如下方没有浮动单元格，也会显示排序按钮，但点击无效
2. 当浮动单元格上设置了默认的[字段排序](#sort)后，点击列标题排序，会以当前列标题指标优先排序
3. 同时只有一个列标题指标排序能生效，当依次点击多个列标题排序时，只生效当前点击的一个
:::
示例地址：[点击列标题排序](https://demo.succbi.com/v5/demo/单向分组)
## 更多设置{#more}
[//]: # "包括显示模式、提示等。"
---
url: "https://docs.succapp.com/v5/guide/report/design/style/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/table-style"
title: "样式设置"
---
---
order: 3
navTitle: 样式设置
---
# 样式设置
---
url: "https://docs.succapp.com/v5/guide/report/design/style/table-style.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/style/table"
title: "表格样式"
---
---
order: 1
---
# 表格样式
## 主题选择{#themes}
系统自带了多个[主题](../../manage-themes/README.md)，主题里面定义了常用的[单元格风格](#cell-style)，包括正文、大标题、小计等，一般使用风格就可以实现比较美观的报表了。\
如果自带的风格不能满足需求的，可以再单独设置每个[单元格样式](#cell)。
## 单元格样式{#cell}
### 单元格风格{#cell-style}
对报表来说，风格是单元格的所有属性样式的集合。每个[主题](../../manage-themes/README.md)中都存有10个默认的单元格风格，如正文、大标题1、行（列）标题\_一级标题等。可以随时对单元格风格进行一键切换，来应对不同的使用场景。\
在报表设计器中，选中单元格，在右侧**属性栏**>**样式**下可以使用和管理单元格风格：
- **新增风格**：当已有的风格都无法满足我们的需求时，我们可以通过点击风格列表右上角的\*\*＋号\*\*来新增风格。新增的风格默认为单元格当前样式风格
- **应用风格**：当我们需要快捷设置单元格样式的时候，可以应用风格，一键设置单元格的样式
- **更新风格**：当我们想要将当前样式覆盖到当前风格中时，可以更新风格
- **编辑风格**：编辑风格适用于需要手动调整风格的情况。点击编辑风格按钮可以打开风格管理，在风格管理中对当前风格进行编辑
- **重命名**：修改当前选中风格名称
- **删除**：删除当前选中风格
### 单元格大小{#cell-layout}
单元格大小用于设置单元格的**高度**和**宽度**。选中单元格，在**属性栏**>**样式**，展开**布局**属性，可以设置单元格大小：
- **高度**、**宽度**：决定单元格的行高和列宽，单位是px
- **自动撑大行高**：单元格设置**自动换行**后，勾选该属性，可以实现单元格的行高跟随文字高度自动撑大
- **自动撑大列宽**：勾选该属性后，可以实现单元格的列宽跟随文字内容自动撑大
- **最大宽度** ：当勾选了自动撑大列宽属性后，可以设置最大宽度。当单元格的内容超出宽度设置后，会自动撑大单元格宽度，宽度不会超过该属性的设置，单位是px。例如，设置单元格宽度为`100`，最大宽度为`200`：
1. 当内容长度未超过100px时，单元格宽度为100px
2. 当内容长度在100px-200px之间时，单元格宽度随内容自动撑大
3. 当内容长度超过200px时，单元格宽度只能撑大到200px
- **缩小字体填充**：未设置自动撑大行高或自动撑大列宽时，提供该属性设置。勾选后，单元格的内容超出宽度的设置时，文字会自动缩小显示，最小为12px
::: tip 自动撑大列宽计算
- 某一列有单元格勾选**自动撑大列宽**属性时，此列最终列宽的计算规则为：
1. 列宽跟随勾选该属性的单元格文字内容自动撑大
2. 该列勾选此属性的单元格宽度里，剔除大于单元格（随文字撑大单元格的内容）平均宽度+150px的特殊宽度，取剩下的最大宽度+20px作为此列自动撑大的列宽
3. 最终列宽须大于该列80%勾选此属性的单元格（随文字撑大单元格的内容）宽度，此项优先级高于第2条
4. 自动撑大后最终列宽不得超过800px，即当宽度撑大到800px后，不再撑大
5. 该列勾选此属性的单元格个数不超过200时，每个单元格都参与计算，超过时将通过采样计算自动撑大的列宽，参与采样计算的单元格个数不超过2000
效果展示：[自动撑大列宽](https://demo.succbi.com/v5/demo/自动撑大列宽)
:::
### 单元格字体样式{#cell-font}
选择单元格后，可以在**属性栏**>**样式**>**字体**中设置单元格的字体、形状、颜色和大小，同样的选择一列、一行或一片单元格，也可以进行批量设置。
- **字体**：提供多种常见的字体。点击字体下拉框进行设置，支持用户按需进行[字体扩展](../../../dev/extension/extension-points/font.md)
- **形状**：提供四种形状，分别是**粗体**、*斜体*、下划线、~~删除线~~。点击选择字体形状按钮进行设置，允许同时选择多种形状
- **颜色**：单元格文字的显示颜色。点击颜色区域，下拉展开主题色板进行设置，默认为主题色板第一行的第二个颜色，支持用户按需自定义颜色，具体操作参考文档[制作自定义主题](../../manage-themes/custom-themes.md)
- **大小**：单元格文字的显示大小，单位是px，默认是12px。如果在**属性栏**>**布局**中勾选了[缩小字体填充](#layout)，文字的大小会根据单元格内容长度自动缩小显示
### 单元格文字显示格式{#cell-format}
选择一个或多个单元格，可以在**属性栏**>**样式**>**字体**中设置，将单元格内文字（包括数字、日期、字符串等）按照指定格式显示出来，支持用户添加和管理自定义显示格式，具体的规则和语法参考文档[显示格式](../../../data-viz/dash/design/data/displayformat.md)。
### 单元格文字对齐方式{#cell-align}
对齐属性用于设置单元格内文字的对齐方式。选中单元格，在**属性栏**>**样式**，展开**字体**属性，选择需要设置的对齐方式。单元格提供4种类型的对齐方式：
- **横向对齐**：左对齐、居中、右对齐、两边对齐、自动对齐（适用于单元格内容为字段的情况，数值型居右，非数值型居左）
- **纵向对齐**：垂直居上对齐、垂直居中对齐、垂直居下对齐
- **缩进**：输入数值，单位是px，和横向对齐有关系
- 左对齐、两边对齐：朝右缩进
- 右对齐：朝左缩进
- 居中：缩进无效
- **自动换行**：勾选自动换行后，当单元格文本长度超过列宽时，会自动换行显示
::: tip 文字过长自动换行说明
若文字过长，设置了**自动换行**后，行高不会自动撑大，如需行高跟随文字高度自动撑大，需要在**样式**>**布局**下勾选**自动撑大行高**属性。
:::
**输入组件标题的对齐方式**
输入组件的标题可以设置文字的对齐方式。选中组件的标题，在**属性栏**>**样式**，展开**字体**属性，组件标题提供了水平方向的4种对齐方式，包括：左对齐、居中、右对齐、两边对齐。
### 单元格前后缀图标{#cell-icon}
报表支持设置单元格的前缀图标和后缀图标。选中单元格`B3`，在**属性栏**>**样式**中展开**图标**分组，可以分别设置图标前后缀的**图标来源**、**大小**、**颜色**三个属性。其中，**图标来源**属性设置可以参考仪表板的[图标来源](../../../data-viz/dash/components/more/icon.md#source)文档。
图标的位置受单元格[内边距](#cell-padding)影响，给单元格设置左右边距后，图标会随单元格文字内容左移或右移。
:::tip 设置动态前后缀图标
支持给单元格设置动态的前后缀图标，例如单元格数值大于`1`时图标为绿色，单元格数值小于`1`时图标为红色，设置说明可以参考[条件样式](./condition-style.md)文档。
:::
### 单元格背景填充{#cell-bgfill}
报表支持设置单元格的背景填充样式。选中单元格`A3`，在**属性栏**>**样式**中展开**填充**分组，系统提供三种填充方式：**无填充**、**颜色填充**、**图片填充**，具体设置及区别参考文档[背景](../../../app/superpage/design/style/README.md#filling)。
### 隔行换色{#cell-even-backgroud}
**隔行换色**可以实现浮动范围内的数据行奇偶行颜色各异。如隔行换色展示各省的销售情况，操作步骤如下：
1. **启用隔行换色**：选中浮动主单元格`A5`，在右侧**属性栏**>**样式**>**填充**展开，勾选**隔行换色**
2. **设置标题行/列数**：默认值为0，当需要前面两列为标题列，不希望参与隔行换色，则设置值为`2`
示例地址：[分省销售情况表](https://demo.succbi.com/v5/demo/单向分组)
:::tip 隔行换色说明
1. 在报表[主题](../../manage-themes/README.md)中，已经配置了符合当前主题风格的**隔行换色**颜色。切换主题时，该颜色也会发生变化
2. **隔行换色**功能设置的是偶数行的颜色，奇数行的颜色继承单元格上设置的背景颜色
3. **设置标题行/列数**该属性设置为0时，即不启用该功能。如果浮动范围内的标题行或者列，不希望参与各行换色，则通过设置标题行的功能实现。例如设置值为`2`，则隔行换色不作用前两列
:::
### 单元格边框{#cell-border}
边框属性用来设置单元格的边框和内部斜线。选中`A3`单元格，在右侧属性栏**样式**>**边框**中进行设置
- **位置**：上边框、右边框、下边框、左边框、内部斜线
- **样式**：提供几种常用的样式。选择常用样式后，下方的自定义样式会随之变化
- **自定义样式**：
- 线型：虚线、实线、点线
- 颜色：边框线颜色
- 粗细：线条宽度
### 斜线单元格{#cell-set-diagonal}
斜线单元格是统计报表中常见的操作，系统内置了多种斜线类型可供选择。\
选中`A3`单元格，在右侧**属性栏**>**样式**>**边框**中，点击**设置内部斜线**按钮，弹出设置单元格斜线样式对话框：
- **类型**：下拉按需选择合适的斜线类型
- **自定义样式**：设置显示的边框类型、颜色和粗细
- **区域文字**：设置斜线单元格区域文字，可以双击修改
### 动态斜线单元格{#cell-set-diagonal-auto}
动态斜线适用于报表行列动态变化的场景。\
选中`A3`单元格，在右侧**属性栏**>**样式**>**边框**中，点击**设置内部斜线**按钮，弹出设置斜线单元格对话框
- **类型**：下拉选择`动态斜线`
- 区域文字：可输入动态宏表达式，支持从参数栏组件进行获取。例如，报表行列标题由组件cx1、cx2、cx3决定，`${if(cx1!='',cx1+"|")}|${if(参数2!='',参数2+"|")}|${if(参数3!='',参数3+"|")}`
- **自定义样式**：设置显示的边框类型、颜色和粗细
### 单元格内边距{#cell-padding}
报表支持给单元格设置内边距，内边距数值越大，单元格内容与边框距离越远。选中单元格`A3`，可以在**属性栏**>**样式**>**内边距**中设置单元格的上、下、左、右内边距，单位为px。
## 行/列样式{#row-col}
当一行一列或多行多列单元格的样式一致时，可以直接点击行表头或列表头，批量设置行/列样式。行/列样式起到批量为单元格设置样式的作用，当设置行列样式之后，会把行列区域里所有单元格样式更新。
### 行/列的高度和宽度{#row-col-size}
点击行表头选中第三行，在右侧**样式**>**布局**中，可以输入数值批量设置单元格行高，单位是px，设置列宽操作同理。
### 整行字体属性{#row-col-font}
点击行表头选中第三行，在右侧**样式**>**字体**中，可以批量设置整行单元格的字体属性：
- **字体样式**：设置方法参考文档[单元格字体样式](#cell-font)
- **对齐方式**：设置方法参考文档[单元格文字对齐方式](#cell-align)
### 整行背景填充{#row-col-bgfill}
点击行表头选中第三行，在右侧**样式**>**填充**中，可以设置整行单元格的背景填充方式，具体方法参考文档[单元格背景填充](#cell-bgfill)。
### 整行单元格的内边距{#row-col-padding}
点击行表头选中第三行，在右侧**样式**>**内边距**中，输入数值，可以设置整行或整列单元格的上下左右内边距，具体方法参考文档[单元格内边距](#cell-padding)。
### 行/列显示{#row-col-visible}
对于报表中的单个单元格，无法对其设置**显示**属性，只能对整行或整列进行设置。点击行表头选中第三行，在右侧**样式**>**显示**中，可以设行的显示属性，提供如下选项：
1. **显示**
2. **隐藏**
3. **`条件`**：表达式动态设置行列的显示隐藏。当表达式返回true则显示行列，返回false则不显示行列
## 工作表样式{#sheet}
工作表中可以设置当前工作表的整体样式，如[画布样式](#sheet-fill)、[表体位置](#sheet-position)等。点击画布空白处，右侧属性栏即显示为工作表相关设置。
### 画布填充{#sheet-fill}
可以设置当前工作表的画布背景，在**属性栏**>**工作表样式**>**画布**>**填充**中设置，支持**无填充**、**颜色填充**以及**图片填充**三种填充方式，具体可查看文档[填充](../../../app/superpage/design/style/README.md#filling)。
### 画布内边距{#sheet-padding}
可以设置画布的内边距，即当前工作表的表体与画布边框之间的距离，单位为`px`，在**属性栏**>**工作表样式**>**画布**>**内边距**中设置。
### 表体显示位置{#sheet-position}
可以设置查看界面中，工作表在画布上的显示位置为**居左**或**居右**。在**属性栏**>**工作表样式**>**表体**>**布局**>**位置**中设置：
### 一键修改单元格内边距{#all-padding}
报表中单元格的内边距支持一键修改，在**属性栏**>**工作表样式**>**单元格**>**内边距**中设置即可。如果想单独修改某个单元格内边距，需在[单元格内边距](#cell-padding)中设置。
:::tip 单元格内边距设置优先级
1. 单独设置每一个单元格的内边距优先级最高
2. 一键修改只针对未设置过单元格内边距的单元格，并将内边距值也写入对应单元格下的内边距中
:::
---
url: "https://docs.succapp.com/v5/guide/report/design/style/condition-style.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/condition-style"
title: "condition-style"
---
---
order: 2
navTitle: 条件样式
---
# 条件样式
使用条件样式可以实现使用样式标注符合规则的数据，可以帮助直观查看数据、发现关键数据问题和数据的变化趋势。例如：
- 使用红色文字标注同比增幅小于10%的省份
- 使用不同的图标标注计划完成情况，绿色图标表示完成度超过90%
条件样式可以根据指定的条件动态更改单元格的外观，如果满足条件则设置作用范围内单元格的样式，否则不生效。
报表的条件样式包括[突出显示](#highlight)、[最前最后](#first-last)、[数据条](#databar)、[色阶](#color-scale)、[步进器](#stepper)、[图标集](#icon-set)这六种，可以根据应用场景选择合适的类型。
|突出显示 | 最前最后 | 数据条|
|:-:|:-:|:-:|
 |  | 
|色阶 | 步进器 | 图标集|
 |  | 
## 使用条件样式{#usage}
设置条件样式的入口在报表设计器顶部的工具栏，选中单元格后单击工具栏中的**条件样式**，即可弹出条件样式的设置对话框。下面以标注增幅为例来介绍具体的操作步骤
示例地址：[条件样式](https://demo.succbi.com/v5/bi/%E5%8D%95%E5%90%91%E5%88%86%E7%BB%84)
1. **选中单元格**：在表格区域选择`C5`单元格
2. **添加条件样式**
- 打开设置面板：在顶部工具栏中，点击**条件样式**打开设置对话框
- 添加：点击**添加**来新增一个突出显示的条件样式
- 重命名：鼠标滑动至新增的条件样式上，单击**重命名**，更名为`增幅大于0`
3. **设置规则**
- 设置作用作用范围：默认是第一步中选中的单元格`C5`，这里增加一个单元格，设置为`C5,E5`，具体语法规则见[作用范围](#range)
- 设置条件规则：选择**当前值**-**大于**-0
4. **设置样式**：在样式栏下拉选择主题风格`值大于0`
5. **新增第二个条件样式**：按照上述流程新增一个条件样式或**复制**前面新增的条件样式，并将其重命名为`增幅小于0`，规则设置为**当前值**-**小于**-0，然后选择风格`值小于0`
6. **保存条件样式设置**：点击对话框上的**确定**按钮保存当前条件样式设置
## 条件样式设置{#conditionstyles-set}
设置条件样式的对话框大体分为四个部分，分别是添加条件样式区、规则设置区、样式设置区以及预览区。添加的条件样式只会对满足规则、且在作用范围内的单元格生效，生效后展示的效果即是它在**样式设置区**所设置的效果
1. **添加条件样式区**
- 显示样式规则：若是希望查看当前选中的单元格上的条件样式，则可以选择**当前选择**。若希望查看全表的条件样式，则可以选择**当前工作表**。默认为**当前选择**
- 添加：可以点击**添加**按钮，添加突出显示、数据条、色阶等六种条件样式，且可以对条件样式进行**重命名**、**复制**、**删除**的操作，详见[添加条件样式](#add)
2. **规则设置区**
- 规则类型：可切换条件样式类型
- 作用范围：设置当前条件样式可生效的单元格，详见[作用范围](#range)
- 规则：每种条件样式的规则都有其特殊性，将在每种条件样式下单独介绍
3. **样式设置区**：不同类型的条件样式的属性不一样，可通过样式设置实现不同的效果
4. **预览区**：设置完样式后可在预览区预览效果
### 添加条件样式{#add}
下面以具体的操作来看一下如何添加条件样式，对条件样式进行**重命名**、**复制**、**删除**等操作
示例地址：[添加条件样式](https://demo.succbi.com/v5/DEMO/ana/report/float/float/%E5%8D%95%E5%90%91%E5%88%86%E7%BB%84.rpt?:edit=true&:sheet=main)
### 作用范围{#range}
- **如何设置作用范围为几个不连续的单元格？**
- 可在工作表中按住CTRL键同时选中多个单元格后，打开条件样式的对话框进行设置
- 当选择工作表中的某一个单元格，并完成了条件样式的设置，但此时又希望同样的条件样式作用在另一个或另外多个不连续的单元格时，可在**作用范围**的输入框中输入对应的单元格并用英文逗号分隔；例如`A5,C5,E5`
- **如何设置作用范围为几个连续的单元格？**
- 可在工作表中用鼠标框选多个单元格后，打开条件样式对话框进行设置
- 直接在条件样式对话框中的**作用范围**处设置连续的单元格，用英文冒号表示连续；例如`A5:D5`
**总结**：作用范围有两种语法，连续单元格用英文冒号`:` ，非连续单元格用英文逗号`,` ，两种语法可以混用，例如`A5:D5,H6`
## 突出显示{#highlight}
突出显示的条件样式可以给满足条件的数据设置不同的字体、填充、图标前后缀等内容，一般用于对增幅进行标注，例如增幅大于0显示为绿色，增幅小于0则显示为红色。操作步骤参考[使用条件样式](#usage)
示例地址：[突出显示](https://demo.succbi.com/v5/bi/%E7%AA%81%E5%87%BA%E6%98%BE%E7%A4%BA)
### 规则设置{#highlight-rule}
在条件样式对话框中的**规则设置区**提供了突出显示的规则相关的设置，满足规则时条件样式才会生效，突出显示的规则提供了三种类型的设置
- **当前值**：为默认选项，当前作用范围内的单元格的值满足设置的条件后，条件样式即可生效，通常都会采用这种方式
- **公式**：可以写表达式条件，表达式中可以引用其他单元格或组件的值；例如：`[main].B5>0`
- **总是生效**：没有条件，条件样式总是生效的
### 样式设置{#highlight-style}
在条件样式对话框中的**样式设置区**提供了突出显示的样式相关属性设置，系统中每个报表主题内均已提前预设了一些简单的条件样式风格，直接选择即可复用，也可以自行设置后将其保存为对象内或主题内的风格，样式设置的所有相关介绍见[报表样式](./table-style.md#css)
- **添加**：将当前设置好的样式保存为“对象内”或“主题”的风格
- 对象内：只作用于当前报表页面
- 主题：会存储在主题中，所有使用该主题的报表，均可以使用
- **管理样式**：可对当前已经存在的风格进行重命名、复制、删除的操作
- **保存样式**：若是在当前选择的风格上进行了调整，且希望其他使用该风格的地方也延用这些调整，就可以保存样式
## 最前最后{#first-last}
最前最后的条件样式可以给满足条件的数据设置不同的字体、填充、图标前后缀等内容，一般用于对TOPN进行标注，例如前五名使用绿色背景填充，后五名使用红色背景填充。操作步骤参考[使用条件样式](#usage)
示例地址：[最前最后](https://demo.succbi.com/v5/demo/%E6%9C%80%E5%89%8D%E6%9C%80%E5%90%8E)
### 规则设置{#first-last-rule}
在条件样式对话框中的**规则设置区**提供了最前最后的规则相关设置
- **前-数字**：将数据进行**降序排列**时的前N个，输入框中的有效输入为大于0的整数
- **前-百分比**：将数据进行**降序排列**时的前N%，输入框中的有效输入为0到100之间的数值，输入10时即为10%
- **后-数据**：将数据进行**升序排列**时的前N个，有效输入为大于0的整数
- **后-百分比**：将数据进行**升序排列**时的前N%，有效输入为0到100之间的数值，输入10时即为10%
### 样式设置{#first-last-style}
在条件样式对话框中的**样式设置区**提供了最前最后的样式相关属性设置，同突出显示的[样式设置](#highlight-style)
## 数据条{#databar}
数据条可以使当前单元格的数据根据大小显示成长短不一的横向柱子，能够更加直观的看到数据趋势，如下动图所示是设置数据条的方式，详细操作步骤介绍见[使用条件样式](#usage)
示例地址：[数据条](https://demo.succbi.com/v5/demo/%E6%95%B0%E6%8D%AE%E6%9D%A1_1)
### 规则设置{#databar-rule}
在条件样式对话框中的**规则设置区**提供了数据条的规则相关的设置
- **显示字段值**：勾选该属性后，数据条上会显示数值，默认是勾选的
- **最小值/最大值**：设置最小值/最大值有如下五种设置方式
- 最小值/最大值：直接以当前单元格的最小/最大数据，作为最小/最大值，无需输入
- 数字：直接手动输入一个固定的数值作为最小/最大值
- 百分点值：有效输入为0到100之间的数值
- 计算原理：使用EXCEL中的`PERCENTILE.INC()`函数来计算，实际返回值为`PERCENTILE.INC(array,百分点值)`，详细介绍见[EXCEL的帮助文档](https://www.office68.com/excel/24261.html)
- 公式：支持写[表达式](../../../exp/README.md)，如`[main].B4`
- 百分比：使用百分比可确保值的分布是成比例的，有效输入为0到100之间的数值
- 计算原理：实际返回值是`min+(max-min)×百分比`，公式中的max和min是指当前单元格内的数组的最大值和最小值
### 样式设置{#databar-style}
- **正值填充**：设置数据条的填充方式，并设置`值>0`时数据条的颜色
- **方向**：可选择方向是**从左到右**还是**从右到左**，即选择正值数据条的坐标轴是在左侧还是右侧
- **宽度**：设置数据条的高度占单元格的百分比，可设置范围为0%到100%
- **边框**：设置正值数据条的边框样式，包括线条的类型、颜色及粗细
- **负值填充**：设置`值<0`时数据条的颜色
- **坐标轴位置**：设置处于正值数据条与负值数据条中间的坐标轴的位置，当数据有正有负时才会显示，有如下三种选择
- 自动：系统根据数据自行调整坐标轴位置
- 中间点：处于单元格的正中间
- 无：不显示坐标轴
- **坐标轴**：设置坐标轴的线条样式及颜色、粗细
- **边框**：设置负值数据条的边框样式，包括线条的类型、颜色及粗细
## 色阶{#color-scale}
色阶可以根据当前单元格的数据大小给背景填充深浅不一的颜色，如下动图所示是设置色阶的方式，详细操作步骤介绍见[使用条件样式](#usage)
示例地址：[色阶](https://demo.succbi.com/v5/demo/%E8%89%B2%E9%98%B6)
### 样式属性{#color-scale-style}
- **色阶**：直接从主题自带的几组渐变色中选择色阶的填充色
- **最小点/中间点/最大值**：设置最小点/中间点/最大值，以及对应的填充色。其中最小点/中间点/最大值的几种设置项的原理同数据条的[规则设置](#databar-rule)
- **倒序**：勾选倒序后，背景颜色越深表示数值越小，背景颜色越浅表示数值越大
## 步进器{#stepper}
步进器可以根据数据的大小填充不同个数的图标，常用于占比或评分，如下动图所示是设置步进器的方式，详细操作步骤介绍见[使用条件样式](#usage)
示例地址：[步进器](https://demo.succbi.com/v5/demo/%E6%AD%A5%E8%BF%9B%E5%99%A8)
### 规则设置{#stepper-rule}
在条件样式对话框中的**规则设置区**提供了数据条的规则相关的设置
- **显示字段值**：勾选**显示字段值**后即可同时在单元格内展示步进器和数值
- **类型**：根据数据类型选择即可
- 离散：离散型的图标是完整的，不会出现显示半个的情况
- 连续：连续是根据实际值来显示图标，可能会出现高亮半个图标的情况
- **最大值**：可以通过**固定值**或者**公式**的方式设置最大值，也可以直接使用当前单元格数据的最大值。最大值与图标数相呼应，当图标全部显示或全部高亮时对应的值即是最大值
- **图标数**
- 当**类型**为`离散`时，是指最多显示N个图标，不论当前单元格内的数值多大，显示的图标数量不会超过N个
- 当**类型**为`连续`时，设置的是作为背景的图标数量，例如当图标数为5、评分为1分时，仍固定显示5个图标作为背景，只有1个图标被高亮
|离散 | 连续 |
|:-:|:-:|
 | 
### 样式属性{#stepper-style}
- 当步进器的**类型**为`离散`时，可设置图标、图标大小、图标颜色、间距等属性
- 当步进器的**类型**为`连续`时，可设置图标、图标大小、高亮颜色、背景、透明度、间距等属性
## 图标集{#icon-set}
使用图标集可以对数据进行注释，并可以将数据分为几个类别，每个图标代表一个值或者一个值的范围，如下动图所示是设置图标集的方式，详细操作步骤介绍见[使用条件样式](#usage)
示例地址：[图标集](https://demo.succbi.com/v5/demo/%E5%9B%BE%E6%A0%87%E9%9B%86)
- **类型**：根据数据类型选择即可
- 离散：适合于离散型数据，可设置每一个值对应要展示的图标和图标颜色。常用于对状态进行标注，例如将`待审核`、`审核通过`、`驳回`这三种状态使用不用的图标进行标注
- 连续：适合于连续型数据，可设置区间值，以及这个区间内的值对应要显示的图标，且可以设置图标颜色。常用于对完成率进行标注，例如完成率高于95%时显示绿色圆形图标，低于80%时显示红色圆形图标
- **图标集**：如主题中有配置好的图标集风格，可直接选择使用
---
url: "https://docs.succapp.com/v5/guide/report/design/paramsbar/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/paramsbar"
title: "参数栏"
---
---
order: 6
---
# 参数栏
常用的报表会需要一些条件筛选出对应的数据，参数栏就是用来放置这些筛选条件的，如在参数栏放置一个时间的下拉框筛选出对应时间的数据，放置这些筛选条件的方式有两种：
- 将参数组件拖入参数栏，并设置组件的相关属性
- 将[模型字段](../../../data-gov/GLOSSARY.md#data-model)拖入到参数栏，参数栏会根据字段的类型生成对应输入组件，比如拖入`销售日期`字段到参数栏，会自动生成日期组件
示例地址：[单向分组](https://demo.succbi.com/v5/demo/%E5%8D%95%E5%90%91%E5%88%86%E7%BB%84)
## 布局设置{#layout}
参数栏支持设置其内部布局，点击参数栏的空白处，在设计器的右侧栏显示的**属性栏**>**内部布局**处可以设置。
- **对齐方式**：控制参数栏中各组件的对齐方式，如`左对齐`，`水平居中`，`右对齐`。未勾选**与表体对齐**属性时参照画布对齐，勾选**与表体对齐**属性后参照表体对齐
- **行间距**：设置参数栏内组件的行间距，参数组件换行可以使用[换行符](https://docs.succapp.com/v5/rpt/component/warp)组件
- **与表体对齐**：勾选表示参数栏内的组件与表体对齐，与表体对齐的方式在**对齐方式**属性中设置
## 样式设置{#style}
参数栏同样支持样式设置，包括填充与内边距，具体介绍如下：
- **填充**：在**属性栏**>**填充**可以设置参数栏的填充效果，包括`无填充`、`颜色填充`、`图片填充`
- **内边距**：在**属性栏**>**内边距**可以设置参数栏的内边距
## 设置打开报表时显示表体内容{#initializtion}
想要打开报表后查询结果自行加载，或只有在点击了查询按钮后才加载查询结果，就可以在**属性栏**>**高级**处进行设置。具体属性介绍如下：
- **初始化时查询**：默认勾选，勾选表示打开报表后查询结果自行加载出来，不勾选时需要搭配`查询`按钮使用，只有在点击了查询按钮后才加载查询结果。如：[横向嵌套分组](https://demo.succbi.com/v5/demo/%E6%A8%AA%E5%90%91%E5%B5%8C%E5%A5%97%E5%88%86%E7%BB%84)
- **修改参数时查询**：默认勾选，表示修改参数栏中组件的值会加载查询结果，比如修改时间下拉框中的选中时间，报表会加载出该时间的查询结果
## 相关文档{#docs}
- 输入组件自带过滤功能，设置自动过滤属性后，系统会自动根据输入组件指定的字段过滤数据，更多信息可以查看[下拉框](../../components/input/combobox.md)文档
- 在报表的右侧属性栏中，也提供了过滤功能，在过滤器中也可以实现数据筛选，更多信息可以查看[过滤器](../data/README.md#filter)文档
- 参数栏组件的默认值可以通过设置参数动态控制，也可以通过URL传递参数值控制组件的默认值，更多信息可以查看[参数](../../../data-viz/dash/design/data/param.md#url-param)文档
- 参数栏中下拉框可实现参数联动，如大区-省-市-门店联动，在选择了某大区后，省的下拉列表中只会显示该大区对应的省，以及市和门店也只显示对应根节点下的数据，更多信息可以查看[下拉框](../../components/input/combobox.md)文档
---
url: "https://docs.succapp.com/v5/guide/report/design/properties/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/properties"
title: "报表属性"
---
---
order: 7
navTitle: 报表属性
---
# 报表属性
## 冻结行列{#frozencell}
当报表的水平或垂直方向超过了一页的宽度时，可以通过设置冻结行列，实现在滚动表格到另外区域时，特定的行和列仍然可见。
冻结行列只能冻结单元格上侧的行和左侧的列。
### 添加冻结行列{#frozencell-how}
在报表设计器中，点击工作表的空白处，在右侧**属性栏**>**冻结行列**设置，操作如下：
1. **冻结单元格**：设置`B5`，当滚动表格时，B5单元格的上方和左侧是一致可见的
2. **设置冻结线显示的范围**：可设置行标题(列标题)上不显示冻结线
1. 显示行：设置`3`到`5`行，1、2行分别是标题和说明文字，不会显示冻结线
2. 显示列：设置`A`到`G`行，表示冻结线显示列的范围
::: tip 冻结说明
- **快捷设置冻结**：选中`B5`单元格，右键选择`冻结窗格`，同样可以达到效果。但是冻结线显示范围仍然需要在工作表属性上设置
- **取消冻结**：操作方式类似冻结操作。也可以选中任意单元格，右键选择`取消冻结`
:::
冻结规则示例如下：
|冻结内容|冻结单元格属性|
| :---------| :--------:|
|冻结首行|A2|
|冻结首列|B1|
|冻结首行和首列|B2|
|冻结第一行，冻结A/B列|C2|
|冻结前两行，冻结第一列|B3|
### 设置冻结线的样式{#frozencell-style}
系统自带的每个主题都带有冻结线的样式配置，也可以在工作表中自定义设置。选中工作表空白处，在右侧**属性栏**>**样式**>**表体**中，展开**冻结线**，可以设置颜色和线条粗细（单位为px）。
## 报表分页{#page}
报表数据量比较大时，可以设置数据分多页展示，便于查看数据。设置报表分页操作步骤如下：
1. **启动分页**：选中浮动主单元格，在右侧**属性栏**>**单元格**>**浮动**下，勾选**启用分页**
2. **设置分页属性**：点击工作表的空白区域，在右侧**属性栏**>**工作表**下，展开分页即可设置。这些属性均有默认设置，可以按需修改
- 每页行数：每页显示的数据条数
- 对齐：分页栏在报表底部的显示位置，可以设置为居左、居中或居右
- 页码翻页：勾选后显示页码数字，可以点击数字跳转
- 页码样式：页码数字的背景样式
- 跳转翻页：勾选后在分页栏显示页码输入框，输入页码点击跳转翻页
- 显示总行数：勾选后在分页栏显示报表数据的总条数，查询总条数会耗费额外的数据资源
示例地址：
[明细分页表](https://demo.succbi.com/v5/demo/明细分页表/play)
::: tip 分页设置说明
一个工作表中，同时只能允许一个浮动范围设置了分页。如果有多个浮动范围启用了，只会第一个生效。
:::
## 打印{#print}
报表支持打印功能，在设计器左上角，点击**文件**>**报表选项**>**打印**可以设置打印属性。
### 打印页面排版设置{#print-typesetting}
报表支持对打印页面进行相应排版的设置，基本属性如下：
- **纸张大小**：可根据需要选择常见的纸张类型，如`A4`，`A5`。也可以选择自定义大小，自定义宽和高（厘米）
- **起始页码**：一般用于自定义选择打印页面时，对页码的控制。如设置**起始页码**为`2`，打印第一页的页码就为2。选择打印的**页面**为`仅限页码为偶数的页面`时，包括第一页在内的其他页码为偶数的页面就会被打印
- **缩放**：可根据需要选择`根据纸张调整缩放`或者`自定义缩放比例`
- 根据纸张调整缩放后：可根据需要选择将`整个报表打印在一页`、`所有列打印在一页`、`所有行打印在一页`、`自定义`
- 自定义缩放比例：可自定义设置缩放百分比
- **垂直居中**：默认不勾选表示居上，勾选表示表体在页面垂直居中
- **水平居中**：默认勾选，勾选表示表体在页面水平居中，不勾选表示居左
- **页眉**：可以设置页眉，以及页眉到页面顶部距离
- 页眉显示格式：可设置为`无`、`第1页`、`第1页，共？页`
- 距离：后边的距离框，可调整页眉与页面顶部的距离（厘米）
- **页脚**：可以设置页眉，以及页眉到页面底部距离
- 页眉显示格式：可设置为`无`、`第1页`、`第1页，共？页`
- 距离：后边的距离框，可调整页眉与页面底部的距离（厘米）
### 打印区域设置{#print-area}
打印时，可以对打印的区域进行设置。以下方打印报表前10行为例：
1. 报表标题部分制作
2. 在**文件**>**报表选项**>**打印**>**打印区域**处进行设置，如`A1:G10`
3. 门户查看界面查看点击**打印**按钮查看打印效果
### 分页打印设置{#print-paging}
报表支持对分页打印进行如下设置：
- 数据量过多分页后，后面的分页没有标题行，可将指定区域设为分页的标题行
- 双面打印，一侧装订时，可将奇数页和偶数页的左右边距对调，实现正反页的边距一致
示例地址：[奇偶页对称页边距](https://demo.succbi.com/v5/demo/奇偶页对称页边距)
1. 报表标题部分制作
2. 在**文件**>**报表选项**>**打印**>**顶标题行**处进行设置，如想要第三行为分页标题行，就可以设置为`3`
3. 勾选**对称页边距**
4. 门户查看界面查看点击**打印**按钮查看打印效果
### 套打{#print-chromatography}
套打一般用于单据或者凭证上，将已有内容按一定的格式打印出来，以下方打印发票为例：
1. 报表表体部分制作
2. 在**文件**>**报表选项**>**打印**处勾选**套打**进行设置
3. 门户查看界面查看点击**打印**按钮查看打印效果
示例地址：[发票套打](https://demo.succbi.com/v5/demo/发票套打)
:::tip 打印小贴士
需要在[权限](../../../permission/grant/operations.md#action)操作处勾选打印功能，才能在门户查看界面打印报表。
:::
### 更多打印场景{#print-more}
- 如果一个报表使用了下拉框或其他输入组件筛选数据，想要实现打印全部数据，可以采用脚本实现。具体设置可见：[DEMO](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=打印多条数据)
- 想要实现自行选择报表的打印行数，支持用脚本实现。具体设置可见：[DEMO](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=增量打印)
## 水印{#watermark}
报表支持设置水印，在设计器左上角点击**文件**>**报表选项**>**水印**对报表设置水印，具体属性如下：
- **启用水印**：勾选表示报表启用水印
- **水印类型**：在**水印类型**处可选择`文字水印`或`图片水印`
- 文字水印：可设置文字的**水印内容**、**字体**、**字号**、**字色**、**铺满页面**等属性
- 铺满页面：勾选表示将水印内容重复铺满页面。不勾选可以在**位置**属性处设置水印展示的位置
- 图片水印：可设置[图片来源](../../../data-viz/dash/components/more/image.md#source)、[填充方式](../../../data-viz/dash/components/more/image.md#fill)、**冲蚀**、**位置**等属性
- 冲蚀：勾选后图片变为半透明的浅对比度的水印效果
- **旋转**：表示将水印顺时针旋转设置的角度
- **打印水印**：勾选表示打印报表时，水印会随着报表一同打印出来
示例地址：[文字水印](https://demo.succbi.com/v5/demo/文字水印)
## 工作表更多属性{#more}
### 工作表显示条件{#more-condition}
**显示条件**设置用于控制工作表的显示与隐藏，只有满足当前的显示条件时，工作表内容才会显示。\
点击工作表空白处，在右侧属性栏**工作表**>**高级**>**显示**中设置，提供了如下选项：
1. 显示
2. 隐藏
3. `条件`：表达式动态设置工作表的显示隐藏。当表达式返回`true`则显示工作表，返回`false`则不显示工作表
::: tip 优先级说明
在**报表选项**中设置[**默认显示工作表**](#rpt-defaultsheet)属性的内容为`sheet1`，如果该工作表设置了**显示条件**为`隐藏`，则默认设置不起作用，即计算界面不显示任何内容。
:::
### 工作表浏览器页面标题{#more-title}
设置了工作表的**页面标题**属性，在查看页面当显示当前工作表时，浏览器标签页内容为该属性设置的值。例如使用标签页的切换实现动态显示多个工作表，每切换一个工作表，浏览器标签显示为对应页面的标题描述。\
点击工作表空白处，在右侧属性栏**工作表**>**高级**>**页面标题**中直接输入内容。该属性缺省内容为报表的元数据名称。
示例地址：[设置页面标题](https://demo.succbi.com/v5/demo/切换标签页)
### 工作表允许框选单元格{#more-cell}
**允许框选单元格**属性，是用于控制在报表查询界面是否能选中每个单元格。点击工作表空白处，在右侧属性栏**工作表**>**高级**中勾选**允许框单元格**该属性即可实现，该选项默认为勾选状态。
## 报表高级选项{#rpt}
在设计器左上角**文件**>**报表选项**中，可以设置报表的全局选项。
### 默认显示工作表{#rpt-defaultsheet}
### NULL和0参与运算的规则{#rpt-nullzero}
### 查看界面更多菜单是否显示{#rpt-more}
---
url: "https://docs.succapp.com/v5/guide/report/manage-themes/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/themes"
title: "报表主题概述"
---
---
order: 8
navTitle: 主题管理
indexTitle: 概述
---
# 报表主题概述
使用报表主题可以快速美化报表，避免重复设置一些相同的样式属性，例如标题、合计行、说明文字等，能够很大程度上提升工作效率也方便了后期的维护和管理，并且还可以通过主题实现报表风格的快速切换。
报表主题分**项目主题**和**系统主题**：
- 项目主题：仅用于当前项目下的报表文件，相关文件是存储在`当前项目/资源/settings/themes/rpt`下
- 系统主题：可用于当前系统中所有项目下的报表文件，相关文件是存储在`系统数据/资源/settings/themes/rpt`下
## 主题切换{#switch-theme}
通过主题切换，报表可以快速实现不同的风格样式，应用于不同的使用场景。
示例地址：[切换主题风格](https://demo.succbi.com/v5/DEMO/ana/%E6%8A%A5%E8%A1%A8/%E5%88%86%E7%BB%84%E6%8A%A5%E8%A1%A8/%E4%BA%A4%E5%8F%89%E5%88%86%E7%BB%84.rpt?:edit=true)
## 系统自带主题模板{#system-theme}
系统自带多个美观的报表主题，这些主题都是经过设计师精心设置的，直接选择即可复用样式，与仪表板不同的是，报表需要存储的风格较为固定，常用的**正文**、**大标题**、**行列一级标题**、**表头（尾）**、**行列二级标题**、**小计**、**合计**、**解释性文字**、**链接单元格**等这些风格基本就能囊括日常的使用场景。
## 制作自己的主题{#custom-theme}
如果系统自带的主题模板无法满足当前的项目需求，那么我们可以按照特定的需求新增一个[自定义主题](./custom-themes.md)即可。
---
url: "https://docs.succapp.com/v5/guide/report/manage-themes/system-themes.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/system-themes"
title: "system-themes"
---
---
order: 2
navTitle: 系统自带的主题
---
# 系统自带的主题
产品自带多个美观的报表主题，直接选择即可复用它的样式。主题文件中包含了色板、色阶、单元格风格、条件样式等内容。单元格风格中则是存储了单元格的边框、背景、字体边距等样式属性。
通过本篇文档的学习，您可以了解到系统的各个报表主题和主题下的单元格风格，以及如何去使用这些风格快速实现一张美观的报表。
## 单元格风格{#cell-style}
系统自带的报表主题，每个主题中报表单元格的风格列表基本一致，都是预设了`正文`、`大标题`、`行(列)标题_一级标题`、`表头(尾)`、`行(列)标题_二级标题`、`小计`、`合计(1)`、`合计(2)`、`解释性文字`、`链接单元格`、`注释`这些单元格风格，都是归纳了常见的表格样式后做成的内置风格，能够覆盖报表大多数的应用场景。
在制作报表时的所有单元格初始风格默认为`正文`，报表制作完成后可根据自身需求去选用风格，风格的名称即代表了该风格的适用场景，例如：
- **正文**：一般用于数据展示
- **大标题**：一般用于该报表的大标题
- **行(列)标题\_一级标题** / **行(列)标题\_二级标题**：用于报表的行标题或列标题
- **表头（尾）**：可用于该报表上方或底部的说明文字
- **小计**：一般用于报表中部分数据的合计，例如省份下面的各个市的数据的小计
- **合计（1）**/ **合计（2）**：可用于报表合计行
- **解释性文字**：可用于对某个指标或名词的解释说明
- **链接单元格**：用于可以点击下钻或者跳转页面的单元格
- **注释**：可用于标注解释性的文字或符号
## 主题切换{#switch-theme}
系统内置的主题均是严格按照风格的对应规则来处理风格列表的，这样可以实现报表主题之间的无障碍切，保证不论切换到哪个主题均能保持页面美观。
切换主题时单元格的风格的对应规则如下：
- 切换主题时按照风格名称对应切换，如`海蓝`主题下单元格的风格为`行（列）标题_一级标题`，则切换到`灰白`主题后也会对应使用`行（列）标题_一级标题`。所以，所有主题下对应的风格名称需保持一致
- 如果找不到则使用默认风格，即`正文`，一般如果直接使用系统自带的主题风格不会出现这种情况，但若是用户仅在当前主题下新增了自定义风格，然后切换到其他主题时是会有找不到对应风格的情况
|水绿|海蓝|天青|油墨|
-|-|-|-|
|!|||
|灰白|灰黛|打印|松绿|
-|-|-|-|
||||
## 使用主题风格优化页面{#application}
使用报表的单元格风格去优化报表页面相对来说较为简单，因为报表的格式是基本固定的，只需要在适合的场景使用适合的风格即可，使用主题风格去优化报表可以避免很多字体大小、颜色、边距等细节设置，能够提高工作效率。
---
url: "https://docs.succapp.com/v5/guide/report/manage-themes/custom-themes.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/custom-themes"
title: "custom-themes"
---
---
order: 3
navTitle: 制作自定义主题
---
# 制作自定义主题
系统支持自定义报表主题，当[系统自带的主题](./system-themes.md)无法满足项目需求时，可以根据项目设计并新增主题，本文将介绍如何去新增自定义主题。
新增自定义主题可按如下步骤操作：
1. [确定主题规范](#inspect)：当确定了主题的主色调之后，还需要设计师去设计相关的配色，并产出主题规范
2. [新增主题文件](#custom-theme)：通过复制或导入的方式，新增主题文件
3. [修改主题色板和风格](#modify)：根据设计师提供的主题规范，对主题进行自定义配置
4. [更新缩略图](#thumbnail)：替换thumbnail.png文件
5. [测试主题](#test)：测试新增的主题，确保颜色、风格无误
## 检查主题规范文件{#inspect}
设计师需提供主题规范，需要确认包含如下内容：
1. 主题色板10个颜色
2. 主题渐变10个颜色
3. 6个指定的主题颜色：定义单元格边框、冻结行列线、以及输入组件的下拉面板和选中高亮的颜色
4. 4组色阶（不限于4组）
5. 单元格风格：大标题、行(列)标题\_一级标题、表头(尾)、行(列)标题\_二级标题、小计、合计(1)、合计(2)、解释性文字、链接单元格、注释。这些是归纳了常见的场景后做成的内置风格，覆盖了报表大多数应用场景
[点击此处下载报表主题规范原图](https://www.jianguoyun.com/p/DSWgqCcQz--gChiaq6wE)（提取码：SuccBI）
## 新增主题{#custom-theme}
新增主题有两种方式，复制已有的主题或直接导入新的主题文件。
:::tip 说明
若想制作[系统主题](./README.md)则将主题文件放在`系统资源`项目下，若想制作[项目主题](./README.md)则将主题文件放在`目标项目`下。
:::
### 复制已有主题{#copy}
1. **复制主题**：在【系统数据】项目里的【资源】-【settings】-【themes】-【rpt】目录下复制一个已有的主题文件
2. **重命名**：修改主题名称和描述，注意这里的主题名称相当于ID，只能用英文
### 导入新的主题文件{#import}
1. **导入主题文件**：在【项目】-【资源】-【settings】-【themes】-【rpt】目录下导入一个报表主题文件，点击[此处](https://www.jianguoyun.com/p/DYcWXEwQz--gChidq6wE)下载（提取码：SuccBI）
2. **重命名**：修改主题名称和描述
## 修改主题{#modify}
报表主题文件目录下包含**icons**、**images**、**theme.json**、**thumbnail**这些内容。
修改报表主题包含两部分内容，分别是修改主题色板和单元格风格：
- **修改json**：如需修改主题的基础色调，即主题色板，需[修改主题的theme.json文件](#modify-json)
- **修改单元格风格**：[单元格风格](/rpt/style)即通常用到的`正文`、`大标题`等风格，可以直接在界面上对[单元格风格进行更新](#modify-style)
:::tip 说明
报表主题风格相对比较固定，初次确定下来后，如非必要不建议多次进行调整。且同一时间建议只能有一个人修改主题风格，多人同时修改时会相互覆盖，可能导致部分内容丢失，所以建议指定一人维护。
:::
### 修改json{#modify-json}
需要进入主题的json文件中，修改对应位置颜色的十六进制值，需要修改的内容有:
- [主题色板10个颜色](../../data-viz/dash/manage-themes/制作自己的主题.md#themecolor1)
- [主题渐变10个颜色](../../data-viz/dash/manage-themes/制作自己的主题.md#gradient)
- [6个指定颜色](../../data-viz/dash/manage-themes/制作自己的主题.md#specify-color)
- [4组色阶](../../data-viz/dash/manage-themes/制作自己的主题.md#color-scale)
具体操作可参考[仪表板主题制作](../../data-viz/dash/manage-themes/制作自己的主题.md#modify)。
### 修改单元格风格{#modify-style}
由于复制或导入的主题文件中都已经包含对应的风格，只需修改更新即可。报表主题中内置的单元格风格都需要更新，下面以`行(列)标题_二级标题`为例来演示如何修改风格，具体操作如下：
1. **选择主题**：在报表中切换到新增的主题
2. **打开主题规范**：打开[主题规范文件](#inspect)，找到需要修改的单元格风格，用于取色
3. **应用风格**：选中一个单元格，打开风格列表，找到需要更新的`行(列)标题_二级标题`，应用风格
4. **修改风格**：在主题规范文件中找到`行(列)标题_二级标题`对应的填充色、字体颜色以及字体大小，依次修改报表中的对应样式属性
5. **更新风格**：修改完成后，点击风格名称右侧的小三角，下拉选择`更新风格`
6. 按照以上操作修改完所有的风格即可
## 更新缩略图{#thumbnail}
报表主题缩略图是用来示意当前主题的基础样式，用户可以根据缩略图初步对主题进行筛选使用。更新报表主题缩略图的操作同[仪表板-更新缩略图](../../data-viz/dash/manage-themes/README.md#thumbnail)。
## 测试主题{#test}
### 确认当前主题风格无误{#test-current-theme}
可以制作一张包含所有单元格风格的报表，类似下图，确认**单元格的填充**、**字体的样式**、**隔行换色的颜色**、**冻结行列线的颜色**、**单元格边框色**等是否与设计稿一致。
### 确认可无障碍切换主题{#test-switch-theme}
需切换到其他报表主题测试单元格风格是否异常，有以下几个需要注意的异常点：
1. 单元格的填充色未发生变化
2. 字体样式未发生变化或有异常变化
3. 隔行换色颜色与主题不匹配
4. 边框颜色与主题边框色不符
5. 冻结线的颜色未变化或与设置的主题色不符
---
url: "https://docs.succapp.com/v5/guide/report/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/faq"
title: "常见问题"
---
---
order: 99
navTitle: 常见问题
---
# 常见问题
!!!children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/report/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/rpt/errcode"
title: "报表错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 报表错误提示排查
---
url: "https://docs.succapp.com/v5/guide/ci/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci"
title: "报表填报"
---
---
description: 报表填报用于构建类 Excel 的多级报表报送、数据采集、填报校验、上报审批和汇总分析应用。
order: 9
navTitle: 报表填报
indexTitle: 概述
---
# 报表填报
报表填报用于构建类 Excel 的多级报表报送和数据采集应用。它适合把集团年报月报、财务预算、卫生直报、监管报送、明细采集等原本依赖 Excel 文件流转的业务，转成可在线设计、填报、校验、上报、审批、汇总和分析的 SuccApp 应用。
## 适用场景{#scenarios}
当业务需要保留 Excel 表样、按单位和数据期组织填报、在浏览器中录入和校验数据，并让上级单位查看报送状态、审批、锁定和汇总时，优先使用报表填报。
典型场景包括：
- 周期报送：年报、季报、月报、日报等固定周期数据采集。
- 多级填报：集团总部与分子公司、主管部门与下级机构、监管单位与被监管对象之间的数据报送。
- 预算和统计：财务预算、事业计划、经营统计、卫生统计、人力资源统计等复杂表样填报。
- 明细采集：人员、设备、合同、网点、项目等一单位多条记录的数据采集。
- 质量管控：使用校验公式、批量校验、特例说明、审批流程和数据锁定控制数据质量。
如果只是搭建门户首页、查询页面、信息维护页或常规 Web 式业务表单，通常使用 SuperPage；如果只是制作固定版式输出、打印或分发的查询结果，通常使用报表。
## 核心能力{#features}
- 类 Excel 设计体验：支持单元格、公式栏、Sheet、增删行列、合并拆分单元格、表格线和条件样式。
- Excel 兼容：可导入 Excel 表样生成填报表，填报时支持导入导出 Excel，也支持从 Excel 复制粘贴数据。
- 多种填报表样：支持固定行表、纵向浮动、横向浮动、局部浮动、固定表和浮动表组合、多级小计和明细填报。
- 自动数据建模：可根据表样和数据映射自动生成业务模型，也可绑定已有模型和字段。
- 取数和计算：支持默认值、计算公式、取数公式、前期数据、第三方数据和跨表引用。
- 校验和上报：支持必填、逻辑校验、跨表校验、批量校验、警告和特例校验，并区分保存草稿和正式提交。
- 报送管理：支持按数据期、填报单位查看上报情况，进行催报、审批、锁定、解锁和逐级汇总。
- 数据利用：填报数据入库后可继续用于查询、汇总、报表、仪表板和其他业务应用。
## 基本流程{#workflow}
1. [新建报表填报应用](./design-fapp/create-formapp.md)：选择模板或导入 Excel 表样，确定周期填报或信息管理等应用类型。
2. [设计填报报表](./design-fapp/design-form/README.md)：调整表样、单元格类型、固定行表或浮动表结构。
3. [设置数据存储](./design-fapp/data-storage.md)：自动生成模型，或引入已有模型并完成数据映射。
4. [配置取数和计算](./design-fapp/fetch-and-calc.md)：设置默认值、计算公式、取数公式和跨表计算。
5. [配置数据校验](./design-fapp/validate.md)：添加必填、逻辑校验、批量校验和特例规则。
6. [发布报表填报应用](https://docs.succapp.com/v5/ci/publish)：生成运行期资源，让填报用户可以访问。
7. [填报数据](./filling.md)：填报用户保存草稿、提交数据、导入导出 Excel、处理校验错误。
8. [配置审批流程](./design-fapp/workflow.md)：需要多人处理时，配置提交、审批、退回等流程节点。
## 推荐阅读{#next}
- [报表填报应用设计器](./design-fapp/designer.md)：了解设计器界面、Sheet、工具栏、属性栏和快捷键。
- [应用设置](./design-fapp/settings/README.md)：配置数据期、填报单位、数据填写、上报管理、水印和打印。
- [浮动填报](./design-fapp/float-submit/README.md)：处理动态增删行列、导入、合并单元格、分级小计和汇总。
- [数据管理](./data-manage.md)：管理已填报的数据、状态和相关操作。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci/design-fapp"
title: "创建报表填报应用"
---
---
order: 3
navTitle: 创建报表填报应用
---
# 创建报表填报应用
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/create-formapp.md"
htmlUrl: "https://docs.succapp.com/v5/ci/create-fapp"
title: "新建报表填报应用"
---
---
order: 1
navTitle: 新建报表填报应用
---
# 新建报表填报应用
新建一个报表填报应用的步骤如下：
1. **新建入库**：进入项目的**表单**模块，点击**新建**，选择**报表填报应用**
2. **确认表样**：新建对话框中可以选择内置的表样模板，也可以通过导入 Excel 生成自定义表样
3. **确认应用类型**：表样确定后，选择合适的[报表填报应用类型](#choose-types)，确定后进入报表填报设计器界面
4. **命名保存**：点击**保存**按钮，在命名对话框输入合适且有意义的名称，点击确定即可
## 报表填报应用类型{#choose-types}
报表填报应用按照不同业务需求分为了两种类型：
1. [周期填报应用](settings/periodic-filling.md)：用户在指定周期内向对应填报单位上报数据的应用。比如卫生统计月报、财务预算年报等，可以使用周期填报应用
2. [信息管理应用](settings/information-manage.md)：对模型表数据进行增删管理的应用，如用户管理、部门管理等
## 导入Excel表样{#import-excel}
报表填报应用支持通过导入的Excel来生成表样。**新建报表填报应用**，点击新建对话框中的**导入Excel**按钮，选择要导入的Excel，当Excel中包含多个sheet时，会自动根据每个sheet生成对应的表单。
:::tip
新建完成后，若需要继续导入Excel表单，可点击工具栏左侧**文件**按钮，在弹出菜单中选择**导入Excel表样**。
:::
## 新建工作表{#new-sheet}
报表填报应用支持添加多种类型的工作表，在标签页中点击加号可新建工作表：
- **表单**：填报数据的工作表，新建后可在工作表中根据业务需求自行设置填报内容。
- **报表**：支持在报表填报应用中嵌入查询报表，常用于展示一些汇总数据等，配置属性可参考文档[嵌入报表](../../app/superpage/components/embed/embedreport.md)。
- **SuperPage**：支持在报表填报应用中嵌入[SuperPage](../../app/superpage/README.md)，常用于一些个性化的Web式表单填报需求，配置属性可参考文档[嵌入SuperPage](../../app/superpage/components/embed/embedsuperpage.md)。
- **文件夹**：可按照具体业务将各个工作表按文件夹划分，便于在工作表较多的情况下快速找到要查看的工作表。
## 模板管理{#mgr-templates}
使用模板可以快速搭建报表填报应用，除了系统内置模板，用户也可以自行添加常用的模板，具体操作步骤如下：
1. 进入**报表填报应用**设计器，做好常用的表样以及其他设置
2. 点击工具栏左侧**文件**按钮，菜单中选择**保存为模板**，输入模板标题，标题与已有模板相同时会覆盖，不同则新增
3. 再次新建报表填报应用时，可以使用新增的模板
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/designer.md"
htmlUrl: "https://docs.succapp.com/v5/ci/designer"
title: "报表填报应用设计器"
---
---
order: 2
navTitle: 报表填报应用设计器
---
# 报表填报应用设计器
报表填报应用设计器是用来设计填报报表的可视化工具，使用所见即所得的方式设计填报报表。报表填报应用设计器页面如下图：
报表填报应用设计器主要包括如下功能板块：
1. **数据源**：数据源区域列出了可以用于表单中的数据，表单内部生成以及外部引入的模型都会在列表中展示，可以添加表内数据加工、增加计算字段或删除模型等。
2. **表单列表**：集中列出当前报表填报应用下所有Sheet，可在该列表中统一管理，支持搜索、新增、重命名、删除等功能。
3. **导航栏**：报表填报应用除基本的表单设置外，还可配置[审批流程](./workflow.md)以及其他的一些[应用设置](./settings/README.md)，在导航栏中可切换进行配置。
4. **工具栏**：通过选中单个或多个单元格并点击按钮，可实现插入行、插入列、删除行、删除列、设置单元格等功能。还可通过工具栏中的设置添加条件样式或校验公式等。
5. **标签页**：可切换不同Sheet，支持新增、删除、重命名Sheet，Sheet过多超出显示范围时会在末尾显示能展示表单页菜单的更多按钮。
6. **表格区**：类似Excel的Sheet页面，对表格内容进行编辑，支持设置多种[单元格类型](./design-form/cell-types.md)，双击数据源中字段可直接设置单元格输入方式，支持类似Excel的拾取单元格操作来编辑表达式。
- **列表头**：选择列表头上的字母即可全选整列，如点击`D`，可选中该列单元格进行批量操作
- **行表头**：选择行表头上的数字即可全选整行，如点击`6`，可选中该行单元格进行批量操作
7. **属性栏**：显示当前工作区选中对象的可配置属性，并可以对属性进行修改，包括：单元格基本属性、样式和交互
## 视图{#view}
工具栏右侧**视图**按钮，用于控制设计器中显示内容，可展开收起部分属性设置区域或切换单元格显示内容，可对下述属性进行设置：
- **设计器布局**：包含**校验公式**、**国际化**、**左边栏**、**右边栏**设置，勾选时会在设计器的左侧、右侧或底部显示对应的设置面板，取消勾选则隐藏。
- **放大工作区**：放大整个**表格区**，通常用于表样较大，希望有更多空间来设置表样内容的场景。
- **单元格**：设置单元格中的显示内容，默认是显示固定文字或计算公式，也可设置为显示成其他单元格属性，比如校验公式、校验提示等。
- **表达式**：默认为**显示描述信息**，即报表填报应用中用到表达式的地方都默认显示引用变量的描述，还可设置为**显示变量名**，即直接显示变量名称。
- **工具栏按钮**：默认为**图标和文字**，设计器工具栏中的按钮下方文字即其对应的标题文字，默认是都显示的，也可设置为**仅显示图标**。
- **标签页**：标签页支持设置名称和描述，该设置用于控制标签页具体是显示名称还是描述或者一起显示。
## 快捷键{#hotkey}
报表填报应用设计器快捷键操作与报表设计器一致，可参考文档[报表设计器快捷键](../../report/designer.md#hotkey)。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings"
title: "报表填报应用设置"
---
---
order: 3
navTitle: 报表填报应用设置
---
# 报表填报应用设置
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/period.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/period"
title: "数据期"
---
---
order: 1
navTitle: 数据期
---
# 数据期
**数据期**是报表填报应用的填报频度。例如工作周报，员工每周定期的汇报工作进展，此时对应的**数据期**就是周。类似的还有企业信息年报，财务月报等需要周期性的上报数据的场景。**数据期**是**周期填报应用**的数据粒度之一，**信息管理应用**无需设置。本文主要介绍**数据期**相关的各种属性设置，包括如何控制填报的频度以及填报的开始结束时间等。
## 固定周期{#fixed-period}
**固定周期**是指用户按照一个预制好的固定时间频度填报数据，如每周一次，每月一次。基本设置如下：
- **填报周期**：时间粒度，决定了一个数据期有多长时间，默认可供选择的有日期、年月、年、年季、半年、年周、年旬，也可通过自定义[日期角色](../../../data-gov/model/field-role.md#date)添加更多个性化填报周期。
- **当前期**：存在多期数据时，设置默认应该显示哪一期的数据，可选择自动、表达式。
- **自动**：根据当前填报时间自动设置最近的一期为当前期，比如填报时是2023年12月1日，如果是年报则自动将2023年作为当前期，月报则将2023年12月作为当前期，以此类推。
- **表达式**：设置一个表达式，返回指定日期，根据该日期来找到所在的数据期范围确定默认显示哪期数据，如对于月报希望每月5号前以上月为当前期，5号后以当月为当前期，可以输入`TOSTR(IF(DAY()<5,ADDDATE(TODAY(),-1,'M'),TODAY()),'yyyyMM')`。如果此时返回的是具体日期，如20240510，那么也会找到2024年5月作为默认当前期。兼容各种常见的日期格式：20240510、2024-05-10、2024/05/10、2024年05月10日。
- **填报开始时间**：设置一期填报什么时候开始，未到时间时则无法填报，可选择无限制、自动、相对。
- **无限制**：对填报时间不做限制，用户可在任意时间填报所有期的数据。
- **自动**：默认选项，按照当前填报周期类型自动判断开始时间，如年报是每年的1月1日开始，月报是每个月的1号开始等。
- **相对**：在**锚点时间**的基础上设置相对值，锚点时间的期初、期末对应当前填报周期的默认范围，如年报，期初是每年1月1日，期末即每年12月31日。设置年报的开始时间为**期初后9自然日**，即开始填报时间为每年的1月10日，其余设置以此类推。
- **填报结束时间**：设置选项和**填报开始时间**一致，仅默认值不同，默认为**无限制**。
::: tip
1. 设置固定周期后，所有在报表填报应用中生成的模型都会自动添加**数据期**字段，并自动给字段添加上相应的[日期角色](../../../data-gov/model/field-role.md#date)，比如填报周期选择的是**年**则相应的字段[日期角色](../../../data-gov/model/field-role.md#date)也会被设置为**年**。
2. 如果是从报表填报应用外部引入的模型，则需要自行给模型添加有设置对应[日期角色](../../../data-gov/model/field-role.md#date)的主键字段，报表填报应用会自动根据这个关系找到对应的**数据期**字段。
:::
## 实时填报{#realtime-report}
**实时填报**是指用户可以随时根据业务需要进行数据填报，没有固定频度。例如部门的人员信息维护，每当有新人入职或者部分员工的个人信息发生更改时，都需要实时的填报数据，这种填报与时间无关，没有固定的周期限制。
## 应用场景{#scenarios}
本章节主要介绍各种实际业务场景下针对报表填报应用数据期的自定义配置。
### 定期上报周计划{#week-plan}
管理者要求各员工以周为频度定期上报各自的工作计划，所有员工需要在周五到周日的时间范围内填报下周的工作计划，到新的一周后，周一到周四的时间可以对本周的计划进行修改调整。此需求是典型的周报场景，但与常规周报不同的是，每一期的填报时间并不是从周一开始到周日结束的，此处每一期的工作计划都是从上周五开始填报到本周四结束才开始新的一期计划的上报，因此需要调整数据期设置如下：
1. 在**设置**>**数据期**中修改**当前期**为**表达式**。
2. 在**动态当前期**中设置表达式`TOSTR(IF(WEEKDAY(TODAY())>=5,ADDDATE(TODAY(),8-WEEKDAY(TODAY()),'d'),ADDDATE(TODAY(),-(WEEKDAY(TODAY())-1),'d')),'yyyyMMdd')`，该表达式的意思是当前时间是周五到周日时以下周为当前期，否则是本周。
3. 设置**填报开始时间**为**相对**，当周的计划是从上周五开始填报的，可设置**开始时间**为`期初前3自然日`，期初指本周一。
4. 设置**填报结束时间**为**相对**，当周的计划在本周四结束填报，可设置结束时间**结束时间**为`期末前3自然日`，期末指本周日。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/org.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/org"
title: "填报单位"
---
---
order: 2
navTitle: 填报单位
---
# 填报单位
**填报单位**是报表填报应用中需要填报数据的组织机构、部门或个人。比如集团的企业年报，填报单位是整个集团及其下级分子公司的组织架构；再比如员工填写KPI计划，填报单位就是每个员工个体。**填报单位**是**周期填报应用**的数据粒度之一，**信息管理应用**无需设置。基本设置如下：
- **填报单位**：选择存储填报单位信息的数据模型，可直接在此处引入外部模型，报表填报应用会按该模型中的数据展示填报单位。
- **填报单位层次**：选择填报单位模型中设置的层次，以模型的默认层次为主，也支持选择该模型中设置的其他层次作为填报单位树的展现形式。不同类型的层次作为填报单位的默认行为不同，分为下述四种情况：
- **父子层次**：比如集团分子公司，默认情况下父单位和子单位都需要填报本单位的数据。
- **分段层次**：默认体验与父子层次一致。
- **多字段层次**：只有叶子单位需要填报数据，比如卫统直报，需要填报数据的单位是各医疗机构，但为了上级卫健委能更加方便的查看数据，往往会将医疗机构按照所属的卫健委分类，让填报单位按照**卫健委-医疗机构**的层次来展示数据，这种情况下上级往往都是不填报数据的。
- **多字段+父子层次**：是多字段层次的一种补充情况，只有属于父子层次那部分的单位能够填报数据，例如部分医疗机构是存在分支机构的，那么最后得到的层次会是**卫健委-总医疗机构-分支医疗机构**，只有医疗机构那部分单位能够实际填报数据。
::: tip
1. 设置填报单位后，所有在报表填报应用中生成的模型都会自动添加**填报单位**字段，并自动给字段设置关联表，关联表即是此处选择的填报单位模型。
2. 如果是从报表填报应用外部引入的模型，则需要自行给模型对应的主键字段添加关联表，使用的关联表必须与填报单位中设置的模型一致，这样报表填报应用才能自动识别外部模型的**填报单位**字段。
:::
## 限制填报单位范围{#org-range}
某些业务场景中，不希望填报单位使用模型的全量数据，比如集团公司在全国都有分子公司，但该报表填报应用只需要湖北省的分子公司填报，此时可通过表达式来进一步缩小填报单位的范围。
- **设置填报单位范围**：开关设置，勾选后可设置**填报单位范围**。
- **填报单位范围**：在填报单位模型的基础上设置过滤条件，只有满足条件的单位才需要填报数据，比如限制湖北省的分子公司需要填报，则可设置表达式为`行政区划.省='420000'`，过滤条件中只能引用填报单位模型中存在的字段，为空时所有单位可填。
- **浏览单位过滤条件**：浏览单位数据时会作用的过滤条件，比如管理员在查看单位列表时希望只看那些已填报并通过校验的数据，则可设置条件为`提交状态 = 1 AND 校验状态 = 1`。还可通过**参数**来动态修改可浏览的单位数据，具体可参考[自定义过滤菜单](./interface.md#filter-menu)。
::: tip
**填报单位范围**与**浏览单位过滤条件**两者有本质区别，主要体现在以下几点：
1. **填报单位范围**决定的是哪些单位需要填报，更多是对基层单位填报表单时有影响，而**浏览单位过滤条件**不限制单位的填报，只限制查看时能看到哪些单位数据，主要是影响监管用户能查看的单位范围。
2. **填报单位范围**只支持写**固定条件**，即确定后不会发生动态变化的条件，比如行政区划限制湖北省后，不会根据用户的身份或界面操作发生变化。
3. **浏览单位过滤条件**多是使用**动态条件**，会受到用户在界面上的操作影响，比如用户要切换查看不同状态下的数据，可以通过类似`xx状态 = 参数1`的条件达到目的，切换状态时可通过修改参数值来影响最终的过滤结果。
:::
## 填报明细数据{#detail-data}
**明细数据**是在**填报单位**下能自由增删的业务数据，比如填报单位的固定资产信息，每个单位下的固定资产都不一样，需要填报用户自行在各单位下去添加每个固定资产的信息，类似的情况下都需要启用**明细数据**。
- **填报明细数据**：允许单位填报明细数据的开关设置，勾选后出现其他设置选项。
- **明细数据主键**：明细数据的主键字段，用于标识唯一的一条明细数据。以上述固定资产填报为例，需要设置固定资产ID为明细数据主键，设置的字段在提交数据时不允许为空。
- **数据浏览模式**：在查看数据时，明细数据列表以何种形式展示，分为**前后两级页面**和**左右分栏**两种形式。
- **前后两级页面**：点击填报单位后，下钻到单位对应的明细数据列表，是单独的一个页面。
- **左右分栏**：点击填报单位后，在右侧弹出该单位下对应的明细数据列表，填报单位列表与明细数据列表以左右分栏的形式展示在页面中。
- **明细数据整体上报**：所有明细数据总是以单位为整体来上报，当所有明细数据都通过校验时才允许单位上报数据。
- **允许提交空数据**：部分单位可能没有明细数据能够上报，此时允许这样的单位直接上报空数据代表该单位已上报数据。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/interface.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/interface"
title: "界面外观"
---
---
order: 3
navTitle: 界面外观
---
# 界面外观
**界面外观**是指报表填报应用的[数据列表](#list)、[工具栏](toolbar)等用户在浏览界面时查看的内容。比如管理员可以通过填报单位列表查看各单位的填报状态，列表中需要展示的内容可以根据管理员的需求来自定义，工具栏中需要有哪些操作按钮也可以根据实际需要添加配置。本文主要介绍如何配置报表填报应用的各种外观设置。
| 查询列表 | 左右分栏的表单 |
| :---------: | :--------: |
|  |  |
## 数据列表{#list}
**数据列表**是帮助管理用户了解填报情况的查询列表。它可以帮助管理员掌握每一期各单位的填报情况，比如查看有多少单位在当前期已经填报了或正在填报中。在报表填报应用中，可以查看的**数据列表**分为三种：数据期列表、填报单位列表和明细数据列表。
- **数据期列表**：以[数据期](./period.md)为粒度展示填报情况的列表，通常是展示每一期有多少单位已报或未报等。仅当报表填报应用是按[固定周期](./period.md#fixed-period)上报数据时才允许设置。
- **填报单位列表**：以[填报单位](./org.md)为粒度展示填报情况的列表，通常是展示各单位的状态，如校验状态、锁定状态等，也会统计每个单位及其下级单位的数据上报情况。仅当报表填报应用有确定的[填报单位](./org.md)时才允许设置。
- **明细数据列表**：展示[填报单位](./org.md)下[明细数据](./org.md#detail-data)的列表，如单位下的固定资产信息，人员信息等。仅当报表填报应用可以填报[明细数据](./org.md#detail-data)时才允许设置。
### 列表基础设置{#basic-settings}
报表填报应用提供了一系列设置来控制数据列表中展示的内容。各数据列表的属性设置基本一致，以数据期列表为例，基础设置如下图所示：
- **上级单位数据期列表**：配置数据列表内容，可以定义数据列表有哪些列，每列显示哪些内容，设置属性在后续章节[列表内容设置](#datalist)中具体介绍。
- **显示序号**：勾选后在数据列表首列显示序号列。
- **点击列头排序**：勾选后点击数据列表列头会按该列内容进行排序，多次点击会切换排序方式。
- **工具栏**：配置数据列表对应的工具栏，可以设置过滤、搜索框以及功能按钮等，设置属性在后续章节[工具栏](#toolbar)中具体介绍。
- **上级单位默认显示**：默认选项为**当前数据期**，大部分情况下更期望直接看当前期的数据，这种情况下会直接进入当期的填报单位列表，还可选择**数据期列表**，此时进入报表填报应用会先显示数据期列表页面。
::: tip
1. **数据期列表**的设置被分为**上级单位**和**基层单位**两套。这是因为**基层单位**只能看到自己单位的数据，因此在数据期列表中往往不需要展示一些统计数据。而**上级单位**能看到自己单位以及所有下级单位的数据，一般都会在列表中展示统计数据。基于这种普遍的差异，所以提供了两套设置。
2. **填报单位列表**和**明细数据列表**都只有一套设置是因为不论哪个单位能看到的列表内容都是统一的。
:::
### 列表内容设置{#datalist}
点击列表设置的**配置**按钮，弹出对话框设置如下图所示：
- **字段**：用于控制列中显示的内容，支持通过表达式自定义，弹出表达式对话框后也可直接拾取左侧的系统表字段。
- **标题**：列表头的名称。
- **显示格式**：根据当前列中的内容设置[显示格式](../../../project-manage/display-format.md)，支持自定义显示格式。
- **显示**：控制当前列是否显示，可选择**显示**、**隐藏**或**条件**。
- **对齐方式**：默认为自动，会根据当前内容自动设置对齐方式，比如字符型居左、数值型居右、日期居中等，也可手动指定为确定的对齐方式。
## 工具栏{#toolbar}
支持自定义工具栏，可任意添加功能按钮，过滤数据列表的输入框或搜索框等。将整个工具栏划分为左、中、右三个区域，添加到对应区域的元素会按照对应区域的对齐方式来排列，对齐方式分别对应居左、居中、居右。
工具栏中可以添加的元素有以下七种：
- **数据期**：特殊的字段过滤，只在填报单位列表、明细数据列表以及表单工具栏中可添加，用于过滤数据期。
- **填报单位**：特殊的字段过滤，仅在明细数据列表和表单工具栏中可添加，用于过滤填报单位。
- **按钮**：包括系统默认按钮以及自定义按钮，添加时可直接使用子菜单中的默认按钮，默认按钮上都有预设好配套的交互；添加自定义按钮，可自行在按钮上添加需要的交互功能。
- **允许多选**：按钮的属性设置，对于用户自定义的按钮，系统无法自动判断按钮是否能勾选多条数据进行操作，因此需要人为指定，当一个工具栏中不存在允许多选操作的按钮时，数据列表中也不会显示勾选框列。
- **菜单按钮**：支持设置菜单按钮，可在按钮下继续添加按钮，父按钮点击后子按钮会以菜单的形式展示。
- **字段过滤**：支持从系统表或业务表中挑选字段来作为列表的过滤条件，配置方法可参考文档[字段过滤](../../../app/superpage/components/input/fieldsfilter.md#field-settings)，报表填报应用中对设置做了简化，仅支持下拉框、文本、数值、日期四种输入方式。
- **文本**：可在工具栏中添加一段说明文本，支持自定义宏表达式。
- **搜索框**：工具栏中有且只能有一个搜索框，用于搜索列表中的内容，需要定义关键字对应的**搜索字段**，不设置时，默认搜索当前列表的主键和其对应的文字字段，提供了两种搜索方式，搜索定位和快速搜索。
- **搜索定位**：仅根据搜索关键字在列表中定位，搜索后，高亮列表中关键字，支持上一个下一个切换定位条目。
- **快速搜索**：根据关键字查询显示最接近的几条数据，选择指定条目后跳转，支持定义搜索面板，设置可参考文档[快速搜索](../../../app/superpage/components/input/searchbox.md)。
- **分割线**：没有任何属性设置，仅用于使工具栏更美观，功能划分更明确。
::: tip 紧凑模式
各个页面的工具栏设置是相互独立的，页面与页面之间可能会分栏显示，比如填报单位列表与明细列表分栏显示、填报单位列表与表单分栏显示等。此时就有可能出现因为工具栏中元素过多，而工具栏占用的空间不足以显示下全部内容的情况。**紧凑模式**应用于空间不足的情况下，设置选项如下：
- **保持不变**：该元素始终显示且保持原样，如果最终工具栏内容还是超出显示范围，则出现滚动条。
- **仅显示图标**：仅按钮、搜索框可设置，空间不足时，只显示设置的图标。
- **显示在更多菜单中**：仅按钮可设置，空间不足时，会收到更多中，点击更多可在菜单中看到该按钮。
- **隐藏**：空间不足时，该元素直接隐藏。
:::
## 表单设置{#form}
- **表单显示方式**：设置以何种形式来打开表单，可选择前后两级页面、左右分栏、弹出对话框。
- **前后两级页面**：以下钻的形式进到表单页面，比如前一个页面是填报单位列表，点击基层填报单位后跳转到第二级表单页面。
- **左右分栏**：两级页面的内容以左右分栏的形式展示在一个页面中，比如点击基层填报单位，此时在右侧弹出对应的表单面板。
- **弹出对话框**；表单内容以对话框的形式展示。
- **工具栏**：表单工具栏设置与列表工具栏设置类似，可参考章节[工具栏](#toolbar)介绍。
- **标签显示位置**：设置标签页的默认显示位置，除了常规的顶部和底部外，还能以树的形式固定在左右两侧或悬浮在表单上。
- **标签显示格式**：表单标签支持设置名称和描述两个属性，标签页中默认显示标签的描述，还可设置以其他形式在标签页中展示。
- **显示行列头**：设置表格的行列头是否显示。
- **表体位置**：统一控制所有标签页下表体的对齐方式，可选择居左或居中。
## 应用场景{#scenarios}
本章节主要介绍各种实际业务场景下针对报表填报应用浏览界面的自定义配置。
### 添加统计数据{#count}
在数据列表中，有时报表填报应用默认提供的已报数、应报数等统计数据无法满足业务的实际需求，比如管理机构的人力数据，需要在填报单位列表中显示男女性别的总人数，具体操作如下所示：
1. 在**设置**>**界面外观**>**填报单位列表**中点击**配置**列表按钮，弹出列表编辑对话框
2. 点击**添加**增加新列**男性人数**，在字段中输入表达式`SUM(IF(人力信息表.性别代码 = '2', 1, 0))`，表达式的含义是对明细数据求和，当性别为女的时候数据量加1
3. 查看填报单位列表，新增的列能正常计算出相应的结果
### 显示流程进度{#flow-schedule}
报表填报应用支持[工作流](../workflow.md)，管理员往往需要在填报单位列表中能够查看对应单位此时处在的流程进度，具体设置如下：
1. 在**设置**>**界面外观**>**填报单位列表**中点击**配置**列表按钮，弹出列表编辑对话框
2. 点击**添加**增加一个新列作为操作列，在操作列下新增一个按钮作为查看进度的触发按钮
3. 给按钮配置**显示流程进度**交互，确认后到查看界面确认效果
### 自定义过滤菜单{#filter-menu}
todo
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/datafill.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/datafill"
title: "数据填写"
---
---
order: 4
navTitle: 数据填写
---
# 数据填写
数据填写是用于控制表单的数据填报、数据校验以及自动取数等功能的设置。比如设置是否允许上级单位上报数据；数据填报时进行数据校验、特例上报；新增数据时自动初始化页面等。本文将重点介绍这些功能的基本使用方法。
## 限制上级单位上报{#org-report}
在实际场景中，上级单位有时不需要上报数据。比如数据汇总时，上级单位可能只需要查看汇总数据但不需要上报。[父子层次](../../../data-gov/model/data-hierarchy.md#paternity)的[填报单位](./org.md)默认所有单位都会上报数据，此时就需要以下设置来控制上级单位的默认行为：
- **上级单位不显示表单**：勾选后在单位树上选择上级单位节点，不会显示表单，只会展开填报单位树。
- **允许上级单位上报数据**：勾选后上级单位正常填报数据；不勾选时，上级单位无法填报数据，同时上级单位工具栏上的保存、提交按钮将会自动被隐藏。
::: tip
[多字段层次](../../../data-gov/model/data-hierarchy.md#multifields)的[填报单位](./org.md)默认上级总是不能填报数据，此时即便设置**允许上级单位上报数据**也不会生效，如果需要在点击上级时查看汇总的表单数据，也可通过上述设置来实现。
:::
## 数据校验{#data-validate}
**数据校验**设置是报表填报应用针对全局校验设置的一些开关选项。它决定了报表填报应用中的[校验公式](../validate.md)有怎样的校验标准。比如是否对校验的等级进行划分，或是允许对一些不通过的校验进行解释说明等。当未启用校验时，报表填报应用中所有设置的校验公式都会失效，以下是相关设置：
### 校验分级{#validate-grade}
校验分级是指校验有`错误`跟`警告`两个级别，错误级别影响提交，只有错误级别的校验全部通过后数据才能正常提交；警告级别默认不影响提交，只提醒用户。如在进行项目周期填报时项目的开始时间必须小于结束时间、在进行收益填报时收益为负数则出现警告提示，但数据可以正常提交。要实现数据分级，需要通过属性配置来完成。
- **启用警告**：勾选后校验错误将分`错误`和`警告`2个级别。警告级别默认不影响提交，只提醒用户，也可设置**有警告时不能提交**。
- **有警告时不能提交**：勾选后警告级别的校验也必须全部通过才允许提交。
::: tip
只有勾选了**启用警告**，在报表填报设计界面添加校验公式时才会出现**错误级别**属性，设置好该属性后才能实现校验分级。更多的介绍可查看[数据校验](../validate.md)文档。
:::
### 特例校验 {#special-validate}
特例校验是指数据上报的过程中某个校验公式不通过时，进行合理的解释说明后该处的数据可作为特殊情况提交。特例校验是针对单个校验公式而言的，而非整体数据。例如公司报销电脑的金额在10000元以下，报销显示器的金额在2000以下，但设计人员由于工作原因对设备有特殊的要求，购买的设备均超过了标准，此时需要对每笔金额分别进行解释说明然后上报。
- **启用特例**：勾选后允许对校验错误的数据进行解释说明，填写解释说明后，不满足校验公式的数据作为特殊情况提交。与校验分级类似，**启用特例**后，设置校验公式时才能设置每个公式单独的特例条件。
- **特例条件**：启用特例的条件，满足此条件时才能真的启用特例校验。比如设置“管理用户”才能做特例说明。每条校验公式上也可独立设置特例条件，与此处的条件是AND的关系，只有2个条件都满足时才能启用该条校验公式的特例。
### 其他校验{#else}
数据校验还支持校验数据是否在可选范围内以及批量校验多个单位的数据，具体介绍如下：
- **检验可选项范围**：勾选后下拉框的值必须在下拉可选项范围内，否则校验错误，无法提交。不勾选时，下拉框的值不在可选项范围内也可正常提交。比如在进行联系人信息维护时，联系人【职务】有`管理人员`、`技术人员`、`数据分析师`这三种选项，从excel导入数据到表单时，excel中存在`高校教师`这个职务，数据导入后下拉框会给出`#ERR:高校教师`的提示，表明高校教师不在可选范围。此时如果勾选了**检验可选项范围**，数据将出现校验错误，无法提交。若未勾选**检验可选项范围**，数据可正常提交。
- **启用批量校验**：勾选后可在数据列表处选择多个填报单位同时进行数据校验，校验结果以对话框的形式展现，支持下载校验结果。一般搭配批量校验按钮使用。如同时对A公司下面的三个子公司填报的所有数据进行校验，只需要在数据列表处勾选这三家单位，点击批量校验按钮即可。
## 自动取数{#fetch-data}
自动取数是指新增数据时表单按照设置的公式自动初始化数据的过程。常用于新增数据时，获取数据库或者第三方系统中的数据初始化到表单页面中，根据需要修改后上报。自动取数常搭配取数公式进行。更多关于取数的内容可查看[取数计算](/ci/fetch-and-cal)文档。
- **自动取数**：可下拉选择自动初始化表单数据的方式。有下列三个选项：
- 无数据时自动取数：新增数据时，表单引用的模型中若无数据可装载，则按照对应的设置自动初始化表单数据。
- 总是自动取数：新增数据时，页面总是初始化表单数据。浮动表单中，若初始化的数据与装载的模型数据之间有冲突则按照设置的[浮动汇总方式](/ci/fetch-and-cal)合并数据。
- 不自动取数：新增数据时，系统不自动进行数据初始化。使用该选项时常在填报页面使用取数按钮手动初始化页面。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/submit-management.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/submit-management"
title: "上报管理"
---
---
order: 5
navTitle: 上报管理
---
# 上报管理
表单的上报管理是指对上报的数据进行审批、锁定、汇总等操作，比如数据的层层审批、上报数据的锁定、上级单位自动汇总下级单位数据等。
## 数据审批{#data-examine}
在很多填报场景中，基层数据上报后需要由上级领导进行审批，比如分公司进行销量上报，由总公司的领导进行审批。报表填报应用支持对数据层层上报审批，审批流程的绘制可参考[绘制工作流](../../../app/workflow/design.md)文档。报表填报应用在绘制流程之前需要在设计器的**设置**>**上报管理**中启用审批。
- **启用审批**：勾选表示当前报表填报应用可设置审批流程。勾选后报表填报设计器导航栏会新增一个**流程**的标签页，在此页面可绘制填报流程。
- **工作流**：表单使用的工作流。在表单的流程页面绘制并发布工作流后，**工作流**下拉框会自动默认选择当前报表填报应用内的工作流，也支持下拉选择其他工作流。
- **发起流程条件**：发起流程的条件，只有满足条件用户上报数据的同时才会发起流程，否则仅上报数据，不发起流程。例如当涉及的金额超过5000才需要发起流程等。
::: tip
当报表填报应用引用外部工作流时，该工作流会在**流程**页面中同步显示，以便查看，但不可修改。
:::
## 数据锁定{#data-lock}
数据锁定可防止意外的数据更改或删除。很多场景中数据上报之后需要对上报的数据进行锁定，锁定后的数据不支持增删改，仅可查看。比如销售人员将每月销售情况上报后数据就会自动锁定，不允许后续修改。报表填报应用支持**提交后自动锁定**数据。
- **提交后自动锁定**：表单数据提交后将自动锁定，不可增删改，仅可查看。
::: tip 手动锁定解锁
除了上述介绍的**提交后自动锁定**外，报表填报应用也支持手动设置解锁锁定。比如基层业务员上报业务数据，领导审批之前，业务员可修正数据，领导审批通过后手动锁定数据，数据便不可再修改。可以通过在工具栏上配置【锁定】、【解锁】按钮实现。具体使用可参考文档[界面外观](./interface.md)。
:::
## 汇总{#collect}
汇总是指按照指定的汇总方式，汇总下级数据或汇总符合条件的数据。报表填报应用支持在初始化时自动汇总数据，或手动点击工具栏上的汇总按钮汇总数据。自动汇总设置需要在属性处进行配置，启动自动汇总后，系统默认会自动汇总下级数据，若需要按条件进行汇总或设置浮动汇总方式，需另行配置。
### 汇总下级数据{#subordinate-collect}
汇总下级数据有两种情况：一是直接汇总下级单位数据；二是按照条件汇总符合条件的数据。汇总下级数据常用于上级单位不上报数据仅监测下级数据的情况，比如总公司汇总分公司的销量数据；按条件汇总数据，常用于多个单位间有某种联系的情况，比如汇总所有亏损的事业部的项目情况。其具体的属性设置如下：
- **汇总方式**：数据汇总的方式，可选择`汇总下级数据`、`按条件`两种。
- 汇总下级数据：上级单位汇总直接下级的数据。
- 按条件：按照设置的**汇总条件**将数据进行汇总。选择该选项后会出现**汇总条件**的属性，可在此配置汇总条件。
- 汇总条件：满足条件的单位进行数据汇总。如填报单位有多个层级时，每个上级单位都需要汇总基层数据修改后上报，此时就可以设置汇总条件只汇总基层的数据，保证上级节点直接从基层单位获取数据进行修改。
### 浮动汇总方式{#float-collect}
浮动汇总方式是指在对浮动表单进行汇总时所采用的数据处理方式。比如总公司汇总分公司的销量数据、设备明细等。根据业务的不同我们需要选择不同的汇总方式，比如是根据主键进行数据加总、还是将数据列出所有明细、又或者不汇总浮动表单的数据等。具体属性的介绍如下：
- **浮动汇总方式**：下级单位浮动表的默认汇总方式。有两种选择：`按主键汇总`、`不汇总`。
- 按主键汇总：按照主键标识对浮动数据进行汇总，主键相同的数据汇总，主键不同的数据追加。如总公司汇总产品的销量情况，此时销售的产品是相同的，所以可以根据产品直接将多个分公司的销量数据进行汇总。
- 不汇总：上级单位对下级单位的浮动数据不进行汇总。
::: tip 列出明细数据
除了上述两种方式之外，还存在一种浮动汇总方式，即列出所有明细。**列出所有明细**是指将下级或者基层的所有浮动表数据都列在上级的表单中。如总公司汇总分公司所有的设备信息，每台设备都是有唯一的，所以汇总设备数据的时候，需要将所有的设备以明细的形式展示。更多具体介绍可见[列出下级单位数据](../fetch-and-calc.md#list-org)。
:::
### 其他汇总{#else}
除上述的汇总设置外，系统还支持设置只汇总审批通过的数据和只汇总上报的数据。基本的设置如下：
- **只汇总审批通过的数据**：勾选表示上级单位只汇总审批通过的数据。
- **只汇总已上报的数据**：勾选表示只汇总已上报的数据。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/print.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/print"
title: "打印"
---
---
order: 7
navTitle: 打印
---
# 打印
表单支持将填报的报表数据进行打印，以纸质的的形式呈现出来。表单的打印功能与报表类似，支持套打、设置页面排版、分页打印、设置打印区域等功能。更多关于打印的场景以及属性设置可参考文档[打印](../../../report/design/properties/README.md#print)。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/watermark.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/watermark"
title: "水印"
---
---
order: 8
navTitle: 水印
---
# 水印
系统支持为报表填报应用添加水印，半透明置于表单中，不影响数据阅读性。根据具体的使用场景可以选择所有场景都展示水印或仅在填报页面、导出页面、或打印页面添加水印。水印的常见内容主要有当前登录用户所在机构ID、名称和用户ID、名称等。具体使用方式与报表相同，具体内容可见[水印](../../../report/design/properties/README.md#watermark)。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/settings/advanced-setting.md"
htmlUrl: "https://docs.succapp.com/v5/ci/settings/advanced-setting"
title: "高级"
---
---
order: 9
navTitle: 高级
---
# 高级
高级属性主要包括报表填报应用的类型以及后端脚本的引用。具体如下：
- **应用类型**：报表填报应用的属性。在创建报表填报应用时进行选择，后续不可修改。包括周期填报和信息管理两种类型。具体说明可见文档[报表填报应用类型](../create-formapp.md#choose-types)。
- **启用后端脚本**：勾选后可使用后端脚本。表单支持使用脚本来实现个性化的后端新增、删除、更新数据等逻辑。
- 后端脚本文件：脚本文件地址。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/design-form/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci/design-form"
title: "设计填报报表"
---
---
order: 4
navTitle: 设计填报报表
---
# 设计填报报表
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/design-form/data-mapping.md"
htmlUrl: "https://docs.succapp.com/v5/ci/data-mapping"
title: "表样和数据映射"
---
---
order: 2
navTitle: 表样和数据映射
---
# 表样和数据映射
报表填报应用常见的表样有固定表、浮动表这2种。固定表可以根据需要选择列表存储或行表存储的方式，而浮动表则仅适合于行表存储。报表填报应用可以根据表样及其对应的数据映射自动生成数据模型，具体说明可见文档[模型设计](https://docs.succapp.com/v5/app/model-design)；也可以根据需要选择引入外部模型创建表单。本文主要为大家讲解具体的表样及其对应的数据映射。
## 固定表{#fix-table}
固定表是指数据填报界面中只能在固定的单元格进行填报的一类表单。制作固定表时，需要在设计器页面完整地绘制出行列内容以及需要填写的单元格，在绘制过程中能够灵活的的调整表格样式。固定表可以根据需要进行列表存储或者行表存储，具体说明见下方章节。
### 列表存储{#line-table}
列表存储是指数据是通过列来扩展的，增加一个指标，数据库表中新增一列。固定表默认按照列表存储。以下方的车辆销售详情为例，每种车型需要填写四个销售指标，表样中有3种车型。这些指标会被存储为数据库表中的一行数据，总共有12个字段。
::: tip
需注意本文中所有数据映射关系图中均省略了[数据期](../settings/period.md)和[填报单位](../settings/org.md)两个字段，实际使用时需要酌情添加。
:::
### 行表存储{#row-table}
行表存储即数据是通过增加行来扩展的，新增一个维项，数据库表中新增一行数据。固定表想要实现行表存储，需进行[行存储设置](#row-condition)。报表填报应用会将行存储条件所在的一行、一列或者一系列类别的数据存储为一行，若多个行存储条件之间存在交叉的情况，则以and的关系进行存储，在数据模型上体现为多个维项同为主键标识一条数据。具体的数据映射关系如下：
#### 行存储设置{#row-condition}
行存储的设置可以控制当前的指标属于哪个维度，即哪一行数据，是实现固定表按行存储的关键步骤。在设计器界面勾选**行表存储**后，可设置**行表条件**，行表条件可控制指标所属的维度。行表存储通常会搭配**条件**区域使用。设置行存储有直接引用维成员、手动设置行存储两种方式。
##### 直接引用维成员 {#auto}
直接引用维成员适用于数据模型中的维度有关联维表且为主键的情况。比如资产负债表中，【项目】字段已关联了资产项目表且该字段为主键，在制作该表时，就可以直接引用项目的维成员。具体步骤如下：
1. 查看维成员：查看维成员有两种方式。
- 直接右键数据模型的维项，选择【显示维成员】。
- 在工具栏上的**条件**下拉选择**批量添加条件**，选择对应的数据模型及维项。
2. 引用维成员：引用维成员的方式有如下三种，任意选择即可。引用了维成员的单元格会自动勾选上【行表存储】属性，并生成对应维项的行表条件，如`资产负债表.项目='010100'`。同时单元格会自动框选一个条件区域，该条件区域均会受行表条件控制，且条件区域支持手动调整。
- 单选拖拽：鼠标点击维成员拖拽至单元格中。
- 多选拖拽：多选维成员，并拖拽至单元格中，即可实现批量引用维成员。多选引用维成员时，系统会根据拖入的维成员个数自动扩充行。
- 双击：选中单元格，双击维项即可引用维成员，成功后选中单元格自动往下，可再次双击设置下一个单元格。但该行为只会在已有单元格上执行，不会自动扩充行。
::: tip
在拖入维成员至空白单元格时，维项名称将自动填充至空白单元格；若单元格已有内容，拖入维成员时，单元格内容不变仅增加行存储设置。
:::
##### 手动设置行存储 {#manual}
手动设置行存储常用于数据模型中的维度未关联维表或需要设置动态行表条件的情况，如年报中填报产品每月的销量。这里月份不会关联维表，需手动设置行存储条件。
1. 手动设置条件范围：选中单元格，点击标签栏上的【条件】，并调整好条件范围。
2. 设置行存储：选中主条件单元格，在【属性栏】-【单元格】-【数据】属性处勾选**行表存储**，并设置好行表条件，所在条件区域的单元格均受该条件影响。比如设置行表条件为`年月 = 当前数据期 + '02'`，即整个条件区域的数据均为当前数据期2月份的数据。
## 浮动表{#float-table}
浮动表是指数据填报界面能够动态增加数据的一类表样。浮动表可以采用不同的浮动形式，包括横向浮动、纵向浮动和交叉浮动等类型，以满足不同数据录入和展示需求。浮动表仅适合于行表存储，[浮动](../float-submit/README.md)的设置可以让用户在填报界面动态新增数据，且能够将数据按行存储。以下方各车型销售明细表为例，每行代表一种车型的销量详情，由于数据在填报界面可以动态添加，所以数据对应存储为n行+5个字段，具体如下图：
::: tip
浮动表在设计器界面仅制作布局与结构，不展示完整的数据，因此浮动表相比固定表而言，对表样的调整有一定的局限性。
:::
## 注意事项{#scene}
### 引入外部模型实现数据映射{#note}
引入外部模型来实现数据映射时，创建的外部模型需要注意以下内容：
- **数据期**：主键，若表单为[实时填报](../settings/period.md#realtime-report)则不需要该字段。该字段需根据表单的[填报周期](../settings/period.md#fixed-period)设置好对应的字段角色。比如报表填报应用为年报，每年填写一次，则需要设置数据期的字段角色为【年】。
- **填报单位**：主键，若报表填报应用不涉及到填报单位则不需要该字段。该字段需根据表单的[填报单位](../settings/org.md)绑定对应的维表。
- **维度**：报表填报应用中需要的维度信息。根据使用场景的不同维度存在以下两种情况。
- 若某维度是标识一行数据的关键字段，必须设置为主键，且若需要使用其维成员，需提前绑定好维表。如资产负债表中的【项目】字段。
- 若某维度仅用于存储基本的维度信息，无需设置为主键。根据需要设置好对应的字段长度等内容即可。
- **度量**：报表填报应用中需要的度量信息。根据需要设置好对应的字段长度等内容。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/design-form/cell-types.md"
htmlUrl: "https://docs.succapp.com/v5/ci/cell-types"
title: "单元格类型"
---
---
order: 3
navTitle: 单元格类型
---
# 单元格类型
**单元格类型**是Excel表单提供的各种单元格的输入方式。报表填报应用支持多种**单元格类型**，用于应对各种填报场景。选用合适的**单元格类型**，既能增强用户体验，又能控制数据输入的规范。
|默认类型单元格|日期类型单元格|
|---|---|
|||
## 基本类型{#basic-type}
报表填报应用支持8种**基本类型**，分别为：文本、数值、下拉框、日期、时间、选择面板、勾选框和搜索框。在体验上与SuperPage的输入组件类似，属性配置可参考[输入组件](../../../app/superpage/components/input/textinput.md)。不同的是，在报表填报应用中无需手动建模和绑定字段，支持根据单元格的类型及属性自动生成模型和字段。
示例地址：[单元格类型](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=cell-type&:sheet=BasicType)
## 其他类型{#other-type}
除基本类型外，报表填报应用还支持了一些特殊的**单元格类型**，比如**字格**和**进度条**等，可以在特定场景下满足用户需求。
### 链接{#link}
链接单元格用于需要在表格中添加操作的场景。通常在表格中放置一个操作按钮会使表格整体样式看起来不太协调，所以当需要在表格内部提供操作按钮时，建议使用链接单元格，体验如下图所示：
示例地址：[链接](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=cell-type&:sheet=Link)
链接单元格的常见使用场景：
- **跳转外部链接或其他系统内部资源**：单元格中自带类似[打开链接](../../../app/superpage/design/action/linkto.md)交互的设置，可参考文档说明。
- **制作首页目录跳转到其他工作表**：效果类似Excel的超链接设置，点击后可以跳转到指定工作表的某个单元格上，支持导出Excel，导出后会自动转换成Excel中的超链接设置。
- **在单元格中添加业务操作**：如点击后总是下载一个文件供用户参考，点击后修改其他单元格的内容或是直接更新数据库中的数据等，类似的操作都可以通过链接单元格加交互的方式实现。
### 字格{#char-grid}
当需要上报一些财务数据时，数据位数较多，常规的输入方式容易导致错漏，在报表填报应用中提供了一种特有的**字格**输入方式，将单元格按照货币单位拆分为多个小格，方便用户对比数据，体验如下图所示：
示例地址：[字格](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=cell-type&:sheet=CharGrid)
### 进度条{#progress-bar}
当需要上报带有占比、进度等含义的百分比时。数值形式不便于比较和查看。使用**进度条**，能够将填入的数值自动显示为进度条，使数值间的对比更加明显，增强了易读性。
示例地址：[进度条](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=cell-type&:sheet=ProcessBar)
## 单元格类型变化{#type-change}
报表填报应用会根据单元格类型自动生成模型。在[发布报表填报应用](https://docs.succapp.com/v5/ci/publish)前，所有内部生成的模型都是临时的，此时修改**单元格类型**，模型也会相应变化。更多详细说明可参考[数据存储](../data-storage.md)文档。
在[发布报表填报应用](https://docs.succapp.com/v5/ci/publish)后，临时模型才会实际生成。此后再次修改单元格类型，模型中的字段类型也不会自行调整，比如原本为**文本输入**的单元格，生成的字段是**字符型**的，发布后将单元格类型修改为**数值输入**，字段不会自动调整为**浮点型**。
报表填报应用针对上述情况做了一些兼容性处理，即便存储的字段是字符型，单元格类型为**数值输入**，报表填报应用也能自动将填写的数值以字符串的形式存储到数据表中，类似的兼容性处理还有在日期单元格中存储字符型、整型等。还存在一些无法兼容的情况，比如数值单元格存日期型，此时需要在[模型管理](../../../data-gov/model/README.md)手动调整字段类型。
::: tip
下拉框和选择面板中**可选项**的数据类型必须与存储字段类型保持一致。如果可选项主键为**字符型**，实际存储数据为**整型**，可能会导致两个结果：1、装载数据时无法匹配可选项；2、对于不兼容类型转换的数据库，查询表单时可能会报错。
:::
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/design-form/condition-style.md"
htmlUrl: "https://docs.succapp.com/v5/ci/condition-style"
title: "条件样式"
---
---
order: 4
navTitle: 条件样式
---
# 条件样式
**条件样式**可以根据指定的条件动态更改单元格的外观。报表填报应用中仅支持**突出显示**和**最前最后**的条件样式，设置方式可参考报表的[条件样式](../../../report/design/style/condition-style.md)文档。本文主要介绍表单单元格特有的**计算**、**只读**、**禁用**等**状态样式**以及他们对应的显示规则。
## 状态样式{#state-style}
**状态样式**是指单元格处于某种特殊状态下才会展示的样式。报表填报应用的单元格拥有多种[状态](#cell-state)，在实际填报过程中，往往需要一目了然的知道各单元格处于什么[状态](#cell-state)，比如哪些单元格是可以填写的或哪些单元格的数据是计算得到的，为了便于区分这些单元格通常都会在样式上提供明显的特点。如下图所示，所有**计算单元格**都默认加上了斜线底纹：
### 单元格状态{#cell-state}
在报表填报应用中将单元格划分为多种状态，比如某些单元格总是只会显示固定内容，某些单元格的值是通过计算得到的等，在报表填报应用中单元格被划分为以下几种状态：
- **固定单元格**：内容中仅有固定文本或宏表达式的单元格，通常是作为标题使用，没有对应的状态样式，固定单元格的样式一般都是稳定不会修改的。
- **可输入单元格**：设置了[单元格类型](./cell-types.md)且未设置禁用或只读的单元格，没有对应的状态样式。
- **计算单元格**：添加了**计算公式**且满足**计算条件**的单元格，对应**计算状态样式**。
- **只读单元格**：设置了[单元格类型](./cell-types.md)且设置为只读的单元格，对应**只读状态样式**。
- **禁用单元格**：设置了[单元格类型](./cell-types.md)且设置为禁用的单元格，对应**禁用状态样式**。
### 状态样式显示规则{#display-rule}
**状态样式**总是**叠加**显示在当前单元格样式上。以计算单元格为例，当在单元格中添加计算公式后，不论单元格的样式是怎样的，总是会在原本基础上叠加一个斜线底纹：
::: tip 覆盖计算样式
默认的**计算样式**只是一个斜线底纹的背景图片，某些情况下即便单元格是计算的也不希望他有这个底纹，此时可以通过单元格**样式设置**>**单元格填充**>**图片填充**中设置背景图片为空来覆盖掉计算样式叠加的背景图片。
:::
## 自动切换状态样式{#change-state}
在填报过程中，单元格的状态有时并不是稳定的，例如某些单元格只有在满足条件的情况下才会计算，不满足条件时需要用户手动填写，这种情况下单元格会在计算和可输入两种状态间根据条件来切换；或是浮动表中不同行的计算规则不一样，某些行需要算合计，某些行需要手动填报：
| 切换状态样式 | 浮动状态样式 |
| :---: | :---: |
|  |  |
| 示例地址：[切换状态样式](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF%E7%99%BB%E8%AE%B0&:sheet=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF) | 示例地址：[浮动状态样式](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E4%B8%8A%E6%9C%9F%E5%80%BC&:dataPeriod=202401&:orgId=010101&:sheet=%E6%B5%AE%E5%8A%A8%E8%A1%A8-%E8%A1%A5%E7%BB%B4%E9%A1%B9) |
::: tip
通过**条件样式**能达到一样的效果，因为上述需求根源上也是根据条件在变换单元格样式。但是当表越大，涉及到的单元格越多时，这样设置就会变得极其复杂，比如有十个单元格是通过条件来决定是计算还是输入，则在**条件样式**的设置中对应的也需要十条规则，以此类推。**状态样式**通过一条规则即可批量的将所有满足状态的单元格附加上对应样式。
:::
## 自定义状态样式{#custom}
报表填报应用提供了三种状态可供设置样式，分别是**计算**、**只读**和**禁用**状态。默认配置下只有**计算样式**会叠加一个斜线底纹，**只读**和**禁用**不会叠加任何样式。当默认的样式不满足需求时，比如**计算状态**下不想用斜线底纹想修改为其他背景图案，或是**只读状态**下希望添加一个`-`作为占位符，此时可通过[修改风格](../../../report/design/style/table-style.md#cell-style)实现：
## 样式优先级{#priority}
单元格中有多种样式设置，不同的设置显示的优先级不同，下述样式设置的优先级按从低到高排列：
1. [主题风格](../../../report/design/style/table-style.md#cell-style)中的样式设置
2. [状态样式](#state-style)中的样式设置
3. 用户在单元格属性中自定义的样式设置
4. 浮动表的[隔行换色](../../../report/design/style/table-style.md#cell-even-backgroud)设置
5. 用户自定义的[条件样式](../../../report/design/style/condition-style.md)设置
当存在多个不同优先级的样式共同作用时，不同的样式属性是共同作用的，比如字体大小和单元格背景可以共同作用；相同的样式属性，由高优先级的样式设置覆盖低优先级的样式设置。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci/float-submit"
title: "浮动填报"
---
---
order: 5
navTitle: 浮动填报
---
# 浮动填报
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/read-and-write.md"
htmlUrl: "https://docs.succapp.com/v5/ci/read-and-write"
title: "限制浮动数据读写"
---
---
order: 1
navTitle: 限制浮动数据读写
---
# 限制浮动数据读写
在复杂业务中，常常需要多人协同维护浮动表。为确保数据安全准确，报表填报应用可根据用户角色灵活配置数据行操作权限。通过精细设定增删改条件，满足复杂权限需求，保障用户在授权范围内操作数据。下面以`OKR工作目标表`为例展开介绍。
示例地址：[OKR工作目标表](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%AE%A2%E6%88%B7%E6%9C%8D%E5%8A%A1%E6%83%85%E5%86%B5&:dataPeriod=202405&:sheet=%E5%AE%A2%E6%88%B7%E6%9C%8D%E5%8A%A1%E6%83%85%E5%86%B5)
此表格的维护需由部门成员共同参与，确保内容对所有成员公开透明。为确保数据的准确性和安全性，每位用户仅被授权修改和删除其自行添加的数据行。通过条件表达式进行灵活控制。
1. 在**修改行限制**和**删除行限制**中使用表达式：`F4 != 用户`，含义为当前行的`负责人`若不是当前用户，则无法**修改行**和**删除行**；
2. 若想限制用户只能看到自己添加的数据，则可在**行显示条件**中添加表达式`F4 = 用户`实现；
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/filter-and-sort.md"
htmlUrl: "https://docs.succapp.com/v5/ci/filter-and-sort"
title: "数据的筛选和排序"
---
---
order: 2
navTitle: 数据的筛选和排序
---
# 数据的筛选和排序
报表填报应用支持对浮动区域内列数据进行排序和筛选。排序支持默认、升序或降序三种排列方式；同时，筛选功能允许用户添加多条筛选条件，并支持多种逻辑判断，如“属于”、“等于”、“非空”等，以满足不同需求。下面以`员工信息表`为例展开介绍。
示例地址：[员工信息表](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF%E7%99%BB%E8%AE%B0&:sheet=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF)
在维护`员工信息表`时，由于企业员工人数较多，难以快速定位到对应员工数据行，添加筛选排序功能后能更快帮助我们定位到对应数据行。可在右侧浮动属性栏中通过勾选**点击列头排序**和**允许筛选数据**开启功能。
- **仅排序**：点击“姓名”旁的图标依次切换不排序、升序和降序；
- **仅筛选**：提供“部门”筛选条件编辑器，编辑器输入方式根据[单元格类型](../design-form/cell-types.md)不同而变化；
- **同时使用**；将排序与筛选条件放入同一个弹出框，共同作用于“入职时间”；
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/merge-cell.md"
htmlUrl: "https://docs.succapp.com/v5/ci/merge-cell"
title: "自动合并单元格"
---
---
order: 3
navTitle: 自动合并单元格
---
# 自动合并单元格
报表填报应用具备浮动区域内单元格的自动化合并功能，以满足不同业务需求。该功能提供多样化的合并策略，涵盖连续相同内容合并、分组合并以及跨区域合并等，具体业务适用场景及功能细节如下所述。
## 合并连续相同内容{#merge-consecutive-identical}
在制作`客户服务情况表`时，需要实现类似嵌套浮动的效果，提高可读性的同时简化数据输入，外层为“客户公司”，内层为“项目”，可填写多个“客户公司”，每个公司中又包含多个“项目”。
|合并前效果|合并后效果|
|---|---|
|||
示例地址：[客户服务情况](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%AE%A2%E6%88%B7%E6%9C%8D%E5%8A%A1%E6%83%85%E5%86%B5&:dataPeriod=202405&:sheet=%E5%AE%A2%E6%88%B7%E6%9C%8D%E5%8A%A1%E6%83%85%E5%86%B5)
通过以下配置可在`客户服务情况表`中实现嵌套浮动的填报效果：
1. 勾选“客户公司”单元格下的**合并连续相同单元格**，浮动方向上相邻且内容相同的多个单元格将合并；
2. 在填写“客户公司”后，只需选中“项目”单元格点击添加行，系统将自动生成一个新的项目行；
3. 若需新增“客户公司”，只需选中“客户公司”单元格点击添加行，系统将自动生成一个新的客户公司行；
## 按不同分类合并相同内容{#merge-by-group}
在`门店销售情况`中，为便于数据查阅，需将“门店”、“门店类型”和“门店级别”列进行合并。然而，直接勾选**合并连续相同单元格**可能导致跨部门数据的错误合并。为确保合并的准确性和实用性，可先根据“门店”进行分组，并在组内进行排序，随后再进行合并操作。
|普通合并|分组合并|
|---|---|
|||
示例地址：[门店销售情况](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%A4%9A%E7%BA%A7%E6%B5%AE%E5%8A%A8%E6%95%B0%E6%8D%AE%E5%A1%AB%E6%8A%A5&:sheet=%E5%88%86%E7%BB%84%E5%90%88%E5%B9%B6)
通过以下配置可在`门店销售情况`中实现分组合并的效果：
1. 首先将需要合并的列如“门店类型”和“门店级别”勾选上**合并连续相同单元格**；
2. 将“门店”作为**分组合并**的依据单元格,这样设置之后，在合并前首先会判断两行数据是否属于同一“门店”，只有属于同一个“门店”时才会合并；
## 合并相邻空白内容{#merge-adjacent-blank}
在`网络外卖餐饮专项整治统计表`中，使用“项目表”进行[补足维项](./supplement-data.md#items-complement)。项目信息由分类、来源和名称构成，但部分项目因缺乏来源信息，导致表单中出现不必要的空白单元格，影响视觉体验。为提高页面美观度，建议对无来源信息的项目采取与左侧空白单元格合并的处理方式。
|普通合并|合并相邻空白内容|
|---|---|
|||
示例地址：[网络外卖餐饮专项整治统计表](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%A4%9A%E7%BA%A7%E6%B5%AE%E5%8A%A8%E6%95%B0%E6%8D%AE%E5%A1%AB%E6%8A%A5&:sheet=%E5%90%88%E5%B9%B6%E7%9B%B8%E9%82%BB%E5%8D%95%E5%85%83%E6%A0%BC)
通过以下配置可在`网络外卖餐饮专项整治统计表`中按非浮动方向合并空白单元格：
1. 勾选**合并指定相邻单元格**；
2. 将B4作为相邻单元格，当B4为空或与项目名称相同时，则会往左合并；
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/supplement-data.md"
htmlUrl: "https://docs.succapp.com/v5/ci/supplement-data"
title: "补足浮动数据"
---
---
order: 4
navTitle: 补足浮动数据
---
# 补足浮动数据
报表填报应用支持浮动行内自动补足维项或空白行，减少了用户手动输入或复制粘贴的繁琐操作，提高了编制效率。同时，由于减少了手动操作，该功能也大大降低了错误的可能性，确保了数据的准确性。
- **补足场景**
- **无数据时补足**：默认选项，当数据库中没有数据时补足；
- **初次填报时补足**：仅在第一次填报时才补足；
- **总是补足**：在任何情况下都将补足；
- **满足条件时补足**：可以按照条件进行灵活补足，如根据不同的填报单位和数据期判断是否需要补足；
- **提交补足行**
- **自动**：默认选项，当补足方式为补维项时，所有补足行都将被提交；补空白行时，只有手动修改的行才会被提交；
- **总是提交**：无论如何，所有补足行都将提交；
- **提交手动修改的行**：只有手动编辑过的补足行才行会被提交；
## 补足空白行数据{#fill-with-blank}
在填写`入职登记表`时，对于“教育经历”和“培训情况”，通常情况下用户都不会只单独录入一条，如果事先预留出多个空行，这样用户在填报时就无需再多次添加行了。
示例地址：[入职登记](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%85%A5%E8%81%8C%E7%99%BB%E8%AE%B0%E8%A1%A8&:newData=true&:sheet=%E5%85%A5%E8%81%8C%E7%99%BB%E8%AE%B0%E8%A1%A8)
通过以下配置可在`入职登记表`中自动添加空白行：
1. 在“教育经历”和“培训情况”浮动主键上勾选**补足空白行**
2. 分别设置补足3行空白行
## 补足维项数据{#items-complement}
设计`网络外卖餐饮专项整治统计表`时，考虑到本次专项整治计划的“项目”在填报前就已确认，维护在`项目表`中，在填报时希望能够直接将所有的项目展示出来，并且连同项目的来源和分类信息一同展示。
示例地址：[网络外卖餐饮专项整治统计表](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%A4%9A%E7%BA%A7%E6%B5%AE%E5%8A%A8%E6%95%B0%E6%8D%AE%E5%A1%AB%E6%8A%A5&:sheet=%E5%90%88%E5%B9%B6%E7%9B%B8%E9%82%BB%E5%8D%95%E5%85%83%E6%A0%BC)
通过以下配置可在`网络外卖餐饮专项整治统计表`中自动添加维项成员行：
1. 使用**补维项**将项目补全；
2. 使用[LOOKUP()](../../../exp/func/others/LOOKUP.md)可查取到“来源”和“分类”，这样就能实现在补足维项的同时补足表单的数据完成初始化；
3. 若仅需要展示部分维项成员，则可以通过[维项过滤](../../../app/superpage/components/input/combobox.md#dimension-filtering)控制；
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/level-subtotal.md"
htmlUrl: "https://docs.succapp.com/v5/ci/level-subtotal"
title: "分级小计"
---
---
order: 5
navTitle: 分级小计
---
# 分级小计
当浮动区域增加新行时，报表填报应用支持自动为该区域添加上级节点（即小计行），并基于关联表的层级结构自动进行数据的求和。这一功能在填报时中极大地提升了填报效率，下面以`车辆销量统计表`为例展开介绍。
示例地址：[自动添加小计行](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%88%86%E7%BA%A7%E5%B0%8F%E8%AE%A1&:dataPeriod=202405&:sheet=%E8%87%AA%E5%8A%A8%E6%B7%BB%E5%8A%A0%E5%B0%8F%E8%AE%A1%E8%A1%8C)
在`车辆销量统计表`中需要计算不同车型的销量合计值。每当有新的车型商品被添加至统计表时，需同步为其添加上级小计节点，以便快速计算该节点下所包含的多个车型的合计销量。
1. 开启**自动添加小计行**；
2. 勾选**自动汇总**；
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/summary-floatdata.md"
htmlUrl: "https://docs.succapp.com/v5/ci/summary-floatdata"
title: "汇总浮动数据"
---
---
order: 6
navTitle: 汇总浮动数据
---
# 汇总浮动数据
在实际填报场景中，数据需层层上报，上级往往作为汇总节点。处理浮动数据时，有两种方式：基于主键汇总和直接展示所有下级数据。这两种方式各有优势，适用于不同业务场景，具体介绍如下。
## 按主键汇总下级浮动数据{#summarize-by-key}
“财务部”和“人力资源”属于“行政中心”，其中下级单位填报数据后，上级单位需要对下级单位的数据进行汇总，希望统计整个“行政中心”下不同类别的销量，需要按照“车型”进行分组汇总。
示例地址：[按主键汇总下级浮动数据](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E6%B1%87%E6%80%BB&:orgId=9120&:dataPeriod=202406&:sheet=sumFloat-primary)
通过以下配置可在`部门销售情况`实现上级单位按照“车型”汇总下级单位的浮动数据：
1. 首先开启**自动汇总**（设置->上报管理->启用自动汇总）；
2. 浮动区域汇总方式选择**按主键汇总**。上级单位会自动汇总下级单位的数据，将车型相同的浮动行的数据进行汇总；
## 列出下级浮动数据{#list-org}
分公司C负责统计其下属子公司G、H、I的在岗职工情况。在编制`在岗职工统计表`时，统计表应详尽地展示各子公司中不同岗位分类下的人数明细数据。
示例地址：[列出下级单位数据](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%88%97%E5%87%BA%E4%B8%8B%E7%BA%A7%E5%8D%95%E4%BD%8D%E6%95%B0%E6%8D%AE)
在开启汇总时，浮动也可以设置为不汇总浮动表数据，将所有下级单位的数据以浮动表的形式在上级单位的表单中展示出来,具体配置步骤可参考[取数计算](../fetch-and-calc.md#list-org)。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/float-submit/import-data.md"
htmlUrl: "https://docs.succapp.com/v5/ci/import-data"
title: "导入浮动数据"
---
---
order: 7
navTitle: 导入浮动数据
---
# 导入浮动数据
在数据填报环节，无论是通过导入还是粘贴操作，浮动表都需基于浮动主键合并。实际业务中，常将表单导出为Excel模板供用户填报，但此时浮动主键可能被隐藏。导入时系统将难以分辨数据行是新增还是更新，且难以精准定位至目标行。因此，推荐选取一个显性的、具有唯一性的**业务单元格**作为浮动行的定位基准,下面以`员工信息登记表`为例展开介绍。
示例地址：[员工信息登记表](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF%E7%99%BB%E8%AE%B0&:sheet=%E5%91%98%E5%B7%A5%E4%BF%A1%E6%81%AF)
此表在设计时，“唯一键”列被隐藏，Excel模板未含此列，导致导入时无法定位浮动行。为确保准确性，需确保新员工的数据为新增数据，老员工的数据需要修改。需在导入前选定**业务单元格**,由于身份证同样可以作为唯一标识，所以可选取“身份证号码”为**业务单元格**，在导入时将根据**业务单元格**进行浮动行定位。
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/fetch-and-calc.md"
htmlUrl: "https://docs.succapp.com/v5/ci/fetch-and-calc"
title: "取数和计算"
---
---
order: 6
navTitle: 取数和计算
---
# 取数和计算
报表填报应用支持多种灵活的取数和计算方式，包括基本的四则运算，[函数](../../exp/func/README.md)计算，从数据模型中取数等各种情况。本文主要介绍在各种不同的业务场景下，如何使用报表填报应用的取数计算能力。以下是计算相关的基本属性设置：
## 默认值{#default-value}
**默认值**是一种只会在页面初始化时计算一次的表达式，后续不会因为用户填报表格或点击计算按钮而重新计算。通常用于新增数据时，计算一个初始值，用户在后续填报时可以根据实际业务情况进行再次修改。对于计算后就不再修改的内容，比如按照固定的规则生成主键或计算创建人等，此时还需要额外设置单元格不可填写。
示例地址：[默认值](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=default_value)
## 计算公式{#calc}
**计算公式**是可以按需进行再次计算的公式，当计算公式引用的其他单元格发生变化时会自动重新计算，当用户点击**计算**按钮时也会重新计算。比如在表单中需要在填写过销量和单价后自动计算出销售金额，则可在填写销售金额的单元格中添加**计算公式**，计算单价和销量相乘的结果。
示例地址：[计算公式](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=inter_table_calc)
::: tip
1. **计算条件**可以控制**计算公式**只在条件返回`TRUE`或为空时才会计算，例如根据输入的身份证号码来计算出生日期、性别，只有当输入的内容是符合身份证号码规范的时候计算才有意义，此时可以设置计算条件为`pidcheck(身份证号码)`。
2. 单元格添加**计算公式**后，会自动叠加上**计算**状态样式，默认是一个斜线底纹，详细规则可参考[条件样式](./design-form/condition-style.md)文档。
3. 有**计算公式**的单元格默认不可填写，当需要填写时，需要设置**单元格**>**输入**>**禁用/只读**属性为**启用**。
:::
## 取数公式{#fetchdata}
**取数公式**可以自动从数据库或第三方业务系统获取实际的数据并初始化到表格，供用户确认后按需修改并上报。实际使用过程中，可能会对一个数据集按多种取数口径来取数，类似报表查询，如下示例所示：
示例地址：[取数公式](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=fixed_fetchdata)
给**取数公式**添加**取数条件**的过程类似于在报表单元格上添加[过滤](../../report/design/data/README.md#filter)，例如上述示例地址中的报表填报应用，所有的**取数公式**其实都是在对一份明细数据求[COUNT](../../exp/func/aggregate/COUNT.md)，只是会用不同的取数条件来过滤得到不同维度下的明细数据结果。
::: tip
1. **取数条件**等价于报表单元格的过滤条件，它是对数据集过滤条件的一种补充，与数据集过滤条件是AND的关系。
2. **取数执行条件**等价于计算公式的**计算条件**，是在满足这个条件的情况下才会计算**取数公式**。
:::
## 根据业务场景选用公式{#choose}
由于默认值、计算公式以及取数公式的计算逻辑不同，业务上存在一些容易混淆的情况可能导致公式错误配置，以下述常见场景进行说明：
- 以[UUID](../../exp/func/string/UUID.md)作为主键存储。
- 错误配置：在**计算公式**中添加`UUID()`，这会导致主键内容不稳定，每次手动触发计算都会导致主键发生变化。
- 正确配置：在**默认值**中设置，这样生成的主键就是稳定不变的。
- 初始化时以前期数据作为默认值，并可在得到的结果基础上继续修改，修改后的内容不希望被覆盖掉。
- 错误配置：在**计算公式**中使用[PRE](../../exp/func/analysis/PRE.md)函数计算前期数据，并设置单元格允许编辑，这会导致触发计算交互时，这些不希望被覆盖的数据会因此重新计算而被覆盖。
- 正确配置：在**默认值**中配置，由于默认值初始化时仅计算一次的原则，后续触发的计算或取数交互都不会对其造成影响所以总是不会覆盖数据。
- 初始化时以前期数据作为默认值，并可继续修改，初始化的来源数据可能发生变化，需要手动同步最新数据后继续修改。
- 错误配置：在**默认值**或**计算公式**中配置，并设置单元格允许编辑，如果是默认值则后续来源数据修改无法同步，如果是计算公式则会导致手动修改的数据很容易无意中被覆盖掉。
- 正确配置：在**取数公式**中配置，页面初始化时获取初始值，可以继续修改，当数据来源发生变化后点击取数按钮重新取数即可，还可仅对指定有变化的数据集进行重新取数。
- 根据下拉框可选项内容计算，计算得到的内容还可继续修改。
- 错误配置：在**计算公式**中获取下拉选项相关内容，并设置单元格允许修改，这样设置会导致手动触发计算其他内容时此处修改过的值也会重新计算进而发生数据覆盖。
- 正确配置：通过**设置组件属性**交互来设置单元格的值，当下拉框值发生变化时触发交互同步修改需要发生计算的其他单元格，后续触发计算也不会导致这里的内容被覆盖。
- 单元格之间存在计算逻辑，导出Excel后在Excel中进行修改，然后导入回表单，希望导入的结果和文件中的内容一致。
- 错误配置：在**计算公式**中配置相应的计算逻辑，并且设置单元格允许修改，这种情况下导入最后计算公式总是会重新计算导致导入的结果与文件中的不一致。
- 正确配置：通过**设置组件属性**交互来设置单元格的值，单元格允许编辑，此时再次导入不会重新触发计算。
## 计算优先级{#priority}
报表填报应用中有多种数据来源，除默认值、计算公式以及取数公式外，还可以有汇总数据和补足数据，当这些数据来源同时作用时，按以下优先级计算：
1. 提交过数据后，如果单元格有绑定字段，则再次进入表单总是以**绑定字段**中装载的数据为主，不会计算其他表达式。
2. **汇总数据**仅在查看上级单位的表单时有效，如果上级单位没有提交过数据且设置了汇总，则此时以汇总为主，如果此时汇总的单元格上有**计算公式**，且**计算公式**中引用了其他汇总单元格，则汇总后该**计算公式**会因为被影响计算而自动计算一次。
3. 新增数据时，如果此时不是汇总单位，则按照**取数公式**>**默认值**>**计算公式**的优先级来计算。
4. **计算公式**总是会在引用的内容发生变化的情况下自动计算。
5. **补足数据**只能在浮动表中作用，优先级总是最低的，当汇总、取数或装载的数据不满足期望的行数时，才会处理补足。
6. 汇总、取数、计算都可通过对应的按钮强行触发计算。
## 应用场景{#scenarios}
### 取前期数据{#pre}
有时需要将以前填报的数据作为参考值显示在表单中。比如填报每月的收支情况，希望在填本月的数据时能够对比下上月的数据，此时可以使用[PRE](../../exp/func/analysis/PRE.md)函数来获取上一期的数据。
示例地址：[上期值](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E4%B8%8A%E6%9C%9F%E5%80%BC)
::: tip
[PRE](../../exp/func/analysis/PRE.md)函数针对字段使用时，需要带上字段的模型前缀，使用类似`pre(model1.field1)`的表达式来获取字段对应的前期数据。
:::
### 浮动表取其他模型数据{#float-fetch}
填报浮动表时，可使用**取数公式**来初始化一批数据到浮动行中。这样做的好处在于填报时无需自行添加行，大部分能直接通过查询得到的内容不需要用户再手动输入，用户只需要填写必要的数据即可。例如填报产品销量明细，可将要填写的产品以及部分规格参数初始化到浮动表中，用户只需要填写每类产品的销售单价以及销售数量即可。
示例地址：[浮动取数](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=float_fetchdata)
以产品销量填报为例，浮动表取其他模型的数据有以下几个关键步骤：
1. 对取数模型施加过滤条件，仅保留需要获取的数据，此处只保留第一级的产品数据。
2. 在**浮动单元格**中设置**取数公式**为`产品表.代码`，这决定了在做取数查询时会以这个字段作为查询的主粒度，即当前产品表中有多少行数据那么浮动区域中初始化的行也一定是一致的。
3. 在浮动区域的其他单元格中设置需要一起取数的内容，此处需要获取产品名称，因此在B3单元格中设置**取数公式**为`产品表.名称`。
::: tip
1. **取数公式**的应用可以看作是一个报表查询，报表填报应用只是将查询的结果存储到填报模型中。
2. 基于上述概念，浮动表取数时，浮动单元格必须设置**取数公式**。如果没有，效果等同于报表的浮动单元格中未设置计算公式，会导致查不出来任何数据。
3. 浮动表的主键是技术键时，比如UUID，此时浮动单元格可以没有**取数公式**，但浮动区域必须设置**业务单元格**，**业务单元格**中必须有**取数公式**，此时取数的查询会以**业务单元格**为依据。
4. 当**浮动单元格**或**业务单元格**有关联维表，此时通过**数据补足**搭配**计算公式**可以达到一样的取数效果，具体操作可参考[浮动设置](/ci/floating)文档。
:::
### 列出下级单位数据{#list-org}
上级单位填报时，有时需要参考下级单位的数据。如果按照默认体验去查看下级单位的数据，需要频繁的在填报单位树中切换，因此会将所有下级单位的数据以浮动表的形式在上级单位的表单中展示出来。
示例地址：[列出下级单位数据](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%88%97%E5%87%BA%E4%B8%8B%E7%BA%A7%E5%8D%95%E4%BD%8D%E6%95%B0%E6%8D%AE)
以在岗职工统计表为例，在上级单位的表单中列出所有下级有以下几个关键步骤：
1. 克隆当前填报数据集，右键点击**设置**，在**高级**标签页下勾选**自定义加载数据条件**。
2. 添加**加载数据条件**，设置`数据期=当前数据期`和`填报单位.上级单位=当前单位`，意思是要过滤出所有当前数据期下本单位的下级单位数据。
3. 添加**浮动区域**，绑定上述克隆数据集，并在对应的单元格上设置好**绑定字段**，这样设置后，打开表单时如果克隆数据集过滤后有数据则会自动装载到表单浮动区域中。
4. **浮动区域**设置显示条件`当前单位.SZ_LEAF != '1'`，仅在上级单位打开表单时才显示。
::: tip
**周期填报应用**中所有与单元格有绑定关系的数据集都有默认的数据期、填报单位过滤条件，这限制了填报者不能越权操作其他单位的数据，因为这个限制，默认情况下，表单中是无法直接展示其他单位数据的。详细说明可参考[数据存储](./data-storage.md)文档。
:::
### 取单行数据集的数据{#onerowquery}
当数据来源于同一模型且有相同的取数口径时，建议使用**单行数据集**取数。单行数据集的取数方式可参考**SuperPage**的[取数和计算](https://docs.succapp.com/v5/guide/superpage/fetch-and-calc)文档。表单示例如下：
示例地址：[单行数据集](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=index_calc)
### 取指标数据集的数据{#measure}
通过#表达式，可获取**单主键**模型指定行的数据，常用于获取指标的相关信息进行计算。例如员工绩效考核，需要根据不同的考核项来填写员工的分数，以固定表的形式填报存储时按[行存储](./design-form/data-mapping.md#row-table)，填报时需要表样中提供每个考核项的总分值供填报人参考，表单示例如下：
示例地址：[指标计算](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=index_calc)
在固定行表中，指标项的行表条件通常会覆盖整行，但是条件区域内的计算公式不会作用行表条件，即在计算公式中使用`数据集.字段`来获取指标中的信息时，即便在条件区域内存在行表条件来过滤指定行，此时计算公式中引用的数据集也不会作用这个条件，这会导致数据集仍是多行的无法计算出结果，此时需要通过#表达式来获取指定行数据。
1. 引用的数据集本身是单主键或添加完过滤条件后仅余下某个主键未被过滤时，编辑表达式，在这类数据集后写#会提示所有候选项的信息。
2. 通过形如`数据集#[指标ID].字段`的表达式可以获取到该数据集指定行某个字段的值。
### 使用QUERY函数取数{#query}
当要取的数据比较简单且数据量不大时，可在计算公式中使用[QUERY](../../exp/func/others/QUERY.md)函数达到效果，具体使用场景可参考[QUERY](../../exp/func/others/QUERY.md)函数文档。表单示例如下：
示例地址：[QUERY函数](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=query_func)
### 一致性维度计算{#conformeddim}
不同浮动区域按相同维度浮动时，此时认为它们具有一致性维度，例如都是按产品类型浮动出所有产品小类。当具有一致性维度的浮动区域间需要相互引用内容进行计算时，如下示例所示：
| 填写数据 | 根据一致性维度同步内容 |
| :------: | :------: |
|  |  |
示例地址：[一致性维度计算](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=conformed_dimenson)
1. 浮动表A按产品浮动，用于填写各小类产品的销售情况。
2. 浮动表B同样按产品浮动，用于同步浮动表A中填写的零售单价和销售数量。
3. 两表都是按产品类型浮动的，具有一致性维度，此时可在浮动表B中直接引用浮动表A中的单元格，即形如`浮动表A.D4`的表达式即可，系统会自动按照对应的产品类型来得到相同产品类型的数据。
::: tip
1. 如果不使用一致性维度计算规则，当存在这种跨浮动区域的引用时，需要通过[浮动函数](../../exp/func/float/FALL.md)来明确需要获取浮动结果中哪一行的数据，即上述获取相同产品的数据需要使用类似`FGET(浮动表A.D4,浮动表A.A4=A4)`的表达式，意为依据当前浮动行的产品类型来获取浮动表A中相同类型的数据，这样写相对比较麻烦。
2. 一致性维度计算只适用于在一个浮动区域中获取另一个浮动区域中相同行的数据，即上述类似获取相同产品类型数据的场景，如果需要获取不同行的数据，例如产品类型为A1的行要获取其他浮动区域中产品类型为A2的数据，此时还是需要借助[浮动函数](../../exp/func/float/FALL.md)来达到目的。
:::
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/validate.md"
htmlUrl: "https://docs.succapp.com/v5/ci/validate"
title: "数据校验"
---
---
order: 7
navTitle: 数据校验
---
# 数据校验
**数据校验**是报表填报过程中管控数据质量的重要功能，通过使用批量校验它也能快速的检验一批历史数据的数据质量。数据校验支持取第三方数据、前期数据、跨表数据等做各种灵活的校验设置。本文主要介绍如何添加**数据校验**规则，填报时的校验错误处理请参考[填报数据](../filling.md)文档。
示例地址：[医院人事](https://demo.succbi.com/v5/ci/%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B)
## 添加校验规则{#add-rules}
校验规则有多种设置入口，如下图所示：
- **单元格属性设置**：设置[单元格类型](./design-form/cell-types.md)后，在**单元格**>**校验**设置中可设置单元格必填或添加校验公式。
- **工具栏校验按钮**：通过工具栏**校验按钮**，可添加[逻辑校验规则](#logic-rules)或[批量设置必填](#nonempty)。
- **校验面板工具栏**：在[校验列表](#validate-panel)中可统一管理所有校验公式，点击工具栏添加按钮可添加校验规则。
## 校验规则列表{#validate-panel}
**校验规则列表**是报表填报应用统一管理校验公式的地方，在工具栏>校验菜单中点击**显示所有校验公式**可在报表填报应用设计器底部弹出**校验列表**，也可在[视图](./designer.md#view)中勾选**校验公式**来显示。
- 除了在单元格中设置校验规则外，还可在表单全局设置中直接添加校验规则，所有的校验规则都会统一收集到**校验列表**中展示。
- 校验规则按照所属的工作表进行划分，默认情况下会在**校验列表**中展示所有工作表中的校验规则，也可切换只展示当前工作表中设置的校验规则或是选中某个单元格来展示跟该单元格相关的校验规则。
- 双击**校验列表**中的那些在全局添加的校验规则可进行修改，如果是单元格上添加的规则则是定位到对应单元格的属性设置中。
### 校验规则的筛选和搜索{#filter-search}
在**校验列表**中支持对校验规则进行筛选和搜索，如下操作所示：
- 点击工具栏中的筛选按钮会弹出筛选菜单，支持根据多种维度来筛选面板中展示的规则。
- 展示：选择展示的范围，包括当前表单上的校验公式，选中单元格上的校验公式以及全部校验公式。
- 级别：校验公式的**错误级别**，可多选，只展示勾选级别的校验公式。
- 分类：校验公式分为[逻辑校验](#logic-rules)和[必填](#nonempty)两类，可多选，只展示勾选分类的校验公式。
- 点击工具栏搜索按钮，弹出搜索框，输入关键字会实时过滤所有包含该关键字的校验公式，能够搜索的范围是当前校验面板中筛选后的结果。
### 更多操作{#more-opertions}
- 校验面板中的规则支持导入导出，点击校验面板工具栏更多按钮可将设置好的校验公式批量导出，也可将Excel中准备好的符合规范的校验公式批量导入到报表填报应用中。
- 在校验面板中支持框选多行校验规则，右键批量设置这些规则的属性，比如批量设置禁用，禁用后的规则会被置灰，或者批量的将错误级别的规则修改为警告级别。
## 逻辑校验规则{#logic-rules}
点击**工具栏**>**校验**按钮可新增**逻辑校验**公式，设置对话框如下：
- **编号**：校验公式的编号，报表填报应用默认会以`CHK`开头往后排序，用户也能根据一些业务含义来自定义，比如某些校验规则是国家标准，可以设置编号与标准一致方便后期维护和比对。
- **错误级别**：分为**错误**和**警告**两种级别，**错误**级别的规则必须全部通过才能提交数据，**警告**级别的规则即便不通过也不影响数据的提交，此处设置会受到应用设置中[校验分级](./settings/datafill.md#validate-grade)设置的影响。
- **校验公式**：校验规则的主体，决定了内容要满足什么样的要求，比如`A1>100`，当单元格A1的值大于100时则通过校验。编辑校验公式时支持拾取单元格。
- **错误提示**：当未通过校验规则时展示给用户的提示信息，通常是为了告诉用户怎么样输入正确的值。
- **生效条件**：生效条件为空或者返回`TRUE`时才作用这条校验规则。
::: tip
校验公式启用时，如果校验相关的元素都不可见，则校验公式默认失效，例如校验`A1>B1`，假设Excel表单第一行是隐藏的，此时界面上无法看到A1和B1单元格，则这条校验公式默认不生效，因为即便生效，用户也没有办法修改。
:::
### 高级设置{#advanced-settings}
逻辑校验对话框中，可展开**高级设置**，高级设置中包含以下设置：
- **启用**：控制校验公式是否启用，禁用后校验时会忽略这条公式。
- **允许特例**：允许对这条校验公式进行特例说明，勾选后，即便未通过校验也可以在填写过特例说明后正常提交数据，需要搭配**应用设置**>**数据填写**>[特例校验](./settings/datafill.md#special-validate)相关设置使用。
- **备注**：针对校验公式的一段描述信息，方便后续维护修改。
### 通过生效条件简化校验{#condition}
在实际场景中经常会遇到一些比较复杂的校验规则，以下面这条校验规则为例，其中包含多种情况，不同情况需要校验不同的规则：
`CASE WHEN A1='1' THEN B1>C1 WHEN A1='2' THEN B1+C1=D1 WHEN A1='3' THEN B1*C1=D1 WHEN A1='4' THEN B1=C1 END`
类似上述这类比较复杂的校验公式，都可以通过拆分后分别设置生效条件来简化设置，使多个公式整体修改的更为易读且方便后期维护，以下是拆分后的设置：
| 校验公式 | 生效条件 |
| :---------| :-------- |
| B1>C1 | A1='1' |
| B1+C1=D1 | A1='2' |
| B1\*C1=D1 | A1='3' |
| B1=C1 | A1='4' |
::: tip
当出现校验错误时，校验公式中所有涉及的单元格都会被标红提示，例如`IF(A1=1,B1>C1)`，出错时A1，B1，C1单元格都会被标红处理。这条校验规则也可以修改为`B1>C1`，然后在生效条件中设置`A1=1`，这样设置后只会将A1单元格中的内容作为依据来判断校验规则是否生效，实际校验的内容还是B1和C1，所以此时即便校验错误也只会在B1和C1单元格处提示。
:::
## 批量添加必填{#nonempty}
除**逻辑校验**外，报表填报应用还支持批量设置**必填**，点击**工具栏**>**校验菜单**选择**必填**设置：
必填设置是将报表填报应用中所有与单元格有绑定关系的模型列到对话框中，用户可切换模型后批量选择某些字段需要**必填**，确定后，报表填报应用会根据选择的字段找到对应绑定的单元格来批量设置**必填**。
::: tip
此处的设置只是一种快捷方式，效果等价于直接在单元格上设置**必填**。
:::
## 启用批量校验{#batch-valid}
给[周期填报应用](./create-formapp.md#choose-types)设置好校验公式后，在**报表填报应用设置**>[数据填写](./settings/datafill.md)>**数据校验**中可开启**启用批量校验**。**批量校验**可以帮助管理员对一批单位数据快速校验，执行批量校验时，会针对每条数据使用报表填报应用中配置好的校验公式进行校验，全部校验完成后会返回结果，具体使用过程可参考[填报数据](../filling.md)文档。
## 应用场景{#scenarios}
### 警告校验和特例校验{#worning-rules}
某些校验公式比较特殊，即便在不满足校验规则的情况下也可以允许用户提交数据。当设置校验公式为警告级别时，默认只会在提交数据时对用户给出警告信息，但用户仍可正常上报数据；允许校验公式添加特例时，即便校验错误用户也可在校验时添加特例说明让这条校验公式无条件通过，相关具体的校验体验可参考[填报数据](../filling.md)文档。
示例地址：[警告和特例](https://demo.succbi.com/v5/ci/%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B)
### 可选项范围校验{#dim-rules}
报表填报应用支持从Excel中导入数据，有时会出现导入的数据中存在垃圾数据的情况，比如单元格下拉框中可选的范围是A、B、C，但导入的内容却是一串文字，默认情况下在提交数据时会针对这种错误进行自动判断，不在单元格可选项范围内时不允许提交。如果需要禁用这种判断可参考[数据填写](./settings/datafill.md#else)文档。
### 跨表校验{#cross-rules}
报表填报应用支持跨表校验，当多个标签页下的表单数据存在校验关系时，可使用[逻辑校验](#logic-rules)设置来定义规则：
示例地址：[跨表校验](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%8D%AB%E7%BB%9F1-1%28%E5%8C%BB%E9%99%A2%E7%B1%BB%29&:dataPeriod=2024)
1. 添加[逻辑校验](#logic-rules)规则，可直接通过**单元格拾取**来获取多张表下单元格的数据，比如此处当前表的`招生人数`要小于另外一张表的`编制人数`。
2. 校验公式添加完成后，可在**校验列表**中点击数据列下内容分别定位到校验公式中涉及到的不同元素。
::: tip
1. 校验面板中有一列`工作表`数据，代表对应的校验公式是属于哪个工作表的。
2. 当所有校验相关的单元格都属于同一个工作表时，则校验公式中只需要定义类似`A1>B1`的公式即可。
3. 当涉及到跨表校验时，会将写入的第一个单元格对应的工作表作为这条校验公式的所属工作表，继续添加其他工作表中的单元格时，需要添加表名前缀，如`工作表1.A1`。
:::
### 取浮动行数据校验{#float-rules}
当表单中包含固定表以及浮动表时，有时需要获取浮动表中的数据和固定表中的内容进行对比校验，例如所有报销明细的金额相加要小于本次报销额度，报销明细中属于聚餐费用的部分应当每条都不超过500等。此时需要使用[浮动](../../exp/func/float/README.md)函数来设置校验公式。
示例地址：[浮动校验](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E7%BD%91%E7%82%B9%E7%BB%B4%E6%8A%A4&:orgId=110000&:sheet=%E7%BD%91%E7%82%B9)
### 取模型数据校验{#query-rules}
在表单中，有时不会列出所有校验所需的元素，例如填写人员的统计数据时，某些校验规则需要另外的人员明细表数据做汇总求和后的结果来和表单中填写的数据进行比对，如果数据量不大且需要计算的内容不多时，可以在校验规则中使用[QUERY](../../exp/func/others/QUERY.md)函数来获取需要的数据。此处是在校验公式中结合使用了[取数](./fetch-and-calc.md)能力，具体可参考**SuperPage**的[取数和计算](https://docs.succapp.com/v5/guide/superpage/fetch-and-calc)文档。
### 行列间批量校验{#batch-settings}
当某些连续的行列中有着类似的校验公式时，比如C列每行的值都得分别大于D列每行的值，此时可在校验规则中设置类似`[C1:C10]>[D1:D10]`的行列间批量校验的规则，避免反复的在校验规则中添加类似`C1>D1`、`C2>D2`的设置。
示例地址：[行列间批量校验](https://demo.succbi.com/v5/DEMO/app/case/market-suprvision-system.app?:id=%E8%A7%92%E8%89%B2%E5%88%87%E6%8D%A2)
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/workflow.md"
htmlUrl: "https://docs.succapp.com/v5/ci/workflow"
title: "审批流程"
---
---
order: 8
navTitle: 审批流程
---
# 审批流程
报表填报应用内置了易用的流程设计器，可以帮助用户绘制审批流程。搭配表单的填写可呈现一个完整的业务流程，比如在进行销售数据管理时市级单位填报后，经过层层审批后上报集团总公司。
示例地址：[层层审批](https://demo.succbi.com/v5/ci/%E5%B1%82%E5%B1%82%E5%AE%A1%E6%89%B9)
## 流程设计器 {#designer}
流程设计器是用来绘制流程的可视化工具，提供图形化的界面，可以方便直观地定义整个流程。报表填报应用在绘制流程之前需要在设计器的**设置**>**上报管理**中**启用审批**。[启用审批](./settings/submit-management.md#data-examine)后报表填报设计器导航栏会新增一个流程的标签页，在此页面可绘制填报流程。关于流程设计器的详细介绍可见[工作流设计器](../../app/workflow/new.md#designer)。与低代码的工作流不同的是，报表填报应用内置的流程设计器与填报工作表共用数据源。
## 设计业务流程 {#design}
设计业务流程不仅仅是指流程图的绘制，还包括对每个任务节点处理人、可执行的操作、数据权限、消息通知等整个审批完整的业务流程设置，具体内容可见下方章节。
### 绘制流程图 {#draw}
绘制流程图是指使用流程设计器中的节点与分支呈现一个工作流程或业务流程的过程。流程图中每个节点都代表一个工作任务（除了开始节点和结束节点）。关于如何绘制流程图以及流程节点、流程线条的介绍具体可见文档[绘制工作流](../../app/workflow/design.md)。表单除了可以自己绘制流程外还可以[直接引用外部流程](./settings/submit-management.md#data-examine)，引用的外部流程会同步在流程设计器中，但在流程设计器中外部流程不可编辑修改。
### 节点处理人设置 {#candidate}
节点处理人是在流程流转到节点时，能查看流程数据并进行数据填写、审批、任务分配等处理操作的用户。比如请假流程中，能审批请假单的用户就是审批节点的处理人。对于节点处理人的设置具体可见文档[节点处理人设置](../../app/workflow/candidate.md)。
### 流程操作 {#operate}
不同的任务节点根据业务流程可以指定不同的操作。工作流支持提交、批准、否决、退回等多种操作。如在请假申请中，用户申请时的任务节点操作为提交，在管理员审批时的任务节点操作为批准和退回。关于流程操作的设置具体可见文档[流程操作](../../app/workflow/operate.md)。流程操作常搭配不同的操作按钮进行，比如退回操作搭配退回按钮等。与低代码不同的是表单会自动根据流程节点上的操作来显示按钮，无需人为控制按钮的显示隐藏或禁用。
### 节点数据和权限设置 {#datapermissions}
节点数据权限设置用于控制不同的流程节点中表单输入项的权限，比如请假申请时可以输入请假原因、请假类型等，但是部门经理审批请假单时却只能查看而不能修改请假原因、请假类型等内容。更多详情可见文档[节点数据和权限设置](../../app/workflow/datapermissions.md)。
### 消息通知 {#notice}
消息通知是指流程流转时，系统能自动给相关负责人发送通知消息。比如张三发起请假申请，其组长李四会收到一条待办任务的通知。通过消息中携带的链接，能直接打开对应的处理页面，提升流程处理效率。更多详情可见文档[消息通知](../../app/workflow/notice.md)。
## 自定义流程状态 {#custom}
报表填报应用发布后会自动创建一张流程实例表的索引表，同时系统在索引表中提供了默认的流程字段，报表填报应用依据索引表中的流程字段可自定义单位列表中的流程状态，以下图在[单位列表](./settings/interface.md#datalist)中自定义处理人字段为例：
1. **新增字段**：在**导航栏**>**设置**>**界面外观**>**填报单位列表**中点击添加按钮。
2. **设置字段信息**：在按钮的**字段**属性处设置需要显示的内容，如`数据索引表.当前流程处理人`；在**标题**属性处设置其对应的标题，如`处理人`。
::: tip
除了简单的添加流程状态外，报表填报应用还支持在单位列表中查看对应的流程进度，具体内容可参考文档[显示流程进度](./settings/interface.md#flow-schedule)。
:::
### 扩充索引表的流程字段 {#expand}
除了[数据索引表](./data-storage.md)中默认的流程字段外，可以根据流程实例表中的字段扩展索引表中的流程状态字段。只需在索引表中创建一个对应的新字段，其物理字段名格式为`FLOW_`加上`流程实例表中对应字段的物理字段名`。如想在索引表中增加**流程描述**字段，流程实例表中**流程描述**对应的物理字段为`INSTANCE_DESC`，在索引表中新增字段时对应的物理字段应为`FLOW_INSTANCE_DESC`。关于索引更多的内容可查看[索引管理](data-gov/model-index/)。系统默认的数据索引表以及索引表中默认的流程状态字段如下：
| 字段 | 物理字段名 |
| :---------| :-------- |
| 流程实例代码 | FLOW\_INSTANCE\_ID |
| 流程实例状态 | FLOW\_INSTANCE\_STATE |
| 流程结果 | FLOW\_INSTANCE\_RESULT |
| 当前流程处理人 | FLOW\_CURRENT\_USERS |
| 当前流程节点 | FLOW\_CURRENT\_NODES |
| 最近流程处理人 | FLOW\_UPDATE\_USER |
| 最近流程处理时间 | FLOW\_UPDATE\_TIME |
| 最近流程处理结果| FLOW\_LAST\_TASK\_RESULT |
| 最近处理意见 | FLOW\_LAST\_COMMENT |
::: tip 查询流程系统表与扩充索引表流程字段的区别
扩充索引表流程字段可以在一定程度上提升数据查询的性能。表单的数据列表在查询时以索引表为主，如要查询的字段信息索引表中不存在时，需要关联查询流程的系统表，此过程可能会性能造成影响。因此在索引表中特意默认带上一些常用的流程状态字段，在写入索引表数据时可以同步流程信息，表单在进行查询时可以直接查询到索引表中的数据，从而避免频繁的关联查询，提升查询效率。
:::
---
url: "https://docs.succapp.com/v5/guide/ci/design-fapp/data-storage.md"
htmlUrl: "https://docs.succapp.com/v5/ci/data-storage"
title: "数据存储"
---
---
order: 9
navTitle: 数据存储
---
# 数据存储
报表填报应用的数据与模型紧密联系，用户提交的数据将保存在相应模型对应的数据表中。在制作报表填报应用时，报表填报应用支持自动生成模型，同时也支持直接使用已有的模型创建报表填报应用。本文主要讲解自动创建模型与引入已有模型各自的特点。
## 自动创建模型 {#auto}
报表填报应用在创建并发布后，系统会根据报表填报设计器中的设置自动创建相应的数据模型，比如根据表样布局和字段配置生成对应的业务表等。若对填报模型没有业务或技术上的要求，比如不限定物理字段名的命名规范等，可以直接使用系统自动创建模型的机制，只需要按需设置好数据期、填报单位以及对应的单元格的类型，并发布报表填报应用即可，具体介绍见下方章节。
### 表单粒度设置{#setting}
报表填报应用相关的粒度设置会对自动生成业务表有所影响，比如在报表填报应用中，通常通过填报单位、数据期等信息来唯一确定一条数据。因此当设置了[数据期](./settings/period.md#fixed-period)和[填报单位](./settings/org.md)后，报表填报应用会在自动生成的业务表中增加这两个字段作为主键，这两个字段相关信息以及报表填报应用还支持设置的其他粒度详情如下：
- **数据期**：设置[数据期](./settings/period.md#fixed-period)为固定周期后，报表填报应用自动创建的业务表上会增加一个数据期的主键，且该字段的字段角色与选定的**填报周期**一致。
- **填报单位**：选择[填报单位](./settings/org.md)后，报表填报应用自动创建的业务表上会增加一个填报单位的主键，同时该字段会绑定填报单位维表。
- **填报明细数据**：勾选[填报明细数据](./settings/org.md#detail-data)后，需要设置一个明细数据主键，随着明细主键的设置，系统会将该字段自动设置为主键。
### 生成业务表 {#business}
业务表主要是存储表单页面中填报的数据。报表填报应用会根据[表单粒度设置](#setting)与表样的[数据映射](./design-form/data-mapping.md)自动生成模型，无需手动绑定字段，单元格初次设置[单元格类型](./design-form/cell-types.md#type-change)后会在数据源处生成对应的数据模型及字段，后续依次设置其他字段时，数据模型会自动创建字段并进行绑定。在[发布报表填报应用](https://docs.succapp.com/v5/ci/publish)前，所有内部生成的模型都是临时的，此时修改单元格类型，模型字段也会相应变化，单元格类型与模型字段相应关系如下表格：
报表填报应用会根据表样按照其[数据映射](./design-form/data-mapping.md)自动生成模型，
| 单元格类型 | 对应字段类型 |
|---------|-------- |
| 文本输入 | 字符型 |
| 数值输入 | 浮点型 |
| 下拉框 | 字符型，在**可选项**属性处选择维表后，该字段也将绑定对应的维表，若允许多选，则默认字段存储设置为允许多值|
| 日期 | 字符型，字段角色自动设置为日期 |
| 时间|字符型，字段角色自动设置为时间|
|选择面板|字符型，在**可选项**属性处选择维表后，该字段也将绑定对应的维表，若允许多选，则默认字段存储设置为允许多值|
|勾选框|整型|
|搜索框|字符型|
|上传附件|字符型，字段角色自动设置为附件，若允许上传多个附件则默认字段存储设置为允许多值|
|上传图片|字符型，字段角色自动设置为图片，若允许上传多个附件则默认字段存储设置为允许多值|
|字格|浮点型|
|进度条|浮点型|
::: tip
在表单发布前，可在**数据**属性处调整字段长度，浮点型还支持调整小数位数。也可以通过切换视图来批量修改字段的属性，具体可见[视图](./designer.md#view)。
:::
### 修改表单模型 {#modify}
表单自动生成的模型一经发布，已有字段便不再受表单内单元格类型的改变或删除的影响，仅支持新增字段，若需要修改或删除，需要在数据模块中对模型进行处理，具体可见[模型管理](../../data-gov/model/README.md)。比如随表单的发布，自动生成了公司基本信息表，该表中有公司名称、公司规模两个字段且都为字符型，后续在表单上进行修改是否存在影响具体如下：
- **修改单元格类型**：字段不发生变化。如在设计器页面修改公司规模的单元格类型为数值输入，保存发布后，公司规模的字段不会发生变化。
- **删除单元格**：字段不发生变化。如在设计器界面删除公司规模的相关单元格，保存发布后，公司规模的字段不发生变化，依旧存在。
- **新增**：新增一个字段。如在设计器界面新增一个公司地址的单元格，表单发布后，模型表中会新增一个公司地址的字段。
## 显示隐藏的表单模型 {#display-model}
报表填报应用通常会将一些非数据源列表引入的数据源隐藏起来，避免数据源列表中显示过多的数据源。这些隐藏起来的数据源通常不会直接被单元格的引用，但在报表填报应用中也需要查询这些表。按照不同的用途可以将这些表分为系统表和可选项表，具体介绍见下方。想要显示这些隐藏的表单模型可点击数据源右侧的`﹀`，选择**显示隐藏数据集**。
- [系统表](#system-model)：记录报表填报应用中的填报状态、校验信息等基本信息的数据模型，发布应用时会自动生成。如索引表、数据期表等。
- 可选项表：下拉框可选项处，或[填报单位](./settings/org.md)处引入的维表。如填报单位维表、下图中的产品维表等。
## 报表填报应用系统表{#system-model}
报表填报应用的系统表主要是指记录报表填报应用中的填报状态、校验信息等基本信息的数据模型。报表填报应用发布后，系统会根据相关设置自动生成对应的系统表，比如根据数据期的设置可生成对应的索引表和数据期表等。
### 索引表 {#index}
索引表主要用于记录报表填报应用的填报状态，包括锁定状态、流程状态、提交时间等内容。[填报单位列表](./settings/interface.md#list)主要是以填报单位表为主查询，通过关联索引表获取单位的填报状态，如填报单位的应报数、已报数等。需要注意的是只有报表填报应用中设置了填报单位或数据期时，才会自动生成该表。关于索引表的更多详情可见文档[数据索引表](/sys-tables/ci/fa_index)。
### 数据期表 {#period}
数据期表主要用于存储数据期、数据期描述等相关内容。数据期表内的数据与用户填报时能切换的数据期有关，如报表填报应用是月报，当前月份为6月，填报将从6月开始，数据期的下拉框内可选择的日期仅有选项`6月`。但如果用户希望填写前几个月的数据，此时可以在数据期表中插入前几个月的数据期，填报界面的数据期下拉框内便会出现这些选项。需要注意的是，只有报表填报应用的数据期为固定周期时，才会自动生成该表。关于数据期表的更多详情可见文档[数据期表](/sys-tables/ci/fa_period)。
### 校验结果表 {#check}
校验结果表主要用于记录批量校验的相关信息，比如校验类型、校验公式、错误级别等。需要注意的是，只有报表填报应用在**设置**>**数据填写**>**数据校验**处**勾选启用批量校验**，才会在发布应用时自动生成该表。关于校验结果表的更多详情可见文档[校验结果表](/sys-tables/ci/fa_validresult)。
## 引入已有模型{#model}
报表填报应用支持引入已有模型来实现表单对应的数据存储。引入的模型需注意相关的字段设置，具体可见[引入外部模型实现数据映射](./design-form/data-mapping.md#note)。需要注意的是，报表填报应用不会主动修改外部引入的模型。比如引入已有模型制作报表填报应用时，若需要新增一个字段存储数据，需要事先在模型中添加好新字段，然后再回到应用中在对应单元格上**绑定字段**。
---
url: "https://docs.succapp.com/v5/guide/ci/filling.md"
htmlUrl: "https://docs.succapp.com/v5/ci/filling"
title: "填报数据"
---
---
order: 4
navTitle: 填报数据
---
# 填报数据
报表填报应用提供了类Excel式的填报体验，与Excel有良好的交互性能够相互导入导出、粘贴数据，并且支持完备的逻辑校验规则来确保填报数据的质量等。本文主要介绍填报用户的各种填报体验以及相关功能用法。
## 数据的保存与提交{#submit}
报表填报应用通过**提交**和**保存**按钮将数据存储入库，两种方式存在以下区别：
1. 业务含义不同
1. **提交**是确认上报当前单位的数据，代表当前存储的这份数据是有正式意义的。
2. **保存**仅代表草稿，是最终提交数据的中间过程，一般是没填完时需要临时保存一下数据，不代表最终的正式数据。
2. 校验规则的判断
1. 所有[错误](./design-fapp/validate.md#logic-rules)级别的校验规则都必须通过才允许**提交**，否则提交失败。
2. **保存**时忽略所有配置的校验规则，只需要满足主键和业务键不为空且唯一索引不冲突即可。
3. 数据状态的写入
1. **提交**时，数据的**提交状态**置`1`，**草稿状态**置`0`，代表当前数据是**已提交**的状态。
2. **保存**时，数据的**提交状态**置`0`，**草稿状态**置`1`，代表当前数据是**填报中**的草稿。
### 明细数据整体上报{#total-submit}
当报表填报应用需要根据单位来上报明细数据时，比如要填报各单位下的人员信息，填报人员可能是一条一条填写后提交的或是直接批量导入的，在填报完明细后需要明确告诉上级单位当前单位数据都上报完了，需要将单位的上报状态修改为**已上报**，此时需要在明细列表中点击批量上报来修改填报单位的上报状态，如下动图操作所示：
示例地址：[明细整体上报](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B&:orgId=420000000009)
::: tip
1. 批量上报时会根据数据的校验状态来判断上报的这些数据是否符合规范，存在不符合规范的数据时无法上报成功。
2. 某些业务场景下可能存在单位下没有明细数据也是正常的情况，此时也可以在单位下上报空的明细数据代表这个单位已经确定填报过了，只是没有明细数据。
:::
### 提交后自动锁定{#auto-lock}
某些业务场景下，管理员会限制数据在提交后就不允许修改了，例如某些考核内容的填报，确定提交后数据就会**自动锁定**，填报用户只能查看不能再对填写的数据进行修改，除非管理员再次解锁了数据才允许继续修改。
## 填报浮动表数据{#floating-submit}
浮动表指的是在填报过程中能动态新增行列的表。可在表单工具栏中点击**添加行**，**删除行**按钮来控制浮动区域中的数据，也可通过[快捷键](#hotkey)来增删行：
### 数据的筛选和排序{#filter-and-order}
支持对浮动表做筛选和排序数据，不同列上的筛选条件共同作用，取AND的关系，操作如下图所示：
## 数据的复制粘贴{#copy}
报表填报应用支持与Excel进行数据交互，相互之间能够任意复制粘贴数据。与许多常见的复制粘贴规则不一样，将Excel数据粘贴到表单中时，有以下规则：
1. 只允许将数据粘贴到那些允许输入的单元格中。
2. 如果是将数据粘贴到**浮动表**中，则默认会按照主键或业务键进行**合并**，具体规则和导入浮动表一致，可参考后续章节[浮动表数据导入](#float-import)。
3. 将Excel数据粘贴到有下拉选项的单元格中时，报表填报应用能自动根据粘贴的内容找到对应的选项并将单元格的值替换为对应的代码值，如果粘贴的内容在选项中找不到会在单元格中提示选项不存在。
## 数据导入{#import}
报表填报应用支持和Excel文件做表样匹配并将匹配到的工作表中的内容直接导入到表单中，想要正常匹配到表样需要遵循以下规则：
1. Excel文件中的工作表名称需要与报表填报应用中对应要导入的工作表名称完全一致。
2. 在上一条的基础上，Excel中的表样结构必须与要导入的表单结构完全一致，不能存在某些标题单元格名称不一样或位置不一样的情况。
### 浮动表数据导入{#float-import}
导入浮动表数据时，总是依据浮动区域的**主键**或**业务键**来将导入的数据和浮动区域中已存在的数据进行**合并**，合并规则如下示意图所示：
1. 以**主键**或**业务键**为依据判断是相同行的，导入的数据合并到浮动区域中，有差异的部分以导入的数据为准。
2. 判断是不同行的追加到浮动区域中。
3. 保留浮动区域内没有找到与导入数据有相同关系的行。
### 批量导入明细数据{#batch-import}
单位能够填报明细数据时，管理员可设置允许让填报用户批量导入单位下的明细数据，通常都会在工具栏中提供可供下载的导入模版，填报用户可下载模板后将需要导入的数据按照模版填充，然后再导入到报表填报应用中。具体效果如下所示：
示例地址：[批量导入](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B&:orgId=420000000009)
导入时支持选择导入的模式：
- **合并**：默认选项，覆盖重复的数据，追加不存在的数据。
- **覆盖**：删除所有已存在的数据，导入文件中所有数据。
- **追加**：忽略重复的数据，追加不存在的数据。
## 数据导出{#export}
报表填报应用支持导出数据，在**表单工具栏**>**更多菜单**中点击导出可显示导出对话框，支持自定义导出文件名、导出格式以及选择要导出的工作表等。
::: tip 导出下拉选项
导出Excel文件时，支持导出单元格下拉选项，由于Excel的默认限制，目前导出的下拉选项总字符长度超过255时会无法导出。
:::
### 批量导出明细数据{#batch-export}
明细填报中允许用户导出自己权限范围内的明细数据，支持一键导出所有明细或是仅导出勾选的明细，在**明细列表工具栏**>**更多菜单**中点击批量导出，未勾选明细时导出所有明细，勾选后仅导出勾选的明细数据：
## 切换数据期{#period}
当填报的表单需要按照固定周期定期上报数据时，默认情况下打开表单时通常都会根据当前时间来填报最近的一期数据，比如月报，6月份打开的话就会默认填报6月份的数据，有时可能存在一些历史数据还没有填报的情况，此时可以在工具栏中切换到历史数据期来填写那一期的数据。
## 自定义冻结行列{#freeze}
当填报的表样较大在屏幕中无法完整显示时，滚动页面往往会导致一些关键信息例如一些标题单元格被滚动到无法看到的位置，从而难以分辨当前表单中的数据是属于哪些内容。上述情况下，可右键单元格设置**冻结窗格**，以冻结的单元格为基准，单元格前面的行或列在滚动页面时不会跟随滚动，效果如下所示：
## 处理校验错误{#valid}
提交表单或点击工具栏中的校验按钮时，会触发报表填报应用的校验设置，当填写的数据不满足校验规则时，此时不允许提交表单数据。报表填报应用在填报过程中提供了校验列表来帮助用户快速定位和处理校验错误：
1. 点击**提交**，如果填报的内容不符合管理员定义的校验规则，此时会在所有有问题的单元格上做出标记，并在表单下方弹出校验列表来展示所有校验出错的地方。
2. 点击校验列表中的条目会自动定位到相关的校验错误的单元格，也可点击数据列中精准定位到错误数据的单元格。
3. 将内容修改正确后，单元格红色标记消失且错误的校验规则也从校验列表中消失。
4. 某些校验规则允许**特例说明**，在填写说明后即便这条规则在逻辑上仍无法通过，在提交时也会忽略这条规则。
5. 有些校验规则是**警告**级别的，即便不处理也不会影响数据的正常提交，只是提示某些内容可能不太合理但是也没有到错误的等级。
### 批量校验{#batch-valid}
批量校验可以针对一批单位数据进行快速校验，校验完成后会将校验结果告知给用户，并在数据列表中标注每行数据的**校验状态**，具体操作如下动图所示：
示例地址：[批量校验](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B&:orgId=420000000009)
批量校验返回结果后，点击对话框中的**下载校验结果**按钮，会得到一个展示所有校验错误内容的Excel文件，包含以下内容：
| 标题 | 描述 |
| :---- | :---- |
| 填报单位 | 填报单位的代码值，用于标识错误的数据属于哪家单位，该标题通常都有专门的业务名称，比如示例中是医疗机构 |
| 单位名称 | 单位对应的业务名称，作为单位代码的补充，只看单位代码很难明确是哪家单位的数据校验错误 |
| 明细代码 | 明细数据的代码值，用于标识错误的数据属于哪条业务明细，该标题通常有专门的业务名称，比如示例中是以人员的身份证号作为明细代码的 |
| 校验公式ID | 校验规则的编号，用于帮助用户快速找到是哪条校验规则出错了 |
| 校验信息 | 校验规则的提示信息，通常是告知用户具体什么错了的业务说明 |
| 校验公式 | 校验规则的逻辑判断公式 |
| 校验数据 | 校验规则中所有相关的用来判断是否通过校验的数据，帮助用户明确具体是哪部分内容错误导致的校验不通过 |
| 例外说明 | 用户手工输入的特例说明 |
## 快捷键{#hotkey}
填报界面快捷键：
| 功能 | Windows/Linux | macOS |
| :---------- | :---- | :---- |
| 横向定位下一个单元格 | `Tab` | `Tab` |
| 横向定位上一个单元格 | `Shift+Tab` | `Shift+Tab` |
| 纵向定位下一个单元格 | `Enter` | `Enter` |
| 纵向定位上一个单元格 | `Shift+Enter` | `Shift+Enter` |
| 焦点单元格朝指定方向移动 | `方向键` | `方向键` |
| 滚动到焦点单元格所在行列指定方向第一个单元格 | `Ctrl+方向键` | `Ctrl+方向键` |
| 清空单元格内容 | `Delete`/`Backspace` | `Delete`/`Backspace` |
| 撤销 | `Ctrl + Z` | `Command + Z` |
| 重做 | `Ctrl + Y` | `Command + Y` |
| 全选 | `Ctrl + A` | `Command + A` |
| 复制 | `Ctrl + C` | `Command + C` |
| 剪切 | `Ctrl + X` | `Command + X` |
| 粘贴 | `Ctrl + V` | `Command + V` |
| 当前行上面插入一行 | `Ctrl + Shift + Up` | `Command + Shift + Up` |
| 当前行下面插入一行 | `Ctrl + Shift + Down` | `Command + Shift + Down` |
| 当前列左边插入一列 | `Ctrl + Shift + Left` | `Command + Shift + Left` |
| 当前列右边插入一列 | `Ctrl + Shift + Right` | `Command + Shift + Right` |
| 删除行列 | `Alt + R` | `Alt + R` |
| 显示下拉面板 | `Alt + Down` | `Alt + Down` |
| 关闭下拉面板/退出编辑状态 | `Esc` | `Esc` |
---
url: "https://docs.succapp.com/v5/guide/ci/data-manage.md"
htmlUrl: "https://docs.succapp.com/v5/ci/data-manage"
title: "填报管理"
---
---
order: 5
navTitle: 填报管理
---
# 填报管理
报表填报应用在填报过程中，通常需要上级单位的用户作为管理用户来监管报表填报应用的数据填报，从而确保整个填报过程有序可控。在[填报数据](./filling.md)文档中介绍了基层填报用户在填报数据时的一系列操作，本文主要介绍管理用户在监管填报数据时的一些操作和功能的使用方法。
## 数据的搜索{#search}
报表填报应用支持根据输入的关键字在数据列表中搜索定位相关的数据，支持按关键字定位和快速搜索两种搜索方式：
| 搜索定位 | 快速搜索 |
| :----: | :----: |
|  |  |
- **搜索定位**：根据关键字在数据列表中依次定位搜索到的结果，支持点击上一个下一个按钮来切换定位的结果。
- **快速搜索**：根据关键字显示一个搜索结果的列表，点击列表中的条目能直接打开数据对应的表单。
### 单位列表中搜索明细{#search-detail}
管理用户在查看能填报明细数据的报表填报应用时，有时需要明确查询某条明细数据，但是又不知道这条明细对应的填报单位是什么，比如医院的人事信息填报，管理用户有张三的身份证号，但是不知道张三是哪家医院的，此时可在单位列表中用身份证号进行搜索：
示例地址：[搜索明细](https://demo.succbi.com/v5/ci/%E5%8C%BB%E9%99%A2%E4%BA%BA%E4%BA%8B)
单位列表中的搜索框默认会按照单位信息进行搜索，上述情况下也支持直接在搜索的结果列表中直接切换搜索明细数据，切换后即可展示关键字对应的明细搜索结果，点击条目后会跳转到对应数据的表单。
## 数据的筛选过滤{#filter}
在数据列表的工具栏中，支持添加一些过滤下拉框来辅助用户管理数据，报表填报应用默认会提供**上报状态**、**校验状态**、**锁定状态**这三个用于筛选数据状态的下拉框，也可根据实际业务需求来添加一些业务相关的过滤字段。如需了解如何配置可参考[工具栏](./design-fapp/settings/interface.md#toolbar)配置文档。
## 数据的锁定和解锁{#lock}
锁定和解锁用于手动控制某期某单位的数据是否可填，当某些数据期或者单位的数据不希望填报用户可以继续填写时，管理用户可在数据列表中锁定这些数据，锁定后的数据无法再被修改，除非管理用户解锁该数据。
## 查看流程进度{#progress}
报表填报应用可以配置审批流程，当用户填报了单位数据后还需要经过后续的审批直到最后流程走完，管理用户可能需要监控流程的处理情况，此时可在单位列表中查看每条流程的进度状态，流程进度的显示配置可参考[显示流程进度](./design-fapp/settings/interface.md#flow-schedule)文档。
## 汇总下级数据{#summarize}
某些业务需要上级单位可以汇总所有下级单位的数据以便于查看整体的填报情况，报表填报应用支持对[固定表](./design-fapp/design-form/data-mapping.md#fix-table)以及[浮动表](./design-fapp/design-form/data-mapping.md#float-table)进行数据汇总：
| 固定表数据汇总 | 浮动表按主键汇总 |
| :----: | :----: |
|  |  |
示例地址：[数据汇总](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=%E6%B1%87%E6%80%BB&:orgId=9100&:dataPeriod=202303&:sheet=sumFloat-primary)
::: tip 浮动表列出所有下级数据
浮动表除了**按主键汇总**外，还支持在上级单位查看的浮动表中能够罗列出所有下级明细，此时通常是不能修改的，即便能修改的情况一般也是在下级单位数据的基础上进行修改，具体制作方式可参考[列出下级单位数据](./design-fapp/fetch-and-calc.md#list-org)文档。
:::
## 批量校验{#batch-valid}
管理用户有时需要帮助下级填报用户将保存的数据批量上报，这个过程中没有通过校验的数据往往是不允许上报的，因此在批量上报数据前，通常都需要对即将上报的数据先做**批量校验**，**批量校验**功能的使用过程可参考[填报数据](./filling.md#batch-valid)文档。
## 批量导入和导出{#import-and-export}
管理用户通常能批量导入或导出自己权限范围内的报表填报应用数据，相关操作与填报用户导入导出明细数据的操作类似，可参考[填报数据](./filling.md#batch-valid)文档。
---
url: "https://docs.succapp.com/v5/guide/ci/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/ci/faq"
title: "表单和流程常见问题列表"
---
---
order: 99
navTitle: 常见问题
---
# 表单和流程常见问题列表
!!!children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/ci/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/ci/errcode"
title: "数据填报错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 数据填报错误提示排查
---
url: "https://docs.succapp.com/v5/guide/app/README.md"
htmlUrl: "https://docs.succapp.com/v5/app"
title: "低代码搭建业务应用"
---
---
order: 10
navTitle: 低代码应用
---
# 低代码搭建业务应用
---
url: "https://docs.succapp.com/v5/guide/app/overview.md"
htmlUrl: "https://docs.succapp.com/v5/app/overview"
title: "低代码应用概述"
---
---
order: 1
---
# 低代码应用概述
SuccAP在设计之初就规划和实现了低代码应用搭建能力，使用SuccAP可以快速搭建各类个性化业务应用系统，如预算系统、省级全流程冷链溯源系统、核酸检测系统、企业数据中台……，极大的减少研发投入、缩短交付周期、降低实施成本。
::: tip 初次使用建议
如果你是第一次使用SuccAP进行低代码应用搭建，本文会让你更快速、更全面的了解SuccAP低代码应用搭建的思路和方法论，强烈建议你在进一步操作前仔细阅读本文。
:::
\[\[toc]]
## 什么是低代码？{#what-is-lowcode}
通俗的说低代码就是通过易用的、可视化的操作、加上少量的代码或脚本的方式快速的搭建业务应用。低代码可以提升开发人员的效率，也可以让非开发人员也能进行应用开发。
市面上的低代码产品大致分3类，可视化编程类、表单驱动类、模型驱动类：
1. 可视化编程类概念其实由来已久了，目的是为了提升研发效率，还是面向开发人员的一个IDE工具。
2. 表单驱动类是通过傻瓜式的定义表单和简单的流程来配置一个以表单为核心的小应用，表单驱动类低代码产品的特点是傻瓜式、简单易用，但个性化能力不足。
3. SuccAP是模型驱动类的低代码产品，通过多种可视化“建模”工具（包括数据模型、页面设计器、流程设计器、报表设计器……）快速搭建业务系统，SuccAP通过多种工具配合使用，可以搭建复杂的、个性化的业务应用。
## SuccAP低代码应用搭建方法论{#lowcode-methodology}
SuccAP提供了低代码应用搭建的一站式工具集，遵守一定的方法可以更高效的使用SuccAP进行应用搭建，使用SuccAP进行低代码应用搭建主要包括下面几个环节：
如上图：
1. **需求调研和原型设计同步**，利用SuccAP的快速页面搭建能力，快速的构建原型系统，在原型系统上与用户进行需求沟通，用户甚至自己可以参与原型系统搭建，做到设计即开发。
2. **规划系统底层数据模型**，由实施人员或用户掌控数据，做到以数据为核心，数据驱动业务开发，为后续进一步使用、分析和管理数据资产做好准备。
3. **在原型基础上进一步搭建系统**，完善UI细节、业务逻辑、交互，搭建的过程中就在不断测试，做到开发即测试。
4. **测试上线**，性能测试、安全测试、压力测试，部署上线
## 需求调研和原型设计{#prototyping}
原型设计非常重要，它可以帮助在系统开始开发前根最终用户沟通需求，尽量降低开发过程中系统需求变动的可能性。传统的原型制作方法（如使用AxureRP）不够敏捷、原型无法直接做为进一步开发的基础，我们推荐直接在SuccAP中制作原型。
使用SuccAP做原型更敏捷，可以在与用户沟通需求的同时就把将来系统的“架子”搭出来，可以做到上午沟通需求下午就能直接看一个初步的原型，原型产出的内容也可以作为下一步实际开发的基础，原型开发的工作产出也不会废弃，做到真正的**设计即开发**。
[//]: # "TODO 放一个动图，体现快速原型设计的效果"
SuccAP提供了SuperPage、工作流、门户页面等功能，原型设计时需要根据业务需求按需选择：
1. [应用设计器](./app-designer.md)集应用编辑、资源管理、预览查看等功能为一体的多功能设计器，它使低代码应用的搭建更为清晰明了、方便快捷
2. [SuperPage](./superpage/README.md)适合搭建各类PC应用页面、移动App页面，包括表单类页面、数据查询类页面或对话框类页面
3. [工作流](./workflow/README.md)流程设计器，可以一站式搭建业务流程类应用
4. [门户应用](./portal-page/README.md)是一个框架类页面，它将其它各个零散的页面组织在一起，形成一个完整的PC端业务应用框架
5. [移动App](./mobile/README.md)可以发布到多个平台，包括微信小程序、企业微信、钉钉等
6. [集成SuccBI](../README.md#SuccBI)可以基于应用数据统计查询、搭建可视化页面
[//]: # "TODO 继续介绍具体的方法，并link到具体的功能文档"
## 规划业务数据模型{#data-models}
在需求调研和原型设计做到一定程度后就可以考虑开始规划业务数据模型了，业务数据模型是进一步进行低代码开发的必备基础。SuccAP低代码的目标是能搭建复杂的、个性化的业务应用，所以我们将数据模型开放给实施人员或用户掌控，他们需要管控业务读取了哪些数据、修改了哪些数据、数据分哪些表、主键是什么等等。用户掌控数据，也为后续进一步使用、分析和管理数据资产做好准备。
对于一个有一定规模的业务应用来说，数据模型的规划设计不是一次性就完成的，需要不断的优化改进，规划业务数据模型时需要重点关注下面几点：
1. 总共有哪些数据模型（可以理解为数据表），哪些是字典表（如行政区划、产品类别表），哪些是事务性表（如订单表、出入库表）。
2. 每个表的主键是什么，比如订单表就应该有一个订单编号字段，对于一个业务系统的数据模型来说，主键通常是必须的，可以是单字段或多字段主键。
3. 每个表的维键字段有哪些，比如订单表就应该有产品编号、客户编号、时间等，这些非数值的信息往往就是维键，通常用来进行数据的关联或检索。
4. 每个表的度量字段有哪些，度量字段往往是数值型字段，比如点单表中的数量、价格等字段，度量字段往往用来进行合计、汇总。
5. 表与表之间的关联关系。
SuccAP提供了逻辑层的、可视化的数据模型设计功能，用户不需要关心具体的数据库物理层技术细节，在SuccAP定义数据模型后，SuccAP会自动创建物理层表结构：
[//]: # "TODO 继续介绍具体的方法，并link到具体的功能文档"
更多帮助见[数据管理](./data-gov)。
## UI、交互、App{#build-app}
在原型设计经过初步的确认、数据模型规划有一定基础后，就可以开始进一步搭建整个业务系统了，让整个应用一步一步的真正的能用起来。
更多帮助见[SuperPage](./superpage/README.md)。
## 业务流程{#flow}
SuccAP提供了流程设计器，充分考虑了复杂流转业务，提供了多个业务节点、分支条件、多种业务流程操作等，能够灵活动态设置每个流程环节的参与人及可访问的资源。
更多帮助见[工作流](./workflow/README.md)。
## 应用的安全性{#security}
SuccAP十分重视数据安全，充分考虑了黑客的渗透攻击和越权攻击的防护。SuccAP作为一个低代码平台提供了多种安全相关的功能设置，业务应用的安全性问题也需要依赖应用搭建者的正确设置。
更多帮助见[应用的安全性](./security.md)。
## 测试上线{#test}
对于用户量较大的系统，上线前建议做好压力测试。
更多帮助见[压力测试](../devops/test/jmeter-test.md)。
## 运维和版本迭代{#devops}
TODO
---
url: "https://docs.succapp.com/v5/guide/app/new-app.md"
htmlUrl: "https://docs.succapp.com/v5/app/new-app"
title: "新建应用"
---
---
order: 2
---
# 新建应用
当我们需要低代码搭建一个新的业务应用时就需要新建应用。一个应用往往对应一个完整的业务应用场景，用户能在应用内完成一系列相关的业务流程活动，如省级全流程冷链溯源系统、企业采购管理系统、人力资源系统……
应用内可以新建和管理仪表板、报表、表单流程、SuperPage等资源，应用也可以直接引用应用外已经存在的资源。
新建一个应用步骤如下：
1. **新建应用入口：** 进入项目的**应用**模块，点击**新建**，选择模板，进入[应用设计器](./app-designer.md)
2. **新建应用内部资源：** 点击左上角右箭头`>`展开[应用资源面板](./app-designer.md#app)，点击加号`+`新建应用内部资源，第一次保存资源时也会对应用进行命名及保存
3. **浏览资源：** 点击应用默认的`index.tpg`页面，将**应用资源面板**或**项目资源区**中的资源拖入**门户内容区**，即可在[门户页面](./portal-page/README.md)中浏览该资源
4. **命名保存：** 点击**保存**按钮，在命名对话框输入合适且有意义的名称，点击**确定**即可
---
url: "https://docs.succapp.com/v5/guide/app/app-designer.md"
htmlUrl: "https://docs.succapp.com/v5/app/designer"
title: "应用设计器"
---
---
order: 3
---
# 应用设计器
应用设计器是一个集应用编辑、资源管理、预览查看等功能为一体的多功能设计器，它使低代码应用的搭建更为清晰明了、方便快捷。应用设计器界面如下图所示：
可以将其划分为如下几个区域：
1. 应用资源面板：显示应用内各种资源文件，分为文件区、数据区和API区
2. 应用设计区：对资源文件进行编辑的页面
## 资源的新建、修改与删除{#cud}
应用设计器的**应用资源面板**内支持新建文件，文件支持以下几类：
- **应用类**：包括[门户模板首页](./portal-page/README.md)（包括移动首页、电脑端首页）、[SuperPage](./superpage/README.md)
- **分析类**：包括[报表](../report/README.md)、[仪表板](../data-viz/README.md)、ActiveDoc等
- **数据类**：包括[数据库表模型](../data-gov/GLOSSARY.md#data-table)、[SQL查询](../data-gov/sql-model.md)、[数据加工](../data-process/README.md)、[脚本数据集](../dev/script/frontend/dataset-script.md)、[空白模型](../data-gov/input-model-data.md)等
- **表单类**：包括[报表填报应用](../ci/design-fapp/settings/README.md)、[工作流](./workflow/README.md)
- **脚本类**：包括[前端脚本](../dev/script/frontend/README.md)、[后端脚本](../dev/script/backend/README.md)等
- **API类**：包括[程序流](./actionflow/README.md)、[后端脚本](../dev/script/backend/README.md)
- **文件类**：包括文件夹、文件等
新建的文件将保存在相应的目录下，如仪表板、SuperPage等保存在文件目录下，数据加工等保存在数据目录下，程序流、后端脚本保存在API目录下。右键已经创建完成的文件，可以对文件进行**重命名**或进行**删除**，也可以选择**复制到**对当前文件进行复制并保存在指定目录下。
在**应用资源面板**选中文件，右侧的**应用设计区**将展示为对应的设计界面。如选中**仪表板**，设计区展示为仪表板编辑页；选中**报表**，设计区展示为报表编辑页。
## 调整目录结构{#construction}
左侧资源树包含了创建的所有应用资源文件，右键文件选择“移动到”，将文件调整到目标目录下。这里我们提供了一种目录结构思路，可参考文档[应用文件组织](./files.md)，使文件便于分类管理和维护。
## 文件的导入与导出{#load-upload}
应用设计器内支持将文件导出，右键文件选择**导出**，将自动建立下载任务，下载后的文件保存在浏览器下载默认文件夹下。导入文件后，文件的路径依据右键选择的文件或文件夹进行存放：
- 文件夹：导入的文件保存在该文件夹下
- 文件：导入的文件与选中的文件保存在同一目录下
:::tip
应用设计器内不支持对excel、word文件进行预览编辑，该类文件的查看与编辑需要依据浏览器中是否存在对该类文件的查看、编辑功能。
- 若浏览器不具备查看与编辑功能
- 编辑时：打开本地excel或word应用
- 查看时：自动下载该文件
- 若浏览器具备查看与编辑功能，将在浏览器新标签页打开该文件
:::
## 权限设置{#permission}
在应用设计器内可以对文件的查看、编辑、交互等权限进行设置，权限的具体介绍可以参考文档[权限的操作说明](../permission/grant/operations.md)。
---
url: "https://docs.succapp.com/v5/guide/app/files.md"
htmlUrl: "https://docs.succapp.com/v5/app/files"
title: "应用文件组织"
---
---
order: 4
navTitle: 应用文件组织
---
# 应用文件组织
一个实际业务项目中会包含数据录入、数据查询、可视化分析等，需要用到较多文件资源，使用规范的、清晰的文件组织来管理这些文件资源能帮助项目成员快速了解相关业务、维护资源以及内容的扩充和移植，本文讲述低代码应用开发过程中的文件组织管理的规范。
## 应用文件总体组织规范{#rules}
应用模块中，根据展示业务不同可新建多个应用，应用命名规则为简短小写英文名称，如`oa`。在一个应用中，应用资源面板会默认存在**文件**、**数据**、**API**三个目录，该目录不可删除与重命名，只可在对应目录下新建应用资源，如下图是一个典型的业务应用的资源目录示例：
- **文件**：相关业务资源以及可视化页面等存放与文件目录下，可新建SuperPage、仪表板、脚本文件等，名称统一小写简短英文字母，减号`-`分割，对url友好，更多规范可查看[资源文件组织](#resource)
- **数据**：只会被当前应用用到的数据可以存放在数据目录下，模型文件名统一大写英文字母，下划线`_`分割，文件描述可以使用中文，如`FACT_LEAVE_APPLY-请假申请表`，文件较多，按照业务模块管理目录，更多规范可查看[数据模型组织](#data)
- **API**：程序流以及后端脚本存放于API目录下，如后端脚本`custom.action`放于该目录下，名称使用小写简短英文字母，更多规范查看[程序流和后端脚本组织](#api)
:::tip
系统中新建文件，可以填写文件的**名称**和**描述**，新建成功后，名称和描述以`-`连接，如下图效果：
:::
## 资源文件组织{#resource}
在**文件**目录中可新建业务文件、图片文件、脚本文件以及开放文件等，这些文件的存放目录规范如下：
- **业务文件**：可新建SuperPage等文件，先按照移动端、PC端显示形式分别存放对应目录，再按照业务模块存放对应业务目录中，统一小写简短英文，减号`-`分割，如`qjsq`请假申请页面
- **图片文件**：数量较少，可统一放到`images`目录中，数量较多，可分业务模块放到对应业务目录的`images`目录中，统一使用小写英文
- **开放文件**：即不需要权限或登录就能访问的文件，统一存放于`public`目录中，使用小写简短英文命名
- **工作流文件**：执行流程的工作流文件，具体可查看[工作流](./workflow/README.md)，统一存放与`workflow`文件使用小写简短英文命名
- **脚本文件**：大部分脚本文件存放于`scripts`目录中，统一小写命名，部分脚本文件有约定位置，如下所示：
- 前端脚本：名称为`custom.ts`，存放与`文件`目录下，新建该文件自动生成`custom.js`文件，详见[前端脚本开发](../dev/script/frontend/custom-ts.md)
- 样式脚本：名称为`custom.less`，存放与`文件`目录下，新建该文件自动生成`custom.css`文件，详见[前端自定义样式开发](../dev/script/styles/custom-less.md)
## 数据模型组织{#data}
:::warning
只在内部使用的数据模型建议放到应用中的数据目录下，如果数据可能会被其他地方用到，比如其他业务、分析、可视化等，则建议放到元数据项目的[数据](../data-gov/README.md)模块中。
:::
在**数据**目录中，可新建数据模型，只在内部使用的数据模型建议放到该目录下。该目录下文件规范如下：
- **业务目录**：模型文件若较多，可以考虑按业务板块新建一级子目录分目录管理，目录名建议大写英文字母，业务描述放到文件名的描述中，如目录为`LEAVE-请假`
- **事实表**：放入对应业务目录中，统一大写英文字母，下划线`_`分割，文件描述可以使用中文，如`FACT_LEAVE_APPLY-请假申请`
- **维表**：公共的维表可以发放到独立的`DIM`目录，业务维表可以放到对应业务目录中，文件名命名以`DIM_`开头，如`DIM_SQLX-申请类型`
- **物理表**：大写英文字母，下划线`_`分割，尽量与模型表名保持一致，如`FACT_LEAVE_APPLY`、`DIM_SQLX`
以下列举一些文件命名规则以供参考：
|种类|名称规则|举例（名称-描述）|
|--|--|--|
|业务文件夹|具有含义的简短英文名称或描述首字母缩写|`LEAVE-请假`、`KQGL-考勤管理`|
|事实表|FACT+上级目录名称+表信息英文名称或描述首字母缩写|`FACT_LEAVE_APPLY-请假申请表`、`FACT_KQGL_DKXXB-打卡信息表`|
|维表|DIM+业务英文名称+维表描述信息首字母大写|`DIM_LEAVE_QJLX-申请类型`|
|通用维表|DIM+GEN+表信息首字母缩写|`DIM_GEN_XZQHFZ-行政区划父子`|
|部分通用维表|DIM+项目名称或业务文件名称+表信息首字母缩写|`DIM_OA_SPZT-审批状态`|
|数据表|大写英文名称，与模型表名称保持一致|`FACT_LEAVE_APPLY`、`DIM_LEAVE_QJLX`|
## 程序流和后端脚本组织{#api}
在**API**目录中可新建程序流和后端脚本文件，文件名约定为小写英文，减号`-`分割或驼峰命名，可直接存放与该目录下，如后端脚本`custom.action.ts`直接存放于当前目录下，新建该文件会自动生成`custom.action`文件，详见[后端脚本开发](../dev/script/backend/README.md)。
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/README.md"
htmlUrl: "https://docs.succapp.com/v5/app/portal-page"
title: "门户页面介绍"
---
---
order: 5
navTitle: 门户页面
indexTitle: 门户页面介绍
---
# 门户页面介绍
门户页面是一个集成的、易用的、有业务意义的信息展现平台，可以将一系列相关的内容按照自定义的方式组织到门户中，形成一个完整的业务应用框架：
|||
| --- | --- |
|||
SuccBI提供了所见即所得的门户页面设计器，业务用户也可以制作：
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/new-portal.md"
htmlUrl: "https://docs.succapp.com/v5/app/portal-page/new-portal"
title: "新建门户页面"
---
---
order: 1
---
# 新建门户页面
新建一个门户的步骤如下：
1. 进入项目的**应用**模块
2. 点击新建，选择[门户模板](#template)并点击**根据模板新建**，此时进入了新的门户页面
3. 接下来可以[添加资源至门户页面](#add)，并对[门户内容属性](#attributes)、[门户页面属性](#page)进行设置
4. 最后点击保存按钮保存新建的门户页面，之后可以在**应用**模块下单击该门户直接进行查看，也可以右键选择**编辑**对该门户页面进行编辑修改
## 门户设计器{#designer}
系统提供了所见即所得的门户设计器，可以通过拖拉拽快速实现门户应用，门户设计器界面如下图所示：
可以将其划分为如下几个区域：
1. **应用资源区**：应用资源区列出了当前应用下的所有资源，可点击+号新建资源
2. **项目资源区**：项目资源区列出了当前项目中的所有资源，可在项目名称下拉框中选择对应的项目，或者在搜索框中搜索项目下的资源
3. **门户内容区**：门户中需要展示的内容需要添加至内容区，点击对应的内容节点可在内容下方的属性栏中进行样式等属性设置
4. **预览区**：在预览区可以即时预览当前门户页面的效果
5. **属性栏**：在属性栏中可以针对整个门户页面进行样式及交互设置，如主题切换、门户背景等
## 门户模板选择{#template}
为了方便用户快速的设计门户页面，系统将常见的页面“版式”制作成了一系列门户模版，模版固化了页面的主体版式，提供了一些简单的属性设置、主题设置，这样用户只需要进行简单的设置即可快速完成一个门户页面（门户模版页面可以进行扩展开发，参考文档[扩展管理](../../dev/extension/extension-points/README.md)、[门户模板扩展](../../dev/extension/extension-points/portalTemplate.md)）。
制作一个门户页面首先要做的就是选择一个合适的模版，系统内置了丰富的门户模板可供选择。选择门户模板的方式有2种：
1. 新建门户是**根据模板创建**的，在新建时可以选择适合的门户模板：
1. 门户创建后，在门户设计器里可以更新模板，在**属性栏**>**样式**>**更改模板**
门户模板的分类及规则如下：
1. **首页型门户**：展示门户中包含的业务模块，不会直接显示文件内容，该类型门户一般用于系统首页。系统内置了丰富的首页型门户，如【旋转星球首页】、【蓝色首页】、【经典磁贴】等
2. **内容型门户**：即可直接在当前门户页面中直接查看节点页面内容，如【海洋门户】等
3. **播放型门户**：该类门户可进行页面自动播放，如【通用幻灯片模板】，可进行多个页面的左右切换和自动播放
4. **移动门户**：移动门户可用来快速搭建移动端效果的移动app，如【默认移动模板】，移动APP的介绍可参考文档[移动App](../mobile/README.md)
:::tip
首页型门户只支持叶子节点，不支持文件夹节点
:::
## 添加资源到门户页面{#add}
门户页面本身只是一个框架，没有内容，需要引用各类资源（包括仪表板、报表、报表填报应用等）最终才能组合成一个完整的业务页面。引用资源的方法很简单，将制作好的资源拖入到门户页面“内容”面板即可：
1. 添加当前项目的资源：**项目资源区**中会显示当前项目下的所有资源，直接从**项目资源区**拖入资源至**门户内容区**即可
2. 跨项目引用：如果拥有其它项目的查看权限，可以在项目列表下拉框中切换选择其它项目，将资源拖入到**门户内容区**
系统提供了多种拖入资源的操作方式：
1. 拖入资源操作方式：从**项目资源区**将需要在门户中展示的资源拖入至**门户内容区**即可
- 直接拖入文件或文件夹
- 将资源拖拽至叶子节点上替换当前节点内容
- 将资源拖到文件夹节点上时，即添加文件夹子节点
2. 新增节点操作方式：当需要将拖入的资源自定义分类时，可以在内容区**右键**新增节点方式自由组织目录结构。包括**新增节点**和**新增文件夹节点**两类：
- 新增子节点：即叶子节点，可在**链接**属性处，自定义添加资源路径，如：`/DEMO/ana/报表/分组报表/钻取子表/店面销售情况表.rpt`
- 新增子文件夹节点：即在当前文件夹节点下新建子文件夹
:::tip
1. 拖入到内容区域的资源包括文件夹或文件，可以通过**右键**方式快速定位并高亮项目资源区所在位置，即选中节点**右键**>**在项目资源中定位**
2. 当资源在原始路径下有修改，门户中也会自动更新内容，不需重新将资源拖入至门户中
3. 拖入文件夹至内容区域，无法对文件夹内的内容进行调整，空的子目录也会在门户中显示，对于有些子目录不希望在门户页面中显示，可以在内容下方的属性设置>**高级**>**显示**中选择**隐藏**
4. 在叶子节点上为**新增节点**，在文件夹上为**新增同级节点**，新增的节点可拖入文件夹或叶子节点
:::
### 移除资源{#delete}
当需要将资源从门户中移除时，提供了2种操作方式：
1. 在**内容区**将资源内容直接拖入**项目资源区**
2. 在**内容区**节点上**右键**选择**移除**
### 调整资源顺序{#order}
在内容区，可以对自定义节点的内容调整顺序，拖动节点进行调整即可，在预览区中会即时生效：
### 门户内容属性设置{#attributes}
**门户内容区**可分为2部分，上半部分是当前门户中所引用的资源内容，下半部分可以对选中的内容节点进行相关的属性设置：
- **标题修改**：当资源拖入到**门户内容区**后，该资源节点的标题默认是资源的**名称**属性。可以修改标题，当删除默认标题后，界面显示为空。修改后，可以在预览区看到效果
- **链接设置**：自定义资源链接，可设置外部系统链接，仅有在**增加同级节点**和**增加子节点**时可进行设置
- **打开方式**：可设置自定义链接节点的打开方式，如`嵌入`、`新浏览器标签页`、`替换当前浏览器界面`，仅可对链接节点进行设置
- **图标设置**：设置资源在门户中的图标，以及图标颜色、大小。分为4种状态：
- 默认：即不管节点是何种状态，如鼠标移入或鼠标点击，都始终是一种图标。对拖入的不同的资源类型系统都有内置的默认图标
- 鼠标移入：鼠标移到节点上时显示的图标
- 鼠标点击：鼠标点击节点时显示的图标
- 不可用：当节点属于禁用时显示的图标，禁用一般是自动的，不需要设置
- **布局方式设置**：设置门户的资源的展示方式，只有文件夹节点有此属性，更多布局方式介绍可参考文档[门户布局方式](./portal-layout.md)
- **高级设置**：
- 默认展开：表示当切换到当前节点时，默认展开节点下的所有资源，只有文件夹节点才有此属性
- 默认选择：表示当初次打开门户或切换到当前节点所在的文件夹节点时，默认显示当前页面，只有叶子节点有此属性
- 显示：表示资源在门户中是否显示，可选项有：显示、隐藏和条件，当选择条件时，可以输入表达式对该资源的显示进行限制
- 参数设置：在门户中的页面可以从URL上读取参数，将参数传递到切换后的页面上。参考文档[如何在门户页面传递参数给资源](./FAQ/如何在门户页面传递参数给资源.md)
### 内容属性扩展{#expand}
门户模板内容节点的扩展属性，此属性是由扩展开发作者提供的，不同的门户模板有不同的扩展属性：
- 磁铁型首页门户：
- 纵向排列：设置当前节点的标题和图表纵向排列
- 换行显示：设置当前节点所在行中当前节点之前的内容（包括当前节点）与节点之后的内容换行显示
- 背景：设置当前节点方块的显示背景
- 宽度：设置当前节点方块的宽度，支持输入具体的像素值或百分率，如90px或50%
## 门户页面属性设置{#page}
在门户属性栏中，可自定义门户页面的样式及导航栏的交互事件。
### 门户样式设置{#style}
在**属性栏**>**样式**下设置门户页面的相关样式：
- **浏览器标题设置**：在浏览器中打开当前门户页面时，在浏览器标签页上会显示该属性设置的标题内容
- **标题栏Logo和标题设置**：标题栏在门户页面的顶端，可以设置标题栏的logo和标题文字内容，一般是使用单位的logo和业务标题
- **背景设置**：门户页面背景可分为3部分：
- 标题栏背景：在门户中一般门户顶端属于门户的标题栏，只有内容型门户模板可以设置标题栏背景。
- 左侧树背景：门户左侧内容树的背景，只有带左侧树的门户模板有此设置，如【绿色门户】、【海洋门户】等
- 背景：设置资源的背景颜色
- **高级**：
- 内容自适应模板主题：此属性默认勾选。当内容（如仪表板、报表等）的主题与门户中的主题不一致时，内容等将自适应调整主题使其适应该门户的主题风格。取消勾选可让内容的主题风格不受门户模板主题风格的影响
- 设置适配主题：在不同的门户主题下，为各资源类型适配不同的主题风格。点击**设置适配主题**，设置门户主题映射到的资源类型的主题，当门户切换到设置的主题时，对应的资源将自动适配为设置的主题（注：当资源有多个适配主题时，会按照选择的选择的先后顺序进行适配，当资源不支持该适配主题时，会自动适配下一个主题）
### 样式扩展{#style-expand}
门户样式扩展是由门户模板的开发者提供的，根据模板此类属性的选项也不同：
- 区块磁贴首页模板：
- 标题栏居中对齐：设置门户的标题居中对齐
- 标题栏在顶部显示：设置门户的标题栏在顶端显示，勾选此项后标题栏和区块作为整体将居中对齐
- 区块文字显示在外面：区块磁贴首页型门户模板中区块文字默认在区块内部显示，勾选此项后文字将显示在区块下方
- 视图宽度：表示门户中标题栏和区块的整体宽度
- 区块高度：设置每个区块的高度
- 区块宽度：设置每个区块的宽度
:::tip
1. 视图宽度及区块的高度和宽度，支持输入具体的像素值或百分率，如900px或80%
2. 每个区块的高度都是一致的，不支持单独设置单个区块的高度。支持设置单个区块的宽度，点击区块对应的内容节点，在**内容区**属性中**扩展属性**>**宽度**，参考[门户内容属性设置](#门户内容属性设置)
3. 当每个区块的总宽度超过视图宽度时，区块的排列位置起点不变，宽度会往右侧超出
:::
- 通用幻灯片模板：
- 显示标题：通用幻灯片中会默认展示节点的标题
- 内容撑满页面：在ppt幻灯片中，默认有一个展示窗口，节点内容会在窗口中展示。当页面内容较多需要全屏展示时取消勾选即可
### 导航栏交互设置{#interactive}
导航栏即门户页面顶端右侧区域，在**属性栏**>**交互**中提供了对门户导航栏的设置，用户可以自定义导航栏的交互事件。设置交互事件后，会在门户顶部导航栏右侧出现对应的选择按钮：
- **注销**：勾选后导航栏即会出现个人头像，点击个人头像下拉选择注销即可退出登录系统
- **显示当前日期和时间**：勾选后，即可在导航栏中显示系统的当前日期和时间
- **返回首页**：勾选后根据是否设置**首页地址**会有以下2种情况，其中首页地址支持相对地址和绝对地址，或者系统外部地址：
- 设置了**首页地址**：输入地址后，导航栏上即会出现返回首页的按钮，点击后即可返回指定的首页地址。
- 未设置**首页地址**：当该门户是作为其他门户的子门户时，勾选返回首页导航栏上即会出现返回首页的按钮，在该门户页面点击后会跳转到该门户所在的父门户首页。若不是作为子门户，未设置首页地址，即返回首页不生效，导航栏不会出现该交互按钮。
- **切换主题**：系统对各类门户模板都提供了适应当前模板的主题（除首页型模板门户外），勾选后并**选择允许切换的主题**，即可在预览界面选择对应主题进行切换。当允许切换的主题选择0个或1个时，则表示没有其他主题可进行切换，导航栏上不会显示切换主题的按钮。若需要在门户模板中添加自定义的主题，可参考文档[如何切换门户页面主题](./FAQ/如何切换门户页面主题.md)
:::tip
在设计器中不能进行**注销**和**返回首页**，需保存门户后进行**查看**时才可操作
:::
### 交互扩展设置{#interactive-expand}
扩展属性是由门户模板开发作者提供的，不同门户页面有不同的扩展属性。
- 通用幻灯片模板：
- 显示全屏按钮：在门户右上角的功能按钮处提供全屏查看的按钮
- 显示缩略图按钮：在门户右上角的功能按钮处提供查看缩略图的按钮，勾选后在播放页面时点击该按钮，将显示该门户下的所有页面内容，并以缩略图的形式展示
- 显示左右切换键：在门户左右两侧显示左右切换的按钮
- 显示顶部自动切换按钮：勾选后顶部会增加自动切换的按钮，点击后门户中的内容即可自动进行轮播
- 页面停留时间（毫秒）：当启动自动切换页面后，每个页面停留设置的时间后，会轮播展示下一个页面
- 显示底部圆点：在门户底部会以圆点的形式代表每一个页面，点击对应圆点即可显示对应页面
- 自动隐藏功能按钮
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/portal-layout.md"
htmlUrl: "https://docs.succapp.com/v5/app/portal-page/portal-layout"
title: "门户布局方式"
---
---
order: 2
---
# 门户布局方式
门户的布局方式即用来设置门户内容的下级节点的展示样式。只有文件夹节点可设置布局方式。
## 默认布局方式{#default}
系统内置了丰富的门户模板，在每类模板中节点都有默认的布局方式，布局方式为：
1. 除幻灯片和首页门户类型外，其它门户默认模板布局方式是顶部标签页+左侧树形式
2. 可以设置每个目录节点的布局方式，该设置只影响该目录下的资源，不会影响到下一级目录
## 设置布局方式{#setts}
在门户设计器内容区，选择文件夹节点>**内容属性栏**>**布局方式**，在下拉列表中选择对应的布局方式后，即可在右侧的预览区预览效果
:::tip
1. 未选中节点时，即设置一级节点的布局方式。
2. 节点的布局方式，作用的范围是直接下级节点，每一个节点都只能控制下一级的布局方式。
:::
## 布局方式类型{#type}
门户的布局方式有[左侧树](#left-tree)、[标签页](#tabbar)、[子菜单](#submenu)、[缩略图](#thumbnail)。各种类型之间可以进行组合布局，如在一级资源节点布局方式为标签页，二级资源节点为子菜单。
各种布局方式的规则如下：
| 布局类型 | 规则 |
| -------- | ------------------------------------------------------------ |
| 左侧树 | 如果上级节点是左侧树，当级节点选择左侧树时，表示作为当前树的节点布局，而不是生成一棵新的树 |
| 标签页 | 1. 标签页布局不能嵌套，即标签页布局下的子资源不能再设置为标签页布局
2. 标签页布局只支持二级资源的展现形式为标签页，即在一级资源设置布局方式为标签页 |
| 子菜单 | 一级资源不能使用子菜单布局 |
| 缩略图 | 以缩略图形式展示二级目录下的资源，如果是文件夹则展示文件夹的缩略图 |
:::tip
首页型模板资源节点不能是目录或文件夹，故不支持设置布局方式。
:::
### 左侧树{#left-tree}
下级资源节点在门户的左侧以树的形式展示
### 标签页{#tabbar}
当前资源下的节点以多个标签页的形式展现。
### 子菜单{#submenu}
在当前节点下，子节点的内容以菜单列表的形式展现在当前节点下，点击节点名称即可出现子菜单列表。
### 缩略图{#thumbnail}
以缩略图形式展示二级目录下的资源，有**分组**和**大纲**两种方式。缩略图缺省情况下，系统会自动截取一个缩略图；也可以自定义缩略图，有如下有两种设置方法：
1. 在**门户内容区**>**选中节点**>**高级**>**缩略图**中设置，可设置默认、静态图片以及URL。当门户中新增的节点，链接引用外部资源时，只能使用此方式设置缩略图
2. 拖入的资源，可右键节点定位该资源，**右键资源**>**属性**>**缩略图**>**PC预览**中，点击上传即可。该方法上传的缩略图优先级低于在门户内容区中设置的缩略图
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/portal-permission.md"
htmlUrl: "https://docs.succapp.com/v5/app/portal-page/portal-permission"
title: "门户权限控制"
---
---
order: 3
---
# 门户权限控制
一个业务应用可能会有若干个[门户页面](./README.md)组成，一个门户页面是一个集成的页面，内部有多个子模块页面。一个实际的业务系统往往也会针对不同的业务用户分配不同的权限，如不同权限的用户能查看的门户页面不同、不同权限的用户查看同一个门户页面时能看到的功能模块会有不同……。
子模块页面就是门户设计器中拖入到门户页面内容区域的页面资源：
门户页面的权限控制通常涉及到下面几点：
\[\[toc]]
## 门户页面权限设置{#portal-page-permission}
门户页面是一个集成的页面，内部包含了很多子模块页面，但是门户页面本身也还是一个“页面资源”，本质上类似一个仪表板页面或者报表页面，门户页面本身也是可以被分配权限的。与其他资源文件的权限分配方式一样，门户页面的权限需要在**权限**模块下进行权限分配，可参考文档[文件权限管理](../../permission/grant/README.md#file-permission)。
:::tip 提示
分配了门户页面的权限并不代表就可以查看门户页面内部的所有子功能模块页面，门户页面内部引用的其他页面也需要分配权限才能查看。
具体见[页面内子模块权限管理](#portal-page-resource)。
:::
## 页面内子模块权限设置{#portal-page-resource}
门户页面内引用到的子页面也是要被分配权限才能查看的，其权限分配方式和门户页面本身并无区别，在**权限**模块下为用户分配相关子资源页面的查看权限。
:::tip 提示
**门户页面只是将用户有权限查看的页面集成到一起给用户查看了，所有要查看的页面包括门户页面和其内部的子页面都要进行权限分配，也就是说当前用户必须对所有资源包括门户页面和门户页面的子资源页面都拥有权限才行**。
:::
如下图有4个子页面，门户页面显示时会根据当前用户的权限决定显示哪些隐藏哪些：
### 在门户页面的节点上控制显示隐藏{#page-visible-condition}
有些时候不方便通过权限控制子页面的显示隐藏时，也可以通过在门户页面上设置子页面的显示条件来做到，显示条件是一个表达式，可以根据用户的某些属性动态控制子页面资源节点的显示与隐藏。
在门户页面的文件内容区选中该资源节点，然后设置该资源的**显示**属性。如设置“用户组管理”资源仅对管理员展示，则在**高级**>**显示**下选择**条件**，并输入显示条件表达式`USER_INGROUP('demo_sec_glz')`，具体可参考文档[门户内容属性设置](./new-portal.md#attributes)。
## 数据级次权限设置{#data-level}
数据级次权限是指不同用户查看同一个页面时显示不同的数据范围，如北京市用户只能查看北京市的数据、武汉市的只能查看武汉市的……。
门户页面及其内部子页面的数据级次范围遵守统一的数据级次权限设置规则，在**权限**模块下设置资源内容的数据范围，具体可参考文档[数据级次权限](../../permission/grant/datarange.md)。
## 首页设置{#index-page}
首页是用户登录系统后默认显示的页面，通常的业务应用中，不同的业务用户登录后查看的页面可能会有不同，SuccBI支持灵活的首页设置，具体见：
1. [如何定位应用的首页](./FAQ/如何定位应用的首页.md)。
2. [系统默认首页设置](../../sys-settings/basic/homePage.md)。
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/README.md"
htmlUrl: "https://docs.succapp.com/v5/portal-page/faq"
title: "门户FAQ"
---
---
order: 4
---
# 门户FAQ
!!! children !!!
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/如何切换门户页面主题.md"
htmlUrl: "https://docs.succapp.com/v5/howto/d23323fb"
title: "如何切换门户主题"
---
# 如何切换门户主题
SuccBI自带多个门户[模板](../new-portal.md#template)供用户选择使用，而每个门户模板都有一种或多种主题，切换不同的主题能够让门户更加的融洽与美观，本文介绍如何切换门户主题。
## 设置门户默认展示主题{#direct-switch}
设置门户默认展示的主题，可以进入到门户设计器，在**样式**属性栏下方的**主题**下拉框处选择的主题，就是门户默认展示的主题。
## 设置可切换主题{#set-switch}
门户查看界面可以一键切换主题，可以在门户设计器中勾选**切换主题**即可开启此功能。勾选后可以设置切换哪些主题，在允许切换的主题中勾选，此时选中的主题就是门户查看界面中的主题选项。
## 设置资源适配主题{#adaptive-theme}
门户中引用的资源自适应门户主题的风格，可以在**样式**属性栏勾选**内容自适应模板主题**即可。如果加入门户的资源需要保留原有的主题效果，则去掉该勾选，一般用于ppt模板，适合大屏时使用。
也可以指定资源的适配主题，例如当门户选择`浅绿`主题时，仪表板使用`紫色浪潮`主题，则在**设置适配主题**中设置门户主题为`浅绿`，资源类型为`仪表板`，适配主题为`紫色浪潮`，即可实现。
更多的说明可参考文档[门户样式设置](../new-portal.md#style)。
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/如何在门户中嵌入权限管理页面.md"
htmlUrl: "https://docs.succapp.com/v5/howto/permission"
title: "如何在门户中嵌入权限管理页面"
---
# 如何在门户中嵌入权限管理页面
## 需求描述{#description}
系统提供权限管理模块，包含部门管理、用户管理、用户组管理三个页面，共同实现用户权限管理功能，该功能是在管理界面进行的，当需要将权限开放给业务用户维护时，也可将该模块嵌入到门户页面。
## 设置方法{#setup}
将权限管理模块嵌入门户有[拖入资源](#drag)和[自定义链接](#link)两种操作方式。
### 拖入资源操作方式{#drag}
权限管理模块作为系统资源，可直接通过拖拽资源方式嵌入门户，步骤如下：
1. 新增文件夹节点：新建或打开已有的门户页面，在**门户内容区**右键**新增文件夹节点**，并修改标题和图标（可参考文档[添加资源到门户页面](../new-portal.md#add)）
2. 拖入权限管理模块：在**项目资源区**切换项目为`权限管理`，分别拖拽权限管理的部门管理、用户管理、用户组管理三个页面到**门户内容区**新建的文件夹节点下
### 自定义链接操作方式{#link}
使用自定义链接操作方式嵌入权限管理界面到门户中，步骤如下：
1. 新增文件夹节点：新建或打开已有的门户页面，在**门户内容区**右键**新增文件夹节点**，并修改标题和图标
2. 新增子节点：右键新增的文件夹节点，选择**新增子节点**，分别新增三个子节点，对应部门管理、用户管理、用户组管理三个页面，并修改标题和图标
3. 自定义链接：在子节点**链接**属性中分别输入权限管理三个页面路径，设置打开方式为`嵌入`，各页面路径如下
- 部门管理：`/sysdata/app/security.app/depts.fapp`
- 用户管理：`/sysdata/app/security.app/users.fapp`
- 用户组管理：`/sysdata/app/security.app/groups.fapp`
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/如何在门户页面传递参数给资源.md"
htmlUrl: "https://docs.succapp.com/v5/howto/e2538410"
title: "如何在门户页面传递参数给资源"
---
# 如何在门户页面传递参数给资源
门户作为一个框架，除了添加的多个资源外，也存在着打开对应资源的同时传递参数给资源的场景。SuccBI中的门户页面支持传递参数值给对应的资源如仪表板、报表等，从而实现从门户页面进入资源时达到展示特定的数据或效果。
示例地址：[门户页面传递参数](https://demo.succbi.com/v5/demo/门户页面传递参数?MDDM=SLFS02012\&XSSJ=201811\&XS=0)
## 门户资源节点上设置参数{#setup1}
添加资源到门户后，在[门户内容区](../new-portal.md#designer)选择指定资源后，在**高级**属性处可以**添加参数**进行传递。\
此方式需要给参数设置默认值，常用于为参数设置默认值，避免缺省的场景，以打开店面销售情况表传递参数为例，实现思路如下：
1. 明确资源页面中存在的[全局参数](../../../data-viz/dash/design/data/param.md)及其作用，如`MDDM`、`XSSJ`这两个参数就是用于资源页面过滤出对应【门店编码】与【销售时间】的数据
2. 将资源页面拖入门户内容区，在**高级**>**添加参数**处添加需要传递的参数并设置参数值，如`MDDM`设置参数值为`'SLFS02012'`、`XSSJ`设置参数值为`201809`
## 设置资源节点的URL参数{#setup2}
新增[非文件夹节点](../new-portal.md#add)后，在**链接**属性处设置资源路径时，可带上资源页面的参数。以自定义链接传递id为例，实现思路如下：
1. 在门户内容区右键，**新增同级节点**或**新增子节点**，如新增子节点`交互`
2. 在链接属性处添加资源链接并设置参数，如`/DEMO/app/ap.app?id=交互`
## 浏览器地址栏传递参数{#setup3}
直接在URL（即浏览器地址栏）地址后添加传递的参数，参数的语法规则可以查看[参数](../../../data-viz/dash/design/data/param.md#url-param)文档介绍。\
此方法，可以将参数直接传递给资源，不需要在门户资源节点上设置参数。实现思路如下：
1. 在报表中定义全局参数，如`url_param`
2. 直接在浏览器地址栏添加参数及参数值，如`&url_param=3`
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/如何定位应用的首页.md"
htmlUrl: "https://docs.succapp.com/v5/howto/4123b624"
title: "如何定位应用的首页"
---
# 如何定位应用的首页
复杂的应用一般会有多个页面，不同的用户通过不同的设备登录并访问应用的时候，需要显示合适的页面给用户。
系统通过如下规则确定应用的首页，优先级依次如下：
1. `index.action`
2. `index.mpg` - 如果用户使用的是移动设备
3. `index.spg`
4. `index.tpg`
5. `index.html`
---
url: "https://docs.succapp.com/v5/guide/app/portal-page/FAQ/如何集成第三方页面到门户中.md"
htmlUrl: "https://docs.succapp.com/v5/howto/98f4916a"
title: "如何集成第三方页面到门户中"
---
---
order: 2
---
# 如何集成第三方页面到门户中
## 需求描述{#description}
由于[门户页面](../README.md)本身只是一个框架，没有内容，在添加资源到门户页面时，除了直接将系统内部的资源文件拖拽到内容区外（可参考文档[添加资源到门户页面](../new-portal.md#add)），也会存在和第三方系统集成，需要将第三方的页面加入到门户中。
## 设置方法{#setup}
门户页面内容区的每一个节点，都对应了一个资源内容，当第三方页面集成到门户中时，也需要有一个节点作为进入该页面的“入口”，步骤如下：
1. **在门户页面中创建新的节点作为第三方页面的入口**：在门户页面的**内容区**点击鼠标右键，在弹出的菜单中选择**新增节点**
2. **设置节点对应的第三方页面及打开方式**：
1. 设置该节点的名称
2. 在**链接**属性中输入第三方页面的URL
3. 设置打开方式为**嵌入**或其他
::: tip
如果需要访问第三方系统时能正确的登录以及安全性控制请参考: [将第三方系统页面嵌入到SuccBI](../../../dev/integrate/link-3rd-page.md)
:::
---
url: "https://docs.succapp.com/v5/guide/app/mobile/README.md"
htmlUrl: "https://docs.succapp.com/v5/app/mobile"
title: "移动App介绍"
---
---
order: 6
navTitle: 移动App
indexTitle: 移动App介绍
---
# 移动App介绍
SuccBI提供了丰富的组件，零编码就可实现移动App，基于一套技术标准，可以发布多个平台，包括微信小程序、企业微信、钉钉等。
|DEMO移动App|OA系统小程序|疫苗预约小程序|博冷链小程序|
|--|--|--|--|
|||||
示例地址：[DEMO移动App](https://demo.succbi.com/v5/demo/mobile/%E9%A6%96%E9%A1%B5)
可以点击如下链接了解具体的功能操作：
!!!children (guide/app/mobile) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/app/mobile/new-app.md"
htmlUrl: "https://docs.succapp.com/v5/app/mobile/new-app"
title: "新建移动App"
---
---
order: 1
navTitle: 新建移动App
---
# 新建移动App
新建一个移动App步骤如下：
1. 进入项目的**应用**模块，点击新建，选择**移动分组**中的默认移动模板
2. 对应用进行命名，如`移动App`，进入[移动App设计器](#designer)
3. 接下来可以将**应用资源面板**或**项目资源区**中的移动页面拖入**内容区**，即可在首页中浏览该资源。具体操作可查看[添加资源到移动App](#add)
4. 保存后，在**应用**模块下点击即可查看，右键选择**编辑**可以继续修改该App应用
5. 也可以打开右上角的二维码，在同一局域网下，使用手机扫码查看该移动App
## 移动App设计器{#designer}
系统提供了所见即所得的移动App设计器，可以通过拖拉拽快速实现移动App，与[门户设计器](../portal-page/new-portal.md#designer)一致。App设计器界面如下图所示：
## 添加资源到移动App{#add}
移动App是门户的一种，可以引入各种资源（包括仪表板、报表、SuperPage等）组合成一个具有完整业务意义的移动App。只需将制作好的移动资源拖入到**App内容区**即可，具体方法可查看[添加资源到门户页面](../portal-page/new-portal.md#add)，也可以[调整资源顺序](../portal-page/new-portal.md#order)以及[移除资源](../portal-page/new-portal.md#delete)。
:::tip
移动App中需要引用移动资源，以保证移动上的效果适配。移动资源制作方法可查看[仪表板-移动](../../data-viz/dash/design/mobile/README.md)、[SuperPage-移动](../superpage/design/mobile.md)
:::
### 移动App内容属性设置{#attributes}
在App内容区下半部分，可以设置节点属性，包括**标题**、**图标**、**布局方式**以及其他一些**高级**设置，具体可查看[门户内容属性设置](../portal-page/new-portal.md#attributes)。移动App的布局可查看文档[移动App布局方式](./mobile-layout.md)
## 移动App页面属性设置{#settings}
在属性栏中，可设置App页面的样式及交互事件。
1. 在**属性栏**>**样式**下可设置移动App页面的标题栏背景，背景填充方式可参考[填充](../superpage/design/style/README.md#filling)样式。标题栏在App页面的顶端，如下图所示。
2. 在**属性栏**>**交互**下可设置移动App页面下拉刷新功能，下拉页面，即可在页面顶部时出现刷新数据，与[刷新数据](../superpage/design/action/refresh-data.md)交互功能一致。
---
url: "https://docs.succapp.com/v5/guide/app/mobile/mobile-layout.md"
htmlUrl: "https://docs.succapp.com/v5/app/mobile/mobile-layout"
title: "移动App布局方式"
---
---
order: 2
navTitle: 移动App布局方式
---
# 移动App布局方式
移动App支持自定义布局设置，在移动App设计器**内容区**，选择**文件夹节点**>**内容属性栏**>**布局方式**，在下拉列表中选择对应的布局方式后，即可在右侧的预览区预览布局效果。
默认移动模板布局方式为**底部标签**+**列表**，App首页默认为底部标签布局，新增的文件夹节点默认为列表布局，只有在首页和文件夹节点可设置布局方式。
## 布局方式类型{#type}
移动App的布局方式有[底部标签](#bottom-label)、[浮动标签](#float-label)、[顶部标签](#top-label)、[宫格](#grid)、[缩略图](#thumbnail)、[列表](#list)。各种类型之间可以进行组合布局，如在一级资源节点布局方式为底部标签，二级资源节点为缩略图。
### 底部标签{#bottom-label}
当前资源下的节点在移动App底部以标签页形式显示，该布局只能在首页中设置一级资源节点。
### 浮动标签{#float-label}
当前资源下的节点在移动App底部以标签页形式显示，若下级资源节点个数为奇数，则中间的节点图标会浮动出底部；为偶数，效果则与底部标签布局一致。
### 顶部标签{#top-label}
当前资源下的节点在移动App顶部以标签页形式显示，选中的节点名称下有高亮横线。
### 宫格{#grid}
当前资源下的节点以宫格形式显示，可设置宫格的**大小**、**框线**以及**分组**。宫格中显示的图标为[App内容属性](./new-app.md#attributes)中设置的图标。
### 缩略图{#thumbnail}
当前资源下的节点以缩略图形式显示，可设置缩略图的**大小**以及**分组**。缩略图缺省情况下，系统会自动截取一个缩略图；也可以自定义缩略图，有如下两种设置方法：
1. 在**App内容区**>**选中节点**>**高级**>**缩略图**中设置，可设置默认、静态图片以及URL。当移动App中新增的节点，链接引用外部资源时，只能使用此方式设置缩略图
2. 拖入的资源，可右键节点定位该资源，**右键资源**>**属性**>**缩略图**>**手机预览**中，点击上传即可。该方法上传的缩略图优先级低于在App内容区中设置的缩略图
:::tip
在**App内容区**设置的缩略图只适用于当前App，所以在已有资源中设置缩略图，建议使用第二种方法，该方法在不同App中引入同一个资源不用重新设置缩略图。
:::
### 列表{#list}
当前资源下的节点以列表形式显示。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage"
title: "SuperPage介绍"
---
---
order: 7
navTitle: SuperPage
indexTitle: SuperPage介绍
---
# SuperPage介绍
SuperPage是SuccAP提供的一种可视化设计制作**任意的**、**业务化的**和**个性化的**页面或对话框的功能。
一个符合业务使用场景的业务应用往往会有一些个性化的功能性页面，这些页面包含标签页、列表、操作按钮、导航菜单……，它们看起来更像是一个“网页”或是一个业务功能对话框，这些页面不是报表、不是仪表板，在以前开发这样的“网页”或“对话框”通常需要研发工程师编码完成，现在可以用SuperPage可视化设计制作这样的页面或对话框。
使用SuperPage制作个性化页面或对话框相比于传统编码方式具有如下优势：
1. 低成本、高效率
2. 零编码、易维护
3. 可扩展、高复用
4. 美观易用、不损失业务体验
可以点击如下链接了解具体的功能操作：
!!!children (guide/app/superpage) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/app/superpage/new-spg.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/new-spg"
title: "新建SuperPage"
---
---
order: 2
navTitle: 新建SPG
---
# 新建SuperPage
新进一个SuperPage页面的步骤如下：
1. 进入项目的**应用**模块，在模板选择对话框中选择需要的应用模板，进入[应用设计器](../app-designer.md)
2. 在[应用设计器](../app-designer.md)点击左上角的展开箭头，点击+号，在菜单列表中选择**SuperPage**
3. 在**新建SuperPage**对话框中选择需要的模板
4. 在命名对话框中输入合适且有意义的**名称**，点击**确定**即可新建SuperPage页面
5. 接下来可以添加数据模型及拖入组件进行布局和编辑，完成后点击**保存**即可
---
url: "https://docs.succapp.com/v5/guide/app/superpage/designer.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/designer"
title: "SuperPage设计器界面介绍"
---
---
order: 3
navTitle: SPG设计器
---
# SuperPage设计器界面介绍
SuperPage设计器是用来设计SuperPage页面的可视化工具，SuperPage设计器界面如下图：
可以将其划分为如下几个区域：
1. **数据源**：数据源区域列出了用于可视化分析的数据模型，也可以添加数据模型、数据集、表内数据加工、定义模型间的关联关系、增加计算字段、删除数据模型等
2. **组件区**：提供了丰富的可视化组件，如常用、布局、导航组件等，可以使用拖拽的方式从组件区中将组件快速添加到画布
3. **画布**：画布是可视化组件布局的区域，可以在画布中添加任意组件，并通过拖拽的方式，任意布局组件的位置
4. **属性栏**：显示画布中当前选中组件的可配置属性，包括：数据、样式、交互等
5. **工具栏**：工具栏中提供了对SuperPage页面的全局设置，如全局参数、定时刷新等
## 设计器快捷键{#hotkey}
设计器支持快捷键如下：
| 功能 | Windows/Linux | macOS |
| ---------- | :---- | :---- |
| 剪切 | `Ctrl + X` | `Command + X` |
| 复制 | `Ctrl + C` | `Command + C` |
| 粘贴 | `Ctrl + V` | `Command + V` |
## 查看引用{#view-reference}
使用查看引用可以快速查看以及定位当前[模型表](./design/datasourse.md)、[组件](./components/common/text.md)或[参数](../../data-viz/dash/design/data/param.md)在页面中被引用的地方。在设计器中，选中模型表或组件，点击鼠标右键，在弹出的菜单中选择**查看引用**选项即可查看引用列表，点击内容，可定位到对应组件或数据源引用的位置，如下所示：
设计器中支持查看引用的内容如下：
- **数据模型查看引用**：可以查看模型或字段被哪些组件属性引用
- **组件查看引用**：可以查看选中组件被其他组件或数据源引用情况
- **参数查看引用**：可以查看引用该参数的组件或数据源列表
### 快速修改引用错误{#modify-reference-errors}
删除被引用的模型表、组件以及参数时，会弹出引用该内容的列表，当强制删除后，被引用的地方出现报错。同时右上角信息处会显示错误提示，点击可快速定位错误，也就是删除内容被引用的地方。
## 调整组件图层{#adjust-layer}
在制作SuperPage过程中，需要将组件固定在某个位置时会使用[绝对位置](./design/layout.md#absolutely)，设置绝对位置后，该组件可能会被其他组件遮挡，此时可通过调整组件图层将其置于顶部，即**选中组件**>**右键菜单**，点击**置于顶层**即可。只有设置绝对位置的组件可以调整图层顺序。
调整图层选项有**上移一层**、**下移一层**、**置于顶层**、**置于底层**四个，具体可参考[仪表板调整组件图层](../../data-viz/dash/designer.md#adjust-layer)。
## 组件大纲树{#outline-tree}
在设计器中拖入组件制作内容时，会依据拖入顺序以及包含关系自动生成组件大纲树，点击左上角**文件**>**显示/隐藏组件大纲**即可查看，大纲树可点击左上角图标拖动出来，也可移动到页面中的任何位置。大纲树提供了如下操作：
1. 选中组件可快速定位在画布中的位置
2. 可展开/收起面板等容器，快速查看组件之间的包含关系
3. 使用拖拽快速调整组件的位置
4. 右键弹出菜单可对其进行快捷操作，如复制、重命名等
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components"
title: "SuperPage组件"
---
---
order: 4
navTitle: SPG组件
---
# SuperPage组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/common"
title: "常用组件"
---
---
order: 1
navTitle: 常用
---
# 常用组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/text.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/text"
title: "SuperPage组件-文本"
---
---
order: 1
navTitle: 文本
---
# SuperPage组件-文本
文本组件主要是作为描述性、解释性语言来串联整个页面。如网站中的一些标题等。本文主要结合文本组件常见的使用场景，来为大家揭秘文本组件的使用方式与属性特征。
示例地址：[文本组件](https://demo.succbi.com/v5/ap/text)
## 基本使用 {#use}
文本组件是一个十分常用的组件，在使用时可以直接使用纯文本展示固定的文本内容，也可以在文本内容中使用含有宏的表达式读取数据表中的内容或进行计算。
1. **将文本组件拖入到画布中**：在**组件区**>**常用**分组下将**文本**组件拖入到画布中
2. **设置文本内容**：可双击输入文本内容，或在**属性栏**>**文本**>**内容**设置文本内容
## 文本自适应 {#adaptive}
文本组件支持根据规则自适应调整组件和字体的大小以及呈现方式。比如文本溢出时进行缩排、宽度不够时显示省略号等，更多展示效果如下图：
### 自定义文本行数 {#flex-wrap}
文本组件支持自定义文本的展示行数，比如当文字内容较多可能会超出组件大小时，可通过**自动换行**属性设置是否换行展示或者仅展示一行。
- **自动换行**：默认勾选，勾选表示文本超出组件宽度时会自动换行。勾选该属性后会出现**显示行数**属性。不勾选时仅展示单行文本，超出文本组件的部分用`...`代替
- **显示行数**：可限制自动换行的文本行数，系统默认有`自动`、`两行`、`三行`三个选项，也可以通过手动输入数字来限定行数
### 文本溢出时缩排 {#indentation}
文本组件除了可以自定义展示行数外，对于超出预设范围的文字，也可以通过**文字调整**属性设置文本溢出时自动缩排，确保文字在文本组件内显示完整且格式整齐。文字调整主要有三种方式不调整、溢出时缩排、根据文字大小调整。
- **不调整**：对超出预设范围的文字不进行调整
- **溢出时缩排**：文本组件大小固定时，文本内容超出预设范围，将对文本进行缩排，确保文字在文本组件内显示完整且格式整齐
- **根据文字大小调整**：文本组件高度固定时，多行文本内容超出预设高度，可自动根据文字内容撑大组件
## 自定义提示 {#tips}
系统支持对文本组件设置自定义提示，当鼠标移入文本内容时，会自动显示自定义的提示内容。比如对于超出预设范围且不自动换行的文本，鼠标移入该文本时，自动提示完整的文本内容。
- **自定义提示内容**：在**文本**>**提示**属性处选择并输入对应的提示内容
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/button.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/button"
title: "SuperPage组件-按钮"
---
---
order: 2
navTitle: 按钮
---
# SuperPage组件-按钮
按钮组件是通过点击来执行操作，需要配合交互使用。例如点击按钮实现列表数据的下载等，同时可以为不同应用场景下的按钮设置适配的样式，如下是常用的样式效果：
示例地址：[按钮](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8C%89%E9%92%AE)
## 使用按钮组件{#start}
**操作步骤：**
1. **拖入按钮：** 在**组件区**>**常用**分组下将按钮组件拖入到画布中或者某个区域内
2. **设置标题：** 在**属性栏**>**按钮**>**内容**中，设置按钮标题
3. **选择风格：** 在**属性栏**>**样式**中可以根据情况选择需要的按钮风格，或者可以通过样式属性进行设置，也可以通过[状态样式](#状态样式)设置按钮**悬停**等状态样式
4. **设置交互：** 在**属性栏**>**交互**>**添加动作**中，可以添加需要的按钮交互事件，比如添加**导出数据**交互来导出列表数据
:::tip
按钮、图标按钮组件均属于按钮一类。两个组件的功能一致，区别是默认的设置不同，可以根据用途快速拖入到合适的场景中。其中不同的默认设置如下：
- 内容：按钮内容为**按钮**，图标按钮**无内容**
- 位置大小：按钮宽度**自适应**，图标按钮宽度为**固定像素**
- 图标前缀：按钮默认为**无**，图标按钮默认**有**
- 内边距：按钮左右默认为**10**，图标按钮左右默认为**0**
:::
## 属性介绍{#properties}
### 状态样式{#style}
用于按钮组件特殊值，或者设置鼠标在按钮组件上进行操作时，按钮状态的样式，主要有以下几种类型：
- 突出显示：设置当按钮的值为某个特殊值时，按钮的显示样式
- 按钮状态样式：当鼠标**悬停**、**按下**、或**选中**按钮时的样式效果
- 忙碌：忙碌是一种加载状态，设置忙碌，当按钮处于正在加载的状态时会显示此样式效果
- 禁用：设置按钮禁止使用的样式效果
关于状态样式的更多说明，可以参考文档[状态样式介绍](../../design/style/condition-style.md#introduce)。
### 启用切换{#switch}
可以切换按钮点击前与选中后的文字内容、以及页面交互效果，以此来标注按钮是否被选中。比如勾选**启用切换**，设置对应选中后标题，点击按钮切换文字内容来标注升序或降序的排序：
示例地址：[启用切换](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8C%89%E9%92%AE)
## 应用场景{#scenarios}
### 点击按钮弹出菜单选项{#menu}
与其他组件一起组合使用，也是按钮常使用的一种方法。点击按钮可以弹出菜单，这是按钮组件与菜单组件组合使用的效果，通过点击按钮弹出菜单，即可进行多级菜单的选择。
在**属性栏**>**交互**>**添加动作**，添加**弹出菜单**交互，选择对应的**菜单组件**即可，更多操作设置查看[菜单](./menu.md)。
示例地址：[弹出菜单](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8C%89%E9%92%AE)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/icon.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/icon"
title: "SuperPage组件-图标"
---
---
order: 3
navTitle: 图标
---
# SuperPage组件-图标
SuperPage提供了图标组件，用来显示系统自带的、用户上传的或者使用URL的图标：
示例地址：[图标](https://demo.succbi.com/v5/demo-spg/%E5%9B%BE%E6%A0%87)
## 使用图标{#use}
使用图标组件可以按照需要选择相应的图标，并且可以自定义图标的颜色和大小：
1. **拖入图标组件**：将**组件>常用>图标**拖入到目标面板中
2. **选择图标并自定义图标的颜色和大小**：在**图标>基本>图标**中分别设置
## 图标来源{#source}
SuperPage提供了**图标库**、**对象内图标**、**主题图标**和**URL**四种可选来源，可以参考SuperPage[图片来源](./image.md#source)文档中的**静态图片**和**路径**。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/image.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/image"
title: "SuperPage组件-图片"
---
---
order: 4
navTitle: 图片
---
# SuperPage组件-图片
SuperPage提供了图片组件，可以显示上传的静态图片、指定路径的图片和数据库中的图片信息。
示例地址：[图片](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%9B%BE%E7%89%87)
## 使用图片组件{#start}
在SuperPage中，图片是一个常用的组件。操作步骤如下：
1. **拖入图片组件：** 在**组件区**>**常用**分组下将**图片**组件拖入到画布中
2. **设置图片内容：** 在**属性栏**>**图片**中，**图片来源**选择`静态图片`，在对象内选择图片即可
3. **设置填充方式：** 在**图片**>**填充方式**中根据图片效果选择合适的**填充方式**，如`充满容器`
## 图片来源{#source}
图片组件提供了**静态图片**、**数据表**、**路径**三种可选来源。根据图片的性质可以选择不同方式：
- **静态图片**：可选择**对象内图片**、**主题图片**以及**图片库**，也可以自定义上传，具体可参考[静态图片](#image)
- **数据表**：在**图片字段**属性中，选择数据表中存储图片路径的字段即可。图片字段下拉框中，只显示数据表中字段角色为[附件角色](../../../../data-gov/model/field-role.md#file)和[图片角色](../../../../data-gov/model/field-role.md#file)的字段
- **路径**：在**图片路径**属性中直接写入图片的路径即可，分为以下几种情况
- 使用本主题内的，可直接右键复制图片路径即可，如`$THEMEIMG:/images/picture1.png`
- 使用其他主题的，可打开对应图片的属性，复制路径粘贴即可，如`/sysdata/settings/themes/dash/purple/images/bg_guage.png`
- 使用外网的路径，如`https://docs.succbi.com/assets/img/2019-11-24-17-04-53.a004db9f.png`
- 使用动态路径，即编写表达式控制动态显示图片，且表达式可以使用模型字段和全局参数，如`${if(param=1,'$THEMEIMG:/images/picture1.png','$THEMEIMG:/images/picture2.png')}`
### 静态图片{#image}
静态图片下的三种图片类型主要区别在于存储位置不同，具体如下：
- **对象内图片**：存储于当前页面对象中，在其他页面中的对象内图片区域不可见
- **主题图片**：存储于对应[主题](https://docs.succapp.com/v5/superpage/themes)中，不同的页面使用相同主题时，主题图片中内容是一致的
- **图片库**：存储于当前[项目](../../../../project-manage/README.md)中的公开图片库，同一个项目中的不同页面图片库内容也是一致的
当原本已有的图片不满足需求时，可根据图片通用性等进行自定义上传，不需要显示图片时，也可以**清除图片**。
## 填充方式{#fill}
图片组件提供了六种填充方式，可以满足不同大小、不同类型的图片适应更好的场景效果：
- **原始大小**：可调节缩放比例调整图片大小，图片大小与容器大小无关。容器大于图片，图片完全显示；容器小于图片，图片只显示容器框所在部分。可设置水平与垂直对齐方式
- **拉伸**：图片不按比例缩放，而是根据容器大小拉伸，让一张图片就占满容器，可能会变形，但图片是完整显示的
- **充满容器**：图片等比缩放，按照图片的最小边来适应容器的最大边，如果图片和容器的比例不一致，就有部分被切掉而显示不了
- **适合于容器**：图片等比缩放，按照图片的最大边来适应容器的最小边，图片会完全显示在容器内，容器可能会有部分是空白的。
- **平铺**：将图片平铺显示，可通过缩放比例调整图片大小，比例越小，容器中平铺的图片越多，适用于背景纹理的图片。平铺有三种平铺方式：
- 平铺：同时向横向与纵向进行平铺，铺满容器
- 横平铺：向横向方向进行平铺，只平铺一行
- 纵平铺：向纵向方向进行平铺，只平铺一列
- **切片**：切片是一种较为灵活的填充方式，这种方式在填充的时候，会将图片划分为3\*3的九宫格区域。其中四个角的图片部分是不会收到拉伸的，上下的中间区域会被水平拉伸，左右的中间区域会被垂直拉伸，具体参考下图
| 切片编辑器 | 切片原理 |
| --- | --- |
|  |  |
## 应用场景{#scenarios}
### 图片墙{#photo-wall}
图片可以读取数据库图片，照片墙实现思路：
1. 使用[浮动面板](../layout/floatpanel.md)组件，该组件中拖入图片组件
2. 图片组件设置为从数据库中读取图片即可
示例地址：[图片-图片浮动](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%9B%BE%E7%89%87)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/common/menu.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/menu"
title: "SuperPage组件-菜单"
---
---
order: 5
navTitle: 菜单
---
# SuperPage组件-菜单
菜单是一系列选项列表，支持配置单级、多级以及带图标的菜单列表。可以与按钮组件组合实现弹出菜单效果，如在PC端和移动端点击按钮弹出菜单会有不同的适配效果：
|PC端|移动端|
|--|--|
|||
示例地址：[菜单](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%BC%B9%E5%87%BA%E8%8F%9C%E5%8D%95)
## 使用菜单组件{#start}
菜单组件通常是由用户的交互触发而显示的，比如点击按钮后显示下拉菜单、右键点击显示菜单等。使用菜单需要两个步骤，包括拖入菜单并配置菜单项内容、配置交互实现弹出菜单。具体步骤如下：
1. **拖入菜单：** 在**组件区**>**常用**分组下将菜单组件拖入到画布中
2. **设置菜单项：** 在**属性栏**>**菜单**>**设置菜单项**中，添加菜单项，并为其设置内容和交互
- 设置内容：标题为`导出`，设置`导出图标`
- 设置交互：切换到交互中，添加动作为`导出数据`，并设置数据组件属性为`列表1`
3. **配置弹出菜单交互：** 在按钮中添加**弹出菜单**交互，并在**菜单组件**属性中选择对应的菜单组件`菜单8`即可，更多设置查看[弹出菜单交互](#popupmenu)
:::tip
在预览、查看等界面不能看见菜单组件，所以菜单组件可以位于画布中任意位置且不影响其他组件，建议位于被弹出菜单交互引用的组件附近。
:::
## 弹出菜单交互{#popupmenu}
菜单组件必须配合**弹出菜单**交互使用才能将菜单中设置的内容展示在页面中，才能实现菜单的作用。使用时只需两个步骤：
1. 在对应组件中添加**弹出菜单**交互
2. 在**菜单组件**属性中选择对应的菜单组件
弹出的菜单也能适应手机，效果可见顶部移动端效果动图。在**弹出菜单**>**手机显示**属性中提供了移动端弹出菜单的设置：
- **悬浮菜单**：从点击的位置以悬浮面板形式显示菜单
- **底部滑出**：从底部滑出，停留在底部，默认为底部滑出，此时可对菜单进行以下设置
- 自动添加“取消”按钮：勾选后，则在菜单最底部出现取消按钮
- 菜单标题：在菜单顶部出现菜单标题
- 顶部描述：在标题下方出现描述信息，支持输入宏
## 属性介绍{#description}
### 菜单设置{#settings}
点击**设置菜单项**，在弹出的编辑对话框中可以设置菜单列表和菜单项。
**菜单列表设置**
在设置菜单项对话框的左侧，可以设置菜单列表。点击**添加**默认在一级菜单尾部添加新的菜单项，名称默认为`菜单项+数字`。菜单列表具体设置如下所示：
- 添加：点击添加或者下拉按钮可以添加新的菜单项或者菜单子项
- 添加菜单项：点击添加或者下拉按钮可直接添加菜单项
- 添加菜单子项：在**下拉按钮**>**添加到下级**，选择菜单项，可以添加当前选中菜单项的子项
- 添加分割线：在**下拉按钮**可以添加分割线，默认添加在菜单项尾部，需要移至菜单项之间，起到分隔菜单项作用
- 搜索：当选项较多时，可以通过搜索按钮输入菜单项标题关键字，能快速找到目标菜单项
- 复制：点击复制按钮可复制菜单项，属性会保持一致
- 删除：点击删除按钮即可删除当前菜单项
- 移动：选中菜单项拖动即可移动菜单项的顺序
**菜单项设置**
选中某个菜单项，在设置菜单项对话框的右侧，可以设置该菜单项的内容和交互。具体属性内容如下：
- 标题：设置弹出菜单中显示菜单项的标题
- 内容：设置菜单项的值
- 图标：设置菜单项标题的图标前缀，可设置颜色
- 显示：设置该菜单项在满足一定条件时是否显示，可使用[表达式](../../../../exp/README.md)
- 启用：设置该菜单项在满足一定条件时是否启用发生交互，可使用[表达式](../../../../exp/README.md)
- 允许勾选：设置菜单项在满足一定条件时是否被勾选，可使用[表达式](../../../../exp/README.md)，勾选后在标题前方会出现`√`的图标。其中**分组**是对菜单项进行分组，当设置相同时，在同一组的菜单项中默认只能勾选一个
- 交互：设置对应菜单项可触发的交互动作，可参考文档[交互](../../design/action/README.md)
### 弹出菜单大小设置{#size}
弹出菜单的大小，默认是根据菜单项个数与标题长度自动调整到合适大小，也可以根据需求手动调整。提供如下属性设置：
- 菜单项高度：默认为自适应，自动根据菜单项个数调整高度，也可以设置固定高度
- 菜单项宽度：默认为自适应，自动根据菜单项标题长度调整宽度，也可以设置固定宽度
- 选项内边距：默认为0，调整弹出菜单上下、左右内边距
## 应用场景{#application}
### 多级菜单{#multistage}
当菜单项较多时，可以按照功能为菜单项分类，显示为树形结构的多级菜单。在**设置菜单项**对话框左侧，选中需要设置下级菜单的菜单项，点击下拉按钮在**添加到下级**中选择菜单项，即可实现树形结构的多级菜单：
示例地址：[菜单-多级菜单](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%BC%B9%E5%87%BA%E8%8F%9C%E5%8D%95)
### 动态菜单项{#trends}
菜单项可以设置动态的显示隐藏条件和禁用条件，这样可以动态决定某些菜单是否显示是否可用，例如根据登录用户不同决定某个菜单是否显示。通过设置菜单项的**显示**>**显示条件**属性或者**启用**>**启用条件**属性即可实现。
如勾选一行列表时显示编辑菜单项，设置编辑菜单项的显示条件表达式为`[列表1].[勾选行数] = 1`：
|勾选单行列表菜单项|勾选多行列表菜单项|
|---|---|
|||
示例地址：[菜单-禁用与隐藏](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%BC%B9%E5%87%BA%E8%8F%9C%E5%8D%95)
### 移动底部菜单{#mobile}
当需要在手机上显示菜单时，能以底部滑出的效果显示适应手机。只需将**弹出菜单交互**>**手机显示**属性设置为`底部滑出`即可，更多移动设置可参考[弹出菜单交互](#popupmenu)。
示例地址：[移动底部菜单](https://demo.succbi.com/v5/demo-spg/mobile/%E5%BC%B9%E5%87%BA%E8%8F%9C%E5%8D%95)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/layout"
title: "布局组件"
---
---
order: 2
navTitle: 布局
---
# 布局组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/panel.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/panel"
title: "SuperPage组件-面板"
---
---
order: 1
navTitle: 面板
---
# SuperPage组件-面板
面板组件是用于布局页面内容的容器。当部分页面内容需要按照一定的规则排列时，可以将内容放置到面板组件中，并使用面板组件的横向或纵向布局组合达到排版目的。如条件输入框横向排列，且能根据屏幕宽度自动换行：
示例地址: [面板组件地址](https://demo.succbi.com/v5/demo-spg/%E9%9D%A2%E6%9D%BF)
## 使用面板组件{#use}
在SuperPage页面中，面板组件是用于布局内容，操作步骤如下：
1. **拖入面板组件：** 在**组件区>布局**分组下将面板组件拖入到画布或者某个区域内容
2. **设置面板内部布局方式：** 继续选择拖入的面板组件，在**属性栏>面板**中，选择面板内部的布局方式为`横向布局`
3. **设置面板组件的位置大小：** 在**属性栏>面板**中，根据需求设置面板组件的位置，以及高度和宽度的占比
4. **设置面板样式：** 在**属性栏>样式**中可以根据情况设置组件的边框，或者内边距、外边距，以达到美观的布局效果
通过上述步骤即可实现使用面板布局页面内容，更多的布局技巧可以查看文档[SuperPage布局](../../design/layout.md)。
### 面板相关组件介绍{#introduction}
**面板、横向布局、纵向布局、工具栏**这四类组件均为容器组件，用于页面的布局。四个组件的功能一致，区别是默认的内部布局方向不同，可以根据用途快速拖入合适的布局容器。其中：
- 面板组件：内部布局方向默认是纵向
- 横向布局组件：内部布局方向默认是横向
- 纵向布局组件：内部布局方向默认是纵向
- 工具栏：内部布局方向默认是横向，且自带三个面板。三个面板横向排开，区别在于其内部布局的横向对齐方式不同。
- 左侧面板：左对齐
- 中间面板：居中
- 右侧面板：右对齐
## 内部布局属性介绍{#inside}
面板组件提供了内部布局属性设置，用于控制拖入到面板内部任意组件的布局方向、横纵向对齐方式、是否有滚动条以及是否绕排设置。
### 内部组件排列方向设置{#direction}
**方向**属性是用于控制拖入到**面板**内部任意组件的排列方向，提供了两个属性设置：
- **内部布局方向**：快捷设置排列方式，提供了纵向和横向两个选项。其中，纵向表示纵向排列内部组件，横向表示横向排列内部组件
- **方向**：和内部布局方向功能一致。提供了更多的方向设置，分别为：
- 纵向：内部组件纵向排列
- 横向：内部组件横向排列
- 纵向自底向上：内部组件反向从底部往上排列，和纵向是上下反向
- 横向自右向左：内部组件反向从右边往左边排列，和横向是左右反向
### 内部组件对齐设置{#alignment}
对齐设置包括组件的横向对齐方式和纵向的对齐方式，这里的对齐属性设置是和[方向](#内部组件排列方向设置)的设置有关联。
当**方向**属性设置为`横向`或`横向自右向左`时，可以设置组件的横向对齐和纵向对齐方式：
- **横向对齐：** 内部组件横向排列时，设置横向的对齐方式。提供了五个设置选项，包括左对齐、右对齐、居中、两端对齐、均匀分散。其中两端对齐是指最左和最右的组件顶头，中间组件均匀分布；均匀分散是指每个组件平分排列
- **纵向对齐：** 内部组件横向排列时，纵向的对齐方式设置。提供了五个设置选项，包括拉伸、顶端对齐、底端对齐、居中、基线对齐。
- 拉伸：表示内部组件占据的高度撑满面板组件的高度。拉伸和内部组件的**位置大小**设置有关系，当内部组件的**宽度**为`自适应`时，拉伸才会起作用。
- 基线对齐：按照一行内所有组件的基线对齐。当设置为绕排时，若排列超过一行时，则每一行按照行内的组件基线对齐
当**方向**属性设置为`纵向`或`纵向自底向上`时，可以设置组件的纵向对齐和横向对齐方式：
- **纵向对齐：** 内部组件纵向排列时，设置纵向的对齐方式。提供了五个设置选项，包括顶端对齐、底端对齐、居中、两端对齐、均匀分散。选项的说明同方向为横向的横向对齐。
- **横向对齐：** 内部组件纵向排列时，横向的对齐方式设置。提供了五个设置选项，包括拉伸、左对齐、右对齐、居中、基线对齐。选项的说明同方向为横向的纵向对齐。
### 滚动条和绕排设置{#scroll-wind}
当面板组件占据的大小不能完整显示内部组件内容时，可以选择设置滚动显示或者内容绕排显示：
- **滚动条：** 设置后面板组件内部会出现对应滚动条，可以滚动显示不可见区域内容。提供了四个设置选项
- 无：默认是无滚动条
- 横向滚动：显示横向的滚动条
- 纵向滚动：显示纵向的滚动条
- 横纵向滚动：显示横向和纵向的滚动条
- **绕排：** 当内部组件一行或者一列显示不下时，设置为绕排后，内部组件会换行显示。
- **行对齐：** 当勾选`绕排`时，会出现此属性，用于设置绕排后，当排列组件超过一行时每行之间的对齐方式，提供的选项和[方向属性](#内部组件排列方向设置)的设置有关系
- 方向属性为`横向对齐`：提供了六个设置选项，包括拉伸、顶端对齐、底端对齐、居中、两端对齐、均匀分散
- 方向属性为`纵向对齐`：提供了六个设置选项，包括拉伸、左对齐、右对齐、居中、两端对齐、均匀分散
## 应用场景{#scene}
布局组件嵌套，并按需设置方向为横向或纵向布局，可以实现多样的布局效果。
### 工字形布局{#i-shape}
工字形布局是web应用比较广泛的布局，它将页面分成了页头，侧面导航栏，内容栏和页脚栏四个部分。具体形式如下所示：
示例地址: [工字形布局](https://demo.succbi.com/v5/demo-spg/%E9%9D%A2%E6%9D%BF)
### 卡片式布局{#card}
卡片式布局常以方块方式展示关键信息。具体形式如下所示：
示例地址: [卡片式布局](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E9%9D%A2%E6%9D%BF)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/panelbook.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/panelbook"
title: "SuperPage组件-多页面板"
---
---
order: 5
navTitle: 多页面板
---
# SuperPage组件-多页面板
多页面板用于多页面展示相关业务，可以配合标签页组件动态切换显示面板页面，每个面板页面都可以任意组合布局，功能与[面板](superpage/component/panel)相同。如下示例：
示例地址：[多页面板](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%A4%9A%E9%A1%B5%E9%9D%A2%E7%89%88)
## 使用多页面板组件{#start}
多页面板可以添加多个页面，使用时需要在各页面添加相应的内容，并使用标签页或下拉框等组件设置交互以实现页面的切换。以标签页为例，如下是操作步骤：
1. **使用多页面板组件**：在**组件区**>**布局**中将**多页面板**组件拖入到画布中
2. **添加面板页面**：多页面板默认提供了两个面板页，由于此时需要三个页面，所以在左上角的下拉列表中选择**添加**一个页面
3. **在每个面板页面填充内容**：在多页面板组件左上角的下拉列表中切换页面，为每个页面设置内容，可以参考[面板](superpage/component/panel)
4. **使用标签页组件切换多页面板**：选中标签页，在**交互**中添加**切换多页面板**，目标对象选择该多页面板，目标面板选择**事件源序号**。具体的使用方法可参考[标签页](../navigation/tabbar.md)
## 切换多页面板交互{#switch-panelbook}
多页面板组件配合[标签页](../navigation/tabbar.md)、[下拉框](../input/combobox.md)组件以及**切换多页面板**交互，可以实现多页面板中子页面的动态切换，具体交互设置可查看[切换多页面板交互](../../design/action/switch-panelbook.md)。
## 属性介绍{#attribute}
### 默认页{#defaultpage}
默认页，即第一次查看时显示的面板页面。可以设置某个具体的面板页面为默认页，也可以动态设置默认面板页面。选中多页面板组件，按一次ESC键，在**多页面板**>**默认页**中设置。有两种类型的设置方式：
- **选择固定值**：即选择固定的页面，如panel1
- **动态显示默认面板**：即选择**条件**，在弹出的对话框中编辑表达式，一般配合用户使用。例如根据用户所在用户组决定显示的页面，表达式为`IF(USER_INGROUP('anonymous),'panel1','panel2')`，表示若用户属于匿名用户，则显示panel1，否则显示panel2
### 名称{#name}
单个面板页面的名称，唯一标识该页面，不能重复。名称支持重命名，按ESC键弹出多页面板页面的管理菜单，切换到需要修改名称的面板页面，在**面板**>**名称**中重命名。
### 面板页面管理{#manage}
在多页面板页面管理菜单中可以添加，删除，移动和复制面板页面，也可以重命名面板页面名称。选中多页面板，在多页面板组件的左上角菜单中进行相关操作。
- **添加**：添加新的面板页面。点击菜单中的添加按钮，即可添加一个新的面板页面。新的面板页面的命名是根据系统中生成的页面顺序自动在panel后面加1，且名称是当前面板中唯一的。
- **重命名**：快捷修改页面的名称。点击重命名按钮，即可修改该页面的名称，名称唯一不可重复。
- **复制**：复制当前选中的页面。复制的页面名称是根据系统中生成的页面顺序自动在panel后面加1，且名称是当前面板中唯一的，并排序在当前所有页面的最后。复制出来的面板页面内容是一致的，修改互不影响。
- **删除**：删除选中的页面。点击需要删除页面后面的删除按钮，即可删除当前选中的页面，可以通过撤销键撤销此操作。
- **移动**：在多页面板的页面管理菜单下拉框中，选中页面并使用鼠标左键进行拖拽，将其移动到期望位置。
#### 操作小技{#tips}
**如何将多页面板1的内容快速复制到多页面板2中？**
1. 按住Ctrl键，鼠标左键将多页面板1中待复制内容拖拽到外层容器中
2. 切换到多页面板2，鼠标左键将已经复制好的内容拖到多页面板2中即可
:::tip
当多页面板被组件占满时，选中该组件，按一次ESC键进入到多页面板的页面管理菜单，再按一次ESC键即可进入到多页面板的默认页编辑处。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/sliderpanel.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/spliderpanel"
title: "SuperPage组件-滑动面板"
---
---
order: 6
navTitle: 滑动面板
---
# SuperPage组件-滑动面板
滑动面板组件与[多页面板](./panelbook.md)相似，用于在同一页面切换展示不同的面板页面。多页面板需要和选项卡配合切换页面，滑动面板自带轮播效果，可以使用不同的方式自动轮播切换页面内容。如下示例：
示例地址：[滑动面板](https://demo.succbi.com/v5/ap.app?id=%E6%BB%91%E5%8A%A8%E9%9D%A2%E6%9D%BF)
## 使用滑动面板组件{#how-to-use}
滑动面板的使用方法与[多页面板](./panelbook.md)相似，需要在各页面添加相应的内容。不同之处在于：滑动面板提供了切换页面的功能，不需要额外使用别的组件进行页面切换。滑动面板不仅支持对固定的内容进行展示，还支持浮动展示数据，以下介绍**滑动面板**两种不同的使用方法。
### 展示静态数据{#static}
滑动面板展示的内容可以是固定不变的，使用时需要添加多个页面，在每个页面中添加需要展示的内容即可。以在各页面中展示固定的图片为例，具体步骤如下：
1. **设置静态展示内容**：在**滑动面板**>**来源**中选择**静态**
2. **设置面板内容**：滑动面板默认提供了一个页面，根据需要在左上角的编辑菜单下拉列表中选择**添加**页面。并在**组件区**>**常用**中将**图片**组件拖入到各页面，并为其选择图片。**图片**组件的具体使用方法可参考[图片](../common/image.md)
### 展示数据模型中的数据{#table}
滑动面板展示的内容也可以是动态的，即模型表中有多少行数据，滑动面板就能够浮动出多少内容，使用时仅需要在一个页面中设置引用字段，滑动面板将根据模型表自动浮动出数据，具体的设置方法与[浮动面板](./floatpanel.md)类似。以在滑动面板中展示模型表中的图片内容为例，操作步骤如下：
1. **设置动态展示内容**：在**滑动面板**>**来源**中选择**数据表**，选择模型表“附件表\_图片墙”
2. **设置面板内容**：在滑动面板提供的默认页中添加[图片](../common/image.md)组件和[文本](../common/text.md)组件
1. **图片**：设置**图片来源**为数据表，**图片字段**选择与**滑动面板**同一模型表下用于存储图片信息的字段，即选择“附件表\_图片墙”下的“存储路径”字段，随后对图片的样式进行设置
2. **文本**：引用与**滑动面板**同一模型表下的字段,如引用“附件表\_图片墙”下的“附件名称”字段，随后对文本样式进行设置
:::tip
对滑动面板进行设置时，若选中的是滑动面板中的页面，需按一次esc返回至滑动面板管理界面
:::
## 属性介绍{#property}
属性中提供了页面的显示方式和动画效果的设置。
### 显示方式{#display}
滑动面板可以设置各页面的显示方式，以呈现不同的页面展示效果。在**滑动面板**>**内部布局**>**显示方式**中设置，可选项有：
- **幻灯片**：面板页面滑动切换页面，类似幻灯片的播放方式。默认显示方式为幻灯片
- **突出中间**：同时展示多个页面，最多为3个，且中间的页面最大，两旁的页面较小。选择后滑动面板组件自动调整各页面之间的布局
- **指定个数**：同时展示指定个数的页面，播放时滑动指定个数的面板页面。选择后滑动面板组件自动调整各页面之间的布局
### 播放属性设置{#play}
滑动面板可以设置播放的滑动效果以及自动轮播。在**滑动面板**>**高级**中提供了动画和自动播放的设置
- **动画**：设置切换面板是否需要滑入的动画效果
- 持续时间：在**动画**属性中勾选**滑入**后，设置滑动过程中所用的时间
- **自动播放**：设置是否自动切换到下一个面板页面。勾选后提供如下属性设置：
- 停顿：每个页面在自动播放时停留的时间
- 循环：设置是否循环轮播面板页面，提供了三个选项：
- 循环：所有页面播放完后重新播放
- 停留在结束：最后一个面板页面播放完成后，停留在该页面
- 停留在开始：最后一个面板页面播放完成后，回到第一个面板页面并停留在该页面
### 面板页面管理{#manage}
在滑动面板页面管理菜单中可以添加、删除、移动和复制面板页面。除不能快捷重命名页面名称外，其他功能操作与[多页面板](./panelbook.md)相似。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/floatpanel.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/floatpanel"
title: "浮动面板"
---
---
order: 7
---
# 浮动面板
浮动面板可以根据数据源行数浮动出多个面板，浮动出的面板功能和[面板](superpage/component/panel)一致，如下图：
示例地址：[浮动面板](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%B5%AE%E5%8A%A8%E9%9D%A2%E6%9D%BF)
## 使用浮动面板组件{#use}
浮动面板是根据数据源中数据条数浮动出多个子面板，再在子面板中拖入组件进行使用。以显示企业名称为例说明，如下是操作步骤：
1. **使用浮动面板组件**：在**组件区**>**布局**中，将**浮动面板**拖入到画布中
2. **浮动区域的取数**：选中浮动区域，在**浮动面板**>**数据**中选择【企业基本信息】，该下拉选项为数据源列表，数据源的引用可参考[引入数据](../../design/datasourse.md)
3. **子面板设置**：以文本组件为例，选中子面板，将文本组件拖入到浮动面板的子面板中，在**文本**>**内容**中双击引用【企业名称】
通过以上3个步骤即可实现浮动展示各公司名称。
## 属性介绍{#attribute}
### 组成部分{#component}
浮动面板是根据数据源数据条数浮动出多个子面板，包括：
- 子面板：子面板中可以拖入组件进行展示。子面板的数量由所选数据源的数据条数而定。子面板的功能与面板功能一致，具体可参考[面板](superpage/component/panel)
- 浮动区域：浮动区域就是浮动面板容器，用于浮动子面板的容器组件。浮动区域的内部布局可参考[布局](../../design/layout.md)
## 常见问题{#faq}
### 如何控制浮动出的子面板个数？{#how}
在数据源中添加过滤条件，控制浮动出的数据量，以此来控制子面板的显示数量
### 子面板布局技巧{#skill}
浮动面板中的组件布局可以参考[面板](superpage/component/panel)进行布局
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/splitline.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/splitline"
title: "SuperPage组件-分割条"
---
---
order: 10
navTitle: 分割条
---
# SuperPage组件-分割条
分割条是用于分割页面布局的组件，例如上下布局的页面，可以使用分割条分割成上下布局，可以拖拽分割条改变上下布局的大小，也可以折叠收起布局中的内容。效果如下所示：
示例地址：[分割条](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%86%E5%89%B2%E6%9D%A1)
## 使用分割条组件{#use}
分割条根据分割上下、左右的布局可以衍生多种其他布局，比如左-右上-右下、左上-左下-右等。以左-右上-右下布局为例，如下是操作步骤：
1. **分割左右布局**：在**组件区**>**布局**中将**竖直双向箭头**的**分割条**组件拖入面板中，放置于左侧面板与右侧面板中间
2. **分割上下布局**：拖入**水平双向箭头**的**分割条**组件，放置于右侧上下面板中间，可拖动分割条
:::tip
分割条较细时，无法选中或者不能右键进行删除，可点击左上角**文件**>**显示/隐藏组件大纲**，在弹出的组件树中选择对应分割条组件进行操作即可
:::
## 属性介绍{#attribute}
### 拖动和折叠设置{#drag-fold}
分割条可设置拖动和展开折叠两种操作属性，效果可查看文档开头效果图。在**属性栏**>**分割条**下勾选**可拖动**与**可展开折叠**属性即可：
**拖动**
在查看界面可以拖动分割条快速调整布局大小，勾选**可拖动**属性即可，默认被勾选。当勾选该属性时，鼠标移至分割条上，会出现可拖动的图标，即可进行左右或者上下拖动改变布局大小。
**展开折叠**
对分割条分割的组件进行折叠和展开，选择性查看内容，勾选**可展开折叠**属性即可，默认不勾选。当勾选该属性后，会展开三个相关属性设置：
- 折叠方向：设置折叠的方向，且只对该方向上的组件折叠与展开。
- 竖直分割条：可选左侧或右侧，默认折叠左侧组件
- 水平分割条：可选上方或下方，默认折叠上方组件
- 默认折叠：属性勾选后，组件初始为折叠状态
- 显示折叠/展开图标：属性勾选后，折叠/展开图标总是显示；当不勾选时，只有鼠标移至分割条才会显示该图标
### 两边间距{#space}
两边边距，即分割条与分隔开的组件的两边距离。在**属性栏**>**样式**>**两边间距**中进行设置：
### 线条{#line}
分割条的线条效果可以自定义，提供了线条虚实线、颜色和粗细设置。在**属性栏**>**样式**>**线条**中进行设置：
## 应用场景{#scene}
### 折叠/展开条件{#condition}
根据实际情况可分割不同布局，清晰展示业务需求，比如展示默认条件下的数据，仅在需要切换条件时才显示可选条件。使用分割条分割左右布局，左侧为选择条件，右侧为列表数据，默认折叠左侧条件即可：
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/layout/divider.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/divider"
title: "SuperPage组件-分割线"
---
---
order: 11
navTitle: 分割线
---
# SuperPage组件-分割线
分割线是用于分割页面布局的组件，类似[分割条](./splitline.md)组件。与分割条的区别是，分割线适用于上下布局的页面且带有标题，可以折叠收起与分割线同级的组件。如下是在段落之间设置分割线且能折叠的效果：
示例地址：[分割线](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%86%E5%89%B2%E7%BA%BF)
## 使用分割线组件{#use}
分割线用于分割上下布局，可为下方组件设置标题以及折叠下方组件，只需将分割线拖入到需要被折叠组件的上方使用即可，具体操作步骤如下所示：
1. **使用分割线组件：** 在**组件区**>**布局**中将**分割线**组件拖入到画布中
2. **设置分割线标题**：在**属性栏**>**分割线**>**标题**中设置即可，例如`SuccBI`
3. **设置分割线样式：** 在**属性栏**>**样式**中可设置分割线的风格，比如设置居中分割线
## 属性介绍{#attribute}
### 标题{#title}
设置分割线的标题内容，也可以为标题设置图标前缀：
- 标题内容：在**属性栏**>**分割线**>**标题**中设置即可
- 图标前缀：在**属性栏**>**样式**>**图标**中设置即可，也可设置图标样式
### 展开折叠{#fold}
对分割线下方到下一个分割线之前的同级组件进行折叠或展开，当内容较多可进行折叠，以便查看其他内容。
在**属性栏**>**分割线**下勾选**可展开折叠**属性即可，默认勾选，当勾选该属性后可对下方属性进行设置：
- 默认折叠：属性勾选后，分割线下方同级组件初始为折叠状态
- 折叠/展开图标：在**属性栏**>**样式**>**折叠/展开图标**中可对图标显示位置与颜色进行设置
- 左侧显示：将折叠/展开图标显示在最左侧，包括图标前缀的左侧，不勾选时默认显示在右侧
- 颜色：设置折叠/展开图标的颜色
### 连接线{#connector}
连接线即分割线中的线条，用于修饰分割效果，可设置线条样式与线条位置。在**属性栏**>**样式**>**连接线**中设置即可：
- 线条：设置分割线的线条虚实线、颜色与粗细
- 线条位置：设置分割线相对于标题的位置，可设置居上、居中、居下
## 应用场景{#scene}
### 折叠收起过滤选项{#filter-option}
选项较多时，可使用分割线对其进行分类隔开，分别设置标题，且对选项较多类别可设置默认折叠，方便查看其他类别选项。如企业类型和所属行业类别选项较多，可设置默认折叠：
示例地址：[折叠收起过滤选项](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%86%E5%89%B2%E7%BA%BF)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/navigation/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/navigation"
title: "导航组件"
---
---
order: 3
navTitle: 导航
---
# 导航组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/navigation/steppers.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/steppers"
title: "SuperPage组件-步骤条"
---
---
order: 1
navTitle: 步骤条
---
# SuperPage组件-步骤条
步骤条是引导用户按照流程完成任务的分步导航条，可根据实际应用场景设定步骤。步骤条组件可以配合其他组件及交互一起使用，实现达到流程每进行一步时，步骤条状态也随之变化的效果：
示例地址：[步骤条](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%AD%A5%E9%AA%A4%E6%9D%A1)
## 使用步骤条组件{#use}
步骤条组件可以根据需求设置多个步骤选项，并结合[按钮](../common/button.md)组件、[多页面板](../layout/panelbook.md)组件，及[改变组件属性](../../design/action/README.md)交互、[切换多页面板](../../design/action/README.md)交互一起使用。
实现思路：
1. 完成[多页面板](../layout/panelbook.md)中的内容制作和按钮
2. 设置步骤条组件内容
3. 分别给多页面板中的按钮添加[改变组件属性](../../design/action/README.md)交互、[切换多页面板](../../design/action/README.md)交互实现步骤条的状态动态进行变化，如点击下一步时，步骤条进行到下一个步骤并切换多页面板
具体操作步骤如下：
1. 设置步骤条子项：在**属性栏**>**组件**>**子项设置**，设置子项属性，新添加的步骤条组件默认会有三个子项`步骤1`、`步骤2`、`步骤3`
2. 下拉选择默认选项为`步骤2`，也可通过[表达式](../../../../exp/README.md)获取
3. 在多页面板的第1页添加**下一步**按钮，设置按钮的交互：
- 设置组件属性：**选择组件**->`步骤条1`，**属性名**->`value`，**属性值**->`步骤2`
- 切换多页面板：**目标对象**->`多页面板1`，**目标面板**->`下一页`
4. 多页面板中其他页面中的**上一页**及**下一页**的按钮交互中，只需修改对应的**设置组件属性->属性值**，**切换多页面板->目标面板**
## 属性介绍{#attribute}
### 子项设置{#subitem}
**子项列表设置**
在设置子项对话框的左侧，可以设置子项列表。步骤条默认包含3个子项，内容分别为`步骤1`、`步骤2`、`步骤3`，可自定义修改或删除，点击添加可添加新的子项。点击添加默认在一级子项尾部添加新的子项，名称默认为步骤+数字。子项列表具体设置如下所示：
- 添加：点击添加按钮可添加新的选项
- 搜索：点击搜索按钮可对选项内容进行搜索
- 复制：点击复制按钮可复制选项，属性会保持一致，系统会自动通过ID加以区分
- 删除：点击删除按钮即可删除当前选项
- 移动：选中子项拖动即可移动子项的顺序
**子项选项设置**
选中某个子项，在设置子项对话框的右侧，可以设置该子项的步骤内容和交互。具体属性内容如下：
- 内容：即步骤条上显示的子项标题
- 描述：对该步骤进行补充说明的描述性内容，可以为空
- 显示：设置该步骤在满足一定条件时是否显示，可使用[表达式](../../../../exp/README.md)，如当登录人员下拉框的值为管理员时不显示步骤3，设置步骤3的显示条件表达式为`[登录人员].[值]!="admin"`
- 交互：点击对应步骤可触发的交互动作，如打开链接、刷新数据等，点击**添加动作并**设置对应属性即可，可参考文档[交互](../../design/action/README.md)。
### 步骤条{#stepbar}
在**属性栏**>**样式**>**步骤条**中可设置整个步骤条组件的属性和样式。
#### 排列
设置步骤条的布局方式，有3种布局方式：
- 横向：默认为横向布局，当为横向布局时，可设置步骤条文字的**对齐**方式
- 对齐：**左对齐**或者**居中对齐**
- 纵向：可设置为纵向布局，即步骤条的进度走向为从上至下
- 箭头：即步骤形状为箭头形，当布局为箭头时，可勾选**是否显示最后一个箭头**
- **是否显示最后一个箭头**：默认勾选，且可设置箭头的**颜色**及**宽度**，宽度的单位为px
| 横向 | 纵向 | 箭头 |
| --- | --- | --- |
||||
#### 状态样式
用于标注步骤条的特殊值，或者设置鼠标在步骤条上进行操作时，步骤条的状态样式，主要有以下几种类型：
- 突出显示：设置当步骤条的值为某个特殊值时，选项的显示样式，参考文档[突出显示](../../design/action/README.md)
- 步骤条状态样式：当鼠标**悬停**、**聚焦**时步骤条及选项的样式效果，参考文档[步骤条状态样式](../../design/style/README.md)
### 步骤属性{#step}
在**属性栏**>**样式**>**步骤**可设置步骤条中的步骤子项的字体、步骤线、背景等样式。
#### 步骤线
即每个步骤间相连的线条，可设置步骤线的线型、颜色、宽度及步骤线位置。
**步骤线位置**：根据数值调整步骤线位置，即步骤线与步骤条组件顶部的距离，数值不能小于0，单位为px。0默认为居中位置，1为最顶端的位置
### 数字样式{#number}
即步骤条中标记当前是第几步的数字标记，显示在步骤的标题前，在**属性栏**>**样式**>**数字**可设置数字的是否显示，及字体、背景、宽高等样式。
- **显示**：设置步骤数字的显示隐藏，当显示数字时，可勾选**步骤完成后显示“√”**
- **宽高**：设置数字位置的宽度及高度，支持自定义宽高，输入大于0的数字即可，单位为px
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/navigation/tabbar.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/tabbar"
title: "SuperPage组件-标签页"
---
---
order: 2
navTitle: 标签页
---
# SuperPage组件-标签页
标签页组件可以根据需求新增多个标签选项，可以结合多页面板使用，通过切换标签选项控制切换多页面板页面的显示：
示例地址：[标签页](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%87%E7%AD%BE%E9%A1%B5)
## 使用标签页组件{#use}
标签页组件可以根据需求新增多个标签选项，可以结合多页面板使用，如下是操作步骤：
1. **设置标签页选项**：在**属性栏**>**标签页**>**编辑选项**，点击**添加**分别添加4条选项，并设置**内容**信息
2. 下拉选择**默认选项**为**基本信息**，也可通过[表达式](../../../../exp/README.md)获取
3. **添加交互**：**属性栏**>**交互**>**切换多页面板**，多页面板的制作可参考文档[多页面板](../layout/panelbook.md)
1. 目标对象：**多页面板1**
2. 目标面板：**事件源序号**
## 属性介绍{#attribute}
### 选项设置{#option-setting}
点击**编辑选项**可进行选项设置，编辑选项对话框分为3部分：选项、样式、交互。
**选项**
定义标签页中各个选项值。标签页默认包含3个选项，**内容**分别为`选项1`、`选项2`、`选项3`，可自定义修改或删除，点击**添加**可添加新的选项。选项包含以下几个属性：
- 内容：即标签页上显示的选项标题，可以重复
- 数字：可在内容上添加数字进行标记，可使用[表达式](../../../../exp/README.md)进行取数，数字会显示在选项内容的右上角，示例见[数字提示](#数字提示)
- ID：用区分不同的选项，可为空，不可重复，当为空时系统会自动增加标识
- 显示：设置该选项在满足一定条件时是否显示，可使用[表达式](../../../../exp/README.md)
- 可用条件：设置该选项满足一定条件时点击可发生交互，可使用[表达式](../../../../exp/README.md)
**选项管理**
- 添加：点击添加按钮可添加新的选项
- 搜索：点击搜索按钮可对选项内容进行搜索
- 复制：点击复制按钮可复制选项，属性会保持一致，系统会自动通过ID加以区分
- 删除：点击删除按钮即可删除当前选项
**样式**
在样式下可分别设置**选项**和**数字**的字体、背景等。在编辑选项对话框中的**样式**设置优先级高于**属性栏**中的样式设置。
当修改了样式的相关属性，**重置**按钮会高亮显示，点击**重置**可恢复至默认的样式设置。
**交互**
点击对应选项可触发的交互动作，如打开链接、刷新数据等，点击**添加动作并**设置对应属性即可，可参考文档[交互](../../design/action/README.md)。
### 标签页属性{#tab}
在**属性栏**>**样式**>**标签页**中可设置整个标签页组件的属性和样式。
#### 切换选中动画
勾选**启用**后，可以设置动画属性，即选中时标签页选项下线条标记的样式：
- 选中线条颜色：设置线条的颜色，可设置为纯色和渐变色
- 选中线条宽度：设置线条占其对应选项的占比，100%即为线条与选项等宽
- 选中线条高度：设置线条的高度，最小为1，最大为10
#### 方向
可设置标签页的选项布局为**纵向**，在**属性栏**>**样式**>**标签页**>**高级**里设置，默认为**横向**。
#### 状态样式
用于标注标签页的特殊值，或者设置鼠标在标签页上进行操作时，标签页的状态样式，主要有以下几种类型：
- 突出显示：设置当标签页的值为某个特殊值时，选项的显示样式，参考文档[突出显示]()
- 标签页状态样式：当鼠标**悬停**、**选中**或**按下**时标签页及选项的样式效果，参考文档[标签页状态样式](../../design/style/README.md)
### 选项属性{#option-attribute}
在**属性栏**>**样式**>**选项**可设置标签页中的选项字体、排列大小、对齐方式及图标等样式。
#### 排列
设置选项排列时的宽度、高度及对齐方式等
- **宽度**：可对**最大宽度**和**最小宽度**进行设置，对标签页组件的宽度进行调整，可选择为以下三种方式：
- 自适应：文本自适应容器的大小，默认为**自适应**
- 像素：输入具体像素值的时候，在任何屏幕大小下组件大小都是固定的
- 百分比：百分比的时候，组件大小会根据屏幕大小变化
- **高度**：高度的设置可参考宽度设置
- **对齐**：设置选项在标签页中的对齐方式，包含**居左对齐**、**居中对齐**、**居右对齐**、**两端对齐**、**均匀分散**
- **两边间距**：设置选项值与标签页两端的间距，输入大于0的具体数值即可，不可大于宽度的一半
### 数字属性{#number}
当在[选项](#选项设置)中设置了数字，可在**属性栏**>**样式**>**数字**中设置数字提示的字体、背景、边框等样式。
## 应用场景{#scene}
通过对标签页的相关属性设置，可实现不同的效果及交互满足不同的应用场景。
### 数字提示{#numtips}
显示选项的提示数字，可位于文字右边或选项右上角，可用于标记某选项。
示例地址：[标签页-数字提示](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%87%E7%AD%BE%E9%A1%B5)
### 动态标签{#dynamic-label}
可设置动态显示隐藏某些选项。通过[下拉框组件]()与标签页的**选项**>**显示条件**属性即可实现，如当登录人员下拉框的值为管理员时显示高级信息，设置选项高级信息的显示条件表达式为`[登录人员].[值]=="admin"`：
示例地址：[标签页-动态标签](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%87%E7%AD%BE%E9%A1%B5)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/data/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/data"
title: "数据组件"
---
---
order: 4
navTitle: 数据
---
# 数据组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/data/list.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/list"
title: "SuperPage组件-列表"
---
---
order: 1
navTitle: 列表
---
# SuperPage组件-列表
列表组件常用于展示多行明细数据，配合输入组件（如下拉框、日期框）可实现动态查询过滤数据。列表组件还支持点击列头排序、分页、[数据条](../../../../report/design/style/condition-style.md#databar)、[突出显示](../../../../report/design/style/condition-style.md#highlight)、[色阶](../../../../report/design/style/condition-style.md#color-scale)等功能，通过设置交互还可以实现数据的修改和导出。
示例：[列表组件](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
## 使用列表组件{#start}
使用列表组件主要进行两个设置：
1. 绑定要显示的数据集
2. 设置要显示的列
下面以一个显示企业基本信息的列表为例，介绍具体的操作步骤：
1. **拖入列表组件**：在**组件区**>**数据**分组下将列表组件拖入到画布中
2. **设置列表数据**：在**属性栏**>**列表**>**数据**中引用`企业基本信息`，该信息是在[数据](../../design/datasourse.md)中引入的外部数据模型
3. **设置列的内容、样式和交互**：在**属性栏**>**列表**>**数据**中，点击**设置列**，删除企业名称重复的`企业内部序号`列，并在`序号`列的**样式**中设置标题行及数据行的**对齐**属性为居中对齐
4. **设置列表样式**：可按需设置
- 设置隔行换色：在**属性栏**>**样式**>**数据行**中可启用数据行**隔行换色**
- 设置冻结列：在**属性栏**>**列表**>**高级**中可为列表添加**冻结列**，在**属性栏**>**样式**>**列表**中可设置**冻结线**样式
- 添加条件样式：在**属性栏**>**样式**>**列表**中可为列表添加**条件样式**
## 列表设置{#list}
在列表的**属性栏**中可以分别进行属性及样式的设置。
### 列表分页设置{#page}
列表组件在**属性栏**>**列表**下内置**分页**属性，可在[数据模型](../../design/datasourse.md)中调整分页行数，能够满足分页的基本需求：
- **对齐**：分页栏相对于列表位置的对齐效果，可选项：居中对齐、居左对齐、居右对齐、两端对齐（当显示了总行数时，分页栏和总行数是两端对齐效果 ）
- **页码样式**：可设置分页栏的页码样式，包括：无方框、方框、实心方框
- **显示总行数**：启用后会在分页栏左侧显示总行数
如需实现更灵活的分页效果，如动态调整分页行数、跳转、自定义页码样式等，可使用[分页导航组件](./pagenavigation.md)。
### 允许用户调整列宽{#width}
在**属性栏**>**列表**>**高级**中可设置**允许用户调整列宽**属性，支持在查看界面拖动列宽。
### 冻结列设置{#frozen}
在**属性栏**>**列表**>**高级**下启用**冻结列**后，可以在**属性栏**>**样式**>**列表**中设置冻结线的样式。冻结列默认冻结标题行，同时可设置冻结的列数：
- **列数**：输入项为数字且小于列表总列数，默认为1，即冻结第一列
### 列表排序设置{#sort}
列表本身不具有过滤数据以及排序的功能，如果需要对列表数据进行排序，根据数据引入方式的不同有以下两种途径：
1. 数据模型：在模型的排序属性中添加一个或多个排序字段并指定排序方式，参考[数据模型中指定排序字段](../../../../data-gov/model/model-settings.md#sort-fields)
2. 数据集：在左侧的排序属性中添加一个或多个排序字段并指定排序方式，并且在数据集中指定排序字段的优先级高于数据模型中指定排序字段，参考[数据集中指定排序字段](../../../../data-viz/dash/design/datasource.md#creat-dataset)，
::: tip 列头排序
列表也可以通过点击列头进行排序，参考文档：[列的交互设置](#line-setting)
:::
## 列设置{#line}
在**属性栏**>**列表**中设置了**数据属性**后，会出现**设置列**的选项。点击**设置列**，在弹出的对话框中可以进行列的设置，包括：显示哪些列、列的字段、列的样式等。
### 设置显示哪些列{#manifest}
列表默认会自动显示所有绑定数据集中的字段，通过调整**设置列**对话框中的列表条目、字段属性，可以设置列表组件显示哪些列。将鼠标悬停在列字段上，点击右侧图标可对列字段进行便捷的克隆及删除操作，同时支持列字段的添加、移动、显示条件，具体如下：
- **添加**：添加新的字段或选中字段的下级按钮
- 添加按钮：可添加多个按钮，常用于交互操作，例如修改数据、打开链接等
- **移动**：在界面上可通过上下拖拽字段的方式进行顺序调整
- **显示条件**：仅在**显示**属性中选择**显示条件**时出现，可输入[表达式](../../../../exp/README.md)
### 列的样式设置{#line-style}
在列的样式设置界面，可对列的字体样式、显示格式、单元格背景、列宽、图片前后缀等进行设置：
- **标题行-列宽**：列的标题和数据长度都会影响列宽，故提供了三种模式
- 固定：可输入固定值，常用于列长度固定的场景，例如：电话号码、身份证号等
- 自适应：列数据长短不一时，可设置宽度范围，如公司名称、地址等。在适应不同屏幕大小时，也可以设置不同空间下，相对于列表可占用的剩余宽度放大缩小的倍数，但无法超过宽度范围
- 自定义：可同时设置固定与自适应的所有列宽属性，在固定长度的基础上可根据界面长度自动撑大宽度，常用于操作列（即包含操作按钮）
- **条件样式**：可以在右侧**属性栏-样式-条件样式**下，给列添加**数据条**、**突出显示**等条件样式，详细介绍见[SPG的条件样式](../../design/style/condition-style.md#condition-style)
### 动态选择显示的列{#dynamic-line}
列表组件支持在查看列表数据的时候，可由用户动态选择显示哪些列字段。使用**属性栏**>**列表**>**高级**下的**动态列**属性，与[下拉框组件](../input/combobox.md)搭配使用即可实现。具体可参考[动态显示列表](#动态显示列表)。
### 根据条件显示隐藏列{#condition}
当列表的某些列需要根据数据情况、用户身份信息等来确定是否显示，而不由用户选择决定时，可在**设置列**>**列**>**显示条件**中通过表达式实现。
### 列的交互设置{#line-setting}
列设置中内置了多样化的交互属性，可实现数据的排序、勾选、链接等效果：
- **点击列头排序**：启用后可通过点击列头的方式，对数据进行排序
- **显示勾选框**：启用后会在数据行显示勾选框，常用于交互式列表
- **在标题行上显示全选框**：仅在启用**显示勾选框时**出现，启用后会在列的标题行显示全选框
- **交互事件**：可在列上增加交互事件，包括：[打开链接]()、刷新数据、[设置参数值]()等
## 行设置{#row}
适当调整行属性，可以让列表的展示效果更加舒适美观，如隔行换色、行高、内边距等。
### 标题行样式设置{#title-row}
在**属性栏**>**样式**中提供了**标题行**样式设置，包括：字体、背景、内边距等属性：
- **高度**：设置标题行的行高，详细可参考[行的高度设置](#行的高度设置)
- **隐藏标题行**：当标题行不需要显示时，勾选即可隐藏标题行
### 数据行样式设置{#data-row}
**属性栏**>**样式**中提供了**数据行**的样式设置，包括字体、隔行换色、背景等属性：
- **隔行换色**：勾选即可实现隔行换色的效果，详见[隔行换色设置](#隔行换色设置)
- **高度**：可设置数据行的行高，具体可参考[行的高度设置](#行的高度设置)
::: tip 按钮设置
数据行同样支持设置[按钮](../common/button.md)的对齐方式和字体属性样式，主要包含以下两个方面：
1. 选中按钮所在列，可以在**属性栏**>**样式**>**数据行**>**对齐**中通过对齐方式来调整按钮位置
2. 选中按钮，可以在**属性栏**>**样式**中调整按钮标题样式
:::
### 行的高度设置{#row-height}
列表在**属性栏**>**样式**>**标题行**下提供了高度的相关设置：
- **高度**：行的高度，可输入固定值
- **最大高度**：启用自动撑大行高时，可撑大的最大高度值
- **自动撑大行高**：启用后，可由文字自动撑大行高
以上三个属性的设置规则如下：
- 在未启用**自动撑大行高**时，行高等于**高度**属性设置的值
- 启用**自动撑大行高**后，行高的范围大于等于**高度**设置的值，小于等于**最大高度**设置的值
### 隔行换色设置{#color}
可设置偶数行的背景色，勾选**数据行**的**隔行换色**属性即可启用。该属性提供了色调板，可进行纯色、渐变色的填充，同时支持设置颜色的透明度。
## 应用场景{#scenarios}
列表不仅可以实现明细数据的展示，还可以应用于更多的场景，如：[交互式列表](#交互式列表)、[动态显示列表](#动态显示列表)等。
### 自由查询列表{#query}
在列表数据展示的基础上，如果希望能够自由调整筛选字段对列表数据进行过滤，可添加[字段过滤组件](../input/fieldsfilter.md)并引用同一个数据模型来实现自由查询效果。以展示企业列表的自由查询为例，可增加以下步骤：
1. **拖入字段过滤组件**：在**组件区**>**输入**分组下将[字段过滤组件](../input/fieldsfilter.md)拖入到列表组件上方，在**属性栏**>**字段过滤**>**数据**中引用`企业基本信息`即可实现过滤效果。
2. **设置默认的筛选字段**：选中字段过滤组件，点击**设置列**，在`企业名称`、`经营状态`、`企业类型`的**字段**属性中，勾选**默认显示**属性，并设置`企业名称`的**操作符**属性为`包含`
示例：[列表-数据检索](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
### 交互式列表{#interactive}
利用列表的交互功能，可以实现对数据行进行编辑、删除、导出，如使用交互式列表对设备采购信息进行维护：
示例：[列表-增删改查](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%95%B0%E6%8D%AE%E9%9B%86%E4%BA%A4%E4%BA%92)
**实现思路**
基于[列的交互设置](#列的交互设置)，搭配[按钮组件](../common/button.md)及[对话框组件]()，可实现以下效果：
- **数据编辑**：数据编辑的实现分为以下三个部分
- 实现点击弹出效果：在列上添加编辑按钮，在画布中拖入对话框组件，为按钮添加**交互事件**为`显示对话框/悬浮面板`，并设置**对话框组件**属性为刚刚拖入的对话框即可
- 实现数据填写效果：在对话框中使用输入组件设计好表单，保证与列表的列字段一一对应
- 实现数据提交效果：在每个输入组件的**数据**属性中一一绑定数据模型的对应字段，并设置默认值为该字段，如`[资产信息维护].[资产编码]`。在对话框中加入提交按钮，并为提交按钮添加**交互事件**为`提交表单`即可
- **数据删除**：通过在列按钮上添加`删除数据`的**交互事件**即可实现，需要在**数据**属性中与列表引用同一个数据模型，可在**数据范围**属性中选择删除的数据范围
- **数据导出**：为按钮添加`导出数据`的**交互事件**，并在**数据组件**属性中选择列表组件即可
### 动态显示列表{#dynamic-list}
使用[动态列](#动态列)属性，搭配[下拉框组件](../input/combobox.md)可以实现通过自由选择字段的方式，动态显示列数据的效果。
示例：[列表-动态选择列](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
以动态显示企业的属性列为例，实现步骤如下：
1. 设置下拉选项：从**组件区**>**输入**分组中拖入[下拉框组件](../input/combobox.md)，将**标题**命名为`动态输入项`，设置**可选项**属性为`企业基本信息`，并设置以下信息：
- **属性**设置为`字段名称`
- 勾选**允许多选**及**显示已选个数**属性
- 在**下拉框**>**数据**>**默认值**中勾选默认显示的字段
2. 在列表的**属性栏**>**列表**>**数据**>**设置列**中，将需要动态显示字段的**列**>**显示**属性设置为隐藏
3. 在列表的**属性栏**>**列表**>**高级**>**动态列**中输入表达式：`${[动态输入项].[值]}`
::: tip
[下拉框组件](../input/combobox.md)支持在**可选项**中设置数据模型，在制作[动态显示列表](#动态显示列表)时需要与列表组件引用同一数据模型，才可实现动态显示效果。
:::
### 单列交互列表{#single}
列表也可作为树的形式展示，实现点击选中行实时刷新数据效果，如使用单列交互列表刷新企业信息：
示例：[列表-列表交互](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
**实现思路**
列表组件支持在展示界面选中数据行，通过右侧的[文本组件](../common/text.md)可以获取选中数据行的字段值，在文本组件的**内容**属性中输入表达式`${[列表1].[选中值].[企业类型].[标题]}`即可实现交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/data/pagenavigation.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/pagenavigation"
title: "SuperPage组件-分页导航"
---
---
order: 6
navTitle: 分页导航
---
# SuperPage组件-分页导航
分页导航组件常用于多行明细数据的分页展示，支持设置[页码导航](#navigation)、[页码样式](#page)等，与[列表](./list.md)、[浮动面板](../layout/floatpanel.md)搭配可实现风格各异的分页导航效果。
示例：[分页导航组件](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%86%E9%A1%B5%E5%AF%BC%E8%88%AA)
## 使用分页导航组件{#start}
分页导航组件的工作原理是将用户选择的分页选项，先作用到对应的数据集对象上，数据集完成分页查询后，再自动通知界面上的其他组件刷新数据，所以分页导航组件只需要绑定相应的数据集即可实现与其他组件的数据联动。使用分页导航组件主要进行二个设置：
1. 绑定分页的数据
2. 启用所需的导航功能
分页导航组件可与[列表组件](./list.md)、[浮动面板组件](../layout/floatpanel.md)等搭配使用，以分页显示企业的基本信息为例，操作步骤如下：
1. **拖入分页导航组件**：在**组件区**>**数据**分组下将分页导航组件拖入到画布中
2. **绑定分页数据**：在**属性栏**>**组件**>**数据**中引用`企业基本信息`，该数据为列表引用的数据模型
3. **设置导航功能**：在**属性栏**>**组件**>**高级**中，按需对**显示页码**、**允许跳转**等属性进行取消勾选
4. **设置导航栏样式**：在**属性栏**>**样式**中，按需对**页码**、**按钮**等进行样式调整
::: tip
部分组件内置了分页功能（如列表组件），但是内置的分页栏样式和位置比较固化，如果使用分页导航组件来实现分页效果，可以将内置的分页功能禁用。
:::
## 属性介绍{#properties}
分页导航组件在**属性栏**>**组件**下提供了**数据**、**位置大小**、**显示页码**等导航功能设置，在**属性栏**>**样式**下提供了**字体**、**背景**、**对齐**等导航栏样式设置。
### 页码导航设置{#navigation}
分页导航组件支持多种外观设置，包括是否显示页码、是否显示总行数等，在**属性栏**>**组件**>**高级**中可以设置：
- **显示页码**：以按钮的形式，按照页码顺序平铺在导航栏，可通过点击页码来翻页，启用后可进行[页码样式设置](#page)及[按钮样式设置](#button)
- **允许跳转**：仅在显示页码时生效，可手工输入页码数，通过点击跳转按钮进行页数跳转
- **允许选择每页行数**：用户可以选择每页显示的行数，默认为100行
- **显示总行数**：在导航栏左侧显示总行数
- **显示首页和尾页**：在页码左右两侧，以按钮的形式分别显示首页和尾页
以上设置默认都是启用的，可根据实际需要取消勾选。当页码导航设置均禁用时，分页导航组件会提供默认的导航栏，可以进行翻页及跳转。
### 页码样式设置{#page}
在**属性栏**>**样式**>**页码**中提供了页码样式的设置，包括页码的样式类型、高亮效果、填充效果等：
- **页码样式**：提供了方框、方块、数字三种显示模式，不同选项的样式设置有一定区别
- **方块**：可设置边框的默认颜色、高亮色、圆角，也可以设置页码的字体大小、默认颜色、高亮色、悬浮高亮色、填充色、填充高亮色，还可以选择是否启用页码之间的间隔
- **方框**：可设置边框的高亮色、圆角，也可以设置页码的字体大小、默认颜色、高亮色、悬浮高亮色、填充高亮色
- **数字**：默认无边框及填充，可设置页码的字体大小、默认颜色、高亮色、悬浮高亮色
### 按钮样式设置{#button}
分页导航中的按钮包括：首页、尾页、上一页和下一页，可以设置样式。在**属性栏**>**样式**>**按钮**下提供了文字样式、符号样式两种显示模式：
- **文字样式**：按钮上显示的是文字信息
- **符号样式**：按钮上显示的是左右箭头
以上两种样式都可以对颜色、大小进行设置。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/embed"
title: "嵌入组件"
---
---
order: 5
navTitle: 嵌入
---
# 嵌入组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embedreport.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embedreport"
title: "SuperPage组件-嵌入报表/仪表板"
---
---
order: 1
navTitle: 报表/仪表板
---
# SuperPage组件-嵌入报表/仪表板
SuperPage页面中，使用嵌入报表组件，可以在SuperPage页面上显示报表结果。嵌入报表和嵌入仪表板的功能一致，本文以嵌入报表为例，介绍嵌入报表/仪表板的用法。如在SuperPage页面中嵌入报表：
示例地址：[嵌入报表](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8A%A5%E8%A1%A8)
## 使用嵌入报表{#start}
在SuperPage中，只支持嵌入已经存在的报表，可参考文档[新建报表](../../../../../getstarted/SuccBI/report/first-report.md)完成报表的制作。使用嵌入报表需要两个步骤，包括拖入报表组件、设置嵌入报表的路径和参数。具体步骤如下：
1. **拖入报表组件**：在**组件区**>**嵌入**分组下将报表组件拖入到画布中
2. **设置嵌入报表的[路径](#path)和[参数](#param)**：
- 设置嵌入报表的路径：在**属性**>**报表**>**路径**中，在下拉列表选择需要嵌入的报表
- 设置参数：在**属性**>**报表**>**路径**>**编辑参数**中，可根据需求设置参数
## 属性介绍{#properties}
通过设置嵌入报表的**路径**与**参数**，可在SuperPage页面展示不同的报表，在**属性栏**>**报表**>**路径**下设置。
### 路径{#path}
路径即需要显示的报表的绝对路径，修改路径可展示不同的报表，可设置**指定路径**或**动态路径**：
- **指定路径**：固定展示一张报表，在下拉框中选择系统已经存在的报表，系统自动填写该报表位置的路径
- **动态路径**：根据条件可动态展示多张报表中的一张，在下方输入框中写入路径条件表达式，如`${IF(条件,"/DEMO/ana/报表/分组报表/单向分组.rpt","/DEMO/ana/报表/分组报表/交叉分组.rpt")}`，右键报表点击**属性**即可复制路径
### 参数{#param}
嵌入报表时可以从SuperPage页面中传递参数到报表中展示不同的节点或者过滤数据，可参考文档[URL参考](../../../../dev/references/sys-urls.md)。点击**编辑参数**即可设置参数，可设置多个，下拉列表中会显示在报表中添加的全局参数及系统支持的报表参数，嵌入报表中支持的参数有：
- `:edit`：传递`true`可进入设计器页面
- `:filters`：过滤条件，当需要对报表中的数据按照特定的条件展示的时候，可通过设置过滤条件的方式来实现
- `:breadcrumb`：面包屑路径，用于设置是否显示面包屑路径，面包屑路径指的是钻取的元数据路径
- **自定义参数**：支持将自定义的全局参数或输入组件的值作为URL参数传递进来，如定义参数隐藏标题，**参数**为`hidetitle`，**参数值**为`true`
更多参数配置可参考文档[URL参考-报表、仪表板URL](../../../../dev/references/sys-urls.md#ana)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embeddatamodel.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embeddatamodel"
title: "SuperPage组件-嵌入数据模型"
---
---
order: 4
navTitle: 数据模型
---
# SuperPage组件-嵌入数据模型
SuperPage页面中，使用嵌入数据模型组件，就能直接在页面上查看和管理数据模型，可以嵌入[模型管理](../../../../data-gov/model/README.md)中的数据查询界面、加工流程图、字段列表界面等。如在页面中嵌入`企业名录`模型表：
示例地址：[嵌入数据模型](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%95%B0%E6%8D%AE%E6%A8%A1%E5%9E%8B)
## 使用嵌入数据模型{#start}
嵌入数据模型只支持展示已经存在的模型表，使用嵌入数据模型需要两个步骤，包括拖入数据模型组件、设置路径与参数。具体步骤如下：
1. **拖入数据模型组件：** 在**组件区**>**嵌入**分组下将数据模型组件拖入到画布中
2. **设置路径与参数：** 在**属性栏**>**数据模型**>**路径**下设置路径与编辑参数
- 设置路径：在路径属性中选择指定路径，并在下方下拉框中选择需要嵌入的数据模型表，如`企业名录`模型表，系统会自动写入该模型表的路径
- 编辑参数：点击**编辑参数**进入编辑参数对话框，设置**参数名称**与**参数值**，如需要显示数据内容，则可将参数名称设为`:viewer`，参数值设为`data`
## 属性介绍{#properties}
通过设置嵌入数据模型的路径与参数，可在SuperPage页面展示不同的模型表以及模型表不同的输出节点。在**属性栏**>**数据模型**>**路径**下设置：
### 路径{#path}
路径即需要显示的数据模型的绝对路径，修改路径可展示不同的模型表，可设置**指定路径**与**动态路径**：
- 指定路径：固定展示一张数据模型表，在下拉框中选择系统已经存在的数据模型表，系统自动填写该模型表位置的路径
- 动态路径：根据条件可动态展示多张数据模型表中的一张，在下方输入框中写入路径条件[表达式](../../../../exp/README.md)，如`${IF(条件,"/DEMO/data/tables/行业/服饰企业/fact/SAL_F_XS_DAY.tbl","/DEMO/data/tables/行业/服饰企业/fact/SAL_F_XS_MONTH.tbl")}`，右键模型表点击属性即可复制路径
### 参数{#param}
通过编辑参数的**参数名称**和**参数值**，可展示模型表不同输出节点以及不同数据内容，可设置多个参数。在编辑参数对话框中进行设置，以`:viewer`参数为例：
参数名称为`:viewer`，默认参数值为`data`，显示数据内容，还可传递以下参数值：
- `data` - 进入模型数据查询界面
- `linkages` - 显示模型的血统分析界面
- `fields` - 显示模型的字段列表界面
- `relations` - 显示模型的关联关系界面
- `dataflow` - 显示模型的加工流程图
- `hierarchy` - 显示模型的层次界面
- `settings` - 显示模型的基本设置界面
当`:viewer`传递`data`时，还可以添加更多参数配置，来显示不同的数据内容，可参考文档[URL参考-模型表URL](../../../../dev/references/sys-urls.md#模型表URL)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embedform.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embedform"
title: "SuperPage组件-嵌入CI表单"
---
---
order: 5
navTitle: CI表单
---
# SuperPage组件-嵌入CI表单
SuperPage页面中，使用嵌入CI表单组件，可以将发布的报表填报应用嵌入到SuperPage页面中进行数据填报。如在页面中嵌入`采购申请单`:
示例地址：[嵌入CI表单](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%A1%A8%E5%8D%95_1)
## 使用嵌入CI表单{#use}
嵌入CI表单只支持填报已发布的表单，若表单未发布，会在界面中给出提示。使用嵌入CI表单需要两个步骤，包括拖入数据模型组件、设置路径与参数。操作步骤参考[嵌入数据模型](./embeddatamodel.md#使用嵌入数据模型)。**嵌入表单**的差异在于可设置的[参数](#参数)不同，如需要直接显示表单填报界面，则可将参数名称设为`:newData`，参数值设为`true`。
## 属性介绍{#attribute}
### 路径{#path}
路径是用来设置嵌入表单的路径，可以引用某个表单，也可以根据条件动态设置某个表单，具体可参考[嵌入数据模型](./embeddatamodel.md#路径)。
### 参数{#param}
嵌入CI表单常用的参数如下：
- `:newData` - 进入表单填写界面，开始一个新的流程申请、或者打开编辑一个已存在的数据
- `:dataPeriod` - 显示某个数据期的数据，适用于周期填报应用
- `:orgId` - 显示某个明细数据
- `:detailId` - 显示某个明细数据
- `:sheet` - 默认显示哪张表单
- `:sheets` - 显示哪些表单，逗号分隔，不传默认显示全部
- `:hideSheets` - 隐藏哪些表单，逗号分隔，从目前可以显示的表单中剔除掉
- `:readonly` - 用只读方式显示表单
更多参数配置可参考文档[URL 参考 - 报表填报应用](../../../../dev/references/sys-urls.md#fapp)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embedsuperpage.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embedsuperpage"
title: "SuperPage组件-嵌入SuperPage"
---
---
order: 6
navTitle: SuperPage
---
# SuperPage组件-嵌入SuperPage
使用嵌入SuperPage的组件，可以在页面中嵌入其它的SuperPage页面。
## 嵌入SuperPage的适用场景{#scene}
1. 在页面中嵌入一些可复用的SuperPage（比如用户注册页面、通用列表等），减少重复工作
2. 需要填报的表单内容较长的情况下，可将长表单拆分成多个SuperPage页面，便于分开维护
例如：个人中心包含了待办事件、个人信息管理和收藏中心，每个模块都是一个单独的SuperPage页面，使用[多页面板](../layout/panelbook.md)和嵌入SuperPage组件的方式，能将多个SuperPage页面组合在同一个页面中，如下图所示：
示例地址：[嵌入SuperPage](https://demo.succbi.com/v5/DEMO/app/ap.app?:edit=true&:file=%E4%B8%AA%E4%BA%BA%E4%B8%AD%E5%BF%83.spg)
## 使用嵌入SuperPage组件{#use-embedsuperpage}
嵌入SuperPage需要两个步骤，包括拖入嵌入SuperPage组件和设置路径。具体操作步骤如下：
1. **拖入SuperPage组件**： 在**组件区**>**嵌入**分组下将SuperPage组件拖入到画布中
2. **设置路径与参数**： 在**属性栏**>**SuperPage**>**路径**下设置路径与编辑参数
- 设置路径：即需要显示的SuperPage的绝对路径，修改路径可展示不同的SuperPage，具体可参考[嵌入数据模型](./embeddatamodel.md#路径)
- 编辑参数：可以自定义参数传递到嵌入spg页面中
**路径设置**
在**属性栏**>**SuperPage**>**路径**下设置，可设置指定路径与动态路径，具体可参考[嵌入数据模型](./embeddatamodel.md#路径)。
## 提交嵌入SuperPage页面的数据{#submit}
嵌入的Superpage页面也是可以提交数据的。当页面的业务较复杂，页面涉及多个业务或多个页面切换操作时，可以考虑将页面拆分为多个SuperPage子页面，然后使用嵌入方式将这些零散页面集合在一起，可以方便后期维护。
如下图中包含了人员基本信息，职业经历和教育经历，需要切换填写后提交数据。类似这样的需求，有两种实现思路：
1. 提交按钮在嵌入SuperPage页面外：
- 集成页面添加按钮，并设置[提交表单](../../design/action/submit-data.md)交互
- 交互[提交表单](../../design/action/submit-data.md)>**范围**设置为**指定组件**，并在**提交组件**中指定待提交的嵌入SuperPage组件
2. 提交按钮在被嵌入SuperPage页面内：
- 被嵌入SuperPage页面添加按钮，并设置[提交表单](../../design/action/submit-data.md)交互
- 交互[提交表单](../../design/action/submit-data.md)>**范围**设置为**默认**即可，无需其余特殊设置
示例地址：[嵌入SuperPage提交数据](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8)
:::tip
1. 提交通常需要设置[url参数](../../../../dev/references/sys-urls.md)，最常用的是`:newData`参数设置为`TRUE`,代表此时为新增数据
2. 嵌入页面间的数据传递，如嵌入的SuperPage2需要引用SuperPage1中输入控件INPUT1的值，此时需要在SuperPage2中添加全局参数param1(参数名可自定义)，在SuperPage2中设置参数`param1=[SuperPage1].[INPUT1]`,此处需要输入**组件ID**而不是组件名称
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embedwebview.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embedwebview"
title: "SuperPage组件-嵌入网页"
---
---
order: 8
navTitle: 网页
---
# SuperPage组件-嵌入网页
SuperPage提供了嵌入网页组件（iframe），可以将系统外部页面或系统内部的[元数据文件](/dev/meta/file-exts)URL嵌入到SuperPage中展示。如在SuperPage页面中嵌入`科普中国网`：
示例地址：[嵌入网页](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E7%BD%91%E9%A1%B5)
## 嵌入系统外页面{#web}
在SuperPage中嵌入系统外的页面，只需要拖入网页组件，并设置外部网页路径。具体步骤如下：
1. **拖入网页组件**： 在**组件区**>**嵌入**分组下将网页组件拖入到画布中
2. **设置路径**：在**属性栏**>**网页**>**路径**中将网页的路径设置为`http://www.kepuchina.cn`
## 嵌入系统内元数据页面{#meta}
使用嵌入系统内元数据页面与[嵌入系统外页面](#嵌入系统外页面web)的操作相同，在**路径**中建议输入**应用绝对地址**，可通过右键查看元数据属性的方式找到路径，如：`/DEMO/app/ap.app/案例/企业信息自助查询/企业一户式.spg`。
## 网页路径设置{#url}
网页路径可以是一个URL地址，也支持输入宏，同时支持多种地址类型，具体可参考[二维码内容设置](../more/qrcode.md#内容)。嵌入内部元数据和外部页面的路径设置有所区别：
- **系统外页面**：一般为**互联网URL地址**，如果嵌入的是一个外部应用页面，传递参数时则需要了解相应的参数说明文档
- **系统内元数据页面**：与嵌入元数据的**动态路径**属性类似，具体可参考[嵌入数据模型](./embeddatamodel.md#路径)，但是在传递参数时需要将参数写在URL后，如：`/DEMO/app/ap.app/案例/企业信息自助查询/企业一户式.spg?qydm=${[企业].[企业内部序号] ? [企业].[企业内部序号] :'017231fd0731445eb85ae3cd41d52ed6'}`，更多设置可查看文档：[URL参考](../../../../dev/references/sys-urls.md)
## 嵌入网页组件与嵌入元数据组件的区别{#differ}
嵌入网页组件会嵌入一个完整的`HTML页面`（iframe），即使是系统内部的元数据文件也是以网页形式嵌入的。而嵌入元数据组件嵌入的是一个`组件`（div），如[嵌入仪表板](./embedreport.md)、[嵌入CI表单](./embedform.md)等，可以和父页面有更多交互，如无刷新的传递参数、嵌入的SuperPage页面可以和父页面同时[提交数据](../../design/submit-data.md)等。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/embedhtml.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/embedhtml"
title: "SuperPage组件-嵌入HTML"
---
---
order: 9
navTitle: HTML
---
# SuperPage组件-嵌入HTML
SuperPage提供了嵌入HTML组件，可以将来源不同的HTML嵌入到SuperPage中展示。如在SuperPage页面中嵌入一段自定义的HTML：
示例地址：[嵌入HTML](https://demo.succbi.com/v5/DEMO/app/ap.app?id=HTML)
## 使用嵌入HTML组件{#start}
使用嵌入HTML组件时，只需要在拖入HTML组件后，选择**HTML来源**并设置来源属性即可。如嵌入一段自定义的HTML，具体步骤如下：
1. **拖入HTML组件**：在**组件区**>**嵌入**分组下将HTML组件拖入到画布中
2. **设置HTML来源**：在**属性栏**>**数据**中，选择**HTML来源**为`HTML`，并点击**编辑HTML**按钮，在弹出的对话框中根据实际需求输入相应的HTML代码
## HTML来源{#source}
嵌入HTML组件的HTML来源除了可以自定义，还支持从模型数据中取字段值，以及引用已有的HTML文件，最终读取的都是一段HTML代码：
- **HTML**：默认选项，点击**编辑HTML**按钮可自定义HTML，通过在HTML中输入宏可实现与HTML的交互，如与[按钮组件](../common/button.md)搭配显示一个步进器
- **字段**：需要提前[引入数据模型](../../design/datasourse.md)，可通过指定存储HTML数据的**字段**来显示HTML页面
- **URL**：可通过[动态路径](./embeddatamodel.md#路径)的方式引用已有的HTML文件，支持输入宏及多种地址类型，如使用**应用绝对地址**：`SuperPage.app/控件/嵌入/URL嵌入HTML.html`，具体可参考[二维码内容设置](../more/qrcode.md#内容)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/gisPOIMarker.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/gispoimarker"
title: "SuperPage组件-地点标注"
---
---
order: 13
navTitle: 地点标注
---
# SuperPage组件-地点标注
SuperPage提供了GIS地图，使用地点标注组件可以在GIS上根据地址或经纬度标注出地理位置信息，并可以放大缩小查看。
示例地址：[地点标注](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%9C%B0%E7%82%B9%E6%A0%87%E6%B3%A8)
:::tip
地点标注支持多种不同的底图风格显示，可以在[系统设置-外部服务-GIS](../../../../sys-settings/more/remote-services/gis.md)中自定义底图样式，并在**属性栏**>**样式**>**地图**>**底图风格**选择自定义的底图风格。
:::
## 使用地点标注组件{#start}
数据中包含了位置或经纬度信息，可以在GIS地图上标注出明确位置，且可以设置地图的显示级别，如在GIS上标出武汉建设银行硚口支行的位置，具体步骤如下：
- **绑定数据模型**：在**属性栏**>**地点标注**>**数据**中选择引用的数据模型，如`武汉建设银行硚口支行`模型
- **设置地址类型并绑定位置字段**：根据地址在数据模型中存储的数据类型选择[地址类型](#address-type)为**经纬度**或者**地址**，并设置相关位置字段
- **设置地图操作模式**：在**属性栏**>**地点标注**>**高级**下可设置地图的操作模式，如**点击放大显示**、**启用拖拽**、**启用缩放**等，更多设置见[地图操作模式](#operate)
:::tip
地点标注中只能标注一个地点，故引用的数据模型只能有一条数据，可通过对数据模型设置过滤条件或者设置为单行数据集，可参考文档[数据模型设置-过滤条件](../../../../data-viz/dash/design/datasource.md#filter)
:::
## 地址类型{#address-type}
地点标注可以根据地址或经纬度进行标注，地址类型可选**经纬度**或**地址**，默认为**经纬度**。选取地址类型后，需要设置对应的字段：
- **经纬度**：当地址类型为经纬度时，需要选择**经度**和**纬度**字段，下拉选择数据模型中的**经度**、**纬度**字段即可，**经度**和**纬度**字段需要关联地理角色，参考文档[字段角色-地理](../../../../data-gov/model/field-role.md#geo)
- **地址**：当地址类型为地址时，需要选择**地址**字段，并可设置**地区**字段提高位置准确性
- **地区**：可选，一般是行政区划之类的地理范围，可以是行政区划代码（如110000）或者行政区划名称（如湖北、武汉...）。当不指定地区时，默认为全国。选择明确的地区更有利于根据地址精确定位到地点
- **地点代码**：可选，行政区划代码，用于对地址的标识，有利于根据地址精确定位到地点
## 地点标注信息设置{#label}
在GIS地图中可以添加提示信息，在**属性栏**>**地点标注**>**提示框**中设置：
- **不显示**：始终不显示提示框，默认为**不显示**
- **点击后显示**：当在地图中点击该地点后显示提示信息，需要设置**提示信息**内容，输入自定义的内容即可
- **自动显示**：在地图中始终显示提示信息，需要设置**提示信息**内容，输入自定义的内容即可
可以为标注的点设置图标，在**属性栏**>**样式**>**图标**下，可以选择已有的图标或者上传自定义图标。
## 缺省地点标注设置{#center}
当数据返回的数据为空，或者在地图上找不到对应位置时，可以显示为缺省状态下的地点标注。可以**属性栏**>**地图**>**地图中心**中设置，有2种设置格式：
- 地址：直接输入具体地址，如`武汉市东西湖区革新大道388-1(1)`
- 经纬度：输入确定的经纬度，格式为`ARR(经度, 纬度)`，可参考[ARR()](../../../../exp/func/json/ARR.md)
## 地图显示级别设置{#map-level}
地图级别即设置地图可缩放的最大级别，缩放级别越大可显示的城市信息越详细。在**属性栏**>**地点标注**>**高级**中设置，显示级别包括：**自动**、**街道**、**县区**、**城市**、**省**、**国家**、**高级**。
- 默认为**自动**，即以当前地点为中心点，自动定格地图级别，为**自动**时不会将缩放级别锁死
- 当为**高级**时，需要输入**缩放级别**，可设范围为\[2，20]。数字越小，缩放级别越小，即地图的范围越大。可以使用[表达式](../../../../exp/README.md)动态获取地图显示级别，如获取输入框中输入的显示级别，表达式为`${[地图显示级别]}`
## 地图操作模式{#operate}
在**属性栏**>**地点标注**>**高级**下可设置地图的操作模式，如点击地点后放大弹出对话框放大显示地点标注，双击对话框中的地点可以缩放地图，勾选**点击放大显示**即可。以及可以对地图**启用拖拽**、**启用缩放**等操作设置，可参考文档[地点分布](/superpage/component/gispoints/#operate)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/gispath.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/gispath"
title: "SuperPage组件-移动轨迹"
---
---
order: 15
navTitle: 移动轨迹
---
# SuperPage组件-移动轨迹
SuperPage提供了GIS地图，使用移动轨迹组件可以在地图中显示2个地点（起点和终点）之间的行动轨迹路线。
示例地址：[移动轨迹](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E7%A7%BB%E5%8A%A8%E8%BD%A8%E8%BF%B9)
:::tip
移动轨迹支持多种不同的底图风格显示，可以在[系统设置-外部服务-GIS](../../../../sys-settings/more/remote-services/gis.md)中自定义底图样式，并在**属性栏**>**样式**>**地图**>**底图风格**选择自定义的底图风格。
:::
## 使用移动轨迹展示移动路线{#start}
使用移动轨迹组件需要绑定含有地址信息字段的模型数据，具体数据要求可参考[数据设置](#data-settings)，同时根据需求选择合适的[轨迹类型](#type)，并进行对应设置即可。下方列举两个场景：
1. 需要显示巡查、行驶过的详细路径，则数据需要有固定频率记录的多条路径信息，如每5s采集经纬度位置，轨迹类型可选择**行动轨迹**
2. 需要显示当前地点到目的地的路径，则数据中需要有起始与目的地的中文地址或经纬度，轨迹类型可选择**地点路线**，以记录执法人员停留点大于5分钟为例，具体步骤如下：
1. **拖入移动轨迹：** 在**组件区**>**嵌入**分组下将**移动轨迹**组件拖入到布局中
2. **绑定数据模型：** 在**属性栏**>**移动轨迹**的**数据**中选择含有地址信息的数据模型，如`执法人员单次行动停留点`模型
3. **选择轨迹类型并设置：** 在**属性栏**>**移动轨迹**>**数据**的**轨迹类型**中选择**地点路线**类型，并根据地址在数据模型中存储的数据类型选择地址类型为**经纬度**或者**地址**，设置相关位置字段，更多可查看[数据设置](#data-settings)
## 数据设置{#data-settings}
在**属性栏**>**移动轨迹**>**数据**中需要引入含有位置信息数据的模型表，模型表设置如下：
- **经纬度**：当地址类型为**经纬度**时，需要选择**经度**和**纬度**字段，下拉选择数据模型中的**经度**、**纬度**字段即可，**经度**和**纬度**字段需要设置地理角色，可参考文档[字段角色-地理](../../../../data-gov/model/field-role.md#geo)
- **地址**：当地址类型为**地址**时，需要选择**地址**字段，也可设置**地址**字段提高位置准确性，**地址**和**地区**字段也需要设置[地理角色](../../../../data-gov/model/field-role.md#geo)
- 地区：可选，一般是行政区划之类的地理范围，可以是行政区划代码（如110000）或者行政区划名称（如湖北、武汉...）。当不指定地区时，默认为全国。选择明确的地区更有利于根据地址精确定位到地点
当存放多个轨迹点的地址信息数据时，模型表中有两种存储形式：
- 存放多条数据：将每个轨迹点的地址信息存放为一条数据，如每一组经度度分别存在一行，则多个点就有多条数据，可查看[执法人员单次行动轨迹表](https://demo.succbi.com/v5/DEMO/data?:open=jWh9BgmY7FCjIqa8SPyGED&:expandIds=%2FDEMO%2F%24APPMODEL)
- 存放一条数据：将多个轨迹点的位置信息存放在一行中，如将多个经度、纬度分别以逗号`,`分割存放在一行数据中
在**数据**处选择绑定数据模型之后，还需设置**地址类型**、**轨迹点索引**、**轨迹类型**等：
- **地址类型**：可选择**经纬度**与**地址**类型，**行动轨迹**类型适用于数据量较大的，所以地址类型默认为**经纬度**，不可选择
- **轨迹点索引**：设置轨迹路径中轨迹点顺序位置，如选择数据模型中的时间类型字段`开始时间`，则会按开始时间对轨迹点进行排序
- **轨迹类型**：可选择**地点路线**与**行动轨迹**两种类型，地点路线适用于较简单的移动路线，行动轨迹适用于数据量较大且需要展示轨迹点详细位置信息的移动轨迹，具体可查看[移动轨迹类型](#type)
### 移动轨迹类型{#type}
可以根据路线复杂度、数据量、展示地址信息等需求对轨迹类型进行选择：
- **地点路线**：一般用来显示人员行动的简单路线，常用于包含少量轨迹点的数据，支持使用地址与经纬度两种地址类型作为数据在程序中转换。如跑步软件中，只需要记录从起始到终点的简单路线，对于经过的点的详细信息不需要了解
- **行动轨迹**：一般用来显示人员行动的具体路线以及查看停留点的信息，数据量较大，只能用经纬度作为数据，对于路线上的经过点也支持在提示信息中直接给出地点的基本信息。如检查人员上访多个家庭检查，记录行驶数据生成具体行动轨迹路线，同时对每个停留点的详细信息也能记录展示
|地点路线|行动轨迹|
|--|--|--|--|--|
|||
### 轨迹点设置{#trackpoint}
有**起点**、**终点**和**经过点**三类轨迹点，其中：
- 起点与终点：分别只有一个，可以设置提示信息和标签内容
- 经过点：可以有多个，当在**移动轨迹**>**数据**>**经过点**中勾选了**突出经过地点**，在匹配条件属性中写入[表达式](../../../../exp/README.md)，符合该匹配条件的经过点才会显示，如`${[执法人员单次行动轨迹].[停留时间] > 5}`，则停留时间大于5的经过点才会显示。勾选后，同样可以设置提示信息和标签内容
所有的轨迹点都可以设置提示信息和标签内容，如下：
- 提示信息设置：在**提示框**属性中可设置对轨迹点做补充说明的提示信息，在**样式**>**提示框**中可以设置提示信息的样式，可参考[轨迹点提示信息样式设置](#promptbox)。提示信息有三种显示方式：
- 不显示
- 自动显示：直接显示
- 鼠标移入显示：鼠标移至点上，才会显示提示信息
- 标签设置：勾选显示标签后，在输入框中写表达式，如`${[执法人员单次行动停留点].[经过顺序]}`，则在轨迹点上会显示依次经过的顺序`1`、`2`等
## 样式设置{#properties}
在**属性栏**>**样式**中可设置移动轨迹的[地图样式](#map)、[轨迹样式](#style)、[提示信息样式](#promptbox)等。
### 地图样式设置{#map}
在**样式**>**地图**中可设置地图的类型，以及底图类型与底图风格。
- 底图类型：可以选择卫星图模式
- 底图风格：可设置标准、幻月黑、月光银、远山黛风格
### 轨迹样式设置{#style}
在**样式**>**轨迹**中可设置轨迹与轨迹点的样式以及[动画样式](#animation)。
**轨迹样式**
包含**轨迹**与**经过轨迹**的样式，经过轨迹效果会叠加在轨迹效果之上。在轨迹中可直接设置样式，经过轨迹则需要在**轨迹**>**经过轨迹**中勾选**显示经过效果**才能设置，轨迹样式如下：
- 轨迹：可设置轨迹颜色与大小
- 在轨迹中显示箭头：勾选后轨迹中会显示从起点朝向终点的箭头，在弹出的**箭头**中可设置箭头的颜色与大小，**箭头间隔**中设置每个箭头的间距
- 在终点显示箭头：此设置只能在轨迹中设置
**轨迹点样式**
在**起点**、**终点**、**经过点**中可分别设置对应轨迹点的样式，包括图标、显示位置等：
- 图标：设置在对应点处显示的图标，默认为标记地点图标，可设置图标的宽度与高度，前一个为宽度设置
- 显示位置：设置图标在对应点的相对位置，包括上方、左侧、中心、左上等
- 标签偏移：设置对应点的标签偏移量
- 标签字体：设置标签的字体、颜色与大小
### 动画效果{#animation}
在**样式**>**轨迹**>**动画**中可设置整个移动轨迹的动画效果，可设置如下属性：
- 自动播放动画：勾选后才会播放轨迹动画效果
- 循环播放：勾选后，轨迹动画可循环播放
- 动画时长：设置播放一次动画的时长
- 轨迹流动特效：勾选后可以显示轨迹流动的特效，并且可以调节流动速度
- 巡航器：可设置轨迹移动巡航的图标、颜色和大小
### 轨迹点提示信息样式设置{#promptbox}
在**样式**>**提示框**中可以设置轨迹点提示框的字体、背景等样式。
## 地图操作模式{#operate}
在**属性栏**>**移动轨迹**>**高级**中可设置地图的操作模式，可启用移动轨迹组件的拖拽和缩放，勾选**启用拖拽**与**启用缩放**即可。
- 启用拖拽：预览界面可使用鼠标拖拽移动轨迹位置
- 启用缩放：预览界面可使用鼠标滚动来缩放移动轨迹，也会弹出**显示缩放按钮**选项，勾选后，在移动轨迹右下角会出现缩放按钮，点击按钮可对应缩放
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/embed/dialog.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/dialog"
title: "SuperPage组件-对话框/悬浮面板"
---
---
order: 17
navTitle: 对话框/悬浮面板
---
# SuperPage组件-对话框/悬浮面板
SuperPage提供了对话框/悬浮面板组件，在父页面中可以弹出子页面，并可增删改数据进行提交。如在PC端和移动端点击按钮显示对话框/悬浮面板会有不同的适配效果：
|PC端|移动端|
|--|--|
|||
示例地址：[对话框](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AF%B9%E8%AF%9D%E6%A1%86)
:::tip
SuperPage中可以有多种方式显示对话框：
1. 本文中描述的**对话框/悬浮面板**组件配合[显示对话框/悬浮面板](../../design/action/show-dialog.md)交互
2. **打开链接**交互配合**对话框**显示方式。该方式与这里的对话框组件不同，是需要将打开链接交互中的页面**显示方式**设置为`对话框`形式，具体可参考[打开链接-显示方式设置](../../design/action/linkto.md#how_to_show)
:::
## 使用对话框/悬浮面板组件{#start}
对话框/悬浮面板通常是由用户的交互触发而显示的，比如点击[文本](../common/text.md)、[按钮](../common/button.md)等组件显示对话框/悬浮面板。对话框/悬浮面板与页面类似，所有组件均可拖入到其中，因此可以根据需求可以有多种类型的对话框，以信息对话框为例：
**操作步骤：**
1. **拖入对话框/悬浮面板组件：** 在**组件区**>**嵌入**中将**对话框/悬浮面板**组件拖入到画布中
2. **编辑对话框内容：** 双击对话框进入编辑界面，可从左侧组件区域中拖入多个组件到对话框中，如拖入`文本组件`到内容区域，并输入内容`这是一段信息`
3. **配置显示对话框/悬浮面板交互：** 在`点击打开Dialog`文本上设置**显示对话框/悬浮面板**交互，**对话框组件**属性选择对应的对话框，如`对话框1`，更多设置查看[显示对话框/悬浮面板交互](../../design/action/show-dialog.md#start)
:::tip
在预览、查看等界面不能看见对话框/悬浮面板组件，所以该组件可以位于画布中任意位置且不影响其他组件，建议位于被显示对话框/悬浮面板交互引用的组件附近。当页面中无法选中时可点击**文件**>**显示/隐藏组件大纲**进行选中
对话框有默认编辑界面，可在默认界面上做修改，也可删除重新布局。对话框宽度与高度默认最小设置为`500`，若需要的对话框较小，可在**对话框**>**位置大小**中进行调整，默认界面如下：
:::
## 显示对话框/悬浮面板交互{#show-dialog}
对话框/悬浮面板组件必须配合**显示对话框/悬浮面板**交互使用才能将对话框/悬浮面板中设置的内容展示在页面中，才能实现其作用。具体操作及设置可查看[显示对话框/悬浮面板交互](../../design/action/show-dialog.md)。
## 悬浮面板{#floatdialog}
悬浮面板与对话框在功能上无本质区别，但在弹出的效果有所不同，悬浮面板弹出的效果是直接悬浮在弹出位置下方的，只因在**属性栏**>**对话框**>**高级**中勾选了**显示为悬浮面板**属性，悬浮面板组件该属性默认被勾选。同时在**高级**中勾选**允许拖动窗口大小**属性后，也可修改弹出的对话框大小。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/input"
title: "输入组件"
---
---
order: 6
navTitle: 输入
---
# 输入组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/textinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/textinput"
title: "SuperPage组件-文本输入"
---
---
order: 1
navTitle: 文本输入
---
# SuperPage组件-文本输入
文本输入组件可以在输入文字信息后，过滤或者提交数据：
- [过滤数据](#使用文本输入组件过滤数据)：输入的关键字可以匹配筛选出相关数据
- [提交数据](#使用文本输入组件提交数据)：将输入的信息存入到数据库中。例如用户注册，输入个人信息后点击注册，即可将用户数据提交到用户表中
以过滤数据的功能为例，使用文本输入组件和列表组件搭配使用，搜索门店相关信息：
:::tip
**多行输入**组件与**文本输入**组件的功能和使用方法一致，适用场景有所区别：
- **文本输入**组件：适合单行数据的输入
- **多行输入**组件：输入信息较长，需要换行显示。**多行输入**组件还可以根据输入的内容自动换行，也可以按“enter”换行。
:::
## 使用文本输入组件过滤数据{#filter}
**文本输入**组件自动过滤的是数据模型的数据，将作用到所有使用此数据模型的组件。使用时需要为过滤的数据绑定**条件字段**，并搭配其他展示数据的组件一起使用。以搭配列表组件搜索门店相关信息为例，如下是具体操作步骤：
1. **使用文本输入组件**：在**组件区**>**输入**中将**文本输入**组件拖入到布局中
2. **设置自动过滤**：在**文本输入**>**数据**中勾选**自动过滤**，在**条件字段**中选择【门店名称】，**匹配模式**选择**包含**
## 使用文本输入组件提交数据{#submit}
**提交数据**的使用方法与**过滤数据**类似，**文本输入**组件在提交数据时，绑定需要提交到的字段，并搭配按钮组件一起使用。以提交【销售数量】的数据为例：
1. **设置提交数据**：选中**文本输入**组件，在**文本输入**>**数据**中勾选**提交数据**，在**绑定字段**中选择【销售数量】
2. **设置提交按钮**：选中**按钮**组件，在**交互**中选择**提交表单**
以上步骤即可实现简单的数据提交，更多的数据提交介绍可以查看文档[提交数据](../../design/submit-data.md)。
:::tip
**自动过滤**和**提交数据**两个功能互斥使用，同时仅能满足一项操作。若已勾选**自动过滤**，再次勾选**提交数据**时，**自动过滤**的选中效果自动取消。
:::
## 属性介绍{#properties}
### 自动过滤{#autofilter}
当开启了**自动过滤**功能，在组件中输入内容后可以过滤数据。勾选**自动过滤**即启动了过滤功能，需要对以下三个属性进行设置：
- **为空时包含所有**：勾选后，当输入框没有内容时，展示所有的数据
- **条件字段**：必选项，绑定需要实现过滤的字段，若不设置，将无法过滤数据
- **匹配模式**：必选项，选择过滤方式
- 包含：匹配出包含输入框中内容的数据
- 开头为：匹配出开头为输入框中内容的数据
- 结尾为：匹配出结尾为输入框中内容的数据
- 精准匹配：匹配出和输入框中内容完全一致的数据
### 校验{#validate}
启用了**校验**功能后，可以对组件中输入的内容进行**校验**，当内容不符合设定的规则时，将在组件下方以红色文字的形式提示用户。**校验**属性中提供了两种设置方式：
- **必填**：设置该组件必须要填写内容，当勾选后，在组件标题的前面会自动加上红色星号。当检测到必填项没有填写内容时，会在顶部以消息框的形式提示用户“请输入xxx”，“xxx”为该组件的标题，并且组件下方也会用红色文字提示用户
- **校验**：勾选后需要设置**校验公式**和**校验提示**
- 校验公式：输入表达式对文本的内容进行校验，表达式返回true表示校验通过，例如使用[REGEXP\_MATCH](../../../../exp/func/string/REGEXP_MATCH.md)函数判断输入的人名是否合法
- 校验提示：自定义校验不通过时，组件下方红色文字显示的内容，若不设置**校验提示**，则校验失败后默认显示`校验失败`
- **最大长度**：限制组件中允许输入字符的最大长度，达到最大限度后不再允许用户输入
:::tip 提交数据
- 当使用[校验表单](../../design/action/validate-data.md)交互对指定范围内的所有输入组件进行校验时，若校验不通过，则可以自动定位至校验失败的组件。数据提交前的校验介绍可参考文档[提交数据](../../design/submit-data.md#validate)
- 组件勾选了**必填**，[提交数据](../../design/submit-data.md#validate)时根据**显示属性**设置的不同，有两种情况：
- 隐藏组件：提交数据时不进行校验
- 禁用组件：提交数据时进行校验
:::
### 其他属性介绍{#other-properties}
- **提示**用于鼠标悬停在组件时，对用户进行提示。在**文本输入**>**高级**>**提示**中进行设置
- **占位符**用于当输入框内容为空时，在输入框内占位显示提示信息。在**文本输入**>**高级**>**占位符**中进行设置
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/numberinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/numberinput"
title: "SuperPage组件-数值输入"
---
---
order: 2
navTitle: 数值输入
---
# SuperPage组件-数值输入
数值输入组件和[文本输入组件](./textinput.md)功能类似，输入信息后可以过滤或者提交数据。区别在于数值输入组件中限定了只能输入数字，不能输入其它类型的内容。
以过滤数据的功能为例，使用数值输入组件和列表组件搭配使用，对销售数量进行过滤：
示例地址：[数值输入](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%BE%93%E5%85%A5%E6%8E%A7%E4%BB%B6)
## 使用数值输入组件过滤数据{#use}
在SuperPage中，使用数值输入组件过滤数据时，需要为过滤的数据绑定**条件字段**，并搭配其他展示数据的组件一起使用。以搭配列表组件为例对销售数量进行过滤，如下是具体操作步骤：
1. **使用数值输入组件**：在**组件区**>**输入**中将**数值输入**组件拖入到布局中
2. **设置自动过滤**：在**数值输入**>**数据**中勾选**自动过滤**，在**条件字段**中选择【销售数量】，**匹配模式**选择**大于**
通过以上操作即可实现数值输入组件和列表组件搭配使用，对销售数量进行过滤。
**数值输入组件和文本输入组件的区别和联系**
数值输入组件和[文本输入组件](./textinput.md)的功能和使用方法一致，二者在可输入类型和过滤数据时的匹配模式上有区别：
- **数值输入**组件：只能输入数值类型的数据。过滤数据时的匹配模式为数值大小匹配，包括`大于、小于、等于`三种方式。数值输入组件的其他属性可参考[文本输入](./textinput.md)。
- **文本输入**组件：可以输入任何类型的数据。过滤数据时的匹配模式为字段的模糊匹配，包括`包含、开头为、结尾为、精确匹配`四种方式。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/checkbox.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/checkbox"
title: "SuperPage组件-勾选框/单选框"
---
---
order: 5
navTitle: 勾选框
---
# SuperPage组件-勾选框/单选框
勾选框与单选框的使用方法一致，只是样式不同。本文以勾选框为例介绍勾选框、单选框的用法。
示例地址：[勾选框](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%8B%BE%E9%80%89%E6%A1%86)
## 使用勾选框组件提交数据{#submit}
勾选框输入组件的**提交数据**和其它输入组件**提交数据**操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，可以将输入信息提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。
## 使用勾选框组件过滤数据{#filter}
勾选框和单选框本身不具备自动过滤的功能，当需要使用该组件过滤其它组件数据时，例如根据勾选框是否发生股权转让过滤列表数据，可以如下方式实现：
- 在数据下选中需要过滤数据的模型，**右键**>**设置**>**过滤条件**，点击**添加**选择**表达式**，输入表达式`[企业年报].[是否发生股权转让]=[是否发生股权转让].[值]`
:::tip
过滤数据需要在添加的数据模型上设置过滤条件，即可作用在所有引用了该数据模型的组件，可参考文档[为仪表板添加数据-数据模型设置](../../../../data-viz/dash/design/datasource.md#filter)
:::
## 设置勾选框的返回值{#value}
在**勾选框**>**高级**属性里可以指定勾选框的返回值，即当勾选框勾选时与未勾选时返回的值：
- 勾选值：默认是1，勾选时提交的数据值
- 未勾选值：默认值是0，不勾选时提交的数据值
例如是否已婚的勾选框，勾选后返回值是1，表示已婚；未勾选返回值是0，表示未婚。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/selectionpanel.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/selectionpanel"
title: "SuperPage组件-单选/多选面板"
---
---
order: 8
navTitle: 单选/多选面板
---
# SuperPage组件-单选/多选面板
SuperPage提供了选择面板，包括单选面板和[多选面板](#multiple)，可以过滤或提交数据。[多选面板](#multiple)与单选面板的功能一致，只需要勾选**允许多选**即可。本文以单选面板为例，介绍选择面板的用法。
示例地址：[单选面板](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E9%80%89%E6%8B%A9%E9%9D%A2%E6%9D%BF)
## 使用单选面板过滤数据{#filter}
使用单选面板组件过滤数据有2种方式：
- **自动过滤数据**：当单选面板绑定了字段，那么可以启用**自动过滤**，此时系统会自动以单选面板选择的值为过滤条件，如【企业类型】单选面板，选择对应企业类型后即可自动过滤查询出来的数据。勾选**自动过滤**属性并设置**条件字段**属性即可，具体可参考[使用下拉框过滤数据](./combobox.md#filter)。
- **过滤数据模型的数据**：当过滤条件比较复杂，或者单选面板的值没有绑定字段，此时需要通过[表达式](../../../../exp/README.md)编写过滤条件进行过滤，可参考文档[勾选框-使用勾选框过滤数据](./checkbox.md#filter)。
## 使用单选面板提交数据{#submit}
单选面板提交数据的方式与其它输入组件一致，需要勾选[提交数据](../../design/action/submit-data.md)并设置**绑定字段**，具体可参考文本输入组件。具体可参考[文本输入组件](./textinput.md#submit)。
## 选项数据{#data}
### 来自模型数据{#model-data}
当单选面板的选项数据在已有模型表中存在时，在**可选项**的下拉列表中选择对应的模型表即可，并且可以设置选项的显示内容及节点属性等，与下拉框组件属性设置一样，可参考文档[下拉框](./combobox.md)。
### 枚举值{#options}
如果无法从数据模型中获得可选值，那么也可以自行编辑枚举值。在**可选项**下选择**枚举值**，然后点击**编辑枚举值**：
## 多选面板{#multiple}
多选面板与单选面板的使用方法一致，只是允许同时选择多个选项，及选择框的样式不一致。使用多选面板有2种方式：
- 从**组件区**>**输入**分组下拖入**多选面板**到页面中
- 将单选面板设置**允许多选**：在**选择面板**>**可选项**中勾选**允许多选**即可
:::tip
当多选时提交的多个值之间是以逗号分隔存储在字段中，若展示数据时需要与[关联表](../../../../data-gov/model/README.md#associated-table)的数据关联起来，则需要给字段设置[字段角色](../../../../data-gov/model/field-role.md#values)为**多值**。
:::
## 属性介绍{#properties}
### 横向排列{#horizontal}
单选面板的排列方式默认为**横向**，当为**横向**时可设置绕排和按列对齐：
- **绕排**：设置为**自动绕排**后，选项一行显示不下时，会自动换行排列。也可以选择**不绕排**显示选项
- **按列对齐**：设置**自动绕排**后，可以设置选项按列自动对齐排列
- **固定列数**：设置了按列对齐后，可以设置一行显示几列，输入大于0的整数，2表示显示2列
| 自动绕排 | 按列对齐 |
| -------- | -------- |
|  |  |
### 纵向排列{#vertical}
在**属性栏**>**样式**>**面板**下可设置单选面板的排列方式为**纵向**排列：
### 启用展开收起{#expand-collapse}
当选项较多时，可以收起部分选项，勾选该属性即可。可以设置默认是收起的效果，勾选**默认收起**属性即可，可设置收起时默认的**显示行数**：
- **显示行数**：收起时，显示的选项行数，默认为1，即只显示一行，输入大于0的整数即可
### 选项面板样式设置{#optional}
在**属性栏**>**样式**>下可设置面板和选项的样式：
- **面板**：包括填充、边框、内边距等样式设置
- **选项**：可以设置选项文字的字体、填充、边框、圆角、边距等，也可以设置是否**显示勾选图标**
- **显示勾选图标**：当勾选后在选项前会有一个可勾选的框，选择选项时可点击勾选框或者选项标题，若未勾选，则只显示选项标题，点击选项标题即代表选中。默认勾选该选项
## 单选面板、下拉框、选择列表区别介绍{#difference}
单选面板、[下拉框](./combobox.md)、[选择列表](./treeselector.md)表输入组件的作用一致，区别在于数据的展现形式和应用场景不一致：
| 组件 | 展示方式 | 应用场景 |
| --- | --- | --- |
| 单选面板 | 平铺 | 适用于选项较少的数据，如价格档次等 |
| [下拉框](./combobox.md) | 下拉列表 | 适用于展示有层次结构的数据，如销售单位、行政区划等 |
| [选择列表](./treeselector.md) | 列表 | 与下拉框类似，可展示有层次结构的数据 |
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/combobox.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/combobox"
title: "SuperPage组件-下拉框"
---
---
order: 9
navTitle: 下拉框
---
# SuperPage组件-下拉框
使用下拉菜单展示或选择内容，可用于提交或过滤数据。
示例地址：[下拉框](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E4%B8%8B%E6%8B%89%E6%A1%86)
## 使用下拉框组件过滤数据{#filter}
使用下拉框组件过滤数据时有2种方式：
- [设置数据模型的过滤条件](#model-filter)
- [自动过滤](#autofilter)
### 过滤数据模型的数据{#model-filter}
当下拉框的列表数据未与模型表的数据关联时，即使用枚举值，此时需要在模型上设置过滤，可参考文档[勾选框-使用勾选框过滤数据](./checkbox.md#filter)。
### 自动过滤{#autofilter}
下拉框组件自动过滤的是数据模型的数据，将作用到所有使用此数据模型的组件。使用时需要为过滤的数据绑定条件字段，并搭配其他展示数据的组件一起使用。以搭配[列表](../data/list.md)组件搜索大区销售信息为例，如下是具体操作步骤：
1. **使用下拉框组件**：在**组件区**>**输入**中将**下拉框**组件拖入到布局中
2. **绑定下拉框的数据**：在**属性栏**>**下拉框**>**可选项**中下拉选择`区域编码`，设置属性为`大区`，更多的属性设置见[下拉列表为模型数据](#model-data)
3. **设置自动过滤**：在**属性栏**>**下拉框**>**过滤**中勾选自动过滤，在**条件字段**中选择`大区`
4. **设置默认值**：在**属性栏**>**下拉框**>**输入**中指定默认值为`华北`
## 使用下拉框组件提交数据{#submit}
下拉框输入组件的**提交数据**和其它输入组件**提交数据**操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，可以将输入信息提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。\
当多选时提交的多个值之间是以逗号分隔存储在字段中，若展示数据时需要与[关联表](../../../../data-gov/model/README.md#associated-table)的数据关联起来，则需要给字段设置[字段角色](../../../../data-gov/model/field-role.md#values)为**多值**。
## 下拉列表为枚举值{#options}
当下拉框的数据需要手动添加时，可以选择枚举值，在**可选项**下选择**枚举值**后，点击**编辑枚举值**，可添加下拉框的数据。点击**下面插入行**即可新增枚举项，枚举值由**值**和**描述**组成：
## 下拉列表为模型数据{#model-data}
当下拉框的列表数据在已有模型表中存在时，可直接选择对应的模型表，在**可选项**的下拉列表中会显示当前页面中添加的数据模型以及模型中对应的[关联表](../../../../data-gov/model/README.md#associated-table)，并且可以设置列表选项的显示内容及节点属性等：
### 下拉内容设置{#field}
下拉列表的内容默认是维表的主键信息和默认的层次信息，也可以自定义下拉列表的内容，在**下拉框**>**可选项**>**属性**中设置即可。\
当**可选项**中设置的是维表时，在**属性**的选项中会列出该维表的所有属性，选择某个属性后，下拉框组件的下拉列表会显示该属性的内容，如只显示大区的数据，则在**属性**中选择为`大区`。\
当自定义属性后，根节点和显示最大级次的设置将不起作用。
:::tip 下拉属性
- 当选择的模型为多主键且设置了周期快照，需指定属性为某个字段。
- **属性**下拉列表显示的是该模型的所有维度字段，下拉框组件的数据是按照维度字段去重显示。
:::
### 根节点设置{#root}
当**可选项**设置的是数据表且带有层次时，可以设置显示哪些根节点，以及是否显示根节点，见[下拉框联动](#linkage)。设置方式如下：
- **根节点**：当设置了根节点内容后，下拉列表只显示该节点下的数据。输入的内容是可选项中数据表的主键信息
- 限制显示单个节点：例如只显示**湖北省**的节点，内容输入为`420000`
- 限制多个节点：限制多个节点需要使用[ARR](../../../../exp/func/json/ARR.md)函数。例如显示**湖北**和**湖南**节点，内容输入为`ARR(420000,430000)`
- **显示根**：勾选后，则会将根节点属性中设置的节点显示在列表中。默认不显示
### 维项过滤设置{#dimension-filtering}
**维项过滤**是一个过滤条件，帮助下拉框组件缩小数据显示范围，只将满足条件的维成员显示在下拉框中，使用维表中的字段即可。如绑定销售单位维表的下拉框中，会将该维表中的字段列在数据中，如表达式为`[大区名称]!='华北'`，即在下拉框中不显示华北。
当[属性](#field)选择为【字段名称】时，维项过滤可以过滤哪些字段不显示，语法如下：
```md
[字段名称] = 'XSDW' // 过滤物理字段名
[字段名称].[名称] = '销售单位' // 过滤逻辑名
[字段名称].[名称] = '销售单位, 销售计划' // 过滤多个逻辑名
```
示例地址：[企业查询-输出字段](https://demo.succbi.com/v5/DEMO/app/ap.app/%E6%A1%88%E4%BE%8B/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2.tpg?id=%E4%BC%81%E4%B8%9A%E6%9F%A5%E8%AF%A21)
### 显示最大级次{#level}
当在下拉列表中显示的是一个带有层次的数据时，可以设置**显示最大级次属性**，限制树形显示到哪一个级次。该属性只能输入数字，即0、1、2...，其中0表示最大级次。
### 显示统计数{#statistics}
在下拉框的选项列表中可统计该选项对应的数据总数，勾选**显示统计数**属性，并选择了**统计字段**后，在下拉框组件的列表中会显示该字段的统计数字。如**产品类型**下拉框，勾选**显示统计数**之后，会在每个选项后显示每类产品对应的产品个数。
- 可隐藏统计数为0的选项，只需要勾选**隐藏统计数为0的项**即可。
- **统计字段**可以选择可选项中设置的数据模型字段，也可以选择该spg页面中添加的其它数据模型字段。如果选择了其它数据模型字段，该数据模型需要和可选项中选择的数据模型粒度是一致的。
## 下拉框操作设置{#settings}
可以通过下拉框设置来修改下拉框数据的可选设置：
- **默认值**：默认的筛选条件设置，可以下拉选择固定值或者[表达式](../../../../exp/README.md)获取
- **允许多选**：勾选该选项后，可以同时勾选或选中多个下拉框中的节点，允许多选后可设置**显示已选个数**及**显示“全部”**
- **允许清空**：勾选后，允许删除下拉框中已选择的数据。若未勾选，当勾选了数据后只能通过选择其他选项来替换已选择的数据
- **只选叶子节点**：勾选该选项后，点击根节点只能展开根节点并不能被选中，且只能选中或勾选无叶子节点的子节点
- **显示已选个数**：当勾选**允许多选**，可选择**是否显示已选个数**。勾选后，当下拉框中选择了数据后，会在下拉框中显示已选择的选项个数
- **显示“全部”**：当勾选后，下拉框的列表中会有一条“全部”的选项，选择**全部**后会勾选所有的选项
### 自动选中第一项{#first-item}
勾选后下拉框自动选中列表数据里面的第一项，此属性与**默认值**属性互斥，**默认值**的优先级更高，即设置了**默认值**之后，**自动选中第一项**不生效。
## 应用场景{#scenarios}
### 下拉框联动{#linkage}
使用下拉框可实现参数联动，如`大区-省-市-门店`联动，在选择了某大区后，省的下拉列表中只会显示该大区对应的省，以及市和门店也只显示对应根节点下的数据：
**实现方式：**
场景一：大区-省-市-门店联动，默认选中第一项
1. 设置下拉框**省**的[维项过滤](#dimension-filtering)表达式为`[大区]=[大区联动1].[值]`
2. 设置下拉框**市**的[根节点](#root)为`[省联动1]`、设置下拉框**门店**的[根节点](#root)为`[市联动1]`
场景二：大区-省-市-门店联动，前一个组件没有选择时，后面的组件不可选
1. 设置下拉框省的禁用条件为`[大区联动2].[值]=""`
场景三：大区-省-市-门店联动，前一个组件没有选择时，后面的组件是隐藏的
1. 设置下拉框**省**的显示条件为`[大区联动3].[值]!=""`
### 动态显示下拉框数据{#display}
下拉框可以设置动态的显示隐藏条件和禁用条件，这样可以动态决定某些数据是否显示及下拉框是否可用，例如根据登录用户不同决定某个菜单是否显示。通过设置下拉框的**显示**>**显示条件**属性或者**禁用**>**禁用条件**属性即可实现。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/datecombobox.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/datecombobox"
title: "SuperPage组件-日期"
---
---
order: 10
navTitle: 日期
---
# SuperPage组件-日期
SuperPage提供了日期组件，选择日期数据后用于过滤或提交数据。以过滤数据功能为例，使用日期组件和列表组件搭配使用，对销售日期进行过滤：
示例地址：[日期](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%97%A5%E6%9C%9F)
## 使用日期组件过滤数据{#filter}
使用日期组件过滤数据有2种方式：
- **自动过滤数据**： 勾选数据中**自动过滤**，并绑定**条件字段**，如`销售日期`，此时系统会自动以日期组件中的值过滤数据，具体可参考[文本输入组件](./textinput.md#filter)
- **过滤数据模型的数据**： 当日期中的数据与模型表的数据无关联时，此时若需要过滤数据则可在模型上设置过滤条件，可参考文档[勾选框-使用勾选框过滤数据](./checkbox.md#filter)
## 使用日期组件提交数据{#submit}
日期组件的提交数据与其它输入组件提交数据操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，可以将选中的日期提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。
## 日期选项设置{#settings}
在**日期**>**选项**下可以设置日期显示**类型**与**范围**：
- **类型**：日期组件可使用不同类型，如年、年月日等，可参考日期对话框组件的[日期数据设置](./datedialog.md#settings)
- **范围**：日期组件默认为固定值，也可设置相对值与范围
- 指定：下拉选择指定的日期或时间为默认值
- 相对值：在**选项**中勾选**允许选择相对值**，点击日期组件，在弹出的日期对话框上方点击**相对**，可设置相对日期，如设置相对今天的前一天日期，则日期会根据每天日期变化始终显示前一天的日期数据
- 范围：在**选项**中勾选**允许选择范围**，点击日期输入框，在弹出的日期对话框上方点击**范围**，可设置范围日期的起始日期与结束日期
- **表达式**：设置表达式的计算结果作为默认值，可使用[表达式函数](../../../../exp/README.md)，输入值或范围表达式。如默认查询当天的数据，则表达式为`today()`；查询近一个月的数据，即上个月的今天到当日的数据，表达式示例`'[' + adddate(today(),-1,'m') + '~' + today() + ']'`，更多日期函数及其使用方法可查看文档[日期函数](../../../../exp/func/date/README.md)
|指定|相对|范围|
|--|--|--|
||||
## 日期显示方式{#display}
日期组件支持两种显示方式，显示模式是根据访问设备自动适配的：
- **PC端**：以下拉方式显示日期对话框
- **移动端**：底部弹出面板方式显示，与日期对话框移动端显示一致
|PC端|移动端|
|--|--|
|||
## 日期组件与日期对话框组件的区别{#difference}
日期组件与[日期对话框](./datedialog.md)组件均能设置日期且自身具备过滤数据功能，二者在使用方法与功能上有所区别：
||体验|提交数据|日期范围|
|--|--|--|--|--|
|**日期**|点击日期组件以下拉方式显示日期对话框|自身具备提交数据功能|可设置指定值、相对值、范围|
|**日期对话框**|需要借助按钮以及交互弹出日期对话框|自身不具备提交数据功能，需要借助交互或其它输入组件|只能选择指定值|
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/searchbox.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/searchbox"
title: "SuperPage组件-快速搜索"
---
---
order: 15
navTitle: 快速搜索
---
# SuperPage组件-快速搜索
**快速搜索组件**是**输入组件**的一种，与[输入框](./textinput.md)和[下拉框](./combobox.md)类似，都可用于**提交数据**或**过滤数据**。其特殊之处在于，在输入**关键字**后，系统会按照指定的**搜索规则**，在数据库中搜索匹配的数据，并以下拉列表的形式展示搜索的**结果项**，供用户选取，被选取的**结果项**作为**快速搜索组件**的**值**可用于数据的**提交**或**过滤**。
- **过滤数据**：输入关键字并选择搜索结果可以过滤模型数据
- **提交数据**：将选择的搜索结果存入到数据库中，如机构新增，输入机构的关键字并选择机构，点击提交即可将机构信息新增至机构表中
以快速搜索组件的过滤功能为例，通过与[列表组件](../data/list.md)搭配可实现企业人员信息的过滤：
示例：[快速搜索组件](https://demo.succbi.com/v5/bi/%E5%BF%AB%E9%80%9F%E6%90%9C%E7%B4%A2%E4%BC%81%E4%B8%9A)
## 使用快速搜索组件过滤数据{#filter}
快速搜索组件支持绑定数据模型，在过滤数据时会作用到所有引用了该数据模型的组件。使用时需要为过滤的数据绑定**条件字段**，并搭配展示数据的组件一起使用。如通过企业名称筛选出该企业的全部人员信息，实现步骤如下：
1. **拖入快速搜索组件**：在**组件区**>**输入**中将**快速搜索**组件拖入到画布中
2. **设置搜索规则**：在**属性栏**>**快速搜索**>**搜索**中，绑定`企业主要人员`，点击**搜索规则**将搜索字段设置为`企业名称`
3. **设置搜索面板**：勾选**自定义搜索面板**在展开的配置项中设置**标题字段**为`企业名称`，还可以按需设置**描述字段**，更多设置说明可查看[搜索设置](#自定义搜索面板settings)
4. **设置自动过滤**：在**属性栏**>**快速搜索**>**过滤**中勾选自动过滤，并选择条件字段为`企业内部序号`。
## 使用快速搜索组件提交数据{#submit}
快速搜索组件**提交数据**的方法与其他输入组件**提交数据**操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性；提交时，会将搜索框选中条目对应的主键作为数据提交到对应的**绑定字段**中去。
快速搜索组件的搜索结果可被其他组件引用，通过搭配其他输入组件，可实现在选择搜索结果后，同时提交多个组件数据的效果，如使用[文本输入组件](./textinput.md)获取企业信息搜索结果中的`法定代表人`字段数据，在**计算公式**的编辑框中，双击拾取**参数**属性下快速搜索组件的`法定代表人`字段即可。
::: tip TIP
快速搜索组件只会查询页面中使用到的字段，如果某字段在页面中从未被引用过，则查询时会忽略该字段。
:::
## 搜索规则{#rule}
搜索规则设置主要用于优化搜索性能。以`企业信息表`为例，比如可以通过`社会信用代码`、`企业名称`、`手机号`等多个字段进行搜索，在未做优化时当用户输入一串数字想搜索手机号，会同步搜索`企业名称`这样没有关联的字段，消耗了额外的性能。此时可以进一步细化搜索规则，比如判断当前输入内容是数字时则只搜索`手机号`，是汉字时则只搜索`企业名称`。搜索规则设置如下图所示：
添加数据集后，点击**搜索规则**按钮。对话框中内置了一条**默认规则**，需要给**默认规则**添加**搜索字段**作为保底规则，默认规则不可删除，总是在所有规则的下面。**搜索规则**可拖拽调整顺序，从上往下判断，命中某条规则后则用该规则进行搜索，后续规则不再判断。每条**搜索规则**需要设置**业务描述**、**搜索规则**、**搜索字段**、**搜索方式**：
- **业务描述**：用于区分不同的**搜索规则**，通常根据**搜索规则**的使用场景命名，如“身份证号”、“姓名”等
- **搜索规则**：通常使用[正则表达式](../../../../exp/func/string/REGEXP_MATCH.md#example)来匹配当前输入内容，用于判断当前输入内容是何种形式；也可直接在表达式中使用[`startwith`](../../../../exp/func/string/STARTSWITH.md)、[`contains`](../../../../exp/func/string/CONTAINS.md)等字符串函数来判断，通过`快速搜索组件ID.输入值`获取用户的输入值作为函数的参数
- **搜索字段**：搜索时用于匹配关键字的字段，可多选
- **搜索方式**：搜索框中输入的内容和**搜索字段**进行匹配时的判断规则，包括**等于**、**包含**、**开头是**、**结尾是**、**不搜索**五种搜索方式,默认为**包含**
::: tip
系统内置了部分常用的搜索规则，添加时可直接选用。内置规则可通过系统国际化配置进行修改，对应的国际化KEY是`dsn.searchrules.addItems`。
:::
## 自定义搜索面板{#settings}
在**属性栏**>**快速搜索**>**搜索**中，需要选择搜索的数据模型，勾选**自定义搜索面板**之后，可以配置更多的字段，且配置的字段都来源于**数据**中引入的数据模型，且字段信息可以在其他组件中引用.
- **标题字段**：选择搜索结果的数据后，在搜索框中显示的字段，只可单选，为空时搜索框默认显示**主键对应的文字字段**
- **描述字段**：作为**标题字段**的额外补充信息，显示在每条搜索结果的下方，可辅助用户准确选择搜索结果。描述字段可多选，为空时不显示，当选择多个字段时会按照字段的默认顺序排列，通过鼠标悬停的方式可查看详细信息
- **数据格式**：控制**搜索面板**中数据条目的呈现格式
- **移动端浮动显示候选项**：默认不勾选，移动端使用快速搜索时，会弹出二级页面展示搜索候选项；勾选该项后，候选项以浮动形式展示
- **浮动显示候选项条件**：当搜索的候选项以浮动的形式展示时，设置该项，可调整候选项可展示最大条目数
:::tip
快速搜索组件的搜索结果列表仅展示前10条数据，搜索结果是按照数据模型中的数据默认顺序排序的。如需更准确的定位数据，可通过逻辑匹配字符对多个关键字进行拼接，并以空格或'|'分隔，如：`湖北 武汉`代表搜索字段数据中含有'湖北'与'武汉'，`湖北|武汉`则代表含有'湖北'或'武汉'，具体可参考：[逻辑匹配](../../../../exp/types.md#logic-match)
:::
## 快速搜索与搜索框的区别{#difference}
快速搜索组件与[搜索框](./searchinput.md)组件都可以通过输入关键字的方式进行数据过滤，但快速搜索组件在输入关键字后会弹出搜索结果的浮动框，可辅助用户更准确的选择输入内容，再根据选择的结果进行数据过滤，如通过选择具体的企业名称过滤出该企业下的人员信息。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/richtextinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/richtextinput"
title: "SuperPage组件-富文本输入"
---
---
order: 16
navTitle: 富文本
---
# SuperPage组件-富文本输入
富文本编辑器是所见即所得的文本编辑器，可输入文字，上传图片、视频、附件、表格等内容，可以方便用户编辑文章、通知公告等：
示例地址：[富文本输入](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AF%8C%E6%96%87%E6%9C%AC)
## 使用富文本输入组件{#use}
富文本与Microsoft Word编辑功能类似，可设置多种文本格式，同时支持打印、预览等功能。提交数据与显示数据时需要搭配其它组件一起使用。
具体操作步骤如下：
1. **拖入富文本：** 在**组件区**>**输入**分组下将**富文本**组件拖入到画布中
2. **设置提交数据：** 在**富文本输入**>**数据**中勾选[提交数据](../../design/submit-data.md)，绑定存储富文本内容的clob字段，如`正文信息`，并在保存按钮组件中添加**提交表单**交互。
3. **设置附件存储：** 若需要上传图片、视频、附件，则需要勾选**允许插入图片**与**启用附件**属性，并绑定数据集，以及设置如下属性：
- [数据集](#启用附件)：选择`上传附件_富文本`数据模型
- [附件ID](#启用附件)：选择`附件唯一标识`字段
- [文件名](#启用附件)：选择`附件名称`字段
- [业务键](#启用附件)：选择`资源ID`字段，并设置对应计算公式
如果不指定独立的附件存储表，依旧可以上传图片，图片会以html内的base64编码方式存储，适合存储少量的小图片，但不支持上传视频和附件。
4\. **查看界面编辑富文本内容：** 在查看界面的富文本中输入文字信息、图片、视频等内容后，点击保存按钮即可将富文本数据提交到模型表中
富文本输入的内容存储的数据格式为html，在页面上显示富文本输入的内容，可以使用[HTML](../embed/embedhtml.md)组件。在**组件**>**数据**>**HTML来源**选择**字段**，在弹出的字段中选择存储富文本内容的clob字段，如`正文信息`即可。
## 属性介绍{#attribute}
### 启动附件{#startup}
当需要在富文本中上传附件或视频时，需要勾选**启用附件**并进行以下设置：
1. 选择用于存储附件的数据表，由于一个富文本可以包含多个附件，所以用于存储附件的表是一个独立的模型表，和存储富文本HTML的表分离，这两个表会自动使用附件ID字段进行关联
2. 在以下附件属性设置中进行对应设置，其中附件ID、文件内容、业务键为必填项。
- **附件ID**：用于存储上传附件的主键，必填项
- **文件名**：用于存储上传附件的文件名称，系统自动处理获取上传文件的名称。当点击附件下载时，会显示对应附件的名称，对于上传附件为必填项，若只需上传图片可选填
- **文件内容**：用于存储富文本中视频、附件以及图片当作附件存储时的文件内容，必填项。文件内容的存储方式由字段类型决定，提供了两种字段类型：
- blob字段：存储附件内容对应的的二进制内容，必须设置[附件角色](../../../../data-gov/model/field-role.md)
- 字符字段：存储附件在服务器工作目录下的相对路径，相对路径为`attachments/is7uMHE4jIIBRe7qs06gRG/PATH/附件ID`，必须设置[附件角色](../../../../data-gov/model/field-role.md)
- **大小限制（MB/个**）：可限制上传的图片、视频与文件的大小，当上传附件超过该限制大小时，会弹出提示
- **上传类型**：可限制上传附件文件的类型，支持无限制、图片、语音、视频、文档以及自定义
- **业务键**：用于存储与该附件相关业务数据的ID，相当于外键，将附件内容与相关业务数据关联
- **计算公式**：用于计算业务键的值，一般是富文本绑定模型对应主键ID的值
启用后富文本输入框的工具栏会出现对应插入视频与文件的按钮。上传的图片、视频和附件会存储在附件表，在HTML中只会记录附件的ID。
### 允许插入图片{#insertpic}
当需要在富文本中上传图片时，需要勾选**允许插入图片**，可使用以下两种方式存储：
1. 以base64编码方式直接存储在富文本HTML中，可直接上传图片，不需要其它设置
2. 图片较大时，可作为附件存储，需要勾选**图片当作附件存储**属性，其它设置与启用附件中一致
允许后富文本输入框的工具栏会出现插入图片的按钮，使用附件存储图片时，上传的图片会存储在附件表中。使用图片方式直接上传图片时会以图片原图显示，使用附件方式上传图片则以链接形式显示。
### 工具栏设置{#toolbar}
富文本除一些基本工具之外，还可以根据需求自定义添加多种工具，如插入图片、插入视频、插入附件、插入表格等，勾选对应的工具，将在富文本上方工具栏处出现对应工具的图标。在**属性栏**>**样式**>**工具栏**中勾选即可：
## 应用场景{#scene}
### 文章管理{#article}
通过编辑富文本与显示富文本内容能够制作文章管理列表，通过新增与编辑按钮可对富文本内容进行新增和修改，保存按钮可提交富文本的数据到模型表中，点击列表标题可对富文本的内容使用HTML组件进行展示查看，具体制作方式可参考[提交数据](../../design/submit-data.md)，效果如下动图所示：
示例地址：[富文本-文章管理](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AF%8C%E6%96%87%E6%9C%AC)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/searchinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/searchinput"
title: "SuperPage组件-搜索框"
---
---
order: 16
navTitle: 搜索框
---
# SuperPage组件-搜索框
搜索框组件的功能与[文本输入组件](./textinput.md#submit)类似，可实现数据的快速过滤或提交。以快速过滤数据的功能为例，使用搜索框组件和[列表组件](../data/list.md)搭配使用，搜索企业的人员信息：
示例：[搜索框组件](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%90%9C%E7%B4%A2%E6%A1%86)
## 使用搜索框组件过滤数据{#filter}
使用搜索框组件过滤数据与[文本输入组件](./textinput.md#autofilter)类似，但无法选择**匹配模式**，默认是`包含`的过滤方式，因此常用于快速实现数据的模糊查询。
::: tip 更多
除了搜索框组件，[快速搜索组件](./searchbox.md)也可以实现更准确的数据过滤，两者的区别可参考[快速搜索与搜索框的区别](./searchbox.md#difference)
:::
## 使用搜索框组件提交数据{#submit}
搜索框组件**提交数据**的使用方法与其他输入组件**提交数据**的操作方式类似，勾选**提交数据**属性并设置**绑定字段**属性，可以将输入信息提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/fieldsfilter.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/fieldsfilter"
title: "SuperPage组件-字段过滤"
---
---
order: 17
navTitle: 字段过滤
---
# SuperPage组件-字段过滤
SuperPage提供了字段过滤组件，用于过滤数据。在查看界面用户可以动态的添加过滤字段，以及切换查询的操作符等。如使用字段过滤筛选企业列表信息的数据：
示例地址：[字段过滤](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AD%97%E6%AE%B5%E8%BF%87%E6%BB%A4)
## 使用字段过滤组件过滤数据{#filter}
字段过滤组件过滤的是数据模型的数据，将作用到所有使用此数据模型的组件。使用时需要为字段过滤组件绑定数据模型，并搭配其他展示数据的组件一起使用。以搭配列表组件过滤企业基本信息为例，如下是具体操作步骤：
1. **使用字段过滤组件**：在**组件区**>**输入**中将字段过滤组件拖入到布局中
2. **绑定字段过滤数据并设置字段**：在**字段过滤**>**数据**下选取添加的数据模型，并点击**设置字段**选择默认显示的字段及输入方式和操作符设置，见[可选字段设置](#field-settings)
3. **设置自动过滤**：在**字段过滤**>**数据**中勾选**自动过滤**
4. **设置显示条件及操作符**：在**属性栏**>**字段过滤**下可设置**总是显示“并且”和“或”**、**总是显示操作符**，见[运算条件设置](#operation-conditions)、[操作符设置](#operator)
### 字段过滤组件操作{#use}
在查看界面，可在字段过滤组件中修改操作符、运算条件、调整字段位置等：
- **添加字段**：点击字段前后的空白位置或者点击**添加**按钮，可添加过滤字段，需要勾选**允许动态添加条件**，见[动态添加条件设置](#add-condition})
- **删除字段**：点击输入框右上角的功能按钮选择**删除**可删除字段，需要勾选**允许动态添加条件**，见[动态添加条件设置](#add-condition})
- **切换操作符**：点击字段输入框前的操作符或者输入框右上角的功能按钮可切换操作符，需要勾选**允许切换操作符**，见[操作符设置](#operator)
- **调整字段位置**：拖动字段即可调整字段位置
- **修改”并且“和”或“关系”**：点击关系符"并且"和“或”，可切换运算关系，当为“或”关系时，或条件的内容会用括号括起来，需要勾选**允许“或”关系**及**总是显示“并且”和“或”**，见[运算条件设置](#operation-conditions)
- **转换成表达式模式**：当[允许转成表达式模式](#expression-filter)时，点击表达式模式可输入复杂的过滤条件表达式进行过滤
## 查询模板设置{#query-template}
使用字段过滤组件可以灵活添加多个字段组合用于过滤数据。当同一个组合条件频繁使用时，可以将这个组合条件保存为查询模板，在下次使用时加载保存过的组合条件，提高查询效率。如查询企业信息为例：
示例地址：[企业信息自助查询](https://demo.succbi.com/v5/DEMO/app/ap.app/%E6%A1%88%E4%BE%8B/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2.tpg?id=%E8%87%AA%E7%94%B1%E6%9F%A5%E8%AF%A2)
### 保存为查询模板{#save-template}
点击`保存查询模板`，在弹出的对话框中输入模板名称，即可将条件组合保存为查询模板，具体的实现思路如下：
1. 准备一个数据模型：提前准备好，用于存放模板的数据。记录查询模板的数据模型结构至少需要包含：
- 模板名称：在弹出对话框中输入的模板名称，一般建议带有业务意义的名称，方便下次使用
- 字段过滤查询条件：用于存储选择的哪些字段条件，系统将字段条件以json数组的形式进行保存，建议数据长度设置大一些
- 其它字段：其它需要存储到模型中的字段，例如**企业查询1**中，将输出数据项也保存在了模板中，示例[企业查询1](https://demo.succbi.com/v5/DEMO/app/ap.app/%E6%A1%88%E4%BE%8B/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2.tpg?id=%E4%BC%81%E4%B8%9A%E6%9F%A5%E8%AF%A21)
2. 保存查询的模板：
- 添加[对话框](../embed/dialog.md)组件：用于保存查询模板，包含一个[文本输入](./textinput.md)组件用于输入模板名称，一个确定[按钮](../common/button.md)组件提交数据，按照示例截图制作即可
- 使用[更新数据](../../design/action/update-data.md)交互：设置按钮的交互动作，其中数据使用的是上面准备的数据模型。数据范围选择为**当前查询结果**，具体的字段信息可以在【更新字段设置】属性中处理，具体可以查看[更新数据](../../design/action/update-data.md)交互
3. 添加一个[按钮](../common/button.md)，用于点击弹出对话框`保存查询模板`
### 载入查询模板{#loading-template}
点击`载入查询模板`按钮，在弹出对话框中选择对应的模板名称后即可载入对应的过滤条件进行过滤，具体的实现思路如下：
- 添加[对话框](../embed/dialog.md)组件：用户点击【载入查询模板】弹出该对话框，用于选择已存在的模板
- 列表展示保存的模板：对话框需要使用列表展示已经存入的查询模板，具体可查看[列表](../data/list.md)文档
- 设置选中后的交互：在**确定**按钮上使用[设置组件属性](../../design/action/set-component-property.md)的交互，并设置交互的属性：
- **选择组件**：为对应的过滤条件组件，如【字段过滤1】
- **属性名**：`value`
- **属性值**：获取的是存储字段过滤查询添加的列，使用[arr\_get()](../../../../exp/func/json/ARR_GET.md)函数查询出对应查询模板字段中存储的json数组的值，如表达式为`arr_get([列表2].[选中值].[字段过滤查询条件].[值],0)`
- 添加一个[按钮](../common/button.md)：用于点击弹出对话框`载入查询模板`
## 可选字段设置{#field-settings}
在**属性栏**>**字段过滤**中设置了数据属性后，会出现设置字段的选项。点击**设置字段**，在弹出的对话框中可以进行字段的设置，包括：**字段列表设置**、**字段属性设置**、**输入方式设置**等
### 设置可选的字段列表{#field-list}
字段过滤组件添加条件时，下拉列表自动显示了绑定数据集的所有字段，可以在设置字段对话框中进行设置调整：
- 显示哪些字段：在对话框左侧可以添加、复制、删除和移动字段，添加、复制、删除和移动字段只是修改字段列表中选择的字段信息，不会对数据模型的结构发生变化
- 默认显示的字段：添加的字段默认是不显示的，选中某个字段，在右侧的字段下，勾选**默认显示**即可。勾选后可设置默认值及操作符。操作符与字段类型相关：
- **字符型**：操作符包括**等于**、**包含**、**匹配**、**检索**、**为空**、**不为空**、**开头是**、**结尾是**、**不等于**、**不包含**、**不匹配**
- **日期型**：操作符包括**属于**、**不属于**、**包含**、**小于**、**小于等于**、**大于**、**大于等于**、**排除**、**为空**、**不为空**
- **数值型**：操作符包括**等于**、**小于**、**小于等于**、**大于**、**大于等于**、**范围**、**为空**、**不等于**、**不为空**
:::tip
当字段有[关联表](../../../../data-gov/model/README.md#associated-table)且**输入方**式为**下拉框**时，操作符为**属于**、**不属于**。
:::
### 字段属性设置{#field-properties}
选择对应字段名称，在对话框右侧可设置字段属性，包含以下内容：
- **字段**：即当前字段在数据模型中对应的字段
- **标题**：字段的显示标题，可自定义
- **输入方式**：设置当前字段的[输入方式](#input)，只有维度字段可设置，默认为**自动**
- **默认显示**：勾选**默认显示**后，在字段过滤中会显示默认当前字段，勾选默认显示后可设置**默认值**和默认**操作符**
- **数据格式**：即字段内容的显示格式，只有维度字段可设置，包含**标题**、**值**、**标题-值**
- **输入提示**：当输入框的内容为空时，在输入框内显示的提示信息
- **为空时包含所有值**：当未输入内容时，即过滤所有数据
- **校验**：当为度量字段时，可对输入的数据进行校验，可设置**校验公式**及**校验提示**
### 输入方式设置{#input}
选择对应字段名称，在对话框右侧字段属性中可设置每个字段的输入方式，包含以下几种方式：
- **自动**：默认为**自动**，根据字段类型自动判断为下拉框，日期，文本输入或数值，也可以手动设置
- **下拉框**：字段有[关联表](../../../../data-gov/model/README.md#associated-table)时可以选择，如【企业类型】。
- 如果没有关联数据表，会将该字段数据去重后显示在下拉列表中。当输入方式为**下拉框**时，可设置**允许多选**、**显示“全部”**、**允许清空**，可参考文档[下拉框-下拉框操作设置](./combobox.md#settings)。
- 当字段存在[关联表](../../../../data-gov/model/README.md#associated-table)时，可设置选项的显示内容及节点属性，包括**根节点**、**是否显示根**、**维项过滤**、**显示最大级次**，可参考文档[下拉框](./combobox.md#root)
- **日期**：日期型的字段，或者设置了字段角色为日期
- **文本输入**：字段或文本型的字段，如【企业地址】
- **数值输入**：数值型的字段，输入框中只能输入数值，如【注册资本】
## 动态添加条件设置{#add-condition}
在**属性栏**>**字段过滤**下可设置动态添加条件，允许添加字段、添加“或”条件、以及转成表达式模式进行过滤：
### 允许添加字段{#add-field}
勾选后在查看界面用户可以自由添加和删除过滤字段，该选项默认是勾选的：
- **删除字段**：点击每个字段右上角的功能按钮选择**删除**即可删除字段
- **添加按钮**：可设置添加按钮的显示标题，如`添加条件`，点击**添加按钮**可添加字段，添加的多个字段之间过滤条件为“并且”的关系。若勾选了**允许“或”条件**，添加字段时，可选择**添加为“或”关系的条件**
- **清空按钮**：可设置清空按钮的显示标题，如`清空`，点击**清空按钮**可清空字段过滤中的全部过滤条件，即查询全部数据
### 使用表达式模式过滤数据{#expression-filter}
字段过滤组件提供两种模式过滤数据：
- **字段选择模式**：即通过可视化的下拉框，或者输入框等形式选择字段内容过滤数据，在**字段选择模式**只支持“并且”和“或”关系的单层括号进行嵌套
- **表达式模式**：当**允许动态添加条件**后，可以转成表达式模式进行过滤，勾选**允许转成表达式模式**，点击**表达式**按钮可输入表达式进行过滤。
- 切换到**表达式模式**下，会自动将**字段选择模式**下的条件转成表达式，也可以继续输入复杂的表达式，例如多个“并且”和“或”关系的嵌套，`([企业名称] *= '武汉' OR [登记机关] in ('420000') OR [企业类型] in ('1000')) AND ([经营状态] in ('01') AND [注册资本(万元)] = '[1000~5000]' AND ([成立日期] <= '20200101' OR [核准日期] >= '20100101'))`
- 点击**返回**按钮，可切换成字段选择模式，并且可以设置**默认为表达式模式**及**显示表达式工具栏**
当设置了**允许转成表达式模式**，提供了更多属性：
- **默认表达式模式**：字段过滤默认为表达式模式，勾选后，点击**返回**按钮，可切换成字段选择模式
- **显示表达式工具栏**：勾选后当显示为表达式模式时，会显示表达式工具栏，可选择字段列表及添加操作符
### 运算条件设置{#operation-conditions}
多个字段过滤的运算关系可以设置为“并且”或“或”关系，可以嵌套，提供了如下属性设置：
- **允许“或”条件**：勾选后，当动态添加字段时，可在添加字段对话框中勾选**添加为“或”关系的条件**，默认勾选。“或”关系的条件会用括号括起来
- **总是显示“并且”和“或”**：勾选后，会在每个字段输入框前面显示当前字段与其他字段间的条件关系，点击“并且”和“或”可以切换运算关系
## 操作符设置{#operator}
在显示界面可允许切换操作符，在**属性栏**>**字段过滤**>**高级**下勾选**允许切换操作符**即可，点击字段选择框右上方的功能按钮或者当显示操作符时点击切换即可。\
可以设置总是显示操作符，在**属性栏**>**字段过滤**>**高级**下勾选**总是显示操作符**。当没有勾选该选项时，每个字段类型都会有一个默认的操作符，即操作符下拉框列表中的第一个选项，默认操作符会自动隐藏，切换为其它操作符时才会显示操作符。
:::tip
在字段设置对话框中当字段**默认显示**时，可设置默认显示的操作符。
:::
## 输入项宽度设置{#width}
可设置字段过滤组件中字段输入项的宽度，在**属性栏**>**字段过滤**>**输入项宽度**中即可设置输入框的宽度及标题宽度：
- **宽度**：即每个字段输入框的宽度，单位为px，输入大于0的整数即可。当未输入固定宽度时，系统会有一个默认宽度，在不同分辨率及大小屏幕上会自适应，可设置**最大宽度**
- **最大宽度**：当未输入固定宽度时，输入框宽度会自适应，但不能超过设定的最大宽度，单位为px，输入大于0的整数即可
- **标题宽度**：可设置为**自适应**、**像素**、**百分比**，同时可设置**最小/最大标题宽度**
## 输入组件样式设置{#style}
在**属性栏**>**样式**下可设置字段过滤组件的布局及输入组件的样式：
- **内部布局**：字段过滤组件内部布局默认为**横向**排列，可调整为**纵向**排列
- **对齐方式**：包含**左对齐**、**居中对齐**、**右对齐**
- **下拉框**：当[输入方式](#input)为下拉框时，设置下拉框的样式，下拉选择对应的风格即可，这里共用的是下拉框组件的风格，如果需要增加，需要在[下拉框](./combobox.md)的样式中进行管理
- **输入框**：当[输入方式](#input)为**文本输入**或**数值输入**时，设置文本输入或数值输入框的样式，下拉选择对应的风格即可，这里共用的是文本输入组件的风格，如果需要增加，需要在[文本输入](./textinput.md)的样式中进行管理
- **日期框**：当[输入方式](#input)为**日期**时，设置日期输入框的样式，下拉选择对应的风格即可，这里共用的是日期组件的风格，如果需要增加，需要在[日期](./datecombobox.md)的样式中进行管理
- **添加按钮**：当[允许动态添加条件](#add-condition)时，可设置添加按钮的样式，这里共用的是按钮组件的风格，如果需要增加，需要在[按钮](../common/button.md)的样式中进行管理
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/resselector.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/resselector"
title: "资源选择"
---
---
order: 18
navTitle: 资源选择
---
# 资源选择
spg提供了资源选择组件，以对话框方式选择系统内部资源，并将资源以路径或ID的方式存入数据模型中，如下：
[示例地址](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%B5%84%E6%BA%90%E9%80%89%E6%8B%A9)
## 使用资源选择提交数据{#start}
资源选择组件的提交数据和其它输入组件提交数据操作方式一致，勾选提交数据属性并设置绑定字段属性，可以将资源路径或ID提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。区别在于资源选择组件可以设置[返回值类型](#return-value)，以及[可供选择的资源类型](#optiontype)。
## 属性介绍{#properties}
### 返回值设置{#return-value}
在**高级**>**返回值**属性里，可以设置资源的返回值类型，系统提供了两种返回值类型：
- **路径**：文件存储的路径，可以右键点击文件，在**属性**里进行查看
- **ID**：文件的ID，在文件创建时会自动生成。同样可以在**属性**里进行查看
### 可选类型{#optiontype}
在**高级**属性里可以通过**可选类型**限制可供选择的资源类型，通过**根目录**限制开始寻找资源的根目录，具体如下：
- **可选类型**
- **分析**：可选项为.rpt和.dash文件，即仪表板和报表文件
- **模型**：可选项为.tbl文件，即模型表文件
- **表单**：可选项为.fapp文件，即表单文件
- **应用**：可选项为.app文件，即应用文件
- **根路径**：限制开始寻找资源的根目录，如：`/DEMO/ana/快速开始示例`，限制了只能从`/DEMO/ana/快速开始示例`下开始寻找资源
**可选类型**默认为全部类型，**根路径**不做限制时，默认展示系统里的所有目录。当限制了可选类型，但没有限制根路径时。如果某个目录下不存在对应类型的文件，则会显示一个空目录
## 业务场景{#business-scenarios}
资源选择组件可以配合其他输入组件使用，将`资源名称`、`资源类型`、`资源路径`等详细信息存储到数据库中。在列表里展示资源时，点击资源路径，查看资源详情，效果可参考上面的动图。具体实现思路如下：
1. 添加**文本输入**组件和**资源选择**组件，绑定提交字段，设置提交数据交互，将资源的详细信息提交到数据库中，可参考[文本输入组件](./textinput.md#submit)。
2. **资源选择**组件设置返回值类型为`路径`，限制可供选择的资源类型以及开始寻找资源的根目录
3. 添加一个**列表**展示所有的资源，在`资源路径`列上设置打开链接交互，链接到资源详情页面，并将`资源路径`作为参数传递到资源详情页面，可参考[列表的交互设置](../data/list.md#manifest)
4. 资源详情页面用一个[嵌入组件](../embed/README.md)，设置动态路径来展示资源详情，可参考[数据模型](../embed/embeddatamodel.md)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/upload.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/upload"
title: "上传附件"
---
---
order: 19
navTitle: 上传附件
---
# 上传附件
系统支持上传附件的功能，可以上传图片、音频、视频、文档等多种类型的文件。上传的文件可以以二进制的形式存在数据库中，也可以只在数据库中存储路径，而文件内容存储在磁盘文件系统。
## 使用上传附件组件{#start}
**上传附件**组件在提交数据时，需要设置附件存储的模型表，绑定提交字段，并和按钮组件搭配使用。上传图片组件和上传附件组件的功能类似，区别在于上传图片组件只能上传图片类型的文件。
[示例地址：list列表-增删改查-新增](https://demo.succbi.com/v5/DEMO/app/ap.app?id=列表)
操作步骤：
1. **拖入上传附件组件**：在**组件区**>**输入分组**下将上传附件组件拖入到画布中，并在**组件栏**>**标题**中设置标题为`企业信息附件`
2. **选择数据集**：在**组件**>**数据**>**数据集**里下拉选择用于存储附件的数据表`企业基本信息_附件`，并绑定需要提交数据的字段，系统可以自动记录额外的一些附件相关信息，例如`文件大小`，`文件名`等。具体可参考[上传附件数据存储](#dataStorage)
3. **设置提交数据**：勾选**提交数据**，可以限制上传附件大小、个数、类型等，可参考[上传附件限制设置](#limit)
4. **设置更多提交字段**：数据集中只存储了附件相关的字段，当需要记录一些系统字段，如`上传用户`等信息时，可以在**更多字段设置**中添加，点击加号按钮添加2个提交字段
- **上传用户**：目标字段选择`上传用户`，值输入表达式`$user.id`，[$user.id](../../../../exp/var/$user.md)函数用于获取当前用户id
- **企业内部序号**：目标字段选择`企业内部序号`，值选择参数栏的`企业内部序号`，或写表达式`[企业内部序号]`
5. **设置提交数据交互**：可参考[提交表单](../../design/action/set-component-property.md)交互
### 存储方式{#store}
系统提供了2种附件的存储方式：
- **磁盘存储**：当**文件内容**绑定的提交字段为**字符字段**时，上传的附件会存储在磁盘中，路径格式及场景说明参考[文件存储类型](../../../../data-gov/model/field-role.md#file)
- **数据库存储**：当**文件内容**绑定的提交字段为**blob字段**时，上传的附件会以二进制形式存储在数据库中
:::tip
无论哪种存储模式，均需要将**文件内容**属性绑定的字段设置为[附件角色](../../../../data-gov/model/field-role.md)。当上传文件后，还未点击提交按钮之前，数据是还未提交到数据库中的，这时数据是临时存储在服务器的`workdir/clusters-share/upload-files`目录下，且`upload-files`文件夹存储的临时文件会定期自动删除。
:::
### 设置附件多对一业务关联{#object-relational-mapping}
一个表单中可能会同时上传多个附件信息，例如企业信息的填报，会传多个企业的附件图片信息。
此时附件的数据是单独一个模型表存储的，在附件存储的模型表中，需要有一个外键存储企业信息模型的主键，在模型表上根据企业主键对附件表进行过滤。从而可以实现企业信息下总是只能显示该企业上传的附件信息，并且可以对这些附件进行增加、删除等操作
外键的设置需要单独在**上传附件**>**提交数据**>**更多字段设置**中增加，在这里设置的字段会存储到数据集设置的模型表中：
- **目标字段**：数据存储的目标字段，类似提交数据的绑定字段
- **值类型**：表达式
- **值**：提交到数据库的值，可以为固定值，也可以为参数值或控件参数值
除了外键信息，还可以增加额外的其它信息，如`上传用户`、`上传时间`等信息。
## 属性介绍{#properties}
### 上传附件数据存储{#dataStorage}
设置存储附件的数据表，附件组件可以同时上传多个附件，且会有附件的一些附加属性。所以用于存储附件的表是一个单独的模型表，在数据集中选择存储的模型即可，该下拉框选项是在数据中引入的数据模型。提供了如下属性设置：
- **附件ID**：当上传多个附件时，该属性为必填项，用于存储上传附件的主键，这个字段的数据是系统自动生成的唯一标识。当上传单个附件时，若表单界面已经设置了附件的主键输入信息，**附件ID**可以不填。
- **文件名**：选填，存储附件的文件名称，系统会获取上传的文件名称存储到该字段中。点击下载附件时，下载的附件名称也是该属性设置的值
- **文件大小**：选填，存储附件的大小，若指定了存储字段，系统会获取上传的附件大小并写入到该字段中
- **修改时间**：选填，存储该附件的最后修改时间
- **文件内容**：必填项，用于存储附件里的文件内容。文件内容的存储方式由字段类型决定，可参考[存储方式](#store)
### 上传附件限制设置{#limit}
当附件勾选了提交数据时，可以对上传的附件做一些限制，提供了如下设置：
- **上传类型**：可限制上传附件文件的类型，支持无限制、图片、语音、视频、文档以及自定义，自定义文件类型多个文件后缀名之间用英文逗号进行分隔，如：`doc,mp3,png`
- **大小限制（MB/个）**：可限制上传的图片、视频与文件的大小，当上传附件超过该限制大小时，会弹出提示
- **必须至少上传一个**：未上传附件时，无法进行提交，与必填项相似
- **允许提交多个附件**：允许同时上传多个附件，每个附件都是一条单独的数据进行存储
当不勾选提交数据时，附件组件可以展示上传的内容，可以进行预览和下载操作，但是不能上传。
| 类型 | 格式 |
| :---------| :-------- |
|图片|`pjp`、`jpg`、`pjpeg`、`jpeg`、`jfif`、`png`、`gif`、`bmp`、`svgz`、`ico`、`tif`、`tiff`、`webp`|
|语音|`mp3`、`wav`、`wave`、`ape`、`acc`、`cde`、`wma`、`mka`、`mid`|
|视频|`rm`、`rmvb`、`avi`、`mov`、`asf`、`mpeg`、`mpg`、`dat`、`navi`、`ifo`、`vob`、`wmv`、`asx`|
|文档|`doc`、`docx`、`xls`、`xlsx`、`ppt`、`pptx`、`pdf`、`txt`|
### 显示方式{#display}
上传的附件可以以缩略图或列表的形式显示，在**样式**>**显示方式**下可以选择
| 缩略图 | 列表 |
| :---------| :-------- |
|||
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/passwordinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/passwordinput"
title: "SuperPage组件-密码输入"
---
---
order: 21
navTitle: 密码输入
---
# SuperPage组件-密码输入
SuperPage提供了密码输入组件，和其它输入组件类似，可以将输入的内容提交到数据库中。密码输入组件中输入的信息会以`·`的形式加密显示，也可以切换明文显示。
示例地址：[密码输入](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AF%86%E7%A0%81%E8%BE%93%E5%85%A5%E6%A1%86)
## 使用密码输入组件提交数据{#submit}
密码输入组件的**提交数据**和其它输入组件**提交数据**操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，可以将输入信息提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。
## 属性介绍{#properties}
### 切换输入信息可见{#information-display}
密码输入组件中输入的信息默认以`·`的形式加密显示，也可以切换信息的显示状态，具体操作为：
- 在**密码输入**>**高级**里，勾选**允许切换密码可视**，勾选后密码输入框后会出现一个眼睛形状的图标，点击可以切换密码可视状态
## 常用密码校验规则{#validation-rules}
| 校验规则 | 校验公式 |
| :---------| :-------- |
|密码长度为8-20位|`LEN([密码.值])>7 AND LEN([密码.值])<21`|
|密码至少包含大写字母、小写字母、数字中的任意两种|`(if(REGEXP_MATCH([密码].[值],"[0-9]"),1,0) +if(REGEXP_MATCH([新密码].[值],"[A-Z]"),1,0) +if(REGEXP_MATCH([新密码].[值],"[a-z]"),1,0))>1`|
|密码长度为8-20位，必须包含字母和数字，支持部分特殊字符|`REGEXP_MATCH([密码].[值],'(?=.*([a-zA-Z].*))(?=.*[0-9].*)[a-zA-Z0-9-*/+.~!@#$%^&*_]{8,20}$')`|
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/signinput.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/signinput"
title: "SuperPage组件-签名"
---
---
order: 22
navTitle: 签名
---
# SuperPage组件-签名
**签名**组件，可以将签名信息以图片的形式提交到数据库中。常用于移动端的电子签名，例如电子文书中需要签名。以请假条的签名为例：
示例地址：[签名](https://demo.succbi.com/v5/demo-spg/%E7%AD%BE%E5%90%8D)
## 使用签名组件提交数据{#use}
与其他输入组件的提交数据方法类似，**签名**组件在提交时，需要绑定模型表中的字段，并搭配按钮组件一起使用。
1. **使用签名组件**：在**组件区**>**输入**中将**签名**组件拖入到布局中
2. **设置提交数据**：选中**签名**组件，在**签名**>**数据**中指定要提交到的模型表并绑定相应的字段
- **内容字段**：必填项，绑定字段的**字段类型**需要设置为**blob**，[字段角色](../../../../data-gov/model/field-role.md)设置为**附件**，用来记录签名的图片信息
- **修改时间**：绑定字段通常为**时间戳**类型，用来记录签名的修改时间
3. **设置提交按钮**：选中**按钮**组件，在**交互**中选择**提交表单**
以上步骤即可实现电子签名，同时提交到数据库中。更多的数据提交介绍可以查看文档[提交数据](../../design/submit-data.md)。签名信息提交到数据库以后，可以在电子文书中通过类似`<#image src=MODEL.CONTENT(对应签名的内容字段) width=3.5/>`的语句来引用签名信息达到展示效果。
## 属性介绍{#attribute}
### 设置签字屏幕方向{#signature}
- **签字屏幕方向**：用于设置电子签名时移动设备上默认是横屏还是竖屏签名。在**签名**>**高级**>**签字屏幕方向**中进行设置。提供了三个选项：
- 自适应：默认为该选项，在移动设备屏幕方向未锁定时，签字屏幕方向会随移动设备屏幕方向自适应调整
- 横屏：签字屏幕方向默认为横屏，不再适应移动设备屏幕方向调整
- 竖屏：签字屏幕方向默认为竖屏，不再适应移动设备屏幕方向调整
- **显示旋转屏幕按钮**：在**签名**>**高级**>**显示旋转屏幕按钮**中进行设置。默认不勾选，勾选后签名界面会多出一个旋转屏幕按钮，点击后可切换签字屏幕横屏竖屏展示。不受**签字屏幕方向**设置影响，点击旋转屏幕按钮总能修改当前**签字屏幕方向**。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/filtersviewer.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/filtersviewer"
title: "条件指示器"
---
---
order: 23
navTitle: 条件指示器
---
# 条件指示器
SuperPage提供了条件指示器的组件，用于显示其他组件上设置的过滤条件，也可以在条件指示器上删除已添加的过滤条件。
## 使用条件指示器{#start}
条件指示器需要结合其他过滤组件一起使用，在[指示条件](#indicative-condition)里选择过滤组件后：
- **显示已添加的条件**：在勾选的过滤组件上选择过滤条件，条件指示器上对应的会增加一个板块显示该过滤条件
- **删除已添加的条件**：在条件指示器上删除过滤条件，对应的过滤组件也会删除该过滤条件。
[示例地址](https://demo.succbi.com/v5/demo-spg/%E6%9D%A1%E4%BB%B6%E6%8C%87%E7%A4%BA%E5%99%A8)
操作步骤：
1. 在**组件区**>**输入组件**里，拖入一个条件指示器组件到画布中，并设置标题为`所有分类`
2. 在**条件指示**>**指示条件**下拉框里勾选需要展示过滤条件的组件
## 指示条件设置{#Indicative-condition}
在**条件指示**属性栏>**指示条件**属性的下拉列表中，显示了当前页面中所有的过滤组件，被勾选的组件产生的条件会显示在条件指示器上。
## 条件指示器样式设置{#style-setting}
在样式属性栏提供了面板和选项的样式设置：
- **面板**：设置整个条件指示器组件的样式。包括标题、边距、条件样式等。
- **选项**：设置每个过滤条件的样式。包括字体、背景填充、圆角等。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/datedialog.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/datedialog"
title: "SuperPage组件-日期对话框"
---
---
order: 25
navTitle: 日期对话框
---
# SuperPage组件-日期对话框
SuperPage提供了日期对话框组件，可以与按钮组件组合实现弹出日期对话框，选择的日期数据可用于过滤数据，如下动图所示：
## 使用日期对话框组件过滤数据{#filter}
日期对话框是由用户的交互触发而显示，比如点击按钮后弹出日期对话框，选择某个时间后过滤列表数据。使用日期对话框过滤数据主要有两个操作步骤:
1. 设置日期对话框自动过滤
2. 弹出日期对话框
**操作步骤：**
1. **拖入日期对话框组件：** 在**组件区**>**输入**中将日期对话框组件拖入到画布中
2. **设置日期对话框自动过滤：** 在**属性栏**>**日期对话框**>**数据**中勾选**自动过滤**，在条件字段中选择`销售日期`，并设置日期类型等，更多设置查看[日期数据设置](#settings)
3. **弹出日期对话框：** 在`选择日期`按钮上设置[显示对话框/悬浮面板](../../design/action/show-dialog.md)交互，**对话框组件**选择对应的日期对话框，如`日期对话框2`即可
## 使用日期对话框提交数据{#submit}
日期对话框组件自身不具有提交数据功能，若需要提交数据则需借助[更新数据](../../design/action/update-data.md)交互事件，将日期对话框中选择的日期数据更新到模型表中来实现提交数据。
## 日期数据设置{#settings}
在**日期对话框**>**数据**下可以限制日期对话框的显示内容，包括：
- **类型**：提供了多种类型设置。例如选择了年，则对话框中只能选择年份。
- 选择为自动：当选择为自动时，则与模型表中字段的自动显示格式对应
- 非自动的其它类型：可以设置**最早**和**最晚**，用于限制可选范围
- **默认值**：日期对话框默认选中的时间，可以写固定值或者[表达式](../../../../exp/README.md)，默认值的选择是和类型联动的
## 日期对话框显示方式{#display}
日期对话框支持两种显示方式，显示模式是根据访问设备自动适配的：
- **PC端**：以对话框方式显示
- **移动端**：底部弹出的面板方式显示
|PC端|移动端|
|--|--|
|||
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/input/treeselector.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/treeselector"
title: "SuperPage组件-选择列表"
---
---
order: 26
navTitle: 选择列表
---
# SuperPage组件-选择列表
SuperPage提供了选择列表组件，能以树的形式展示数据，可用于提交或过滤数据。
示例地址：[选择列表](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E9%80%89%E6%8B%A9%E5%88%97%E8%A1%A8)
## 使用选择列表组件过滤数据{#filter}
使用选择列表组件过滤数据有2种方式：
- **自动过滤数据：** 勾选数据中**自动过滤**，并绑定**条件字段**，如`销售单位`，此时系统会自动以选择列表选中的值为过滤条件过滤数据，常与[列表](../data/list.md)组件搭配使用，具体可参考[下拉框-自动过滤](./combobox.md#autofilter)
- **过滤数据模型的数据：** 当选择列表中的数据与模型表的数据无关联时，即使用枚举值，此时若需要过滤数据则可在模型上设置过滤条件，可参考文档[使用勾选框过滤数据](./checkbox.md#filter)
## 使用选择列表组件提交数据{#submit}
选择列表组件的提交数据与其它输入组件提交数据操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，可以将选中或勾选的信息提交到数据库中，具体可参考[文本输入组件](./textinput.md#submit)。
当多选时提交的多个值之间以逗号分隔存储在字段中，若展示数据时需要与对应[关联表](../../../../data-gov/model/README.md#associated-table)关联，且给字段设置[字段角色](../../../../data-gov/model/field-role.md#values)为**多值**。
## 可选项设置{#options}
选择列表的显示内容需要设置可选项，有如下两种设置方式：
1. **枚举值**：当模型表原有数据不满足需求时，可以使用枚举值手动添加数据，具体操作可参考下拉框中的[下拉列表为枚举值](./combobox.md#options)
2. **模型表**：当选择列表的数据在模型表中时，可直接选择对应的模型表，在**可选项**的下拉列表中会显示当前页面中添加的数据模型以及模型中对应的关联维表，并且可以设置列表选项的显示内容及节点属性等
- **选择列表内容设置**：选择列表内容设置与下拉框中[下拉内容设置](./combobox.md#field)一致，同时可以勾选**允许搜索**属性，勾选后顶部出现搜索框可对列表选项进行搜索
- **根节点设置**：当**可选项**设置的数据表带有层次时，可对根节点进行设置，与下拉框中的[根节点设置](./combobox.md#root)一致
- **选择列表内容设置**：选择列表内容设置与下拉框中[下拉内容设置](./combobox.md#field)一致，同时可以勾选**允许搜索**属性，勾选后顶部出现搜索框可对列表选项进行搜索
- **根节点设置**：当**可选项**设置的数据表带有层次时，可对根节点进行设置，与下拉框中的[根节点设置](./combobox.md#root)一致
- **维项过滤设置**：使用**维项过滤**属性可对选择列表选项内容进行过滤，与下拉框中的[维项过滤设置](./combobox.md#dimension-filtering)一致，同时选择列表还支持隐藏子节点为空的父节点，勾选**隐藏空的父节点**属性即可
- **显示最大级次**：选择列表中显示带有层次的数据时，可设置**显示最大级次**属性，与下拉框中[显示最大级次](./combobox.md#level)一致
- **显示统计数**：在选择列表中可显示按**统计字段**统计的选项数据总数，与下拉框中的[显示统计数](./combobox.md#statistics)一致，同时选择列表提供了按照统计字段排序的功能，在**显示统计数**>**排序**属性设置即可
## 显示多列数据{#display-data}
选择列表支持显示多列数据，形成一个能展开折叠、搜索、勾选的可操作列表。在**属性栏**>**选择列表**>**可选项**中勾选**显示多列数据**属性，并对**子项设置**即可，子项设置与列表设置列类似：
- **设置显示列**：选择列表根据需求添加显示列，操作可参考列表组件的[设置显示哪些列](../data/list.md##manifest)，可以勾选**是否参与搜索**，若勾选则此列在搜索范围内，与之匹配的内容会被特殊颜色标注
- **列的样式设置**：可分别对列的标题行与数据行进行样式设置，可参考列表组件的[列的样式设置](../data/list.md#line-style)
- **根据条件显示隐藏列**：可根据条件显示隐藏不同的列，可参考列表组件的[根据条件显示隐藏列](../data/list.md#condition)
- **列的交互设置**：选择列表中也可为列设置事件交互，可参考列表组件的[列的交互设置](../data/list.md#line-setting)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/mobile"
title: "移动组件"
---
---
order: 7
navTitle: 移动
---
# 移动组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/mobilegrid.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/mobile/mobilegrid"
title: "SuperPage组件-宫格"
---
---
order: 1
navTitle: 宫格
---
# SuperPage组件-宫格
宫格组件可以快速实现手机移动应用常见的网格功能板块布局效果，如下图：
示例：[宫格组件](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E5%AE%AB%E6%A0%BC)
## 使用宫格组件{#start}
有两种方式设置宫格组件内的单元格：
- **数据集**：宫格内显示多少单元格由数据集的数据决定，这种方式多用于设计动态内容的宫格
- **自定义**：宫格内显示多少单元格由设计者在制作SuperPage的时候自己增加，也可以通过显示条件动态控制单元格显示隐藏，这种方式多用于宫格相对固定变化不多的场景
## 自定义宫格内容{#start-custom}
当宫格内的单元格相对固定、变化不多时，推荐自定义设置宫格内容，可以在制作SuperPage的时候添加好要显示的单元格，设置好每个单元格的位置、图标、标题等信息：
1. **拖入宫格组件**：在**组件区**>**移动**分组下将**宫格**组件拖入到画布中
2. **设置单元格的内容**：在**属性栏**>**宫格**>**数据类型**中选择**自定义**，点击**编辑单元格**弹出对话框，可以添加多个**单元格**并分别设置内容
- **添加单元格**：点击对话框左侧的**添加**按钮添加单元格
- **设置单元格属性和交互**：选中单元格后右侧可设置属性以及[交互](../../design/action/README.md)动作。
### 单元格设置{#editcell}
在**宫格**>**数据**中，点击**编辑单元格**可以自定义设置宫格内容，包括每个单元格的属性以及交互动作。
单元格属性中可设置每个单元格的内容、描述、角标等信息，下图是属性设置对应的界面效果：
- **内容**：标题，可输入固定值或动态的宏表达式
- **描述**：描述信息，标题的补充说明，也可用于展示某些统计数字，可输入固定值或动态的宏表达式
- **角标**：统计数字，可输入固定值或动态的宏表达式，一般用于提示该单元格代表的模块下有多少待办任务或未读消息等
- **图标**：图标信息，可使用系统内置的图标或用户自行上传的图标
- **填充**：背景填充，默认无填充，可选择颜色填充、图片填充或动效填充
单元格[交互](../../design/action/README.md)中可设置每个单元格的[交互](../../design/action/README.md)动作。**宫格**组件一般会起到页面导航的作用，因此，单元格的[交互](../../design/action/README.md)动作通常会使用[打开链接](../../design/action/linkto.md)交互来实现效果。
:::tip
角标中的数字通常使用宏表达式来动态显示，常用于提示该模块下有多少未读消息或待办任务等，希望为0时不显示角标可使用如`${IF(角标数字 = 0,NULL,角标数字)}`的表达式来达到效果。
:::
## 宫格布局和样式设置{#cell-setup}
在**属性栏**>**宫格**中可设置宫格的布局属性：
- **宫格间隙**：控制单元格之间的间距
- **宫格列数**：控制一行中显示几个单元格
- **宫格高度**：用于统一设置单元格的高度
### 宫格样式设置{#cell-style}
在**属性栏**>**样式**中，可设置**宫格**和**单元格**的样式：
- **宫格**：可设置宫格的背景填充、边框、圆角等，作用于宫格组件整体
- **单元格**：可设置单元格的文字字体、填充、边框等，作用于宫格组件内所有单元格
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/mobilelist.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/conponment/mobilelist"
title: "SuperPage组件-移动列表"
---
---
order: 2
navTitle: 列表
---
# SuperPage组件-移动列表
移动列表组件用于在移动布局中展示多行数据，配合输入组件（如下拉框、日期框）可实现动态查询过滤数据。
## 使用移动列表组件{#start}
使用移动列表组件主要进行两个设置：
- 绑定要显示的数据集
- 设置要显示的字段
下面以显示企业基本信息的列表为例，介绍具体的操作步骤：
- **拖入列表组件**：在**组件区**>**移动**分组下将**列表**组件拖入到画布中
- **设置移动列表数据**：在**属性栏**>**移动列表**>**数据**中引用`企业基本信息`，列表划分了几个显示区块，包括**标题字段**、**时间字段**、**状态字段**、**数量字段**等，可以按需设置，见[列表设置](#field-setting)
- **设置显示更多字段**：除了列表数据显示的字段外，可以通过**添加更多字段**的方式，添加更多的显示内容
- **设置列表样式**：在**属性栏**>**样式**>**列表**下可设置每个字段的风格
## 列表设置{#field-setting}
在**属性栏**>**移动列表**>**数据**中可配置列表中显示的字段信息：
- **标题字段**：显示在最上面内容，一般为为主键对应的文字字段，如【企业名称】
- **时间字段**：表示这个数据的时间状态，显示在标题右侧
- **状态字段**：显示在标题下方一行，可以是选择多个字段并排显示，表示这个数据的状态，比如“正常”、“停业”、“加急”，可以是一个[多值](../../../../data-gov/model/field-role.md#values)维键
- **数量字段**：一般为度量，用于显示某个指标值，如【注册资本】
- **图标字段**：如果显示图标，可以设置图标字段，显示在标题左侧
- **更多字段**：勾选**显示更多字段**后可添加更多字段，输入标题并选取对应字段即可。可添加多个字段，显示在标题及状态字段下方，一个字段一行
## 列字段的样式设置{#field-style}
在**属性栏**>**样式**>**列表**下可以设置列表中[显示字段](#field-setting)的风格，当需要标注特殊值时，可**配置特殊状态样式**，如**企业状态**的值为**存续**时，显示为`标题2`的样式，**在业**时显示为`标题3`的样式：
:::tip
每个字段下拉的样式共用的是[单行文本](../common/text.md)的样式，如果需要增加，需要在单行文本的样式中进行管理。
:::
## 列表的交互设置{#list-action}
在**属性栏**>**移动列表**>**高级**下可设置列表的交互操作，可实现数据的下拉刷新数据、上拉加载数据等效果：
- **显示箭头**：勾选后，会显示一个向右的箭头，当点击列表可以打开链接钻取查询详细信息时可以勾选显示箭头
- **显示勾选框**：勾选后，在列表左侧会显示一个勾选框，一般搭配[交互](../../design/action/README.md)动作使用，如删除数据
- **下拉刷新**：当在列表顶部时，下拉列表可刷新数据
- **上拉加载**：当列表滚动到页面底部时，上拉列表可加载更多数据
### 操作按钮设置{#setting-button}
可添加列表操作按钮，勾选**显示操作按钮**后点击**配置操作按钮**在弹出的配置对话框中可添加：
选中添加的按钮，在设置操作按钮对话框的右侧，可以设置该按钮的内容和交互。具体属性内容如下：
- **内容**：设置按钮的显示标题
- **显示位置**：设置按钮在列表上的显示位置，可选**右边**、**右下角**、**侧滑**，当为**侧滑**时可输入**确认标题**，如侧滑删除数据，滑动后显示**确定删除此条数据吗？**，点击确认标题后即可删除数据
- **按钮风格**：下拉选择按钮的样式，共用的是[按钮](../common/button.md)组件的样式，如果需要增加，需要在[按钮](../common/button.md)的样式中进行管理
- **图标前缀**：给按钮添加图标前缀，可设置图标的颜色及大小等
- **显示**：设置该按钮在满足一定条件时是否显示，可使用[表达式](../../../../exp/README.md)
- **禁用**：设置该按钮在满足一定条件时是否启用发生交互，可使用[表达式](../../../../exp/README.md)
- **交互**：设置对应按钮可触发的交互动作，可参考文档[交互](../../design/action/README.md)
### 搜索框{#searchbox}
勾选**显示搜索框**后会在列表上方出现一个搜索框:
- **占位符**：即搜索框内容为空时默认显示在搜索框内的信息
- **搜索字段**：对列表数据搜索的内容设置，可对允许搜索的字段进行关键字搜索，符合条件的内容会高亮显示
## 列表样式设置{#style}
在**属性栏**>**样式**下可设置列表和数据行的样式：
- **列表**：包括填充、内边距、外边距、[字段列表风格](#field-style)
- **数据行**：包括填充、边框、圆角、内边距等
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/mobilecelllist.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/conponment/mobilecelllist"
title: "SuperPage组件-移动设置列表"
---
---
order: 3
navTitle: 设置列表
---
# SuperPage组件-移动设置列表
设置列表组件可以快速实现手机移动应用常见的列表功能布局效果，如下图：
## 使用列表组件{#start}
**设置列表**是通过设置项对话框来进行管理的，可以增加、删除、调整位置等操作，每个设置项可以独立设置交互，系统还内置了一些常用的设置项，比如**修改密码**、**绑定手机**、**账号管理**、**我的消息**。具体操作步骤如下：
1. **拖入设置列表组件：** 在**组件区**>**移动**分组下将**设置列表**组件拖入到画布中
2. **设置列表选项：** 在**属性栏**>**设置列表**中，点击**设置列表**弹出对话框，可以添加多个设置项，并分别为每个设置项设置内容和交互等
- **添加设置项：** 点击左上角添加按钮，添加一个选项
- **设置交互：** 选中选项后，右侧可以设置属性以及[交互](../../design/action/README.md)动作
## 列表样式设置{#style}
在右侧**属性栏**>**样式**下提供了列表的标题、描述、提示、背景填充、单元格背景和线条的设置。
## 支持的子项类型{#settings}
在**属性栏**>**设置列表**，点击弹出的对话框中可自定义设置列表中选项，系统提供了多种类型的设置项，如下：
- **单元格：** 普通的单元格，可以设置**标题**、**描述**、**提示**等
- **文本：** 文本输入项，类似于[文本](../common/text.md)组件，可以在**内容**处输入想要显示的文本字段
- **按钮：** 按钮功能项，类似于[按钮](../common/button.md)组件，可以在**内容**中设置按钮显示的文本，此按钮可以搭配其他的交互完成相关功能
- **开关：** 开关功能项，添加后点击可以切换开关状态，可以设置开关**标题**、**描述**、**提示**等，此开关可以搭配其他的交互完成相关功能
- **间隔：** 用于隔开上下两个功能，调整优化布局
- **系统功能：** 系统提供了四个内置功能
- **修改密码：** 可以修改当前用户的登录密码
- **绑定手机：** 绑定后，可以使用手机号码+验证码的方式登录
- **账号管理：** 可修改当前用的登录账号的用户名
- **我的消息：** 内置的消息模块，可以接收系统下其它模块推送的消息，包括全部、公告、通知、催办、待办、私信等
- **目录：** 可以无限设置多级目录和内容
根据设置项的不同，系统会生成不同属性栏选项，这些类型的修改是不能单独设置某个列表的样式设置，需要在**属性栏**>**样式**统一设置。具体内容设置如下：
- **标题：** 设置选项标题，**文本**、**按钮**、**间隔**和**系统功能**不可设置
- **描述：** 为选项添加一段描述字段，**文本**、**按钮**、**间隔**和**系统功能**不可设置
- **提示：** 为选项添加一段提示信息，**文本**、**按钮**、**间隔**、**开关**和**系统功能**不可设置
- **图标：** 在选项前面添加一个图标，**文本**、**按钮**、**间隔**和**系统功能**不可设置
- **内容：** 在选项中填写显示内容，仅**文本**和**按钮**可填写
## 子项交互设置{#interactive}
**设置列表**中每个设置项的交互都可以单独设置，和其它组件的交互设置功能一致，可以参考[交互](../../design/action/README.md)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/filterbar.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/conponment/filterbar"
title: "SuperPage组件-字段过滤（移动设备）"
---
---
order: 5
navTitle: 字段过滤
---
# SuperPage组件-字段过滤（移动设备）
在移动端可以使用移动字段过滤组件过滤数据。
示例地址：[字段过滤](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E5%AD%97%E6%AE%B5%E8%BF%87%E6%BB%A4)
## 使用移动字段过滤组件过滤数据{#filter}
字段过滤组件过滤的是数据模型的数据，将作用到所有使用此数据模型的组件。使用时需要为字段过滤组件绑定数据模型，并搭配其他展示数据的组件一起使用。以搭配列表组件过滤企业基本信息为例，如下是具体操作步骤：
1. **使用移动字段过滤组件**：在**组件区**>**移动**中将**字段过滤**组件拖入到布局中
2. **绑定字段过滤数据并设置字段**：在**字段过滤**>**数据**下选取添加的数据模型，并点击**设置字段**添加[过滤字段](#setting-field)及[字段属性设置](#properties)、或[添加操作按钮](#operate-button)
3. **设置自动过滤**：在**字段过滤**>**数据**中勾选**自动过滤**
## 过滤字段设置{#setting-field}
### 显示哪些字段{#display}
自动字段过滤组件不会自动将数据集字段显示在字段列表中，需要在**属性栏**>**字段过滤**>**数据**下绑定数据模型后，点击**设置字段**可设置字段过滤中显示的字段。添加的字段，根据字段类型提供的属性有差异，参考[字段属性设置](#properties)。\
在弹出的对话框中，可以点击**添加**按钮添加字段；或点击下拉菜单，选择数据集中的字段，也可以点击**复制**按钮，进行添加：
:::tip
字段标题默认`字段1`、`字段2`，若选择了模型表中的字段则标题为字段名称，在字段属性中修改字段**标题**即可
:::
### 字段属性设置{#properties}
每个字段都有2个默认属性：
- **字段**：数据过滤字段，下拉列表中显示的是引入的数据模型所有字段
- **标题**：显示在顶部的选项标题，当选择了字段后，标题默认为字段名称，可自定义修改
字段类型不同，属性之间存在差异，分为如下几类：
1. 设置了[关联表](../../../../data-gov/model/README.md#associated-table)的字段：可以设置**维项过滤**、**显示方式**、是否**允许多选**，**显示全部**等，可参考[下拉框](../input/combobox.md#settings)
2. 日期字段：无其他属性，通过日期选择框的形式选择一个日期进行过滤
3. 数值型字段：默认是输入区间，可设置**最低输入区间提示**、**最高输入区间提示**
4. 其他字段：字段是字符串、没有设置[关联表](../../../../data-gov/model/README.md#associated-table)、不是日期角色等，只能输入关键字进行过滤
也提供了一些通用属性设置：
- **默认值**：默认的筛选条件设置，可以下拉选择固定值或者[表达式](../../../../exp/README.md)获取
- **占位符**：当字段为非数值型时，可设置占位符。当未输入内容时，默认显示的内容
- **显示方式**：当字段有[关联维表](../../../../data-gov/model/README.md#associated-table)时，选项的显示方式
- 自动：条目少于50时自动平铺，否则列表显示
- 列表：支持单级和多级
- 平铺：可一级分组
### 搜索设置{#search}
当字段类型设置了[关联表](../../../../data-gov/model/README.md#associated-table)时，选择过滤条件时可对维项列表数据进行搜索，勾选**允许搜索**即可，默认不勾选：
- **搜索框占位符**：搜索框内部当未输入内容时，默认显示的内容
- **最近搜索**：根据搜索时间降序显示，最近一次搜索的维项排在最前面。有搜索内容时才显示最近搜索，没有不显示
- **常用**：默认显示选择频率排名前10的，根据使用频率降序显示
- **最近搜索风格**：显示最近搜索的的内容上的样式风格，这里共用的是[文本输入](../input/textinput.md)组件的风格，如果需要增加，需要在文本输入的样式中进行管理
## 添加操作按钮{#operate-button}
### 添加排序{#rank-menu}
排序有两种体验，一种是多个字段排序选择，一种是按某个字段排序。排序菜单用来实现前者，排序按钮是实现后者。
- 排序菜单：在排序菜单中用于添加多个不同的排序字段，对数据进行动态排序。排序菜单可以添加到**字段列表**中和[按钮](#button)下面，排序菜单下面只能添加**排序按钮**
- 排序按钮：根据排序依据对字段进行排序，出现在字段列表上时是带有上下箭头的按钮，不能直接添加到[按钮](#button)下面，只能添加到[排序菜单](#rank-menu)和字段列表中
**排序依据设置**
- **默认值**：默认排序的依据，可选**无**、**升序**、**降序**
- **排序方向**：**降序、升序切换**、**升序、降序切换**、**仅升序**、**仅降序**
### 添加按钮{#button}
点击按钮可以执行交互动作，按钮下面添加[过滤字段](#setting-field)或[排序菜单](#rank-menu)。如添加一个更多按钮，在按钮下方添加多个过滤字段，通过按钮实现展开收起的折叠效果。
## 过滤条件重置{#reset}
当字段过滤条件中有筛选条件时可点击**重置**按钮清空已选择的条件，可自定义重置按钮的显示文字，默认标题为**重置**。当字段过滤中未选择任何筛选条件时，重置按钮不可点击。在**属性栏**>**字段过滤**>**高级**下输入重置按钮的标题内容即可：
## 字段过滤布局设置{#layout}
当字段过滤组件中字段列表较多，超出组件大小时，会自动进行缩放排列，可添加横向滚动，拖动滚动条查看所有的字段列表，在**属性栏**>**字段过滤**>**高级**下勾选**横向滚动**即可：
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/mobile/switchbox.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/conponment/switchbox"
title: "switchbox"
---
---
order: 11
navTitle: 开关
---
# 开关
开关组件用于在移动布局中控制内容开启或关闭，与[单选框](../input/checkbox.md)组件使用方法一致。如下图所示：
示例地址：[输入组件](https://demo.succbi.com/v5/demo-spg/mobile/%E8%BE%93%E5%85%A5%E7%BB%84%E4%BB%B6)
## 使用开关组件提交数据{#submit}
开关组件的**提交数据**和其它输入组件提交数据操作方式一致，勾选**提交数据**属性并设置**绑定字段**属性，具体可参考[文本输入组件](../input/textinput.md)。但提交的内容与输入组件不同，开关组件只能将开关的返回值提交到数据库中，可查看[设置开关的返回值](#value)，**默认值**和**计算**只能控制开关的初始状态。
## 使用开关组件控制其它组件的显示{#display}
开关组件有开启和关闭两种状态，可以根据状态控制其它组件的显示隐藏。如开启上传免冠照时，才出现照片的上传内容。操作步骤如下：
1. 设置开关的返回值：**勾选值**与**未勾选值**均有默认值，可直接使用，具体可查看[设置开关的返回值](#value)
2. 设置开关控制的组件显示：在**上传附件组件**>**显示**属性中，将显示设置为`条件`，显示条件表达式为`[开关1].[值]='1'`，则开关开启时，才会显示上传免冠照的内容
## 设置开关的返回值{#value}
在**开关**>**输入**属性里可以指定开关的返回值，即当开启开关时与关闭时返回的值：
- 勾选值：默认值为1，开启时的返回值
- 未勾选值：默认值为0，关闭时的返回值
例如是否上传免冠照的开关，开启后返回值是1，可显示免冠照上传；未开启返回值是0，则不能上传免冠照。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/more/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/components/more"
title: "其它组件"
---
---
order: 8
navTitle: 其它
---
# 其它组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/more/qrcode.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/qrcode"
title: "SuperPage组件-二维码"
---
---
order: 5
navTitle: 二维码
---
# SuperPage组件-二维码
SuperPage中可以根据链接生成二维码图片，用户可以通过移动设备扫码访问链接，也可以长按识别二维码。如用户可以通过扫描二维码的方式快速访问SuccBI的demo：
示例地址：[二维码](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E4%BA%8C%E7%BB%B4%E7%A0%81)
## 使用二维码{#start}
在SuperPage页面中，使用二维码组件，可以根据url自动生成二维码图片，设置二维码的操作步骤如下：
1. **拖入二维码组件**：在**组件区**>**其他**分组下将二维码组件拖入到画布或者某个区域
2. **设置二维码[**内容**](#内容)**：在**属性**>**二维码**>**内容**中，设置生成二维码的链接
通过上述步骤，即可实现根据url自动生成二维码。
## 属性介绍{#properties}
可以自定义生成二维码的背景、边框等样式。
### 内容{#content}
在**属性**>**二维码**>**内容**中，可以设置二维码的内容，通常设置为一个URL地址，同时也支持输入宏（如果宏返回的内容有特殊符号或中文，考虑使用表达式函数[ENCODEURI](../../../../exp/func/string/ENCODEURI.md)或[ENCODEURICOMPONENT](../../../../exp/func/string/ENCODEURICOMPONENT.md)进行编码），系统支持的地址类型有：
- **互联网URL地址**：以`https://`、`http://`、`//` 等开头的地址，如`https://www.succez.com`。
- **服务器绝对地址**：以`/`开头的地址（如果有上下文路径，需要自己带上上下文路径），如`/bi/DEMO/app/ap.app`，其中`bi`是应用上下文，如果用代理服务器把两个系统代理到了一个地址，但上下文不同，可以通过服务器绝对地址在应用间互相链接。
- **应用绝对地址**：相对于当前Web应用（tomcat）上下文的地址，如`DEMO/APP/ap.app`，可以访问当前应用下的资源，系统会自动补上上下文路径。可以是相对于根的地址。
- **相对当前页面地址** 以`./`或`../`开头，如当前地址是`http://host:port/context/DEMO/APP/ap.app`，应用相对地址为`./index.tpg`，则完整URL地址为`http://host:port/context/DEMO/APP/ap.app/index.tpg`。
### 动态生成二维码{#dynamic}
二维码组件可以和文本输入组件搭配使用。如在文本输入组件中输入`http://www.succez.com`，二维码组件中会根据此链接自动生成二维码。
- 在文本输入组件**属性**>**交互**中，添加**设置组件属性**的交互
- **选择组件**中下拉选择二维码组件，**属性名**设置为value，**属性值**设置为`[组件名称].[值]`
通过上述步骤，即可实现动态生成二维码。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/components/more/timer.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/component/timer"
title: "SuperPage组件-计时器"
---
---
order: 8
navTitle: 计时器
---
# SuperPage组件-计时器
SuperPage提供了计时器组件，可以实现倒计时、秒表和定时循环等，如下图：
示例地址：[计时器](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%AE%A1%E6%97%B6%E5%99%A8)
## 使用计时器组件{#start}
计时器是一个“虚拟”组件，没有界面，在设置的时长内，按设置间隔定时触发在计时器上设置的[交互](../../design/action/README.md)动作，配合其他组件可以完成特定的效果。同时计时器状态也会发生变化，从而实现计数功能，状态包括秒表的秒数或倒计时剩余的秒数、当前时间、激活状态、触发次数等。
**操作步骤：**
1. **拖入计时器组件：** 在**组件区**>**其它**中将**计时器**组件拖入到画布中
2. **计时器设置：** 在**属性栏**>**计时器**下，选择计时器的类型为`秒表`，时长为`5`秒，间隔为`1`秒，更多设置查看[计时器设置](#settings)
3. **显示计时器时间：** 拖入[文本](../common/text.md)组件，设置内容为`${[计时器1].[秒]}`，文本会自动获取计时器返回的数据，并实时发生变化，更多效果查看[应用场景](#application)
## 计时器设置{#settings}
在**属性栏**>**计时器**中可对计时器的**类型**、**时长**、**间隔**、**启动方式**进行设置，可实现不同效果的计时器。
### 计时器类型{#type}
计时器支持**倒计时**、**秒表**和**自动循环**三种计时类型。在**计时器**>**类型**中设置：
- 倒计时：在设定的时长内按照间隔进行倒计时，直到时间为0秒时停止计时，可设置时长与间隔
- 秒表：从0秒开始计时，按照间隔显示时间直到设置的时长时停止计时，可设置时长与间隔
- 自动循环：按照设置的间隔自动循环，常用于循环播放多页面板，只可设置间隔，详细可查看[循环切换多页面板](#cycle)
不同类型可设置的属性不同，如下：
- 时长：在设置的时长内计时器状态发生变化，直到时长结束停止，自动循环类型不可设置
- 间隔：表示每间隔一次计时器状态发生一次变化，若计时器添加有交互，则每间隔一次也会执行一次交互，默认1秒，三种类型计时器均可设置间隔
### 计时器启动{#mode}
计时器支持**自动**、**手动**和按**条件**启动三种方式。在**计时器**>**启动**中设置：
- 自动：自动计时，无需手动触发
- 手动：手动触发计时，需与[按钮](../common/button.md)、[调用组件方法](../../design/action/invoke-component-method.md)等交互搭配使用，可查看[验证码倒计时](#countdown)
- 条件：根据启用条件中的[表达式](../../../../exp/README.md)来判断是否启用
## 应用场景{#application}
### 验证码倒计时{#countdown}
使用计时器可实现手机登录获取验证码时，倒计时60秒的效果。实现思路如下：
1. 计时器设置`倒计时`类型，时长为`60`秒，间隔`1`秒，启动方式为`手动`
2. 在`获取验证码`按钮上添加`调用组件方法`交互，选择组件设置为`计时器11`，方法设置`开始计时`
示例地址：[应用场景-验证码倒计时](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%AE%A1%E6%97%B6%E5%99%A8)
### 循环切换多页面板{#cycle}
使用计时器可实现循环播放页面效果，循环效果需与[多页面板](../layout/panelbook.md)配合实现。实现思路如下：
1. 计时器设置`定时循环`类型，间隔为`3`秒，启动方式为`手动`，并设置[切换多页面板](../../design/action/switch-panelbook.md)交互
2. 在`开始`按钮上添加`调用组件方法`交互，选择组件设置为`计时器8`，方法设置`开始计时`
示例地址：[应用场景-循环播放图片](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E8%AE%A1%E6%97%B6%E5%99%A8)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/design"
title: "设计SuperPage"
---
---
order: 5
navTitle: SPG制作
---
# 设计SuperPage
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/datasourse.md"
htmlUrl: "https://docs.succapp.com/v5/guide/superpage/datasourse"
title: "为SuperPage添加数据"
---
---
order: 1
navTitle: 引入数据
---
# 为SuperPage添加数据
数据是SuperPage页面中组件的取数来源。添加的数据可以是数据表、临时数据加工或数据集，添加到数据的模型表即可用于页面取数。基于添加的模型可新建计算字段，以及模型设置，如过滤条件、设置参数、权限等。SuperPage中添加数据模型及模型设置的方式与仪表板中一致，
可参考文档[为仪表板添加数据模型](../../../data-viz/dash/design/datasource.md)。本文重点介绍SuperPage中数据集权限以及工作流数据源部分。
## 数据集权限设置{#dataset-permission}
SuperPage中组件可提交数据至数据模型中，故可为数据集添加读写等权限，点击数据集模型名称**右键**选择**设置**>**权限**
- **继承页面的权限设置**：默认勾选，表示当前登录用户对该仪表板拥有的权限会继承到该模型上
- **限制读权限**：限制该模型的读取权限，勾选后可配置权限
- 禁止：禁止该模型的读取权限
- 仅允许指定的用户：通过设置表达式，仅允许匹配的用户拥有该模型的读权限
- 仅允许指定的用户组：通过设置表达式，仅允许匹配的用户组拥有该模型的读权限
- **限制写权限**：限制该模型的写入权限，权限配置如限制读权限
- **限制删除权限**：限制该模型的删除权限，权限配置如限制读权限
- **限制导出权限**：限制该模型的导出权限，权限配置如限制读权限
- **限制写字段**：设置是否允许指定字段的更新
- 类型：分为**只允许更新指定字段**和**禁止更新指定字段**
- 选择字段：指定允许或禁止更改的字段
- **限制写范围**：设置数据范围，比如`销售月份=200910`，符合该范围的数据才拥有写入权限
- **启用模型上的校验规则**：提交和更新数据的时候默认会自动使用模型上设置的校验逻辑校验数据的合法性
:::tip
1. 拥有对该SuperPage页面**编辑**权限的用户才可设置模型权限
2. 内部的权限是额外添加的权限，在**权限模块**的基础上
3. 数据集模型的权限设置与[新建数据集](../../../data-viz/dash/design/datasource.md#creat-dataset)时定义的[数据集类型](../../../data-viz/dash/design/datasource.md#dataset-type)有关，如数据集类型为**可读**，则权限中只可设置**限制读权限**
4. 在**权限模块**设置的是落地的数据表或者数据加工的权限，是系统通用的表，数据集属于SuperPage内嵌的模型表，只能在单个SuperPage页面里面使用，所以只能单独设置
:::
## 工作流数据源{#wfl-data}
**工作流数据源**是[SuperPage与工作流集成使用](../../workflow/work-with-spg.md)的媒介，通过**工作流数据源**可以在SuperPage中自行配置任务列表、表单页面等流程必须的处理页面，本文仅对设置属性进行说明，详细的集成原理可参考[与SuperPage集成](../../workflow/work-with-spg.md)文档。
### 我的待办{#my-tasks}
当需要制作待办或已办等展示流程任务数据的列表时，需要在页面中引入[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)，用户可直接将其引入或通过加工关联上业务表数据后再引入，再根据需求设置对应的**过滤条件**。基于上述设置，在**工作流数据源**中提供了**我的待办**、**我的已办**等快捷设置方式，本质上还是引入了[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)，但对引入的数据源会有默认的过滤条件，例如**我的待办**会在[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)中过滤出属于当前用户的活动中的任务数据，具体设置如下：
- **选择要获取的数据**：可在此设置中切换成其他类型的**工作流数据源**
- **关联表单数据一起**：流程的任务数据是不包含业务数据的，当用户希望查询的任务列表能带上一些业务数据的信息时，比如需要查询出请假申请的请假人和请假天数，此时可以勾选**关联表单数据一起**并选择一个业务表作为关联对象，系统会自行将选择的业务表与[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)通过**业务代码**进行关联
- **自定义过滤条件**：勾选后，在默认的过滤条件基础上课额外添加过滤条件
### 流程任务信息{#task-img}
当需要在页面中获取到当前正在处理的流程任务的相关信息时，比如当前任务处于流程的哪个环节，需要引入**流程任务信息**，**流程任务信息**的来源也是[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)，不同于**我的待办**，**流程任务信息**总是单行的，通过数据源设置上的**任务ID**来自动过滤[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)来得到唯一行的任务数据，具体设置如下：
- **选择要获取的数据**：可在此设置中切换成其他类型的**工作流数据源**
- **任务ID**：通常是输入一个参数或一个实际的任务ID，通过有效的任务ID能在[流程任务表](../../../dev/sys-tables/README.md#flow-tasks)中过滤出对应的任务信息
### 流程表单数据{#page-img}
**流程表单数据**指的是**工作流**中使用的业务表，如请假申请表或报销申请表等。工作流中的相关操作[提交表单](./action/submit-data.md)、[执行流程](./action/execute-flow.md)等都需要借助**流程表单数据**的作用来达到效果。具体设置如下：
- **选择要获取的数据**：可在此设置中切换成其他类型的**工作流数据源**
- **选择工作流**：只能在工作流文件中选择，用于确定是哪个工作流中的业务数据
- **选择表单**：只能在选定的工作流的业务数据中选择，多张业务表需要在SuperPage中同时使用时，要添加多个**流程表单数据**
- **任务ID**：通常是输入一个参数或一个实际的任务ID，通过有效的任务ID可以得到指定的业务表数据
- **根据流程设置显示隐藏或禁用输入项**：勾选后，所有绑定当前**流程表单数据**的输入组件会自动根据[节点数据权限设置](../../workflow/datapermissions.md)来控制显示和禁用情况
:::tip
**流程表单数据**就是对工作流中的业务表加上了一层定义，代表选出来的业务表是工作流中的表。不同于直接引入这些业务表，引入这个定义是为了方便系统能默认提供一些流程上的设置：
- [提交表单](./action/submit-data.md#start-flw)交互只有往**流程表单数据**中新增数据时才会自动生成流程任务数据
- 通过**流程表单数据**可以获取到[节点数据权限](../../workflow/work-with-spg.md#read-and-write)，根据设置能自动控制绑定了**流程表单数据**中字段的输入组件的显示和禁用
- 根据提供的**任务ID**能快速过滤出当前处理的业务数据并装载到业务表单上
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/layout.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/layout"
title: "SuperPage布局"
---
---
order: 3
navTitle: 布局
---
# SuperPage布局
SuperPage布局即对整个页面组件的摆放位置的规划，通过不同组件结合各种容器组件即可实现各种布局效果的页面，比如：
| 网站首页式布局 | 信息卡片式布局 | 纵向卡片式布局 |
| ---| --- | --- |
|  |  |  |
## 页面布局{#layout}
SuperPage设计器的最底层是由画布构成的，画布上同样具有布局的属性。画布上的布局属性决定了整个页面的布局基调，画布的布局属性主要分为：
**内部布局**：快捷设置画布中内容的排列方式，具体可参考[内部组件排列方向设置](superpage/component/panel#direction)。
**位置大小**：控制SuperPage页面宽度和高度显示，主要分为：
| 整个视图 | 横向撑满 | 固定宽度 | 手机 |
| ---| --- | --- | --- |
|  |  |  |  |
- **整个视图**：宽度和高度均为百分之百铺满的布局方式，适用于展示一个满屏显示且横向纵向都没有滚动的页面
- **横向撑满**：宽度百分之百铺满，高度自适应的布局方式，适用于纵向滚动展示内容
- **固定宽度**：宽度为固定值，高度自适应的布局方式，适用于定宽展示内容
- **手机**：移动端式布局，适用于在移动端上展示内容
- **自定义**：灵活设置宽度和高度，适用于局限性不大的场景下，可以根据不同的需求自定义调整高度和宽度
**位置**：设置画布在屏幕中的位置，主要有**默认**、**水平居中**和**水平垂直居中**三个选项。显示效果分别是：
| 默认 | 水平居中 | 水平垂直居中 |
| ---| --- | --- |
|  |  |  |
- **默认**：画布在屏幕的左上角显示
- **水平居中**：画布在屏幕顶端居中显示，当画布的**位置大小**设置为**固定宽度**或画布宽度小于屏幕宽度时，建议**位置**选择**水平居中**
- **水平垂直居中**：画布在屏幕中心显示，当画布的宽高为固定值且宽高小于显示屏幕宽高时，建议**位置**选择**水平垂直居中**
## 容器组件{#container}
容器组件内部可以摆放其他组件（**画布**本质上也是一个容器组件），容器组件具有内部布局属性设置，可以决定内部组件的布局方式。其中主要包括**面板**、**多页面板**、**滑动面板**以及**浮动面板**四类。容器组件主要是用来给**画布**划分区域的，把**画布**根据不同的内容划分为各自独立的区域，再在各自独立的区域中进行内容制作。通常情况下是，一个**画布**中放置多个容器组件，这样就可以组合出一个丰富内容的页面。那么容器组件各自的大致功能如下：
| 面板 | 多页面板 | 滑动面板 |
| ---| --- | --- |
|  |  |  |
| 浮动面板 | 分割条 | 分割线 |
| --- | --- | --- |
|  |  |  |
- **面板**：用于放置其他布局容器或组件的容器，具体可参考[面板](superpage/component/panel)
- **多页面板**：多个页面展示不同页面，且可以配合便签页动态切换显示，具体可参考[多页面板](../components/layout/panelbook.md)
- **滑动面板**：同**多页面板**功能类似，但是可以自动实现循环播放，具体可参考[滑动面板](../components/layout/sliderpanel.md)
- **浮动面板**：浮动面板可以根据数据源行数浮动出多个面板，浮动出的面板功能和面板一致，具体可参考[浮动面板](../components/layout/floatpanel.md)
- **分割条**：用于分割页面的布局组件，具体可参考[分割条](../components/layout/splitline.md)
- **分割线**：同**分隔条**的作用一致[分割线](../components/layout/divider.md)
::: tip
横纵向布局设置、滚动条、绕排属性均适用于画布、容器组件，以下将以画布为示例。
:::
### 横向布局{#crosswise}
横向布局主要是用来将内容按照从左往右的规则依次进行摆放，可以横向滚动查看内容，也可以绕排查看内容，具体效果如下：
| 横向布局 | 横向滚动布局 | 横向绕排布局 |
| ---| --- | --- |
|  |  |  |
设置方法：
- **设置画布内部布局**：在**画布**>**内部布局**中选择**横向**，选择**横向**后，系统会自动默认设置布局中其它对齐属性，包括**方向**、**横向对齐**、**纵向对齐**、**滚动条**、**绕排**，具体可参考[面板对齐设置](../components/layout/panel.md#alignment)
### 纵向布局{#lengthways}
纵向布局正好与横向布局相反，纵向布局是将内容从上往下依次进行排列，纵向布局具体效果如下：
| 纵向布局 | 纵向滚动布局 |
| ---| --- |
|  |  |
设置方法：
- **设置画布内部布局**：在**画布**>**内部布局**中选择**纵向**，选择**纵向**后，系统会自动默认设置布局中其它对齐属性，具体属性可参考[面板对齐设置](../components/layout/panel.md#alignment)
### 滚动条{#scrollbar}
放置的内容超出屏幕的宽或高的时候，可以设置一个滚动条辅助查看页面内容，滚动条主要分为：
- **无**：默认无滚动条
- **横向滚动**：当页面内容超出屏幕的宽度时，且需要进行横向拖动查看内容。可以添加横向滚动条辅助查看
- **纵向滚动**：当画布高度固定时，内容排列布局超出了屏幕高度时，可以添加纵向滚动条辅助查看
- **横纵向滚动**：同时需要横向或者纵向查看时，可以添加横纵向滚动条辅助查看
### 绕排{#winding}
页面内容的**绕排**设置通常是跟**横向布局**结合使用的，当内容横向排放时超出屏幕宽度且不需要横向滚动查看内容时，我们就可以考虑设置**绕排**。**绕排**主要分为：
- **不绕排**：默认内容不会进行绕排排列
- **绕排**：超出**画布**的内容，会按照设置的布局方向换行依次排列
- **反向绕排**：**反向绕排**是**绕排**镜像的对称
## 组件位置大小{#location}
组件位置大小主要是用来控制组件在画布中的放置的位置，宽高度以及是否伸缩。
### 相对位置{#relative}
**相对位置**表示子组件相对于父容器的一种位置状态，且兄弟组件之间会出现挤压但不会覆盖的情况，处理规则如下：
1. 设置了**相对位置**后，子组件会自动计算与其它子组件和父容器之间的位置间距
2. 当父容器放大缩小时，系统会根据父容器放大缩小的范围重新计算各个子组件与子组件之间，以及子组件与父容器之间的位置间距
3. 子组件与子组件之间也会在位置距离不够的情况下互相挤压
4. 所有的子组件都会受到父容器内部空间大小和自己本身宽高设置中最大最小值的约束
依据上诉规则，最终形成一种弹性布局的效果。
### 绝对位置{#absolutely}
**绝对位置**不会出现兄弟组件之间相互挤压的情况，但是会在特定情况下受父容器挤压，处理规则如下：
- 设置了相邻两个边的间距属性，比如设置了左和上，此时子组件会固定在父容器的左上角，缩放父容器时不会对子组件造成挤压或拉伸
- 设置了相对两个边的间距属性，比如设置了上和下，此时缩放父容器会对子组件的宽度造成挤压或拉伸，反之亦然
- 四边均设置间距属性，此时子组件的宽高均受父容器的挤压或拉伸
### 撑满父容器{#full}
**撑满父容器**是将父容器布局方向中剩下的空间进行挤占，比如下图为横向布局，画布中的内容会将横向剩余空间全部进行挤占。这是一种比较快捷的设置组件位置的方法。
### 宽高和伸缩{#size}
宽高的设置可以控制组件在父容器中的所占位置大小，通过不同设置也可以实现弹性宽高。宽高的主要如下：
- **自适应**：这种设置方式会根据组件中的内容自动设置宽高，也可以设置最大、最小值来控制组件自动生成的大小。如果均不设置，组件就是一种弹性伸缩状态，可以理解为父容器的大小无限伸缩。这是一种常用的设置方式
- **像素**：这是一种固定大小的设置宽高的方式，且这种设置方式不会随浏览器的大小自动伸缩
- **百分比**：将宽高设置为百分比之后，就是计算子组件在父容器中的百分比大小，这种设置方式也是一种弹性设置方式
- **伸缩**：如果将**伸缩**选项设置为**是**，子组件就会自动将父容器剩余的空间占满。该属性的优先级高于上诉三种宽高设置的优先级
## 移动设备布局{#mobile}
SuperPage是支持设置移动布局，实现在移动端查看的需求。设置移动布局的方法有两种，分布是：
| 空白移动模板 | 手机布局 |
| ---| --- |
|  |  |
1. 方式一：新建SuperPage页面时，系统内置了**空白移动模板**，选择**空白移动模板**即可
2. 方式二：pc页面下，在**画布**>**位置大小**中选择**手机**布局即可
### 移动端屏幕展示方向{#direction}
**屏幕方向**：设置移动端画布展示方向，方向包括**自适应**、**横向**和**纵向**三种。在**画布**>**位置大小**>**屏幕方向**中设置
## 常用布局技巧{#skill}
### 快速定位父容器（组件）{#locate-parent}
在布局中经常会遇到需要修改某个父容器（组件）属性的情况，定位父容器（组件）的办法有两种，分别是：
1. **组件大纲树**：可以通过组件大纲树去快速定位父容器（组件），在左上角的**文件**>**显示/隐藏组件大纲**即可打开大纲树,此方式适用于多种容器复杂嵌套情况
2. **ESC定位法**：通过选中子组件，然后按下ESC键可逐层向上选中父容器（组件），此方式适用于简单嵌套情况
| 组件大纲树 | ESC定位法 |
| ---| --- |
|  |  |
### 快速移动组件{#moving}
将一个组件从容器A拖入到容器B且此时的容器之间的嵌套比较复杂，可以利用组件大纲树实现快速移动组件，方法如下：
## 常用布局效果{#scene}
### 工字型布局{#shape}
工字型布局可以将页面分为页头，侧面导航栏、内容栏和页脚栏四部分。适用于制作网页式的布局页面。
| 工字型布局 | 网页工字型 |
| ---| --- |
|  |  |
设置方法：
1. **画布**>**内部布局**选择**纵向**
2. **画布**中拖入三个**面板**，其中放置侧面导航和内容栏的内容面板需要是纵向布局的面板，可以直接选择**横向布局**组件或者拖入**面板**后将**内部布局**设置为横向布局。页头面板和页脚面板的宽度设置成`百分之百`，高度自适应，中间面板的**伸缩**设置为`是`
3. 在内容面板中分布再拖入两个**面板**，宽度根据实际情况进行设置
4. 再在各个容器中放入实际需要的组件即可
### 卡片式布局{#card}
卡片式布局可以清晰的将各种信息工整的展示出来，适用于企业信息展示。
| 卡片式布局 | 企业信息卡片 |
| ---| --- |
|  |  |
设置方法：
1. **画布**>**内部布局**选择**纵向**
2. **画布**中拖入一个**面板**（**内部布局**设置为纵向布局）**纵向布局**作为父面板，高度根据实际情况而定
3. 父面板中根据信息展示行数数量拖入相应数量的**面板**（**内部布局**设置设置为横向布局）或**横向布局**作为子面板1，**内部布局**>**伸缩**设置为`是`
4. 子面板1中根据信息展示列数数量拖入相应数量的**面板**（**内部布局**设置设置为横向布局）或**横向布局**作为子面板2，**内部布局**>**宽度**设置为`百分之五十`，**内部布局**>**纵向布局**选择**居中**
5. 子面板2中拖入**单行文本**显示信息即可
::: tip
我们可以先布局好一行
再按住Ctrl键，选中组件拖动，快速复制组件
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/submit-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/submit-data"
title: "在SuperPage中提交数据"
---
---
order: 4
navTitle: 提交数据
---
# 在SuperPage中提交数据
SuperPage提供了提交数据的功能，可以在页面上实现数据的增加、删除、修改、导入等操作。
## SuperPage提交数据的原理
下图描述了SuperPage提交数据的工作原理：
使用SuperPage提交数据，主要有图中所示的4个关键环节：
1. **可提交数据的容器组件**：在SuperPage中，容器组件只要内部放置了**输入组件**（如[输入框](../components/input/textinput.md)、下拉框），且**输入组件**绑定了提交字段，那么它就可以提交数据。可以把这样的容器组件理解为一个“表单”，比如一个SuperPage页面整体提交数据、一个SuperPage内部的[对话框](../components/embed/dialog.md)提交数据，或者是一个[面板](superpage/component/panel)组件提交自己面板内的数据。
2. **交互**：交互是一个动作，组件的动作需要通过交互实现，不同场景使用不同的交互。SuperPage支持多个提交数据的交互，如[提交表单](./action/submit-data.md)、[删除数据](./action/delete-data.md)、[导入数据](./action/import-data.md)等。**交互**设置需要有载体组件，一般使用[按钮](../components/common/button.md)。
3. **一个“可写”的数据集**：SuperPage页面的取数来源，也是提交数据对应的数据库表，需要在**数据**中引用并设置“可写”，具体可参考文档[引入数据](./datasourse.md)。
4. **提交**：这是一个可选的环节，通常用户可以在步骤二的**交互**中就直接通过**数据集**把数据提交入库了。但是有时候用户可能会在页面中反复多次修改数据并不提交，最后确认修改完成后再提交，此时需要使用两个**交互**，即在第二个步骤用“提交表单”或“删除数据”等交互并设置交互的**暂存**属性，**暂存**后所有的修改将自动保存在浏览器页面的数据集对象中，待步骤四的**提交交互**将数据入库。
## 各种提交数据的场景
- [新增数据](#insert)
- [修改数据](#update)
- [删除数据](#delete)
- [提交附件](#upload)
- [导入数据](#import-data)
- [对多表在一个事务中进行增删改](#multiple-operations)
### 新增数据{#insert}
新增数据即将数据**新增**到数据库中（此时如果数据同时被其他用户新增了，那么会出现主键冲突错误的提示），这里使用的**交互**为[提交表单](./action/submit-data.md)。初始化SuperPage页面或对话框时传递参数`:newData=true`，表示是新增数据。**提交表单**交互会自动识别这个参数，进行“新增”提交。根据不同的“表单”，向交互传递`:newData`的方法也不同：
- **SuperPage页面**：使用[打开链接](./action/linkto.md)交互链接到新页面，在参数中添加`:newData=true`
- **对话框**：使用[显示对话框/悬浮面板](./action/show-dialog.md)打开对话框时，在模式中选择**新数据**，系统自动向对话框传递`:newData`参数
### 修改数据{#update}
修改数据即对数据库内已有的数据进行**更新**。初始化SuperPage页面或对话框时应传递待修改数据的主键信息，**提交表单**交互会根据该主键进行“更新”提交。实际上**修改数据**和**新增数据**的操作基本类似，两者的区别在于传递的参数不同。传递主键信息的方法如下：
- **在对话框中进行修改**：**显示对话框/悬浮面板**交互的模式选择**加载数据**
- **在新的SuperPage页面中修改**：**打开链接**交互中设置主键参数，在新的页面接收参数并设置过滤条件
通过上述方式进入“表单”后，“表单”的输入组件中会自动显示绑定字段的数据内容，用户可在此基础上进行修改。
### 删除数据{#delete}
删除数据即对数据库内已有的数据进行**删除**，需要使用[删除数据](./action/delete-data.md)交互。常见应用场景如下：
- **列表**显示数据，在操作列中有删除按钮，点击可以删除该行数据；或者在列表前有勾选，删除所有勾选项
- 明确知道需要删除某个主键值的一条数据，如在新闻公告编辑界面，点击删除按钮，删除这一条数据
### 提交附件{#upload}
使用**附件**组件可以提交各种文件，如文档、图片、视频等。附件可以作为blob字段存储于数据库，也可以用文件形式存储于磁盘。将附件上传至数据库时需要使用[提交表单](./action/submit-data.md)交互，更多信息见[附件](../components/input/upload.md)组件说明。
### 导入数据{#import-data}
SuperPage支持以导入文件的方式将数据存入数据库，需要用到**导入数据**交互。文件模板可以事先上传到系统中，使用[打开链接](./action/linkto.md)交互下载模板，[导入数据](./action/import-data.md)交互将Excel内的数据存入至系统中。常用的上传方式如下：
1. **直接将数据导入目标表**：在**导入数据**交互中设置目标数据集
2. **先将数据导入到临时表，经过处理或确认后再复制到目标表**：需要使用两个数据模型，一个用来暂存用户上传的数据，一个用来存放最终数据。可以搭配[列表](../components/data/list.md)将暂存的数据展示出来，待所有修改操作结束后，使用[复制数据](./action/copy-data.md)交互将临时数据复制到最终所需的数据模型中
:::tip
提供模板的原因在于**导入数据**交互对导入的文件字段有一定的要求：
- 第一行必须为目标模型表的字段名称
- Excel中包含的字段与**导入数据**交互中设置的**更多字段**应包含模型表内所有字段。
:::
### 对多表在一个事务中进行增删改{#multiple-operations}
- **不同输入组件内容写入不同模型**：输入组件的**绑定字段**支持绑定不同模型表字段，**提交表单**交互中也可以选择多个数据模型
- **多次修改一次性提交**：即用户进行多次修改但不提交数据，待所有修改结束后再将数据提交入库。结合上文介绍的增删改操作，所用到的**提交表单**、**删除数据**交互均支持**暂存**，这些数据将被存在浏览器页面的数据集对象中，最后通过**提交表单**交互，将修改后的数据一次性存入数据库
- **同一份数据写入到多个模型表**：SuperPage的**输入组件**仅允许绑定一个字段，将该数据向多个模型表传递时，需要使用[更新数据](./action/update-data.md)交互。**更新数据**支持将指定组件的数据信息存入到指定模型表内，使用时可添加多个**更新数据**交互
## 提交前校验数据合法性{#validate}
**校验数据**即校验输入数据的合法性，一般有两种校验方式：
- **前端校验**：输入组件自带校验功能，校验失败时可在组件下方显示提示信息，需要在**校验**属性中设置，可参考文档[文本输入-校验](../components/input/textinput.md#validate)
- **后端校验**：当多个页面的数据都需要向同一张模型表中提交，且数据的校验规则相同时，可使用[数据校验](https://docs.succapp.com/v5/data-gov/data-audit)
若希望在提交前校验输入的内容是否符合规范，需要在**提交表单**或其他提交类交互动作中勾选**校验数据**，勾选后将优先进行**前端校验**，**前端校验**通过后进行**后端校验**，当且仅当两种校验都通过时，数据才能存入至数据库中。若不勾选**校验数据**，则不会进行数据提交的校验，此时仅在填写**表单**时，**输入组件**进行简单的前端校验。
:::tip
**模型校验**的规则也可以在**输入组件**中体现，需要在**模型表设置**>**权限**中**启用模型上的校验规则**，当校验失败后，**模型校验**中设置的提示信息将在组件下方显示出来。
:::
## SuperPage提交数据的安全控制{#security}
实际业务中，数据库中的数据是不能随意修改的，在使用SuperPage提交数据时，建议做一些安全控制。SuperPage和系统权限管理都提供了相应的处理机制：
- **页面读写的权限**：页面的读写权限决定了登录用户在系统中是否可以访问该SuperPage页面及查看的数据范围，具体介绍可参考文档[权限管理](../../../permission/grant/README.md)。
- **数据集限制数据的修改范围**：在SuperPage内部可以对数据模型进行提交数据的各项限制，一方面包括该数据模型是否能够进行读写操作、字段是否能够修改等，一方面针对用户是否拥有对该数据集读或写、删除数据等的权限。具体介绍可参考文档[引入数据](./datasourse.md#数据集权限设置)。
## 记录数据提交的日志{#log}
todo，产品还未支持
## SuperPage提交数据与表单区别{#difference}
- 报表填报应用专注于固定周期报送和Web填报，如省市区县三级的层层上报数据、分子公司为集团定期上报经营数据等
- SuperPage的提交数据适用于带有业务流程的应用场景
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/style/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/style"
title: "SuperPage组件的样式设置"
---
---
order: 5
navTitle: 设置组件样式
indexTitle: 概述
---
# SuperPage组件的样式设置
SuperPage的组件可以通过**样式设置**来改外观，如文字字体、背景填充、边框、阴影等。
## 风格{#style}
风格是组件所有样式的集合，每一个组件都可以保存多个风格。使用风格能够快速切换组件的外观，当修改风格后，所有应用到该风格的组件外观也将一起变化，具体介绍可参考文档[风格](../../../../data-viz/dash/design/type/basic/style.md)。
## 字体{#font}
设置文字的字体类型、颜色、大小、横向对齐方向、纵向对齐方向等。
## 填充{#filling}
使用**填充**可以设置组件的背景样式，有以下几个选项：
- **无填充**：组件背景不进行填充，组件显示的颜色与上层容器的背景颜色有关
- **颜色填充**：指定组件的背景颜色，可以使用**纯色**或**渐变色**
- **图片填充**：可选择系统图片库中的图片，也可自定义上传图片或使用图片URL，具体可参考文档[图片](../../components/common/image.md)
- **动效填充**：背景以动态的效果展示，除了系统中提供的动效背景外，还可以自定义进行扩展，具体可参考文档[动效背景扩展](../../../../dev/extension/extension-points/animationEffect.md)
## 边框{#border}
边框属性用来设置组件的外部边框线，包括边框的位置、线条类型和粗细。
- 边框位置：外部整体边框、上边框、有边框、下边框、左边框
- 线条类型：点线、实线、虚线、无
- 线条粗细：数值越大，边框线越粗
:::tip
[列表](../../components/data/list.md)组件的**边框**属性中，可以设置其内部的网格线。
:::
## 圆角{#border-radius}
圆角即使用圆弧替换方角，圆角的大小用圆弧的半径表示。可单独设置圆角的位置及大小。
## 边距{#padding}
用于设置组件边框与其他内容的距离，区分为内边距和外边距，当数值越大时，距离越远：
- 内边距：组件的边框与其内容之间的空白距离
- 外边距：组件边框与其他组件之间的空白距离
## 阴影{#shadow}
用于给组件的边框或文字添加阴影效果，分为以下三类：
- 外阴影：组件边框向外扩散的阴影
- 内阴影：组件边框向其内部扩散的阴影
- 文字阴影：为组件内部的文字内容设置阴影
阴影有如下属性：
- 样式：根据上、下、左、右4个方向有9种样式组合
- 颜色：设置阴影的颜色
- X偏移：阴影水平方向上的偏移量
- Y偏移：阴影垂直方向上的偏移量
- 模糊半径：将模糊效果有边缘向两端延伸
- 扩展半径：增加阴影的尺寸
示例地址：[企业查询](https://demo.succbi.com/v5/demo-spg/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E6%9F%A5%E8%AF%A23)
## 条件样式{#condition-style}
当满足不同的条件时，组件的样式可以展示为不同的效果，具体介绍可参考文档[SuperPage组件的条件样式](./condition-style.md)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/style/condition-style.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/style/condition-style"
title: "SuperPage组件的条件样式"
---
---
order: 1
navTitle: 条件样式
---
# SuperPage组件的条件样式
在Superpage中可以通过条件样式来标注符合规则的数据或动态更改单元格的外观，例如：
- 使用红色文字标注同比增幅小于10%的省份
- 使用不同的图标标注计划完成情况，绿色图标表示完成度超过90%
也可以使用状态样式来实现鼠标悬停、选中、按下等状态效果，例如：
- 鼠标滑动到按钮或文字上时有阴影效果
- 选中选项后有高亮效果
条件样式|状态样式|
-|-|
||
## 条件样式{#condition-style}
设置条件样式的入口在右侧属性栏的样式栏下，下面在数据列表中以具体的操作来展示条件样式的用法，使用数据条来展示电影时长，使用步进器来展示电影评分。关于条件样式的详细介绍可查看[报表条件样式](../../../../report/design/style/condition-style.md)。
示例地址：[条件样式](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8)
1. **选择组件**：选择需要添加条件样式的组件，即列表
2. **添加条件样式**：在**属性栏-样式-列表-条件样式**下点击**添加**按钮，添加一个**数据条**的条件样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择`电影时长`
- **设置样式**：修改**正值填充**的颜色，并设置**宽度**为`70%`，设置**边框**为`无`
3. **添加第二个条件样式**：点击设置面板左上角的**添加**按钮，添加一个**步进器**的条件样式
- **设置作用范围**：下拉选择需要作用的字段，这里选择`评分`
- **设置样式**：选择**类型**为`连续`，修改图标的**高亮颜色**，并调整**间距**为`2%`，取消勾选**显示字段值**
4. **保存条件样式设置**：点击对话框上的确定按钮保存当前条件样式设置
## 使用状态样式{#use}
状态样式的入口同条件样式，下面以添加按钮悬停、按下的状态样式为例来介绍具体的操作步骤。
示例地址：[状态样式](https://demo.succbi.com/v5/demo-spg/%E6%8C%89%E9%92%AE)
1. **选择组件**：选择需要添加状态样式的组件，即按钮
2. **添加状态样式**：在**属性栏-样式-列表-条件样式**下点击**添加**按钮，添加一个**悬停**的状态样式
- **设置作用范围**：选择**作用范围**为当前按钮，默认即是当前按钮，此处无需修改
- **设置样式**：在**样式**栏下拉选择主题风格`悬停`
3. **添加第二个状态样式**：点击设置面板左下方的**添加**按钮，添加一个**鼠标按下**的状态样式
- **设置样式**：在**样式**栏下拉选择主题风格`按下`
4. **保存条件样式设置**：点击对话框上的确定按钮保存当前条件样式设置
## 状态样式设置{#set-up}
设置状态样式的对话框大体分为四个部分，分别时添加状态样式区、作用范围设置区、样式设置区以及预览区，添加的状态样式仅对作用范围内的组件生效。
1. **添加状态样式区**：可以点击添加按钮，添加悬停、按下、选中等五种状态样式，且可以对状态样式进行重命名、复制、删除的操作，详见[添加条件样式](../../../../report/design/style/condition-style.md#add)
2. **作用范围设置区**：设置可应用当前状态样式的组件，当组件包含子项时，如**标签页**，也可设置作用范围为子项
3. **样式设置区**：可设置字体、对齐、圆角、边距、阴影等样式属性
4. **预览区**：设置完样式后可在预览区预览效果
## 状态样式介绍{#introduce}
状态样式是根据组件的状态来展示不同的效果，包含悬停、按下、选中、禁用、聚焦这五种。
### 悬停{#hover}
悬停即是指，当鼠标滑动到组件上时的状态，添加悬停状态样式的具体操作参考[使用状态样式](#use)。
示例地址：[悬停](https://demo.succbi.com/v5/demo-spg/%E6%8C%89%E9%92%AE)
### 按下{#press}
按下即是指，使用鼠标左键点击组件，从按下之后到松开之前这段时间内的状态，添加按下状态样式的具体操作参考[使用状态样式](#use)。
示例地址：[按下](https://demo.succbi.com/v5/demo-spg/%E6%8C%89%E9%92%AE)
### 选中{#select}
选中即是指，使用鼠标左键点击选择某个选项后的状态，添加选中状态样式的具体操作参考[使用状态样式](#use)。
示例地址：[选中](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8)
### 禁用{#disable}
禁用即是指，当前**组件-显示-禁用**属性设置为`禁用`时的状态，组件在这种状态下，不可进行任何操作，添加禁用状态样式的具体操作参考[使用状态样式](#use)。
示例地址：[禁用](https://demo.succbi.com/v5/demo-spg/%E6%8C%89%E9%92%AE)
### 聚焦{#focus}
聚焦一般用于步骤条中，对当前正在进行中的步骤进行状态标注，添加聚焦状态样式的具体操作参考[使用状态样式](#use)。
示例地址：[聚焦](https://demo.succbi.com/v5/demo-spg/%E6%AD%A5%E9%AA%A4%E6%9D%A1)
## 支持使用条件样式和状态样式的组件{#arrange}
组件|状态样式|条件样式|
-|-|-|
[文本](../../components/common/text.md)|悬停、按下、禁用|不支持
多行文本|悬停、按下、禁用|不支持
[按钮](../../components/common/button.md)|悬停、按下、选中、禁用|突出显示
[文本/数值输入](../../components/input/textinput.md)|禁用|突出显示
多行输入|禁用|突出显示
[多选/单选面板](../../components/input/selectionpanel.md)|悬停、按下、选中、禁用|突出显示
[下拉框](../../components/input/combobox.md)|禁用|突出显示
[日期](../../components/input/datecombobox.md)|禁用|突出显示
[快速搜索](../../components/input/searchbox.md)|禁用|突出显示
[搜索框](../../components/input/searchinput.md)|禁用|突出显示
[条件指示](../../components/input/filtersviewer.md)|悬停、按下、选中|突出显示
[标签页](../../components/navigation/tabbar.md)|悬停、按下、选中|突出显示
[步骤条](../../components/navigation/steppers.md)|选中、聚焦|突出显示
[数据列表](../../components/data/list.md)|不支持|突出显示、最前最后、数据条、步进器、色阶、图标集
[树](https://docs.succapp.com/v5/superpage/component/tree)|悬停、按下、选中|突出显示
[移动列表](../../components/mobile/mobilelist.md)|不支持|突出显示
消息列表|不支持|突出显示
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action"
title: "SuperPage组件的交互概述"
---
---
order: 6
navTitle: 设置组件交互
indexTitle: 概述
---
# SuperPage组件的交互概述
交互是一个动作，SuperPage中的大部分动作需要靠交互实现，如
- 将数据提交到数据库中需要使用[提交表单](./submit-data.md)或[更新数据](./update-data.md)等交互
- 点击按钮时为参数赋值需要使用[设置参数值](./set-param-value.md)交互
- 跳转到新的页面需要使用[打开链接](./linkto.md)交互
交互的使用需要载体组件，通过搭配不同的交互，能够快速实现各种功能，各交互之间相互独立，从上至下依次执行。
## 前端交互与后端交互{#browser-and-server}
交互主要分为前端交互和后端交互。
前端交互：主要是UI交互，如打开对话框、设置属性值、设置参数值、切换多页面板等。
后端交互：提交表单、更新数据、导入数据、删除数据、发送消息等，需要由后端接口处理。后端交互如果连续配置，且**启用条件**都是**启用**或等待**上一个交互完成**，则在一个事务中执行。如果交互中配置了成功或失败后的提示，则以事务中最后一个交互为准。
一个组件的交互执行完毕后，会返回交互执行的布尔值结果，有任何一个失败了，就返回false，否则返回true。
## 交互的执行条件和执行顺序{#condition}
交互可以设置生效条件，在**生效条件**属性中设置，提供了如下选项：
- **启用**：默认为**启用**，将等待上一个交互正常执行完成后执行
- **禁用**：禁用该交互，通常用于调试
- **条件**：需要满足某种条件后再执行交互，同时需要对**等待执行**、**等待状态**和**启用条件**进行设置。交互在执行前先进行等待，等待结束后根据**启用条件**判断是否执行
- **等待执行**：
- 上一个交互：上一个交互，默认为该选项
- 立即执行：立即执行该交互，与上一个交互并行执行
- 其他可选交互列表：除了当前交互之外的所有交互列表，按交互设置顺序显示
- **等待状态**：
- 完成：等待的交互执行成功
- 失败：等待的交互执行失败
- 结束：等待的交互执行结束（包括成功和失败）
- **启用条件**：输入表达式对交互的使用条件进行限制，当表达式返回`true`时交互生效，否则交互不生效，如等待**上一个交互完成**，**启用条件**为`[参数1]=1`，表示等待上一个交互正常执行完成后，判断参数1的值是否等于1，该交互方可执行
设置多个动作交互时可使用一些技巧，下面列举一些典型的应用场景：
1. **如何将多个数据提交动作合并在一个事务中**：只需要使多个提交动作交互连续，即可自动合并到一个事务中，详情可参考[多个提交数据请求合并一个事务提交](#merge)。
2. **特殊交互的位置设置**：当使用[关闭对话框/悬浮面板](./show-dialog.md#close)、[打开链接](./linkto.md)等交互时，建议将该交互放在交互列表最下面，例如当[关闭对话框/悬浮面板](./show-dialog.md#close)放到多个交互的中间位置时，执行交互后对话框关闭将导致后面的交互无法执行。
## 设置交互的触发事件{#trigger}
交互可以设置生效的前置触发事件，在**触发事件**属性中设置，有以下几个选项：
- **单击**：鼠标左键单击或移动端进行点击
- **双击**：鼠标左键双击
- **右键单击**：鼠标右键单击
- **移入**：鼠标移动到该组件时，就触发交互
- **移出**：鼠标光标从该组件上移开时，触发该交互
若交互的载体组件为**输入组件**，则触发事件的选项为：
- **内容变化**：输入框内容发生变化触发交互
- **输入**：输入内容时触发该交互。值得注意的是，**正在输入**的时候不是**内容变化**，输入完成并失去焦点后，才是内容变化
- **回车**：按回车时触发交互
若交互的载体组件为**画布**时，则触发事件的选项为：
- **页面加载完成**：当前页面加载完成后触发交互
- **单击**：鼠标左键单击或移动端进行点击
- **右键单击**：鼠标右键单击
## 后端交互事务{#transaction}
通过设置`等待`选项，可以控制交互之间的执行顺序。下面列举一些典型的应用场景：
### 多个提交数据请求合并一个事务提交{#merge}
在交互列表中，后端交互如果连在一起，且都是**启用**或等待**上一个交互完成**，那么这些提交数据的交互会合并为一个事务，一起提交到后端。如果提交完成后有提示信息，那么以最后一个交互上的配置为准。
### 提交数据成功后打开成功对话框，失败后打开失败对话框{#submit}
提交数据后可以配置两个打开对话框的交互，分别打开成功对话框和失败对话框，成功对话框配置等待上一个交互完成，失败对话框配置等待提交数据交互失败。
### 点击按钮提交数据，同时记录一条日志{#log}
按钮上配置**提交表单**交互用于提交表单数据，配置**插入数据**交互用于提交一条操作日志，两个交互都配置**立即执行**，他们会并行执行，发送2个请求。
## 安全策略{#security}
在执行后端交互时，为了保证交互执行的正确性，系统提供了一些额外的手段来提高系统提交数据的安全性。
### 一个事务的交互在一起执行{#together}
当配置一系列的后端交互在一个事务中执行时，这些交互会通过一个提交请求到后端执行，一起成功或失败。
### 校验更新数据的结果{#validate}
在更新库存时，我们会遇到先更新库存再插入订单的情况，当库存为0时不应该插入订单。此时可以在更新库存的数据集上增加`[库存]>0`的条件，如果更新语句返回的结果等于0，那么**更新数据**交互的**检查更新结果**选项默认会判断该语句失败，则不会继续执行。在**检查更新结果**选项中，还可以设置更多选项以调整检查策略。
### 防止提交到数据库的数据被篡改{#tampering}
黑客可以通过模拟或修改http请求的参数等手段对提交的数据进行修改。我们可以通过如下手段来防止写入数据库的数据被篡改：
- 在更新或删除数据交互中设置的数据集，需要加上严格的过滤条件，而不是仅仅依靠用户传递的参数。比如用户仅能删除或更新创建者为自身的数据，那么数据集上应该有条件`[XX表].[创建者]=$user.id`。
- 在后端交互事务最前面增加一个**后端校验**的交互，将对参数的校验或对数据库中的数据校验写在该交互中。如当数据库中无法select出指定参数的数据时，才能够将该参数的数据插入到数据库中。由于校验使用的参数和插入的参数是一致的，所以即使参数被修改，也可以避免提交脏数据。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/set-param-value.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/set-param-value"
title: "SuperPage交互-设置参数值"
---
---
order: 1
navTitle: 设置参数值
---
# SuperPage交互-设置参数值
**设置参数值**交互通过改变[全局参数](../../../../data-viz/dash/design/data/param.md)的值，修改后引用到该参数的组件会自动更新数据。如下是使用同一个对话框，通过点击不同的按钮，实现对话框的标题为**新增**或是**修改**：
## 使用设置参数值{#start}
使用设置参数值交互，需要提前设置[全局参数](../../../../data-viz/dash/design/data/param.md)。以点击不同按钮弹出同一个对话框，区分弹出对话框的标题为新增或修改为例，操作如下：
1. **设置全局参数：** 点击右上角[参数](../../../../data-viz/dash/design/data/param.md)，弹出全局参数对话框，新增参数，如名称为`bt`，描述为`对话框显示的标题`
2. **引用参数：** 双击打开`企业数据新增与修改`对话框，在标题处文本组件中引用该参数，如`${[bt]}`
3. **添加交互并编辑参数：**
1. 选中`新增`按钮，添加**设置参数值**交互，点击**编辑参数**，进入参数对话框中新增参数，参数名称选择`bt`，参数值设为`新增`
2. 选中列表中的`编辑`按钮，添加**设置参数值**交互，同理，参数名称选择`bt`，参数值设为`修改`
:::tip
设置参数值交互的参数对话框中，**参数名称**的下拉内容来源于全局参数，这里改变参数需提前在[全局参数](../../../../data-viz/dash/design/data/param.md)中定义。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/set-component-property.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/set-component-property"
title: "设置组件属性"
---
---
order: 2
navTitle: 设置组件属性
---
# 设置组件属性
本文介绍通过设置组件属性交互中可以设置的所有组件的属性。
\[\[toc]]
## 通用属性{#common-properties}
**value-值**
设置组件的值。如文本、输入组件、链接、图片的src等。
### 树{#tree-properties}
**selected-勾选值**
设置树的勾选值。TODO:等实现后在补充
**checked-选中值**
设置树的选中值。TODO:等实现后在补充
### Gis地点分布{#gispoints-properties}
**visibleLayers-可见图层下标集合**
设置Gis地点分布的可见图层，参数类型为number\[]。如\[0,1]代表设置第1个和第2个图层可见，其余图层不可见。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/invoke-component-method.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/invoke-component-method"
title: "SuperPage交互-调用组件方法"
---
---
order: 3
navTitle: 调用组件方法
---
# SuperPage交互-调用组件方法
本文介绍通过调用组件方法交互中可以调用的所有组件的方法。
\[\[toc]]
## 通用方法
### click()-点击
触发组件的点击事件。TODO
### focus()-聚焦
触发组件的聚焦事件。
## 按钮
### setValue(*args*)-设置按钮值{#button}
参数：
1. ***value*** 按钮描述，类型为字符串。
## 多页面板
### next(*args*)-下一页{#panelbook-next}
切换到下一页。参数：
1. ***loop*** 是否循环切换，为true时，如果当前是最后一页，则切换到第一页。TODO
### previous(*args*)-上一页{#panelbook-previous}
切换到上一页。参数：
1. ***loop*** 是否循环切换，为true时，如果当前是第一页，则切换到最后一页。TODO
## 滑动面板
### next(*args*)-下一页{#sliderpanel-next}
切换到下一页。参数：
1. ***loop*** 是否循环切换，为true时，如果当前是最后一页，则切换到第一页。TODO
### previous(*args*)-上一页{#sliderpanel-previous}
切换到上一页。参数：
1. ***loop*** 是否循环切换，为true时，如果当前是第一页，则切换到最后一页。TODO
## 富文本输入
### print()-打印{#richtextinput}
调用当前富文本内容的打印窗口，无参数。
## 多选面板
### checkAll()-全部选中{#selectionpanel-checkall}
全选所有数据项。TODO
### uncheckAll()-全部反选{#selectionpanel-uncheckall}
全选所有数据项。TODO
## 上传附件/上传图片{#upload}
### showUploadDialog()-显示上传对话框{#upload-showuploaddialog}
显示上传对话框，无参数。TODO
## 签名
### showSignPanel()-显示签名面板{#signpanel}
显示签名面板，无参数。TODO
## 选择列表
### expandAll()-展开全部{#treeselector-expandall}
展开选择列表的所有节点，无参数。
### collapseAll()-折叠全部{#treeselector-collapseall}
折叠选择列表的所有节点，无参数。
### checkAll()-勾选全部{#treeselector-checkall}
选中选择列表的所有节点，无参数。
### uncheckAll()-反选全部{#treeselector-uncheckall}
取消选择列表的所有选择节点，无参数。
### find(*args*)-搜索{#treeselector-find}
传入关键字，对选择列表进行搜索，隐藏不匹配的节点，高亮显示关键字。参数：
1. ***keyword*** 搜索关键字，忽略大小写，类型为字符串。
## 列表
### checkAll()-全部选中{#list-checkall}
全选所有数据项。TODO
### uncheckAll()-全部反选{#list-uncheckall}
全选所有数据项。TODO
### find(*args*)-搜索{#list-find}
传入关键字，对选择列表进行搜索，隐藏不匹配的节点，高亮显示关键字。参数：
1. ***keyword*** 搜索关键字，忽略大小写，类型为字符串。
## 树
### checkAll()-全部选中{#tree-checkall}
全选所有数据项。TODO
### uncheckAll()-全部反选{#tree-uncheckall}
全选所有数据项。TODO
## 报表
### print()-打印{#embedreport-print}
调出嵌入网页的打印窗口，无参数。TODO:目前无参数，待[BI-38781](https://jira.succez.com/browse/BI-38781)完善后补充
### export(*args*)-导出数据{#embedreport-export}
导出报表数据，参数：
1. ***fileName*** 文件名,默认为报表名称。
2. ***exportFormat*** 导出格式，默认为xlsx。
3. ***sheet*** 工作表，默认为当前工作表。
4. ***exportPage*** 导出页，默认为当前页。
5. ***showExportDialog*** 是否弹出导出选项对话框，默认为false；
6. ***selectPageEnabled*** 是否允许在导出选项对话框中选择导出页，默认为false；
7. ***selectSheetEnabled*** 是否允许在导出选项对话框中选择导出工作表，默为false；
8. ***selectFormatEnabled*** 是否允许在导出选项对话框中选择导出格式，默认为false；
9. ***allSelectFormat*** 导出选项对话框可选的导出格式，默认为\["xlsx","pdf"]。
## Superpage
### print()-打印{#embedsuperpage}
调出嵌入网页的打印窗口，无参数。TODO:目前无参数，待[BI-38781](https://jira.succez.com/browse/BI-38781)完善后补充
## 网页
### print()-打印{#webview}
调出嵌入网页的打印窗口，无参数。
## HTML
### print()-打印{#html-print}
调出嵌入网页的打印窗口，无参数。
## 视频
### play()-播放{#video-play}
播放嵌入的视频，如果嵌入已在视频则无操作，无参数。
### stop()-暂停{#video-stop}
停止播放嵌入的视频，如果嵌入视频已经停止播放则无操作，无参数。
### fullScreen()-最大化{#video-fullscreen}
全屏展示嵌入视频，不改变视频播放状态，无参数。
### setMuted(*args*)-设置是否静音播放{#video-setmuted}
参数：
1. ***muted***，类型为布尔值，必选，为true时开启嵌入视频声音，为false时关闭嵌入视频声音。
## 文档
### zoomIn(*args*)-放大{#document-zoomin}
参数：
1. ***level*** 放大倍数，可选，类型为number，默认放大倍数为1。
### zoomOut(*args*)-缩小{#document-zoomout}
参数：
1. ***level*** 缩小倍数，可选，类型为number，默认缩小倍数为1。
### print()-打印{#document-print}
调用当前嵌入文档内容的打印窗口，无参数。
### export(*args*)-导出{#document-export}
参数：
1. ***name*** 导出文档名，可选，类型为string，默认值为文件uuid的base64编码。
### search()-搜索{#document-search}
打开嵌入文档的搜索框，打开的搜索框需手动关闭，无参数。
## Gis地点分布
### setLayerVisible(*indexOrName*, *visible*)-设置图层显示隐藏{#gispoints-setlayervisible}
参数：
1. ***number|string*** 图层的序号或名称，序号从0开始。
2. ***boolean*** true为显示，false为隐藏。
### setVisibleLayers(*indexOrNames*)-设置显示的图层{#gispoints-setvisiblelayers}
设置指定图层显示，并隐藏其它图层。
参数：
1. ***indexOrNames\[]*** 图层的序号或名称。
### toggleLayerVisible(*indexOrName*)-切换图层显示隐藏{#gispoints-togglelayervisible}
参数：
1. ***indexOrName*** 图层的序号或名称。
### startDrawing(*type*)-使地图进入绘制框选框状态{#gispoints-startdrawing}
使地图进入绘制框选框状态，用户可以在地图上绘制圆、矩形和多边形，并对这些形状框选的散点进行进一步操作。参数：
1. ***around|rectangle|polygon*** 初始绘制的形状，包括圆形、矩形、多边形。即进入绘制状态后用户立即就可以用鼠标绘制的形状。也可以在工具栏上切换形状。
### finishDrawing()-使地图退出绘制框选框状态{#gispoints-finishdrawing}
使地图退出绘制框选框状态，无参数。
### loadDrawGeometry(*geometry*)-加载已绘制的框选框{#gispoints-loaddrawgeometry}
加载已绘制的框选框到地图，如果地图当前不是绘制框选框状态，那么会自动进入绘制框选框状态。参数：
1. ***geometry*** 表示一个地理几何结构，如：
1. 方圆500米`AROUND(117.195907,39.118327, 500)`
2. 矩形`rectangle(117.195907,39.118327, 116.925304,38.935671)`
3. 或多边形`polygon(117.195907,39.118327, 116.925304,38.935671, 117.654173,39.032846)`。
## 对话框
### showDialog()-显示对话框{#dialog-showdialog}
打开对话框，无参数。
### hide()-关闭对话框{#dialog-hide}
关闭对话框，无参数。
### 计时器
### start()-开始计时{#timer-start}
开启计时器，无参数。
### stop()-结束计时{#timer-stop}
停止计时器，无参数。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/linkto.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/linkto"
title: "SuperPage交互-打开链接"
---
---
order: 4
navTitle: 打开链接
---
# SuperPage交互-打开链接
**打开链接**交互用于跳转到其他对象，支持系统内部对象及外部链接，可以以弹出对话框或页面的方式展示。如列表展示各企业信息，点击企业名称查看企业详情：
示例地址：[企业查询](https://demo.succbi.com/v5/DEMO/app/DEMO.app?id=%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2)、[打开链接交互](https://demo.succbi.com/v5/DEMO/app/SuperPage.app?id=打开链接交互)
## 使用打开链接{#method}
使用**打开链接**交互需要搭配载体组件，除使用**按钮**组件外，也可将该交互附于其他浮动展示数据的组件上，浮动出来的每行数据都会带有交互动作，如**列表**、**浮动面板**组件等。
以列表为例介绍**打开链接**交互的使用方法，实现点击【企业名称】，跳转到对应企业的详情页面：
1. **交互动作设置**：
1. 在[列表](../../components/data/list.md)的【企业名称】列中添加交互**打开链接**
2. 在**链接**属性窗口选择目标类型为**应用**，并在**链接到**属性中选择目标页面。添加参数`qydm`，值为`[列表1].[企业内部序号]`，具体介绍可参考[参数设置](#param)
2. **目标页面的设置**：目标页面需要接收参数用于过滤，则需要定义全局变量
1. 目标页面定义全局参数`qydm`
2. 在目标页面的模型表中设置过滤条件，具体可参考文档[引入数据](../../../../data-viz/dash/design/datasource.md#filter)
:::tip
将参数传递给目标页面，目标页面的全局参数和传递过来的自定义参数名称一致（区分大小写），则会自动接收到该数据
:::
## 链接设置{#link}
在**打开链接**交互的**链接**属性对话框中，可以设置目标对象的类型、路径、标题、传递参数等。
### 支持的目标页面类型{#type}
**打开链接**交互可以打开系统内部的页面，也可以打开系统外部页面。在**打开链接**>**链接**属性对话框中的**目标类型**属性进行类型选择
- **文件**：支持打开报表或仪表板链接
- **应用**：支持打开应用下的所有应用资源链接，包括门户、SuperPage、模型等
- **报表填报应用**：支持打开表单链接
- **URL**：通过URL可以链接到外部页面，也可以访问一个系统内的一个文件型资源
- 外部页面：一般为互联网URL地址
- 系统内的文件型资源：包括仪表板、报表、SuperPage等。URL可以是该资源在本系统内的完整路径，如`/DEMO/app/ap.app?id=打开链接交互`；也可以是与当前页面的相对路径，如`./登录.spg`；也可以写宏，如`/demo-spg/${userid}`
- **工作流表单**：支持动态打开工作流的[表单页面](../../../workflow/work-with-spg.md#link-to)，通过传递的任务代码来获取对应的[表单页面](../../../workflow/work-with-spg.md#link-to)地址
- **短路径**：支持打开已配置的短路径链接，短路径配置可参考文档[短路径](../../../app-settings.md#shorturls-rules)
**链接到**属性的下拉列表和选择类型有关系：
- 目标类型为**文件**/**应用**/**报表填报应用**时，**链接到**属性列表中会展示对应模块的资源可供选择，当选择资源后，可通过定位按钮进行定位
- 目标类型为**URL**时，提供了输入项方式，可以实现根据条件动态显示页面，或外部页面
### 数据显示模式设置{#model}
当[目标类型](#type)为**应用**或者**报表填报应用**时，会在链接属性对话框中出现**模式**设置，可以对打开目标页面的数据显示方式进行设置，具体可参考[对话框数据显示模式设置](./show-dialog.md#data)：
- 新数据：使目标页面的提交操作为[新增数据](../submit-data.md#insert)，相当于参数`:newData=true`
- 重新初始化：每一次打开目标页面时，都会重新初始化页面内容，如上一次打开目标页面后进行的未保存修改，在下次打开时会清空
- 保留上次状态：根据目标页面进行复用，两次打开同一个页面，当传递的参数完全相同，或者不传递任何参数时，依旧维持上次打开时的状态
### 目标页面的标题设置{#name}
**标题**可以自定义目标页面的显示标题，在**打开链接**>**链接**属性对话框中的**标题**进行设置，若没有设置标题，会自动使用元数据描述或者名称。标题的显示位置和显示方式有关：
- 显示方式为对话框：为对话框标题，显示在对话框左上角
- 显示方式为当前容器：以该标题展示在面包屑路径
### 参数设置{#param}
**打开链接**可以将系统参数以及目标页面的全局参数提取并显示在参数下拉列表中，也可以自定义参数传递给目标页面，具体可参考文档[URL参考](../../../../dev/references/sys-urls.md)。对于不同目标类型显示的系统参数不同：
- 文件：
- `:filter`：过滤条件
- `:breadcrumb`：面包屑路径
- 应用
- `:newData`：新建数据
- `:loadData`：装载数据
## 显示方式设置{#how\_to\_show}
### 对话框{#dialog}
目标页面以对话框形式展现在当前页面，可以对对话框的属性进行设置：
- **大小**及**位置**设置
- 大小：可选项有自动、自定义。当选择自定义时，可以对宽度和高度进行设置，如输入百分比如`80%`，也可以直接输入数字，输入数字时默认以像素为单位
- 位置：对话框在当前页面显示的位置，可选项有居中、居左、居右、顶部、底部
- **按钮**设置：可以在对话框底部自定义设置多个按钮，点击**设置按钮**会弹出编辑对话框，可在其中添加按钮
- 按钮：可设置按钮的**标题**、**图标**、**位置**、**显示**内容
- 交互：可为每一个按钮设置[交互](./README.md)事件
### 新浏览器标签页面{#new\_tab}
新开一个浏览器标签页，显示目标页面。
### 替换当前浏览器页面{#replace\_tab}
在浏览器当前页面打开目标页面，即当前页面的URL变为目标页面的URL，可使用浏览器的返回按钮返回到上一页。
### 当前容器{#current\_container}
若当前页面展示在门户或其他页面容器中，新页面打开时也将显示在该容器内部
- **带面包屑路径**：当前容器左上角显示面包屑路径
- **不带面包屑路径**：当前容器内部覆盖显示目标页面。在使用时建议在目标页面增加**返回**按钮。
:::tip
在目标页面制作**返回**按钮，需要为该按钮设置[返回上页](./returnto.md)交互，并为**页面**属性指定返回的页面为上一次打开的页面。
:::
## 移动端的打开链接交互{#mobile}
移动端的**打开链接**交互与电脑端基本一致，主要区别在于目标页面展示的效果不同，主要有以下几点区别：
1. [标题](#name)将作为移动端的标题文字
2. 移动端打开目标页面后，在左上角自带**返回**按钮，点击该按钮可返回上一个页面。若显示方式为[替换当前浏览器页面](#replace_tab)，表示不会返回到上一个页面
3. 若显示方式为**对话框**，仍然以新页面的形式展示
## 使用场景{#use-case}
### 使用打开链接下载文件{#download}
**打开链接**支持下载或预览文件，包括ActiveDoc、excel等，使用时需提前在门户中存放文件，在交互中**链接到**该文档的路径，针对不同类型的文件，参数的设置不同：
- **ActiveDoc**：如下载企业的信息报告，需添加`:export`参数，参数值表示导出的文件格式或文件名，如`pdf`表示导出pdf、`xxxx.pdf`表示导出名字为xxxx的pdf文件，具体可参考文档[URL参考](../../../../dev/references/sys-urls.md#activedoc)。示例地址：[企业查询](https://demo.succbi.com/v5/DEMO/app/SuperPage.app/%E6%A1%88%E4%BE%8B/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2.tpg?id=%E4%BC%81%E4%B8%9A%E6%9F%A5%E8%AF%A21)
- **excel**：如下载[导入数据](./import-data.md)的导入模板，只需链接到该文档，无需设置参数。示例地址：[列表-增删改查](https://demo.succbi.com/v5/DEMO/app/SuperPage.app?id=%E5%88%97%E8%A1%A8)
- **word等浏览器支持预览的文件**：**打开链接**链接到的文档将直接在浏览器新标签页中打开预览页面
### 打开链接为短路径{#short\_path}
为了使得URL简短、美观且具有业务意义，同时方便搜索引擎优化，可以在应用的设置中配置[短路径](../../../app-settings.md#shorturls)，打开链接交互的目标类型选择短路径，列表会自动将应用中已配置的短路径展示出来以供选择。
示例地址：[文书加密下载](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=%E6%96%87%E4%BB%B6%E5%8A%A0%E5%AF%86%E4%B8%8B%E8%BD%BD)
- **短路径不含参数**：交互执行时会根据配置的短路径映射到对应的源路径地址并进行跳转
- **短路径包含参数**：配置的短路径中使用了花括号括起来的参数变量如`/demo/{id}`或`/demo/{id:[\d]+}`等，选择这类短路径后用户界面会自动出现相应的参数列表
除了直接使用目标类型为短路径，在URL中也可以利用应用配置的短路径规则来对URL地址进行匹配映射。示例地址：[API生成器](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=API%E7%94%9F%E6%88%90%E5%99%A8)
### 打开链接调用后端脚本{#call\_script}
打开链接也可以用来调用一些后端嵌入式脚本，效果类似[调用WebAPI](./WebAPI.md)。但调用WebAPI更适用于数据验证、按需取数据、自动更新页面等场景，打开链接更适用于下载文件的操作。如图点击下载按钮可以一键打包下载某条业务数据的所有附件：
示例地址：[上传附件到第三方存储](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=%E4%B8%8A%E4%BC%A0%E9%99%84%E4%BB%B6%E5%88%B0%E7%AC%AC%E4%B8%89%E6%96%B9%E5%B9%B3%E5%8F%B0%E5%AD%98%E5%82%A8)
如图所示，添加打开链接交互，设置目标类型为URL，URL输入框填写脚本文件的资源路径地址，如`/DEMO/app/script-demo.app/API/第三方接口文件下载/downloadZip.action`，根据脚本需求添加相应的参数（可参考[调用WebAPI-设置参数](./WebAPI.md#param)），即可使用打开链接交互，调用后端脚本的执行。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/switch-panelbook.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/switch-panelbook"
title: "SuperPage交互-切换多页面板"
---
---
order: 5
navTitle: 切换多页面板
---
# SuperPage交互-切换多页面板
**切换多页面板**配合[标签页](../../components/navigation/tabbar.md)、[下拉框](../../components/input/combobox.md)组件，可以实现[多页面板](../../components/layout/panelbook.md)中多个子页面之间的动态切换。如下图所示：
示例地址：[多页面板](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%A4%9A%E9%A1%B5%E9%9D%A2%E6%9D%BF)
## 使用切换多页面板{#start}
使用切换多页面板交互，需要在该页面中提前设置好[多页面板](../../components/layout/panelbook.md)组件内容，并通过**目标对象**属性选择需要切换的多页面板。以使用**标签页**组件为例，点击标签页选项切换多页面板中的多个子页面，具体步骤如下：
1. **添加组件：** 在页面中分别添加多页面板和标签页组件，并设置内容
2. **添加交互并设置属性：**
1. 选中**标签页**组件，添加**切换多页面板**交互
2. 在交互中，**目标对象**属性选择需要切换的`多页面板1`，目标面板为`事件源序号`，更多切换规则可查看[设置切换多页面板的规则](#rules)
## 设置切换多页面板的规则{#rules}
切换多页面板，提供了四种切换规则，可在**目标面板**中进行设置：
- **事件源序号**：根据**标签页**或**下拉框**里值的顺序，与多页面板中子页面的顺序进行匹配切换，当选中标签页的第一个选项时，就切换到多页面板的第一个panel页
- **事件源值**：根据**下拉框**中[枚举值的值](../../components/input/combobox.md#options)或者**标签页**中[选项的内容](../../components/navigation/tabbar.md#选项设置)，与多页面板中子页面的[名称](../../components/layout/panelbook.md#name)进行匹配切换
- **指定页**：自定义切换到指定的子页面，可在下拉框中选择指定的页面。**下一页**、**上一页**、**第一页**、**最后一页**是已经确定序号的指定页
- **动态页**：可以根据[表达式](../../../../exp/README.md)书写条件不同，切换的子页面不同，如`IF([标签页1].[值]="面板3",3,2)`，当标签页的选项为`面板3`时，就切换到第三个子页面，否则切换到第二个子页面
:::tip
多页面板配合下拉框组件，不使用切换多页面版交互也可以实现动态切换，可参考[多页面板-默认页](../../components/layout/panelbook.md#defaultpage)设置。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/popup-menu.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/popup-menu"
title: "SuperPage交互-弹出菜单"
---
---
order: 6
navTitle: 弹出菜单
---
# SuperPage交互-弹出菜单
**弹出菜单**用于弹出页面中的[菜单](../../components/common/menu.md)组件。如在PC端和移动端点击按钮弹出菜单会有不同的适配效果：
|PC端|移动端|
|--|--|--|
||||
示例地址：[弹出菜单](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%BC%B9%E5%87%BA%E8%8F%9C%E5%8D%95)
## 使用弹出菜单{#start}
使用**弹出菜单**交互，需要在该页面中提前设置好菜单，具体操作步骤与设置可查看[菜单-弹出菜单交互](../../components/common/menu.md#popupmenu)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/show-dialog.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/show-dialog"
title: "SuperPage交互-显示对话框/悬浮面板"
---
---
order: 7
navTitle: 显示对话框/悬浮面板
---
# SuperPage交互-显示对话框/悬浮面板
**显示对话框/悬浮面板**用于显示该页面中的[对话框/悬浮面板](../../components/embed/dialog.md)组件。如在PC端和移动端点击按钮弹出菜单会有不同的适配效果：
|PC端|移动端|
|---|---|
|||
示例地址：[对话框](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%AF%B9%E8%AF%9D%E6%A1%86)
## 使用显示对话框/悬浮面板{#how-to-use}
使用**显示对话框/悬浮面板**交互，需要在该页面中提前设置好[对话框/悬浮面板](../../components/embed/dialog.md)组件，并通过**对话框组件**属性选择需要打开的对话框。以使用[按钮](../../components/common/button.md)组件为例，点击按钮打开“新增对话框”，具体步骤如下：
1. **添加对话框组件**：在页面中添加**对话框**组件，名称设为【企业数据新增与修改】
2. **添加交互并设置属性**：
1. 选中“新增”按钮，添加**显示对话框/悬浮面板**交互
2. **对话框组件**属性中选择需要显示的【企业数据新增与修改】对话框，**模式**选择[新数据](#newData)
## 对话框数据显示模式设置{#data}
**模式**属性可以设置弹出对话框的数据显示方式，提供了四种选择：
- [新数据](#newData)：对话框总是执行**提交新数据**的操作
- [加载数据](#loadData)：将当前行或选中的数据传入目标对话框
- **重新初始化**：每次打开时重新初始化对话框或悬浮面板及其内容，如上一次打开对话框后进行的未保存修改，在下次打开时会清空。
- **保留上次状态**：对话框或悬浮面板打开时维持上次打开时的状态，数据引用的变化会导致该对话框进行刷新，如每次打开对话框时维持上次设置的查询条件等。
### 新数据{#newData}
**新数据**相当于参数`:newData=true`，若**对话框**或**悬浮面板**中有[数据提交](../submit-data.md)，总是执行[新增数据](../submit-data.md#insert)操作。
### 加载数据{#loadData}
**加载数据**一般配合[列表](../../components/data/list.md)组件等数据组件使用，可以将选中的当前行或勾选的数据行传入到对话框或悬浮面板中，提供了三种交互体验，在**数据范围**属性中设置：
- **勾选的**：一般搭配**列表**或**勾选框**等具有**勾选**效果的组件使用，对话框内获取到的数据仅针对勾选的数据行
- **当前行**：一般与**列表**或**浮动面板**搭配使用，对话框的数据加载仅针对当前选中行的数据
- **高亮的**：一般搭配**树**、**列表**组件使用。按住Ctrl选中数据行，选中的数据行以高亮显示，打开的对话框加载高亮显示的数据行
选择**勾选的**、**高亮的**需要设置**数据组件**，该属性将选择的**数据组件**内勾选或高亮的内容传入到对话框中。
:::tip
**模式**为**加载数据**打开对话框时，绑定了字段的输入组件**会**自动加载出相应的数据，可在此基础上进行修改并提交，常用于**修改数据**，如修改员工信息。
**模式**为**新数据**打开对话框时，绑定了字段的输入组件**不会**加载数据，在输入组件中输入的内容最终会以**新的数据行**保存至表内对应的字段中，常用于**新增数据**，如新增员工信息。
因此对话框内有提交操作时，**新增数据**和**修改数据**可以使用同一个对话框，仅**模式**上进行区别。
:::
## 参数设置{#param}
**参数**属性中可以给**全局参数**进行赋值，使用时需提前在页面中设置**全局参数**，效果与[设置参数值](./set-param-value.md)一致。
## 移动效果设置{#mobile}
在移动端使用**对话框/悬浮面板**组件时，需要使其显示效果适应手机。在**手机显示**属性中提供了手机打开对话框时的样式，效果见顶部移动端效果动图，设置如下：
- **默认**：以对话框形式打开
- **下级页面**：以打开“新页面”的形式打开对话框，对话框的**名称**属性设置的值，即为打开页面的标题
- **底部滑出**：从底部滑出，停留在底部。**顶部滑出**、**右侧滑出**、**左侧滑出**效果均与之类似
## 显示对话框方式{#display}
SuperPage中可以有多种方式显示对话框：
1. 本文中描述的**显示对话框/悬浮面板**交互配合对话框组件
2. **打开链接**交互配合对话框显示方式。该方式与这里的对话框组件不同，是需要将打开链接交互中页面的**显示方式**设置为`对话框`形式，具体可参考[打开链接-显示方式设置](./linkto.md#how_to_show)
## 关闭对话框/悬浮面板{#close}
打开的对话框可以使用**关闭对话框/悬浮面板**交互进行关闭，一般搭配[对话框/悬浮面板](../../components/embed/dialog.md)中的[按钮](../../components/common/button.md)组件使用。若**对话框**内设置了打开其它的**对话框**，在关闭子对话框时可勾选**同时关闭父对话框**，同时关闭该对话框及其父对话框。
:::tip 交互位置
同一个组件中，添加多个交互时，交互按照从上至下顺序依次执行，当使用**关闭对话框/悬浮面板**交互时，建议将该交互放在交互列表最下面，避免对话框关闭导致后面的交互无法执行。
若希望了解更多关于交互执行顺序的说明，可参考[交互的执行条件和执行顺序](./README.md#condition)。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/maximize.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/maximize"
title: "SuperPage交互-最大化"
---
---
order: 9
navTitle: 最大化
---
# SuperPage交互-最大化
使用**最大化**交互，可以将目标组件全屏显示。如下点击**单级菜单**按钮选择**放大**，[列表](../../components/data/list.md)组件在浏览器页面全屏显示，按**ESC**或者点击**右上角关闭按钮**退出全屏：
示例地址：[按钮](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8C%89%E9%92%AE)
## 使用最大化{#maximize}
**最大化**交互通常搭配[按钮](../../components/common/button.md)或者[菜单](../../components/common/menu.md)组件使用，比如设置了**最大化**交互的菜单项可以让列表在浏览器内全屏显示，如下动图所示：
1. **添加菜单项并添加交互**：标题设置为`放大`，添加**最大化**交互
2. **设置该交互属性**：属性栏中，目标组件选择`列表2`
## 设置全屏属性{#fullscreen}
当需要目标组件占满**整个屏幕**，勾选**全屏**属性即可实现。如果不勾选，目标组件在**浏览器界面**全屏显示，仍然会显示浏览器url地址栏。全屏后的内容，可以**按ESC**或者点击右上角的关闭按钮退出全屏
## 对话框组件最大化按钮{#dialog}
拖入一个新的[对话框](../../components/embed/dialog.md)组件，编辑界面默认提供了**最大化**按钮，与单独为某个组件设置最大化的区别是：
- 不用选择**目标组件**，会自动放大当前对话框
- 勾选**全屏**属性，对话框也仅在**浏览器页面**全屏显示
- 最大化后，点击**右上角的最大化按钮**会退出最大化，若按**ESC**会直接关闭当前对话框，之后再次弹出对话框仍然为全屏模式，刷新浏览器后再次弹出对话框则为默认大小
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/show-component.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/show-component"
title: "SuperPage交互-显示/隐藏组件"
---
---
order: 10
navTitle: 显示组件
---
# SuperPage交互-显示/隐藏组件
**显示组件**交互用于显示被隐藏的组件，与**隐藏组件**交互组合使用，可以实现动态显示与隐藏效果。如搜索企业名称，当企业名称不为空时，显示统一社会信用代码，否则不显示：
示例地址：[显示隐藏组件交互](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%98%BE%E7%A4%BA%E9%9A%90%E8%97%8F%E7%BB%84%E4%BB%B6%E4%BA%A4%E4%BA%92)
## 使用显示组件{#show-component}
使用**显示组件**交互，搭配**隐藏组件**交互，根据不同的[启用条件](./README.md#condition)，可以实现组件的动态显示。以搜索企业名称为例，企业名称不为空，则显示统一社会信用代码，具体步骤如下：
1. **添加需要显示的组件：** 在页面中添加[面板](superpage/component/panel)组件，如`面板20`，并在面板中添加两个[文本](../../components/common/text.md)组件，用于显示信用代码信息
2. **添加交互并设置属性：** 选中`企业名称`的[快速搜索](../../components/input/searchbox.md)框
1. 添加**显示组件**交互，**生效条件**设为`条件`，**启用条件**为`[企业名称：] is not NULL`，同时将**目标组件**选择上方加入的`面板20`
2. 同理，添加**隐藏组件**交互，设置**启用条件**为`[企业名称：] is NULL`，并将目标组件选择`面板20`即可
## 切换显示和隐藏{#switch}
**显示组件**交互除了与**隐藏组件**交互组合使用，实现组件动态显示效果之外，只利用**显示组件**交互也可以实现动态显示效果。需要在**显示组件**交互中勾选**切换显示和隐藏**属性，勾选后，无论组件的初始状态为显示或隐藏，每[触发事件](./README.md#trigger)发生一次，就可动态切换一次状态。如下图所示：
示例地址：[按钮-菜单按钮](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8C%89%E9%92%AE)
## 使用隐藏组件{#hide-component}
**隐藏组件**交互的用法与**显示组件**交互一致，但作用相反，具体使用可查看[使用显示组件](#show-component)交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/show-message.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/show-message"
title: "SuperPage交互-显示消息框"
---
---
order: 13
navTitle: 显示消息框
---
# SuperPage交互-显示消息框
**显示消息框**交互用于显示用户执行某个操作之后的提示信息。如录入采购物品条形码时显示错误的提示消息框：
示例地址：[显示消息框](https://demo.succbi.com/v5/demo-spg/%E6%89%AB%E7%A0%81%E6%9E%AA%E8%BF%9E%E7%BB%AD%E5%BD%95%E5%85%A5)
## 使用显示消息框{#use}
使用**显示消息框**交互，通常需要提前设置好该交互的[生效条件](./README.md#condition)，即在满足某个条件后才弹出提示消息，如输入采购物品条形码，回车时会检测条形码是否已经使用过，如果已使用，则弹出“采购物品条形码已录入!”的错误消息框，具体步骤如下：
1. **添加显示消息框交互并配置属性**：选中采购物品条形码文本输入框，添加**显示消息框**交互，**生效条件**选择条件，[启用条件](./README.md#condition)设置为`[确认物品条形码是否录入].[总行数（数据集）]>0`，**消息类型**选择`错误`，**显示模式**设置为默认的`消息框`，**消息内容**设置为`${IF([确认物品条形码是否录入].[总行数（数据集）]>0,'采购物品条形码已录入!')}`
2. **添加其他交互并设置交互属性**：依次添加[提交表单](./submit-data.md)、[新数据](./new-data.md)、[调用组件方法](./invoke-component-method.md)并设置相应的属性
## 设置消息类型{#type}
在**消息类型**属性中可以根据提示情况选择合适的显示状态，具体如下：
- **消息类型**：在**消息类型**下拉框中选择**成功**(success)、**等待**(waiting)、**信息**(info)、**警告**(warning)、**错误**(error)之中的一种，每一类都有不同的提示界面，用来给用户传达不同的提示信息
- **动态消息类型**：**消息类型**属性中选择**动态类型**，选中后，可以输入表达式，用来动态产生上述五种消息类型，如 `1=1?'warning':'info'`用来显示警告消息
## 设置显示模式{#mode}
显示模式分为**消息框**和**对话框**两种，分别提供不同的提示页面。
### 消息框{#message}
**显示模式**下拉框选择`消息框`之后，提示信息在屏幕的上方以消息框的形式展示。提供了如下属性设置：
- **停留时间（毫秒）**：默认为`3000`毫秒，即停留时间结束后，消息框会自动关闭
- **等待消息框隐藏**：仅显示模式为消息框时才有效，表示等消息框消失后再执行下一个交互
- **消息内容**：默认为空，支持写表达式，显示在消息框的正中间
### 对话框{#dialog}
显示模式下拉框选择对话框之后，提示信息在屏幕的中间以对话框的形式展示给用户。对话框在下方提供了按钮供用户关闭对话框，提供了如下属性设置：
- **消息标题**：默认为空，支持写表达式，显示在对话框的左上角
- **消息内容**：默认为空，支持写表达式，显示在对话框的正中间
- **按钮**：不同的消息类型提供了不同的按钮
- **成功**、**等待**和**信息**右下角提供了关闭按钮，点击后可以关闭对话框
- **警告**右下角提供了确定按钮，点击后关闭对话框
- **错误**下方提供了复制和确定按钮，点击复制按钮复制错误信息，点击确定按钮关闭对话框
## 与数据类交互消息提示的区别{#difference}
[提交表单](./submit-data.md#after)等很多数据类交互可以直接在交互中设置消息提示，与**显示消息框**交互的不同之处在于提交表单只能显示成功或失败的提示消息框。
## 移动端显示效果{#mobile}
移动端显示消息框的交互设置和PC端的一致，显示效果有所不同，如下：
- **消息框**：以透明的消息框在屏幕中间显示，不提供关闭按钮
- **对话框**：以不带提示图标的白色对话框在屏幕中间显示
示例地址：[移动端显示消息框](https://demo.succbi.com/v5/demo-spg/mobile/%E6%98%BE%E7%A4%BA%E6%B6%88%E6%81%AF%E6%A1%86)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/show-confirm-dialog.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/show-confirm-dialog"
title: "SuperPage交互-弹出确认对话框"
---
---
order: 14
navTitle: 弹出确认对话框
---
# SuperPage交互-弹出确认对话框
**弹出确认对话框**交互，常用来弹出提示信息，如删除数据前或者录入数据后弹出确认对话框：
|PC端|移动端|
|---|---|
|||
示例地址：[列表增删改查](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)、[弹出确认对话框](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E5%BC%B9%E5%87%BA%E7%A1%AE%E8%AE%A4%E5%AF%B9%E8%AF%9D%E6%A1%86%E4%BA%A4%E4%BA%92)
## 使用弹出确认对话框{#show-confirm-dialog}
**弹出确认对话框**常与其他交互配合使用，用于在执行某个交互动作之前，弹出确认对话框进行提示，以点击**删除选中**[按钮](../../components/common/button.md)弹出确认对话框为例，具体操作步骤如下：
1. **添加弹出确认对话框交互并设置属性：**
- 选择**删除选中**按钮，添加**弹出确认对话框**交互
- 在交互中，设置**标题**为`删除${[列表1].[勾选行数]}条数据`，**内容**为`您确认删除${[列表1].[勾选值].[资产名称]}吗`
2. **添加自定义按钮并设置属性：**
- **按钮**属性选择自定义，点击设置按钮，在弹出的对话框中添加两个按钮，标题名称分别为**删除**和**取消**
- **删除**按钮添加[删除数据](./delete-data.md)交互，数据选择`资产信息维护`，范围选择`勾选的`，数据组件选择`列表1`，**取消**按钮添加[关闭对话框/悬浮面板](./show-dialog.md#close)交互
以上设置即可实现，当点击删除选中按钮时会先弹出确认对话框提示用户：
- 选择对话框中的删除，继续执行后续的删除数据交互
- 选择取消，则关闭确认对话框
## 对话框内容设置{#content}
使用**弹出确认对话框**提示用户时，可以设置对话框的**标题**和**内容**，提供了如下属性设置：
- 标题：支持写表达式，如 `删除${[列表1].[勾选行数]}条数据`，PC端和移动端的显示效果有如下区别：
- PC端：标题在左上角，不设置内容时显示为“确定”
- 移动端：标题是居中显示的，不设置内容时不显示
- 内容：支持写表达式，如 `您确认删除${[列表1].[勾选值].[资产名称]}吗`，PC端和移动端的显示效果有如下区别：
- PC端：内容是居左显示的，不设置内容时不显示
- 移动端：内容是居中显示的，不设置内容时不显示
- 按钮：[默认](#setting1)提供了确定和取消按钮，也可以进行[自定义](#setting2)按钮设置
### 默认按钮{#setting1}
如果需要执行弹出确认对话框后面的交互，对话框的按钮默认提供了标准的**确定**和**取消**两个按钮，显示在对话框的右下角，后面的交互会根据[生效条件](./README.md#condition)来判断是否执行
- **确定按钮**：点击后该交互算作执行成功，若后面的交互生效条件设置为**上一个交互执行成功**，则接着执行后面的交互，在对话框右下角以蓝色按钮样式显示
- **取消按钮**：点击后该交互算作执行失败，若后面的交互生效条件设置为**上一个交互执行成功**，则不执行后面的交互，若后面的交互生效条件设置为**上一个交互执行失败**，则接着执行后面的交互，在对话框右下角以白色按钮样式显示
### 自定义按钮{#setting2}
除了系统自带的默认按钮设置，也可以**自定义**对话框的按钮，例如弹出提示信息对话框，只需要一个关闭按钮，就可以使用自定义方式实现，实现思路如下：
1. 选择自定义按钮，点击**设置按钮**，弹出设置按钮的对话框
2. 在对话框中，添加按钮，并设置[关闭对话框/浮动面板](./show-dialog.md#close)交互
自定义按钮继续执行更多逻辑，需要在该按钮上添加交互，例如这里的关闭按钮，需要在该按钮上添加[关闭对话框/浮动面板](./show-dialog.md#close)交互执行关闭对话框的功能
:::tip
**弹出确认对话框**交互中设置为**默认**按钮时，与下方的交互之间是异步执行，即下面的交互需要等待弹出确认对话框交互执行的结果，**自定义**按钮时是同步执行，即在弹出确认对话框交互执行的同时，下面的交互就执行了。当使用**自定义按钮**后，想要异步执行，只能在自定义的按钮上配置交互处理后续逻辑。
:::
## 与提交数据类交互中弹出对话框的区别{#difference}
[提交数据](../submit-data.md)类交互如[提交表单](./submit-data.md#confirm)、[删除数据](./delete-data.md#tooltips)等，可以直接在交互中设置弹出确认对话框，该对话框与“弹出确认对话框”交互的不同之处在于提交数据类交互中的弹出确认对话框只能设置内容，不能设置标题，且对话框内按钮不可以自定义设置
|弹出确认对话框交互|删除数据|
|---|---|
|||
示例地址：[移动弹出确认对话框](https://demo.succbi.com/v5/demo-spg/mobile/%E7%A1%AE%E8%AE%A4%E5%AF%B9%E8%AF%9D%E6%A1%86)
## 应用场景{#scene}
在表单上填写完信息后，点击**保存**按钮，弹出的确认对话框中，提供**继续录入**按钮，点击后再次进入表单页面填写新的数据。使用**自定义**按钮即可实现该效果，实现思路如下：
1. 添加**弹出确认对话框**交互：在表单界面的**保存**按钮上，添加**弹出确认对话框**交互
2. 自定义交互按钮：在该交互中添加**继续录入**按钮，并设置[显示对话框/浮动面板](./show-dialog.md)交互并再次进入表单页面填写新数据，添加取消按钮，设置[关闭对话框/浮动面板](./show-dialog.md#close)交互用来关闭对话框
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/scroll.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/scroll"
title: "SuperPage交互-滚动"
---
---
order: 15
navTitle: 滚动
---
# SuperPage交互-滚动
使用滚动交互可以使页面或具有滚动属性的组件，在指定范围内滚动，如[滑动面板](../../components/layout/sliderpanel.md)可进行指定的上一页，下一页滚动，示例如下：
示例地址：[滚动](https://demo.succbi.com/v5/demo-spg/滚动)
## 使用滚动交互{#use}
滚动交互的使用，极大的方便了用户在页面冗长的情况下快速将页面滚动到自己想要章节，以下方页面滚动到基础功能处为例：
- **增加一个按钮**：在页面新增一个按钮如`滚动到基础功能处`
- **增加滚动交互**：给按钮增加一个`滚动`交互，**滚动范围**选择`当前页面`，**滚动距离**选择`到组件`，**到组件**选择基础功能所在的`单行文本3`
## 滚动范围设置{#limit}
想要控制滚动在什么范围内进行，可以对**滚动范围**进行设置。系统提供的**滚动范围**有：`自动`、`当前页面`、`指定组件`。滚动交互能够正常进行的前提条件是：设置的**滚动范围**是可滚动的。
- **自动**：当前选中组件的上层容器
- **当前页面**：当前设计器中的画布
- **指定组件**：即自定义滚动范围，如`面板3`
## 滚动距离设置{#space}
如果一个页面有多个章节，我们想快速定位到具体的章节，就可以将**滚动距离**设置成这个章节。滚动距离只能在[滚动范围](#limit)内进行设置。系统提供的**滚动距离**包括`到顶部`、`到底部`、`事件源序号`、`上一页`、`下一页`、`上一行`、`下一行`、`到组件`、`动态组件`这九种。
- `到顶部`与`到底部`可以直接定位到滚动范围的顶部和底部
- `事件源序号`、`上一页`、`下一页`、`上一行`、`下一行`这几种主要是面向[滑动面板](../../components/layout/sliderpanel.md)，滑动面板自带的按钮中就包含了滚动到[事件源序号](./switch-panelbook.md#rules)、[上一页](./switch-panelbook.md#rules)、[下一页](./switch-panelbook.md#rules)
- `到组件`则是能够直接将指定组件滚动到**滚动范围**顶部，若**滚动范围**和**滚动距离**均设置为`到组件`时，**滚动距离**可选择的组件会限定在**滚动范围**的组件中。
- `动态组件`相当于`到组件`的特殊情况，通过表达式控制`到组件`的具体情况,如表达式`IF([标签页1].[值]='基础功能', 'text3', IF([标签页1].[值]='首尾滚动', 'text7', 'text6'))`
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/new-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/new-data"
title: "SuperPage交互-新数据"
---
---
order: 16
navTitle: 新数据
---
# SuperPage交互-新数据
使用**新数据**交互，可以在目标页面组件中生成一条新的数据，如点击**新增资产信息**按钮后，表单内容清空，用户输入后提交一条新的资产信息：
示例地址:[树增加与修改](https://demo.succbi.com/v5/demo-spg/%E6%A0%91%E5%A2%9E%E5%8A%A0%E4%B8%8E%E4%BF%AE%E6%94%B9)
## 使用新数据{#use}
**新数据**交互通常搭配[提交表单](./submit-data.md)交互使用，该交互会清空表单界面或对话框，当用户填写完毕并提交数据时会以**新的数据**进行提交入库，以新增资产信息为例，具体操作步骤如下：
1. **添加提交表单交互**：选中**保存**按钮，添加**提交表单**交互，**范围**选择指定组件，**组件**选择panel4，用于提交用户填写的新数据
2. **添加新数据交互**：选中**新增资产信息**按钮，添加**新数据**交互，选择panel4**组件**
### 与显示对话框/浮动面板或者打开链接的新数据模式的区别{#difference}
**新数据**交互用于提交SuperPage页面的新数据时，与使用[打开链接](./linkto.md)跳转到新页面时在模式中选择“新数据”或者[显示对话框/悬浮面板](./show-dialog.md)的模式中选择“新数据”的作用相同，都是让目标表单或者对话框获取到`:newData=true`参数，具体可以参考[提交表单](./submit-data.md#insert)文档。不同之处在于**新数据**交互会让当前目标表单内容或者对话框内容清空，而不是跳转到一个新的界面。
:::tip
使用**新数据**交互，若目标组件中设有**默认值**，新数据交互会让组件内容还原为默认值；若目标组件设置了[UUID()](../../../../exp/func/string/UUID.md)或[RAND()](../../../../exp/func/math/RAND.md)等计算公式，新数据交互会使组件内容重新计算生成一条新数据。
:::
## 设置新数据的范围{#range}
**新数据**交互可以设置哪些范围内的目标组件生成新数据，在**范围**属性中设置，具体可以参考[装载数据](./load-data.md#display)文档。
## 与重置数据交互的区别{#diversity}
**新数据**交互和[重置数据](./reset-data.md)交互都是对已经修改的表单内容进行处理，不同之处在于：
1. **新数据**交互会清空表单或者对话框内容，**重置数据**则是将当前页面组件中的内容还原至初始状态
2. **新数据**交互一般搭配**提交表单**使用，该交互使页面清空，用户在输入完毕后，后续的“提交表单”会把它当作“新数据”提交，而重置数据仅是对当前数据进行还原
## 使用新数据生成新验证码{#code}
**新数据**交互可以用来生成新的文本信息，如点击验证码生成一个新的验证码，实现思路如下：
1. 设置文本框计算公式为`${LEFT(UUID(),4)}`
2. 选中文本，添加新数据交互，并设置好交互属性
示例地址:[提交单行数据](https://demo.succbi.com/v5/demo-spg/%E6%8F%90%E4%BA%A4%E5%8D%95%E8%A1%8C%E6%95%B0%E6%8D%AE/newData)
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/load-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/load-data"
title: "SuperPage交互-装载数据"
---
---
order: 17
navTitle: 装载数据
---
# SuperPage交互-装载数据
**装载**就是将数据通过某个载体显示出来，**装载数据**交互支持在当前页面的指定组件或容器中加载数据，无需打开新的页面或对话框，其效果与**显示对话框/悬浮面板**的[加载数据](./show-dialog.md#loadData)类似，如在左侧列表中选择企业名称，在右侧显示该企业的详细信息：
示例地址：[列表-列表交互](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
## 使用装载数据{#how-to-use}
**装载数据**交互，作用于两个组件之间，即发起装载的主体组件和数据装载的目标组件：
- **主体组件**：一般为展示数据的组件，如[树](https://docs.succapp.com/v5/superpage/component/tree)、[列表](../../components/data/list.md)等
- **目标组件**：任意能获取模型表数据的组件均可，可以是单个组件如[文本输入](../../components/input/textinput.md)、[文本](../../components/common/text.md)等；也可以是包含多个组件的容器，如[面板](superpage/component/panel)等
当点击主体组件的某一行数据时，通过**装载数据**交互，这行数据的更多信息将在目标组件中显示出来。以在列表中选择企业名称，右侧显示该企业的详情为例，具体使用步骤如下：
1. **引用字段**：在面板中添加[文本](../../components/common/text.md)组件，并为组件设置字段内容`${[企业基本信息].[企业名称]}`，该字段所在模型表需要与**列表**组件引用的模型表一致
2. **为列表组件添加交互**：在列表的**交互**中选择**装载数据**，指定**数据范围**为**当前行**，**范围**为**指定组件**，**提交组件**为panel28
:::tip
**树**组件不支持**当前行**的数据范围，若使用**树**作为主体组件，一般需要使用两个模型表，一个作为左侧列表的数据，一个用来作为右侧显示的数据，具体用法与[主体和目标组件使用不同模型表](#differ)一致
:::
### 主体和目标组件使用不同模型表{#differ}
主体组件与目标组件使用的模型表不同时，需要搭配[设置参数值](./set-param-value.md)交互获取选择行的数据，以左侧树中选择资产列表，在右侧显示该资产的详细信息为例，实现思路如下：
1. 设置全局参数`a`接收选中行的主键信息
2. 在主体组件上使用**设置参数值**对参数进行赋值，并设置**装载数据**交互
3. 在目标组件引用的模型表上使用该全局参数进行过滤，如`[资产信息维护-表单].[资产编码]=[a]`
当点击数据行时，**装载数据**交互将主动发起一次查询请求，得到模型表过滤后的数据，最终将该结果填入指定的容器或组件中
示例地址：[树增加与修改](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%91%E5%A2%9E%E5%8A%A0%E4%B8%8E%E4%BF%AE%E6%94%B9)
## 需要装载的数据范围{#range}
**装载数据**交互支持设置加载哪些符合条件的数据，在**数据范围**属性中提供了两种可选项：
- **勾选的**：一般搭配**列表**或**勾选框**等具有勾选效果的组件使用，仅装载勾选的数据行数据，同时需要设置主体组件，交互将仅装载选择的主体组件中的内容
- **当前行**：一般与**列表**搭配使用，仅装载当前选中的数据行的数据，默认为**当前行**
## 目标组件设置{#display}
**装载数据**交互能够对数据展示的目标组件进行设置，在**范围**属性中选择：
- **默认**：该选项为默认项，如果主体组件在对话框组件中，则该对话框内的组件进行装载；若不在，则整个页面内的组件进行装载
- **整个页面**：将整个页面内的组件进行装载
- **所在对话框/悬浮面板**：主体组件所在的对话框或悬浮面板内的组件进行装载
- **指定组件**：选择后，需要在**提交组件**中勾选显示数据的目标组件
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/reset-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/reset-data"
title: "SuperPage交互-重置数据"
---
---
order: 18
navTitle: 重置数据
---
# SuperPage交互-重置数据
**重置数据**交互能够将当前页面组件中的内容还原至初始状态，一般与[表单](../submit-data.md)搭配使用，如：
1. 在“表单”中新增个人信息，点击**重置**按钮，清空已填写的内容
2. 在“表单”中修改资产信息，点击**重置**按钮，已修改的内容将被还原
3. 查看经营状态为“在业”的企业，点击**清空条件**按钮，“在业”的限制条件被清除，页面将展示所有的数据
示例地址：[树增加与修改](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%91%E5%A2%9E%E5%8A%A0%E4%B8%8E%E4%BF%AE%E6%94%B9)、[分类浏览](https://demo.succbi.com/v5/DEMO/app/DEMO.app/%E4%BD%8E%E4%BB%A3%E7%A0%81%E6%A1%88%E4%BE%8B/%E4%BC%81%E4%B8%9A%E4%BF%A1%E6%81%AF%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2.tpg?id=%E5%88%86%E7%B1%BB%E6%B5%8F%E8%A7%88)
## 使用重置数据{#user}
**重置数据**的使用没有任何限制，只需在[按钮](../../components/common/button.md)上添加该交互，并选择重置的[范围](#range)即可，若输入组件中设有默认值，则重置后会将组件内容还原为默认值。以使用**重置数据**交互还原资产信息“表单”中修改的内容为例，使用步骤如下：
1. **输入组件绑定字段**：为[文本输入](../../components/input/textinput.md)组件绑定字段，使“资产名称”、“金额”等组件内容能够自动加载原数据
2. **配置交互**：在按钮中添加重置数据交互，并设置**范围**为panel4，表示点击该按钮时，panel4中的所有内容还原至初始状态
## 重置的范围设置{#range}
**重置数据**交互可以设置指定哪些组件或者数据集进行重置，在**范围**属性中设置，有以下几个选项：
- **默认**：该选项为默认项，如果载体组件在对话框组件中，则重置对话框内的数据；若不在，则重置整个页面内的数据
- **整个页面**：重置页面中的所有数据
- **所在对话框/悬浮面板**：重置按钮所在的对话框或悬浮面板中的数据
- **指定组件**：选择后，需要在提交组件中勾选需要进行重置的组件
- **指定数据行**、**指定数据集**：适用于页面内有提交数据且使用了暂存的场景，具体可查看[重置暂存数据](#reset-tmp)
### 重置暂存数据{#reset}
重置暂存数据一般适用于页面内需要[提交数据](../submit-data.md)，并使用了[暂存](./submit-data.md#tmp-storage)属性的场景。由于**暂存**后的数据保留在浏览器对应的数据集中，还未真正存入到数据库中，所以使用**重置数据**交互可以对指定的数据模型的修改进行还原，如：
- 若添加了新的数据行，则删除新增的数据行
- 若删除了某行数据，则该行数据将被还原，且还原到该数据行之前所在模型表的位置
- 若修改了数据，则将该数据还原为之前的内容
**范围**属性中提供了可以重置暂存数据的选项：
- **指定数据行**：重置目标模型表中指定的数据行数据，一般使用**主键**字段获取该行数据，需要在**数据集**属性中选择模型表，并在**主键字段设置**中为主键赋值。如对列表中某行数据进行修改后，点击“重置”按钮，将该行数据修改的内容还原
- **指定数据集**：将指定的模型表修改项全部清空，选择后需要在**数据集**中选择对应的模型表。如重置该模型表的在本页面内所有新增、修改、删除的暂存操作，将模型表的数据还原为初始状态
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/validate-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/validate-data"
title: "SuperPage交互-校验表单"
---
---
order: 19
navTitle: 校验表单
---
# SuperPage交互-校验表单
“表单”是存放输入组件的容器，它可以是面板、对话框或者整个SuperPage页面。**校验表单**交互用于校验这些“表单”里的输入项是否符合规则，一般在[数据提交](../submit-data.md)之前执行，如找回密码时校验是否输入了登录账号和验证信息：
示例地址：[找回密码](https://demo.succbi.com/v5/demo-spg/%E6%89%BE%E5%9B%9E%E5%AF%86%E7%A0%81)
## 使用校验表单交互{#use}
使用**校验表单**交互前需要在[输入组件](../../components/input/textinput.md#validate)中勾选**校验**属性并设置这个输入组件的**校验公式**，**校验表单**在执行时会检查范围内的所有输入组件的数据是否符合校验公式设置的规则，若不符合，则进行提示。以找回密码时校验输入为例，使用**校验表单**交互的步骤如下：
1. **为输入组件设置校验公式**：
1. 登录账号：在**校验**属性中勾选**必填**，表示该输入组件是必填项；勾选**校验**，可以自定义输入校验公式`[用户表].[ID] IS NOT NULL`，判断输入的用户名是否在系统中存在，并输入校验提示信息`账号不存在或账号输入错误`
2. 验证码：同1在**校验**属性中勾选**必填**和**校验**属性，在校验公式中输入`[文本输入5].[值]=[随机验证码]`，表示输入的内容必须和生成的验证码一致，并输入校验提示信息`验证码错误`
2. **设置校验表单交互**：在**下一步**按钮中添加校验表单交互，选择**范围**为**指定组件**，设置**提交组件**为`纵向布局9`，表示检查该面板内部的输入组件校验是否通过
:::tip
为**输入组件**设置校验后，当鼠标焦点从输入框内部离开时，便会对**输入组件**的内容进行校验，这是组件自带的校验规则，**校验表单**交互的使用可以不需要**输入内容-失焦**这两个步骤就可以校验输入组件内部的数据是否符合规范，如检查必填的组件是否输入了内容。
[提交表单](./submit-data.md)交互在执行时也会校验“表单”中的输入项是否符合规范，其校验的范围是选择的“提交范围”，当使用**提交表单**交互提交数据且需要校验的组件包含在提交范围内时，可以不需要使用**校验表单**交互。
:::
## 校验范围{#range}
**校验范围**属性用于设置**校验表单**交互检查哪个范围内的输入组件，若输入组件不在**校验表单**交互的校验范围内，则不会对这些组件进行校验操作，选项的具体介绍可参考[检查范围设置](./check-save.md#range)。
## 校验提示{#message}
**表单校验**交互执行后，根据校验的结果可以对用户进行提示，若输入组件的数据不符合校验公式设置的规则，则表示校验失败，只有当所有的校验公式都满足时，才代表校验成功。
**表单校验**交互支持设置校验结果的提示信息，需要勾选**失败后显示提示**或**成功后显示提示**属性，以**失败后显示提示**为例：
- 若不勾选**失败后显示提示**，则校验失败后仅在**校验失败**的输入组件下显示自身定义的**校验提示**
- 若勾选了**失败后显示提示**，则可以以**对话框**或**消息框**的形式提示用户，如果没有设置自定义的提示信息，则默认显示`校验失败`（成功后显示的默认提示为`校验成功`），如果设置了自定义的提示信息，则显示自定义的内容。若需要自定义对话框的标题、按钮或消息框的显示时间，可以使用[弹出确认对话框](./show-confirm-dialog.md)与[显示消息框](./show-message.md)交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/check-save.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/check-save"
title: "SuperPage交互-检查修改"
---
---
order: 21
navTitle: 检查修改
---
# SuperPage交互-检查修改
**检查修改**交互适用于有**提交**操作的场景，可以检查**表单**是否有修改并给出对应的提示，**表单**与**提交数据**的具体介绍可参考文档[提交数据](../submit-data.md)。如新增资产信息时退出填写，**检查修改**弹出确认框：
示例地址：[树增加与修改](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%A0%91%E5%A2%9E%E5%8A%A0%E4%B8%8E%E4%BF%AE%E6%94%B9)
## 使用检查修改交互{#how-to-use}
使用**检查修改**交互，需要提前设置好是检查已修改内容还是检查未修改内容，该交互**提示**属性中提供了`有修改时提示`和`无修改时提示`两种选项，在对表单内容进行检查的时候会根据不同的设置进行提示：
- **有修改时提示**：在关闭页面或执行其他操作时对已修改尚未保存的**表单**弹出对话框进行提示
- **无修改时提示**：通常搭配**提交表单**交互使用，提交时对未作修改的**表单**进行提示
### 有修改时提示{#true}
在**提示**下拉选项中选择`有修改时提示`后，使用**检查修改**交互检查[范围](#range)内已修改的**表单**内容是否已经保存，若已保存则继续执行其他操作，若未保存则弹出对话框进行提示。如下场景说明了表单做了修改时，哪些组件能够触发该交互：
- 在关闭对话框时，检查该对话框内部的**表单**内容是否已经保存，则触发该交互的组件是对话框的“关闭”按钮
- 使用“新增”按钮创建一张新的**表单**时，每次点击“新增”按钮，需要对上次填写但未保存的内容进行提示，则触发该交互的组件是“新增”按钮
- 填写的内容尚未提交时，点击[树](https://docs.succapp.com/v5/superpage/component/tree)查看别的数据，需要对之前未保存的表单进行提示，则触发该交互的组件是**树**
- 刷新页面时，需要检查页面内**表单**内容是否已经保存，则触发该交互的是**画布**
将可能会导致**表单**中尚未保存内容丢失的场景考虑周全后，在相关的组件上添加**检查修改**交互，即可进行提示。下面以点击**新增资产信息**生成新的**表单**，点击**树**查看其他资产信息为例，通过**检查修改**交互提示用户进行保存，具体步骤如下：
1. **制作表单**：配置需要**提交数据**的表单，并配置好按钮之间的交互设置
2. **设置检查修改**：在“新增资产信息”按钮上添加**检查修改**交互，将该交互调整到已添加交互的第一个，使其第一个执行，**范围**选择**表单**所在的组件`面板4`，其他属性默认
3. **设置切换数据时检查修改**：在**树**中添加**检查修改**交互，设置与第二个步骤相同
### 无修改时提示{#false}
在**提示**下拉选项中选择`无修改时提示`后，使用**检查修改**交互检查[范围](#range)内**表单**，若未做修改则弹出消息框或对话框进行提示，具体操作步骤如下：
1. **添加检查修改交互并设置属性**：选中**保存**按钮，添加**检查修改**交互，**范围**选择`默认`，**提示**设置为`无修改时提示`，**提示方式**选择默认的`消息框`
2. **添加提交表单交互**：在按钮上继续添加**提交表单**交互，并设置好相关属性
:::tip
当生效条件为启用时，交互是从上到下依次执行的，将**检查修改**交互置于第一个，能够先检查**表单**内容的修改，再进行其他操作
::::
## 检查范围设置{#range}
**检查修改**交互中可以设置检查哪一个组件或者容器里的修改，在**范围**中选择：
- **默认**：该选项为默认项，如果该交互的载体组件在对话框中，则该对话框内的组件进行检查；若不在，则整个页面内的组件进行检查
- **整个页面**：将整个页面内的组件进行检查
- **所在对话框/悬浮面板**：对交互的载体组件所在对话框或悬浮面板进行检查
- **指定组件**：选择后，需要在**组件**中勾选进行检查的目标组件
## 提示消息设置{#message}
当在提示下拉框中选择[有修改时提示](#true)或者[无修改时提示](#false)时，会有不同的提示消息设置：
1. 设置为**有修改时提示**时，当**表单**进行了修改且未保存时，进行其他操作时将弹出对话框提示用户，该对话框所显示的内容和标题、按钮名称等都可以进行设置：
- **标题**：默认为“确认”，在对话框的左上角显示
- **内容**：默认为“您的修改尚未提交，是否放弃修改？”，在对话框中部显示
- **确认按钮**：按钮显示的文字默认为“确认”，点击后放弃修改并继续执行操作，在对话框右下角以蓝色按钮样式显示
- **取消按钮**：按钮显示的文字默认为“取消”，点击后关闭对话框，不进行任何操作，在对话框右下角以白色按钮样式显示
2. 设置为**无修改时提示**时，当**表单**内容未做修改时，可以弹出消息框或者对话框进行提示，在**提示方式**中进行设置，可以自定义内容，默认为“页面未发生修改，是否保存？”
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/refresh-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/refresh-data"
title: "SuperPage交互-刷新数据"
---
---
order: 22
navTitle: 刷新数据
---
# SuperPage交互-刷新数据
使用**刷新数据**交互，可以刷新页面内的指定组件的数据，把最新的数据展示出来。如在日志查询界面中下拉框参数全部选择完成后，点击**刷新**按钮，查询最新的系统日志：
示例地址：[刷新数据](https://demo.succbi.com/v5/demo-spg/%E7%B3%BB%E7%BB%9F%E6%97%A5%E5%BF%97%E6%9F%A5%E8%AF%A2)
## 使用刷新数据交互{#refresh}
使用**刷新数据**交互，通常与[按钮](../../components/common/button.md)组件搭配使用。在查询条件或数据发生变化时，若数据未自动刷新，则点击**刷新**按钮会展示最新的数据，以系统日志表查询为例，具体操作步骤如下：
1. **添加按钮交互**：选中按钮，添加**刷新数据**交互
2. **设置交互属性**：**数据源**选择**默认**的全部选项
### 数据源设置{#setting}
**刷新数据**交互刷新的是数据源，即已经添加的模型表、数据加工或数据集，从而驱动引用该数据源的组件数据界面发生变化。目标数据源可以在交互属性栏中设置，默认为**全部**选项，使用该交互可以刷新已经添加的所有数据源，若用户只想刷新某个或某几个数据源，可在下拉选项中按需勾选目标数据源。
:::tip
模型设置了**立即刷新**属性，在查询条件变化时，数据会自动刷新，若是数据库表或者其他情况下出现的数据更新，界面数据无法自动刷新，则需要使用**刷新数据**交互手动刷新数据。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/submit-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/submit-data"
title: "SuperPage交互-提交表单"
---
---
order: 23
navTitle: 提交表单
---
# SuperPage交互-提交表单
“表单”是存放输入组件的容器，它可以是[面板](superpage/component/panel)、[对话框](../../components/embed/dialog.md)或者整个SuperPage页面。**提交表单**交互用于将这些“表单”里的输入组件数据提交至数据库。如添加一条新的企业信息：
示例地址：[列表](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
## 使用提交表单{#use}
**提交表单**是SuperPage[提交数据](../submit-data.md)功能中经常使用的交互，它能够实现[新增数据](../submit-data.md#insert)，[修改数据](../submit-data.md#update)、[删除数据](../submit-data.md#delete)。以下分情况介绍如何使用**提交表单**交互。
### 新增数据{#insert}
**新增数据**即向数据库中新增一条新的数据。在使用**提交表单**时，有以下两个前提：
1. “表单”获取`:newData=true`参数。可通过在前置页面[打开链接](./linkto.md)跳转到本页面时在模式中选择“新数据”或[显示对话框/悬浮面板](./show-dialog.md)的模式中选择“新数据”，具体可参考文档[提交数据之新增数据](../submit-data.md#insert)
2. 为**输入组件**绑定字段
该交互将输入组件的内容写入到绑定的数据表字段中。以新增企业信息为例，具体使用方法如下：
1. **设置新增数据标志**：在**显示对话框/悬浮面板**交互中设置模式为**新数据**
2. **为输入组件绑定写入数据字段**：为输入组件绑定对应字段，使输入组件中输入的内容能够存储到数据库中对应的字段下，如：
- 企业内部序号：在**文本输入**>**数据**中勾选**计算**，在**计算公式**中输入表达式`UUID()`，并勾选**提交数据**，**绑定字段**选择【企业内部序号】
- 对其他输入组件依次绑定字段
3. **设置提交数据交互**：在**提交**按钮的**交互**中添加动作，选择**提交表单**，并设置**范围**为**所在对话框/悬浮面板**
:::tip
为【企业内部序号】添加计算公式的原因在于：企业内部序号为模型表主键，若手动输入则用户可能会输入重复的信息，所以一般为系统自动生成，故可用UUID生成唯一的主键，确保主键不会重复，更多用法可参考文档[UUID](../../../../exp/func/string/UUID.md)。
:::
### 更新数据{#update}
**更新数据**即对数据库中已存在的数据进行修改。在使用**提交表单**更新数据时，有以下两个前提：
1. “表单”需要获取到该数据行，可使用[显示对话框/悬浮面板](./show-dialog.md)的**加载数据**模式或[打开链接](./linkto.md)交互传递主键参数，具体可参考文档[提交数据之修改数据](../submit-data.md#update)
2. “表单”内的输入组件绑定模型字段
通过上述设置打开“表单”时，“表单”内的输入组件会自动显示需要修改的该数据行数据，使用**提交表单**时，该交互会将数据更新至数据库中对应的模型数据行上。
### 多次修改在一个事务中提交{#cud}
**提交表单**能够提交数据集，这决定了该交互能够将增删改后的数据提交至数据库中，实现这一目的需要借助各交互的**暂存**属性。各交互将修改后的数据**暂存**在当前浏览器对象数据集中，**提交表单**交互能够把暂存到数据集上的所有数据提交至数据库中，可参考[暂存](#tmp-store)属性介绍。
示例地址：[提交主从表](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%8F%90%E4%BA%A4%E4%B8%BB%E4%BB%8E%E8%A1%A8&:newData=true)
### 同时提交多个表的数据{#multip}
**提交表单**是根据输入组件绑定的字段进行提交的，在不同的输入组件中可以绑定不同表的数据字段，**提交表单**交互将这些数据一同提交至对应的模型表中。若要限制能够提交哪个模型表，可以在**范围**属性中进行限制，具体可参考[数据的提交范围](#range)。
## 数据的提交范围{#range}
提交表单数据时，可以设置哪些范围内的输入组件能够提交，在**范围**属性中设置，有以下几个选项：
- **默认**：该选项为默认项，如果载体组件在**对话框**组件中，则提交**对话框**内输入组件的数据；若不在，则提交整个页面内的数据
- **整个页面**：将页面内所有绑定了字段的输入组件数据提交至数据库
- **所在对话框/悬浮面板**：提交按钮所在的对话框或悬浮面板
- **指定组件**：选择后，需要在**提交组件**中勾选需要进行提交的组件
- **指定数据集**：只提交绑定了该数据模型的输入组件，且需要在**数据集**属性中勾选数据模型
**忽略隐藏的组件**属性可设置将隐藏的组件数据不进行提交操作，如多页面板的隐藏页，即使内部存在修改，也不会提交。
## 暂存数据{#tmp-store}
**暂存**可以将数据保存在浏览器页面的对象数据集中。暂存后，页面中展示的数据将显示为修改后的内容，需要再次使用**提交表单**交互将修改后的数据提交至数据库中。即使用**暂存**的思路是：
1. 添加“保存”按钮并使用**提交表单**交互，勾选暂存
2. 添加“提交”按钮并使用**提交表单**交互，不勾选暂存
当点击“提交”按钮时，才把数据真正的存入数据库中。若暂存后没有使用未设置**暂存**属性的**提交表单**交互，一旦关闭该页面，**暂存**的数据将不会保存。
与数据提交相关的交互都拥有**暂存**属性，除**提交表单**外，还包括[删除数据](./delete-data.md)、[更新数据](./update-data.md)、[复制数据](./copy-data.md)。在这些交互中设置**暂存**后，无论进行何种修改操作，都不会影响数据库中的数据，最终可通过**提交表单**交互（不设置暂存）将这些修改后的数据一同提交至数据库中。
地址：[列表增删改查](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)
:::tip
若希望将新增的内容删除、已删除或已修改的内容还原，可使用[重置数据](./reset-data.md#reset)交互将指定模型表数据还原为初始状态
:::
## 发起流程{#start-flw}
当需要在SuperPage中使用**工作流**时，比如发起一个请假或报销申请，需要用到**提交表单**交互来**发起流程**，流程的发起涉及到两个关键点：
- 在SuperPage中需要引入[流程表单数据](../datasourse.md#page-img)作为输入组件绑定字段的数据源
- **提交表单**交互勾选**发起流程**属性
当有**工作流**发起时，系统会自动在[流程实例表](../../../../dev/sys-tables/README.md#flow-insts)与[流程任务表](../../../../dev/sys-tables/README.md#flow-tasks)中产生对应的流程数据。在SuperPage中运用工作流的详细说明可参考[与SuperPage集成](../../../workflow/work-with-spg.md)文档。
### 发起流程并进入审批{#start-to-apply}
当需要正式发出申请并进入工作流的审批环节时，需要勾选**发起流程**属性。在往[流程表单数据](../datasourse.md#page-img)中插入数据的同时，系统会自动操作[流程任务表](../../../../dev/sys-tables/README.md#flow-tasks)中的数据，使发起节点的流程任务自动完成并生成下一节点的待办任务，最后达到的效果以请假流程举例：
1. 张三填报了一个请假的申请单，在提交的同时便触发了发起流程，此时完成了工作流中申请节点的任务，张三不能再对提交的内容继续修改
2. 流程继续走到下一个由李四审批的节点，此时系统会自动生成一条审批的待办任务给李四，李四能在自己的待办任务列表中看到这条任务
### 只保存表单数据{#keep-data}
某些发起申请的表单可能会有较多的输入项，可能导致用户不能一次性填写完成，这时候往往需要在页面上提供一个**保存**的按钮，只保存当前已填写的表单数据，不会直接进入到审批环节。这时候需要取消勾选**发起流程**属性，使**提交表单**交互不会让流程进入到审批环节。但是为了用户能再次找到这份数据，系统仍会自动生成第一个节点的待办任务，以请假的流程举例：
1. 张三填写了请假的申请单，此时他使用了页面上的保存按钮，该按钮设置了**提交表单**交互但并未勾选**发起流程**
2. 张三仍可停留在当前页面继续修改他的申请内容，当他从申请页面退出后，他可以在自己的待办任务列表中再次找到这条申请节点的任务，进到表单页面继续修改，直到点击设置了**发起流程**的提交按钮将流程正式发起进入到审批环节
:::tip
此处的**发起流程**属性设置更多的是一种业务上的概念，即提出申请并正式进入审批环节。是否自动生成流程任务数据只与是否通过**提交表单**交互往[流程表单数据](../datasourse.md#page-img)中新增了数据有关。发起和保存的区别仅在于是否会自动完成申请节点的任务。
:::
## 提示信息设置{#confirm}
### 提交前提示{#before}
- **弹出对话框确认**：交互执行前，弹出对话框提示是否确认
- **校验失败后显示提示**：该属性适用于需要**校验数据**的情况，可自定义文字内容，设置后若校验失败，则在顶部显示提示信息；若不进行设置，则根据输入组件自带的校验提示信息进行显示
|设置前|设置后|
| --- | --- |
|||
### 提交后提示{#after}
- **成功后关闭对话框**：默认勾选，提交数据成功后，关闭所在对话框，若没有打开对话框，则无效果
- **成功后显示提示**：提交数据成功后，顶部显示自定义的文字内容
- **失败后显示提示**：提交数据失败后，顶部显示自定义的文字内容
顶部的提示消息框会在页面中停留3秒再隐藏，若希望自定义设置其停留的时间，可以使用[显示消息框](./show-message.md)交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/insert-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/insert-data"
title: "SuperPage交互-插入数据"
---
---
order: 24
navTitle: 插入数据
---
# SuperPage交互-插入数据
**插入数据**交互用于往数据表中插入一条数据，如填写表单内容后点击保存按钮添加一条收货地址：
示例地址：[选择地址](https://demo.succbi.com/v5/demo-spg/mobile/%E9%80%89%E6%8B%A9%E5%9C%B0%E5%9D%80)
## 使用插入数据{#use}
使用**插入数据**交互，需要提前设置好**数据与字段的对应关系**，若插入的数据不在数据库中，则可以往数据表中插入一条新数据。
若是插入的数据在数据表中已经存在，即主键已存在，则会显示`主键重复，或者违反唯一约定`的红色错误提示消息框。以向数据表中成功插入一条收货地址为例：
1. **设置待插入的模型表**：在对话框的“保存”按钮上添加**插入数据**交互，**数据集**选择`选择地址结果`
2. **设置插入字段对应关系**：在**插入字段设置**属性弹出的对话框中添加目标组件的内容与模型表字段的对应关系：
- 目标字段为`收货人`，值为`[收货人].[值]`，表示将插入目标模型表的收货人字段设置为**收货人**的输入值
- 对其他需要插入的字段依次进行设置
:::tip
**插入数据**交互一次只能插入一条数据，如果要插入多条数据，可以使用[执行sql](https://docs.succapp.com/v5/superpage/action/execute-sql)交互执行insert语句来实现批量插入。
:::
## 设置插入字段{#setting}
**插入数据**需要提前设置插入哪些字段的值，设置后会将指定的值插入到目标字段，点击**插入字段设置**，在弹出的对话框中进行设置：
- **目标字段**：模型表需要插入的字段
- **值类型**：支持选择表达式
- **值**：支持写表达式，通常为某个输入组件的值或者传入的参数值
## 提示信息设置{#tip}
**插入数据**交互完成前后可自定义提示信息，在属性栏中勾选了相关选项后，交互完成前会弹出对话框进行确认，交互完成后会弹出顶部消息框进行提示，具体设置可以参考[提交表单](./submit-data.md#confirm)文档。
## 暂存{#store}
**暂存**可以将要插入的数据保存在浏览器页面的对象数据集中。暂存后页面中展示的数据将显示为最新的内容，需要再次用[提交表单](./submit-data.md)交互将插入后的数据提交至数据库中。具体可以参考[提交表单](./submit-data.md#tmp-store)中暂存的用法。
## 插入数据与提交表单的区别{#difference}
**提交表单**也可以用来往数据表中插入一条数据，不同之处在于**插入数据**只能插入新数据，而**提交表单**还可以修改数据表中已存在的数据，更多说明可以参考[提交表单](./submit-data.md)交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/update-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/update-data"
title: "SuperPage交互-更新数据"
---
---
order: 25
navTitle: 更新数据
---
# SuperPage交互-更新数据
**更新数据**交互用于对数据进行更新修改，如更新一批资产的使用状态：
示例地址：[列表增删改查](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)
## 使用更新数据{#how-to-use}
**更新数据**交互在执行时根据[数据与字段的对应关系](#corresponding)将数据更新至数据库中，若待更新的数据不存在，则可以执行新增数据。以弹出对话框并使用**更新数据**交互修改资产的状态为例，使用步骤如下：
1. **设置待更新的模型表**：在对话框的“确定”按钮上添加**更新数据**交互，并在**数据**属性中添加需要更新的模型表，需要提前将该模型表引入至当前SuperPage页面
2. **设置更新范围**：设置**数据范围**为“勾选的”，**数据组件**选择“列表1”
3. **设置更新字段对应关系**：在**更新字段设置**属性中[设置输入组件的内容与模型表字段的对应关系](#corresponding)，如：
1. 目标字段为“资产状态”，值为`[修改资产状态]`，表示将资产状态改为下拉框“修改资产状态”中选择的值
2. 对其他需要更新的字段依次进行设置
**数据**属性的下拉列表中包括所有可写的数据集，在该属性中设置需要更新的目标数据集，仅可选择一项，当需要为多个模型表的数据进行更新时，需要添加多个**更新数据**交互。
## 更新属性设置{#property}
**更新数据**交互执行时会修改[数据范围](#update-range)内的数据，并按照[字段的对应关系](#corresponding)将数据更新至对应的字段中。
### 数据的更新范围{#update-range}
**更新数据**交互仅更新其范围内的数据，可选项有：
- **勾选的**：此范围下需要设置**数据组件**属性，需要确认勾选数据的载体组件，通常是[列表](../../components/data/list.md)
- **当前行**：一般使用于[列表](../../components/data/list.md)内部的按钮，更新触发交互所在行的数据
- **高亮的**：高亮选中，类似于勾选，只是操作体验不同，一般应用于[树](https://docs.succapp.com/v5/superpage/component/tree)
- **按条件**：仅更新满足**条件字段**的数据，表示当某一行的某个字段数据满足特定的值时，更新该行数据
- **当前查询结果**：更新指定模型表中当前过滤出的数据，如可通过[字段过滤](../../components/input/fieldsfilter.md)组件来过滤列表数据，更新**当前查询结果**可更新列表中所有数据
### 设置更新字段{#update-fields}
更新数据时需要明确地设置更新哪些字段的值，SuccBI会自动将指定的值更新至目标字段。点击**更新字段设置**按钮，在弹出的对话框中进行设置：：
- **目标字段**：模型表需要更新的字段
- **值类型**：有以下几个选项
- **表达式**：输入表达式为字段赋值
- **自增**：指定字段进行自增更新，在“值”中输入自增数据的大小，如输入2表示每次+2
- **自减（>0）**：指定字段进行自减更新，其最小值为0
- **自减**：指定字段进行自减更新，其最小值可以为负数
## 数据不存在时执行插入{#none-insert}
当更新数据时，如果在数据库中不存在该数据，可以继续执行插入操作，该操作仅支持插入一行新的数据。需要勾选**数据不存在时执行插入**属性，并在**插入字段设置**中设置字段与数据的对应关系，注意这里只能使用表达式进行取值。
## 暂存{#tmp-storage}
**暂存**可以将数据保存在浏览器页面的对象数据集中。**暂存**后，页面中展示的数据将显示为更新后的内容，需要再次使用[提交表单](./submit-data.md)交互将更新后的数据提交至数据库中。可参考[提交表单](./submit-data.md)中**暂存**的使用方法。
## 提示信息设置{#tooltips}
**更新数据**交互完成前后可自定义提示信息，设置后会在交互动作完成前后弹出对话框确认，具体设置可参考[提交表单](./submit-data.md)。
## 检查更新结果{#check}
更新数据时，可以检查实际更新的数据行数与期望更新的数据行数是否一致，当两者之间存在差异时，撤销更新并对用户进行提示。如在当前页面中勾选了三行数据进行更新，若其中一行数据被其他人删掉了，则实际只更新了两行数据，与期望更新的三行数据不符，此时会提示用户更新失败。对于期望更新的行数有以下几种设置：
- **自动（默认）**：分为以下几种情况
- 若对主键设置了过滤条件，则默认检查行数为1行
- 若[数据范围](#update-range)是`当前行`，则默认检查行数为1行
- 若**数据范围**是`勾选的`或`高亮的`，则默认检查行数为勾选或高亮的行数
- 若**数据范围**是`当前查询结果`，则默认检查行数为当前查询结果的行数
- 若**数据范围**是`按条件`，则默认检查行数为满足条件的数据行数
- **单行**：检查是否仅更新了一行数据
- **等于期望行数**：检查是否更新了期望行数的数据，需要在**成功更新的行数**输入框中设置期望值
- **期望行数范围**：检查实际更新的行数是否在区间范围内。若只填写了下限，则表示实际更新的行数需要大于等于该数值；若只填写了上限，则表示实际更新的行数需要小于等于该数值
- **不检查**：不检查当前更新数据的结果
若检查更新结果与预期不符合，还可以自定义编辑其提示信息，需要在**失败提示**输入框中进行设置。
:::tip
**更新数据**是一个事务性的操作，当数据库返回的实际更新行数与期望更新行数不符合时将进行回滚，并且通知用户**更新数据**交互执行失败。
:::
## 更新数据与提交表单{#difference}
**更新数据**交互和[提交表单](./submit-data.md#update)交互都可以对数据进行更新，在只需要更新一行数据时，二者均可使用，但若希望批量修改多行数据，则选择**更新数据**交互更为方便。**提交表单**交互更多的是用来提交“表单”的数据内容，它通常是在一个事务内把“表单”内部所有更新、删除、新增后的数据一同提交入库，这需要“表单”内部有若干个绑定了字段的[输入组件](../../components/input/README.md)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/delete-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/delete-data"
title: "SuperPage交互-删除数据"
---
---
order: 26
navTitle: 删除数据
---
# SuperPage交互-删除数据
**删除数据**交互用于模型表中的数据删除，常与[列表](../../components/data/list.md)搭配使用。如下动图所示，在列表中删除指定数据：
示例地址：[列表-增删改查](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8)
## 使用删除数据{#use}
**删除数据**交互通常搭配[列表](../../components/data/list.md)组件使用，设置了**删除数据**交互的[按钮](../../components/common/button.md)可放在[列表](../../components/data/list.md)内删除对应行数据，或放在[列表](../../components/data/list.md)外勾选删除多行数据，具体制作步骤如下：
1. 删除列表当前行
- 在[列表](../../components/data/list.md)中添加操作按钮，并为按钮添加**删除数据**交互
- 在交互属性设置>**数据**中指定要删除的数据模型，此处通常与列表使用的数据一致
- 设置**数据范围**为**当前行**，意为列表中每一行的按钮仅能删除所在行的数据
2. 删除列表勾选行
- [列表](../../components/data/list.md)中需要设置勾选框，在列表外部设置按钮，添加**删除数据**交互
- 在交互属性设置>**数据**中指定要删除的数据模型
- 设置**数据范围**为**勾选的**，此时会多出**数据组件**属性，选择勾选数据的对象组件，即第一步中设置的[列表](../../components/data/list.md)
## 数据的删除范围{#deleterange}
在交互设置**数据**属性中指定好对象模型表后，可在**数据范围**中设置数据的删除范围，有以下几种：
- 勾选的：此范围下需要设置**数据组件**属性，需要确认勾选数据的载体组件，通常是[列表](../../components/data/list.md)
- 当前行：应用于[列表](../../components/data/list.md)内部按钮，删除触发交互所在行的数据
- 高亮的：高亮选中，类似于勾选，只是操作体验不同
- 当前查询结果：删除指定模型表中当前过滤出的数据，如可通过[字段过滤](../../components/input/fieldsfilter.md)组件来过滤列表数据，删除当前查询结果可起到清空列表的作用
## 暂存数据{#tmpstorage}
**暂存**可以将数据保存在浏览器页面的对象数据集中。**暂存**后，页面中展示的数据将显示为删除后的内容，需要再次使用[提交表单](./submit-data.md)交互将删除后的数据提交至数据库中。可参考[提交表单](./submit-data.md)中**暂存**的使用方法。
## 提示信息设置{#tooltips}
**删除数据**交互完成前后可自定义提示信息，设置后会在交互动作完成前后弹出对话框确认，具体设置可参考[提交表单](./submit-data.md)。
## 应用场景{#apply}
### 列表数据的删除{#apply-list}
与[列表](../../components/data/list.md)结合的**删除数据**应用场景主要分为三种：
- 列表内删除当前行
- 列表外批量删除勾选行
- 清空当前查询结果，即删除当前列表所有数据
前两类应用场景已在[使用删除数据](#use)中说明，此处不再重复。删除列表当前所有数据需要用到删除**当前查询结果**，如下动图中点击清空即为删除当前列表中查询出的结果：
示例地址：[列表增删改查](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E5%88%97%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)
1. 给要删除数据的模型表设置过滤条件，或者也可以搭配[字段过滤](../../components/input/fieldsfilter.md)组件来过滤数据源
2. 删除数据交互设置中**数据**指定为第1步设置过滤条件的数据源，**数据范围**指定为**当前查询结果**
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/import-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/import-data"
title: "SuperPage交互-导入数据"
---
---
order: 27
navTitle: 导入数据
---
# SuperPage交互-导入数据
**导入数据**交互用于将excel或csv文件中的数据提交至数据库中，常与[按钮](../../components/common/button.md)搭配使用。如点击按钮，使用导入数据的方式将企业信息填报至数据库中：
示例地址：[列表-增删改查](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8)
## 使用导入数据{#use}
### 数据来源{#origin}
1. **excel、csv文件**：这类文件的数据从外部获取，并通过[文件上传](#upload_method)将数据导入
2. **其他模型表**：从数据库的其他模型表中获取数据并作为补充与excel一同导入，可参考[关联模型表数据导入](#other_table)
### 使用场景{#usage}
1. **直接导入**：通过**导入数据**交互，直接将数据存入目标模型表中
2. **筛选后导入**：将通过交互导入的数据存入至**临时表**中，通过[复制数据](./copy-data.md)对筛选后的数据保存至最终所需的目标表中
### 导入文件的要求{#demand}
1. **字段名称相同**：若勾选“导入所有同名字段”，则excel第一行统一为字段名称，该字段名称需要与模型表内字段名称完全一致；若不勾选，则无此要求，但必须在[更多字段设置](#other_field)中加入映射关系
2. **必须包含主键字段**：上传的excel文件中，必须包含目标模型表的[主键](../../../../data-gov/model/model-settings.md#primary-key)字段
## 示例步骤{#step}
为避免上传excel时数据格式不统一，可以使用[打开链接](./linkto.md#download)交互提供excel模板，下面以企业信息的导入填报为例，具体操作步骤如下：
### 提供下载模板{#model}
1. **制作excel模板**：用excel制作一个表格，在第一行的每一列中输入字段名称
2. **将excel导入门户中**：打开SuperPage资源树，右键导入已经制作好的excel
3. **添加下载excel模板的按钮**：新增**下载模板**的按钮，在**交互**中添加[打开链接](./linkto.md)交互，并链接到excel的存放路径
### 设置导入属性{#set\_property}
1. **按钮组件添加交互**：选中**按钮**组件，在**交互**中添加**导入数据**
2. **设置交互属性**：在**交互**>**导入数据**>**文件**中选择上传文件，在**目标数据集**选择对应的模型表，选择[覆盖模式](#write_method)，勾选**导入所有同名字段**
3. **更多字段设置**：在[更多字段设置](#other_field)中的**目标字段**中选择excel模板内没有提供的字段，并手动输入表达式给该字段赋值
:::tip
**目标数据集**属性用于设置将数据导入至的数据模型，该模型需提前在SuperPage中进行引用，并设置该模型为**可写**或**可读可写**。
:::
## 数据文件上传方式{#upload\_method}
**导入数据**交互提供了两种上传方式，在**文件**属性中进行设置，有以下两个选项：
1. **上传文件**：表示直接弹出一个选择文件的对话框，选择文件上传并导入
2. **附件控件**：表示从附件控件中取文件信息，需要在**附件控件**属性中选择对应的[上传附件](../../components/input/upload.md)组件
若需获取上传的文件ID，可以勾选**将文件ID设置给指定参数**属性，将上传的文件ID赋值给提前设置好的**全局参数**。如对导入的文件进行筛选，使用文件ID进行区分，则可通过勾选该属性获取文件ID。
## 数据的导入方式{#data}
### 数据写入方式{#write\_method}
数据导入至数据库中时，需要为其设置导入方式，如**追加**、**覆盖**、**合并**等，在**覆盖模式**属性中进行设置：
- **覆盖全部**：清空表内原有的所有数据，并将导入的数据填入
- **追加**：在表内原有的数据上进行追加，不覆盖原有数据，若存在主键相同的数据，不进行任何操作
- **合并**：根据**主键**进行判断，若**主键**相同，则进行覆盖导入，若**主键**不同，则进行追加导入
勾选**导入所有同名字段**，系统自动将excel或csv文件中的字段名称与模型表的字段名称进行匹配并导入；若不进行勾选，则需要在[更多字段](#other_field)中设置目标模型表的字段与文件字段的对应关系，否则无法正确导入。
### 关联模型表数据导入{#other\_table}
在导入excel数据的基础上，还可以从其他模型表中获取数据并补全至指定的字段中。如上传企业信息excel时，法定代表人不需要填写，而是从其他表中获取到该企业的法定代表人并存入至目标数据模型中，**关联数据导入**属性就提供了从其他表取数的入口。勾选后需要对如下属性进行设置：
1. **关联数据集**：选择需要从中取数的模型表
2. **关联数据字段**：**关联数据集**中需要与excel进行关联的字段，如模型表字段【企业名称】
3. **关联文件字段**：与**关联数据集**需要进行关联的字段，如excel中的【企业名称】
**关联数据集**的数据将作为补充数据与excel的数据一同导入至目标模型表，必须在[字段设置](#other_field)中设置**关联数据集**字段与目标数据集的映射关系，若设置的字段在excel中已经存在，则以**关联数据集**中的数据为准。
### 更多字段设置{#other\_field}
需要由系统自动生成的字段值，可以在**更多字段**属性下进行设置，如创建时间不需要在excel中填写，可通过`now()`表达式将当前时间赋值给创建时间字段。勾选**更多字段**，并在**更多字段**>**字段设置**对话框中编辑。
1. **目标字段**：目标数据集的字段
2. **类型与值**
- 表达式：通过表达式取到数据，“值”为表达式
- 文件ID：将上传的文件ID赋给目标字段
- 关联表字段：使用**关联数据导入**后必须设置的类型，“值”为**关联数据集**对应的**目标数据集**字段
- 文件字段：对应上传excel中的字段，“值”为excel的字段名称。
- excel列名：每列数据的列头一般是本列数据的标题，例如“资产名称”
- 行号：需要获取每行数据的行号时，可手动输入“行号”
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/copy-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/copy-data"
title: "SuperPage交互-复制数据"
---
---
order: 28
navTitle: 复制数据
---
# SuperPage交互-复制数据
**复制数据**交互主要应用于多行数据的批量插入。如下动图，为检查任务添加待查企业，将指定的企业信息复制到待查任务表：
示例地址：[复制数据](https://demo.succbi.com/v5/demo-spg/%E5%A4%8D%E5%88%B6%E6%95%B0%E6%8D%AE)
## 使用复制数据{#use}
**复制数据**交互通常是将设置了[映射关系](#mapping)的字段中的内容按照指定的[数据范围](#copyrange)以及[覆盖模式](#coveragemode)从**源数据集**复制到**目标数据集**中。以新增检查对象为例，具体使用方法如下：
1. **按钮组件添加交互**：选中**按钮**组件，在**交互**中添加**复制数据**
2. **设置对象数据集**：在**源数据集**和**目标数据集**属性设置中分别指定`企业基本信息表`和`企业对象表`为复制的源表以及目标表
3. **设置数据范围和覆盖模式**：将[数据范围](#copyrange)设置为**当前查询结果**，[覆盖模式](#coveragemode)设置为**追加**，意为将当前查询出来的企业作为本次检查的对象且不会重复添加相同企业
4. **设置字段映射关系**：勾选[导入所有同名字段](#same-field)并设置[更多字段](#more-field)，在[更多字段](#more-field)可自定义**目标字段**的数据来源
## 数据的复制范围{#copyrange}
在交互设置**数据范围**中可设置数据的复制范围，决定了源数据集中哪些数据会被复制到目标数据集，设置选项可参考[删除数据](./delete-data.md#deleterange)文档中的详细说明。
## 数据的写入方式{#coveragemode}
**覆盖模式**决定了数据从**源数据集**复制到**目标数据集**时，以主键为依据做何种操作：
- 覆盖全部：会先清空**目标数据集**中的数据，再将**源数据集**中的复制数据插入到**目标数据集**中
- 追加：以主键为依据往**目标数据集**中插入数据，会略过与**目标数据集**中主键重复的数据
- 合并：对于主键重复的数据为合并操作，其余数据正常插入
## 字段映射关系设置{#mapping}
### 导入所有同名字段{#same-field}
勾选**导入所有同名字段**属性设置后，**源数据集**与**目标数据集**中的字段按照以下顺序进行匹配：
1. [物理字段](../../../../data-gov/model/README.md#model-field)名相同的优先匹配
2. [物理字段](../../../../data-gov/model/README.md#model-field)名不同但[名称](../../../../data-gov/model/README.md#model-field)相同的其次匹配
复制时仅能将有映射关系的字段内容从**源数据集**写入到**目标数据集**中。
### 更多字段{#more-field}
**更多字段**设置应用于某些字段无法与**源数据集**自动形成映射关系时，优先级高于**导入所有同名字段**设置。可通过两种方式来设置**目标字段**中的内容：
- 表达式：可输入计算公式作为**目标字段**的值存入**目标数据集**中，如可通过表达式`$user.user_id`获取当前用户代码设置到对应的字段
- 源表字段：可从**源数据集**中选择字段与**目标数据集**中的**目标字段**形成映射关系，此时不需要物理字段名或字段名称保持一致
:::tip
**复制数据**通常用于在目标表中插入多行数据，因此**目标数据集**中的主键应当注意有设置正确的映射关系
:::
## 数据暂存{#tmpstorage}
**暂存**可以将数据保存在浏览器页面的对象数据集中。**暂存**后，页面中展示的数据将显示为复制后的内容，需要再次使用[提交表单](./submit-data.md)交互将复制后的数据提交至数据库中。可参考[提交表单](./submit-data.md)中**暂存**的使用方法。
## 设置提示信息{#tooltips}
**复制数据**交互完成前后可自定义提示信息，包括校验提示以及交互完成前后的提示信息，具体设置可参考[提交表单](./submit-data.md)。
## 应用场景{#apply}
### 确认Excel导入数据{#apply-Excel}
在使用Excel[导入数据](./import-data.md)时,通常不希望导入的数据直接入库，这时候可以先将数据导入到一张临时表中，等到数据确认后再将临时表中的数据复制到目标表中：
示例地址：[列表增删改查](https://demo.succbi.com/v5/demo-spg/%E5%88%97%E8%A1%A8%E5%A2%9E%E5%88%A0%E6%94%B9%E6%9F%A5)
1. 需要额外准备一张临时表，通常与正式表一致即可。使用[导入数据](./import-data.md)将数据先插入到一张临时表，并通过[列表](../../components/data/list.md)来展示临时表数据
2. 确认临时表中的数据，通过[删除数据](./delete-data.md)将一些不合适的数据排除
3. 使用**复制数据**，将临时表中的数据追加覆盖到正式表
4. 通过[删除数据](./delete-data.md)清空临时表中数据
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/send-email.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/send-email"
title: "SuperPage交互-发送邮件"
---
---
order: 32
navTitle: 发送邮件
---
# SuperPage交互-发送邮件
使用**发送邮件**交互，可以给多人发送邮件，如下填写好工作周报内容后自动发送给相关同事：
示例地址：[发送邮件](https://demo.succbi.com/v5/demo-spg/发送邮件)
## 使用发送邮件{#send}
使用**发送邮件**交互可搭配输入组件进行使用，来获取邮件的接收者，主题，以及正文内容等。以自定义工作周报邮件为例：
1. **添加发送按钮**：在页面添加按钮，名称设为`发送`
2. **添加交互并设置属性**：
1. 选中`发送`按钮，添加**发送邮件**交互
2. 在交互中，设置**收件人邮箱**设为`${[收件人]}`；**抄送人邮箱**设为`${[抄送人]}`；**消息内容**选择`自定义`；**主题**设为`${[主题]}`；**正文**内容选择`${[富文本输入1].[值]}`
:::tip
发送邮件需提前配置邮件服务，在**系统设置**>**外部服务**>[邮件](../../../../sys-settings/more/remote-services/email.md)中可以设置
:::
## 接收人邮箱设置{#receiver}
在**发送邮件**的属性窗口可设置**收件人邮箱**和**抄送人邮箱**，接收人邮箱设置通常有如下使用场景：
- 想要自定义邮件的接收人，就可以与输入组件搭配使用，获取输入组件的值，如`${[收件人]}`
- 若想要邮件的接收人固定为同一人，则直接在收件人邮箱这里填写具体的邮箱
- 若邮件想要发送给多人，可以在抄送人或收件人处填写多个邮箱号以英文的`,`隔开
## 邮件内容设置{#content}
邮件的内容设置支持自定义以及模板选择。在**发送邮件**的属性窗口的**消息内容**处即可设置。
### 自定义邮件内容
根据具体的需求用户可以自定义邮件的内容，在**消息内容**属性中选择`自定义`，可以设置邮件的标题和正文内容，以下图为例：
- **标题**：邮件的标题，可输入具体的文本或获取输入组件的值，如`${[主题]}`
- **正文**：邮件的正文，提供富文本的编辑器，也可以从输入组件中获取数据，如`${[富文本输入1].[值]`
### 使用模板发送邮件
模板的选择使用户在固定场景上发送邮件更加快捷与方便。模板的设置与新建在**系统管理**>[协同办公](https://docs.succapp.com/v5/sys/settings/co)中完成。可以通过创建参数向模板传递数据，模板获取到指定的数据后就可以按照设置好的模板发送邮件。**消息内容**选择模板，同时还需要设置具体模板及模板参数，以下图为例：
- **模板**：存放的是在[协同办公](https://docs.succapp.com/v5/sys/settings/co)中创建的模板，如选择`请假申请模板`
- **模板参数**：参数名称在[协同办公](https://docs.succapp.com/v5/sys/settings/co)中创建模板时进行定义，参数值可通过输入组件获取，如开始时间的参数值为`[开始时间].[值]`
## 提示信息设置{#tips}
对于邮件的发送状态也可以设置对应的提示信息，系统默认勾选**成功后显示提示**。可根据需要勾选**成功后显示提示**与**失败后显示提示**，在勾选框下面的文本框处可以设置提示的文本，在邮件发送后就会根据状态，显示[提示信息](./submit-data.md#after)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/call.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/call"
title: "call"
---
---
order: 33
navTitle: 拨打电话
---
# SuperPage交互-拨打电话
**拨打电话**交互适合在手机端使用，可以对当前交互中设置的手机号进行呼叫、复制或者添加到手机通讯录。
## 使用拨打电话{#use}
**拨打电话**交互中的电话号码可以是一个固定的号码，也可以是从[模型表](../../../../data-process/README.md)中获取或通过[表达式](../../../../exp/README.md)获取的动态号码。下面以给移动列表中的按钮添加**拨打电话**交互为例来介绍如何使用：
示例地址：[拨打电话](https://demo.succbi.com/v5/demo-spg/mobile/%E6%8B%A8%E6%89%93%E7%94%B5%E8%AF%9D)
1. **选择组件**：选择需要添加交互的组件，此处选中[移动列表](../../components/mobile/mobilelist.md)
2. **添加交互**：在右侧属性栏处，打开设置子项对话框，选择按钮后，切换到交互栏，点击`添加`按钮新增一个**拨打电话**的交互
3. **设置电话号码**：打开输入框后，输入模型名称以获取到模型中的`联系电话`的字段内容
## 设置电话号码{#set-phonenumber}
电话号码可以是固定的某一个号码，也可以是从[模型表](../../../../data-process/README.md)或通过[表达式](../../../../exp/README.md)获取到的动态号码：
- 固定号码：直接输入号码即可，如 `13698754567`
- 动态号码：需要先输入宏，然后在宏中使用表达式或引用模型表字段，如 `${[基本信息表].[联系电话]}`
在设置电话号码时，如果是像座机号码那样中间有`-`符号的无需输入，系统会自动识别，且电话号码类型不限：
- 短号码，如 `12306`、`110`
- 座机号码，如 `4008-0401-99`
- 带区号的电话号码，如 `021-88568888`
- 手机号码，如 `13698754567`
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/send-verify-code.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/send-verify-code"
title: "send-verify-code"
---
---
order: 34
navTitle: 发送验证码
---
# SuperPage交互-发送验证码
使用**发送验证码**交互用来为指定的手机号码发送一条验证码，结合[校验验证码](./check-verify-code.md)交互来使用，如注册时用户输入收到的验证码校验成功后才能成功注册：
示例地址：[提交单行数据](https://demo.succbi.com/v5/demo-spg/%E6%8F%90%E4%BA%A4%E5%8D%95%E8%A1%8C%E6%95%B0%E6%8D%AE/newData)
## 使用发送验证码{#use}
使用**发送验证码**交互发送短信验证码时需要提前进行如下配置：
1. 需要提前配置**短信**服务，在系统设置>外部服务>[短信](../../../../sys-settings/more/remote-services/message.md)中配置，短信运营商会提前配置好外部短信模板以及外部短信模板参数
2. 同时需要在**系统设置>[协同办公](https://docs.succapp.com/v5/sys/settings/co)>消息模板**中配置系统内的模板，并添加上一步中和短信运营商定义的外部模板参数同名的模板参数，以此来定义好外部模板参数与系统内模板参数的映射关系
以新用户注册时向手机发送一条验证码为例，用户在填写完手机号码后，点击**获取验证码**按钮，向用户手机发送一条模板内容的短信验证码：
1. **添加交互**：选中`按钮4`,添加**发送验证码**交互
2. **设置交互相关属性**：设置**启用条件**为`[验证码发送记录表].[总行数]<=3`，**验证码类型**选择`短信`，**消息模板**选择`短信发送模板`，**验证码参数**选择`code`，**电话号码**设置为`${[文本输入3].[值]}`
:::tip
- 设置启用条件目的是限制同一用户一天最多只能发送三次
- `code`是短信运营商定义的外部模板参数名，用来传递验证码信息，需要在**系统设置>[协同办公](https://docs.succapp.com/v5/sys/settings/co)>消息模板**中添加模板时添加该参数
:::
## 短信验证码消息设置{#properties}
发送短信验证码支持使用模板发送，可以根据业务创建不同的消息模板，该交互提供了如下的属性设置：
- **消息类型**：提供了短信消息推送，在**验证码类型**属性中选择`短信`即可
- **消息内容设置**：短信验证码的消息内容使用模板来自定义
- **消息模板**：：**消息模板**下拉框选项会显示提前在系统设置>[协同办公](https://docs.succapp.com/v5/sys/settings/co)中已经配置好的**消息分类**为验证码的模板，使用发送验证码交互需要选择**发送方式**为`短信`的消息模板
- **模板参数**：参数名称在[协同办公](https://docs.succapp.com/v5/sys/settings/co)中创建消息模板时定义的全局参数，参数值可以通过输入组件获取
- **验证码参数**：下拉选项显示**系统设置>[协同办公](https://docs.succapp.com/v5/sys/settings/co)>消息模板**中已经添加用来映射**外部模板参数**的**短信模板参数**，选择运营商定义的传递验证码信息的参数后，使用发送验证码交互时系统会自动生成验证码信息传递给该参数
- **电话号码**：支持写表达式，一般是某个输入组件的值，为短信服务商发送验证码的目标电话号码，未指定时会选择系统用户表中的电话号码，如果系统用户表中也没有电话号码，则该交互失效
:::tip
使用**发送验证码**交互时的手机号码和验证码会记录在数据库的[验证码记录表](../../../../dev/sys-tables/README.md#verify)中。
:::
## 提示消息设置{#message}
对于短信验证码的发送状态可以设置对应的提示信息，系统默认勾选**成功后显示提示**和**失败后显示提示**，可根据需要勾选。在勾选框下面的文本框处可以设置提示的文本，在短信验证码发送后就会根据发送状态，显示[提示信息](./submit-data.md#after)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/check-verify-code.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/check-verify-code"
title: "check-verify-code"
---
---
order: 35
navTitle: 校验验证码
---
# SuperPage交互-校验验证码
**校验验证码**交互结合[发送验证码](./send-verify-code.md)来使用，用来在发送验证码之后对验证码和手机号码进行校验，如用户在输入验证码校验成功后才能成功注册：
示例地址：[提交单行数据](https://demo.succbi.com/v5/demo-spg/%E6%8F%90%E4%BA%A4%E5%8D%95%E8%A1%8C%E6%95%B0%E6%8D%AE/newData)
## 使用校验验证码交互{#check}
使用**校验验证码**交互需要提前设置好需要校验的**验证码**和**手机号码**，验证是否与发送验证码时用到的验证码和手机号码相匹配。通常适用于提交数据的场景，在输入指定位数的验证码后执行该交互，校验成功则提交数据，否则显示校验失败的提示。以校验新用户注册时的手机号和验证码为例，具体操作步骤如下：
1. **添加交互**：选择**确认**按钮，添加**校验验证码**交互
2. **配置交互相关属性**：**启用条件**设置为`[勾选框1]==1`，**验证码**设置为`${[文本输入9]}`，**手机号码**设置为`${[文本输入3]}`，并设置好相应的提示信息
:::tip
使用**发送验证码**交互时的**手机号码**和**验证码**记录在后台的[验证码记录表](../../../../dev/sys-tables/README.md#verify)中，使用**校验验证码**交互系统会在后台进行校验。
:::
## 设置校验验证码和手机号码{#checkboth}
**校验验证码**交互可以校验用户输入的验证码是不是运营商发送的验证码，同时也可以校验手机号码是不是发送该验证码的手机号码：
- **验证码设置**：在**验证码**属性中设置，通常设置为用户输入验证码的输入组件的值，支持写表达式
- **手机号码设置**：在**验证手机**属性中设置，主要分以下两种情况
- **勾选验证手机选项**：发送验证码时指定了手机号码，使用**校验验证码**交互校验手机号码需要指定相同的手机号码，在**手机号码**属性中设置对应的表达式
- **不勾选验证手机选项**：发送验证码时没有指定手机号码，使用**校验验证码**交互也不需要指定验证手机号码，会自动取系统用户表中的用户手机号码进行验证。如果系统用户表没有用户的手机号码，则该交互失效
## 提示消息设置{#message}
对于短信验证码的校验状态可以设置对应的提示信息，系统默认勾选**成功后显示提示**和**失败后显示提示**，可根据需要勾选。在勾选框下面的文本框处可以设置提示的文本，在输入验证码后使用该交互就会根据校验状态，显示[提示信息](./submit-data.md#after)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/export-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/export-data"
title: "SuperPage交互-导出数据"
---
---
order: 36
navTitle: 导出数据
---
# SuperPage交互-导出数据
**导出数据**交互可以将当前页面查询出的数据导出为Excel或csv数据文件，常与[按钮](../../components/common/button.md)搭配使用。如点击导出按钮，将企业信息导出为Excel文件：
## 使用导出数据{#use}
下面以企业信息**导出数据**为例，具体操作步骤如下：
1. **按钮组件添加交互**：选择**按钮**组件，在**交互**中添加**导入数据**
2. **设置交互属性**：在**交互**>**导出数据**>**数据组件**中选择`列表1`，勾选**弹出导出选项对话框**，再依次勾选**允许选择导出页**和**允许选择导出格式**，更多设置可查看[设置允许用户选择导出文件属性](#custom)
## 设置导出文件默认属性{#property}
可以设置导出文件的默认名称、文件格式、导出数据量。如下：
- **数据组件**：选择**导出数据**交互作用的目标组件，仅导出**列表**组件的数据
- **文件名**：导出的数据文件默认名称
- **默认**：默认设置，系统会根据当前的SuperPage页面的名称自动生成同名的文件名称
- **自定义**：自定义导出文件名称，支持填写表达式
- **导出格式**：支持**xlsx**和**csv**两种格式，默认是**xlsx**
- **导出页**：支持导出**当前页**和**所有页**两种，默认是**当前页**
## 设置允许用户选择导出文件属性{#custom}
用户在导出数据文件时，可以自定义文件名称、文件格式、导出数据量，通过勾选**弹出框设置**后，可在**弹出框设置**下方勾选相应的属性对用户开放，如下：
- **允许选择导出页**：在导出弹窗中可选择导出**当前页**或**所有页**
- **允许选择导出格式**：在导出弹窗可选择**可选格式**中勾选的文件格式
- **可选格式**：可选择**xlsx**和**csv**两种格式，也可以选择**全部**
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/order-data.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/order-data"
title: "SuperPage交互-排序数据"
---
---
order: 37
navTitle: 排序数据
---
# SuperPage交互-排序数据
使用**排序数据**交互，可以实现让数据按照指定的字段升序或降序显示。如点击成立日期，可按照成立日期对企业进行升序或降序切换：
示例地址：[排序数据](https://demo.succbi.com/v5/demo-spg/%E6%8E%92%E5%BA%8F%E6%95%B0%E6%8D%AE)
## 使用排序数据{#start}
使用**排序数据**交互，一般需要搭配[按钮](../../components/common/button.md)组件使用，同时需要使用[列表](../../components/data/list.md)或[浮动面板](../../components/layout/floatpanel.md)组件来展示数据。以点击成立日期按钮，对企业列表按照**成立日期**进行升序和降序排列切换为例，具体步骤如下：
1. **添加组件：** 在页面中添加`成立日期`按钮，勾选[启用切换](../../components/common/button.md#switch)
2. **添加交互并设置属性：**
1. 选中`成立日期`按钮，添加**排序数据**交互
2. 在交互中，数据集选择`企业基本信息`，**排序**表达式为`CLRQ ${IF([成立日期].[选中值],'desc','asc')}`即可
:::tip 按钮启用切换属性说明
[按钮](../../components/common/button.md)组件的[启用切换](../../components/common/button.md#switch)属性，是否勾选会影响按钮的返回值，如下：
- 未勾选该属性时：连续多次点击按钮，按钮的`选中值`不受影响，始终返回`TRUE`
- 勾选该属性时：
- 第一次点击按钮时，按钮的`选中值`返回`TRUE`
- 再次点击按钮时，`选中值`为`FALSE`
:::
## 设置排序依据{#order}
**排序**属性是数据进行排序的依据，可设置依据的字段以及升序或降序排列。输入为宏表达式，可以逗号分割多个字段，如`字段1 asc,字段2 desc`。字段名可以是[名称](../../../../data-gov/model/README.md#model-field)也可以是[物理字段名](../../../../data-gov/model/README.md#model-field)。如以下几种写法：
- `CLRQ desc`：按照成立日期降序排列
- `成立日期 desc`：按照成立日期降序排列
- `CLRQ ${IF([成立日期].[选中值],'desc','asc')}`：点击成立日期按钮对数据按照成立日期进行升序和降序切换
- `${[排序方式].[值]} desc`：排序方式为下拉框，下拉框是字段名列表，选择下拉框中某个选项即可按照该字段降序排序，该交互是设置在下拉框组件上
- `${[排序方式].[值]} ${if (btn1, "DESC", "ASC"}`：选择排序方式下拉框中的某个选项后，点击按钮1，可以按照该选项进行升序和降序切换排序。该交互需要在下拉框组件和按钮组件上都设置
- `CLRQ desc,HZRQ asc`：按照成立日期进行降序排列，若成立日期相同，则按照核准日期升序排列
:::tip 排序优先级
用户在[模型属性](../../../../data-gov/model/model-settings.md#sort-fields)以及[查询数据集](../../../../data-viz/dash/design/datasource.md#dataset-properties)上，也能设置按照指定的字段排序数据。排序优先级：
排序数据交互>查询数据集>模型属性
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/returnto.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/returnto"
title: "SuperPage交互-返回上页"
---
---
order: 38
navTitle: 返回上页
---
# SuperPage交互-返回上页
**返回上页**交互常用于打开链接后，返回上一次打开的页面或返回到其他指定页面。如点击列表中企业名称查看企业详情，再点击返回上页按钮，即可返回企业列表页面：
示例地址：[企业查询](https://demo.succbi.com/v5/DEMO/app/DEMO.app?id=%E8%87%AA%E5%8A%A9%E6%9F%A5%E8%AF%A2)
## 使用返回上页{#start}
使用**返回上页**交互，一般需要搭配[按钮](../../components/common/button.md)组件以及[打开链接](./linkto.md)交互使用。以打开链接返回上一次打开的页面为例，具体步骤如下：
1. **添加组件：** 在打开链接目标页面中添加`返回上页`按钮
2. **添加交互：** 选中`返回上页`按钮，添加**返回上页**交互，**页面**设置为`上页`即可
## 返回页面{#return}
在返回上页交互中，可以设置返回的页面：
- **上页**：可返回上一次打开的页面，需与[打开链接](./linkto.md)交互配合使用，并且打开链接显示方式为**当前容器**。[打开链接-当前容器](./linkto.md#current_container)显示方式也可以通过自带的面包屑路径返回上页
- **跳转到登录页**：跳转到系统的[登录页](../../../../dev/script/system-pages/login-page.md)
- **跳转到首页**：跳转到系统的[默认首页](../../../../sys-settings/basic/homePage.md)
- **跳转到指定页**：跳转到系统中指定的某个路径，支持短路径设置以及自定义路径。如`demo-spg/列表`，即可跳转到SuperPage应用列表页面中
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/dataset-page.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/dataset-page"
title: "SuperPage交互-数据集翻页"
---
---
order: 39
navTitle: 数据集翻页
---
# SuperPage交互-数据集翻页
使用**数据集翻页**交互，可以对模型表所在的组件进行翻页控制。以按钮控制列表翻页为例：
示例地址：[数据集](https://demo.succbi.com/v5/demo-spg/数据集行数与翻页)
## 使用数据集翻页{#use}
**数据集翻页**通常搭配[按钮](../../components/common/button.md)、[勾选框](../../components/input/checkbox.md)或者[下拉框](../../components/input/combobox.md)等组件使用，比如通过按钮控制列表翻页：
- **添加按钮**：在合适的位置添加按钮，如`下一页`
- **增加交互**：为**按钮**增加**数据集翻页**交互，**触发事件**选择`单击`，数据选择[列表](../../components/data/list.md#start)的引用的模型表`企业基本信息_查询`，**操作**选择`下一页`
## 数据集翻页设置{#page}
数据集翻页设置支持`上一页`，`下一页`，`第一页`，`最后一页`，`显示指定页`。选择`显示指定页`后，会出现一个**页码**输入框，输入指定的页码或相关表达式，如中间页`CEILING([企业基本信息_查询].[总页数]/2)`即可实现跳转到指定页。
:::tip
列表自带分页功能，也可以使用[分页导航](../../components/data/pagenavigation.md)实现分页功能，若想要分页功能更加个性化，可使用**数据集翻页**与[设置数据集每页行数](./set-dataset-pagesize.md)交互
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/set-dataset-pagesize.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/set-dataset-pagesize"
title: "SuperPage交互-设置数据集每页行数"
---
---
order: 40
navTitle: 设置数据集每页行数
---
# SuperPage交互-设置数据集每页行数
使用**设置数据集每页行数**交互，可以控制模型表在组件中每页的显示行数。以下拉框控制显示列表每页显示行数为例：
示例地址：[数据集](https://demo.succbi.com/v5/demo-spg/数据集行数与翻页)
## 设置数据集每页行数{#use}
**设置数据集每页行数**通常搭配[按钮](../../components/common/button.md)、[多选面板](../../components/input/selectionpanel.md)或者[下拉框](../../components/input/combobox.md)等组件使用，比如通过下拉框选定的数量控制数据表在列表中每页显示的行数：
- **下拉框设置枚举值**：在**可选项**处设置[枚举值](../../components/input/combobox.md#options)可实现自定义选项值。如这里的五个枚举值`20`，`50`，`100`，`200`，`500`
- **增加交互**：为**下拉框**增加**设置数据集每页行数**交互，**触发事件**选择`内容变化`，**数据**选择[列表](../../components/data/list.md#start)的引用的模型表`企业基本信息_查询`，**每页行数**选择`[每页行数].[值]`
:::tip
**设置数据集每页行数**常与[数据集翻页](./dataset-page.md)同时使用，实现对列表的每页行数以及翻页设置
:::
## 行数设置范围{#limit}
通过设置每页的行数可控制模型表在组件每页显示的行数，每页行数可设置的行数范围为`[1,+∞]`。
:::tip
- 当数据集设置的行数为`0`时，不影响组件每页默认显示的行数
- 当设置的行数超过了数据集的总行数或**每页行数**处直接输入数据表名，如`[企业基本信息_查询]`时，默认一页展示数据集的所有行数
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/scan.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/scan"
title: "SuperPage交互-扫码"
---
---
order: 43
navTitle: 扫码
---
# SuperPage交互-扫码
SuperPage中提供了扫码交互，可以使用移动设备（手机，平板等）或扫码枪进行扫码，获取码内的信息。
## 使用扫码交互{#start}
扫码交互执行需要有如下步骤：
1. 扫码需要提前和微信做好单点配置，具体可参考[单点登录](../../../../devops/sso/wechat.md)
2. 添加按钮，设置扫码交互
3. 点击扫码按钮，打开一个扫码弹窗，将扫码返回的信息设置给指定的参数，此时用户可以根据识别信息进行数据库查询以便校验识别结果的合法性，根据用户设置的校验公式进行校验，校验失败会提示用户并不再执行下面的步骤，具体见[对返回的信息做数据校验](#check)
4. 设置识别结果和数据库查询结果给参数、输入组件或者给指定数据集增加一行数据，可参考[将识别返回信息设置给参数或组件](#return-value)
5. 完成扫码
如下是使用扫码提交信息的具体步骤：
1. **添加单次扫码按钮：** 在**组件区**>**常用分组**下将按钮组件拖入到画布中，可参考文档[按钮](../../components/common/button.md)
2. **添加扫码交互：** 选中按钮，在**属性栏**>**交互**下点击添加动作，选择**扫码**
3. **设置交互属性：**
1. 选择设备为**默认**，场景为**默认**
2. **将返回信息设置给参数或组件：** 勾选**将返回内容设置给参数**，并点击**组件设置**添加**目标组件**和**值**，具体见[将识别返回信息设置给参数或组件](#return-value)
3. **提交扫码数据：** 勾选**结果插入到数据集**，选择提交的数据集，并点击**字段设置**添加**目标字段**和**值**；选择**覆盖模式**为**追加**，并设置提示信息，具体见[将返回结果写入到数据库中](#set-dataset)
## 支持的设备类型{#device-type}
扫码交互支持微信扫码和扫码枪扫码，在**设备**和**场景**属性里进行设置。详细属性如下：
- **默认**：如果是移动端设备，则调用微信扫码；如果是PC端设备，会打开一个文本输入弹窗，手动输入码值。默认选项下，只提供了默认的扫码场景，即扫描二维码和条形码
- **扫码枪**：扫码枪的场景支持扫描二维码和条形码
如果需要支持其他设备类型，可以在扩展模块中导入相应的扩展包，详细可参考[扩展管理](../../../../devops/extension-manage/README.md)
## 设置连续扫码{#scanning}
扫码方式分为单次扫码和连续扫码，二者的体验区别如下：
- **单次扫码：** 默认为单次扫码，即点击扫码按钮，调用微信扫码，扫码完成后，自动关闭扫码窗口。每次扫码前都要点击一次扫码按钮
- **连续扫码：** 勾选连续输入后，可以进行连续扫码，连续扫码完成后，不会自动关闭扫码窗口
连续扫码提供了2种体验：
- **持续扫码**：只勾选**连续输入**，点击扫码按钮，调用微信扫码。上一个扫码完成后，自动弹出扫码窗口，继续扫码
- **确认后继续**：勾选**连续输入**和**确认后继续**。上一个扫码完成后，会提示扫码成功，点击屏幕，才能继续扫码
## 将识别返回信息设置给参数或组件{#return-value}
将扫码返回的信息设置给参数或组件，具体可参考OCR识别[将识别返回信息设置给参数或组件](./OCR.md#return-value)。区别在于扫码交互的辅助输入结果，只有扫码结果。
### 对返回的信息做数据校验{#check}
扫码交互支持对返回的信息做数据校验。在数据校验开始前和校验后两个阶段，都可以将返回的信息填充到参数或组件，而校验通过的数据才可填充到组件或插入到数据集中，具体可参考OCR识别[对返回的信息做数据校验](./OCR.md#check)
### 将校验前的结果设置给参数{#set-param}
当有返回结果时，会将返回信息传递给设置的参数或组件。具体可参考OCR识别[将校验前的结果设置给参数](./OCR.md#set-param)
### 将校验后的结果填充到组件{#set-component}
在校验表达式中设置了校验规则，只有在校验通过后才会将返回信息传递给设置的参数或组件。具体可参考OCR识别[将校验后的结果填充到组件](./OCR.md#component)
## 将返回结果写入到数据库中{#set-dataset}
将扫码返回的结果信息存储到数据集中，在扫码交互下勾选**结果插入到数据集**属性，并选择需要插入的数据模型及字段设置即可。具体可参考OCR识别[将识别返回信息写入到数据库中](./OCR.md#set-dataset)
## 应用场景{#application-scenarios}
1. **扫码提交新数据：** 扫码后往数据库里插入一条新数据，如商品出售时，扫码新增一条订单数据。具体效果可以在[单次/多次扫码](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E6%89%AB%E7%A0%81)中进行体验
2. **扫码更新已有数据：** 扫码后更新数据库里的一条已有数据，如出库时，扫描货物的二维码，修改货物的剩余库存。具体效果可以在[扫码更新数据](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E6%89%AB%E7%A0%81)中进行体验
3. **扫码查看溯源数据：** 扫码查看数据，如扫描防伪码，可以查看对应产品的详细信息。具体效果可以在[扫码溯源](https://demo.succbi.com/v5/DEMO/app/ap.app/index.mpg?id=%E6%89%AB%E7%A0%81)中进行体验
扫描第一个二维码打开扫码demo，然后切换到对应的标签页，点击扫码按钮，扫描下方的二维码即可体验对应的扫码场景，更多扫码体验可查看[扫码交互](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%89%AB%E7%A0%81%E4%BA%A4%E4%BA%92)
| 扫码demo | 单次/多次扫码 | 扫码更新数据 | 扫码溯源 |
| --------| -------- | -------- | -------- |
|  |  |  |  |
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/OCR.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/ocr"
title: "SuperPage交互-OCR识别"
---
---
order: 45
navTitle: OCR识别
---
# SuperPage交互-OCR识别
SuperPage中提供了OCR识别交互，利用互联网上的OCR服务（使用OCR服务需要系统配置好外部服务信息，在**系统设置**>**更多**>**外部服务**>**文字识别**中启用相应服务并添加对应参数，可参考文档[文字识别](../../../../sys-settings/more/remote-services/ocr.md)）识别证件图片中的文字信息。如点击按钮上传身份证照片后获取身份证号码和姓名：
示例地址：[OCR识别](https://demo.succbi.com/v5/DEMO/app/ap.app?id=OCR%E8%AF%86%E5%88%AB)
## 使用OCR识别身份证{#start}
OCR识别交互执行过程中会依次执行如下流程：
1. 获取用户的证件图片，通过附件组件或者直接上传，具体见[支持的文件类型](#file-type)。
2. 压缩并上传图片给互联网OCR服务。
3. 获取互联网OCR服务返回的信息并设置给指定的参数，此时用户可以根据识别信息进行数据库查询以便校验识别结果的合法性，根据用户设置的校验公式进行校验，校验失败会提示用户并不再执行下面的步骤，具体见[对返回的信息做数据校验](#check)。
4. 设置识别结果和数据库查询结果给参数、输入组件、或者给指定数据集增加一行数据，可参考[将识别返回信息设置给参数或组件](#return-value)。
5. 完成识别。
如下是使用上传身份证按钮识别身份证信息的具体步骤：
1. **添加上传身份证正面照按钮**：在**组件区**>**常用**分组下将**按钮**组件拖入到画布中，可参考文档[按钮](../../components/common/button.md)。
2. **添加OCR识别交互**：选中按钮，在**属性栏**>**交互**下点击**添加动作**，选择**OCR识别**。
3. **设置交互属性**：
1. 设置识别的[文件类型](#file-type)为**上传图片**、设置[识别设备](#recognition-type)为**阿里云证照识别**，[场景](#recognition-type)为**身份证**。
2. **将返回信息设置给参数或组件**：勾选[将返回内容设置给参数](#return-value)，并点击**组件设置**添加**目标组件**和**值**。
## 支持的文件类型{#file-type}
OCR识别的来源文件包括**上传图片**、**附件组件**，在OCR识别交互下的**文件**属性中选择对应的文件类型即可：
- 可以设置**图片质量**，即图片压缩后的大小质量，输入大于0的数字即可。当为0.1时，压缩比最大。
- 通过**附件组件**上传的图片，可以进行预览；通过按钮点击上传的图片直接进行信息识别。
:::tip
上传的图片会保存在[工作目录](../../../../devops/install/basic-install/workdir-and-defdb.md#set-workdir)workdir的`\clusters-share\upload-files`路径下
:::
## 支持的证照识别类型{#recognition-type}
OCR识别提供了2种证照识别设备，包括**阿里云证照识别**、**百度证照识别**。在**OCR识别**交互下的**设备**属性中选择即可，证照识别设备不同可识别的证照**场景**也不同：
- **阿里云证照识别**：身份证、银行卡、二维码
- **百度证照识别**：身份证、驾驶证、行驶证、银行卡、二维码、营业执照
:::tip
不同的证照场景返回内容的辅助输入结果不一致，可参考[将识别返回信息设置给参数或组件](#return-value)
:::
## 将识别返回信息设置给参数或组件{#return-value}
通过OCR识别返回的信息，可以设置给全局参数或者页面中的组件，组件设置的值类型可选**表达式**或**辅助输入结果**：
- **表达式**：当选择表达式时，可以通过输入[表达式函数](../../../../exp/README.md)获取交互结果的值，如使用[JSON\_GET()](../../../../exp/func/json/JSON_GET.md)函数获取交互数据中的姓名`JSON_GET([事件].[交互数据],'姓名')`
- **辅助输入结果**：即通过OCR识别返回的结果，辅助输入结果返回的值与识别的证照[场景](#file-type)相关：
- **身份证**：姓名、性别、民族、出生、住址、公民身份号码
- **驾驶证**：姓名、性别、住址、证号、国籍、准驾车型、初次领证日期、出生日期、有效期限、至
- **行驶证**：号牌号码、车辆类型、所有人、住址、使用性质、品牌型号、车辆识别代码、发动机号码、注册日期、发证日期
- **银行卡**：银行卡卡号、有效日期、银行名称、银行卡类型
- **二维码**：类型、文本
- **营业执照**：社会信用代码、经营范围、单位名称、证件编号、注册资本、法人、地址
### 对返回的信息做数据校验{#check}
OCR交互支持对返回的信息做数据校验。在数据校验开始前和校验后两个阶段，都可以将返回的信息填充到参数或组件，而校验通过的数据才可填充到组件或插入到数据集中，校验设置如下：
- **校验表达式**：在**校验表达式**中可输入校验公式，如校验识别的证件ID（公民身份号码）不为空且数据集中不存在该条数据，表达式示例`len(filter(select([OCR识别信息].[证件ID]),[sfz_baidu_id]=@))=0 AND [sfz_baidu_id] is not NULL`
- **校验成功提示设置**：勾选**校验成功提示**并输入提示信息内容即可，如`上传成功！`
- **校验失败提示设置**：**校验表达式**返回是`false`，则校验失败。勾选**校验失败提示**并输入提示信息内容即可，如`身份信息已存在，或公民身份号码未获取到，请上传有效的证件图片！`
:::tip
校验后将结果填充到组件中的设置，在如下两种场景下生效：
1. 没有添加校验表达式：表示不需要对识别结果进行校验，直接将返回信息填充到组件中。
2. 设置了校验表达式：当返回结果校验通过时，会把识别返回的信息填充到组件中显示，只能传递到**参数**或[输入组件](../../components/input/README.md)中，若返回结果校验失败，则不会将识别结果填充到组件中显示。
:::
### 将校验前的结果设置给参数{#set-param}
当有返回结果时，会将返回信息传递给设置的参数或组件。在**OCR识别**交互下，勾选**将返回内容设置给参数**，并在**组件设置**中选择填充到的**目标参数和组件**：
### 将校验后的结果填充到组件{#set-component}
在校验表达式中设置了校验规则，只有在校验通过后才会将返回信息传递给设置的参数或组件。在**OCR识别**交互下，勾选**结果填充到组件**属性，并在**组件设置**中选择填充到的**目标参数和组件**：
## 将识别返回信息写入到数据库中{#set-dataset}
可将OCR识别的结果信息存储到数据集中，在OCR识别交互下勾选**结果插入到数据集**属性，并选择需要插入的数据模型及字段设置即可，可对返回信息添加校验，将校验通过的结果插入到数据集中，参考[对返回的信息做数据校验](#check)。
- **数据**：即需要插入的数据集模型，需要在页面中引用该模型。
- **字段设置**：将返回信息插入的目标字段设置，插入的数据模型结构需包含要插入的字段内容。
- **覆盖模式**：当插入的数据主键重复时，数据的**覆盖模式**包含2种：**合并**、**追加**，默认为**合并**。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/WebAPI.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/WebAPI"
title: "SuperPage交互-调用WebAPI"
---
---
order: 47
navTitle: 调用WebAPI
---
# SuperPage交互-调用WebAPI
**调用WebAPI**交互可以调用后端嵌入式脚本，用于对表单或SuperPage页面进行后端的个性化业务处理。如图点击执行调度计划按钮后，立即执行调度计划：
示例地址：[执行调度计划](https://demo.succbi.com/v5/DEMO/app/script-demo.app?id=%E6%89%A7%E8%A1%8C%E8%B0%83%E5%BA%A6%E8%AE%A1%E5%88%92)
## 使用调用WebAPI{#use}
**调用WebAPI**交互可以通过资源路径调用任意`.action`的文件，以调用`custom.action`中`runScheduleOrETL`方法实现执行调度计划的功能为例，具体操作步骤如下：
1. **添加交互**：选择**执行调度计划**按钮，添加**调用WebAPI**交互
2. **配置交互相关属性**：**API地址**中输入`/DEMO/app/script-demo.app/custom.action?method=runScheduleOrETL`，**参数**属性中**参数名称**设置为`mode`，**参数值**设置为`schedule`。更多参考[设置参数](#param)
## 设置参数{#param}
当后端脚本需要前端页面传递参数时，可在**调用WebAPI**交互中定义多个参数。而后端脚本方法中提供了自定义参数`params`来接收，该参数是一个json对象，通过`params.参数名`的方式（该参数名，是在交互中定义的参数）可以获取页面传递的参数内容。相关使用可参考下图中的注释部分。
## 返回内容设置{#return}
后端脚本在执行完成后会有返回内容，当需要接收脚本处理后的返回内容时，可以勾选**将返回内容设置给参数**选项，并在**参数**下拉框中指定参数来接收返回内容。此处下拉框可供选择的参数来源于定义的[全局参数](../../../../data-viz/dash/design/data/param.md)，需要提前设置。
## 提示信息设置{#tooltips}
### 调用前提示{#before}
- **调用前显示确认对话框**：交互执行前，弹出对话框提示是否确认
### 调用后提示{#after}
- **成功后关闭对话框**：默认勾选，调用WebAPI成功后，关闭所在对话框，若没有打开对话框，则无效果
- **成功后显示提示**：调用WebAPI成功后，顶部显示自定义的文字内容
- **失败后显示提示**：调用WebAPI失败后，顶部显示自定义的文字内容
顶部的提示消息框会在页面中停留3秒再隐藏，若希望更多的自定义设置，可以使用[显示消息框](./show-message.md)交互。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/show-files.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/show-files"
title: "SuperPage交互-预览文件"
---
---
order: 48
navTitle: 预览文件
---
# SuperPage交互-预览文件
使用**预览文件**交互可以全屏预览图片、PDF、Word、视频、音频类等资源文件。如点击预览按钮，即可预览相关文件资源，在预览界面点击右上角关闭按钮或按esc可以退出预览：
|PC端|移动端|
|---|---|
|||
示例地址：[PC端附件预览](https://demo.succbi.com/v5/demo-spg/%E9%99%84%E4%BB%B6%E9%A2%84%E8%A7%88)、[移动端附件预览](https://demo.succbi.com/v5/demo-spg/mobile/预览附件)
## 使用预览文件{#use}
使用**预览文件**交互需要搭配载体组件，除使用[按钮](../../components/common/button.md)组件外，也可将该交互附于其他浮动展示数据的组件上，浮动出来的每行数据都会带有交互动作，如[列表](../../components/data/list.md)、[浮动面板](../../components/layout/floatpanel.md)。
以列表为例介绍预览文件交互的使用方法，实现点击预览按钮，预览相关文件资源：
1. **添加预览文件交互**：在列表的操作列的**预览**按钮添加预览文件交互
2. **设置交互属性**：文件来源选择`数据集`，数据选择`上传附件_富文本`，附件字段选择`存储路径`
## 文件来源设置{#source}
系统内部提供了两种文件的存储方式，可以参考[上传附件](../../components/input/upload.md#store)文档，除了来自系统内部之外，还可以是外网中的资源，均可以使用该交互实现文件的预览，文件来源下拉框提供了**数据集**和**自定义**两种选项。
### 预览来自数据集的文件{#dataset}
当文件资源以**路径**的形式存放在模型表的字段里，预览文件交互需要进行以下设置：
- **文件来源**：下拉框中选择**数据集**
- **数据**：下拉框中选择组件和交互的取数来源，可以是数据模型、临时的数据加工或者新建的数据集
- **附件字段**：选择数据表中存储**图片/附件**路径的字段即可。在下拉框中，只显示数据表中[字段角色](../../../../data-gov/model/field-role.md)为附件角色和图片角色的字段
- **数据范围**：预览文件交互支持预览哪些符合条件的数据，在数据范围属性中提供了四种可选项，可以参考[删除数据](./delete-data.md#deleterange)文档
### 预览自定义文件地址{#customize}
当文件资源存放在**元数据**中或者来自系统外的页面时，可以参考[网页](../../components/embed/embedwebview.md#url)文档，预览文件交互需要进行以下设置：
1. **文件来源**：下拉框中选择**自定义**，这里的地址可以为系统内部地址，也可以是外网地址，主要是以下几种形式：
- **相对地址**：如`../../public/audios/钢琴.mp3`
- **绝对地址**:
- 模块绝对地址：如`/DEMO/ana/图表/图形/条形竞赛图.dash`
- 网页绝对地址：如`http://172.23.126.107:8080/DEMO/public/audio/钢琴.mp3`
- **表达式**：如`${[path]}`
2. **参数设置**：可以根据需求设置地址参数，具体可参考[URL参考](../../../../dev/references/sys-urls.md)文档，点击编辑参数即可设置参数，可设置多个，下拉列表中会显示在SuperPage中添加的全局参数
## 设置文件名{#filename}
预览时文件名称显示在左上角，系统默认是元数据中的名称，也可以自定义文件名，在**文件名**属性中选择自定义即可，支持写表达式。
## 设置预览文件可下载{#download}
预览界面右上角提供了资源下载的入口，点击下载图标可以下载相关文件资源，如果不需要此功能，去掉**允许下载**勾选即可。
## 预览多个文件{#multiple}
可以预览多个文件，在预览界面右上角可以使用左右箭头切换上一张和下一张，实现思路如下：
1. 相关组件添加**预览文件**交互
2. 文件来源：不同的来源方式设置不同
- 来自数据集的文件：数据集返回的是多条数据，且设置**数据范围**为当前查询结果
- 自定义文件地址：多个文件地址使用换行符分割
以预览多张图片为例，点击预览多个图片按钮即可预览图片资源：
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/download-files.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/download-files"
title: "SuperPage交互-下载文件"
---
---
order: 49
navTitle: 下载文件
---
# SuperPage交互-下载文件
使用**下载文件**交互可以下载图片、PDF、Word、视频、音频类等资源文件。如点击下载按钮，即可下载相关文件资源：
示例地址：[下载文件](https://demo.succbi.com/v5/demo-spg/%E9%99%84%E4%BB%B6%E9%A2%84%E8%A7%88)
## 使用下载文件交互{#use}
使用**下载文件**交互需要搭配载体组件，除使用[按钮](../../components/common/button.md)组件外，也可将该交互附于其他浮动展示数据的组件上，浮动出来的每行数据都会带有交互动作，如[列表](../../components/data/list.md)、[浮动面板](../../components/layout/floatpanel.md)。
以列表为例介绍下载文件交互的使用方法，实现点击下载按钮，下载相关文件资源：
1. **添加下载文件交互**：在列表的操作列的**下载**按钮添加**下载文件**交互
2. **设置交互属性**：文件来源选择`数据集`，数据选择`上传附件_富文本`，附件字段选择`存储路径`
## 文件来源设置{#source}
系统内部提供了两种文件的存储方式，可以参考[上传附件](../../components/input/upload.md#store)文档，除了来自系统内部之外，还可以是外网中的资源，均可以使用该交互实现文件的下载，相关属性设置可以参考[预览文件](./show-files.md#source)文档。
## 设置打包成ZIP{#zip}
**下载文件**交互支持下载对应的**ZIP文件**，需要进行如下属性设置：
1. **打包成ZIP**：勾选即可下载对应的ZIP文件，当下载多个文件资源时，不管是否勾选都自动打包成ZIP文件
2. **ZIP文件名**：默认名为元数据中的名称，也可以自定义ZIP文件的名称，支持写表达式
## 下载多个文件资源{#multiple}
**下载文件**交互可以一次性下载多个文件资源，实现思路如下：
1. 相关组件添加**下载文件**交互
2. 文件来源：不同的来源方式设置不同
- 来自数据集的文件：数据集返回的是多条数据，且设置**数据范围**为当前查询结果
- 自定义文件地址：多个文件地址使用换行符分割
如点击**下载多个文件**按钮，即可下载相应ZIP文件：
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/login.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/login"
title: "SuperPage交互-登录"
---
---
order: 50
navTitle: 登录
---
# SuperPage交互-登录
使用**登录**交互，可以通过低代码方式在页面中搭建登录界面，其功能与系统自带的[登录](../../../../dev/references/web-api/auth/signin.md)功能逻辑一致。如在SuperPage页面中点击登录按钮，即可弹出登录对话框进行登录操作：
示例地址：[登录](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E7%99%BB%E5%BD%95)
## 使用登录{#start}
使用**登录**交互，一般需要配合[文本输入](../../components/input/textinput.md)、[密码输入](../../components/input/passwordinput.md)、[按钮](../../components/common/button.md)、[文本](../../components/common/text.md)等组件使用，使用文本输入组件来输入用户信息；使用密码输入组件来输入密码信息。然后在登录交互中获取该输入信息，与数据库中存储的信息进行比对，一致就能登录成功。具体操作步骤如下：
1. **添加组件：** 在页面中添加`用户名`文本输入组件、`密码`输入组件以及`确定`按钮
2. **添加交互并设置属性：**
1. 选中`确定`按钮，添加**登录**交互
2. 在交互中，**用户名**设置为`=[用户名：].[值]`，**密码**设置为`=[密码].[值]`即可，更多设置可查看[登录设置](#setting)
## 登录设置{#setting}
在登录交互中，需要获取用户输入的用户名、密码等信息，与数据库中的数据进行匹配。同时也可以根据需求进行其他属性设置，具体如下：
- **用户名**：必填项，获取用户输入的用户名信息，如`=[用户名：].[值]`
- **密码**：必填项，获取用户输入的密码信息，如`=[密码].[值]`
- **验证码**：获取用户输入的验证码信息，如`=[验证码].[值]`。验证码由后端自动生成以图片形式显示，根据用户的输入自动在服务层校验。使用该值主要防止恶意软件随意登录
- **用户类型**：包括**系统用户**、**外部用户**两种，当为系统用户时，自动与`/sysdata/data/tables/sec/USERS.tbl`模型表中的数据进行匹配；当为外部用户时，自动与`/sysdata/data/tables/sec/EXTERNAL_USERS.tbl`模型表中的数据进行匹配。默认为系统用户
- **登录成功后刷新页面**：登录成功后立即刷新页面
- **成功后关闭对话框**：当登录操作是在一个对话框中操作时，登录成功后可关闭该对话框
- **将错误信息显示在指定位置**：勾选后，会弹出**目标组件**，该下拉框中只能选择文本组件，并将错误信息`用户名或密码错误`显示在选中的文本组件中
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/logout.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/logout"
title: "SuperPage交互-注销登录"
---
---
order: 51
navTitle: 注销登录
---
# SuperPage交互-注销登录
使用**注销登录**交互，可以通过低代码方式在页面中配置注销按钮，可以方便用户注销以及切换用户等，其功能与系统自带的[注销](../../../../dev/references/web-api/oauth2/logout.md)功能逻辑一致。如在SuperPage页面中可根据场景配置注销登录：
|PC端|移动端|
|--|--|
|||
示例地址：[注销登录](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E7%99%BB%E5%BD%95)
## 使用注销登录{#start}
使用**注销登录**交互，一般需要配合[按钮](../../components/common/button.md)组件或者[设置列表](../../components/mobile/mobilecelllist.md)使用，只需在组件上添加该交互即可。具体操作步骤如下：
1. **添加组件：** 在页面中添加`注销登录`按钮
2. **添加交互：** 选中`注销登录`按钮，添加**注销登录**交互即可
## 注销成功后{#success}
在注销登录交互中，可以设置注销成功后的状态：
- **留在当前页面**：注销成功后，依旧停留在当前注销页面
- **刷新页面**：注销成功后，立即刷新页面，默认为该选项
- **跳转到登录页**：注销成功后，跳转到登录页面，该登录页为系统[登录页](../../../../dev/script/system-pages/login-page.md)。弹出**是否记住当前页面地址**，勾选后，再次登录，可进入上次注销时的页面；不勾选则进入系统默认首页
- **跳转到首页**：注销成功后，进入登录页面，再次登录成功直接进入首页，该首页为系统[默认首页](../../../../sys-settings/basic/homePage.md)
- **跳转到指定页**：注销成功后，进入登录页面，可以指定系统中某个路径，支持短路径设置以及自定义路径。如`demo-spg/列表`，即可跳转到SuperPage应用列表页面中
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/copy-to-clipboard.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/copy-to-clipboard"
title: "SuperPage交互-复制到剪切板"
---
---
order: 52
navTitle: 复制到剪切板
---
# SuperPage交互-复制到剪切板
**复制到剪切板**常用于一键复制信息，如点击**复制全文**可以把文章内容复制到剪切板：
示例地址：[复制到剪切板](https://demo.succbi.com/v5/demo-spg/mobile/%E5%A4%8D%E5%88%B6%E5%88%B0%E5%89%AA%E5%88%87%E6%9D%BF)
## 使用复制到剪切板{#use}
**复制到剪切板**交互可以将目标内容复制到剪切板，之后可以供用户粘贴到需要的地方，以点击文本复制全文信息为例，具体操作步骤如下：
1. **添加复制到剪切板交互**：选中`复制全文`文本组件，添加**复制到剪切板**交互
2. **设置交互相关属性**：设置**内容**为`${[文章]}`
### 复制内容设置{#content}
要复制的目标信息可以在该交互的**内容**属性中设置，可以是一段文字信息，如`这个世界很美好`，设置后该交互可以把此段文字复制到剪切板，同时支持写表达式，如`${[文章]}`，可以用来复制某个组件里的信息。
:::tip
使用**复制到剪切板**交互后，Windows可以按快捷键`win+v`来查看剪切板，macOS可以在`Finder>编辑>显示剪切板`中查看剪切板，如果进行了多次复制，剪切板的内容就会变成最后一次复制的信息，系统关闭后剪切板中的内容会自动清除。
:::
## 同系统自带复制功能的区别{#difference}
**复制到剪切板**交互同系统自带的复制功能作用相同，即右键复制或者使用快捷键`crtl+c`，都是复制一段信息到剪切板，不同之处在于系统自带的复制功能只能复制选中的内容，而**复制到剪切板**交互可以自定义需要复制的内容，而且该交互可以使“复制”的动作更业务化自由化一些，一键即可复制。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/script.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/script"
title: "SuperPage交互-执行脚本"
---
---
order: 53
navTitle: 执行脚本
---
# SuperPage交互-执行脚本
**执行脚本**交互可以调用前端浏览器的个性化`JavaScript`脚本，用以实现产品默认无法实现的个性化需求。如图勾选多个文件后，点击勾选导出PDF按钮可以批量导出相应的PDF文件的压缩文件：：
示例地址：[导出ActiveDoc为PDF](https://demo.succbi.com/v5/demo-spg/%E6%89%B9%E9%87%8F%E5%AF%BC%E5%87%BAActiveDoc)
## 使用执行脚本{#use}
**执行脚本**交互只能执行[custom.ts](../../../../dev/script/frontend/custom-ts.md)编译后的`custom.js`中的指定函数，不能执行任意位置的脚本，也不能执行后端脚本，如有需要可以通过`custom.js`中的函数再调用其它位置的脚本或后端脚本。新建好应用资源下的`custom.js`脚本后，**执行脚本**交互中脚本函数下拉列表会显示`custom.js`中的脚本交互函数，可以按需选择函数，以运行**exportPdf**脚本函数实现导出PDF的功能为例，具体操作步骤如下：
1. **添加交互**：选择**勾选导出PDF**按钮，添加**执行脚本**交互
2. **配置交互相关属性**：**脚本函数**下拉列表中选择`exportPdf`，**参数**属性中**参数名称**设置为`pathColumn`，**参数值**设置为`list1.column5`
## 设置参数{#param}
脚本函数中有一些自定义参数，对应的参数值传入之后可以正常运行函数。添加了**执行脚本**交互后，需要在**参数**设置对话框中添加**参数名称**和**参数值**，参数名称需要与脚本中定义的参数名保持一致。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/call-action-flow.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/call-action-flow"
title: "SuperPage交互-调用程序流"
---
---
order: 54
navTitle: 调用程序流
---
# SuperPage交互-调用程序流
SuperPage的交互动作除了在页面上设置使用外，还可以通过**调用程序流**的方式完成，更多说明可以查看[程序流](../../../actionflow/README.md)文档。本文介绍如何在SuperPage中使用一个已经配置好的程序流，如在SuperPage中通过**调用程序流**完成点赞的数据写入：
示例地址：[排序数据](https://demo.succbi.com/v5/demo-spg/%E6%8E%92%E5%BA%8F%E6%95%B0%E6%8D%AE)
## 使用调用程序流{#use}
使用**调用程序流**交互动作之前，需要在应用下先创建好[程序流](../../../actionflow/design.md)。设置调用程序流交互动作时，选择需要调用的程序流，交互动作在执行时会调用选择的程序流，程序流执行完毕后会更新当前SuperPage的数据。具体操作步骤如下：
1. **选择程序流**：在**程序流**属性中选择对应的**程序流**，该属性会列出当前项目下所有的程序流，按需选择
2. **设置参数**：在**参数**属性中传递两条值到程序流中，更多说明可参考[传递参数](#trans-param)
1. 参数名称为`dz`，值为`IF([点赞表].[类型]=1,0,1)`
2. 参数名称为`qyid`，值为`[企业基本信息].[企业内部序号]`
## 传递参数{#set-param}
在**调用程序流**交互动作中，可以向[程序流](../../../actionflow/README.md)中传递参数的值，主要有以下几点：
1. 提前在相应的程序流中添加[全局参数](../../../../data-viz/dash/design/data/param.md)
2. 在**调用程序流**的**参数**属性中，点击**编辑参数**按钮，并在**参数**对话框中设置参数与值的对应关系
通过以上两个步骤，即可在调用该**程序流**时，为**程序流**中的**全局参数**赋值。
## 回传参数{#get-param}
当**调用程序流**执行结束后，需要获取**程序流**返回的内容显示在SuperPage界面上，可以通过**回传参数**将**程序流**中的数据回传到SuperPage页面中来，如调用**程序流**中配置好的算法服务，将值返回给前端页面进行展示。设置如下：
1. 勾选**回传参数**选项，该选项默认勾选
2. 点击**编辑参数**按钮，在参数对话框中设置当前页面的参数与程序流的参数之间的对应关系
若勾选后没有设置对应关系，参数则不会回传。
- **参数名称**：当前SuperPage中定义的全局参数，用来接收回传的参数值
- **参数值**：**程序流**中定义的全局参数，在**程序流**中通过更新全局参数的值来回传给SuperPage中指定的参数
:::tip
可以把**传递参数**和**回传参数**理解为在调用方法时，给方法传递参数，以及获取方法调用后的返回值。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/action/execute-flow.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/action/execute-flow"
title: "SuperPage交互-执行流程"
---
---
order: 55
navTitle: 执行流程
---
# SuperPage交互-执行流程
当需要在SuperPage中使用**工作流**时，比如使一个请假或报销流程能够正常流转，这涉及到两个关键点：
1. 申请人在填写完申请信息后需要[发起流程](./submit-data.md#start-flw)，相关设置可参考[提交表单](./submit-data.md#start-flw)文档
2. [发起流程](./submit-data.md#start-flw)后，在审批环节中，用户需要通过**执行流程**交互对流程任务进行审批，使流程能够继续走到下一环节直到流程结束
本文主要讲解如何使用**执行流程**交互去处理流程任务，如下动图就是通过**执行流程**交互来批准请假申请：
示例地址：[请假申请](https://demo.succbi.com/v5/DEMO_OA/app/OA.app?:edit=true&:file=glysp.spg)
## 使用执行流程{#use}
一个工作流想要正常运转通常至少需要具备两个页面：
1. **任务列表**：用于展示当前用户所有待办或已办的流程任务，通常使用工作流数据源[我的待办](../datasourse.md#my-tasks)制作，设置方法可参考[引入数据](../datasourse.md#my-tasks)文档
2. **表单页面**：用于发起人填报申请信息，处理人进行审批操作的页面，通常是从**任务列表**跳转到对应任务的处理表单页面
**执行流程**交互主要应用于上述提到的**表单页面**中，且大部分情况都是在做审批处理的**表单页面**中使用，**执行流程**交互会根据从**任务列表**传递过来的**任务代码**按照配置的[流程操作](../../../workflow/operate.md)去处理指定的流程任务，以请假流程的审批页面中的批准按钮为例：
1. **按钮组件添加交互**：选中**按钮**组件，在**交互**中添加**执行流程**
2. **指定流程任务来源**：
1. 在**交互属性**>**目标流程任务**中选择[来自流程数据源](#wfl-data)选项，此处在交互添加时已有默认设置
2. 在**交互属性**>**流程数据源**中选择引入到SuperPage页面中的[流程表单数据](../datasourse.md#page-img)
3. **指定流程操作**：在[流程操作](#operate)设置中可选择以什么样的方式来处理流程，此处默认选择**批准**操作
4. **指定处理意见**：勾选[指定处理意见](#advice)后，将输入意见的组件值添加到设置中
## 定位待处理的流程任务{#workflow}
使用**执行流程**交互，首先需要确定当前在处理的是什么流程任务，比如当前流程任务在处理的是张三发起的请假申请，[流程节点](../../../workflow/design.md#add-node)走到了组长审批环节。这些任务信息需要通过交互属性**目标流程任务**中的设置来获取，**目标流程任务**设置中提供了多种设置选项，下面分章节介绍不同选项的设置方法以及应用场景。
### 来自流程数据源{#wfl-data}
从一个[流程数据源](../datasourse.md#page-img)中，通过其模型设置中提供的**任务代码**，可以获取到当前在处理的流程任务信息。往往在当前页面需要使用[流程数据源](../datasourse.md#page-img)来展示流程任务的表单信息时使用。如请假申请的审批页面需要通过[流程数据源](../datasourse.md#page-img)来展示申请人填写的申请信息，此时可直接借助[流程数据源](../datasourse.md#page-img)`请假申请表`来获取当前处理的请假流程的任务信息。这种方式下的**执行流程**，有以下关键点：
1. 页面中需正确引入[流程表单数据](../datasourse.md#page-img)，且进入到表单页面时要传递正确的**任务代码**
2. **执行流程**交互的**目标流程任务**设置为**来自流程数据源**，并正确指定设置好的[流程数据源](../datasourse.md#page-img)
示例地址：[请假审批](https://demo.succbi.com/v5/DEMO_OA/app/OA.app?:edit=true&:file=glysp.spg)
:::tip
[流程数据源](../datasourse.md)有多种类型，此处提到的[流程数据源](../datasourse.md)专指[流程表单数据](../datasourse.md#page-img)。
:::
### 用户批量选择{#batch-use}
任务信息可以从一个带有流程**任务代码**的数据[列表](../../components/data/list.md)中获取。往往应用在申请信息在列表中一目了然，审批人希望直接在列表上批量勾选一批数据同时批准或否决的场景。如请假流程，其申请信息足够简单，审批人往往希望直接批量处理自己的待审批任务。在将属性**目标流程任务**设置为**用户批量选择**后，具体设置属性如下：
- **数据**：选择SuperPage中的[引入模型](../datasourse.md)，不限模型类型，但模型中需要包含记录**任务代码**的字段
- **任务代码**：可在模型字段范围中选择，批量处理流程任务时，通过选择的字段内容得到**任务代码**从而定位到对应的流程任务
- **数据范围**：可选择**勾选的**或**当前行**，用于确定要处理的流程任务范围
- **数据组件**：数据范围选择**勾选的**时可以设置，选择勾选数据的对象组件
:::tip
**用户批量选择**所使用的数据表通常直接就是[流程任务表](../../../../dev/sys-tables/README.md#flow-tasks)，或是由[流程任务表](../../../../dev/sys-tables/README.md#flow-tasks)加工后得到的数据表。
:::
### 指定任务代码{#taskid}
任务信息还可以从指定的**任务代码**中获取。往往应用于在任务列表行中去处理当前行的流程任务。参考批量处理请假申请的场景，用户可能不想批量勾选处理而是根据列表行上展示的信息来逐条点击行上的处理按钮来执行流程。这种设置下有以下几点需要注意：
1. 仅支持通过表达式设置单个**任务代码**
2. 设置的**任务代码**必须是当前用户可处理的，否则触发交互时系统会自动给出提示信息，可处理的任务是指：
1. **任务代码**对应的流程任务是分配给当前用户的
2. **任务代码**对应的流程任务尚未被处理
:::tip
与从**流程数据源**中获取任务信息来处理流程任务不同，**指定任务代码**设置通常是应用在不需要进入到表单页面来处理流程任务时的场景。
:::
## 流程操作{#operate}
在交互设置**流程操作**中提供了工作流中审批相关的[流程操作](../../../workflow/operate.md)，如批准，否决，退回等。详细说明可参考[流程操作](../../../workflow/operate.md)文档。
:::tip
在流程节点的设置上也可以配置[流程操作](../../../workflow/operate.md)，需要注意的是，在执行某流程节点的任务时，如果触发的操作是流程节点上未配置的，则会提示用户不能使用未配置的操作。如请假申请的组长审批节点中只配置了**批准**和**退回**操作，则此时通过交互去**否决**该流程任务是不被允许的。
:::
## 指定处理意见{#advice}
交互设置**指定处理意见**，勾选后可以通过表达式来设置流程任务处理时的**处理意见**，通常是取页面某输入组件的值。
1. 表单页面中需要提供输入**处理意见**的输入组件
2. **执行流程**交互勾选**指定处理意见**属性后，需要将输入组件的值设置到表达式中
3. 交互执行时，系统自动将对应输入组件的内容记录到[流程任务表](../../../../dev/sys-tables/README.md#flow-tasks)的**处理意见**字段中
:::tip
如果处理意见是不需要记录在业务表中的，则审批页面中提供的输入处理意见的输入组件都是不需要绑定提交字段的。
:::
## 指定跳转节点{#node}
交互设置**指定跳转节点**，用于**流程退回**时可自由指定要退回到的节点的场景。在[流程节点](../../../workflow/design.md#add-node)的[退回](../../../workflow/operate.md)操作设置中，可将多个节点设置为可退回的节点。以下图部门经理审批节点为例：
当张三发起请假申请，经由他的项目经理李四审批通过后，申请到达部门经理审批节点，由王五处理。此时针对退回有以下两种情况：
1. 不指定跳转节点时，默认退回到离当前节点最近的[流程节点](../../../workflow/design.md#add-node)，即项目经理审批节点
2. 指定跳转节点时，所添加表达式的计算结果需要是[流程节点](../../../workflow/design.md#add-node)的**节点ID**，例如此处可以直接指定为申请节点的**节点ID**，则退回时直接退到申请节点。**节点ID**的设置可参考[绘制工作流](../../../workflow/design.md#task-node)文档
:::tip
**指定跳转节点**的表达式支持设置多个**节点ID**，多个**节点ID**之间逗号分隔，只支持并行分支的场景，如对一份合同进行审批，需要A，B，C三个部门并行审批后再由领导审批，领导审批时，可能A，B部门的资料提交错误，此时可以通过**指定跳转节点**设置只退回A，B审批的节点，部门C无需处理。
:::
## 提示信息设置{#tooltips}
**执行流程**交互完成前后可自定义提示信息，设置后会在交互动作完成前后弹出对话框确认，具体设置可参考[提交表单](./submit-data.md)。
---
url: "https://docs.succapp.com/v5/guide/app/superpage/design/mobile.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/mobile"
title: "SuperPage移动页面"
---
---
order: 7
navTitle: 移动
---
# SuperPage移动页面
SuperPage移动页面应用于移动端展示和使用：
|应聘登记|请假管理|首页宫格|
| --- | --- | --- |
||||
## 新建移动SuperPage{#new}
在新建SuperPage时，选择**移动**模板即可创建一个移动SuperPage。当该页面的内容制作完成后，还可以将页面加入到[移动APP](../../mobile/README.md)内进行查看。
## 移动设计器{#designer}
根据移动模板完成新建后，[SuperPage设计器](../designer.md)中的画布区域将展示为移动端的效果，这也是与PC端SuperPage设计器的唯一区别。在制作移动内容时可根据该移动效果调整页面的布局和组件样式。
## 移动组件{#components}
SuperPage大多数组件在移动端查看时能够自适应调整为移动效果，并且为了使效果更好，组件区中还提供了一些移动组件，如[宫格](../components/mobile/mobilegrid.md)、[移动列表](../components/mobile/mobilelist.md)等。这些组件的使用不仅能够使页面呈现出来的效果更加自然、美观，还可以实现一些移动端才能够进行的操作，如侧滑等。
:::tip
搭建移动SuperPage页面时，组件的使用方法不会发生改变，并且由于一些交互提供了移动端的属性设置，会使组件的展示适配移动端，如[显示对话框/悬浮面板](./action/show-dialog.md#display)的**显示方式**属性提供了**底部滑出**等。其他交互的具体使用方法可参考[交互文档](./action/README.md)。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/superpage/faq"
title: "SuperPage常见问题列表"
---
---
order: 9
navTitle: 常见问题
---
# SuperPage常见问题列表
!!!children (guide/app/superpage/faq) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/app/superpage/faq/默认值、绑定字段与计算公式.md"
htmlUrl: "https://docs.succapp.com/v5/howto/513e6365"
title: "默认值、绑定字段与计算公式"
---
---
order: 1
---
# 输入组件默认值、绑定字段与计算公式之间的区别
输入组件可以设置计算公式、默认值，也可以设置绑定字段，这些设置都可以影响输入项的值，当同时设置时优先级是：计算公式 > 绑定字段 > 默认值。
## 默认值{#defvalue}
1. 如果设置了计算公式并且计算条件为空或返回true，那么会忽略默认值设置。
2. 如果设置了绑定字段且当前页面是从数据库加载数据（不是新建数据模式打开页面，没有传递`:newData=true`），那么也不会计算默认值。
3. 如果没有计算公式也没有绑定字段，或者设置了绑定字段但是页面是以新建数据的模式打开的（传递了`:newData=true`），那么会计算默认值。
## 绑定字段{#bind-field}
绑定字段往往用于提交数据（见[提交表单交互](../design/action/submit-data.md)），当页面不是以“新数据”模式打开（没有传递`:newData=true`），系统会将绑定字段的数据装载到输入组件中。
当绑定字段的值加载到输入组件后，如果字段所在的数据集发生了变化（比如过滤条件变了），那么输入组件的值不会随之改变，除非使用[重置数据交互](../design/action/reset-data.md)。
如果同时设置了计算公式（且计算条件为空或返回true），那么计算公式的值会覆盖绑定字段的值。
## 计算公式{#calc-exp}
计算公式用于在页面上根据需要动态的修改一个输入组件的值，当计算公式引用的数据发生变化后计算公式会自动重新计算。
计算公式可以搭配计算条件一起使用，当计算条件为空或返回true时计算公式才会生效。
:::warning
在计算公式中使用[RAND](../../../exp/func/math/RAND.md)或[UUID](../../../exp/func/string/UUID.md)等函数时需要注意，页面每次加载时计算结果都不同，通常应该考虑使用[默认值属性](#defvalue)。
:::
---
url: "https://docs.succapp.com/v5/guide/app/superpage/faq/关联填充规则.md"
htmlUrl: "https://docs.succapp.com/v5/howto/fill-relation-rules"
title: "关联填充规则"
---
---
order: 2
---
# 关联填充规则
## 用法
选择模型右键-设置关联填充规则
## 功能介绍
SuperPage中控件不具备查询数据能力，只能将数据集的数据直接查询并填充到控件，相比之下仪表板和报表可是设置浮动区域在控件上对模型分组、嵌套关联查询。
SuperPage 增加了一个概念[关联填充规则](./关联填充规则.md)，用来解决浮动控件中使用了多个模型，且上下级模型之间数据应该关联关系的问题
## 注意事项
1. 关联填充规则虽然定义在模型上，但是其生效的必要条件是要在浮动控件中使用了多个模型，比如用两个并列的列表分别查询`企业基本信息`和`企业主要人员`，不会作用两者的关联填充规则，在上级浮动面板中展示`企业基本信息`，内部用列表查每个企业的`企业主要人员`，才会作用两者的关联填充规则
## 主键自动关联
两个模型中其中之一的主键在另一个模型中有同名字段，就会用同名字段关联，可以是多个字段。如`企业基本信息`和`企业主要人员` 都有`企业内部序号`且该字段是`企业基本信息`的主键字段，不需要再手动定义填充规则，设计器中模型右键-设置关联填充规则。
`企业基本信息` 与`企业投资关系`没有主键相关同名字段，需要手动定义关联填充规则。
## 自动根据主查询结果过滤其他查询
默认会启用此选项。
`企业基本信息`上级，`企业投资关系`在下级，会先查询`企业基本信息`的数据，根据查询出来的企业过滤`企业投资关系`，前面说了，SuperPage数据集不在外部做表间关联查询(join)。查询的sql 如下:
```sql
select field1,field2 from 企业投资关系 where 投资企业内部序号 in ('id1','id2','id3')
```
id1,id2,id3 是企业基本信息表的查询结果。当SuperPage的设计者明确知道上级查询的企业id是全量的企业数据，此时默认依然拼一个巨大的in条件的sql就不是理想结果，可以取消勾选此选项来优化查询。不影响界面效果。
## 使用场景
1. 浮动面板`企业基本信息`，内部用列表查`企业投资关系`显示每个企业投资的企业，手动定义关联填充规则`[企业基本信息].[企业内部序号]=[企业投资关系].[投资企业内部序号]`
2. 浮动面板`企业基本信息`，内部用列表查`企业投资关系`显示投资本企业的个人和企业，手动定义关联填充规则`[企业基本信息].[企业内部序号]=[企业投资关系].[被投资企业内部序号]`
3. 浮动面板`企业基本信息`，内部用列表查`企业主要人员`显示每个企业主要人员，主键自动关联
4. 社区显示问题列表时，希望能同时列出“我点赞过”的状态，手动定义关联填充规则`[问题表].[问题ID]=[点赞表].[点赞对象ID]`
---
url: "https://docs.succapp.com/v5/guide/app/workflow/README.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow"
title: "工作流介绍"
---
---
order: 8
navTitle: 工作流
indexTitle: 工作流介绍
---
# 工作流介绍
SuccBI低代码内置了工作流引擎，可以一站式搭建个性化业务流程类的业务应用。
SuccBI内置了易用的流程设计器，帮助业务用户绘制业务流程，流程可以和表单对象、SuperPage对象、微信小程序等进行无缝集成，从而呈现一个完整的业务流程应用。
可以点击如下链接了解具体的功能操作：
!!!children (guide/app/workflow) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/app/workflow/new.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/new"
title: "新建工作流"
---
---
order: 1
navTitle: 新建工作流
---
# 新建工作流
新建一个工作流步骤如下：
1. 进入项目的**应用**模块，右键应用选择编辑，进入[应用设计器](../app-designer.md)
2. 在应用设计器点击左上角的展开箭头，选择`workflow`目录，点击新建，在菜单列表中选择**工作流**
3. 在命名对话框中输入合适且有意义的名称，点击确定进入[工作流设计器](#designer)
4. 接下来可以添加数据模型以及添加节点[绘制工作流](./design.md)，并设置属性，完成后点击保存，并点击右上角的**发布**即可
:::tip
每次对流程进行修改后，不仅要点击**保存**，同时必须进行**发布**，发布成功后，修改的内容才能生效。
:::
## 工作流设计器{#designer}
工作流设计器是用来绘制流程的可视化工具，提供图形化的界面，可以方便直观地定义整个流程，工作流设计器界面如下图：
可以将其划分为如下几个区域：
- **数据源**：数据源区域列出了工作流的表单数据源，用于在分支条件、工作流消息中引用。在工作流中，可以配置各节点对数据源各字段的读写控制
- **流程图**：此区域用于绘制流程图，对流程节点进行编辑，添加节点、添加网关以及添加程序流等，可参考文档[绘制工作流](./design.md)
- **属性栏**：显示流程、节点以及线条的可配置属性，如描述、通知、可进行的表单操作、节点处理人、数据权限、分配方式等
- **工具栏**：工具栏中提供了对工作流的全局设置，如全局参数、消息模板、发布等，绘制完成的流程必须进行发布才能生效
---
url: "https://docs.succapp.com/v5/guide/app/workflow/design.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/design"
title: "绘制工作流"
---
---
order: 3
navTitle: 绘制工作流
---
# 绘制工作流
工作流描述了一个工作流程的内部过程，图中的每个节点都代表一个工作任务（除了开始节点和结束节点），一个典型的工作流示例如下：
绘制工作流主要分为以下几个步骤：
\[\[toc]]
## 添加流程节点{#add-node}
当新建一个工作流时，系统会自动添加一个开始和结束节点，此时只需要添加工作流中的其他工作节点即可。添加节点有两种方法：
1. **直接点击加号添加**：鼠标悬停或选中节点，移动到边框上的小圆点，会变成+号，点击+号，可直接添加任务节点
2. **右键弹出菜单添加**：在节点边框上的+号处右键弹出菜单，可添加节点。也可右键空白地方添加节点，右键空白处新增的节点未与其他节点进行连接，需要手动添加连接线
选中某个节点并右键节点上的+号以及右键空白处，在菜单列表中提供了流程节点的选择，有五种类型，如任务节点、网关节点等，如下所示：
:::tip
当鼠标悬停在节点上时，每条边框上会出现一个小圆点，鼠标悬停变成+号，为当前作用的接口。
:::
### 任务节点{#task-node}
任务节点是需要有业务人员参与的流程节点，需要指定处理人。制定流程的过程就是设置每个节点的属性，如节点数据权限、节点处理人等，通过这些属性将每一个节点连接起来，实现所定义流程的流转以及流程控制的目的。可参考文档[节点处理人设置](./candidate.md)、[节点数据权限设置](./datapermissions.md)。
:::tip
任务节点的高级设置中，可以查看该节点的**节点ID**，**节点ID**不可手动修改，通过SuperPage[执行流程](../superpage/design/action/execute-flow.md)时，退回到指定节点需要用到此处的**节点ID**信息，详情可参考[执行流程](../superpage/design/action/execute-flow.md#node)文档。
:::
### 网关节点{#gateway-node}
网关节点用于条件判断，使用菱形框表示。当流转条件比较复杂、需要分步或者维护时可以使用网关，帮助理清流程图结构，表示此处会根据不同条件，流转到不同的节点。网关没有节点属性，是通过[连线上的条件](#branch-condition)执行不同分支。
### 程序流节点{#actionflow-node}
程序流节点用于无人操作的批处理，能自动化处理一系列业务流程，程序流节点的上一个节点执行完成后，则会自动处理当前程序流。如报销中财务审批通过后自动打款，则可以添加程序流节点，并在该节点的程序流属性中选择程序流文件即可。更多程序流内容可查看文档[程序流](../actionflow/README.md)。
### 脚本节点{#scripts-node}
脚本节点类似于程序流节点，当流程流转到该节点的时候，能自动进行批处理，无需处理人操作。更多脚本内容可查看文档[脚本开发](https://docs.succapp.com/v5/app/script)。
### 结束节点{#end-node}
每一条工作流中，都至少有一个结束节点。新建报表填报应用时，系统会自动添加一对开始和结束节点，将最后一个任务节点与结束节点进行连线即可。当流程中任务可能因为其他条件而需要结束流程，可根据需要自定义添加结束节点。
## 流程线条{#line}
流程线条用来连接2个节点，以及在连线上设置分支的流转条件，如下所示：
### 连接节点{#link-two-nodes}
鼠标移动到节点边框上的小圆点时，会变成一个+号，点击后引出连线，到下一节点时，根据线头的位置，能自动连接最近的接点。如果要重新调整连线，可选中连线，连线的起点、终点以及中间会出现圆点，选中圆点可拖动连接至其他节点或调整连线的大小。
### 流程分支条件{#branch-condition}
将节点进行连线，如果该节点有两个及以上线条流出时，一般会设置分支条件，流程依据条件决定下一步到达的节点。也可勾选**默认分支**属性，勾选后不可设置分支条件。
如请假申请后，研发工程师需要项目经理审批，选中两个节点之间的连线，在**属性栏**>**连线**>**分支条件**中设置连线条件`USER_PROPERTY([请假申请表].[申请人ID],'DEPT_ID')='dev'`。
## 删除节点或线条{#delete}
当不需要节点或线条时，可以将其删除。选中节点或线条，鼠标右键，在弹出的菜单中点击**删除**即可。在删除节点时，同时会将连接该节点的线条都删除，如下所示：
:::tip
当需要同时删除多个节点或线条时，可以使用鼠标框选多个，或者按住ctrl，鼠标点击选中多个，选中的颜色会变成橙色，进行批量删除。
:::
---
url: "https://docs.succapp.com/v5/guide/app/workflow/candidate.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/candidate"
title: "节点处理人设置"
---
---
order: 4
navTitle: 节点处理人设置
---
# 节点处理人设置
节点处理人是在流程流转到节点时，能查看流程数据并进行数据填写、审批、任务分配等处理操作的用户。比如请假流程中，能审批请假的用户，就是审批节点的处理人。
进入工作流设计器，选中任务节点，在右侧**属性栏**>**节点**>**处理人**>**指定处理人**下点击**添加**按钮，在弹出的对话框中根据实际需求选择节点处理人。节点处理人有以下四种设置方式：
- [动态用户](#dynamic-user)
- [用户组](#user-group)
- [部门](#department)
- [用户](#user)
## 动态用户{#dynamic-user}
动态用户，节点处理人不是固定的单一用户或者一组用户，不同的发起人，根据不同的规则，可以获取到不同的处理人。比如请假申请中：
1. 财务部门的员工请假，需要财务部门经理审批
2. 研发部门的员工请假，需要研发部门经理审批
这两条审批规则均是需要发起人所在部门的部门经理审批，这种场景建议使用动态用户，操作如下：
1. 选中部门经理审批节点，在右侧**节点**属性栏的**处理人**处，点击**添加**按钮
2. 在弹出的**选择处理人**对话框中，双击**发起人**到对话框上方的展示区
3. 再双击**发起人**的**所在部门**
4. 最后双击部门经理所在的用户组**审批用户**，点击**确定**即可
这样添加的动态用户会形成一个解析链：**发起人**>**所在部门**>**审批用户**，即节点的处理人为发起人所在部门的部门经理。设置完一类节点处理人后，可以继续点击**添加**按钮，根据需求可以设置多个节点处理人，多个处理人处理流程节点任务的方式可在**分配方式**属性中设置，默认为自动，更多可参考[处理方式设置](#processing-method)。
### 动态用户类型{#type}
系统提供了多种类型的动态用户，如下所示：
- **发起人**：流程的启动用户，发起流程的人。请假是发起人所在部门的组长审批，则需添加发起人的所在部门，以及组长所在用户组，如`发起人 > 所在部门 > 组长`
- **动态处理人**：支持输入表达式，可以拾取表单上表示用户的字段，或者写条件来指定用户。在填写请假申请时，手动选择项目经理，作为任务的处理人，如`[请假申请表].[项目经理]`
- **动态部门**：支持输入表达式，可以拾取表单上表示部门的字段，或者写条件来指定部门。湖北省案件审查，需要湖北下的区级部门参与，因此可以用函数取区级编码为42开头的部门，如`(USER_PROPERTY([流程].[启动用户],'deptid') like '42%'`
- **动态用户组**：支持输入表达式，可以写条件来指定用户组
- **指定部门**：可直接选择系统组织结构中的部门。报销金额过大时，需要财务部门负责人来复核，此时可直接选择财务部门
- **指定节点处理人**：当前流程图中指定节点已经处理过任务的人。医院采购大型设备时，需要之前初审节点的用户再次复核要采购的大型设备，则可直接选择之前的初审节点处理人
- **指定节点候选人**：当前流程图中指定节点的所有处理人，包括未进行任务处理的人
- **上一节点处理人**：上一节点已经处理过任务的人。比如请假申请时，组长审批完成后，需要组长对应的部门经理审批，如`上一节点处理用户 > 上级部门 > 部门经理`
- **上一节点候选人**：上一节点的所有处理人，包括未进行任务处理的人
::: tip
动态用户可以一直往上添加上级部门，如果系统组织结构中没有对应的部门，则会找不到处理人，此时会退回给发起人或者管理员处理。
:::
## 用户组{#user-group}
设置用户组为节点的处理人，则该用户组中的所有用户将成为此节点的处理人。比如医院采购大型设备时，需要专家组进行评审，此时就可以选择`专家组`用户组作为评审节点的处理人。
## 部门{#department}
设置部门为节点的处理人，则该部门中的所有用户将成为此节点的处理人。比如报销流程中，需要财务部门的人对报销单进行核准，此时就可以选择`财务部`作为核准节点的处理人。
## 用户{#user}
设置明确的用户为节点的处理人。比如请假天数大于3天，需要总经理审批，由于公司的高层一般不会变动，此时可以选择总经理用户作为节点的处理人。
::: warning
当用户基本不会变动时，可以使用指定用户作为节点处理人。一般不推荐使用具体的用户作为节点处理人，如果用户总是在发生变化，包括转岗、借调或者离岗后，则需要对流程进行修改。
:::
## 处理方式设置{#processing-method}
当节点有多个处理人时，系统提供了或签、会签、签收三种任务处理方式，在**属性栏**>**节点**>**处理人**中设置**分配方式**即可，如下所示：
- **或签**：每一个处理人均可进行操作处理，当有一人进行操作后，则不需要其他人进行处理。如该节点有ABC三人审批，三人会同时收到审批通知，只需要其中任意一人审批通过即可到下一个审批节点，为默认方式
- **会签**：每一个处理人都需要进行操作处理，且需要每个人都同意，该节点处理结果才为通过。如该节点有ABC三人审批，三人会同时收到审批通知，需全部同意之后，审批才可到下一审批节点。常用于需要多个相同级别的领导同时进行审批
- **签收**：与或签方式类似，但需要处理人先进行**签收**，才能进行审批等操作处理，当其中任意一人签收了，其他人则不能进行签收操作。签收一般被使用在比较重要以及处理工期较长的任务中，需要提前认领或锁定任务，如审批合同，避免多人同时进行，工作重复
:::tip
当节点有多个处理人时，系统内部会为每个处理人创建一条相同的任务，分开记录每个处理人的处理信息，如处理结果、处理意见等，任务信息会记录到流程任务表`FLOW_TASKS`，具体可查看文档[FLOW\_TASKS-流程任务表](../../dev/sys-tables/README.md#flow-tasks)。
**或签**处理方式时，如果有一个人进行了处理，则其他人的任务也被完成；**签收**处理方式与**或签**一样，当有人签收后，其他人的任务被完成，如果退签，则每个处理人会再次重新生成一条任务。
:::
---
url: "https://docs.succapp.com/v5/guide/app/workflow/operate.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/operate"
title: "流程操作"
---
---
order: 5
navTitle: 流程操作
---
# 流程操作
不同的任务节点根据业务流程可以指定不同的操作，工作流支持**提交**、**批准**、**否决**、**退回**等多种操作。如在请假申请中，用户申请时的任务节点操作为**提交**，在管理员审批时的任务节点操作为**批准**和**退回**。
- **提交**：提交数据，如员工提交请假申请
- **批准**：批准发起的申请，如组长批准员工的请假申请。批准后，请假申请会自动流转到下一个节点
- **否决**：否决发起的申请，如组长不同意员工的请假申请。否决后，该申请流程会直接结束，申请人可以提交新的请假申请，处理结果标记为`已否决`
- **退回**：将发起的申请退回到之前的节点，如申请不符合，可进行退回，申请人可进行重填，然后再次审批等
- 默认退回到上一节点
- 支持指定退回节点，勾选**指定退回节点**，在**可退回节点**下拉框中选择需要退回的节点即可
- **终止**：终止申请流程，与否决类似，但是两者流程记录的结果不同，终止处理结果标记为`已终止`，可以区分不同的业务意义
- **撤回**：可对已处理的任务进行撤回，如对发起的申请进行撤回，当整个请假流程未完成时，申请人不想请假了，可以直接进行撤回，更多可查看[撤回](#recall)
:::tip
操作支持多选，在页面上只能执行**操作**属性中勾选的操作选项。撤回操作与其他操作不同，需要在[执行流程交互-操作](../superpage/design/action/execute-flow.md)中进行设置。
:::
## 撤回{#recall}
申请人可对发起的申请进行撤回，重新填写。在**属性栏**>**流程**>**撤回**中勾选**允许撤回**属性即可，也可设置**撤回时需要填写原因**，当执行撤回操作时，系统会自动弹出填写原因的对话框。
此处设置为全局设置，勾选后，当流程未结束时，默认每个节点均可撤回。此时每个任务节点在**属性栏**>**节点**>**高级**中会出现**禁止被撤回**属性，当某些节点不想要被撤回时，可勾选该属性。如请假申请中，请假申请被审批之后不允许撤回，则除申请节点之外，其他节点均需要勾选**禁止被撤回**属性。
---
url: "https://docs.succapp.com/v5/guide/app/workflow/datapermissions.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/datapermissions"
title: "节点数据权限设置"
---
---
order: 6
navTitle: 节点数据权限设置
---
# 节点数据权限设置
节点数据权限设置用于控制不同的流程节点表单输入项的权限，比如请假申请时可以输入`请假原因`、`请假类型`等，但是部门经理审批请假单时却只能查看而不能修改`请假原因`、`请假类型`等内容。
设置思路如下：
1. 选中任意一个任务节点，在右侧**属性栏**>**节点**>**数据**属性中，可设置节点数据的读写权限，点击**放大编辑**按钮，可以放大数据设置界面。如选中`部门经理审批`流程节点，找到`请假原因`、`请假类型`等字段，将**可写**属性勾选去掉
2. 设置的权限数据为工作流中添加的数据源数据，具体可参考文档[在工作流中添加数据源](./work-with-spg.md)，数据源所有字段的表单组件都默认勾选**可见**和**可写**
3. 页面输入组件的读写权限想要绑定工作流的数据权限，则需在页面添加流程表单数据源时，勾选底部的**根据流程设置显示隐藏或禁用输入项**，具体可参考文档[在SuperPage中添加流程数据源](./work-with-spg.md)
::: tip
节点数据权限设置是对参与流程处理的用户权限的细分操作，对于是否能发起流程、参与流程审批，还需要对用户进行[权限管理](../../permission/grant/README.md)配置以及流程中[处理人设置](./candidate.md)
:::
---
url: "https://docs.succapp.com/v5/guide/app/workflow/notice.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/notice"
title: "工作流消息通知"
---
---
order: 7
navTitle: 消息通知
---
# 工作流消息通知
流程流转时，系统能自动给相关负责人发送通知消息，比如张三发起请假申请，其组长李四会收到一条待办任务的通知。通过消息中携带的链接，能直接打开对应的处理页面，提升流程处理效率。常见的通知消息如下图所示：
|待办通知|结果通知|退回通知|
|--|--|--|
||||
## 启用消息通知{#enable}
工作流可以自动给处理人发送通知消息，提醒处理人及时处理流程中的任务。在系统中内置了多种通用的消息模板，支持发送常规的待办、退回以及结果通知等，想启用消息通知时，只需要做如下配置：
1. **配置摘要字段**：在**流程**>**属性栏**>**数据**设置中可配置[摘要字段](#summary)，[摘要字段](#summary)是流程中的主要信息，发送的消息通知中会带上[摘要字段](#summary)的内容，配置说明可参考后续文档章节[摘要字段](#summary)
2. **启用消息通知**：在**流程**>**属性栏**>**高级**设置中可勾选**启用通知**，勾选后系统会按照内置的消息模板在工作流流转过程中发送通知消息
完成上述配置后，工作流就可以自动发送通知消息了，如果系统内置的默认模板不足以满足需求，可继续参考后续文档章节[消息的自定义配置](#custom)。
:::tip 相关系统设置
消息能正常发送，还需要系统的管理员做一些前置的准备工作：
1. 在**系统设置**>**外部服务**中需要配置[邮件](../../sys-settings/more/remote-services/email.md)和[短信](../../sys-settings/more/remote-services/message.md)服务，如果需要发送微信消息的，需要参考配置文档[微信登录](../../devops/sso/wechat.md)。
2. 在**系统设置**>**协同办公**中需要配置好默认的**消息模板**，系统中有提供默认的模板配置，不用修改就能正常使用，管理员也可对按照自身系统业务对默认模板进行一些自定义修改，详细说明可参考文档[协同办公](https://docs.succapp.com/v5/sys/settings/co)。
:::
## 消息的自定义配置{#custom}
当系统内置的消息模板不足以满足用户的自定义需求时，比如某个工作流在领导审批节点发送的待办消息需要和其他节点的待办消息有所不同，则此时可以针对这些差异来自行配置个性化的消息模板，工作流中的消息配置如下图所示：
点击**工具栏**>**消息模板**设置后会弹出**消息模板**设置对话框，以自定义领导审批节点的待办消息模板为例，消息模板的配置分为以下步骤：
1. **管理消息模板**：在**消息模板**的配置对话框中，左侧显示了所有已配置的模板，其中包含了系统自带的默认模板，用户可新增模板或对已有模板进行修改，此时我们需要新增一个模板并给其设置一个有意义的业务描述。更多设置说明可参考[消息模板管理](#manage)章节
2. **设置匹配规则**：选择新增的模板，需要配置好对应的[匹配规则](#match)，由于是需要配置待办的消息通知，此时对应的**匹配事件**是**分配任务**，匹配节点为**领导审批**。更多配置说明可参考[匹配规则设置](#match)章节
3. **设置推送内容**：确认好[匹配规则](#match)后，需要继续确定消息的[推送内容](#content)，可以在模板中配置自定义的摘要信息或是直接选择其他的内容模板作为推送的主要内容。更多配置说明可参考[推送内容设置](#content)章节
## 消息模板管理{#manage}
在工作流中，可对使用的消息模板进行增删管理。在[协同办公](https://docs.succapp.com/v5/sys/settings/co)设置中提供了系统默认的模板设置，可以满足常规的待办，催办以及结果通知需求。工作流中的消息模板设置初始默认继承[协同办公](https://docs.succapp.com/v5/sys/settings/co)中的设置，用户可在工作流中做自定义修改。模板管理的操作说明如下：
1. 点击工具栏中的**消息模板**按钮，可以打开消息模板设置对话框
2. 可直接点击对话框中左侧的**添加**按钮添加消息模板，也可点击**添加**按钮右侧的下拉箭头使用其他添加选项
1. **通知**：添加**通知**类型的消息模板
2. **抄送**：添加**抄送**类型的消息模板
3. **系统流程模板**：被删除的**系统模板**可在此处再次添加回来，**系统模板**就是在[协同办公](https://docs.succapp.com/v5/sys/settings/co)设置中配置的模板
3. 鼠标悬停在模板上时，会显示模板的操作按钮
1. **重置**：对于系统提供的默认模板，工作流中有自定义修改的，可以通过**重置**按钮将其还原为系统初始状态
2. **复制**：将指定模板复制一份
3. **删除**：将指定模板删除，如果删除的是系统模板，则可以在添加选项中的**系统流程模板**中重新添加回来
### 消息类型介绍{#type}
根据接收消息的用户不同，系统将要发送的消息分为**通知**和**抄送**两类：
1. **通知**：只会发送给当前任务对应的处理人，接收这类消息的用户通常都是在流程中需要处理任务的用户，如在请假流程中，当张三发起请假申请后，流程走到组长审批环节，此时如果设置了待办通知模板，则会给组长审批节点的[节点处理人](./candidate.md)即张三的组长发送对应的通知消息
2. **抄送**：在抄送模板设置中，需要添加抄送人，系统只会给抄送人发送对应的消息。抄送人通常是指对流程有一定关注但不参与流程任务处理的用户，如在新人考核流程中，公司的领导可能并不参与考核过程，但考核中的关键步骤的结果可能会以抄送消息的形式发给领导
:::tip 通知和抄送的区别
**通知**与**抄送**最大的区别在于**通知**消息的接收人是系统自动判断的，只会发送给节点的处理人，而**抄送**消息需要用户在对应的**抄送**模板上手动指定**抄送人**。
从配置上来说，**抄送**是**通知**的补充，当某些消息通过**通知**无法自动发送给某些未参与流程任务处理的用户时，就可以通过**抄送**消息来自由的配置发送给那些额外的用户。
:::
## 匹配规则设置{#match}
只有满足模板的匹配规则时，系统才会发送对应的消息通知，模板的匹配规则设置属性如下：
- **匹配事件**：单选，只有在节点上触发相应的[事件](#event)时，系统才会根据模板上的配置来给用户发送对应的消息，比如用户发起的请假申请在组长审批后被退回到了申请节点，则此时是在申请节点触发了**退回事件**，如果有配置了匹配**退回事件**的模板，此时会给申请人发送对应的模板消息 。有关[事件](#event)的详细说明可参考后续文档章节
- **匹配节点**：多选，默认是全部节点，可选择工作流中的[流程节点](./design.md#add-node)，和**匹配事件**搭配，只有在选择的节点上触发**匹配事件**才会发送消息
- **抄送人**：仅**抄送模板**需要设置，设置方法可参考[节点处理人设置](./candidate.md)文档，**抄送**消息只会发送给模板上配置的**抄送人**
- **匹配条件**：支持输入表达式，未设置时默认为`TRUE`，返回`FALSE`时，视为不满足发送该模板的条件，不会发送对应的模板消息
:::tip 消息的发送规则
1. 工作流消息在发送时会自动过滤掉触发消息发送时的用户，比如A、B、C三个用户同时处理某流程节点的任务，流程中配置了当**任务完成**时发送的通知消息，此时A完成了任务，通知只会发送给B、C，A作为触发消息的处理人会被自动过滤掉。
2. 工作流中配置的消息模板，按照从上到下优先匹配的原则，在同一时间内只会给同一个用户发送一种模板的消息。比如在流程中分别配置了**流程结束**以及**任务结束**时发送的消息，**流程结束**的消息模板排在**任务结束**的消息模板前面，当流程的最后一个任务完成时，此时也触发了**流程结束**事件，即同时满足了两类模板的发送条件，这两类模板如果分开来看，发送消息时都会发给用户A，但根据发送原则只会匹配到第一个模板消息。
:::
### 事件{#event}
[流程操作](./operate.md)执行完成后，会触发工作流中的相关事件，比如审批用户对当前审批的任务进行**批准**或**否决**等操作后，待审批的任务处理完成了，会触发**任务完成**事件。以简单的请假流程为例，来对事件进行说明：
| 事件 | 触发操作 | 触发方式 | 示例 |
|--|----|----|----|
|退回|退回|流程被退回到某节点|流程从组长审批节点退回到申请节点，即是在申请节点触发退回事件|
|撤回|撤回|流程任务被撤回|流程已到达组长审批节点，申请人将流程撤回到申请节点，即是在组长审批节点触发了撤回事件|
|分配任务|提交、批准|流程顺利往下进行到下一个节点|提交请假申请单，流程往下走到组长审批节点，即是在该节点触发了分配任务的事件|
|任务结束|提交、批准、否决、终止|处理人通过流程操作来处理自己的待办任务，按照操作的不同会有批准、否决、终止三类任务结束的结果|用户处理了组长审批节点的任务后，即是在组长审批节点触发了任务结束事件|
|节点完成（仅抄送模板可设置）|提交、批准、否决、终止|流程节点对应的所有任务被处理完成|会签节点，A，B，C共同处理，所有任务处理完成后触发节点完成事件|
|流程结束（仅抄送模板可设置）|提交、批准、否决、终止|流程被否决、终止或顺利走完完整流程|请假流程整个审批完成，或在中间节点被审批用户否决时触发流程结束事件|
|催办|催办|到达催办时间后系统自动催办或有其他用户手动催办|流程停留在组长审批节点事件过长，申请人对自己发起的流程进行催办，此时就是在组长审批节点触发了催办事件|
|处理人变更|签收、取消签收、转交|流程任务的处理人发生变更时|用户A将自己的任务转交给用户B处理，即为触发处理人变更事件|
## 推送内容设置{#content}
消息的推送内容主要由内容正文和链接两部分组成，在系统的[协同办公](https://docs.succapp.com/v5/sys/settings/co)设置中提供了默认的模板内容，常见的消息推送内容如下图所示：
推送内容的具体设置属性如下：
- **消息模板**：决定了发送消息的内容，可以在**系统设置**>**协同办公**>**消息模板**中列出的模板中选择，点击**编辑模板**按钮可以跳转到[协同办公](https://docs.succapp.com/v5/sys/settings/co)中自定义模板内容，模板内容的详细设置可参考文档[协同办公](https://docs.succapp.com/v5/sys/settings/co)
- **自定义摘要**：勾选后显示**摘要字段**设置，设置说明可参考后续章节[摘要字段](#summary)。当消息中需要显示不同的摘要信息时可以设置，比如某产品的试用申请流程，只有当最后申请通过了才会在通知消息中发送有效期的信息，则此时申请通过的消息模板中可以自定义**摘要字段**，添加上这个有效期的字段
- **自定义发送方式**：[协同办公](https://docs.succapp.com/v5/sys/settings/co)中创建的模板会设置发送方式，如果需要自定义，可勾选此选项，在系统已配置的发送范围内指定发送方式，可多选
- **启用链接**：勾选后，消息中会带上跳转到任务处理页面的链接，仅用于微信、邮件，通知模板默认勾选，抄送模板默认取消勾选
- **自定义链接**：勾选**启用链接**后可以设置，勾选后可以通过如下设置自定义消息中携带的链接地址
- **链接类型**：可选择**内部资源**或**URL**，决定了自定义的链接来源
- **内部资源**：**链接类型**选择**内部资源**时需要设置，从系统内部中选择资源作为携带的链接地址
- **URL**：**链接类型**选择**URL**时需要设置，直接以设置的**URL**作为携带的链接地址
- **参数**：设置链接页面所需参数的值
### 摘要字段{#summary}
**摘要字段**是用来描述一条流程主要信息的字段，通常是选取业务表中的字段作为**摘要字段**，如在请假流程中，可设置申请人、请假开始时间以及请假天数作为**摘要字段**。在**属性栏**>**流程**>**数据**中可设置**摘要字段**：
1. 可点击右上角的添加按钮添加**摘要字段**
2. 添加后在**字段选择**下拉框中可选择业务表中的字段
3. 可手动设置**字段标题**，未设置时默认使用字段名称作为标题
4. 按住左侧的**拖拽图标**可调整字段间的顺序
:::tip 摘要的继承设置以及应用场景
1. 可在**流程全局**、**流程节点**以及**消息模板**中分别配置摘要字段，系统按照**消息模板**>**流程节点**>**流程全局**的优先级来确定要使用的摘要信息。
2. 由于在默认的消息模板内容中，系统只配置了通用的流程相关的信息，每个工作流的消息差异可以在**摘要字段**中体现，建议在配置工作流时同步配置**摘要字段**。
3. 摘要信息还可应用到SuperPage的[列表](../superpage/components/data/list.md)与[移动列表](../superpage/components/mobile/mobilelist.md)用于展示流程任务的待办列表等。
:::
## 流程催办{#urge}
当业务上对工作流事务的处理时间有要求时，可以对工作流设置**催办**，当任务到达催办时间且仍未被处理时，系统会自动给对应的处理人发送催办消息。这涉及到两个关键点：
1. 在[消息模板](#message-template)中需要配置匹配了**催办事件**的消息模板
2. 在**属性栏**>**流程**>**催办**中需要**启用催办**，并配置**催办日期**以及**催办时间**
- **催办日期**：决定了任务具体在哪一天进行催办，根据以下三种标准配合设置的偏移时间来计算催办的具体日期
- **任务到达后**：任务到达节点的那一刻开始计算，比如任务到达时是周五，偏移时间设置的是1个工作日，则会在下周一进行催办，如果是1个自然日，则是在周六进行催办
- **截止时间前**：流程节点上可设置[截止时间](#deadline)，设置说明可参考后续章节。这种设置下会按照[截止时间](#deadline)为标准往前计算偏移量来获取催办日期，比如[截止时间](#deadline)为周五，偏移时间设置为1个工作日，则在周四时进行催办
- **截止时间后**：按照[截止时间](#deadline)为标准往后计算偏移量来获取催办日期
- **催办时间**：可选择系统中类型为工作流的计划任务，依据任务的时间设置发送催办通知，更多可查看[计划管理](../../schedule/README.md#manage-schedule)。当计划任务执行时，会判断流程任务是否到达催办时间，到达的任务便会发出对应的催办通知
:::tip 催办的自定义设置
1. 在**属性栏**>**节点**>**催办**中可以设置**禁用催办**或**自定义催办时间**，这是为了某些流程环节不需要催办或任务紧急程度不一样时可以单独对节点有不一样的设置。
2. 上述设置是系统自动催办的设置，手动催办设置，可参考[执行流程](../superpage/design/action/execute-flow.md)文档。
:::
### 任务截止时间{#deadline}
每个任务节点都可以设置**截止时间**，系统能根据设定的**截止时间**自动对任务进行处理，催办设置中也需要依据截止时间发送催办通知。设置如下所示：
- **截止时间**：可设置固定、动态、无三种选项，按照不同规则来确定**截止时间**
- **固定**：**截止时间**设置为固定时，需要设置**处理时长**，系统会根据任务到达的时间加上**处理时长**得到任务的**截止时间**
- **动态**：**截止时间**设置为动态时，需要设置**表达式**，用于用户直接在表单中指定**截止时间**的场景，表达式中通常是获取业务表中字段的值
- **无**：无截止时间
- **超时操作**：任务到达截止时间后，会自动根据**超时操作**中的设置来处理流程任务
- **无**：不做任何操作
- **自动通过**：任务自动批准，流程进入到下一节点
- **退回到上一步**：将任务退回到上一节点
- **退回到起始节点**：将任务退回到申请节点
- **终止流程**：将流程终止掉
:::tip 截止时间的计划任务设置
与**催办时间**类似，任务到达**截止时间**后并不会立即执行相关的**超时操作**，在项目设置的[工作流设置](../../project-manage/wfl-setting.md)中统一提供了**截止时间**的配置，只能选择系统中类型为工作流的计划任务，计划任务执行时会判断流程任务是否超时，并对超时任务进行自动处理。
:::
## 数据安全{#datasafe}
在发送的消息通知中，对携带链接的查看做了相应的**数据安全**设置，包括以下限制：
1. 流程任务的处理页面通常只有处理人以及在流程中添加了查看权限的管理员有查看权限，针对抄送模板，即便抄送人没有查看权限，比如张三的任务抄送给李四，李四默认是没有查看权限的，但此时由于李四是抄送人的关系，所以可以通过消息中携带的链接进行查看
2. 抄送人只能查看任务内容，但不能对任务进行任何操作
3. 其他无关的用户即便通过其他手段获取到消息中携带的链接，通过链接进入页面也会提示无权限
---
url: "https://docs.succapp.com/v5/guide/app/workflow/work-with-spg.md"
htmlUrl: "https://docs.succapp.com/v5/app/workflow/work-with-spg"
title: "与SuperPage集成"
---
---
order: 10
navTitle: 与SuperPage集成
---
# 与SuperPage集成
**工作流**支持与SuperPage集成使用。当需要搭建一个完整的工作流业务系统时，工作流负责处理底层的流程运转，SuperPage则负责处理流程数据的查询、填报以及审批的相关页面。工作流与SuperPage集成的关键点在于[流程数据源](../superpage/design/datasourse.md#wfl-data)的使用。下面分章节讲解集成各部分的原理：
\[\[toc]]
## 工作流流转原理{#wfl-data}
在工作流流转过程中，系统会自动对流程相关的两张系统表[流程实例表](../../dev/sys-tables/README.md#flow-insts)与[流程任务表](../../dev/sys-tables/README.md#flow-tasks)进行操作，以请假申请为例，当张三发起一条请假申请，并在后续走完审批流程的过程中，系统表中的数据操作如下：
- [流程实例表](../../dev/sys-tables/README.md#flow-insts)
- 发起请假申请，表中新增一行数据，会记录流程ID、业务主键（此处是记录请假单号）等关键信息来标识这是张三发起的一条请假申请
- 组长李四进行审批，审批通过后会更新这行数据的最后处理人，处理结果以及时间等信息来表示这条流程的最新状态
- 流程完整走完后，会将这行数据的**实例状态**更新为`finished`，代表张三的这条请假申请已经走完流程了
- [流程任务表](../../dev/sys-tables/README.md#flow-tasks)
- 每个[流程节点](./design.md#add-node)经过时都会生成对应的流程任务，以张三发起申请后，需要经过组长审批、部门经理审批的简单流程为例，此处对应3个[流程节点](./design.md#add-node)，会生成3条流程任务，即在[流程任务表](../../dev/sys-tables/README.md#flow-tasks)中对应新增3行数据
- 同一[流程节点](./design.md#add-node)有多人处理时，按照处理人数生成流程任务，比如张三的组长有两个，那么在组长审批节点时，会给两个组长都生成流程任务，如果是**或签**，则其中一个组长审批完成后，另外一个组长的流程任务就会由系统自动完成
- 流程中多次经过同一[流程节点](./design.md#add-node)，如张三发起申请后被组长李四退回，流程再次回到申请节点，此时是针对申请节点生成新的流程任务，而不是在第一次申请时的任务基础上进行修改。
:::tip
1. 一条申请记录，在[流程实例表](../../dev/sys-tables/README.md#flow-insts)中始终只有一条数据，用于记录申请的实时状态。[流程任务表](../../dev/sys-tables/README.md#flow-tasks)中会有多条数据，每一个流程任务对应一条数据。[流程实例表](../../dev/sys-tables/README.md#flow-insts)与[流程任务表](../../dev/sys-tables/README.md#flow-tasks)是一对多的关系。
2. 在发起流程时，[流程任务表](../../dev/sys-tables/README.md#flow-tasks)中会生成申请节点的流程任务并直接将任务状态置为已完成，同时会生成下一个节点的待办任务。
:::
## 查询流程任务列表{#task-list}
用户在处理工作流相关事务时，针对不同的用户角色，通常需要查看不同的任务列表，以OA系统为例，常用的列表有：
| 待办列表 | 已办列表 | 申请列表 |
| ------- | ------- | ------- |
|  |  |  |
- [待办列表](https://demo.succbi.com/v5/DEMO_OA/app/OA.app?id=%E4%BB%BB%E5%8A%A1)：系统的审批用户使用，用于展示OA系统中所有待自己处理的流程任务，可能是请假或报销的待审批任务等
- [已办列表](https://demo.succbi.com/v5/DEMO_OA/app/OA.app?id=%E4%BB%BB%E5%8A%A1)：系统的审批用户使用，用于展示OA系统中所有自己已处理的流程任务，可以查看自己的处理记录
- [申请列表](https://demo.succbi.com/v5/DEMO_OA/app/OA.app?id=%E6%88%91%E7%9A%84&:drillPage=%2FDEMO_OA%2Fapp%2FOA.app%2Fmobile%2Fhome_internal%2Fapply.spg%3FpageCache%3DcreatePage&:drillPageTitle=%E6%88%91%E7%9A%84%E7%94%B3%E8%AF%B7)：所有人通用，用于展示OA系统中自己申请的流程，如需要查询自己发起的报销申请到了流程的哪一环节
在SuperPage中提供了[流程数据源](../superpage/design/datasourse.md#wfl-data)的设置，通过[我的待办](../superpage/design/datasourse.md#my-tasks)、**我的已办**等[流程数据源](../superpage/design/datasourse.md#wfl-data)的引入可以很方便的获取到需要查询的任务列表。详细说明可参考[引入数据](../superpage/design/datasourse.md#my-tasks)文档。
:::tip
[我的待办](../superpage/design/datasourse.md#my-tasks)、**我的已办**等设置只是系统提供的一种快捷设置方式，用户也可以自行引入[流程任务表](../../dev/sys-tables/README.md#flow-tasks)或相关**数据加工**并为其添加需要的过滤条件作为查询的任务列表。
:::
## 跳转到工作流表单页面{#link-to}
以OA系统为例，整个系统中可能有多种工作流，请假流程，报销流程，合同审批流程等。这意味着审批用户的**待办列表**中会有多个流程的审批任务。点击这些任务后跳转到的处理任务的**表单页面**都是不同的，比如审批请假申请和报销申请的**表单页面**必然是不同的两个页面。系统能够从任务列表根据选择的流程任务自动跳转到**表单页面**，这其中涉及到两个关键点：
1. 在**工作流**的配置中，在流程全局和节点设置中可以指定处理任务的**表单页面**，系统可以很容易的得到流程节点对应的**表单页面**地址
2. 任务列表中设置[打开链接](../superpage/design/action/linkto.md)交互，链接的对象指定为**工作流表单**，则打开链接时会根据当前选择的流程任务自动找到其在**工作流**上配置的**表单页面**地址
**工作流**的**表单页面**设置如下：
- **表单页面选择**：默认的下拉框中可选择系统内部资源作为表单页面
- **指定表单URL**：勾选后，下拉框会变为输入框，可手动输入表单页面的URL
- **指定手机端**：勾选后，可额外设置手机端的表单页面，系统会自动根据使用的设备跳转到指定页面
## 读写流程表单数据{#read-and-write}
以请假申请为例，审批用户在**待办列表**中点击张三的申请跳转到了处理请假流程的**表单页面**，此时**表单页面**中需要展示张三的请假申请信息。也就是说跳转到**表单页面**后，系统需要自动定位到当前在处理的业务数据，不能出现点击张三的任务结果进到页面看到的是李四的申请信息的情况。工作流表单数据的读写需要使用[流程表单数据](../superpage/design/datasourse.md#page-img)，在**数据**>**工作流**中可添加[流程表单数据](../superpage/design/datasourse.md#page-img)，设置说明可参考[引入数据](../superpage/design/datasourse.md#page-img)文档。此处介绍系统如何通过[流程表单数据](../superpage/design/datasourse.md#page-img)定位业务数据：
1. 从**待办列表**跳转到**表单页面**时，在[打开链接](../superpage/design/action/linkto.md)交互中需要将**任务代码**信息传递给了**表单页面**的`taskId`参数
2. 在**表单页面**中将`taskId`设置到引入的[流程表单数据](../superpage/design/datasourse.md#page-img)中，以请假申请的设置为例，就是将`taskId`设置到[流程表单数据](../superpage/design/datasourse.md#page-img)`请假申请表`的**任务ID**属性中
3. 将`请假申请表`设置为**单行数据集**，并在**表单页面**中的输入组件上绑定`请假申请表`中对应的字段
通过上述设置，当**表单页面**获取到从**待办列表**传递过来的**任务代码**时，系统能从[流程任务表](../../dev/sys-tables/README.md#flow-tasks)中自动获取当前任务对应的**业务代码**，以请假流程为例，此处获取到的是`请假单号`。同时，在[流程表单数据](../superpage/design/datasourse.md#page-img)`请假申请表`中也设置了这个**任务代码**，系统可以很自然的通过获取到的`请假单号`来过滤`请假申请表`，并将信息自动装载到绑定了`请假申请表`的组件中。
:::tip
1. 给[流程表单数据](../superpage/design/datasourse.md#page-img)提供正确的**任务代码**就可以定位到指定的业务数据，但数据的自动装载还需要注意将[流程表单数据](../superpage/design/datasourse.md#page-img)设置为**单行数据集**。
2. 业务模型为主从表的场景中，比如报销流程，可能有`报销申请表`和`报销明细表`，主表与从表是一对多的关系，这种情况下从表的数据装载，不需要设置对应[流程表单数据](../superpage/design/datasourse.md#page-img)为**单行数据集**。
:::
## 控制表单输入项的权限{#data-control}
同一个**工作流**，在不同的[流程节点](./design.md#add-node)中，某些业务数据可能会有不同的读写权限设置。以请假申请为例，在申请节点，用户可以填写基本的申请信息，但无法输入`调休天数`的内容，而当申请进入组长审批环节，此时组长可以修改组员的`调休天数`但无法修改其基本的申请信息。类似的效果可以通过在组件上写禁用条件的方式来实现，但带有流程的表单，一般推荐在工作流上进行配置，容易管理，这涉及到以下关键点：
1. 在[流程节点](./design.md#add-node)中可添加[节点数据权限设置](./datapermissions.md)，确定业务数据的字段读写权限
2. 在**表单页面**中通过[流程表单数据](../superpage/design/datasourse.md#page-img)来[读写流程表单数据](#read-and-write)，页面中的组件需要绑定[流程表单数据](../superpage/design/datasourse.md#page-img)中的字段
3. [流程表单数据](../superpage/design/datasourse.md#page-img)的设置中需要勾选**根据流程设置显示隐藏或禁用输入项**属性，设置说明可参考[引入数据](../superpage/design/datasourse.md#page-img)文档
通过上述设置，当表单页面获取到**任务代码**后，系统能自动获取到对应的[流程节点](./design.md#add-node)信息，从而根据[流程节点](./design.md#add-node)上的字段权限设置来自动控制绑定了对应字段的输入组件的读写情况。
:::tip
1. 只有能够绑定字段的输入组件才能根据[节点数据权限设置](./datapermissions.md)来自动控制读写，按钮、文本等组件如果也想达到类似的效果，则需要在显示和禁用条件中通过[wfl\_canview](../../exp/func/others/WFL_CANVIEW.md)、[wfl\_canedit](../../exp/func/others/WFL_CANEDIT.md)函数进行设置。
2. 针对已完成的任务，再次进入到任务的表单页面时，绑定了[流程表单数据](../superpage/design/datasourse.md#page-img)中字段的输入组件都会自动变成禁用模式。
:::
## 流程操作交互{#wfl-actions}
流程相关的操作交互可以分为两种：
1. 操作流程业务数据的交互，如[提交表单](../superpage/design/action/submit-data.md)、[更新数据](../superpage/design/action/update-data.md)等
2. 操作流程任务的交互，用来**发起流程**或在审批时对流程任务进行批准、退回等操作
以下主要对操作流程任务的交互进行说明：
- [提交表单](../superpage/design/action/submit-data.md#start-flw)：应用于流程的发起，在提交流程业务的同时发起新的流程，更多详细说明可参考[提交表单](../superpage/design/action/submit-data.md#start-flw)文档
- [执行流程](../superpage/design/action/execute-flow.md)：用于流程发起后，处理流程任务的审批工作，可对用户的待办流程任务进行批准、否决以及退回等操作，更多详细说明可参考[执行流程](../superpage/design/action/execute-flow.md)文档
- [批量发起流程](https://docs.succapp.com/v5/superpage/action/batch-start-flow)：多用于上级分配的流程任务，比如由管理员批量选择一批员工来发起考核流程，更多说明可参考[批量发起流程](https://docs.succapp.com/v5/superpage/action/batch-start-flow)文档
## 通知消息{#message}
工作流流转过程中，当符合发送条件时，系统会自动根据配置的**消息模板**来给对应用户发送[消息通知](./notice.md)。比如请假流程的待办消息模板配置的发送条件是当流程中的任意节点有新的流程任务生成时就发送消息，那么当张三完成申请后，组长李四生成了一条待办的流程任务，此时系统就会根据模板配置自动给李四发送待办消息。详细的通知说明可参考[消息通知](./notice.md)文档。
## 数据安全{#datasafe}
:::warning
当使用工作流与SuperPage集成来搭建完整的业务系统时，请尽量使用[流程数据源](../superpage/design/datasourse.md#wfl-data)来制作SuperPage页面，这涉及到流程的**数据安全**问题。使用[流程数据源](../superpage/design/datasourse.md#wfl-data)时，系统会自动判断当前用户对他正在处理的流程任务是否具备相应的权限，如张三不能在没有权限的情况下看到李四的待办任务详情，更不能直接处理李四的待办任务。直接在页面中引入[流程实例表](../../dev/sys-tables/README.md#flow-insts)或[流程任务表](../../dev/sys-tables/README.md#flow-tasks)以及其加工模型的操作可能导致**数据泄露**。
:::
---
url: "https://docs.succapp.com/v5/guide/app/security.md"
htmlUrl: "https://docs.succapp.com/v5/app/security"
title: "应用的安全性"
---
---
order: 9
navTitle: 应用的安全性
---
# 应用的安全性
SuccBI十分重视数据安全，充分考虑了黑客的渗透攻击和越权攻击的防护。
:::warning 安全告知
SuccBI作为一个低代码平台提供了多种安全相关的功能设置，业务应用的安全性问题也需要依赖应用搭建者的正确设置。
:::
## 安全性设计原则
TODO
“使用者”只能在“作者”限定的数据范围内查询和更新
所有安全处理逻辑都在服务器完成，杜绝黑客伪装请求越权访问数据
## 加密和脱敏
TODO
数据使用国密加密算法存储到数据库
数据脱敏后发送给前端
## 数据安全设置
TODO
数据集类型：只读、只写、读写
查询条件、写条件、设置只允许特定的用户写…
后端校验逻辑、最大查询行数
## 资源权限分配
TODO
## 脚本的安全
TODO
---
url: "https://docs.succapp.com/v5/guide/app/actionflow/README.md"
htmlUrl: "https://docs.succapp.com/v5/app/actionflow/overview"
title: "程序流"
---
---
order: 9
navTitle: 程序流
indexTitle: 概述
---
# 程序流
程序流是SuccBI提供的一种基于流程的可视化服务器端API设计的功能。
一个业务应用往往会有一些个性化的服务器端处理逻辑，如对文章进行点赞、商品订单的新增和修改等。这些操作往往需要在一个事务中完成，如下单操作需要先查询商品库存，如果还有库存就将库存-1，并插入一条订单数据；否则直接返回提示没有库存。调用程序流可以保证整个过程在后端执行，不被前端代码篡改执行逻辑。
在以前开发这样的服务器端接口通常需要研发工程师编码完成，现在可以用程序流定义服务器端的逻辑。
## 为什么要使用程序流{#reason}
**程序流**中执行的内容往往可以在[SuperPage](../superpage/README.md)中直接配置，但时常会遇到这些情况：相同的交互需要重复多次的在每个按钮上添加、一个按钮上添加了多个交互，各交互的执行条件不同，不容易维护、一些敏感的数据总是从前端提交等等，这些问题的产生促使了**程序流**的诞生。
调用**程序流**，把交互放在后端执行，能够带来以下几点好处：
1. 当页面按钮上设置的交互较多，且交互设置有执行条件，此时可以把交互放在**程序流**中，用线条表示执行条件，节点表示交互，展示不同情况下执行哪些交互，易于后期对交互进行维护
2. 同一个页面的不同按钮，或不同页面的按钮中，需要配置的交互相同，若每次都重新配置，则操作量太大，将这些交互放在**程序流**中执行，只需要配置一个**程序流**，就可以在每个按钮中**调用程序流**来使用这些交互
3. 使用**程序流**可以将页面的制作与后台逻辑交互的配置分离，这样可以让实现界面的工程师与配置交互的工程师同时工作，提高效率
4. 业务上一些查询数据的请求可以在**程序流**中通过API接口发送
---
url: "https://docs.succapp.com/v5/guide/app/actionflow/new.md"
htmlUrl: "https://docs.succapp.com/v5/app/actionflow/new"
title: "新建程序流"
---
---
order: 1
navTitle: 新建程序流
---
# 新建程序流
新建一个程序流的步骤如下：
1. 进入项目的**应用**模块，右键应用选择**编辑**，进入[应用设计器](../app-designer.md)
2. 在应用设计器的**API**目录下新建**程序流**
3. 在命名对话框中输入合适且有意义的名称，点击确定进入[程序流设计器](#designer)
4. 接下来可以添加数据模型以及添加节点绘制**程序流**，并设置属性，完成后点击保存即可
:::tip
**程序流**可以在SuperPage页面中通过[调用程序流](../superpage/design/action/call-action-flow.md)使用，也可以在[工作流](../workflow/README.md)中添加**调用程序流**节点使用。
:::
## 程序流设计器{#designer}
可以将其划分为如下几个区域：
- **数据源**：数据源区域列出了程序流中使用到的模型表，可在分支条件、节点的数据操作中引用
- **流程图**：此区域用于绘制程序流的流程图，可添加并编辑节点的交互操作、分支条件等，具体可参考文档[绘制程序流](./design.md)
- **属性栏**：显示分支线条、节点的可配置属性，如分支的启用条件、节点交互的具体设置等
- **工具栏**：工具栏中提供了对程序流的全局设置，如全局参数
---
url: "https://docs.succapp.com/v5/guide/app/actionflow/design.md"
htmlUrl: "https://docs.succapp.com/v5/app/actionflow/design"
title: "绘制程序流"
---
---
order: 2
navTitle: 绘制程序流
---
# 绘制程序流
程序流使用可视化的流程图绘制出服务器端后台业务逻辑的执行流程，图中每一个节点都代表一个执行动作（类似SuperPage的交互动作），本文讲述如何进行程序流的绘制：
## 添加流程节点{#add-node}
当新建一个程序流时，系统会自动添加一个开始和结束节点，此时只需要添加程序流中的其他节点即可，如鼠标点击**开始**节点边框四周的+号，选择其中一个，即可添加第一个节点。
添加节点时有三种类型可选：
1. **动作节点**：一个节点对应一个动作，当流程走到这个节点时，就会执行这个节点上的动作。节点的可选项是[SuperPage动作](../superpage/design/action/README.md)的子集，主要是对数据的操作类动作，如[复制数据](../superpage/design/action/copy-data.md)、[提交表单](../superpage/design/action/submit-data.md)等。对于一些样式类的交互动作，如[显示对话框/悬浮面板](../superpage/design/action/show-dialog.md)，需要在SuperPage页面中自行设置，具体用法可参考对应的动作文档
2. **网关节点**：网关节点用于条件判断，使用菱形框表示。当流转条件比较复杂、需要分步或者维护时可以使用网关，帮助理清流程图结构，表示此处会根据不同条件，流转到不同的节点。网关没有节点属性，是通过连线上的条件执行不同分支
3. **结束节点**：每一条程序中，都至少有一个结束节点。新建程序流时，系统会自动添加一对开始和结束节点，将最后一个节点与结束节点进行连线即可。当流程中任务可能因为其他条件而需要结束流程，可根据需要自定义添加结束节点
## 流程线条{#line}
流程线条用来连接两个节点，以及在连线上设置分支的流转条件，如下所示：
### 连接节点{#link-two-nodes}
鼠标移动到节点边框上的小圆点时，会变成一个+号，拖拽这个加号可以引出连线，拖动到目标节点边框四周的圆点上松开鼠标，可以绘出两节点之间的连线。如果要重新调整连线，可选中连线，连线的起点、终点以及中间会出现圆点，选中圆点可拖动连接至其他节点或调整连线的大小。
### 流程分支条件{#branch-condition}
如果节点有两个及以上线条流出时，需要设置线条的分支条件，流程依据设置的条件决定下一步执行到达的节点。有两种设置条件的方式：
- **设置启用条件**：即根据上一个节点的执行状态判断是否流转，在**启用**属性上设置，有以下几种选项：
- 上一节点成功：表示上一节点执行成功时走这个线条分支，为默认选项。若上一节点是开始节点且满足**执行条件**，则一定会走这个分支
- 上一节点错误：表示上一节点执行失败时走这个线条分支，可选择具体的导致上一节点执行失败的错误类型：
- 全部：表示上一节点只要执行失败，无论导致失败的原因是什么，都会走这个线条分支，为默认选项
- 主键冲突：表示操作的数据主键与表内已有数据的主键重复
- 校验失败：表示模型上设置了[数据校验](https://docs.succapp.com/v5/data-gov/data-audit)，且校验失败
- 其他异常：除**主键冲突**和**校验失败**外的所有异常错误
- 上一节点结束：表示只要上一节点执行结束，无论最终的结果是否成功，都将走这个线条分支
- 其他分支都不执行时：表示当其他线条分支的条件都不满足时，则走这个分支，该条件的优先级较低，总是优先判断条件为**上一节点成功/错误/结束**的分支
- 禁用：禁用这条分支后，该条分支节点不再执行，一般在调试阶段使用，选择后不可设置**执行条件**
- **设置执行条件**：输入表达式来判断模型中的数据或**程序流**中的全局参数是否满足某种条件，需要勾选**设置执行条件**，勾选后必须同时满足**启用**条件和**执行条件**，才会流转到该线条分支
:::tip
当程序流的任意一条分支都不满足条件时，程序流会直接结束，值得注意的是，这种情况并不算程序流执行失败。
:::
## 删除节点或线条{#delete}
当不需要节点或线条时，可以将其删除。选中节点或线条，鼠标右键，在弹出的菜单中点击删除即可。在删除节点时，同时会将连接该节点的线条都删除，如下所示：
:::tip
当需要同时删除多个节点或线条时，可以按住ctrl，鼠标点击选中多个后松开ctrl，选中的颜色会变成橙色，此时右键在弹出的菜单中选择**删除**可以进行批量删除。
:::
---
url: "https://docs.succapp.com/v5/guide/app/actionflow/component-commands.md"
htmlUrl: "https://docs.succapp.com/v5/app/actionflow/component-commands"
title: "组件命令{#component-commands}"
---
---
order: 20
navTitle: 组件命令
---
# 组件命令{#component-commands}
本文列出程序流“执行组件命令”节点可以调用的组件命令。配置时先选择目标组件，再选择该组件支持的命令；可以先按组件分组查看支持哪些命令，再到命令详情中查看参数。
## 按组件分组查看{#command-groups}
### 输入{#command-group-input}
本组组件：列表上传（`listUpload`）、列表选择（`selector`）、勾选框（`checkbox`）、勾选框组（`checkboxGroup`）、卡片上传（`cardUpload`）、多行输入（`multipleInput`）、字段过滤（`fieldsFilter`）、密码输入（`passwordInput`）、富文本输入（`richtextInput`）、引用表（`datasources`）、快速搜索（`searchbox`）、搜索框（`searchInput`）、数值输入（`numberInput`）、文本输入（`input`）、日期选择（`dateSelector`）、时间选择（`timeSelector`）、条件指示器（`filtersViewer`）、树形选择（`treeSelector`）、签名（`signInput`）、表达式输入（`expInput`）、资源选择（`resSelector`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`focus`](#command-focus) | 聚焦 | **以下组件不支持：**
~~条件指示器（`filtersViewer`）~~ | 聚焦。 |
| [`blur`](#command-blur) | 失去焦点 | **以下组件不支持：**
~~条件指示器（`filtersViewer`）~~ | 失焦。 |
| [`clear`](#command-clear) | 清空 | 所有输入 | 清空组件内容。 |
| [`uploadFile`](#command-upload-file) | 上传文件 | **仅以下组件支持：**
列表上传（`listUpload`）
卡片上传（`cardUpload`） | |
### 数据{#command-group-data}
本组组件：树（`tree`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`find`](#command-find) | 搜索 | 所有数据 | 按关键字搜索。 |
| [`locateNextFoundItem`](#command-locate-next-found-item) | 定位下一个节点 | 所有数据 | 定位到下一个或上一个搜索结果。 |
### 嵌入{#command-group-embed}
本组组件：Superpage（`embedSuperpage`）、仪表板（`embedDashboard`）、报表（`embedReport`）、数据模型（`embedDataModel`）、文档（`document`）、流程进度（`embedFlowProgress`）、表单（`embedForm`）、表单应用（`embedFapp`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`addBlankRows`](#command-add-blank-rows) | 新增行 | **仅以下组件支持：**
表单（`embedForm`）
表单应用（`embedFapp`） | 增加空白行。 |
| [`removeRows`](#command-remove-rows) | 删除行 | **仅以下组件支持：**
表单（`embedForm`）
表单应用（`embedFapp`） | 删除指定行。 |
| [`forceRefresh`](#command-force-refresh) | 刷新 | 所有嵌入 | |
| [`zoomIn`](#command-zoom-in) | 放大 | **仅以下组件支持：**
文档（`document`） | |
| [`zoomOut`](#command-zoom-out) | 缩小 | **仅以下组件支持：**
文档（`document`） | |
| [`print`](#command-print) | 打印 | **仅以下组件支持：**
Superpage（`embedSuperpage`）
报表（`embedReport`）
文档（`document`） | |
| [`export`](#command-export) | 导出 | **仅以下组件支持：**
报表（`embedReport`）
文档（`document`） | |
| [`search`](#command-search) | 搜索 | **仅以下组件支持：**
文档（`document`） | |
| [`validateForm`](#command-validate-form) | 校验 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`saveDraft`](#command-save-draft) | 保存 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`submitData`](#command-submit-data) | 提交 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`importData`](#command-import-data) | 导入 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`exportData`](#command-export-data) | 导出数据 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`lockData`](#command-lock-data) | 锁定 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`unlockData`](#command-unlock-data) | 解锁 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`calculateForm`](#command-calculate-form) | 计算 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
| [`deleteFAppData`](#command-delete-fapp-data) | 删除 | **仅以下组件支持：**
表单应用（`embedFapp`） | |
### 工具{#command-group-util}
本组组件：计时器（`timer`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`start`](#command-start) | 开始 | 所有工具 | 启动计时器。 |
| [`stop`](#command-stop) | 停止 | 所有工具 | 停止计时器。 |
### 媒体{#command-group-media}
本组组件：视频（`video`）、音频（`audio`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`stop`](#command-stop) | 停止 | **仅以下组件支持：**
视频（`video`） | 停止计时器。 |
| [`forceRefresh`](#command-force-refresh) | 刷新 | **仅以下组件支持：**
音频（`audio`） | |
| [`play`](#command-play) | 播放 | **仅以下组件支持：**
视频（`video`） | |
| [`fullScreen`](#command-full-screen) | 最大化 | **仅以下组件支持：**
视频（`video`） | |
| [`setMuted`](#command-set-muted) | 设置是否静音播放 | **仅以下组件支持：**
视频（`video`） | |
### 地图{#command-group-map}
本组组件：2D地图（`gisMap2D`）、3D地图（`gisMap3D`）、百度地图（`gisMapBmap`）、高德地图（`gisMapAmap`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`rollup`](#command-rollup) | 上卷 | 所有地图 | |
| [`setView`](#command-set-view) | 设置地图视角 | 所有地图 | |
### 统计图{#command-group-chart}
本组组件：双向条形图（`pyramid`）、图标条形图（`hpictogramBar`）、图标柱状图（`pictogramBar`）、折线图（`line`）、散点图（`scatter`）、旭日图（`sunburst`）、条形图（`hbar`）、柱形图（`bar`）、桑基图（`sankey`）、玫瑰图（`rose`）、环形图（`ring`）、矩阵图（`treemap`）、组合图（`combo`）、词云图（`wordCloud`）、象形条形图（`hpictorialBar`）、象形柱形图（`pictorialBar`）、雷达图（`radar`）、面积图（`area`）、饼图（`pie`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`rollup`](#command-rollup) | 上卷 | 所有统计图 | |
### 指标图{#command-group-measure}
本组组件：仪表盘（`gauge`）、水位图（`waterPercent`）、进度环（`percentRing`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`rollup`](#command-rollup) | 上卷 | 所有指标图 | |
### 开发{#command-group-develop}
本组组件：HTML（`html`）、JS组件（`jsComponent`）、网页（`webview`）。
本组支持以下命令。多个组件共用同一个命令时，命令详情只在后文写一次。
| 命令 | 名称 | 支持组件 | 说明 |
| :--- | :--- | :--- | :--- |
| [`forceRefresh`](#command-force-refresh) | 刷新 | **以下组件不支持：**
~~HTML（`html`）~~ | |
| [`print`](#command-print) | 打印 | **以下组件不支持：**
~~JS组件（`jsComponent`）~~ | |
## 命令详情{#command-details}
### setProperty{#command-set-property}
设置组件属性。
例如：设置组件显示隐藏、启用禁用、输入只读等。
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `name` | `字符串` | 属性名。 |
| `value` | `任意值` | 属性值。 |
### focus{#command-focus}
聚焦。
### blur{#command-blur}
失焦。
### clear{#command-clear}
清空组件内容。
### find{#command-find}
按关键字搜索。
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `keyword` | `字符串` | 搜索关键字。 |
| `searchMode` | `ComponentSearchMode` | 搜索模式。默认值：`flatFilter`。可选值：、、。 |
### locateNextFoundItem{#command-locate-next-found-item}
定位到下一个或上一个搜索结果。
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `forward` | `布尔值` | 是否向后定位。默认值：`true`。为`true`时定位下一个搜索结果，为`false`时定位上一个搜索结果。 |
| `recursive` | `布尔值` | 是否循环定位。默认值：`true`。为`true`时到达边界后从另一端继续定位。 |
### addBlankRows{#command-add-blank-rows}
增加空白行。
在目标行位置插入一行或多行空白数据。可指定插入位置（前/后、下级）和初始数据。未指定
`targetRow` 时，插入到数据视图的末尾。
启用行操作特征`rowOperation`才支持此命令。
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `count` | `数值` | 新增行数。默认值：`1`。 |
| `targetRow` | `JSON` | 插入目标行，不存在时插入到表格最后一行。 |
| `asChild` | `布尔值` | 为true时插入到目标行下级。默认值：`false`。 |
| `insertBefore` | `布尔值` | 为true时插入到目标行之前，否则插入到目标行之后。默认值：`false`。 |
| `data` | `JSON \| JSON[]` | 新增空行的初始化数据。单行时传一个 JSON 对象；新增多行时传 JSON 对象数组，数组下标和新建行顺序一一对应。
没有提供对应下标的数据时，该行保持空白。
JSON 对象的 key 是组件 id，如 `"column1"`、`"column2"`；value 是要写入该组件的值。 |
| `autoSelect` | `布尔值` | 自动选中插入的行。默认值：`false`。 |
### removeRows{#command-remove-rows}
删除指定行。
未传 `row` 时，默认删除触发命令的当前行；若当前行也不存在会弹出警告
提示。
启用行操作特征`rowOperation`才支持此命令。
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `row` | `JSON \| JSON[]` | 操作的行。 |
| `autoSelect` | `布尔值` | 自动选中其他行。默认值：`false`。 |
### start{#command-start}
启动计时器。
启动或恢复计时器的运行，开始按配置的间隔或持续时间执行计时逻辑。
### stop{#command-stop}
停止计时器。
暂停计时器的运行，停止所有定时回调。
### rollup{#command-rollup}
### forceRefresh{#command-force-refresh}
### uploadFile{#command-upload-file}
### zoomIn{#command-zoom-in}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `level` | | 缩放值。 |
### zoomOut{#command-zoom-out}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `level` | | 缩放值。 |
### print{#command-print}
### export - document{#command-export-document}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `name` | | 文件名。 |
### export - exportFormat{#command-export-export-format}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `fileName` | | 文件名。 |
| `exportFormat` | | 导出格式。默认值：`xlsx`。可选值：`xlsx`、`pdf`。 |
| `sheet` | | 工作表。默认值：`current`。可选值：`current`：当前、`all`：所有。 |
| `exportPage` | | 导出页。默认值：`currentPage`。可选值：`currentPage`：当前页、`allPage`：所有页。 |
| `showExportDialog` | | 弹出导出选项对话框。默认值：`false`。 |
| `selectPageEnabled` | | 允许选择导出页。默认值：`false`。 |
| `selectSheetEnabled` | | 允许选择工作表。默认值：`false`。 |
| `selectFormatEnabled` | | 允许选择导出格式。默认值：`false`。 |
| `allSelectFormat` | | 可选格式。默认值：`["xlsx","pdf"]`。可选值：`xlsx`、`pdf`。 |
### search{#command-search}
### validateForm{#command-validate-form}
### saveDraft{#command-save-draft}
### submitData{#command-submit-data}
### importData{#command-import-data}
### exportData{#command-export-data}
### lockData{#command-lock-data}
### unlockData{#command-unlock-data}
### calculateForm{#command-calculate-form}
### deleteFAppData{#command-delete-fapp-data}
### setView{#command-set-view}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `zoom` | | 缩放级别。 |
| `centerLng` | | 中心经度。 |
| `centerLat` | | 中心纬度。 |
| `rotation` | | 旋转角度。 |
| `pitch` | | 俯仰角度。 |
| `animation` | | 显示过渡动画。 |
### play{#command-play}
### fullScreen{#command-full-screen}
### setMuted{#command-set-muted}
| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| `muted` | | 是否静音。 |
---
url: "https://docs.succapp.com/v5/guide/app/app-settings.md"
htmlUrl: "https://docs.succapp.com/v5/app/settings"
title: "应用设置"
---
---
order: 10
navTitle: 应用设置
---
# 应用设置
## 短路径{#shorturls}
短路径配置主要用于精简、美化业务应用的URL地址，并且更好的支持SEO。
在应用设置中配置好短路径后，当浏览器访问的URL匹配到了配置的短路径规则，服务器端会将请求转发到对应的源路径上，浏览器收到的就是源路径的响应内容。当用户在浏览器进行操作引起了当前页面URL发生变化，此时也会将匹配的源路径替换为短路径，总是会确保浏览的URL是期望的短路径。
示例地址：[应用设置](https://demo.succbi.com/v5/DEMO/app/DEMO.app?:edit=true&:file=settings.json)
::: warning 警告
配置路径映射时不仅需要配置直接访问业务应用的短路径，业务应用操作过程中URL会发生变化，短路径配置需要涵盖所有需要替换的URL。
例如配置了将路径`/demo`映射到应用`/DEMO/app/DEMO.app`，用户在界面上操作会让URL加上id参数，最终URL会变为`/demo?id=xxx`。如果需要URL形式为`/demo/xxx`，则需要添加映射规则`/demo/{id}`=>`/DEMO/app/DEMO.app?id={id}`。
:::
### 短路径配置规则{#shorturls-rules}
短路径和源路径之间支持以下几种匹配规则：
| 描述 | 短路径 | 源路径 | 示例 |
| :--------------- | :----------------- | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| 完整路径匹配 | `/demo` | `/DEMO/app/DEMO.app` | 访问`/demo`，映射到`/DEMO/app/DEMO.app` |
| 路径变量匹配 | `/demo/{id}` | `/DEMO/app/DEMO.app?id={id}` | 访问`/demo/图形`，映射到`/DEMO/app/DEMO.app?id=图形` |
| 路径变量正则匹配 | `/demo/{id:[\d]+}` | `/DEMO/app/DEMO.app?id={id}` | 访问`/demo/123`，映射到`/DEMO/app/DEMO.app?id=123`。如果访问`/demo/abc`，则不会匹配到这条规则，如果也没有匹配到后续规则，会返回404 |
| 路径变量匹配 | `/demo/{mkbl}/{id}` | `/DEMO/app/DEMO_TEST.app/portal/{mkbl}.tpg?id={id}` | 访问`/demo/fs/权限`，映射到`/DEMO/app/DEMO_TEST.app/portal/fs.tpg?id=权限`|
| 当前目录匹配 | `/demo` | `.` |在应用`/DEMO/app/DEMO.app`中进行配置，访问`/demo`，映射到`/DEMO/app/DEMO.app`|
| 相对路径匹配 | `/demo/{id}` | `?id={id}` |在应用`/DEMO/app/DEMO.app`中进行配置,访问`/demo/图形`，映射到`/DEMO/app/DEMO.app?id=图形`|
| 设置不生效 | `/DEMO` | `/DEMO/app/DEMOAP.app` |访问`/DEMO`，因其是系统本来有效的路径，故不会匹配到`/DEMO/app/DEMOAP.app`，而展示本来的`/DEMO`页面|
说明：
1. 短路径中可以使用花括号括起来的变量，花括号括起来的内容可以只是变量名如`/demo/{id}`，也可以包括变量匹配的正则表达式如`/demo/{id:[\d]+}`，其中`id`是变量名，可以任意修改，变量名可以用到源路径中。
2. 变量只能匹配一级路径段不能匹配多级路径，如`/demo/{id}`可以匹配`/demo/001`但不能匹配`/demo/def/001`。
3. 源路径可以配置相对于当前应用的路径，例如在应用`/DEMO/app/DEMO.app`中配置源路径`home.tpg?id={id}`，则实际源路径为`/DEMO/app/DEMO.app/home.tpg?id={id}`。
4. 源路径可以使用`.`代表当前应用路径，例如在应用`/DEMO/app/DEMO.app`中配置源路径`.`，则实际源路径为`/DEMO/app/DEMO.app`。
5. 可能会有多条配置匹配到相同的路径的情况，此时可以通过调整配置顺序来调整优先级。
6. 配置的短路径不能与系统默认的路径相同，相同时将产生冲突，短路径设置不生效。例如`/DEMO/app/DEMOAP.app`的短路径不能配置为`/DEMO`、`/DEMO/app`等系统中本来有效的路径。
---
url: "https://docs.succapp.com/v5/guide/app/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/app/faq"
title: "常见问题"
---
---
order: 12
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/app/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/app/errcode"
title: "低代码错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 低代码错误提示排查
---
url: "https://docs.succapp.com/v5/guide/co/README.md"
htmlUrl: "https://docs.succapp.com/v5/co"
title: "协同"
---
---
order: 11
navTitle: 协同
---
# 协同
---
url: "https://docs.succapp.com/v5/guide/co/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/co/faq"
title: "常见问题"
---
---
order: 99
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/co/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/co/errcode"
title: "协同错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 协同错误提示排查
---
url: "https://docs.succapp.com/v5/guide/exp/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp"
title: "表达式"
---
---
order: 12
---
# 表达式
!!!children (guide/exp) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/exp/operators.md"
htmlUrl: "https://docs.succapp.com/v5/exp/operators"
title: "表达式操作符"
---
---
order: 1
navTitle: 操作符
---
# 表达式操作符
系统中支持的所有表达式操作符如下：
\[\[TOC]]
## 四则运算符{#arithmetic}
| 操作符 | 说明 | 示例 |
| :---------:| :--------| :-------- |
| `+` | 加法运算 | `1+2=3` |
| `-` | 减法运算 | `3-2=1` |
| `*` | 乘法运算 | `3*2=6` |
| `/` | 除法运算 | `6/3=2` |
| `%` | 求模运算 | `3%2=1` |
## 逻辑运算符{#logic}
| 操作符 | 说明 | 示例 |
| :---------:| :--------| :-------- |
| `NOT` | 非运算(与IN、LIKE、CONTAIN等组合使用) | `[纳税表].[行业] NOT LIKE '%工业%'` 选取纳税行业中不包含'工业'的数据 |
| `!` | 非运算(与=、~等组合使用) | `[纳税表].[月份]!=1` 选取纳税月份不等于1月的数据 |
| `EXISTS` | 存在运算，与SELECT函数构成过滤条件 | `EXISTS SELECT([发票表], [企业信息].[ID]=[发票表].[销方企业] and [企业信息].[失信]='Y')` 过滤出失信企业开具的发票信息 |
| `NOT EXISTS` | 不存在 | `NOT EXISTS SELECT([发票表], [企业信息].[ID]=[发票表].[销方企业] and [企业信息].[失信]='Y')` 过滤出不是失信企业开具的发票信息 |
| `=` | 等于 | `[纳税表].[省份]=420000` 选取纳税省份等于湖北省的数据(不包含下级) ；`[纳税表].[省份].[省市县层次]=420000` 选取纳税省份等于湖北省的数据(包含下级)|
| `BELONG` | 属于，等价于`[维键字段].[默认层次]='xx'` | `[纳税表].[省份] BELONG 420000` 选取纳税省份等于湖北省的数据(包含下级)，等价于 `[纳税表].[省份].[默认层次]=420000`； `420000 BELONG 420000` BELONG自身时返回true |
| `NOT BELONG` | 不属于(包含自身及下级)，等价于`[维键字段].[默认层次]!='xx'` | `[纳税表].[省份] NOT BELONG 420000` 选取纳税省份不等于湖北省的数据(包含下级)，等价于 `[纳税表].[省份].[默认层次]!=420000`； `420000 NOT BELONG 420000` BELONG自身时返回false |
| `==`(Deprecated，过时弃用) | 只等于(用于维项表达式时只等于自身) | `[纳税表].[省份]==420000` 选取纳税省份字段等于`420000`的数据(不包含下级) |
| `>` | 大于 | `[纳税表].[纳税额]>1000` 选取纳税额大于1000的数据 |
| `<` | 小于 | `[纳税表].[纳税额]<2000` 选取纳税额小于2000的数据 |
| `>=` | 大于等于 | `[纳税表].[纳税额]>=1000` 选取纳税额大于等于1000的数据 |
| `<=` | 小于等于 | `[纳税表].[纳税额]<=2000` 选取纳税额小于等于2000的数据 |
| `!=` | 不等于| `[纳税表].[省份]!=420000` 选取纳税省份不等于湖北省的数据(不包含下级) ；`[纳税表].[省份].[省市县层次]!=420000` 选取纳税省份不等于湖北省的数据(包含下级) |
| `!==`(Deprecated，过时弃用) | 不等于用于维项表达式时不包含下级 | `[纳税表].[省份]!==420000` 选取纳税省份字段不等于`420000`的数据(不包含下级) |
| `<>` | 不等于 | `[纳税表].[月份]<>1` 同上 |
| `AND` | 逻辑与 | `[纳税表].[月份]=1 AND [纳税表].[地区]='01'` 选取纳税月份为1月且地区为01的数据|
| `&&` | 逻辑与 | `[纳税表].[月份]=1 AND [纳税表].[地区]='01'` 同上 |
| `OR` | 逻辑或 | `[纳税表].[月份]=1 || [纳税表].[月份]=2` 选取纳税月份为1月或2月的数据 |
| `||` | 逻辑或 | `[纳税表].[月份]=1 || [纳税表].[月份]=2` 同上 |
| `IS` | 连接NULL或NOT NULL关键字 |`[纳税表].[月份] IS NULL` 选取纳税月份为空的数据 |
| `IS NULL` | 等于空 | 同上 |
| `IS NOT NULL` | 不等于空 | `[纳税表].[月份] IS NOT NULL` 选取纳税月份不为空的数据 |
| `BETWEEN` | 与AND搭配，选取介于两个值之间的数据范围 | `[纳税表].[纳税额] BETWEEN 1000 AND 2000` 选取纳税额在1000-2000的数据|
| `IN` | 查询具体范围内数据 | `[纳税表].[地区] IN ('01','02','03')` 选取纳税地区在(01,02,03)范围内的数据|
| `NOT IN` | IN的非运算 | `[纳税表].[地区] NOT IN ('01','02')` 选取纳税地区不在(01,02)范围内的数据|
| `LIKE` | 与通配符组合实现模糊查询 | `[纳税表].[行业] LIKE '%信息%'` 选取纳税行业中包含'信息'的数据 |
| `NOT LIKE` | LIKE的非运算 | `[纳税表].[行业] NOT LIKE '%工业%'` 选取纳税行业中不包含'工业'的数据|
| `CONTAINS` | 包含，灵活查询的操作符，详见[逻辑匹配](./types.md#logic-match)。 | `[纳税表].[行业] CONTAINS '信息|电子'` 选取纳税行业中包含'信息'或者'电子'的数据 |
| `NOT CONTAINS` | 不包含 | `[纳税表].[行业] NOT CONTAINS '信息|电子'` 选取纳税行业中不包含'信息'或者'电子'的数据 |
| `STARTS WITH` | 以xx开头，等价于`LIKE 'xx%'` | `[纳税表].[企业] STARTS WITH '中国'` 选取纳税企业中以'中国'开头的数据 |
| `NOT STARTS WITH` | 不以xx开头，等价于`NOT LIKE 'xx%'` | `[纳税表].[企业] NOT STARTS WITH '中国'` 选取纳税企业中不以'中国'开头的数据 |
| `ENDS WITH` | 以xx结尾，等价于`LIKE '%xx'` | `[纳税表].[企业] ENDS WITH '股份有限公司'` 选取纳税企业中以'股份有限公司'结尾的数据 |
| `NOT ENDS WITH` | 不以xx结尾，等价于`NOT LIKE '%xx'` | `[纳税表].[企业] NOT ENDS WITH '股份有限公司'` 选取纳税企业中不以'股份有限公司'结尾的数据 |
| `MATCH REGEX` | 匹配正则表达式 | `"abc123" MATCH REGEX "[0-9]"` 返回值为true；`"abc123" match regex '^[0-9]'` 返回false |
| `NOT MATCH REGEX` | 不匹配正则表达式 | `"abc123" NOT MATCH REGEX "[0-9]"` 返回值为false；`"abc123" NOT MATCH REGEX '^[0-9]'` 返回true |
| `MATCH TEXT` | 全文检索（与LIKE不同，全文检索引擎会先对搜索字符串进行分词，再基于分词后的词项进行检索）。| `[纳税表].[企业] MATCH TEXT '百度技术'`或者 `[纳税表].[企业] MATCH TEXT '百度公司'`都可以搜索到`百度在线网络技术有限公司`|
| `NOT MATCH TEXT` | 全文检索不匹配 | `'百度在线网络技术有限公司' NOT MATCH TEXT '百度公司'` 返回false|
| `MATCH INITIAL` | 首字母匹配，左侧只能是配置了[首字母字段](../data-gov/model/README.md#model-field)的字段 | `[企业表].[企业名称] MATCH INITIAL 'XM'` 使用`企业名称`关联的首字母字段`企业名称首字母`匹配`XM`|
| `NOT MATCH INITIAL` | 首字母不匹配 | `[企业表].[企业名称] NOT MATCH INITIAL 'XM'` `企业名称`关联的首字母字段`企业名称首字母`不匹配`XM` |
::: warning
1. `==`、`!==`两个操作符在5.0+版本后已经被弃用（Deprecated），仅出于兼容低版本的需要暂未移除，未来版本可能会移除！
2. 对于过滤时是否包含下级维项由操作符左侧的字段决定，如果左侧是普通字段（包括维键），比如`[企业表].[所属地区]`，那么就是过滤字段本身，不包含下级维项；如果左侧是层次字段，比如`[企业表].[所属地区].[省市县层次]`，那么就是按层次过滤，包含下级维项。
:::
## 括号{#brackets}
| 操作符 | 说明 | 示例 |
| :---------: | :-------- | :-------- |
| `(` | 分隔表达式的计算逻辑 | `IF([利润]>0,"盈利",IF([利润]=0,"盈亏平衡","亏损"))` |
| `)` | 同上 | 同上 |
| `[` | 分隔系统变量(包括数据源字段、用户、位置) | `[纳税表].[月份] [用户].[用户ID]` |
| `]` | 同上 | 同上 |
## 转义符{#escape}
| 操作符 | 说明 | 示例 |
| :---------: | :-------- | :-------- |
| `,` | 分隔参数、数组项等 | `RANK([利润表].[销量], [利润表].[地区])` |
| `.` | 分隔层级 | `[纳税表].[月份] [用户].[用户ID]` |
## 数据项分隔符{#delimiter}
系统中使用表达式进行匹配、搜索等支持谷歌搜索引擎类似的基本语法（OR AND等），可以在输入多个数据项时以约定分隔符分隔，配合操作一起使用能快速实现多个数据项条件之间的OR或AND关系。
系统支持如下几种数据项分隔符：
| 操作符 | 说明 | 示例 |
| :---------: | :-------- | :-------- |
| `,` | 分隔多个数据项进行或运算 | `经营状态='开业,存续'`表示选取经营状态为开业或存续的数据 |
| `|` | 分隔多个数据项进行或运算 | `经营状态='开业|存续'`表示选取经营状态为开业或存续的数据 |
| `OR` | 分隔多个数据项进行或运算 | `经营状态='开业 OR 存续'`表示选取经营状态为开业或存续的数据 |
| `&` | 分隔多个数据项进行与运算 | `企业标签='小规模纳税人&化工'`表示选取企业同时具有`小规模纳税人`和`化工`标签的数据 |
| `AND` | 分隔多个数据项进行与运算，需大写，左右两侧需有空格 | `企业标签='小规模纳税人 AND 化工'`表示选取企业同时具有`小规模纳税人`和`化工`标签的数据 |
| ` ` (空格)| 分隔多个数据项进行与运算，仅用于`包含`、`检索`两种操作符的场景下 | `企业标签 contains '小规模纳税人 化工'`表示选取企业标签同时包含`小规模纳税人`和`化工`两种字符的数据 |
::: tip
1. 考虑到不同语言下的使用情况，`AND`、`OR`两种操作符必须是大写且左右两侧都有空格才生效！
2. 可以结合`(`、`)`来实现复杂的结合运算，比如：`*=武汉&(半导体|投资)`表示包含`武汉`和`半导体`，或包含`武汉`和`投资`
3. 当搜索或匹配的字符串中包含操作符时，比如包含`,`和`AND`等操作符需要当做普通字符串看待搜索是，可以使用双引号`"`括起来作为完整的字符串使用，具体参见[其他符号（双引号-"）](#others)
:::
## 区间范围{#interval}
| 操作符 | 说明 | 示例 |
| :---------: | :-------- | :-------- |
| `~` | 区间范围 | `[销售日期].[年]=2020~2023'`表示`[销售日期].[年]>=2020 AND [销售日期].[年]<=2023` |
| `(` | 左开区间 | `[销售日期].[年]=(2020~2023)'`表示`[销售日期].[年]>2020 AND [销售日期].[年]<2023` |
| `)` | 右开区间 | 同上 |
| `[` | 左闭区间，左右两个边界值都是闭区间时可省略 | `[销售日期].[年]=[2020~2023]'`表示`[销售日期].[年]>=2020 AND [销售日期].[年]<=2023` |
| `]` | 右闭区间，左右两个边界值都是闭区间时可省略 | 同上 |
更多使用示例参考：[数值范围匹配](./types.md#number-range)和[日期范围匹配](./types.md#date-range)
## 其他符号{#others}
| 操作符 | 说明 | 示例 |
| :---------:| :-------- | :-------- |
| `CASE WHEN THEN ELSE END` | 实时计算条件函数 | `CASE WHEN [纳税表].[地区] IN('01','05','07') THEN '北方地区' WHEN [纳税表].[地区] IN('02','03','04','06') THEN'南方地区' ELSE '其他' END` 地区为'01、05、07'返回'北方地区'，'02、03、04、06'返回'南方地区'，其他情况返回'其他' |
| `"` | 当字符串中包括操作符时，左右用`"`括起来的内容当一个完整字符串使用 | `='"(半导体|导体)"'` 表示包含`(半导体|导体)`； `='\"(半导体|导体)\"'` 表示等于`"(半导体|导体)"` |
---
url: "https://docs.succapp.com/v5/guide/exp/types.md"
htmlUrl: "https://docs.succapp.com/v5/exp/types"
title: "数据类型"
---
---
order: 2
navTitle: 数据类型
---
# 数据类型
本文介绍表达式中的数据类型，表达式中的变量、常量、字段等都是有类型的，相比于字段的数据类型，表达式中的数据类型更宽泛一些，如字段类型的字符型和CLOB都会对应表达式中的字符串类型、字段的日期和时间戳都对应表达式中的日期类型，表达式中包括如下类型：
- [数值](#value)
- [日期](#date)
- [布尔](#boolean)
- [JSON](#json)
- [数组](#array)
- [NULL](#null)
## 数值{#value}
数值类型包括整数、浮点数、BigNumber等，数据库中的int、int64、bigint、decimal、numeric、double等在表达式中都是数值类型，表达式中有些函数的参数需要传递整数，如left函数的第二个参数，但传递含有小数的数值也是可以的，在表达式中，各种类型的数值都是可以通用的。
### 数值范围匹配{#number-range}
当需要查找某个指定数值范围内的数据时，可以使用`>`、`<`等操作符进行数值比较，但也可以使用数值范围匹配来查找对应的数据，示例：
|条件|说明|
|-----------|----------------|
|`fact.age='18~20'`|表示年龄在`18,20之间的数据`，包含左右两侧边界值，等价于`fact.age='[18~20]'`或`fact.age>=18 AND fact.age<=20`|
|`fact.age='[18~20)'`|表示年龄在`[18,20)之间的数据`，`[`表示包含左边界值，`)`表示不包含右侧边界值|
|`fact.age='18~'`|表示年龄在`大于等于18岁的数据`，等价于`fact.age>=18`|
|`fact.age='(18~)'`|表示年龄在`大于18岁以上的数据`，等价于`fact.age>18`|
|`fact.age='~20'`|表示年龄在`小于等于20岁以下的数据`，等价于`fact.age<=20`|
### 多个数值匹配{#multi-number}
当需要查找多个指定数值时，可以按照[约定的数据项分隔符](./operators.md#delimiter)同时传递多个值进行匹配，示例：
|条件|说明|
|--|--|
|`fact.age='18,20'` |表示`fact.age IN (18,20)`|
|`fact.age!='18,20'` |表示`fact.age NOT IN (18,20)`|
|`fact.age=参数` |参数包含多值且参数为`18,20`，表示`fact.age IN (18,20)`|
|`fact.age=ARR(18,20)`|表示`fact.age IN (18,20)`|
|`fact.age=ARR('18,19',20)`|表示`fact.age IN (18,19,20)`|
## 字符串{#string}
在表达式中，字符型字段和CLOB型的字段在表达式中是字符串类型，单引号或双引号括起来的内容都是常量字符串。
### 字符串转义符{#string-escape}
单引号或双引号括起来的内容都是常量字符串，如果字符串中有特殊符号如回车换行需要使用转义符来转义，示例：
|条件|说明|
|--|--|
|`\r`|回车符|
|`\n`|换行符|
|`\t`|水平制表|
|`\0`|ASCII码0|
|`\\`|代表一个反斜线字符`\`|
|`\'`|代表一个单引号字符`'`|
|`\"`|代表一个双引号字符`"`|
|`\u+4位16进制数`|代表指定的Unicode字符，如`'\u597d'`代表汉字“好”、`'\uD83D\uDE04'`代表表情符号“😄”|
### 字符串通配符{#string-wildmatch}
在使用`like`或`not like`时，系统支持使用通配符，来生成条件，查询期望的数据。
|通配符|说明|
|--|--|
|`*`或`%`|匹配多个字符，比如：`湖北*` 表示“湖北”开头|
|`?`或`_`|匹配一个字符，比如：`*有限??公司` 表示结尾是“有限某某公司”|
示例：
|条件|说明|
|--|--|
|`fact.[企业名称] like '*科技*'`|匹配企业名称包含`科技`|
|`fact.[企业名称] like '%科技%'`|同上 |
|`fact.[企业名称] like '湖北*'`|匹配企业名称`湖北`开头|
|`fact.[企业名称] like '湖北%'`|同上|
|`fact.[企业名称] like '*有限??公司'`|匹配企业名称结尾是`有限某某公司`|
|`fact.[企业名称] like '*有限__公司'`|同上|
### 通配符与转义符{#generic-escape}
需要查找的数据中含有通配符时，必须使用转义符，才能使查找的通配符具有意义，like默认使用`\`转义，需要特别注意的是，字符串常量也是用`\`转义，所以在表达式中输入常量的通配符需要使用两个转义符。
|条件|说明|
|--|--|
|`fact.[企业名称] like '\\*\\*\\**'`|匹配企业名称`***`开头|
|`fact.[企业名称] like '*\\%*'`|匹配企业名称包含`%`|
|`fact.[企业名称] like '%\\%%'`|同上|
|`fact.[企业名称] like '*\\\\*'`|匹配企业名称包含`\`|
### 逻辑匹配{#logic-match}
在使用`CONTAINS`（包含）关系的条件时，系统支持使用字符串逻辑匹配生成条件，使用`空格`、`AND`或`&`表示逻辑与，用`OR`或`|`表示逻辑或，具体请参考[操作符-数据项分隔符](./operators.md#delimiter)。
如可以使用`fact.[企业名称] CONTAINS '加油站|成品油'`查询企业名称里包含`加油站`或`成品油`的企业，系统会自动将查询条件翻译为`fact.[企业名称] like '*加油站*' or fact.[企业名称] like '*成品油*'`。
在以下几种场景支持使用字符串逻辑匹配：
1. 在输入表达式过滤条件时，如`fact.[企业名称] CONTAINS '加油站|成品油'`
2. 在字段筛选组件中，TODO，link下文档
3. 在其它条件输入组件中，如在参数栏中放一个输入框input1，使用包含方式匹配输入框绑定的条件字段，此时可以直接在输入框中输入逻辑匹配条件，如`武汉 AND 加油站`
更多示例如下：
| 条件 | 说明 |
| -- |---- |
| `CONTAINS '武汉 责任'` | 表示包含`武汉`和`责任`，和`CONTAINS '武汉 AND 责任'`等价 |
| `CONTAINS '武汉 半导体|上海'` | 表示包含`武汉`和`半导体`，或包含`上海` |
| `CONTAINS '武汉 (半导体|投资)'` | 表示包含`武汉`，且含`半导体`或`投资` |
| `CONTAINS '武汉 "半导体(含芯片)"'` | 表示包含`武汉`和`半导体(含芯片)`，其中括号是要包含的字符中的普通字符 |
| `CONTAINS '武汉 "\"半导体\""'` | 表示包含`武汉`和`"半导体"`，其中双引号是要包含的字符中的普通字符 |
| `CONTAINS ARR('武汉&半导体','上海&投资')` | 表示包含`武汉`和`半导体`或包含`上海`和`投资` |
- `"`扩起来的内容，会当一个完整的搜索块使用
- `"`括起的内容里面有`"`时，用`\`转义
### 维项匹配{#dimension-match}
数据库中多数的维都有层次关系，比如像产品、地区等，可以通过[操作符-数据项分隔符](./operators.md#delimiter)中支持的分隔符来表示多个维项值，同时可以根据操作符左侧是字段还是层次还表示是否包含下级维项，参考[逻辑运算符](./operators.md#logic)警告提示框的描述说明。
示例：
| 条件 | 示例 |
|--|--|
|`fact.[区划代码]='420000'`|420000代码表示湖北省，表示包含`湖北省(不包含下级)`的数据|
|`fact.[区划代码].[省市县层次]='420000'`|420000代码表示湖北省，表示包含`湖北省(包含下级)`的数据|
|`fact.[区划代码]='420000,430000'`|支持多选，430000表示湖南省，表示包含`湖北省(不包含下级)和湖南省(不包含下级)`的数据|
|`fact.[区划代码].[省市县层次]='420000,430000'`|支持多选，430000表示湖南省，表示包含`湖北省(包含下级)和湖南省(包含下级)`的数据|
|`fact.[区划代码] BELONG '420000,430000'`|等价于`fact.[区划代码].[默认层次]='420000,430000'`，支持多选，430000表示湖南省，表示包含`湖北省(包含下级)和湖南省(包含下级)`的数据|
|`fact.[区划代码]="420000|430000"`|同上|
|`fact.[标签]="A001&A002"`|标签为A001和A002同时满足。表示and关系的两个值条件，多用于标签条件。|
|`fact.[区划代码]!='420000'`|表示不包含`湖北省(不包含下级)`的数据|
|`fact.[区划代码].[省市县层次]!='420000'`|表示不包含`湖北省(包含下级)`的数据，等价于`fact.[区划代码] NOT BELONG '420000'` |
|`fact.[区划代码]!='420000,430000'`|表示不包含`湖北省(不包含下级)和湖南省(不包含下级)`的数据|
## 日期{#date}
### 相对日期匹配{#relative}
当需要按照某个锚点日期偏移指定时间间隔过滤时，需要使用相对日期来匹配过滤数据。系统中使用`锚点日期关键字+偏移量`的字符串来表示相对日期。
系统中约定的锚点日期关键字有如下几种：
| 类型 | 说明 |
| --- | --- |
| today | 今天，对于一些特殊的数据期类型，如季度，today可以表示当期 |
| now | 现在，当前时刻，含有当前日期和时分秒信息，是一个时间戳。now也可以用于和日期或年月进行比较，表示当天、当月或当年 |
| current | 本期、本月、本季， 根据当前数据期类型的不同，current表示它的当前一期，如果是退化日期维，那么也就是维中设置当期值，如果当前是日期类型，那么等价于today |
| firstPeriod | 首期，往往表示当年的第一期，根据当前数据期类型的不同，如年季，表示当年第一季度 |
| lastPeriod | 最后一期，往往表示当年的最后一期，根据当前数据期类型的不同，如年季，表示当年第四季度 |
| week1 | 本周第一天，等价于monday |
| monday | 本周第一天，等价于week1 |
| weekend | 本周最后一天 |
| day1 | 本月第一天 |
| lastDay | 本月最后一天 |
| lastWorkday | 上一个工作日 |
| firstDayOfYear | 本年第一天 |
| lastDayOfYear | 本年最后一天 |
系统中约定的偏移时间间隔类型有如下几种：
| 类型 | 说明 |
| --- | --- |
| y | 年 |
| q | 季 |
| m | 月 |
| w | 周 |
| d | 天 |
| wd | 工作日 |
| ym | 月，忽略年份 |
| yd | 天，忽略年份 |
| md | 天，忽略月份 |
示例：
|条件|说明|
|--|--|
|`fact.[上映日期]='today'`|表示日期为`今天`的数据|
|`fact.[上映日期]='-1d'`|表示日期为`昨天`的数据|
|`fact.[上映日期]='+1d'`|表示日期为`明天`的数据|
|`fact.[上映日期]='week1'`|表示日期为`本周1`的数据|
|`fact.[上映日期]='week1-7d'`|表示日期为`上周1`的数据|
|`fact.[上映日期]='day1-1d'`|表示日期为`上月最后1天`的数据|
|`fact.[上映日期]='-1m'`|表示日期为`上月的今天`的数据|
|`fact.[上映日期]='firstDayOfYear'`|表示日期为`今年第1天`的数据|
|`fact.[上映日期]='lastDayOfYear'`|表示日期为`今年最后1天`的数据|
|`fact.[上映日期]='week1'`|表示日期为`本周1`的数据|
|`fact.[上映日期]='-1w'`|表示日期为`上周的今天`的数据|
|`fact.[上映日期]='-1q'`|表示日期为`上季的今天`的数据|
### 日期范围匹配{#date-match}
当需要查找某个日期范围内的数据时，需要使用日期范围匹配来查询所期望的数据。
示例：
|条件|说明|
|--|--|
|`fact.[上映日期].[年]='[2019~2020]'`|表示日期为`[20190101~20200101]`之间的数据|
|`fact.[上映日期].[年]='[2019~]'`|表示日期为`20190101及以后`的数据，等价于`>=20190101`|
|`fact.[上映日期].[年]='[~2020]'`|表示日期为`20200101及以前`的数据，等价于`<=20200101`|
|`fact.[上映日期].[年月]='[201901~202008]'`|表示日期为`[20190101~20200801]`的数据|
|`fact.[上映日期].[年月]='[201902~]'`|表示日期为`20190201及以后`的数据，等价于`>=20190201`|
|`fact.[上映日期].[年月]='[~202008]'`|表示日期为`20200801及以前`的数据，等价于`<=20200801`|
|`fact.[上映日期].[年月日]='[20190101~20190701]'`|表示日期为`[20190101~20190701]`之间的数据|
|`fact.[上映日期].[年月日]='[20190101~]'`|表示日期`20190101及以后`的数据，等价于 `>='20190101'`|
|`fact.[上映日期].[年月日]='[~20190701]'`|表示日期`20190701及以前`的数据，等价于 `<='20190701'`|
|`fact.[上映日期].[日期]='[20190101 08:30:00~20190701 09:00:00]'`|表示日期为`[20190101 08:30:00~20190701 09:00:00]`之间的数据，时间使用24小时制|
|`fact.[上映日期]='[09:00:00~12:30:00]'`|表示`每天9:00到12:30`的数据，时间使用24小时制|
|`fact.[上映日期]='[21:00:00~03:30:00]'`|表示`每天21:00到次日凌晨03:30`的数据|
|`fact.[上映日期]='[21:00:00~21:00:00]'`|表示`每天21:00这一时刻`的数据|
|`fact.[上映日期].[年]='['+adddate(year(today()),-3,'y')+'~'+year(today())+']'`|动态区间，表示最近三年|
|`fact.[上映日期]='week1-2w~weekend'`|表示日期为`前三周`的数据|
|`fact.[上映日期]='day1-1m~day1-1d'`|表示日期为`上个月的第1天到上个月的最后1天`的数据|
### 自适应粒度匹配{#adaptive}
当字段是日期型、时间戳型或者具有日期角色时，能根据传递的值自适应粒度匹配。
示例：
|条件|说明|
|--|--|
|`fact.[上映日期]='[2019~2020]'`|右侧区间范围值是4位，自适应粒度为`年`，左侧字段等价于`[上映日期].[年]`，表示`[上映日期].[年]='[2019~2020]'`|
|`fact.[上映日期]='2019'`|右侧值是4位，自适应粒度为`年`，左侧字段等价于`[上映日期].[年]`，表示`[上映日期].[年]='2019'`|
|`fact.[上映日期]='2019,2020'`|右侧是多值，每个值都是4位，自适应粒度为`年`，左侧字段等价于`[上映日期].[年]`，表示`[上映日期].[年]='2019,2020'`|
|`fact.[上映日期]='[201901~202001]'`|右侧区间范围值是6位，自适应粒度为`年月`，左侧字段等价于`[上映日期].[年月]`，表示`[上映日期].[年月]='[201901~202001]'`|
|`fact.[上映日期]='201901'`|右侧值是6位，自适应粒度为`年月`，左侧字段等价于`[上映日期].[年月]`，表示`[上映日期].[年月]='201901'`|
|`fact.[上映日期].[年月]='20190801'`|细粒度值自适应粗粒度字段，左侧字段是年月，右侧是日期，右侧细粒度的值自适应粒度为`年月`，等价于`fact.[上映日期].[年月]='201908'`|
|`fact.[上映日期]='201901,202001'`|右侧是多值，每个值是6位，自适应粒度为`年月`，左侧字段等价于`[上映日期].[年月]`，表示`[上映日期].[年月]='201901,202001'`|
|`fact.[创建时间]='[20190102~20200301]'`|右侧区间范围值是8位，自适应粒度为`年月日`，左侧字段等价于`[创建时间].[日期]`，表示`[创建时间].[日期]='[20190102~20200301]'`|
|`fact.[创建时间]='20190102'`|右侧值是8位，自适应粒度为`年月日`，左侧字段等价于`[创建时间].[日期]`，表示`[创建时间].[日期]='20190102'`|
|`fact.[创建时间]='20190102,20200101'`|右侧是多值，每个值是8位，自适应粒度为`年月日`，左侧字段等价于`[创建时间].[日期]`，表示`[创建时间].[日期]='20190102,20200101'`|
|`fact.[上映日期]='2019,202001'`|右侧是不同粒度的多值，第一个值是4位，自适应粒度为`年`；第二个值是6位，自适应粒度为`年月`，表示`[上映日期].[年]='2019' OR [上映日期].[年月]='202001'`|
|`fact.[上映日期].[年]='20190928,202001'`|右侧是不同粗粒度的多值，都自适应粒度为`年`，表示`[上映日期].[年]='2019' OR [上映日期].[年]='2020'`|
|`fact.[上映年月]='2019,202001,20180818'`|右侧是不同粒度的多值，既有粗粒度，也有细粒度的值，自适应粒度后表示为`fact.[上映年月].[年]='2019' OR fact.[上映年月]='202001' OR fact.[上映年月]=='201808'`|
|`fact.[上映日期].[年月]='week1-2w~weekend'`|按照相对日期计算出来的日期范围进行粒度自适应|
|`fact.[上映日期].[年月]='day1-1m~day1-1d'`|按照相对日期计算出来的日期范围进行粒度自适应|
::: tip
日期自适应粒度可以双向自适应：
1、粗粒度值自适应细粒度字段，取细粒度字段相同粒度的维属性过滤，比如：`[上映日期]='201802'`自适应为`fact.[上映年月].[年月]='201802'`
2、细粒度值自适应粗粒度字段，将细粒度值截断，比如：`[上映日期].[年月]='20180210'`自适应为`[上映日期].[年月]='201802'`
:::
## 布尔{#boolean}
布尔值有两个值：真和假，值为真用`true`，值为假用`false`。也可以使用其他数据类型进行布尔值的转换，如下所示：
|数据类型|转换结果|
|--|--|
|`任何非零数字`|`true`|
|`0`|`false`|
|`任何非空字符串`|`true`|
|`""(空字符串)`|`false`|
示例：
|条件|示例|
|--|--|
|`if($XSSL,fact.[销售数量]>$XSSL,true)`|表示`销售数量为参数中的销售数量时，输出大于该参数的销售数量，否则输出全部销售数量`|
|`if(fact.[销售数量] IS NOT NULL,[销售数量],0)`|表示`销售数量不为空时，输出为销售数量的数据，否则输出0`|
## JSON{#json}
表达式支持JSON（JavaScript Object Notation）数据类型，其规范与JavaScript一致，JSON中可能也包括数组，比如JSON中某些key的值可以是数组，但数组也会作为一个独立的数据类型在[数组](#array)中描述。
系统支持了一系列的JSON表达式函数用于提供操作JSON数据的能力，如[JSON\_OBJECT](./func/json/JSON_OBJECT.md)、[JSON\_GET](./func/json/JSON_GET.md)、[JSON\_SET](./func/json/JSON_SET.md)等等，其中有些函数是适用于数组的，数组函数也是以JSON开头的。在前端浏览器中的表达式计算、后端Java段的表达式函数计算和SQL中均可使用这些JSON函数，但受限于数据库本身的JSON支持能力，部分JSON函数可能在某些数据库无法使用。
## JsonPath{#jsonpath}
JsonPath是一种描述JSON内部的特定位置的数据的语法，由于JSON是一个结构可以任意复杂的对象，当希望获取或更新JSON中的某个位置的数据时通过JsonPath可以很好的进行表达，以下面的JSON为示例：
```json
{
"store": {
"book": [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fiction",
"author": "J.R.R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
},
"expensive": 10
}
```
示例语法（表达式中以json\_data代表上面的示例数据）：
| 表达式 | 结果 |
| --- | --- |
| `JSON_GET(json_data,'expensive')` | `10` |
| `JSON_GET(json_data,'$.expensive')` | `10` |
| `JSON_GET(json_data,'$.store[1].category')` | `reference` |
| `JSON_GET(json_data,'$.store[*].author')` | `["Nigel Rees","Herman Melville","J.R.R. Tolkien"]` |
更多示例请参考：[JsonPath](https://github.com/json-path/JsonPath)
在表达式中可以通过JSON路径语法来表示JSON路径，语法和示例参考：[JsonPath](https://github.com/json-path/JsonPath)，以下是支持的操作符：
| 操作符 | 描述 |
| --- | --- |
| `$` | 数组、JSON的根元素 |
| `.property` | 选择父对象中的指定属性，此时父对象必须是JSON |
| `[n]` | 从数组中选择第 n 个元素。索引从1开始。 |
| `[index1,index2,…]` | 选择具有指定索引的数组元素 |
| `[start:end]`、`[start:]` | 从起始索引到结束索引（但不包括结束索引）选择数组元素。如果省略 end，则选择从开始到数组末尾的所有元素。 |
| `[:n]` | 数组的前 n 个元素 |
| `[-n:]` | 选择数组的最后 n 个元素 |
| `*` | 通配符选择JSON或数组中的所有元素 |
| `@` | 当前元素的值 |
| `@#` | 当前元素的序号，0开始 |
::: tip 提示
1、JsonPath的语法规则同样适用于数组、嵌套JSON数组。
2、产品中的路径同时还兼容直接传递数组下标和JSON的KEY。路径是数值表示数组索引下标，是`$`开头字符表示JsonPath的路径，非`$`开头的字符，则表示是json的key，如果json的key也是以`$`开头，则使用`\$`转义。
:::
## 数组{#array}
数组可以是普通的一维数组、二维数组以及嵌套JSON的数组等，上面的JsonPath语法同样适用于获取数组元素。
示例数据：
```json
[
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fiction",
"author": "J.R.R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
]
```
示例语法（表达式中以json\_data代表上面的示例数据）：
| 表达式 | 结果 |
| --- | --- |
| `JSON_GET(json_data, 1)` | `{"category": "reference","author": "Nigel Rees","title": "Sayings of the Century","price": 8.95}` |
| `JSON_GET(json_data, '$[1]')` | `{"category": "reference","author": "Nigel Rees","title": "Sayings of the Century","price": 8.95}` |
| `JSON_GET(json_data, '$[2].author')` | `Herman Melville` |
## NULL值{#null}
表达式中是存在null值的，`null`表示null值、未填写数据的字段和输入框的值也是null，在表达式中null参与的运算规范，不同于sql、也不同于excel，在数据库中null参与的任何运算返回的都是null、文本字段中存储null和空字符串也不同，而在excel中没有null的概念，单元格没填写内容就认为是空。
在表达式中null参与的运算有一些特殊的规则，我们希望在大多数情况下使用者不需要特殊处理null，但有些极端情况下可能还是需要识别是不是null的，比如我们的表达式中就有`isnull`这个运算符，这可以让系统在翻译对应的SQL语句时自动产生条件`字段 is null`或`字段=''`，另外由于null在db中参与任何四则运算都是返回null，比如`null+1`返回null，但其实更希望它返回1，系统会在产生SQL的时候自动应对这些情况，多数情况下都能做到符合用户的预期，在少数情况下，用户也能通过写入一些特定的规则的表达式语法或其他方式能做到一些特殊的计算规则。
在表达式中规则如下：
1. null当字符串使用时等价于空字符串，如`null=''`返回true，`null+'abc'`返回'abc'，`字段=''`在翻译SQL时为`字段 is null`。
2. `==`、`is null`和`is not null`是用于严格对待null的判断，不同于其他操作符，如 `'' is null`返回false，`null==''`返回false，`''=null`还是返回true。
3. \=、!=、>、>=、<、<=、in、like、contains等比较运算符，如果是和字符串进行比较，null和''等价，null和null用=比较是相等的，其他操作数（不管是否null）和null比较的都返回false。
4. null在四则运算中，包括加减乘除、AVG、SUM等，如果操作数都是null，那么返回null。
5. null在加法中（包括SUM）被忽略，如`null+1`返回1，`null+null`返回null，`字段+1`在翻译SQL时会翻译为`ifnull(字段,0)+1`。
6. null在减法中当0处理，如`null-1`返回-1，`null-null`返回null，`字段-1`在翻译SQL时为`字段-1`。
7. 在乘法、除法中，如果有一个操作数为null，那么结果为null
8. null当作布尔值时是false，`null&true`返回false，`!null`返回true，`if(null,1,2)`返回2，`null=false`返回true，`null==false`返回false。
在系统产生的SQL中，除了符合上面的表达式计算规则外，还有如下规则：
1. 不管底层数据库字段存储是否支持区分对待null和空串，系统在提交数据到DB时，''会转化为null，也就是说不会往字符串字段中写入空串。
2. 在查询时，如果用户过滤条件写`字段=''`，那么翻译为SQL时为`字段 is null`，考虑到性能和SQL简洁性，系统不会自动加上`or 字段=''`，如果用户的db中存在历史数据有区分对待null和''，那么用户需要显式的写条件`字段==''`才能做严格的空串比较
3. 字段作!=、<>、>、<等比较时，如果是和字符串比较，那么按上面表达式的规则null等价于''，其他情况，如果比较数是null，那么非null值大于null、非null也不等于null，如果比较数不是null，那么直接比较即可。
4. 万一用户不希望系统在翻译SQL时自动处理null的问题，比如希望`字段+null`时，就严格按字面翻译SQL，那么可以使用`RAW_SQL`系列函数。
5. null值不参与SQL的count统计计数，这个和SQL一致。
---
url: "https://docs.succapp.com/v5/guide/exp/display-format.md"
htmlUrl: "https://docs.succapp.com/v5/exp/display-format"
title: "显示格式"
---
---
order: 2.5
navTitle: 显示格式
---
# 显示格式
**显示格式**用于控制不同类型数据（包括数字、日期等）的格式化显示，通过设置合适的显示格式可以使页面的数据更加清晰易懂。产品支持页面级别、应用级别、项目级别和系统全局的设置，详细内容参考文档[显示格式](../project-manage/display-format.md)。本文将重点解析显示格式的语法规范，包括[数字](#number)、[日期](#data)、[时间](#data)等的语法规范与语法示例。
## 数字{#number}
### 语法规范{#number-grammar}
| 代码 | 含义 |
| ---- | ---- |
| 0 | 如果数字的位数少于格式中的0会补0，如显示格式设置为00.00，原值是8.9时，显示值为08.90 |
| # | 如果数字在小数的两侧位数少于格式中的#符号时，不会补0 |
| ? | 如果数字的位数少于格式中的?会补空格，以便小数点在列中对齐 |
| , | 千位分隔符：逗号（,）。在数字中每隔三位插入一个分隔符，以便快速识别数字的位数和数量级 |
| e或E | 科学计数法，如：E-、E+、e-、e+ |
| \[DBNum1] | 中文小写数字 |
| \[DBNum2] | 中文大写数字 |
| ！ | 表示其后的是一个字符，和千位分隔符等结合使用可以实现万元的效果 |
| rmb | 格式化人民币（大写）,SuccBI特有的，等价于`金山文档：[dbnum1][$RMB]`,`Excel：[>0][dbnum2]G/通用格式元;;;` |
| 正数;负数;0;字符串 | 由`;`隔开，从左至右依次表示正数、负数、0、字符串的显示格式 |
### 语法示例{#number-example}
| 格式代码 | 含义 | 原值 | 显示结果 |
| ---- | ---- | ---- | ---- |
| 00.00 | 如果数字的位数少于格式中的0会补0 | 8.9 | 08.90 |
| #.## | 如果数字在小数的两侧位数少于格式中的#符号时，不会补0 | 8.9 | 8.9 |
| ??.?? | 如果数字的位数少于格式中的?会补空格 | 8.9 | `(空格)8.9(空格)` |
| #, | 单位换算，实际值为12000，显示为12 | 12000 | 12 |
| #,###, | 单位换算，实际值为1000，显示为1 | 1000 | 1 |
| #,## | 千位分隔符 | 1000 | 1,000 |
| #,### | 千位分隔符 | 12000 | 12,000 |
| 0.000 | 三位小数 | 1000.12 | 1000.120 |
| #,##0.000 | 千位分隔符且保留3位小数 | 1000.12 | 1,000.120 |
| ####.# | 四舍五入保留一位小数 | 1234.59 | 1234.6 |
| #.000 | 显示三位小数 | 8.9 | 8.900 |
| 0.# | 四舍五入保留一位小数 | .631 | 0.6 |
| 0.0,, | 单位换算，实际值为12200000，显示为12.2 | 12200000 | 12.2 |
| 0.000% | 百分比保留3位小数 | 10.12% | 10.120% |
| 0% | 百分比不保留小数位 | 10.12% | 10% |
| 0.00E+00 | 科学计数法，如：E-、E+、e-、e+ | 12,200,000 | 1.22E+07 |
| 0.00E-00 | 科学计数法，如：E-、E+、e-、e+ | 12,200,000 | 1.22E07 |
| #0.0E+0 | 科学计数法，如：E-、E+、e-、e+ | 12,200,000 | 1.2E+7 |
| \[DBNum1] | 中文小写数字 | 1000.12 | 一千.一二 |
| \[DBNum2] | 中文大写数字 | 1000.12 | 壹仟.壹贰 |
| 0.00"元" | 数值末尾加单位，如加“元” | 1000.12 | 1000.12元 |
| $@"美元" | 数值末尾加单位，如加“美元” | 2300 | $2300美元 |
| #,###,0.00,"千元" | 单位换算为千且保留两位小数，实际值为1000，显示1.00千元 | 1000 | 1.00千元 |
| 0!.0,"万元" | 单位换算为万元，实际值为11000，显示为1.1万元 | 11000 | 1.1万元 |
| 0!.00,,"亿元" | 单位换算为亿元且保留两位小数，实际值为110000000，显示为1.10亿元 | 110000000 | 1.10亿元 |
| 0.00!"元\\" | 输出双引号" | 1000.12 | 1000.12"元" |
| rmb | 格式化人民币（大写）,SuccBI特有的,`金山文档：[dbnum1][$RMB]`,`Excel：[>0][dbnum2]G/通用格式元;;;` | 1234.56 | 壹仟贰佰叁拾肆元伍角陆分 |
| 0.00;-0.00;# | 0显示为空，数值显示值保留两位小数，如实际值为0，显示值为空；实际值为-1.1，显示值为-1.10；实际值为2.2233，实际值为2.22 | -1.1 | -1.10 |
| 0.00;-0.00;0;"0" | 0和字符串（包括空）都显示为0，数值显示值保留两位小数，如实际值为空，显示值为0；实际值为0，显示值为0；实际值为`abc`，显示值为0；实际值为2.2233，实际值为2.22 | （空） | 0 |
## 日期{#data}
### 语法规范{#date-grammar}
| 代码 | 含义 |
| ---- | ---- |
| yyyy | 将年显示为四位数字 |
| yy | 将年显示为两位数字 |
| q | 将日期显示为季度 |
| m | 将月显示为不带前导零的数字 |
| d | 将日显示为不带前导零的数字 |
| dd | 根据需要将日显示为带前导零的数字 |
| ddd | 将日显示为缩写形式（Sun 到 Sat） |
| dddd | 将日显示为完整名称（Sunday 到 Saturday） |
### 语法示例{#date-example}
| 格式代码 | 含义 | 原值 | 显示结果 |
| ---- | ---- | ---- | ---- |
| yyyy/mm/dd | 日期 | 19700101 | 1970/01/01 |
| yyyy年q季度 | 年份与季度 | 19700101 | 1970年1季度 |
| ddd | 星期缩写 | 19700101 | Thu |
| dddd | 星期 | 19700101 | Thursday |
## 时间{#time}
### 语法规范{#time-grammar}
| 代码 | 含义 |
| ---- | ---- |
| h | 将小时显示为不带前导零的数字 |
| hh | 根据需要将小时显示为带前导零的数字。如果格式包含AM或PM，则时间采用12小时制。否则，时间将采用24小时制 |
| m | 将分钟显示为不带前导零的数字。注意:m或mm代码必须紧跟在h或hh代码之后，或后面紧接ss代码；否则，Excel将显示月份而不是分钟数。 |
| mm | 根据需要将分钟显示为带前导零的数字 |
| s | 将秒显示为不带前导零的数字 |
| ss | 根据需要将秒显示为带前导零的数字 |
| AM/PM | 使用 12 小时制显示小时 |
| am/pm | 使用 12 小时制显示小时 |
| 000 | 秒的小数位，Excel只能精确到毫秒，有的数据库可以到微秒 |
### 语法示例{#time-example}
| 格式代码 | 含义 | 原值 | 显示结果 |
| ---- | ---- | ---- | ---- |
| yyyy/mm/dd hh:mm:ss | 日期 | now() | 2025/08/18 14:47:56 |
| `h:m:s` | 获取时分秒，无需补0 | 09:03:06 | 9:3:6 |
| hh:mm:ss | 获取时分秒，每个部分用两位数字显示，不足两位时在前面补0 | 09:03:06 | 09:03:06 |
| hh:mm:ss AM/PM | 使用 12 小时制显示小时 | 13:03:33 | 01:03:33 PM |
| hh:mm:ss am/pm | 使用 12 小时制显示小时 | 13:03:33 | 01:03:33 PM |
| hh:mm:ss.000 | 显示时刻，精确到毫秒 | now() | 14:47:56.845 |
## 转义{#escape}
### 语法规范{#escape-grammar}
| 代码 | 含义 |
| ---- | ---- |
| "字符" | 双引号内的字符原样显示，如设置显示格式为"#\n"#,###，原值是1000时，显示值为#\n1,000 |
| \单个字符 | \右侧单个字符原样显示，如设置显示格式为`\#\\n#,###`，原值是1000，显示值为#\n1,000 |
### 语法示例{#escape-example}
| 格式代码 | 含义 | 原值 | 显示结果 |
| ---- | ---- | ---- | ---- |
| "#\n"#,### | 使用千分符隔开数字并在开头加#\n | 1000 | #\n1,000 |
| `\#\\n#,###` | 使用千分符隔开数字并在开头加#\n | 1000 | #\n1,000 |
| `\"@\"` | 单元格内容的开头和结尾分别加上`"` | HelloWorld! | "HelloWorld!" |
## 维项{#dimension}
### 语法规范{#dimension-grammar}
| 格式代码 | 含义 |
| --- | --- |
| @ | 当前值 |
| @txt | 维文本 |
| @ @txt | 原值 维文本 |
### 语法示例{#dimension-example}
| 格式代码 | 含义 | 原值 | 显示结果 |
| ---- | ---- | ---- | ---- |
| @(@txt) | 原值(维文本)，如展示行政区划代码字段，该字段关联行政区划维表，维表主键设置文字字段为行政区划名称，则显示内容为行政区划代码(行政区划名称) | 420000 | 420000(湖北省) |
## 使用场景{#usage-scenario}
产品里针对不同的数据类型内置了一些常见的显示格式供直接选择使用，也可以根据需求添加自定义显示格式。同时，显示格式语法也用于[TOSTR函数](./func/transform/TOSTR.md)控制数据输出格式。以下是仪表板中添加和管理自定义显示格式的过程示例，在报表、Superpage中也是类似过程。
### 添加自定义格式{#custom}
点击**添加自定义格式**弹出新增显示格式对话框：
1. 格式编号：自定义该显示格式的格式编号
2. 格式名称：自定义该显示格式的格式名称
3. 格式：输入该显示格式的格式表达式
4. 预览：添加格式后可以预览格式效果
如图为添加显示格式**1位小数**：
### 管理自定义格式{#manage}
点击**管理自定义格式**弹出管理显示格式对话框：
**管理自定义格式**中有三个属性：
1. 新增：新增显示格式
2. 修改：修改已有的显示格式
3. 删除：删除已存在的显示格式
---
url: "https://docs.succapp.com/v5/guide/exp/component-properties.md"
htmlUrl: "https://docs.succapp.com/v5/exp/component-properties"
title: "组件表达式变量{#component-properties}"
---
---
order: 3
navTitle: 组件属性
---
# 组件表达式变量{#component-properties}
本文列出组件和单元格类型在表达式中可读取的变量。表达式编辑器中通常显示中文名称。
## 使用方式{#usage}
在表达式中引用组件变量时，先选择组件，再选择变量。例如“姓名”输入框的“值”变量可写成：
```text
[姓名].[值]
```
不同组件可读取的变量不同。通用变量来自组件能力，特殊变量来自组件自己的属性配置。
## 组件变量{#component-vars}
### 表格{#component-group-table}
本组组件：交叉表（`crossTable`）、分组表（`groupTable`）、明细表（`columnTable`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 地图{#component-group-map}
本组组件：2D地图（`gisMap2D`）、3D地图（`gisMap3D`）、百度地图（`gisMapBmap`）、高德地图（`gisMapAmap`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 文本{#component-group-text}
本组组件：富文本（`richtext`）、文本（`text`）、标题（`title`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 装饰{#component-group-decoration}
本组组件：背景块（`backgroundBlock`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 容器{#component-group-container}
本组组件：分隔面板（`splitPanel`）、多页面板（`panelBook`）、对话框（`dialog`）、折叠面板（`collapsePanel`）、抽屉（`drawer`）、浮动面板（`datasetFloatPanel`）、浮动面板（`queryFloatPanel`）、网页段落栏（`section`）、面板（`panel`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。
**以下组件不支持：**
~~对话框（`dialog`）~~
~~抽屉（`drawer`）~~ |
### 输入{#component-group-input}
本组组件：列表上传（`listUpload`）、列表选择（`selector`）、勾选框（`checkbox`）、勾选框组（`checkboxGroup`）、卡片上传（`cardUpload`）、多行输入（`multipleInput`）、字段过滤（`fieldsFilter`）、密码输入（`passwordInput`）、富文本输入（`richtextInput`）、引用表（`datasources`）、快速搜索（`searchbox`）、搜索框（`searchInput`）、数值输入（`numberInput`）、文本输入（`input`）、日期选择（`dateSelector`）、时间选择（`timeSelector`）、条件指示器（`filtersViewer`）、树形选择（`treeSelector`）、签名（`signInput`）、表达式输入（`expInput`）、资源选择（`resSelector`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$value` | 值 | |
| `$txt` | 标题 | 同`$txt` |
| `$validate` | 校验 | 所有校验规则汇总后的结果，有一条校验规则不通过，校验结果为该校验规则计算结果。
**以下组件不支持：**
~~条件指示器（`filtersViewer`）~~ |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
| `$autoFilter` | 自动过滤的编译属性名 | **以下组件不支持：**
~~列表上传（`listUpload`）~~
~~卡片上传（`cardUpload`）~~
~~密码输入（`passwordInput`）~~
~~条件指示器（`filtersViewer`）~~
~~签名（`signInput`）~~
~~资源选择（`resSelector`）~~ |
| `$inputValue` | 输入值 | 输入组件处于输入状态下，用户手动输入的内容。
**仅以下组件支持：**
多行输入（`multipleInput`）
密码输入（`passwordInput`）
富文本输入（`richtextInput`）
数值输入（`numberInput`）
文本输入（`input`）
表达式输入（`expInput`） |
### 统计图{#component-group-chart}
本组组件：双向条形图（`pyramid`）、图标条形图（`hpictogramBar`）、图标柱状图（`pictogramBar`）、折线图（`line`）、散点图（`scatter`）、旭日图（`sunburst`）、条形图（`hbar`）、柱形图（`bar`）、桑基图（`sankey`）、玫瑰图（`rose`）、环形图（`ring`）、矩阵图（`treemap`）、组合图（`combo`）、词云图（`wordCloud`）、象形条形图（`hpictorialBar`）、象形柱形图（`pictorialBar`）、雷达图（`radar`）、面积图（`area`）、饼图（`pie`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 指标图{#component-group-measure}
本组组件：KPI（`kpi`）、仪表盘（`gauge`）、图标条（`iconBar`）、水位图（`waterPercent`）、进度条（`dataBar`）、进度环（`percentRing`）、里程表（`odometer`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 嵌入{#component-group-embed}
本组组件：Superpage（`embedSuperpage`）、仪表板（`embedDashboard`）、报表（`embedReport`）、数据模型（`embedDataModel`）、文档（`document`）、流程进度（`embedFlowProgress`）、程序流（`embedActionFlow`）、表单（`embedForm`）、表单应用（`embedFapp`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。
**以下组件不支持：**
~~程序流（`embedActionFlow`）~~ |
### 按钮{#component-group-button}
本组组件：图标按钮（`iconButton`）、按钮（`button`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 媒体{#component-group-media}
本组组件：图标（`icon`）、图片（`image`）、视频（`video`）、装饰图标（`decorativeIcon`）、音频（`audio`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 导航{#component-group-navigator}
本组组件：卡片标签页（`tabbarCard`）、按钮标签页（`tabbarButton`）、简洁分页栏（`paginationSimple`）、简约标签页（`tabbarSimple`）、菜单（`menu`）、阶梯分页栏（`paginationStep`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。
**以下组件不支持：**
~~菜单（`menu`）~~ |
| `$pagingStatus_targetComponent` | 分页状态 | 分页栏组件的分页状态系统属性，由系统自动生成并维护，记录分页栏所需的分页状态数据。其
值为包含 pageSize, pageNum, totalRowCount 的 JSON 对象。
件。
**仅以下组件支持：**
简洁分页栏（`paginationSimple`）
阶梯分页栏（`paginationStep`） |
### 开发{#component-group-develop}
本组组件：HTML（`html`）、JS组件（`jsComponent`）、网页（`webview`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 工具{#component-group-util}
本组组件：二维码（`qrcode`）、条形码（`barcode`）、计时器（`timer`）、选中分组（`selectionGroup`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。
**仅以下组件支持：**
二维码（`qrcode`）
条形码（`barcode`） |
| `$time` | 时间 | **仅以下组件支持：**
计时器（`timer`） |
| `$steps` | 触发次数 | **仅以下组件支持：**
计时器（`timer`） |
| `$seconds` | 秒 | **仅以下组件支持：**
计时器（`timer`） |
| `$active` | 激活状态 | **仅以下组件支持：**
计时器（`timer`） |
| `$value` | 值 | **仅以下组件支持：**
选中分组（`selectionGroup`） |
### 图层{#component-group-layer}
本组组件：区块图层（`districtLayer`）、图片图层（`imageLayer`）、底图图层（`amapBaseLayer`）、底图图层（`bmapBaseLayer`）、底图图层（`leafletBaseLayer`）、散点图层（`scatterLayer`）、标记图层（`markerLayer`）、棱柱图层（`prismLayer`）、气泡图层（`bubbleLayer`）、热力图层（`heatMapLayer`）、百度区块图层（`bmapDistrictLayer`）、百度散点图层（`bmapScatterLayer`）、百度热力图层（`bmapHeatmapLayer`）、百度特效点图层（`bmapEffectPointLayer`）、百度飞线图层（`bmapFlyLineLayer`）、飞线图层（`flyLineLayer`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 数据{#component-group-data}
本组组件：Excel列表（`excelList`）、树（`tree`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
### 其他组件{#component-group-other}
本组组件：categoryTree（`categoryTree`）、dataList（`dataList`）、dataPeriodList（`dataPeriodList`）、detailDataList（`detailDataList`）、leafOrgPeriodList（`leafOrgPeriodList`）、orgTree（`orgTree`）、页面（`fillForms`）。
本组组件可读取以下变量。多个组件共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
## 单元格类型变量{#celltype-vars}
### 单元格类型{#celltype-group-cell-type}
本组单元格类型：HTML（`html`）、列表上传（`listUpload`）、列表选择（`selector`）、勾选框（`checkbox`）、勾选框组（`checkboxGroup`）、卡片上传（`cardUpload`）、图片（`image`）、多行（`multipleInput`）、按钮组（`buttonGroup`）、数值（`numberInput`）、文本（`input`）、文本（`text`）、日期（`dateSelector`）、时间（`timeSelector`）、标签（`label`）、树形选择（`treeSelector`）、计算（`calculate`）、评分（`rating`）、进度（`progress`）、链接（`link`）。
本组单元格类型可读取以下变量。多个单元格类型共用同一个变量时，变量说明只写一次。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$sorts` | 组件排序条件 | 组件排序条件是运行时动态作用到查询上的排序条件，作用于组件定义的第一个查询。排序条件
格式为`组件ID 排序方式`，排序方式见`SortDirection`。
组件排序条件**会**覆盖数据集排序。
合法的排序条件：
- `col1 asc`，col1 是列子组件 ID
- `col1 desc`
- `col1 asc, col2 desc`，多个排序条目用逗号分隔
**使用场景**
- 列表的列头排序
- 分组表的列头排序
- 交叉表的行维度列头排序 |
| `$pageSize` | 每页行数 | 控制组件的分页大小。超出最大行数限制时会抛出异常。 |
| `$pageNum` | 当前页 | 控制组件的分页数。超出最大页数时，会返回空结果集。 |
| `$totalRowCount` | 总行数 | |
| `$pageRowCount` | 当前页行数 | 当前页的查询结果行数，如果不是最后一页，则返回`pageSize`，最后一页不满分页大小时，返回实
际行数。 |
| `$totalPageCount` | 总页数 | 该属性由`总行数 / 分页大小`计算得出。 |
| `$hasNextPage` | 是否有下一页 | 当前页码为最大页码时返回`false`。 |
| `$hasPreviousPage` | 是否有上一页 | 当前页码为0时返回`false`。 |
| `$value` | 值 | **以下组件不支持：**
~~图片（`image`）~~
~~按钮组（`buttonGroup`）~~
~~链接（`link`）~~ |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$visible` | 显示 | 1. 对可视化组件，表示组件是否是显示的，如按钮、菜单是否可见。
2. 对程序流节点，没有效果，总是true
3. 对于数据集字段，表示字段是否可查询数据，例如列权限限制了某些字段不能查看或提交，或者当
前用户在工作流的某个节点不能查看某些字段，有时候字段可以查看，但是不能提交，见
`$enable`。
4. 对于数据集，表示是否可以查询数据，例如没有任何列权限，或者当前用户在工作流的某个节点不能
查看数据集的所有字段。 |
| `$txt` | 标题 | 同`$txt`
**以下组件不支持：**
~~HTML（`html`）~~
~~图片（`image`）~~
~~按钮组（`buttonGroup`）~~
~~链接（`link`）~~ |
| `$validate` | 校验 | 所有校验规则汇总后的结果，有一条校验规则不通过，校验结果为该校验规则计算结果。
**以下组件不支持：**
~~HTML（`html`）~~
~~图片（`image`）~~
~~按钮组（`buttonGroup`）~~
~~文本（`text`）~~
~~链接（`link`）~~ |
| `$autoFilter` | 自动过滤的编译属性名 | **以下组件不支持：**
~~HTML（`html`）~~
~~列表上传（`listUpload`）~~
~~卡片上传（`cardUpload`）~~
~~图片（`image`）~~
~~按钮组（`buttonGroup`）~~
~~文本（`text`）~~
~~链接（`link`）~~ |
| `$inputValue` | 输入值 | 输入组件处于输入状态下，用户手动输入的内容。
**仅以下组件支持：**
多行（`multipleInput`）
数值（`numberInput`）
文本（`input`） |
---
url: "https://docs.succapp.com/v5/guide/exp/aflnode-properties.md"
htmlUrl: "https://docs.succapp.com/v5/exp/aflnode-properties"
title: "程序流节点变量{#aflnode-properties}"
---
---
order: 4
navTitle: 程序流节点变量
---
# 程序流节点变量{#aflnode-properties}
本文列出程序流节点在表达式中可读取的变量。表达式编辑器中通常显示中文名称。
## 使用方式{#usage}
在程序流表达式中引用节点变量时，先选择节点，再选择变量。例如“HTTP请求”节点的“状态码”变量可写成：
```text
[HTTP请求].[状态码]
```
不同节点可读取的变量不同。通用变量来自程序流节点能力，特殊变量来自节点自己的属性配置。
## 通用节点变量{#common-vars}
所有程序流节点都可以读取以下通用变量。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$id` | 组件ID | 唯一标识一个组件，如程序流中的一个节点、页面中的一个可视化组件。
也用作数据行的下级变量，表示当前行的标识值。行标识值并非固定字段，而是根据
计算区域的查询类型动态推断：
- 分组查询：值为维度成员值，即分组字段的聚合键。
- 层次展开的明细查询：值为层次路径值，表示当前行在层次树中的位置。
- 纯明细查询：值为行主键值。
- 单行计算区域：无行标识，返回 undefined。 |
| `$name` | 名称 | 如输入组件的标题、字段的名称（不是物理字段名）、程序流节点的标题…… |
| `$type` | 类型 | 一个字符串，表示组件的类型。
如程序流节点的类型、可视化组件的类型…… |
| `$success` | 成功 | 一个布尔值，表示如程序流节点最后一次是否成功运行了。
为false表示没有运行或运行错误了 |
| `$errorCode` | 错误状态码 | 如果没有错误此属性为空，此属性默认等于`$error`的errCode子属性。 |
| `$errorMessage` | 错误信息 | 如果没有错误此属性为空，此属性默认等于`$error`的message子属性。 |
| `$error` | 错误对象 | 通过 `程序流节点.$error` 可以访问节点执行过程中发生的错误信息。
下级变量定义详见 `$error.md` 文档。
实现说明：
- 变量类：`ExpVar_$error`（实现 `IExpVar` 接口）
- 结果类：`$Error`（实现 `IExpressionAccessible` 接口）
- 变量接收基础对象`Error` |
| `$runCount` | 运行次数 | 一个整形，表示如程序流节点运行过几次，在循环中可能会有多次。 |
| `$startTime` | 开始时间 | 如果节点可能在循环中多次执行，那么表示最后一次执行的开始时间。 |
| `$elapsedTime` | 运行时长(ms) | 运行时长，单位毫秒。
如程序流节点运行耗费了多长时间。 |
| `$endTime` | 结束时间 | 如果节点可能在循环中多次执行，再开始执行时此属性会设置为0，执行完成后表示最后一次执行的结
束时间。 |
| `$outPort` | 出口 | 表示程序流节点执行过程中从哪个输出端口出去了。 |
## 文件{#aflnode-group-file}
### 读取文件元数据{#aflnode-read-file-meta-data}
类型值：`readFileMetaData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
| `$exists` | 是否存在 | 比如程序流节点“读取文件信息”，标识文件是否存在。 |
| `$files` | 子文件列表 | 读取文件元数据时，可能文件有子文件，可以通过此变量来获取子文件元数据信息，值是子文件
元数据数组 |
### 读取文件内容{#aflnode-read-file-content}
类型值：`readFileContent`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
## 输出{#aflnode-group-output}
### 脚本输出文件{#aflnode-action-script-output}
类型值：`actionScriptOutput`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
## 对话框{#aflnode-group-dialog}
### 显示确认对话框{#aflnode-show-confirm-dialog}
类型值：`showConfirmDialog`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
| `$confirmed` | 是否确认 | 确认对话框的属性，表示是否已确认。 |
## 数据{#aflnode-group-data}
### 删除数据{#aflnode-delete-data}
类型值：`deleteData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
### 复制数据{#aflnode-copy-data}
类型值：`copyData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
### 导入数据{#aflnode-import-data}
类型值：`importData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$file` | 交互上传文件 | 表示前端交互过程中直接上传得到的临时上传文件 ID，供后续服务端节点读取上传文件。 |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
### 执行SQL{#aflnode-execute-sql}
类型值：`executeSql`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
| `$resultJson` | 查询结果数据json | 1. 执行查询sql时是一个JSON数组对象，形如`[{"column1":"value1","column2":"value2"},...]`
2. 执行大模型对象时，如果设置了json返回格式，那么此变量可以获取以对应格式的json |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
### 插入数据{#aflnode-insert-data}
类型值：`insertData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
| `$generatedKey` | 自动设置的主键值 | 程序流插入节点生成的自增长主键变量值 |
### 更新数据{#aflnode-update-data}
类型值：`updateData`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$affectedRowCount` | 影响数据行数 | 表示程序流节点执行过程中，影响的数据行数，如删除数据。 |
## 调用{#aflnode-group-invoke}
### HTTP请求{#aflnode-http-request}
类型值：`httpRequest`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
| `$headers` | 请求头 | 此变量代表http请求头部信息，数据格式为`J`，程序流httpRequest节点使用此变
量记录请求头部信息。 |
| `$statusCode` | 状态码 | 此变量代表http请求结果中的状态码，数据格式为`I`，程序流httpRequest节点使
用此变量记录请求结果状态码。 |
### 发起工作流{#aflnode-start-work-flow}
类型值：`startWorkFlow`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 工作流启动结果 | 工作流启动结果对象，当前只包含 `instance` 流程实例信息。任务列表等细节尚未作为节点变量暴露。 |
### 大模型对话{#aflnode-llm-chat}
类型值：`llmChat`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
| `$resultJson` | 查询结果数据json | 1. 执行查询sql时是一个JSON数组对象，形如`[{"column1":"value1","column2":"value2"},...]`
2. 执行大模型对象时，如果设置了json返回格式，那么此变量可以获取以对应格式的json |
### 执行前端脚本{#aflnode-execute-browser-script}
类型值：`executeBrowserScript`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
### 执行后端程序流{#aflnode-execute-action-flow}
类型值：`executeActionFlow`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
### 执行后端脚本{#aflnode-execute-action-script}
类型值：`executeActionScript`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
### 执行工作流{#aflnode-execute-work-flow}
类型值：`executeWorkFlow`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 工作流执行结果 | 工作流执行结果对象，当前只包含 `instance` 流程实例信息。任务列表等细节尚未作为节点变量暴露。 |
### 执行程序流组件{#aflnode-execute-embed-action-flow}
类型值：`executeEmbedActionFlow`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
## 组件{#aflnode-group-component-action}
### 弹出对话框{#aflnode-show-dialog}
类型值：`showDialog`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 对话框返回值 | 对话框关闭时返回的结果。常见为按钮 ID，例如 `ok`、`cancel`、`close`；页面目标
或自定义弹窗也可能返回业务数据，具体以弹窗配置和关闭动作返回值为准。 |
### 执行命令{#aflnode-execute-command}
类型值：`executeCommand`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
### 检查修改{#aflnode-check-save}
类型值：`checkSave`。
| 变量 | 名称 | 说明 |
| :--- | :--- | :--- |
| `$result` | 结果数据 | 表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
执行sql节点查询的结果集返回的是一个"Column Named"二维数组，可以通过数组函数访问。 |
---
url: "https://docs.succapp.com/v5/guide/exp/var/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/vars"
title: "系统变量"
---
---
order: 4
navTitle: 系统变量
indexTitle: 概述
---
# 系统变量
系统支持很多全局可用的变量，有些变量是几乎每个地方都能使用的，如[$user](./$user.md)，而有些只能在特定的场景下使用，如[$action](./$action.md)，所有的变量如下：
!!!children (guide/exp/var)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/var/$action.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$action"
title: "$action - 当前交互动作对象"
---
---
navTitle: $action
---
# $action - 当前交互动作对象
`$action`代表当前交互动作对象。
一个程序流的交互动作是一个可以在表达式中访问的对象，如更新数据、执行SQL、HTTP请求等，它们都可以有一些自己的属性，利用这些属性用户可以方便的获取交互动作执行的信息或结果，引用交互动作，可以通过它们的ID来引用，就像在页面中引用一个可视化组件那样，在当前交互动作内部（如其内部的条件分支的条件表达式中）可以通过`$action`代表当前交互动作自己，就像在组件内部可以通过`$self`引用组件自己一样。
::: tip 提示
`$action`专门用于访问当前交互动作对象，`$self`则专门用来访问可视化组件对象，在一个组件的事件交互动作列表中可以同时使用它们，比如一个按钮组件，它的交互动作列表中如果有一个执行SQL的动作，那么可以通过`$action`访问到“执行SQL”动作对象，然后可以通过`$self`访问到按钮组件对象。
:::
## 交互对象属性{#subvars}
通过`$action.xxxx`可以访问到当前动作的属性，不同的节点拥有不同的属性。
**通用属性**
- `$action.$id` - 交互动作的ID。
- `$action.$name` - 动作的名称，即用户在节点上输入的名称，可以是一个有一定业务意义的简短字符串。
- `$action.$desc` - 描述信息。
- `$action.$type` - 组件的类型。
- `$action.$enable` - 节点是否启用了。
- `$action.$success` - 成功状态，一个布尔值，表示如程序流节点最后一次是否成功运行了。
- `$action.$errorCode` - 错误状态码，如果没有错误此属性为空。
- `$action.$errorMessage` - 错误的描述，如果没有错误此属性为空。
- `$action.$error` - 流程中最后一次运行的错误，此属性是一个对象，可以通过下级属性访问更多信息，见[$error](./$error.md)，null表示没有错误。
- `$action.$runCount` - 运行次数，一个整形，表示如程序流节点运行过几次，在循环中可能会有多次。
- `$action.$startTime` - 节点的开始执行时间，如果节点可能在循环中多次执行，那么表示最后一次执行的开始时间。
- `$action.$elapsedTime` - 运行时长，单位毫秒，如程序流节点运行耗费了多长时间。
- `$action.$endTime` - 节点的执行结束时间，如果节点可能在循环中多次执行，再开始执行时此属性会设置为0，执行完成后表示最后一次执行的结束时间。
- `$action.$outPort` - 出口端，表示程序流节点执行过程中从哪个输出端口出去了。
**节点专用变量，不同的节点拥有不同的属性：**
- `$action.$confirmed` - 确认对话框的属性，表示是否已确认。
- `$action.$result` - 结果数据，表示某些节点的结果数据，例如执行SQL节点的查询结果、HTTP请求节点的响应数据等。
- `$action.$resultFile` - 结果文件，表示某些节点的结果文件，例如导出数据的导出文件。
- `$action.$httpResponse` - HTTP响应信息，如HTTP请求节点的响应信息。
- `$action.$downloadURL` - 交互执行结果文件下载地址，返回的URL是/开头的带有上下文路径的URL路径。
- `$action.$affectedRowCount` - 影响数据行数，表示程序流节点执行过程中，影响的数据行数，如删除数据。
- `$action.$totalDataCount` - 总行数，总行数是指总共要处理的数据行数，比如导入数据时的总行数。
- `$action.$successDataCount` - 成功的行数，如导入成功的行数、校验通过的行数。
- `$action.$failureDataCount` - 失败的行数，如校验失败的行数、导入失败的行数。
- ……
---
url: "https://docs.succapp.com/v5/guide/exp/var/$browser.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$browser"
title: "$browser - 当前浏览器环境"
---
---
navTitle: $browser
---
# $browser - 当前浏览器环境
`$browser`代表当前的浏览器环境，在前端页面和后端的表达式计算中都可以使用此变量，在后端使用时，表示当前发起请求的浏览器环境，如果当前是二次开发调用或者定时调用，那么此属性依然存在，但内部的下级属性都为空。
在表达式中可以通过`$browser.xxx`的形式来判断浏览器环境，有如下属性：
- `$browser.name` - 浏览器的名称，如`MSIE`、`Edge`、`Chrome`……，如果是未知的浏览器返回`Unknown`
- `$browser.version` - 浏览器版本，如：`92`
- `$browser.webkit` - 浏览器是否基于webkit内核，比如chrome浏览器中会返回true
- `$browser.os` - 操作系统，如`win10`、`macOS`
- `$browser.userAgent` - 浏览器的User-Agent字符串，如：`Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36`
- `$browser.mobile` - 是否在手机端或者平板中
- `$browser.phone` - 是否在手机端
- `$browser.mac` - 是否在PC端mac环境中
- `$browser.pad` - 是否在平板中
- `$browser.ios` - 是否在移动端ios系统中
- `$browser.android` - 是否在andriod环境中
- `$browser.edge` - 是否为微软edge浏览器
- `$browser.chrome` - 是否为chrome浏览器
- `$browser.safari` - 是否为safari浏览器
- `$browser.firefox` - 是否为火狐浏览器
- `$browser.opera` - 是否为opera浏览器
- `$browser.weixin` - 是否在微信浏览器中
- `$browser.wxwork` - 是否为企业微信
- `$browser.wxapp` - 是否为微信小程序
- `$browser.qqbrowser` - 是否为qq浏览器
- `$browser.qq` - 是否在qq中打开
- `$browser.tim` - 是否在TIM中打开
- `$browser.alipay` - 是否为支付宝浏览器
- `$browser.alipayapp` - 是否为支付宝小程序
- `$browser.locationHost` - 系统路径
---
url: "https://docs.succapp.com/v5/guide/exp/var/$components.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$components"
title: "$components - 当前页面所有组件的根对象"
---
---
navTitle: $components
---
# $components - 当前页面所有组件的根对象
`$components` 当前页面所有组件的根，当数据集的ID与组件ID重复时需要带上根来访问。
- `$components` - 页面组件的根
- `$components.text1` - 文本1组件
- `$components.text1.$value` - 文本1组件的值
---
url: "https://docs.succapp.com/v5/guide/exp/var/$datainf.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$datainf"
title: "$datainf - 表单数据状态信息"
---
---
navTitle: $datainf
---
# $datainf - 表单数据状态信息
`$datainf`代表表单的数据状态信息，在表达式中可以通过`$datainf.xxx`的形式获取表单的状态信息，有如下属性：
- `$datainf.isNewData` - 是否为新增的且还未提交的明细数据
- `$datainf.lastSubmitTime` - 获取最近一次上报的时间
- `$datainf.approved` - 获取表单数据审批状态，返回true,表示该数据已审批通过；返回false,表示该数据待审批或未审批通过
- `$datainf.locked` - 获取表单数据锁定状态，返回true,表示该数据已锁定；返回false,表示该数据未锁定
- `$datainf.lockUserId` - 获取锁定操作时的用户ID
- `$datainf.lockOrgId` - 获取锁定操作时的填报单位ID
- `$datainf.flowId` - 当前流程实例ID
- `$datainf.flowNodeId` - 当前流程节点ID
- `$datainf.flowNodeDesc` - 当前流程节点描述
---
url: "https://docs.succapp.com/v5/guide/exp/var/$datasets.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$datasets"
title: "$datasets - 当前页面所有数据集的根对象"
---
---
navTitle: $datasets
---
# $datasets - 当前页面所有数据集的根对象
`$datasets` 当前页面所有数据集的根，当数据集的ID与组件ID重复时需要带上根来访问。
- `$datasets.QYJBXX` - 访问页面的`QYJBXX`数据集
- `$datasets.QYJBXX.QYMC` - `QYJBXX`数据集的`QYMC`字段
---
url: "https://docs.succapp.com/v5/guide/exp/var/$did.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$did"
title: "$did - 报表填报应用中当前明细数据的ID"
---
---
navTitle: $did
---
# $did - 报表填报应用中当前明细数据的ID
`$did`代表当前打开的明细数据，没有打开明细数据时返回null，在表达式中可以通过`$did.xxx`的形式获取该明细数据的属性，如：
- `$did` - 明细数据ID
- `$did.id` - 明细数据ID
- `$did.name` - 明细数据名称
- 其他明细信息表中的字段
也可以使用`$did.xxx.yyy`的形式获取明细数据维中的维字段关联维表的属性，以设备明细数据为例，可通过以下表达式获取设备表的属性：
- `$did.sblx.name` - 返回设备的类型名称
- `$did.jgbm.name` - 返回设备的采购部门名称
---
url: "https://docs.succapp.com/v5/guide/exp/var/$error.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$error"
title: "$error - 当前异常信息"
---
---
navTitle: $error
---
# $error - 当前异常信息
`$error`代表当前发生异常时的错误信息。
在程序流中，`$error`当做全局变量访问时表示流程最近一次发生的错误，例如在程序流的错误响应设置中访问`$error`表示获取导致当前流程终止运行的错误信息、而在一个节点中访问`$error`表示获取当前节点最近一次发生的错误信息，也许是当前节点自己的错误，也许是当前节点上游节点发生的错误但被捕获了。若想准确获取一个节点的错误，可以使用`节点.$error`访问指定节点的错误信息。
在表达式中可以通过`$error.xxx`的形式获取一些错误信息的属性，如：
- `$error.errorCode` - 异常编码，如：`err.db.duplicateKey` 主键重复，或者违反唯一约定
- `$error.message` - 关于异常的描述信息，如：`(succbidw)Duplicate entry '2020060401' for key 'PRIMARY'`
- `$error.causeMessage` - 导致异常的最初的异常的错误信息
- `$error.className` - 异常的类名
- `$error.sqlState` - JDBC异常的SQLState
- `$error.sqlErrorCode` - JDBC异常的VendorErrorCode
- `$error.properties` - 异常内部的详细信息，如字段不存在的异常，可以通过`$error.properties.fieldName`取到字段名
- `$error.stackTrace` - 异常堆栈，如：`com.succez.commons.jdbc.SuccezSQLException: (succbidw)Duplicate entry '2020060401' for key 'PRIMARY' at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)...`
---
url: "https://docs.succapp.com/v5/guide/exp/var/$event.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$event"
title: "$event - 当前事件信息"
---
---
navTitle: $event
---
# $event - 当前事件信息
`$event`代表当前交互发生时的事件信息。常用于：
1. 在交互的启用条件中判断，只有当满足具体的交互细节时才执行交互动作。例如点击日历组件的“警告数字”时显示详细警告信息的提示面板、点击输入框的标题时显示帮助信息。
2. 在交互弹出的对话框中，通过事件对象获取更多信息用于过滤数据。
在表达式中可以通过`$event.xxx`的形式获取细节信息，包括：
- `$event.type` - 事件的类型，包括`click`, `dbclick`, `hover`, `contextmenu`, `input`, `change`……
- `$event.value` - 当前事件发生时所在的组件的“值”，等价于`$event.target.value`
- `$event.txt` - 当前事件发生时所在的组件的值作用显示格式之后的“文本”，等价于`$event.target.txt`
- `$event.target` - 触发该事件的组件（或部件、节点等），即事件发生的源头组件，可访问属性见[target](#event-target)
- `$event.currentTarget` - 监听事件的组件，即事件是是被哪个组件所处理的，可访问属性见[target](#event-target)
- `$event.timeStamp` - 事件发生时的时间戳
- `$event.altKey` - 事件发生时是否按下了alt键
- `$event.ctrlKey` - 事件发生时是否按下了ctrl键
- `$event.metaKey` - 事件发生时是否按下了meta键（windows是win键，macOS是cmd键）
- `$event.shiftKey` - 事件发生时是否按下了shift键
- `$event.key` - 用户键盘输入时输入的键，如`a`表示字母a，`Enter`表示回车键
- `$event.code` - 键盘输入时输入的键的代码，如`Space`表示空格、'ArrowUp'表示向上箭头，见
- `$event.repeat` - 是否按住了键盘没有松开
- `$event.isComposing` - 是否正在使用输入法输入
- `$event.button` - 鼠标点击时鼠标的按钮，0表示左键，1表示中键，2表示右键
- `$event.screenX` - 鼠标在屏幕中的X坐标\`
- `$event.screenY` - 鼠标在屏幕中的Y坐标\`
- `$event.clientX` - 鼠标在视窗可视区域中的X坐标\`
- `$event.clientY` - 鼠标在视窗可视区域中的Y坐标\`
- `$event.offsetX` - 鼠标在当前元素中的X坐标\`
- `$event.offsetY` - 鼠标在当前元素中的Y坐标\`
- `$event.pageX` - 鼠标在当前窗口页面中的X坐标（含滚动）\`
- `$event.pageY` - 鼠标在当前窗口页面中的Y坐标（含滚动）\`
- `$event.movementX` - 鼠标相对于上次事件的X坐标的移动距离\`
- `$event.movementY` - 鼠标相对于上次事件的Y坐标的移动距离\`
## `$event.target` 属性{#event-target}
`$event.target` 和 `$event.currentTarget` 都是组件对象，其属性相同：
- `.id` - 事件发生时用户点击的组件的id
- `.name` - 触发该事件的组件的名称，如：柱形图有两个指标系列，点击不同柱子可获取对应的指标名称
- `.value` - 触发该事件的组件的值，如：被点击的树节点的id、按钮的值、输入框的值、日历中的用户点击的日期……
- `.txt` - 触发该事件的组件的值作用显示格式之后的文本，如：输入框的文本，单元格的文本
- `.dataCount` - 当前事件发生时所在的组件关联数据的行数。如：gispoints一个经纬度上对应了多个点；列表多选了几行数据并点击右键
- `.type` - 事件发生时用户点击或操作的“部件”，用于判断用户点击的具体内容，可能的类型见[$event.target.type](#event-target-type)
- `.dom` - 事件发生时点击的DOM元素，可以通过它进一步访问到下面的属性：
- `.textContent` - DOM的内容，等价于`.dom`
- `.tag` - DOM的tag，如`a`、`div`
- `.className` - DOM的内容样式，如果有多个那么逗号分割
- `.attributes` - DOM的所有属性构成的JSON字符串
## `$event.target.type` 可能的值{#event-target-type}
- `nodeIcon` - 表示点击的树节点图标
- `nodeText` - 表示点击的树节点标题
- `tree` - 表示点击的树的空白区域
- `date` - 表示点击的日历控件的某一天（通过`$event.value`可以知道具体哪天）
- `hintNumber` - 表示点击提示数字
- `warnNumber` - 表示点击警告数字
- `errorNumber` - 表示点击错误数字
- ……，更多类型，可以由组件实现者提供
---
url: "https://docs.succapp.com/v5/guide/exp/var/$file.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$file"
title: "$file - 当前文件对象"
---
---
navTitle: $file
---
# $file - 当前文件对象
`$file`代表当前文件对象，在表达式中可以通过`$file.xxx`的形式来获取文件属性，有如下属性：
- `$file.id` - 元数据ID。
- `$file.name` - 文件名称。
- `$file.desc` - 文件描述。
- `$file.path` - 文件的绝对路径。
- `$file.parentDir` - 文件的父路径，以`/`开头,不以`/`结尾。项目的父路径会返回`/`。
- `$file.revision` - 文件的版本，每次修改，版本都会加1。
- `$file.projectName` - 文件的所属的项目。
- `$file.creator` - 创建人。
- `$file.createTime` - 创建时间。
- `$file.modifier` - 最后修改人。
- `$file.modifyTime` - 最后修改时间。
- `$file.type` - 文件类型。
- `$file.labels` - 文件的标签，是一个JSON数组。
- `$file.favorite` - 当前用户是否收藏了文件，是一个布尔值。
- `$file.customOption` - 扩展属性，是一个json，是用户自己定义的属性。
---
url: "https://docs.succapp.com/v5/guide/exp/var/$flow.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$flow"
title: "$flow - 当前工作流状态信息"
---
---
navTitle: $flow
---
# $flow - 当前工作流状态信息
`$flow`代表工作流状态，在表达式中可以通过`$flow.xxx`的形式获取工作流属性或状态信息，有如下属性：
- `$flow.flowName` - 流程描述，即工作流资源描述，如`请假申请`
- `$flow.bussinessDesc` - 流程业务描述，如`张三的请假申请`
- `$flow.bussinessKey` - 流程业务代码
- `$flow.state` - 流程运行状态。
- `$flow.state="active"` 正在运行
- `$flow.state="draft"` 草稿状态，未正式发起
- `$flow.state="finished"` 结束
- `$flow.result` - 流程处理状态。
- `$flow.result="normal"` 正常结束
- `$flow.result="reject"` 被否决
- `$flow.result="terminate"` 被强制结束
- `$flow.startTime` - 流程发起时间
- `$flow.startUser` - 流程发起人，可获取到用户对象，可继续访问下级属性。
- `$flow.updateTime` - 最后处理时间
- `$flow.updateUser` - 最后处理人，可获取到用户对象，可继续访问下级属性。
- `$flow.endTime` - 流程结束时间
- `$flow.currentUser` - 当前处理人，可获取到用户对象，可继续访问下级属性（兼容多个用户，如`$flow.currentUser.userName`在负责人有多个时，返回`张三,李四`）。
- `$flow.urgeTime` - 催办时间
- `$flow.urgeUser` - 催办用户，可获取到用户对象
- `$flow.task` - 当前任务
- `$flow.task.assignee` - 当前任务负责人，只会有一个用户，可获取到用户对象，可继续访问下级属性。
- `$flow.task.processor` - 当前任务处理人，可获取到用户对象，可继续访问下级属性。
- `$flow.task.comment` - 当前任务处理意见
- `$flow.task.startTime` - 当前任务开始时间
- `$flow.task.endTime` - 当前任务处理时间
- `$flow.task.result` - 当前任务处理结果。`submit`-提交；`approve`-批准；`reject`-否决；`retreat`-退回；`retract`-撤回；`autocomplete`-自动完成，如或签任务被完成等。
- `$flow.task.dueTime` - 当前任务截止时间
- `$flow.node` - 当前节点
- `$flow.node.txt` - 当前节点描述
- `$flow.node.assignee` - 当前节点负责人，有一个或多个用户，可获取到用户对象，可继续访问下级属性（兼容多个用户，如`$flow.node.assignee.userName`在负责人有多个时，返回`张三,李四`）。
- `$flow.node.processor` - 当前节点处理人，有一个或多个用户，可获取到用户对象，可继续访问下级属性。
- `$flow.node.comment` - 当前节点处理意见
- `$flow.node.startTime` - 当前节点开始时间
- `$flow.node.endTime` - 当前节点结束时间
- `$flow.node.result` - 当前节点处理结果。`submit`-提交；`approve`-批准；`reject`-否决；`retreat`-退回；`retract`-撤回；`autocomplete`-自动完成，如或签任务被完成等。
- `$flow.preNode` - 上级节点
- `$flow.preNode.txt` - 上级节点描述
- `$flow.preNode.assignee` - 上级节点负责人，有一个或多个用户，可获取到用户对象，可继续访问下级属性（兼容多个用户，如`$flow.preNode.assignee.userName`在负责人有多个时，返回`张三,李四`）。
- `$flow.preNode.processor` - 上级节点处理人，有一个或多个用户，可获取到用户对象，可继续访问下级属性。
- `$flow.preNode.comment` - 上级节点处理意见
- `$flow.node.startTime` - 上级节点开始时间
- `$flow.preNode.endTime` - 上级节点处理时间
- `$flow.preNode.result` - 上级节点处理结果。`submit`-提交；`approve`-批准；`reject`-否决；`retreat`-退回；`retract`-撤回；`autocomplete`-自动完成，如或签任务被完成等。
---
url: "https://docs.succapp.com/v5/guide/exp/var/$id.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$id"
title: "$id - 报表填报应用当前填报单位的ID"
---
---
navTitle: $id
---
# $id - 报表填报应用当前填报单位的ID
`$id`代表当前填报单位(周期填报应用)或数据条目(信息管理应用)，以下统称为 `当前填报单位`，在表达式中可以通过`$id.xxx`的形式获取当前填报单位的属性，如：
- `$id` - 单位ID
- `$id.id` - 单位ID
- `$id.name` - 单位名称
- 其他填报单位维中的字段
也可以使用`$id.xxx.yyy`的形式获取填报单位维中的维字段关联维表的属性，如获取部门ID字段关联的对应部门表中的相关属性：
- `$id.dq.name` - 返回填报单位所在大区的名称
- `$id.swjg.name` - 返回填报单位所属税务机关的名称
---
url: "https://docs.succapp.com/v5/guide/exp/var/$job.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$job"
title: "$job - 当前长任务运行上下文"
---
---
navTitle: $job
---
# $job - 当前长任务运行上下文
`$job` 表示当前后台长任务或批任务的运行上下文，适用于数据加工、取数模型、指标库提取、批量校验、批量计算、知识库提取等场景。
`$job` 不用于页面交互、普通表达式输入上下文、工作流实例/任务上下文，这些场景仍分别使用 `$event`、`$flow`、`$flowtask`。
在表达式中可以通过 `$job.xxx` 的形式获取任务运行信息，包括：
- `$job.id` - 任务运行ID
- `$job.name` - 任务名称
- `$job.resId` - 关联资源ID
- `$job.userId` - 执行用户ID
- `$job.executor` - 执行者，返回用户对象，可继续访问下级属性，如 `$job.executor.name`
- `$job.startTime` - 开始时间
- `$job.endTime` - 结束时间
- `$job.elapseTime` - 执行耗时
- `$job.retryTimes` - 当前是第几次重试，首次执行为 `0`
- `$job.trigger` - 触发方式，手动`1`，定时`2`，如果是定时执行，可以通过`$scheduleRunInf`获取更多计划信息。
- `$job.taskId` - 任务ID
- `$job.taskName` - 任务名称
- `$job.taskType` - 任务类型，`etl`数据加工，`script`批处理脚本，`workflow`工作流，`afl`程序流
- `$job.params` - 运行参数，返回 JSON 对象
- `$job.extractPlan` - 提取方案ID
- `$job.extractMode` - 提取模式，`OverwriteAll`全量覆盖，`Rebuild`全量重建，`Append`追加，`Merge`合并追加
- `$job.isIncremental` - 是否增量提取
- `$job.incFrom` - 增量提取起点
- `$job.incTo` - 增量提取终点
- `$job.state` - 运行状态，`WAITING`等待执行，或等待重试，`RUNNING`运行中，`TIMEOUT`超时，`BLOCK`阻塞，`CANCLED`取消
- `$job.totalCount` - 总行数
- `$job.successCount` - 成功数
- `$job.failCount` - 失败数
- `$job.ignoreCount` - 忽略数
- `$job.errorSamples` - 失败数据样例列表
`$job.errorSamples` 只用于提供轻量级失败样例，不建议在这里暴露完整失败明细或全量忽略数据。样例中的每一项通常只包含少量摘要信息，如 `id`、`key`、`message`、`file`、`table` 等。
示例：
```ts
// 判断当前是否为定时触发
$job.trigger = 2
// 判断是否为增量提取
$job.isIncremental
// 针对不同提取方案使用不同过滤条件
if($job.extractPlan='inc', year_month > ADDDATE(today(), -3, 'm'))
// 获取任务状态
$job.state
// 获取失败样例
$job.errorSamples
```
---
url: "https://docs.succapp.com/v5/guide/exp/var/$language.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$language"
title: "$language - 当前页面语言"
---
---
navTitle: $language
---
# $language - 当前页面语言
`$language` 当前页面的语言
---
url: "https://docs.succapp.com/v5/guide/exp/var/$location.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$location"
title: "$location - 当前地理定位信息"
---
---
navTitle: $location
---
# $location - 当前地理定位信息
`$location`代表当前位置信息，在表达式中可以通过`$location.xxx`的形式获取位置的详细信息，如：
- `$location.country` - 当前位置所在国家，如：中国
- `$location.province` - 当前位置所在省份，如：湖北省
- `$location.city` - 当前位置所在城市，如：武汉市
- `$location.cityCode` - 当前位置所在的城市编码，如：027
- `$location.district` - 当前位置所在区/县：如：江汉区
- `$location.streetInfo` - 当前位置所在街道信息，如：发展大道207号
- `$location.postCode` - 当前位置的邮政编码，如：430022
- `$location.adCode` - 当前位置的区域代码，如：420010
- `$location.address` - 当前位置的详细地址信息，如：湖北省武汉市江汉区发展大道207号
- `$location.lng` - 当前位置的经度，如：114.34686
- `$location.lat` - 当前位置的纬度，如：30.58448
## **GPS定位**{#locate}
- **GPS**：全球定位系统（英文：Global Positioning System），是一种以人造地球卫星为基础的高精度无线电导航的定位系统，它在全球任何地方以及近地空间都能够提供准确的地理位置、车行速度及精确的时间信息。
- **室内GPS**：GPS是接收卫星直射下来的信号，室内的建筑物会遮挡卫星发射的信号，导致室内定位的精度会受到影响。
- **移动端GPS**：移动端包括手机、PAD和其它带有GPS定位芯片的智能设备（如手表、音箱等），成功定位需要满足以下四个条件：
- 移动端GPS打开，且所使用的App或浏览器已获取定位权限。
- iOS10以上系统和Android的一些版本，已禁止在非`HTTPS`协议的域名下定位，需要升级到`HTTPS`。
- 微信7.0版本升级了对`HTTPS`的安全限制，导致`HTTPS`的定位不能正常使用，导致出现苹果可以正常获取定位，安卓获取不到的现象，若出现该问题需要将站点升级到`HTTPS`。
- 在连接WIFI的情况下，移动端获取的是WIFI定位结果，在GPS定位受限时，可以通过WIFI网络获取定位信息。
- **PC端GPS**：PC设备上一般缺少GPS芯片，主要通过IP进行定位，定位精度相对移动GPS较低。
## 坐标介绍{#axis}
1. `WGS84`：国际坐标系，为一种大地坐标系，也是目前广泛使用的GPS全球卫星定位系统使用的坐标系。
2. `GCJ02`：火星坐标系，是由中国国家测绘局制订的地理信息系统的坐标系统。 由WGS84坐标系经加密后的坐标系。
3. `BD09`：百度坐标系，在GCJ02坐标系基础上再次加密。
目前产品通过HTML5的`Geolocation API`接口获取地理定位，返回是GPS坐标，即WGS84坐标。如果在页面中使用了`$location.lng`、`$location.lat`表达式，会在用户客户端通过GPS查询当前位置经纬度，并通过`Geolocation API`接口将该经纬度返回。
---
url: "https://docs.succapp.com/v5/guide/exp/var/$logs.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$logs"
title: "$logs - 当前对象日志信息"
---
---
navTitle: $logs
---
# $logs - 当前对象日志信息
`$logs`代表当前对象的日志信息，在表达式中可以通过`$logs.xxx`的形式来获取日志信息，有如下属性：
- `$logs.lastLog` - 最新的一条日志，返回一个日志条目对象。
- `$logs.lastSql` - 最新的一条SQL日志，返回一个日志条目对象。
- `$logs.lastSqlDuration` - 最新的一条SQL的执行耗时。
- `$logs.allSqls` - 所有的SQL日志，返回一个数组。
- `$logs.allLogs` - 所有的日志，返回一个数组。
- `$logs.duration` - 总持续时间，毫秒。
- `$logs.count` - 日志条数。
- `$logs.logLevel` - 日志记录级别。
日志条目对象对象有如下子属性：
- `.time` - 日志时间。
- `.desc` - 日志描述。
- `.level` - 日志级别。
- `.type` - 日志的类型，log、sql、code、exception。
- `.subLogs` - 子日志，返回一个数组，每个数组条目仍然是一个日志条目对象，不会不会再有更深一层的子日志了。
---
url: "https://docs.succapp.com/v5/guide/exp/var/$page.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$page"
title: "$page - 当前页面信息"
---
---
navTitle: $page
---
# $page - 当前页面信息
`$page`代表当前页面，在表达式中可以通过`$page.xxx`的形式来获取页面属性，有如下属性：
- `$page.activeSheet` - 当前工作表
- `$page.activeSheet.$id` - 当前工作表ID
- `$page.activeSheet.$name` - 当前工作表名称
- `$page.$anchors` - 页面内的所有锚点，是一个json数组，形如`[{"id":"anchor1", caption:"xxxxx"}...]`
---
url: "https://docs.succapp.com/v5/guide/exp/var/$params.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$params"
title: "$params - 当前页面所有参数的根对象"
---
---
navTitle: $params
---
# $params - 当前页面所有参数的根对象
`$params`代表当前页面所有参数的根，当参数ID与组件ID等重复时需要带上根来访问。
- `$params.QYID` - 参数`QYID`
---
url: "https://docs.succapp.com/v5/guide/exp/var/$pid.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$pid"
title: "$pid - 报表填报应用当前上级单位的ID"
---
---
navTitle: $pid
---
# $pid - 报表填报应用当前上级单位的ID
`$pid`代表当前填报单位的上级单位(周期填报应用)或当前数据条目的上级条目(信息管理应用)，以下统称为 `上级填报单位`，在表达式中可以通过`$pid.xxx`的形式获取上级单位的属性，如：
- `$pid` - 上级单位ID
- `$pid.id` - 上级单位ID
- `$pid.name` - 上级名称
- 其他填报单位维中的字段
也可以使用`$pid.xxx.yyy`的形式获取填报单位维中的维字段关联维表的属性，如获取部门ID字段关联的对应部门表中的相关属性：
- `$pid.dq.name` - 返回上级单位单位所在大区的名称
- `$pid.swjg.name` - 返回上级单位所属税务机关的名称
---
url: "https://docs.succapp.com/v5/guide/exp/var/$request.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$request"
title: "$request - HTTP请求的信息"
---
---
navTitle: $request
---
# $request - HTTP请求的信息
`$request`通常使用在程序流中，表示当前交互发生时的WEB请求的信息。常用于：
1. 在程序流中判断只有当请求地址是来自内网地址时才执行某些操作，`$request.remoteAddr`获取发送请求的IP地址。
2. 在程序流中判断只有当请求的方法是POST时才执行某些操作，`$request.method` 获取请求的方法。
如果程序流是由后端定时执行或者二次开发脚本执行的，那么此变量内部的属性会返回空值。
在表达式中可以通过`$request.xxx`的形式获取细节信息，包括：
- `$request.method` - 请求的方法
- `$request.path` - 请求的路径（不含contextPath，不含参数）
- `$request.parameters` - 请求的参数，是一个JSON对象
- `$request.requestURI` - 请求的URI(含contextPath，不含参数)
- `$request.queryString` - 请求参数部分，即问号后面的部分（不含问号）
- `$request.protocol` - 请求的协议（带版本），如`HTTP/1.1`
- `$request.scheme` - 请求的协议（不带版本），如`http`、`https`
- `$request.port` - 请求的端口
- `$request.headers` - 请求的headers，是一个JSON对象
- `$request.characterEncoding` - 请求的字符编码
- `$request.locale` - 请求的语言
- `$request.contentType` - 请求的MIME类型，不含charset
- `$request.contentLength` - 请求的body长度
- `$request.remoteAddr` - 请求的远程地址
- `$request.remoteHost` - 请求的远程主机
- `$request.remotePort` - 请求的远程端口
- `$request.localAddr` - 本机响应请求的IP地址
- `$request.localPort` - 本机响应请求的端口
- `$request.cookies` - cookies，是一个JSON对象
- `$request.contextPath` - 请求的contextPath，如`/api`
- `$request.sessionId` - 当前会话的ID
- `$request.requestBody` - POST请求有效，根据请求的contentType返回不同类型，如果是JSON返回JSON对象，其他情况可能是字符串，对于上传文件的请求，返回空
- `$request.files` - POST请求且`Content-Type: multipart/form-data;`时有效，表示是一个上传文件的请求，返回一个数组对象，成员是文件，文件已经提前存放到临时文件中了
---
url: "https://docs.succapp.com/v5/guide/exp/var/$response.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$response"
title: "$response - HTTP响应的信息"
---
---
navTitle: $response
---
# $response - HTTP响应的信息
`$response`是HTTP请求响应的信息，常用于程序流部分可能发送HTTP请求的节点中，表示请求的响应信息。
在表达式中，可以通过`actionNodeXxx.$response.xxx`的形式获取细节信息，包括：
- `$response.statusCode` - 响应的状态码
- `$response.statusText` - 响应的状态文本
- `$response.headers` - 响应的headers，是一个JSON对象
- `$response.characterEncoding` - 字符编码
- `$response.locale` - 语言
- `$response.contentType` - MIME类型
- `$response.contentLength` - body长度
- `$response.cookies` - 响应的cookies，是一个JSON对象
---
url: "https://docs.succapp.com/v5/guide/exp/var/$self.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$self"
title: "$self - 当前值"
---
---
navTitle: $self
---
# $self - 当前值
`$self`代表当前组件值。常用于：
1. 在单元格条件样式中，`$self`表示条件样式所在单元格的值，例如：如果单元格的值大于0时想将字体设置为红色，可以在条件样式的表达式中写`$self>0`。
2. 在交互中，`$self`表示交互所在组件的值，例如：如果想在单元格的设置参数值交互中想将全局参数的值设置为当前点击单元格的值，可以在参数值的表达式中写`=$self`。
在表达式中`$self`相当于当前组件，所以当前组件可以引用的下级变量都可以通过`$self.xxx`的形式获取。
- `$self.value` - 相当于直接写了`$self`，表示引用当前组件值
- `$self.txt` - 表示引用当前组件的文本值
- ...
---
url: "https://docs.succapp.com/v5/guide/exp/var/$server.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$server"
title: "$server - 当前服务器环境"
---
---
navTitle: $server
---
# $server - 当前服务器环境
`$server`代表当前服务器环境，在表达式中可以通过`$server.xxx`的形式来获取服务器属性，有如下属性：
- `$server.workDir` - 工作目录路径，末尾不带斜杠。
- `$server.language` - 默认语言。用户没有设置，返回服务器操作系统的语言。如`zh_CN`。
- `$server.serverURL` - 服务器外网部署地址，包含上下文。
- `$server.intranetURL` - 服务器内网部署地址。没有设置，则为空的字符串""。
---
url: "https://docs.succapp.com/v5/guide/exp/var/$user.md"
htmlUrl: "https://docs.succapp.com/v5/exp/var/$user"
title: "$user - 用户信息"
---
---
navTitle: $user
---
# $user - 用户信息
`$user`代表当前登录用户，在表达式中可以通过`$user.xxx`的形式获取用户的属性，如：
- `$user.id` - 用户ID
- `$user.name` - 用户名称
- `$user.org_id` - 用户所在的机构ID
- `$user.dept_id` - 用户所在的部门ID
- `$user.phone` - 手机号码
- `$user.enabled` - 启用状态
- `$user.creat_time` - 用户创建时间
- `$user.anonymous` - 是否匿名用户
- `$user.user_labels` - 用户标签
- `$user.user_directory` - 用户目录，`sys`表示内部用户，`external`表示外部用户
- 也可以使用用户表中存在的其他字段名或者新增的属性字段
也可以使用`$user.xxx.yyy`的形式获取用户表中的字段关联了维表的相关属性，如获取部门ID字段关联的对应部门表中的相关属性：
- `$user.dept_id.dept_name` - 返回当前登录用户所在的部门名称
- `$user.dept_id.parent_id` - 返回当前登录用户所在部门的上级部门ID
- `$user.dept_id.sz_level` - 返回当前登录用户所在部门的层级
- `$user.dept_id.sz_isleaf` - 判断当前登录用户所在部门是否是叶子节点
- 也可以使用部门表中存在的其他字段名或者新增的属性字段
示例地址：[权限函数-$user](https://demo.succbi.com/v5/DEMO/app/ap.app?id=%E6%9D%83%E9%99%90%E5%87%BD%E6%95%B0)
---
url: "https://docs.succapp.com/v5/guide/exp/func/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/funcs"
title: "函数列表"
---
---
order: 5
navTitle: 函数列表
indexTitle: 函数参考
---
# 函数列表
!!!children (guide/exp/func) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/string-funcs"
title: "字符函数列表"
---
---
navTitle: 字符函数
---
# 字符函数列表
!!!children (guide/exp/func/string)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/LEN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/len"
title: "LEN - 返回字符串中的字符个数或者数组的长度"
---
# **LEN**
返回字符串中的字符个数或者数组的长度。
## 语法{#grammar}
LEN(**object**)
- **object**：必需。对象，目前支持数组和字符串
- 参数是数组时，将返回数组的长度
- 其他对象将转为字符串对象运算，然后返回文本字符串中的字符个数
- 参数中带有转义字符、空格、空字符串时，算为一个字符长度
**示例地址：** [LEN](https://demo.succbi.com/v5/bi/len)
## 示例{#example}
1. `LEN("string")` 参数是字符串，获取字符串的字符个数，返回`6`
2. `LEN(ARR(1,2,'abd',5))` 参数是数组，获取数组的长度，返回`4`
3. `LEN("te测试st")` 参数是汉字字母混合，返回`6`
4. `LEN(A1)` 引用单元格A1的值，返回`11`
5. `LEN([门店月销汇总表].[门店].[门店名称])` 引用模型字段，返回门店名称长度`11`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/LEFT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/left"
title: "LEFT - 从字符串的第一个字符开始返回指定个数的字符"
---
# **LEFT**
从字符串的第一个字符开始返回指定个数的字符。
## 语法{#grammar}
LEFT(**str**, **num**)
- **str**：给定的字符串对象
- **num**：非负整数，指定返回的字符数量。它的合法取值是1到字符串长度
- 如果num小于或等于0或者为NaN类型时，返回空字符串
- 如果num大于字符串长度，返回整个字符串
**示例地址：** [LEFT](https://demo.succbi.com/v5/bi/left)
## 示例{#example}
1. `LEFT("qwer",2)` 返回字符串前两位字母`qw`
2. `LEFT("210502198412020944",6)` 返回身份证的地区码`210502`
3. `LEFT("zhangming@qq.com",FIND("zhangming@qq.com","@"))` 返回邮件的用户名`zhangming` [FIND](./FIND.md)函数
4. `CONCAT(LEFT("这件商品现在卖的很火",4),"......")` 描述只显示部分信息`这件商品......` [CONCAT](./CONCAT.md)函数
5. `IF(LEFT("湖北省武汉市江岸区建设大道",FIND("湖北省武汉市江岸区建设大道","省"))="湖北","属于","不属于")` 判断地址是不是属于湖北省`属于` [IF](../logic/IF.md)函数
6. `CONCAT(LEFT(E14,4),"-",MID(E14,4,4),"-",MID(E14,8,4),"-",RIGHT(E14,4))` 银行卡号分段显示`6226-0902-1929-8748`
7. `LEFT("湖北省武汉市",3)` 字符串为汉字返回`湖北省`
8. `LEFT(A1,4)` 返回单元格A1的前四位，即生产季节的年份`2016`
9. `LEFT([门店销售明细表].[生产季节],4)` 参数值返回生产季节的年份`2016`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/RIGHT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/right"
title: "RIGHT - 从字符串的最后一个字符开始返回指定个数的字符"
---
# **RIGHT**
从字符串的最后一个字符开始返回指定个数的字符。
## 语法{#grammar}
RIGHT(**str**, **num**)
- **str**：给定的字符串对象
- **num**：非负整数，指定返回的字符数，它的合法取值是`1`到`len(str)`
- 如果num<=0或者为NaN类型时，返回空字符串
- 如果num>len(str)，返回整个字符串
**示例地址：** [RIGHT](https://demo.succbi.com/v5/bi/right)
## 示例{#example}
1. `RIGHT("qwer",2)` 返回字符串后两位字母`er`
2. `RIGHT("13424559878",4)` 返回手机号后四位`9878`
3. `RIGHT(E11,LEN(E11)-FIND(E11,"-")-1)` 返回店名的名称`武汉店`
4. `CONCAT(LEFT(E12,4),"-",MID(E12,4,4),"-",MID(E12,8,4),"-",RIGHT(E12,4))` 银行卡号分段显示`6226-0902-1929-8748` [CONCAT](./CONCAT.md)函数
5. `RIGHT(E25,2)` 引用单元格，返回生产季节`春夏`
6. `RIGHT([门店销售明细表].[生产季节].[季节名称],2)` 引用模型字段，返回生产季节`春夏`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/MID.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/mid"
title: "MID - 从字符串中指定的起始位置起返回指定长度的字符串"
---
# **MID**
从字符串中指定的起始位置起返回指定长度的字符串，用法与[SUBSTR函数](./SUBSTR.md)相同。
## 语法{#grammar}
MID(**str**, **start\_index**, \[**num**])
- **str**：给定的字符串对象
- **start\_index**：非负整数，规定要提取的子串的第一个字符在str中的位置。合法取值范围是`1`到`len(str)`
- start\_index>0：在字符串的指定位置开始
- start\_index<0：从字符串结尾的指定位置开始
- start\_index=0：返回空字符串
- start\_index>len(str)：返回空字符串
- start\_index+num>len(str)：返回的子串一直到字符串的结尾
- **num**：可选的非负整数，返回子串的长度
- 合法取值范围：`1`到`len(str)-start_index+1`
- 不传递参数时：返回的子串会一直到字符串的结尾
- num<1：返回空字符串
**示例地址：** [MID](https://demo.succbi.com/v5/bi/mid)
## 示例{#example}
1. `MID("qwer",2)` 从第二个字符一直到字符串尾，返回`wer`
2. `MID("210502198412020944",7,8)` 返回身份证中的出生日期，返回`19841202`
3. `MID("03-武汉店",1,FIND("03-武汉店",'-')-1)` 返回门店编码，返回`03` [FIND](./FIND.md)函数
4. `MID(A1,1,4)` 静态值返回生产季节的年份，返回`2017`
5. `MID([门店销售明细表].[生产季节],1,4)` 参数值返回生产季节的年份，返回`2017`
6. `MID("asd",0,2)` start\_index=0，返回结果为空字符串
7. `MID("asd",4,2)` start\_index超过字符串长度，返回结果为空字符串
8. `MID("abcdefg",-1,4)` start\_index<0，返回结果从字符串结尾的指定位置开始，返回`g`
9. `MID("asd",1,4)` num超过字符串长度，返回字串一直到字符串的结尾，返回`asd`
10. `MID("asd",2,0)` num=0，返回结果为空字符串
11. `MID("asd",2,-1)` num<1，返回结果为空字符串
12. `MID("湖北省武汉市",5,3)` start\_index+num>len(str)，返回子字符串一直到结尾，返回`汉市`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SUBSTR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/substr"
title: "SUBSTR - SUBSTR函数表示从字符串中指定的起始位置截取的字符串或字符串表达式"
---
# **SUBSTR**
SUBSTR函数表示从字符串中指定的起始位置截取的字符串或字符串表达式，用法与[MID函数](./MID.md)相同。
## 语法{#grammar}
SUBSTR(**str**, **start\_index**, \[**num**])
- **str**：指定的要截取的字符串。
- **start\_index**：非负整数，规定要提取的子串的第一个字符在str中的位置。合法取值范围是`1`到`len(str)`
- start\_index>0：在字符串的指定位置开始
- start\_index<0：在从字符串结尾的指定位置开始
- start\_index=0：返回空字符串
- start\_index>len(str)：返回空字符串
- start\_index+num>len(str)：返回的子串一直到字符串的结尾
- **num**：可选的非负整数，返回子串的长度，缺省时返回字符表达式的值结束前的全部字符
- 合法取值范围：`1`到`len(str)-start_index+1`
- 不传递参数时：返回的子串会一直到字符串的结尾
- num<1：返回空字符串
**示例地址：** [SUBSTR](https://demo.succbi.com/v5/bi/substr)
## 示例{#example}
1. `SUBSTR("abcde",1,null)`返回结果为空字符串
2. `SUBSTR("asd",0,2)` start\_index=0，返回结果为空字符串
3. `SUBSTR("asd",4,2)` start\_index超过字符串长度，返回结果为空字符串
4. `SUBSTR("abcdefg",-1,4)` start\_index<0，返回结果从字符串结尾的指定位置开始，返回`g`
5. `SUBSTR("210502198412020944",7,8)` 返回身份证中的出生日期，返回`19841202`
6. `SUBSTR("asd",1,4)` num超过字符串长度，返回字串一直到字符串的结尾，返回`asd`
7. `SUBSTR("asd",2,0)` num=0，返回结果为空字符串
8. `SUBSTR("asd",2,-1)` num<1，返回结果为空字符串
9. `SUBSTR("湖北省武汉市",5,3)` start\_index+num>len(str)，返回子字符串一直到结尾，返回`汉市`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/UPPER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/upper"
title: "UPPER - 将给定的字符串转换为大写"
---
# **UPPER**
将给定的字符串转换为大写。
## 语法{#grammar}
UPPER(**str**)
- **str**：给定的字符串对象
**示例地址：** [UPPER](https://demo.succbi.com/v5/bi/upper)
## 示例{#example}
1. `UPPER('qwer')` 参数为小写字母，返回`QWER`
2. `UPPER('QwEr')` 参数为大小写字母，返回`QWER`
3. `UPPER(A1)` 引用单元格，返回转大写的企业内部序号`0014E9A03BBACBAE09D41AD124864A09`
4. `UPPER([企业基本信息].[企业内部序号])` 引用模型字段，返回转大写的企业内部序号`0014E9A03BBACBAE09D41AD124864A09`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/LOWER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lower"
title: "LOWER - 将给定的字符串转换为小写"
---
# **LOWER**
将给定的字符串转换为小写。
## 语法{#grammar}
LOWER(**str**)
- **str**：给定的字符串对象
**示例地址：** [LOWER](https://demo.succbi.com/v5/bi/lower)
## 示例{#example}
1. `CHAR(33)` 返回ASCII码33对应的字符特殊符号`!`
2. `LOWER('QWER')` 参数为大写字母，返回`qwer`
3. `LOWER('qwer')` 参数为小写字母，返回`qwer`
4. `LOWER('QwEr')` 参数为大小写字母，返回`qwer`
5. `LOWER(A1)` 将单元格A1的大写字符转为小写，返回`91420100ma4kxdh9xt`
6. `LOWER([企业基本信息].[统一社会信用代码])` 参数值将统一社会信用代码大写字符转为小写，返回`91420100ma4kxdh9xt`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/CONCAT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/concat"
title: "CONCAT - 拼接多个字符串"
---
# **CONCAT**
拼接多个字符串。当第一个**p1**参数是数组时，将进行数组的连接；其他情况，会将**pN**转换为字符串，然后进行字符串连接。
## 语法{#grammar}
CONCAT(**pN**)
- **pN**：连接的对象，目前支持字符串和数组对象
**示例地址：** [CONCAT](https://demo.succbi.com/v5/bi/concat)
## 示例{#example}
1. `CONCAT("张三","13589779856")` 姓名与电话号码拼接，返回字符串`张三13589779856`
2. `CONCAT(LEFT(E10,3),"-",MID(E10,3,4),"-",RIGHT(E10,4))` 电话号码分隔符分割，返回字符串`135-8977-9856`
3. `CONCAT("小明",IF(95>90,"优秀",""))` 按条件拼接，返回字符串`小明优秀`
4. `CONCAT(ARR(1),ARR(2))` 参数为数组，返回数组`[1,2]`
5. `CONCAT(ARR(1),'ab')` 参数为数组和字符串，返回数组`[1,ab]`
6. `CONCAT('ab','','cd')` 参数为空，返回字符串`abcd`
7. `CONCAT('a',' ','b')` 参数含有空格，返回字符串`a b`
8. `CONCAT('@','$',',')` 参数含有特殊字符，返回字符串`@$,`
9. `CONCAT(12,3)` 参数是数字字符，返回字符串`123`
10. `CONCAT(1.2,2.4)` 参数是小数，返回字符串`1.22.4`
11. `CONCAT((1),2)` 参数含有()，没有引号，返回字符串`12`
12. `CONCAT('(1)','2')` 参数含有()，有引号，返回字符串`(1)2`
13. `CONCAT([企业基本信息].[成立日期].[年],'年',[企业基本信息].[成立日期].[月份],'月')` 拼接年和月，返回字符串`2019年06月`
14. `CONCAT(IFNULL([企业基本信息].[法定代表人],''),IFNULL([企业基本信息].[工商注册号],''))` 法定代表人和为空的工商注册号拼接，返回字符串`沈丹婷`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/CONTAINS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/contains"
title: "CONTAINS - 判断字符串中是否包含子字符串"
---
# **CONTAINS**
判断字符串中是否包含子字符串。如果参数**str**中包含子字符串**substr**，则返回 *true* ，否则返回 *false* 。
## 语法{#grammar}
CONTAINS(**str**, **substr**)
- **str**：需要判断的字符串
- **substr**：子字符串
**示例地址：** [CONTAINS](https://demo.succbi.com/v5/bi/contains)
## 示例{#example}
1. `CONTAINS("湖北省武汉市江岸区","武汉")` 查询地址是不是武汉地区，返回`true`
2. `IF(CONTAINS("计算机1603班","03"),"他是三班的")` 返回判断后的信息，返回字符串`他是三班的`
3. `CONTAINS('abcde','ab')` 字符串包含子字符串，返回`true`
4. `CONTAINS('abcde','fd')` 字符串不包含子字符串，返回`false`
5. `CONTAINS('','1')` 字符串为空，返回`false`
6. `CONTAINS('ab cde','b cd')` 字符串包含空格，返回`true`
7. `CONTAINS("ab\tcd","\t")` 字符串含有转义字符，返回`true`
8. `CONTAINS("#$@%!","!")` 字符串为特殊字符，返回`true`
9. `CONTAINS('abcde','')` substr为空，返回`true`，字符串开头结尾是空字符串
10. `CONTAINS('abc','abc')` substr等于原字符串，返回`true`
11. `CONTAINS("abcde",'c'+'d')` substr是表达式，返回`true`
12. `CONTAINS("abcde",'a'|'d')` substr为多个字符串，返回`false`，无法判断多个字串的情况
13. `CONTAINS('','')` str和substr都为空，返回`true`
14. `CONTAINS(A1.[标题],"毛衣")` 引用单元格，判断`A1`的款式是否为毛衣
15. `CONTAINS([门店销售明细表].[款式组合].[款式组合名称],"毛衣")` 引用模型字段，判断款式是否为毛衣
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/FIND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/find"
title: "FIND - 返回一个字符串在另一个字符串中首次出现的位置"
---
# **FIND**
返回一个字符串在另一个字符串中首次出现的位置，从前向后检索。参数 **str** 中的字符位置是从`1`开始的，如果要检索的字符串值没有出现，则返回`0`，查找时区分大小写。
## 语法{#grammar}
FIND(**str**, **find\_value**, **\[start\_index]**)
- **str**：需要检索的字符串
- **find\_value**：需要检索的字符串值
- **start\_index**：可选的非负整数。规定在字符串中开始检索的位置。它的合法取值是 `1` 到 `LEN()`。如省略该参数，则将从字符串的首字符开始检索
**示例地址：** [FIND](https://demo.succbi.com/v5/bi/find)
## 示例{#example}
1. `FIND('abcad','a')` 检索字符串首次出现的位置，返回数值`1`
2. `FIND('abcbcd','c',2)` 从位置2开始查找，返回数值`3`
3. `FIND('abcd','A')` 查找有大小写区分，找不到返回数值`0`
4. `FIND('12311','11')` 参数为数字字符，返回数值`4`
5. `FIND('这是武汉中心','中')` 参数为中文字符，返回数值`5`
6. `FIND(' 2 1','1')` 参数含空格，返回数值`4`，一个空格占一个位置
7. `FIND('#$%&!.','%')` 参数为特殊字符，返回数值`3`
8. `FIND("a\t\nb",'b')` 参数含转义字符，返回数值`4`，转义字符占一个位置
9. `FIND('',2)` 参数为空字符串，返回数值`0`
10. `FIND('123','')` `find_value`为空字符串，返回`0`
11. `FIND(A1,'(','2')` 引用单元格，返回`A1`中`(`的位置
12. `FIND([门店销售明细表].[门店].[门店名称],'(','2')` 引用模型字段，返回`(`的位置
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/LASTFIND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lastfind"
title: "LASTFIND - 返回一个字符串在另一个字符串中最后出现的位置"
---
# **LASTFIND**
返回一个字符串在另一个字符串中最后出现的位置，从后向前检索。参数 **str** 中的字符位置是从`1`开始的，如果要检索的字符串值没有出现，则返回`0`，查找时区分大小写。
## 语法{#grammar}
LASTFIND(**str**, **find\_value**, **\[start\_index]**)
- **str**：需要检索的字符串
- **find\_value**：需要检索的字符串值
- **start\_index**：可选的非负整数。规定在字符串中开始检索的位置。它的合法取值是 `1` 到 `LEN()`。如省略该参数，则将从字符串的尾字符开始检索
**示例地址：** [LASTFIND](https://demo.succbi.com/v5/bi/lastfind)
## 示例{#example}
1. `LASTFIND('abcad','a')` 检索字符串首次出现的位置，返回数值`4`
2. `LASTFIND('abcbcd','c',2)` 从位置2开始查找，返回数值`1`
3. `LASTFIND('abcd','A')` 查找有大小写区分，找不到返回数值`0`
4. `LASTFIND('12311','11')` 参数为数字字符，返回数值`4`
5. `LASTFIND('这是武汉中心','中')` 参数为中文字符，返回数值`5`
6. `LASTFIND(' 2 1','1')` 参数含空格，返回数值`4`，一个空格占一个位置
7. `LASTFIND('#$%&!.','%')` 参数为特殊字符，返回数值`3`
8. `LASTFIND("a\t\nb",'b')` 参数含转义字符，返回数值`4`，转义字符占一个位置
9. `LASTFIND('',2)` 参数为空字符串，返回数值`0`
10. `LASTFIND('123','')` `find_value`为空字符串，返回`0`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SEARCH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/search"
title: "SEARCH - 返回某个指定的字符串值在字符串中首次出现的位置"
---
# **SEARCH**
返回某个指定的字符串值在字符串中首次出现的位置，用法同[FIND](./FIND.md)函数，查找时不区分大小写。
该函数将从头到尾地检索字符串 **str** ，看它是否含有子串 **search\_value** ：
- 开始检索的位置在字符串的 **start\_index** 处或字符串的开头（没有指定 **start\_index** 时）
- 如果找到一个 **search\_value** ，则返回 **search\_value** 的第一次出现的位置。 **str** 中的字符位置是从 1 开始的
- 如果要检索的字符串值没有出现，则该方法返回 `0` 。查找时不区分大小写
## 语法{#grammar}
SEARCH(**str**, **search\_value**, **\[start\_index]**)
- **str**：需要检索的字符串
- **search\_value**：需要检索的字符串值
- **start\_index**：可选的整数参数。规定在字符串中开始检索的位置。它的合法取值是`1`到`len(str)`。如省略该参数，则将从字符串的首字符开始检索
**示例地址：** [SEARCH](https://demo.succbi.com/v5/bi/search)
## 示例{#example}
1. `SEARCH('abcad','a')` 返回检索字符串首次出现的位置`1`
2. `SEARCH('abcbcd','c',2)` 指定检索位置并返回检索字符串首次出现的位置`3`
3. `SEARCH(E31,'(','2')` 引用单元格，返回`(`的位置`4`
4. `SEARCH([门店销售明细表].[门店].[门店名称],'(','2')` 引用模型字段，返回`(`的位置`4`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/STARTSWITH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/startswith"
title: "STARTSWITH - 判断字符串是否以指定的字符串开头"
---
# **STARTSWITH**
判断字符串是否以指定的字符串开头。
## 语法{#grammar}
STARTSWITH(**str**, **prefix**)
- **str**：需要判断的字符串
- **prefix**：指定开头的字符串
如果参数 **str** 以参数 **prefix** 开头，则返回 *true* ，否则为 *false*
**示例地址：** [STARTSWITH](https://demo.succbi.com/v5/bi/startswith)
## 示例{#example}
1. `STARTSWITH("https://www.baidu.com","https")` 判断网址是不是https协议，返回值为`true`
2. `STARTSWITH("421300","42")` 判断行政区划代码是不是属于湖北，返回值为`true`
3. `STARTSWITH('abc','b')` prefix 不在字符串开头，返回值为`false`
4. `STARTSWITH('abc','A')` 区分大小写，返回值为`false`
5. `STARTSWITH('a bc','a b')` 字符串包含空格，返回值为`true`
6. `STARTSWITH(A1,'湖北')` 引用单元格`A1`，判断企业是不是湖北企业
7. `STARTSWITH([企业基本信息].[企业名称],'湖北')` 引用模型字段，判断企业是不是湖北企业
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/ENDSWITH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/endswith"
title: "ENDSWITH - 判断字符串是否以指定的字符串结尾"
---
# **ENDSWITH**
判断字符串是否以指定的字符串结尾。如果参数 **str** 以参数 **suffix** 结尾，则返回 *true* ，否则返回 *false* 。
## 语法{#grammar}
ENDSWITH(**str**, **suffix**)
- **str**：需要判断的字符串
- **suffix**：指定结尾的字符串
**示例地址：** [ENDSWITH](https://demo.succbi.com/v5/bi/endswith)
## 示例{#example}
1. `IF(ENDSWITH("123.exe",".exe"),"这是一个exe执行文件")` 判断文件是不是exe执行文件，返回字符串`这是一个exe执行文件`
2. `ENDSWITH("210502198412020944","020944")` 校验身份证后六位，返回`true`
3. `ENDSWITH("abc",'a')` `suffix`不在字符串的结尾，返回`false`
4. `ENDSWITH("abc",'C')` 区分大小写，返回`false`
5. `ENDSWITH("ab c","b c")` 字符串包含空格，返回`true`
6. `ENDSWITH("abc/t/n",'c')` 转义字符，返回`false`
7. `ENDSWITH("湖北武汉","武汉")` 汉字字符，返回`true`
8. `ENDSWITH(",#￥@a#",'#')` 特殊符号，返回`true`
9. `ENDSWITH("abc",'')` `suffix`为空字符串，返回`true`，字符串以空字符串结尾
10. `ENDSWITH('abc','abc')` `suffix`等于原字符串，返回`true`
11. `ENDSWITH("abc","abcd")` `suffix`长度超过原字符串，返回`false`
12. `ENDSWITH(A1.[标题],"米灰色")` 引用单元格，判断`A1`是否为米灰色款式
13. `ENDSWITH([门店销售明细表].[款式组合],"米灰色")` 引用模型字段，判断是否为米灰色款式
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SAME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/same"
title: "SAME - 返回指定的字符串参数是否和字符串对象在忽略大小写的情况下相等"
---
# **SAME**
返回指定的字符串参数是否和字符串对象在忽略大小写的情况下相等。
## 语法{#grammar}
SAME(**str1**, **str2**)
- **str1**：必需。指定的字符串参数
- **str2**：必需。指定的字符串对象
**示例地址：** [SAME](https://demo.succbi.com/v5/bi/same)
## 示例{#example}
1. `SAME('abc','abc')` 字母字符串一致，返回`true`
2. `SAME('abc','ABC')` 字母字符串分别为大小写，返回`true`
3. `SAME('abc','abcd')` 字母字符串不一致，返回`false`
4. `SAME('abc','NULL')` 字母字符串与NULL，返回`false`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/TRIM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/trim"
title: "TRIM - 删除字符串中首尾的空白符"
---
# **TRIM**
删除字符串中首尾的空白符。
## 语法{#grammar}
TRIM(**str**)
- **str**：必需，给定的字符串对象
**示例地址：** [TRIM](https://demo.succbi.com/v5/bi/trim)
## 示例{#example}
1. `TRIM(' abc 123 文字 ')` 去掉字符串首尾空格，返回`abc 123 文字`
2. `TRIM(A1)` 引用单元格，返回企业变更前信息`变更前：潘立慧`
3. `TRIM(" 变更前：" + [变更信息].[变更前])` 引用模型字段，返回企业变更前信息`变更前：潘立慧`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/LTRIM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/ltrim"
title: "LTRIM - 删除字符串中左侧的空白符"
---
# **LTRIM**
删除字符串中左侧的空白符。
## 语法{#grammar}
LTRIM(**str**)
- **str**：给定的字符串对象
**示例地址：** [LTRIM](https://demo.succbi.com/v5/bi/ltrim)
## 示例{#example}
1. `LTRIM(" ab c ")` 返回`ab c `
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/RTRIM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rtrim"
title: "RTRIM - 删除字符串右侧的空白符"
---
# **RTRIM**
删除字符串右侧的空白符。
## 语法{#grammar}
RTRIM(**str**)
- **str**：给定的字符串对象
**示例地址：** [RTRIM](https://demo.succbi.com/v5/bi/rtrim)
## 示例{#example}
1. `RTRIM("ab c ")` 返回字符串`ab c`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/REPLACE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/replace"
title: "REPLACE - 替换字符串中的特定子字符串"
---
# **REPLACE**
替换字符串中的特定子字符串。
## 语法{#grammar}
REPLACE(**str**, **substr**, **newsubstr**)
- **str**：必需。将要执行替换操作的字符串
- **substr**：必需。要替换的特定子字符串
- **newsubstr**：必需。将替换substr特定字符串的另一个字符串
**示例地址：** [REPLACE](https://demo.succbi.com/v5/bi/replace)
## 示例{#example}
1. `REPLACE("abc","a","A")` 字符串中字母的替换，返回字符串`Abc`
2. `REPLACE("abc","e","f")` substr字符串不在str字符串中，返回字符串`abc`
3. `REPLACE("abc","abcde","xyz")` substr超过str字符串内容，返回字符串`abc`
4. `REPLACE("!@#","#","&")` 特殊字符的替换，返回字符串`!@&`
5. `REPLACE(A1,"服饰","fushi")` 引用单元格`A1`，返回字符串`盛利fushi(鼓楼南街店)`
6. `REPLACE([门店销售明细表].[门店].[门店名称],"服饰","fushi")` 引用模型字段，返回字符串`盛利fushi(鼓楼南街店)`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/REGEXP_EXTRACT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/regexp_extract"
title: "REGEXP_EXTRACT - 返回与正则表达式匹配的子字符串"
---
# **REGEXP\_EXTRACT**
返回与正则表达式匹配的子字符串。
此函数会在指定的字符串中查找符合正则表达式的内容， **index** 为空默认返回第一个匹配的子字符串，未匹配则返回空字符串。
## 语法{#grammar}
REGEXP\_EXTRACT(**str**, **pattern**, **\[index]**)
- **str**：给定的字符串对象
- **pattern**：一个用于匹配字符串的正则表达式，正则表达式中的`\`需要连续输入2个，第一个`\`表示转义。[正则表达式的语法参考](https://www.runoob.com/regexp/regexp-intro.html)
- **index**：可选，匹配的子字符串索引， 1 表示返回第一个匹配的子字符串
**示例地址：** [REGEXP\_EXTRACT](https://demo.succbi.com/v5/bi/regexp_extract)
## 示例{#example}
1. `REGEXP_EXTRACT("abc123","[0-9]+")` 提取数字，返回字符串`123`，`index`为空默认返回第一个匹配项
2. `REGEXP_EXTRACT("ab4c123","[0-9]",2)` 提取第二个匹配的数字，返回字符串`1`
3. `REGEXP_EXTRACT("12.34","\\d*(?=\\.)")` 提取小数部分的整数部分，返回字符串`12`
4. `REGEXP_EXTRACT("我Cd123","[A-Z][a-z]")` 提取字母，返回字符串`Cd`
5. `REGEXP_EXTRACT("123小明AB","[\\u4e00-\\u9fa5]+")` 提取人名，返回字符串`小明`
6. `REGEXP_EXTRACT("13487598742","[0-9]{4}$")` 提取手机号后四位，返回字符串`8742`
7. `REGEXP_EXTRACT("210502198412020944","\\d{8}(?=\\d{4}$)")` 提取身份证的出生年月，返回字符串`19841202`
8. `REGEXP_EXTRACT("月亮在5月12日最亮","\\d{1,2}月\\d{1,2}日")` 提取文本中的日期，返回字符串`5月12日`
9. `REGEXP_EXTRACT("在https://www.baidu.com中下载","https?://.+?(com|cn|net).*?")` 提取文本中的网址，返回字符串`https://www.baidu.com`
10. `REGEXP_EXTRACT("我的邮箱是xxxx@qq.com","[\\w]+(\\.[\\w]+)*@[\\w]+(\\.[\\w]*)")` 提取文本中的qq邮箱，返回字符串`xxxx@qq.com`
11. `REGEXP_EXTRACT("ip地址是192.168.2.3","(25[0-5]|2[0-4]\\d|[0-1]?\\d?\\d)(\\.(25[0-5]|2[0-4]\\d|[0-1]?\\d?\\d)){3}")` 提取文本中的ipv4地址，返回字符串`192.168.2.3`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/REGEXP_REPLACE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/regexp_replace"
title: "REGEXP_REPLACE - 替换字符串中与正则表达式匹配的子字符串"
---
# **REGEXP\_REPLACE**
替换字符串中与正则表达式匹配的子字符串。
## 语法{#grammar}
REGEXP\_REPLACE(**str**, **pattern**, **replacement**)
- **str**：需要被替换的字符串对象
- **pattern**：一个用于匹配字符串的正则表达式，正则表达式中的`\`需要连续输入2个，第一个`\`表示转义。[正则表达式的语法参考](https://www.runoob.com/regexp/regexp-intro.html)
- **replacement**：替换 pattern 的子串
**示例地址：** [REGEXP\_REPLACE](https://demo.succbi.com/v5/bi/regexp_replace)
## 示例{#example}
1. `REGEXP_REPLACE("abc123", "[0-9]", "-")` 将数字替换成减号，返回字符串`abc---`
2. `REGEXP_REPLACE("abc123","[a-z]","-")` 将字母替换为减号，返回字符串`---123`
3. `REGEXP_REPLACE("abca","ab","-")` 参数为字母字符，返回字符串`-ca`
4. `REGEXP_REPLACE("abc123", "[^\\d]+", "")` 将非数字字母去除，返回字符串`123`
5. `REGEXP_REPLACE("一二三一","一二","-")` 参数为中文字符，返回字符串`-三一`
6. `REGEXP_REPLACE("备 刘", "(\\S+)\\s(\\S+)", "$2$1")` 将英文格式的人名改成中文格式，返回字符串`刘备`
7. `REGEXP_REPLACE('12345678','(\\d)(?=(\\d{3})+$)','$1,')` 数字加上千分符，返回字符串`12,345,678`
8. `REGEXP_REPLACE('+86 13856427896','(\\+[0-9]{2})( )([0-9]{3})([0-9]{4})([0-9]{4})','($1)$3-$4-$5')` 手机号格式化，返回字符串`(+86)138-5642-7896`
9. `REGEXP_REPLACE('6226090219298748','([0-9]{4})([0-9]{4})([0-9]{4})([0-9]{4})','$1 $2 $3 $4')` 银行卡号用空格分开，返回字符串`6226 0902 1929 8748`
10. `REGEXP_REPLACE('20210510','([0-9]{4})([0-9]{2})([0-9]{2})','$1年$2月$3日')` 日期格式替换，返回字符串`2021年05月10日`
11. `REGEXP_REPLACE('12ab_A','[0-9A-Za-z_]','*')` 数据加密，返回字符串`******`
12. `REGEXP_REPLACE('12\n34','\n','')` 删除转义字符，返回字符串`1234`
13. `REGEXP_REPLACE([门店销售明细表].[导购员].[员工姓名],'刘宏雨','刘 宏雨')` 引用数据模型，员工姓和名用空格隔开，返回字符串`刘 宏雨`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/REGEXP_MATCH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/regexp_match"
title: "REGEXP_MATCH - 判断是否匹配正则表达式"
---
# **REGEXP\_MATCH**
判断是否匹配正则表达式。完全不匹配才返回 *false* 。
## 语法{#grammar}
REGEXP\_MATCH(**str**, **pattern**)
- **str**：给定的字符串对象
- **pattern**：一个用于匹配字符串的正则表达式，正则表达式中的`\`需要连续输入2个，第一个`\`表示转义。[正则表达式的语法参考](https://www.runoob.com/regexp/regexp-intro.html)
**示例地址：** [REGEXP\_MATCH](https://demo.succbi.com/v5/bi/regexp_match)
## 示例{#example}
1. `REGEXP_MATCH("abc123","[0-9]")` 数字校验，返回`true`，匹配0到9中的一个字符
2. `REGEXP_MATCH("1234",'^-?\\d+$')` 整数校验，返回`true`
3. `REGEXP_MATCH("23","^[1-9]\d*$")` 正整数校验，返回`true`，首位不为0
4. `REGEXP_MATCH("Admin_123456","^[a-zA-Z]\\w{5,17}$")` 密码复杂度校验，返回`true`，只允许为数字、英文、下划线并以字母开头，长度为6-18
5. `REGEXP_MATCH("13598224932","^((13[0-9]{1})|(15[0-9]{1})|(18[0-9]{1}))\\d{8}$")` 手机号码校验，返回`true`，匹配手机号是否为`13*`、`15*`、`18*`的11位数字
6. `REGEXP_MATCH("210502198412020944","^[1-9]\\d{5}(18|19|20)\\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx]")` 身份证校验，返回`true`
7. `REGEXP_MATCH("我是小明","明")` 汉字校验，返回`true`
8. `REGEXP_MATCH("xxxx@qq.con","[\\w]+(\.[\\w]+)*@[\\w]+(\.[\\w]?)")` 邮箱校验，返回`true`，匹配qq邮箱
9. `REGEXP_MATCH("420107","[1-8][1-7]\\d{4}")` 行政区划校验，返回`true`，匹配区划编码
10. `REGEXP_MATCH("https://www.baidu.com","^https?://.+?(com|cn|net).*?")` 网址校验，返回`true`，匹配http和https协议
11. `REGEXP_MATCH("AbCd","[A-Z]")` 英文字符，返回`true`
12. `REGEXP_MATCH("192.168.2.3","^(25[0-5]|2[0-4]\\d|[0-1]?\\d?\\d)(\.(25[0-5]|2[0-4]\\d|[0-1]?\\d?\\d)){3}$")` ipv4地址校验，返回`true`
13. `REGEXP_MATCH([门店销售明细表].[销售日期],"20180414")` 引用模型字段，匹配日期
### 常用人名校验
1. `REGEXP_MATCH("小明",'^[\\u4e00-\\u9fa5]{2,4}$')` 常见中国人名校验，匹配2-4位中文人名
2. `REGEXP_MATCH("疗𦬅旺",'^((?![\\u3000-\\u303F])[\\u2E80-\\uFE4F]|·)*(?![\\u3000-\\u303F])[\\u2E80-\\uFE4F]$')` 中国人名（含生僻字）校验，排除中文句号逗号、书名号等汉字符号，并包含少数民族姓名
3. `REGEXP_MATCH("Tony Park",'^[A-Z][a-z]+\\s[A-Z][a-z]+$')` 标准英文人名校验（姓和名首字母大写）
4. `REGEXP_MATCH("疗𦬅旺",'^[A-Z][a-z]+\\s[A-Z][a-z]+$') OR REGEXP_MATCH("疗𦬅旺",'^((?![\\u3000-\\u303F])[\\u2E80-\\uFE4F]|·)*(?![\\u3000-\\u303F])[\\u2E80-\\uFE4F]$')` 中英文人名（含生僻字）校验，中英文分开校验用 OR 连接
::: tip Java和JavaScript正则表达式的区别
前后端正则匹配生僻字结果不一样，Java和JavaScript的正则匹配遇到代理对时处理逻辑不一样，大部分的校验都是前端JavaScript实现的校验，若遇到需要特殊处理下
- JavaScript会分开匹配每个code，无法写代理对的范围，可以绕开类似用`[\\u3000-\\u303F][\\u2E80-\\uFE4F]`来表示范围
- Java把属于一个字符的两个code作为整体匹配，并且只能通过代理对的范围匹配，类似于`[\\u3000\\u2E80-\\u303F\\uFE4F]`来表示范围
:::
### 复杂中国人名校验
复杂中国人名校验，包含生僻字，中文及少数民族姓名并排除中英文特殊符号、颜文字和emoji，demo地址：[校验中国人名](https://demo.succbi.com/v5/demo-spg/%E6%A0%A1%E9%AA%8C%E4%B8%AD%E5%9B%BD%E4%BA%BA%E5%90%8D)
:::details 表达式示例
`//比较广泛的中文汉字（\\u2E80-\\uFE4F），包含生僻字和很多不需要的字符
(
REGEXP_MATCH("张三",'^((?![\\u3000-\\u303F])[\\u2E80-\\uFE4F])*$')//常见人名含生僻字
OR
REGEXP_MATCH("张三",'^((?![\\u3000-\\u303F])[\\u2E80-\\uFE4F])+(·)((?![\\u3000-\\u303F])[\\u2E80-\\uFE4F])+$')//少数民族姓名含生僻字
)
//排除CJK标点符号(\\u3000-\\u303F)
AND
(
REGEXP_MATCH("张三",'^((?![\\uFE30-\\uFE4F])[\\u2E80-\\uFE4F])*$')//常见人名含生僻字
OR
REGEXP_MATCH("张三",'^((?![\\uFE30-\\uFE4F])[\\u2E80-\\uFE4F])+(·)((?![\\uFE30-\\uFE4F])[\\u2E80-\\uFE4F])+$')//少数民族姓名含生僻字
)
//排除CJK兼容符号（\\uFE30-\\uFE4F）包括竖排变体、下划线、顿号
AND
(
REGEXP_MATCH("张三",'^((?!([\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF][\\u200D|\\uFE0F]|[\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF]|[0-9|*|#]\\uFE0F\\u20E3|[0-9|#]\\u20E3|[\\u203C-\\u3299]\\uFE0F\\u200D|[\\u203C-\\u3299]\\uFE0F|[\\u2122-\\u2B55]|\\u303D|[\\A9|\\AE]\\u3030|\\uA9|\\uAE|\\u3030))[\\u2E80-\\uFE4F])*$')//常见人名含生僻字
OR
REGEXP_MATCH("张三",'^((?!([\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF][\\u200D|\\uFE0F]|[\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF]|[0-9|*|#]\\uFE0F\\u20E3|[0-9|#]\\u20E3|[\\u203C-\\u3299]\\uFE0F\\u200D|[\\u203C-\\u3299]\\uFE0F|[\\u2122-\\u2B55]|\\u303D|[\\A9|\\AE]\\u3030|\\uA9|\\uAE|\\u3030))[\\u2E80-\\uFE4F])+(·)((?!([\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF][\\u200D|\\uFE0F]|[\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF]|[0-9|*|#]\\uFE0F\\u20E3|[0-9|#]\\u20E3|[\\u203C-\\u3299]\\uFE0F\\u200D|[\\u203C-\\u3299]\\uFE0F|[\\u2122-\\u2B55]|\\u303D|[\\A9|\\AE]\\u3030|\\uA9|\\uAE|\\u3030))[\\u2E80-\\uFE4F])+$')//少数民族姓名含生僻字
)
//排除颜文字和emoji表情符号（[\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF][\\u200D|\\uFE0F]|[\\uD83C|\\uD83D|\\uD83E][\\uDC00-\\uDFFF]|[0-9|*|#]\\uFE0F\\u20E3|[0-9|#]\\u20E3|[\\u203C-\\u3299]\\uFE0F\\u200D|[\\u203C-\\u3299]\\uFE0F|[\\u2122-\\u2B55]|\\u303D|[\\A9|\\AE]\\u3030|\\uA9|\\uAE|\\u3030）`
:::
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/CLEAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/clean"
title: "CLEAN - 删除字符串中不能打印的字符"
---
# **CLEAN**
删除字符串中不能打印的字符。主要为ASCII码32及以前的字符。
## 语法{#grammar}
CLEAN(**str**)
- **str**：待处理的字符串
**示例地址：** [CLEAN](https://demo.succbi.com/v5/bi/clean)
## 示例{#example}
1. `CLEAN(NULL+'text')` 删除了字符串中的NULL，返回`text`
2. `CLEAN(char(9)+"text"+char(10))` 删除了字符串中不能打印的字符char(9) 和 char(10)，返回`text`
3. `CLEAN('a b c')` 参数中有空格时，不会删除空格，返回`a b c`
4. `CLEAN([门店月销汇总表].[年月])` 参数为年月，返回删除不能打印字符后的值，返回`201806`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SPLIT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/split"
title: "SPLIT - 按指定分隔符分割字符串"
---
# **SPLIT**
按指定分隔符分割字符串。
依照指定分割符分割字符串，返回分隔后的字符串数组。
## 语法{#grammar}
SPLIT(**str**, **separator**)
- **str**：必需，要分割的字符串。
- **separator**：必需，分隔符，如 `","`、`" "`、`"|"`、`"-"`、`"."` 等。
**示例地址：** [SPLIT](https://demo.succbi.com/v5/bi/split)
## 示例{#example}
1. `SPLIT("a，b，c","，")` 按`，`（中文逗号）分割，返回数组`["a","b","c"]`
2. `SPLIT("abc 123 文字"," ")` 按空格分割，返回数组`["abc","123","文字"]`
3. `SPLIT("一句话。下一句。再下一句","。")` 按句号分割，返回数组`["一句话","下一句","再下一句"]`
4. `SPLIT(A1,"-")` 按`-`分割单元格`A1`的值
5. `SPLIT("abc 123 文字","")` 分割符为空字符串时将逐个字符分割，返回数组`["a","b","c"," ","1","2","3"," ","文","字"]`
6. `SPLIT("a？bc<>d efg",null)` 分割为null时没有可分割的内容，返回数组`["a？bc<>d efg"]`
7. `SPLIT("",",")` 带分割字符串为空串时返回空数组`[]`
8. `SPLIT(null,",")` 带分割字符串为空串时返回null
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/MD5.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/md5"
title: "MD5 - 对字符串进行加密"
---
# **MD5**
对字符串进行加密。
## 语法{#grammar}
MD5(**str**)
- **str**：需要进行加密的字符串对象
**示例地址：** [MD5](https://demo.succbi.com/v5/bi/md5)
## 示例{#example}
1. `MD5("abc")` 加密字母，返回`900150983cd24fb0d6963f7d28e17f72`
2. `MD5(A1)` 加密事实表对象，引用单元格，返回`84ddfb34126fc3a48ee38d7044e87276`
3. `MD5([门店销售明细表].[日销单明细ID]+[门店销售明细表].[销售日期])` 拼接多条字段，取字段的MD5，该加密是通过数据库SQL计算的，返回`a0576fea08cc0d69cc67079d667e2685`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SHA1.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sha1"
title: "SHA1 - 使用哈希算法给数据加密"
---
# **SHA1**
使用哈希算法给数据加密。
用法同[MD5()](./MD5.md)，但是相比之下[MD5()](./MD5.md)更安全一些。
## 语法{#grammar}
SHA1(**str**)
- **str**：需要进行加密的字符串对象
**示例地址：** [SHA1](https://demo.succbi.com/v5/bi/sha1)
## 示例{#example}
1. `SHA1("String")` 参数为字符串，返回`3df63b7acb0522da685dad5fe84b81fdd7b25264`
2. `SHA1(12345.6789012345)` 参数为数字，转为字符串加密`aa5723f70d092e20535a89d9ceb54032c6a1c0c5`
3. `SHA1(A1)` 引用单元格，加密门店名称`a556821067e9c2a320046df0b373c8119f5c978c`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/UUID.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/uuid"
title: "UUID - 返回一个128位二进制的唯一字符串"
---
# **UUID**
返回一个128位二进制的唯一字符串，每次使用该函数返回的字符串都不相同。
**示例地址：** [UUID](https://demo.succbi.com/v5/bi/uuid)
## 示例{#example}
1. `UUID()` 生成一个唯一字符串`ac1f17c0afb148a8a2668339e2893860`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/SEQNUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/seqnum"
title: "SEQNUM - 返回一个自增长序列号"
---
# **SEQNUM**
返回一个自增长序列号。
此函数产生一个数字编号给客户端，可用于生成流水号、序列号，这个数字会确保在当前服务器环境（含集群）中不会重复。
## 语法{#grammar}
SEQNUM(**namespace**)
- **namespace**：必需，序列名称，用于标识这个序列。比如当一个表单有两个需要自动递增的序列时，各自独立的递增，就需要设置不同的 namespace
**示例地址：** [SEQNUM](https://demo.succbi.com/v5/bi/seqnum)
## 示例{#example}
1. `SEQNUM('exp-test-2021')` 参数为字符串，返回自增长序列号
2. `SEQNUM(2021)` 参数为数值，返回自增长序列号
3. `SEQNUM(USER_PROPERTY('id'))` 参数为动态变化的表达式，返回自增长序列号
4. `SEQNUM('exp-test-2020')+'-'+SEQNUM('exp-test-2021')` 拼接多个序列号，返回自增长序列号的拼接值
5. `"鄂市监-"+SEQNUM(A1)` 实施机关检查抽查序列号，引用单元格`A1`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/ESCAPE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/escape"
title: "ESCAPE - 对指定类型的内容进行转义编码"
---
# **ESCAPE**
对指定类型的内容进行转义编码。解码使用[UNESCAPE](./UNESCAPE.md)函数。
## 语法{#grammar}
ESCAPE(**content**, **contentType**)
- **content**：要编码的内容
- **contentType**：指定内容的类型，支持四种内容类型**html** 、**js** 、**html-attr**
**示例地址：** [ESCAPE](https://demo.succbi.com/v5/bi/escape)
## 示例{#example}
1. `ESCAPE('', 'html');` 转义html，返回字符串`<script>alert("XSS")</script>`
2. `ESCAPE('Image "Logo"', 'html-attr');` 转义html属性，返回字符串`Image "Logo"`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/UNESCAPE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/unescape"
title: "UNESCAPE - 对指定类型的内容进行解码"
---
# **UNESCAPE**
对指定类型的内容进行解码。编码使用[ESCAPE](./ESCAPE.md)函数。
## 语法{#grammar}
UNESCAPE(**content**, **contentType**)
- **content**：要解码的内容
- **contentType**：指定内容的类型，支持四种内容类型**html** 、**js** 、**html-attr**
**示例地址：** [UNESCAPE](https://demo.succbi.com/v5/bi/unescape)
## 示例{#example}
1. `UNESCAPE('用户输入：<strong>Hello&World</strong>', 'html')` URL参数解码，返回字符串`用户输入：Hello&World`
2. `UNESCAPE('Hello\\x20\\x22World\\x22\\x0A', 'js');` js内容解码，返回字符串`Hello "World"\n`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/CHAR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/char"
title: "CHAR - 返回ASCII码对应的字符"
---
# **CHAR**
返回ASCII码对应的字符。
## 语法{#grammar}
CHAR(**num**)
- **num**：需要转换的ASCII码，用10进制表示
**示例地址：** [CHAR](https://demo.succbi.com/v5/bi/char)
## 示例{#example}
1. `CHAR(33)` 返回ASCII码33对应的字符特殊符号`!`
2. `CHAR(48)` 返回ASCII码48对应的字符数字`0`
3. `CHAR(65)` 返回ASCII码65对应的字符大写字母`A`
4. `CHAR(97)` 返回ASCII码97对应的字符小写字母`a`
5. `CHAR(32)` 返回ASCII码32对应的字符空格` `
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/REPT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rept"
title: "REPT - 按照给定的次数重复拼接字符串"
---
# **REPT**
按照给定的次数重复拼接字符串。
## 语法{#grammar}
REPT(**str**, **count**)
- **str**：给定的字符串对象
- **count**：重复拼接的次数，必须为大于0的正整数
**示例地址：** [REPT](https://demo.succbi.com/v5/bi/rept)
## 示例{#example}
1. `REPT("abc",3)` 拼接字母，返回字符串`abcabcabc`
2. `REPT("123",2)` 拼接数字，返回字符串`123123`
3. `REPT("a bc",2)` 字符参数带空格，返回字符串`a bca bc`
4. `REPT([门店月销汇总表].[尺码],2)` 引用模型字段，返回字符串`0303`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/CODE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/code"
title: "CODE - 返回字符对应的ASCII码"
---
# **CODE**
返回字符对应的ASCII码。
返回的代码对应于本机所使用的字符集。
## 语法{#grammar}
CODE(**char**)
- **char**：需要转换的字符，字符数大于1时只取首字符的ASCII码
**示例地址：** [CODE](https://demo.succbi.com/v5/bi/code)
## 示例{#example}
1. `CODE('!')` 参数为特殊字符，返回字符"!"对应的ASCII码`33`
2. `CODE('0')` 参数为数字，返回字符"0"对应的ASCII码`48`
3. `CODE('A')` 参数为大写字母，返回字符"A"对应的ASCII码`65`
4. `CODE('a')` 参数为小写字母，返回字符"a"对应的ASCII码`97`
5. `CODE(' ')` 参数为空格，返回字符" "对应的ASCII码`32`
6. `CODE('abcd')` 参数为多个字符，返回首字符的ASCII码`97`
7. `CODE('测试')` 参数为文字，返回首个文字的ASCII码`27979`
8. `CODE('A1')` 返回A1单元格首字符的ASCII码`83`
9. `CODE([门店销售明细表].[门店])` 返回门店首字符的ASCII码`83`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/ENCODEURI.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/encodeuri"
title: "ENCODEURI - 编码URI"
---
# **ENCODEURI**
编码URI。该方法的目的是对URI进行完整的编码，如下情况不会编码：
- ASCII字母和数字
- ASCII标点符号，包括：`-_.!~*'()`
- 具有特殊含义的ASCII标点符号，包括：`;/?:@&=+$,#`
## 语法{#grammar}
ENCODEURI(**uri**)
- **uri**：必需。一个含有URI或其他要编码的字符串，其他对象将转为字符串对象
**示例地址：** [ENCODEURI](https://demo.succbi.com/v5/bi/encodeuri)
## 示例{#example}
1. `ENCODEURI("http://www.w3school.com.cn")` 参数含有数字字母，返回字符串`http://www.w3school.com.cn`，不转义URI分隔符`:`、`/`
2. `ENCODEURI("http://www.w3school.com.cn/My first/")` 参数含有数字字母和空格，返回字符串`http://www.w3school.com.cn/My%20first/`，不转义URI分隔符`:`、`/`
3. `ENCODEURI("search=中文")` 参数含有中文，返回字符串`search=%E4%B8%AD%E6%96%87`
4. `ENCODEURI("/?:@&=+$#")` 参数含有`/?:@&=+$#`特殊字符，返回字符串`/?:@&=+$#`，不转义URI分割符
5. `ENCODEURI("- _ . ! ~ * ' ( )")` 参数含有ASCII标点符号，返回字符串`-%20_%20.%20!%20~%20*%20'%20(%20)`
6. `ENCODEURI("")` 参数为空字符串，返回空字符串
7. `ENCODEURI(NULL)` 参数为NULL，返回`null`
8. `ENCODEURI(NOW())` 参数为函数返回值，返回`20220509`，转为字符串运算
9. `ENCODEURI(FALSE)` 参数为布尔型，返回`false`
10. `ENCODEURI(A1)` 引用单元格，对`A1`表示的网址进行编码
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/ENCODEURICOMPONENT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/encodeuricomponent"
title: "ENCODEURICOMPONENT - 编码 URI 参数"
---
# **ENCODEURICOMPONENT**
编码 URI 参数。如下情况不会编码：
- ASCII 字母和数字
- ASCII 标点符号，包括：`-_.!~*'()`
请注意 ENCODEURICOMPONENT()函数与[ENCODEURI()](./ENCODEURI.md) 函数的区别之处，前者假定它的参数是 URI 的一部分（比如协议、主机名、路径或查询字符串），因此将转义用于分隔 URI 各个部分的标点符号，比如：`;/?:@&=+$,#`
## 语法{#grammar}
ENCODEURICOMPONENT(**str**)
- **str**：必需。一个含有URI组件或其他要编码的字符串，其他对象将转为字符串对象
**示例地址：** [ENCODEURICOMPONENT](https://demo.succbi.com/v5/bi/encodeuricomponent)
## 示例{#example}
1. `ENCODEURICOMPONENT("http://www.w3school.com.cn")` 参数含有数字字母，返回字符串`http%3A%2F%2Fwww.w3school.com.cn`，转义URI分隔符 `:`、`/`
2. `ENCODEURICOMPONENT("http://www.w3school.com.cn/My first/")` 参数含有数字字母和空格，返回字符串`http%3A%2F%2Fwww.w3school.com.cn%2FMy%20first%2F`，转义URI分隔符 `:`、`/`
3. `ENCODEURICOMPONENT("search=中文")` 参数含有中文，返回字符串`search%3D%E4%B8%AD%E6%96%87`
4. `ENCODEURICOMPONENT("/?:@&=+$#")` 参数含有`/?:@&=+$#`特殊字符，返回字符串`%2F%3F%3A%40%26%3D%2B%24%23`，转义用于分割URI的标点符号
5. `ENCODEURICOMPONENT("-_.!~*'()")` 参数含有ASCII标点符号，返回字符串`-_.!~*'()`
6. `ENCODEURICOMPONENT(A1)` 引用单元格，返回`A1`编码后的字符串
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/ESCAPE_HTML.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/escape_html"
title: "ESCAPE_HTML - 对指定类型的内容进行HTML转义编码"
---
# **ESCAPE\_HTML**
对指定类型的内容进行HTML转义编码。解码使用[UNESCAPE\_HTML](./UNESCAPE_HTML.md)函数。
## 语法{#grammar}
ESCAPE\_HTML(**content**)
- **content**：要编码的HTML内容
**示例地址：** [ESCAPE\_HTML](https://demo.succbi.com/v5/bi/escape_html)
## 示例{#example}
1. `ESCAPE_HTML('');` 返回字符串`<script>alert("XSS")</script>`
---
url: "https://docs.succapp.com/v5/guide/exp/func/string/UNESCAPE_HTML.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/unescape_html"
title: "UNESCAPE_HTML - 对指定类型的内容进行HTML解码"
---
# **UNESCAPE\_HTML**
对指定类型的内容进行HTML解码。编码使用[ESCAPE\_HTML](./ESCAPE_HTML.md)函数。
## 语法{#grammar}
UNESCAPE\_HTML(**content**)
- **content**：要解码的HTML内容
**示例地址：** [UNESCAPE\_HTML](https://demo.succbi.com/v5/bi/unescape_html)
## 示例{#example}
1. `UNESCAPE_HTML('用户输入：<strong>Hello&World</strong>')` 返回字符串`用户输入：Hello&World`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/data-funcs"
title: "日期函数列表"
---
---
navTitle: 日期函数
---
# 日期函数列表
!!!children (guide/exp/func/date)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/TODAY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/today"
title: "TODAY - 返回当前日期"
---
# **TODAY**
返回当前日期。默认格式为yyyy-mm-dd。
默认只有年、月份、天数三个属性，小时、分钟数、秒数为0。
**示例地址：** [TODAY](https://demo.succbi.com/v5/bi/today)
## 示例{#example}
1. `TODAY()` 返回当前时间`2022-05-05`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/NOW.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/now"
title: "NOW - 返回当前日期和时间"
---
# **NOW**
返回当前日期和时间，默认格式为yyyy-mm-dd hh:mi:ss。精确到毫秒。
**示例地址：** [NOW](https://demo.succbi.com/v5/bi/now)
## 示例{#example}
1. `NOW()` 返回当前时间`2022-05-05 15:07:41`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/DATE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/date"
title: "DATE - 返回时间戳类型"
---
# **DATE**
返回时间戳类型。
参数可以按顺序指定任意多个，如只指定了**year**参数，那么返回的日期对象将只包含年份，其他属性为0。省略时返回当前时间的天数，和[NOW()](./NOW.md)函数的返回值相同。
## 语法{#grammar}
DATE(**year**, **month**, **day**, **hour**, **minute**, **second**)
- **year**： 一个四位整数，表示日期的年份
- **month**：1-12的整数，表示一年中的月份
- **day**：1-31的整数，表示一个月中的天数
- **hour**：0-23的整数，表示一天中的小时数
- **minute**：0-59的整数，表示一个小时中的分钟
- **second**：0-59的整数，表示一分钟中的秒数
**示例地址：** [DATE](https://demo.succbi.com/v5/bi/date)
## 示例{#example}
1. `DATE(2020,7,15,16,20,3)` 返回表示日期时间的数字`2020-07-15 16:20:03`
2. `DATE(2020)` 输入值只有年，返回`2020`
3. `DATE(2020,7)` 输入值只有年月，返回`2020-07`
4. `DATE(2020,7,15)` 输入值只有年月日，返回`2020-07-15`
5. `DATE(2020,7,15,16)` 输入值省略分、秒，返回`2020-07-15 16`
6. `DATE(2020,7,15,16,20)` 输入值省略秒，返回`2020-07-15 16:20`
7. `DATE(A1,B1)` 引用单元格数值，返回销售日期`2018-12-01`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/YEAR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/year"
title: "YEAR - 返回日期对象的年份值"
---
# **YEAR**
返回日期对象的年份值，返回值为 1900 到 9999 之间的整数。
## 语法{#grammar}
YEAR(**date**)
- **date**：可选，日期类型或日期类型字符串。省略时返回当前时间的年份
**示例地址：** [YEAR](https://demo.succbi.com/v5/bi/year)
## 示例{#example}
1. `YEAR()` 返回当前时间的年份`2022`
2. `YEAR("20200716")` 日期格式为yyyyddmm返回年份`2020`
3. `YEAR("2020-07-16")`日期格式为yyyy-dd-mm返回年份`2020`
4. `YEAR("2020/07/16")` 日期格式为yyyy/dd/mm返回年份`2020`
5. `YEAR("2020.07.16")` 日期格式为yyyy.dd.mm返回年份`2020`
6. `YEAR(A1)` 静态字段获取A1的值，返回日期中的年份`2017`
7. `YEAR([门店销售明细表].[销售日期])` 数据库字段获取销售日期，返回日期中的年份`2017`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/MONTH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/month"
title: "MONTH - 返回日期对象的月份值"
---
# **MONTH**
返回日期对象的月份值，返回值是 1 ~ 12 之间的一个整数。
## 语法{#grammar}
MONTH(**date**)
- **date**：可选，日期类型或日期类型字符串。省略时返回当前时间的月份
**示例地址：** [MONTH](https://demo.succbi.com/v5/bi/month)
## 示例{#example}
1. `MONTH()` 返回当前时间的月份`4`
2. `MONTH("20200716")` 日期格式为yyyyddmm返回月份`7`
3. `MONTH("2020/07/16")` 日期格式为yyyy/mm/dd返回月份`7`
4. `MONTH("2020.07.16")` 日期格式为yyyy.mm.dd返回月份`7`
5. `MONTH("2020-07-16")` 日期格式为yyyy-mm-dd返回月份`7`
6. `MONTH(A1)` 静态字段获取A1的值，返回日期中的月份`12`
7. `MONTH([门店销售明细表].[销售日期])` 数据库字段获取销售日期，返回日期中的月份`12`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/DAY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/day"
title: "DAY - 返回日期对象中的日"
---
# **DAY**
返回日期对象中的日。
## 语法{#grammar}
DAY(**date**)
- **date**：可选，日期类型或日期类型字符串。省略时返回当前时间的天数
**示例地址：** [DAY](https://demo.succbi.com/v5/bi/day)
## 示例{#example}
1. `DAY()` 返回当前日期中的天数`25`
2. `DAY("20200716")` 日期格式为yyyyddmm返回天数`16`
3. `DAY("2020-07-16")` 日期格式为yyyy-mm-dd返回天数`16`
4. `DAY("2020/07/16")` 日期格式为yyyy/mm/dd返回天数`16`
5. `DAY("2020.07.16")` 日期格式为yyyy.mm.dd返回天数`16`
6. `DAY(DATE(2021,1,26,0,1,1))` 转换为日期对象后返回日期的天数`26`
7. `DAY(TODATE("20210126000001","yyyymmddhhmmss"))` 返回日期对象后返回日期的天数`26`
8. `DAY(A1)` 静态字段获取A1的值，返回日期中的天数`11`
9. `DAY([门店销售明细表].[销售日期])` 数据库字段获取销售日期，返回日期中的天数`11`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/DATEDIF.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/datedif"
title: "DATEDIF - 返回两个日期之间的天数、月数或年数"
---
# **DATEDIF**
返回两个日期之间的天数、月数或年数。返回的天数不包含结束日期，返回的月份会包含结束月份，返回的年份会包括结束年份。
## 语法{#grammar}
DATEDIF(**dateStart**, **dateEnd**, **\[type]**)
- **dateStart**：必需，起始日期
- **dateEnd**：必需，结束日期
- **type**：可选，计算类型，默认计算的是两个日期之间相隔的年份，详见[时间间隔类型](../../types.md#relative)
**示例地址：** [DATEDIF](https://demo.succbi.com/v5/bi/datedif)
## 示例{#example}
1. `DATEDIF("20200715","20210716","y")` 返回日期之间相隔的年数，返回数值`1`
2. `DATEDIF("20200715","20180717","y")` 结束日期小于起始日期，返回数值`-2`
3. `DATEDIF("20200715","20210716","m")` 返回两个日期之间的月数，返回数值`12`
4. `DATEDIF("20200715","20210716","d")` 返回两个日期之间的天数，返回数值`366`
5. `DATEDIF("20200715","20210915","ym")` 返回两个日期之间相隔的月份，忽略年份，返回数值`2`
6. `DATEDIF("20120101", "20130202", "yd")` 返回两个日期之间相隔的天数，忽略年份，返回数值`32`
7. `DATEDIF("20120101", "20130202", "md")` 返回两个日期之间相隔的天数，忽略年份和月份，返回数值`1`
8. `DATEDIF("2020-07-21","2020-07-23","d")` 日期格式为yyyy-mm-dd，返回数值`2`
9. `DATEDIF("2020.07.21","2020.07.23","d")` 日期格式为yyyy.mm.dd，返回数值`2`
10. `DATEDIF("2020/07/21","2020/07/23","d")` 日期格式为yyyy/mm/dd，返回数值`2`
11. `DATEDIF("2020 07 21","2020 07 23","d")` 日期格式为yyyy mm dd，返回数值`2`
12. `DATEDIF(DATE(2021,1,26,0,1,1),DATE(2021,1,27,0,2,2))` 转换为日期对象后返回日期之间间隔的天数，返回数值`1`，[DATE](./DATE.md)函数
13. `DATEDIF(TODATE("20210126000101","yyyymmddhhmmss"),TODATE("20210127000202","yyyymmddhhmmss"),"d")` 返回日期对象后返回日期之间间隔的天数，返回数值`1`，[TODATE](../transform/TODATE.md)函数
14. `DATEDIF(A1,A2,"d")` 引用单元格，返回`A1`到`A2`之间的天数
15. `DATEDIF([起始日期],[截止日期],"d")` 引用模型字段，返回`起始日期`到`截止日期`之间的天数
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/ADDDATE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/adddate"
title: "ADDDATE - 返回与起始日期间隔一定时间间隔的日期"
---
# **ADDDATE**
返回与起始日期间隔一定时间间隔的日期。
返回值类型由第一个参数**date**的类型决定。如果**date**是字符串，则返回字符串；如果**date**是日期，则返回日期。
## 语法{#grammar}
ADDDATE(**date**, **offset**, **datepart**)
- **date**：起始日期，日期类型，也可以是日期类型的字符串
- **offset**：时间间隔，表示要增加或减少的时间
- **datepart**：时间间隔类型，不区分大小写，详见[时间间隔类型](../../types.md#relative)
**示例地址：** [ADDDATE](https://demo.succbi.com/v5/bi/adddate)
## 示例{#example}
1. `ADDDATE('2020',1,'y')` 返回2020年的后一年`2021`
2. `ADDDATE('202007',1,'y')` 返回2020年7月的后一年`202107`
3. `ADDDATE('20200715',1,'y')` 返回2020年7月15日的后一年`20210715`
4. `ADDDATE('202007',1,'m')` 返回2020年7月的后一月`202008`
5. `ADDDATE('20200715',1,'d')` 返回2020年7月15日的后一天`20200716`
6. `ADDDATE('20200715',-1,'d')` 返回2020年7月15日的前一天`20200714`
7. `ADDDATE('2020-07-23',2,'m')` 日期格式为yyyy-mm-dd`2020-09-23`
8. `ADDDATE('2020.07.23',2,'m')` 日期格式为yyyy.mm.dd`20200923`
9. `ADDDATE('2020/07/23',2,'m')` 日期格式为yyyy/mm/dd`2020/09/23`
10. `ADDDATE('2020 07 23',2,'m')` 日期格式为yyyy mm dd`20200923`
11. `LASTDAY(ADDDATE(TODAY(),-1,'m'))` 返回当前日期的上个月的最后一天`2022-04-30`
12. `IF(DAY(TODAY())>=15,ADDDATE(ADDDATE(TODAY(),-1,'M'),16-DAY(TODAY()),'D'),ADDDATE(ADDDATE(TODAY(),-2,'M'),16,'D'))` 如果当前日期大于15号，就返回16天前，否则就返回上个月的16天前`2022-03-21`
13. `IF(DAY(TODAY())>=15,DATE(year(ADDDATE(TODAY(),-1,'M')),month(ADDDATE(TODAY(),-1,'M')),'16'),DATE(year(ADDDATE(TODAY(),-2,'M')),month(ADDDATE(TODAY(),-2,'M')),'16'))` 如果当前日期大于15号，就返回上个月16号，否则就返回上上个月的16号`2022-03-16`
14. `ADDDATE(TODAY(),-(WEEKDAY(TODAY())-1),'d')` 返回当前日期所在周的第一天`2022-05-02`
15. `ADDDATE(TODAY(),7-WEEKDAY(TODAY()),'d')` 返回当前日期所在周的最后一天`2022-05-08`
16. `ADDDATE(TODAY(),-(DAY()-1),'d')`返回当前日期所在月的第一天`2022-05-01`
17. `ADDDATE([门店销售明细表].[销售日期],1,'y')` 返回销售日期的后一年`20191215`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/NETWORKDAYS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/networkdays"
title: "NETWORKDAYS - 返回两个日期之间的所有工作日天数"
---
# **NETWORKDAYS**
返回两个日期之间的所有工作日天数。若开始时间大于结束时间，那么返回的值将是一个负数。
## 语法{#grammar}
NETWORKDAYS(**dateStart**, **dateEnd**, **\[holidays]**, **\[nonholidays]**)
- **dateStart**：必需，起始日期
- **dateEnd**：必需，结束日期
- **holidays**：可选，表示需要从工作日历中排除的日期值，该参数是由日期所构成的数组常量
- **nonholidays**：可选，表示需要从周末日历中排除的日期值，该参数是由日期所构成的数组常量
**示例地址：** [NETWORKDAYS](https://demo.succbi.com/v5/bi/networkdays)
## 示例{#example}
1. `NETWORKDAYS('20201223','20201224')` 返回两个日期之间的工作日天数，返回数值`2`
2. `NETWORKDAYS('20201223','20201224','20201223')` 返回两个日期之间的工作日天数，其中12月23日为节假日，返回数值`1`
3. `NETWORKDAYS('20201223','20201225','','20201225')` 返回两个日期之间的工作日天数，其中12月25日为工作日，返回数值`3`
4. `NETWORKDAYS('20201223','20201226','20201223','20201226')` 返回两个日期之间的工作日天数，其中12月23日为节假日，12月26日为工作日，返回数值`3`
5. `NETWORKDAYS('20201223','20201227',ARR('20201224','20201225'),ARR('20201226','20201227'))` 返回两个日期之间的工作日天数，其中12月24日、12月25日为节假日，12月26日、12月27为工作日，返回数值`3`
6. `NETWORKDAYS(TODAY(),YEAR(TODAY())+'1231')` 返回今年剩余工作日的天数，返回数值`171`
7. `NETWORKDAYS('20200930','20200901')` 结束日期小于起始日期，返回数值`-23`
8. `NETWORKDAYS('2020-09-01','2020-09-30')` 日期格式为yyyy-mm-dd，返回数值`23`
9. `NETWORKDAYS('2020.09.01','2020.09.30')` 日期格式为yyyy.mm.dd，返回数值`23`
10. `NETWORKDAYS('2020/9/1','2020/9/30')` 日期格式为yyyy/mm/dd，返回数值`23`
11. `NETWORKDAYS('2020 09 01','2020 09 30')` 日期格式为yyyy mm dd，返回数值`23`
12. `NETWORKDAYS(A1,A2)` 引用单元格，返回`A1`到`A2`的工作日天数
13. `NETWORKDAYS([行政处罚信息].[决定日期],[行政处罚信息].[公示日期])` 引用模型字段，返回`公示日期`到`决定日期`的工作日天数
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/WEEKDAY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/weekday"
title: "WEEKDAY - 返回日期对象中的当前天数是星期几"
---
# **WEEKDAY**
返回日期对象中的当前天数是星期几。
## 语法{#grammar}
WEEKDAY(**date**, **\[type]**)
- **date**：日期对象
- **type**：可选，默认值为2
- `1`：表示一周从周日开始，返回（1=周日，2=周一，...，7=周六）
- `2`：表示一周从周一开始，返回（1=周一，2=周二，...，7=周日）
**示例地址：** [WEEKDAY](https://demo.succbi.com/v5/bi/weekday)
## 示例{#example}
1. `WEEKDAY("20200715")` 返回日期对象中的当前天数是星期几，返回数值`3`
2. `WEEKDAY("20200715",1)` 参数值为1，周日返回1，返回数值`4`
3. `WEEKDAY("20200715",2)` 参数值为2，周一返回1，返回数值`3`
4. `WEEKDAY("2020-02-01")` 日期格式为yyyy-dd-mm，返回数值`6`
5. `WEEKDAY("2020.02.01")` 日期格式为yyyy.dd.mm，返回数值`6`
6. `WEEKDAY("2020/02/01")` 日期格式为yyyy/dd/mm，返回数值`6`
7. `WEEKDAY("2020 02 01")` 日期格式为yyyy dd mm，返回数值`6`
8. `WEEKDAY(A1)` 引用单元格，返回`A1`的日期对象是星期几
9. `WEEKDAY([行政处罚信息].[公示日期])` 返回`公示日期`是星期几
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/WEEKNUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/weeknum"
title: "WEEKNUM - 返回日期对象在一年中的周数"
---
# **WEEKNUM**
返回日期对象在一年中的周数。
## 语法{#grammar}
WEEKNUM(**date**, **\[type]**, **\[minDay]**)
- **date**：日期对象
- **type**：可选，默认值为2
- `1`：表示一周从周日开始，返回（1=周日，2=周一，...，7=周六）
- `2`：表示一周从周一开始，返回（1=周一，2=周二，...，7=周日）
- **minDay**：可选，表示一周最少天数，默认值为7
**示例地址：** [WEEKNUM](https://demo.succbi.com/v5/bi/weeknum)
## 示例{#example}
1. `WEEKNUM("20200301")` 返回日期对象在一年中的周数，返回数值`8`
2. `WEEKNUM("20200301",1)` 类型值设为1，返回数值`9`
3. `WEEKNUM("20200301",2)` 类型值设为2，返回数值`8`
4. `WEEKNUM("2020-03-01")` 日期格式为yyyy-dd-mm，返回数值`8`
5. `WEEKNUM("2020.03.01")` 日期格式为yyyy.dd.mm，返回数值`8`
6. `WEEKNUM("2020/03/01")` 日期格式为yyyy/dd/mm，返回数值`8`
7. `WEEKNUM("2020 03 01")` 日期格式为yyyy dd mm，返回数值`8`
8. `WEEKNUM(A1)` 引用单元格，返回`A1`在一年中的周数
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/WORKDAY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/workday"
title: "WORKDAY - 返回起始日期之前或之后相隔指定工作日的某一工作日的日期值"
---
# **WORKDAY**
返回起始日期之前或之后相隔指定工作日的某一工作日的日期值。
## 语法{#grammar}
WORKDAY(**dateStart**, **days**, **\[holidays]**, **\[nonholidays]**)
- **dateStart**：必需，起始日期
- **days**：必需，为起始日期之前或之后不含周末及节假日的天数，值为正则产生未来日期；值为负则产生过去日期
- **holidays**：可选，表示需要从工作日历中排除的日期值，该参数是由日期所构成的数组常量
- **nonholidays**：可选，表示需要从周末日历中排除的日期值，该参数是由日期所构成的数组常量
**示例地址：** [WORKDAY](https://demo.succbi.com/v5/bi/workday)
## 示例{#example}
1. `WORKDAY('20201223',1)` 返回一个工作日后的日期，返回日期`2020-12-24`
2. `WORKDAY('20201223',-1)` 返回一个工作日前的日期，返回日期`2020-12-22`
3. `WORKDAY('20201223',2,'20201225')` 返回二个工作日后的日期，其中12月25日为节假日，返回日期`2020-12-28`
4. `WORKDAY('20201223',3,'','20201226')` 返回三个工作日后的日期，其中12月26日为工作日，返回日期`2020-12-26`
5. `WORKDAY('20201223',3,'20201225','20201226')` 返回三个工作日后的日期，其中12月25日为节假日，12月26日为工作日，返回日期`2020-12-28`
6. `WORKDAY('20201223',2,ARR('20201224','20201225'),ARR('20201226','20201227'))` 返回二个工作日后的日期，其中12月24日、12月25日为节假日，12月26日、12月27日为工作日，返回日期`2020-12-27`
7. `WORKDAY("2020-7-16",3)` 日期格式为yyyy-dd-mm，返回日期`2020-07-21`
8. `WORKDAY("2020.7.16",3)` 日期格式为yyyy.dd.mm，返回日期`2020.07.21`
9. `WORKDAY("2020/7/16",3)` 日期格式为yyyy/dd/mm，返回日期`2020/07/21`
10. `WORKDAY("2020 7 16",3)` 日期格式为yyyy dd mm，返回日期`2020 07 21`
11. `WORKDAY('20201223',1.8)` 返回1.8个工作日后的日期（向下取整为1），返回日期`2020-12-24`
12. `WORKDAY('20201223',-0.1)` 返回0.1个工作日前的日期（向下取整为-1），返回日期`2020-12-22`
13. `WORKDAY(A1,1)` 返回`A1`一个工作日后的日期
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/DAYS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/days"
title: "DAYS - 返回两个日期之间的天数"
---
# **DAYS**
返回两个日期之间的天数。
返回的天数不包含结束的日期。如果起始日期大于结束日期，那么返回相差日期的绝对值。
## 语法{#grammar}
DAYS(**dateStart**, **dateEnd**)
- **dateStart**：必需。起始日期
- **dateEnd**：必需。结束日期
**示例地址：** [DAYS](https://demo.succbi.com/v5/bi/days)
## 示例{#example}
1. `DAYS("20200714","20200716")` 日期格式为yyyymmdd，返回`2`
2. `DAYS("20200716","20200714")` 结束日期小于起始日期，返回`2`
3. `DAYS("202002","202003")` 日期格式为yyyymmdd，返回`29`
4. `DAYS("2019","2020")` 日期格式为yyyy，返回`365`
5. `DAYS("2020-07-12","2020-07-16")` 日期格式为yyyy-mm-dd，返回`4`
6. `DAYS("2020-07-12","2020-07-16")` 日期格式为yyyy.mm.dd，返回`4`
7. `DAYS("2020/07/12","2020/07/16")` 日期格式为yyyy/mm/dd，返回`4`
8. `DAYS("2020 07 12","2020 07 16")` 日期格式为yyyy mm dd，返回`4`
9. `DAYS(A1,B1)` 引用单元格A1到B1的日期时长，返回`13`
10. `DAYS([行政处罚信息].[公示日期],[行政处罚信息].[决定日期])` 参数值返回行政处罚公示日期到决定日期时长，返回`13`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/HOUR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/hour"
title: "HOUR - 返回日期对象的小时数"
---
# **HOUR**
返回日期对象的小时数。
以整数的形式返回时间戳类型的日期对象的小时数，返回值是 0 （午夜） 到 23 （晚上 11 点）之间的一个整数。
## 语法{#grammar}
HOUR(**date**)
- **date**：可选，时间戳类型的字段或者表达式。省略时返回当前时间的小时数
**示例地址：** [HOUR](https://demo.succbi.com/v5/bi/hour)
## 示例{#example}
1. `HOUR()` 返回当前时间的小时数`14`
2. `HOUR("20200723 11:44:28")` 日期格式为yyyyddmm返回小时数`11`
3. `HOUR("2020-07-23 11:44:28")` 日期格式为yyyy-mm-dd返回小时数`11`
4. `HOUR("2020.07.23 11:44:28")` 日期格式为yyyy.mm.dd返回小时数`11`
5. `HOUR("2020/07/23 11:44:28")` 日期格式为yyyy/mm/dd返回小时数`11`
6. `HOUR("2020 07 23 11:44:28")` 日期格式为yyyy mm dd返回小时数`11`
7. `HOUR(DATE(2021,1,26,5,1,1))` 转换为日期对象后返回日期的小时数`5`
8. `HOUR(TODATE("20210126050101","yyyymmddhhmmss"))` 返回日期对象后返回日期的小时数`5`
9. `HOUR(A1)` 静态字段获取A1的值，返回日期对象中的小时数`1`
10. `HOUR([门店销售明细表].[销售日期])` 数据库字段获取销售日期，返回日期对象中的小时数`1`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/MINUTE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/minute"
title: "MINUTE - 返回日期对象的分钟数"
---
# **MINUTE**
返回日期对象的分钟数，返回值是 0 ~ 59 之间的一个整数。
## 语法{#grammar}
MINUTE(**date**)
- **date**：可选，时间戳类型的字段或者表达式。省略时返回当前时间的分钟数
**示例地址：** [MINUTE](https://demo.succbi.com/v5/bi/minute)
## 示例{#example}
1. `MINUTE()` 返回当前时间的分钟数`1`
2. `MINUTE("20120314 12:34:56")` 日期格式为yyyyddmm返回分钟数`34`
3. `MINUTE("2020-07-16 11:30:30")` 日期格式为yyyy-mm-dd返回分钟数`30`
4. `MINUTE("2020.07.16 11:30:30")` 日期格式为yyyy.mm.dd返回分钟数`30`
5. `MINUTE("2020/07/16 11:30:30")` 日期格式为yyyy/mm/dd返回分钟数`30`
6. `MINUTE("2020 07 16 11:30:30")` 日期格式为yyyy mm dd返回分钟数`30`
7. `MINUTE(DATE(2021,1,26,5,5,1))` 转换为日期对象后返回日期的分钟数`5`
8. `MINUTE(TODATE("20210126050501","yyyymmddhhmmss"))` 回日期对象后返回日期的分钟数`5`
9. `MINUTE(A1)` 静态字段获取A1的值，返回日期中的分钟数`1`
10. `MINUTE([门店销售明细表].[销售日期])` 数据库字段获取销售日期，返回日期中的分钟`1`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/SECOND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/second"
title: "SECOND - 返回日期对象的秒数值"
---
# **SECOND**
返回日期对象的秒数值，返回值是 0 ~ 59 之间的一个整数。
## 语法{#grammar}
SECOND(**date**)
- **date**：可选，时间戳类型的字段或者表达式。省略时返回当前时间的秒数值
**示例地址：** [SECOND](https://demo.succbi.com/v5/bi/second)
## 示例{#example}
1. `SECOND()` 返回当前时间的秒数值`23`
2. `SECOND("20200717 10:23:45")` 日期格式为yyyymmdd返回秒数值`45`
3. `SECOND("2020-07-16 11:30:30")` 日期格式为yyyy-mm-dd返回秒数值`30`
4. `SECOND("2020.07.16 11:30:30")` 日期格式为yyyy.mm.dd返回秒数值`30`
5. `SECOND("2020/07/16 11:30:30")` 日期格式为yyyy/mm/dd返回秒数值`30`
6. `SECOND("2020 07 16 11:30:30")` 日期格式为yyyy mm dd返回秒数值`30`
7. `SECOND(DATE(2021,1,26,0,1,15)))` 转换为日期对象后返回日期的秒数值`15`
8. `SECOND(TODATE("20210126000115","yyyymmddhhmmss"))` 返回日期对象后返回日期的秒数值`15`
9. `SECOND(A1)` 静态字段获取A1的值，返回日期中的秒数值`40`
10. `SECOND([门店销售明细表].[销售时间])` 数据库字段获取销售日期，返回日期中的秒数值`40`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/TIME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/time"
title: "TIME - 返回特定时间的序列号"
---
# **TIME**
返回特定时间的序列号。
该函数返回的十进制数字是一个范围在0到1之间的值，表示0点到24点之间的时间。
## 语法{#grammar}
TIME(**hour**, **minute**, **second**)
- **hour**：必需。0到23之间的数字，代表小时
- **minute**：必需。0到59之间的数字，代表分钟
- **second**：必需。0到59之间的数字，代表秒
**示例地址：** [TIME](https://demo.succbi.com/v5/bi/time)
## 示例{#example}
1. `TIME(12,0,0)` 表示12时0分0秒在一天中代表的小数部分，返回`0.5`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/SECONDS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/seconds"
title: "SECONDS - 返回两个日期之间间隔的秒数"
---
# **SECONDS**
返回两个日期之间间隔的秒数。
如果起始日期大于结束日期，则返回负数。
## 语法{#grammar}
SECONDS(**dateStart**, **dateEnd**)
- **dateStart**：必需，为起始日期。可以是日期类型的字符串，也可以使用[TODATE](../transform/TODATE.md)转成日期对象
- **dateEnd**：必需，为结束日期。类型同上
**示例地址：** [SECONDS](https://demo.succbi.com/v5/bi/seconds)
## 示例{#example}
1. `SECONDS("20200717 10:23:45","20200717 10:23:59")` 日期格式为yyyymmdd，返回`14`
2. `SECONDS("20200717 10:23:59","20200717 10:23:45")` 结束日期小于起始日期，返回`-14`
3. `SECONDS("2020-07-17 10:23:45","2020-07-17 10:23:59")` 日期格式为yyyy-mm-dd，返回`14`
4. `SECONDS("2020.07.17 10:23:45","2020.07.17 10:23:59")` 日期格式为yyyy.mm.dd，返回`14`
5. `SECONDS("2020/07/17 10:23:45","2020/07/17 10:23:59")` 日期格式为yyyy/mm/dd，返回`14`
6. `SECONDS("2020 07 17 10:23:45","2020 07 17 10:23:59")` 日期格式为yyyy mm dd，返回`14`
7. `SECONDS("20210126000001","20210126000002")` 日期格式为yyyymmddhhmmss，返回`1`
8. `SECONDS(DATE(2021,1,26,0,1,1),DATE(2021,1,26,0,2,2))` 转换为日期对象后返回日期之间间隔的秒数，返回`61`
9. `SECONDS(TODATE("20210126000101","yyyymmddhhmmss"),TODATE("20210126000202","yyyymmddhhmmss")）` 返回日期对象后返回日期之间间隔的秒数，返回`61`
10. `SECONDS(A1,B1)` 引用单元格A1到B1的之间的秒数，返回`1,123,200`
11. `SECONDS([行政处罚信息].[决定日期],[行政处罚信息].[公示日期])` 参数值返回行政处罚公示日期到决定日期之间的秒数，返回`1,123,200`
---
url: "https://docs.succapp.com/v5/guide/exp/func/date/LASTDAY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lastday"
title: "LASTDAY - 返回指定日期所在月份的最后一天"
---
# **LASTDAY**
返回指定日期所在月份的最后一天。
## 语法{#grammar}
LASTDAY(**date**)
- **date**：必需，日期类型参数
**示例地址：** [LASTDAY](https://demo.succbi.com/v5/bi/lastday)
## 示例{#example}
1. `LASTDAY(TODAY())` 返回当前日期的最后一天，返回日期`20220531`
2. `LASTDAY("20200715")` 日期格式为yyyymmdd，返回日期`20200731`
3. `LASTDAY("2020-07-15")` 日期格式为yyyy-mm-dd，返回日期`2020-07-31`
4. `LASTDAY("2020.07.15")` 日期格式为yyyy.mm.dd，返回日期`2020.07.31`
5. `LASTDAY("2020/07/15")` 日期格式为yyyy/mm/dd，返回日期`2020/07/31`
6. `LASTDAY("2020 07 15")` 日期格式为yyyy mm dd，返回日期`2020 07 31`
7. `LASTDAY(ADDDATE(TODAY(),-1,'m'))` 返回当前日期的上个月的最后一天，返回日期`20220430`
8. `DAY(LASTDAY(TODAY()))`返回当前月份的天数
9. `LASTDAY(A1)` 引用单元格，返回`A1`日期所在月份的最后一天
10. `LASTDAY([公示日期])` 引用模型字段，返回`公示日期`所在月份的最后一天
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/float-funcs"
title: "地理函数列表"
---
---
navTitle: 浮动函数
---
# 地理函数列表
!!!children (guide/exp/func/float)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FINDEX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/findex"
title: "FINDEX - 计算浮动行的序号"
---
# **FINDEX**
计算浮动行的序号。
没有过滤条件时默认返回当前浮动行的序号，有过滤条件时返回第一个满足条件行的行号。行号从1开始，当有分页时只取在当前页中的行号，返回值为整型。
## 语法{#grammar}
FINDEX(**condition**)
- **condition**：可选，过滤条件，不传则默认返回当前浮动行的序号
## 示例{#example}
1. `FINDEX()` 返回当前浮动行的序号
2. `FINDEX(A2>0)` 返回`A2`单元格的浮动行中第一个值大于0行的行号
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FGET.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fget"
title: "FGET - 返回浮动区域中满足条件的第一个单元格的值"
---
# **FGET**
返回浮动区域中满足条件的第一个单元格的值，当不存在满足条件的单元格时，返回的是null。同[FFIRST](./FFIRST.md)。
## 语法{#grammar}
FGET(**exp**, **condition**)
- **exp**：必需，求值参数，既可以是一个单元格，也可以是一个表达式，必须含有浮动单元格。
- **condition**：可选，过滤数据的规则，满足该条件的第一个元素将被返回。
## 示例{#examples}
1. `FGET(D1, B1="华中")` 返回`B1`为`“华中”`的`D1`的第一个值
2. `FGET(E1, C1='01' OR C1='02')` 返回`C1='01'`或者`C1='02'`时，第一个`E1`的值
3. `FGET(E1, C1 in('01', '02'))`返回`C1='01'`或者`C1='02'`时，第一个`E1`的值
4. `FGET(E1*D1,D1>10000)` 先对`D1`做过滤，将数组中大于10000的第一个元素，乘以对应的`E1`单元格值再返回
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FSUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fsum"
title: "FSUM - 对浮动区域中满足指定条件的单元格求和"
---
# **FSUM**
对浮动区域中满足指定条件的单元格求和。
## 语法{#grammar}
FSUM(**exp**, **condition**)
- **exp**：必需，表示要求和的值，可以是单元格，也可以是表达式。这里不仅可以求和，也可以做四则运算。必须含有浮动单元格
- **condition**：可选，用于确定对哪些单元格求和的条件
## 示例{#example}
1. `FSUM(C1,C1<16)` 将浮动单元格`C1`小于16的值求和后返回
2. `FSUM(D1,D1>80)` 将浮动单元格`D1`大于80的值求和后返回
3. `FSUM(C1*D1,C1<16)` 将浮动单元格`C1`小于16的值，乘以对应的`D1`，再求和返回
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FCOUNT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fcount"
title: "FCOUNT - 计算浮动区域中满足给定条件的单元格的个数"
---
# **FCOUNT**
计算浮动区域中满足给定条件的单元格的个数。返回值为整型。
## 语法{#grammar}
FCOUNT(**condition**)
- **condition**：必需，过滤条件，条件中需含有浮动单元格
## 示例{#example}
1. `FCOUNT(B1="02")` 对B1单元格的值等于`02`的进行计数
2. `FCOUNT(C1>500)` 对C1单元格的值大于`500`的进行计数
3. `FCOUNT(D1<90000)` 对D1单元格的值小于`90000`的进行计数
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FCOUNTD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fcountd"
title: "FCOUNTD - 计算浮动区域中满足给定条件的单元格去重后的个数"
---
# **FCOUNTD**
计算浮动区域中满足给定条件的单元格去重后的个数，返回值为整型。
## 语法{#grammar}
FCOUNTD(**exp**, **condition**)
- **exp**：必需。表示要去重统计的值，可以是单元格，也可以是表达式。必须含有浮动单元格
- **condition**：可选，过滤条件，条件中需含有浮动单元格
## 示例{#example}
1. `FCOUNTD(A1,B1="02")` 过滤浮动区域中B1单元格等于`02`的行，并对A1单元格的值进行去重计数
2. `FCOUNTD(A1,C1>500)` 过滤浮动区域中C1单元格大于`500`的行，并对A1单元格的值进行去重计数
3. `FCOUNTD(A1,D1<90000)` 过滤浮动区域中D1单元格小于`90000`的行，并对A1单元格的值进行去重计数
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FMAX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fmax"
title: "FMAX - 计算浮动区域中满足给定条件的单元格的最大值"
---
# **FMAX**
计算浮动区域中满足给定条件的单元格的最大值，返回值类型为指定的表达式的类型。
## 语法{#grammar}
FMAX(**exp**, **condition**,**getValue**)
- **exp**：必需，表示要计算最大值的值，可以是单元格，也可以是表达式。这里不仅可以求和，也可以做四则运算。必须含有浮动单元格
- **condition**：可选，用于确定对哪些单元格求最大值的条件
- **getValue**：可选，默认求第一个参数exp的最大值，也可以获取exp最大值所在浮动行的其他属性，比如：获取销售数量最大的产品名称
## 示例{#example}
1. `FMAX(C1,C1<16)` 将浮动单元格`C1`小于16的值求最大值后返回
2. `FMAX(D1,D1>80)` 将浮动单元格`D1`大于80的值求最大值后返回
3. `FMAX(C1*D1,C1<16)` 将浮动单元格`C1`小于16的值，乘以对应的`D1`，再求最大值返回
4. `FMAX(F1,D1='高档',A1)` 过滤浮动区域中`D1`等于`高档`的浮动行，再计算`F1`最大的`A1`的值
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FMIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fmin"
title: "FMIN - 计算浮动区域中满足给定条件的单元格的最小值"
---
# **FMIN**
计算浮动区域中满足给定条件的单元格的最小值，返回值类型为指定的表达式的类型。
## 语法{#grammar}
FMIN(**exp**, **condition**,**getValue**)
- **exp**：必需，表示要最小值的值，可以是单元格，也可以是表达式。这里不仅可以求和，也可以做四则运算。必须含有浮动单元格
- **condition**：可选，用于确定对哪些单元格求最小值的条件
- **getValue**：可选，默认求第一个参数exp的最小值，也可以获取exp最小值所在浮动行的其他属性，比如：获取销售数量最大的产品名称
## 示例{#example}
1. `FMIN(C1,C1<16)` 将浮动单元格`C1`小于16的值求最小值后返回
2. `FMIN(D1,D1>80)` 将浮动单元格`D1`大于80的值求最小值后返回
3. `FMIN(C1*D1,C1<16)` 将浮动单元格`C1`小于16的值，乘以对应的`D1`，再求最小值返回
4. `FMIN(F1,D1='高档',A1)` 过滤浮动区域中`D1`等于`高档`的浮动行，再计算`F1`最小的`A1`的值
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FAVG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/favg"
title: "FAVG - 对浮动区域中满足指定条件的单元格求平均值"
---
# **FAVG**
对浮动区域中满足指定条件的单元格求平均值。
## 语法{#grammar}
FAVG(**exp**, **condition**)
- **exp**：必需，表示要求和的值，可以是单元格，也可以是表达式。这里不仅可以求和，也可以做四则运算。必须含有浮动单元格
- **condition**：可选，用于确定对哪些单元格求平均值的条件
## 示例{#example}
1. `FAVG(C1,C1<16)` 将浮动单元格`C1`小于16的值求平均值后返回
2. `FAVG(D1,D1>80)` 将浮动单元格`D1`大于80的值求平均值后返回
3. `FAVG(C1*D1,C1<16)` 将浮动单元格`C1`小于16的值，乘以对应的`D1`，再求平均值返回
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FINDEXV.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/findexv"
title: "FINDEXV - 计算可见行的序号"
---
# **FINDEXV**
计算可见行的序号。
没有过滤条件时默认返回当前可见行的序号，有过滤条件时返回第一个满足条件可见行的行号。行号从1开始，返回值为整型。
## 语法{#grammar}
FINDEXV(**condition**)
- **condition**：可选，过滤条件，不传则默认返回当前可见行的序号
## 示例{#example}
1. `FINDEXV()` 返回当前可见行的序号
2. `FINDEXV(A2>0)` 返回`A2`单元格的浮动行中第一个值大于0可见行的行号
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FFIRST.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/ffirst"
title: "FFIRST - 返回浮动区域中满足条件的第一个单元格的值"
---
# **FFIRST**
返回浮动区域中满足条件的第一个单元格的值，当不存在满足条件的单元格时，返回的是null。。同[FGET](./FGET.md)。
## 语法{#grammar}
FFIRST(**exp**, **condition**)
- **exp**：必需，要返回的值，既可以是一个单元格，也可以是一个表达式，必须含有浮动单元格。
- **condition**：可选，用于过滤浮动区域的范围。
## 示例{#examples}
1. `FFIRST(D1)` 返回浮动行中第一个`D1`的值
2. `FFIRST(E1, C1='01')` 过滤浮动区域中满足条件`C1='01'`的行，并返回第一个`E1`单元格的值
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FLAST.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/flast"
title: "FLAST - 返回浮动区域中满足条件的最后一个单元格的值"
---
# **FLAST**
返回浮动区域中满足条件的最后一个单元格的值。
## 语法{#grammar}
FLAST(**exp**, **condition**)
- **exp**：必需，要返回的值，既可以是一个单元格，也可以是一个表达式。必须含有浮动单元格
- **condition**：可选，用于过滤浮动区域的范围。
## 示例{#examples}
1. `FLAST(D1)` 返回浮动行中最后一个`D1`的值
2. `FLAST(E1, C1='01')` 过滤浮动区域中满足条件`C1='01'`的行，并返回最后一个`E1`单元格的值
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FSEL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fsel"
title: "FSEL - 返回浮动区域内满足给定条件的的数据"
---
# **FSEL**
返回浮动区域内满足给定条件的的数据，返回值为数组。当不存在满足条件的元素时，返回的是空数组。
## 语法{#grammar}
FSEL(**exp**, **condition**)
- **exp**：必需，求值参数，既可以是一个单元格，也可以是一个表达式。必须含有浮动单元格
- **condition**：可选，过滤数据的规则，满足该条件的元素将返回
## 示例{#example}
1. `FSEL(C1, B1="01")` 当`B1`等于`01`的时候，返回`C1`形成的数组
2. `FSEL(C1, B1 in ARR ("01","02"))` 当`B1`等于`01`或者`02`的时候，返回`C1`形成的数组
3. `FSEL(C1*D1, C1>50000)` 将`C1`大于50000的第一个元素，乘以对应的`D1`返回数组
4. `FSEL(ARR(B1, C1, D1),B1="01")` 当`B1`等于`01`的时候，返回`B1 C1 D1`的值
5. `FSEL(ARR(B1, C1, D1),C1>0)`选择`C1`大于0的行的值，返回`B1 C1 D1`的值
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FOUT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fout"
title: "FOUT - 跳出F函数"
---
# **FOUT**
跳出F函数，在浮动行上返回表达式的值。
## 语法{#grammar}
FOUT(**exp**)
- **exp**：必需，计算的表达式，既可以是一个单元格，也可以是一个表达式，必须含有浮动单元格。
## 示例{#examples}
1. `FSUM(B3, A3 <= FOUT(A3))` FSUM函数写在浮动区域内的单元格中，若B3代表销售金额，A3代表年月，则表示在每个浮动行中计算出截止当前年月的销售金额累积汇总值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FALL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fall"
title: "FALL - 在整个浮动区域中计算表达式"
---
# **FALL**
在整个浮动区域中计算表达式。在嵌套浮动中，下级浮动区域的表达式默认会带上上级浮动的条件约束，使用FALL可以跳出上级浮动条件的约束。
## 语法{#grammar}
FALL(**exp**)
- **exp**：必需，计算的表达式，既可以是一个单元格，也可以是一个表达式，必须含有浮动单元格。
## 示例{#examples}
1. `FSUM(FALL(J4), J4 > 10000)` FSUM函数写在浮动区域中，J4跳出上级浮动条件约束，在整个浮动区域中将浮动单元格J4大于10000的值求和后返回
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FLAG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/flag"
title: "FLAG - 计算浮动区域中满足条件的单元格往上偏移指定行后的值"
---
# **FLAG**
计算浮动区域中满足条件的单元格往上偏移指定行后的值。
## 语法{#grammar}
FLAG(**exp**, **condition**, **offset**, **condition**)
- **exp**：必需，要返回的值，既可以是一个单元格，也可以是一个表达式。必须含有浮动单元格
- **offset**：可选，往上的偏移量，默认值是1。
- **defvalue**：可选，取值超出浮动行范围时会返回值，默认为`NULL`。
- **condition**：可选，用于过滤浮动行的范围，比如，希望往上找第1个`C1`不为空的值，那么条件写为`C1 IS NOT NULL`
## 示例{#examples}
1. `FLAG(D1)` 返回上一个`D1`的值，如果超出浮动行范围，返回`null`
2. `FLAG(D1, 1, 0)` 返回上一个`D1`的值，如果超出浮动行范围，返回`0`
3. `FLAG(D1, 1, null, D1 IS NOT NULL)` 返回上一个不为空的D1的值，如果超出浮动行范围，返回`null`
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FLEAD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/flead"
title: "FLEAD - 计算浮动区域中满足条件的单元格往下偏移指定行后的值"
---
# **FLEAD**
计算浮动区域中满足条件的单元格往下偏移指定行后的值。
## 语法{#grammar}
FLEAD(**exp**, **condition**, **offset**, **condition**)
- **exp**：必需，要返回的值，既可以是一个单元格，也可以是一个表达式。必须含有浮动单元格
- **offset**：可选，往下的偏移量，默认值是1。
- **defvalue**：可选，取值超出浮动行范围时会返回值，默认为`NULL`。
- **condition**：可选，用于过滤浮动行的范围，比如，希望往下找第1个`C1`不为空的值，那么条件写为`C1 IS NOT NULL`
## 示例{#examples}
1. `FLEAD(D1)` 返回下一个`D1`的值，如果超出浮动行范围，返回`null`
2. `FLEAD(D1, 1, 0)` 返回下一个`D1`的值，如果超出浮动行范围，返回`0`
3. `FLEAD(D1, 1, null, D1 IS NOT NULL)` 返回下一个不为空的D1的值，如果超出浮动行范围，返回`null`
---
url: "https://docs.succapp.com/v5/guide/exp/func/float/FPRE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fpre"
title: "FPRE - 返回浮动区域中指定偏移单元格的值"
---
# **FPRE**
返回浮动区域中指定偏移单元格的值。
## 语法{#grammar}
FPRE(**exp**, **offset**, **defValue**)
- **exp**：必需，要返回的值，既可以是一个单元格，也可以是一个表达式。必须含有浮动单元格
- **offset**：可选，整数，表示与当前浮动行的偏移量。默认为-1，表示上一行。为负数，表示取上面行的数据，为正数，表示取下面行的数据。
- **defValue**：可选，没有找到行时返回的值。如FPRE(A2,-1,"a")，当第一行计算时，没有上一行，返回"a"。
## 示例{#examples}
1. `FPRE(D1)` 返回上一行中`D1`的值
2. `FPRE(D1,-2)` 返回上两行中`D1`的值
3. `FPRE(D1,2)` 返回下两行中`D1`的值
4. `FPRE(E1, -1,'A')` 返回上一行的`E1`的值，如果没有上一行，返回`A`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/math-funcs"
title: "数学函数列表"
---
---
navTitle: 数学函数
---
# 数学函数列表
!!!children (guide/exp/func/math)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ROUND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/round"
title: "ROUND - 按指定的位数对数值进行四舍五入"
---
# **ROUND**
按指定的位数对数值进行四舍五入。
## 语法{#grammar}
ROUND(**number**, **num\_digits**)
- **number**：需要进行四舍五入的数字。
- **num\_digits**：可选，指定的位数，按此位数进行四舍五入。默认值为 0。
## 示例{#examples}
1. `ROUND(3.14,1)=3.1`
2. `ROUND(3.74)=4.0`
3. `ROUND(21.4,-1)=20.0`
4. `ROUND(2.15,0)=2.0`
## 详细描述
该函数将指定的数字按指定的位数来进行四舍五入。
- *num\_digits* > 0，则四舍五入到指定的小数位。
- *num\_digits* = 0，则四舍五入到最接近的整数。
- *num\_digits* < 0，则在小数点左侧进行四舍五入。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/CEILING.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/ceiling"
title: "CEILING - 对数值进行向上舍入"
---
# **CEILING**
对数值进行向上舍入。
## 语法{#grammar}
CEILING(**number**)
- **number**： 必需 ，表示一个具体的数值，或是一个事实表的度量表达式。
## 示例{#examples}
1. `CEILING(1.6)=2`
2. `CEILING(-1.6)=-1`
## 详细描述
该函数对数值进行向上舍入，返回最接近且大于或等于 *number* 的整数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/FLOOR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/floor"
title: "FLOOR - 对数值进行向下舍入"
---
# **FLOOR**
对数值进行向下舍入。
## 语法{#grammar}
FLOOR(**number**)
- **number**：必需 ，表示一个具体的数值，或是一个事实表的度量表达式。
## 示例{#examples}
1. `FLOOR(1.6)=1`
2. `FLOOR(-1.6)=-2`
## 详细描述
该函数对数值进行向下舍入，返回最接近且小于或等于 *number* 的整数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/RAND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rand"
title: "RAND - 返回均匀分布的随机数"
---
# **RAND()**
返回均匀分布的随机数。
## 示例{#examples}
1. `RAND()` 返回介于 0 到 1 之间的随机数，如 0.1835463363395088
2. `RAND()*50` 返回介于 0 到 50 之间的随机数
## 详细描述
该函数返回大于等于 0 及小于 1 的均匀分布随机实数，每次计算工作表时都将返回一个新的随机实数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SQRT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sqrt"
title: "SQRT - 返回数值的算数平方根"
---
# **SQRT**
返回数值的算数平方根。
## 语法{#grammar}
SQRT(**number**)
- **number**：必需。数值型参数，大于等于0。
## 示例{#examples}
1. `SQRT(4)=2`
2. `SQRT(0)=0`
3. `SQRT(-4)=""`
## 详细描述
该函数用来求一个数值型参数的平方根，一个正数有两个平方根，这里只返回非负数的平方根（算数平方根）。不支持求负数的二次方根。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ABS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/abs"
title: "ABS - 返回数值或度量表达式的绝对值"
---
# **ABS**
返回数值或度量表达式的绝对值。
## 语法{#grammar}
ABS(**number**)
- **number**：需要计算其绝对值的实数，或是一个事实表的度量表达式。
## 示例{#examples}
1. `ABS(2)=2`
2. `ABS(-2)=2`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/POWER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/power"
title: "POWER - 返回参数 *x* 的 *y* 次幂的值"
---
# **POWER**
返回参数 *x* 的 *y* 次幂的值。
## 语法{#grammar}
POWER(**x**, **y**)
- **x**：必需。底数,任意实数。
- **y**：必需。幂数,任意实数。
## 示例{#examples}
1. `POWER(2,3)=8.0`
2. `POWER(8,1/3)=2.0`
## 详细描述
该函数返回参数 *x* 的 *y* 次幂的值。任何数的0次幂都为1。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/EXP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/exp"
title: "EXP - 返回e的n次幂"
---
# **EXP**
返回e的n次幂。
## 语法{#grammar}
EXP(**number**)
- **number**：幂指数。
## 示例{#examples}
1. `EXP(1)=2.7182818284590455`
2. `EXP(2)=7.38905609893065`
## 详细描述
该函数返回 *e* 的 *number* 次幂。常数 *e* 等于 2.71828182845904，是自然对数的底数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/PI.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/pi"
title: "PI - 返回圆周率 *pi* 的值"
---
# **PI**
返回圆周率 *pi* 的值。
## 语法{#grammar}
PI()
## 示例{#examples}
1. `PI()=3.141592653589793`
## 详细描述
该函数用来获得圆周率 *pi* 的值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/LOG10.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/log10"
title: "LOG10 - 返回以 10 为底的对数"
---
# **LOG10**
返回以 10 为底的对数。
## 语法{#grammar}
LOG10(**number**)
- **number**：计算的正实数。
## 示例{#examples}
1. `LOG10(10)=1.0`
2. `LOG10(1E5)=5.0`
## 详细描述
该函数返回以 10 为底的对数。*number* 需要是一个正实数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/LOG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/log"
title: "LOG - 根据给定的底数返回数值的对数"
---
# **LOG**
根据给定的底数返回数值的对数。
## 语法{#grammar}
LOG(**number**, **base**)
- **number**：必需。为用于计算对数的正实数。
- **base**：必需。为对数的底数，不允许为空。
## 示例{#examples}
1. `LOG(10,10)=1`
2. `LOG(8,2)=3`
## 详细描述
该函数根据给定的底数 *base* ，返回 *number* 的对数。底数 *base* 不允许为空；*number* 要大于0。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/LN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/ln"
title: "LN - 返回数值的自然对数"
---
# **LN**
返回数值的自然对数。
## 语法{#grammar}
LN(**number**)
- **number**：必需，为大于 0的任意数值。
## 示例{#examples}
1. `LN(3)=1.0986122886681098`
2. `LN(EXP(3))=3` e的3次幂的自然对数
## 详细描述
该函数返回一个数的自然对数。自然对数以常数项 *e* (2.71828182845904) 为底。*number*必须大于0。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/TRUNC.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/trunc"
title: "TRUNC - 返回参数按照指定精度截取后的值"
---
# **TRUNC**
返回参数按照指定精度截取后的值。
## 语法{#grammar}
TRUNC(**number**, **num\_digits**)
- **number**：必需。需要截尾取整的数字。
- **num\_digits**：可选。用于指定取整精度的数字。省略时默认为 0。
## 示例{#examples}
1. `TRUNC(2.22)=2`
2. `TRUNC(2.22,1)=2.2`
3. `TRUNC(3.47,1)=3.4` 截取时不存在舍入
## 详细描述
该函数返回 *number* 按照指定精度 *num\_digits* 截取后的值，截取时直接去除数字的小数部分,不存在舍入。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/PRODUCT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/product"
title: "PRODUCT - 计算所有参数的乘积"
---
# **PRODUCT**
计算所有参数的乘积。
## 语法{#grammar}
PRODUCT(**number1**, **number2**, **...**, **numberN**)
- **number1**：必须，任意实数。
- **number2**：可选，任意实数。
## 示例{#examples}
1. `PRODUCT(1,2)=2`
2. `PRODUCT(-3,4,5)=-60`
## 详细描述
该函数返回所有参数的乘积。目前参数 *number1* 只支持数值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sin"
title: "SIN - 返回给定角度的正弦值"
---
# **SIN**
返回给定角度的正弦值。
## 语法{#grammar}
SIN(**angle**)
- **angle**：角度，以弧度表示。
## 示例{#examples}
1. `SIN(0.5)=0.479425538604203`
2. `SIN(PI()/2)=1.0` 90度的正弦值
## 详细描述
该函数返回给定角度的正弦值，以弧度为单位指定角度。若要从角度转换成弧度，将角度乘以 **PI()**/180 ，或使用 **randians()** 函数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/COS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/cos"
title: "COS - 返回给定角度的余弦值"
---
# **COS**
返回给定角度的余弦值。
## 语法{#grammar}
COS(**angle**)
- **angle**：角度，以弧度表示。
## 示例{#examples}
1. `COS(3)=-0.9899924966004454`
2. `COS(PI())=-1.0` 180度的余弦值
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/TAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tan"
title: "TAN - 返回给定角度的正切值"
---
# **TAN**
返回给定角度的正切值。
## 语法{#grammar}
TAN(**angel**)
- **angel**：角度，以弧度表示。
## 示例{#examples}
1. `TAN(45*PI()/180)=1` 45度的正切值
2. `TAN(RADIANS(45))=1`
## 详细描述
该函数返回给定角度的正切值，以弧度为单位指定角度。若要从角度转换成弧度，将角度乘以 **PI()**/180 ，或使用 **randians()** 函数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/DEGREES.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/degrees"
title: "DEGREES - 将弧度转换为角度"
---
# **DEGREES**
将弧度转换为角度。
## 语法{#grammar}
DEGREES(**angle**)
- **angle**：待转换为度的弧度角。
## 示例{#examples}
1. `DEGREES(PI())=180` 弧度为PI()，其对应的角度为180度
2. `DEGREES(0.5) =28.64788975654116`
## 详细描述
该函数用于将弧度转换为角度，计算公式：角度=$弧度\*180$/**PI()**。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/RADIANS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/radians"
title: "RADIANS - 将角度转换为弧度"
---
# **RADIANS**
将角度转换为弧度。
## 语法{#grammar}
RADIANS(**angle**)
- **angle**：待转换为弧度的角度。
## 示例{#examples}
1. `RADIANS(30)=0.5235987755982988`
2. `RADIANS(60)=1.0471975511965976`
## 详细描述
该函数用于将角度转换为弧度，计算公式：弧度=角度$\*$**PI()**/$180$。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ATAN2.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/atan2"
title: "ATAN2 - 返回指定的 X 及 Y 坐标值的反正切值"
---
# **ATAN2**
返回指定的 X 及 Y 坐标值的反正切值，以弧度表示。
## 语法{#grammar}
ATAN2(**x\_num**, **y\_num**)
- **x\_num**\*：点的 X 坐标。
- **y\_num**\*：点的 y 坐标。
## 示例{#examples}
1. `ATAN2(1,1)=0.7853981633974483`
2. `ATAN2(-1,-1)=-2.356194490192345`
3. `ATAN2(-1,-1)*180/PI()=-135`
## 详细描述
该函数返回指定的 *X* 及 *Y* 坐标值的反正切值。反正切值是指从 *X* 轴到通过原点 (0, 0) 和坐标点 (*x\_num*,*y\_num*) 的直线之间的夹角。该角度以弧度表示，并介于 -pi 到 pi 之间（不包括 -pi）。 若要以角度表达反正切，请将结果乘以 180/PI( ) 或使用 DEGREES 函数。如果 *x\_num* 和 *y\_num* 同时为零，此函数将返回 0。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/FACT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fact"
title: "FACT - 返回数的阶乘"
---
# **FACT**
返回数的阶乘。
## 语法{#grammar}
FACT(**number**)
- **number**：非负数。
## 示例{#examples}
1. `FACT(3.833)=6` 3.833截尾取整
2. `FACT(5)=120`
## 详细描述
该函数返回参数 *number* 的阶乘，等于 $1*2*3\*...\*$*number* 。如果 *number* 不是整数，则截尾取整。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SIGN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sign"
title: "SIGN - 返回数字的正负号"
---
# **SIGN**
返回数字的正负号。
## 语法{#grammar}
SIGN(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `SIGN(10)=1`
2. `SIGN(-10)=-1`
3. `SIGN(10-10)=0`
## 详细描述
该函数返回 *number* 的正负号。当 *number* 为正数时返回 1，为零时返回 0，为负数时返回 -1。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ODD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/odd"
title: "ODD - 返回对指定数值进行向上(下)舍入后的奇数"
---
# **ODD**
返回对指定数值进行向上(下)舍入后的奇数。
## 语法{#grammar}
ODD(**number**)
- **number**：要进行舍入的值，可以是任意实数。
## 示例{#examples}
1. `ODD(2)=3`
2. `ODD(-2)=-3` 向下舍入
## 详细描述
该函数返回对指定数值进行向上(下)舍入后的奇数。正数向上进行舍入，负数向下进行舍入;无论数字符号如何，都按远离 0 的方向向上舍入;如果 *number* 恰好是奇数，则不须进行任何舍入处理。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/EVEN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/even"
title: "EVEN - 将正数向上舍入到最近的偶数"
---
# **EVEN**
将正数向上舍入到最近的偶数，负数向下舍入到最近的偶数。
## 语法{#grammar}
EVEN(**number**)
- **number**：要进行舍入的数值。不能直接对事实表中的度量进行舍入操作。
## 示例{#examples}
1. `EVEN(1.5)=2`
2. `EVEN(-1.5)=-2`
## 详细描述
该函数返回 *number* 沿绝对值增大方向取整后最接近的偶数。不论 *number* 的正负号如何，函数都向远离零的方向舍入；如果 *number* 恰好是偶数，则无需进行任何舍入处理。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/CORREL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/correl"
title: "CORREL - 返回2组数组的相关系数"
---
# **CORREL**
返回2组数组的相关系数。
## 语法{#grammar}
CORREL(**arr1**, **arr2**)
- **arr1**：必需。数组对象1。
- **arr2**：必需。数组对象2。
## 示例{#examples}
1. `CORREL(arr(3,2,4),arr(9,7,12))=0.9933992677987821`
## 详细描述
该函数返回两个数组间的相关系数，使用相关系数可以确定两个属性之间的关系。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ASIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/asin"
title: "ASIN - 返回数值的反正弦值"
---
# **ASIN**
返回数值的反正弦值。
## 语法{#grammar}
ASIN(**number**)
- **number**：介于 -1 到 1 之间的实数。
## 示例{#examples}
1. `ASIN(0.8)=0.9272952180016123`
2. `ASIN(-0.5)=-0.5235987755982989`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ACOS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/acos"
title: "ACOS - 返回数值的反余弦值"
---
# **ACOS**
返回数值的反余弦值。
## 语法{#grammar}
ACOS(**number**)
- **number**：介于 -1 到 1 之间的实数。
## 示例{#examples}
1. `ACOS(-0.5)=2.0943951023931957`
2. `ACOS(-0.5)*180/PI()=120` 以度表示-0.5的反余弦值
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ATAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/atan"
title: "ATAN - 返回数值的反正切值"
---
# **ATAN**
返回数值的反正切值。
## 语法{#grammar}
ATAN(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `ATAN(1)=0.7853981633974483`
2. `ATAN(-6)=-1.4056476493802699`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/COT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/cot"
title: "COT - 返回给定角度的余切值"
---
# **COT**
返回给定角度的余切值。
## 语法{#grammar}
COT(**angle**)
- **angle**：角度，以弧度表示。
## 示例{#examples}
1. `COT(3)=-7.015252551434530`
2. `COT(PI()/2)=0` 90度的余切值
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SEC.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sec"
title: "SEC - 返回给定角度的正割值"
---
# **SEC**
返回给定角度的正割值。
## 语法{#grammar}
SEC(**angle**)
- **angle**：角度，以弧度表示。
## 示例{#examples}
1. `SEC(75)=1.084891372374910`
2. `SEC(PI())=-1.0` 180度的正割值
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/CSC.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/csc"
title: "CSC - 返回给定角度的余割值"
---
# **CSC**
返回给定角度的余割值。
## 语法{#grammar}
CSC(**angle**)
- **angle**：角度，以弧度表示。
## 示例{#examples}
1. `CSC(15)=1.537780561540850`
2. `CSC(PI()/2)=1.0` 90度的余割值
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SINH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sinh"
title: "SINH - 返回数值的双曲正弦值"
---
# **SINH**
返回数值的双曲正弦值。
## 语法{#grammar}
SINH(**number**)
- **number**：为任意实数。
## 示例{#examples}
1. `SINH(1)=1.1752011936438014`
2. `SINH(-1)=-1.1752011936438014`
## 详细描述
求指定数值的双曲正弦值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/COSH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/cosh"
title: "COSH - 返回数值的双曲余弦值"
---
# **COSH**
返回数值的双曲余弦值。
## 语法{#grammar}
COSH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `COSH(0)=1.0`
2. `COSH(2.99)=9.967984964144161`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/TANH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tanh"
title: "TANH - 返回数值的双曲正切值"
---
# **TANH**
返回数值的双曲正切值。
## 语法{#grammar}
TANH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `TANh(-2)=-0.9640275800758169`
2. `TAN(0)=0`
## 详细描述
该函数返回某一数值的双曲正切值，以弧度表示。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ASINH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/asinh"
title: "ASINH - 返回数值的反双曲正弦值"
---
# **ASINH**
返回数值的反双曲正弦值。
## 语法{#grammar}
ASINH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `ASINH(10)=2.99822295029797`
2. `ASINH(-2.5)=-1.6472311463710965`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ACOSH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/acosh"
title: "ACOSH - 返回数值的反双曲余弦值"
---
# **ACOSH**
返回数值的反双曲余弦值。
## 语法{#grammar}
ACOSH(**number**)
- **number**：大于或等于 1 的任意实数。
## 示例{#examples}
1. `ACOSH(1)=0`
2. `ACOSH(10)=2.993222846126381`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ATANH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/atanh"
title: "ATANH - 返回数值的反双曲正切值"
---
# **ATANH**
返回数值的反双曲正切值。
## 语法{#grammar}
ATANH(**number**)
- **number**：-1 到 1 之间的任意实数。
## 示例{#examples}
1. `ATANH(0.76159416)=1.0000000096297197`
2. `ATANH(-0.1)=-0.10033534773107562`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ACOT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/acot"
title: "ACOT - 返回数值的反余切值"
---
# **ACOT**
返回数值的反余切值。
## 语法{#grammar}
ACOT(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `ACOT(6)=0.165148677414627`
2. `ACOT(-2)=2.677945044588990`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/ACOTH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/acoth"
title: "ACOTH - 返回数值的反双曲余切值"
---
# **ACOTH**
返回数值的反双曲余切值。
## 语法{#grammar}
ACOTH(**number**)
- **number**：绝对值大于 1 的任意实数。
## 示例{#examples}
1. `ACOTH(6)=0.168236118310606`
2. `ACOTH(-2)=-0.549306144334055`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/COTH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/coth"
title: "COTH - 返回数值的双曲余切值"
---
# **COTH**
返回数值的双曲余切值。
## 语法{#grammar}
COTH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `COTH(2)=1.037314720727550`
2. `COTH(-1)=-1.313035285499330`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/CSCH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/csch"
title: "CSCH - 返回数值的双曲余割值"
---
# **CSCH**
返回数值的双曲余割值。
## 语法{#grammar}
CSCH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `CSCH(1.5)=0.469642440595225`
2. `CSCH(-1)=-0.850918128239322`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/SECH.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sech"
title: "SECH - 返回数值的双曲正割值"
---
# **SECH**
返回数值的双曲正割值。
## 语法{#grammar}
SECH(**number**)
- **number**：任意实数。
## 示例{#examples}
1. `SECH(1.5)=0.425096034942280`
2. `SECH(-1)=0.648054273663885`
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/BITAND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/bitand"
title: "BITAND - 返回参数的按位与值"
---
# **BITAND**
返回参数的按位与值。
## 语法{#grammar}
BITAND(**x1** ,**x2**, **...**, **xN**)
- **xN**：必需，被操作的数值。不少于2个。
## 示例{#examples}
1. `BITAND(0,1)=0`
2. `BITAND(1,1)=1`
## 详细描述
该函数返回对所有参数进行按位与操作后的结果。参数必须大于等于2个。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/BITOR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/bitor"
title: "BITOR - 返回参数的按位或值"
---
# **BITOR**
返回参数的按位或值。
## 语法{#grammar}
BITOR(**x1** ,**x2**, **...**, **xN**)
- **xN**：必需，被操作的数值。不少于2个。
## 示例{#examples}
1. `BITOR(0,1)=1`
2. `BITOR(1,1)=1`
## 详细描述
该函数返回对所有参数进行按位或操作后的结果。参数必须大于等于2个。
---
url: "https://docs.succapp.com/v5/guide/exp/func/math/BITXOR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/bitxor"
title: "BITXOR - 返回参数的按位异或值"
---
# **BITXOR**
返回参数的按位异或值。
## 语法{#grammar}
BITXOR(**x1** ,**x2**, **...**, **xN**)
- **xN**： 必需，被操作的数值。不少于两个
## 示例{#examples}
1. `BITXOR(0,1)=1`
2. `BITXOR(1,1)=0`
## 详细描述
该函数返回对所有参数进行按位异或操作后的结果。参数必须大于等于2个。
---
url: "https://docs.succapp.com/v5/guide/exp/func/logic/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/logic-funcs"
title: "逻辑函数列表"
---
---
navTitle: 逻辑函数
---
# 逻辑函数列表
!!!children (guide/exp/func/logic)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/logic/IF.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/if"
title: "IF - 判断某个表达式的布尔值"
---
# **IF**
判断某个表达式的布尔值，根据结果返回相应的值，支持多层嵌套。
## 语法{#grammar}
IF(**expression**, **result1**, **\[result2]**)
- **expression**：必需，作判断的表达式
- **result1**：必需，表达式判断结果为 *true* 时返回的值
- **result2**：可选，表达式判断结果为 *false* 时返回的值
## 示例{#example}
1. `IF(1=1,"right","wrong")` 表达式判断为真，返回字符串`right`
2. `IF(A2>0,"增加",if(A2=0,"持平","下降"))` 引用单元格，支持多层嵌套
3. `IF([利润]>0,"盈利",if([利润]=0,"盈亏平衡","亏损"))` 引用模型字段
---
url: "https://docs.succapp.com/v5/guide/exp/func/logic/IFNULL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/ifnull"
title: "IFNULL - 返回第一个不为 *null* 的表达式的值"
---
# **IFNULL**
返回第一个不为 *null* 的表达式的值，如果都为 *null* ，则返回 *null* ，支持同时设置多个表达式。
## 语法{#grammar}
IFNULL(**expression1**, **expression2**, **...**, **expressionN**)
- **expressionN**：必需，作判断的表达式或字段，至少两个，支持同时设置多个
## 示例{#example}
1. `IFNULL(null,'first')` 返回第一个不为 *null* 的字符串`first`
2. `IFNULL(null,null,'非null')` 表达式为多个，返回第一个不为 *null* 的字符串`非null`
3. `IFNULL('','为null返回值')` 表达式为空字符串，空字符串不为 *null* ，返回空字符串
4. `IFNULL(0,'为空返回值')` 表达式为0，返回数值`0`
5. `IFNULL(A2,"暂无数据")` 引用单元格，判断`A2`是否为空
6. `IFNULL([企业基本信息].[人员规模],"暂无数据")` 引用模型字段，判断`[人员规模]`是否为空
---
url: "https://docs.succapp.com/v5/guide/exp/func/logic/ISNUMBER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/isnumber"
title: "ISNUMBER - 检查参数是否为数值"
---
# **ISNUMBER**
检查参数是否为数值，如果是返回 *true* ，否则返回 *false* 。
## 语法{#grammar}
ISNUMBER(**param**)
- **param**：要检查的值
## 示例{#example}
1. `ISNUMBER(123)` 参数为数值，返回`true`
2. `ISNUMBER("123")` 参数为字符串，返回`false`
3. `ISNUMBER("a")` 参数为字符串，返回`false`
4. `ISNUMBER('')` 参数为空字符串，返回`false`
5. `ISNUMBER(YEAR("20220101"))` 参数为函数返回值，返回`true`，[YEAR](../date/YEAR.md)函数返回值为数值
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/aggregate-funcs"
title: "聚合函数列表"
---
---
navTitle: 聚合函数
---
# 聚合函数列表
!!!children (guide/exp/func/aggregate)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/SUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/sum"
title: "SUM - 计算合计值"
---
# **SUM**
计算合计值。
SUM函数可用于数据统计查询时的合计值统计，也可以用于多个值之间的加法计算：
- 聚合统计：对一个字段或表达式进行聚合统计，此时只能传递一个参数，通常是传递要统计合计值的字段，等同于数据库的SUM函数。
- 四则运算：对多个值进行加法计算，等价于使用加号`+`，也可以合计浮动数据和数组，此时SUM就不是一个聚合统计函数了。
## 语法{#grammar}
SUM(**param1**, **param2**, **...**, **paramN**)
- **paramN**：必需。在查询统计中传递一个参数表示统计合计值，传递多个值、单元格区块、数组对象时表示加法运算。
## 示例{#example}
**示例地址：** [SUM](https://demo.succbi.com/v5/bi/sum)。
用于合计统计，此时只能传递一个参数，常量或字段：
1. `SUM(1)` 求行数，等价于 `COUNT()`。
2. `SUM(model1.field1)` 统计字段field1的合计值，如果每行field1字段都为null，或者一行数据也没有，返回null。
3. `SUM(model1.field1+model1.field2)` 统计字段field1+field2的合计值，等价于 `SUM(model1.field1)+SUM(model1.field2)`。
用于加法运算，传递多个参数：
1. `SUM(-1,1.1,2.2,3.3,4.4)` 传入多个数值，返回 `10`。
2. `SUM(ARR(1,2,3))` 传入数组，返回数值`6`，传递数组时不支持在SQL中运算。
3. `SUM(ARR(1,2),2,ARR(2,3))` 传入数组和数值，等价于对数组和数值分别求和后相加，返回`10`。
4. `SUM(1,2,'3')` 数值和非数值型数字，会自动尝试将字符串转换为数字，返回数值`6`。
5. `SUM(1,2,"山"," ","!")` 忽略非数值字符串，返回`3`，传递非数值字符串时不支持在SQL中运算。
6. `SUM('a','山',' ','!')` 全为非数值字符串，返回`NULL`。
7. `SUM(1,2,NULL,3)` 自动忽略`NULL`，返回数值`6`。
8. `SUM(NULL,NULL,NULL)` 全为`NULL`，返回`NULL`。
9. `SUM(1+1,4-3,3*5,6/3)` 表达式，返回数值`20`。
10. `SUM(1,2,3)+SUM(1,2)` 四则运算，返回数值`9`。
11. `SUM(2,3,7)/SUM(1,2,3)` 四则运算，返回数值`2`。
用于浮动区域的合计值计算，传递单元格序列或浮动组件：
1. `SUM(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的总和。报表分页时，计算当前页浮动单元格`A2`数据的总和。
2. `SUM(A2:A5)` 计算A2、A3、A4、A5这几个连续的单元格的合计值。
3. `SUM(A2:A5,B2:B5)` 计算2个连续单元格的合计值，等价于`SUM(A2:A5)+SUM(B2:B5)`。
4. `SUM(input1)` input1是浮动面板内部的一个数值输入框，计算所有浮动面板内的input1的总和。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/COUNT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/count"
title: "COUNT - 计数统计（不去重）"
---
# **COUNT**
计数统计（不去重）。
COUNT函数可用于数据统计查询时的计数统计，也可以用于多个值之间计数计算。COUNT函数只会忽略空值，不会去重数据，去重可以使用[COUNTD](./COUNTD.md)函数。
- 聚合统计：对一个字段或表达式进行聚合统计，计算非空值的数量。此时只能传递一个参数，通常是传递要计数的字段，等同于数据库的COUNT函数。
- 四则运算：对多个值进行计数计算，也可以计数浮动数据和数组，此时COUNT就不是一个聚合统计函数了。
## 语法{#grammar}
COUNT(**field**)
- **field**：必需。事实表中的字段，支持任意类型。
**示例地址：** [COUNT](https://demo.succbi.com/v5/bi/count)
## 示例{#example}
用于计数统计，此时只能传递一个参数，字段或表达式：
1. `COUNT(model1.field1)` 统计字段field1的计数值，如果每行field1字段都为null，或者一行数据也没有，返回null。
2. `COUNT([门店月销汇总表].[门店])` 参数为数据模型字段，返回该字段的计数。
用于求计数值，传递多个参数：
3. `COUNT(ARR(1,1,2,2,3))` 参数为数组，含重复数据不会去重返回`5`。
4. `COUNT(ARR(1,2,NULL,3))` 参数为数组，含空值时会忽略空值返回`3`。
5. `COUNT(ARR(1,2,"",3))` 参数为数组，含空字符串时会忽略空字符串返回`3`。
用于浮动区域的计数值计算，传递单元格序列或浮动组件：
6. `COUNT(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/COUNTD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/countd"
title: "COUNTD - 计数统计（去重）"
---
# **COUNTD**
计数统计（去重）。
COUNTD函数可用于数据统计查询时的去重计数统计，也可以用于多个值之间计数计算。COUNTD函数会忽略空值，去重数据，不去重可以使用[COUNT](./COUNT.md)函数。
- 聚合统计：对一个字段或表达式进行聚合统计，计算非空值的数量。此时只能传递一个参数，通常是传递要计数的字段，等同于数据库的COUNTD函数。
- 四则运算：对多个值进行计数计算，也可以计数浮动数据和数组，此时COUNTD就不是一个聚合统计函数了。
## 语法{#grammar}
COUNTD(**field**)
- **field**：必需。事实表的字段，支持任意类型。
**示例地址：** [COUNTD](https://demo.succbi.com/v5/bi/countd)
## 示例{#example}
用于去重计数统计，此时只能传递一个参数，字段或表达式：
1. `COUNTD(model1.field1)` 统计字段field1的计数值，如果每行field1字段都为null，或者一行数据也没有，返回null。
2. `COUNTD([企业投资关系].[投资企业内部序号])` 参数为数据模型字段，返回该字段的去重计数。
用于求去重计数值，传递多个参数：
3. `COUNTD(ARR(1,1,2,2,3))` 参数为数组，含重复数据会去重返回`3`。
4. `COUNTD(ARR(1,2,NULL,3))` 参数为数组，含空值时会忽略空值返回`3`。
5. `COUNTD(ARR(1,2,"",3))` 参数为数组，含空字符串时会忽略空字符串返回`3`。
用于求浮动区域的去重计数值，传递单元格序列或浮动组件：
6. `COUNTD(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/AVG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/avg"
title: "AVG - 计算平均值"
---
# **AVG**
计算平均值。
AVG函数可用于数据统计查询时的平均值统计，也可以用于多个值之间的求平均值计算：
- 聚合统计：对一个字段或表达式进行聚合统计，此时只能传递一个参数，通常是传递要统计平均值的字段，等同于数据库的AVG函数。
- 四则运算：对多个值进行求平均值计算，也可以合计浮动数据和数组，此时AVG就不是一个聚合统计函数了。
## 语法{#grammar}
AVG(**param1**, **param2**, **...**, **paramN**)
- **paramN**：必需。在查询统计中传递一个参数表示统计平均值，传递多个值、单元格区块、数组对象时表示求平均值运算。
**示例地址：** [AVG](https://demo.succbi.com/v5/bi/avg)
## 示例{#example}
用于统计平均值，此时只能传递一个参数，字段或表达式：
1. `AVG(model1.field1)` 统计字段field1的平均值，如果每行field1字段都为null，或者一行数据也没有，返回null。
用于求平均值运算，传递多个参数：
2. `AVG(1,2,3)` 正整数，返回数值`2`。
3. `AVG(ARR(1,2,3))` 常量数组，返回数值`2`。
4. `AVG(ARR(1,2),0,ARR(4,5))` 数值和数组，返回数值`2.4`。
5. `AVG(1,2,'3')` 数值和非数值型数字，返回数值`2`，字符串`'3'`转为数值计算。
6. `AVG(-1,-2,-3)` 负数，返回数值`-2`。
7. `AVG(1.2,2.3,3.4)` 小数，返回数值`2.3`。
8. `AVG(1+1,4-3,3*5,6/3)` 表达式，返回数值`5`。
9. `AVG(1,2,'')` 含空字符串，返回数值`1.5`，忽略该空字符串。
10. `AVG(1,2,NULL)` 含`NULL`，返回数值`1.5`，忽略`NULL`参数。
11. `AVG(1,2,3)+AVG(1,2)` 四则运算，返回数值`3.5`。
12. `AVG(2,3,7)/AVG(1,2,3)` 四则运算，返回数值`2`。
用于浮动区域的合计值计算，传递单元格序列或浮动组件：
13. `AVG(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的平均值。报表分页时，计算当前页浮动单元格`A2`数据的平均值。
14. `AVG(A2:A5)` 计算A2、A3、A4、A5这几个连续的单元格的平均值。
15. `AVG(A2:A5,B2:B5)` 计算2个连续单元格的平均值。
16. `AVG(input1)` input1是浮动面板内部的一个数值输入框，计算所有浮动面板内的input1的平均值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/MAX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/max"
title: "MAX - 计算最大值"
---
# **MAX**
计算最大值。
MAX函数可用于数据统计查询时的最大值统计，也可以用于多个值之间的求最大值计算：
- 聚合统计：对一个字段或表达式进行聚合统计，此时只能传递一个参数，通常是传递要统计最大值的字段，等同于数据库的MAX函数。
- 四则运算：对多个值进行求最大值计算，也可以合计浮动数据和数组，此时MAX就不是一个聚合统计函数了。
## 语法{#grammar}
MAX(**param1**, **param2**, **...**, **paramN**)
- **paramN**：必需。在查询统计中判断该参数内最大值，传递多个值、单元格区块、数组对象时表示计算多个区域内的最大值。
**示例地址：** [MAX](https://demo.succbi.com/v5/bi/max)
## 示例{#example}
用于最大值统计，传入一个参数、字段或表达式：
1. `MAX(model1.field1)` 计算字段field1的最大值，如果每行field1字段都为null，或者一行数据也没有，返回null。
用于找到数组最大值，传入多个值或数组：
2. `MAX(1.2,2.3,3.4)` 数值，返回数值`3.4`。
3. `MAX(ARR(1,2,3))` 数组，返回数值`3`。
4. `MAX("a","b","bA","bB","A")` 字母，返回字符串`bB`，按Unicode编码逐字符比较。
5. `MAX(ARR(1,2),99,ARR(11,13,14))` 数值和数组，返回数值`99`。
6. `MAX(12,23,'123')` 数值和非数值型数字，返回数值`123`，`'123'`转成数值计算。
7. `MAX(1+1,4-3,3*5,6/3)` 表达式，返回数值`15`。
8. `MAX(1,2,NULL,3)` 含有`NULL`，返回数值`3`，忽略`NULL`。
9. `MAX(NULL,NULL,NULL)` 全为`NULL`，返回`NULL`。
用于找到浮动区域的最大值，传递单元格序列或浮动组件：
10. `MAX(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的最大值。报表分页时，计算当前页浮动单元格`A2`数据的最大值。
11. `MAX(A2:A5)` 计算A2、A3、A4、A5这几个连续的单元格最大值。
12. `MAX(A2:A5,B2:B5)` 计算2个连续单元格的最大值。
13. `MAX(input1)` input1是浮动面板内部的一个数值输入框，计算所有浮动面板内的input1的最大值。
[//]: # "在判断最大值时，可以对多种类型进行判断，不同类型的判断会根据 unicode 码的先后进行判断。如'A'比'a'大。"
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/MIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/min"
title: "MIN - 计算最小值"
---
# **MIN**
计算最小值。
MIN函数可用于数据统计查询时的最小值统计，也可以用于多个值之间的求最小值计算：
- 聚合统计：对一个字段或表达式进行聚合统计，此时只能传递一个参数，通常是传递要统计最小值的字段，等同于数据库的MIN函数。
- 四则运算：对多个值进行求最小值计算，也可以合计浮动数据和数组，此时MIN就不是一个聚合统计函数了。
## 语法{#grammar}
MIN(**param1**, **param2**, **...**, **paramN**)
- **paramN**：必需。在查询统计中判断该参数内最小值，传递多个值、单元格区块、数组对象时表示计算多个区域内的最小值。
**示例地址：** [MIN](https://demo.succbi.com/v5/bi/min)
## 示例{#example}
用于最小值统计，传入一个参数、字段或表达式：
1. `MIN(model1.field1)` 计算字段field1的最小值，如果每行field1字段都为null，或者一行数据也没有，返回null。
用于找到数组最小值，传入多个值或数组：
2. `MIN(1.2,2.3,3.4)` 数值，返回数值`1.2`。
3. `MIN(ARR(1,2,3))` 数值，返回数值`1`。
4. `MIN("a","b","Ab","bB","Aa")` 字母，返回字符串`Aa`，按Unicode编码逐字符比较。
5. `MIN(ARR(1,2),99,ARR(11,13,14))` 数值和数组，返回数值`1`。
6. `MIN(123,23,'12')` 数值和非数值型数字，返回数值`12`，`'12'`转成数值计算。
7. `MIN(1+1,4-3,3*5,6/3)` 表达式，返回数值`1`。
8. `MIN(1,2,NULL,3)` 含有`NULL`，返回数值`1`，忽略`NULL`。
9. `MIN(NULL,NULL,NULL)` 全为`NULL`，返回`NULL`。
用于找到浮动区域的最小值，传递单元格序列或浮动组件：
10. `MIN(A2)` A2是浮动区域内的单元格，计算浮动单元格`A2`数据的最小值。报表分页时，计算当前页浮动单元格`A2`数据的最小值。
11. `MIN(A2:A5)` 计算A2、A3、A4、A5这几个连续的单元格最小值。
12. `MIN(A2:A5,B2:B5)` 计算2个连续单元格的最小值。
13. `MIN(input1)` input1是浮动面板内部的一个数值输入框，计算所有浮动面板内的input1的最小值。
[//]: # "在判断最小值时，可以对多种类型进行判断，不同类型的判断会根据 unicode 码的先后进行判断。如'A'比'a'小。"
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/STDEV.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/stdev"
title: "STDEV - 计算样本标准偏差"
---
# **STDEV**
计算样本标准偏差。
STDEV计算给定数据的样本标准偏差。用于衡量抽样数据的波动性，会忽略数据中的 *NaN* 值。
## 语法{#grammar}
STDEV(**number1**, **number2**, **...**, **numberN**)
- **numberN**：对应于总体样本的数字参数。还可以使用单个数组或对数组的引用，而不是由逗号分隔的参数。
## 示例{#examples}
1. `STDEV(arr(2,3,4))=1.0` 传入一个整数数组，返回数值`1.0`。
2. `STDEV(1,2,3,4)=1.2909944487358056` 传入数值，返回数值`1.2909944487358056`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/VAR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/var"
title: "VAR - 计算样本方差"
---
# **VAR**
计算样本方差。
VAR是一个统计聚合函数，用于衡量样本数据的离散程度。它通过计算数据点与样本均值的平均平方偏差，反映数据分布的波动性。
## 语法{#grammar}
VAR(**arr**)
- **arr**：必需。需要计算方差的数组，数组的元素可以是整形或者浮点型的数值，表示需要计算方差的数据序列。
## 示例{#examples}
1. `VAR(arr(1,2,3,4,5))=2.5` 传入一个整数数组，返回数值`2.5`。
2. `VAR(arr(3,4,4,5,4))=0.5` 传入一个整数数组，返回数值`0.5`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/MEDIAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/median"
title: "MEDIAN - 计算数组的中值"
---
# **MEDIAN**
计算数组的中值。
MEDIAN用于计算一组数据的中间值，如果数组内数字有奇数个，返回数组位于中间位置的数。如果数组内数字有偶数个，返回位于中间的两个数的平均值。
## 语法{#grammar}
MEDIAN(**arr**)
- **arr**：数组对象。
## 示例{#examples}
1. `MEDIAN(arr(1,2,3))=2` 传入一个整数数组，返回数值`2`。
2. `MEDIAN(arr(1,2,3,4)=2.5` 传入一个整数数组，返回数值`2.5`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/QUANTILE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/quantile"
title: "QUANTILE - 计算分位数值"
---
# **QUANTILE**
计算分位数值。
QUANTILE用于计算数组的四分位数，即数组元素从小到大排列后的四分位数。若 *quart* < 0 或 *quart* > 4 ,则返回空值；若 *quart* 不为整数，则截尾取整。忽略 *NaN* 值。
## 语法{#grammar}
QUANTILE(**arr**, **quart**)
- **arr**：数组对象。
- **quart**：返回哪一个四分位值。
* 0：最小值
* 1：第一个四分位数
* 2：第二个四分位数（中位数）
* 3：第三个四分位数
* 4：最大值
## 示例{#examples}
1. `QUANTILE(arr(1,2,3,4),1)=1.75` 传入数组和数值，返回数值`1.75`。
2. `QUANTILE(arr(1,2,3,4),3)=3.25` 传入数组和数值，返回数值`3.25`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/STDEVP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/stdevp"
title: "STDEVP - 计算总体标准偏差"
---
# **STDEVP**
计算总体标准偏差。
STDEVP计算给定数据的总体标准偏差。用于衡量总体数据的波动性，会忽略数据中的 *NaN* 值。
## 语法{#grammar}
STDEVP(**values**, **size**, **ignoreNan**)
- **values**：需要计算总体标准差的数据。
- **size**：可选，参与计算总体标准差的数据个数，省略时全部计算。
- **ignoreNan**：可选，在计算过程中值为 *NaN* 的数据不参与计算的数据个数，省略时不参与计算。
## 示例{#examples}
1. `STDEVP(arr(2,3,4))=0.8164965809277257` 传入一个整数数组，返回数值`0.8164965809277257`。
2. `STDEVP([1,2,3,"a"],4)=0.8164965809277263` 传入数组和数值，忽略数组中的a字符，返回数值`0.8164965809277257`。
3. `STDEVP([1,2,3,"a"],4,0)=1.118033988749895` 传入数组和数值，0参与计算，返回数值`1.118033988749895`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/VARP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/varp"
title: "VARP - 计算总体方差"
---
# **VARP**
计算总体方差。
VARP是一个统计聚合函数，用于衡量完整总体的离散程度。它直接计算所有数据点与总体均值的平方偏差平均值，反映数据分布的波动性。
## 语法{#grammar}
VARP(**arr**)
- **arr**：必需。需要计算总体方差的数组，数组的元素可以是整形或者浮点型的数值，表示需要计算总体方差的数据序列。
## 示例{#examples}
1. `VARP(arr(1,2,3,4,5))=2` 传入一个整数数组，返回数值`2`。
2. `VARP(arr(3,4,4,5,4))=0.4` 传入一个整数数组，返回数值`0.4`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/COVAR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/covar"
title: "COVAR - 计算协方差"
---
# **COVAR**
计算协方差。
COVAR函数是计算两个变量的协方差函数，用于量化两个数据集的线性关联程度，分析数据的相关性。
## 语法{#grammar}
COVAR(**x**, **y**)
- **x**：计算协方差的第一个数据数组。
- **y**：计算协方差的第二个数据数组。
## 示例{#examples}
1. `COVAR(arr(1,2,3),array(3,4,5))=1.0` 传入两个整数数组，返回数值`1.0`。
2. `COVAR(arr(1.3,2.5,3.6),arr(3.8,4.4,5.6))=1.03` 传入两个小数数组，返回数值`1.03`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/GEOMEAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/geomean"
title: "GEOMEAN - 计算几何平均数"
---
# **GEOMEAN**
计算几何平均数。
GEOMEAN函数用于计算一组数组的几何平均数，用于处理乘法关系的数据，分析增长率、比率。数组中的 *NaN* 以及非正数的元素在计算时将被忽略;当传入的数组中包含的正数个数为0时，返回空值。
## 语法{#grammar}
GEOMEAN(**arr**)
- **arr**：数组对象。
## 示例{#examples}
1. `GEOMEAN(arr(2,3,4,5)=3.309750919646873` 传入一个整数数组，返回数值`3.309750919646873`。
2. `GEOMEAN(arr(-1,2,3,4,5))=3.309750919646873` 传入一个带负数的数组，-1被忽略了，返回数值`3.309750919646873`。
3. `GEOMEAN(arr(3,3,4,6))=4` 传入一个整数数组，返回数值`4`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/aggregate/AVEDEV.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/avedev"
title: "AVEDEV - 计算平均偏差"
---
# **AVEDEV**
计算平均偏差。
AVEDEV函数是一个统计聚合函数，用于衡量一组数据的离散程度。分析数据的变异性和稳定性。
## 语法{#grammar}
AVEDEV(**param**)
- **param**：任意多个数值类型参数或一个数组参数。
## 示例{#examples}
1. `avedev(arr(1,2,2))=0.4444444444444444` 传入一个整数数组，返回数值`0.4444444444444444`。
2. `avedev(1.3,2.5,2.6)=0.5555555555555556` 传入一个小数数组，返回数值`0.5555555555555556`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/analysis-funcs"
title: "分析函数列表"
---
---
navTitle: 分析函数
---
# 分析函数列表
!!!children (guide/exp/func/analysis)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/PRE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/pre"
title: "PRE - 计算上期的统计数值"
---
# **PRE**
计算上期的统计数值。
此函数的计算，需要数据模型是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
PRE(**field**, **\[offset]**, **\[periodField]**)
- **field**：数值类型的表达式，一般是度量的字段名，如果没有统计方法，数值类型默认取合计值，字符类型默认取最大值
- **offset**：可选。数据偏移参数，支持具体的数据期
- `PP` 默认值，表示取上期，等价于整数`-1`
- `NP` 表示取下期
- `YA` 表示取去年同期
- `FM` 表示取年初
- **periodField**：可选。指定数据期字段，默认取模型设置的数据期字段，但是当模型有多个业务数据期字段时，比如说合同签订时间、到货时间、打款时间等等，不同的度量需要根据不同时间计算同环比，此时可以使用数据期字段参数来指定。
## 示例{#example}
1. `PRE([销售数量])` 上期合计值，默认取合计值`7214`
2. `PRE(AVG([销售数量]),'PP')` 'PP' 表示取上期，返回上期平均值`18.3096`
3. `PRE([销售数量],'NP')` 'NP' 表示取下期，返回下期合计值`5507`
4. `PRE([销售数量],'YA')` 'YA' 表示取去年同期，返回去年同期的合计值`4934`
5. `PRE([销售数量],'FM')` 'FM' 表示取年初，返回年初合计值`4788`
6. `PRE([销售数量],'201801')` 指定数据期为201801的合计值`4788`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/ROW_NUMBER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/row_number"
title: "ROW_NUMBER - 返回排序字段值的唯一排名"
---
# **ROW\_NUMBER**
返回排序字段值的唯一排名。
(6, 9, 9, 14) 按升序排列为 (1, 2, 3, 4)。
## 语法{#grammar}
ROW\_NUMBER(**orderfield**, **\[ordertype]**, **\[partitionfield]**,...)
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby括起
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
- **partitionfield**：可选，分组字段，可以设置多个，表示指定分组内的排名；不指定，则表示全部数据的排名
## 示例{#example}
1. `ROW_NUMBER([销售数量])` 按照销售数量排名，默认升序
2. `ROW_NUMBER([销售数量],'desc')` 按照销售数量降序排名
3. `ROW_NUMBER(ORDERBY([销售数量],[上下装],[价格档次]))` 按照销售数量、上下装、价格档次升序排名
4. `ROW_NUMBER(ORDERBY([销售数量]),[日销单ID])` 按订单号分组，按照销售数量升序的排名
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RANK.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rank"
title: "RANK - 返回排序字段值的标准竞争排名"
---
# **RANK**
返回排序字段值的标准竞争排名。
(6, 9, 9, 14) 按升序排列为 (1, 2, 2, 4)。
## 语法{#grammar}
RANK(**orderfield**, **\[ordertype]**, **\[partitionfield]**,...)
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby括起
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
- **partitionfield**：可选，分组字段，可以设置多个，表示指定分组内的排名；不指定，则表示全部数据的排名
## 示例{#example}
1. `RANK([销售数量])` 按照销售数量排名，默认升序
2. `RANK([销售数量],'desc')` 按照销售数量降序排名
3. `RANK(ORDERBY([销售数量],[上下装],[价格档次]))` 多个分组，按照销售数量升序排名
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/YOY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/yoy"
title: "YOY - 计算同比增幅"
---
# **YOY**
计算同比增幅，返回百分比。
同比增幅 = (本期值 - 去年同期值) / 去年同期值。此函数的计算，是相对去年同期的`比值`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
YOY(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `YOY([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/MOM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/mom"
title: "MOM - 计算环比增幅"
---
# **MOM**
计算环比增幅，返回百分比。
环比增幅 = (本期值 - 上期值) / 上期值。此函数的计算，是相对上期的`比值`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
MOM(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `MOM([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/MOFM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/mofm"
title: "MOFM - 计算年初增幅"
---
# **MOFM**
计算年初增幅，返回百分比。
年初增幅 = (本期值 - 年初值) / 年初值。此函数的计算，是相对年初的`比值`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
MOFM(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `MOFM([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/FIRST_VALUE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/first_value"
title: "FIRST_VALUE - 返回某个区域数据中的第一个值"
---
# **FIRST\_VALUE**
返回某个区域数据中的第一个值。
## 语法{#grammar}
FIRST\_VALUE(**field**, **partitionfield**, **orderfield**, **ordertype**)
- **field**：必需，字段名。
- **partitionfield**：必需，分组字段；如果不需要分组字段，传null；如果有多个分组字段的时需使用partitionby。
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby。
- **ordertype**：可选，指定排序类型，'asc' 升序，'desc' 降序，默认为升序。
## 示例{#examples}
1. `FIRST_VALUE([纳税表].[企业], null, [纳税表].[纳税额])` 按\[纳税表].\[纳税额]升序排列取第一个企业。
2. `FIRST_VALUE([纳税表].[企业], [纳税表].[地区], [纳税表].[纳税额],'DESC')` 按地区分组，纳税额降序排列取第一个企业。
3. `FIRST_VALUE([纳税表].[企业], partitionby([纳税表].[地区], [纳税表].[行业]), [纳税表].[纳税额])` 按地区和行业分组，取纳税额升序的第一个企业。
4. `FIRST_VALUE([纳税表].[企业], null, orderby([纳税表].[月份],'ASC',[纳税表].[纳税额],'DESC'))` 按月份升序、纳税额降序，取第一个企业。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/LAST_VALUE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/last_value"
title: "LAST_VALUE - 返回某个区域数据中的最后一个值"
---
# **LAST\_VALUE**
返回某个区域数据中的最后一个值。
## 语法{#grammar}
LAST\_VALUE(**field**, **partitionfield**, **orderfield**, **ordertype**)
- **field**：必需，字段名。
- **partitionfield**：必需，分组字段；如果不需要分组字段，传null；如果有多个分组字段的时需使用partitionby。
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby。
- **ordertype**：可选，指定排序类型，'asc' 升序，'desc' 降序，默认为升序。
## 示例{#examples}
1. `LAST_VALUE([纳税表].[企业], null, [纳税表].[纳税额])` 按\[纳税表].\[纳税额]升序排列，取最后一个企业。
2. `LAST_VALUE([纳税表].[企业], [纳税表].[地区], [纳税表].[纳税额], 'DESC')` 按地区分组，纳税额降序排列，取最后一个企业。
3. `LAST_VALUE([纳税表].[企业], partitionby([纳税表].[地区], [纳税表].[行业]), [纳税表].[纳税额])` 按地区、行业分组，纳税额升序排列，取最后一个企业。
4. `LAST_VALUE([纳税表].[企业], null, orderby([纳税表].[月份],'ASC',[纳税表].[纳税额],'DESC'))` 按月份升序、纳税额降序排列，取最后一个企业。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/GROUP_CONCAT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/group_concat"
title: "GROUP_CONCAT - 将字段的值连接为指定分隔符分隔的字符串"
---
# **GROUP\_CONCAT**
将字段的值连接为指定分隔符分隔的字符串。
## 语法{#grammar}
GROUP\_CONCAT(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**, **\[separator]**, **\[maxlength]**)
- **field**：必需，要连接的字段
- **partitionfield**：可选，分组字段，使用partitionby括起，只在oracle有效
- **orderfield**：可选，排序字段，field字段值按什么顺序连接，使用orderby括起，只在mysql和oracle有效
- **ordertype**：可选，指定排序类型，'asc'升序，'desc'降序，默认为升序
- **separator**：可选，分隔符，默认为逗号
- **maxlength**：可选，连接字符串的最大长度，只在vertica和oracle有效
## 示例{#example}
1. `GROUP_CONCAT([电影演员表].[电影名称],"、")` 用顿号连接演员参演电影名称
2. `GROUP_CONCAT([电影演员表].[电影名称],ORDERBY([电影演员表].[排序序号],'desc'),"、")` 用顿号连接演员参演电影名称，以排序序号降序排列
不同的数据库用法不同，下面分数据库举例。
### Oracle
使用listagg实现，支持Oracle11及以上版本，是一个聚合函数，也是窗口函数，支持partitionby子句。
- maxlength 由于oracle的字符串varchar大小限制为4000，因此使用listagg拼接字符串时可能会出现字符串长度超过限制的异常，使用xmlagg+xmlparse来代替，
当指定maxlength大于4000，使用xmlagg+xmlparse来实现。注意：***代替的方法不支持partitionby子句***。
1. `GROUP_CONCAT([主体登记表].[经营范围], ';')` 按groupby语句分组，用分号连接经营范围。
2. `GROUP_CONCAT([主体登记表].[经营范围], orderby([主体登记表].[注册资金], 'desc'), ';')` 按groupby语句分组，注册资金降序，用分号连接经营范围。
3. `GROUP_CONCAT([主体登记表].[经营范围], partitionby([主体登记表].[法人]), orderby([主体登记表].[注册资金], 'desc'))` 按企业法人分组，注册资金降序，用逗号连接经营范围。
4. `GROUP_CONCAT([主体登记表].[经营范围], ';', 4001)` 按groupby语句分组，用分号连接经营范围。使用xmlagg+xmlparse来实现
### MySQL
在MySQL下，此函数是一个聚合函数，只能用于有groupby语句的sql中。
1. `GROUP_CONCAT([主体登记表].[经营范围], ';')` 按groupby语句分组，用分号连接经营范围。
2. `GROUP_CONCAT([主体登记表].[经营范围], orderby([主体登记表].[注册资金], 'desc'), ';')` 按groupby语句分组，注册资金降序，用分号连接经营范围。
### Vertica
使用listagg实现，支持Vertica9及以上版本，只是一个聚合函数，且有如下限制：
- 只能用于有groupby语句的sql中。
- 不支持partitionby子句。
- 不支持排序，即orderby子句。
- maxlength 默认为10240，最大支持65535。
1. `GROUP_CONCAT([主体登记表].[经营范围], ';')` 按groupby语句分组，用分号连接经营范围。
2. `GROUP_CONCAT([主体登记表].[经营范围], ';', 65535)` 按groupby语句分组，用分号连接经营范围。
3. `GROUP_CONCAT([主体登记表].[经营范围], 65535)` 按groupby语句分组，用逗号连接经营范围。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/GROUP_CONCATD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/group_concatd"
title: "GROUP_CONCATD - 返回排序将字段的值连接为指定分隔符分隔的字符串"
---
# **GROUP\_CONCATD**
返回排序将字段的值连接为指定分隔符分隔的字符串，如果有相同的值将去重。
## 语法{#grammar}
GROUP\_CONCATD(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**, **\[separator]**, **\[maxlength]**)
- **field**：必需，要连接的字段
- **partitionfield**：可选，分组字段，使用partitionby括起，只在oracle有效
- **orderfield**：可选，排序字段，field字段值按什么顺序连接，使用orderby括起，只在mysql和oracle有效
- **ordertype**：可选，指定排序类型，'asc'升序，'desc'降序，默认为升序
- **separator**：可选，分隔符，默认为逗号
- **maxlength**：可选，连接字符串的最大长度，只在vertica和oracle有效
## 示例{#example}
1. `GROUP_CONCATD([电影工作人员表].[负责工作内容],"、")` 用顿号连接去重后的所有的工作内容
2. `GROUP_CONCATD([电影工作人员表].[电影名称],ORDERBY([电影工作人员表].[职位],'asc'),"、")` 用顿号连接参与的电影名称，按照职位升序排序
其他用法和`GROUP_CONCAT`相同，详见：[GROUP\_CONCAT](./GROUP_CONCAT.md)
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/LAG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lag"
title: "LAG - 返回同一字段前N行的数据"
---
# **LAG**
返回同一字段前N行的数据。
## 语法{#grammar}
LAG(**field**, **offset**, **defval**, **partitionfield**, **orderfield**, **ordertype**)
- **field**：必需，字段名。
- **offset**：必需，偏移量，上1个或上N个的值。
- **defval**：必需，默认值，取值超出表范围时会返回默认值，通常指定为null。
- **partitionfield**：必需，分组字段，多个分组字段的时需使用partitionby，如果没有分组字段，则指定为null。
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby。
- **ordertype**：可选，指定排序类型，'asc' 升序，'desc' 降序，默认为升序。
## 示例{#examples}
1. `LAG([纳税表].[企业] , 1, null, [纳税表].[地区], [纳税表].[纳税额] ,'ASC')` 按地区分组，纳税额升序，返回企业前1行的值。
2. `LAG([纳税表].[企业] , 1, null, null, [纳税表].[纳税额] ,'ASC')` 按纳税额升序，返回企业前1行的值。
3. `LAG([纳税表].[企业] , 1, null, partitionby([纳税表].[地区],[纳税表].[行业]), orderby([纳税表].[纳税额] ,'desc',[纳税表].[企业]))` 按地区、行业分组，纳税额降序，如果纳税额相等，按企业升序，返回企业前1行的值。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/LEAD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lead"
title: "LEAD - 返回同一字段后N行的数据"
---
# **LEAD**
返回同一字段后N行的数据。
## 语法{#grammar}
LEAD(**field**, **offset**, **defval**, **partitionfield**, **orderfield**, **\[ordertype]**)
- **field**：必需，字段名
- **offset**：必需，偏移量，上1个或上N个的值
- **defval**：必需，默认值，取值超出表范围时会返回默认值，通常指定为null
- **partitionfield**：必需，分组字段，多个分组字段的时需使用partitionby，如果没有分组字段，则指定为null
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `LEAD([纳税表].[企业], 1, null, [纳税表].[地区], [纳税表].[纳税额] ,'DESC')` 按地区分组，纳税额降序返回企业后1行的值
2. `LEAD([纳税表].[企业] , 1, null, null, [纳税表].[纳税额] ,'ASC')` 按纳税额升序，返回企业后1行的值
3. `LEAD([纳税表].[企业] , 1, null, partitionby([纳税表].[地区],[纳税表].[行业]), orderby([纳税表].[纳税额] ,'desc',[纳税表].[企业]))` 按地区、行业分组，纳税额降序，如果纳税额相等，按企业升序，返回企业后1行的值
4. 场景：为计算回购率，需算出本月购买人数中有多少人下月再次购买，此时可以在数据加工中使用LEAD函数偏移出次月的销售数据，如下DEMO所示
- 数据处理：`偏移出次月数据`节点处，新增计算字`年月_次月`使用LEAD函数偏移出次月购买人数 [数据加工](https://demo.succbi.com/v5/DEMO/data?:open=kgCMnd9S7yCo6dTU5lbZBB)
- [回购率DEMO](https://demo.succbi.com/v5/demo/回购率/play)
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/YOY_VALUE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/yoy_value"
title: "YOY_VALUE - 计算同比增减额"
---
# **YOY\_VALUE**
计算同比增减额。
同比增减额 = 本期值 - 去年同期值。此函数的计算，是相对去年同期的`增减额`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
YOY\_VALUE(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `YOY_VALUE([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/MOM_VALUE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/mom_value"
title: "MOM_VALUE - 计算环比增减额"
---
# **MOM\_VALUE**
计算环比增减额。
环比增减额 = 本期值 - 上期值。此函数的计算，是相对上期的`增减额`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
MOM\_VALUE(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `MOM_VALUE([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/MOFM_VALUE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/mofm_value"
title: "MOFM_VALUE - 计算年初增减额"
---
# **MOFM\_VALUE**
计算年初增减额。
年初增减额 = 本期值 - 年初值。此函数的计算，是相对年初的`增减额`，需要数据表是`周期快照`类型，并指定`数据期`字段，相关说明可以查看文档 [数据期类型](../../../data-gov/model/model-settings.md)设置。
## 语法{#grammar}
MOFM\_VALUE(**field**)
- **field**：数值类型的表达式，一般是度量的字段名
## 示例{#example}
1. `MOFM_VALUE([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RANK_DENSE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rank_dense"
title: "RANK_DENSE - 返回排序字段值的密集排名"
---
# **RANK\_DENSE**
返回排序字段值的密集排名。
(6, 9, 9, 14) 按升序排列为 (1, 2, 2, 3)。
## 语法{#grammar}
RANK\_DENSE(**orderfield**, **\[ordertype]**, **\[partitionfield]**,...)
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby括起
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
- **partitionfield**：可选，分组字段，可设置多个，表示指定分组内的排名；不指定，则表示全部数据的排名
## 示例{#example}
1. `RANK_DENSE([销售数量])` 按照销售数量排名，默认升序
2. `RANK_DENSE([销售数量],'desc')` 按照销售数量降序排名
3. `RANK_DENSE(ORDERBY([销售数量],[上下装],[价格档次])) ` 按照销售数量、上下装、价格档次升序排名
4. `RANK_DENSE(ORDERBY([销售数量]),[日销单ID]) ` 按订单号分组，按照销售数量升序的排名
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RANK_MODIFIED.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rank_modified"
title: "RANK_MODIFIED - 返回排序字段值调整后的竞争排名"
---
# **RANK\_MODIFIED**
返回排序字段值调整后的竞争排名。
(6, 9, 9, 14) 按升序排列为 (1, 3, 3, 4)。
## 语法{#grammar}
RANK\_MODIFIED(**orderfield**, **\[ordertype]**, **\[partitionfield]**,...)
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby括起
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
- **partitionfield**：可选，分组字段，可以设置多个，表示指定分组内的排名；不指定，则表示全部数据的排名
## 示例{#example}
1. `RANK_MODIFIED([销售数量])` 按照销售数量排名，默认升序
2. `RANK_MODIFIED([销售数量],'desc')` 按照销售数量降序排名
3. `RANK_MODIFIED(ORDERBY([销售数量],[上下装],[价格档次]))` 按照销售数量、上下装、价格档次升序排名
4. `RANK_MODIFIED(ORDERBY([销售数量]),[日销单ID])` 按订单号分组，按照销售数量升序的排名
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RANK_PERCENT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rank_percent"
title: "RANK_PERCENT - 返回排序字段值的百分位排名"
---
# **RANK\_PERCENT**
返回排序字段值的百分位排名。
(6, 9, 9, 14) 按升序排列为 (0.25, 0.75, 0.75, 1)。
## 语法{#grammar}
RANK\_PERCENT(**orderfield**, **\[ordertype]**, **\[partitionfield]**,...)
- **orderfield**：必需，排序字段，多个排序字段时需要使用orderby括起
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
- **partitionfield**：可选，分组字段，可以设置多个，表示指定分组内的排名；不指定，则表示全部数据的排名
## 示例{#example}
1. `RANK_PERCENT([销售数量])` 按照销售数量排名，默认升序
2. `RANK_PERCENT([销售数量],'desc')` 按照销售数量降序排名
3. `RANK_PERCENT(ORDERBY([销售数量],[上下装],[价格档次]))` 按照销售数量、上下装、价格档次升序排名
4. `RANK_PERCENT(ORDERBY([销售数量]),[日销单ID])` 按订单号分组，按照销售数量升序的排名
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/TOTAL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/total"
title: "TOTAL - 返回整个区域数据的总合计值"
---
# **TOTAL**
返回整个区域数据的总合计值。
## 语法{#grammar}
TOTAL(**field**)
- **field**：必需，字段名
## 示例{#example}
1. `TOTAL([销售表].[销售数量])` 求总销售数量，等价于 `WINDOW_SUM([销售表].[销售数量])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/ORDERBY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/orderby"
title: "ORDERBY - 设置多字段排序"
---
# **ORDERBY**
设置多字段排序，用于窗口函数、排名函数、group\_concat函数中。
## 语法{#grammar}
ORDERBY(**orderfield**, **\[ordertype]**, ...)
- **orderfield**：必需，排序字段，可以设置多个
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RANK(ORDERBY([销售表].[销售数量],[销售表].[上下装],[销售表].[价格档次]))` 多个分组，升序排名，如果销售数量相等，则按上下装排名
2. `GROUP_CONCAT([门店销售明细表].[款式组合].[款式组合名称], orderby([销售表].[销售数量], 'desc'),'；')` 按group by语句分组，按销售数量降序，用分号连接款式组合名称
3. `RUNNING_SUM([销售表].[销售数量],ORDERBY([销售表].[季度],'asc'))` 按季度排序求销售数量的累计合计值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/PARTITIONBY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/partitionby"
title: "PARTITIONBY - 设置分组字段"
---
# **PARTITIONBY**
设置分组字段，用于窗口函数、group\_concat函数中。
## 语法{#grammar}
PARTITIONBY(**partitionfield**, **...**)
- **partitionfield**：必需，分组字段，可以设置多个。
## 示例{#examples}
1. `RUNNING_SUM([利润表].[利润], partitionby([利润表].[地区], [利润表].[行业]), [利润表].[月份])` 按多字段分组求累计合计值。
2. `GROUP_CONCAT([主体登记表].[经营范围], partitionby([主体登记表].[法人]), orderby([主体登记表].[注册资金], 'desc'))` 按企业法人分组，注册资金降序，用逗号连接经营范围。
3. `FIRST_VALUE([纳税表].[企业], partitionby([纳税表].[地区], [纳税表].[行业]), [纳税表].[纳税额])` 按地区和行业分组，取纳税额升序的第一个企业。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_AVG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_avg"
title: "WINDOW_AVG - 返回某个区域数据的平均值"
---
# **WINDOW\_AVG**
返回某个区域数据的平均值。
## 语法{#grammar}
WINDOW\_AVG(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_AVG([销售表].[销售数量])` 整个区域，求销售数量平均值
2. `WINDOW_AVG([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量平均值
3. `WINDOW_AVG([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量平均值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_SUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_sum"
title: "WINDOW_SUM - 返回某个区域数据的合计值"
---
# **WINDOW\_SUM**
返回某个区域数据的合计值。
## 语法{#grammar}
WINDOW\_SUM(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_SUM([销售表].[销售数量])` 整个区域，求销售数量合计值
2. `WINDOW_SUM([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量合计值
3. `WINDOW_SUM([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量合计值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_COUNT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_count"
title: "WINDOW_COUNT - 返回某个区域数据的行数"
---
# **WINDOW\_COUNT**
返回某个区域数据的行数，单次浮动时相当于 COUNT()，忽略NULL值。可设置分组依据。
## 语法{#grammar}
WINDOW\_COUNT(**field**, **partitionfield**, **...**)
- **field**：可选，为空表示求总行数，如果有partitionfield的情况下求总行数，传null。
- **partitionfield**：可选，支持多个分组字段。
## 示例{#examples}
1. `WINDOW_COUNT()` 整个区域，求总行数。
2. `WINDOW_COUNT([利润表].[企业])` 求企业行数。
3. `WINDOW_COUNT(null, [利润表].[地区])` 按地区分组，求行数。
4. `WINDOW_COUNT([利润表].[企业], [利润表].[地区], [利润表].[行业])` 按地区和行业分组，求企业行数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_COUNTD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_countd"
title: "WINDOW_COUNTD - 返回某个区域数据的计数统计（去重）"
---
# **WINDOW\_COUNTD**
返回某个区域数据的计数统计（去重），可设置分组依据，未设置分组字段时相当于 COUNTD()，忽略NULL值。
## 语法{#grammar}
WINDOW\_COUNTD(**field**, **partitionfield**, **...**)
- **field**：必需，事实表的字段，支持任意类型。
- **partitionfield**：可选，支持多个分组字段。
## 示例{#examples}
2. `WINDOW_COUNTD([利润表].[企业])` 求企业去重数量。
3. `WINDOW_COUNTD([利润表].[企业], [利润表].[地区])` 按地区分组，计算各个地区下的企业去重数量。
4. `WINDOW_COUNTD([利润表].[企业], [利润表].[地区], [利润表].[行业])` 按地区和行业分组，计算企业数量。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_MAX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_max"
title: "WINDOW_MAX - 返回某个区域数据的最大值"
---
# **WINDOW\_MAX**
返回某个区域数据的最大值。
## 语法{#grammar}
WINDOW\_MAX(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_MAX([销售表].[销售数量])` 整个区域，求销售数量最大值
2. `WINDOW_MAX([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量最大值
3. `WINDOW_MAX([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量最大值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_MIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_min"
title: "WINDOW_MIN - 返回某个区域数据的最小值"
---
# **WINDOW\_MIN**
返回某个区域数据的最小值。
## 语法{#grammar}
WINDOW\_MIN(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_MIN([销售表].[销售数量])` 整个区域，求销售数量最小值
2. `WINDOW_MIN([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量最小值
3. `WINDOW_MIN([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量最小值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_CONCAT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_concat"
title: "WINDOW_CONCAT - 将某个区域数据的字段值连接为指定分隔符分隔的字符串"
---
# **WINDOW\_CONCAT**
将某个区域数据的字段值连接为指定分隔符分隔的字符串，可设置分组依据，未设置分组字段时相当于 GROUP\_CONCAT()，忽略NULL值。
## 语法{#grammar}
WINDOW\_CONCAT(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**, **\[separator]**)
- **field**：必需，要连接的字段
- **partitionfield**：可选，分组字段，使用partitionby括起
- **orderfield**：可选，排序字段，field字段值按指定顺序连接，使用orderby括起
- **ordertype**：可选，指定排序类型，'asc'升序，'desc'降序，默认为升序
- **separator**：可选，分隔符，默认为逗号
## 示例{#example}
1. `WINDOW_CONCAT([主体登记表].[经营范围], partitionby([主体登记表].[法人]), orderby([主体登记表].[注册资金], 'desc'))` 按照企业法人分组，按照注册资金降序排序，用逗号连接主体的经营范围。
2. `WINDOW_CONCAT([主体登记表].[经营范围],"、")` 用顿号连接演员参演电影名称
3. `WINDOW_CONCAT([电影演员表].[电影名称],ORDERBY([电影演员表].[排序序号],'desc'),"、")` 用顿号连接演员参演电影名称，以排序序号降序排列
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_CONCATD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_concatd"
title: "WINDOW_CONCATD - 将某个区域数据的字段值连接为指定分隔符分隔的字符串"
---
# **WINDOW\_CONCATD**
将某个区域数据的字段值连接为指定分隔符分隔的字符串，如果有相同的值将去重，可设置分组依据，未设置分组字段时相当于 GROUP\_CONCATD()，忽略NULL值。
## 语法{#grammar}
WINDOW\_CONCATD(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**, **\[separator]**)
- **field**：必需，要连接的字段
- **partitionfield**：可选，分组字段，使用partitionby括起
- **orderfield**：可选，排序字段，field字段值按什么顺序连接，使用orderby括起
- **ordertype**：可选，指定排序类型，'asc'升序，'desc'降序，默认为升序
- **separator**：可选，分隔符，默认为逗号
## 示例{#example}
1. `WINDOW_CONCATD([主体登记表].[经营范围], partitionby([主体登记表].[法人]), orderby([主体登记表].[注册资金], 'desc'))` 按照企业法人分组，按照注册资金降序排序，用逗号连接主体的经营范围。
2. `WINDOW_CONCATD([电影工作人员表].[负责工作内容],"、")` 用顿号连接去重后的所有的工作内容
3. `WINDOW_CONCATD([电影工作人员表].[电影名称],ORDERBY([电影工作人员表].[职位],'asc'),"、")` 用顿号连接参与的电影名称，按照职位升序排序
其他用法和`WINDOW_CONCAT`相同，详见：[WINDOW\_CONCAT](./WINDOW_CONCAT.md)
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_MEDIAN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_median"
title: "WINDOW_MEDIAN - 返回某个区域数据的中值"
---
# **WINDOW\_MEDIAN**
返回某个区域数据的中值。
## 语法{#grammar}
WINDOW\_MEDIAN(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_MEDIAN([销售表].[销售数量])` 整个区域，求销售数量中值
2. `WINDOW_MEDIAN([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量中值
3. `WINDOW_MEDIAN([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量中值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_STDEV.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_stdev"
title: "WINDOW_STDEV - 返回某个区域数据的标准偏差"
---
# **WINDOW\_STDEV**
返回某个区域数据的标准偏差。
## 语法{#grammar}
WINDOW\_STDEV(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_STDEV([销售表].[销售数量])` 整个区域，求销售数量标准偏差
2. `WINDOW_STDEV([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量标准偏差
3. `WINDOW_STDEV([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量标准偏差
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_STDEVP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_stdevp"
title: "WINDOW_STDEVP - 返回某个区域数据的总体标准差"
---
# **WINDOW\_STDEVP**
返回某个区域数据的总体标准差。
## 语法{#grammar}
WINDOW\_STDEVP(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_STDEVP([销售表].[销售数量])` 整个区域，求销售数量总体标准差
2. `WINDOW_STDEVP([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量总体标准差
3. `WINDOW_STDEVP([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量总体标准差
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_VAR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_var"
title: "WINDOW_VAR - 返回某个区域数据的样本方差"
---
# **WINDOW\_VAR**
返回某个区域数据的样本方差。
## 语法{#grammar}
WINDOW\_VAR(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_VAR([销售表].[销售数量])` 整个区域，求销售数量样本方差
2. `WINDOW_VAR([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量样本方差
3. `WINDOW_VAR([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量样本方差
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_VARP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_varp"
title: "WINDOW_VARP - 返回某个区域数据的样本总体方差"
---
# **WINDOW\_VARP**
返回某个区域数据的样本总体方差。
## 语法{#grammar}
WINDOW\_VARP(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_VARP([销售表].[销售数量])` 整个区域，求销售数量样本总体方差
2. `WINDOW_VARP([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量样本总体方差
3. `WINDOW_VARP([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量样本总体方差
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WINDOW_WEIGHT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/window_weight"
title: "WINDOW_WEIGHT - 返回某个区域数据的占比"
---
# **WINDOW\_WEIGHT**
返回某个区域数据的占比。
此函数相当于`字段/SUM(字段)`。可设置分组依据，同[WEIGHT](./WEIGHT.md)函数。
## 语法{#grammar}
WINDOW\_WEIGHT(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WINDOW_WEIGHT([销售表].[销售数量])` 整个区域，求销售数量占比
2. `WINDOW_WEIGHT([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量占比
3. `WINDOW_WEIGHT([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量占比
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_AVG.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_avg"
title: "RUNNING_AVG - 返回某个区域数据的累计平均值"
---
# **RUNNING\_AVG**
返回某个区域数据的累计平均值，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_AVG(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**)
- **field**：必需，字段名
- **partitionfield**：可选，分组字段，多个分组字段时需使用 partitionby
- **orderfield**：可选，排序字段，多个排序字段时需要使用 orderby；如果不指定，默认按 field 升序累计
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RUNNING_AVG([销售表].[销售数量])` 按销售数量升序，求销售数量累计平均值
2. `RUNNING_AVG([销售表].[销售数量],[销售表].[年],[销售表].[月度])` 按年分组，按月份升序，求销售数量累计平均值
3. `RUNNING_AVG([销售表].[销售数量],ORDERBY([销售表].[季度],'asc')` 整个区域，按季度升序，求销售数量累计平均值
4. `RUNNING_AVG([销售表].[销售数量],PARTITIONBY([销售表].[年],[销售表].[季度]),ORDERBY([销售表].[月份],'asc'))` 按年、季度分组，按月份升序，求销售数量累计平均值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_SUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_sum"
title: "RUNNING_SUM - 返回某个区域数据的累计合计值"
---
# **RUNNING\_SUM**
返回某个区域数据的累计合计值，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_SUM(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**)
- **field**：必需，字段名
- **partitionfield**：可选，分组字段，多个分组字段时需使用 partitionby
- **orderfield**：可选，排序字段，多个排序字段时需要使用 orderby；如果不指定，默认按 field 升序累计
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RUNNING_SUM([销售表].[销售数量])` 按销售数量升序，求销售数量累计合计值
2. `RUNNING_SUM([销售表].[销售数量],[销售表].[年], [销售表].[月度])` 按年分组，按月份升序，求销售数量累计合计值
3. `RUNNING_SUM([销售表].[销售数量],ORDERBY([销售表].[季度],'asc'))` 整个区域，按季度升序，求销售数量累计合计值
4. `RUNNING_SUM([销售表].[销售数量],PARTITIONBY([销售表].[年],[销售表].[季度]),ORDERBY([销售表].[月份],'asc'))` 按年、季度分组，按月份升序，求销售数量累计合计值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_COUNT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_count"
title: "RUNNING_COUNT - 返回某个区域数据的累计行数"
---
# **RUNNING\_COUNT**
返回某个区域数据的累计行数，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_COUNT(**field**, **partitionfield**, **orderfield**,**ordertype**)
- **field**：必需，字段名。
- **partitionfield**：可选，分组字段，多个分组字段的时需使用partitionby。
- **orderfield**：可选，排序字段，多个排序字段时需要使用orderby；如果不指定，默认按field升序累计。
- **ordertype**：可选，指定排序类型，'asc' 升序，'desc' 降序，默认为升序。
## 示例{#examples}
1. `RUNNING_COUNT([利润表].[企业])` 按\[利润表].\[利润]升序求累计企业行数。
2. `RUNNING_COUNT([利润表].[企业], [利润表].[地区], [利润表],[利润],'DESC')` 按地区分组，按利润降序求累计企业行数。
3. `RUNNING_COUNT([利润表].[企业], partitionby([利润表].[地区], [利润表].[行业]), [利润表].[月份])` 按地区、行业分组，按月份升序，求累计企业行数。
4. `RUNNING_COUNT([利润表].[企业], orderby([利润表].[月份], 'ASC', [利润表].[利润], 'DESC')` 整个区域，按月份升序、利润降序排序，求累计企业行数。
5. `RUNNING_COUNT(COUNT()), [利润表].[地区], [利润表].[月份])` 当处于分组统计时，按地区分组，按月份升序，求企业行数的累计行数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_MAX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_max"
title: "RUNNING_MAX - 返回某个区域数据的累计最大值"
---
# **RUNNING\_MAX**
返回某个区域数据的累计最大值，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_MAX(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**)
- **field**：必需，字段名
- **partitionfield**：可选，分组字段，多个分组字段时需使用 partitionby
- **orderfield**：可选，排序字段，多个排序字段时需要使用 orderby；如果不指定，默认按 field 升序累计
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RUNNING_MAX([销售表].[销售数量])` 按销售数量升序，求销售数量累计最大值
2. `RUNNING_MAX([销售表].[销售数量],[销售表].[年], [销售表].[月度])` 按年分组，按月份升序，求销售数量累计最大值
3. `RUNNING_MAX([销售表].[销售数量],ORDERBY([销售表].[季度],'asc'))` 整个区域，按季度升序，求销售数量累计最大值
4. `RUNNING_MAX([销售表].[销售数量],PARTITIONBY([销售表].[年],[销售表].[季度]),ORDERBY([销售表].[月份],'asc'))` 按年、季度分组，按月份升序，求销售数量累计最大值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_MIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_min"
title: "RUNNING_MIN - 返回某个区域数据的累计最小值"
---
# **RUNNING\_MIN**
返回某个区域数据的累计最小值，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_MIN(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**)
- **field**：必需，字段名
- **partitionfield**：可选，分组字段，多个分组字段时需使用 partitionby
- **orderfield**：可选，排序字段，多个排序字段时需要使用 orderby；如果不指定，默认按 field 升序累计
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RUNNING_MIN([销售表].[销售数量])` 按销售数量升序，求销售数量累计最小值
2. `RUNNING_MIN([销售表].[销售数量],[销售表].[年], [销售表].[月度])` 按年分组，按月份升序，求销售数量累计最小值
3. `RUNNING_MIN([销售表].[销售数量],ORDERBY([销售表].[季度],'asc'))` 整个区域，按季度升序，求销售数量累计最小值
4. `RUNNING_MIN([销售表].[销售数量],PARTITIONBY([销售表].[年],[销售表].[季度]),ORDERBY([销售表].[月份],'asc'))` 按年、季度分组，按月份升序，求销售数量累计最小值
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/RUNNING_WEIGHT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/running_weight"
title: "RUNNING_WEIGHT - 返回某个区域数据的累计占比"
---
# **RUNNING\_WEIGHT**
返回某个区域数据的累计占比，可设置分组依据及排序依据。
## 语法{#grammar}
RUNNING\_WEIGHT(**field**, **\[partitionfield]**, **\[orderfield]**, **\[ordertype]**)
- **field**：必需，字段名
- **partitionfield**：可选，分组字段，多个分组字段时需使用 partitionby
- **orderfield**：可选，排序字段，多个排序字段时需要使用 orderby；如果不指定，默认按 field 升序累计
- **ordertype**：可选，指定排序类型，`asc` 升序，`desc` 降序，默认为升序
## 示例{#example}
1. `RUNNING_WEIGHT([销售表].[销售数量])` 按销售数量升序，求累计占比
2. `RUNNING_WEIGHT([销售表].[销售数量],ORDERBY([销售表].[季度],'asc'))` 整个区域，按季度升序，求销售数量累计占比
3. `RUNNING_WEIGHT([销售表].[销售数量],PARTITIONBY([销售表].[年],[销售表].[季度]),ORDERBY([销售表].[月份],'asc'))`按年、季度分组，按月份升序，求销售数量累计占比
---
url: "https://docs.succapp.com/v5/guide/exp/func/analysis/WEIGHT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/weight"
title: "WEIGHT - 返回某个区域数据的占比"
---
# **WEIGHT**
返回某个区域数据的占比。
此函数相当于`字段/SUM(字段)`。可设置分组依据，同[WINDOW\_WEIGHT](./WINDOW_WEIGHT.md)函数，是该函数的简写。
## 语法{#grammar}
WEIGHT(**field**, **\[partitionfield]**)
- **field**：必需，字段名
- **partitionfield**：可选，支持多个分组字段
## 示例{#example}
1. `WEIGHT([销售表].[销售数量])` 整个区域，求销售数量占比
2. `WEIGHT([销售表].[销售数量],[销售表].[年])` 按年分组，求销售数量占比
3. `WEIGHT([销售表].[销售数量],[销售表].[年],[销售表].[季度])` 按年和季度分组，求销售数量占比
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/transform-funcs"
title: "转换函数列表"
---
---
navTitle: 转换函数
---
# 转换函数列表
!!!children (guide/exp/func/transform)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOSTR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tostr"
title: "TOSTR - 解析一个对象并返回一个字符串"
---
---
description: 转换为字符串
---
# **TOSTR**
解析一个对象并返回一个字符串。
## 语法{#grammar}
TOSTR(**str**, **format**)
- **str**：给定的字符串对象
- **format**：可选，字符串格式。当**format**参数省略时，使用默认的行为将对象输出为字符串。如果传入了**format**参数，则按照格式化输出的方式输出字符串
## 示例{#example}
| 表达式 | 返回值 | 说明 |
| ------------------------------------------------------------ | ------------------------------ | ------------------------- |
| =TOSTR(1.2345,"0.000") | 1.235 | 保留三位小数 |
| =TOSTR(20110308,'yyyy-mm-dd') | 2011-03-08 | 格式化日期 |
| =TOSTR(20110308,'yyyy年第q季度') |2011年第1季度 | 格式化年季的日期 |
| =TOSTR(TODATE('1370667962663', 'milliseconds'),"yyyy-mm-dd") | 2013-06-08 | 格式化带有分秒的日期 |
| =TOSTR(TODAY(),'yyyy-mm-dd hh:MM:ss') | 2013-03-05 00:00:00 | 格式化today函数计算的时间 |
| =TOSTR(NOW(),'yyyy-mm-dd hh:MM:ss') | 2013-03-05 14:28:54 | 格式化now函数计算的时间 |
| =TOSTR(56,'￥0.000') | ￥56.000 | 货币保留3位小数 |
| =TOSTR(56,'"$"@') | $56 | 数值前加单位 |
| =TOSTR(56,'@"元'") | 56元 | 数值后加单位 |
| =TOSTR(11000,'0!.0,"万元"') | 1.1万元 | 数值转化为万元 |
| =TOSTR(11000,'#,###,.00,"千元"') | 11.00千元 | 数值转化为千元 |
| =TOSTR(8,'\[DBNum1]') | 八 | 中文小写数字 |
| =TOSTR(8,'\[DBNum2]') | 捌 | 中文大写数字 |
| =TOSTR(12345,'#,##') | 12,345 | 千位分隔符 |
| =TOSTR(1234,'#,##0.000') | 1,234.000 | 千位分隔符且保留3位小数 |
| =TOSTR(1.234,'0%') | 123% | 百分比取整 |
| =TOSTR(1.234,'0.0%') | 123.4% | 百分比保留1位小数 |
| =TOSTR(1.234,'0.000%') | 123.400% | 百分比保留3位小数 |
| =TOSTR(1234.56,'人民币rmb') | 人民币壹仟贰佰叁拾肆元伍角陆分 | 格式化人民币（大写） |
| =TOSTR(1234.56,'收入：\[dbnum1]rmb') | 收入：一千二百三十四元五角六分 | 格式化人民币（小写） |
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOINT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/toint"
title: "TOINT - 解析一个对象并返回一个整数"
---
---
description: 转换为整数
---
# **TOINT**
解析一个对象并返回一个整数。
**toInt()** 会根据**string**来判断数字的基数。如果**string**以 `"0x" `开头**toInt()** 会把**string**的其余部分解析为十六进制的整数。如果**string**以 1 ~ 9 的数字开头，**toInt()** 将把它解析为十进制的整数。不支持八进制整数。
## 语法{#grammar}
TOINT(**str**)
- **str**：给定的字符串对象
## 示例{#example}
1. `TOINT('123')` 可以识别数字字符串，返回整数`123`
2. `TOINT('000123')` 可以识别数字字符串，返回整数`123`
3. `TOINT(123.123)` 浮点数，返回整数`123`
4. `TOINT('abc')` 对象不能转换为数字，返回`0`
5. `TOINT(true)` 布尔型true，返回`1`
6. `TOINT(false)` 布尔型false，返回`0`
7. `TOINT('')` 空字符串，返回`0`
8. `TOINT("0xa")` 以"0x"开头，返回`0`
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TONUM.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tonum"
title: "TONUM - 解析一个对象并返回一个浮点数"
---
---
description: 转换为浮点数
---
# **TONUM**
解析一个对象并返回一个浮点数。当**str**参数不能转换为数字时返回空值。
## 语法{#grammar}
TONUM(**str**)
- **str**：给定的字符串对象
## 示例{#example}
1. `TONUM('123')` 可以识别数字字符串并返回浮点数`123`
2. `TONUM(123.123)` 浮点数返回浮点数`123.123`
3. `TONUM(true)` 布尔型true返回`1`
4. `TONUM(false)` 布尔型false返回`0`
5. `TONUM('0')` 字符0返回空值`NaN`
6. `TONUM('')` 空字符串返回空值`NaN`
7. `TONUM('abc')` 对象不能转换为数字时返回空值`NaN`
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TODATE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/todate"
title: "TODATE - 返回日期对象"
---
# **TODATE**
返回日期对象。
该函数是将日期字符串按照指定的日期格式转换成日期对象，如果没有指定日期格式，那么默认按照`yyyyMMdd hh:mm:ss`的格式进行转换。**formatString**区分大小写，月份需要大写。
## 语法{#grammar}
TODATE(**dateString**, **formatString**)
- **dateString**：日期字符串
- **formatString**：可选，日期格式字符串。默认格式为 "yyyyMMdd hh:mm:ss"
## 示例{#example}
1. `TODATE("20120409 04:04:03","yyyyMMdd")` 日期字符串，返回`20120409 00:00:00`
2. `TODATE("20120409 04:04:03")` 毫秒值，返回`20120409 04:04:03`
3. `TODATE('20120409','yyyyMMdd')` 年月日，返回`20120409`
4. `TODATE('201204','yyyyMM')` 年月，返回`201204`
5. `TODATE('2012','yyyy')"` 年，返回`2012`
## 详细描述{#description}
| 格式 | 示例 |
| ---------------------| ------------------------------ |
| Y M D | 年 月 日 |
| H m S | 时 分 秒 |
| yyyy | 2012 |
| yyyy年 | 2012年 |
| yyyyMM | 201204 |
| yyyy-MM | 2012-04 |
| yyyy年MM月 | 2012年04月 |
| yyyyMMdd | 20120409 |
| yyyy-MM-dd | 2012-04-09 |
| yyyy年MM月dd日 | 2012年04月09日 |
| yyyyMMdd HH:mm:ss | 20120409 04:04:03 |
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOBOOL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tobool"
title: "TOBOOL - 解析一个对象并返回一个布尔值"
---
---
description: 转换为布尔值
---
# **TOBOOL**
解析一个对象并返回一个布尔值。
## 语法{#grammar}
TOBOOL(**object**)
- **object**：被解析的对象
## 示例{#example}
1. `TOBOOL(TRUE)` 布尔型true，返回`true`
2. `TOBOOL(FALSE)` 布尔型false，返回`false`
3. `TOBOOL(0)` 数值0，返回`false`
4. `TOBOOL(1)` 非零数值，返回`true`
5. `TOBOOL('')` 空字符串，返回`false`
6. `TOBOOL('123')` 非空字符串，返回`true`
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOJSON.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tojson"
title: "TOJSON - 将json格式字符串转为JSON对象"
---
# **TOJSON**
将json格式字符串转为JSON对象。
多数情况下可以不使用此函数，系统中接受JSON对象或数组对象的地方，基本都可以直接使用字符串形式的JSON对象或数组，对于可能内容有特殊符号值的JSON对象，也可以考虑使用`JSON_OBJECT`函数构造JSON对象。
## 语法{#grammar}
TOJSON(**json**)
- **json**：必需，一个json形式的字符串，如`'{"key1": 123, "key2": 456}'`
## 示例{#example}
1. `TOJSON('{"key1": 123, "key2": 456}')` 返回JSON对象
2. `TOJSON('[{"id":1,"name":""张三},{"id":2,"name":"李四"}]')` 返回JSON数组对象
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/FROMUNIXTIME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/fromunixtime"
title: "FROMUNIXTIME - 用于将 Unix 时间戳（即从 1970-01-01 00:00:00 UTC 开始的秒数）转换为时间戳对象"
---
# **FROMUNIXTIME**
用于将 Unix 时间戳（即从 1970-01-01 00:00:00 UTC 开始的秒数）转换为时间戳对象。
## 语法{#grammar}
FROMUNIXTIME(**unixtime**)
- **unixtime**：必需，Unix 时间戳，整型或浮点型，指从1970-01-01 00:00:00 UTC 开始的秒数。毫秒数用小数位表示。
## 示例{#example}
1. `FROMUNIXTIME(1447430881)` 返回时间戳`2015-11-13 10:08:01`
2. `FROMUNIXTIME(1744196280.255)` 返回时间戳`2025-04-09 10:58:00.255`，精确到毫秒
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOTIMEZONE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/totimezone"
title: "TOTIMEZONE - 将一个时区的时间（时间字符串或时间戳对象）转为另一个时区的时间并返回"
---
---
description: 时区转换
---
# **TOTIMEZONE**
将一个时区的时间（时间字符串或时间戳对象）转为另一个时区的时间并返回。
## 语法{#grammar}
TOTIMEZONE(**timestamp**, **to\_timezone**, **from\_timezone**)
- **timestamp**：必填，时间字符串、时间戳对象或时间戳字段
- **to\_timezone**：必填，目标时区，UTC+8、+0800、Asia/Shanghai等格式都能识别
- **from\_timezone**：可选，表示第一个参数`timestamp`的时间是哪个时区的，默认是当前时区，也可以指定
## 示例{#example}
1. `totimezone('2022-02-16 12:00:00', 'utc+10')` 将当前时区的时间转换为`utc+10`的时间
2. `totimezone('2022-02-16 12:00:00 GMT+3', 'utc+10')` 把GMT+3时区的时间转换为`utc+10`的时间
3. `totimezone('2022-02-16 12:00:00', 'Asia/Shanghai')` 将当前时区的时间转换为`Asia/Shanghai`的时间
4. `totimezone('2022-02-16 12:00:00', 'utc+10', 'utc+5')` 将utc+5的时间转换为utc+10的时间
5. `totimezone([会议预约时间], 'utc-9') ` 将数据表中`[会议预约时间]`转为`utc-9`的时间
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TOUNIXTIME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/tounixtime"
title: "TOUNIXTIME - 将时间戳对象转换unixtime（从 1970-01-01 00:00:00 UTC 开始的秒数）"
---
# **TO\_UNIXTIME**
将时间戳对象转换unixtime（从 1970-01-01 00:00:00 UTC 开始的秒数）。
## 语法{#grammar}
TOUNIXTIME(**date**)
- **date**：可选，时间戳类型的字段或者表达式，省略时表示当前时间。
## 示例{#example}
1. `TOUNIXTIME('2015-11-13 10:08:01')` 返回unixtime`1447430881`
2. `TOUNIXTIME('2025-04-09 10:58:00.255')` 返回unixtime`1744196280.255`，精确到毫秒
3. `TOUNIXTIME()` 返回当前时间的unixtime
---
url: "https://docs.succapp.com/v5/guide/exp/func/transform/TYPEOF.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/typeof"
title: "TYPEOF - 返回对象的类型"
---
---
order: 270
---
# **TYPEOF**
返回对象的类型。
返回一个字符串形式的类型表示，可能为：
|类型表示|类型说明|
|:---|:---|
|object|对象|
|array|数组|
|string|字符串|
|number|数字|
|boolean|布尔值|
|null|null值|
## 语法{#grammar}
TYPEOF(**val**)
- **val**：必需，要判断类型的JSON对象或值，可以直接传递数值、字符串、JSON或数组，也可以传递JSON或数组的字符串形式。
## 示例{#example}
1. `TYPEOF('-123.4')` 返回`number`。
2. `TYPEOF('[1,2,3]')`，等价于`TYPEOF(ARR(1,2,3)')`，返回`array`。
3. `TYPEOF('{"a":1}')`，等价于`TYPEOF(JSON_OBJECT("a",1)')`，返回`object`。
4. `TYPEOF('"ab\"c"')` 返回`string`。
5. `TYPEOF(JSON_GET('[{"key1": 123, "key2": "abc"},{"key1": 456, "key2": "def"}]','$[1].key2'))` 返回`string`。
6. `TYPEOF(null)` 返回 `null`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/json"
title: "JSON函数列表"
---
---
navTitle: JSON函数
---
# JSON函数列表
!!!children (guide/exp/func/json)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr"
title: "ARR - 构建一个数组对象"
---
# **ARRAY**
构建一个数组对象。
## 语法{#grammar}
ARR(**value1**, **value2**, **...**)
- **value**：可选，将传入的多个value组合成一个数组，每一个参数都是数组中的一个元素。
## 示例{#example}
1. `ARR()` 返回空数组 `[]`。
2. `ARR(null)` 返回空数组 `[null]`。
3. `ARR(1, "abc", NULL, now())` 返回 `[1,"abc",null,'2024-01-22 15:00:00']`。
4. `ARR(JSON_OBJECT('KEY1',123),JSON_OBJECT('KEY2',456))` 返回 `[{"KEY1":123},{"KEY2":456}]`。
5. `ARR(ARR(1,1,3),ARR(1,2,3))` 返回二维数组 `[[1,1,3][1,2,3]]`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_GET.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_get"
title: "ARR_GET - 返回数组中指定位置的元素"
---
# **ARR\_GET**
返回数组中指定位置的元素。
## 语法{#grammar}
ARR\_GET(**arr**, **index**)
- **arr**: 必需，数组或其字符串形式
- **index**: 可选，指定位置，1开始
## 示例{#example}
1. `ARR_GET(ARR("a", "b", "c"), 2)` 返回字符串`b`
2. `ARR_GET(ARR("a", "b", "c"), 5)` 越界后返回null
3. `ARR_GET(null, 1)` null数组返回null
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_LEN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_len"
title: "ARR_LEN - 返回数组的长度"
---
# **ARR\_LEN**
返回数组的长度。
## 语法{#grammar}
ARR\_LEN(**arr**)
- **arr**：必需，JSON或数组。
## 示例{#example}
1. `ARR_LEN(ARR('id', 87, 'name', 'carrot'))` 返回数组长度 `4`
2. `ARR_LEN('[]')` 返回数组长度 `0`
3. `ARR_LEN(null)` 返回null
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_CONTAINS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_contains"
title: "ARR_CONTAINS - 判断数组是否包含指定的元素"
---
# **ARR\_CONTAINS**
判断数组是否包含指定的元素。
## 语法{#grammar}
ARR\_CONTAINS(**arr**, **value**)
- **arr**：必需，判断此数组是否包含参数`value`指定的元素
- **value**：必需，判断是否被参数`arr`指定的数组包含
## 示例{#example}
1. `ARR_CONTAINS(ARR(1,2,3), '3')` 返回`true`
2. `ARR_CONTAINS(ARR(1,2,3), 4)` 返回`false`
3. `ARR_CONTAINS(ARR(1,2,3), null)` 返回`false`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_CONTAINS_ALL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_contains_all"
title: "ARR_CONTAINS_ALL - 判断数组是否包含另一个数组的所有元素"
---
# **ARR\_CONTAINS\_ALL**
判断数组是否包含另一个数组的所有元素。
## 语法{#grammar}
ARR\_CONTAINS\_ALL(**arr**, **sub\_arr**)
- **arr**：必需，判断此数组是否包含参数`sub_arr`指定的数组的所有元素
- **sub\_arr**：必需，判断此数组的所有元素是否被参数`arr`指定的数组包含
## 示例{#example}
1. `ARR_CONTAINS_ALL(ARR(1,2,3), '[2,3]')` 返回`true`
2. `ARR_CONTAINS_ALL(ARR(1,2,3), '[2,4]')` 返回`false`
3. `ARR_CONTAINS_ALL(ARR(1,2,3), ARR(3,4))` 返回`false`
4. `ARR_CONTAINS_ALL(ARR(1,2,3), null)` 返回`false`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_CONTAINS_ANY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_contains_any"
title: "ARR_CONTAINS_ANY - 判断数组是否包含另一个数组的任意元素"
---
# **ARR\_CONTAINS\_ANY**
判断数组是否包含另一个数组的任意元素。
## 语法{#grammar}
ARR\_CONTAINS\_ANY(**arr**, **sub\_arr**)
- **arr**：必需，判断此数组是否包含参数`sub_arr`指定数组的任意元素
- **sub\_arr**：必需，判断此数组的任意元素是否被参数`arr`指定的数组包含
## 示例{#example}
1. `ARR_CONTAINS_ANY(ARR(1,2,3), '[2,4]')` 返回`true`
2. `ARR_CONTAINS_ANY(ARR(1,2,3), '[4,5]')` 返回`false`
3. `ARR_CONTAINS_ANY(ARR(1,2,3), ARR(3,4))` 返回`true`
4. `ARR_CONTAINS_ANY(null, ARR(3,4))` 返回`false`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_FIND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_find"
title: "ARR_FIND - 查找数组中满足条件的第一个元素"
---
# **ARR\_FIND**
查找数组中满足条件的第一个元素。
找不到时返回`null`。
## 语法{#grammar}
ARR\_FIND(**arr**, **condition**)
- **arr**：必需，需要过滤的数组对象或其字符串形式
- **condition**：必需，条件过滤表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_FIND('[1,2,3]', @>=2)` 第二个元素满足条件，返回`2`
2. `ARR_FIND('[1,2,3]', @>=5)` 没有元素满足条件，返回null
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_FIND_INDEX.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_find_index"
title: "ARR_FIND_INDEX - 查找数组中满足条件的第一个元素的位置"
---
# **ARR\_FIND\_INDEX**
查找数组中满足条件的第一个元素的位置。
1开始，返回-1表示没有找到。
## 语法{#grammar}
ARR\_FIND\_INDEX(**arr**, **condition**)
- **arr**：必需，需要过滤的数组对象或其字符串形式
- **condition**：必需，条件过滤表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_FIND_INDEX('[1,null,3]', @ is null)` 第二个元素满足条件，返回2
2. `ARR_FIND_INDEX('[1,2,3]', @>=5)` 没有元素满足条件，返回-1
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_EVERY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_every"
title: "ARR_EVERY - 判断是否数组中每个元素都满足指定的条件"
---
# **ARR\_EVERY**
判断是否数组中每个元素都满足指定的条件。
遍历传入的数组对象，只有每个元素都满足指定的条件时，才返回true。
## 语法{#grammar}
ARR\_EVERY(**arr**, **condition**)
- **arr**：必需，需要判断的数组对象或其字符串形式
- **condition**：必需，条件过滤表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_EVERY(ARR(1,2,3),@>0)` 判断数组中是否所有元素都大于0
2. `ARR_EVERY(SPLIT(COMBOBOX1,','),LOOKUP(@,MZRS_XXB.YSZYFWDM)!=null)` 校验用户在下拉框`COMBOBOX1`中多选的职业类型是否在字段`MZRS_XXB.YSZYFWDM`关联的维表中都存在。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_SOME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_some"
title: "ARR_SOME - 判断是否数组中至少有一个元素满足指定的条件"
---
# **ARR\_SOME**
判断是否数组中至少有一个元素满足指定的条件。
遍历传入的数组对象，只要有一个元素满足指定的条件，就返回true。
## 语法{#grammar}
ARR\_SOME(**arr**, **condition**)
- **arr**：必需，需要判断的数组对象或其字符串形式
- **condition**：必需，条件过滤表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_SOME(ARR(1,2,3), @%2=0)` 判断数组中是否存在偶数
2. `ARR_SOME(SPLIT(COMBOBOX1,','),LOOKUP(@,MZRS_XXB.YSZYFWDM)=null)` 校验用户在下拉框`COMBOBOX1`中多选的职业类型是否存在不合法的选项，即在字段`MZRS_XXB.YSZYFWDM`关联的维表中不存在的选项。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_APPEND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_append"
title: "ARR_APPEND - 追加1个或多个元素到数组尾部并返回新的数组"
---
# **ARR\_APPEND**
追加1个或多个元素到数组尾部并返回新的数组。
此函数不会检查数组中是否已存在要追加的元素，如需判断，可结合`ARR_CONTAINS`函数一起使用。
此函数可运行于浏览器端、后端服务器端或SQL中，在SQL中此函数依赖数据库本身对JSON类型的支持能力，虽然大部分数据库都支持JSON数据类型，但可能部分数据库支持的不完善。
## 语法{#grammar}
ARR\_APPEND(**arr**, **value1**,..., **valueN**)
- **arr**：必需，数组或其字符串形式
- **value**：必需，需要追加的值
## 示例{#example}
1. `ARR_APPEND('["a", "b", "c"]', 'd')` 返回`["a", "d", "c", "d"]`
2. `ARR_APPEND(ARR("a", "b", "c"), 'd', 'e')` 返回`["a", "b", "c", "d", "e"]`
3. `IF(ARR_CONTAINS(ARR_FIELD1, 'a'), ARR_FIELD1, ARR_APPEND(ARR_FIELD1, 'a'))` 当ARR\_FIELD1包含a时，返回ARR\_FIELD1，否则返回ARR\_FIELD1加上a
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_PREPEND.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_prepend"
title: "ARR_PREPEND - 插入1个或多个元素到数组首部并返回新的数组"
---
# **ARR\_PREPEND**
插入1个或多个元素到数组首部并返回新的数组。
此函数不会检查数组中是否已存在要插入的元素，如需判断，可结合`ARR_CONTAINS`函数一起使用。
此函数可运行于浏览器端、后端服务器端或SQL中，在SQL中此函数依赖数据库本身对JSON类型的支持能力，虽然大部分数据库都支持JSON数据类型，但可能部分数据库支持的不完善。
## 语法{#grammar}
ARR\_PREPEND(**arr**, **value1**,..., **valueN**)
- **arr**：必需，数组或其字符串形式
- **value**：必需，需要插入的值
## 示例{#example}
1. `ARR_PREPEND('["a", "b", "c"]', 'd')` 返回`["d", "a", "d", "c"]`
2. `ARR_PREPEND(ARR("a", "b", "c"), 'd', 'e')` 返回`["d", "e", "a", "b", "c"]`
3. `IF(ARR_CONTAINS(ARR_FIELD1, 'a'), ARR_FIELD1, ARR_PREPEND(ARR_FIELD1, 'a'))` 当ARR\_FIELD1包含a时，返回ARR\_FIELD1，否则返回ARR\_FIELD1加上a
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_CONCAT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_concat"
title: "ARR_CONCAT - 连接两个或多个数组并返回新数组"
---
# **ARR\_CONCAT**
连接两个或多个数组并返回新数组。
## 语法{#grammar}
ARR\_CONCAT(**array1**,..., **arrayN**)
- **array**：必需，要连接的数组，可传递数组对象或其字符串形式
## 示例{#example}
1. `ARR_CONCAT(ARR("a", "b", "c"), ARR("1", "2"))` 返回数组`["a", "b", "c", "1", "2"]`
2. `ARR_CONCAT('["a", "b", "c"]', '["1", "2"]')` 返回数组`["a", "b", "c", "1", "2"]`
3. `ARR_CONCAT('["a", "b", "c"]', null)` 返回数组`["a", "b", "c"]`
4. `ARR_CONCAT(null, '["a", "b", "c"]')` 返回数组`["a", "b", "c"]`
5. `ARR_CONCAT(null, null)` 返回`NULL`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_REMOVE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_remove"
title: "ARR_REMOVE - 删除数组中首个指定的值并返回新的数组"
---
# **ARR\_REMOVE**
删除数组中首个指定的值并返回新的数组。
如果数组中存在多个相同值，只删除第一个，如果需要删除所有的相同值，请使用[ARR\_REMOVE\_ALL](./ARR_REMOVE_ALL.md)函数。
## 语法{#grammar}
ARR\_REMOVE(**arr**, **value**)
- **arr**：必需，数组或其字符串形式。
- **value**：必需，要删除的值。
## 示例{#example}
1. `ARR_REMOVE(ARR("a", "b", "c"), 'b')` 返回数组对象`["a", "c"]`
2. `ARR_REMOVE(ARR("a", "b", "c", "b"), 'b')` 只会删除第一个匹配的值，返回数组对象`["a", "c", "b"]`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_REMOVE_ALL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_remove_all"
title: "ARR_REMOVE_ALL - 删除数组中所有指定的值并返回新的数组"
---
# **ARR\_REMOVE\_ALL**
删除数组中所有指定的值并返回新的数组。
如果数组中存在多个相同值，则会删除所有的，如果数组中不会有多个相同的值，那么可以使用[ARR\_REMOVE](./ARR_REMOVE.md)函数，只删除一个。
## 语法{#grammar}
ARR\_REMOVE\_ALL(**arr**, **value**)
- **arr**：必需，数组或其字符串形式。
- **value**：必需，要删除的值。
## 示例{#example}
1. `ARR_REMOVE_ALL(ARR("a", "b", "c"), 'b')` 返回数组对象`["a", "c"]`
2. `ARR_REMOVE_ALL(ARR("a", "b", "c", "b"), 'b')` 会删除所有匹配的值，返回数组对象`["a", "c"]`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_DISTINCT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_distinct"
title: "ARR_DISTINCT - 数组去除重复数据"
---
# **ARR\_DISTINCT**
数组去除重复数据。
## 语法{#grammar}
ARR\_DISTINCT(**arr**)
- **arr**：必需，传递要去除重复数据的数组或数组的字符串形式。
## 示例{#example}
1. `ARR_DISTINCT(ARR(1,2,3,2))` 去除重复数据2，结果为`[1,2,3]`
2. `ARR_DISTINCT('[1,2,3,2]')` 等价于上面的示例，结果为`[1,2,3]`
3. `ARR_DISTINCT(ARR('a','b','c'))` 没有重复数据，结果为`['a','b','c']`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_FILTER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_filter"
title: "ARR_FILTER - 过滤数组并返回符合条件的数据项"
---
# **ARR\_FILTER**
过滤数组并返回符合条件的数据项。
遍历传入的数组对象，筛选出符合条件的数据，然后返回新的数组元素构成的新数组。
## 语法{#grammar}
ARR\_FILTER(**arr**, **condition**)
- **arr**：必需，需要过滤的数组对象或其字符串形式
- **condition**：必需，条件过滤表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_FILTER(ARR(1,2,3),@>2)` 返回数组中大于2的元素，返回值`[3]`
2. `ARR_MAP(ARR_FILTER(ARR(1,2,3,4),@>2),@*2)` 返回数组中大于2的元素，并且将每个元素乘以2，返回值`[4,6]`
3. `ARR_MAP(ARR_FILTER('[[1,2,3,4],[2,2,5,4],[1,2,6,4]]',ARR_GET(@,1)=1),ARR_GET(@,3))` 返回二维数组中每行第一个元素=1的行的第三个元素，返回值`[3,6]`
4. `ARR_FILTER(SPLIT(COMBOBOX1,','),LOOKUP(@,MZRS_XXB.YSZYFWDM)=null)` 找到用户在下拉框`COMBOBOX1`中多选的职业类型中，在字段`MZRS_XXB.YSZYFWDM`关联的维表中不存在的类型有哪些。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_MAP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_map"
title: "ARR_MAP - 遍历数组并返回每个元素变换后的新数组"
---
# **ARR\_MAP**
遍历数组并返回每个元素变换后的新数组。
遍历传入的数组对象，对数组元素进行一个变换运算得到一个新的数组元素，然后返回新的数组元素构成的新数组。
## 语法{#grammar}
ARR\_MAP(**arr**, **exp**)
- **arr**：必需，需要过滤的数组对象或其字符串形式
- **exp**：必需，数组元素变换表达式，可用`@`表示当前元素，`@#`表示当前元素的序号（1开始）
## 示例{#example}
1. `ARR_MAP(ARR(1,2,3),@*2)` 每个元素乘以2，返回值`[2,4,6]`
2. `ARR_MAP(ARR_FILTER(ARR(1,2,3,4),@>2),@*2)` 返回数组中大于2的元素，并且将每个元素乘以2，返回值`[4,6]`
3. `ARR_MAP(ARR_FILTER('[[1,2,3,4],[2,2,5,4],[1,2,6,4]]',ARR_GET(@,1)=1),ARR_GET(@,3))` 返回二维数组中每行第一个元素=1的行的第三个元素，返回值`[3,6]`
4. `ARR_MAP(SPLIT(PARAM1,','),LOOKUP(@,MZRS_XXB.YSZYFWDM))` 找到参数`PARAM1`中传递的多个职业类型对应的标题文字。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_SORT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_sort"
title: "ARR_SORT - 返回排序后的新数组"
---
# **ARR\_SORT**
返回排序后的新数组。
## 语法{#grammar}
ARR\_SORT(**array**, **ordertype**)
- **array**：必需，要排序的数组，或数组的字符串形式
- **ordertype**：可选，默认升序，"asc" 升序，"desc" 降序。
## 示例{#example}
1. `ARR_SORT(ARR(2, 1, 4))` 返回`[1,2,4]`。
2. `ARR_SORT("[2, 1, 4]")` 也接受传递数组的字符串形式，返回`[1,2,4]`。
3. `ARR_SORT(ARR(2, 1, 4),'desc')` 返回`[4,2,1]`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_JOIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_join"
title: "ARR_JOIN - 返回数组所有元素拼接起来形成的字符串"
---
# **ARR\_JOIN**
返回数组所有元素拼接起来形成的字符串。
## 语法{#grammar}
ARR\_JOIN(**arr**, **seperator**, **ignoreNull**)
- **arr**：必需，需要过滤的数组对象或其字符串形式
- **seperator**：可选，分隔符，默认为空字符串
- **ignoreNull**：可选，是否忽略空元素，包括空字符串和null，默认不忽略
## 示例{#example}
1. `ARR_JOIN(ARR(1,2))` 返回字符串 `"12"`
2. `ARR_JOIN(ARR(1,2),',')` 用','拼接数组，返回字符串`"1,2"`
3. `ARR_JOIN(ARR(1,'',2,null,4),',')` 多个元素用','拼接起来，不忽略空值，返回值`1,,2,,4`
4. `ARR_JOIN(ARR(1,'',2,null,4),',',true)` 多个元素用','拼接起来，并忽略空值，返回值`"1,2,4"`
5. `ARR_JOIN(B1$)` 获取浮动单元格`B1`的数据，拼接起来，返回值`中档低档高档`
6. `ARR_JOIN(C1$,',')` 获取浮动单元格`C1`的数据，用','拼接起来，返回值`821,1399,267`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/ARR_UNION.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/arr_union"
title: "ARR_UNION - 返回多个数组的并集"
---
# **ARR\_UNION**
返回多个数组的并集。
ARR\_UNION函数可用于数据统计查询时的数组聚合统计并集，也可以用于多个数组之间的并集计算：
- 聚合统计：对一个数组字段进行聚合统计，此时只能传递一个参数，通常是传递要统计并集的数组字段，类似于数据库的SUM函数。
- 并集运算：对多个数组进行并集计算，此时此函数就不是一个聚合统计函数了，而是一个“行内”的运算函数。
## 语法{#grammar}
ARR\_UNION(**param1**, **param2**, **...**, **paramN**)
- **paramN**：必需。在查询统计中传递一个参数表示要聚合统计并集，传递多个值时表示并集计算。
## 示例{#example}
用于聚合统计，此时只能传递一个参数：
1. `ARR_UNION(model1.field1)` 统计字段field1的并集值，如果每行field1字段都为null或一行数据也没有那么返回null。
用于并集运算，传递多个参数：
1. `ARR_UNION(ARR(1,2,3), ARR(2,3,4))` 返回数组 `[1,2,3,4]`。
2. `ARR_UNION(ARR(1,2,3), null)` 返回数组 `[1,2,3]`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_OBJECT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_object"
title: "JSON_OBJECT - 构造一个JSON对象"
---
# **JSON\_OBJECT**
构造一个JSON对象。
## 语法{#grammar}
JSON\_OBJECT(**key1**, **value1**, **...**, **keyN**, **valueN**)
- **key1**：必需，表示JSON的一个属性的属性名
- **value1**：必需，表示JSON的一个属性的属性值
## 示例{#example}
1. `JSON_OBJECT('key1', 123, 'key2', 456)` 返回JSON对象`'{"key1":123,"key2":456}'`
2. `JSON_OBJECT('key1', 123, 'key2', JSON_OBJECT('key21', 456))` JSON\_OBJECT可以嵌套，生成更复杂的json，返回`'{"key1":123,"key2":{"key21":456}}'`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_GET.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_get"
title: "JSON_GET - 返回JSON中指定路径的值"
---
# **JSON\_GET**
返回JSON中指定路径的值。
## 语法{#grammar}
JSON\_GET(**json**, **path**)
- **json**：必需，JSON对象或其字符串形式。
- **path**：可选，指定路径，可以是JSON的KEY或者是[JSON\_PATH](../../types.md#json)语法表示的路径。
## 示例{#example}
1. `JSON_GET(JSON_OBJECT("key1",123, "key2", 456), 'key1')` 返回`123`
2. `JSON_GET('{"key1": 123, "key2": [1,2,3]}', 'key2')` 返回数组`[1,2,3]`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_SET.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_set"
title: "JSON_SET - 添加或更新JSON中指定位置的值并返回新的对象"
---
# **JSON\_SET**
添加或更新JSON中指定位置的值并返回新的对象。
指定路径存在值时更新值，不存在时插入新的值，如果传入的值为null，那么将在JSON中保留null值，如果希望传递null值时删除值，可以使用`JSON_REMOVE`函数。
此函数可运行于浏览器端、后端服务器端或SQL中，在SQL中此函数依赖数据库本身对JSON类型的支持能力，虽然大部分数据库都支持JSON数据类型，但可能部分数据库支持的不完善，因此会不支持此函数或只支持部分能力。在更新字段值时（如程序流的更新数据交互中）用户无需直接使用此函数更新字段，由于模型层已经明确定义了JSON字段的内部结构，用户只需要设置需要更新的JSON内部的部分KEY对应的值即可，系统内部会自动使用数据库底层的JSON字段增量更新能力只更新JSON中需要更新的值。
## 语法{#grammar}
JSON\_SET(**json**, **path1**, **value1**,..., **pathN**, **valueN**)
- **json**：必需，JSON对象或数组，或其字符串形式。
- **path**：必需，指定路径，可以是数组索引下标、JSON的KEY或者是[JSON\_PATH](../../types.md#json)语法表示的路径。
- **value**：必需，需要设置的值，可以传递多个path与value的参数对，实现同时更新多个值。
## 示例{#example}
1. `JSON_SET('{"key1": 123, "key2": 456}', 'key3', 789)` 返回JSON`{"key1": 123, "key2": 456, "key3": 789}`
2. `JSON_SET(JSON_OBJECT("key1", 123, "key2", 456), 'key2', 1)` 返回JSON`{"key1": 123, "key2": 1}`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_REMOVE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_remove"
title: "JSON_REMOVE - 删除JSON中指定位置的值并返回新的JSON"
---
# **JSON\_REMOVE**
删除JSON中指定位置的值并返回新的JSON。
## 语法{#grammar}
JSON\_REMOVE(**json**, **path1**,..., **pathN**)
- **json**：必需，JSON对象或其字符串形式。
- **path**：必需，JSON的KEY或者是[JSON\_PATH](../../types.md#json)语法表示的路径。
## 示例{#example}
1. `JSON_REMOVE('{"key1": 123, "key2": 456}', 'key2')` 返回JSON对象`{"key1": 123}`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_MERGE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_merge"
title: "JSON_MERGE - 合并两个或多个JSON并返回合并结果"
---
# **JSON\_MERGE**
合并两个或多个JSON并返回合并结果，相同路径的值会被右侧传入的值覆盖。
## 语法{#grammar}
JSON\_MERGE(**json1**,..., **jsonN**)
- **json**：必需，要合并的JSON对象或数组
## 示例{#example}
1. `JSON_MERGE(JSON_OBJECT({"key1": 123, "key2": 456}), JSON_OBJECT({"key1": 111, "key3": 333}))` 返回JSON`{"key1": 111, "key2": 456, "key3": 333}`
2. `JSON_MERGE(ARR("a", "b", "c"), ARR("1", "2"))` 返回`["1", "2", "c"]`
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_PRETTY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_pretty"
title: "JSON_PRETTY - 返回格式化后的JSON字符串"
---
# **JSON\_PRETTY**
返回格式化后的JSON字符串。
## 语法{#grammar}
JSON\_PRETTY(**json**)
- **json**：必需，JSON。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_QUOTE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_quote"
title: "JSON_QUOTE - 将字符串转义为双引号扩起来的JSON值"
---
# **JSON\_QUOTE**
将字符串转义为双引号扩起来的JSON值。
如果传入的字符串内部有回车、换行、双引号等特殊字符，那么将使用`\`进行转义，如果参数为NULL，则返回NULL。转义后的内容可以通过调用函数[JSON\_UNQUOTE](./JSON_UNQUOTE.md)还原。
## 语法{#grammar}
JSON\_QUOTE(**str**)
- **str**：必需，待转义的字符串，为NULL，则返回NULL。
## 示例{#example}
1. `JSON_QUOTE('abc')` 返回`"abc"`。
2. `JSON_QUOTE('ab"c')` 返回`"ab\"c"`。
3. `JSON_QUOTE(null)` 返回`null`。
4. `JSON_QUOTE('null')` 返回`"null"`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_UNQUOTE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_unquote"
title: "JSON_UNQUOTE - 反转义双引号扩起来的JSON值字符串"
---
# **JSON\_UNQUOTE**
反转义双引号扩起来的JSON值字符串。
JSON值字符串有其编码形式，具体见[JSON\_QUOTE](./JSON_QUOTE.md)函数示例，此函数是JSON\_QUOTE函数的反向操作，用于还原值本身的内容。
## 语法{#grammar}
JSON\_UNQUOTE(**str**)
- **str**：必需，待反转义的JSON值字符串，为NULL，则返回NULL。
## 示例{#example}
1. `JSON_UNQUOTE('"abc"')` 返回`abc`。
2. `JSON_UNQUOTE('"ab\"c"')` 返回`ab"c`。
3. `JSON_UNQUOTE(null)` 返回 NULL。
4. `JSON_UNQUOTE('"null"')` 返回`null`（null是4个字符构成的字符串）。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_VALID.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_valid"
title: "JSON_VALID - 判断字符串是否为一个合法的JSON对象或数组"
---
# **JSON\_VALID**
判断字符串是否为一个合法的JSON对象或数组。
## 语法{#grammar}
JSON\_VALID(**str**)
- **str**：必需，要判断的字符串。
## 示例{#example}
1. `JSON_VALID('-123.4')` 返回`false`，只有数组和JSON对象才是合法的。
2. `JSON_VALID('[1,2,3]')` 返回`true`，数组合法。
3. `JSON_VALID('{"a":1}')` 返回`true`，JSON对象合法。
4. `JSON_VALID('"ab\"c"')` 返回`false`，字符串不合法。
5. `JSON_VALID('hello')` 返回 `false`。
6. `JSON_VALID('"a":1}')` 返回`false`。
7. `JSON_VALID(null)` 返回`false`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/json/JSON_KEYS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/json_keys"
title: "JSON_KEYS - 返回JSON的KEY的数组"
---
# **JSON\_KEYS**
返回JSON的KEY的数组
## 语法{#grammar}
JSON\_KEYS(**json**)
- **json**：必需，JSON。
## 示例{#example}
1. `JSON_KEYS(JSON_OBJECT('id', 87, 'name', 'carrot'))` 返回`["id","name"]`
---
url: "https://docs.succapp.com/v5/guide/exp/func/geo/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/geo-funcs"
title: "空间函数列表"
---
---
navTitle: 空间函数
---
# 空间函数列表
!!!children (guide/exp/func/geo)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/geo/ST_DISTANCE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/st_distance"
title: "ST_DISTANCE - 计算2个地点之间的距离（单位米）"
---
# **ST\_DISTANCE**
计算2个地点之间的距离（单位米）。
用于查询地理信息时同时查询出距离信息，例如监管员移动监管时能在手机上显示每个被监管企业离自己有多远。也可以用于当作过滤条件查询某个距离范围内的企业（此时推荐使用函数[ST\_WITHIN](./ST_WITHIN.md)，性能更好）。
PostGIS标准参考：https://postgis.net/docs/manual-3.5/ST\_Distance.html
## 语法{#grammar}
ST\_DISTANCE(**point1**, **point2**)
- **point1**：必需，地点1的经纬度，支持地理坐标类型字段，或者通过[ST\_POINT](./ST_POINT.md)和[ST\_GEOMFROMTEXT](./ST_GEOMFROMTEXT.md)函数将经纬度转换为地理坐标类型。
- **point2**：必需，地点2的经纬度，支持地理坐标类型字段，或者通过[ST\_POINT](./ST_POINT.md)和[ST\_GEOMFROMTEXT](./ST_GEOMFROMTEXT.md)函数将经纬度转换为地理坐标类型。
## 示例{#examples}
1. `ST_DISTANCE(ST_POINT([企业信息].[经度], [企业信息].[纬度]), ST_POINT(117.195907, 39.118327))` 查询企业列表时将每个企业距离指定的地址的距离一起查询出来
2. `ST_DISTANCE([企业信息].[经纬度], ST_POINT(117.195907, 39.118327))` 同上，其中经纬度是地理坐标类型字段
3. `ST_DISTANCE([企业信息].[经纬度], ST_GEOMFROMTEXT('POINT(117.195907 39.118327')))` 同上
4. `ST_DISTANCE(ST_POINT([企业信息].[经度], [企业信息].[纬度]), ST_POINT($location.lng, $location.lat))` 查询企业列表时将每个企业距离当前用户所在的地址的距离一起查询出来
5. `ST_DISTANCE(ST_POINT([企业信息].[经度], [企业信息].[纬度]), ST_POINT($location.lng, $location.lat))<300` 查询距离我少于300米的企业
6. `ST_DISTANCE([企业信息].[经纬度], ST_POINT($location.lng, $location.lat))<300` 同上
---
url: "https://docs.succapp.com/v5/guide/exp/func/geo/ST_GEOMFROMTEXT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/st_geomfromtext"
title: "ST_GEOMFROMTEXT - 将`WKT`格式的地理字符串转换为地理类型"
---
# **ST\_GEOMFROMTEXT**
将`WKT`格式的地理字符串转换为地理类型。
`WKT`是一种描述点、线、面等几何信息的简易文本字符串，非常易于存储。
当用于地理函数运算时，需要转换为地理类型，比如：判断某个地点是否在指定的地理范围内（参考[ST\_WITHIN](./ST_WITHIN.md)）。
`WKT`格式说明
1. 坐标：`POINT(116.397 39.908)` 其中116.397表示经度，39.908表示纬度。
2. 路线：`LINESTRING(116.397 39.908,121.4737 31.2304)`
3. 区域：`POLYGON((116.397 39.908,121.4737 31.2304,113.2644 23.1291,116.397 39.908))`
1. 区域的坐标是闭环的，即开始坐标和结尾坐标必需相同。
2. 区域使用了双括号，是为了表示有洞的多边形：`POLYGON((35 10, 45 45, 15 40, 10 20, 35 10), (20 30, 35 35, 30 20, 20 30))`
`WKT`标准参考：
https://postgis.net/docs/manual-3.5/using\_postgis\_dbmanagement.html#OpenGISWKBWKT
https://en.wikipedia.org/wiki/Well-known\_text\_representation\_of\_geometry
PostGIS标准参考：https://postgis.net/docs/manual-3.5/ST\_GeomFromText.html
## 语法{#grammar}
ST\_GEOMFROMTEXT(**wkt**, **srid**)
- **wkt**：必需，字符串，表示`WKT`格式的几何字符串，比如：`POINT(经度 纬度)`。
- **srid**：可选，整数，表示坐标的参考系，默认值为`4326`，表示`WGS84`坐标系。
## 示例{#examples}
1. `ST_GEOMFROMTEXT('POINT(117.195907 39.118327)')` 将`WKT`格式的坐标字符串转换为地理坐标类型。
2. `ST_GEOMFROMTEXT('LINESTRING(116.397 39.908,121.4737 31.2304)')` 将`WKT`格式的路线字符串转换为地理路线类型。
3. `ST_GEOMFROMTEXT('POLYGON((116.397 39.908, 121.4737 31.2304,113.2644 23.1291,116.397 39.908))')` 将`WKT`格式的区域字符串转换为地理区域类型。
4. `ST_WITHIN([企业信息].[地理坐标], ST_GEOMFROMTEXT('POLYGON((117.195907 39.118327, 116.925304 38.935671, 117.654173 39.032846, 117.195907 39.118327))'))` 查询用户绘制的一个多边形内的企业。
---
url: "https://docs.succapp.com/v5/guide/exp/func/geo/ST_POINT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/st_point"
title: "ST_POINT - 将经纬度转换为地理坐标类型"
---
# **ST\_POINT**
将经纬度转换为地理坐标类型。
构造一个点坐标，可以有多种用途，比如：查询两个坐标点之间的距离（参考[ST\_DISTANCE](./ST_DISTANCE.md)）。
PostGIS标准参考： https://postgis.net/docs/manual-3.5/ST\_MakePoint.html
## 语法{#grammar}
ST\_POINT(**lng**, **lat**, **srid**)
- **lng**：必需，浮点数，表示经度。
- **lat**：必需，浮点数，表示纬度。
- **srid**：可选，整数，表示坐标的参考系，默认值为`4326`，表示`WGS84`坐标系。
## 示例{#examples}
1. `ST_POINT(117.195907, 39.118327)` 将经纬度转换为地理坐标类型。
2. `ST_POINT([企业信息].[经度], [企业信息].[纬度])` 将企业的经纬度转换为地理坐标类型。
3. `TOSTR(ST_POINT(117.195907, 39.118327))` 返回`WKT`格式的坐标字符串：`POINT(117.195907 39.118327)`
4. `ST_DISTANCE(ST_POINT([企业信息].[经度], [企业信息].[纬度]), ST_POINT(117.195907, 39.118327))` 查询企业列表时将每个企业距离指定的地址的距离一起查询出来
---
url: "https://docs.succapp.com/v5/guide/exp/func/geo/ST_WITHIN.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/st_within"
title: "ST_WITHIN - 判断某个地点是否在指定的地理范围内"
---
# **ST\_WITHIN**
判断某个地点是否在指定的地理范围内。
PostGIS标准参考：https://postgis.net/docs/manual-3.5/ST\_Within.html
## 语法{#grammar}
ST\_WITHIN(**geometry1**, **geometry2**, **distance**)
- **geometry1**：必需，表示一个地理坐标，支持地理坐标类型字段，或者通过[ST\_POINT](./ST_POINT.md)和[ST\_GEOMFROMTEXT](./ST_GEOMFROMTEXT.md)函数将经纬度转换为地理坐标类型。
- **geometry2**：必需，表示一个地理区域，支持地理坐标类型字段，或者通过[ST\_POINT](./ST_POINT.md)和[ST\_GEOMFROMTEXT](./ST_GEOMFROMTEXT.md)函数将经纬度转换为地理坐标类型。
- **distance**：可选，表示距离**geometry2**区域边界的距离，该距离内的坐标点也属于此函数表达的范围内，单位米。常用于方圆500米范围内的查询。
## 示例{#examples}
1. `ST_WITHIN(ST_POINT([企业信息].[经度], [企业信息].[纬度]), ST_POINT(117.195907, 39.118327), 500)` 查询指定地点方圆500米内的企业
2. `ST_WITHIN([企业信息].[地理坐标], ST_POINT(117.195907, 39.118327), 500)` 同上，其中经纬度是地理坐标类型字段
3. `ST_WITHIN([企业信息].[地理坐标], ST_GEOMFROMTEXT('POINT(117.195907 39.118327)'), 500)` 同上
4. `ST_WITHIN(ST_POINT([企业信息].[经度],[企业信息].[纬度]), ST_GEOMFROMTEXT('POLYGON((117.195907 39.118327, 116.925304 38.935671, 117.654173 39.032846, 117.195907 39.118327))'))` 查询用户绘制的一个多边形内的企业。
5. `ST_WITHIN([企业信息].[地理坐标], ST_GEOMFROMTEXT('POLYGON((117.195907 39.118327, 116.925304 38.935671, 117.654173 39.032846, 117.195907 39.118327))'))` 同上
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/others-funcs"
title: "其他函数列表"
---
---
navTitle: 其他函数
---
# 其他函数列表
!!!children (guide/exp/func/others)!!!
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/LOOKUP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/lookup"
title: "LOOKUP - 从指定表中查询指定数据行数据"
---
# **LOOKUP**
从指定表中查询指定数据行数据，其中查询表(lookup\_table)需要有且只有一个主键。
## 语法{#grammar}
LOOKUP(**lookup\_value**, **lookup\_table**, **\[lookup\_field]**)
- **lookup\_value**：必需。要查找的数值，对应模型表中的主键值，既可以是单元格对象，也可以是一个表达式。
- **lookup\_table**：必需。待查找数值的数据表，只能写页面内的引入了的模型变量（不是字符串），不能直接写表路径。
- **lookup\_field**：查询属性名，可以是字段名或字段名称。仅当模型的主键设置了文字字段时，可以不传，默认返回文字字段。
## 示例{#example}
1. `LOOKUP('110101',[销售单位])` 获取110101在模型表`[销售单位]`中对应的`ID`
2. `LOOKUP(B3,[销售单位],'XSDWMC')` 返回B3单元格的值在模型表`[销售单位]`中`XSDWMC`字段对应的值
3. `LOOKUP('SLFS00087',[终端门店],'门店名称')` 返回SLFS00087的值在模型表`[终端门店]`对应的`门店名称`字段值
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/QUERY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/query"
title: "QUERY - 从数据集查询满足条件的一个或多个数据"
---
# **QUERY**
从数据集查询满足条件的一个或多个数据。
query函数常用于独立灵活的取数计算、[明细填报中取汇总指标数据](##detail-agg)、[跨表数据校验](##cross-check)、[复杂统计分析计算](##complex-statistics)、[动态数据范围权限控制](##dynamic-ds-auth)等场景，能够灵活地从数据集中查询并返回满足条件的数据。
## 语法{#grammar}
QUERY(**exp**, **condition**)
- **exp**：必需，查询表达式，通常是一个引用数据集字段的表达式。可以根据表达式内容返回单个值、一维数组或二维数组等，具体请参考[示例](#example)。
- **condition**： 可选，数据集的查询过滤条件，可以关联其他表进行过滤。
**示例地址：** [QUERY](https://demo.succbi.com/v5/bi/query)
## 示例{#example}
1. 返回一个值
没有使用ARR函数、聚合函数时，默认总是返回查询结果的第一条数据的值。
比如查询满足`[企业基本信息].[经营状态]='存续'`条件的第一条数据的企业名称：`IF(QUERY([企业基本信息].[企业名称],[企业基本信息].[经营状态]='存续') IS NOT NULL,TRUE,FALSE)`
2. 返回一维数组
使用[ARR函数](../json/ARR.md)将多行查询结果转为一维数组返回。
比如查询过滤我关注的用户的信息：`[用户表].[用户ID] IN QUERY(ARR([用户信息].[用户ID]),[用户关注表].[关注人]=$user.id)`
3. 返回二维数组
使用[ARR函数](../json/ARR.md)查询多个字段时将多行查询结果转为二维数组返回。
比如查询满足条件的客户信息：`QUERY(ARR([用户信息].[用户ID],[用户信息].[用户名称]),[用户信息].[性别]='女' and [用户信息].[年龄]>25 and [用户信息].[注册时间]>'2024-01-01')`
4. 返回一个聚合值
使用[SUM](../aggregate/SUM.md)、[COUNT](../aggregate/COUNT.md)等聚合函数将多行数据聚合为一个值返回。
比如查询满足条件的客户数量：`(QUERY(COUNT([用户信息].[用户ID]),[用户信息].[性别]='女' and [用户信息].[年龄]>25 and [用户信息].[注册时间]>'2024-01-01'))`
5. 多个query函数自动合并查询
页面内多个地方使用query函数时，系统会根据查询模型和条件自动合并，减少对发起的查询请求数量。示例参考：TODO
6. 全量缓存数据在内存中再计算query函数
页面经常做大量query查询时，如果查询的模型数据量不大，可以把数据集设置为[允许下载全量数据]()，系统将数据先全量缓存到内存中，再在内存中进行query函数计算，提升查询性能。示例参考：TODO
7. 与SELECT函数的区别
[SELECT](./SELECT.md) 函数只在SQL端计算，SELECT函数表达式必须放在模型的计算字段或过滤条件中使用，而query函数可以独立构造查询，能放在任何可以使用表达式的地方。
## 场景{#scene}
### 明细填报中取汇总指标数据{#detail-agg}
常用于表单、superpage等明细查询页面中取汇总数据，减少对数据加工的依赖，简化取数逻辑。
比如在门店的产品销售情况填报表单中，表单在初始化时会按照产品维浮动出产品列表，同时需要将要填报的销售数量、销售金额等指标从业务库的销售明细表中汇总计算出来，传统的做法是需要使用数据加工提前汇总好数据再引用，现在可以直接通过`query(sum([销售明细表].[销售数量]))`表达式来取汇总数据。
示例地址：[表单取数](https://demo.succbi.com/v5/DEMO/app/ci.app?:id=fetch-and-calc&:dataPeriod=202212&:orgId=010301&:sheet=query_func)
### 跨表数据校验{#cross-check}
在表单填报场景中，经常需要对填报的数据进行跨表校验以确保数据的准确性和一致性。通过QUERY函数可以灵活地获取其他表中的相关数据，实现复杂的跨表业务规则校验，而不需要创建很多临时的数据加工用来取数。
常见的跨表校验场景：
1. 唯一性校验
比如在新增用户信息时，需要校验用户手机号是否已被使用：
`QUERY(COUNT([用户信息].[手机号]),[用户信息].[手机号]=表单.手机号)>0`
2. 数据一致性校验
在采购订单填报时，需要校验采购金额是否超过预算限额：
`采购金额 > QUERY(SUM([预算表].[剩余金额]),[预算表].[部门ID]=$user.dept_id)`
3. 业务规则校验
在合同审批表单中，校验经办人是否具有对应的业务权限：
`合同金额 <= QUERY([员工权限表].[审批额度],[员工权限表].[员工ID]=$user.id)`
### 复杂统计分析计算{#complex-statistics}
在BI报表分析中，经常需要分析销售趋势和业绩达成情况，比如计算最近12个月的累计销售额来评估业务增长情况。或者在预算管理中需要按月跟踪预算执行进度，计算年度累计预算完成率等。
以计算累计销售额为例:
`QUERY(SUM([销售表].[销售额]),[销售表].[销售日期].[年月] BETWEEN 起始年月 AND 截止年月)`
### 动态数据范围权限控制{#dynamic-ds-auth}
在OA系统中管理公司所有的项目建设情况，包括项目的人力资源、合同、进度等信息。一个员工可以参与多个项目并担任不同的项目角色，这些信息单独记录在`项目成员表`中。
为了实现基于用户项目角色权限进行数据过滤，可以使用QUERY函数动态控制登录用户的数据范围：`[项目信息表].[项目ID] in QUERY(ARR([项目成员表].[项目ID]),[项目成员表].[用户ID]=$user.id)`
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/SELECT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/select"
title: "SELECT - 构造一个子查询"
---
# **SELECT**
构造一个子查询，可以是单行子查询作为结果集的一部分，也可以在in和exists操作符后面构成过滤条件。
## 语法{#grammar}
SELECT(**exp**,**where**)
- **exp**：必需。是一个模型的名称、模型的字段引用。
- **where**： 必需。表示关联关系表达式和条件过滤表达式。
## 用途
1. 作为计算字段使用，`exp`只能是单个字段或表达式，且必须是是单行子查询。
2. 与in操作符构成过滤条件，`exp`可以是单个字段或多字段数组。
3. 与exists操作符构成过滤条件，`exp`必须是表名，如果`where`中没有关联关系，则取全局关联关系。
## 示例{#examples}
1. `select([企业信息].[企业名称], [发票表].[销方]=[企业信息].[纳税人识别号])` 用于单字段，查询销方的企业名称等相关信息。
2. `select(count([发票表].[发票编码]), [发票表].[销方]=[企业信息].[纳税人识别号])` 用于单字段，查询各个企业的开局发票总数。
3. `[发票表].[销方] in select([企业信息].[ID], [企业信息].[失信]='Y')` 过滤出销方是失信企业的相关信息。
4. `exists select([发票表], [企业信息].[ID]=[发票表].[销方企业] and [企业信息].[失信]='Y')` 过滤出失信企业开具的发票信息。
5. `exists select([变更表], [企业信息].[ID]=[变更表].[ID] and [变更表].[变更类型]='法人变更')` 过滤出发生企业法人发生变更的企业。
6. `arr([发票表].[发票号码], [发票表].[发票代码]) in select(arr([逃税预警].[发票号码], [逃税预警].[发票代码]), [逃税预警].[逃税类型]=9)` 过滤出逃税预警的发票信息，这是一个`多字段`的in条件。
## 案例分析
查询需求：
对企业信息的查询，可以添加各种查询条件，如果企业是投资企业，则统计其总投资额。
分析：
`[企业投资关系]`中，一个企业可以投资多个企业，也可以被多个企业投资，是一个多对多的关系的对应表。
如果用常规分析方法，需要先从`[企业投资关系]`中统计出投资企业的投资总额，然后关联`[企业基本信息]`，需要一个加工。
新的思路：
使用系统提供的selelct函数和exists进行统计和过滤。
企业基本信息中加一个计算字段：
投资总额=`select(sum([企业投资关系].[认缴出资金额]),[企业投资关系].[投资企业ID]=[企业ID])`
表示从`[企业投资关系]`中统计投资金额，和企业表的关系是`[企业投资关系].[投资企业ID]=[企业ID]`。
如果需要过滤出所有投资企业，则可以通过exists过滤：
`EXISTS select([企业投资关系].[被投资企业ID],[企业投资关系].[投资企业ID]=[企业基本信息].[企业ID])`
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/USER_INGROUP.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/user_ingroup"
title: "USER_INGROUP - 判断用户是否在指定组"
---
# **USER\_INGROUP**
判断用户是否在指定组。
## 语法{#grammar}
USER\_INGROUP(**\[user\_id]**, **group\_id**)
- **user\_id**: 可选，表示要判断的用户的ID，不传递时表示当前用户。
- **group\_id**: 要进行判断的组ID。
## 示例{#examples}
1. `USER_INGROUP('manager')` 判断当前用户是否属于组`manager`。
2. `USER_INGROUP('zhang', 'manager')` 判断用户`zhang`是否属于组`manager`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/USER_GROUPS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/user_groups"
title: "USER_GROUPS - 返回指定用户的用户组列表"
---
# **USER\_GROUPS**
返回指定用户的用户组列表。
## 语法{#grammar}
USER\_GROUPS(**\[user\_id]**)
- **user\_id**：可选，表示要获取用户组信息的用户ID，不传递时表示当前用户。
## 示例{#examples}
1. `USER_GROUPS()` 返回当前用户的组，返回值是一个数组，如： `['group1', 'group2']`
2. `USER_GROUPS('zhang')` 返回用户`zhang`的组，返回值是一个数组，如： `['group1']`
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/DEPT_PROPERTY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/dept_property"
title: "DEPT_PROPERTY - 获取部门的属性"
---
# **DEPT\_PROPERTY**
获取部门的属性。
## 语法{#grammar}
DEPT\_PROPERTY(\[**dept\_id**],**pname**)
- **dept\_id**: 可选，表示要获取信息的部门的ID，不传递时表示获取当前用户所在部门的属性，大小写敏感。
- **pname**: 要获取的属性名，如：`id`, `name`, `deptid`, `deptname`, `parentid`, `orgid`, 或其它部门表中存在的字段名，忽略大小写。
## 示例{#examples}
1. `DEPT_PROPERTY('name')` 获取当前用户所在部门的名称
2. `DEPT_PROPERTY('parentid')` 获取当前用户所在部门上级部门的ID
3. `DEPT_PROPERTY('dev', 'orgid')` 获取部门`dev`的所属机构的ID
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/USER_PROPERTY.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/user_property"
title: "USER_PROPERTY - 获取用户的属性"
---
# **USER\_PROPERTY**
获取用户的属性。
## 语法{#grammar}
USER\_PROPERTY(**\[user\_id]**, **pname**)
- **user\_id**: 可选，表示要获取信息的用户的ID，不传递时表示当前用户。
- **pname**: 要获取的属性名，如：`id`, `name`, `org_id`, `dept_id`, `phone`, `email`, `qq`, `wechat`, 或其它用户表中存在的字段名。
## 示例{#examples}
1. `USER_PROPERTY('email')` 获取当前用户的邮件地址。
2. `USER_PROPERTY('zhang', 'qq')` 获取用户`zhang`的qq号码。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/USER_PERMISSION.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/user_permission"
title: "USER_PERMISSION - 判断当前登录用户是否有对应的权限"
---
# **USER\_PERMISSION**
判断当前登录用户是否有对应的权限
## 语法{#grammar}
USER\_PERMISSION(**path**, **operations**)
- **path**: 必需，元数据资源路径，可使用完整路径如`/example/ana`，也可使用相对路径如`../path1`、`./path2`,也可以使用`.`用于代表当前资源。
- **operations**: 必需，要进行判断的权限操作，若是需要同时判断多个权限操作，请用`,`分隔，比如`mgr-m-edit,view-basic`。
## 示例{#examples}
1. `USER_PERMISSION(".","mgr-m-edit")` 判断当前用户是否对当前资源有`编辑`权限。
2. `USER_PERMISSION("/TestCase/ana/example.dash", "mgr-m-save")` 判断当前用户对资源`/TestCase/ana/example.dash`有`保存`权限。
3. `USER_PERMISSION("../example.dash","view-basic,mgr-m-edit")`判断当前用户是否对与当前资源同级名为`example.dash`的同时拥有`查看`和`编辑`权限。
4. `USER_PERMISSION("./example.fapp","action-approve")` 判断当前用户是否对当前资源目录下名为`exmaple.fapp`的报表填报应用有`审批`权限;
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/OFFSET.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/offset"
title: "OFFSET - 通过行列偏移量获取单元格"
---
# **OFFSET**
通过行列偏移量获取单元格。和f系列函数不同，这个偏移是针对设计器中的单元格进行偏移的，而不是浮动后的单元格，主要用于做一些固定表，想获取浮动行中的单元格需要使用f系列函数。
## 语法{#grammar}
OFFSET(**row**, **col**, **\[property]**)
- **row**：必需。行偏移量，正数向下移动，负数向上移动，0表示不移动，只能写常量。
- **col**：必需。列偏移量，正数向右移动，负数向左移动，0表示不移动，只能写常量。
- **property**：要取的单元格属性名，不传默认取单元格的值。
**示例地址：** [OFFSET](https://demo.succbi.com/v5/bi/offset)
## 示例{#examples}
1. `offset(-1,0)` 获取当前单元格向上移动一个单元格的值，例如：当前单元格是B2时，表示获取B1单元格的值
2. `offset(1,0)` 获取当前单元格向下移动一个单元格的值，例如：当前单元格是B2时，表示获取B3单元格的值
3. `offset(0,1)` 获取当前单元格向右移动一个单元格的值，例如：当前单元格是B2时，表示获取C2单元格的值
4. `offset(0,-1)` 获取当前单元格向左移动一个单元格的值，例如：当前单元格是B2时，表示获取A2单元格的值
5. `offset(-1,0,'$txt')` 获取当前单元格向上移动一个单元格的文本值，例如：当前单元格是B2时，表示获取B1单元格的文本值
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/DECODE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/decode"
title: "DECODE - 将control_value数值与后面的一系列的偶序列数值相比较"
---
# **DECODE**
将control\_value数值与后面的一系列的偶序列数值相比较，以决定返回值。
## 语法{#grammar}
DECODE(**control\_value**, **value1**, **result1**\[,value2,result2…] \[,default\_result])
- **control\_value**\* 必需，期望比较的值，可以是表达式。
- **value1** 必需，第一个比较值。
- **result1** 必需，如果control\_value等于第一个比较值，则返回此参数值。
- **value2** 第二个比较值。
- **result2** 如果control\_value等于第二个比较值，则返回此参数值。
- **valueN** 第N个比较值。
- **resultN** 如果control\_value等于第N个比较值，则返回此参数值。
- **default\_result** 默认值，如果前面`偶数序列值`都不能匹配，则返回此参数值，如果没有此参数，则返回null。
需要注意的是：所有返回值类型必须相同。
## 示例{#examples}
- `decode( x , 1 , 'x is 1', 2 ,'x is 2', 'others')`
- 当x等于1时，则返回'x is 1'。
- 当x等于2时，则返回'x is 2'。
- 否则，返回'others'。
- `decode( x , 1 , 'x is 1', 2 ,'x is 2', null, 'nulls')`
- 当x等于1时，则返回'x is 1'。
- 当x等于2时，则返回'x is 2'。
- 当x为null，则返回'nulls'。
- 否则，返回null。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/TABLE_FIELD.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/table_field"
title: "TABLE_FIELD - 查询动态字段"
---
# **TABLE\_FIELD**
查询动态字段。
通常用于查询数据时动态选择要查询统计的字段。在制作报表或可视化图形时，如果我们明确的知道要取哪个字段的值，那么可以直接通过对应的字段名引用它，但在有些需求场景下，具体要查询哪些字段是有报表查看者决定的，可能是通过参数栏的参数选择查询哪个字段，也可能是通过其他方式动态决定查询哪个字段。
见报表示例：[多维分析](https://demo.succbi.com/v5/demo/%E5%A4%9A%E7%BB%B4%E5%88%86%E6%9E%90)。
## 语法{#grammar}
TABLE\_FIELD(**table**, **field**)
- **table**： 必需。表名，如`[销售明细表]`。不支持传递动态表名。
- **field**：必需。动态字段，可以是个参数指定字段，控制不同条件下查询不同字段。
## 示例{#examples}
1. `TABLE_FIELD([销售明细表], [字段下拉框1])` 字段下拉框1 中配一些字段表达式枚举值，通过下拉框切换字段，实现查询不同字段。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/SCRIPT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/script"
title: "SCRIPT - 调用页面脚本中的表达式函数"
---
# **SCRIPT**
调用页面脚本中的表达式函数，并返回脚本函数的计算结果。
脚本编写见：[前端表达式脚本函数](../../../dev/script/frontend/expression-functions.md)和[后端表达式函数脚本](../../../dev/script/backend/expression-functions.md)。
## 语法{#grammar}
SCRIPT(**script\_funcname**, **arg1**, **...**, **argN**)
- **script\_funcname**：必需，脚本函数名。脚本中定义 `expfunc_函数名`，表达式中传入去掉 `expfunc_` 后的名称。
- **arg1**：可选，传给脚本函数的第 1 个参数。
- **argN**：可选，传给脚本函数的第 N 个参数。
## 示例{#examples}
1. `SCRIPT('formatRegion', [客户].[地区编码])` 调用脚本函数 `expfunc_formatRegion`。
2. `SCRIPT('weatherForecast15', treeSelector1.LNG, treeSelector1.LAT)` 把经纬度传给脚本函数并返回天气数据。
## 详细描述{#details}
表达式会先计算 `SCRIPT` 后面的参数，再把参数值传给脚本函数。脚本函数第一个参数由系统传入，是表达式计算上下文；从第二个参数开始，依次对应 `SCRIPT` 中的 **arg1** 到 **argN**。
`SCRIPT` 可以返回字符串、数值、布尔值、日期、对象或数组等结果。前端表达式脚本函数还可以返回 `Promise`，表达式会等待异步结果返回后继续计算。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/MEASURE_BINS.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/measure_bins"
title: "MEASURE_BINS - 将字段值按照指定的区间进行分组"
---
# **MEASURE\_BINS**
将字段值按照指定的区间进行分组。
## 语法{#grammar}
MEASURE\_BINS(**field**, **fieldBins**, **fieldBinsDesc**)
- **field**：必需，数值类型字段。
- **fieldBins**：必需，指定字段的区间。使用\[]和()分隔区间，\[]表示保护区间，()表示不包含区间。如`[1,10)[10,50)[50~)`。也可以用`-`分隔，如`1-10-50~`等价于`[1,10)[10,50)[50~)`
- **fieldBinsDesc**：可选，字段区间的描述，不同区间用逗号分隔。
## 示例{#examples}
1. `MEASURE_BINS(年龄, '1-10-50~')` 年龄按照1-10,10-50,50以上分组，描述为`1~10`,`10~50`,`50~`。
2. `MEASURE_BINS(年龄, '[1,10)[10,50)[50~)','1到10岁,10到50岁,50以上')` 年龄按照1-10,10-50,50以上分组，描述为`1到10岁`,`10到50岁`,`50以上`。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/MEASURE_NAMES.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/MEASURE_NAMES"
title: "MEASURE_NAMES - 列出指定的度量字段"
---
# **MEASURE\_NAMES**
列出指定的度量字段。
通常用于查询数据时动态选择要查询统计的字段，通常用于查询数据时动态选择要查询统计的字段。在制作报表或可视化图形时，如果我们明确的知道要取哪个字段的值，那么可以直接通过对应的字段名引用它，但在有些需求场景下，具体要查询哪些字段是有报表查看者决定的，可能是通过参数栏的参数选择查询哪些字段，也可能是通过其他方式动态决定查询哪些字段。
`MEASURE_NAMES`函数多用于在报表浮动单元格浮动动态的度量字段列表，搭配模型的`[度量值]`属性一起使用，见报表示例[动态列查询报表](https://demo.succbi.com/v5/demo/%E5%8A%A8%E6%80%81%E5%88%97%E6%9F%A5%E8%AF%A2)。
## 语法{#grammar}
MEASURE\_NAMES(**table**, **fields**, **fieldsCaption**, **fieldsDisplayFormat**)
- **table**： 必需。表名。
- **fields**：必需。类型是数组，动态字段列表，可以是个参数指定字段，控制不同条件下查询不同字段。
- **fieldsCaption**：可选。类型是数组，动态字段描述列表，指定了就作为查询的字段描述列返回，否则查询根据表达式自动生成描述。
- **fieldsDisplayFormat**：可选。类型是数组，动态字段显示格式列表，指定了就作为查询的字段显示格式列返回，否则查询根据表达式自动生成显示格式。
## 示例{#examples}
1. `MEASURE_NAMES([销售明细表], [字段列表下拉框1], [字段列表下拉框1].[标题])` 字段下拉框1 中配一些字段表达式枚举值，通过下拉框切换字段，实现查询不同字段。
2. `MEASURE_NAMES([销售明细表], [字段列表下拉框1], [字段列表下拉框1].[标题], [字段列表下拉框1].[displayFormat])` 字段下拉框1 中配一些字段表达式枚举值，通过下拉框切换字段，实现查询不同字段，指定了每个字段的显示格式。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/WFL_CANDO.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/wfl_cando"
title: "WFL_CANDO - 判断当前用户对流程任务是否能做特定的审批操作"
---
# **WFL\_CANDO**
判断当前用户对流程任务是否能做特定的审批操作。
## 语法{#grammar}
WFL\_CANDO(**taskId**,**operation**)
- **taskId**：流程任务代码，支持接收单个字符串或数组
- **operation**：流程操作，只支持下列单个参数
- 提交：submit
- 批准：approve
- 退回：retreat
- 否决：reject
- 终止：terminate
- 撤回：retract
## 示例{#examples}
1. `WFL_CANDO('006cb96f7d8d9e4998','approve')` 判断当前用户对指定任务是否能做批准操作，如果允许则返回true
2. `WFL_CANDO(taskId,'retreat')` 判断当前用户对传入到页面中的流程任务是否能做退回操作，如果允许则返回true
3. `WFL_CANDO(list1.$checked.taskId,'approve')` 判断当前用户对列表勾选的流程任务是否都能做批准操作，所有勾选的任务都允许则返回true，通常用于批量审批的场景
## 详细描述
该函数返回布尔值，判断用户对流程任务是否有对应的审批操作能力。用户能做的审批操作，受限于工作流节点上的操作配置，可参考文档[流程操作](../../../app/workflow/operate.md)。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/WFL_CANEDIT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/wfl_canedit"
title: "WFL_CANEDIT - 判断指定工作流模型是否可写"
---
# **WFL\_CANEDIT**
判断指定工作流模型是否可写，或指定的工作流模型字段是否可写。
## 语法{#grammar}
WFL\_CANEDIT(**modelOrField**)
- **modelOrField**：工作流模型或者工作流模型字段表达式。
## 示例{#examples}
1. `WFL_CANEDIT([销售明细表])` 判断工作流模型\[销售明细表]是否存在可写字段，如果存在则返回true
2. `WFL_CANEDIT([销售明细表].[销售单位].[表达式])` 判断工作流模型\[销售明细表]的\[销售单位]字段是否可写，可写则返回true
## 详细描述
该函数返回布尔值，表明指定的工作流模型下是否存在可写字段，或者指定的工作流模型字段是否可写。
工作流模型的字段是否可写，是在工作流的节点数据权限中设置，可参考文档[工作流节点数据权限设置](../../../app/workflow/datapermissions.md)。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/WFL_CANVIEW.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/wfl_canview"
title: "WFL_CANVIEW - 判断指定工作流模型是否可读"
---
# **WFL\_CANVIEW**
判断指定工作流模型是否可读，或指定的工作流模型字段是否可读。
## 语法{#grammar}
WFL\_CANVIEW(**modelOrField**)
- **modelOrField**：工作流模型或者工作流模型字段表达式。
## 示例{#examples}
1. `WFL_CANVIEW([销售明细表])` 判断工作流模型\[销售明细表]是否存在可读字段，如果存在则返回true
2. `WFL_CANVIEW([销售明细表].[销售单位].[表达式])` 判断工作流模型\[销售明细表]的\[销售单位]字段是否可读，可写则返回true
## 详细描述
该函数返回布尔值，表明指定的工作流模型下是否存在可读字段，或者指定的工作流模型字段是否可读。
工作流模型的字段是否可读，是在工作流的节点数据权限中设置，可参考文档[工作流节点数据权限设置](../../../app/workflow/datapermissions.md)。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_BOOL.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_bool"
title: "RAWSQL_BOOL - SQL直通函数"
---
# **RAWSQL\_BOOL**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是bool类型。
## 语法{#grammar}
RAWSQL\_BOOL(**sql\_expr**, **arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_BOOL('?1>?2', [fact].[Sales], [fact].[Sales2])` 比较两个值大小。
2. `RAWSQL_BOOL('exists (select 1 from test.JJHK t where t.ID=?1)', [fact].[纳税人识别号])` 实现一个exists条件。
3. `RAWSQL_BOOL('?1 in (select ID from test.JJHK)', [fact].[纳税人识别号])` 实现一个in条件。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_DATE.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_date"
title: "RAWSQL_DATE - SQL直通函数"
---
# **RAWSQL\_DATE**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是日期类型。
## 语法{#grammar}
RAWSQL\_DATE(**sql\_expr**, **arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_DATE('max(?1)', [fact].[成立日期])` 求最大日期。
2. `RAWSQL_DATE('FN_GET_WORK_DATE1_S(?1, ?2)', [fact].[CI_DATE], [fact].[IN_BUSS_TYPE])` FN\_GET\_WORK\_DATE1\_S是自定义函数，商用车，进件时间调整,将非工作时间调整为工作时间。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_DATETIME.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_datetime"
title: "RAWSQL_DATETIME - SQL直通函数"
---
# **RAWSQL\_DATETIME**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是时间戳类型。
## 语法{#grammar}
RAWSQL\_DATETIME(**sql\_expr**, **arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_DATETIME('max(?1)', [fact].[updatetime])` 求最大更新时间。
2. `RAWSQL_DATETIME('FN_GET_WORK_DATE1_S(?1, ?2)', [fact].[CI_DATE], [fact].[IN_BUSS_TYPE])` FN\_GET\_WORK\_DATE1\_S是自定义函数，商用车，进件时间调整,将非工作时间调整为工作时间。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_INT.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_int"
title: "RAWSQL_INT - SQL直通函数"
---
# **RAWSQL\_INT**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是整型、长整型。
## 语法{#grammar}
RAWSQL\_INT(**sql\_expr**, **arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_INT('?1', [fact].[人数])` 直接替换。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_NUMBER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_number"
title: "RAWSQL_NUMBER - SQL直通函数"
---
# **RAWSQL\_NUMBER**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是数值类型。
## 语法{#grammar}
RAWSQL\_NUMBER(**sql\_expr**, **arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_NUMBER('MEDIAN(?1)', [fact].[Sales])` 求\[fact].\[Sales]的中位数。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/RAWSQL_STR.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/rawsql_str"
title: "RAWSQL_STR - SQL直通函数"
---
# **RAWSQL\_STR**
SQL直通函数，可用于将`SQL表达式`直接发送到数据库，而不由BI系统进行解析。
如果您有BI系统不能识别的`自定义数据库函数`，则可以使用直通函数调用这些自定义函数。
返回值是字符串类型。
## 语法{#grammar}
RAWSQL\_STR(**sql\_expr**,**arg1**, **...**, **argN**)
- **sql\_expr**：必需，sql表达式，直接发送到数据库，可以包含?1,...,?N等参数。
- **arg1**: 可选，sql\_expr的参数，对应sql\_expr中的?1。
- **argN**: 可选，sql\_expr的参数，对应sql\_expr中的?N，N是第N个参数。
## 示例{#examples}
1. `RAWSQL_STR('first_value(?1) over (partition by ?2 order by ?3 desc)', [fact].[userid], [fact].[swjgid], [fact].[tzze])` 按税务机关分组，投资额降序排列取第一个企业用户，这是oracle的语法。
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/PIDCHECK.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/pidcheck"
title: "PIDCHECK - 判断是否为合法的身份证号"
---
# **PIDCHECK**
判断是否为合法的身份证号，返回对象可以直接当布尔值使用。
## 语法{#grammar}
PIDCHECK(**pid**)
- **pid**：必需，要检查的身份证ID，字符串类型
## 示例{#example}
1. `PIDCHECK('350822197101183592')` 参数为有效身份证号，返回`true`
2. `PIDCHECK('44092319850718266X')` 参数为有效身份证号且校验位为X，返回`true`，小写x将判断为`false`
3. `PIDCHECK('3508221971011')` 参数为无效身份证号，返回`false`
4. `PIDCHECK("")` 参数为空字符串，返回`false`
5. `PIDCHECK(350822197101183592)` 参数不为字符串类型，返回`false`，不为字符串，判断为`false`
---
url: "https://docs.succapp.com/v5/guide/exp/func/others/APPLY_FILTER.md"
htmlUrl: "https://docs.succapp.com/v5/exp/func/apply_filter"
title: "APPLY_FILTER - 将多个字段的过滤条件应用到指定的表上"
---
# **APPLY\_FILTER**
将多个字段的过滤条件应用到指定的表上。
## 语法{#grammar}
APPLY\_FILTER(**filters**, **table**)
- **filters**： 必需。通常传递字段筛选器组件对象。
- **table**：可选。需要应用过滤条件的表，默认不传，表示应用到所在查询的主表上。
## 用途
字段筛选器可以动态选择多个字段设置过滤条件，通常过滤条件是自动生效的不需要使用`APPLY_FILTER`函数。
自动过滤只能使用一个目标数据表，当需要让字段筛选器的过滤条件应用到多个数据表时就需要用到`APPLY_FILTER`函数。`APPLY_FILTER`函数会自动根据字段名（优先使用字段名，其次使用物理字段名）进行匹配。
## 示例{#examples}
1. `APPLY_FILTER([更多查询条件1], [企业基本信息表])` 将用户在字段筛选器“更多查询条件1”选择的过滤条件应用到“企业基本信息表”对应的字段上。
---
url: "https://docs.succapp.com/v5/guide/exp/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/exp/faq"
title: "常见问题"
---
---
order: 12
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/exp/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/exp/errcode"
title: "表达式错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 表达式错误提示排查
---
url: "https://docs.succapp.com/v5/guide/perf/README.md"
htmlUrl: "https://docs.succapp.com/v5/perf"
title: "性能优化"
---
---
order: 13
navTitle: 性能优化
---
# 性能优化
---
url: "https://docs.succapp.com/v5/guide/perf/db-pref.md"
htmlUrl: "https://docs.succapp.com/v5/perf/db-perf"
title: "数据仓库性能优化"
---
---
order: 1
navTitle: 数据仓库性能优化
---
# 数据仓库性能优化
大数据量的数据加工或分析查询中常常会遇到性能问题，导致数据加工执行耗时长、报表查询响应慢，而数据仓库的性能优化往往是一件极其复杂的工作，不仅需要具备专业的数据库优化技能，还要熟悉掌握整个数据仓库的架构、模型建设等情况。传统的DBA人员往往只能掌握一种或两种数据库的优化技术，而且对企业全局的数据仓库架构和系统业务知之甚少，随着BI产品的应用，更是难以应对灵活多变的即席分析。
SuccBI在产品层面将数据仓库中性能优化的三个层次：即数据仓库架构、数据模型、数据库底层，融为一体，综合治理和管控，同时利用产品平台的天然优势，在优化上智能的融合了业务的理解，提升了优化的针对性和有效性。
SuccBI性能优化功能均支持通过可视化的操作配置过程来完成，无需掌握数据库优化相关命令，同时也屏蔽了不同类型数据库实现上的差异，提供给用户完全统一的使用体验。
SuccBI支持多种性能优化方式，如[聚集](#agg)、[子集](#subset)、[索引](#index)、[分区](#partition)、[预连接](#pre-connect)、[表分析](#table-analyze)、[Elasticsearch检索](#es)等
## 聚集{#agg}
保存最细粒度的原始表称为基础表，而聚集表是对原始表中某个或某几个维度进行汇总而产生的汇总表。汇总的强度越大（颗粒越粗），聚集表中的数据量就越小，查询的速度就越快。在所有提高数据仓库性能的方法中，建立聚集表是最有效的一种方法。\
SuccBI以数据仓库维度建模理论为根基，融合了聚集模型在大量大数据项目中实践应用的经验，在产品层提供了简单易用且智能化的聚集优化功能。
[更多聚集管理介绍>>](https://docs.succapp.com/v5/data-gov/agg-management)
## 子集{#subset}
数据子集是基于数据模型表和数据加工表进行过滤、排序、选择字段等操作后的子集，它是一个更接近具体业务的数据集合，在数据仓库中它有另外一个名称，即切片。在OLAP应用中，数据子集能将大表查询转换为小表查询，这样用户在较频繁的查询某个特定条件下的数据时能有效提升查询效率。\
SuccBI支持的数据子集在一定意义上扩展了数据仓库中传统的切片。
[更多子集管理介绍>>](https://docs.succapp.com/v5/data-gov/subset-management)
## 索引{#index}
索引是一种数据结构，能够帮助用户快速的检索数据库表中的数据。索引在数据库层面的优化中占据着举足轻重的地位。一般对于查询概率比较高，经常作为where条件的字段设置索引。常见的索引类型有唯一索引、组合索引、反向键索引、位图索引、函数索引等。\
SuccBI支持对索引进行集中管理和监控。
[更多索引管理介绍>>](../data-gov/model/model-index.md)
## 分区{#partition}
分区技术是数据库层面的一种常见的优化手段，其采用的是“分而治之”的思想，它根据`分区键`将一个表物理的分解为多个更小的、更易管理的部分，但在逻辑上仍然是一张表。分区非常适用于数据仓库的大表优化，如根据`年月`分区键将数据表划分成若干个物理分区，在BI的报表分析中按年月来查询时，数据库能自动定位到目标物理分区，提高访问数据的效率。常见的分区方式有范围分区、散列分区、列表分区及自增长分区等。\
SuccBI支持模型的分区优化。
[更多分区管理介绍>>](https://docs.succapp.com/v5/data-gov/partition-management)
## 预连接{#pre-connect}
预连接是通过对事实表和维度表的联合查询而生成的一类汇总表，在预连接表中保存有维度表中的描述信息和事实表中的事实值。通过预连接，可以避免用户查询时数据库产生表连接操作，所以预连接表的查询效率要高很多。\
SuccBI在加工模型中支持预连接表。
[更多预连接管理介绍>>](https://docs.succapp.com/v5/data-gov/pre-connect)
## 表分析{#table-analyze}
数据库在执行SQL时会先根据表的统计信息来确定表的访问方式生成执行计划。但表的统计信息并非实时更新，过旧的统计信息可能会直接导致SQL解析时生成错误且低效的执行计划，从而严重影响系统的运行效率。
统计信息的更新需要在数据库层面设置定时的采集任务，该采集任务一般是针对全库或者某个用户，难以实现表级别的采集任务调度，同时传统的定时采集任务往往会与数据仓库的ETL时间窗口发生冲突，导致既占用了数据库服务器资源，又可能采集到错误的统计信息。
SuccBI基于产品平台的优势，能更好更有效的管理调度表分析。
[更多表分析管理介绍>>](https://docs.succapp.com/v5/data-gov/table-analyze)
## Elasticsearch检索{#es}
Elasticsearch检索是指SuccBI在产品层集成了Elasticsearch搜索引擎，你可以通过创建[Elasticsearch模型](https://docs.succapp.com/v5/data-gov/elasticsearch-model)将Elasticsearch索引当做普通表一样轻松的管理起来。
借助Elasticsearch，SuccBI可以提供给你应对海量数据[全文检索](./full-text-search.md)的能力。
---
url: "https://docs.succapp.com/v5/guide/perf/optimize.md"
htmlUrl: "https://docs.succapp.com/v5/perf/optimize"
title: "仪表板、报表性能优化"
---
---
order: 3
navTitle: 仪表板、报表性能优化
---
# 仪表板、报表性能优化
当页面出现加载过慢或者卡顿的情况时，可从以下几点着手排查：
- **[查看页面SQL请求耗时情况](#sql-perf)**
- **[查看页面资源加载耗时情况](#slow-page-load)**
- **[查看网络资源是否正常](#net)**
- **[查看WEB服务器性能](#server)**
## SQL查询耗时{#sql-perf}
### SQL查询数量过多{#too-many-sql}
调出开发者工具（可以使用F12快捷键调出），在调试页面查看页面的`SQL(querydata)`请求数量是否过多，如过多可考虑优化数据加工，将多个加工处理到同一个加工中，减少SQL请求数量。\
检查是否执行了不必要的SQL，其中数据界面没使用到的SQL需要定位分析原因。
### SQL查询耗时过久{#slow-sql}
查看SQL请求中`Stalled`时间，如过长可检查下网络情况。\
查看SQL请求中`TTFB`时间，如过长可针对该请求对应的数据模型进行优化，具体可为该模型添加索引或者设置预览数据，可参考文档[数据仓库性能优化](./db-pref.md#agg)。
查看SQL请求中的SQL语句，可复制到数据源中进行执行分析优化。
## 页面资源加载耗时{#slow-page-load}
若是页面资源加载过慢，可从以下几点排查：
- 图片资源加载过慢：请检查静态资源是否过大，图片一般不要超过300K，建议将图片资源压缩后再上传，[压缩网站地址](https://tinypng.com/)
- 如有二次开发脚本：请检查`js类资源`加载情况，若过慢可以排查脚本中是否import了非必要的类或方法
- 如Web层做了代理：建议在代理层做[静态资源的缓存](../devops/cluster/reverse-proxy.md#cache)，实现页面请求的动静分离，静态资源要走缓存后，加载后下次不会在从服务器再加载
## 网络资源{#net}
查看网络资源能否正常访问，可从以下几点排查：
- 查看代理是否正常
- 检查防火墙，可使用不经过防火墙的IP访问BI系统进行排查
- 在本地和服务器抓包，分析网络异常位置，再做进一步处理
## WEB服务器{#server}
查看WEB服务器性能，另外日志级别设置也会影响系统性能：
- 查看或监控`内存`、`CPU`使用情况，如`内存`、`CPU`使用率过高，可能是有任务阻塞或高并发访问，可分析在线用户数、线程堆栈，若是高并发，可扩展集群
- 检查日志文件`catalina.out`，如产生大量日志文件，可查看日志级别设置，日志级别设置为`TRACE`、`DEBUG`可能会严重影响系统性能，建议修改为`INFO`
::: tip 提示
- CPU、内存等变化会导致[产品许可](../sys-settings/basic/license.md)失效，请确认后处理
- 若日志级别为DEBUG，会产生大量日志，影响系统性能
:::
---
url: "https://docs.succapp.com/v5/guide/perf/full-text-search.md"
htmlUrl: "https://docs.succapp.com/v5/perf/fulltextsearch"
title: "全文检索"
---
---
order: 10
---
# 全文检索
## 什么是全文检索{#what-is-fulltextsearch}
日常生活中的数据通常分为两类：结构化数据和非结构化数据。
- **结构化数据**：指具有固定格式或有限长度的数据，如数据库，元数据等。
- **非结构化数据**：指不定长或无固定格式的数据，如邮件，word文档等。
按照数据的分类，搜索也分为两种：
- **对结构化数据的搜索**：如使用SQL语句对数据库表中字段数据的搜索，利用windows搜索对文件名，类型，修改时间进行搜索等。
- **对非结构化数据的搜索**：如用Google和百度等搜索引擎可以搜索大量内容数据。
通过信息技术手段实现对word、邮件、文章等无固定格式的非结构化数据进行检索的方式即为全文检索。通常意义上的全文检索具有如下的特征：
1. 提供快速查询响应
基于倒排索引实现关键词的快速查询响应
2\. 结果相关性排序\
对匹配上的文档来打分，相关性越高的文档获得的分数越高，返回时越靠前。
随着企事业单位信息化进程的发展，数据出现爆发式的增长，海量数据如何实现快速的全文检索，是当前信息系统建设中遇到的严峻挑战。
## SuccBI的解决方案{#solution}
### 集成搜索引擎{#integrated-search-engine}
SuccBI是企业级产品，应用场景中往往有海量的数据，业务需求复杂而多变，随着业务的增长会有迁移或扩容的需求，同时海量数据的检索过程不是单纯的搜索，会伴随一些统计分析。基于这样的应用场景，SuccBI选择在产品层面集成了当前开源的、最主流、成熟的搜索引擎[Elasticsearch](https://www.elastic.co/cn/elasticsearch/)，借助Elasticsearch，SuccBI可以轻松的应对海量数据的全文检索。同时对于SuccBI来说，Elasticsearch就如同一个普通的数据仓库数据源，它可以完美无缝的与分析模块进行协同工作。
### 方案思路与架构{#solution-architecture}
SuccBI产品提供的解决方案架构如下：
SuccBI在产品层集成Elasticsearch，使得数据的存储更加灵活。来源系统中结构化数据部分在建模后存储在Vertica、Oracle等关系型数据库中，而非结构化数据部分，如文档、邮件、日志则可以采集、加工存储在[Elasticsearch模型](https://docs.succapp.com/v5/data-gov/elasticsearch-model)中（通常也是先归集存储在数据仓库模型中，通过同步机制将数据同步到Elasticsearch，详见[Elasticsearch模型](https://docs.succapp.com/v5/data-gov/elasticsearch-model)）。
这样，只需要在应用时根据需要选择使用[Elasticsearch模型](https://docs.succapp.com/v5/data-gov/elasticsearch-model)进行检索即可，使用Elasticsearch模型时，系统的查询将在Elasticsearch引擎中运行并返回结果。
### 解决方案优势{#solution-advantages}
在SuccBI产品层面使用上面的方案架构集成Elasticsearch具有如下优势：
1. SuccBI可立即获得Elasticsearch搜索引擎的超强检索能力，在海量数据检索场景下，充分利用Elasticsearch集群的高扩展性、高可用性、高性能为你提供稳定可靠的检索服务。
2. SuccBI集成Elasticsearch搜索引擎，屏蔽了技术上的复杂实现，对使用者完全透明，简单易用，无需SQL技能、无需Elasticsearch原理知识、无需掌握Elasticsearch的REST API、零编码，让业务人员能更好的聚焦于业务信息。
---
url: "https://docs.succapp.com/v5/guide/perf/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/perf/faq"
title: "常见问题"
---
---
order: 12
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/perf/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/perf/errcode"
title: "性能优化错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 性能优化错误提示排查
---
url: "https://docs.succapp.com/v5/guide/permission/README.md"
htmlUrl: "https://docs.succapp.com/v5/permission"
title: "权限管理"
---
---
order: 14
navTitle: 权限管理
---
# 权限管理
---
url: "https://docs.succapp.com/v5/guide/permission/depts.md"
htmlUrl: "https://docs.succapp.com/v5/permission/depts"
title: "部门管理"
---
---
order: 1
---
# 部门管理
本文主要讲解如何进行部门管理，包括下列内容：
\[\[toc]]
## 增删改部门{#modify}
1. 新增部门：在[权限](./README.md)>部门页面点击新增按钮，在右侧的部门属性栏中输入正确的信息，点击**保存**即可成功创建部门
2. 修改部门信息：选择需要修改的部门，修改相关信息后点击**保存**即可
3. 删除部门：选择需要删除的部门，点击删除按钮，会再次弹出确认删除对话框，点击**确定**部门将被删除。支持同时勾选多个部门批量删除。
::: tip
- 修改部门信息不是缓慢变化，修改后无法查到历史记录，请谨慎操作
- 删除后的部门会从系统部门表中移除，无法恢复，请谨慎操作
- 删除部门后，如果有下级部门也会一并删除
:::
部门属性信息如下：
- 部门ID：不能为空，且必须是唯一的。若ID重复，则覆盖原相同ID部门的信息。
- 部门名称：ID对应的名称信息，不能为空，可以重复。
- 上级部门：可以为空，为空时该部门为一级部门，没有上级部门。当存在上级部门时此处需要选择上级部门名称。如果选中某个部门节点后点击新增按钮，这里会默认选择新增时被选中的节点，也可以再次修改为其他节点。
## 与第三方机构库对接{#third-party-depts}
部门（即机构）已经在第三方系统中存在，例如oa、钉钉等软件或其他业务系统，如何将部门导入到系统中，可以参考文档：[如何导入第三方系统的用户表和部门表](./FAQ/如何导入第三方系统的用户表和部门表.md)
## 为部门的用户分配权限{#grant}
系统不支持对部门直接分配权限，为用户分配权限的方法有两种：
1. 为单个用户分配权限：**用户>权限**，找到部门下的用户，选择对应资源添加权限。参考文档[权限管理-分配权限](./grant/README.md#分配权限)
2. 为部门下的多个用户批量分配权限：将同一部门的用户添加到一个用户组，[批量赋权](./groups.md#用户组权限分配)
---
url: "https://docs.succapp.com/v5/guide/permission/users.md"
htmlUrl: "https://docs.succapp.com/v5/permission/users"
title: "用户管理"
---
---
order: 2
---
# 用户管理
本文主要讲解如何进行用户管理，包括下列内容：
\[\[toc]]
## 增删改用户{#modify}
1. 新增用户：在[权限](./README.md)>用户页面点击新增按钮，在右侧的用户属性栏中输入正确的信息，点击**保存**即可成功创建用户
2. 修改用户信息：选择需要修改的用户，修改相关信息后点击**保存**即可
3. 删除用户：选择需要删除的用户，点击删除按钮，会再次弹出确认删除对话框，点击**确定**用户将被删除。支持同时勾选多个用户批量删除
::: tip
- 修改用户信息不是缓慢变化，修改后无法查到历史记录，请谨慎操作
- 删除后的用户会从系统用户表中移除，无法恢复，请谨慎操作
:::
用户基本信息如下：
- 用户ID：用户登录系统时使用的用户名。不能为空，且必须是唯一的。若ID重复，则覆盖原相同ID用户的信息。
- 用户名称：ID对应的名称信息，不能为空，可以重复。
- [部门](./depts.md)：可以为空，为空时该用户不属于任何部门。若在此处选择某一部门，则在组织架构中将该用户划分到此部门下。
- 密码：用户登录系统时使用的登录密码。不能为空，长度不超过40个字符，支持英文、数字和特殊字符，英文区分大小写。
- 手机号：用户的手机号。
- 邮箱：用户的邮箱。
- 启用：表示是否启用该用户，被启用的用户才能登录系统，默认勾选。
## 为用户分配权限{#grant}
为用户分配权限有2种方式：
1. **用户>权限**，选择对应资源添加权限。参考文档[权限管理-为单个用户分配权限](./grant/README.md#single-user)
2. 将拥有相同权限的用户添加到一个用户组，[批量赋权](./groups.md#assign-permissions)
## 超级管理员{#admin}
超级管理员是一个系统的内置用户，用户名为admin，系统安装部署完毕后便会自动添加这个用户。超级管理员具有系统所有的权限，允许执行任何操作，使用超级管理员时需要特别注意，以免误操作导致系统问题。
## 与第三方用户库对接{#third-party-users}
用户已经在第三方系统中存在，例如oa、钉钉等软件或其他业务系统，如何将用户导入到系统中，可以参考文档：[如何导入第三方系统的用户表和部门表](./FAQ/如何导入第三方系统的用户表和部门表.md)
## 如何做第三方用户库的单点登录{#sign-in}
单点登录提供在多系统共存的环境下，用户只需要登录一次就可以访问所有关联系统的功能，是目前比较流行的企业业务整合的解决方案之一。如何实现和第三方用户库做单点登录可以参考文档：[单点登录](../devops/sso/README.md)
## 外部用户{#external-users}
系统包含了两套用户：
- 系统用户：即存储在用户表中的用户，可直接在**权限**页面下进行用户管理
- 外部用户：用于区别于系统用户，外部用户可以脱离系统组织机构。一般用于标记系统资源管理人员之外非固定访问用户，启用外部用户可以提高查询数据库表的查询效率。
如对于政府机构项目一般会将固定的政府管理用户存储在系统用户中，将社会公共人员用户存储为外部用户。
### 启用外部用户{#enable-external-users}
在**系统设置**>**安全设置**>**登录安全**>页面下勾选**启用外部用户**后，外部用户表中的用户即可进行登录系统：
### 增删改外部用户{#modify-external-users}
勾选**启用外部用户**后，可在**权限**页面看到外部用户信息，并且可以增加、删除、修改外部用户，方式与系统用户管理一致，可参考[增删改用户](#modify)，外部用户信息存储在[外部用户表](https://demo.succbi.com/v5/sysdata/data?:open=IRtXQkHVjMBbVO0EohQ5sB&:tblview=modelData)（`/sysdata/data/tables/sec/EXTERNAL_USERS.tbl`）中。
### 为外部用户分配权限{#external-users-permission}
勾选**启用外部用户**后，在用户组中会增加一个外部用户组`external`，为该用户组添加权限后，所有的外部用户即可继承该用户组上的权限，可参考文档[用户组管理-外部用户组](./groups.md#external)。\
外部用户不可添加到[部门](./depts.md)和[用户组](./groups.md)中，不可给单独的外部用户添加权限。
---
url: "https://docs.succapp.com/v5/guide/permission/groups.md"
htmlUrl: "https://docs.succapp.com/v5/permission/groups"
title: "用户组管理"
---
---
order: 3
---
# 用户组管理
用户组是相同权限用户的集合，通过设置用户组的权限可以批量的设置多个用户的权限。\
用户组管理包含以下内容：
\[\[toc]]
## 增删改用户组{#modify}
用户组的维护包括新增、修改和删除操作：
1. 新增用户组：点击**新增**，在**基本**中输入用户组的相关信息，点击**保存**即创建新的用户组
2. 修改用户组：选择需要修改的用户组，修改相关信息后点击**保存**即可
3. 删除用户组：选择需要删除的用户组，点击**删除**，在弹出的删除确认框中点击**确定**，该条用户组数据即被成功删除。支持同时勾选多个用户组批量删除。
用户组基本信息：
- 用户组ID：不能为空，且必须是唯一的，不能重复。若ID重复，则覆盖原相同ID用户组的信息。
- 用户组名称：ID对应的名称信息，不能为空，可以重复。
- 描述信息：对用户组信息的描述，可以为空。
- 启用：表示是否启用该用户组，勾选后用户组的权限即可生效，默认勾选。
:::tip
点击**校验**，可以检查**用户组ID**、**用户组名称**是否为空，输入及保存时，系统也会自动校验
:::
## 匹配特定用户{#match-user}
可以通过**手动添加用户**为用户组匹配特定用户，点击**添加**添加用户组成员，在下拉列表中选择对应部门，或者在搜索框搜索用户
## 动态批量匹配用户{#auto-match}
为用户组添加成员时支持动态批量匹配，即使用**自动匹配条件**自动匹配满足匹配条件的用户：
- 条件表达式中可以使用[用户属性字段](../exp/var/$user.md)结合[表达式](../exp/README.md)一起使用。
- 当用户的属性发生变化，不满足匹配条件时，成员信息会自动刷新。
如将湖北省的审批用户均添加至“湖北审批”用户组，添加自定义匹配条件为`[用户ID] LIKE '%sp'`
:::tip
自动匹配条件中只能使用用户表中已有的属性字段，若需要使用自定义的用户属性字段，根据字段的值标识用户，如`【审批状态】=1`的用户为审批用户，可在用户表中新增自定义字段即可，参考文档[如何使用字段的自定义属性](../data-gov/faq/howto-custom-field-property.md)
:::
## 用户组权限分配{#assign-permissions}
为用户组中的成员分配权限有2种方式：
1. **用户组**>**权限**，选择对应资源添加权限
2. 在对应资源的下拉列表中选择权限，选择用户组添加权限，如何分配权限可参考文档[权限管理-文件权限管理](./grant/README.md#file-permission)
## 系统内置用户组{#built-in-group}
系统中内置了4个用户组：
- [超级管理员用户组](#admin)
- [所有用户组](#allusers)
- [匿名用户组](#anonymous)
- [外部用户组](#external)
### 超级管理员用户组admin{#admin}
该用户组内的用户即拥有系统超级管理员权限，即系统的所有权限，可参考[用户管理-超级管理员](./users.md#admin)
### 所有用户组allusers{#allusers}
所用用户组是系统里所有用户的集合，为该用户组分配权限时，所有的用户都会拥有该权限。
### 匿名用户组anonymous{#anonymous}
匿名用户即不需要登录即可访问系统，为该用户组分配权限后，在**系统设置**>**安全设置**>**登录安全**>页面下勾选**启用匿名用户**后，用户即可免登录系统进行页面信息的查看。
:::tip
匿名用户因为是免密登录，出于对系统安全性考虑，建议一般为匿名用户只分配查看的权限。
:::
### 外部用户组external{#external}
外部用户即区别于系统用户的用户，可参考文档[用户管理-外部用户](./users.md#external-users)。在**系统设置**>**安全设置**>**登录安全**>页面下勾选**启用外部用户**后，即可为外部用户组分配权限，外部用户表中的用户会继承该用户组的权限。
---
url: "https://docs.succapp.com/v5/guide/permission/grant/README.md"
htmlUrl: "https://docs.succapp.com/v5/permission/grant"
title: "权限管理"
---
---
order: 4
navTitle: 权限管理
indexTitle: 分配权限
---
# 权限管理
权限决定了登录用户在系统中可以访问的资源及可查看的数据范围，即元数据权限和数据级次权限。系统提供了灵活的权限管理机制，包含以下内容：
\[\[toc]]
## 为单个用户分配权限{#single-user}
为用户分配权限的操作步骤如下:
1. 在**权限**>**用户**列表下，选中需要分配权限的用户，在右侧选择**权限**标签页，进入权限管理界面
2. 权限管理界面列出了该用户当前的权限，勾选对应的对象名称并选择[权限操作](./operations.md)
3. 点击**保存**按钮，用户权限即添加成功
4. 在文件资源中也可以为单个资源分配单个用户或用户组权限，可查看文档[文件权限管理](#file-permission)
权限属性:
- 名称：即用户可操作的对象，系统会列举项目下的所有元数据对象，勾选对应的元数据即可
- 权限：限定能对指定的对象进行哪些操作，没有选择的操作将不被允许，参考[权限操作说明](./operations.md)
- 数据范围：即数据级次权限，用于限定用户可以查看的数据范围，默认为全部，也可添加自定义数据范围，通过条件表达式获取，参考文档[数据级次权限](./datarange.md)
- 继承自：当用户的权限来自于用户组或上级部门时，会显示该用户的权限的来源
:::tip 提示
1. 当只勾选对象名称时，权限操作默认为**查看**权限，也可直接选择[权限操作](./operations.md)，确定后会自动勾选上对象。
2. 勾选上级父资源目录分配权限时，下级子资源也会自动继承权限，参考[权限继承规则](#权限继承规则)
:::
## 为多个用户分配权限{#multiple-users}
当多个用户拥有相同的权限时，可以将这些用户加入到一个[用户组](../groups.md)，并为用户组分配权限，加入到用户组的所有用户自动继承该用户组的权限。\
为[用户组](../groups.md)分配权限的方式与为单个用户分配的方式一致，区别在于入口不同：
- 用户：**用户**>**权限**
- 用户组：**用户组**>**权限**
## 文件权限管理{#file-permission}
在文件管理界面，为用户分配选中文件的权限，此方式适用于新建或查看文件时快捷为已存在的用户添加权限：
1. 选择对应文件，如分析下的服饰企业的首页看板仪表板，在下拉框中选择**权限**
2. 在搜索框中输入**用户**或**用户组**名称，并勾选对应的权限操作
3. 点击**确定**按钮，元数据的权限即分配成功
:::tip 提示
1. 在文件列表界面分配权限时，权限操作与在用户(用户组)管理界面的权限操作是一致的，参考[权限操作说明](./operations.md)
2. 在权限管理界面与文件管理界面上分配与修改权限时，用户与文件的权限是同步的。即在用户管理界面分配权限后，在文件上能看到自身的权限，在文件上分配权限后，在用户的权限列表中也可看到对应的文件对象权限
3. 在文件管理界面分配权限，可以同时分配给[用户](../users.md)或者[用户组](../groups.md)
:::
## 数据范围管理{#datarange}
数据范围用于设置用户可查看的数据范围，如湖北省的用户只能查看湖北地区的数据。
数据范围的设置有3种类型：
- 默认：当用户没有继承的权限来源时，数据范围默认为全部，即可查看所有的数据
- 添加数据范围：可根据业务用户的实际需要，自定义可查看的数据范围，参考文档[数据级次权限](./datarange.md)
- 继承：当用户拥有继承自用户组或父目录的权限时，会默认继承用户组或父目录上的数据范围设置
:::tip 提示
用户修改文件数据范围后，会覆盖继承自用户组或父目录的数据范围，此时修改继承的用户组或父目录数据范围将不会影响该文件数据范围，如需应用修改后的用户组或父目录数据范围，可点击`继承`恢复文件的数据范围为继承的数据范围
:::
## 权限继承规则{#rules}
### 父目录与子文件的权限继承规则{#directory-and-files}
1. 子文件的权限会继承父目录的权限
2. 子文件上不允许取消继承自父目录的权限，继承的权限是灰色的，只能基于继承的权限增加更多的权限
### 用户与用户组的权限继承规则{#users-and-group}
1. 加入用户组的用户，会继承用户组的权限
2. 不允许修改继承自用户组的操作权限和数据范围，只能基于继承的权限增加更多的操作权限和数据范围
### 反权限设置{#anti-authority}
当用户同时拥有自身权限和继承自用户组的权限时，而自身权限与继承的权限有冲突，需要禁用用户组的权限，即反权限操作。\
如用户所在用户组拥有表单的查看和填报数据权限，某特殊用户的权限只能进行查看。在用户权限管理中，禁用继承自用户组的权限即可。在权限操作列表中对应权限操作上**右键**>**禁用**，如在**填报数据**上右键禁用。
---
url: "https://docs.succapp.com/v5/guide/permission/grant/datarange.md"
htmlUrl: "https://docs.succapp.com/v5/permission/datarange"
title: "数据级次权限"
---
---
order: 1
---
# 数据级次权限
**数据级次权限**是指不同权限用户查看同一个页面时显示不同的数据，如湖北省的用户只能查看湖北地区的数据，湖南省的用户只能查看湖南地区的数据：
|湖北用户|湖南用户|
|---|---|
|||
示例地址：[总体经营情况](https://demo.succbi.com/v5/DEMO/app/%E6%9C%8D%E9%A5%B0%E9%94%80%E5%94%AE%E9%A9%BE%E9%A9%B6%E8%88%B1.app?:id=%E6%80%BB%E4%BD%93%E7%BB%8F%E8%90%A5%E6%83%85%E5%86%B5)（湖北用户：hb01/123456，湖南用户：hn01/123456）
## 原理及使用方法{#principle}
**数据级次**是针对[事实表](../../data-gov/GLOSSARY.md#fact-table)所关联的[维表](../../data-gov/GLOSSARY.md#dimension-key)来进行限制的，比如“服饰数据”事实表中关联了“行政区划”维表，该维表内部有各个省市编码，如“湖北”、“湖南”等，当限制只能查看湖北地区的数据时，事实表在查询时会强制加上查询湖北地区的条件，所以设置数据范围需要有以下几个步骤：
1. 添加上述的数据范围维表，需要在**项目设置**中添加，具体可参考文档[项目数据范围设置](../../project-manage/data-permission-setting.md)
2. 在资源上为用户或用户组选择**数据范围**，即在**权限**界面为不同的用户分配**数据范围**，可参考[为用户分配数据级次权限](#distribute)
:::tip
除了可以对单个用户设置**数据范围**，还可以通过**继承用户组权限**的方式进行限制，具体可参考文档[权限管理](./README.md#rules)。以下内容均以设置单个用户的数据范围为例进行介绍。
:::
## 为用户分配数据级次权限{#distribute}
为用户分配数据级次权限需要在**数据范围**中设置，这里有四种分配类型：
- **默认**：使用默认的数据范围，默认值的内容可以在[项目数据范围设置](../../project-manage/data-permission-setting.md#default-range)中设置
- **选择项目中预设的数据范围**：选择任意一个在[项目数据范围设置](../../project-manage/data-permission-setting.md#data-range)中预设的数据范围
- **新增数据范围**：可以在当前页面自定义数据范围，具体可见[添加一条新的数据范围](#add)，该类型仅管理员可见
- **继承**：继承该用户所属用户组或父目录的数据范围设置，若另外设置了**数据范围**，则以设置的内容为准
:::tip
在项目数据范围中设置的数据范围，可以直接在**数据级次权限**中进行分配，既方便选择不同的数据范围，也利于进行统一的管理。这可以理解为在当前项目定义了一个项目内的变量，该变量表示数据的不同范围，定义后的内容在权限模块下引用。
:::
## 添加数据范围{#add}
在**权限**模块下添加的**数据范围**仅在该页面可用，需要对以下几个内容进行设置：
- **名称**：对数据范围的简要描述
- **权限操作**：设置**查看**、**编辑**等类型的权限操作，具体可参考[权限操作介绍](#operation)
- **数据范围**：需要提前在**项目数据范围设置**中定义一个数据范围维表，随后在对话框内部使用**表达式**设置动态数据范围或指定具体的维项，具体设置可参考[项目数据范围设置](../../project-manage/data-permission-setting.md#data-range)
:::tip
只有管理员才能在这个权限树上自定义数据范围为其他用户进行分配，其他用户在分配权限时，只能使用**项目数据范围设置**中已经定义好了的数据范围，并且该用户还必须属于[项目数据范围设置](../../project-manage/data-permission-setting.md#data-range)中设置的**用户组**。
:::
### 权限操作介绍{#operation}
**数据范围**中的**权限操作**可以针对不同的**数据范围**分配不同的**权限操作**，如分配“湖北”、“湖南”两地数据的查看权限和“湖北”地区数据的数据导出权限。这里**操作范围**的选项是外部[分配权限](./README.md)的子集，即只有在外部分配了的权限才能出现在**数据范围**的**权限操作**下拉列表中，其中：
- [仪表板](../../data-viz/dash/README.md)、[报表](../../report/README.md)、[数据模型](../../data-gov/GLOSSARY.md#data-model)：只能分配**查看**权限
- [表单](../../ci/design-fapp/settings/README.md)、[SuperPage](../../app/superpage/README.md)：可以分配**查看**、**审批**、**填写数据**、**数据管理**权限，这些权限的具体介绍可以参考文档[权限操作说明](./operations.md)
---
url: "https://docs.succapp.com/v5/guide/permission/grant/operations.md"
htmlUrl: "https://docs.succapp.com/v5/permission/operations"
title: "权限操作说明"
---
---
order: 1
---
# 权限操作说明
权限操作即登录用户在系统可进行的权限操作，当直接勾选上级权限操作时，默认勾选下级所有子权限操作：
权限操作分为3类:
\[\[toc]]
:::tip
1. 权限操作与各功能模块相关，在对应模块的资源上只会显示该模块具有的权限操作列表。如只有**表单**模块有填报数据的权限操作，在其他模块的权限操作列表上不会提供该选项。
2. **系统数据**项目下的元数据，只有**管理**的权限操作，即不进行权限操作的细分，能进行所有的操作，如查看、新建、修改、删除等，即完全控制。
:::
## 查看{#view}
对对象进行查看的权限：
- 查看：允许用户查看资源，查看操作是一个基本的操作，拥有其它操作权限时将默认拥有该操作的权限
- 查看评论：允许用户查看评论，只有**分析**模块的元数据有此操作权限
- 查看[流程图](../../data-process/build-data-flow/README.md)：允许用户查看数据加工的加工流程图，只有**数据**模块有此操作权限
- 查看[模型属性](../../data-gov/model/model-settings.md)：允许用户查看模型表的属性，只有**数据**模块由此操作权限
- 预览sql：允许用户预览数据加工的sql，只有**数据**模块由此操作权限
- 查看[性能优化](../../data-process/optimization/README.md)：允许用户查看模型表的性能优化设置，只有**数据**模块由此操作权限
## 交互{#action}
在查看权限的基础上，能进一步的进行一些符合当前业务用户身份（非管理员）的操作，比如对仪表板的数据进行下钻、填报表单数据等：
- [数据过滤](../../data-viz/dash/design/data/data-filter/README.md)：允许用户对数据进行筛选
- 数据[下钻](../../data-viz/dash/design/action/drill-down.md)：允许用户进行钻取，只有**分析**模块的元数据有此操作权限
- 视图管理：允许用户将计算结果保存为视图以及进行视图的增删改操作，只有**分析**模块的元数据有此操作权限
- [分享](https://docs.succapp.com/v5/co/share)：允许用户进行分享，只有**分析**模块的元数据有此操作权限
- 刷新：允许用户进行数据刷新
- 导出：允许用户导出元数据
- 添加评论：允许用户对仪表板或报表等发表评论，只有**分析**模块的元数据有此操作权限
- 打印：允许用户打印元数据页面
- 复制到剪切板：允许用户复制当前页面的内容到剪切板
- [填报数据](../../ci/filling.md)：只有**表单**模块有此操作权限
- 提交数据：允许用户填报并提交表单数据
- 添加草稿：允许用户将填报的数据保存为草稿
- 导入填报数据：允许用户通过导入的方式填报表单数据
- 粘贴：允许用户粘贴内容至表单进行填报
- [审批](../../ci/design-fapp/workflow.md)：允许用户审批表单数据或流程审批，只有**表单**模块有此操作权限
- 数据管理：只有**表单**模块有此操作权限
- 锁定数据：允许用户锁定表单数据
- 解锁数据：允许用户解锁表单数据
- 删除数据：允许用户删除表单数据
- 批量审核：允许用户审核表单数据
- 批量计算：允许用户批量计算表单数据
- 批量导出：允许用户批量导出表单数据
## 管理{#manage}
能对对象进行增加、删除、和修改操作：
- 文件管理
- 编辑：允许用户编辑元数据
- 保存：允许用户保存元数据
- 重命名：允许用户重命名元数据
- 移动：允许用户移动元数据位置
- 复制：允许用户复制元数据
- 导入元数据：允许用户导入元数据，只有在文件夹上有此操作选项
- 导出元数据：允许用户导出元数据
- 分配权限：允许用户在自身权限范围内为其他用户分配权限
- 评论管理：允许用户编辑或删除评论，只有**分析**模块的元数据有此操作权限
- [提取数据](../../data-process/data-output/README.md#提取数据)：允许用户提取模型表的数据，只有**数据**模块有此操作权限
- 导出：允许用户导出文件数据源，只有文件数据源上有此操作选项
- 新建，只有在文件夹上有此操作选项
- 新建文件夹：允许用户新建文件夹
- 新建仪表板：允许用户新建仪表板
- 新建图分析：允许用户新建图分析
- 新建报表：允许用户新建报表
- 新建应用：允许用户新建应用
- 新建模型：允许用户新建模型，包括空白模型，ods模型，sql模型，数据库表模型
- 新建文件数据源：允许用户新建文件数据源
- 新建表单：允许用户新建表单
- 删除，只有文件夹上有此操作权限；对文件夹资源分配**删除**，代表对可以删除这个文件夹的下级资源，但无权限删除这个文件夹本身。
- 删除文件夹：允许用户删除文件夹
- 删除仪表板：允许用户删除仪表板
- 删除报表：允许用户删除报表
- 删除图分析：允许用户删除图分析
- 删除应用：允许用户删除应用
- 删除模型：允许用户删除模型，包括空白模型，ods模型，sql模型，数据库表模型
- 删除文件数据源：允许用户删除文件数据源
- 删除表单：允许用户删除表单
- 数据源管理，只有**项目**>**数据**>**数据源**有此类操作权限
- 更新数据：允许用户对物理表的数据进行修改
- 修改表结构：允许用户修改表结构、以及删除表
- 导入数据：允许用户导入数据
- 导出数据：允许用户导出数据
- 数据查询：允许用户查询数据
- 数据删除：允许用户删除数据
- 清空表数据：允许用户清空表数据
- 删除表：允许用户删除表
---
url: "https://docs.succapp.com/v5/guide/permission/grant/public-anonymous.md"
htmlUrl: "https://docs.succapp.com/v5/permission/anonymous-and-public"
title: "public目录和匿名用户"
---
---
order: 3
---
# public目录和匿名用户
系统中常会有一些公开资源开放给所有人看，比如：登录、账号注册、密码重置、问卷调查等。SuccBI提供了两种开放资源方式：
\[\[toc]]
## public 目录{#public}
SuccBI定义在项目下级目录`public`（比如：`/DEMO/public`）和应用下级目录`public`（比如：`/DEMO/app/demo.app/public`）下的资源为公开资源。
1. 任何用户（无论是登录了还是没登录）都可以查看这些资源。
2. 这个目录不能被分配权限，也就不能限制资源展示数据的范围。所以在编辑资源的时候就需要控制好数据范围，避免泄露重要数据。
3. 只有项目管理员或者应用管理员才能修改或添加资源。
:::tip
**public目录**提供了比较简单的开放资源管理，仅要求放到public目录下，但也无法做更细致的权限控制，适用于存放分类单一并且不需要细致把控的资源。
:::
## 匿名用户{#anonymous}
匿名用户本质上是未登录的用户在访问SuccBI系统时，系统给加上的一样身份定义。特点有：
1. 可被分配权限，并且可以限定访问的数据范围。针对用户组名为`anonymous`的用户分配的权限，将被作用到匿名用户上，[权限分配参考](../groups.md#assign-permissions)。
2. 在SuccBI系统中会认为是已登录状态，在[自定义脚本](../../dev/script/backend/README.md)中进行登录判断的时候需要注意这一点。
3. 在没有权限访问系统首页的时候，会跟正常登录用户一样，根据已经拥有的权限去定位到有权限访问的位置。
:::tip
1. **匿名用户**提供更为开放的管理方式，适用于对公开资源展示有细致把控的情况。
2. 在设置系统首页的表达式中可以通过`$user.anonymous`来判断是不是使用匿名用户登录的。
3. 系统默认关闭匿名用户功能，打开设置请参考：**系统设置**>**安全**>**安全设置**>**登录安全**>**用户登录**>**[匿名用户](../../sys-settings/security/securityconf.md#login-user)**。
:::
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/README.md"
htmlUrl: "https://docs.succapp.com/v5/permissiom/faq"
title: "权限管理常见问题列表"
---
---
order: 6
navTitle: 常见问题
---
# 权限管理常见问题列表
!!!children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/如何导入第三方系统的用户表和部门表.md"
htmlUrl: "https://docs.succapp.com/v5/howto/e36b4f73"
title: "如何导入第三方系统的用户表和部门表"
---
---
order: 1
---
# 如何导入第三方系统的用户表和部门表
很多时候需要将第三方系统的用户、部门等信息同步到SuccBI系统中，SuccBI支持实时连接和导入两种方式进行同步。本文主要介绍SuccBI部署完成后，如何通过**数据加工**的方式将第三方用户和部门信息导入到系统中。
## 实现思路{#ideas}
1. 导入之前，需要先连接第三方用户和部门表，系统支持[上传数据文件](../../data-connect/README.md#connect-database)和添加[第三方数据源](../../data-connect/README.md#connect-database)两种方式连接第三方用户和部门表。
2. 连接第三方用户和部门表后，可以使用数据加工将[第三方系统](#tri-synchronize)、[SuccezBI3.14](#ci-synchronize)以及[SuccBI](#bi-synchronize)中的用户和部门信息导入到系统中，提取后即可将数据进行同步。
3. SuccBI也支持对第三方用户密码的导入或重置，只需将明文密码按照指定规则加密再导入到用户表的`password`字段，具体可参考[如何加密用户密码](#encrypt-user)。
4. 若需要将第三方用户和部门数据定时更新到SuccBI中，也可以通过[计划调度](../../schedule/README.md)对数据加工进行定时提取，实现用户和部门数据的同步。
:::tip 提示
导入第三方系统的用户表和部门表前，需要先对SuccBI中的[szsys\_4\_users](../../dev/sys-tables/README.md#users)和[szsys\_4\_depts](../../dev/sys-tables/README.md#depts)表进行备份。
:::
## 连接第三方用户表和部门表{#import-tables}
连接第三方用户表和部门表有两种方式：
1. 进入**项目**>**数据**>**数据源**>**文件数据源**，点击[上传数据文件](../../data-connect/README.md#upload-data-file)，将用户和部门文件上传到SuccBI中进行连接。
2. 进入**项目**>**数据**>**新建**>**数据源连接**，添加[第三方数据源](../../data-connect/README.md#connect-database)，然后连接数据库中的用户表和部门表进行数据加工。
## 与SuccBI用户表和部门表进行字段映射{#field-mapping}
第三方系统和SuccezBI3.14通过数据加工导入用户表和部门表时，需要与SuccBI系统用户表和部门表进行字段映射，SuccBI也支持在提取时选择目标表字段进行映射。用户表和部门表的常用映射字段如下所示：
- [用户表常用字段](#user-common)
- [部门表常用字段](#department-common)
### 添加字段映射{#add-mapping}
数据加工添加字段映射具体步骤如下：
1. 新建数据加工，添加`模型输出`节点，在**数据加工**>**模型输出**>**模型属性**的`提取表`属性中选择目标数据库表。
2. 将`模型输出`节点切换为**字段列表**栏，在`物理字段名`中选择目标数据库表的字段与原表字段进行映射。
3. 点击**保存**按钮保存数据加工，并点击**提取数据**执行提取。
### 用户表常用字段{#user-common}
下面是用户表常用字段，用户表详细信息可参考[这里](../../dev/sys-tables/README.md#users)。
|字段名| 主键| 字段类型| 字段描述| 说明|
|:------| :------| :------| :------| :------|
|USER\_ID| 是| VARCHAR(32)| ID| 外部用户表主键，创建用户时默认与用户名相同|
|USER\_NUMBER| | VARCHAR(32)| 用户名| 用于登录，具有唯一性约束|
|USER\_NAME| | VARCHAR(128)| 姓名| |
|NICKNAME| | VARCHAR(128)| 昵称| |
|DEPT\_ID| | VARCHAR(64)| 所属部门| |
|ORDER\_ID| | VARCHAR(64)| 排序ID| |
|PASSWORD| | VARCHAR(128)| 密码密文| 加盐加密，默认使用`sha1`算法加密|
|SALT| | VARCHAR(16)| 盐| |
|PHONE| | VARCHAR(16)| 移动电话| 可用于登录|
|EMAIL| | VARCHAR(128)| 邮件地址| 可用于登录|
|ENABLED| | NUMBER(1)| 是否启用| 1启用，0禁用|
### 部门表常用字段{#department-common}
下面部门表常用字段，部门表详细信息可参考[这里](../../dev/sys-tables/README.md#depts)。
|字段名| 主键| 字段类型| 字段描述| 说明|
|:------| :------| :------| :------| :------|
|DEPT\_ID|是 | VARCHAR(64) | ID | 部门表主键，创建部门时默认与部门编号相同，创建后不可再修改 |
| DEPT\_NUMBER | | VARCHAR(64) | 部门编号 | 部门的业务主键，具有唯一性约束 |
| DEPT\_NAME | | VARCHAR(256) | 部门名称 | |
| PARENT\_ID | | VARCHAR(64) | 父部门ID | |
## 如何加密用户密码{#encrypt-user}
第三方系统和SuccezBI3.14导入用户密码到`PASSWORD`字段中时，需要对密码进行加密，SuccBI在[用户表](../../dev/sys-tables/README.md#users)中设置了`salt`字段专门用于密码加密，用户可在[导入用户表](#tri-users)时使用列加工进行加密拼接，加密拼接方式为`sha1(明文密码字段+[盐])`，默认加密算法为[sha1](../../exp/func/string/SHA1.md)。
:::tip 提示
若无法获取用户明文密码，也可对密码进行重置，加密拼接方式为`sha1(重置后的密码+[盐])`。
:::
## 导入另一个SuccBI系统的用户和部门表{#bi-synchronize}
导入另一个SuccBI系统的用户和部门表较为简单，只需新建数据加工，并将源系统的数据提取到目标系统的用户表和部门表。
### 同步用户表{#bi-users}
同步其他SuccBI系统的用户表步骤如下：
1. 进入**数据**模块，点击**新建**>**数据加工**新建数据模型。
2. 将源系统的用户表拖入数据模型中，并添加添加`模型输出`组件。
3. 将`模型输出`组件切换到**模型属性**列表，主键选择`USER_ID`，目标数据库表选择`szsys_4_users`，提取方式选择`按主键追加`，并勾选`更新已有数据`。修改完毕后保存模型并提取数据。
4. 最后点击**保存**按钮保存数据加工，并点击**提取数据**执行提取。
### 同步部门表{#bi-depts}
部门表的同步与用户表基本相同，具体步骤如下：
1. 进入**数据**模块，点击**新建**>**数据加工**新建数据模型。
2. 将源系统的用户表拖入数据模型中，并添加添加`模型输出`组件。
3. 将`模型输出`组件切换到**模型属性**列表，主键选择`DEPT_ID`，提取表选择`szsys_4_depts`，提取方式选择`按主键追加`，并勾选`更新已有数据`。修改完毕后保存模型并提取数据。
4. 最后点击**保存**按钮保存数据加工，并点击**提取数据**执行提取。
## 导入第三方系统的的用户表和部门表{#tri-synchronize}
### 导入第三方系统的用户表{#tri-users}
导入第三方系统的用户表步骤如下：
1. 进入**数据**模块，点击**新建**>**数据加工**新建数据模型，将第三方系统的用户表拖入数据模型中进行数据加工。
2. 在数据加工中添加`列加工`组件，新增`用户名`字段，字段与用户代码相同，并根据[加密用户密码](#encrypt-user)生成`密文密码`，然后点击`选择字段`按钮，并对需要同步的用户数据进行筛选。
3. 添加`模型输出`组件，切换到**模型属性**配置提取信息，主键选择`USER_ID`，目标数据库表选择`szsys_4_users`，提取方式选择`按主键追加`，并勾选`更新已有数据`。
4. 在`模型输出`组件中切换到**字段列表**，并在`物理字段名`中根据[用户表常用字段](#user-common)设置[字段映射](#add-mapping)。
5. 最后点击**保存**按钮保存数据加工，并点击**提取数据**执行提取。
### 导入第三方系统的部门表{#tri-depts}
导入第三方系统的部门表步骤如下：
1. 进入**数据**模块，点击**新建**>**数据加工**新建数据模型，将第三方系统的部门表表拖入数据模型中进行数据加工。
2. 添加`列加工`组件，并新增`部门编号`字段，字段一般与部门ID相同，然后点击`选择字段`按钮，筛选需要同步的字段信息。
3. 添加`模型输出`组件，切换到**树形结构**属性栏新建父子层次，父字段选择`上级机构`，子字段选择`部门编号`，点击`自动创建层次字段`后，系统会自动生成部门层次信息。
4. 将`模型输出`组件切换到**模型属性**列表，主键选择`DEPT_ID`，提取表选择`szsys_4_depts`，提取方式选择`按主键追加`，并勾选`更新已有数据`。
5. 在`模型输出`组件中切换到**字段列表**，将`物理字段名`根据[部门表常用字段](#department-common)进行与第三方部门表字段进行[字段映射](#add-mapping)。
6. 最后点击**保存**按钮保存数据加工，并点击**提取数据**执行提取。
## 导入老版本(3.1.4)的用户和部门表{#ci-synchronize}
导入SuccezBI3.1.4的用户表和部门表与导入第三方用户和部门表步骤基本相同，具体可参考[导入第三方系统的的用户表和部门表](#ci-system)。
## 定时同步用户表和部门表
使用数据库表进行数据加工导入第三方用户表和部门表时，若需要定时更新用户和部门信息，可以设置计划任务实现用户和部门信息的定时同步。具体可参考[调度管理](../../schedule/README.md)。
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/如何禁用元数据目录访问权限.md"
htmlUrl: "https://docs.succapp.com/v5/howto/e7aa72b4"
title: "如何禁用元数据目录访问权限"
---
---
order: 2
---
# 如何禁用元数据目录访问权限
## 需求描述{#description}
出于安全考虑，很多时候项目对终端用户只需要展示结果页面，不允许用户通过URL访问其管理界面，此时就需要对该部分用户禁用元数据目录访问权限。
## 设置方法{#setup}
禁用元数据目录访问权限只需要在**项目设置**>**基本**处勾选`限制访问默认管理界面`即可，更多详细操作可查看文档[项目基本设置](../../project-manage/basic-setting.md#restrict-metamgr)。
:::tip
勾选`限制访问默认管理界面`后，只有当用户拥有项目完整的管理权限才可以重新访问元数据目录。
:::
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/如何设置用户只能看到所属部门的数据.md"
htmlUrl: "https://docs.succapp.com/v5/howto/e7aa7660"
title: "如何设置用户只能看到所属部门的数据"
---
---
order: 4
---
# 如何设置用户只能看到所属部门的数据
本文主要介绍，如何通过权限去设置各部门用户只能查看本部门的数据，比如财务部用户只能查看财务部的数据，销售部用户只能查看销售部的数据。
## 设置思路{#principle}
设置用户只能查看本部门的数据，需要遵循如下几个要点：
1. 确定业务表中，由哪个字段限定数据范围。例如：一张销售明细表，【门店区域】字段，标识了每一条销售数据是属于哪个销售区域的。那【门店区域】为`华中`的数据，只能由`华中`区域范围的用户可见
2. 确定部门表中，有字段标识当前登录用户数据范围。例如：通过用户部门表中的【所属区域】字段，是能确定当前登录用户所在区域是`华中`还是`华南`
3. 业务表与部门表中的区域关联了同一张维表。例如【行政区划】表，这样业务表中的【门店区域】字段与部门表中的【所属区域】就可以对应上
通过以上几点结合，我们就可以在**项目设置**>**数据范围**处[引用数据范围维表](../../project-manage/data-permission-setting.md#dim-range)，[设置数据范围](../../project-manage/data-permission-setting.md#data-range)，最后在权限模块下为用户或用户组[分配权限](../grant/README.md)，达到用户所在部门的【所属区域】字段为`华中`，则只能看到销售明细表中【门店区域】为华中的数据。具体步骤可参考[设置方法](#setup)。
## 设置方法{#setup}
我们以湖北分公司这个部门为例，限定其部门的用户只能查看湖北省的数据。通过上面的思路分析，操作步骤如下：
1. 检查业务表中的数据范围字段：业务表中存在`区域编码`字段，关联了`行政区划（父子）`表
2. 设置部门数据范围：在**权限**>**部门**模块中的**所属地**属性设置本部门的数据范围为`湖北省`，若没有所需属性可[添加新属性](./如何为系统用户添加新的属性.md)。
**所属地**属性在部门表中的存储格式为行政区划，即当前结果存储为`420000`，此时，业务表与部门表的范围就有了一致性
3. [引入数据范围维表](../../project-manage/data-permission-setting.md#dim-range)：根据需要引入可以限制数据范围的维表，如：`行政区划（父子）`，设置好其代号为`XZQH`、简要描述为`行政区划`
4. [设置常用数据范围](../../project-manage/data-permission-setting.md#data-range)：在常用数据范围处添加数据范围。具体属性设置如下
- 名称：该数据范围的名称，如`当前用户行政区划`
- 用户组：可使用该数据范围的用户组，如`领导组`
- 数据范围：设置想要限制的数据范围，如设置表达式`行政区划 = DEPT_PROPERTY('districtId')`
5. [设置默认数据范围](../../project-manage/data-permission-setting.md#default-range)：在默认数据范围的下拉框处选择相应的数据范围即可。如`当前用户行政区划`
6. [权限分配](../grant/README.md)：给用户或者用户组分配权限时，选择我们设置好的数据范围
::: tip 数据范围小贴士
1. `DEPT_PROPERTY('districtId')`用于获取当前用户所在部门的所属地，详情可查看[DEPT\_PROPERTY文档](../../exp/func/others/DEPT_PROPERTY.md)。
2. 在项目设置处添加的常用数据范围只是预设置，还需要在权限处为用户或用户组去设置数据范围才能生效。
:::
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/如何为系统用户添加新的属性.md"
htmlUrl: "https://docs.succapp.com/v5/howto/adf61a38"
title: "如何为系统用户添加新的属性"
---
---
order: 6
---
# 如何为系统用户添加新的属性
## 需求描述{#description}
系统内置的用户表包含了用户ID、用户名称、部门、手机号等内容（见[USERS-用户表](../../dev/sys-tables/README.md#users)），在某些情况下，可能需要更多的字段去记录业务上用户的某些属性，如`管辖区域`、`权限级次`等等，这就需要为用户添加新的属性了。
## 设置方法{#setup}
SuccBI系统中所有用户的基本信息都在**用户表**中记录，拥有**系统数据**权限的用户可以在**系统数据**项目>**数据模块**>**sec文件夹**中访问`USERS`表，想要为**系统用户**添加新的属性，需要在`USERS`表中进行新增属性字段，若希望在新增用户时就能对该属性进行设置，还可以[修改用户表单](#modify)。
### 修改用户表单{#modify}
具有**系统数据**项目下**应用**模块的APP编辑权限的用户，可以修改**权限**模块下新增/修改用户的表单。编辑**security**应用，找到**users.fapp**资源，即可在用户表单中修改输入项，配置新的用户属性在表单中显示出来，表单的使用方法可以参考[表单](../../ci/design-fapp/settings/README.md)。
:::tip
新增部门、机构等属性与新增用户属性的步骤基本一致。
:::
## 新增的用户属性如何使用{#how-to-use}
新增后的用户属性，与其他属性一样，可以通过`[用户].[管辖区域]`来获取到当前登录用户的管辖区域信息，其中`[用户].`后面的内容是[字段名称](../../data-gov/model/README.md#model-field)，获取当前登录用户信息的表达式具体介绍可参考文档[$user](../../exp/var/$user.md)。
---
url: "https://docs.succapp.com/v5/guide/permission/FAQ/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/permissiom/errcode"
title: "权限管理错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 权限管理错误提示排查
---
url: "https://docs.succapp.com/v5/guide/project-manage/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage"
title: "项目管理"
---
---
order: 16
navTitle: 项目管理
indexTitle: 概述
---
# 项目管理
项目管理用于创建和维护 SuccApp 中的元数据项目。界面中的“项目”就是元数据项目，用来组织和管理一组互相关联的数据模型、数据加工、调度、页面、程序流、应用、报表、门户入口和配套资源。
一个元数据项目通常用于交付一个客户、一个组织或一套相互关联的业务应用。即使不同业务应用归属不同部门，只要它们共享底层基础数据、统一门户入口、公共模型或项目级配置，也通常放在同一个项目中，再在项目内部按应用、业务板块和目录划分。
新建项目需要谨慎。通常只有两套内容从数据模型、加工、调度到页面、程序流、应用和发布边界都需要完整隔离时，才考虑拆成多个项目。更多底层目录和文件规范见[元数据项目](../dev/meta/rules/project.md)。
!!! children !!!
---
url: "https://docs.succapp.com/v5/guide/project-manage/new-project.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/new-project"
title: "新建项目"
---
---
order: 1
---
# 新建项目
项目用于组织和管理一组互相关联的数据模型、数据加工、调度、页面、程序流、应用、报表、门户入口和配套资源。通常一个客户或一个组织使用一个项目即可；不同部门的业务应用如果共享基础数据、统一门户入口、公共模型或项目级配置，也建议放在同一个项目中，再在项目内部按应用和业务板块划分。
只有当两套内容从数据模型、加工、调度到页面、程序流、应用和发布边界都需要完整隔离时，才建议新建多个项目。确认需要新建后，按下面步骤操作。
1. 在项目列表页面点击**新建项目**。
2. 在弹出框中填写**项目名称**。项目名称会用在 URL 中，且**新建后不可修改**，建议使用简短的字母、数字、下划线和点号，不能使用中文或其他特殊符号，例如 `demo_test`。
3. 填写**描述**，用于描述该项目的业务意义，例如**测试 demo 功能**。
4. 点击**确定**，即可成功创建一个项目。
::: tip
1. 只有拥有新建项目权限的用户才能新建项目
2. 项目名称不能重复
3. DEMO 体验版自带 [系统元数据项目](../dev/meta/rules/project.md#system-meta-project) 和 DEMO 项目；安装部署 war 包时，是否部署 DEMO 项目可选择，系统默认选择部署。
:::
---
url: "https://docs.succapp.com/v5/guide/project-manage/basic-setting.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/basic-settings"
title: "项目基本设置"
---
---
order: 2
---
# 项目基本设置
用于设置项目的基本信息，比如项目描述、logo和缩略图等。
点击**demo\_test**项目进入项目详情页面，再点击**省略号**>**项目设置**>**基本**，自定义项目的基本属性。
## 基本属性介绍{#basic}
| 功能 | 用途 |
| :---------| :-------- |
| 名称 | 项目创建后无法修改 |
| 描述 | 创建该项目时所填写的业务描述，可以进行修改 |
| 限制访问默认管理界面 | 勾选后，无管理权限的用户无法进入数据、分析、表单等系统所有的元数据页面 |
| logo | 系统提供默认logo，用户可点击**上传**，自定义项目的logo，见[logo](#logo) |
| 缩略图 | 系统提供默认缩略图，用户可点击**上传**，自定义项目的缩略图，见[缩略图](#缩略图)|
### logo{#logo}
项目logo会显示在页面左上角，logo的样式原则上不做限制，但建议采用16:9比例，且无背景填充的图片。
### 缩略图{#thumbnail}
缩略图会显示在项目列表页面，且需使用16：9比例的图片。
### 限制访问默认管理界面{#restrict-metamgr}
系统自带有管理元数据资源的管理界面即下图所展示的界面：
在设置了项目中勾选了`限制访问默认管理界面`后，只有当用户被某个项目的管理权限（注意是管理权限），用户才有权限进入管理界面，示例权限分配如下：
### 自动预热{#precompile}
勾选了`自动预热`之后，系统升级并重新启动时自动预加载、预编译此项目的资源，以加速用户首次访问系统的性能。
---
url: "https://docs.succapp.com/v5/guide/project-manage/data-mgr-setting.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/data-mgr-settings"
title: "项目数据管理设置"
---
---
order: 3
---
# 项目数据管理设置
创建一个项目时，通常需要先在项目管理设置中添加可用的数据源、设置项目的默认数据库，除此之外，还可以在这里设置模型与物理表之间描述信息的同步策略、执行查询时NULL值的排序规则等。主要分为[数据源](#source)、[模型](#model)、[权限](#power)、[查询](#query)、[性能优化](#performance)五个方面的设置。
## 数据源{#source}
### 允许使用数据源{#data-sources}
添加允许在项目内部使用的数据源，项目内的模型、数据加工、应用等，只能使用此处添加的数据源。创建项目时默认只有default数据源，如果需要接入新的数据源，可通过以下两种方式添加：
1. 在系统全局的[数据源管理](../data-connect/datasources.md)中新建数据源，再在此处添加新建的数据源。
2. 直接在项目内[新建数据源](/getstarted/bi/data-connect/#_1、数据库连接)，项目内创建的数据源会自动添加到`允许使用数据源`中。
### 默认数据库{#default}
默认数据库是系统默认用于存储和管理数据仓库数据、用户业务应用数据的数据库。新建的数据加工、报表填报应用中的数据默认存储到默认数据库。
:::tip
只有可写的数据源才能作为默认数据源，可在[数据库连接属性](../data-connect/datasources.md#properties-setting)中进行设置。
:::
### 默认Elasticsearch数据源{#default-es-datasource}
默认Elasticsearch数据源作为新建Elasticsearch模型时的默认存储库。该选项只能指定[Elasticsearch类型](../data-connect/datasources.md#create-datasource)的数据源，设置后，新建Elasticsearch模型后方便保存时自动生成索引。
## 模型{#model}
### 同步模型描述{#description}
默认勾选，保存模型时将模型描述定义为目标数据库表的备注。
模型的描述通常作为模型的业务解释，若全部同步到数据库表上，其他直连数据库的人也能看到，可能会导致项目模型的业务设计泄露。如果项目对业务设计的安全性要求较高，可以取消勾选。
### 同步模型字段描述{#field-description}
默认勾选，保存模型时将模型字段的描述作为目标数据库表字段的备注。
模型字段的描述通常是模型字段的业务解释，若全部同步到数据库表字段上，其他直连数据库的人也可以看到，这样会导致项目模型的业务设计泄露。若项目对业务设计的安全性要求较高，可以取消勾选。
### 读取物理字段注释{#physical-comments}
默认勾选，导入模型时将数据库表字段的备注信息作为模型表字段的名称，数据库表作为节点拖入到加工时，数据库表字段的备注信息会作为节点字段的名称。
使用SuccBI建模时，自动读取物理字段注释，能很好地帮助使用者理解模型的结构和数据。通常是需要勾选的，但是有些数据库读取数据库表的元数据信息很慢，比如vertica，为了避免影响使用时的性能，可以取消勾选。
### 读取数据库表注释{#database-comments}
默认勾选，导入模型时将数据库表的备注信息作为模型表的名称，数据库表作为节点拖入到加工时，数据库表的备注会作为节点的名称。
使用SuccBI建模时，自动读取数据库表注释，能很好地帮助使用者理解模型的用途。若在项目中使用的数据库读取数据库表的元数据信息很慢，比如vertica，为了避免影响使用时的性能，可以取消勾选。
### 隐藏字段属性列{#field-property}
选择需要隐藏的字段属性，在项目内的模型中查看[字段列表](../data-gov/model/README.md#model-field)时，勾选的字段属性不会显示。
项目会默认显示所有的字段属性，在模型的[字段列表](../data-gov/model/README.md#model-field)中显示时比较冗余，列宽容易挤压，可以根据项目建设的用途隐藏掉不常用的字段属性，简化字段列表的显示。比如在业务系统的建设中，通常不需要数据元、取数公式、取数条件等数据治理项目常用的属性，可在此处将属性列隐藏。
### 记录实时查询总行数{#record}
勾选后，项目创建或保存[实时查询的数据加工](../data-process/data-output/README.md#virtual)时会在[数据表信息表](../dev/sys-tables/README.md#meta-tables)中记录加工总行数，不勾选只会记录[落地数据加工](../data-process/data-output/README.md#materialized)的总行数。默认是不勾选的，若项目希望通过[数据表信息表](../dev/sys-tables/README.md#meta-tables)中记录的数据在前端展示数据模型的总行数，可以勾选此项。
## 权限{#power}
### 启用“我的数据”{#mydata}
默认不启用，启用后，会在**数据**>**模型**中增加**我的模型**目录，用户可在**我的模型**中管理自己的私有数据和数据模型。
在一些企业或机构中，有些业务人员也需要独立地进行数据处理和分析，他们创建的模型是私有的或临时的，不应该存放在企业级的公共数据仓库中，比如税务部门下的税务人员也会自助分析偷漏税企业的情况，这种场景下就可以启用**我的数据**来管理自己的私有模型和数据。
### 启用“应用数据”{#application-data}
默认勾选，勾选后，会在**数据**>**模型**中增加**应用模型**目录，用户可在**应用模型**中管理报表填报应用和应用模块产生的数据。
报表填报应用或应用模块录入的数据，有一些是项目的业务数据，若项目对业务数据的安全性要求较高，不希望用户在数据模块中查看这些数据，如核酸检测的录入信息，可以取消勾选。
### 允许访问系统数据{#system-data}
默认不勾选，勾选后，会在**数据**>**模型**中增加**系统数据**目录，用户可在**系统数据**中查看日志数据、用户数据等系统数据。
为了保证系统的正常运行，防止用户修改系统数据后系统运行故障，通常此项是不勾选的，若用户希望在项目中对日志数据、用户数据等系统数据进行加工，通过加工后的数据在项目中展示当前系统运行情况，可以勾选此项。
### 允许上传数据文件{#uploading-data}
默认勾选，勾选允许上传数据文件后，会在**数据**>**数据源**>**文件数据源**中增加**上传数据文件**选项，用户可点击此项从本地上传数据文件到系统进行数据加工。若需要上传的文件较大，可在**系统设置**>**安全设置**>**阈值设置**>[文件上传](../sys-settings/security/securityconf.md#upload-file-restrictions)设置上传文件大小阈值。
一些项目出于对数据安全和规范的考虑，只允许用户使用项目内的数据进行数据加工，此时可以取消勾选，将上传数据文件选项隐藏，使用户无法上传本地数据到项目中。
### 允许访问公共数据{#access-publicdata}
启用允许访问公共数据后，会在**数据**>**模型**增加公共项目目录，用户可通过此目录访问其他公共项目的数据。通常是不启用的，若需要将公共项目的模型复制到当前项目进行加工，或项目的业务流程需要跨项目[设置关联关系](../data-gov/model/model-relations.md#oper-steps)，可以启用此项。
### 本项目作为公共数据项目{#publicdata}
启用后，本项目将作为公共数据项目被已启用[允许访问公共数据](#access-publicdata)的项目访问。为了保证项目内数据的独立性，通常是不启用的，若其他项目需要复制本项目的数据模型进行数据加工，或项目的业务流程需要跨项目[设置关联关系](../data-gov/model/model-relations.md#oper-steps),可以启用此项。
## 查询{#query}
### NULL值计算规则{#null-calculation}
默认不勾选，勾选后，当数据为NULL时，会将NULL值当作0值进行处理。
一些数据加工的计算字段中存在很多空值，这样会导致数据加工中大部分行没有结果，为了使加工结果正常返回，需要将字段中的NULL值转换为0值，此时可以进行勾选来实现0值的转换，使加工正常完成。
### 分母为0计算规则{#denominator-calculation}
默认勾选，勾选分母为0计算规则后，当存在分母为0的数据时，会将数据当做NULL值进行处理。
### NULL值升序排序规则{#ascending}
对模型数据进行升序排列时，值为null的数据的排序规则，可设置为`排在最前`、`排在最后`或`数据库默认规则`，默认排在最前。
### NULL值降序排序规则{#descending}
对模型数据进行降序排列时，值为null的数据的排序规则，可设置为`排在最前`、`排在最后`或`数据库默认规则`，默认排在最后。
### Oracle并行查询{#parallel-query}
Oracle数据源执行查询的并行数，未设置时默认为1，即不启用并行查询。若项目将Oracle中的数据用于多维分析，可在这里设置并行数以提高计算效率。
### Oracle是否使用join语法{#join}
默认勾选，勾选后，Oracle数据库表进行关联时使用`join语法`连接，不勾选则使用`(+)语法`连接。通常使用`join语法`进行连接，当Oracle进行多表关联时，若字段数超过1000，建议取消勾选，使用`(+)语法`进行连接以获得更好的性能。
## 性能优化{#performance}
### 默认查询预览数据{#default-query}
默认勾选，勾选后，数据加工[预览数据](../data-process/optimization/README.md#debugdatasets)时只查询[预览数据默认行数](#default-data)中指定行数的数据，以加快预览速度。
项目中数据加工里数据的数据量一般较大，预览全部数据通常较慢，一般不建议取消勾选，若项目中进行数据加工的数据量较小，且用户需要在预览数据时查看全部数据，可以取消勾选。
### 预览数据默认行数{#default-data}
启用[默认查询预览数据](#default-query)后生效，在数据加工中添加节点时，新节点预览数据的预览行数，默认预览10000行。
---
url: "https://docs.succapp.com/v5/guide/project-manage/wfl-setting.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/wfl-settings"
title: "项目工作流设置"
---
---
order: 5
navTitle: 项目工作流设置
---
# 项目工作流设置
在项目设置中提供了该项目下的所有工作流的通用配置，配置属性如下图所示：
- **截止时间**：可选择系统中类型为工作流的[计划任务](../schedule/README.md)，系统会按照所选计划的执行频度去判断当前项目内所有已发布的工作流程，按照流程或流程任务节点上设置的截止时间和超时自动处理规则对超时任务进行自动处理，如自动通过或自动退回。
---
url: "https://docs.succapp.com/v5/guide/project-manage/data-permission-setting.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/data-permission-settings"
title: "项目数据范围设置"
---
---
order: 6
---
# 项目数据范围设置
项目数据范围设置用来配置不同权限用户访问项目时能看到的模型数据范围的策略，配合[数据级次权限](../permission/grant/datarange.md)一起使用，不同用户登录系统时可以自动过滤数据，保证数据在企业内部不同部门或分公司之间的相互独立性和安全性。
## 数据范围维表{#dim-range}
一个项目中是存在多个[维表](../data-gov/GLOSSARY.md#dimension-table)的，只有部分与**用户**的某种属性存在关联的维表才会设为**数据范围维表**，比如`行政区划维表`（用来表示模型表数据来源地区，和用户所属地之间存在关系）和`机构表`（用来表示模型表数据来源机构，和用户所在机构存在关系）等等，在一个项目中可以设置多个数据范围维表以支持在同一个[常用数据范围](#data-range)中添加多个条件。
如使用`行政区划`维表与[模型表](../data-gov/GLOSSARY.md#data-model)的地区字段进行关联，此时可以定义`行政区划`维表为**数据范围维表**，当满足[数据范围条件](#data-range)所设置地区范围与用户所属地区相同时，只保留符合条件的数据，需要设置以下几个内容：
- **代号**：表示维表的标识符，也是系统存储这条**数据范围维表**信息的标识符，需要确保该标识符不会轻易被修改，若被修改可能会影响已有的权限设置，如`XZQH`
- **简要概述**：用来描述该维表的文字，在[设置数据范围](#data-range)中选择时展示的是这里设置的内容，如`行政区划（服饰数据）`
- **维表**：代表数据层级的维表，下拉列表中包含了这个项目中可查看到的所有模型表信息
## 常用数据范围{#data-range}
在设置**常用数据范围**后，给用户或用户组分配权限时可以直接选用，如下图所示，详情可见[数据级次权限](../permission/grant/datarange.md)。
在设置常用数据范围时，需要说明的是常用数据范围设定有**用户组**，只有**分配权限的用户至少属于其中一个用户组**或者**管理员**才能在权限数据范围分配时使用。
- **名称**：用来表示定义的数据范围，最好取带有业务意义的名称，即方便与其他数据范围进行区分，又可以快速了解该数据范围的作用
- **用户组**：用于限定哪些用户可以使用这项数据范围，即除了“管理员”之外的用户，必须属于这里选定的用户组才能为其他用户分配该项数据范围
- **数据范围**：在第一个下拉框中选择[数据范围维表](#dim-range)中设置的内容，再设置其具体的范围条件，一个条件仅支持对一个维表作出范围限定，在设置了多个维表的情况下，可支持设置多个条件，多个条件之间是“AND”关系，如满足用户查看“华中地区分公司下”下“湖北省销售情况”的数据（需要设置两个数据范围维表，一个是机构维表，一个是行政区划维表）。设置时有以下两种情况：
- **添加静态的数据范围**：为用户分配具体的数据范围，可选择多个条件，如为用户指定其可查看的数据为湖北省数据，需要在下拉框中选择**选择维项**，随后在弹出的对话框中选择`湖北省`
- **添加动态的数据范围**：使用表达式获取当前登录用户的某些信息，并以此作为条件动态的展示其权限范围内的数据，如使用表达式`DEPT_PROPERTY('districtID')`获取当前登录用户的所属地（用户所属部门中包含了部门所在地，通过获取部门所在地得到用户所属地区），并使在[数据范围维表](#dim-range)中添加的`行政区划（服饰数据）`等于该用户的所属地，即可得到仅属于其所属地区的数据
在同一个**常用数据范围**中可以添加多个**数据范围**，与上述添加**数据范围条件**不同的是，一个数据范围的多个条件是“AND”关系，一个常用数据范围里添加的多个**数据范围**是“OR”的关系，即满足其中一个数据范围即可，这使得用户可以访问更多的数据。
## 设置默认数据范围{#default-range}
给用户或用户组设置权限后，数据范围默认使用的是**默认数据范围**，如下图，设置权限后数据范围即**默认(当前用户行政区划)**，详情可见[数据级次权限](../permission/grant/datarange.md)。
若绝大多数用户或用户组的数据范围是**默认**，并且希望批量修改其**数据范围**时，可以在这里更改**默认数据范围**，再为特定的用户或用户组选择其他**数据范围**，该属性默认为**全部**，即访问所有数据。
---
url: "https://docs.succapp.com/v5/guide/project-manage/delete-project.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/delete-project"
title: "删除项目"
---
---
order: 7
---
# 删除项目
::: danger 警告！！！
项目删除后，项目中的所有信息也会被从系统中彻底删除，且**无法恢复**！请谨慎操作！
:::
只有拥有删除项目权限的用户才能删除项目，方法如下：
1. 进入项目详情页面，点击**省略号**>**项目设置**>**删除项目**
2. 输入**项目名称**并勾选**我已了解风险**勾选框
3. 点击**删除项目及其所有数据**即可删除
---
url: "https://docs.succapp.com/v5/guide/project-manage/file-mgr.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/file-mgr"
title: "file-mgr"
---
---
order: 8
navTitle: 文件管理
---
# 文件管理
右键选中的资源文件，可对资源文件进行操作管理，如对资源进行[查看](#check)、[编辑]()、[重命名](#rename)、[导入和导出](#import-export)、[刷新](#refresh)等操作，也可查看当前资源的[基本信息](#basic-information)，元数据文件管理通用操作如下图所示：
## 文件操作{#operate}
可对资源文件进行查看、重命名、移动、导入、导出、收藏等基础操作。
### 查看{#check}
查看文件有两种方式：
1.点击**查看**选项，可全屏展示当前文件的内容，不显示操作工具栏，如下所示：
2.使用URL查看，常规使用文件路径作为URL进行查看，也可以使用文件ID作为URL进行查看。以查看DEMO项目BI模块的大屏`仓库运输数字化大屏`为例：
- **使用文件路径作为URL进行查看**
`仓库运输数字化大屏`的文件路径为`https://demo.succbi.com/v5/DEMO/ana/dash/viz/Warehouse%20Logistics.dash`，在浏览器输入此路径可以直接查看。
- **使用文件ID作为URL进行查看**
- **使用背景**：在实现从第三方平台跳转至系统特定页面的过程中，若采用文件路径直接作为URL进行跳转，那么一旦目标文件被重命名，就需要及时更新第三方平台上的跳转链接。若未能及时作出调整，系统将无法识别已变更的文件路径，导致跳转失败。
此时更为稳健的做法是在跳转链接中采用文件的唯一标识符（即文件ID）而非其物理路径。这样一来，即便文件在系统中经历了重命名或位置变动，跳转链接也能持续有效，无需频繁修改第三方平台的配置。
- **配置方法**：将查看链接的URL设置为：域名+上下文+/fid/ID即可自动识别跳转，即便更改文件名也无需再次修改URL。其中ID为目标文件的高级属性，它是文件的唯一ID，在创建文件时自动生成且后续一般不会更改。仓库运输数字化大屏的属性ID为`XYk4pLsxK9KAFBkGSBE61B`，那么可以设置查看的URL为`https://demo.succbi.com/v5/fid/XYk4pLsxK9KAFBkGSBE61B`
- **文件ID**：点击文件的**属性**，在**高级**处的ID即为文件ID
:::tip
特别注意：当希望查看的页面是门户时，不能直接使用.app的文件ID，而是需要使用.tpg的文件ID
:::
### 重命名{#rename}
点击**重命名**，弹出重命名对话框，可修改文件的名称和描述，在数据加工、分析、应用等资源中被引用的文件重命名后，文件能够自动更新重构。
### 移动{#move}
点击**移动到**选项，弹出文件资源所在模块下的目录结构对话框，同时定位当前文件所在目录，选择其他目录，则可以将文件移动到选中目录；也可点击对话框左下角**新建文件夹**按钮，移动到新的目录中。在数据加工、分析、应用等资源中被引用的文件移动位置后，文件能够自动更新重构。
系统也提供了快捷移动文件的操作方法：选中文件，长按鼠标左键拖入到其他目录，会弹出确认对话框，点击确定即可快捷移动文件。
若只在当前目录下拖动文件，可修改文件的顺序。目录下的文件顺序被修改后，右键弹出管理菜单会增加**重置为默认排序**的选项，点击即可还原为最开始的顺序。
:::tip
快捷移动文件中，如果想要放在目录的下级文件夹中，可将文件拖入目录上，停留2s，该目录会自动展开，想要移动到多层目录下，同理使用此方法即可。
:::
### 复制{#copy}
点击**复制到**选项，与移动到一样，弹出文件所在资源模块下的目录结构对话框，可将文件复制到选中目录。
数据中的模型表复制稍有不同，在对话框左下角会多出一个**创建新表**的选项，勾选它，复制模型表的同时会创建一个新的物理表，两者区别如下：
- **直接复制**：和原来的表指向同一个物理表模型
- **勾选创建新表复制**：会创建一个新的物理表模型
- 复制模型数据：勾选创建新表后，会弹出**复制模型数据**的选项，勾选它可以将模型表中的数据复制到新的物理表模型中
### 导入和导出{#import-export}
使用文件的导入和导出功能，可以将文件做备份，避免数据丢失，同时也可以将文件导出后再其他项目中导入，方便少量文件的迁移。
点击**导出**选项，可将文件导出为`scz`文件，导出的文件名称会带上文件的类型，比如导出`柱形图`仪表板，则导出文件名为`柱形图.dash`。
点击**导入**选项，可将刚刚导出的`scz`文件导入到系统的对应模块中，导入时如果文件名称没有同名文件，可直接导入成功，弹出成功提示框；如果有同名文件，则会弹出对话框，选择解决冲突的处理方式：
- **自动重命名**：导入的文件名称将自动重命名，与同名文件共存，重名的表尾部加入后缀\_1，默认为该选项
- **替换同名文件**：导入的文件将替换同名文件，删除已存在的表，最后只保留导入文件
当文件有冲突时，可点击对话框左下角**详细信息**按钮，查看同名文件资源的详细信息。
[数据模块](../data-gov/model/README.md)中导入和导出与其他模块中的导入导出稍有不同，数据表可以导入导出数据表，在导出时可勾选**导出模型关联的数据表**选项，则会将当前模型表的数据表一并导出，如果数据量较大，不建议勾选该选项，推荐使用数据库备份方式进行数据备份或迁移，可查看文档[迁移数据源配置](../devops/upgrade/migrate.md#configuration)。
在导入时一并导入关联的数据表，如果数据表有同名文件，则会弹出对话框，可选择**自动重命名**、**覆盖同名表**、**清空表**三种解决数据表冲突的处理方式，具体可查看文档[导入物理表](../data-connect/dbtable-mgr.md#import)
:::tip
导入文件时，只能将导出的scz文件导入进对应模块中，比如从分析模块中导出的文件，不能导入进数据模块和应用模块。
:::
### 删除{#delete}
点击**删除**选项，会弹出删除确认对话框，在对话框中可以显示该文件被多少资源引用，点击**详细信息**按钮，可查看详细的资源被引用情况，点击路径可打开引用该模型表的资源文件。
### 收藏{#collect}
点击**收藏**选项，可将当前文件放于用户的收藏夹中，收藏可快速找到常用文件。收藏夹的位置位于右上角五角星图标处，点击即可查看收藏的文件。
### 刷新{#refresh}
点击**刷新**选项，可刷新元数据缓存的数据，把最新的数据显示出来。比如A和B两个用户同时修改同一个文件，A已经修改保存，B点击刷新，则可将A修改的内容刷新并同步显示出来，刷新成功后，顶部会出现刷新成功的提示框。
## 文件基本信息{#basic-information}
点击**属性**选项，可以查看文件的基本信息、高级信息，数据模型可查看对应模型信息；除数据模型之外的文件资源，例如仪表板、报表等可查看缩略图信息，具体如下所示：
|数据文件|可视化文件|
|--|--|
|||
- **基本信息**：
- 类型：显示文件的类型，比如模型表为`tbl`、仪表板为`dash`、应用为`app`等
- 路径：文件在当前项目中的路径，如`/DEMO/ana/图表/图形/面积图.dash`，如需要引入当前文件资源路径，可在此处查看该路径
- 版本：记录文件修改的版本，每一次修改保存后，都会记录一次，历史版本管理可查看[元数据历史版本管理](#historic-version)
- 创建：文件的创建时间以及创建用户
- 修改：文件的修改时间以及修改用户
- 描述：文件的描述信息，在新建文件命名或重命名中可设置描述信息
- 标签：只有模型表会显示标签，对文件进行标识，方便管理模型表，在菜单的标签中进行设置
- **高级信息**：
- ID：文件的唯一ID，在创建文件时自动生成
- **缩略图信息**：数据模型没有缩略图信息
- 默认：PC端的缩略图
- 手机：移动端的缩略图
- 上传：系统会自动生成缩略图，点击上传按钮可自定义缩略图
- 重置缩略图：重置为系统默认生成的缩略图
- **模型信息**：只有数据模型有模型信息
- 输出表：模型表的目标数据库表，可查看文档[输出物化的数据表](../data-process/data-output/README.md#materialized)
- 磁盘空间：模型表所占系统的磁盘空间大小
- 调度计划：所在的调度计划名称，调度计划可参考文档[调度管理](../schedule/README.md)
- 提取状态：模型表上一次提取数据的状态，包含在加工界面手动提取以及调度计划提取
- 已提取：提取数据成功，则显示已提取状态
- 未提取：新建的数据加工或对加工做修改并保存，未执行提取数据，则显示未提取
- 取消：提取数据过程中点击取消按钮，则显示取消状态
- 异常：提取数据出现异常导致失败，则显示异常状态，手动提取出现异常可直接弹出异常信息对话框，调度计划中出现异常，可通过调度[日志](../schedule/README.md#log)查看异常信息
- 提取时间：上一次提取数据的时间
- 提取耗时：上一次提取数据所耗费的时间
- 数据期：为模型属性中设置的数据期类型，可查看文档[数据期类型](../data-gov/model/model-settings.md#data-period)
### 文件历史版本管理{#historic-version}
文件每做一次修改保存后，都会记录一次版本，记录历史版本，可以查看文件的修改记录以及还原历史版本。
点击**历史版本**按钮可以弹出历史版本对话框，可以查看版本号、名称、修改时间、修改人以及对历史版本进行编辑、还原、查看代码差异、查看结构差异等操作，版本号为`r0`的为最初版本，版本号后面带有星号`*`的为当前版本：
- **编辑**：点击编辑按钮，可打开新标签页到文件的当前历史版本，可在其基础上重新修改
- **还原**：点击还原，可将最新版本还原到该历史版本，当前版本没有还原按钮
- **差异**：点击差异，可以查看当前历史版本与上一次历史版本的代码差异，通过代码的差异可以看出做了什么修改，最初版本没有差异按钮
- **结构差异**：只有模型表有该选项，点击结构差异，可以查看当前历史版本与上一次历史版本的结构差异，如移除字段或者修改字段类型，最初版本没有结构差异按钮
- **刷新**：点击左上角刷新按钮，可刷新历史版本数据，勾选右上角的**自动刷新**选项，系统可自动刷新历史版本
当历史版本数大于0时，会出现**重置为系统默认**按钮，WAR包里会自动带上系统项目的元数据，系统元数据被修改后，可通过点击该按钮将数据重置为包中的初始数据，新建的项目，在war包里没有对应元数据，不能进行重置操作。
---
url: "https://docs.succapp.com/v5/guide/project-manage/display-format.md"
htmlUrl: "https://docs.succapp.com/v5/devops/project-manage/display-format"
title: "display-format"
---
---
order: 8
navTitle: 显示格式
---
# 显示格式
类似Excel的显示格式，用于将数值或日期等数据显示成更易读的格式。常见的显示格式包括：
1. **数字格式化**：可以设置数字的小数位数、千位分隔符、货币符号等，使数字更易读。
2. **百分比格式化**：可以将数据以百分比形式显示，方便比较和分析。
3. **日期和时间格式化**：可以将日期和时间数据按照指定的格式显示，如年-月-日、月/日/年等。
4. **条件格式化**：可以根据数据的特定条件设置不同的显示格式，如0显示为/，以突出显示特定的数据。
## 显示格式分级管理 {#display-format-scene}
根据需求的不同，系统提供页面级别、应用级别、项目级别和系统全局的设置，以满足不同层次和规模的设计需求。
1. **系统全局设置显示格式**：适用于整个系统或平台。这意味着可以在系统的所有项目、页面或应用程序中使用相同的显示格式。例如，企业级的系统中，希望在整个系统中使用相同的显示格式，确保品牌一致性和用户体验的统一性。系统全局的设置显示格式可以让整个系统中统一样式。
2. **项目全局设置显示格式**：适用于特定项目，在项目中的所有页面或应用程序中使用相同的显示格式。例如，系统里建设多个不同业务类型的项目，各项目需要保持内部格式统一。
3. **应用内设置显示格式**：适用于整个应用程序。在应用程序的各个页面上使用相同的显示格式。例如，在物资采购应用中，希望在所有物品详情页面上使用相同的显示格式，保持一致的体验。
4. **页面内设置显示格式**：适用于单个页面或特定的页面区域，其他页面几乎不会复用。例如0显示为/，突出显示当面页面特定的数据。
不同级别和位置可以设置显示格式，其优先级：**页面级别**>**应用级别**>**项目级别**>**系统全局**。
:::tip 提示
设置了系统全局的显示格式后，进行项目备份恢复操作时，需要勾选**恢复系统设置**，以确保成功恢复系统设置数据。
:::
## 如何设置 {#display-format-settings}
### 系统全局设置显示格式 {#system-global}
进入项目列表，在**系统设置**>**更多**>**国际化**中，可用语言中点击**自定义**。
进入自定义页面后，搜索**sys.displayformats**，此处可以添加个性化的显示格式。
### 项目全局设置显示格式 {#project-global}
进入到项目中，点击**项目管理**>**显示格式**，可添加自定义显示格式。
### 应用内设置显示格式 {#application}
进入到应用中，点击左下角的设置按钮，切换到显示格式界面，可添加自定义显示格式。
### 页面内设置显示格式 {#page}
仪表板、报表、SuperPage、表单均可以在页面内**属性栏**>**样式**>**字体**中设置显示格式，支持用户添加和管理自定义显示格式，具体的设置方法参考文档[显示格式](../data-viz/dash/design/data/displayformat.md)，具体规则和语法参考文档[显示格式](../exp/display-format.md)。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/sys-settings"
title: "系统设置"
---
---
order: 17
navTitle: 系统设置
---
# 系统设置
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/basic/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings"
title: "系统信息"
---
---
order: 1
navTitle: 基本
---
# 系统信息
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/basic/sysinfo.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/sysinfo"
title: "系统信息"
---
---
order: 0
navTitle: 系统信息
---
# 系统信息
系统信息用于查看系统的基本配置信息，如**产品信息**、**操作系统信息**、**JVM环境变量**等内容，效果如下：
## 系统诊断{#diagnosi}
系统诊断主要监控环境**当前运行状态**、**环境编码**、**字符集**等信息，并对当前环境进行诊断，给出修改建议。
- **时区设置**：当前系统所处时区
- **file.encoding设置**：JAVA文件的编码
- **sun.jnu.encoding设置**：操作系统所使用的编码
- **环境变量LANG设置**：系统语言、地区、字符集的设置
- **操作系统字符集**：当前环境所处操作系统的字符集
- **java.awt.headless设置**：用于开启`headless`的状态
- **最大内存设置**：环境设置的`最大使用内存`，具体设置可见[设置启动环境变量](../../devops/install/middleware/tomcat.md#env)
- **中文字体**：是否支持中文字体，导出PDF需要中文字体支持，可参照[Linux安装中文字体](../../devops/install/tool-services/linux-fonts.md)进行设置
- **工作目录磁盘空间**：环境工作所处目录的空间大小，显示了`总空间`以及`剩余空间`，具体配置可参照[配置工作目录](../../devops/install/basic-install/workdir-and-defdb.md#set-workdir)
- **临时文件目录**：环境运行过程中产生的临时文件所放置的目录，具体的目录结构可参照[工作目录的结构](../../devops/install/basic-install/workdir-and-defdb.md#dir)
- **技术日志记录级别设置**：当前日志级别分为`TRACE`、`DEBUG`、`INFO`、`ERROR`，一般设置级别为`INFO`，可参照[日志级别](../performance/console.md#log-level)了解详情
- **集群状态**：当前环境的节点状态及节点名称，节点状态分为`单节点`、`主节点`、`从节点`、`禁用(不进入集群)`，详细集群节点状态介绍可参照[集群状态](../performance/cluster.md)
## 产品信息{#product}
产品信息主要介绍**当前版本**、**产品许可**、**启动时间**等环境信息。
- **版本号**：当前环境运行版本号，各个版本信息可参照[版本更新](../../../whatsnew)
- **产品许可**：产品注册信息，若未进行产品注册，可参照[产品许可](./license.md)进行注册
- **工作目录**：用于存放配置文件、临时文件和缓存文件等文件信息的目录，具体设置可参照[工作目录和默认数据库配置](../../devops/install/basic-install/workdir-and-defdb.md)
- **启动时间**：当前环境的`最近启动时间`
- **部署路径**：当前环境启动时程序所在`路径`
- **web会话**：当前环境正在进行的会话数，可通过[修改Tomcat会话超时时间](../../devops/install/middleware/tomcat.md#timeout)限制当前环境会话数量
- **集群节点名**：当前节点名称
## 系统信息{#information}
系统信息主要显示**环境中间件**、**系统时间**、**系统编码**、**时区**等环境运行信息。
- **中间件**：当前系统使用的`中间件名称以及版本`，各个中间件的配置可以参照[安装配置总体介绍](../../../devops/install)
- **JAVA**：当前系统所使用的`JDK的版本号`
- **JVM内存**：显示当前环境的`使用内存`及`最大内存`，点击`强制回收`按钮可回收无用内存
- **系统物理内存**：当前系统的物理内存
- **磁盘空间**：显示当前环境`已使用空间`和`系统最大空间`
- **系统用户名**：启动系统进程所用用户名称
- **时区**：当前系统设置的时区
- **系统编码**：操作系统的使用编码
- **操作系统**：当前环境所使用的操作系统
- **系统时间**：当前系统的`准确时间`
- **CPU核数**：当前操作系统的核心数目
- **JVM启动参数**：当前环境程序运行所使用的参数，具体参数可参照[启动时支持的环境变量](../../devops/install/basic-install/jvm-sys-properties.md)
## JVM环境变量{#JVMvariable}
JVM环境变量主要显示当前环境运行时，JVM环境中所有配置启动参数。
## 系统环境变量{#variable}
系统环境变量主要显示操作系统运行时的环境变量。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/basic/appearance.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/appearance"
title: "外观设置"
---
---
order: 1
---
# 外观设置
基本设置用于设置系统基本信息，可以设置**网站图标**、**产品logo**、**系统名称**等内容。点击**系统设置**>**基本**>**基本设置**，即可对基本设置进行修改。当对所需要的内容修改完成时，需要点击左上角的保存按钮 ，设置才会生效。
:::tip
当处在某个项目中时，需要点击左上角项目名称，点击返回项目列表，再按照上述操作即可进行修改基本设置
:::
## 网站图标{#favicon}
网站图标是指在该系统中打开网页，显示在浏览器的标签页和地址栏上的图标。可以通过上传图标进行修改，仅支持ico格式的图标，系统默认图标如下所示：
## 产品logo{#logo}
产品logo是指显示在登录界面以及主界面左上角的图标，可以通过上传图片进行修改，常见图片格式有png、jpg、svg、gif等。系统默认logo如下图所示：
## 系统名称{#name}
系统名称是为此系统设置简短的名称，用于生成链接分享卡片，以及登录页面浏览器标签页地址栏中，默认名称为**SuccBI**，也可以根据自己需求自定义系统名称。
## 系统描述{#desc}
系统描述是使用一句话来介绍本系统，用于生成链接分享卡片，默认系统描述为**一站式大数据分析平台**，也可以根据自己需求自定义系统描述。
## 系统语言{#language}
系统语言是可以选择切换中文简体或者English作为本系统的系统语言，默认系统语言为**中文简体**。
## 服务器部署地址{#domain}
服务器部署地址需要填写服务器具体域名如：`https://www.example.com` ，或 ip 地址如： `https://192.168.0.1:8080`。
## 帮助文档服务器地址{#manualserverurl}
帮助文档服务器地址是填写产品手册文档所在的服务器地址，系统一些帮助按钮和链接可以打开此服务器的相关帮助页面。默认为：`https://docs.succsoft.com/`。
## 文档转换服务器地址{#documents4jserverurl}
在查看docx、pptx等文件时需要将文档进行转换，以适配不同设备的不同软件打开文件的效果，所以需要配置[文档转换服务器地址](../../devops/install/tool-services/documents-converter.md)，默认空表示使用系统内置的转换服务（纯Java实现的，存在一定失真）。
## 启用历史版本{#history}
可以勾选启用历史版本，则可以看到每次编辑保存的版本，这些版本对于最近一次的修改来说便成为历史版本，默认勾选该选项。查看历史版本操作如下：
勾选需要查看历史版本的文件，点击右上角**元数据属性**>**历史版本**，弹出对话框，即可对历史版本的数据进行**编辑**、**还原**、**差异**等操作。
## 启用智能压缩{#compress}
必须勾选**启用历史版本**，才会有**启用智能压缩**的选项，如果勾选该选项，则近一周的历史版本会被全部保留，而一周之前的历史版本只会保留每天最新的一版；默认不勾选，不勾选则保留所有历史版本。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/basic/homePage.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/homepage"
title: "默认首页"
---
---
order: 3
---
# 默认首页
首页是指用户登录后第一眼看到的页面（不是指登录页面，而是指用户登录成功后默认访问到的页面）。在不同业务场景下，用户希望登录后能直接看到符合各自业务场景的首页，如：
1. 领导用户登录后直接进入“主营业看板”应用
2. IT部门用户登录后进入项目的“监控”模块
3. 管理员登录后进入到项目列表页面
4. 所有非管理员用户登录后默认显示某个应用页面
首页有多种设置方式个人设置、用户组设置、系统全局都可以设置首页，默认情况下，系统也会根据用户的权限自动确定当前用户的首页，本文重点介绍系统全局首页设置以及根据权限确定首页的逻辑规则。
## 设置系统默认首页{#set-index}
全局首页设置在**系统设置**>**基本**>**默认首页**中进行：
系统支持四种首页类型，并会根据访问设备自动导航首页：
- 桌面端首页
- 移动端首页：没有设置时，会使用桌面端首页
- 外部用户桌面端首页：没有设置时，会使用桌面端首页
- 外部用户移动端首页：没有设置时，会使用移动端首页
:::tip
系统包含了两套用户，其中外部用户是可以脱离系统组织机构的，二者有各自的适用场景，更多说明可查看文档[用户管理-外部用户](../../permission/users.md#external-users)。
:::
首页路径可以输入相对地址、绝对地址，也可以输入带有宏表达式的动态路径，如：
1. `/example` - 名为 example 的项目地址
2. `/example/${$user.id}` - 使用宏动态构建首页地址，更多说明见[带有宏表达式的动态首页路径](#macro-url)。
3. 以`http://`或者`https://`开头的完整URL，比如 `http://example.com/`，需要注意的是对于这种地址，系统将会直接跳转过去，而不会判断该页面是否有权限被当前登录的用户所访问。
### 带有宏表达式的动态首页路径{#macro-url}
首页路径可以输入宏，宏中通常需要使用到[`$user`](../../exp/var/$user.md)表达式对象。
示例1：
1. 需求描述：admin用户组的用户登录，进入到管理界面；其它用户进入到demo门户页面
2. 表达式：`${IF(USER_INGROUP('admin'),"/DEMO","/DEMO/app/DEMO.app")}`
示例2：
1. 需求描述：admin用户登录，进入到管理界面；其它用户进入到demo门户页面
2. 表达式：`${IF([用户]='admin',"/DEMO","/DEMO/app/DEMO.app")}`
示例3：
1. 需求描述：admin用户组的用户登录，进入到管理界面；用户组名称为**manage**的用户登录，进入到DEMO门户；其它用户进入到SuperPage门户
2. 表达式：`${CASE WHEN USER_INGROUP('admin') THEN "/DEMO" WHEN USER_INGROUP('manage') THEN "/DEMO/app/DEMO.app" ELSE "/DEMO/app/ap.app" END}`
## 首页选择策略{#index-politics}
用户登录时，系统会根据当前用户的个人设置、所在用户组的设置、系统设置以及当前用户的权限动态的决定当前用户应该显示哪个首页，规则优先级如下：
1. 如果存在个人设置中的首页设置，那么直接使用个人设置中的首页设置。
2. 如果用户所在的用户组有首页设置，那么使用用户组的首页设置。如果存在多个用户组都有首页设置，那么取第一个用户组（按用户组ID升序排序）的设置。
3. 如果存在系统首页设置并且当前用户对首页有访问权限，则直接进入首页。
4. 若对设置的首页没有权限，则会自动判断用户所拥有的权限决定首页，规则如下：
1. 取所设置首页地址所在的项目，如果用户对该项目有某“应用”的访问权限，那么首页为该应用。
2. 若是仅对一个项目（忽略`系统数据`项目）有权限，如果用户对该项目有某“应用”的访问权限，那么首页为该应用。
3. 如果当前用户使用移动设备访问，那么会优先选用支持移动设备的“应用”访问。
4. 如果用户仅对一个仪表板、报表或页面有权限，那么直接显示有权限的哪个页面。
5. 若是对多个以上资源有权限且未[限制访问默认管理界面](../../project-manage/basic-setting.md#restrict-metamgr)，则直接跳转到`/projects` 页面，进入项目列表。
6. 若是有新建项目权限，则跳转到`/projects` 页面，进入项目列表。
5. 如果以上规则都没有匹配，那么显示[无权限访问页面](../../dev/script/system-pages/status-pages.md#403)。
## 首页地址栏URL{#short-url}
最终访问到的首页地址，将保留来自用户主动在URL上输入的参数和首页设置中的参数，比如：
用户输入的地址为:
```sh
http://succbi.example.com/?param1=pa
```
首页所设置的地址为：
```sh
/DEMO/dashboard?param2=test
```
最终定位到的首页地址将会是:
```sh
http://succbi.exmaple.com/DEMO/dashboard?param1=pa¶m2=test
```
如果希望在地址栏显示简短的URL地址，可以参考[应用设置之短路径](../../app/app-settings.md#shorturls)进行设置。
## 常见问题{#faq}
### 首页设置为门户应用后如何默认显示门户内某个页面{#faq-1}
门户应用内部可以自己设置的，见[如何定位应用的首页](../../app/portal-page/FAQ/如何定位应用的首页.md)。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/basic/license.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/license"
title: "产品许可"
---
---
order: 4
---
# 产品许可
在项目列表界面，点击**系统设置**>**基本**>**产品许可**，用户可以在**产品许可**界面查看产品许可信息、申请产品许可及更新产品许可。
## 产品许可信息{#infomation}
产品许可信息是平台部署后能正常使用的凭证信息，包含了产品名称、版本号、服务器ID、项目名称等。
- 版本号：当前系统的版本号
- 服务器ID：唯一标识部署服务器的ID，和部署服务器的硬件有关系
- 项目名称：当前系统使用的版本名称
- 授权集群节点：申请注册码时填写的客户名称
- 有效期：注册码的有效期，达到有效期后需要重新申请注册码
- 功能说明：说明产品许可授权的功能范围，不同的注册码会有不同的功能授权
## 升级许可{#update}
升级许可一般用于有效期快结束时，通过重新申请注册码并更新许可信息来保持平台的正常使用。点击**升级许可**按钮，平台为用户提供了两种升级许可的方式以及申请许可的入口。
### 申请产品许可{#apply}
用户可以通过微信扫码或者联系客服进行产品许可的申请，申请产品许可时需提供服务器特征码，即服务器ID。
### 更新产品许可{#update-license}
待客服审批完成后，会返回给用户一个.license文件，用户将申请时提供的项目名称和文件中的注册码信息填入相应的位置，或者直接上传.license文件，平台将自动识别文件中的内容，即可更新产品许可。
:::tip 集群节点更新
集群环境上更新产品许可时在任意节点上更新都会作用到整个集群，建议在相对稳定不变的集群节点上更新产品许可。
:::
---
url: "https://docs.succapp.com/v5/guide/sys-settings/security/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/security"
title: "安全设置"
---
---
order: 3
navTitle: 安全
---
# 安全设置
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/security/securityconf.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/securityconf"
title: "安全设置"
---
---
order: 0
navTitle: 安全设置
---
# 安全设置
SuccBI提供了丰富的安全相关设置选项，包括**登录安全**、**密码安全**、**安全等保**、**数据加密脱敏**等，通过进行合理的设置可以让系统通过各种相关安全评测，具体设置界面如下图：
## 安全评测推荐配置{#security-settings}
在系统正式上线运行或开展**信息安全等级保护**测评时，系统推荐配置如下：
|属性|推荐设置|
|:-|:-|
|[密码强度](#password-strength)|**密码最小长度**设置12位以上，勾选**必须包含大小写字母**、**必须包含数字**、**必须包含特殊字符**、**不能包含用户id**|
|[自动检查密码](#password-validity)|勾选**登录时校验强度**、**默认密码检查**，其他属性可视实际情况配置|
|[登录验证](#validate-logon)|勾选**允许锁定保护账号**，**启用图片验证码**，其他属性可视实际情况配置|
|[登录方式](#login-type)|不勾选**允许用户同时多次登录**和**URL登录**，其他属性可视实际情况配置|
|[用户登录](#login-user)|不勾选**匿名用户登录**，如实际业务要求用到匿名用户，需控制好匿名用户权限；如对账号登录安全性要求较高，可启用**系统用户双重登录校验**，其他属性可视实际情况配置|
|[禁用WebDAV](#disable-webdav)|建议勾选，禁用WebDAV可以提高服务器的安全性，防止未经授权的文件操作，禁用后将无法使用ActiveDoc在线编辑功能，可视实际情况配置|
|[启用Ajax加密](#ajax-encryption)|建议勾选,防止某些安全软件将系统查询请求中的部分内容识别为敏感信息，从而拦截请求导致系统异常|
|[Cookie安全传输](#cookie-transmission)|`https`环境下，建议勾选，`http`环境，无需勾选|
|[启用跨域](#cross-domain)|若系统涉及与第三方集成，则需要启用，并配置跨域信任域，参考：[跨域问题](../../dev/integrate/embed-into-3rd.md#cors-iframe)|
|[禁止被嵌入外站Iframe](#prohibit-embedded-iframe)|建议勾选，若项目存在页面[嵌入第三方系统](../../dev/integrate/embed-into-3rd.md)，则无需启用|
|[启用防MIME嗅探](#enable-entimime)|建议勾选，用于防止由MIME类型混淆引发的各类攻击，如XSS、恶意脚本执行|
|[启用内容安全策略](#enable-csp)|建议勾选，预防XSS漏洞|
|[显示执行SQL](#display-sql)|建议不勾选，项目开发阶段建议启用以便开发排查问题|
|[禁止返回异常堆栈](#forbid-exceptions)|建议勾选，异常堆栈常常包含一些敏感信息，会被安全软件识别为信息泄露|
|[禁止输出SourceMap](#forbid-files)|建议勾选，资源映射文件会可能包含一些敏感信息，如源码地址，会被安全软件识别为信息泄露|
|[允许上传的文件类型](#upload-file-restrictions)|根据系统实际情况配置允许上传文件类型，用于防止渗透攻击|
## 密码安全{#password-settings}
用户密码的相关设置，在这里可以设置[密码存储](#password-storage)、[密码强度](#password-strength)、[有效期](#password-validity)、[密码重置](#password-reset)。
### 密码存储{#password-storage}
可以在这里设置密码加密算法，常见的加密算法有`SHA1`、`MD5`、`SM3`，也可以选择`脚本`实现相关函数，具体方法见[钩子脚本](../../dev/script/hooks/hooks-action-ts.md)，选择`明文`后就会明文存储，不使用加密算法。设置对应的加密算法保存后，用户下次修改密码后，密码存储就会使用对应的加密算法。
### 密码强度{#password-strength}
设置了密码强度后，用户第一次登录若使用默认密码，则需要修改密码才能登录。当管理员修改了密码强度，用户第二次登录时若密码不符合密码强度规则，则会根据对应强度规则给出修改建议。
- **密码最小长度**
- **必须包含大小写字母**
- **必须包含数字**
- **必须包含特殊字符**
- **不能包含用户id**
- **容易被黑的密码**：若新密码匹配到此处的规则，则会提示密码太过简单，这里使用枚举方式设定规则
- **密码强度匹配**：这里是一个正则表达式
- **密码强度提示**：当密码未满足**密码强度匹配**的要求时，给用户的提示信息
以上几点是并列关系，可以同时设置，都会生效。
### 自动检查密码{#password-validity}
- **登录时校验强度**：开启后，如果账号密码不满足[密码强度](#password-strength)的校验，则需要先修改密码，才能登录。
- **默认密码检查**：开启后，如果用户从来没有修改过密码，则需要先修改密码，才能登录。
- **记住我的登录状态**：勾选后，登录页面会出现`记住我的登录状态`的勾选框，作用于PC端。
- **记住登录状态的天数**：设置登录状态最长记录多少天，超过这个天数后就需要重新登录。
- **密码最长无修改天数**：当密码的最后修改时间距离当前系统时间大于密码最长无修改天数时，登录后会自动定位到密码修改页面，用户必须修改密码后才能继续操作。
### 密码修改{#password-reset}
- **密码历史记录数**：系统会对已经设置了的密码进行记录，这里表示可被记录的历史条数，如果历史条目数达到上限，会将最先记录的删除，并将新的记录添加进去。修改密码时，不能使用最近记录历史的密码。
- **短信重置密码**：勾选后，可以启用通过手机短信重置密码，参考[重置密码](../../dev/references/web-api/me/resetPassword.md)。
- **允许切换明文展示密码输入**：勾选后，系统中需要输入账号密码的输入框都会展示一个按钮，点击可切换是否展示密码明文。
## 登录安全{#login-settings}
用户登录过程中的相关设置，这里的设置可以影响登录界面的效果，也会影响登录步骤。修改属性后，可点击底部的**保存**按钮，让登录安全设置生效。
### 登录验证{#validate-logon}
- **允许锁定保护账号**：启用后，当用户使用密码登录失败的次数到达**显示警告前尝试次数**设定的值时，系统会开始提示用户距账户被锁定的剩余尝试次数，若失败次数达到**锁定前尝试次数**后，再登录失败就会锁定账户。
:::tip
**显示警告前尝试次数**与**锁定前尝试次数**相等，表示不提示，前者一般要小于后者。
:::
- **图片验证码**：启用后，用户重复登录的次数达到**显示验证码前尝试次数**设定的值时，登录界面就会出现验证码，此时登录，必须要输入正确的验证码才能登录成功。可以设置**验证码字符长度**，一般默认为4位。
### 登录方式{#login-type}
- **允许用户同时多次登录**：启用后，可以使用同一账号同时在多处设备登录。若未启用，在多处设备登录时，则会给出提示，提示可以选择继续登录。
- **启用URL登录**：启用后，可以直接在URL上携带用户密码登录到系统中，参考[URL参数传递用户名密码登录](../../devops/sso/urllogin.md)。为安全考虑，默认是不允许开启的。
- **启用短信验证码登录**：启用后，用户将可以使用账号所绑定手机号获取验证码进行登录，参考[登录API](../../dev/references/web-api/auth/signin.md)，这里会影响到登录页登录框的效果，参考[登录页用户登录模式设置](../../dev/script/system-pages/login-page.md#login-modes)。
- **启用手机密码登录**：启用后，用户将可以在登录界面使用手机号替代用户ID，并且在输入正确密码后登录到系统中，这里的手机号即[用户表PHONE字段](/sys-tables/sec/USERS)。
:::tip
如果用户信息里面没有手机号码，是无法登录的，需要先把手机号码更新。
:::
### 用户登录{#login-user}
- **启用匿名用户**：启用后，在用户组中给[匿名用户组](../../permission/groups.md#anonymous)分配权限，即可不登录访问资源。
- **启用外部用户**：启用后，在用户组中给[外部用户](../../permission/users.md#external-users)分配权限，并且会影响到登录页登录框的效果，参考[登录页用户登录模式设置](../../dev/script/system-pages/login-page.md#login-modes)。
- **外部用户登录方式**：用于控制默认登录界面会针对外部用户展示哪些登录方式，有默认账号登录、手机短信登录、二维码登录方式可供选择。
- **系统用户登录方式**：用于控制默认登录界面会针对系统用户展示哪些登录方式。有默认账号登录、手机短信登录、二维码登录方式可供选择。如果系统用户和外部用户都没有选择任何一种登录方式，默认会开启使用系统账号登录方式。
- **启用系统用户双重登录校验**：开启后，系统用户在登录时需要正确输入账号密码后，再次输入手机验证码才能正确登录。
- **启用外部用户双重登录校验**：开启后，[外部用户](../../permission/users.md#external-users)在登录时需要正确输入账号密码后，再次输入手机验证码才能正确登录。
### 用户信息{#user-info}
- **允许修改用户名称**：勾选后，将允许用户在个人中心修改用户的名称，默认勾选。
- **启用手机绑定验证**：启用后，用户在个人中心修改手机号时，将会发送手机短信进行绑定验证。
- **启用邮箱绑定验证**：启用后，用户在个人中心修改邮箱时，将会发送邮件进行绑定验证。
## 会话管理{#-session-manage}
设置会话存储位置，修改此选项需要重启后才生效。支持两种存储方式：
- **默认**：使用web容器（如Tomcat）默认存储。
- **redis**：将会话存储在redis中，便于集群部署会话转移.
## 安全等保{#classified-protection}
用户使用过程中数据、请求的相关设置，这里的设置影响到数据、请求的安全策略。
### 禁用WebDAV{#disable-webdav}
禁用WebDAV后，在元数据界面和app编辑器中，将无法使用右键编辑打开对应的word，excel和PPT页面。
### 启用Ajax加密{#ajax-encryption}
开启Ajax加密后，所有的Ajax请求，包括body和url都会进行加密，且服务器返回的所有json信息也会被加密。
开启此选项对系统性能有一定影响，在安全评测报告Ajax请求参数或服务器返回内容有不合法内容时可考虑开启。
### Cookie安全传输{#cookie-transmission}
开启Cookie安全传输后，只有使用https等加密协议访问系统时，cookie才会被正确设置，可以通过`Cookie SameSite`设置关闭Cookie限制的请求，具体可参照[cookie-samesite](../../dev/integrate/faq/cookie-samesite.md)。
### 启用跨域{#cross-domain}
开启启动跨域后，在`跨域信任域`中可设置信任域如域名、指定ip，使满足设置的跨域请求被当前服务器接收，信任域的设置规则如下：
1. **使用https协议**：如`https://www.succsoft.com`，表示只信任https协议的域名
2. **使用http协议**：如`http://www.succsoft.com`，表示信任http和https协议的域名
3. **使用带端口的域或ip**：如`http://192.168.1.1:8080`，表示信任指定端口的域名或者ip
**注意：当使用ajax跨域请求的时候需要针对 `XMLHttpRequest` 配置上 `withCredentials=true`（[参考文档](https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest/withCredentials)），否则可能会因为cookie没有传递给服务器，导致请求响应错误。**
### 禁止被嵌入外站Iframe{#prohibit-embedded-iframe}
禁止被嵌入外站Iframe后，响应头中会增加响应头`X-Frame-Options:SAMEORIGIN`，禁止将本系统的页面嵌入到其他网站页面中。
### 启用防MIME嗅探{#enable-entimime}
用于防止基于MIME类型混淆的攻击，启用防MIME嗅探后，响应头会设置`X-Content-Type-Options:nosniff`，如下请求会被阻止：
1. 请求类型是"style"，但MIME类型不是"text/css"
2. 请求类型是"script"，但MIME类型不是JavaScript MIME类型
### 启用内容安全策略{#enable-csp}
启用内容安全策略后会将响应头`X-XSS-Protection`设置为`1; mode=block`，来通知浏览器开启XSS检测，并可通过`安全策略内容`设置Content-Security-Policy中的内容，具体介绍可参照[XSS信息](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/X-XSS-Protection)和[Content-Security-Policy信息](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CSP)
### 显示执行SQL{#display-sql}
启用之后将在查询结果中输出SQL、查询的Query等信息，SQL属于敏感信息，一般不会输出到计算日志中。在测试阶段，为了方便了解系统执行的SQL可以开启，此选项一般用于测试阶段，正式交付此选项不进行启用。
### 禁止返回异常堆栈{#forbid-exceptions}
启用后将禁止输出异常信息到客户端，异常堆栈常常包含一些敏感信息，如源码、绝对路径、cookies、提交的数据等，输出到客户端可能造成信息泄露，产生安全问题。
### 禁止输出SourceMap{#forbid-files}
启用后将禁止输出资源映射文件到客户端，资源映射文件会可能包含一些敏感信息，如源码地址，从而产生安全问题。
## 阈值设置{#thresholds}
环境运行时阈值的相关设置，这里可以设置**短信验证码**、**上传文件大小阈值**、**HTTPClient连接**等。
### 短信验证码{#captcha}
勾选[启用短信验证码登录](#login-type)后生效，用户使用短信验证码方式登录时，系统可以对验证码的长度、发送频率、有效时长做出一些设置，也可以指定验证码重试次数以及锁定时长。
- **短信验证码长度**，一般默认为6个字符。
- **验证码发送频率**，重发验证码的最短时间间隔。
- **验证码有效时长**，默认为10分钟。
- **手机短信锁定时长**，超过`短信验证码重试次数`后的锁定时长，默认锁定时长为10分钟。
- **短信验证码重试次数**，手机号被锁定前，可以尝试输入验证码的次数，默认为5次。
### 文件上传大小{#upload-file-restrictions}
- **上传文件阈值**：用户单次上传文件的大小限制，单位为Kb，默认为102400Kb(100Mb)。
- **允许上传的文件类型**：允许用户上传文件的类型，多个文件类型用逗号隔开。
- **上传视频文件阈值**：用户单次上传视频文件的大小限制，单位Kb，默认为51200Kb(50Mb)。
- **上传图片文件阈值**：用户单次上传图片文件的大小限制，单位为Kb，默认为10240Kb(10Mb)。
- **上传3D模型阈值**：用户上传3D模型文件的大小限制，单位为Kb，默认为5120Kb(5Mb)。
### 数据查询阈值{#query-threshold}
设置用户使用一次SQL查询最多可以返回多少行数据，默认返回500000行。
### 缓存阈值{#cache-size}
- **前端自动缓存数据阈值**：模型属性[前端预加载数据](../../data-gov/model/model-settings.md#downloadalldatamode)没有设置为**允许全量数据**时，根据该阈值自动判断模型是否允许全量下载，默认1000行。
- **前端缓存数据最大行数**：模型属性[前端预加载数据](../../data-gov/model/model-settings.md#downloadalldatamode)设置为**允许全量数据**时，数据量必须小于等于该阈值才能下载全量数据，默认100000行。
- **维表内存缓存阈值**：维表数据一次缓存到内存的最大行数，当维表数据小于阈值时，可全量读取到内存以提高运行效率，默认为1000000行。
- **静态文件缓存秒数**：元数据库中的静态文件如图片、js文件、css文件等在浏览器中进行缓存的有效时间，默认为3600秒。
### HTTPClient连接{#httpclient-pool}
- **HTTPClient连接池大小**：系统访问第三方服务时需要http连接池来提高性能，默认为50，修改此参数会同步修改http中的maxPoolSize参数。
- **HTTPClient最大保持连接时间**：客户端与服务端建立持久连接的最大连接时间，超过此时间，连接会被回收。默认为30000，修改此参数会同步修改http中的keepAliveTime参数。
- **HTTPClient与服务端建立连接的超时时间**：客户端与服务端建立连接的超时时间，超过此时间，客户端会停止请求。默认为10000，修改此参数会同步修改http中的connectionTimeout参数。
- **HTTPClient等待服务端响应数据的超时时间**：客户端与服务端建立连接时，等待服务端响应的超时时间，超过该时间，客户端会停止请求。默认为5000，修修改此参数会同步修改http中的socketTimeout参数。
### 缓慢变化数据全量下载阈值{#download-threshold}
在模型设置缓慢变化时，所有历史数据下载到前端浏览器的阈值，默认为50000行，设置方法可参照[缓慢变化数据提取](../../data-process/data-output/slowchange-output.md)。
### 线程池{#threads}
- **调度线程池最大线程**：执行计划任务时的最多可用线程数目，默认为20线程，计划任务的设置方法可参照[计划管理](../../schedule/README.md#manage-schedule)。
- **数据迁移最大线程数**：跨源迁移数据时最大可用线程数，默认为50线程。
## 回归测试{#test}
环境升级或者系统修改配置后进行回归测试的相关设置，这里的设置影响`回归测试脚本`的启用及可用于回归测试的`测试用户`。
- **启用回归测试脚本**：启用后，用户可在元数据项目新建test目录，添加回归测试脚本进行测试。具体测试方法可参照[回归测试](../../devops/test/regression-test.md)。
- **测试用户**：勾选`启用回归测试脚本`后生效，用于设置测试过程中可使用的账号。执行回归测试过程中，管理员可以用这些用户身份进行免密登录测试。若设置多个账号，各个账号需以逗号隔开。
## 系统日志设置{#sys-log}
- **日志记录级别**：系统日志表中记录的日志信息的级别，分为`OFF`、`FATAL`、`ERROR`、`IMPT`、`INFO`、`VERB`和`ALL`，日志记录越详细，占用的数据库空间越大，日常生产环境建议使用`INFO`级别的日志记录，日志级别描述如下：
|日志级别|级别描述|
|:-:|:-:|
|ERROR|错误|
|FATAL|严重|
|IMPT|重要|
|INFO|信息|
|OFF|关闭|
|VERB|详细|
|ALL|所有|
- **当前日志表大小**：记录当前系统日志表的行数和表大小，系统日志表的介绍可参照[LOG\_SYS-系统日志表](/sys/LOG_SYS)
- **记录文件修改历史**：勾选记后，可在文件的属性栏查看该文件的历史版本内容，可较方便查看和对比文件修改历史。
- **当前文件历史表大小**：当前记录文件修改历史的表的大小，历史版本表的介绍可参照[META\_REVISIONS-历史版本表](/sys-tables/meta/META_REVISIONS)
- **脚本输出日志限制**：设置脚本文件一次执行时使用print函数最多输出多少条日志，默认为10000条。
- **记录模型表信息**：将在系统表中自动记录模型的提取状态、行数、存储空间等关键信息。
## 数据脱敏{#desensitization}
当前系统中对数据脱敏策略的设置，系统默认自带`身份证号`、`手机号`、`姓名`等常见脱敏策略供使用，你可以点击编辑进行修改，也可以点击添加新增脱敏规则。添加修改完毕后，点击底部的`保存`按钮生效。模型中使用数据脱敏可参考[脱敏](../../data-gov/model/data-security.md#desensitization)。
### 掩码数据脱敏{#data-masking}
掩码方式数据脱敏配置如下：
- **ID**：脱敏规则分配的唯一id，新建脱敏规则时由系统自动分配。
- **标题**：对脱敏规则的描述，必填。
- **脱敏方式**：脱敏方式选择掩码方式。
- **掩码设置**：可设置脱敏数据开头和末尾字符的保留个数以及替换掩码的字符。
- **测试示例**：输入测试示例后，可显示脱敏后的结果，必填。
### 正则表达式数据脱敏{#regular-desensitization}
正则表达式数据脱敏配置如下：
- **ID**：脱敏规则分配的唯一id，新建脱敏规则时由系统自动分配。
- **标题**：对脱敏规则的描述，必填。
- **脱敏方式**：脱敏方式选择正则表达式。
- **正则表达式**：脱敏数据的正则表达式写法。
- **替换为**：将脱敏数据替换后的写法，此处也为正则表达式。
- **测试示例**：输入测试示例后，可显示脱敏后的结果，必填。
## 数据加密{#data-encryption}
当前系统中对数据加密策略的设置，内置的加密算法有`SM4`和`AES`，用户可根据需要自行添加或修改加密策略。添加修改完毕后，点击底部的`保存`按钮生效，模型中使用数据加密可参考[加密](../../data-gov/model/data-security.md#encryption)。
::: warning 警告
若修改已有加密策略中的密钥，会导致以前加密的数据无法解密！
:::
数据加密配置如下：
- **ID**：加密策略分配的唯一ID，新建加密策略时由系统自动分配。
- **标题**：对加密策略的描述，必填。
- **算法**：可选择SM4算法或者AES算法。
- **密钥**：加密策略使用的密钥，可自行填写，也可由系统自动生成，必填。
## 系统安全{#system-security}
- **启用项目内计划管理**：计划任务默认只能系统全局管理，启用后，可以给项目管理员分配项目内的计划和任务的管理、查看权限，项目管理员可以管理各自项目内的计划任务。
:::tip
计划任务区分全局和非全局，项目列表下创建的计划任务为全局计划任务，任何项目可见；项目内创建的计划任务为非全局计划任务，仅该项目以及全局计划任务可见。
:::
## 常见问题{#common-encryption}
以下为安全等保测评时，可通过系统安全设置解决的安全漏洞，以及相应解决方案：
### 跨域资源共享CORS漏洞
**解决方案**
在`系统设置`->`安全设置`->`安全等保`中取消勾选启用[跨域](#cross-domain)。
### “Content-Security-Policy”头中缺少“Script-Src”或“Default-src”策略或相应策略不安全
**解决方案**
启用[内容安全策略](#enable-csp)。
### SQL注入漏洞
**解决方案**
勾选[启用Ajax加密](#ajax-encryption)以及取消勾选[显示执行SQL](#display-sql)。
### 跨站点请求伪造
**解决方案**
勾选[禁止被嵌入外站Iframe](#prohibit-embedded-iframe)。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/security/sso.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/sso"
title: "单点登录"
---
---
order: 1
---
# 单点登录
SuccBI提供了多种单点登录的配置方案以支持与第三方系统作集成，以方便通过简单的配置达到目的。系统内置有以下几种配置：
- [微信公众号授权登录](../../devops/sso/wechat.md)
- [微信小程序授权登录](../../devops/sso/wechat-miniprogram.md)
- [钉钉授权登录](../../devops/sso/dingtalk.md)
- [OAuth2服务](../../devops/sso/oauth2.md)
- [CAS服务](../../devops/sso/cas.md)
若是内置的单点登录方式都不能满足条件，还可以通过单点登录的扩展方式进行简单的开发，实现任意单点登录需求：
- [扩展服务](../../dev/extension/extension-points/sso.md)
## 登录设置{#login-conf}
- **默认登录方式**：用于设置当用户访问需要登录才能查看的资源时，系统默认跳转到的单点登录方式。\
示例：如果这时候选中了一种单点登录方式，比如说一种[OAuth2服务](../../devops/sso/oauth2.md)单点登录方式，\
未登录的情况下期望访问 ，常规情况下会跳转到OAuth2服务的授权URL去获取OAuth2服务的认证。
- **扫码登录静默授权**：启用后，手机扫码登录时将自动进行授权，不再提示确认授权登录的页面。
- **二维码提示**：系统登录界面在展示二维码时给出的提示。
## 单点登录方案{#sso-type}
SuccBI支持同时配置多种单点登录方案，也支持同时配置多个同类型的单点登录方式，以满足如内网外网使用不同的登录方式，或者是让用户在登录页面有多种方式选择来进行登录。
### 通用设置{#common-settings}
通用设置包括如下几个方面：
1. 单点基本设置：\
1. 启用：但单点登录方案暂时不可用时，为了保留设置，可以先设置为`未启用`状态。
2. 登录方案ID（ssoid）：唯一标识。
3. 登录方案标题：对单点登录的简要描述。
4. 登录方案描述：详细描述。
2. 用户匹配与不匹配时的策略：\
1. [内部用户和外部用户](../../permission/users.md#external-users)的匹配方式分开配置，也可以同时配置两种匹配方式。在检测时候也会先尝试使用内部用户匹配规则进行匹配，然后才使用外部用户规则进行匹配，并且如果都没有匹配到，这再依判断内部用户规则和外部用户规则，是否需要创建用户。
2. **用户匹配依据1**：用于根据从单点登录方案提供者获取到的用户信息，在系统中查找与之匹配的用户的首要字段
3. **用户匹配依据2**：用于根据从单点登录方案提供者获取到的用户信息，在系统中查找与之匹配的用户的次要字段，如果从首要字段没有查找到，但是通过次要字段查找到了，将会更新这个用户的首要字段对应的数据为最新获取到的数据。
4. **昵称字段**：用于在个人中心判断是否有绑定第三方系统账号的时候展示。
5. **不匹配时**：根据**用户匹配依据1**和**用户匹配依据2**都没有匹配到用户时的策略：
- 拒接登录：展示界面通知改用户没有权限登录SuccBI。
- 创建用户：根据获取到的用户信息，在SuccBI对应用户目录（内部用户或者外部用户）中创建一个用户，并使用这个新创建的用户登录到系统中。
- 发起注册流程：待完善，现在与拒绝登录效果一致。
### 登录实现方案具体设置{#sso-detail}
位于对话框设置栏的第二栏，不同的方式有不同的设置，详细信息请参考：
- [OAuth2服务](../../devops/sso/oauth2.md)
- [微信小程序/微信公众号授权登录](../../devops/sso/wechat.md)
- [钉钉授权登录](../../devops/sso/dingtalk.md)
- [CAS服务](../../devops/sso/cas.md)
---
url: "https://docs.succapp.com/v5/guide/sys-settings/security/trustedapps.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/trustedapps"
title: "授信应用"
---
---
order: 2
---
# 授信应用
SuccBI提供了“授信应用”机制以实现对第三方系统的身份认证，以便第三方系统调用SuccBI的API、访问资源或单点登录，如：
1. 第三方系统无密码访问SuccBI的API并获取相关数据
2. 第三方系统无密码将SuccBI的报表或仪表板嵌入到第三方系统内部
3. 第三方系统无密码调用SuccCI的API自动上报数据
**授信应用**机制使用严密的加密机制“信任”并“只允许”被信任的“应用”访问系统，确保数据的安全。系统支持以下授信应用方式：
\[\[toc]]
## IP授信应用{#trust-ip}
IP授信应用是第三方系统通过服务器向SuccBI服务发送认证请求，然后SuccBI在完成身份认证后向第三方系统发放登录令牌，最后第三方系统使用登录令牌登录到SuccBI的方式完成认证。但是由于对固定IP的需求，适合于内网以及IP地址相对稳定的场景，网络不稳定或互联网环境不推荐使用。
注册IP授信应用的配置如下：
- 应用ID：为授信应用分配的公开唯一id,获取SuccBI身份时需要提供给SuccBI认证应用身份，必填。
- 应用名称： 对应用的简要描述,非必填。
- 应用密匙：授信应用用于获取系统认证的秘钥，必填。
- 授权方式：选择 `信任IP`。
- IP地址： 第三方系统服务器的IP地址，系统在确认用户身份的时候会确认是哪个IP发来的认证请求，必填。
- 用户组：用于限制第三方系统可以申请那些用户用于登录，不填则默认可用使用系统中的所有用户。
完成IP授信应用注册后，还需要第三方系统的一些开发工作，才能真正的让第三方系统访问SuccBI，参考[开发IP授信应用](../../dev/integrate/dev-ip-token.md)。
## 证书授信应用{#trust-cert}
证书授信是通过数字证书的私钥公钥加密机制来实现系统对第三方系统的身份认证。第三方系统持有私钥，SuccBI持有公钥，第三方系统使用私钥加密一个令牌后发送给SuccBI，SuccBI通过公钥验证令牌的合法性来识别第三方系统的身份是否合法。证书授信安全级别较高，适用于各种网络环境。除此之外，SuccBI还提供与证书授信应用对应的方式，以方便第三方系统将SuccBI设置为授信应用，详见[系统证书](#systemcert)。
设置界面在 **系统设置** > **安全** > **授信应用** > **工具栏** > **添加应用**：
注册证书授信应用配置如下：
- 应用ID：为授信应用分配的公开唯一id，获取SuccBI身份时需要提供给SuccBI认证应用身份，必填。
- 应用名称：对应用简要描述，非必填。
- 授权方式：选择`证书授信`。
- 证书：为证书的`公钥`，用于界面认证信息。证书的生成方式为`RSA 1024`位，秘钥格式为`PKCS#8`，`不需要证书密码`。\
也可通过`生成证书`按钮来生成证书，弹窗所展示内容即为`私钥`。
完成了证书授信的系统设置后，还需要第三方系统的一些开发工作，才能真正的让第三方系统访问SuccBI，具体见[开发数字证书登录令牌](../../dev/integrate/dev-ca-token.md)。
## 系统证书{#systemcert}
与[证书授信应用](#证书授信应用)相对的是，SuccBI持有私钥，第三方系统持有公钥的方式，供第三方系统将SuccBI设置为授信应用。系统通过`私钥`加密认证信息然后将认证信息发送给第三方系统，第三方系统通过`公钥`验证私钥的合法性来识别第三方系统身份。
系统证书的`公私钥`不会自动生成，需要管理员在指定系统ID后手动生成。设置界面在 **系统设置** > **安全** > **授信应用** > **工具栏** > **系统证书**：
注:
1. 为保证`私钥`的保密性，设置界面上不会展示`私钥`，若要查看`私钥`请在元数据`/sysdata/settings/settings.json`中键名为`security.trustedapps.systemCert`的配置中查看
2. 证书的`公钥`为界面中的`证书`选项中。
3. 重新生成系统证书前请务确认其它系统有没有正在使用这个证书，以避免造成不必要的麻烦。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/security/log.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/log"
title: "日志查询"
---
---
order: 3
---
# 日志查询
---
url: "https://docs.succapp.com/v5/guide/sys-settings/performance/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/cache"
title: "缓存管理"
---
---
order: 4
navTitle: 运维
indexTitle: 缓存管理
---
# 缓存管理
对系统的文件或数据进行访问时，若每次都从服务器端重新读取数据进行计算，就加大了服务器的压力并且导致访问速度变慢，为此系统会将一些经常访问到的数据存放在内存或临时文件中缓存起来，以提高系统效率。
**缓存管理**用于查看和清理当前服务器上的缓存，当侦测到数据发生变化时（如执行计划任务），系统会自动查询最新的数据，此时不需要手动清理缓存。但是当使用系统外的工具修改数据时（比如直接通过数据库工具修改了表数据），此时系统不会侦测到数据发生变化，需要手动清理缓存。
缓存管理界面如下：
## 清理缓存{#clear-cache}
缓存管理界面提供了以下两种清除缓存的方式：
1. 点击单个缓存类型**操作**列下的**清除**按钮，清除该缓存类型的缓存
2. 点击工具栏的**清除全部**按钮，清除所有缓存类型的缓存
:::tip
1. 系统正常运行时，不需要手动清理缓存，只有在系统外部修改数据源内容时才需要清理和数据源相关的数据库缓存、元数据缓存以及query查询缓存
2. 停留在缓存管理界面时，缓存记录不会自动刷新，需要通过**刷新**来更新缓存记录，而**删除**会将缓存结果删除，并将缓存记录清空
3. 缓存是分模块存储在内存和[工作目录](../../devops/install/basic-install/workdir-and-defdb.md)下的cache目录中的，如果手动删除工作目录下的缓存文件，刷新缓存管理界面，缓存记录也会更新
4. 可参考[如何禁用模型查询的缓存](../../data-gov/faq/howto-disable-query-cache.md)，禁用模型的query查询缓存
:::
## 缓存类型介绍{#type}
缓存分为以下七种类型：
| 缓存类型 | 作用 |
| :---------| :-------- |
| 数据库缓存 | 缓存数据库中有哪些物理表、schema、表结构等信息 |
| 最慢SQL记录 | 记录当前系统中耗时较长的SQL，并存储在`default`数据库中的`SZSYS_MON_SLOWEST_SQLS`表中，可以通过[SQL查询](../../data-gov/sql-model.md)的方式查看，便于查看和分析系统中哪些SQL执行较慢，并进行优化|
| 兼容IE的JS缓存 | 由于ie11中只支持es5,所以通过ie访问系统时，会将js从es6转换成es5，并缓存下来，提高下次访问速度 |
| 标签缓存 | 缓存元数据标签到内存中，加快查询速度 |
| 元数据缓存 | 缓存元数据内容到内存中，包括报表、仪表板等相关的业务对象 |
| 数据文件缓存 | 按照项目缓存上传的csv/xlsx等文件生成的相关结构信息 |
| query查询缓存 | 缓存query的查询结果，当再次查询时，如果查询条件相同，直接返回缓存的结果 |
:::tip
存储最慢SQL记录的规则如下：
1. 当SQL记录不超过100条时，系统会全部记录
2. 当SQL记录条数超过100条时，系统会将当前SQL记录中耗时最长的第100条SQL耗时作为阈值，执行时间超过阈值的SQL会记录下来，已经记录的数据不会删除，同时按照插入后的数据情况，将阈值更新为插入后的数据中耗时最长的第100条。比如前100条SQL记录耗时最长和最短为2s和1s，阈值为1s，此时有个SQL耗时1.1s，那么该SQL会记录下来，同时将阈值提高到1.1s
:::
---
url: "https://docs.succapp.com/v5/guide/sys-settings/performance/cluster.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/cluster"
title: "集群状态"
---
---
order: 1
---
# 集群状态
[集群部署](../../devops/cluster/README.md)完成后，可访问**系统设置** >**运维** > **集群状态**监控各集群节点的运行情况，该列表每3秒轮询获取各节点的运行指标，并以表格的形式显示，便于运维人员了解当前系统的运行状态，并能根据列表中的警示信息，快速定位故障所在。
## 列表信息{#list-info}
### 默认显示列{#columns}
`集群监控`列表默认显示列信息如下：
| 列名 | 说明 |
| :---- |:----|
| 状态 | 标注主从节点并展示集群节点的运行状态，分为：`正常`、`启动中`、`关机`、`失联`、`禁用`，鼠标停留时会悬浮显示该节点的[警示信息](#警示信息及解决方法) |
| URL | 未经过[负载平衡](../../devops/cluster/README.md#load-balancing)的集群节点的内网访问地址，点击可直接跳转至该节点首页 |
| 启动时间 | 系统的启动时间 |
| 心跳时间 | 上一次连接数据库并记录并更新自己状态信息的时间 |
| 网络延迟 | 与当前节点间的网络延迟 |
| 接收消息数 | 接收到的集群消息数 |
| 接收数据 | 通过集群通讯接收到的数据包大小 |
| 发送消息数 | 向其他集群成员发送的集群消息数 |
| 发送数据 | 向其他集群成员发送的数据包大小 |
| JVM最大内存 | 系统设置的JVM最大内存，可参考[环境变量设置](../../devops/install/middleware/tomcat.md#env) |
| Web会话数 | 当前系统Session数量 |
| 物理内存 | 服务器物理内存总容量 |
| %CPU JVM | JVM进程CPU占用百分比 |
| 磁盘可用空间 | 在工作目录所在磁盘分区中，JVM进程可以使用的空间 |
### 可选显示列{#optional}
点击列头行末尾的图标，可展开`调整显示列`勾选框，根据运维需要自由选择列表的显示列
**系统运行指标**
| 列名 | 说明 |
| :---- |:----|
| 所属主节点 | 集群中的主节点URL，应与`状态`中的`主`标识节点一致 |
| 产品版本 | 当前使用war的版本，所有节点前2位应一致 |
| 工作目录 | 安装时设置的[工作目录](../../devops/install/basic-install/workdir-and-defdb.md#set-workdir)路径 |
| 部署路径 | Web容器部署路径 |
| 集群通信地址 | 内网集群节点[通讯的地址和端口](../../devops/cluster/README.md#config-firewall)，集群节点是使用的专用的通信地址和端口进行通信的，没有使用Web端口 |
**服务器运行指标**
| 列名 | 说明 |
| :---- |:----|
| 物理内存 | 服务器物理内存总容量 |
| 物理内存空闲 | 服务器物理空余内存量 |
| % CPU | 服务器的CPU占用百分比 |
| CPU 核数 | 服务器的CPU核心数量 |
| 进程ID | JVM进程ID |
| OS用户 | 启动JVM的操作系统用户名 |
| 磁盘总空间 | 工作目录所在的磁盘分区总空间 |
| 磁盘空余空间 | 工作目录所在的磁盘分区空余空间(包含JVM进程不可用部分) |
**mfc协议相关相关信息**
| 列名 | 说明 |
| :---- |:----|
| initial\_hosts | 系统启动集群初始化时最初要连接的集群节点，由于云平台（如阿里云）通常禁用IP组播，所以系统默认使用TCP协议进行集群通信，集群初始化时需要有最初始的连接节点设置，节点启动后会把自己的通信地址写入数据库，其它节点启动时会读取并正确设置自己的initial\_hosts |
| dynamic\_hosts | 记录的是用户没有在`initial_hosts`中设置的集群节点，可以理解为曾经加入过集群的、的或后来新加入到集群的节点 |
| UFC\_AverageTimeBlocked | 消息发送的阻塞平均时间（以毫秒为单位）|
| UFC\_NumberOfBlockings| 消息发送的阻塞次数 |
| UFC\_NumberOfQueuedMessages | 当前排队的消息数 |
| UFC\_QueuedSize | 所有目的地的所有当前排队的消息的总大小 |
| UFC\_NumberOfQueuings | 消息已排队的次数 |
## 警示信息及解决方法{#warning-and-solution}
当节点出现故障影响集群通讯时，`状态`列中的图标和状态信息会发生改变，同时鼠标停留时会悬浮显示警示信息，根据故障的严重程度分为警告类和错误类
### 警告类{#warning}
集群中某一节点存在可优化的配置项或暂时失联，一般不会影响其他节点，此时`状态`列中图标为黄色感叹号
具体存在以下几种情况：
1. **系统诊断警告**
集群通讯正常但**系统信息** > **系统诊断**中存在需要修改的配置项
**解决方法：**
按照警示中的建议，修改对应的配置，并重新启动tomcat
2. **启动超时，可能宕机或者断开数据库连接**
当节点启动过程中，服务器宕机或数据库连接异常，会导致列表中该节点的状态停留在`启动中`，超时后会出现该警示，此时节点`状态`为`启动中`
**解决方法：**
1. 检查服务器是否宕机
2. 检查该节点ip的数据库连接是否正常，例如数据库连接被阻塞或host发生改变
3. **可能宕机或者断网**
1. 节点网络服务中断，无法与其他节点通讯，此时节点`状态`为`失联`
2. 该节点被非正常关机（如用 `kill -9 PID` 杀死tomcat进程）
**解决方法：**
1. 检查并重启该节点服务器的网络服务
Linux下运行
```sh
service network restart
```
网络服务恢复后，不需要重启tomcat，失联节点会自动重新加入集群
2\. 若存在节点非正常关机的情况，可不必理会，一小时后系统会恢复正常状态。也可以将被关闭的节点重新启动然后正常关闭它
4. **ping超时，可能已经宕机**
该节点服务器宕机或与其他节点网络未联通
**解决方法：**
1. 确认该节点服务器是否宕机
2. 确认该节点网络服务是否正常启动
3. 确认该节点是否还与其他节点处于同一网段
### 错误类{#error}
出现较为严重的故障导致集群功能出现异常，例如出现多个主节点或集群功能被禁用，此时`状态`列中图标为红底交叉图案
具体存在以下几种情况：
1. **集群中有多个主节点，这通常是因为网络不通导致的，请检查网络设置或防火墙设置**
集群节点间的通讯出现故障，导致出现了多个主节点
**解决方法：**
1. 确认所有集群成员间的网络连接是否正常
2. 确认7800-7805端口是否正常开放，可参考[开放集群通讯端口](../../devops/cluster/README.md#config-firewall)
3. 确认所有集群成员的防火墙是否设置了黑名单
2. **当前节点无法连接其它节点，请检查网络设置或防火墙设置**
1. 当前节点与其他集群节点网络不同
2. 最近一小时内存在非正常关机的节点（如用 `kill -9 PID` 杀死tomcat进程），此时进程退出前无法更新数据库的状态，导致当前节点以为被杀死的进程还在运行
**解决方法：**
3. 确认网络通畅，防火墙开放7800～7805这几个端口
4. 如果存在非正常关机节点，可不必理会，一小时后系统会恢复正常状态。也可以将被关闭的节点重新启动然后正常关闭它（如 `kill PID`）
3. **未启用集群，存在其他启用集群的节点**
该节点集群功能被禁用，此时节点状态为`禁用`
**解决方法:**
确认[环境变量](../../devops/install/middleware/tomcat.md#env)中是否存在`-Dsucc.cluster.enable=false`，该变量会禁用集群功能，修改为`-Dsucc.cluster.enable=true`并重启tomcat
---
url: "https://docs.succapp.com/v5/guide/sys-settings/performance/jvmthreads.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/jvmthreads"
title: "线程堆栈"
---
---
order: 2
---
# 线程堆栈
**线程堆栈**用于查看系统的JVM线程堆栈信息，监控系统底层运行状态，便于出现问题时的跟踪定位
## 线程堆栈列表{#list}
1. **线程堆栈**：默认状态下显示线程信息，格式为`Thread[线程名称，优先级，线程组]-线程操作`，点击可展开查看该线程的堆栈情况
2. **堆栈层**：线程的堆栈数量
3. **用户**：执行线程对应操作的SuccBI用户ID，存在以下特殊情况
- `system`：通常都是一些系统的范围，不是直接由登录用户发起的线程，例如：系统日志保存到数据库中、计划任务运行等
- `空值`：没有对应的登录用户的线程，例如tomcat的线程
4. **时长**：线程已经执行的时间，只针对活跃状态，可理解为线程执行某个操作的耗时
5. **状态**：线程的运行状态，存在以下情况
- `运行`：正在执行
- `等待`：休眠等待其他线程唤醒
- `阻塞`：受阻塞并且正在等待监视器锁
- `SQL`：运行中且正在执行SQL
6. **操作**：操作线程对应的任务，分为`查看`、`停止`
- `查看`：查看线程对应的任务日志
- `停止`：停止该任务
## 操作{#operate}
1. 导出：导出当前列表中的线程堆栈信息
2. 刷新：手动刷新显示列表
3. 展开全部：展开所有线程，显示堆栈信息
4. 自动刷新：当线程堆栈发生变化时，自动刷新显示在列表中，默认勾选
5. 只展示sql：只显示`状态`为`SQL`的线程，默认不勾选
6. 只显示运行的：只显示当前正在执行业务逻辑的线程，默认勾选
---
url: "https://docs.succapp.com/v5/guide/sys-settings/performance/console.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/console"
title: "技术日志"
---
---
order: 3
---
# 技术日志
**技术日志**用于查看系统输出的日志信息，同时也支持对系统的日志级别进行快速修改，便于出现问题时的跟踪定位
## 控制台操作{#operate}
1. 清空：清空控制台的日志信息
2. 刷新：手动刷新控制台
3. 复制：复制当前控制台的日志信息
4. 自动刷新：有新的日志输出时，自动刷新显示在控制台中，默认勾选
5. 自动换行：当单条日志长度超过控制台宽度时自动换行，默认勾选
6. 锁定滚动：锁定控制台消息的滚动，在查看某条特定日志时使用，默认不勾选
## 日志级别{#log-level}
修改日志记录范围及其级别，提供[生产环境](#生产环境)、[调试环境](#调试环境)两种模式选择
### 生产环境{#production-environment}
在`日志级别`下拉列表中选择`生产环境日志`，此时所有包路径的的日志级别均为`ERROR`，适合生产环境使用
### 调试环境{#debugging-environment}
在`日志级别`下拉列表中`调试环境`部分，可对日志包路径及其级别进行编辑，日志包路径默认提供`数据库日志`、`脚本日志`、`权限日志`、`登录日志`、`单点登录日志`、`登录过滤日志`、`com.succez`
日志级别由低到高分别为：`TRACE`、`DEBUG`、`INFO`、`ERROR`
1. **TRACE**：级别最低，一般不使用
2. **DEBUG**：比**TRACE**级别高，在调试时使用，能更详细的了解系统运行状态
3. **INFO**：输出系统应该出现的正常状态信息
4. **ERROR**：输出系统出现的错误和异常，适合生产环境使用
:::warning
日志级别设置为TRACE、DEBUG可能会严重影响系统性能，且产生的日志文件会占据大量磁盘空间
:::
默认提供的日志级别不满足需求时，可以点击`添加`，在`添加日志级别`对话框中填写`包路径`和`日志级别`手动添加，例如添加包路径为`com.succez.commons.cluster`、级别为`DEBUG`的日志级别
## 下载日志{#download-log}
下载[工作目录](../../devops/install/basic-install/workdir-and-defdb.md#defjdbc)中`logs`下的日志文件
## 集群{#cluster}
### 将当前日志设置作用到集群其他节点{#effect}
组成集群以后，节点访问是通过负载均衡服务进行路由转发，在外部不易访问指定的节点，而在内网配置，需要登录每台机器也比较繁琐，因此系统提供了`将当前日志设置作用到集群其他节点`的功能
在集群节点配置日志级别后，点击`将当前日志设置作用到集群其他节点`，弹出如下图所示对话框，提示`确认要将当前的日志级别设置应用到集群的其它X个节点吗？`
选择`是`，即可将当前的日志级别设置应用到其它集群节点
---
url: "https://docs.succapp.com/v5/guide/sys-settings/performance/logmanage.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/logmanage"
title: "日志管理"
---
---
order: 5
---
# 日志管理
在系统运行过程中，日志作为记录系统行为的载体，承载着调度跟踪、操作审计和文件追溯等关键用途。随着业务持续运行，日志文件的积累不仅会占用大量存储资源，更会影响系统检索效率。
SuccBI在系统设置中提供了日志管理的功能，通过简单的配置，可以实现对**系统日志**、**调度日志**、**文件历史**的手动清理和定时自动清理。
## 系统日志{#log-system}
系统日志会记录系统的所有操作日志，包括用户访问、调用接口、上传下载等，日志存放在[系统日志表](/sys-tables/sys/LOG_SYS)中。
系统日志模块提供`日志记录级别配置`功能，并支持`立即清理`和`定时调度`两种日志清理机制，实现对用户操作轨迹的全周期管控。
- **日志记录级别**：设定系统日志记录的日志信息级别，分为`OFF`、`FATAL`、`ERROR`、`IMPT`、`INFO`、`VERB`和`ALL`，日志记录越详细，用户操作时产生的日志越多，日常生产环境建议使用`INFO`级别的日志记录，日志级别描述如下：
|日志级别|级别描述|
|:-:|:-:|
|OFF|关闭|
|FATAL|严重|
|ERROR|错误|
|IMPT|重要|
|INFO|信息|
|VERB|详细|
|ALL|所有|
- **当前日志表大小**：记录[系统日志表](/sys-tables/sys/LOG_SYS)当前行数。
- **刷新**：手动更新当前系统日志的行数。
- **立即清理**：点击立即清理会弹出策略窗口，在输入框设置`保留最近天数`后，点击确认就会删除早于设定天数的历史系统日志，然后自动刷新系统日志数据。
- **自动清理日志**：启用自动清理日志功能后，通过设置`日志保留周期`及`清理计划`，系统将定期执行自动化清理任务，实现日志数据的策略化维护与系统资源优化。
- **保留最近天数**：设置系统日志保留的最大天数。
- **清理计划**：设置执行自动清理的计划任务，通过调整计划的执行频次可以控制系统日志的清理周期，详细设置参考[调度管理](../../schedule/README.md)。
## 调度日志{#dispatching-log}
调度日志会记录计划和任务的全部执行情况，日志存放在[任务运行详细日志表](/sys-tables/sys/TASK_RUNLOGS)、[任务运行记录表](/sys-tables/sys/TASK_RUNS)、[计划运行详细日志表](/sys-tables/sys/SCHEDULE_RUNLOGS)以及[计划运行记录表](/sys-tables/sys/SCHEDULE_RUNS)中；
调度日志模块支持独立管理不同执行频率的计划任务日志，结合`立即清理`和`定时调度`清理机制，统一管控分散在多个日志表中的调度执行记录。
- **当前日志表大小**：所有调度日志行数总和。
- **刷新**：手动更新当前调度日志的总行数。
- **立即清理**：点击立即清理会弹出策略窗口，设置`清理策略`后，系统将定向清除历史调度日志，然后自动刷新统计数据。
- **自动清理日志**：自动清理日志启用后，可以通过`清理策略`定义清理规则，配合`清理计划`，实现自动清理调度日志。
- **清理策略**：系统会根据[计划任务](../../schedule/README.md)设置的定时执行频率自动划分执行频率等级，高频任务（如每分钟执行一次）和低频任务（如每月执行一次）产生的日志量不一样，通常会有不同的日志清理策略，在这里可以根据执行频率分级分别配置保留策略，具体分级如下：
|分级策略|清理对象|
|:-:|:-:|
|年级别|年度或者跨年执行的调度日志|
|月级别|月度周期执行的调度日志|
|日级别|每日或每周固定执行的调度日志|
|小时级别|小时级高频调度日志|
|分钟级别|分钟、秒级实时调度日志|
## 文件历史{#file-history}
文件历史中记录着元数据文件的每个版本信息，每次文件存在修改都会多一条文件历史信息，记录存放于[历史版本表](/sys-tables/meta/META_REVISIONS)。
文件历史模块通过`保留最近天数`和`自动压缩版本`两种清理规则，结合`立即清理`和`定时调度`清理机制，实现对历史版本的精准管控，有效避免多版本迭代产生的存储冗余问题。
- **当前日志表大小**：记录[历史版本表](/sys-tables/meta/META_REVISIONS)当前行数。
- **刷新**：手动更新当前历史版本数据行数。
- **立即清理**：点击立即清理会弹出策略弹窗，设置`保留最近天数`和`自动压缩版本`后，系统将定向清除历史版本数据，然后自动刷新统计数据。
- **自动清理日志**：自动清理日志启用后，通过预设保留最近天数和自动压缩版本两项清理策略，配合`清理计划`，实现文件历史版本的智能化管理，在保障必要数据留存的同时有效释放存储空间。
- **清理策略**：设置文件历史清理规则，当`保留最近天数`和`自动压缩版本`同时启用时，会依据两种规则复合清理，日常生产环境建议只启动`自动压缩版本`。
- **保留最近天数**：设置文件历史版本保留的最大天数。
- **自动压缩版本**：勾选后会保留最近七天的所有文件历史版本，超过七天且小于三十天之内的一个小时保留一个版本，超过三十天的一天保留一个版本。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/more"
title: "更多"
---
---
order: 5
navTitle: 更多
---
# 更多
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/i18n.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/i18n"
title: "国际化"
---
---
order: 1
navTitle: 国际化
---
# 国际化
SuccBI支持国际化，默认有中文和英文这两种语言，可以解决不同地区客户访问系统的需求。
## 系统默认语言{#languageSetting}
系统默认支持简体中文和英语这两种语言。在**系统设置**>**更多**>**国际化**中可以配置默认语言设置，点击保存后，让设置生效。
### 使用浏览器的语言设置{#useBrowserLanguage}
开启使用浏览器的语言设置后，若没有在个人设置中设置语言，系统会自动使用当前浏览器的语言设置。关闭该设置后，将会使用系统默认语言设置。
### 系统默认设置{#defaultLanguage}
系统优先使用个人设置中的语言设置，其次是对浏览器的语言设置，最后是系统的默认语言。
## 配置国际化代码{#i18nCode}
系统支持可以自定义国际化代码，选择其中一种语言，进入自定义页面添加需要自定义的国际化，也可以查阅相关国际化内容。
### 自定义国际化内容{#customizeContent}
可以在界面上自定义国际化的内容，操作包括：
- **增加国际化内容**，有两种操作方式：
- 直接修改国际化的Value值，修改后会自动生成一条新的国际化键值对
- 点击工具栏**新增**按钮，新增一条国际化，手动赋值，可以提前赋值好需要修改的Key
- **删除国际化内容**：修改过或者新增的国际化可以删除，选中某一条点击工具栏的**删除**按钮，即可删除。其中，系统默认的国际化是无法删除的
- **查询国际化内容**：在顶部工具栏右边的搜索框中直接输入想要搜索的内容即可
- **重置自定义国际化内容**：点击工具栏的**重置**按钮，会将当前语言的所有自定义国际化内容都删掉，请谨慎操作
### 直接在约定位置增加国际化{#i18nDevelopment}
在国际化做一些自定义修改，比如增加自定义中文国际化、英文国际化，保存后会在系统数据`/sysdata/settings/`文件夹下生成一个i18n文件夹，文件夹内部文件形式如下：
```ts
├──custom.en.properties //自定义英文国际化
└──custom.zh_CN.properties //自定义中文国际化
```
如果在这里面直接修改了对应语言的i18n文件，在项目设置中的自定义国际化界面也可以看到修改后的国际化条目。
:::warning
i18n目录下的所有文件名称均为系统命名规范，不要重命名。否则系统是无法读出用户手动在文件中编辑的国际化
:::
:::tip 小知识
为什么用`i18n`来表示国际化呢:question:
i18n，其来源是英文单词`internationalization`的首末字符i和n，18为中间的字符数，是`国际化`的简称
:::
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services"
title: "外部服务"
---
---
order: 2
navTitle: 外部服务
---
# 外部服务
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/email.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/email"
title: "邮件"
---
---
order: 1
navTitle: 邮件
---
# 邮件
SuccBI的部分产品功能（如[仪表板邮件分享](https://docs.succapp.com/v5/co/share#邮件分享)和SuperPage的[发送邮件交互](../../../app/superpage/design/action/send-email.md)）会使用邮件发送服务，需要配置外部邮件发送服务才能正常发送邮件，具体设置页面如下图：
## 邮件配置{#configuration}
具体配置参数如下：
- **发送方式**：邮件发送服务使用协议，可选择`smtp`或`smtps`作为邮件发送协议。
- **SMTP服务器**：发送邮件服务器地址，常用的SMTP服务器地址参见[常见邮件服务器地址](https://www.cnblogs.com/dengzhangkun/p/4168046.html)。
- **SMTP端口**：SMTP服务器端口，当发送方式为smtp时默认为`25`端口，发送方式为smtps时默认端口为`465`端口。
- **SMTP用户**：邮件发送服务的登录账户，配置外部邮件发送服务前，账户需先开启`SMTP服务`，并配置相应的SMTP服务器。
- **SMTP密码**：邮件发送服务的登录密码。
:::tip
配置完毕后可点击**测试**按钮对邮件发送服务进行测试，若提示`测试邮件配置通过`，表示邮件发送服务可以正常发送邮件。
:::
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/message.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/message"
title: "短信"
---
---
order: 2
navTitle: 短信
---
# 短信
短信功能可以设定系统中[短信验证码登录](../../security/securityconf.md#captcha)、[短信验证码重置密码](../../../dev/references/web-api/me/sendResetPasswordCode.md)等短信发送服务的配置，用户可配置[阿里云](#alicloud)、[腾讯云](#tencent-cloud)短信服务进行短信发送，也可通过[脚本](#script)自定义短信的发送，具体设置页面如下图：
## 阿里云{#alicloud}
系统支持配置阿里云短信服务进行短信发送，具体配置项如下：
- **AccessKeyId**：阿里云管理的云账号ID，获取方式请参见[获取阿里云AccessKey ID和AccessKey Secret](https://help.aliyun.com/knowledge_detail/38738.html)
- **AccessSecret**：阿里云管理的云账号密钥,获取方式请参见[获取阿里云AccessKey ID和AccessKey Secret](https://help.aliyun.com/knowledge_detail/38738.html)
- **短信签名**：指定阿里云账号下的短信签名，只有已添加、并通过审核的短信签名才能使用。更多信息，请参见[阿里云短信签名简介](https://help.aliyun.com/document_detail/108072.html)
- **默认模板ID**： 阿里云中的短信模板ID,当发送消息时候没有指定模板id的时候使用默认短信模板ID，详细信息，请参见[短信模板简介](https://help.aliyun.com/document_detail/108086.html)
## 腾讯云{#tencent-cloud}
系统同样支持使用腾讯云短信服务进行短信发送，具体配置项如下：
- **secretId**：腾讯云管理的API密钥Id，获取方式可见[申请安全凭证](https://cloud.tencent.com/document/product/382/38769#1.-.E7.94.B3.E8.AF.B7.E5.AE.89.E5.85.A8.E5.87.AD.E8.AF.81)
- **secretKey**：腾讯云管理的API密钥,获取方式可见[申请安全凭证](https://cloud.tencent.com/document/product/382/38769#1.-.E7.94.B3.E8.AF.B7.E5.AE.89.E5.85.A8.E5.87.AD.E8.AF.81)
- **sdkAppid**：腾讯云短信服务应用管理界面为应用分配的ID,获取方式可参照[创建应用](https://cloud.tencent.com/document/product/382/37808)
- **短信签名名称**：指定腾讯云账号下的短信签名，必须是已添加、并通过审核的短信签名,短信签名的获取方式可参照[腾讯云短信签名](https://cloud.tencent.com/document/product/382/37794)
- **默认模板ID**：腾讯云中的短信模板ID， 当发送消息时候没有指定模板id的时候使用默认ID,模板ID的获取可参照[创建正文模板](https://cloud.tencent.com/document/product/382/37795)
## 脚本{#script}
系统还可通过自定义脚本实现短信的发送，用户可配置`messager.action.ts`脚本实现自定义短信发送，相关脚本写法可参照[后端脚本开发](../../../dev/script/backend/README.md)。
## 测试发送{#test}
用户配置完毕后，点击**测试发送**按钮可进行短信发送测试，输入**手机号码**以及**短信模板参数**后即可实现短信发送的测试。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/gis.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/gis"
title: "GIS"
---
---
order: 3
navTitle: GIS
---
# GIS
SuccBI的部分产品功能(如SuperPage的[地点标注](../../../app/superpage/components/embed/gisPOIMarker.md)组件和[移动轨迹](../../../app/superpage/components/embed/gispath.md)组件)需要用到GIS地图，系统支持配置[高德地图](#gaode)作为GIS地图服务提供者。具体设置页面如下：
## 高德地图{#gaode}
具体配置参数如下：
- **JS API Key**：JS API应用密钥，前端浏览器显示嵌入的GIS地图时可以进行配置，JS API Key的获取方法可参考[JSAPI](https://lbs.amap.com/api/javascript-api/guide/abc/prepare)。
- **Web API Keys**：web服务密钥，当后端数据加工需要根据地质获取所在经纬度时，可以进行获取配置，获取方法可参考[web服务API](https://lbs.amap.com/api/webservice/guide/create-project/get-key)。
- **SSL**：高德地图支持使用https协议，当网络环境只允许https时可勾选此选项，系统将总是使用https协议。
- **底图样式**：高德地图提供了丰富的底图样式，可使用默认的样式风格，也可点击下方的**添加**按钮，根据[标准样式主题](https://lbs.amap.com/demo/javascript-api/example/personalized-map/set-theme-style)中的主题样式，填入对应的`主题代码`和`样式名称`即可。
:::tip
底图样式自定义完毕后，可在SuperPage的[地点标注](../../../app/superpage/components/embed/gisPOIMarker.md)和[移动轨迹](../../../app/superpage/components/embed/gispath.md)组件中，通过**属性栏**>**样式**>**地图**>**底图风格**选择自定义的底图样式。
:::
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/ocr.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/ocr"
title: "文字识别"
---
---
order: 4
navTitle: 文字识别
---
# 文字识别
SuccBI提供文字识别功能对`身份证`、`银行卡`、`驾照`等证件或照片进行识别，用户可设置[阿里云](#alicloud)、[百度](#baiducloud)或[腾讯证照识别](#tencentcloud)作为默认文字识别服务在SuperPage中进行[OCR识别](../../../app/superpage/design/action/OCR.md)，具体设置页面如下图：
## 阿里云证照识别{#alicloud}
系统支持配置[阿里云证照识别](https://help.aliyun.com/document_detail/30403.html)进行文字识别，具体配置参数如下：
- **AppCode**：阿里云管理的API认证信息，查看方法可见[查询API调用认证信息](https://help.aliyun.com/document_detail/157953.html)。
## 百度证照识别{#baiducloud}
系统同样支持[百度证照识别](https://cloud.tencent.com/document/product/866/)进行文字识别，配置参数如下所示：
- **API Key**：百度云管理应用的的API密钥，获取方法参照[创建应用](https://cloud.baidu.com/doc/OCR/s/dk3iqnq51#2-%E5%88%9B%E5%BB%BA%E5%BA%94%E7%94%A8)。
- **Secret Key**：百度云管理应用的密钥ID，获取方式参照[创建应用](https://cloud.baidu.com/doc/OCR/s/dk3iqnq51#2-%E5%88%9B%E5%BB%BA%E5%BA%94%E7%94%A8)。
## 腾讯证照识别{#tencentcloud}
系统还可通过[腾讯证照识别](https://cloud.tencent.com/document/product/866/17622)进行文字识别，具体配置参数如下：
- **API Key**：腾讯云管理的API密钥ID，获取方法可见[申请安全凭证](https://cloud.tencent.com/document/product/866/33520#1.-.E7.94.B3.E8.AF.B7.E5.AE.89.E5.85.A8.E5.87.AD.E8.AF.81)。
- **Secret Key**：腾讯云管理的API密钥，获取方式可见[申请安全凭证](https://cloud.tencent.com/document/product/866/33520#1.-.E7.94.B3.E8.AF.B7.E5.AE.89.E5.85.A8.E5.87.AD.E8.AF.81)。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/doc-converter.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/doc-converter"
title: "文档转换"
---
---
order: 5
navTitle: 文档转换
---
# 文档转换
文档转换主要用于设置系统中的**文档转换服务**、**截图服务**以及[缩略图服务](#thumbnail-service)的启用情况，具体设置页面如下图：
## 文档转换服务器地址{#translation-server}
在查看docx、pptx等文件时需要将文档进行转换，以适配不同设备的不同软件打开文件的效果。默认为空，表示使用系统内置的转换服务（使用纯java转换，存在一定失真），推荐配置为外部部署的[文档转换服务](../../../devops/install/tool-services/documents-converter.md)地址。
## 截图服务器{#screenshot-server}
用于系统缩略图的生成以及后端导出报表仪表板时一些图片的生成。这里需要填写 Browserless
服务地址，对应系统设置项 `sys.basic.browserServerUrl`，例如：
```text
ws://127.0.0.1:3000/chromium/playwright
```
部署方式和排查说明见[截图服务配置](../../../devops/install/tool-services/screenshot-service.md)。
## 禁用缩略图服务{#thumbnail-service}
缩略图服务会在用户修改了报表、仪表板等对象时自动在后台生成新的缩略图，勾选禁用后不影响产品正常使用，可以节省系统资源。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/docs-server.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/docs-server"
title: "产品手册"
---
---
order: 6
navTitle: 产品手册
---
# 产品手册
SuccBI产品界面中有很多上下文帮助链接，如下图添加数据源时可以点击对话框左下角的`帮助`链接获取帮助信息。
当SuccBI部署在内网中无法访问上下文帮助文档服务器`https://docs.succbi.com/`时，可以在内网部署文档服务器，并在这里配置好文档服务器地址。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/intranet-agent.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/intranet-agent"
title: "内网代理"
---
---
order: 9
navTitle: 内网代理
---
# 内网代理
SuccBI的一些功能需要用到互联网服务，当系统部署在内网，用户使用内网登录无法正常使用[短信验证码登录](../../security/securityconf.md#captcha)以及SuperPage的[地点标注](../../../app/superpage/components/embed/gisPOIMarker.md)、[移动轨迹](../../../app/superpage/components/embed/gispath.md)等功能时，可以使用网关或反向代理服务器将互联网服务代理到内网，并在内网代理中进行配置，保证功能正常使用。
## 代理配置{#Agent}
- **当前网络**：访问互联网服务时的发起地址，配置内网代理时，根据发起访问位置不同，当前网络可配置为`内网访问地址`，或设置为`默认`。
- **默认**：若互联网服务的访问总是通过系统内部发起，如[短信验证码登录](../../security/securityconf.md#captcha)，配置内网代理时，可将当前网络选择为默认，访问对应的互联网服务时会强制使用内网代理。
- **内网访问地址**：若互联网服务的访问总是通过浏览器客户端发起，如SuperPage的[地点标注](../../../app/superpage/components/embed/gisPOIMarker.md)显示高德地图，配置内网代理时，可将当前网络配置为内网访问地址。用户使用内网登录访问时，会通过内网代理访问互联网服务，若通过域名或外网地址登录访问，不需要使用内网代理，直接进行访问。
- **外网服务**：系统需要访问的互联网服务地址，用户可自行配置外网服务地址，或点击下方[高德地图代理](#gaode)和[阿里云短信](#alicloud)按钮快捷获取相应地址。
- **内网代理**：互联网服务对应的反向代理地址，当用户对互联网服务进行访问时，会跳转至反向代理地址进行访问。
:::tip
在进行内网代理配置前，需先使用网关或反向代理服务器将互联网服务代理到内网，反向代理的配置参见[基于nginx的反向代理](../../../devops/cluster/reverse-proxy.md#基于nginx的反向代理)。
:::
## 高德地图代理{#gaode}
点击**高德地图代理**按钮，会在外网服务中添加`https://api.amap.com`域名供用户进行内网代理的配置，高德地图代理的配置参见[在内网访问高德地图](../../../devops/install/tool-services/proxy-gaode.md)。
## 阿里云短信{#alicloud}
点击**阿里云短信**按钮，会在外网服务中添加`dysmsapi.aliyuncs.com`域名供用户进行内网代理的配置，阿里云短信代理的配置参见[内网使用阿里云短信服务]()。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/more/remote-services/cdn.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/remote-services/cdn"
title: "CDN"
---
---
order: 10
navTitle: CDN
---
# CDN
当系统部署所在服务器的性能和带宽有限时，可以使用[CDN服务](../../../devops/install/cloud-platform/CDN.md)加快用户访问系统的速度，具体配置页面如下：
## 启用CDN{#Enable}
勾选后，静态资源（包括js、css、图片等）会使用配置的**CDN域名**进行加载，这样可以加速页面访问并减轻服务器负载，注意：
1. 启用前确保已经进行CDN域名的配置，否则可能导致系统无法访问。
2. 系统内所有静态资源的请求地址都会使用CDN域名，所以同时还需要启用安全设置中的[启用跨域](../../security/securityconf.md#cross-domain)。
## CDN域名{#domain}
CDN加速域名地址，域名接入方法参见[接入CDN服务](../../../devops/install/cloud-platform/CDN.md#subscribe)。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/project/README.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/project"
title: "README"
---
---
order: 5
navTitle: 项目
---
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/sys-settings/project/backup.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/backup"
title: "备份"
---
---
order: 1
navTitle: 备份
---
# 备份
系统中通常包含系统元数据，系统设置及用户权限信息等数据信息。一些重要的数据如果丢失或者损坏，会造成难以挽回的后果。为了确保数据的可用性、完整性和保密性，可以在**项目列表**>**系统设置**>**项目**中对系统数据进行备份操作。
用户可以设置[**手动备份**](#manual)和[**自动备份**](#auto)两种备份方式，备份完成后可在当前页面下方的**备份日志**列表中下载备份包。项目备份界面如下所示：
## 手动备份{#manual}
点击**立即备份**，即可备份当前时刻的系统元数据。
:::tip 说明
备份会将系统中所有项目进行备份，若希望只恢复一个项目，可在[恢复](./restore.md#server-package)时勾选指定项目进行恢复。
:::
## 自动备份{#auto}
勾选**启用定时备份**，可以选择备份的[**时间计划**](../../schedule/README.md)。如选择备份的时间计划为**早晨5点**，到指定时间时，系统会自动备份。
- **保留备份包时长**：对备份包的保留时间进行设置，可以将版本低或长期使用不到的备份包自动删除以节省磁盘空间。默认保留备份包时长为30天。
- **备份日志**：备份日志是对备份过程的记录，可以查看每一次备份完成的**状态**、**时间**、**耗时**、**备份者**等信息。在备份日志中，还能够对备份包进行**下载**和**删除**操作。
- **备份包路径**：[工作目录](../../devops/install/basic-install/workdir-and-defdb.md#dir)`/clusters-share/backup`下。
---
url: "https://docs.succapp.com/v5/guide/sys-settings/project/restore.md"
htmlUrl: "https://docs.succapp.com/v5/sys/settings/restore"
title: "恢复"
---
---
order: 2
navTitle: 恢复
---
# 恢复
:::warning 警告
1. 不要在生产环境上直接进行恢复！若确实需要通过备份包找回丢失的文件，最好先恢复到测试环境后，再把需要还原的内容导入到生产环境。
2. 如果生产环境完全损坏，最好先用数据库备份工具将重要数据做好备份，然后再执行恢复操作。
:::
用户可以选择以下两种恢复方式：
1. [选择服务器上的备份包恢复](#server-package)
2. [上传备份包恢复](#upload-package)
## 选择服务器上的备份包{#server-package}
在备份日志中，可以看到服务器中已经备份的包，在恢复的时候，点击下拉框，可以看到服务器中的备份包列表，选择对应时刻的备份包即可进行恢复。
- **恢复用户和权限数据**：使用备份包中的用户、机构、用户组、权限数据覆盖当前服务器中的数据。默认不勾选。是否恢复用户和权限数据，可参考文档[迁移权限数据](../../devops/upgrade/migrate.md)。
- **恢复系统元数据**：恢复备份包中的系统设置数据，默认不勾选。
- **选择需要恢复的项目**：默认恢复备份包中的所有项目，可以根据实际情况选择恢复项目。
:::tip
当选择要恢复的项目为系统项目，如`sysdata`时，仅仅会覆盖扩展、主题和系统设置；当选择恢复的项目为其他项目，如`DEMO`时，存在同名项目会覆盖同名项目。
:::
## 上传备份包{#upload-package}
在[系统迁移](../../devops/upgrade/migrate.md)的时候，也可以通过上传备份包的方式。点击**上传备份包**,弹出本地资源选择器窗口，找到需要恢复的备份包上传即可。
---
url: "https://docs.succapp.com/v5/guide/devops/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops"
title: "部署运维"
---
---
order: 18
---
# 部署运维
!!!children (guide/devops) 2 !!!
---
url: "https://docs.succapp.com/v5/guide/devops/requirements.md"
htmlUrl: "https://docs.succapp.com/v5/devops/requirements"
title: "安装前准备"
---
---
order: 1
---
# 安装前准备
\[\[toc]]
在山川软件产品安装部署之前，需要先对产品实施架构及其所依赖的软硬件环境等基础信息进行初步了解，然后再根据实际项目的应用场景，选择合适的软硬件配置来实施。
下面从一个典型的山川软件产品实施架构图来逐步了解和掌握安装前所需要做的准备工作。
## 典型的系统架构图{#typical-diagram}
图中间的蓝色矩形框内的应用服务是需要安装部署的部分，主要分为四个部分：`WEB应用服务器`、`分析用途数据库`、`事务用途数据库`和`负载均衡器`。
- Web应用服务器\
主要用来发布山川软件产品包，提供Web应用服务
- 分析用途数据库\
存储数据仓库、数据集市的模型，支撑系统绝大部分的分析应用的查询请求
- 事务用途数据库\
存储产品的元数据及支撑产品事务性需求
- 负载均衡器（可选）\
可配置不同的负载均衡策略，将客户端请求分摊到Web集群中的不同节点。可根据项目的实际情况选配。
要完成以上四部分应用的安装部署，则要先了解每个应用所依赖的软件环境及其兼容性情况。
## 软件要求{#software-requirements}
### 数据库管理软件{#database-software}
[查看山川软件产品所支持的数据库类型列表及其版本兼容性情况>>](./install/database/README.md)
以下表格是不同用途常见的数据库选型情况：
- 分析用途数据库
| 数据库类型 | 版本要求 | 推荐版本 | 下载地址 |
| :-------------- | :------------ | :------------ | :------------ |
| Vertica | 8.x+ | 使用最新版本9.3.x | [地址]() |
| Oracle | 9.x+ | 11g+ | [地址]() |
| Greenplum | 5.x+ | 6.1 | [地址]() |
- 事务用途数据库
| 数据库类型 | 版本要求 | 推荐版本 | 下载地址 |
| :-------------- | :------------ | :------------ | :------------ |
| Oracle | 9.x+ | 11g+ | [地址]() |
| Mysql | 8.x+ | 8.0.18 | [地址]() |
| PostgreSQL | 5.x+ | 12.1 | [地址]() |
| 达梦 | DM7+ | DM8 | [地址]() |
分析用途数据库强烈推荐使用`自带原生负载均衡的纯列式MPP分析数据库Vertica`。\
事务用途数据库推荐使用Oracle 11g数据库。
::: tip 提示
分析用途数据库和事务用途数据库可根据数据量规模、应用类型、用户规模等因素考虑可合并为一个数据库。
:::
### Web应用服务器中间件{#web-middleware}
山川产品支持常见的Web应用服务器中间件，如下：\
| 中间件类型 | 版本要求 | 推荐版本 | 下载地址 |
| :--- | :--- | :--- | :--- |
| tomcat | 8.x | 8.5 | [地址]() |
| WebSphere | 8.x | 8.5 | [地址]() |
| WebLogic | 12.x | 12.2.3 | [地址]() |
优先推荐使用`轻量级Web服务器中间件tomcat`，点击[这里](./install/middleware/tomcat.md)了解tomcat安装配置。
### 负载均衡器{#balancer}
负载均衡器可使用Nginx软件负载均衡，推荐Nginx 1.16，或者硬件负载均衡器F5.
### 其他相关要求{#other}
| 要求细项 | 要求说明 |
| :--- | :--- |
| 客户端浏览器 | FireFox、Chrome、360安全浏览器、360极速浏览器等 |
| 网络要求 | 1. 客户浏览器端到WEB应用服务器保证`10M网络带宽`
2. WEB应用服务器到数据库服务器为`1000M网络带宽`
3. 所有数据库服务器之间（包括与接入数据来源的上游数据库服务器）保证`1000M网络带宽` |
| Web应用服务器JDK环境 | JDK 1.8.0\_131及以上 |
| 服务器操作系统 | 推荐使用Linux服务器操作系统，如RedHat系列、CentOS系列 |
## 应用场景调研{#application}
了解完软件需求后，在准备硬件之前需要先对系统应用场景做初步调研，获取以下四个重要的指标：
- 用户量\
需统计已知用户量、潜在用户量，及在系统服役期限内的未来用户增量总和。
- 同时在线用户数\
需评估平均同时在线系统的用户数量，包括考虑未来可能存在的增量用户
- 数据存储量
统计系统建设已知需要接入的业务数据存储总量、相关业务存储总量，以及按照系统未来建设规划可能纳入的数据存储总量。
- 最大业务数据量\
统计下业务分析查询场景最大的数据表数据量行数，包含未来数据行数增长情况
硬件的配置将根据`用户量`、`同时在线用户数`、`数据存储量`和`最大业务数据量`四个主要指标来进行评估选择。
## 硬件要求{#hardware}
根据[应用场景调研](#应用场景调研)获取的四个主要指标：`用户量`、`同时在线用户数`、`数据存储量`和`最大业务数据量`来评估对应的Web服务器和数据库服务器的CPU、内存及存储的需求。如下：
**指标数据** | **Web服务器** | **分析数据库服务器** | **事务数据库服务器**
:--- | :--- |:--- |:---
用户量<100
同时在线用户数<20
数据存储量<100G
最大业务数据量<50w | 处理器：16核
内存：32G
存储空间：200G
| 与事务用途数据库可合并 | 处理器：24核
内存：64G
存储空间：500G
用户量<300
同时在线用户数<20
数据存储量<100G
最大业务数据量<50w | 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
用户量<100
同时在线用户数<20
数据存储量<100G
最大业务数据量<50w | 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
用户量<100
同时在线用户数<20
数据存储量<100G
最大业务数据量<50w | 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
用户量<100
同时在线用户数<20
数据存储量<100G
最大业务数据量<50w | 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
| 处理器：
内存：
存储空间：
## 典型场景推荐配置{#typical-scenarios}
### 小型项目{#small-projects}
`样例指标：用户量<100 同时在线用户数<20 数据存储量<100G 最大业务数据量<50w`
#### 软硬件配置{#small-configuration}
| 配置项 | Web服务器 | 数据库服务器 |
| :--- | :--- | :--- |
| 节点个数 | 1 | 1 |
| 服务器操作系统 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 |
| 软件及其版本 | Tomcat 8.5 | Oracle 11g |
| 处理器 | CPU类型：至强E5系列
CPU内核数量：16核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：32核
主频：2.6GHz |
| 内存 | 内存类型：DDR4
内存容量：32G | 内存类型：DDR4
内存容量：64G |
| 存储 | 硬盘容量：200G
硬盘架构：SCSI或者SAS
硬盘转数：10000转/每分钟 | 系统盘：200G
硬盘架构：SCSI或者SAS
硬盘转速：10000转/每分钟
数据盘：500G
数据盘磁盘阵列：RAID1 |
::: tip 提示
此类小型项目可将分析用途数据库和事务用途数据库合并。
:::
#### 小型项目架构图{#small-diagram}
### 中型项目{#medium-projects}
`样例指标：用户量<1000 同时在线用户数<100 数据存储量<500G 最大业务数据量<5000w`
#### 软硬件配置{#medium-configuration}
| 配置项 | Web服务器 | 事务数据库 | 分析数据库 | 负载均衡器 |
| :--- | :--- | :--- | :--- | :--- |
| 节点个数 | 2 | 1 | 3 | 与Web服务器共用 |
| 服务器操作系统 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 | 与Web服务器共用 |
| 软件及其版本 | Tomcat 8.5 | Oracle 11g | Vertica 9.2.x | nginx 1.16 |
| 处理器 | CPU类型：至强E5系列
CPU内核数量：16核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：64核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：64核
主频：2.6GHz | 与Web服务器共用 |
| 内存 | 内存类型：DDR4
内存容量：32G | 内存类型：DDR4
内存容量：128G | 内存类型：DDR4
内存容量：128G | 与Web服务器共用 |
| 存储 | 硬盘容量：200G
硬盘架构：SCSI或者SAS
硬盘转数：10000转/每分钟 | 系统盘：200G
硬盘架构：SCSI或者SAS
硬盘转速：10000转/每分钟
数据盘：1.5T
数据盘磁盘阵列：RAID1 | 系统盘：200G
硬盘架构：SCSI或者SAS
硬盘转速：10000转/每分钟
数据盘：1.5T
数据盘磁盘阵列：RAID1 | 与Web服务器共用 |
::: tip 说明
此类项目负载均衡一般可与Web中间件共用服务器，采用Nginx软件负载均衡。
:::
##### 中型项目部署架构图{#medium-diagram}
### 大型项目{#large-projects}
`样例指标：用户量<3000 同时在线用户数<300 数据存储量<1T 最大业务数据量<5亿`
#### 软硬件配置{#large-configuration}
| 配置项 | Web服务器 | 事务数据库 | 分析数据库 | 负载均衡器 |
| :--- | :--- | :--- | :--- | :--- |
| 节点个数 | 5 | 2 | 7 | 独立硬件(F5硬件负载器) |
| 服务器操作系统 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 | - |
| 软件及其版本 | Tomcat 8.5 | Oracle 11g | Vertica 9.2.x | - |
| 处理器 | CPU类型：至强E5系列
CPU内核数量：16核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：64核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：128核
主频：2.6GHz | - |
| 内存 | 内存类型：DDR4
内存容量：32G | 内存类型：DDR4
内存容量：256G | 内存类型：DDR4
内存容量：512G | - |
| 存储 | 硬盘容量：200G
硬盘架构：SCSI或者SAS
硬盘转数：10000转/每分钟 | 系统盘：200G
硬盘架构：SCSI或者SAS
硬盘转速：10000转/每分钟
数据盘：2.5T
数据盘磁盘阵列：RAID1 | 系统盘：200G
硬盘架构：SCSI或者SAS
硬盘转速：10000转/每分钟
数据盘：2.5T
数据盘磁盘阵列：RAID1 | - |
##### 大型项目部署架构图{#large-diagram}
### 外网表单填报采集项目{#collection-items}
#### 项目背景{#background}
每天近20万用户填报健康状况表，持续3个月，项目环境采用云服务器部署。
#### 配置指标预估计算{#configuration-estimate}
- 并发量\
每日20w用户，采集比较简单，按照每天上午两小时，下午两小时为上报集中时间，共4小时。每个用户平均与系统有效交互花费1分钟，共60秒。
并发量为：`200000/3600/4*60=833`
按照每台WEB节点处理300并发的经验值，需配置三节点WEB集群。
- 数据盘\
按照每次上报数据20K磁盘存储
三个月数据量：`20W*10KB*30*3=343G`，推荐使用500G SSD
- WEB外网出口带宽\
按照每个用户平均150KB
WEB外网出口带宽：`833*150KB=122M`
#### 软硬件配置{#project-configuration}
| 配置项 | Web服务器 | 数据库服务器 | 负载均衡 |
| :--- | :--- | :--- | :---|
| 节点个数 | 3 | 1 | - |
| 服务器操作系统 | Centos 6.9 x86\_64 | Centos 6.9 x86\_64 | - |
| 软件及其版本 | Tomcat 8.5 | Oracle 11g | - |
| 处理器 | CPU类型：至强E5系列
CPU内核数量：16核
主频：2.6GHz | CPU类型：至强系列
CPU内核数量：32核
主频：2.6GHz | - |
| 内存 | 内存类型：DDR4
内存容量：32G | 内存类型：DDR4
内存容量：64G | - |
| 存储 | 硬盘容量：150G
硬盘架构：SSD | 系统盘：150G
数据盘：500G
备份盘：500G
硬盘架构：SSD | - |
| 网络 | 千兆网卡 | 千兆网卡 | - |
| 外网带宽 | 5M（任意一台WEB节点开通即可） | - | 122M（采用云负载均衡服务） |
#### 部署架构图{#project-diagram}
---
url: "https://docs.succapp.com/v5/guide/devops/install/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install"
title: "安装配置总体介绍"
---
---
order: 2
navTitle: 安装部署
indexTitle: 安装部署总体介绍
---
# 安装配置总体介绍
本文介绍如何从零安装SuccBI（通常用于生产环境安装，如果只是试用SuccBI，可以直接[试用DEMO体验版](./basic-install/trial-install.md)），以使用Tomcat环境的安装为例，主要安装步骤如下：
1. [下载SuccBI](../../whatsnew/README.md#stable-version)（下载WAR包）
2. [JDK安装配置](./basic-install/JDK.md)
3. [数据库安装配置](./database/README.md)
4. [工作目录和默认数据库配置](./basic-install/workdir-and-defdb.md)
5. [Tomcat安装配置](./middleware/tomcat.md)
6. [JDBC驱动安装配置](./basic-install/jdbc-drivers.md)
7. [Nodejs安装配置](./basic-install/Nodejs.md)
8. [集群环境安装](../cluster/README.md)
:::tip
请先阅读：[安装前准备](../requirements.md)。如果已经进行安装，希望升级程序包，可参考[升级war包](../upgrade/war.md)。
:::
## 其他Web中间件安装{#other-middlewares}
### Websphere{#websphere}
- [Websphere](https://docs.succapp.com/v5/devops/install/websphere)
### 国产中间件{#china-middlewares}
- [TongWeb](./middleware/TongWeb.md)
- [BES Application Server](./middleware/BES.md)
## 配套工具和服务{#more-install}
- [反向代理和负载平衡](../cluster/reverse-proxy.md)
- [Linux安装中文字体](./tool-services/linux-fonts.md)
- [截图服务配置](./tool-services/screenshot-service.md)
- [rar解压缩工具配置](./tool-services/unrar.md)
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/basic-install"
title: "基础安装"
---
---
order: 1
navTitle: 基础安装
---
# 基础安装
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/trial-install.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/trial-install"
title: "DEMO体验版安装配置"
---
---
order: 1
navTitle: DEMO体验版安装
---
# DEMO体验版安装配置
试用SuccBI，可以直接使用DEMO体验版，安装配置步骤如下
\[\[toc]]
## 下载DEMO体验版压缩包{#download-package}
访问[下载地址列表](../../../whatsnew/README.md)，选择版本(推荐当前版本)，下载文件名为`SuccBi-trial-x.x.x.zip`的压缩包。
## 解压运行{#unzip}
### 在Windows上运行{#runs-on-windows}
将压缩包解压，请注意解压路径不宜太深，且路径中尽量不要带有中文和空格。Windows双击根目录下的`startup.bat`后，加载完毕后，会自动弹出浏览器访问页面，也可以直接访问进行初始化。
### 在mac上运行{#runs-on-mac}
使用系统自带的“归档实用工具”解压缩，请注意解压路径不宜太深，且路径中尽量不要带有中文和空格。在终端命令行运行`startup.sh`，当命令行显示
```bash
org.apache.catalina.startup.Catalina.start Server startup in xxxx ms
```
就可以访问进行初始化了。
## 系统初始化{#sysinit}
初始化界面如图
点击`立即试用`，以DEMO体验版压缩包自带的PostgreSQL作为默认数据库，以`admin`为账号密码直接开始试用。
勾选`我已阅读相关协议条款`后，点击`同意并开始试用`，等待系统初始化完成后进入登录界面。
以`admin`为账号和密码进行登录。
:::tip
5.0体验版系统初始化完成后，用户成功登录将无法正常访问DEMO，需要完成[产品许可](../../../sys-settings/basic/license.md)申请流程后，才能获取完整功能访问权限继续使用。
:::
## 更新版本{#update-war}
DEMO体验版也支持通过更换war更新版本，具体步骤如下
1. 访问[下载地址列表](../../../whatsnew/README.md)，下载新版本WAR。
2. Windows双击根目录下的`shutdown.bat`，macOS在终端命令行运行`shutdown.sh`，关闭系统。
3. 备份后删除/server/tomcat/webapps/下的`ROOT.war`和`ROOT`目录，将新版本war移动到该目录，并重命名为`ROOT.war`，同时清空tomcat的work目录。
4. Windows双击根目录下的`startup.bat`，macOS在终端命令行运行`startup.sh`，启动系统。
更多帮助见[升级WAR包](../../upgrade/war.md)。
## 常见问题{#faq}
### PostgreSQL数据库服务连接异常{#db-connect-error}
部署体验版demo时，弹出【服务器拒绝连接】对话框，提示 “请检查数据源连接的 URL 是否正确，服务器是否启动”。底层原因是系统启动时无法连接到 PostgreSQL 数据库服务器，这通常是因为数据库服务未正常启动，可以通过检查Windows系统的任务管理器窗口，查看是否存在`postgres.exe`的进程来确认。
**定位数据库未能启动的原因：**
体验版自带的是PostgreSQL数据库，它是通过命令`D:\\xxx\SuccBI-standalone-xxx\win\postgresql\postgresql.bat start`来启动的，可以通过windows的命令行工具直接执行一下启动命令，并根据输出日志来判断启动故障原因。
**方法一**：通过检查【任务管理器|详细信息】窗口，查看是否存在`postgres.exe`相关进程来判断其运行状态。
**方法二**：点击桌面【开始菜单】，选择【运行】(或按 Win+R 快捷键)，输入`cmd`后，通过命令
`D:\\xxx\SuccBI-standalone-xxx\win\postgresql\bin\pg_ctl -D "D:\\xxx\SuccBI-standalone-xxx\win\postgresql\data" status`
查看运行状态，若返回`no server running`，则说明未启动。
**可能的原因：**
1. **目录含空格或中文**：PostgreSQL 数据库采用 UTF-8 字符集，若在中文目录或包含空格的路径下启动服务，会干扰数据库的正常初始化流程，导致服务无法正常启动。可尝试将体验版 Demo 解压至无空格、纯英文路径（例如：`D:\soft\db`），完成解压后，重新启动服务。
2. **端口被占用**：PostgreSQL 数据库默认使用 15430 端口，当此端口被其他进程占用时，数据库服务因无法获取必要的网络资源，从而无法正常启动。可通过在命令提示符中输入`netstat -ano | find "15430"`，若查到占用进程，说明该端口已被其他程序使用。关闭占用进程后，重新启动服务。
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/Nodejs.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/Nodejs"
title: "Node.js安装配置"
---
---
order: 2
navTitle: Node.js
---
# Node.js安装配置
SuccBI运行需要Node.js环境，服务器端通过Node.js“编译”用户设计的仪表板、报表等内容，提前生成“预编译信息”便于用户快速查看浏览仪表板和报表等内容。
## 配置步骤{#steps}
### 安装Node.js{#install-nodejs}
推荐`16.17.xx`版本，安装方法：
1. 方法1: 访问下载最新稳定版Nodejs并安装，推荐`16.17.xx`版本。
2. 方法2：点击[这里](https://www.jianguoyun.com/p/DThNFWcQ3O-gChiW3s4FIAA)下载
3. 方法3: windows服务器可复制DEMO体验版压缩包目录中的`win/node-v16`目录到服务器
安装完毕后需要在tomcat的启动文件中配置环境变量（Linux下）：
```sh
export PATH=/path/to/node-install-dir/bin:$PATH
```
### 安装Nodejs模块(仅使用IE浏览器时需要){#install-modules}
SuccBI通过Node.js+Babel将Javascript转换为IE能运行的版本发送给IE，浏览器使用IE11时，需要安装Nodejs模块。
安装方法有两种，方法1适用于服务器联网情况下，方法2适用于内网服务器无法连接互联网的情况。
方法1: 全局安装，适用于服务器可以联网的情况:
```sh
# Babel，如果不考虑支持ie11可不安装，推荐`7.6.xx`版本。
npm install -g @babel/preset-env
npm install -g @babel/core
# https://github.com/Microsoft/tslib
npm install -g tslib
```
方法2: 内网安装：
复制DEMO体验版压缩包目录中的`node_modules`目录到服务器目录，如`/path/to/succ/node_modules`，然后在启动[tomcat的启动文件](../middleware/tomcat.md#env)中配置环境变量（Linux下）：
```sh
export NODE_PATH=/path/to/succ/node_modules
```
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/workdir-and-defdb.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/workdir-and-defdb"
title: "工作目录和默认数据库配置"
---
---
order: 3
---
# 工作目录和默认数据库配置
SuccBI运行时需要一个目录来存放配置文件、临时文件和缓存文件等，该目录称为“工作目录”
## 配置工作目录{#set-workdir}
通过JVM环境变量`-Dsucc.workdir`来配置工作目录。SuccBI服务器进程对这个目录要有读写权限，工作目录所在的磁盘确空间足够（可用空间大于`50G`），且性能可靠。
以Tomcat为例，如要配置`/path/to/workdir`作为工作目录，在Tomcat的`bin`目录下新建文件`setenv.sh`（windows是`setenv.bat`），Linux输入内容：
```sh
#!/bin/sh
export JAVA_OPTS="$JAVA_OPTS -Dsucc.workdir=/path/to/workdir（请修改这个路径）"
```
windows输入：
```batch
set "JAVA_OPTS=%JAVA_OPTS% -Dsucc.workdir=C:\path\to\workdir（请修改这个路径）"
```
:::warning
windows配置工作目录路径时，盘符需要为大写，如C:\path\to\workdir，否则系统设置会提示异常。
:::
## 配置默认数据库{#defjdbc}
SuccBI把元数据（模型结构信息、仪表板、报表等文件信息）、日志、权限等数据存储在数据库中，这个数据库称为“默认数据库”。
第一次部署服务器时需要先配置好工作目录，然后可以直接在工作目录中编辑`conf/jdbc.conf`来配置默认数据库；也可以直接启动服务器，用浏览器访问服务器时，SuccBI会显示默认数据库的配置界面，通过可视化界面中进行默认数据库配置。
服务器配置好之后，如果想修改默认数据库配置，可以在系统数据源管理中进行（数据库类型、地址、用户名、密码等关键属性不可修改）；也可以直接修改`conf/jdbc.conf`，但需要重启服务器才能生效，可参考[如何修改默认数据库配置](../../faq/如何修改默认数据库配置.md)。
[conf/jdbc.conf](/dev/meta/jdbc-conf) 是一个JSON格式的文件，你可以手工修改，但需要重启服务器才能生效。
## 工作目录的结构{#dir}
工作目录结构如下：
1. **cache** - 缓存目录，可以清理
2. **clusters-share** - 集群共享目录，此目录下的文件在集群节点之间是共享的（通过OS级别的共享目录技术实现，见[文件共享](../../cluster/README.md#文件共享)）
- **app-attachments** - 存放应用中用户提交到模型中的附件
- **backup** - 系统备份包存储目录
- **cache** - 缓存目录，可以清理
- **converted-documents** - 存放ActiveDoc转换文档的目录
- **data-files** - 文件数据源存储目录
- **dataflow** - 用于存放数据加工错误日志，可以清理
- **download-service** - 存放用户临时下载文件的目录，可以清理
- **file-storage** - 文件服务存储目录，模型上文件角色字段对应文件存储
- **meta-thumbnails** - 存放元数据缩略图的目录
- **meta-thumbnails-custom** - 存放用户上传的自定义元数据缩略图的目录
- **service-cache** - 存放产品长任务运行结果和日志的目录，可以清理
- **upload-files** - 用于存储上传附件提交前产生的临时文件，可以清理
3. **conf** - 配置目录
- **logback.xml** - 可选，lockback的配置文件
4. **extensions-javalib** - 存放新配置数据库连接器的驱动包
5. **logs** - 存放logback日志文件的目录
6. **temp** - 临时文件目录，可以清理
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/jdbc-drivers.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/jdbc-drivers"
title: "JDBC驱动安装配置"
---
---
order: 4
---
# JDBC驱动安装配置
由于SuccBI支持众多的数据库（见[兼容的数据库](../database/README.md)），无法在WAR包中将驱动都包含进来，我们提供了2种WAR包：
1. 没有包含任何驱动文件的（如：`SuccBI-v4.2.0-release-201912091104-55f15a1f-12.war`）。
2. 包含了常用数据库驱动的（文件包含`jdbcdrivers`，如：`SuccBI-v4.2.0-release-jdbcdrivers-201912091104-55f15a1f-12.war`），包含了Mysql、Oracle、Vertica和PostgreSQL的驱动。
你需要根据自己使用的WAR包和具体的数据库需要下载并安装JDBC驱动。
## 获取JDBC驱动{#jdbc-drivers}
1. 方法1: 点击[这里](https://www.jianguoyun.com/p/DdUp8kIQ3O-gChjf1awE)(提取码:SuccBI)下载驱动文件。
2. 方法2: DEMO体验版解压缩目录中的`server/tomcat/lib`目录下带了一些数据库的驱动，可以从这里拷贝驱动文件：
| 数据库 | 驱动文件 |
| ------ | :------------------------------ |
| Mysql | mysql-connector-java-8.0.16.jar |
| Oracle | ojdbc8-18.3.0.0.jar |
| Vertica | vertica-jdbc-9.1.1-0.jar |
| SQL Server | mssql-jdbc-9.2.1.jre11.jar |
| PostgreSQL|postgresql-42.2.2.jar|
## 安装驱动{#driver-install}
将需要的驱动文件复制到`tomcat/lib`目录下即可，见[Tomcat安装配置](../middleware/tomcat.md)。
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/jvm-sys-properties.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/jvm-sys-properties"
title: "启动时支持的环境变量"
---
---
order: 5
navTitle: 环境变量
---
# 启动时支持的环境变量
如何设置系统启动环境变量，参考[设置启动环境变量](../middleware/tomcat.md#env)。
- `-Dsucc.workdir` - 指向产品的工作目录，必须指定，见[配置工作目录](./workdir-and-defdb.md#set-workdir)
- `-Dsucc.jdbc.default` - 可选，指向一个json格式的jdbc配置文件，表示默认数据库的配置，见[配置默认数据库](./workdir-and-defdb.md#defjdbc)
- `-Dsucc.cluster.enable` - 默认`true`，设置成`false`禁用集群
- `-Dsucc.clusterName=192.168`，当服务器有多个ip时，指定集群通讯使用的包含指定前缀的IP
- `-Dsucc.clusterNodeName=节点1`，当前集群节点的名称，用于在日志和集群列表中方便标示节点，不指定时默认用ip地址+web端口号表示
- `-Dsucc.cluster.messageTimeout=3000`，发送集群消息等待结果的超时时间，默认3000毫秒
- `-Dsucc.clusterBindAddress=192.168.7.128`，当服务器有多个ip时，指定集群通讯使用的IP
- `-Dsucc.clusterBindAddressPrefix=192.168`，当服务器有多个ip时，指定集群通讯使用的包含指定前缀的IP
- `-Dsucc.init.forceUpdate` - 默认`false`，表示是否强行升级系统元数据和相关系统数据
- `-Dsucc.checkBrowserCompatible` - 默认`true`，表示是否检查浏览器兼容性
- `-Dsucc.localWebAddress` - 可选，设置本地tomcat局域网访问地址，如`-Dsucc.localWebAddress=http://192.168.7.128:8080`，当未设置时将自动侦测
- `-Dsucc.3admin.enable=true` 启用三员分立，自动创建系统预设的系统管理员、安全保密管理员和安全审计员，三员之间互有制约、相互监督，避免由于权限过于集中带来的安全风险，并禁止使用超级管理员
- `-Dsucc.disableScript.filter=true` 禁用[filter.action](/dev/hooks/filter-action)脚本
- `-Dsucc.disableCDN=true` 禁用[CDN服务](../cloud-platform/CDN.md)，当配置了错误的CDN域名导致无法进入系统时，可添加此参数来禁用CDN。
- `-Dsucc.sessionStore` - 配置session存储方式，有`redis`（使用redis作为session存储器）和`default`（使用web容器中的默认session存储）两种。此配置优先级比`settings.json`配置项`sys.session.store`要高。
其它需要的环境变量：
- `-Dfile.encoding=UTF8`
- `-Xmx4096m` 设置jvm最大可用内存
- `-Djava.net.preferIPv4Stack=true`
- `-Djava.awt.headless=true`
- `-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true` ，见[配置Tomcat](./workdir-and-defdb.md)
- `-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true` ，见[配置Tomcat](./workdir-and-defdb.md)
不需要的环境变量：
- `-XX:MaxPermSize=256m` - Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0
---
url: "https://docs.succapp.com/v5/guide/devops/install/basic-install/JDK.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/jdk"
title: "JDK安装配置"
---
---
order: 6
navTitle: JDK
---
# JDK安装配置
SuccBI运行需要配置JDK环境，推荐安装17版本，本篇介绍Windows和Linux系统下JDK 17.0.12安装配置：
\[\[toc]]
## JDK兼容版本{#compatible-jdks}
SuccBI兼容以下版本的JDK，推荐安装17.0.12版本，可根据实际部署需求选择
|JDK|推荐版本|说明|
|:-:|:-:|:-:|
|Oracle JDK|[17.0.12](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)|[官方说明](https://www.oracle.com/java/technologies/javase/products-doc-jdk17certconfig.html)|
|Open JDK|[17.0.12](https://developers.redhat.com/products/openjdk/download)|[官方说明](https://developers.redhat.com/products/openjdk/overview)|
## Windows安装配置JDK{#windows-jdk}
下载方式有如下两种：
1. 从[ORACLE官方](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)下载Windows版本的JDK，选择对应操作系统的版本是64位。
2. 点击[这里](https://www.jianguoyun.com/p/DWtd3qUQ3O-gChiUnaUGIAA)下载。
下载完成后，安装JDK：
- 安装配置为全局JDK
安装到`C:\Program Files\java\jdk-17.0.12`，安装完成后，配置系统变量:
1. 在Windows 10中打开`控制面板`>`系统和安全`>`系统`。
2. 点击`高级系统设置`，在弹出的`系统属性`对话框中点击`高级`下的`环境变量`。
3. 在`系统变量`中点击`新建`，变量名为`JAVA_HOME`，变量值为`C:\Program Files\java\jdk-17.0.12`。
4. 在`用户变量`中找到`Path`，编辑该变量，新建路径为`%JAVA_HOME%\bin`。
配置完路径后就可以使用java命令了。打开命令提示符，在窗口中输入 `java` 获取命令参数帮助，输入 `java -version` 获取当前JDK版本。
- 配置为SuccBI指定JDK
安装到`\path\to\tomcat\jdk-17.0.12`
编辑tomcat[启动环境变量](../middleware/tomcat.md#env)
在`\path\to\tomcat\bin\setenv.bat`中插入如下内容
```batch
set JAVA_HOME=\path\to\tomcat\jdk-17.0.12
```
配置完成后，进入SuccezBI系统设置可查看当前JDK版本为17.0.12
## linux安装配置JDK{#linux-jdk}
下载方式有如下两种：
1. 在Windows中从[ORACLE官方](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)或[这里](https://www.jianguoyun.com/p/DVdotHIQ3O-gChjvnaUGIAA)下载Linux版本的JDK，再上传到Linux服务器
2. 在服务器上通过wget命令，直接下载安装包，可从Oracle下载页获取对应版本的下载地址
```sh
wget https://download.oracle.com/java/17/archive/jdk-17.0.12_linux-x64_bin.tar.gz
```
下载完成后，将压缩包解压到安装目录：
- 安装配置为全局JDK
安装到`/usr/local`，使用如下命令：
```sh
tar -zxvf jdk-17.0.12_linux-x64_bin.tar.gz -C /usr/local
```
配置系统变量
```sh
vim /etc/profile
#在最后一行插入以下内容
export JAVA_HOME=/usr/local/jdk-17.0.12
export PATH=$JAVA_HOME/bin:$PATH
```
立即生效更改
```sh
source /etc/profile
```
配置完系统变量后就可以使用java命令了。输入`java`获取命令参数帮助，输入`java -version`获取当前JDK版本。
- 安装配置为SuccBI指定JDK
安装到`/path/to/tomcat`，使用如下命令：
```sh
tar -zxvf jdk-17.0.12_linux-x64_bin.tar.gz -C /path/to/tomcat
```
安装完成后配置tomcat的[启动环境变量](../middleware/tomcat.md#env)
```sh
vim /path/to/tomcat/bin/setenv.sh
#插入如下内容
export JAVA_HOME=/path/to/tomcat/jdk-17.0.12
```
配置完成后，进入SuccBI[系统设置](../../../sys-settings/basic/sysinfo.md)可查看当前JDK版本为17.0.12
## 常见问题{#faq}
### 安装JDK提示执行格式错误{#linux-arm}
**问题原因：**
ARM架构服务器如果误用了x86架构的JDK安装包，操作系统无法正确执行对应二进制文件，通常会提示`cannot execute binary file: Exec format error`。
**解决方法**：先执行如下命令查看服务器架构：
```sh
uname -m
```
常见ARM服务器通常返回`aarch64`或`arm64`，此时需要下载并安装对应的`linux-aarch64`版本JDK安装包。
---
url: "https://docs.succapp.com/v5/guide/devops/install/database/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/database"
title: "兼容的数据库"
---
---
order: 2
navTitle: 数据库
indexTitle: 兼容的数据库
---
# 兼容的数据库
SuccBI运行需要数据库，生产环境安装部署通常需要根据需要安装合适的数据库，SuccBI兼容多种数据库，包括传统关系型数据库、SQL on Hadoop数据库、MPP列式数据库和多种国产数据库，数据库有分析型用途、事务型用途和提取源用途之分：
1. 分析型用途：用作存储数据仓库的模型表数据、数据加工的输出存储、报表和仪表板等分析数据时的查询库使用。
2. 事务型用途：存储系统元数据、日志、流程数据、表单数据等。
3. 提取源用途：作为数据加工的数据源使用，用于读取数据并加工后输出到数据仓库。
以上使用场景可以合并使用一个数据库，也可以分开同时使用多个数据库。
[DEMO体验版](../basic-install/trial-install.md)自带了绿色版MySQL数据库，DEMO体验版可直接使用，无需额外安装数据库。
## 兼容数据库列表{#compatible-dbs}
|数据库|分析型用途|事务型用途|提取源用途|说明|
|:-|:-:|:-:|:-:|:-|
|MySQL|支持|支持|支持|版本8+，[MySQL安装配置](./MySQL.md)|
|Oracle|支持|支持|支持|版本9+|
|OceanBase for MySQL|支持|支持|支持|版本4.0|
|PostgreSQL|支持|支持|支持|9+|
|华为OpenGuass|支持|支持|支持|版本2.0|
|SQL Server|支持|支持|支持|版本9+|
|人大金仓-Oracle内核|支持|支持|支持|版本8+|
|人大金仓-PostgreSQL内核|支持|支持|支持|版本8+|
|达梦|支持|支持|支持|版本8.0|
|Informix|支持|-|支持|版本5+|
|南大通用|支持|-|支持|GBase8s|
|Vertica|支持|-|支持||
|YMatrix|支持|支持|支持|版本4+|
|GreenPlum|支持|-|支持||
|Hive|支持|-|支持||
## 安装JDBC驱动{#install-jdbc-drivers}
见[JDBC驱动安装配置](../basic-install/jdbc-drivers.md)。
---
url: "https://docs.succapp.com/v5/guide/devops/install/database/MySQL.md"
htmlUrl: "https://docs.succapp.com/v5/devops/database/MySQL"
title: "MySQL安装配置"
---
---
order: 5
---
# MySQL安装配置
SuccBI支持MySQL数据库，可以将MySQL当作默认数据库、事务性数据库或分析库使用。
## 版本
MySQL8支持了window函数，更有利于分析数据，也有更好的性能，我们推荐使用8.0.16及以上版本。
## 安装MySQL
可以点击[这里](https://dev.mysql.com/downloads/mysql/)进入到官网下载，并查看安装步骤。
## URL配置
jdbc连接URL推荐配置：
```bash
jdbc:mysql://127.0.0.1/succbidw?useUnicode=true&characterEncoding=utf8&allowLoadLocalInfile=true&zeroDateTimeBehavior=convertToNull&useSSL=false
```
## 配置初始化文件
MySQL会按照一定顺序查找配置文件，并读取所有存在的文件。如果该文件不存在，则需要手动创建。有需要可以了解：[MySQL8.0参考手册](https://dev.mysql.com/doc/refman/8.0/en/option-files.html)
配置文件my.ini的推荐配置如下：
```bash
[mysql]
# 设置mysql客户端默认字符集
default-character-set=utf8
[client]
# 设置mysql客户端连接服务端时默认使用的端口
port=3306
default-character-set=utf8
[mysqld]
# 设置3306端口
port=3306
# 设置允许客户端执行load data装载数据，否则会出现ERROR 1148: The used command is not allowed with this MySQL version异常。
# https://dev.mysql.com/doc/refman/8.0/en/load-data-local.html
# 除了服务器端设置设置此参数，还需在url设置allowLoadLocalInfile=true参数。
loose-local-infile=1
# mysql中使用group_concat时，经常遇到报错：Row 25 was cut by GROUP_CONCAT()。
# 原因是MySQL中的参数group_concat_max_len 限制了其返回的最大字符长度，默认为1024，超过后就会报错，此处改大点
group_concat_max_len = 102400
# 设置时区
# 不加这个jdbc连接有异常。
# The server time zone value 'Öйú±ê׼ʱ¼ä' is unrecognized or represents more than one time zone.
# You must configure either the server or JDBC driver (via the serverTimezone configuration property) to use a more specifc time zone value if you want to utilize time zone support.
default-time_zone='+8:00'
# mysql推荐的是utf8mb4，不是utf8， https://www.techug.com/post/in-mysql-never-use-utf8-use-utf8mb4.html
# 可通过sql:SELECT default_character_set_name,schema_name FROM information_schema.SCHEMATA; 查看各个database的默认字符集
character-set-server=utf8mb4
#设置默认数据库引擎为Innodb, 5.5.5开始就是默认引擎。
default-storage-engine=INNODB
#避免出现异常 Row size too large (> 8126). Changing some columns to TEXT or BLOB may help. In current row format, BLOB prefix of 0 bytes is stored inline.
#see https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_page_size
innodb_page_size=32KB
#InnoDB用于缓存数据、索引、锁、插入缓冲、数据字典等
#如果是专用的DB服务器，且以InnoDB引擎为主的场景，通常可设置物理内存的50%
#如果是非专用DB服务器，可以先尝试设置成内存的1/4，如果有问题再调整
#默认值是8M，非常坑X，这也是导致很多人觉得InnoDB不如MyISAM好用的缘故
innodb_buffer_pool_size = 512M
#InnoDB共享表空间初始化大小，默认是 10MB，也非常坑，改成 256M，并且自动扩展
innodb_data_file_path = ibdata1:256M:autoextend
#如果不了解本选项，建议设置为1，能较好保护数据可靠性，对性能有一定影响，但可控
#提高性能可设置为2
innodb_flush_log_at_trx_commit = 1
#InnoDB的log buffer，通常设置为 64MB 就足够了
innodb_log_buffer_size = 64M
#InnoDB redo log大小，通常设置256MB 就足够了
innodb_log_file_size = 256M
#InnoDB redo log文件组，通常设置为 2 就足够了
innodb_log_files_in_group = 2
#启用InnoDB的独立表空间模式，便于管理，性能会高一些，且删表后可自动回收表空间
innodb_file_per_table = 1
#启用InnoDB的status file，便于管理员查看以及监控等
innodb_status_file = 1
#设置事务隔离级别为 READ-COMMITED，提高事务效率，通常都满足事务一致性要求
transaction_isolation = READ-COMMITTED
#在这里，其他配置选项也需要注意：
#设置最大并发连接数，如果前端程序是PHP，可适当加大，但不可过大
#如果前端程序采用连接池，可适当调小，避免连接数过大
max_connections = 100
# 允许连接失败的次数。这是为了防止有人从该主机试图攻击数据库系统
max_connect_errors=100
#设置临时表最大值，这是每次连接都会分配，不宜设置过大 max_heap_table_size 和 tmp_table_size 要设置一样大
max_heap_table_size = 96M
tmp_table_size = 96M
#每个连接都会分配的一些排序、连接等缓冲，一般设置为 2MB 就足够了
sort_buffer_size = 2M
join_buffer_size = 2M
read_buffer_size = 2M
read_rnd_buffer_size = 2M
#建议关闭query cache，有些时候对性能反而是一种损害
#mysql8已经去掉了query cache，详见：https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html
#query_cache_size = 0
#如果是以InnoDB引擎为主的DB，专用于MyISAM引擎的 key_buffer_size 可以设置较小，8MB 已足够
#如果是以MyISAM引擎为主，可设置较大，但不能超过4G
#在这里，强烈建议不使用MyISAM引擎，默认都是用InnoDB引擎
key_buffer_size = 8M
#设置连接超时阀值，如果前端程序采用短连接，建议缩短这2个值
#如果前端程序采用长连接，可直接注释掉这两个选项，是用默认配置(8小时)
#interactive_timeout = 120
#wait_timeout = 120
# 设置以字节发送给服务器的最大数据包大小. (默认: 1MB)
max_allowed_packet = 16M
# mysql8，默认使用caching_sha2_password认证，可以修改为传统的“mysql_native_password”插件认证，用于连接Navicat
default_authentication_plugin=mysql_native_password
# 表名不区分大小写
lower_case_table_names = 1
# mysql8升级到8.0.16后，win版本也出现此问题
# (year(date1)-year(date2))*12+(month(date1)-month(date2)) 返回负数时出异常：
# BIGINT UNSIGNED value is out of range ...
# 原因：year返回UNSIGNED integer，当出现负数，就会出这个异常，5.5以上版本会有这个问题。
# 详见：https://dev.mysql.com/doc/refman/5.5/en/out-of-range-and-overflow.html
# https://dev.mysql.com/doc/refman/5.5/en/sql-mode.html#sqlmode_no_unsigned_subtraction
# 解决办法：配置sql_mode='NO_UNSIGNED_SUBTRACTION'
sql_mode = 'NO_UNSIGNED_SUBTRACTION'
```
配置文件中的路径要和实际存放的路径一致
---
url: "https://docs.succapp.com/v5/guide/devops/install/database/redis.md"
htmlUrl: "https://docs.succapp.com/v5/devops/database/redis"
title: "Redis安装配置"
---
---
order: 6
---
# Redis安装配置
Redis是一个开源的Key-Value 存储数据库，由于是内存型数据库，Redis拥有极高的性能，因此可用于存储web集群session信息，实现[集群会话故障转移](../../cluster/session-failover.md)功能。
:::tip 提示
SuccBI支持使用Redis[单节点模式](#linux-single)、[哨兵模式](#redis-sentinel)和[集群模式](#redis-cluster)存储session信息。
:::
\[\[toc]]
## 获取Redis安装包{#get-installer}
### windows下载Redis{#windows-download}
在GitHub下可以下载Windows系统的Redis，点击[这里](https://github.com/tporadowski/redis/releases)选择最新版本进行下载。
:::tip 提示
mis文件是微软安装版，zip文件是解压版，解压即可使用，这里我们选择下载zip文件。
:::
如果无法打开GitHub，可以在[此处](https://www.jianguoyun.com/p/Dc2-048Q3O-gChiR5KwE)(提取码：SuccBI)获取网盘下载链接。
### linux下载Redis{#linux-download}
1. 访问[Redis官网](https://redis.io/download)下载需要的Redis版本，推荐下载[redis-5.0.14.tar.gz](https://download.redis.io/releases/redis-5.0.14.tar.gz)。
2. 或点击[这里](https://www.jianguoyun.com/p/DdLOpl0Q3O-gChiN5KwE)(提取码：SuccBI)下载。
### 安装Redis{#unzip}
linux安装Redis前，需要对源码包进行编译，编译会依赖gcc编译器，若没有gcc环境，可以使用`yum install gcc gcc-c++`进行安装：
```sh
gcc -v #检查是否有 gcc 编译器
```
解压并安装：
```sh
tar zxvf redis-5.0.14.tar.gz #解压安装包
cd redis-5.0.14.tar.gz #进入解压目录
make && make PREFIX=/home/redis/redis install #安装命令，其中PREFIX为安装目录，用户可自行指定
```
:::tip 提示
linux环境解压后需要编译安装，windows环境只需要解压zip文件即可。
:::
## 配置Redis{#redis-configure}
根据用户不同的需求(如高并发、高可用等)，reids可以部署配置为单节点、哨兵模式和集群模式，具体配置可参考[Redis官方文档](https://redis.io/topics/config)，也可参考以下配置方法：
1. [windows配置Redis单节点](#windows-single)
2. [linux配置Redis单节点](#linux-single)
3. [哨兵模式配置](#redis-sentinel)
4. [集群模式配置](#redis-cluster)
### windows配置Redis单节点{#windows-single}
进入Redis解压目录，编辑配置文件`redis.windows.conf`，修改以下内容：
```sh
bind 127.0.0.1 #默认ip为127.0.0.1，在默认情况下，只允许本机访问Redis服务，如果需要其他主机可以访问Redis服务，可以配置为对应服务器ip
port 6379 #默认端口为6379，也可根据需要更换为其他端口
protected-mode no #关闭保护模式
requirepass foobared #配置Redis密码，默认用#号略去不启用
maxmemory 4294967296 # 内存大小，单位为byte，推荐大小为4G，也可配置成其他大小
notify-keyspace-events AKE #开启key event的监听，使用会话共享服务会使用此参数监听会话
```
cmd进入Redis目录，执行`redis-server.exe redis.windows.conf`语句，出现以下内容，说明启动成功。
### linux配置Redis单节点{#linux-single}
进入Redis解压目录，编辑配置文件`redis.conf`，除了需要修改[windows配置Redis单节点](#windows-single)中的配置外，还需修改以下内容：
```sh
pidfile /home/redis/redis-5.0.14/redis_6379.pid #启动时生成的pid文件位置，用户可自行修改对应目录
daemonize yes #默认以后台进程的方式启动Redis
```
修改完毕后启动Redis服务：
```sh
cd /home/redis/redis/bin/
./redis-server /home/redis/redis-5.0.14/redis.conf #启动Redis，指定之前修改的配置文件
```
查看Redis进程，若可以查到对应的Redis进程，表示启动成功
```sh
ps -ef|grep redis
```
### 哨兵模式配置{#redis-sentinel}
单节点的最大缺点是当节点宕机后，无法对外提供服务。为了保证Redis的高可用，可以在服务器中部署哨兵模式，实现Redis主从自动切换，故障自动转移，提高系统可用性。具体配置如下：
:::tip 提示
哨兵模式配置以一主二从三哨兵结构为例。
:::
#### 主从节点配置{#master-node}
进入Redis解压目录，将redis.conf复制为redis\_7007.conf、redis\_7008.conf、redis\_7009.conf作为主从节点的配置文件：
```sh
cd /home/redis/redis-5.0.14
cp redis.conf redis_7007.conf
cp redis.conf redis_7008.conf
cp redis.conf redis_7009.conf
```
配置可参考[Redis单节点配置](#linux-single)，并增加以下参数：
```sh
masterauth #配置主节点的密码(主从节点密码需要相同)，默认用#号略去不启用
slaveof #此属性只需从节点添加，配置为主节点的ip和端口
```
主从节点启动可参考[Redis单节点配置](#linux-single)，启动后使用`ps -ef|grep redis`查看redis进程，若查到对应的Redis进程，表示主从节点启动成功。
#### 哨兵节点配置{#sentinel-node}
进入Redis解压目录，将`sentinel.conf`复制为`sentinel_7117.conf、sentinel_7118.conf、sentinel_7119.conf`作为哨兵节点的配置文件：
```sh
cd /home/redis/redis-5.0.14
cp sentinel.conf sentinel_7117.conf
cp sentinel.conf sentinel_7118.conf
cp sentinel.conf sentinel_7119.conf
```
编辑配置文件，修改以下内容：
```sh
port 26379 #哨兵节点运行端口
sentinel monitor mymaster 127.0.0.1 6379 2 #将ip和端口更改为主节点的ip和端口
```
修改完毕后启动哨兵节点服务：
```sh
cd /home/redis/redis/bin/
./redis-sentinel /home/redis/redis-5.0.14/sentinel_7117.conf
./redis-sentinel /home/redis/redis-5.0.14/sentinel_7118.conf
./redis-sentinel /home/redis/redis-5.0.14/sentinel_7119.conf
```
启动三个哨兵节点后，可使用`redis-cli`查看相关节点信息，如下所示：
```sh
cd /home/redis/redis/bin/
./redis-cli -p 192.168.10.60 -p 7117
SENTINEL masters
```
### 集群模式配置{#redis-cluster}
Redis哨兵模式已经基本实现高可用和读写分离，但是在这种模式下只有主节点提供写入功能，无法支持高并发，为了使web集群实现高并发，可对Redis进行分布式集群部署，具体操作步骤如下：
:::tip 提示
下面例子的三主三从集群模式部署在同一个服务器，为保证高可用，建议在实际生产环境中使用三台服务器部署Redis集群。
:::
创建节点：
```sh
mkdir /home/redis/redis-cluster #创建集群目录redis-cluster
cd /home/redis/redis-cluster #进入redis-cluster目录
mkdir 7000 7001 7002 7003 7004 7005 #创建Redis节点的目录
```
切换到解压目录，将redis.conf配置文件复制到Redis节点目录
```sh
cd /home/redis/redis-5.0.14
cp redis.conf /home/redis/redis-cluster/7000
```
进入`redis.conf`配置文件，修改以下内容：
```sh
#bind 127.0.0.1 # 取消仅限本地访问的限制
daemonize yes # 设置Redis默认后台运行
protected-mode no # 关闭保护模式
maxmemory 4294967296 # 内存大小，单位为byte，推荐大小为4G，也可配置成其他大小
pidfile ./redis_7000.pid # pidfile文件，对应节点端口
port 7001 # 集群节点端口
cluster-enabled yes # 开启集群
cluster-config-file nodes-7000.conf # 集群的配置，配置文件首次启动时自动生成
```
启动节点：
```sh
cd /home/redis/redis/bin #进入启动目录
./redis-server /home/redis/redis-cluster/7000/redis.conf
```
:::tip 提示
7001-7005节点的启动可参考上述配置并启动，只需更改对应端口即可。
:::
节点启动完毕后，各个节点实际上是独立的，并没有组成一个集群，还需进行以下操作：
```sh
cd /home/redis/redis/bin #进入启动目录
./redis-cli --cluster create --cluster-replicas 1 192.168.10.60:7000 192.168.10.60:7001 192.168.10.60:7002 192.168.10.60:7003 192.168.10.60:7004 192.168.10.60:7005
```
当程序显示`Can I set the above configuration? (type 'yes' to accept):`时，输入yes并回车：
至此集群模式部署完毕。
---
url: "https://docs.succapp.com/v5/guide/devops/install/database/Vertica.md"
htmlUrl: "https://docs.succapp.com/v5/devops/database/Vertica"
title: "Vertica安装配置"
---
---
order: 6
---
# Vertica安装配置
Vertica是一款基于列存储的MPP架构数据库，基于标准的x86服务器，支持存放PB(Petabyte)级别的结构化数据，拥有高性能、高拓展性、高压缩率、高健壮性的特点，主要用于通信与网络分析、数据仓库、物联网分析、客户行行为分析等场景。
SuccBI 支持Vertica作为分析型数据库。
## 安装Vertica{#vertica-install}
### 获取Vertica安装包{#install-pacgage}
访问[官网]()申请下载Vertica，推荐下载10.1.1以及以上版本。
### 静默安装{#silent-install}
Vertica数据库安装前，需先在[此处]()完成系统安装准备，再将下载的rpm安装包上传，使用`rpm -ivh`安装rpm包，然后参照[官方文档]()静默安装。
### 安装Vertica控制台{#console-install}
Vertica也支持管理控制台，可使用控制台对Vertica数据库进行监控、启停或者配置数据库参数等操作，安装步骤可参考[这里]()。
## 系统配置{##system-configuration}
在正式生产环境中，完成Vertica的安装后还需配置**集群负载均衡**以及**最大会话数**，配置如下：
```bash
select set_load_balance_policy('ROUNDROBIN') #集群启用负载均衡，并设置为轮询策略
select set_config_parameter('maxclientsessions',500); #Vertica默认限制为50个会话，在生产环境中连接数一般远大于50，因此正式使用前需设置Vertica最大会话数
```
:::tip 说明
集群负载均衡分为`NONE`、`ROUNDROBIN`、`RANDOM`三种策略，使用Vertica集群时一般设置为`ROUNDROBIN`，具体用法可参考[负载均衡策略]()。
:::
## URL配置{#vertica-url}
jdbc连接URL推荐配置：
```bash
jdbc:vertica://192.168.10.60:5433/vetc?ConnectionLoadBalance=true&BackupServerNode=192.168.10.61:5433,192.168.10.62:5433
```
:::tip 说明
1. `ConnectionLoadBalance=true`表示使用负载均衡，如果未配置集群，可以不进行设置。
2. `BackupServerNode`设置集群中的其他节点，当主节点连接不上时，会自动连接`BackupServerNode`中的节点，确保高可用性，详细连接配置可参考[JDBC连接属性]()。
:::
---
url: "https://docs.succapp.com/v5/guide/devops/install/database/GaussDB.md"
htmlUrl: "https://docs.succapp.com/v5/devops/database/GaussDB"
title: "华为高斯数据库配置"
---
# 华为高斯数据库配置
GaussDB 200是一款具备分析及混合负载能力的分布式数据库，支持x86和Kunpeng硬件架构，支持行存储与列存储，提供PB(Petabyte)级数据分析能力、多模分析能力和实时处理能力，用于数据仓库、数据集市、实时分析、实时决策和混合负载（HTAP）等场景，广泛应用于金融、政府、电信等行业核心系统。
SuccBI支持GaussDB 200，作为事务性和分析性的数据库。
## Driver配置{#driver}
```json
{
"driver": "com.huawei.gauss200.jdbc.Driver",
"url": "jdbc:gaussdb://host:25308/dbname"
}
```
SuccBI使用gsjdbc200.jar驱动。
[线上文档](https://support.huawei.com/enterprise/zh/cloud-computing/gaussdb-200-pid-21407429?category=installation-upgrade)
## 详细说明{#description}
1. 可以作为默认数据源启动。
2. 也可以作为分析库使用。
3. 不支持修改数据表结构。
4. 不支持创建唯一索引。
5. 支持Copy语法，可以通过数据流快速导入数据。
6. 支持常见的应用分析，包括window函数的使用。
:::tip 说明
GaussDB(DWS)默认不支持修改已创建好的某个数据库的字符编码格式，为了适应全球化的需求，使数据库编码能够存储与表示绝大多数的字符，建议创建Database的时候使用`UTF8`编码。具体可参考[官方文档](https://doc.hcs.huawei.com/zh-cn/usermanual/dws/dws_03_0085.html)。
:::
---
url: "https://docs.succapp.com/v5/guide/devops/install/middleware/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/middleware"
title: "中间件"
---
---
order: 3
navTitle: 中间件
---
# 中间件
---
url: "https://docs.succapp.com/v5/guide/devops/install/middleware/tomcat.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/tomcat"
title: "Tomcat安装配置"
---
---
order: 1
navTitle: Tomcat
---
# Tomcat安装配置
\[\[toc]]
## 获取tomcat安装包{#get-installer}
### 下载tomcat{#download}
1. 访问下载需要的tomcat版本，推荐下载：[apache-tomcat-8.5.7x.zip](https://mirrors.tuna.tsinghua.edu.cn/apache/tomcat/tomcat-8/v8.5.78/src/)。
2. 或点击[这里](https://www.jianguoyun.com/p/Dbv9Z1sQ3O-gChiY5KwE)下载
### 解压tomcat安装包{#unzip}
解压缩apache-tomcat-8.5.70.zip后：
1. 清理不需要的文件，需要删除webapps目录下的所有子目录，包括`ROOT`、`manager`等
2. 对于macOS或Linux平台，需要让sh文件都是可执行的，在tomcat目录中执行命令行：`chmod +x bin/*.sh`
3. 将WAR包改名为`ROOT.war`放到tomcat的`webapps`目录下
## 设置启动环境变量{#env}
linux、macOS平台在`bin`目录下新建`setenv.sh`文件，内容如下：
```sh
#!/bin/sh
# 设置语言为中文
export LANG=zh_CN.UTF-8
# 设置java最大内存
export JAVA_OPTS="$JAVA_OPTS -Xmx4G"
# 设置工作目录，参考《工作目录和默认数据库配置》
export JAVA_OPTS="$JAVA_OPTS -Dsucc.workdir=/path/to/workdir（请修改这个路径）"
# 设置其他环境变量
export JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Djava.net.preferIPv4Stack=true -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true"
```
windows是`setenv.bat`，内容如下：
```batch
rem 设置java最大内存
set "JAVA_OPTS=%JAVA_OPTS% -Xmx4G"
rem 设置工作目录，参考《工作目录和默认数据库配置》
set "JAVA_OPTS=%JAVA_OPTS% -Dsucc.workdir=C:\path\to\workdir（请修改这个路径）"
rem 设置其他环境变量
set "JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Djava.net.preferIPv4Stack=true -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true"
```
:::warning
windows配置工作目录路径时，盘符需要为大写，如C:\path\to\workdir，否则系统设置会提示异常。
:::
## 安装JDBC驱动{#jdbc-drivers}
见[JDBC驱动安装配置](../basic-install/jdbc-drivers.md)。
## tomcat配置{#config}
### Tomcat安全性设置{#security}
在`/conf/web.xml`中`sesion-config`节点配置`cookie-config`，增强Tomcat安全性：
- `http-only`属性：当设置为`true`时，通过程序(JS脚本、Applet等)将无法读取到Cookie信息，这样能有效的防止XSS攻击。
```xml
true
```
- `secure`属性(仅限使用https协议时)：当设置为`true`时，创建的Cookie会被以安全的形式向服务器传输，也就是只能在https连接中被浏览器传递到服务器端进行会话验证，不会被窃取到Cookie的具体内容。
:::warning
使用**http**协议的情况下，设置`secure`为`true`会导致Cookie无法发送给服务器，请确认当前使用的协议为**https**
:::
```xml
true
```
- Tomcat AJP协议文件包含/文件读取漏洞：Tomcat AJP协议存在缺陷，攻击者利用该漏洞可通过构造特定参数，读取webapp下的任意文件。若目标服务器同时存在文件上传功能，攻击者可进一步实现远程代码执行
**解决方法1**:
升级Tomcat至`7.0.100`、`8.5.51`、`9.0.31`以后的版本，新版本中已经修复了该漏洞
**解决方法2**：
在`/conf/web.xml`中注释AJP配置，禁用AJP协议端口
```xml
```
- `SameSite`属性：Cookie的SameSite属性用来限制第三方Cookie，从而减少安全风险，可以设置以下3种值：
- Strict：最为严格，完全禁止第三方 Cookie，跨站点时，任何情况下都不会发送Cookie
- Lax：规则稍稍放宽，大多数情况也是不发送第三方Cookie，但是导航到目标网址的Get请求除外
- None：不限制第三方Cookie，前提是必须同时设置`Secure`属性
可根据实际需求，在`conf/context.xml`中配置属性值
```xml
```
### 优化Tomcat性能{#performance}
优化tomcat性能，避免tomcat出现如下警告：
```bash
21-Nov-2019 15:54:04.600 警告 [TimerService-Timer] org.apache.catalina.webresources.Cache.getResource 无法将位于[/WEB-INF/resources/sysdata/settings/templates/fapp/GZRWGL/package.json]的资源添加到Web应用程序[]的缓存中，因为在清除过期缓存条目后可用空间仍不足 - 请考虑增加缓存的最大空间。
```
将位于conf目录下的context.xml改为如下：
```xml
WEB-INF/web.xml
${catalina.base}/conf/web.xml
```
### 修改Tomcat端口号（可选）{#port}
优化网络传输，修改`/conf/server.xml`中的`Connector`添加自动压缩功能，并按需修改tomcat端口号：
```xml
```
### 修改Tomcat会话超时时间（可选）{#timeout}
当用户在一定时间内都未进行操作时，为了更好的利用资源，系统会自动注销该用户，修改`/conf/web.xml`中的`session-timeout`可设置该会话超时时间，默认为30分钟，负数或0为不限制超时时间：
```xml
30
```
## 常见问题{#faq}
### Windows下tomcat控制台乱码{#messycode}
**问题原因**：使用`startup.bat`启动tomcat时，它会读取`catalina.bat`的代码并打开一个新终端运行，而Windows命令行终端的默认编码为`GBK`，与tomcat的默认字符集`UTF-8`不一致
**解决方法**（任选其一）：
1. 修改`/bin/startup.bat`中的启动参数，将`start`修改为`run`，在运行`startup.bat`后不会打开新的控制台
```sh
call "%EXECUTABLE%" run %CMD_LINE_ARGS%
```
2. 修改系统注册表，规定名称为`Tomcat`的命令行终端字符编码为`UTF-8`，具体步骤如下：
1. `Windows` + `R`打开`运行`，在运行框中输入`regedit`，进入注册表编辑器中
2. 在**HKEY\_CURRENT\_USER**>**Console**>**Tomcat**(若不存在则创建)中修改`CodePage`为十进制的`65001`
---
url: "https://docs.succapp.com/v5/guide/devops/install/middleware/BES.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/BES"
title: "BES安装部署"
---
---
order: 2
navTitle: BES
---
# BES安装部署
[BES Application Server](https://www.bessystem.com/product/0ad9b8c4d6af462b8d15723a5f25a87d/info)（以下简称BES），是北京宝兰德软件股份有限公司自主研发的、具有自主知识产权的、遵循Java EE规范的应用服务器，支持最新的行业标准，SuccBI同样支持在BES部署，步骤如下：
\[\[toc]]
## BES控制台安装{#console-install}
### 解压安装包{#unzip}
解压`BES-CLUSTER-9.5.2.zip`到指定目录：
```sh
mkdir /usr/local/BES-CONSOLE
tar -zxvf BES-CLUSTER-9.5.2.tar.gz -C /usr/local/BES-CONSOLE
```
### 启动控制台{#start-console}
1. `BES-CONSOLE/bin` 下执行`initstore.sh`初始化产品。
2. `BES-CONSOLE/bin` 下执行`startManagement`启动管理控制台。
启动后访问http://TongWebIP:6900/console 进入BES控制台，初始用户名和密码分别是`admin`、`B#2008_2108#es`，界面如下图：
## BES管理框架搭建{#build-frame}
BES对资源和应用的管理分为三级：主机、节点、实例
- 主机：安装运行BES的设备，可以是一台物理机，虚拟机或其他提供主机服务的设备。
- 节点：每个实例都需要托管到一台物理计算机上，BES新建了一个轻量级的托管代理进程（即节点管理器）来管理应用服务器实例的生命
周期。
- 实例：web应用运行的载体，类似于整个Tomcat
### 添加主机{#add-host}
在控制台左侧导航区点击`主机管理`进入`主机列表`界面，点击`添加`，填写部署服务器的连接信息
添加完成后可在列表中点击进入该主机，点击左下角`ping`按钮，确认能够正常连接
### 添加节点{#add-node}
在控制台左侧导航区点击`节点管理`进入`节点列表`界面，点击`新建`，填写`节点名称`、`节点目录`、`JAVA_HOME`，其他默认即可
新建完成后可在节点列表查看该节点，此时状态为`未安装`、`未注册服务`，点击上方的`安装`、`注册服务`按钮，安装BES并将其注册为系统服务，服务器重启后，节点会自动启动并将节点下所有实例一起启动。
### 新建实例{#add-example}
在控制台左侧导航区点击`实例管理`进入`实例列表`界面，点击`新建`，填写实例信息，注意此处我们选择独立实例，其他默认即可
新建完成后可在实例列表查看该实例，勾选后启动该实例即可
## 部署SuccBI应用{#deploy-succbi}
在控制台左侧导航区点击**应用管理**>**常用应用**，进入应用列表界面，点击`部署`，选择`分发模式`，上传[版本更新](../../../whatsnew/README.md)中获取的war文件
点击`下一步`，在`部署目标`中选择[已创建的实例](#add-example)
点击`下一步`，在`部署属性`中配置`应用名称`、`应用前缀(即上下文根)`，其他属性默认即可
## 配置实例{#config-example}
应用部署完成后，还需要对实例进行配置，例如修改端口号、配置JVM参数等，在`实例列表`点击[已创建的实例](#add-example)，进入实例配置界面
### 修改端口号{#port}
BES应用默认端口号为18080，可在**基本信息**>**系统属性**中，修改`http-listener-1_port`
### 配置启动参数{#env}
与[tomcat启动环境变量](./tomcat.md#env)一致，切换上方标签页至`JVM`配置
此处可配置JDK目录、JVM最大/最小内存等基础配置
`JVM选项`可配置扩展参数，必须参数配置见下表，更多参数参考[环境变量](../basic-install/jvm-sys-properties.md)
| JVM参数 | 值 |
| :---- |:----|
|-Dfile.encoding|UTF-8|
|-Djava.awt.headless|true|
|-Dsucc.workdir|/path/to/workdir（请修改这个路径）|
## 完成部署{#complete}
实例配置完成后，按照提示重新启动实例，此时SuccBI应用也会同时启动，至此BES下的SuccBI部署已完成，访问http://BES-IP:端口号/上下文根即可访问SuccBI，进入初始化界面。
## 集群部署{#cluster}
由于控制台中可直接对主机进行管理，因此部署集群节点只需要新建主机即可，具体步骤如下：
1. 按照本文内容，以集群节点服务器连接信息新建[主机](#add-host)、[节点](#add-node)、[实例](#add-example)，并在新实例中部署SuccBI应用
2. 按照[集群部署](../../cluster/README.md)中的步骤，配置并加入集群即可
部署完成的应用目标状态应如下图，在两个实例中都为`已启动`
## 常见问题{#faq}
### 无法访问管理控制台
请检查防火墙是否关闭或者开放了`6900`端口。
### 远程节点创建失败
请检查远程节点所在主机用户名密码是否正确，远程机器是否开启了`ssh`服务。
---
url: "https://docs.succapp.com/v5/guide/devops/install/middleware/TongWeb.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/TongWeb"
title: "东方通(TongWeb)安装部署"
---
---
order: 3
navTitle: 东方通(TongWeb)
---
# 东方通(TongWeb)安装部署
[TongWeb](http://m.tongtech.com/Application-Support/Application-Support-17.html)是北京东方通科技股份有限公司自主研发的、具有自主知识产权的、遵循JavaEE7 Web Profile规范的企业级应用服务器，SuccBI同样支持在TongWeb部署，步骤如下：
\[\[toc]]
## TongWeb安装{#install}
### 上传并执行安装程序{#upload-install}
上传TongWeb安装程序，如`Install_TW7.0.4.1_Enterprise_Liunx.bin`至服务器机器，并赋予可执行权限：
```sh
chmod +x Install_TW7.0.4.1_Enterprise_Liunx.bin
```
执行如下命令，按照指示信息开始安装：
```sh
./Install_TW7.0.4.1_Enterprise_Liunx.bin –i console
```
当日志中出现如下一行，没有异常信息，说明TongWeb启动成功：
```sh
[2020-12-28 11:57:24] [INFO] [core] [TongWeb server startup complete in 7839 ms.]
```
### 启动TongWeb{#start}
启动TongWeb需要进入`TongWeb/bin`目录，执行如下命令：
```sh
./startservernohup.sh
```
相同的，执行`stopserver.sh`即可停止TongWeb
启动后访问http://TongWebIP:9060/console 进入TongWeb控制台，默认用户名、密码为`thanos`、`thanos123.com`，界面如下图：
## WEB容器配置{#container-config}
TongWeb支持在控制台中配置WEB容器，类似于在[Tomcat](./tomcat.md)中修改`Tomcat/conf`中的配置。
### 字符集配置{#haracter-set}
在控制台左侧导航区点击**WEB容器配置**>**容器配置**，将`默认请求参数解码字符集`、`默认应答编码字符集`均修改为`UTF-8`
在控制台左侧导航区点击`HTTP通道管理`，选择`tong-http-listener`，在`其他设置`中将`URL编码格式`修改为`UTF-8`
### 端口号修改{#port}
同样在`tong-http-listener`中，修改`监听端口`即可，默认为**8088**
## 部署SuccBI应用{#deploy-succbi}
在控制台左侧导航区点击`应用管理`，进入应用部署界面，点击`部署应用`
`部署文件`选择[版本更新](../../../whatsnew/README.md)中获取的war文件，上传完毕后，点击`开始部署`，进入应用属性配置界面
以下属性按需配置：
- 应用名称：部署后`应用管理`界面显示的名称
- 应用前缀：即访问系统URL的上下文根
- 其他属性：均选择默认配置即可
点击`下一步`，设置虚拟主机为默认的`server`后，即可完成部署，在`应用管理`界面新增了SuccBI应用
## 配置启动参数{#env}
与[tomcat启动环境变量](./tomcat.md#env)一致，在控制台左侧导航区点击`启动参数配置`，在`JVM参数`中配置JVM内存
在`其他JVM参数`中配置JVM扩展参数，必须参数配置如下，更多参数参考[环境变量](../basic-install/jvm-sys-properties.md)
```sh
-Dfile.encoding=UTF-8
-Djava.awt.headless=true
-Dsucc.workdir=/path/to/workdir（请修改这个路径）
-Dsucc.localWebAddress=http://ip:port
```
:::tip
在TongWeb中默认端口号为管理控制台的`9060`，而不是部署应用的监听端口，因此必须通过`-Dsucc.localWebAddress`来指定SuccBI的访问地址，否则在系统中会出现无法查看仪表板的情况，例如`-Dsucc.localWebAddress=http://192.168.3.50:8088`
:::
## 完成部署{#complete}
启动参数配置完成后，重启Tongweb，此时SuccBI应用也会同时启动，至此TongWeb下的SuccBI部署已完成，访问http://TongWebIP:端口/上下文根 进入初始化界面
## 集群部署{#cluster}
1. 按照本文内容，在集群节点服务器分别安装TongWeb并部署SuccBI
2. 按照[集群部署](../../cluster/README.md)中的步骤，配置并加入集群即可
## 常见问题{#faq}
### 请求路径出现乱码{#error-codes}
**问题原因：**
TongWeb容器中的默认字符集均为`GBK`，SuccBI使用`UTF-8`，导致请求路径转码不正确
**解决方法：**
手动修改TongWeb字符集配置至`UTF-8`，可参考[字符集配置](#haracter-set)
### 可视化查看界面出现编译错误{#compilation-errors}
**问题原因：**
在TongWeb中默认端口号为管理控制台的`9060`，而不是部署应用的监听端口，会导致获取端口错误
**解决方法：**
通过`-Dsucc.localWebAddress`来指定SuccBI的访问地址，可参考[配置启动参数](#env)
---
url: "https://docs.succapp.com/v5/guide/devops/install/middleware/ApusicAAS.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/ApusicAAS"
title: "金蝶天燕(ApusicAAS)安装部署"
---
---
order: 6
navTitle: 金蝶天燕(ApusicAAS)
---
# 金蝶天燕(ApusicAAS)安装部署
[ApusicAAS](https://www.apusic.com/list-117.html)是金蝶天燕云计算股份有限公司自主研发的、具有自主知识产权的、全面支持JakartaEE8/9的技术规范的企业级应用服务器，SuccBI同样支持在ApusicAAS部署，步骤如下：
\[\[toc]]
## ApusicAAS安装{#install}
### 上传并执行安装程序{#upload-install}
上传ApusicAAS安装程序，如`AAS-V10.zip`至服务器机器，解压即可：
执行如下命令，解压即为安装：
```sh
unzip AAS-V10.zip
```
### 启动ApusicAAS{#start}
启动ApusicAAS需要进入`ApusicAAS/aas/bin`目录，执行如下命令启动默认域，初次启动默认域时，会要求为audit、admin、secure账户设置密码，按提示输入即可：
```sh
./asadmin start-domain
```
```sh
#出现如下文字内容即代表启动成功
This domain requires an administrative password to be set before
the domain can be started. Please specify an administrative password.
Enter an administrative password for user "audit">
Enter an administrative password for user "audit" again>
Password for User audit has change Successfully!
Enter an administrative password for user "admin">
Enter an administrative password for user "admin" again>
Password for User admin has change Successfully!
Enter an administrative password for user "secure">
Enter an administrative password for user "secure" again>
Password for User secure has change Successfully!
Waiting for mydomain to start .....
Successfully started the domain : mydomain
domain Location: /data/ApusicAS/aas/domains/mydomain
Log File: /data/ApusicAS/aas/domains/mydomain/logs/server.log
Admin Port: 6848
Command start-domain executed successfully.
```
如需停止ApusicAAS，则执行以下命令停止默认域：
```sh
./asadmin stop-domain
```
启动后访问https://ApusicAASIP:6848/ 进入ApusicAAS控制台，登录用户使用初始化时设置的admin账户密码，界面如下图：
## 默认域配置{#mydomain-config}
ApusicAAS支持在控制台中配置默认域，类似于在[Tomcat](./tomcat.md)中修改`Tomcat/conf`中的配置。
### 端口号修改{#port}
在控制台左侧导航区点击**配置**>**server-config**>**HTTP服务**>**HTTP监听程序**，ApusicAAS默认存在三个监听端口：
- `admin-listener`：控制台端口`6848`
- `http-listener-1`：应用HTTP协议端口`6888`
- `http-listener-2`：应用HTTPS协议端口`6887`
在控制台点击`HTTP监听程序`页面的对应监听名称，修改`端口`中的内容保存即可
### JVM启动参数配置{#JVM-config}
在控制台左侧导航区点击**配置**>**server-config**>**JVM设置**，点击上方`JVM选项`切换到参数配置界面
点击`添加JVM选项`必须参数配置如下，更多参数参考[环境变量](../basic-install/jvm-sys-properties.md)
```sh
-Dfile.encoding=UTF-8
-Dsun.jnu.encoding=UTF-8
-DLANG=zh_CN.UTF-8
-Dsucc.workdir=/path/to/workdir
-Dsucc.localWebAddress=http://ip:port
```
:::tip
- 一些其他的JVM配置，如`-Djava.awt.headless=true`、`-Djava.net.preferIPv4Stack=true`，在ApusicAAS已默认存在，可在列表中查看
- 在ApusicAAS中默认端口号为管理控制台的`6848`，而不是部署应用的监听端口，因此必须通过`-Dsucc.localWebAddress`来指定SuccBI的访问地址，否则在部署应用时会出现异常部署失败，例如`-Dsucc.localWebAddress=http://192.168.88.100:6888`
:::
### 内存分配{#memory-config}
ApusicAAS最大内存默认已配置，大小为`1024m`，位置在`JVM选项`页面列表下方，最小内存无默认配置需自行添加，最大内存和最小内存具体大小要**按照自身需求**以及**服务器实际配置**修改
## 部署SuccBI应用{#deploy-succbi}
在控制台左侧导航区点击`应用程序`，进入应用程序部署界面，点击`部署`
`部署文件`使用[版本更新](../../../whatsnew/README.md)中获取的war文件，可选择从ApusicAAS前台上传文件，也可以选择提前将文件上传到服务器进行选择，上传完毕后，会自动选择**类型**为`Web应用程序`
以下属性按需配置：
- 上下文路径：即访问系统URL的上下文根
- 应用程序名称：部署后`应用程序`界面显示的名称
- 其他属性：均选择默认配置即可
设置虚拟服务器为默认的`server`后，点击右上角`确定`开始部署，部署完成后在`应用程序`界面新增了SuccBI应用
## 完成部署{#complete}
启动参数配置完成后，重启ApusicAAS，此时SuccBI应用也会同时启动，至此ApusicAAS下的SuccBI部署已完成，点击SuccBI应用右侧的`访问`，会列出应用的两个访问地址，择一访问即可
## 集群部署{#cluster}
1. 按照本文内容，在集群节点服务器分别安装ApusicAAS并部署SuccBI
2. 按照[集群部署](../../cluster/README.md)中的步骤，配置并加入集群即可
## 常见问题{#faq}
### 部署失败{#compilation-errors}
**问题原因：**
在ApusicAAS中默认端口号为管理控制台的`6848`，而不是部署应用的监听端口，会导致部署错误
**解决方法：**
通过`-Dsucc.localWebAddress`来指定SuccBI的访问地址，可参考[JVM启动参数配置](#JVM-config)
---
url: "https://docs.succapp.com/v5/guide/devops/install/cloud-platform/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/cloud-platform"
title: "云平台"
---
---
order: 4
navTitle: 云平台
---
# 云平台
---
url: "https://docs.succapp.com/v5/guide/devops/install/cloud-platform/huawei-cloud.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/huawei-cloud"
title: "华为鲲鹏云"
---
---
order: 2
navTitle: 华为鲲鹏云
---
# 华为鲲鹏云
[华为鲲鹏云](https://developer.huaweicloud.com/techfield/kunpeng.html)是华为云提供的基于鲲鹏处理器的云服务，且具备多核高并发的特点，适合用于AI、大数据等场景。SuccBI同样支持在华为鲲鹏云下部署，步骤如下：
\[\[toc]]
## 安装配置JDK{#jdk}
### 下载JDK{#jdk-upload}
由于鲲鹏云服务器使用ARM架构处理器，因此只能通过ARM架构的JDK安装包进行安装，可以从[oracle官方](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)下载ARM架构的JDK安装文件，上传到鲲鹏云服务器。
### 安装JDK{#jdk-install}
下载完成后，将压缩包解压到安装目录，并将目录名字改为`jdk`：
```sh
tar -zxvf jdk-11.0.10_linux-aarch64_bin.tar.gz /usr/local
mv /usr/local/jdk-11.0.10 /usr/local/jdk
```
配置系统变量：
```sh
vim /etc/profile
#在最后一行插入以下内容
export JAVA_HOME=/usr/local/jdk
export PATH=$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
```
加载生效：
```sh
source /etc/profile
```
配置完系统变量后就可以在命令行输入`java`获取命令参数帮助，输入`java -version`获取当前JDK版本。
:::warning
若使用其他版本的JDK安装包，配置完毕后，查看版本会提示报错`-bash: /usr/local/jdk/bin/java: cannot execute binary file: Exec format error`。
:::
## 安装配置node.js{#nodejs}
### 下载node.js{#node-upload}
鲲鹏云服务器配置node.js时同样只能使用ARM架构的node.js安装包进行安装，可以从[node.js官方](https://nodejs.org/zh-cn/download/)下载ARM架构的node.js安装文件，上传到鲲鹏云服务器。
### 安装node.js{#node-install}
下载完成后，将压缩包解压到安装目录，并将目录名字更改为`node`：
```sh
tar -zxvf node-v10.17.0-linux-arm64.tar.gz /usr/local
mv /usr/local/node-v10.17.0-linux-arm64 /usr/local/node
```
配置系统变量：
```sh
vim /etc/profile
#在最后一行插入以下内容
PATH=$PATH:/usr/local/nodejs/bin
```
加载生效：
```sh
source /etc/profile
```
配置完系统变量后可以在命令行输入`node --version`获取当前node.js版本。
## Tomcat安装配置{#tomcat-config}
按照[Tomcat安装配置](../middleware/tomcat.md)中的步骤进行配置并启动即可。
## 安装JDBC驱动{#jdbc-drivers}
数据库使用华为提供的`GaussDB(for MySQL)`和`GaussDB dws`数据库，当前SuccBI已支持对应数据库，用户可在[这里](https://www.jianguoyun.com/p/DdUp8kIQ3O-gChjf1awE)(提取码：SuccBI)获取驱动文件进行配置，驱动安装见[JDBC驱动安装配置](../basic-install/jdbc-drivers.md)。
## 集群部署{#cluster}
按照[集群部署](../../cluster/README.md)中的步骤，配置并加入集群即可。
## 常见问题{#faq}
### 安装JDK和node.js时提示执行格式错误{#error-format}
**问题原因：**
鲲鹏云为ARM架构服务器，使用x86架构的安装包进行配置时会提示`-bash: /usr/local/jdk/bin/java: cannot execute binary file: Exec format error`。
**解决方法：**
请在[oracle](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)和[node.js](https://nodejs.org/zh-cn/download/)官网下载对应的ARM架构安装包重新进行配置安装。
---
url: "https://docs.succapp.com/v5/guide/devops/install/cloud-platform/CDN.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/cdn"
title: "接入CDN服务"
---
---
order: 4
navTitle: CDN
---
# 接入CDN服务
接入CDN服务可以在服务器的带宽和性能有限的情况下，有效的加快用户访问系统的速度。本文主要介绍SuccBI如何接入CDN服务。
## CDN加速类型{#type}
1. 静态资源加速。
站点需要支持动静分离，静态资源使用单独的CDN域名来访问。
2. 全站加速。
不区分动态资源和静态资源，整个站点使用一个域名作为CDN的加速域名，一般CDN服务不会加速动态请求，反而会由于回源导致响应时间更长。也有一些支持全站加速的CDN服务，例如腾讯的[ECDN](https://cloud.tencent.com/product/ecdn)，多用于无法动静分离的站点。
SuccBI已支持动静分离，配置CDN后只有静态资源会通过CDN加速，避免了动态资源响应慢的问题，同时节省CDN的流量。
## 准备域名{#prepare-domain}
1. 源站域名：SuccBI实际业务域名。
2. 加速域名：需要使用CDN加速的域名。SuccBI只会使用CDN加速静态资源，需要能通过该域名访问静态资源，因此也要使用该域名反向代理SuccBI服务，可以是和源站域名同源的二级域名。
例如源站域名为`demo.succbi.com`，加速域名为`static.succbi.com`，使用`static.succbi.com`访问的资源都会通过CDN加速。
## 注册、开通CDN服务{#subscribe}
首先需要选择一个CDN服务商开通CDN服务，常见的服务商有：
1. [腾讯云](https://cloud.tencent.com/product/cdn)
2. [阿里云](https://www.aliyun.com/product/cdn)
3. [华为云](https://www.huaweicloud.com/product/cdn.html)
4. [Cloudflare](https://www.cloudflare.com/zh-cn/cdn)
## 基础配置{#base-config}
开通CDN服务后需要完成如下基础配置：
### 域名{#domain}
参考[阿里云](https://help.aliyun.com/document_detail/122181.html?spm=5176.11785003.0.dtree-leaf.5046142fi0qgJz)、[腾讯云](https://cloud.tencent.com/document/product/228/41215)官方文档添加并配置域名，将`加速域名`配置为之前准备好的`static.succbi.com`，`源站域名`配置为`demo.succbi.com`。
### CNAME{#cname}
加速域名添加成功后，CDN服务商会分配对应的CNAME地址，需要完成CNAME配置，CDN加速服务才会生效。参考[阿里云](https://help.aliyun.com/document_detail/27144.htm?spm=a2c4g.11186623.2.30.42d8504dn0ZSB9#task-187531)、[腾讯云](https://cloud.tencent.com/document/product/228/3121)官方文档，将之前准备好的`static.succbi.com`映射到腾讯云提供的CNAME域名。
### HTTPS证书{#https}
为了保证传输安全，正式项目一般都会使用HTTPS协议，CDN服务中也需要同步配置HTTPS证书。参考[阿里云](https://help.aliyun.com/document_detail/27118.html?spm=a2c4g.11174283.6.624.3d6b70350yglON)、[腾讯云](https://cloud.tencent.com/document/product/228/41687)官方文档配置HTTPS证书。
## 回源配置{#back-to-origin}
CDN节点未缓存请求资源或缓存资源已到期时，会回源站获取资源，返回给客户端，并将资源缓存，需要配置以下选项：
### 回源HOST{#origin-host}
源站决定了回源时，请求到哪个IP，而回源HOST决定回源请求访问到该IP上的哪个站点，具体可参考[阿里云](https://help.aliyun.com/document_detail/27131.html?spm=a2c4g.11186623.6.603.41a7f625ps1myN)、[腾讯云](https://cloud.tencent.com/document/product/228/41334)。这里设置为**加速域名**，即`static.succbi.com`。
### 回源协议{#origin-protocol}
指回源时使用的协议和客户端访问资源时的协议保持一致，即如果客户端使用HTTPS方式请求资源，当CDN节点上未缓存该资源时，节点会使用相同的HTTPS方式回源获取资源，具体可参考[阿里云](https://help.aliyun.com/document_detail/34949.html?spm=a2c4g.11186623.6.604.758466f2w5kRUn)、[腾讯云](https://cloud.tencent.com/document/product/228/41334)。这里设置为**HTTPS**。
## 缓存配置{#cache}
使用CDN加速静态资源时，CDN会将源站上的资源缓存到距离客户端最近的CDN节点上。当访问该静态资源时，可直接从CDN的缓存节点上获取，有效避免通过较长的链路回源，提高资源访问效率，需要配置以下选项：
### 缓存HTTP响应头{#response-header}
CDN节点响应用户的HTTP请求时，需要增加如下HTTP响应头以实现跨域访问，配置方法参考[阿里云](https://help.aliyun.com/document_detail/27137.html?spm=a2c4g.11186623.6.618.786b5241cswn4j)、[腾讯云](https://cloud.tencent.com/document/product/228/41737)官方文档。
| 响应头 | 值 |
| --- | --- |
|Access-Control-Allow-Origin|\*|
|Access-Control-Allow-Methods|POST,GET|
|Access-Control-Allow-Credentials|true|
### 缓存过期时间{#cache-expiration}
为了保证CDN缓存命中率，将`js,css,json,spg`文件后缀的缓存过期时间设置尽可能长，配置方法参考[阿里云](https://help.aliyun.com/document_detail/27136.html?spm=a2c4g.11186623.6.616.705b487cHUzG1W)、[腾讯云](https://cloud.tencent.com/document/product/228/47672)官方文档。
### 缓存键规则{#cache-key-rules}
SuccBI静态资源的url都带有版本号参数，可以避免版本更新后CDN依然使用旧的缓存。但是可能部分CDN服务默认会忽略url参数，只用路径作为缓存 key，此时需要做一些额外的设置，[阿里云](https://help.aliyun.com/document_detail/27128.html?spm=5176.11785003.0.dexternal.5046142fi0qgJz)、[腾讯云](https://cloud.tencent.com/document/product/228/47671)都提供了`过滤参数`的选项，关闭或设置为不过滤即可。
## 性能优化{#optimization}
设置加速域名的性能优化功能，缩小访问文件的体积，提升加速业务的效率，需要配置以下选项：
### 智能压缩{#intelligent-compression}
对静态文件类型进行Gzip压缩，有效减少用户传输内容大小，参考[阿里云](https://help.aliyun.com/document_detail/27127.html?spm=a2c4g.11186623.6.647.189bf625Ua5bGJ)、[腾讯云](https://cloud.tencent.com/document/product/228/41736)官方文档，设置开启即可。
## 更改系统设置{#config-syssettings}
1. 在**系统设置** > **外部服务** > **CDN**中配置好加速域名，例如 `static.succbi.com`，保存后即可生效。
2. 在**系统设置** > **安全设置** > **安全等保**中启用跨域，并配置跨域信任域为**源站域名**，例如：`https://demo.succbi.com/v5`。
至此，SuccBI接入CDN服务配置已完成，可打开**源站域名**的任意页面，监控静态资源请求路径是否为**加速域名**，以此判断是否配置成功。
## 常见问题{#FAQ}
### 修改了CDN服务配置后，访问业务域名发现修改未生效{#cdn-cache}
由于CDN节点回源后将本次获取的静态资源缓存，因此修改配置后，需要手动刷新CDN缓存，强制CDN节点回源并获取最新文件，可参考[阿里云](https://help.aliyun.com/document_detail/27140.html?spm=a2c4g.11186623.6.692.39e8210cDtcxyf)、[腾讯云](https://cloud.tencent.com/document/product/228/6299)官方文档进行操作。
### 配置了错误的CDN域名，导致系统无法访问{#cdn-domain-config-error}
此时可以添加启动参数`-Dsucc.disableCDN=true`来禁用 CDN，参考:[启动时支持的环境变量](../basic-install/jvm-sys-properties.md)。然后重启环境将设置修改正确即可。
### 跨域异常{#CORS-error}
如果加载 CDN 域名下的资源时出现了跨域错误，请先检查[更改系统设置](#config-syssettings)步骤中是否启用了跨域，并正确配置了`跨域信任域`。
如果已经正确配置了，有可能是反向代理服务器或者 CDN 服务的相关配置中添加了一些额外的跨域响应头，请检查并去掉这些配置。
### 重定向的次数过多异常{#too-many-redirects}
**问题分析：**
源站开启了HTTP重定向至HTTPS的功能，并且CDN控制台上配置的回源端口为80。在这种情况下，由于CDN回源端口为80，客户端无论是通过HTTP还是HTTPS访问CDN加速域名时，CDN在回源的时候都是使用HTTP请求源站，此时会触发源站的HTTPS强制跳转逻辑，然后源站会要求CDN重新发送一个HTTPS的请求，但是CDN回源的时候仍然会发送HTTP回源请求，然后再进行跳转，以此类推，就会出现反复重定向问题，最终导致出现报错。
**解决方法：**
确认[回源HOST](#origin-host)设置为`加速域名`、[回源协议](#origin-protocol)设置为`HTTPS`
### 如何自定义哪些 url 使用/不使用 CDN 加速？{#custom-rules}
SuccBI 内部有自己的规则来判断哪些请求是静态资源，需要通过CDN加速。如果内部判断规则不符合预期，想要某些特定的请求地址使用/不使用CDN加速，可以通过脚本接口来自定义规则：
```typescript
/**
* 判断一个url是否需要走cdn域名（如ajax请求或者js模块加载的url）。
*
* 系统内部有自动判断某个url是否走cdn域名，通过此函数还可以进一步个性化这个逻辑，覆盖系统内置的判断。
*
* 1. 需要在系统设置中设置cdn域名此函数才有效
*
* @param url 要判断是否走cdn的url，以'/'开头、含url参数、不包含contextpath。
* @returns 根据不同的返回结果会有不同的后续执行逻辑：
* 1. true，走cdn
* 2. false，不走cdn
* 3. undefined，留给系统自己判断
*/
SZ.events.onCheckNeedCDN = (url: string): boolean => {
};
```
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/tool-services"
title: "工具服务"
---
---
order: 5
navTitle: 工具服务
---
# 工具服务
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/linux-fonts.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/linux-fonts"
title: "Linux安装中文字体"
---
---
order: 2
navTitle: 系统字体
---
# Linux安装中文字体
当服务器（通常是Linux服务器）缺少中文字体时，系统产生的缩略图中可能会显示乱码或方块，此时需要为服务器添加相关字体。
## 检查字体{#check}
当系统产生的缩略图中显示乱码或方块时，可以使用`fc-list`命令检查服务器安装的字体中是否含有系统当前使用的字体。
如果服务器中没有该命令，需要先安装相关的软件包。
在Cent OS上，使用如下命令进行安装：
```sh
# 使fc-list命令正常运行
yum install fontconfig
# 使mkfontscale和mkfontdir命令正常运行
yum install mkfontscale
```
或点击[这里](https://www.jianguoyun.com/p/DcVvHoUQ3O-gChij5KwE)下载该命令及其相关依赖rpm包，使用如下命令安装
```sh
rpm -ivh rpm-name.rpm
```
安装顺序为
1. libfontenc-1.1.3-3.el7.x86\_64.rpm
2. freetype-2.3.11-17.el6.x86\_64.rpm
3. libXfont-1.5.1-2.el6.x86\_64.rpm
4. xorg-x11-font-utils-7.2-11.el6.x86\_64.rpm
5. fontpackages-filesystem-1.44-8.el7.noarch.rpm
6. stix-fonts-1.1.0-5.el7.noarch.rpm
7. fontconfig-2.8.0-5.el6.x86\_64.rpm
在Ubuntu上，使用如下命令进行安装：
```sh
# 使fc-list命令正常运行
sudo apt-get install fontconfig
# 使mkfontscale和mkfontdir命令正常运行
sudo apt-get install ttf-mscorefonts-installer
```
## 安装字体{#install}
1. 下载缺少的字体，常见的字体后缀为`.ttf`。常见的中文字体有：宋体、微软雅黑、楷体、黑体、隶书等，可以在[网络](http://www.fonts.net.cn/)上进行下载或者在电脑的`C:\Windows\Fonts`文件夹下搜索，即可找到
2. 将下载的字体拷贝到`/usr/share/fonts`目录下
3. 建立字体的索引信息，使用如下命令：
```sh
mkfontscale
mkfontdir
```
4. 更新字体的缓存，使用如下命令
```sh
fc-cache -fv
```
5. 重启tomcat，重启后字体才能生效
经过以上步骤字体就安装成功了，同时也可以将系统中包含的字体均安装在服务器上。只需将相关字体拷贝到字体目录下，重新运行以上的命令即可。
:::tip 安装字体提示
1. 字体文件仅支持`.ttf`格式
2. 字体文件建议在win7系统中拷贝；从win10系统中拷贝的字体是`.ttc`格式，产品不支持这种格式的字体
3. 在Linux中安装的字体文件名称需要与[字体名称对照表](#comparison)中保持一致
:::
### 字体名称对照表{#comparison}
| 字体名称 | 文件名称 |
| -------- | -----: |
| 宋体 | SimSun.ttf |
| 微软雅黑 | msyh.ttf |
| 黑体 | SimHei.ttf |
| 隶书 | SimLi.ttf |
| 楷体 | SimKai.ttf |
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/proxy-gaode.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/proxy-gaode"
title: "在内网访问高德地图"
---
---
order: 3
navTitle: 内网访问高德
---
# 在内网访问高德地图
在一些安全要求较高的内网环境，浏览器可能被禁止访问互联网，导致地图无法正常展示。此时，可以在内网部署一台代理服务器（下文简称为“GIS代理服务器”），GIS代理服务器只把互联网上的GIS地图服务代理到内网来。下面以代理互联网上的高德地图（https://gaode.com/）为例，说明如何配置内网GIS代理服务器。
| GIS代理服务访问高德地址 | GIS代理服务器本机需监听的端口 |
| ------ | :------------------------------ |
| {vdata,vdata01,vdata02,vdata03,vdata04}.amap.com | 8123 |
| {glyph,glyph01,glyph02,glyph03,glyph04}.amap.com | 200,200{1,4} |
| {sdf,sdf01,sdf02,sdf03,sdf04}.amap.com | 300,300{1,4} |
| {webrd01,webrd02,webrd03,webrd04}.is.autonavi.com | 820{1,4} |
| {wprd01,wprd02,wprd03,wprd04}.is.autonavi.com | 830{1,4} |
| {webst01,webst02,webst03,webst04}.is.autonavi.com | 840{1,4} |
| webapi.amap.com | 8121 |
| ditu.amap.com | 8122 |
| vdata.amap.com | 8123 |
| a.amap.com | 8124 |
| restapi.amap.com | 8125 |
| cache.amap.com | 8126 |
| g.alicdn.com | 8131 |
| at.alicdn.com | 8132 |
| w.cnzz.com | 8141 |
| c.cnzz.com | 8142 |
| q14.cnzz.com | 8143 |
| pcookie.cnzz.com | 8144 |
| log.mmstat.com | 8151 |
| res.mmstat.com | 8152 |
| gm.mmstat.com | 8153 |
| cnzz.mmstat.com | 8154 |
| uri.amap.com | 8119 |
| tm.amap.com | 8118 |
| mvt.amap.com | 8117 |
::: tip\
其中高德地址列表是需要GIS代理服务器开通访问这些地址的权限，本机监听的端口是开通客户端访问GIS代理服务器这些端口的权限
:::
## 将高德服务代理到内网
### 1. 安装部署apache httpd作为反向代理服务
以Centos为例，使用yum安装:
```sh
yum -y install httpd
```
### 2. 修改apache配置文件/etc/httpd/conf/httpd.conf
注释默认监听端口80，并从最后一行开始增加以下行
```sh
AddOutputFilterByType SUBSTITUTE;DEFLATE text/html application/javascript text/javascript text/css
SetOutputFilter INFLATE;SUBSTITUTE;DEFLATE
Substitute "s!\{vdata,vdata01,vdata02,vdata03,vdata04\}\.amap\.com!192.168.3.110:812{3}"
Substitute "s!webrd0(\{[\d\|,]+\})\.is\.autonavi\.com!192.168.3.110:820$1"
Substitute "s!wprd0(\{[\d\|,]+\})\.is\.autonavi\.com!192.168.3.110:830$1"
Substitute "s!webst0(\{[\d\|,]+\})\.is\.autonavi\.com!192.168.3.110:840$1"
Substitute "s!glyph(|0[0-9])\.amap\.com!192.168.3.110:200$1"
Substitute "s!sdf(|0[0-9])\.amap\.com!192.168.3.110:300$1"
Substitute "s|webapi\.amap\.com|192.168.3.110:8121"
Substitute "s|ditu\.amap\.com|192.168.3.110:8122"
Substitute "s|vdata\.amap\.com|192.168.3.110:8123"
Substitute "s|a\.amap\.com|192.168.3.110:8124"
Substitute "s|restapi\.amap\.com|192.168.3.110:8125"
Substitute "s|cache\.amap\.com|192.168.3.110:8126"
Substitute "s|g\.alicdn\.com|192.168.3.110:8131"
Substitute "s|at\.alicdn\.com|192.168.3.110:8132"
Substitute "s|w\.cnzz\.com|192.168.3.110:8141"
Substitute "s|c\.cnzz\.com|192.168.3.110:8142"
Substitute "s|q14\.cnzz\.com|192.168.3.110:8143"
Substitute "s|http\://pcookie\.cnzz\.com|http\://192.168.3.110:8144"
Substitute "s|https\://log\.mmstat\.com|http\://192.168.3.110:9443"
Substitute "s|log\.mmstat\.com|192.168.3.110:8151"
Substitute "s|res\.mmstat\.com|192.168.3.110:8152"
Substitute "s|gm\.mmstat\.com|192.168.3.110:8153"
Substitute "s|cnzz\.mmstat\.com|192.168.3.110:8154"
Substitute "s|uri\.amap\.com|192.168.3.110:8119"
Substitute "s|tm\.amap\.com|192.168.3.110:8118"
Substitute "s|mvt\.amap\.com|192.168.3.110:8117"
Substitute "s|https|http"
Listen 300
ProxyPass / http://sdf.amap.com/
ProxyPassReverse / http://sdf.amap.com/
Listen 30001
ProxyPass / http://sdf01.amap.com/
ProxyPassReverse / http://sdf01.amap.com/
Listen 30002
ProxyPass / http://sdf02.amap.com/
ProxyPassReverse / http://sdf02.amap.com/
Listen 30003
ProxyPass / http://sdf03.amap.com/
ProxyPassReverse / http://sdf03.amap.com/
Listen 30004
ProxyPass / http://sdf04.amap.com/
ProxyPassReverse / http://sdf04.amap.com/
Listen 200
ProxyPass / http://glyph.amap.com/
ProxyPassReverse / http://glyph.amap.com/
Listen 20001
ProxyPass / http://glyph01.amap.com/
ProxyPassReverse / http://glyph01.amap.com/
Listen 20002
ProxyPass / http://glyph02.amap.com/
ProxyPassReverse / http://glyph02.amap.com/
Listen 20003
ProxyPass / http://glyph03.amap.com/
ProxyPassReverse / http://glyph03.amap.com/
Listen 20004
ProxyPass / http://glyph04.amap.com/
ProxyPassReverse / http://glyph04.amap.com/
Listen 8119
ProxyPass / http://uri.amap.com/
ProxyPassReverse / http://uri.amap.com/
Listen 8118
ProxyPass / http://tm.amap.com/
ProxyPassReverse / http://tm.amap.com/
Listen 8117
ProxyPass / http://mvt.amap.com/
ProxyPassReverse / http://mvt.amap.com/
Listen 8121
ProxyPass / http://webapi.amap.com/
ProxyPassReverse / http://webapi.amap.com/
Listen 8122
ProxyPass / http://ditu.amap.com/
ProxyPassReverse / http://ditu.amap.com/
Listen 8123
ProxyPass / http://vdata.amap.com/
ProxyPassReverse / http://vdata.amap.com/
Listen 8124
ProxyPass / http://a.amap.com/
ProxyPassReverse / http://a.amap.com/
Listen 8125
ProxyPass / http://restapi.amap.com/
ProxyPassReverse / http://restapi.amap.com/
Listen 8126
ProxyPass / http://cache.amap.com/
ProxyPassReverse / http://cache.amap.com/
Listen 8127
ProxyPass / http://140.205.177.57/
ProxyPassReverse / http://140.205.177.57/
Listen 8131
ProxyPass / http://g.alicdn.com/
ProxyPassReverse / http://g.alicdn.com/
Listen 8132
ProxyPass / http://at.alicdn.com/
ProxyPassReverse / http://at.alicdn.com/
Listen 8139
ProxyPass / http://140.205.177.57/
ProxyPassReverse / http://140.205.177.57/
Listen 8141
ProxyPass / http://w.cnzz.com/
ProxyPassReverse / http://w.cnzz.com/
Listen 8142
ProxyPass / http://c.cnzz.com/
ProxyPassReverse / http://c.cnzz.com/
Listen 8143
ProxyPass / http://q14.cnzz.com/
ProxyPassReverse / http://q14.cnzz.com/
Listen 8144
ProxyPass / http://pcookie.cnzz.com/
ProxyPassReverse / http://pcookie.cnzz.com/
Listen 9443
ProxyPass / http://log.mmstat.com/
ProxyPassReverse / http://log.mmstat.com/
Listen 8151
ProxyPass / http://log.mmstat.com/
ProxyPassReverse / http://log.mmstat.com/
Listen 8152
ProxyPass / http://res.mmstat.com/
ProxyPassReverse / http://res.mmstat.com/
Listen 8153
ProxyPass / http://gm.mmstat.com/
ProxyPassReverse / http://gm.mmstat.com/
Listen 8154
ProxyPass / http://cnzz.mmstat.com/
ProxyPassReverse / http://cnzz.mmstat.com/
Listen 8201
ProxyPass / http://webrd01.is.autonavi.com/
ProxyPassReverse / http://webrd01.is.autonavi.com/
Listen 8202
ProxyPass / http://webrd02.is.autonavi.com/
ProxyPassReverse / http://webrd02.is.autonavi.com/
Listen 8203
ProxyPass / http://webrd03.is.autonavi.com/
ProxyPassReverse / http://webrd03.is.autonavi.com/
Listen 8204
ProxyPass / http://webrd04.is.autonavi.com/
ProxyPassReverse / http://webrd04.is.autonavi.com/
Listen 8301
ProxyPass / http://wprd01.is.autonavi.com/
ProxyPassReverse / http://wprd01.is.autonavi.com/
Listen 8302
ProxyPass / http://wprd02.is.autonavi.com/
ProxyPassReverse / http://wprd02.is.autonavi.com/
Listen 8303
ProxyPass / http://wprd03.is.autonavi.com/
ProxyPassReverse / http://wprd03.is.autonavi.com/
Listen 8304
ProxyPass / http://wprd04.is.autonavi.com/
ProxyPassReverse / http://wprd04.is.autonavi.com/
Listen 8401
ProxyPass / http://webst01.bis.autonavi.com/
ProxyPassReverse / http://webst01.is.autonavi.com/
Listen 8402
ProxyPass / http://webst02.is.autonavi.com/
ProxyPassReverse / http://webst02.is.autonavi.com/
Listen 8403
ProxyPass / http://webst03.is.autonavi.com/
ProxyPassReverse / http://webst03.is.autonavi.com/
Listen 8404
ProxyPass / http://webst04.is.autonavi.com/
ProxyPassReverse / http://webst04.is.autonavi.com/
```
### 3.启动apache httpd服务并验证接口正常访问
在服务器上使用curl命令测试高德接口以及本地监听响应是否一致
```sh
service httpd start
curl restapi.amap.com
curl 127.0.0.1:8125
```
## 设置高德服务器内网地址
高德服务器内网地址配置参见[内网代理](../../../sys-settings/more/remote-services/intranet-agent.md)
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/screenshot-service.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/screenshot-service"
title: "截图服务配置"
---
---
order: 5
navTitle: 截图服务
---
# 截图服务配置
SuccBI 的缩略图生成和后端导出功能依赖截图服务。当前产品实现中，Java 侧不会再直接启动本机
Chrome，而是通过系统设置中的 Browserless 地址连接截图运行时。
\[\[toc]]
## 运行环境要求
截图服务需要以下运行环境：
| 依赖 | 说明 |
| --- | --- |
| **Browserless 服务** | 截图服务实际连接的浏览器运行时 |
| **Node.js** | Browserless 运行所需环境 |
| **Chromium 浏览器** | Browserless 底层使用的浏览器内核 |
## 部署 Browserless{#install-browserless}
安装前确认 Node.js 已安装（参见 [Node.js 安装配置](../basic-install/Nodejs.md)）。
产品绿色包会通过 `packagefiles/server/playwright` 下的脚本启动 Browserless。日常部署时，需要保证：
1. Browserless 已随产品包正确部署并成功启动。
2. Browserless 使用的 Node.js 与浏览器运行时可正常访问。
3. Browserless 与 BI 服务之间网络互通。
如果是开发环境，也可以使用工作区中的 Browserless 启停入口进行调试。
## 配置截图服务地址{#configure-browserless}
启动 Browserless 后，需要在系统设置中配置截图服务地址。
位置：
- **系统设置** > **更多** > **远程服务** > **文档转换**
配置项：
- `sys.basic.browserServerUrl`
示例：
```text
ws://127.0.0.1:3000/chromium/playwright
```
系统前后端都基于这个地址访问 Browserless。详见[文档转换](../../../sys-settings/more/remote-services/doc-converter.md)。
## 配置 BI 回连地址{#configure-local-web-address}
当 Browserless 与 BI 服务不在同一台机器上时，需要额外配置 JVM 启动参数 `-Dsucc.localWebAddress`，
让 Browserless 能访问到 BI 当前服务地址，例如：
```properties
-Dsucc.localWebAddress=http://192.168.7.128:8080
```
如果 Browserless 与 BI 服务同机部署，通常无需额外配置。
## Linux 字体安装{#linux-fonts}
在 Linux 服务器上，如果截图中出现乱码或方块字，需安装中文字体，参见[Linux 安装中文字体](./linux-fonts.md)。
## 问题排查{#troubleshooting}
1. 检查 Browserless 是否已成功启动，并确认服务地址可访问。
2. 检查系统设置中的 `sys.basic.browserServerUrl` 是否填写正确。
3. 如果 Browserless 独立部署，检查 `-Dsucc.localWebAddress` 是否已正确配置为 Browserless 可访问的 BI 地址。
4. 检查 BI 服务日志，`Screenshotter` 相关日志包含详细的初始化和执行信息。
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/documents-converter.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/documents-converter"
title: "文档转换服务"
---
---
order: 5
navTitle: 文档转换服务
---
# 文档转换服务
SuccBI提供两种方式来进行文档转换：`纯JAVA转换`和`外部转换服务转换`。外部转换服务使用[documents4j](https://github.com/documents4j/documents4j)来部署服务。
\[\[toc]]
## 两种文档转换服务对比{#compare}
::: tip
如果[在系统中配置了外部转换服务器地址](#在succbi系统设置中配置documents4j服务器地址)，则系统仅会使用`外部转换服务`来进行转换
:::
| 对比 | 纯JAVA转换 | 外部转换服务转换 |
| :------: | :--------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------: |
| 部署 | 系统内置，无需额外配置。会占用当前java进程一定资源 | 单独部署,需要在系统中添加配置 |
| 转换效率 | 转换效率较高，并发量大时依赖应用服务器集群配置 | 调用进程外服务进行转换，存在固定的通信开销。documents4j支持集群部署，当存在大量转换调用时可配置多个转换服务器组成集群 |
| 转换效果 | 存在一定失真 | 使用Office软件本身的转换功能，可以做到和在`Microsoft office`中导出PDF一样的转换效果 |
::: tip
- 纯JAVA转换不支持修订，如果在文档中使用到了修订，请使用外部转换服务转换。
:::
## 配置外部转换服务{#tools}
### 安装office工具{#install-office}
Windows下安装Microsoft office不做介绍，以Centos为例，介绍Linux下安装Libreoffice。
保证外网访问正常，使用yum安装：
```bash
yum -y install libreoffice
```
等待安装成功后执行如下命令查找Libreoffice可执行文件所在路径：
```bash
whereis libreoffice
```
### 安装documents4j服务{#install-documents4j}
下载后直接启动即可：
1. 点击[这里](https://www.jianguoyun.com/p/DdsbrEIQ3O-gChid5KwE)下载
2. 启动documents4j服务
```bash
java -jar succ-documents4j-server-standalone-1.1.4.jar http://192.168.7.123:9998 -W true
```
在保存有documents4j-server-standalone-shaded.jar文件夹中在启动命令行工具，执行上述命令，即可在监听端口9998开启服documents4j服务，这里`-W true`标识使用`Microsoft office`开启转换服务。该命令行支持指定服务器上下文地址，如 `http://192.168.7.123:9998/context/`。
::: tip
- documents4j使用`Microsoft office`软件或者[libreoffice](https://www.libreoffice.org/)的内置工具来进行转换，若都没有安装，则服务器将会启动失败。
- `Microsoft office`提供的转换效果要优于`libreoffice`。
- 只有在安装有`Microsoft office 2010`以上版本的Windows机器上才能使用`Microsoft office`。
- `libreoffice`软件的安装没有操作系统限制。
- 使用`libreoffice`软件时候，为了更好转换效果，请安装最新的版本。
- `libreoffice`软件对于并发的支持效果很差，并发进行多个文件转换操作时候，失败率非常高。
- 若同时开启了`Microsoft office`（命令行参数指定`-W true`）和`libreoffice`(命令行参数指定 `-H {path}`)，documents4j服务将仅会使用`Microsoft office`。
:::
命令行主要参数说明：
1. -W,--msoffice \: 是否服务器中安装有`Microsoft office`软件，如果指定为true，则默认使用`Microsoft office`软件做为转换服务，默认为false。
2. -H,--libreoffice-path \：服务器中安装`libreoffice`软件的可执行文件位置，若指定了这个参数，则会开启使用`libreoffice`的转换服务。
3. -F，--base-folder \： 用于指定临时文件的创建地址，如果不指定，将使用操作系统默认指定的临时目录。
4. -P，--process-timeout \：执行一次转换的超时时间，单位为毫秒，默认值为300000。
5. -R，--request-timeout \：响应一起http请求的超时时间，单位为毫秒，默认值为。120000。
6. -S，--core-size \：转换服务的核心线程数量，默认为15。
7. -B，--fallback-size \：当所有核心线程都处于工作状态，需要添加新的工作线程时，一次性创建的线程个数，默认为15。
8. -T，--lifetime \：非核心线程的空闲时间，单位为毫秒，默认值为600000。
9. -V，--level \ 日志级别，可被设置的值有 `off`，`error`，`warn`，`info`，`debug`和 `trace`，默认值和建议设置的值为`warn`。
10. -L,--log \：指定记录日志文件位置，但是只能指定一个，可能会导致这个日志文件增长到非常大。默认打印在控制台。
### 在SuccBI系统设置中配置外部转换服务器地址{#succbi-settings}
在 **系统设置** > **更多** > **外部服务** > **文档转换** 中配置文档转换服务器地址:
服务器地址需要为SuccBI服务器可访问到的地址，可以是内网IP加端口号的组合：`http://192.168.1.2:9998`，也可以是域名：`https://example.com`。请务必要带上`http://`或者`https://`用于指定协议，避免出现访问不正确的问题。
---
url: "https://docs.succapp.com/v5/guide/devops/install/tool-services/unrar.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/unrar"
title: "unrar解压工具"
---
---
order: 7
navTitle: unrar
---
# unrar解压工具
在数据管理中上传文件数据源时支持rar格式，rar格式在上传时会自动解压，需要服务器提供unrar命令的支持。
## window配置unrar命令
下载方式有如下两种：
1. 从下载window版本的WinRAR软件，选择对应操作系统的版本是32位还是64位。
2. 点击[这里](https://www.jianguoyun.com/p/DbBK54QQ3O-gChiz7qwE)下载。
下载完成后，安装WinRAR，如安装到`C:\Program Files\WinRAR`
安装完成后，把该安装路径加到系统环境变量中的path中:
1. 在window 10中打开`控制面板`>`系统和安全`>`系统`。
2. 点击`高级系统设置`，在弹出的`系统属性`对话框中点击`高级`下的`环境变量`。
3. 在`用户变量`中找到`Path`,编辑该变量，将WinRAR的安装目录`C:\Program Files\WinRAR`加到最后面。不同的路径之间用分号分隔。
配置完路径后就可以使用war命令进行压缩、解压缩操作了。打开命令提示符，在窗口中输入 RAR -? 获取命令参数帮助。
## linux配置unrar命令
下载方式有如下两种：
1. 在Windows中从或[这里](https://www.jianguoyun.com/p/DW-zJz8Q3O-gChi17qwE)下载Linux版本的WinRAR软件，再上传到linux服务器
2. 在服务器上通过wget命令，直接下载安装包，使用如下命令：
```sh
wget http://www.rarlab.com/rar/rarlinux-x64-5.8.b4.tar.gz
```
下载完成后，将压缩包解压到安装目录，如安装到`/usr/local`，使用如下命令：
```sh
tar -zxvf rarlinux-x64-5.8.b4.tar.gz /usr/local
```
解压完成后，在`/usr/local/rar`就可以使用rar和unrar命令了，但如果想在全局使用，还需要创建连接添加到全局，使用如下命令:
```sh
ln -s /usr/local/rar/rar /usr/local/bin/rar
ln -s /usr/local/rar/unrar /usr/local/bin/unrar
```
创建连接后就可以在全局使用rar命令进行压缩、解压缩操作了。运行 RAR -? 获取命令参数帮助。
---
url: "https://docs.succapp.com/v5/guide/devops/install/security.md"
htmlUrl: "https://docs.succapp.com/v5/devops/install/security"
title: "系统安全性设置"
---
---
order: 31
navTitle: 系统安全
---
# 系统安全性设置
本文从用户、网络、应用、数据库等多层面介绍让系统更安全、数据不泄漏的具体措施。
## 密码安全
密码安全的范围包括web用户密码，数据库用户密码，操作系统用户密码，其中影响安全的因素有以下三点:
1. 密码复杂度： 密码复杂度也可以说是密码强度，需要密码的组成包含大小写字母，数字，特殊字符中的最少三种，且密码长度不低于8位。
2. 密码生存期： 密码有效期限一般可设置为不超过180天或者90天，到期后有7天的宽限期更新密码，不能重复设置为上次的密码。
3. 密码锁定： 密码多次错误应该有锁定策略，比如5次错误后锁定180秒，防止暴力破解行为。
开启操作系统密码安全策略的以及修改密码操作，以Centos为例：
```sh
#修改文件/etc/login.defs来配置密码生存期
PASS_MAX_DAYS 90 #修改密码最长过期时间为90天
PASS_MIN_LEN 8 #修改密码最短长度为8位
PASS_WARN_AGE 7 #密码过期后宽限期
#修改/etc/pam.d/system-auth来配合密码复杂度，最短8位，大小写、数字、特殊字符最少一位，不能与上次密码相同
password requisite pam_cracklib.so try_first_pass retry=3 type= minlen=8 ucredit=-1 lcredit=-1 ocredit=-1 dcredit=-1 remember=1
#修改/etc/pam.d/sshd配置远程登录密码错误锁定
auth required pam_tally2.so deny=5 lock_time=180 even_deny_root root_unlock_time=90
#修改用户密码，以test用户为例执行以下命令：
passwd test #当两次输入密码后回车，出现 "passwd: all authentication tokens updated successfully" 设置成功
```
数据库密码复杂度配置，mysql8默认已设置，这里以oracle为例：
```sh
#使用oracle本地用户登录sqlplus，执行以下命令
@?/rdbms/admin/utlpwdmg.sql
#修改数据库用户密码，以test用户为例
alter user test identified by 'Password#123';
```
## 系统防火墙
配置良好的防火墙规则，可以减少许多来自互联网、局域网的网络层扫描和攻击。在整个服务器网络环境中，各个机器应该只允许开放其必要的端口给其他服务器，比如web服务器，通常情况下只允许代理服务器访问其8080端口，允许其他web服务器访问7800集群端口。假设有以下服务器组成的环境。
| 服务器角色 | ip |
| ------ | :------------------------------ |
| 代理服务器 | 192.168.1.5 |
| web1 | 192.168.1.10 |
| web2 | 192.168.1.11 |
| DB | 192.168.1.20 |\
那么可以设置的防火墙规则为：
```sh
代理服务器
#允许任意客户端访问80，443端口
iptables -I INPUT -p tcp -m multiport --dports 80,443 -j ACCEPT
```
```sh
web1，web2同理
#允许代理服务器访问8080端口，允许对方访问7800端口
iptables -I INPUT -s 192.168.1.5 -p tcp --dport 8080 -j ACCEPT
iptables -I INPUT -s 192.168.1.11 -p tcp --dport 7800 -j ACCEPT
```
```sh
DB服务器
#允许web服务器访问数据库端口，以3306为例
iptables -I INPUT -s 192.168.1.10,192.168.1.11 -p tcp --dport 3306 -j ACCEPT
```
```sh
#列出防火墙规则，确定上面的规则是否配置成功
iptables -L -n
```
## 系统权限控制
权限的分配应该遵循最小化原则，包括web权限、数据库权限以及操作系统权限，这里只对后两种进行说明:
1. 数据库权限：
1. 在创建数据库用户时，应该只赋予其有限的操作权限，比如oracle，可以授权`grant connect，resource，create view`，mysql可授权`grant all on DBNAME.* to`，这样用户所做的操作无法对其他用户以及数据库全局造成影响
2. 应该坚决避免在web直接使用具有dba权限的用户。
2. 操作系统权限：
1. 各个应用程序，例如web应用，代理应用，数据库应用应该尽可能使用普通用户启动运行，防止应用在受到攻击时对操作系统造成更大范围的破坏，如果有些服务必须使用超级用户启动，那么仍需要确保它的工作进程使用普通用户运行。
2. 列出系统中所有管理员用户名 `cat /etc/passwd | awk -F":" '{ if($3==0) print $1}'` 对于未知的以及不需要的用户及时清理。
3. 建议使用单独的运维账号登录服务器做维护操作，且仅允许此账号切换到管理员。
```sh
#新增test用户为例，作为运维账号
useradd test
#增加test的附加组为wheel
usermod -G wheel test
#修改/etc/pam.d/su取消注释以下行
auth required pam_wheel.so use_uid
#使用test用户登录操作系统后，使用su - root切换至root
```
## 通过代理访问Tomcat
在正式环境中，直接把web服务器暴露出去是比较危险的，客户端可以不受限制的对服务端发送任何请求，比如dos攻击，webshell攻击，SQL注入等，这些攻击请求不仅会极大增加web运行的负担，并且一旦攻击成功，甚至会使服务器崩溃，影响正常用户使用。为了尽可能减少这样的安全风险，我们可以在web服务器的前面增加一层代理服务器，代理服务器仅转发客户端请求，能够承载几万甚至几十万的并发访问，对于一些可能的或者明显攻击的请求可以先在代理服务器中选择过滤、限速、限制ip等，缓解web真实服务器的处理压力，同时也可以对一些正常的web管理页面进行限制访问，参考[负载平衡反向代理配置部分](../cluster/reverse-proxy.md)，以提升环境的安全性和可用性。
## 使用https协议
https所具有的三个特性分别为，保密性、完整性、可靠性，这些特性能够保证客户端与服务端建立链接时对方是可信的，展示和传输的数据是真实可靠的，传输过程中数据是不易被破解和修改的。如果条件允许，我们总是推荐环境中使用https协议，并且能够在 [ssl安全评估站点](https://myssl.com/) 内达到A+级别，需要注意一下几个参数。
| 参数| 值 | 说明 |\
| ------ | :----------------- | :-------------------------- |\
| ssl\_protocols | TLSv1.2,TLSv1.3 | 不使用不安全的TLSv1.1,SSLv3等协议 |\
| ssl\_ciphers | EECDH+AESGCM:EDH+AESGCM | 使用强度高的加密算法，更多算法可以参考ssl安全评估站点 |\
| 增加响应头 | Strict-Transport-Security | 浏览器与该站点建立过https链接后应该总是使用https |
| 使用服务端优先的加密算法 | ssl\_prefer\_server\_ciphers on | |
---
url: "https://docs.succapp.com/v5/guide/devops/install/localization.md"
htmlUrl: "https://docs.succapp.com/v5/devops/localization"
title: "国产化"
---
---
order: 32
---
# 国产化
为了响应国家号召，顺应国产化浪潮，SuccBI对各种国产化环境进行了适配，并支持[芯片](#chip-architecture)、[操作系统](#operating-system)、[中间件](#middleware)以及[数据库](#database)等主流国产软硬件产品，帮助企业实现可控、安全的数字化转型。
## 国产化软硬件介绍{#typical-diagram}
SuccBI支持的国产化软硬件产品包括以下几方面：
- 芯片：兆芯、鲲鹏、飞腾、海光
- 操作系统：银河麒麟、统信、华为欧拉
- 中间件：东方通、金蝶天燕、宝兰德
### 支持的芯片架构{#chip-architecture}
|支持的芯片类型|芯片架构|
|:-:|:-:|
|华为鲲鹏云|ARM|
|海光芯片|x86|
|兆芯|x86|
|飞腾|ARM|
|龙芯3A5000|LoongArch|
### 支持的操作系统{#operating-system}
|支持的操作系统|支持的版本|
|:-:|:-:|
|银河麒麟|V10.0|
|统信UOS|V20|
|华为欧拉|-|
|中科红旗|V8|
### 支持的中间件容器{#middleware}
|支持的中间件|支持的版本|配置方法|
|:-:|:-:|:-:|
|东方通|V7|[东方通安装部署](./middleware/TongWeb.md)|
|宝蓝德|V9.5|[宝蓝德安装部署](./middleware/BES.md)|
## 国产化数据库{#database}
SuccBI也对众多国产化数据库进行了兼容性适配，下面是国产数据库支持情况：
|数据库|分析型用途|事务型用途|支持的版本|
|:---:|:--------:|:--------:|:-------:|
|华为OpenGauss|支持|支持|V2.0|
|人大金仓-Oracle内核|支持|支持|支持|版本8+|
|人大金仓-PostgreSQL内核|支持|支持|支持|版本8+|
|南大通用|支持|-|支持|GBase8s|
|达梦|支持|支持|V8.0|
|OceanBase for MySQL|支持|支持|支持|版本4.0|
|YMatrix|支持|支持|支持|版本4+|
::: tip 提示
SuccBI所有兼容的数据库可参见：[兼容的数据库](./database/README.md)
:::
---
url: "https://docs.succapp.com/v5/guide/devops/sso/README.md"
htmlUrl: "https://docs.succapp.com/v5/sso"
title: "单点登录概述"
---
---
order: 3
navTitle: 单点登录
indexTitle: 概述
---
# 单点登录概述
SuccBI提供了多种单点登录机制，包括[OAuth2协议](https://oauth.net/2/)、数字证书令牌等，还可以通过[扩展开发](../../dev/extension/extension-points/sso.md)提供更个性化的单点登录机制，提供了图形化配置界面可以快速的配置与任意第三方系统的单点登录。
\[\[toc]]
## 连接第三方认证服务{#connect-idp}
当多个系统需要单点登录时，需要有一个统一的**认证服务器**，认证服务器对外提供用户认证、登录授权页面、用户机构管理等功能，其它应用系统使用认证服务器提供的功能进行认证登录。
SuccBI可以连接多种第三方认证服务：
- [连接OAuth2服务器](./oauth2.md)
- [连接CAS服务器](./cas.md)
- [连接LDAP认证服务器](https://docs.succapp.com/v5/sso/ldap)
- [连接第三方数据库中的用户表](https://docs.succapp.com/v5/sso/connect-db-usertable)
- [连接其它登录认证服务](https://docs.succapp.com/v5/sso/other-idp)
## 使用钉钉微信登录{#internet-idp}
- [钉钉登录](./dingtalk.md)
- [微信登录](./wechat.md)
## 数字证书登录令牌{#ca-token}
第三方应用系统可以通过数字证书加密生成一个令牌，然后通过令牌登录和访问SuccBI系统，见[数字证书登录令牌](./ca-token.md)。
## SuccBI对外提供OAuth2服务{#succbi-oauth2-service}
SuccBI也可以作为认证服务器对外提供单点登录服务：
- [SuccBI对外提供OAuth2服务](./succbi-oauth2-service.md)
- [SuccBI之间单点登录](https://docs.succapp.com/v5/sso/with-succbi)
- [IP授信应用开发](../../dev/integrate/dev-ip-token.md)
## 相关文档{#references}
- [将SuccBI页面嵌入到第三方系统](../../dev/integrate/embed-into-3rd.md)
- [将第三方系统链接嵌入到本系统中](../../dev/integrate/link-3rd-page.md)
---
url: "https://docs.succapp.com/v5/guide/devops/sso/oauth2.md"
htmlUrl: "https://docs.succapp.com/v5/sso/oauth2"
title: "连接OAuth2服务"
---
---
order: 3
---
# 连接OAuth2服务
\[\[toc]]
## OAuth2服务简介{#indroduction}
OAuth（开放授权）是一个开放标准，允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。[OAuth2协议](https://oauth.net/2/)是OAuth协议的延续版，在各互联网平台上有的广泛的应用。
SuccBI连接OAuth2服务，可以让用户第一次访问SuccBI内部资源时显示OAuth2服务器的登录页面（或者是授权页面），如果用户之前已经在当前浏览器窗口登录过，那么也可以直接静默授权，不显示登录/授权页面，直接自动登录SuccBI显示用户想看到的内容。
## 使用第三方OAuth2服务登录流程{#oauth-login-flow}
SuccBI内置有调用第三方OAuth2服务API来获取授权，这个需要第三方OAuth2服务满足下列流程：
第三方OAuth2服务需要满足如下条件：
1. 提供三个api接口用于SuccBI来获取授权认证信息：
- 获取用户授权接口(对应流程图第2步)：用于SuccBI在没有登录的时候跳转过来获取用户授权。
- 根据给用户授权生成的授权码获取接口调用凭证（access\_token）（对应流程图第11步）：用于认证SuccBI身份。如果是需要`POST`请求，请确保可以解析以`JSON`格式传递的数据。
- 根据接口调用凭证（access\_token）获取用户信息（对应流程图第14步）。如果是需要`POST`请求，请确保可以解析以`JSON`格式传递的数据。
2. 用户完成授权后重定向回SuccBI系统（对应流程图第9步）的url中带的用户授权凭证参数需要命名为**code**才会被SuccBI识别。
::: tip
如果第三方OAuth2服务不能满足如上条件，可以尝试使用[单点登录扩展服务](../../dev/extension/extension-points/sso.md)进行自定义。
:::
## 配置第三方OAuth2服务{#oauth2-service-settings}
在**系统设置** > **安全** > **单点登录** 中提供配置多个OAuth2服务的配置。[基本设置参考](../../sys-settings/security/sso.md)。
说明：
1. **appid**: 第三方OAuth2服务给SuccBI分配的id。`非必要选项`，可选择直接填写到对应URL参数中。用于认证身份。
2. **appsecret**：第三方OAuth2服务给SuccBI分配的秘钥。`非必要选项`，可选择直接填写到对应URL参数中。用于进一步认证身份。
3. **授权登录页面URL**：当SuccBI没有登录时候，跳转到的第三方OAuth2服务地址。`必要选项`。填入的URL中可使用的参数有：
- ${state}：状态值。用于防止[CSRF攻击](https://zh.wikipedia.org/wiki/%E8%B7%A8%E7%AB%99%E8%AF%B7%E6%B1%82%E4%BC%AA%E9%80%A0)，最终将被替换为一个随机字符串。期望第三方OAuth2服务在完成认证后原样传递给SucccBI，如果第三方OAuth2服务没有实现该机制，可选值不传这个参数。
- ${appid}：将被替换为系统设置中`appid`作为身份认证信息
- ${redirect\_uri}：将被替换为登录成功后期望访问的SuccBI的URL地址，供第三方OAuth2服务在完成认证后重定向回SuccBI。
示例： `http://example.com/authorize?appid=${appid}&redirect_uri=${redirect_uri}&state=${state}`\
最终将在使用的时候后将会被替换为： `http://example.com/authorize?appid=succbiid&redirect_uri=http%3A%2F%2Fsuccbi.com&state=12345`
4. **读取access\_token的URL**：用于SuccBI向第三方OAuth2服务根据用户授权凭证换取接口调用凭证(access\_token)。`必要选项`。默认是使用`GET`请求来进行调用，如果需要使用`POST`请求来调用，可以使用`POST + 一个空格` 作为前缀来指定，其他参数根据URL的的参数规范放置到URL中。URL中可使用的参数变量有：
- ${code}：第三方OAuth2服务在确认用户授权后重定向SuccBI所携带的授权信息。
- ${appid}：将被替换为系统设置中`appid`作为身份认证信息。
- ${app\_secret}：将被替换为系统设置中`appsecret`作为身份认证信息。
- ${redirect\_uri}：将被替换为第三方系统确认用户授权后重定向到SuccBI的URL地址。
示例：`POST http://example.com/access_token?appid=${appid}&appsecret=${app_secret}&redirect_uri=${redirect_uri}&code=${code}`\
最终发送出去的请求为信息的http请求关键信息如下：
```json
{
Request URL: "http://example.com/access_token",
Request Method: "POST",
Content-Type: "application/json;charset=utf-8"
Request Body: "{
"appid": "succbi",
"appsecret": "succbisecret",
"code": "code",
"redirect_uri": "http://succbi.com/demo"
}"
}
```
5. **解析access\_token**：用于告知SuccBI使用什么方式解析请求**读取access\_token的URL**的返回值。`必要选项`。为一个[表达式](../../exp/README.md)。\
示例：`JSON_GET($response, "access_token")`
- `$response`代表http请求的返回值的字符串结果。
- 整体表达式代表的意思是，将响应值作为一个JSON字符串解析，并且取JSON中键为`access_token`的值作为`access_token`。
6. **注销URL**：用于在用户注销在SuccBI注销登录的时候通知第三方OAuth2服务。`非必要选项`。URL上可用的参数有：
- ${appid}：将被替换为系统设置中`appid`作为身份认证信息。
- ${app\_secret}：将被替换为系统设置中`appsecret`作为身份认证信息。
- ${redirect\_uri}：注销SuccBI后期望重定向到的SuccBI的系统界面URL。
- ${state}: 状态值。
示例： `http://example.com/authorize?appid=${appid}&redirect_uri=${redirect_uri}&state=${state}`\
最终将在使用的时候后将会被替换为： `http://example.com/authorize?appid=succbiid&redirect_uri=http%3A%2F%2Fsuccbi.com&state=12345`
7. **获取用户信息URL**：用于使用接口调用凭证(access\_token)向第三方OAuth2服务换取用户信息。`必要选项`。默认是使用`GET`请求来进行调用，如果需要使用`POST`请求来调用，可以使用`POST + 一个空格` 作为前缀来指定，其他参数根据URL的的参数规范放置到URL中：
- ${access\_token}：接口调用凭证。
- ${appid}：将被替换为系统设置中`appid`作为身份认证信息。
示例：`POST http://example.com/access_token?access_token=${access_token}`\
最终发送出去的请求为信息的http请求关键信息如下：
```json
{
Request URL: "http://example.com/getUser",
Request Method: "POST",
Content-Type: "application/json;charset=utf-8"
Request Body: "{
"access_token": "wz4e5x6rc7tv8yb9uni=-908778-980ytfufuyghoti7rdtyg",
}"
}
```
8. **解析用户信息**：用于控制如何从请求`获取用户信息URL`的响应中中获取用户信息。`非必要选项`。
- 不填的情况下，如果返回值是JSON格式，则会取这个JSON中键名为`user`的对象作为完整的用户属性。\
示例：
```json
{
user: {
userId: "zhangsan",
userName: "张三",
enabled: true
},
errorcode: 0
}
```
将直接取 `user`的整个属性，作为用户数据。
- 填写的情况下，需要针对需要写入到系统用户表字段，分别使用表达式进行解析，填写方式如下：
- 左边为属性名，根据用户表字段来命名，不过得将下划线命名方式的用户表字段，修改为驼峰式命名，比如用户表字段为`USER_ID`，则需要填入`userId`。
- 右边为取值表达式：
- 表达式以`$response`作为http请求的返回值的字符串常量，比如`JSON_GET($response, 'userId')`，表明取JSON的第一级参数userId对应的值。
- 也可以使用常量，如果是个字符串，需要用引号括起来，比如填入"external"，表明固定写入字符串`external`。
示例：
## 相关阅读{#related-texts}
- [SuccBI提供的OAuth2服务](../../dev/references/web-api/oauth2/README.md)
- [单点登录扩展服务](../../dev/extension/extension-points/sso.md)
- [OAuth标准(英文)](https://oauth.net/2/)
- [OAuth维基百科(中文)](https://zh.wikipedia.org/zh/%E5%BC%80%E6%94%BE%E6%8E%88%E6%9D%83)
---
url: "https://docs.succapp.com/v5/guide/devops/sso/cas.md"
htmlUrl: "https://docs.succapp.com/v5/sso/cas"
title: "连接CAS服务"
---
---
order: 6
---
# 连接CAS服务
[CAS协议](https://www.apereo.org/projects/cas)与[OAuth2协议](https://oauth.net/2/)相似，可以实现一样的单点登录体验。
---
url: "https://docs.succapp.com/v5/guide/devops/sso/wechat.md"
htmlUrl: "https://docs.succapp.com/v5/sso/wechat"
title: "微信登录"
---
---
order: 7
---
# 微信登录
为了方便用户在微信上访问SuccBI的页面时，直接使用微信账号的身份来进行访问，跳过繁杂的登录步骤，SuccBI提供了绑定[微信公众号服务号](https://kf.qq.com/faq/120911VrYVrA150918fMZ77R.html?scene_id=kf3386)的方式来提供单点登录服务。需要注意的是：微信公众号需要为`服务号`，[关于微信公众号服务号和订阅号的说明](https://kf.qq.com/faq/170815aUZjeQ170815mU7bI7.html)。
\[\[toc]]
:::warning 重要说明
一个公众号请务必保证仅在一个系统中使用。
原因：[获取access\_token调用频率有上限](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/API_Call_Limits.html)，并且重复调用access\_token获取接口将上次获取的access\_token失效，可能会因为多个环境中频繁使用微信相关功能，导致access\_token获取受限制，微信功能当天也就不能使用了。
:::
## 微信公众号的配置{#oa-settings}
1. 完成微信认证： **设置**>**微信认证**，否则公众号没有权限去获取微信的用户信息。
2. 修改微信公众号网页授权信获取用户基本行为当前部署系统的域名地址：**设置**>**公众号设置**>**功能设置**>**网页授权域名**。
\
考虑到微信中其他功能的使用，建议也将js接口安全域名也配置上：**设置**>**公众号设置**>**功能设置**>**js接口安全域名**。
3. 获取公众号开发者信息，并将部署系统的服务器对外IP地址配置到IP白名单中：**设置**>**开发**>**基本配置**\
`AppID` 和 `AppSecret`要被配置到[系统设置](#sys-settings)
## 系统设置{#oa-syssettings}
需要在**系统设置**>**安全**>**单点登录**中添加一个微信单点登录方式，基础单点登录设置请参考：[单点登录方案设置](../../sys-settings/security/sso.md#common-settings)，公众号特征设置说明：
1. `应用类型`： 选择`公众号服务号`。
2. `appId`：见[微信公众号配置](#oa-settings)获取公众号开发者中的`AppId`。
3. `appSecret`：见[微信公众号配置](#oa-settings)获取公众号开发者中的`AppSecret`。
4. `启用扫码登录`： 若是要在登录界面展示使用微信扫码登录电脑端的二维码，请勾选上。
### 用户匹配规则设置{#oa-syssettings-match}
1. 请在`用户匹配字段1`中填写`微信公众号用户唯一ID`(对应物理字段为`WECHAT_OPENID`)。
2. 这个微信公众号绑定了[微信开放平台](https://open.weixin.qq.com/)账号，并且希望通过这个开放平台绑定的小程序、公众号等方式登录本系统时共享同一个账号信息，请在对应的系统或者外部用户表模型中添加一个字段`微信开放平台唯一ID`（物理字段请命名为`WECHAT_UNIONID`），并将这个字段设置为`匹配用户依据1`。如果是之前使用了`微信公众号用户唯一ID`字段作为`匹配用户依据1`，现在选择绑定微信开放平台的时候，请将`微信公众号用户唯一ID`作为`匹配用户依据2`。
::: tip
若是有需求让一个系统用户绑定到多个微信公众号的账号中，并且期望通过不同的微信公众号进入项目的时候使用同一账号：
- 建议注册一个[微信开放平台](https://open.weixin.qq.com/)用于将多个微信公众号绑定到一起，具体详见[微信Unionid机制](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/union-id.html)，并且在对应的系统或者外部用户表模型中添加一个字段`微信开放平台唯一ID`（物理字段请命名为`WECHAT_UNIONID`），并将这个字段设置为`匹配用户依据1`。
- 若是不选择注册微信开放平台账号，建议在系统用户表或者外部用户表中这对模型分别为各种单点登录方式都添加一个字段，物理字段分别命名为`ssoid + "_OPENID"`（比如ssoid是"wx1"，物理字段命名为`WX1_OPENID`）作为`匹配用户依据1`，建议也添加上`ssoid + "_NICKNAME"`（同前）用于存储从第三方系统获取到的用户昵称，便于区分从使用的是哪个微信账号。
:::
## 扫码登录PC{#oa-qrcode}
当完成[系统设置](#oa-syssettings)，并且设置了启用扫码登录当有单点登录方式支持使用扫码登录的时候，默认的登录界面将会展示二维码供用户使用app来进行扫码。具体说明请参考：[扫码登录](../../dev/integrate/qrcode.md#)。
扫码效果展示如下：
- 使用微信扫码二维码会展示如下界面:
本次迁移权限数据SQL如下
```sql
1. 后面还需要删除不需要的部门、用户、权限信息，保险起见备份当前权限信息表
# 备份部门表
CREATE TABLE SZSYS_5_DEPTS_A AS SELECT * FROM SZSYS_5_DEPTS
# 备份用户表
CREATE TABLE SZSYS_5_USERS_A AS SELECT * FROM SZSYS_5_DEPTS
# 备份用户组表
CREATE TABLE SZSYS_5_USER_GROUPS_A AS SELECT * FROM SZSYS_5_USER_GROUPS
# 备份用户组成员表
CREATE TABLE SZSYS_5_USER_GROUP_MEMBERS_A AS SELECT * FROM SZSYS_5_USER_GROUP_MEMBERS
# 备份权限表
CREATE TABLE SZSYS_5_PERMISSIONS_A AS SELECT * FROM SZSYS_5_PERMISSIONS
2. 按照中的需求将原B系统中的权限数据插入到当前环境系统表中
#从SZSYS_4_DEPTS_B插入部门数据到部门表中
INSERT INTO SZSYS_5_DEPTS(SZ_PID0 ,
SZ_PID1 ,
SZ_PID2 ,
SZ_PID3 ,
SZ_PID4 ,
SZ_PID5 ,
PARENT_ID ,
DEPT_ID ,
DEPT_NAME ,
ORG_ID ,
ORDER_ID ,
CREATE_FROM ,
SZ_LEVEL ,
SZ_ISLEAF) SELECT SZ_PID0 ,
SZ_PID1 ,
SZ_PID2 ,
SZ_PID3 ,
SZ_PID4 ,
SZ_PID5 ,
PARENT_ID ,
DEPT_ID ,
DEPT_NAME ,
ORG_ID ,
ORDER_ID ,
CREATE_FROM ,
SZ_LEVEL ,
SZ_ISLEAF
FROM SZSYS_5_DEPTS_B
#从SZSYS_4_USERS_B导入用户数据到用户表中，NOT EXISTS语句防止主键(USER_ID)数据重复
#重复数据以A优先
INSERT INTO SZSYS_5_USERS(USER_ID ,
USER_NAME ,
ORG_ID ,
DEPT_ID ,
ORDER_ID ,
PASSWORD ,
SALT ,
PHONE ,
EMAIL ,
CREATOR ,
QQ ,
WECHAT ,
QQ_OPENID ,
WECHAT_OPENID ,
SIGNUP_FROM ,
DELEGATE_TO ,
ENTERPRISE_USER_ID ,
USER_LABELS ,
ENABLED ,
CREATE_TIME ,
DELEGATE_START_TIME ,
DELEGATE_END_TIME) SELECT USER_ID ,
USER_NAME ,
ORG_ID ,
DEPT_ID ,
ORDER_ID ,
PASSWORD ,
SALT ,
PHONE ,
EMAIL ,
CREATOR ,
QQ ,
WECHAT ,
QQ_OPENID ,
WECHAT_OPENID ,
SIGNUP_FROM ,
DELEGATE_TO ,
ENTERPRISE_USER_ID ,
USER_LABELS ,
ENABLED ,
CREATE_TIME ,
DELEGATE_START_TIME ,
DELEGATE_END_TIME
FROM SZSYS_5_USERS_B t2
WHERE NOT EXISTS
(SELECT 1
FROM SZSYS_5_USERS t1
WHERE t1.USER_ID=t2.USER_ID)
#从SZSYS_4_USER_GROUPS_B导入用户组数据到用户组表中
#NOT EXISTS语句防止主键(GROUP_ID)数据重复，重复数据以A优先
INSERT INTO SZSYS_5_USER_GROUPS(GROUP_ID ,
GROUP_NAME ,
MATCH_EXP ,
DESC ,
CREATE_TIME ,
MODIFY_TIME ,
CREATOR ,
MODIFIER ,
ENABLED ,
REFRESH_STATE) SELECT GROUP_ID ,
GROUP_NAME ,
MATCH_EXP ,
DESC ,
CREATE_TIME ,
MODIFY_TIME ,
CREATOR ,
MODIFIER ,
ENABLED ,
REFRESH_STATE
FROM SZSYS_5_USER_GROUPS_B t2
WHERE NOT EXISTS
(SELECT 1
FROM SZSYS_5_USER_GROUPS t1
WHERE t1.GROUP_ID=t2.GROUP_ID)
#从SZSYS_4_USER_GROUP_MEMBERS_B导入用户组成员数据到用户组成员表中
#NOT EXISTS语句防止主键(USER_ID、GROUP_ID、AUTO_MATCH)数据重复，重复数据以A优先
#EXISTS语句保证导入的用户、用户组是在A系统存在的
INSERT INTO SDI.SZSYS_4_USER_GROUP_MEMBERS(USER_ID ,
GROUP_ID ,
AUTO_MATCH ,
GRANTOR ,
GRANT_TIME) SELECT USER_ID ,
GROUP_ID ,
AUTO_MATCH ,
GRANTOR ,
GRANT_TIME
FROM SZSYS_5_USER_GROUP_MEMBERS_B t2
WHERE NOT EXISTS
(SELECT 1
FROM SZSYS_5_USER_GROUP_MEMBERS t1
WHERE t1.USER_ID=t2.USER_ID
AND t1.GROUP_ID=t2.GROUP_ID
AND t1.AUTO_MATCH=t2.AUTO_MATCH)
AND EXISTS
(SELECT 1
FROM SZSYS_5_USER_GROUPS t3
WHERE t2.GROUP_ID=t3.GROUP_ID)
AND EXISTS
(SELECT 1
FROM SZSYS_5_USERS t4
WHERE t2.USER_ID=t4.USER_ID)
#从**SZSYS_4_PERMISSIONS_B**导入权限数据到权限表中
#EXISTS语句保证导入的用户、用户组是在当前系统存在的
#权限表的主键PERMISSION_ID是唯一的MD5码，因此不需要考虑重复数据的情况
INSERT INTO SDI.SZSYS_4_PERMISSIONS(PERMISSION_ID ,
OWNER_ID ,
OWNER_TYPE ,
RES_PATH ,
ALLOWS ,
FORBIDS ,
DATA_RANGE ,
GRANTOR ,
GRANT_TIME) SELECT PERMISSION_ID ,
OWNER_ID ,
OWNER_TYPE ,
RES_PATH ,
ALLOWS ,
FORBIDS ,
DATA_RANGE ,
GRANTOR ,
GRANT_TIME
FROM SZSYS_5_PERMISSIONS_B t2
WHERE EXISTS
(SELECT 1
FROM SZSYS_5_USERS t1
WHERE t1.USER_ID=t2.OWNER_ID
AND t2.OWNER_TYPE='u')
OR EXISTS
(SELECT 1
FROM SZSYS_5_USER_GROUPS t3
WHERE t3.GROUP_ID=t2.OWNER_ID
AND t2.OWNER_TYPE='g')
3. 按照需求，后面还需要删除不需要的部门、用户、权限信息，保险起见备份当前权限信息表
# 备份部门表
CREATE TABLE SZSYS_5_DEPTS_NEW AS SELECT * FROM SZSYS_5_DEPTS
# 备份用户表
CREATE TABLE SZSYS_5_USERS_NEW AS SELECT * FROM SZSYS_5_DEPTS
# 备份用户组表
CREATE TABLE SZSYS_5_USER_GROUPS_NEW AS SELECT * FROM SZSYS_5_USER_GROUPS
# 备份用户组成员表
CREATE TABLE SZSYS_5_USER_GROUP_MEMBERS_NEW AS SELECT * FROM SZSYS_5_USER_GROUP_MEMBERS
# 备份权限表
CREATE TABLE SZSYS_5_PERMISSIONS_NEW AS SELECT * FROM SZSYS_5_PERMISSIONS
4. 按照需求，删除不需要的"江苏市场监督管理局"(DEPT_ID为'100')及其所有下级部门的权限数据
# 筛选出需要删除的部门数据，条件为最高层级部门ID为'100'，并创建为TEMP_DEPT表
CREATE TABLE TEMP_DEPT AS SELECT * FROM SZSYS_5_DEPTS WHERE SZ_PID0='100'
# 筛选出需要删除的用户数据，并创建为TEMP_USER表
CREATE TABLE TEMP_USER AS SELECT *
FROM SZSYS_5_USERS_NEW t1
WHERE EXISTS
(SELECT 1
FROM TEMP_DEPT t2
WHERE t1.DEPT_ID=t2.DEPT_ID)
#删除TEMP_USER中用户的权限数据
#权限表中OWNER_TYPE字段记录权限拥有者类型，'u'为用户
DELETE
FROM SZSYS_5_PERMISSIONS t1
WHERE EXISTS
(SELECT 1
FROM TEMP_USER t2
WHERE t2.USER_ID=t1.OWNER_ID
AND t1.OWNER_TYPE='u')
#在用户组成员表中删除TEMP_USER中存在的用户组成员数据
DELETE
FROM SZSYS_5_USER_GROUP_MEMBERS t1
WHERE EXISTS
(SELECT 1
FROM TEMP_USER t2
WHERE t2.USER_ID=t1.USER_ID)
#在用户表中删除TEMP_USER中存在的用户数据
DELETE
FROM SZSYS_5_USERS t1
WHERE EXISTS
(SELECT 1
FROM TEMP_USER t2
WHERE t2.USER_ID=t1.USER_ID)
# 在部门表删除TEMP_DEPT中存在的部门数据
DELETE
FROM SZSYS_5_DEPTS t1
WHERE EXISTS
(SELECT 1
FROM TEMP_DEPT t2
WHERE t2.DEPT_ID=t1.DEPT_ID)
5. 合并dev(DEPT_ID为'01')和赛思(DEPT_ID为'Succez')两个部门的用户信息
#在用户表中将DEPT_ID为'01'的DEPT_ID列修改为'Succez'
UPDATE SZSYS_5_USERS SET DEPT_ID='Succez'
WHERE DEPT_ID='01'
#在部门表中删除dev部门
DELETE FROM SZSYS_5_DEPTS
WHERE DEPT_ID='01'
```
### 迁移文件数据源{#file-data}
经过以上步骤，B项目已经合并迁移到了A项目所在的系统中来，但由于文件数据源不包含在元数据内且目前文件数据源不支持导出，所以需要在服务器中手动将文件数据源迁移，步骤如下：
1. 进入原B项目所在服务器的`workdir/clusters-share/data-files/B`目录，拷贝该目录下的所有文件到A项目所在服务器的相同目录下，工作目录在`/Tomcat/bin/setenv.sh`下配置，详见[此处](../install/basic-install/workdir-and-defdb.md#set-workdir)
2. 重启Tomcat
## 迁移完工验证{#verify}
经过以上步骤，迁移合并系统已完成，需要对迁移后的系统进行相关测试，确定该系统下的项目都能稳定运行，大致范围如下:
1. 数据源：连接其他数据库
2. 数据：上传数据文件，数据加工，SQL查询等
3. 分析：设计、分享、评论仪表板
4. 表单：设计表单、流程并发布报表填报应用
5. 应用：设计门户
6. 资源：管理系统资源，如新建、删除、移动、复制资源等
7. 系统设置：设置系统登录页
---
url: "https://docs.succapp.com/v5/guide/devops/upgrade/war.md"
htmlUrl: "https://docs.succapp.com/v5/devops/upgrade/war"
title: "升级WAR包"
---
---
order: 2
---
# 升级WAR包
本文主要介绍如何升级项目中的war包，分为Linux系统升级war包和windows系统升级war包。
升级war包的主要步骤为：
\[\[toc]]
:::warning 升级前必读
由于升级过程中系统可能会对表结构或数据进行升级，为了升级过程更稳定，建议先在测试环境进行升级测试，并对生产环境系统以及数据库的默认数据源进行[完整备份](../../sys-settings/project/README.md#backup)。
替换WAR包并[重启tomcat](#linux-start-tomcat)后，系统会先显示升级确认页面（当新的WAR包版本号的前2位与老版本有变化时才会提示确认页面，第三个版本号变化属于BUG修复并不会提示确认），用户需确认升级版本号是否正确，并输入管理员账号密码后才能开始升级。
:::
## Linux系统升级war包{#linux-war}
正常升级war包的时候，应该使用tomcat启动的Linux用户登录，比如succez用户，一般不使用root登录，但是在实际的工作中，使用root用户的情况比较多，所以本文的Linux系统升级war包部分，以root用户为例子升级war包。
### 停止tomcat{#linux-stop-tomcat}
1. 查看tomcat进程
::: tip
一台Linux服务器可能会存在多个tomcat进程，需要在查询后记录以下两个内容：
1. tomcat进程路径
2. tomcat进程PID
通过进程路径确认对应的产品目录，确认是否操作此目录的产品项目，通过PID验证、结束进程。
::::
具体查看进程的步骤如下：
- 执行命令查看tomcat进程 `ps -ef | grep tomcat` ，
控制台会输出tomcat进程信息
- 根据此进程提供的信息可知，系统中运行了一个tomcat进程，tomcat的启动用户为`succez`用户，进程PID为`1674`
- 根据 `-Dcatalina.base=/succezsoft/tomcat` 可知此进程的tomcat路径为 `/succezsoft/tomcat`
```sh
[root@oracle19c ~]# ps -ef | grep tomcat
succez 1674 1 45 14:00 pts/0 00:00:46 /succezsoft/jdk/bin/java -Djava.util.logging.config.file=/succezsoft/tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.awt.headless=true -Dsucc.workdir=/succezsoft/workdir -Djava.net.preferIPv4Stack=true -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -DLANG=zh_CN.UTF-8 -server -Xmx1g -Xms1g -XX:+UseG1GC -XX:+AlwaysPreTouch -XX:+ScavengeBeforeFullGC -XX:+DisableExplicitGC -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Dorg.apache.catalina.security.SecurityListener.UMASK=0027 -Dignore.endorsed.dirs= -classpath /succezsoft/tomcat/bin/bootstrap.jar:/succezsoft/tomcat/bin/tomcat-juli.jar -Dcatalina.base=/succezsoft/tomcat -Dcatalina.home=/succezsoft/tomcat -Djava.io.tmpdir=/succezsoft/tomcat/temp org.apache.catalina.startup.Bootstrap start
root 1822 1613 0 14:02 pts/0 00:00:00 grep --color=auto tomcat
```
2. 进入tomcat安装目录的bin目录，执行停止程序
```sh
cd /succezsoft/tomcat/bin
./shutdown.sh
```
等待停止程序执行结束后，再次查看tomcat进程 `ps -ef | grep tomcat`，如果相同PID的进程依旧存在，可以使用kill命令结束进程 `kill -9 进程PID`。
::: warning 安全告知
不要一开始就直接使用kill命令，一定先尝试./shutdown.sh之后，无法结束进程，再使用kill命令。
直接kill进程可能导致数据丢失。
:::
3. 清理work目录
进入work目录，删除其中的文件
```sh
cd /succezsoft/tomcat/work
ls
rm -rf Catalina
```
::: warning 安全告知
删除之前一定要确认被删除文件的路径是否有错，如果删除了其他文件可能会导致系统运行错误。
此步骤删除的文件是`tomcat/work`目录下的`Catalina`文件夹及其中的文件。
:::
### 替换war包{#linux-update-war}
1. 备份旧war包，删除旧war包已解压的的目录
```sh
mkdir /succezsoft/tomcat/warbak
cd /succezsoft/tomcat/webapps
mv ROOT.war /succezsoft/tomcat/warbak
rm -rf ROOT
```
- 第一行命令是创建备份文件夹
- 第二行命令是进入webapps目录
- 第三行命令是将旧war包移动到备份文件夹内
- 第四行命令是删除旧war包的解压文件
具体的旧war包名需要去webapps目录查看，上面的步骤仅作为参考，有时候可能会有两个war包或者包名非ROOT.war，需要根据项目情况进行操作。
2. 上传新的升级war包，并移动到webapps目录
根据项目情况选择上传方式，可以使用XFTP等工具上传，假设上传的目录为`/root`，升级war包名为`ROOT.war`，将升级war包移动到`/succezsoft/tomcat/webapps`目录。
```sh
mv /root/ROOT.war /succezsoft/tomcat/webapps
```
如果升级war包名与旧war包名不一致，要将升级war包名修改成旧war包名，例如旧包名为`succezbi.war`的时候要先进行如下操作。
```sh
mv /succezsoft/tomcat/webapps/ROOT.war /succezsoft/tomcat/webapps/succezbi.war
```
更换了新war包之后，要将新war包的权限用户修改成tomcat启动用户。
```sh
chown succez:succez /succezsoft/tomcat/webapps/ROOT.war
```
### 启动tomcat{#linux-start-tomcat}
1. 执行启动程序启动tomcat
先执行命令 `su succez` 切换到上文说到的tomcat启动用户，再执行下面的命令启动tomcat。
```sh
cd /succezsoft/tomcat/bin
./startup.sh
```
2. 再次查看tomcat进程，主要看进程是否正常存活 `ps -ef | grep tomcat`。
3. 如果没有看到新的tomcat进程，就进入logs目录，查看日志信息
```sh
cd /succezsoft/tomcat/logs
tail -100f catalina.out
```
上面的命令是跟踪文件中最后100行的信息，100也可以替换成更大的数字来查看更多的日志行数，看日志中的报错信息，判断无法启动的原因，排查错误之后再次重复上面的步骤启动tomcat。
如果要退出日志查看可以按住键盘上的 `Ctrl + C`。
## Windows系统升级war包{#windows-war}
本文的Windows系统升级war包指的是在DEMO体验版中升级，如果是自己手动部署的环境要升级war包，步骤也是一样的，只是需要根据自己部署的目录做出调整。
本文演示的步骤中：
- DEMO体验版目录：`D:\SuccBI-standalone-4.1.0`
- DEMO体验版tomcat目录：`D:\SuccBI-standalone-4.1.0\server\tomcat`
### 停止tomcat{#windows-stop-tomcat}
进入DEMO体验版目录中，双击`shutdown.bat`执行关闭程序，看到`Tomcat shutdown complete`和`Press any key to continue . . .` 说明tomcat程序已经安全关闭。
这个时候就可以关闭弹出的tomcat和shutdown进程窗口了。
### 替换war包{#windows-update-war}
1. 进入DEMO体验版tomcat目录，创建bak文件夹
2. 进入tomcat目录下的webapps文件夹，删除旧war包解压后的文件夹，并将旧war包移动到bak文件夹内（右键`剪切`移动）
3. 将升级war包复制到tomcat目录下的webapps文件夹内
4. 进入tomcat目录下的work文件夹内，删除`Catalina`文件夹
### 启动tomcat{#windows-start-tomcat}
进入DEMO体验版目录中，双击 `startup.bat`，会弹出tomcat的程序运行窗口，等待一段时间，看到 `Server startup in XXXX ms`，说明tomcat启动成功。
如果程序框闪退或者报错无法继续执行，可以去DEMO体验版tomcat目录下的logs文件夹内，查看 `catalina.out`文件，分析日志中显示的问题，探查启动失败的原因，排查错误后再次启动。
## 验证{#check-web}
完成了如上升级war包的操作后（Linux/Windows），还需要对web进行一些简单测试。
1. 查看版本号，确认已升级。查看系统版本号详见[查看系统信息](../../sys-settings/basic/sysinfo.md)。
2. 简单功能测试。对平时常用的部分测试使用，如果功能完好，没有弹出报错窗口，那就代表本次的升级war包操作成功。
3. 包版本回退。如果升级了war包之后出现问题，项目无法使用，可以选择将war包回退到之前的版本。把之前备份的war包重新换回去，步骤与上述升级war包一致，在紧急情况下重新投入使用，等待新war包中出现的问题给出解决方案再升级。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/README.md"
htmlUrl: "https://docs.succapp.com/v5/devops/faq"
title: "常见问题"
---
---
order: 11
navTitle: 常见问题
---
# 常见问题
!!! children 3 !!!
---
url: "https://docs.succapp.com/v5/guide/devops/faq/为什么有些异常没有堆栈.md"
htmlUrl: "https://docs.succapp.com/v5/howto/5b81247d"
title: "为什么有些异常没有堆栈"
---
---
order: 1
---
# 为什么有些异常没有堆栈
使用过程中可能会出现如下图所示的异常信息中堆栈为空的情况，不利于排查问题。
## 原因{#why}
JVM针对频繁出现的异常做了优化，可以在出现异常的时候快速抛出，不需要打印出整个调用链，这样可以节省异常堆栈的内存分配。
## 解决方法{#solution}
禁用该优化，JVM增加`XX:-OmitStackTraceInFastThrow`参数(参考：[Tomcat设置启动环境变量](../install/middleware/tomcat.md#env))，显示完整异常。
Windows下，在`setenv.bat`或`catalina.bat`中添加以下代码
```batch
set JAVA_OPTS=%JAVA_OPTS% -XX:-OmitStackTraceInFastThrow
```
Linux下，在`setenv.sh`或`catalina.sh`中添加以下代码
```sh
export JAVA_OPTS="$JAVA_OPTS -XX:-OmitStackTraceInFastThrow"
```
---
url: "https://docs.succapp.com/v5/guide/devops/faq/服务器宕机故障排查.md"
htmlUrl: "https://docs.succapp.com/v5/howto/b752f2bb"
title: "服务器宕机故障排查"
---
---
order: 2
---
# 服务器宕机故障排查
\[\[toc]]
当服务器无法访问时通过执行一些系统命令获取一些运行状态信息能帮助技术人员快速定位问题，这些命令是：
## 查看操作系统资源耗费情况
见[如何查看操作系统资源使用情况](./如何查看操作系统资源使用情况.md)，看看系统的瓶颈是在IO／cpu还是内存上，如果是在cpu上，还需要看看是哪个进程，哪个线程：
```sh
top //显示耗费cpu的进程
top -p 进程号 -H //显示这个进程内最耗费cpu的线程，把列出的pid转换成小写16进制可在jvm堆栈中找到堆栈信息
```
## 获取JVM线程堆栈
获取jvm线程堆栈，可以帮助技术人员判断服务器正在执行哪些代码逻辑，“卡”在什么地方了，具体的操作方法见：[如何获取服务器JVM运行堆栈](./如何获取服务器JVM运行堆栈.md)
## 查看是否OutOfMemoryError(OOM)
当系统OOM时，由于JVM一直试图gc回收内存，但一直回收不到内存也可能表现为宕机，更多信息见[OOM（OutOfMemoryError）故障排查](./OOM（OutOfMemoryError）故障排查.md)
---
url: "https://docs.succapp.com/v5/guide/devops/faq/restore-demo-project.md"
htmlUrl: "https://docs.succapp.com/v5/devops/restore-demo-project"
title: "如何恢复DEMO项目到已部署好的环境中"
---
---
order: 3
---
# 如何恢复DEMO项目到已部署好的环境中
本文讲述如何在已部署好的环境中恢复DEMO项目，并提供项目素材和示例配置文件进行项目恢复。
恢复步骤如下所示：
\[\[toc]]
## 获取DEMO项目素材{#get-material}
DEMO项目素材可以通过以下两种方式获取：
1. 将[DEMO体验版](../install/basic-install/trial-install.md)中`/server/resources`目录的内容拷贝上传到服务器中使用。
2. 在[此处](https://www.jianguoyun.com/p/DYbI3toQ3O-gChiAtLQE)下载DEMO项目素材并上传到服务器解压使用。
::: tip 提示
请根据系统版本选择对应的项目素材，否则部分DEMO无法正常恢复！
:::
## 新增数据库配置文件{#configuration}
恢复DEMO项目之前需要配置默认的`succbidw`和`succbiyw`库作为数据仓库和业务应用数据库，具体配置方法如下：
在[工作目录](../install/basic-install/workdir-and-defdb.md#set-workdir)下的`conf`目录中添加`dw.conf` 、`yw.conf`文件作为数据库配置文件，可以在[这里](https://www.jianguoyun.com/p/DVRABfYQ3O-gChj8s7QE)下载常用的数据库示例文件，示例文件内容如下：
```sh
#mysql
{
"driver": "com.mysql.cj.jdbc.Driver",
"dbType": "MySQL",
"url": "jdbc:mysql://localhost:3306/succbi?useUnicode=true&characterEncoding=utf8&allowLoadLocalInfile=true&zeroDateTimeBehavior=convertToNull&useSSL=false",
"user": "succbi",
"password": "succbi666",
"szcp.logConnectionTrace": true
}
#Oracle
{
"driver": "oracle.jdbc.OracleDriver",
"dbType": "Oracle",
"url": "jdbc:oracle:thin:@localhost:1521:orcl",
"purpose": "writable",
"user": "succbi",
"password": "succbi666"
}
```
::: tip 提示
1. 示例文件中的`url`、`user`、`password`需要更换为用户本地的数据库地址以及账号密码。
2. 恢复DEMO使用的数据库需要有**读写**权限，否则DEMO项目恢复后没有数据！
3. 若示例文件中未包含当前使用数据库，可联系技术人员提供示例文件。
:::
## 设置JVM参数{#modify-jvm-profile}
DEMO项目的恢复通过JVM参数控制，在JVM参数中配置素材路径以及默认数据库文件路径后，启动系统时会读取JVM参数中的配置，对DEMO项目进行恢复。配置方法如下：
进入`tomcat/bin`目录，在`setenv.sh`中添加以下参数：
```sh
#初始化配置
export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=succ.demo"
#初始化素材目录
export JAVA_OPTS="$JAVA_OPTS -Dsucc.demo.resources=/path/to/resources/" (/path/to/resources/为示例路径，请修改为DEMO项目素材上传或解压路径)
#初始化数据库
export JAVA_OPTS="$JAVA_OPTS -Dsucc.jdbc.succbiyw=/path/to/workdir/conf/yw.conf -Dsucc.jdbc.succbidw=/path/to/workdir/conf/dw.conf" (/path/to/workdir/为示例路径，请修改为工作目录所在路径)
```
## 初始化更新{#init-update}
恢复DEMO项目需要[更换war包](../upgrade/war.md)才会生效，更换重启后，登录进入系统，若项目列表中新增`DEMO`和`OA`两个项目，说明项目恢复已经完成。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/如何查看操作系统资源使用情况.md"
htmlUrl: "https://docs.succapp.com/v5/howto/424cd9ff"
title: "如何查看操作系统资源使用情况"
---
---
order: 3
---
# 如何查看操作系统资源使用情况
在linux上可以执行`vmstat -S M 1 100`（其他系统如Aix：`vmstat 1 100`），输出信息形如：
**输出字段含义说明：**
1. 进程procs：
- r：在运行队列中等待的进程数，**这个数字如果大于5的情况比较多，说明系统线程切换耗费资源很大**
- b：在等待io的进程数
2. Linux 内存监控内存memoy：
- swpd：现时可用的交换内存（单位KB）。
- free：空闲的内存（单位KB）。
- buff: 缓冲去中的内存数（单位：KB）。
- cache：被用来做为高速缓存的内存数（单位：KB）。
3. Linux 内存监控swap交换页面，如果交换比较频繁说明系统内存不足：
- si: 从磁盘交换到内存的交换页数量，单位：KB/秒。
- so: 从内存交换到磁盘的交换页数量，单位：KB/秒。
4. Linux 内存监控 io块设备: **这2个数字最好是0，如果比较大说明内存不够**
- bi: 发送到块设备的块数，单位：块/秒。
- bo: 从块设备接收到的块数，单位：块/秒。
5. Linux 内存监控system系统:
- in: 每秒的中断数，包括时钟中断。
- cs: 每秒的环境（上下文）转换次数。
6. Linux 内存监控cpu中央处理器：
- us：用户进程使用的时间。以百分比表示，**us比较高，说明cpu资源比较吃紧**
- sy：系统进程使用的时间。 以百分比表示
- id：中央处理器的空闲时间。以百分比表示
- wa: cpu等待io操作的时间。以百分比表示，wa比较高说明io是瓶颈
::: tip
假如 r经常大于 4 ，且id经常小于40，表示中央处理器的负荷很重。 假如bi，bo 长期不等于0，表示物理内存容量太小。
:::
---
url: "https://docs.succapp.com/v5/guide/devops/faq/如何获取服务器JVM运行堆栈.md"
htmlUrl: "https://docs.succapp.com/v5/howto/adc62596"
title: "如何获取服务器JVM运行堆栈"
---
---
order: 4
---
# 如何获取服务器JVM运行堆栈
当系统出现下列情况之一时，可能需要系统管理员能获取到服务器的java虚拟机的运行堆栈，来帮助研发人员排查问题：
1. 访问系统某些功能时反应很慢，但其他功能正常。
2. 访问系统所有页面都很慢，但网络是正常的。
3. 怀疑系统内部有死锁。
4. 为了更准确的定位问题，可以多获取几次堆栈信息，每次获取间隔1～3秒时间。
## 方法1.通过系统功能“线程堆栈”{#threadstack-system}
访问`系统设置`下的`线程堆栈`，效果如下图所示（当系统出现故障、卡顿、网络不畅时可能无法进入系统设置，此时需要使用下面的其他方法）：
## 方法2.windows上ctrl+break {#threadstack-windows}
在windows的cmd控制台上启动tomcat、jetty时，可以通过按下简单ctrl+break来获取JVM堆栈，堆栈会直接输出到标准输出上
## 方法3.linux、unix上kill -3命令 {#threadstack-kill3}
使用`kill -3 + java进程号`，可以通知java进程输出其线程堆栈，sun的jdk会直接将堆栈输出到标准输出上，ibm的jdk（websphere）会生成javacore文件。
**linux/unix+websphere获取java线程堆栈信息的具体操作步骤如下：**
1. 通过命令`ps -ef | grep java`来获取相应的java进程号，例如下面的命令可以显示websphere的server1进程的进程号是`8913104`
```sh
was@ZHSIMAVAR1:/home/was#ps -ef | grep java | grep server1
was 8913104 1 2 May 26 - 9:46 /home/was/IBM/WebSphere/AppServer/java/bin/java -Declipse.security -Dwas.status.socket=32891 -Dosgi.install.area=/home/was/IBM/WebSphere/AppServer -Dosgi.configuration.area=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/servers/server1/configuration -Djava.awt.headless=true -Dosgi.framework.extensions=com.ibm.cds,com.ibm.ws.eclipse.adaptors -Xshareclasses:name=webspherev80_%g,groupAccess,nonFatal -Xbootclasspath/p:/home/was/IBM/WebSphere/AppServer/java/jre/lib/ibmorb.jar -classpath /home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/properties:/home/was/IBM/WebSphere/AppServer/properties:/home/was/IBM/WebSphere/AppServer/lib/startup.jar:/home/was/IBM/WebSphere/AppServer/lib/bootstrap.jar:/home/was/IBM/WebSphere/AppServer/lib/jsf-nls.jar:/home/was/IBM/WebSphere/AppServer/lib/lmproxy.jar:/home/was/IBM/WebSphere/AppServer/lib/urlprotocols.jar:/home/was/IBM/WebSphere/AppServer/deploytool/itp/batchboot.jar:/home/was/IBM/WebSphere/AppServer/deploytool/itp/batch2.jar:/home/was/IBM/WebSphere/AppServer/java/lib/tools.jar -Dibm.websphere.internalClassAccessMode=allow -Xms1024m -Xmx4096m -Xcompressedrefs -Xscmaxaot4M -Xscmx60M -Dws.ext.dirs=/home/was/IBM/WebSphere/AppServer/java/lib:/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/classes:/home/was/IBM/WebSphere/AppServer/classes:/home/was/IBM/WebSphere/AppServer/lib:/home/was/IBM/WebSphere/AppServer/installedChannels:/home/was/IBM/WebSphere/AppServer/lib/ext:/home/was/IBM/WebSphere/AppServer/web/help:/home/was/IBM/WebSphere/AppServer/deploytool/itp/plugins/com.ibm.etools.ejbdeploy/runtime -Dderby.system.home=/home/was/IBM/WebSphere/AppServer/derby -Dcom.ibm.itp.location=/home/was/IBM/WebSphere/AppServer/bin -Djava.util.logging.configureByServer=true -Duser.install.root=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01 -Djava.ext.dirs=/home/was/IBM/WebSphere/AppServer/tivoli/tam:/home/was/IBM/WebSphere/AppServer/java/jre/lib/ext -Djavax.management.builder.initial=com.ibm.ws.management.PlatformMBeanServerBuilder -Dpython.cachedir=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/temp/cachedir -Dwas.install.root=/home/was/IBM/WebSphere/AppServer -Djava.util.logging.manager=com.ibm.ws.bootstrap.WsLogManager -Dserver.root=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01 -Dcom.ibm.security.jgss.debug=off -Dcom.ibm.security.krb5.Krb5Debug=off -Dfile.encoding=UTF-8 -Djava.library.path=/home/was/IBM/WebSphere/AppServer/lib/native/aix/ppc_64/:/ima/vg1/IBM/WebSphere/AppServer/java/jre/lib/ppc64/default:/ima/vg1/IBM/WebSphere/AppServer/java/jre/lib/ppc64:/ima/vg1/IBM/WebSphere/AppServer/java/jre/lib/ppc64/j9vm:/ima/vg1/IBM/WebSphere/AppServer/java/jre/../lib/ppc64:/home/was/IBM/WebSphere/AppServer/bin:/usr/lib:/ima/vg1/IBM/cognos/c10/bin64/: -Djava.endorsed.dirs=/home/was/IBM/WebSphere/AppServer/endorsed_apis:/home/was/IBM/WebSphere/AppServer/java/jre/lib/endorsed:/home/was/IBM/WebSphere/AppServer/endorsed_apis:/home/was/IBM/WebSphere/AppServer/java/jre/lib/endorsed -Djava.security.auth.login.config=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/properties/wsjaas.conf -Djava.security.policy=/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/properties/server.policy com.ibm.wsspi.bootstrap.WSPreLauncher -nosplash -application com.ibm.ws.bootstrap.WSLauncher com.ibm.ws.runtime.WsServer /home/was/IBM/WebSphere/AppServer/profiles/AppSrv01/config ZHSIMAVAR1Node01Cell ZHSIMAVAR1Node01 server1
```
2. 执行kill -3 + java进程号，如：`kill -3 8913104`
3. javacore文件会自动生成在在websphere的profile目录下，例如`javacore.20130527.173545.8913104.0001.txt`，文件名中有时间信息：
```sh
was@ZHSIMAVAR1:/home/was#cd /home/was/IBM/WebSphere/AppServer/profiles/AppSrv01
was@ZHSIMAVAR1:/home/was/IBM/WebSphere/AppServer/profiles/AppSrv01#ls -l
total 46864
drwxr-xr-x 2 was was 4096 May 27 17:12 WORKDIR_IS_UNDEFINED
drwxr-xr-x 3 was was 12288 Apr 10 17:38 bin
drwxr-xr-x 9 was was 256 Apr 10 17:51 config
drwxr-xr-x 6 was was 256 Apr 10 17:44 configuration
drwxr-xr-x 10 was was 256 May 16 21:35 consolepreferences
drwxr-xr-x 3 was was 4096 Apr 10 17:38 etc
drwxr-xr-x 2 was was 4096 Apr 10 17:37 firststeps
drwxr-xr-x 2 was was 256 Apr 10 17:37 installableApps
drwxr-xr-x 3 was was 256 Apr 10 17:38 installedApps
drwxr-xr-x 2 was was 256 Apr 10 17:37 installedConnectors
drwxr-xr-x 3 was was 256 Apr 10 17:51 installedFilters
-rw-r--r-- 1 was was 6490778 Apr 19 14:24 javacore.20130419.142441.8585306.0001.txt
-rw-r--r-- 1 was was 6507262 Apr 19 14:24 javacore.20130419.142446.8585306.0002.txt
-rw-r--r-- 1 was was 6488667 Apr 19 14:24 javacore.20130419.142448.8585306.0003.txt
-rw-r--r-- 1 was was 4456135 May 27 17:35 javacore.20130527.173545.8913104.0001.txt
drwxr-xr-x 5 was was 256 Apr 10 17:59 logs
drwxr-xr-x 4 was was 4096 Apr 10 17:38 properties
drwxr-xr-x 3 was was 256 Apr 10 17:38 servers
drwxr-xr-x 5 was was 4096 Apr 10 17:51 temp
drwxr-xr-x 3 was was 256 Apr 10 17:51 tranlog
drwxr-xr-x 8 was was 4096 May 26 10:01 workspace
drwxr-xr-x 12 was was 4096 May 26 10:01 wstemp
```
**linux/unix+tomcat/weblogic 获取java线程堆栈信息的具体操作步骤如下:**
1. 获取进程id和kill命令和上面的操作一致。
2. tomcat的输出信息在catalina.out文件中。
3. weblogic在weblogic的标准输出文件中，如果是使用nohup启动的weblogic那么可能在nohup.out文件中。
## 方法4. jstack -l pid 命令 {#threadstack-jstack}
```sh
jstack -l 12353 > ./jvm-stacktrace.log
```
jstack 为java自带的命令，可以在java安装目录bin下找到，`12353` 为当前java对应的进程号。 导出线程堆栈，建议间隔几秒钟连续导出3次，要捕捉到当时计算的场景。
## 线程内容分析 {#threadstack-analyse}
1. 通过ibm提供的javacore分析工具jca441.jar打开javacore文件，参考[ibm官方说明](https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=2245aa39-fa5c-4475-b891-14c205f7333c)，点击
[此处](ftp://public.dhe.ibm.com/software/websphere/appserv/support/tools/jca/jca445.jar)下载jca441.jar。
2. 使用命令`java -jar ~/Downloads/jca441.jar` 运行，然后点击工具栏上面的`Open Thread Dumps`按钮，选择javacore文件即可。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/OOM（OutOfMemoryError）故障排查.md"
htmlUrl: "https://docs.succapp.com/v5/howto/a92365a4"
title: "OOM（OutOfMemoryError）故障排查"
---
---
order: 5
---
# OOM（OutOfMemoryError）故障排查
\[\[toc]]
当系统启动后一起正常，但是使用一段时间后或者用户量多了之后就卡了，一直没响应，CPU使用率很高，重启服务后又正常了，这时很可能就是OOM了。
## OutOfMemoryError原因{#what-is-oom}
:::tip
本章节中涉及到操作JVM启动参数的操作请参考[Tomcat设置启动环境变量](../install/middleware/tomcat.md#env)
:::
### 1.java.lang.OutOfMemoryError: Java heap space{#oom-heap}
堆内存不够用了，堆内存32位系统最好大于1G，64位最好大于2G，但不要太大，太大会导致gc慢，更不要大于或接近物理内存大小，否则会使用交换空间虚拟内存严重降低系统性能。
**解决方法**
建议增大JVM启动参数`-Xmx=2048m`
### 2.java.lang.OutOfMemoryError: PermGen space{#oom-permgen}
:::tip
这个异常只对JDK7及以下版本，JDK8已经去掉了PermGen space，改为Metaspace了。JDK8最好设置参数`-XX:MaxMetaspaceSize=256m`，避免JVM无节制的使用内存。
:::
PermGen space的全称是`Permanent Generation space`，是指内存的永久保存区域, 这块内存主要是被JVM存放Class和Meta信息的，Class在被Loader时就会被放到PermGen space中, 它和存放类实例(Instance)的Heap区域不同，GC(Garbage Collection)不会在主程序运行期对 PermGen space进行清理，所以如果你的应用中有很多CLASS的话（包括Spring动态产生的类），就很可能出现PermGen space错误。
**解决方案**
建议增加JVM启动参数`-XX:MaxPermSize=256m`
MaxPermSize参数表示JVM可用的最大PermGen space，MaxPermSize参数大小为32M，MaxPermSize不会占用Max Heap Size（-Xmx）中设置的大小，如果设置：-Xmx1024m -XX:MaxPermSize=256m，那么Max Heap Size是1024m，不是1024m-256m
### 3.java.lang.OutOfMemoryError: GC overhead limit exceeded{#oom-overhead-limit-exceeded}
:::tip
java.lang.OutOfMemoryError: GC overhead limit exceeded，这个是JDK6新添的错误类型。是发生在GC占用大量时间为释放很小空间的时候发生的，是一种保护机制。
:::
JVM GC过程耗时很久但只回收了不到2%的可用内存，如果已经设置了Xmx参数，那么可能是由于某些用户操作导致系统长时间占用大量内存无法GC。在JSP导入大excel时，也会出现此错误提示。
**解决方案**
增加JVM启动参数`-XX:-UseGCOverheadLimit`，更多内容可参考网页[调优JVM内存](https://www.iteye.com/blog/java-boy-463454)
## OutOfMemoryError故障确诊{#oom-check}
当系统cpu消耗很高，而且线程都在做gc的时候可能就是有OOM了，如何确诊呢：
### 看看最忙的线程在干啥{#threads-check}
```sh
top //显示耗费cpu的进程
top -p 进程号 -H //显示这个进程内最好分cpu的线程，把列出的pid转换成小写16进制可在JVM堆栈中找到堆栈信息
```
### 设置gc日志记录，并分析gc日志{#gc-logs-check}
给JVM设置gc日志记录：`-verbose:gc -Xloggc:garbage-collection.log`(参见[oracle官方说明](http://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html))，然后使用网站[gceasy](http://gceasy.io/index.jsp)分析日志：
当提示`Our analysis tells that your application is suffering from memory leak. It can cause OutOfMemoryError, JVM to freeze, poor response time and high CPU consumption.` 时就说明有内存漏洞了。
## OutOfMemoryError故障排查{#heapdump}
### 参数自动导出Heapdump{#heapdump-path}
如果已经进行了合理的`Xmx`和`XX:MaxPermSize`设置，还是出现**OutOfMemoryError**，那需要咨询研发工程师排查问题，为了帮助研发工程师解决问题，增加如下JVM参数以便在出现OOM的时候获得JVM的HeapDump文件：
```sh
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/store/dumpfiles
```
当下次出现OOM后JVM会产生heapdump文件在`/path/to/store/dumpfiles` 目录下，请自行修改`/path/to/store/dumpfiles`的具体位置，确保`/path/to/store/dumpfiles`是一个存在的目录，且启动JVM的系统用户有权限写这个目录，如果下次出现OOM，把HeapDump文件（很大，需压缩后）发送给研发工程师。
### jmap命令导出Heapdump{#heapdump-jmap}
如果系统日志已经发现OOM错误，而未配置`-XX:+HeapDumpOnOutOfMemoryError`参数，并且内存占用比较高，可以通过jdk自带的jmap命令导HeapDump。
```sh
./jmap -dump:live,format=b,file=heap.hprof
```
### 分析heapdump文件{#heapdump-analyse}
生产环境内存一般配置比较高比如10G左右，产生的heapdump文件比较大，可以使用现场测试环境服务器安装MAT，采用命令行进行分析，把分析的结果发给研发进行排除问题。
**MAT下载**
点击[此处](https://www.eclipse.org/mat/downloads.php)下载MAT，选择Linux(X86\_64/GTK+).
**配置MAT**
解压之后，需要修改MAT的配置文件，打开MemoryAnalyzer.ini文件，修改-Xmx的值，使其大于hprof文件的大小，建议是其2倍大小。
**执行分析命令**
```sh
./ParseHeapDump.sh heap.hprof org.eclipse.mat.api:suspects
```
执行以后会生成 xxxx\_Suspects.zip 的压缩包，解压后打开其中的html页面即可看到结果。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/如何处理Mysql异常：Packet for query is too large.md"
htmlUrl: "https://docs.succapp.com/v5/howto/ef9b5bad"
title: "如何解决Mysql异常:Packet for query is too large"
---
---
order: 6
---
# 如何解决Mysql异常:Packet for query is too large
完整异常信息如下
```sh
Packet for query is too large (7342 > 2048). You can change this value on the server by setting the max_allowed_packet
```
## 异常原因
每个数据库对blob字段的大小有限制，Mysql默认的大小太小，导致元数据文件的content字段无法正确存储。
## 解决方案
在Mysql配置文件(Windows下为`my.ini`，Linux下为`my.cnf`)的\[mysqld]配置`max_allowed_packet = 50M`，修改Mysql配置文件参考[Mysql安装配置](../install/database/MySQL.md#配置初始化文件)。
**以Linux为例，具体步骤如下：**
1. 运行下面代码打开配置文件M
```sh
vim /etc/my.cnf
```
2. 在\[mysqld]下修改(若不存在则添加)`max_allowed_packet = 50M`。
3. 保存后运行下面代码重启MySQL服务
```sh
service mysql restart
```
---
url: "https://docs.succapp.com/v5/guide/devops/faq/SQL Server 未返回响应，连接已关闭.md"
htmlUrl: "https://docs.succapp.com/v5/howto/tf7b5abc"
title: "SQL Server 未返回响应，连接已关闭"
---
---
order: 7
---
# SQL Server 未返回响应，连接已关闭
环境：
1. SQLServer2008
2. jdk1.8.0\_231
异常堆栈：
```java
java.io.IOException: SQL Server 未返回响应。连接已关闭。
at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.ensureSSLPayload(IOBuffer.java:513)
at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.readInternal(IOBuffer.java:570)
at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.read(IOBuffer.java:562)
at com.microsoft.sqlserver.jdbc.TDSChannel$ProxyInputStream.readInternal(IOBuffer.java:757)
at com.microsoft.sqlserver.jdbc.TDSChannel$ProxyInputStream.read(IOBuffer.java:745)
at sun.security.ssl.InputRecord.readFully(InputRecord.java:465)
at sun.security.ssl.InputRecord.read(InputRecord.java:503)
at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:975)
at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1367)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1395)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1379)
at com.microsoft.sqlserver.jdbc.TDSChannel.enableSSL(IOBuffer.java:1379)
[wrapped] com.microsoft.sqlserver.jdbc.SQLServerException: 驱动程序无法通过使用安全套接字层(SSL)加密与 SQL Server 建立安全连接。错误:“SQL Server 未返回响应。连接已关闭。”。
at com.microsoft.sqlserver.jdbc.SQLServerConnection.terminate(SQLServerConnection.java:1368)
at com.microsoft.sqlserver.jdbc.TDSChannel.enableSSL(IOBuffer.java:1412)
at com.microsoft.sqlserver.jdbc.SQLServerConnection.connectHelper(SQLServerConnection.java:1058)
at com.microsoft.sqlserver.jdbc.SQLServerConnection.login(SQLServerConnection.java:833)
at com.microsoft.sqlserver.jdbc.SQLServerConnection.connect(SQLServerConnection.java:716)
at com.microsoft.sqlserver.jdbc.SQLServerDriver.connect(SQLServerDriver.java:841)
at com.succez.commons.jdbc.impl.a.a(JdbcUtils.java:1656)
at com.succez.commons.jdbc.impl.a.a(JdbcUtils.java:1413)
```
## 异常原因
sqlserver的jdbc连接，默认使用ssl，而sqlserver的ssl连接使用了3DES的算法。
从JDK 8u171开始，默认disable了3DES算法，详见：
https://java.com/en/download/help/release\_changes.html
```html
Change: XML Signatures Signed with EC Keys Less Than 224 Bits Disabled
To improve the strength of SSL/TLS connections, 3DES cipher suites have been disabled in SSL/TLS connections
in the JDK via the jdk.tls.disabledAlgorithms Security Property.
```
## 解决办法
修改jre\lib\security\java.security，删除jdk.tls.disabledAlgorithms中的3DES\_EDE\_CBC。
## 参考资料
1. https://www.cnblogs.com/blsz/p/11530380.html
2. https://www.java.com/en/configure\_crypto.html
3. https://docs.microsoft.com/zh-cn/archive/blogs/jdbcteam/the-driver-could-not-establish-a-secure-connection-to-sql-server-by-using-secure-sockets-layer-ssl-encryption
---
url: "https://docs.succapp.com/v5/guide/devops/faq/如何修改默认数据库配置.md"
htmlUrl: "https://docs.succapp.com/v5/howto/b5dbcff5"
title: "如何修改默认数据库配置"
---
---
order: 7
---
# 如何修改默认数据库配置
系统运维时可能需要对[默认数据库](../install/basic-install/workdir-and-defdb.md#defjdbc)的配置进行修改，比如：用户名、密码、最大连接数等，本文介绍如何调整默认数据库参数
## 可直接修改的属性{#modifiable-properties}
连接默认数据库时的[选填项](../../data-connect/datasources.md#properties-setting)除**JDBC URL**均支持直接修改，具体如下：
| 属性名称 | 说明 |
| :---- |:----|
| 密码 | 连接数据库用到的密码 |
| 描述 | 数据源连接的描述，设置后会在数据源列表中的`描述`列显示，便于业务区分 |
| 最大连接数 | 数据库连接池最大连接数，即允许同时执行sql的最大连接数，默认为20 |
| 等待超时(秒)| 当连接池满，获取连接会等待，直到有连接可用，如果超过最大等待时间，会抛出超时异常 |
| 有效性检查 | 从连接池获取连接时，测试连接的有效性，默认为不开启。当网络不稳定时，需要勾选开启 |
| 镜像库 | 启用镜像库功能，系统可以利用数据库的镜像能力做到读写分离和分散查询压力，增加系统的承压能力 |
| 镜像库URL | 配置镜像库的地址 |
| 镜像同步延迟时间 | 用于修改模型数据后，是否延迟读取镜像库数据。单位秒，默认0，表示不延迟，可以直接查镜像库 |
| 自定义属性 | 用于数据源的特定参数，可参考[自定义属性](../../data-connect/datasources.md#custom-properties) |
**修改方法：**
`数据源`列表中点击**default** > **编辑**，弹出连接数据库对话框后，即可在输入框中编辑，输入完成后点击`确定`，完成对以上属性的修改，修改即时生效。
## 不可直接修改的属性{#readonly-properties}
为了保证系统的稳定，防止修改后出现默认数据库无法连接的异常，连接数据库的基本信息均无法在`数据源`编辑界面直接修改，包括：**数据库类型**、**地址**、**数据库名**、**用户名**、**JDBC URL**
**修改方法：**
修改服务器[工作目录](../install/basic-install/workdir-and-defdb.md#set-workdir)中[jdbc配置文件](/dev/meta/jdbc-conf)中对应的**user**、**pasword**、**driver**、**url**参数，保存后重新启动tomcat生效。
## 集群环境下注意事项{#notice}
1. 集群各节点间对数据源设置是同步的，因此对于[可直接修改的属性](#不可直接修改的属性)，只需要在某一节点进行修改，其他节点会自动同步。
2. 由于修改url、user会影响集群认证，因此在修改[不可直接修改的属性](#不可直接修改的属性)前，请先关闭所有节点，保证所有节点修改后的配置是可用且一致的，然后再启动tomcat，否则会出现无法加入集群的情况。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/如何处理Mysql异常：Communications link failure.md"
htmlUrl: "https://docs.succapp.com/v5/howto/fd0fe51e"
title: "如何解决Mysql异常:Communications link failure"
---
---
order: 7
---
# 如何解决Mysql异常:Communications link failure
## 问题现象{#mysql-errors}
MySQL数据加工或者计算报表时偶尔会报下列异常。
**异常1：**
```sh
java.io.EOFException: Can not read response from server. Expected to read 4 bytes, read 0 bytes before connection was unexpectedly lost.
at com.mysql.cj.protocol.FullReadInputStream.readFully(FullReadInputStream.java:67)
at com.mysql.cj.protocol.a.SimplePacketReader.readHeader(SimplePacketReader.java:63)
at com.mysql.cj.protocol.a.SimplePacketReader.readHeader(SimplePacketReader.java:45)
at com.mysql.cj.protocol.a.NativeProtocol.readMessage(NativeProtocol.java:556)
[wrapped] com.mysql.cj.exceptions.CJCommunicationsException: Communications link failure
The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.
at jdk.internal.reflect.GeneratedConstructorAccessor117.newInstance(Unknown Source)
at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
at java.base/java.lang.reflect.Constructor.newInstance(Constructor.java:490)
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:61)
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:105)
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:151)
at com.mysql.cj.exceptions.ExceptionFactory.createCommunicationsException(ExceptionFactory.java:167)
at com.mysql.cj.protocol.a.NativeProtocol.readMessage(NativeProtocol.java:562)
at com.mysql.cj.protocol.a.NativeProtocol.readServerCapabilities(NativeProtocol.java:514)
at com.mysql.cj.protocol.a.NativeProtocol.beforeHandshake(NativeProtocol.java:404)
at com.mysql.cj.protocol.a.NativeProtocol.connect(NativeProtocol.java:1447)
```
**异常2：**
```sh
10:45:05.709
正在执行导入，已写入行数：0
10:45:15.861
LOAD DATA LOCAL INFILE 'x' ......
10:57:43.397
正在执行导入，已写入行数：1024000
11:00:28.874
Communications link failure
The last packet successfully received from the server was 913,010 milliseconds ago. The last packet sent successfully to the server was 165,478 milliseconds ago.异常堆栈：
java.net.SocketException: 断开的管道 (Write failed)
at java.base/java.net.SocketOutputStream.socketWrite0(Native Method)
at java.base/java.net.SocketOutputStream.socketWrite(SocketOutputStream.java:110)
at java.base/java.net.SocketOutputStream.write(SocketOutputStream.java:150)
at java.base.security.ssl.SSLSocketOutputRecord.deliver(SSLSocketOutputRecord.java:341)
at java.base.security.ssl.SSLSocketImpl$AppOutputStream.write(SSLSocketImpl.java:1186)
at java.base/java.io.BufferedOutputStream.write(BufferedOutputStream.java:123)
```
## 问题原因{#mysql-cause}
1. MySQL数据库服务重启了，而应用的数据库连接池缓存还是旧的数据库连接。
2. `net_read_timeout`、`net_write_timeout` 参数默认配置的时间过短，一般发生在数据加工数据迁移场景下。以两个MySQL使用数据加工迁移数据为例说明，数据加工抽取数据采用MySQL load data 加管道流的方式实现，由于源头获取数据被卡住了，在往目标库写入数据时超过MySQL `net_read_timeout`参数的限制，该参数默认为30秒，即30秒MySQL没有从jdbc连接中获取数据，就会自动断掉连接。上述异常说明如下：
1. The last packet sent successfully to the server was 165,478 milliseconds ago ，表示在165秒以前成功传输过数据，往MySQL写入数据连接是30秒，而错误是在165秒发生，是因为在这165秒之间没有写入数据了，在165秒以后待管道的源表在次获取数据后进行写入时，这时连接超时抛出了异常。
2. The last packet successfully received from the server was 913,010 milliseconds ago. 表示建立连接执行load data 后，MySQL给jdbc客户端的响应；从上面的异常日志看出，10:45:15开始导入，异常11:00:28抛出，预计913秒左右。
::: warning 注意：
MySQL默认配置了 `wait_timeout=28800` ，8个小时连接没有使用会自动回收掉，回收后连接池不知道继续使用被回收的连接也会导致上述异常，但在SuccBI中默认每半小时检查一下连接的有效性，MySQL数据库自动回收空闲连接应该不存在。
:::
## 排查步骤{#check-steps}
**连接池有效性检查**
配置连接池的有效性，参考数据源管理：[数据源管理](../../data-connect/datasources.md#properties-setting)。如果是配置默认连接池，修改工作目录下的jdbc.conf中的`testConnectionOnCheckout`参数为true，参考如下：
```sh
{
"driver": "com.mysql.cj.jdbc.Driver",
"dbType": "MySQL",
"url": "jdbc:mysql://xxxxxxx:3361/whhsjc?useUnicode=true&characterEncoding=utf8&allowLoadLocalInfile=true",
"user": "xxxxx",
"password": "xxxxx",
"testConnectionOnCheckout": "true"
}
```
**MySQL timeout参数检查**
1. 查看当前MySQL数据库的超时参数，在数据库中执行 `show global variables like '%timeout%'`
```sh
VARIABLE_NAME VALUE
connect_timeout 10
delayed_insert_timeout 300
have_statement_timeout YES
innodb_flush_log_at_timeout 1
innodb_lock_wait_timeout 2
innodb_rollback_on_timeout OFF
interactive_timeout 28800
lock_wait_timeout 31536000
mysqlx_connect_timeout 30
mysqlx_idle_worker_thread_timeout 60
mysqlx_interactive_timeout 28800
mysqlx_port_open_timeout 0
mysqlx_read_timeout 30
mysqlx_wait_timeout 28800
mysqlx_write_timeout 60
net_read_timeout 30
net_write_timeout 60
rpl_stop_slave_timeout 31536000
slave_net_timeout 60
wait_timeout 28800
```
2. 在`my.cnf`(windows为my.ini)中修改`net_read_timeout`、`net_write_timeout` 参数值,修改Mysql配置文件参考[Mysql安装配置](../install/database/MySQL.md#配置初始化文件)
```sh
net_read_timeout=1800
net_write_timeout=1800
```
上述参数单位为秒,修改后需要重启MySQL服务才能生效。
说明：
1. `net_read_timeout` 表示MySQL服务器从客户端读取数据的网络超时，即客户端向服务器提交数据时，等待多少秒仍未执行成功时自动断开连接
2. `net_write_timeout` 表示MySQL服务器往客户端写数据的网络超时，即表示客户端从服务器端读取数据，等待多少秒仍未执行成功时自动断开连接
---
url: "https://docs.succapp.com/v5/guide/devops/faq/Oracle Connection reset by peer.md"
htmlUrl: "https://docs.succapp.com/v5/howto/tf6b5a12"
title: "Oracle Connection reset by peer"
---
---
order: 8
---
# Oracle Connection reset by peer
## 问题现象{#trouble}
环境：
1. Linux服务器
2. Oracle 11g
```java
com.succez.commons.jdbc.SuccezSQLException: (xzzlyk)IO Error: Connection reset by peer
at oracle.jdbc.driver.T4CPreparedStatement.executeForDescribe(T4CPreparedStatement.java:779)
at oracle.jdbc.driver.OracleStatement.executeMaybeDescribe(OracleStatement.java:921)
at oracle.jdbc.driver.OracleStatement.doExecuteWithTimeout(OracleStatement.java:1099)
at oracle.jdbc.driver.OraclePreparedStatement.executeInternal(OraclePreparedStatement.java:3640)
at oracle.jdbc.driver.T4CPreparedStatement.executeInternal(T4CPreparedStatement.java:1384)
at oracle.jdbc.driver.OraclePreparedStatement.executeQuery(OraclePreparedStatement.java:3687)
at oracle.jdbc.driver.OraclePreparedStatementWrapper.executeQuery(OraclePreparedStatementWrapper.java:1165)
at oracle.jdbc.OracleDatabaseMetaData.getTables(OracleDatabaseMetaData.java:2723)
```
## 异常原因{#why}
Oracle JDBC在建立连接时默认读取的Linix的`/dev/random`来产生随机数，但是读取过程可能发送阻塞：
1. Oracle JDBC在建立连接时需要一些随机数据用以加密session token之类的东西，它会读取`/dev/random`设备，`/dev/random`设备会返回小于熵池噪声总数的随机字节。
2. Linux内核熵池，通过搜集键盘，鼠标，中断，磁盘操作来产生随机数据。`/dev/random`可生成高随机性的公钥或一次性密码本。若熵池空了，对`/dev/random`的读操作将会被阻塞，直到收集到了足够的环境噪声为止。
3. `/dev/urandom`则是一个非阻塞的发生器:`dev/random`的一个副本是`/dev/urandom`（”unlocked”，非阻塞的随机数发生器），它会重复使用熵池中的数据以产生伪随机数据。对`/dev/urandom`的读取操作不会产生阻塞，但其输出的熵可能小于`/dev/random`的。
4. 随机数据源默认用的是`/dev/random`。
具体的在java中，是使用`java.security.SecureRandom`产生的随机数：
java.security.SecureRandom is a standard API provided by sun. Among various methods offered by this class `void nextBytes(byte[])` is one. This method is used for generating random bytes.
Oracle 11g JDBC drivers use this API to generate random number during login. Users using Linux have been encountering SQLException("Io exception: Connection reset").
The problem is two fold
1. The JVM tries to list all the files in the /tmp (or alternate tmp directory set by `-Djava.io.tmpdir`) when SecureRandom.nextBytes(byte\[]) is invoked.
If the number of files is large the method takes a long time to respond and hence cause the server to timeout
2. The method void `nextBytes(byte[])` uses `/dev/random` on Linux and on some machines which lack the random number generating hardware the operation slows down to the extent of bringing the whole login process to a halt.
Ultimately the the user encounters `SQLException("Io exception: Connection reset")`
Users upgrading to 11g can encounter this issue if the underlying OS is Linux which is running on a faulty hardware.
Cause The cause of this has not yet been determined exactly. It could either be a problem in your hardware or the fact that for some reason the software cannot read from dev/random
Solution Change the setup for your application, so you add the next parameter to the java command:
`-Djava.security.egd=file:/dev/./urandom`
## 解决办法{#solutions}
### 方法一{#solution1}
直接修改$JAVA\_HOME/jre/lib/security路径下的java.security文件。把`securerandom.source=file:/dev/random`修改成`securerandom.source=file:/dev/./urandom`。
### 方法二{#solution2}
tomcat文档里的建议，采用非阻塞的熵源(entropy source)，通过java系统属性来设置：
```java
-Djava.security.egd=file:/dev/./urandom
```
## 参考资料{#references}
1.
2.
3.
---
url: "https://docs.succapp.com/v5/guide/devops/faq/Oracle SO_TIMEOUT.md"
htmlUrl: "https://docs.succapp.com/v5/howto/oracle_so_timeout"
title: "Interrupt task is already scheduled for the thread Thread[main,5,main] and the type SO_TIMEOUT"
---
---
order: 9
---
# Interrupt task is already scheduled for the thread Thread\[main,5,main] and the type SO\_TIMEOUT
## 问题现象{#trouble}
环境：
1. Linux服务器
2. Oracle 11g, Oracle 19c
3. JDBC Driver 18.3.0.0
异常
```java
java.lang.IllegalStateException: Interrupt task is already scheduled for the thread Thread[Schedule18591,5,main] and the type SO_TIMEOUT
at oracle.net.nt.TimeoutInterruptHandler.scheduleInterrupt(TimeoutInterruptHandler.java:75)
at oracle.net.nt.TimeoutInterruptHandler.scheduleInterrupt(TimeoutInterruptHandler.java:93)
at oracle.net.nt.TimeoutSocketChannel.scheduleInterrupt(TimeoutSocketChannel.java:239)
at oracle.net.nt.TimeoutSocketChannel.connect(TimeoutSocketChannel.java:106)
at oracle.net.nt.TimeoutSocketChannel.(TimeoutSocketChannel.java:86)
at oracle.net.nt.TcpNTAdapter.connect(TcpNTAdapter.java:188)
at oracle.net.nt.ConnOption.connect(ConnOption.java:172)
at oracle.net.nt.ConnStrategy.execute(ConnStrategy.java:508)
at oracle.net.resolver.AddrResolution.resolveAndExecute(AddrResolution.java:521)
at oracle.net.ns.NSProtocol.establishConnection(NSProtocol.java:660)
at oracle.net.ns.NSProtocol.connect(NSProtocol.java:287)
at oracle.jdbc.driver.T4CConnection.connect(T4CConnection.java:1481)
at oracle.jdbc.driver.T4CConnection.logon(T4CConnection.java:540)
at oracle.jdbc.driver.PhysicalConnection.connect(PhysicalConnection.java:782)
at oracle.jdbc.driver.T4CDriverExtension.getConnection(T4CDriverExtension.java:39)
at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:704)
```
后来又新的异常
```java
java.io.FileNotFoundException: /data/tomcat/webapps/dsjyy/dist/favicon.ico (Too many open files)
at java.base/java.io.FileInputStream.open0(Native Method)
at java.base/java.io.FileInputStream.open(FileInputStream.java:219)
at java.base/java.io.FileInputStream.(FileInputStream.java:157)
at org.apache.commons.io.FileUtils.openInputStream(FileUtils.java:299)
at com.succez.commons.util.y.c(WebUtils.java:1202)
at com.succez.commons.util.y.b(WebUtils.java:898)
at com.succez.sys.mvc.StaticFileHandler.doGet(StaticFileHandler.java:100)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:626)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:733)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:231)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)
```
web服务器上文件句柄已经超过允许的最大范围，奇怪的是cpu导出文件`lsof -p`却没有发现很多文件句柄，反而更多的是数据库连接。
## 异常原因{#why}
Oracle jdbc Driver `12.2.0.0` 以上版本，有一个BUG:
当连接的url设置了`oracle.jdbc.ReadTimeout`参数，18.3版本会出`the type SO_TIMEOUT`异常，且会导致`数据库资源无法释放`。
Using the JDBC driver `18.3` along with oracle.jdbc.ReadTimeout property, it is throwing an IllegalStateException and `does not properly free up the database resources`.
It causes a session leak on the database side, eventually hitting the maximum number of processes, which then prevents any new connection to the database.
## 解决办法{#solutions}
降级驱动，使用jdbc(`12.1.0.2`)的版本。
## 参考资料{#references}
1.
2.
---
url: "https://docs.succapp.com/v5/guide/devops/faq/Query异常解决方案.md"
htmlUrl: "https://docs.succapp.com/v5/howto/err-query"
title: "Query异常解决方案"
---
---
order: 10
---
# Query异常解决方案
## 缺少关联关系{#err-query-field-no-joinrelation}
下列情况会出现这个异常：
1. 计算字段中，引用了两个及以上模型的字段。
2. 查询当前数据表时，过滤条件引用了其他数据表的字段。
**解决办法：**
1. 如果根据业务需求，查询的两个表是需要关联的，则应该设置两表的关联关系。
2. 模型管理界面，数据表的`右键`菜单中，有`关联关系`菜单，单击进入设置界面进行设置。
## 不合法的查询{#err-query-illegalquery}
SuccBI会对提交的查询进行严格的校验，比如只能查询管理员在设计SuperPage是指定的字段，查询其它字段会被系统阻止。
出现这个问题可能的原因：
1. 缓存错误，导致无法识别查询。
2. 产品BUG。
**解决办法：**
1. 重新编辑和保存查看的文件（如SuperPage或仪表板文件），清除浏览器缓存，再尝试访问。
2. 联系管理员，将异常完整信息反馈给系统运维人员。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/reset-admin.md"
htmlUrl: "https://docs.succapp.com/v5/howto/reset-admin"
title: "如何重置超级管理员（admin）账号和密码"
---
---
order: 11
---
# 如何重置超级管理员（admin）账号和密码
## 重置admin密码
若仅需要重置密码为 `admin`,可在默认数据源上执行下面这条SQL:
```sql
UPDATE SZSYS_5_USERS
SET salt = 'aKW9SwY9g',
PASSWORD = 'e4d5cc39494ace26872e317788fe6563b0af9ba0',
ENABLED = 1
WHERE USER_ID = 'admin'
```
## 添加admin账号
可在默认数据源上执行这条SQL进行添加，密码为 `admin`:
```sql
INSERT INTO SZSYS_5_users ( USER_ID, USER_NAME, SALT, PASSWORD, ENABLED )
VALUES('admin', 'admin', 'aKW9SwY9g', 'e4d5cc39494ace26872e317788fe6563b0af9ba0', 1 )
```
添加成功后，若使用admin登录到系统中，提示没有权限访问，是因为权限表中没有记录admin的权限，可在默认数据源上执行下面SQL 赋予超级管理员权限：
```sql
INSERT INTO SZSYS_5_USER_GROUP_MEMBERS ( USER_ID, GROUP_ID, AUTO_MATCH )
VALUES('admin', 'admin', 0)
```
## 禁用admin账号
可在默认数据源上执行这条SQL:
```sql
UPDATE SZSYS_5_USERS SET ENABLED = 0 WHERE USER_ID = 'admin'
```
---
url: "https://docs.succapp.com/v5/guide/devops/faq/Java进程内存超出-Xmx指定的大小.md"
htmlUrl: "https://docs.succapp.com/v5/howto/b752f2b1"
title: "Java进程内存超出-Xmx指定的大小"
---
---
order: 12
---
# Java进程内存超出-Xmx指定的大小
## 现象{#trouble}
某系统的实际现象：Tomcat启动时指定了-Xmx=9G，但是使用top命令查看进程的内存占用时，Java进程占用了14.8G，整个服务器的内存是16G，占用了超过90%的内存。
## 可能原因一：堆外内存泄露{#solution1}
在JDK8及以后的版本-Xmx是指定堆内内存的大小，堆外内存的大小不包含在内，多余的内存都是被堆外内存占用。[OOM（OutOfMemoryError）故障排查](./OOM（OutOfMemoryError）故障排查.md)中的方法用于找出堆内内存问题，无法用来排查堆外内存的问题。堆外内存的占用主要有Metaspace、Direct Buffer，需要找出这2块区域占用的内存大小。
Visual VM是一款可以实时查看JVM内存的工具，包括Metaspace和Direct Buffer。下载地址：，注意：
- 使用这款工具需要在启动Tomcat时指定启动参数：`-Djava.rmi.server.hostname=172.18.209.109 -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9500 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false` ，这样Tomcat在启动时会启动JMX服务，Visual VM通过JMX服务获取运行时内存信息。
- 这里`java.rmi.server.hostname`是Tomcat的局域网IP， `com.sun.management.jmxremote.port`可以随便指定，可以就用9500
- Visual VM安装好之后建立remote连接，见下图。
- 建立连接之后就可以查看metaspace和direct buffer：
JDK默认对Metaspace、Direct Buffer没有大小限制，可以设置Tomcat启动参数来指定大小：`-XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m -XX:MaxDirectMemorySize=2048m -Dsun.nio.MaxDirectMemorySize=2048m` 。这里指定最大Metaspace为512m基本够了。
## 可能原因二：堆外内存泄露{#solution2}
linux系统有一个经典的64M问题（叫bug更准确）：。意思是操作系统给进程分配内存时会在一个内存池中分配一块区域，这块区域是64M，如果内存池设置的很大，那么这样的64M区域可能会很多。通过linux的` pmap -x 3563 >pmap.txt`命令可以将指定进程号（比如3563）的内存占用情况输出到一个文本文件中去，下面是一个实际的例子：
可以看到有大量65536K的内存块，有的一块有65536K，有的是一大一小连续的2块加起来等于65536K，总共多达100多个，内存占用很恐怖。
解决办法是设置linux系统参数`export MALLOC_ARENA_MAX=4`。这个实际项目遇到的问题正是通过这个参数解决。
## 小结{#summary}
排查这里的问题时，关键是要找到是这么大内存由哪些部分组成，哪一部分占用了不合理的空间。实际排查时下面这些JDK提供的命令显示内存没有占用那么多，都不到-Xmx指定的大小（9G）：
- jcmd 2303 GC.heap\_info —— 这个可以查看堆信息，执行这个需要指定Tomcat启动参数`-XX:+UnlockDiagnosticVMOptions`
- jcmd 2303 GC.class\_histogram ——这个可以查看class加载情况，执行这个需要指定Tomcat启动参数`-XX:+UnlockDiagnosticVMOptions`
- jcmd 27264 VM.native\_memory detail >native\_memory\_detail.txt，执行这个需要指定Tomcat启动参数`-XX:NativeMemoryTracking=detail`
这间接说明系统不存在内存泄露的问题。换成用pmap命令就能看到真实的内存大小，它输出的内存跟top命令输出的内存是一致的。
---
url: "https://docs.succapp.com/v5/guide/devops/faq/错误提示排查.md"
htmlUrl: "https://docs.succapp.com/v5/devops/errcode"
title: "部署运维错误提示排查"
---
---
order: 99
navTitle: 错误提示排查
---
# 部署运维错误提示排查
---
url: "https://docs.succapp.com/v5/guide/dev/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/overview"
title: "开发"
---
---
order: 19
navTitle: 开发
indexTitle: 概述
---
# 开发
本章节汇总 SuccApp 中面向开发者的能力，包括 AI 低代码开发、元数据文件维护、脚本开发、扩展开发、系统集成和 API 参考。阅读时不必从头到尾顺序学习，先根据要解决的问题选择入口，再进入具体专题。
## 选择入口{#choose}
| 如果你要 | 阅读 |
| --- | --- |
| 使用 AI 和本地工作区参与项目交付 | [AI 低代码开发](./ai-building/README.md) |
| 理解 SuccApp 资源在文件系统中的组织方式 | [元数据系统](./meta/README.md) |
| 编写页面交互、后端接口、表达式函数、钩子或样式 | [脚本开发](./script/README.md) |
| 开发可复用的平台能力，例如组件、模板、连接器或登录方式 | [扩展开发](./extension/README.md) |
| 对接第三方系统、统一身份平台或外部页面 | [集成开发](./integrate/README.md) |
| 查询接口、系统 URL、系统表和依赖说明 | [API 参考](./references/README.md) |
## 开始前先判断{#before-you-start}
进入具体专题前，先判断三件事：
1. **改什么**：是业务页面和模型、脚本逻辑、平台扩展，还是系统集成。
2. **在哪里运行**：前端逻辑运行在浏览器端，后端逻辑运行在服务器端；两者可用的 API、调试方式和验证方式不同。
3. **影响多大**：只影响一个页面或应用的修改，优先找脚本和元数据文档；会被多个项目复用的能力，再考虑扩展开发。
如果不确定从哪里开始，通常先读 [AI 低代码开发](./ai-building/README.md) 和 [元数据系统](./meta/README.md)，再回到具体专题处理任务。
::: tip 提示
脚本、扩展和元数据修改都建议先在测试环境验证，再按团队流程同步到生产环境。
:::
## 推荐阅读路径{#reading-path}
1. 第一次接触开发文档：先读 [AI 低代码开发](./ai-building/README.md)，了解当前推荐的开发协作方式。
2. 要直接维护文件：读 [元数据系统](./meta/README.md)，再按文件类型或任务进入子页面。
3. 已经知道要做脚本、扩展或集成：直接进入对应专题，在专题内查步骤、示例和 API。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building"
title: "AI 低代码开发"
---
---
title: AI 低代码开发
description: >-
介绍如何使用 AI 编辑 SuccApp 元数据文件系统，并通过 SuccApp CLI 和 SuccApp for VS Code
完成低代码开发、验证、协作和发布。
navTitle: AI 低代码开发
indexTitle: 概述
---
# AI 低代码开发
AI 低代码开发是让 AI 参与 SuccApp 项目交付的一种方式：人提出业务目标和验收标准，AI 读取项目规则、理解元数据结构、修改本地文件，再由人和工具一起检查差异、验证效果并同步到服务器。
它不是让 AI 在浏览器设计器里模拟点击，而是把 SuccApp 元数据文件系统当作一套以 JSON 为主的低代码编程语言来编辑。页面、仪表板、报表、数据模型、程序流、脚本、主题和配置都以文件形式保存；AI 编辑这些文件时，应参考[元数据系统](../meta/README.md)中的格式规范、DTS、示例和当前项目同类文件，而不是只凭业务描述生成 JSON。
一次完整的 AI 低代码开发闭环通常包括：先在本地工作区修改元数据文件；再检查 diff、DTS、引用关系和同类文件写法；然后使用 SuccApp CLI 的 `workspace file compile` 执行服务器编译校验，检查 JSON 配置、表达式等元数据语义；通过检查后推送到测试服务器，由 AI 辅助整理验证点、人工完成业务测试；测试确认后，再按团队发布流程同步到生产服务器。
处理任何用户问题时，先理解 AI 低代码开发方式，再阅读[任务驱动](./task-driven.md)，按用户目标进入对应任务目录，并补充读取元数据格式、DTS、示例、工具和验证资料。
## 为什么需要 AI + 低代码{#why}
传统低代码实施主要依赖人在设计器里逐项配置。AI 低代码开发把这些配置沉淀为可阅读、可对比、可回退的文件，让 AI 可以帮助完成查找、理解、生成、批量修改和风险检查，让人把精力放在业务判断、效果验证和发布决策上。
它适合帮助团队完成这些工作：
1. 开发完整的低代码应用，例如 CRM、请假流程、报销流程、合同管理等。
2. 开发完整的数据分析项目，从数据建模、数据加工、调度，到报表、仪表板和可视化页面。
3. 制作或调整单个页面，例如大屏、业务表单、详情页、审批页和移动端页面。
4. 完成二次开发任务，例如脚本开发、第三方系统集成、接口对接、扩展开发和模板定制。
5. 配置系统管理和运维相关能力，例如权限、菜单、组织、角色、数据范围和系统设置。
6. 排查项目问题，例如数据不对、页面打不开、图表无数据、脚本报错、权限不符合预期。
7. 做批量调整和持续交付，例如批量改文案、调整过滤条件、整理脚本、检查差异、推送测试和发布生产。
## AI + 低代码比直接 AI 编程更适合企业应用{#ai-low-code-advantages}
1. **AI + 低代码把“写代码”变成“组合业务能力”**
直接 AI 编程通常要生成前端、后端、接口、权限、数据处理和部署脚本。AI + 低代码则是在 SuccApp 已有的页面、模型、数据集、流程、权限、报表、可视化、调度和发布能力之上完成组合，让 AI 把主要精力放在业务结构和交付目标上。
2. **结构化元数据比自由代码更适合 AI 稳定生成**
SuccApp 元数据文件系统本质上是一套 JSON 形式的低代码编程语言。它有明确的文件位置、字段结构、引用关系、元数据规范、DTS 和同类示例，比自由代码更容易被 AI 理解、生成和修改。
3. **更快更稳定，也更容易被人类掌控**
AI + 低代码可以复用平台内置能力，通常比直接 AI 编码更快；产出又是可阅读、可比较、可验证的元数据，不会变成只有研发人员才能接管的黑盒。业务人员、实施人员和团队负责人可以围绕页面、字段、流程、权限、指标和测试效果理解改动，提出调整并接管结果。
4. **对非专业开发者更友好**
企业应用的很多需求来自业务人员、实施人员、数据分析人员和运维人员。他们关心的是字段怎么定义、页面怎么排、流程怎么走、权限给谁、指标怎么算。AI + 低代码让这些人可以用业务语言参与开发，由 AI 把业务描述转换为 SuccApp 元数据。
5. **不是替代所有编程，而是控制代码的使用范围**
低代码仍然可以使用代码。脚本开发、复杂表达式、第三方系统集成、扩展开发和特殊业务逻辑都可以通过代码完成。区别在于，通用应用能力由平台承担，业务结构由元数据表达，只有确实需要编程的部分才写代码。
## 按角色阅读{#audience}
AI 低代码开发需要项目成员、团队负责人、AI 工具和元数据作者一起协作。你可以按自己的角色选择阅读入口：
| 角色 | 先读什么 | 目标 |
| --- | --- | --- |
| 项目成员 | [快速开始](./quick-start.md)、[任务驱动](./task-driven.md) | 跑通一次 AI 修改、差异检查、测试推送和 Git 提交。 |
| AI Agent | [SuccApp 官方文档 Skill](../../../SKILL.md)、[任务驱动](./task-driven.md) | 按任务读取规则、元数据参考、工具和验证方法。 |
| 团队负责人 | [安全边界](./basics/safety.md)、[团队协作](./release/team-collaboration.md)、[发布生产](./release/release-to-prod.md) | 制定 AI 修改、评审、测试到生产和回退规则。 |
| 工具负责人 | [了解基础概念和工具](./basics/README.md)、[SuccApp CLI](./basics/cli.md)、[SuccApp for VS Code](./basics/vscode.md)、[MCP](./basics/mcp.md) | 了解命令、视图、MCP 能力和安全边界。 |
| 元数据作者 | [元数据即代码](./basics/metadata-as-code.md)、[元数据系统](../meta/README.md) | 理解 JSON 元数据、DTS、同类文件和产品验证的关系。 |
如果只想理解元数据文件格式、后缀、DTS 和 `.meta`，请阅读[元数据系统](../meta/README.md)。本专题重点说明 AI 如何使用这些元数据完成低代码开发任务。
## 首次使用路径{#start}
第一次使用建议按下面顺序阅读：
1. [快速开始](./quick-start.md)：安装工具并跑通一次小修改。
2. [元数据即代码](./basics/metadata-as-code.md)：理解 AI 实际修改的对象。
3. [了解基础概念和工具](./basics/README.md)：了解 SuccApp CLI、SuccApp for VS Code 和 MCP 的分工。
4. [任务驱动](./task-driven.md)：根据用户问题进入对应任务页。
## 安排 AI 任务{#assign-ai-task}
给 AI 安排 SuccApp 修改任务时，先说清目标、环境、范围、参考、禁区和验收方式。任务说明建议见[工作区中的 AI 协作文件](./basics/workspace.md#ai-files)，任务类型入口见[任务驱动](./task-driven.md)。
AI 接手后应先定位候选文件和影响范围，再修改元数据；修改完成后输出文件清单、依据、质量检查结果和需要人工确认的风险。
## 继续阅读{#catalog}
1. [快速开始](./quick-start.md)
2. [任务驱动](./task-driven.md)
3. [了解基础概念和工具](./basics/README.md)：理解元数据即代码、工作区、必备工具、安全边界和实施方式差异。
4. [准备工作区](./workspace/README.md)：初始化工作区、认证、AI 上下文、连接服务器、Git 和同步变化。
5. [管理项目](./project/README.md)：整理元数据项目、目录、资源和修改边界。
6. [处理数据](./data/README.md)：连接、加工、调度、探查、查询、排查数据质量问题，以及准备测试或演示数据。
7. [构建分析可视化](./analytics/README.md)：制作仪表板、图表、指标和筛选联动。
8. [构建报表](./report/README.md)：制作报表、参数、打印、导出、模板和主题。
9. [构建低代码应用](./app/README.md)：制作页面、业务应用、门户、程序流、工作流和移动端。
10. [管理权限](./permission/README.md)：配置用户、用户组、资源权限和数据范围。
11. [脚本开发](../script/choose-script.md)：判断是否需要写脚本，并选择前端脚本、后端脚本、样式、系统页、钩子或程序流脚本节点。
12. [扩展平台能力](./extension/README.md)：开发平台级扩展能力。
13. [排查问题](./troubleshoot/README.md)：排查同步、登录、数据、页面、权限和调度问题。
14. [质量检查](./quality/README.md)：检查 diff、引用、元数据结构、产品运行效果和交付风险。
15. [管理发布](./release/README.md)：协作、提交、发布生产和回退。
16. [通过示例学习](./examples/README.md)：查看 DEMO 元数据和典型示例。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/task-driven.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/task-driven"
title: "任务驱动"
---
---
title: 任务驱动
description: 说明 AI 如何根据用户问题选择 AI 低代码开发任务文档、读取顺序和验证资料。
navTitle: 任务驱动
---
# 任务驱动
AI 接到 SuccApp 低代码开发问题时，先判断用户要完成什么任务，再进入对应任务文档。不要先按“概念、工具、验证、FAQ”这类资料类型路由；这些内容已经拆到具体任务中。
## 路由方法{#routing}
| 用户说法 | 首选任务 |
| --- | --- |
| 第一次使用、想先跑通流程 | [快速开始](./quick-start.md) |
| 想了解 AI 低代码开发、元数据、工作区、安全边界，或不确定该用 CLI、VS Code 还是 MCP | [了解基础概念和工具](./basics/README.md) |
| 初始化工作区、登录、连接服务器、克隆项目、同步变化 | [准备工作区](./workspace/README.md) |
| 新建或整理项目、目录、资源边界，只改指定文件 | [管理项目](./project/README.md) |
| 查找资源文件、模型文件、字段、路径、依赖，或判断某个 `/项目/...` 路径下有什么 | [定位元数据](./project/find-resource.md) |
| 接数据源、查库表、建模型、加字段、加工、提取、调度、准备测试或演示数据 | [处理数据](./data/README.md) |
| 查询物理层数据、执行只读 SQL、确认数据库产品和 SQL 方言，或查询语义层模型、查看 Query DSL JSON 格式 | [查询数据](./data/query-data.md) |
| 做看板、图表、指标卡、筛选器、可视化分析 | [构建分析可视化](./analytics/README.md) |
| 做报表、填报、参数栏、打印、导出、模板和主题 | [构建报表](./report/README.md) |
| 做业务页面、表单、门户、流程、程序流、移动端应用 | [构建低代码应用](./app/README.md) |
| 给用户或用户组开权限，检查权限和数据范围 | [管理权限](./permission/README.md) |
| 二次开发、定制开发、定制页面、样式、脚本、或外部接口 | [脚本开发](../script/choose-script.md) |
| 开发新数据库、新文件格式、新组件、新流程节点等平台扩展 | [扩展平台能力](./extension/README.md) |
| 冲突、推送失败、登录失败、数据不对、页面没反应、调度没跑 | [排查问题](./troubleshoot/README.md) |
| 校验元数据文件是否合法，或想在浏览器预览前获取 `.dash`、`.spg`、`.tbl` 等文件的编译错误 | [元数据合法性校验](./troubleshoot/metadata-validation.md) |
| 检查 AI 改得对不对，做 diff、引用、产品验证和风险评审 | [质量检查](./quality/README.md) |
| 想在浏览器中打开元数据文件、预览页面效果、进入设计器检查或拿到可访问 URL | [预览文件](./quality/preview-file.md) |
| 准备提交、团队协作、发布生产和回退 | [管理发布](./release/README.md) |
| 想找同类元数据样例 | [通过示例学习](./examples/README.md) |
## 通用读取顺序{#reading-order}
1. 先读当前任务目录的 `README.md`。
2. 根据任务页要求继续读相关元数据格式、DTS、示例和当前项目同类文件。
3. 涉及工作区、服务器或数据库时，补充阅读[准备工作区](./workspace/README.md)和[了解基础概念和工具](./basics/README.md)。
4. 修改完成后，按[质量检查](./quality/README.md)检查 diff、引用、元数据结构和产品运行效果。
5. 需要协作交付或上线时，继续阅读[管理发布](./release/README.md)。
## AI 输出要求{#output}
AI 处理任务时，应向用户说明：
1. 已识别的任务类型和读取的任务文档。
2. 候选项目、目录、文件和判断依据。
3. 修改范围、不会修改的范围和需要人工确认的风险。
4. 实际修改文件清单。
5. 已完成的检查和还需要人工验证的内容。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quick-start.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quick-start"
title: "快速开始"
---
---
title: 快速开始
order: 2
navTitle: 快速开始
---
# 快速开始
本文帮助你快速跑通一次 AI 低代码开发闭环：安装工具、初始化 SuccApp 工作区、连接测试服务器、克隆项目、让 AI 做一个小修改、检查差异、推送测试环境并提交 Git。
预计用时 20 到 30 分钟。完成后，你应能得到一个可重复使用的 SuccApp 工作区、一个已克隆的测试项目、一处经过 AI 辅助修改的元数据变更，以及一次可审查的 Git 提交。
## 前提条件{#requirements}
开始前请确认：
1. 有一个可以访问的 SuccApp 测试服务器。
2. 有可以在浏览器中登录该服务器的账号；脚本、CI 或无浏览器环境如需登录，可提前准备 Personal Access Token（PAT）。
3. 已准备一个本地目录作为 SuccApp 工作区。
4. 已安装 Node.js 和 npm，用于安装 SuccApp CLI。
5. 如需图形化检查，已安装 VS Code 和 SuccApp for VS Code。
::: warning 注意
第一次练习建议连接测试环境，不要直接连接生产环境。
:::
## 安装 SuccApp CLI{#install-cli}
SuccApp CLI 已发布到 npm。可以使用 npm 全局安装，安装后本机可直接执行 `succapp` 命令。
```bash
npm install -g @succsoft/succapp
```
安装后确认命令可用：
```bash
succapp --version
succapp --help
```
更多信息见[SuccApp CLI](./basics/cli.md)。
## 可选安装 SuccApp for VS Code{#install-vscode}
如果需要可视化查看服务器项目、Changes、diff 和文件历史，建议安装 SuccApp for VS Code。
在线安装时，在 VS Code 扩展视图搜索 `SuccApp` 并安装。离线环境可以使用与当前 SuccApp 版本匹配的 `.vsix` 安装包：
```bash
code --install-extension succapp-for-vscode-版本号.vsix
```
更多图形化入口见[SuccApp for VS Code](./basics/vscode.md)。
## 初始化工作区{#init-workspace}
选择一个空目录或团队 Git 仓库作为工作区：
```bash
mkdir customer-a-bi-workspace
cd customer-a-bi-workspace
succapp auth login http://localhost:8080
succapp workspace init --server http://localhost:8080
```
`auth login` 默认会打开浏览器完成 OAuth2 授权。如果当前环境无法打开浏览器，可以改用 `succapp auth login --pat http://localhost:8080`，并按提示输入服务器签发的 PAT。
`workspace init` 会初始化 `.succapp/config.json`，并补齐推荐工作区设置、编辑器结构提示、TypeScript 诊断、Git 忽略规则和 AI 协作入口文件。更多说明见[初始化工作区](./workspace/init-workspace.md)。
## 克隆项目{#clone-project}
查看服务器项目并克隆当前任务需要的项目：
```bash
succapp server project list
succapp workspace project clone DEMO
succapp workspace status
```
在 VS Code 中也可以通过 SuccApp 服务器视图克隆项目。
更多说明见[连接服务器与克隆项目](./workspace/connect-and-clone.md)。
## 让 AI 先理解再修改{#ai-edit}
第一次练习建议选择影响范围小、容易验证的修改，例如页面标题、说明文字、按钮文案或测试脚本中的一行日志。
可以先这样要求 AI：
```text
请在当前 SuccApp 工作区中查找客户明细页面相关的元数据文件。
先不要修改，请说明候选文件、判断依据和可能影响范围。
```
确认范围后再允许修改：
```text
请只修改客户明细页面标题，把“客户详情”改为“客户信息详情”。
不要修改字段名、资源 ID、权限、流程和脚本逻辑。修改后请列出变更文件。
```
完整流程见[使用 AI 修改元数据](./task-driven.md)。
## 查看变化和差异{#check-diff}
修改后先查看工作区状态：
```bash
succapp workspace status
```
需要给 AI 或脚本读取时使用结构化输出：
```bash
succapp workspace status --json
```
在 SuccApp for VS Code 中，可以打开 **变化** 视图并逐个文件查看 diff。
推送前确认变化列表里只包含本次需要的文件，没有误删、误改或大范围格式化。`.meta` 文件由 SuccApp 自动维护和修复，但出现大量无关 `.meta` 变化时仍要检查原因。
## 推送测试并预览{#push-preview}
确认差异无误后，推送到测试服务器：
```bash
succapp workspace push
```
如果只想定位当前文件对应的浏览器地址，可以使用：
```bash
succapp workspace file resolve path/to/file.spg
succapp workspace file open path/to/file.spg
```
在 VS Code 中也可以通过 **变化** 视图推送，并选择 **打开服务器视图** 或 **打开服务器编辑页**。
如果推送被远端变化阻止，先查看差异或拉取服务器变化，不要直接强制覆盖。更多说明见[修改、对比、拉取与推送](./workspace/sync-changes.md)和[冲突处理](./troubleshoot/conflict-handling.md)。
## 提交 Git{#commit}
测试通过后，将本地修改提交到 Git：
```bash
git status
git diff
git add path/to/changed-file
git commit -m "调整客户明细页面标题"
```
提交前确认 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、日志、临时文件和未确认的 AI 草稿没有进入 Git。更多说明见[工作区版本管理](./workspace/git-versioning.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics"
title: "了解基础概念和工具"
---
---
title: 了解基础概念和工具
description: 解释 AI 低代码开发中的元数据即代码、SuccApp 工作区、必备工具、安全边界和浏览器实施差异。
navTitle: 了解基础概念和工具
indexTitle: 概述
---
# 了解基础概念和工具
在让 AI 修改 SuccApp 项目前，先理解 AI 实际修改的对象、工作区同步模型、必备工具、安全边界，以及 SuccApp 和浏览器实施方式的差异。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 第一次了解 AI 低代码开发，不清楚 AI 实际修改什么。
- 需要区分 SuccApp 工作区、SuccApp CLI、SuccApp for VS Code 和 MCP 的分工。
- 需要确定 AI 能做什么、哪些操作必须人工确认。
- 需要向团队解释为什么不直接让 AI 在浏览器设计器中模拟点击。
## 任务入口
| 主题 | 先读 | 适用情况 |
| --- | --- | --- |
| 元数据即代码 | [元数据即代码](./metadata-as-code.md) | 理解 AI 修改的是本地工作区中的 SuccApp 元数据文件。 |
| 工作区 | [工作区](./workspace.md) | 理解本地工作区、服务器同步基线、AI 协作文件和 Git 的关系。 |
| SuccApp CLI | [SuccApp CLI](./cli.md) | 需要在终端中初始化工作区、登录服务器、查询数据、检查差异或同步变化。 |
| SuccApp for VS Code | [SuccApp for VS Code](./vscode.md) | 需要人工浏览服务器项目、查看 Changes、打开 diff、编辑脚本或推送测试环境。 |
| MCP | [MCP](./mcp.md) | 需要让支持 MCP 的 AI 客户端读取服务器信息、查元数据或查询数据库结构。 |
| 安全边界 | [安全边界](./safety.md) | 需要约束 AI 写服务器、改生产、删除资源、执行 SQL 或影响权限流程。 |
| 实施方式差异 | [SuccApp 和浏览器实施的区别](./succapp-vs-browser.md) | 需要判断什么时候适合用 SuccApp 工作区，什么时候适合直接在浏览器里配置。 |
## 相关阅读
- [准备工作区](../workspace/README.md)：理解基础概念后，继续初始化工作区、配置认证和克隆项目。
- [质量检查](../quality/README.md)：AI 修改完成后，检查变化范围、元数据结构和产品效果。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/metadata-as-code.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/metadata-as-code"
title: "元数据即代码"
---
---
title: 元数据即代码
navTitle: 元数据即代码
---
# 元数据即代码
SuccApp 元数据文件系统是 AI 低代码开发的核心。AI 不是直接操作数据库中的隐式状态，而是编辑本地工作区中的元数据文件，再通过 SuccApp CLI 或 SuccApp for VS Code 同步到服务器。
这些元数据文件多数是 JSON 或接近 JSON 的结构化文本。它们描述页面、仪表板、报表、数据模型、程序流、脚本、应用配置、主题、数据源和系统设置，可以理解为一套面向 SuccApp 的低代码编程语言。
## 为什么说它是低代码语言{#why-language}
元数据文件具备低代码语言的几个特征：
1. 有固定文件类型，例如 `.spg`、`.dash`、`.rpt`、`.tbl`、`.query`、`.afl`、`.wfl`、`.theme`、`.jdbc`。
2. 有语法和结构约束，基础结构由 JSON 语法、元数据规范和 DTS 共同描述。
3. 有类型和动态分支，例如组件 `type`、数据集 `modelType`、布局 `layoutType`、单元格 `cellType`。
4. 有引用机制，例如 `referenceResources`、`.meta`、文件路径、模型字段、组件 ID 和动作节点 ID。
5. 有运行时语义，同一段 JSON 会在设计器、预览页面、调度、权限、数据查询和发布流程中生效。
AI 修改元数据时，不能只生成“看起来合法”的 JSON，还要遵守这套语言的引用关系、历史结构和运行时约束。
## AI 应该读取哪些事实源{#sources}
修改元数据前，AI 应按下面顺序读取资料：
1. 当前项目规则：`AGENTS.md`、`.agents/rules/`、任务说明和团队约定。
2. 当前工作区同类文件：优先参考同项目、同目录、同版本的真实元数据。
3. 元数据手册：[元数据系统](../../meta/README.md)、文件类型页、元数据规则和 SuccApp Super JSON。
4. DTS 类型：[`/dev-types/index.json`](../../../../dev-types/index.json) 以及 `types/meta/`、`types/api/` 下的类型定义。
5. CLI 检查结果：工作区检查、后续编译校验和服务器返回错误。
6. 产品运行结果：设计器、页面预览、脚本日志和控制台信息。
本页只说明读取顺序、编辑流程和风险边界；字段、枚举、继承、可选性和动态类型分支以 DTS 为准。
## 常见文件和任务{#files}
| 任务 | 常见文件 | 说明 |
| --- | --- | --- |
| 做页面 | `.spg`、`.tpg`、`.fapp`、脚本文件 | 关注组件树、数据集、参数、动作和引用资源。 |
| 做看板 | `.dash`、`.tbl`、`.query` | 关注图表组件、数据集、主题和模型字段。 |
| 做报表 | `.rpt`、`.tbl`、`.query` | 关注单元格、数据区域、参数、导出和打印效果。 |
| 准备数据 | `.tbl`、`.query`、`.jdbc` | 关注字段、数据源、schema、SQL 和数据权限。 |
| 修改流程 | `.afl`、`.wfl` | 关注节点类型、节点 ID、参数流转和错误处理。 |
| 修改脚本 | `.ts`、`.js`、`.action.ts`、`.ftl` | 关注运行环境、类型声明、日志和验证方式。 |
## 修改原则{#rules}
1. 先定位文件类型，再打开对应文件类型页和 DTS。
2. 先读同类文件，再生成或修改结构。
3. 保留稳定标识，不随意改资源 ID、组件 ID、字段名、数据集 ID、动作节点 ID 和 `.meta` 中的资源 ID。
4. 新增、移动或删除文件时，同步检查相关目录 `.meta` 和引用路径。
5. 对大型 JSON 不做无意义全文件格式化，避免 diff 噪声。
6. 修改后至少做元数据静态检查、diff 检查和产品界面验证。
## 推荐阅读{#related}
1. [元数据系统](../../meta/README.md)
2. [SuccApp Super JSON](../../meta/rules/super-json.md)
3. [资源引用与路径](../../meta/rules/reference-paths.md)
4. [文件类型](../../meta/file-types/README.md)
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/workspace.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/workspace"
title: "SuccApp 工作区"
---
---
title: SuccApp 工作区
navTitle: 工作区
---
# SuccApp 工作区
SuccApp 工作区是一个本地目录，用来保存从 SuccApp 服务器克隆下来的元数据项目、服务器配置、同步基线、编辑器辅助配置、AI 协作文件和 Git 版本历史。可以把它理解为 SuccApp 元数据开发的项目目录：人在这里编辑文件，AI Agent 在这里读取规则和修改元数据，SuccApp CLI 和 SuccApp for VS Code 在这里检查差异、拉取和推送服务器变化。
SuccApp CLI 也可以直接读取或修改服务器上的远端文件，但正式项目更建议基于工作区修改本地文件。工作区能把一次修改变成可搜索、可审查、可回退、可协作的文件变更，更适合大项目、AI Agent 批量理解和修改、多文件联动调整、工作区版本管理和团队评审。
## 工作区与工具的关系{#tools}
工作区不是某一个工具的私有目录，而是多个工具共同协作的项目边界。
| 工具或角色 | 在工作区中的作用 |
| --- | --- |
| SuccApp CLI | 初始化工作区，执行状态检查、diff、拉取、推送、修复和脚本化自动化。 |
| SuccApp for VS Code | 浏览服务器项目，查看 Changes、文件历史和差异，并执行交互式同步操作。 |
| Git | 记录本地元数据文件的修改历史，支持评审、回退、分支协作和发布流程。 |
| AI Agent | 读取工作区规则和同类文件，在本地修改元数据，再交给人和工具检查。 |
需要了解 CLI 如何操作工作区时，阅读 [SuccApp CLI](./cli.md)；需要了解 VS Code 图形界面时，阅读 [SuccApp for VS Code](./vscode.md)。
## 初始化工作区{#init}
工作区可以从服务器克隆出初始内容，也可以从团队 Git 仓库恢复已有内容。AI Agent 和脚本化流程通常优先使用 SuccApp CLI；人工需要图形界面时再配合 SuccApp for VS Code。具体步骤见[初始化工作区](../workspace/init-workspace.md)。
## 版本管理{#versioning}
正式项目建议使用 Git 管理工作区。Git 记录团队版本历史、分支、提交、评审和回退；SuccApp 负责连接服务器、维护本地 mirror、检查本地变化和远端变化。推荐入库内容、忽略规则、提交流程和回退方式见[工作区版本管理](../workspace/git-versioning.md)。
## 工作区目录结构{#structure}
典型工作区结构如下。不同项目可能只包含其中一部分目录，实际结构以当前工作区为准。
```text
sales-ops-workspace/ # 工作区根目录，通常也是 Git 仓库根目录
├── .git/ # Git 本地版本库，由 Git 维护
├── .gitignore # Git 忽略规则，排除 SuccApp 运行时文件和本机临时文件
├── AGENTS.md # Codex 等 AI 工具优先读取的工作区说明
├── CLAUDE.md # Claude Code 入口，通常引用 AGENTS.md
├── .github/ # GitHub Copilot 等仓库级配置
│ └── copilot-instructions.md # GitHub Copilot 仓库级说明
├── .agents/ # AI 协作规则、技能和阶段性产物
│ ├── README.md # AI 工作区说明
│ ├── rules/ # 团队长期规则
│ ├── skills/ # 官方离线文档同步成功后写入 succapp-docs/
│ ├── plans/ # AI 实施计划和迁移计划
│ ├── reviews/ # AI 评审记录
│ ├── reports/ # AI 调查和验证报告
│ └── tmp/ # 一次性临时脚本和草稿
├── .succapp/ # SuccApp 工作区运行时目录，通常不提交 Git
│ ├── .gitignore # SuccApp 运行时文件的忽略规则
│ ├── config.json # 当前工作区的服务器地址簿和活跃服务器
│ ├── remote/ # 本地 mirror，保存上次同步时的服务器基线
│ ├── json-schemas/ # 编辑器结构提示辅助文件
│ ├── succ-types/ # 脚本 TypeScript 诊断使用的类型声明
│ ├── tsconfig.action.json # 服务端脚本 TypeScript 诊断配置
│ ├── tsconfig.browser.json # 浏览器脚本 TypeScript 诊断配置
│ ├── merge-base/ # 拉取和合并前保存的服务器基线副本
│ ├── merge-backup/ # 拉取和合并前保存的本地文件备份
│ ├── locks/ # 同步任务锁
│ ├── cache/ # 本地缓存
│ ├── *.log # 本机日志
│ └── state.json # 本机同步状态
├── .vscode/ # VS Code 工作区配置
│ └── settings.json # 文件关联、结构提示、隐藏规则等推荐设置
├── sales-ops/ # 元数据项目目录，对应服务器上的 SALES_OPS 项目
│ ├── .meta # 项目根目录直接子资源的服务器资源标识和附加信息
│ ├── settings/ # 项目级设置、主题、模板和附件
│ │ ├── .meta # settings 目录直接子资源的元信息
│ │ ├── settings.json # 项目设置
│ │ └── themes/ # 项目主题目录
│ ├── data/ # 项目级公共数据模型、查询和加工资源
│ │ ├── .meta # data 目录直接子资源的元信息
│ │ └── tables/ # 公共数据模型目录
│ │ ├── .meta # tables 目录直接子资源的元信息
│ │ ├── SALES_ORDER.tbl # 销售订单数据模型
│ │ ├── CUSTOMER_PROFILE.tbl # 客户画像数据模型
│ │ └── SALES_KPI.query # 销售指标查询
│ ├── app/ # 低代码应用目录
│ │ ├── .meta # app 目录直接子资源的元信息
│ │ └── sales-center.app/ # 销售运营中心应用
│ │ ├── .meta # 应用目录直接子资源的元信息
│ │ ├── settings.json # 应用设置
│ │ ├── index.spg # 应用首页
│ │ ├── customer-list.spg # 客户列表页面
│ │ ├── order-detail.spg # 订单详情页面
│ │ ├── data/ # 应用内私有数据模型或查询
│ │ ├── scripts/ # 应用内脚本
│ │ └── assets/ # 应用内图片、图标等素材
│ ├── ana/ # 跨应用共用的仪表板和报表
│ │ ├── .meta # ana 目录直接子资源的元信息
│ │ ├── sales-overview.dash # 销售总览仪表板
│ │ └── monthly-sales.rpt # 月度销售报表
│ └── public/ # 项目公开静态资源
│ ├── .meta # public 目录直接子资源的元信息
│ └── images/ # 项目公开图片资源
└── tsconfig.json # 工作区脚本 TypeScript 诊断入口配置
```
项目目录、资源文件和目录级 `.meta` 是需要协作管理的元数据，通常应纳入 Git。`.meta` 是 SuccApp 判断本地目录和服务器资源关系的重要文件，新增、移动、重命名或删除资源时，不要把相关 `.meta` 当作普通临时文件删除。
工作区根目录下可以有多个元数据项目，例如 `sales-ops/`、`finance-reporting/` 或 `sysdata/`。一个目录必须包含项目级 `.meta`，才会被 SuccApp 识别为工作区中的元数据项目。
## 本地文件、mirror 和服务器{#sync-model}
SuccApp 用三类内容判断同步状态：
| 内容 | 位置 | 说明 |
| --- | --- | --- |
| 工作区文件 | 项目目录 | 人和 AI 实际编辑的本地元数据文件。 |
| 本地 mirror | `.succapp/remote/` | 上次同步时记录的服务器基线。 |
| 服务器当前内容 | SuccApp 服务器 | 当前正在测试或生产环境生效的元数据。 |
本地文件和 mirror 不一致时，会产生本地变化；mirror 和服务器当前内容不一致时，会产生远端变化；本地和服务器同时改了同一资源时，可能产生冲突。
## AI 协作文件{#ai-files}
SuccApp 推荐工作区设置会初始化常见 AI 协作入口：
| 文件或目录 | 用途 |
| --- | --- |
| `AGENTS.md` | AI 工具优先读取的工作区规则入口。 |
| `CLAUDE.md` | Claude Code 入口，通常引用 `AGENTS.md`。 |
| `.github/copilot-instructions.md` | GitHub Copilot 仓库级说明。 |
| `.agents/rules/` | 团队长期规则。 |
| `.agents/skills/succapp-docs/` | 官方离线文档 skill，同步成功后生成。 |
| `.agents/plans/`、`.agents/reviews/`、`.agents/reports/` | 计划、评审和报告。 |
| `.agents/tmp/` | 一次性临时脚本和草稿。 |
默认情况下，计划、评审、报告和临时文件不应直接进入 Git；需要长期保留时，由团队确认后再调整忽略规则。
给 AI 安排任务时，不建议把所有规则都写成很长的个人提示词。长期规则放在 `AGENTS.md`、`.agents/rules/` 或团队文档中；单次任务提示词只补充本次目标、环境、范围、参考、禁区和验收方式。
| 信息 | 说明 |
| --- | --- |
| 目标 | 要解决的业务问题或期望效果。 |
| 环境 | 当前连接的是测试环境还是生产环境。 |
| 范围 | 允许 AI 查找或修改的项目、目录、页面、模型、脚本或数据源。 |
| 参考 | 已知入口、同类文件、截图、页面路径或业务样例。 |
| 禁区 | 不允许修改或执行的内容，例如权限、流程、生产配置、数据源和 SQL 写操作。 |
| 验收 | 人工如何确认任务完成，例如打开哪个页面、检查哪个 diff 或执行哪类业务流程。 |
如果目标、环境、范围或禁区不清楚，应先让 AI 列出候选文件和判断依据，再确认是否允许修改。
## 推荐协作方式{#recommended}
1. 每个客户或交付项目使用独立工作区。
2. 同一个工作区只管理同一套业务系统的测试和生产服务器。
3. 开始修改前先拉取 Git，再拉取服务器变化。
4. AI 修改前先读取规则和同类文件。
5. 修改后通过 SuccApp diff 和 Git diff 双重检查。
6. 测试环境验证通过后再提交 Git。
后续修改、拉取和推送流程见[修改、对比、拉取与推送](../workspace/sync-changes.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/cli.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/cli"
title: "SuccApp CLI"
---
---
title: SuccApp CLI
navTitle: SuccApp CLI
---
# SuccApp CLI
SuccApp CLI 是面向终端、脚本和 AI Agent 的命令行工具，命令名为 `succapp`。它把 SuccApp 服务器、元数据文件、工作区同步、数据库查询和认证状态开放给命令行，让用户和 AI 可以在浏览器设计器之外完成查询、排查、同步和自动化操作。
在 [AI 低代码开发](../README.md) 中，SuccApp CLI 是 AI Agent 与 SuccApp 产品服务器沟通的主要工具，它让 Agent 可以在终端里读取服务器状态、访问元数据文件、管理工作区、查询数据并用 `--json` 取得结构化结果；详细命令、参数和示例以 `succapp --help` 及各命令域的 `--help` 输出为准。
## 适合场景{#suitable}
SuccApp CLI 适合需要可重复执行、可脚本化或需要结构化输出的任务：
1. 初始化工作区、登录服务器、克隆项目和切换服务器。
2. 让 AI Agent 读取工作区状态、文件 diff、服务器文件、文件历史和数据库结构。
3. 在脚本、终端或 CI 中执行状态检查、同步、修复和验证。
4. 使用 `--json` 输出给 AI 或自动化流程继续处理。
## 安装{#install}
SuccApp CLI 可以使用 npm 全局安装，安装后本机可直接执行 `succapp` 命令：
```bash
npm install -g @succsoft/succapp
```
安装后先检查版本和帮助：
```bash
succapp --version
succapp --help
```
### 版本检查和升级提示{#version-check}
开始使用前，先执行：
```bash
succapp --version
```
这条命令会输出本机 CLI 版本，并在能识别当前服务器时按服务器版本推荐配套 CLI；识别不到服务器时，才按 npm 最新版本判断。看到升级提示时，直接执行提示中的 `npm install -g ...` 命令即可。
AI Agent 或脚本可以按下面方式判断：
| 情况 | 处理方式 |
| --- | --- |
| 提示已是最新版 | 继续执行后续命令。 |
| 提示升级到某个版本或 tag | 先执行提示里的安装命令，再重新运行当前任务。 |
| 提示找不到适配当前服务器的 CLI | 不要直接升级到 npm `latest`，先确认服务器是否也需要升级。 |
| 服务器返回客户端不兼容错误 | 按 CLI 输出的升级或降级建议处理。 |
版本检查不会改变命令结果。使用 `--json` 时，业务结果仍写到 stdout，升级提醒写到 stderr，AI Agent 可以继续稳定解析 stdout。需要在 CI、离线环境或受控终端中关闭检查时，可以设置：
```bash
SUCCAPP_NO_UPDATE_CHECK=1 succapp --version
```
## CLI 运行须知{#concepts}
SuccApp CLI 每次执行都是一个短进程。它先解析命令，确定本次运行要访问的工作区、服务器和认证信息，再通过 SuccApp Dev Tool v2 接口访问服务器，最后把结果输出给人或 AI Agent。
```text
succapp 命令
-> 判断命令类别和运行模式
-> 定位 workspace 和 server URL
-> 读取本机认证信息
-> 调用 SuccApp Dev Tool v2 接口
-> 输出终端文本或 JSON 结果
```
### 命令分类{#domains}
CLI 命令按能力域分组。日常使用时，先判断任务属于哪一类，再进入对应命令域查看 `--help`。
| 命令域 | 功能概述 |
| --- | --- |
| `workspace` | 面向本地 SuccApp 工作区，负责初始化、项目克隆、状态检查、拉取、推送、放弃修改、diff、文件历史和工作区修复。 |
| `server` | 直接访问 SuccApp 服务器，负责服务器连通性、项目、文件、历史、页面地址、脚本和缓存等操作。 |
| `auth` | 管理本机保存的服务器认证状态，负责登录、查看登录状态和退出登录。 |
| `db` | 通过 SuccApp 服务器访问数据源，负责查看数据源、schema、表结构，执行查询和受控数据操作。 |
| `model` | 通过 SuccApp 语义模型访问 `.tbl` 数据模型，负责查看模型摘要、字段、索引，并按模型表达式或 Query DSL 查询模型数据。 |
完整命令、参数和示例以 `succapp --help` 及各命令域的 `--help` 输出为准，手册只介绍使用思路和选择方式。
### 参数输入和输出约定{#input-output}
SuccApp CLI 的参数校验尽量在真正访问服务器前完成。缺少必要参数、传入空值、数字参数不合法，或同一类输入给了多个来源时，命令会先停止并提示用法错误。
常见输入来源有几类：
| 输入来源 | 说明 | 示例 |
| --- | --- | --- |
| 位置参数 | 直接跟在命令后面，适合短路径、模型名、表名或短 SQL。 | `succapp model show ` |
| 选项值 | 通过 `--name=value` 或 `--name value` 传入，适合过滤、排序、行数和短文本。 | `succapp model select --max-rows=20` |
| 文件 | 通过 `--file`、`--query-file` 等选项从本地文件读取内容。 | `succapp model query --query-file=./query.json` |
| 标准输入 | 通过管道把内容传给命令，适合 AI Agent 或脚本临时生成的 SQL、JSON 或 token。 | `cat query.json | succapp model query --stdin` |
同一类业务输入通常只能选择一个来源。例如 `db query` 的 SQL 可以来自 ``、`--file` 或管道 stdin；`model query` 的 Query DSL 可以来自 `--query`、`--query-file` 或 `--stdin`。不要同时传多个来源。
导出类命令还有两个固定约定：
1. `db export` 和 `model export` 必须指定 `--output`，导出结果写入本地文件，不把完整数据写到 stdout。
2. 输出文件已存在时，命令会停止并要求确认；确认覆盖时显式加 `--force`。
### 两种运行模式{#run-modes}
SuccApp CLI 有两种大的运行模式：基于本地工作区运行，或者临时直连服务器运行。
| 运行模式 | 说明 | 适合场景 |
| --- | --- | --- |
| 本地工作区模式 | CLI 在一个 [SuccApp 工作区](./workspace.md) 中运行，基于本地文件、同步基线和服务器状态完成检查、拉取和推送。 | 完整低代码应用开发、AI 修改元数据、工作区版本管理、多人协作和需要可审计 diff 的改动。 |
| 即时远程模式 | CLI 不依赖本地 workspace，直接根据 server URL 访问服务器。 | 临时查询、只读排查、查看服务器文件或历史、生产环境只读检查，以及测试服务器上的小范围确认。 |
简单判断方式是：只要任务会产生需要保留、评审、回退或发布的修改，就优先使用本地工作区模式；如果只是临时读取服务器信息，可以使用即时远程模式。
### Workspace{#workspace}
CLI 的 `workspace` 命令域以 [SuccApp 工作区](./workspace.md) 为运行边界。工作区结构、mirror、AI 协作文件和 Git 协作约定由工作区页统一说明；这里主要说明 CLI 的使用方式。
只要任务会产生需要保留、评审、回退或发布的修改，就优先在工作区中执行 CLI 命令。临时只读查询或小范围排查，可以使用即时远程模式。
典型起步方式是先初始化工作区，再从服务器克隆项目：
```bash
succapp auth login
succapp workspace init --server
succapp workspace project clone
```
进入工作区后，`workspace status`、`workspace file diff`、`workspace file compile`、`workspace pull`、`workspace discard`、`workspace push` 等命令会围绕本地文件和服务器基线工作。如果终端不在工作区目录，也可以显式指定 workspace 目录执行命令。
修改仪表板、报表、页面、模型等元数据后，可以把本地文件内容发送到当前服务器做一次编译校验：
```bash
succapp workspace file compile path/to/file.dash
succapp workspace file compile path/to/file.dash --json
```
该命令只校验本地内容，不保存文件，也不修改服务器内容。校验失败时，CLI 会返回服务器编译得到的错误信息，适合 AI Agent 和脚本在推送前发现表达式、组件配置或模型结构错误。
### Server URL{#server}
`server URL` 是 SuccApp 服务器地址，例如 `http://localhost:8080`，也可以是团队提供的测试服务器或生产服务器地址。CLI 要访问服务器时，必须先确定本次命令的 server URL。
CLI 获取 server URL 的来源按优先级可以理解为：
| 来源 | 说明 |
| --- | --- |
| 命令中的服务器位置参数 | 适合即时远程模式，例如直接对某个服务器执行 `server ping` 或查看服务器文件。 |
| 全局 `--server` | 适合本次命令显式指定服务器，通常不写入当前工作区配置；例外是已初始化但还没有活跃服务器的工作区执行 `succapp workspace project clone --server ` 时，CLI 会把该服务器添加为活跃服务器后再克隆项目。 |
| workspace 活跃服务器 | 在本地工作区模式下最常见，workspace 命令默认使用当前工作区配置的活跃服务器。 |
| `SUCCAPP_SERVER` 环境变量 | 适合脚本或 CI 环境提供默认服务器地址。 |
需要快速确认服务器状态时，可以执行：
```bash
succapp server info
```
命令会输出产品版本、Dev Tool API 版本，以及服务端返回的各类元数据文件最新版本。默认只展示 `product` 和 `metadata` 范围。需要查看 `sys`、`jvm`、`env` 等更多明细时，可以使用 `--scope` 指定范围：
```bash
succapp server info --scope jvm
succapp server info --scope=env,jvm
succapp server info --scope=all
```
`--scope` 可以重复使用，也可以用逗号传入多个范围；`--scope=all` 与 `--all` 都表示展示全部范围。
脚本或 AI Agent 需要读取这些信息时，使用 `--json`。其中元数据版本在 `info.metadataVersions` 中；需要保留服务端详细信息原始结构时，使用 `--raw --json`。
如果 CLI 无法从这些来源得到 server URL，而命令又必须访问服务器，就会停止执行并提示缺少服务器信息。
### 认证{#auth}
除少量连通性检查外，访问服务器项目、文件、同步和数据库能力通常都需要认证。SuccApp CLI 的认证以 server URL 为索引保存：登录时先验证凭证，验证成功后把对应服务器的认证信息保存到本机；后续命令访问同一个服务器时，会自动读取这份本机认证信息。
默认登录方式是 OAuth2 浏览器授权：
```bash
succapp auth login
```
执行后，CLI 会打开浏览器进入 SuccApp 授权页。授权完成后，CLI 保存本机认证状态，并在后续命令中自动刷新 OAuth2 access token。
脚本、CI、远程终端或无浏览器环境可以显式使用 PAT：
```bash
succapp auth login --pat
```
交互终端会提示输入 PAT，也可以从标准输入传入：
```bash
printf "%s" "$PAT" | succapp auth login --pat
```
登录成功后，CLI 会保存可用于访问服务器的 Bearer token，并在后续命令中自动带上认证信息。由于认证信息按服务器地址匹配，服务器地址变更、测试和生产环境切换、或使用不同域名访问同一服务器时，可能需要重新认证或确认当前命令使用的 server URL。
PAT、OAuth2 access token 和 refresh token 只应保存在本机认证状态或受控密钥环境中，不应写入 Git 仓库、项目脚本、文档或日志。认证方式和本机文件结构见[认证配置](../workspace/configure-auth.md)。
## 模型数据查询{#model}
`db` 命令面向数据库和物理表，`model` 命令面向 SuccApp 语义模型。需要了解数据源、schema 或物理表结构时使用 `succapp db`；需要按 `.tbl` 模型查看字段、维键、度量、索引或执行模型查询时使用 `succapp model`。
常用只读命令包括：
```bash
succapp model list --limit 20
succapp model show /Demo/data/tables/APP/Customer.tbl
succapp model fields /Demo/data/tables/APP/Customer.tbl --dim
succapp model indexes /Demo/data/tables/APP/Customer.tbl
succapp model select /Demo/data/tables/APP/Customer.tbl --where "STATUS='ACTIVE'" --max-rows 20
succapp model query --query-file ./query.json --json
```
`model select` 适合对单个 `.tbl` 做快速查询，`--where` 使用 SuccApp 表达式语法。`model query` 适合执行 SuccApp Query DSL，请直接传入 `succ.meta.dw.Query` JSON 对象，返回行数上限等查询选项写入 `options`。查询生产环境或敏感数据时，应限制返回行数，并优先使用 `--json` 交给 AI Agent 继续分析。
## 安全边界{#ai}
使用 SuccApp CLI 时，建议遵守以下边界：
1. 写操作前先执行只读命令，例如 `status`、`file diff`、`server file info`、`db table describe`。
2. 生产服务器上默认只做只读排查；需要写入时必须等待人工确认和发布流程。
3. `workspace discard --force`、`workspace push`、`server file update`、`server file remove`、`db exec`、数据源修改和删除都属于高风险操作。
4. 使用 `--force` 前必须明确影响范围和回退方式。
5. AI Agent 读取命令结果时优先使用 `--json`，但 CLI 结果只能证明命令执行结果，不能替代产品页面和业务流程验证。
6. PAT、OAuth2 access token 和 refresh token 只放在本机认证状态或受控密钥环境中，不写入 Git 仓库。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/vscode.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/vscode"
title: "SuccApp for VS Code"
---
---
title: SuccApp for VS Code
navTitle: SuccApp for VS Code
---
# SuccApp for VS Code
SuccApp for VS Code 是 SuccApp 的图形化开发和同步工具，适合人工浏览服务器项目、查看 Changes、打开 diff、查看文件历史、编辑脚本、推送测试环境和配合 Git 评审 AI 修改。
它主要服务人工交互场景：当 AI 已经修改本地文件后，项目成员可以在 VS Code 中确认变化是否只包含预期文件、diff 是否合理、服务器文件历史是否支持回退，以及推送测试后页面效果是否正确。
1
2
3
4
5
6
7
图中数字对应的界面区域如下：
1. 活动栏：进入 SuccApp、资源管理器、搜索、Git、扩展等 VS Code 视图。
2. 服务器视图：连接和维护服务器、浏览远端项目和文件、克隆项目。
3. 变化视图：查看本地变化、远端变化和冲突，执行推送、拉取、对比等操作。
4. 文件历史视图：查看服务器文件历史，并与历史版本或工作区文件对比。
5. 编辑与差异对比区：编辑本地文件，查看本地版本和服务器版本的差异。
6. AI 助手区：使用 AI Coding 工具辅助修改、解释和检查文件。
7. 状态栏：查看当前服务器、Git 分支、同步状态、文件类型和光标位置等信息。
## 安装{#install}
在线安装时，打开 VS Code 扩展视图，搜索 `SuccApp`，点击安装。安装完成后，活动栏中会出现 SuccApp 图标。
离线环境可以使用 `.vsix` 安装包：
```bash
code --install-extension succapp-for-vscode-版本号.vsix
```
升级离线版本时，先确认 `.vsix` 的版本号和目标服务器版本兼容。升级后重新打开工作区，并检查服务器连接、项目树和同步状态。
## 服务器视图{#servers-view}
服务器视图用于管理当前工作区配置的服务器，并浏览服务器上的项目和文件。
### 顶部按钮{#servers-toolbar}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 添加服务器 | Add Server | 添加服务器地址并登录。 |
| 刷新服务器 | Refresh Servers | 刷新服务器列表和远端项目状态。 |
### 服务器节点菜单{#server-menu}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 连接服务器 | Connect Server | 使用已保存认证状态连接服务器。 |
| 断开服务器连接 | Disconnect Server | 断开当前服务器连接。 |
| 登录服务器 | Login Server | 重新选择 OAuth2 授权或 PAT 登录。 |
| 设置服务器地址 | Set Server URL | 替换服务器地址并迁移本地服务器基线。 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置。 |
### 项目节点菜单{#project-menu}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 克隆项目 | Clone Project | 将服务器项目下载到本地工作区。 |
| 从服务器重置本地项目 | Reset Local Project from Server | 用服务器当前内容重建已克隆项目，可能覆盖或删除本地文件。 |
### 远端文件菜单{#remote-file-menu}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 打开服务器源码 | Open Server Source | 在 VS Code 中以只读方式打开服务器当前内容。 |
| 查看服务器文件历史 | Show Server File History | 在文件历史视图中查看该文件的历史版本。 |
| 复制元数据路径 | Copy Metadata Path | 复制服务器元数据路径。 |
| 复制元数据 ID | Copy Metadata ID | 复制服务器资源 ID。 |
| 打开服务器视图 | Open Server Views | 在浏览器中打开该资源对应的查看页面。 |
| 打开服务器编辑页 | Open Server Edit Page | 在浏览器中打开该资源对应的编辑页面。 |
## 变化视图{#changes-view}
变化视图用于查看本地工作区、服务器基线和服务器当前内容之间的差异。
| 分组 | 英文界面 | 含义 |
| --- | --- | --- |
| 本地变化 | Local Changes | 本地工作区相对上次同步基线发生了变化，可以推送到服务器。 |
| 远端变化 | Remote Changes | 服务器相对本地基线发生了变化，可以拉取到本地。 |
冲突不是独立顶层分组。发生冲突时，同一个资源可能同时出现在本地变化和远端变化中，并带有冲突标记。
### 顶部按钮{#changes-toolbar}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 推送变化 | Push Changes | 批量推送当前窗口中已连接工作区的本地变化。 |
| 拉取变化 | Pull Changes | 批量拉取当前窗口中已连接工作区的服务器变化。 |
| 刷新变化 | Refresh Changes | 刷新同步状态。 |
| 切换树/列表视图 | Toggle Tree/List View | 在目录树和列表展示之间切换。 |
| 放弃修改 | Discard Changes | 批量放弃当前窗口中的本地变化。 |
### 单个变化菜单{#change-menu}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 打开文件 | Open File | 打开变化文件或打开差异。 |
| 推送文件 | Push File | 只推送该文件的本地变化。 |
| 拉取文件 | Pull File | 只拉取该文件的服务器变化。 |
| 放弃修改 | Discard Change | 用同步基线恢复本地文件，必要时会删除本地新增文件。 |
| 采用服务器版本 | Use Server Version | 对有服务器版本的变化使用服务器版本。 |
| 恢复本地版本 | Restore Local Version | 对本地变化或冲突恢复本地版本。 |
| 与服务器版本对比 | Compare File with Server | 打开 VS Code diff。 |
## 文件历史视图{#history-view}
文件历史视图用于查看服务器上的文件历史。常用入口包括服务器视图、变化视图和本地文件菜单中的 **查看服务器文件历史**。
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 刷新文件历史 | Refresh File History | 重新加载当前文件的历史。 |
| 与上一版本对比 | Compare with Previous Version | 对比相邻两个服务器历史版本。 |
| 与工作区文件对比 | Compare with Workspace | 对比某个历史版本和当前本地文件。 |
## 本地文件菜单{#local-file-menu}
| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 与服务器版本对比 | Compare File with Server | 对比本地文件和服务器基线或服务器当前内容。 |
| 打开服务器视图 | Open Server Views | 在浏览器中打开该文件对应的服务器查看页面。 |
| 打开服务器编辑页 | Open Server Edit Page | 在浏览器中打开该文件对应的编辑页面。 |
| 打开服务器源码 | Open Server Source | 以只读方式查看服务器当前源码。 |
| 查看服务器文件历史 | Show Server File History | 查看服务器文件历史。 |
| 复制 Meta 路径 | Copy Meta Path | 复制该本地文件对应的服务器路径。 |
| 复制 Meta ID | Copy Meta ID | 复制 `.meta` 中记录的资源 ID。 |
## 命令面板命令{#commands}
可以通过 VS Code 命令面板执行 SuccApp 命令。
| 中文界面命令 | 英文界面命令 | 说明 |
| --- | --- | --- |
| SuccApp: 添加服务器 | SuccApp: Add Server | 添加服务器并登录。 |
| SuccApp: 使用服务器 | SuccApp: Use Server | 切换当前工作区活跃服务器。 |
| SuccApp: 登录服务器 | SuccApp: Login Server | 登录当前服务器，认证失效时可重新认证。 |
| SuccApp: 断开服务器连接 | SuccApp: Disconnect Server | 断开当前服务器连接。 |
| SuccApp: 移除服务器 | SuccApp: Remove Server | 从当前工作区移除服务器配置，不删除服务器项目。 |
| SuccApp: 设置服务器地址 | SuccApp: Set Server URL | 设置服务器地址并迁移 `.succapp/remote/` 下的本地基线。 |
| SuccApp: 打开服务器配置 | SuccApp: Open Server Config | 打开当前工作区的 `.succapp/config.json`。 |
| SuccApp: 克隆项目 | SuccApp: Clone Project | 从服务器克隆项目。 |
| SuccApp: 移除本地项目 | SuccApp: Remove Local Project | 移除本地项目和本地 mirror。 |
| SuccApp: 拉取变化 | SuccApp: Pull Changes | 拉取服务器变化。 |
| SuccApp: 推送变化 | SuccApp: Push Changes | 推送本地变化。 |
| SuccApp: 推送当前文件 | SuccApp: Push Current File | 推送当前编辑器文件。 |
| SuccApp: 升级文件 | SuccApp: Upgrade File | 将当前文件、指定文件或文件夹下支持的元数据升级到当前服务器内容版本。 |
| SuccApp: 刷新变化 | SuccApp: Refresh Changes | 刷新同步状态。 |
| SuccApp: 修复工作区 | SuccApp: Repair Workspace | 先检查工作区、本地同步基线和同步状态，再修复可自动处理的问题。 |
| SuccApp: 开启自动推送 | SuccApp: Enable Auto Push | 保存后自动推送。 |
| SuccApp: 关闭自动推送 | SuccApp: Disable Auto Push | 关闭保存后自动推送。 |
| SuccApp: 与服务器版本对比 | SuccApp: Compare File with Server | 打开差异对比。 |
| SuccApp: 配置同步忽略规则 | SuccApp: Configure Sync Ignore Rules | 打开同步忽略配置。 |
| SuccApp: 初始化工作区 | SuccApp: Initialize Workspace | 创建或刷新 `.succapp/config.json`、推荐设置、AI 协作目录、TypeScript 类型声明和编辑器结构提示文件。 |
| SuccApp: 从模板新建扩展 | SuccApp: Create Extension from Template | 从服务器模板创建扩展目录。 |
| SuccApp: 推送扩展 | SuccApp: Push Extension | 把扩展目录推送到当前服务器。 |
| SuccApp: 查看日志 | SuccApp: Show Logs | 打开 SuccApp 日志面板。 |
## 快捷键{#keybindings}
| 快捷键 | macOS | 说明 |
| --- | --- | --- |
| `Ctrl+Shift+Down` | `Command+Shift+Down` | 拉取。 |
| `Ctrl+Shift+Up` | `Command+Shift+Up` | 推送。 |
| `Ctrl+Alt+Up` | `Command+Alt+Up` | 推送当前文件。 |
| `Ctrl+Alt+D` | `Command+Alt+D` | 与服务器版本对比。 |
## 设置项{#settings}
SuccApp 设置项可以在 VS Code 设置中搜索 `succapp` 查看。
| 设置项 | 默认值 | 说明 |
| --- | --- | --- |
| `succapp.sync.autoPush` | `false` | 保存文件后自动推送到服务器。 |
| `succapp.sync.autoPushDelay` | `2000` | 自动推送延迟，单位毫秒。 |
| `succapp.sync.autoPull` | `false` | 是否定时自动拉取服务器变化。 |
| `succapp.sync.autoPullInterval` | `60` | 自动拉取间隔，单位秒。 |
| `succapp.sync.ignore` | `["**/node_modules/**", "**/*.log"]` | 同步时忽略的文件匹配模式。 |
| `succapp.sync.maxPushFileSize` | `10Mb` | 单个文件允许推送的最大大小。 |
::: warning 注意
自动推送适合测试环境中的快速调试，不建议在生产环境中开启。自动拉取可能修改本地文件，多人协作时也应谨慎开启。
:::
## 与 AI 协同{#ai}
AI 修改文件后，项目成员应在 SuccApp for VS Code 中检查：
1. Changes 视图是否只包含预期文件。
2. diff 是否存在误删、无关格式化或风险配置。
3. `.meta` 变化是否符合资源操作。
4. 推送测试环境后，浏览器页面或设计器效果是否正确。
5. Git diff 是否适合提交和评审。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/mcp.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/mcp"
title: "MCP"
---
---
title: MCP
navTitle: MCP
---
# MCP
SuccApp MCP 是服务端提供给 AI 客户端的工具协议入口。支持 MCP 的 AI 客户端连接 SuccApp 服务器后，可以通过标准的工具发现和工具调用方式读取系统信息、访问元数据和查询数据库。
MCP 适合让 AI 直接理解服务器现状；如果任务需要本地文件修改、Git 管理、diff 评审和发布流程，仍应使用 SuccApp 工作区，并配合 [SuccApp CLI](./cli.md) 和 [SuccApp for VS Code](./vscode.md)。
## 接入方式{#connection}
当前 SuccApp MCP 入口是服务器上的 HTTP JSON-RPC 接口 `/api/mcp`。客户端应使用 `POST` 请求提交 JSON-RPC 消息；当前不提供 `GET`、SSE 或事件流入口。
MCP 调用需要使用当前 SuccApp 服务器支持的认证方式，例如已登录会话或可访问该服务器的 Bearer token。客户端还应携带 MCP 协议要求的 `Accept` 和协议版本请求头；缺少必要请求头或认证失败时，服务端会返回结构化错误。
## 能力范围{#capabilities}
MCP 能力按领域组织：
| 领域 | 能力 |
| --- | --- |
| 系统和项目 | 读取 SuccApp 系统信息，列出服务器项目。 |
| 元数据文件 | 列出、搜索、读取元数据文件；在权限允许时保存、移动、删除文件。 |
| 设置 | 读取和更新系统、项目或应用相关设置。 |
| 数据库 | 列出数据源只读摘要、schema、表摘要，执行只读查询；在权限允许并确认风险后执行受控 SQL。 |
MCP 返回结构化结果，适合 AI 客户端继续分析和生成后续调用。`tools/list` 固定返回当前版本支持的全部工具，不按当前账号权限裁剪；具体权限、资源是否可访问、危险操作是否已确认，都在 `tools/call` 时返回结构化错误。
当前工具清单包括：
| 工具 | 用途 |
| :--- | :--- |
| `succapp_system_info` | 读取服务器版本、时间和元数据内容版本。 |
| `succapp_project_list` | 列出当前账号可读取的元数据项目。 |
| `succapp_settings_get` | 读取系统、项目或应用设置。 |
| `succapp_settings_set` | 更新系统、项目或应用设置。 |
| `succapp_file_list` | 列出目录下的元数据文件。 |
| `succapp_file_search` | 按路径、名称和文件类型搜索元数据文件。 |
| `succapp_file_read` | 读取文件摘要，并可按需返回文本内容。 |
| `succapp_file_save` | 保存文件或目录；传 `createIfMissing` 可创建不存在的目标。 |
| `succapp_file_delete` | 删除文件或目录。 |
| `succapp_file_move` | 移动或重命名文件。 |
| `succapp_db_list_datasources` | 列出可见数据源的只读摘要和数据库版本信息。 |
| `succapp_db_list_schemas` | 列出数据源下可见的 schema 或 catalog。 |
| `succapp_db_list_tables` | 列出表和视图摘要。 |
| `succapp_db_execute_query` | 执行只读 SQL 查询。 |
| `succapp_db_execute_any` | 执行 SQL 语句；危险 SQL 需要显式确认。 |
## 适合使用 MCP 的场景{#scenarios}
1. AI 需要快速了解服务器版本、项目列表和元数据文件。
2. AI 需要搜索或读取服务器上的元数据，但暂时不需要克隆到本地工作区。
3. AI 需要查看数据源方言信息、表摘要或执行限制行数的只读查询。
4. 团队希望把 SuccApp 服务器能力接入已有 AI 客户端，而不是让 AI 只依赖终端命令。
## 文件读取和写入{#files}
`succapp_file_read` 合并了文件信息和文件内容读取。默认只返回 `path`、`revision`、`modifyTime`、`mimeType`、`byteLength` 和轻量 `fileInfo`，不会把正文放入上下文。需要正文时，调用方传入：
```json
{
"path": "/demo/data/USERS.tbl",
"includeContent": true,
"maxContentBytes": 65536
}
```
返回结果中的 `contentReturned` 表示本次响应是否包含正文。未请求正文、二进制文件或无法返回正文时，工具会通过 `contentOmittedReason` 说明原因；文本内容超过 `maxContentBytes` 时，会返回截断后的正文并设置 `contentTruncated`。这些情况不代表读取失败。文件不存在、无权限等情况仍会作为 tool error 返回。
`succapp_file_save` 是唯一的文件写入口。写入结果只返回 `ok`、`path`、`revision`、`modifyTime`、`created`、`contentChanged`、`metaInfoChanged` 等轻量字段，不再回传完整文件对象。
## 数据库摘要{#database}
`succapp_db_list_datasources` 只返回 AI 生成 SQL 所需的只读摘要，例如数据源名称、连接器类型、数据库产品版本、只读标记等。它不会返回连接串、主机、用户名、密码或 JDBC 参数，也不会把列表调用变成隐式连接测试。
需要了解表时，先使用 `succapp_db_list_tables` 获取 `schema`、`tableName`、`tableType`、`comment` 等摘要。需要字段细节时，可在权限允许的前提下使用 `succapp_db_execute_query` 执行受限查询。
## 与 CLI 和 VS Code 的区别{#difference}
MCP 直接访问 SuccApp 服务器，强调 AI 客户端和服务器能力之间的连接。SuccApp CLI 强调终端、脚本化和本地工作区自动化；SuccApp for VS Code 强调人工浏览、编辑、diff、Changes 和文件历史。
需要可审计修改时，不建议只依赖 MCP 直接改服务器文件。更稳妥的流程是：在工作区中修改本地文件，通过 CLI 或 VS Code 检查差异，推送测试环境验证，再按团队流程提交 Git 和发布生产。
## 权限和安全边界{#safety}
MCP 调用受当前账号权限限制。涉及写服务器文件、更新设置、执行 SQL、删除资源或覆盖已有内容时，应先说明服务器地址、目标对象、影响范围和回退方式，并等待人工确认。
生产环境上默认只使用只读能力。涉及生产写入、强制覆盖、删除或危险 SQL 时，按[安全边界](./safety.md)执行。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/safety.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/safety"
title: "安全边界"
---
---
title: 安全边界
navTitle: 安全边界
---
# 安全边界
AI 可以提高低代码开发效率，但不能替代人工确认业务影响。凡是会写服务器、改生产、覆盖远端、删除资源、执行 SQL 或影响权限流程的操作，都应设置明确确认边界。
## 高风险操作{#high-risk}
以下操作必须先说明影响范围，并由项目成员或负责人确认：
1. 推送生产服务器。
2. 强制覆盖服务器变化。
3. 删除项目、目录、大量文件或目录级 `.meta` 信息。
4. 修改权限、流程、数据范围、系统设置、数据源和账号相关配置。
5. 执行 `db exec`、导入数据、删除数据、修改表结构。
6. 使用 `server file update --force`、`server file remove --force` 等强制服务器写操作。
7. 重置本地项目或放弃大量本地修改。
## 按入口确认{#tool-boundaries}
不同入口的高风险操作名称不同，但确认原则一致：先说明服务器地址、目标项目、文件路径或 SQL、预期影响和回退方式，再由项目成员确认。
| 入口 | 需要确认的操作 |
| --- | --- |
| SuccApp CLI | `workspace push` 到生产服务器、`workspace discard --force`、`workspace project remove --force`、`server file update/remove --force`、`db exec`、`db import`、数据源创建、修改或删除。 |
| SuccApp for VS Code | 推送生产服务器、强制覆盖服务器变化、从服务器重置本地项目、放弃大量修改、切换服务器后立即推送、在生产环境开启自动推送或自动拉取。 |
| MCP | 写服务器文件、更新设置、移动或删除元数据、执行临时脚本、执行危险 SQL、修改数据源、带 `force` 重试被服务端拦截的高风险操作。 |
## AI 修改前确认{#before}
允许 AI 修改前，先确认：
1. 当前连接的是测试环境。
2. Git 工作区和 SuccApp Changes 没有未说明的历史变化。
3. 已明确允许修改的项目、目录、文件和业务范围。
4. 已明确不允许修改的资源，例如权限、流程、生产配置和数据源。
5. 本次修改可以在测试环境复现和验证。
## AI 修改后确认{#after}
AI 修改完成后，至少检查：
1. SuccApp Changes 中只出现预期文件。
2. Git diff 中没有无关格式化、临时文件和运行时文件。
3. 目录级 `.meta`、引用路径、字段名、组件 ID 和数据集 ID 没有被误改。
4. 元数据静态检查或编辑器诊断没有明显结构错误。
5. 产品设计器、页面预览、脚本日志或业务流程验证通过。
6. 需要评审的修改已经提交 Git 并说明业务目的。
## 生产环境原则{#prod}
生产环境只接收已评审、已验证、可回退的版本。AI 不应在没有人工确认的情况下直接推送生产。
发布生产前应确认：
1. Git 版本正确。
2. 测试环境验证通过。
3. 团队评审通过。
4. SuccApp diff 只包含本次发布内容。
5. 无未处理远端变化和冲突。
6. 已准备回退方案。
完整流程见[发布到生产环境](../release/release-to-prod.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/basics/succapp-vs-browser.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/basics/succapp-vs-browser"
title: "SuccApp 和浏览器实施有什么区别"
---
---
title: SuccApp 和浏览器实施有什么区别
navTitle: SuccApp 和浏览器实施的区别
---
# 使用 SuccApp 比直接在浏览器上进行项目实施有何区别和优势
直接在浏览器上实施，适合少量配置和即时调整。SuccApp 更适合项目化交付：多人协作、批量修改、版本留痕、测试到生产同步和 AI 辅助修改。
## 主要区别{#difference}
| 维度 | 浏览器实施 | SuccApp 实施 |
| :--- | :--- | :--- |
| 修改方式 | 在设计器或管理界面中逐项修改 | 在本地工作区中编辑元数据文件 |
| 差异检查 | 依赖人工记忆和界面检查 | 可通过 Changes 视图和 diff 查看差异 |
| 版本历史 | 依赖服务器历史或人工记录 | 可提交到 Git，形成团队版本历史 |
| 多人协作 | 容易互相覆盖 | 可结合 Git、pull、push 和冲突处理协作 |
| 批量修改 | 操作成本较高 | 可用编辑器、搜索替换和 AI 辅助处理 |
| 生产发布 | 容易变成现场手工操作 | 可按 Git 版本和生产差异发布 |
## 什么时候适合用 SuccApp{#when-use}
建议使用 SuccApp 的场景：
1. 项目需要多人协作。
2. 修改需要经过评审和版本记录。
3. 需要从测试环境整理变更后发布到生产环境。
4. 需要批量修改页面、脚本、模型或其他元数据。
5. 需要借助 AI 理解、查找或修改元数据。
6. 需要在发布前确认真实文件差异。
## 什么时候可以继续用浏览器{#when-browser}
以下场景可以继续直接在浏览器中操作：
1. 少量临时查看或验证。
2. 只需要使用设计器完成简单配置。
3. 不涉及团队协作和生产发布。
4. 当前功能只能通过产品界面完成。
## 推荐做法{#recommended}
正式项目中，建议把浏览器和 SuccApp 结合使用：
1. 在 SuccApp 中管理元数据、差异、同步和 Git 版本。
2. 在浏览器中预览页面、检查设计器效果和完成业务验证。
3. 测试环境中小步推送、小步验证。
4. 生产发布前以 Git 版本和 SuccApp 差异为准。
更多流程请阅读[快速开始](../quick-start.md)和[修改、对比、拉取与推送](../workspace/sync-changes.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace"
title: "准备工作区"
---
---
title: 准备工作区
description: 组织 AI 低代码开发中的工作区初始化、认证、AI 上下文、Git、服务器连接、项目克隆和同步变化任务。
navTitle: 准备工作区
indexTitle: 概述
---
# 准备工作区
准备工作区用于建立 AI 修改 SuccApp 元数据所需的本地环境。进入具体开发任务前，先确保工作区、认证、AI 上下文、Git 和服务器同步链路都已准备好。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要初始化本地 SuccApp 工作区。
- 需要配置服务器地址、账号认证或自动登录。
- 需要让 AI 了解项目规则、提示词和协作要求。
- 需要连接服务器、克隆项目、查看本地变化、拉取或推送。
- 需要把 AI 修改纳入 Git 版本管理。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 初始化工作区 | [初始化工作区](./init-workspace.md) | 第一次准备本地目录、项目配置和推荐设置。 |
| 工作区版本管理 | [工作区版本管理](./git-versioning.md) | 需要用 Git 记录、审查、提交或回退 AI 修改。 |
| 认证配置 | [认证配置](./configure-auth.md) | 需要配置服务器登录、访问令牌或认证文件。 |
| AI 提示词设置 | [AI 提示词设置](./configure-ai-context.md) | 需要让 AI 读取项目规则、边界、示例和协作要求。 |
| 连接服务器 | [连接服务器](./connect-and-clone.md) | 需要连接 SuccApp 服务器、浏览远端项目或克隆项目。 |
| 修改与同步 | [修改与同步](./sync-changes.md) | 需要查看变化、拉取远端更新、推送本地修改或处理同步流程。 |
## 相关阅读
- [了解基础概念和工具](../basics/README.md)：先理解工作区、SuccApp CLI、SuccApp for VS Code 和 MCP 的分工。
- [质量检查](../quality/README.md)：修改完成后检查 diff、引用、预览和产品效果。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/init-workspace.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/init-workspace"
title: "初始化工作区"
---
---
title: 初始化工作区
navTitle: 初始化工作区
---
# 初始化工作区
SuccApp 工作区是本地目录，也是 AI、SuccApp CLI、SuccApp for VS Code 和 Git 协作的边界。初始化工作区的目标，是让本地目录具备连接服务器、克隆项目、读取 AI 规则、检查差异、编辑脚本和提交 Git 的基础条件。
AI 低代码开发应从工作区开始，而不是从单个文件开始。工作区中包含项目元数据、目录级 `.meta`、服务器配置、类型声明、编辑器辅助配置、Git 忽略规则和 AI 协作文件，决定了 AI 能否准确理解和安全修改项目。
## 理解工作区{#workspace}
可以把一个 SuccApp 工作区理解为一个 VS Code 项目。一个工作区通常只维护同一套元数据内容对应的服务器，例如同一个客户项目的测试环境和生产环境。
这里的“同一套元数据内容对应的服务器”，不是指服务器地址必须只有一个，而是指这些服务器之间的项目、资源和元数据内容本来就属于同一套交付或同一套业务系统。
不建议把两个无关服务器直接放在同一个工作区中混合管理。如果确实需要在两个无关服务器之间做内容交互，例如一次性的升级或迁移，可以分别把 A、B 两个服务器初始化到两个工作区，再在本地从一个工作区复制需要的文件到另一个工作区，检查后再同步到目标服务器。
## 选择初始化路径{#choose-path}
初始化工作区有两种常见路径：从服务器开始创建工作区，或者从团队 Git 仓库开始恢复工作区。AI Agent 和脚本化流程建议优先使用 SuccApp CLI；人工操作也可以使用 CLI，只有需要图形化选择服务器、查看项目树或检查 Changes 时再打开 SuccApp for VS Code。
正式项目建议从一开始就启用 Git。Git 用于记录本地元数据文件的历史，SuccApp 用于连接服务器和同步元数据，两者解决的问题不同。推荐入库内容、忽略规则和提交流程见[工作区版本管理](./git-versioning.md)。
## 从服务器开始{#init-from-server}
适合团队还没有 Git 仓库，或者需要从某个 SuccApp 服务器拉出初始项目内容的场景。
```bash
mkdir sales-ops-workspace
cd sales-ops-workspace
git init
succapp auth login
succapp workspace init --server
succapp workspace project clone SALES_OPS
git status
```
这组命令会创建本地目录，初始化 Git，登录测试服务器，写入工作区配置，克隆 `SALES_OPS` 项目，并生成本地同步基线。克隆完成后，确认项目目录和目录级 `.meta` 已出现，再提交项目目录、目录级 `.meta` 和团队需要共享的配置。
如果服务器上还没有项目，需要先在浏览器项目管理页面创建项目，或由有权限的用户执行 `succapp server project create `。创建项目后，再克隆到工作区。
人工使用 SuccApp for VS Code 时，可以在命令面板中依次执行 **SuccApp: 初始化工作区**、**SuccApp: 添加服务器** 和 **SuccApp: 克隆项目**。
## 从 Git 仓库开始{#init-from-git}
适合团队已经把工作区内容纳入 Git，或者新成员接手已有项目的场景。
```bash
git clone sales-ops-workspace
cd sales-ops-workspace
succapp auth login
succapp workspace init --server
succapp workspace status --json
```
这组命令会从 Git 取得团队已有工作区，登录测试服务器，刷新本机推荐设置和服务器配置，再输出当前工作区状态。AI Agent 可以优先读取 `workspace status --json` 结果，判断是否存在本地变化、远端变化或冲突。
从 Git 仓库开始时，不要直接用服务器克隆结果覆盖本地目录。先确认 Git 中已有的项目目录，再连接服务器并检查状态；只有确认要接受服务器版本时，再执行 `succapp workspace pull` 拉取服务器变化。
人工使用 SuccApp for VS Code 时，可以打开 Git 克隆后的目录，再执行 **SuccApp: 初始化工作区**、**SuccApp: 添加服务器** 或 **SuccApp: 使用服务器**，最后在 Changes 视图中刷新和检查变化。
添加服务器、登录服务器、使用服务器、浏览远端文件、重置和移除项目等完整操作，请阅读[连接服务器与克隆项目](./connect-and-clone.md)。
## 初始化工作区与刷新推荐设置{#recommended-settings}
执行 `succapp workspace init` 或 **SuccApp: 初始化工作区** 后，SuccApp 会创建或检查 `.succapp/config.json`，并补齐推荐工作区设置、AI 协作入口、TypeScript 诊断配置、编辑器结构提示配置和 Git 忽略规则。
这个命令不要求已经连接服务器。没有服务器连接时，会先完成本地工作区初始化；需要从服务器下载的类型声明、编辑器结构提示和前端运行时依赖清单，会在后续连接服务器、添加服务器或克隆项目时刷新。显式传入 `--server ` 时，SuccApp CLI 会先检查这台服务器的登录状态；如果尚未登录，需要先执行 `succapp auth login `。服务器版本升级后，也可以再次执行 `succapp workspace init --server ` 或 **SuccApp: 初始化工作区**（英文界面为 **SuccApp: Initialize Workspace**）刷新推荐设置。
初始化工作区后，可以获得这些效果：
1. 将 `.tbl`、`.query`、`.dash`、`.rpt`、`.meta` 等常见 SuccApp 元数据文件识别为 JSON，便于使用 VS Code 的语法高亮、格式化和结构检查。
2. 启用 SuccApp 文件图标主题，在资源管理器中更容易区分不同类型的元数据文件。
3. 隐藏 `.succapp/remote/`、缓存、锁、日志和合并备份等运行时文件，减少日常编辑时的干扰。
4. 生成或更新 `tsconfig.json`、`.succapp/tsconfig.action.json`、`.succapp/tsconfig.browser.json`，让 VS Code TypeScript Server 能为服务端脚本和浏览器脚本提供语法诊断。
5. 在工作区存在业务 TypeScript 脚本且服务器支持时，从服务器下载并还原 `.d.ts` 类型声明到 `.succapp/succ-types/`，为脚本编辑提供类型提示和 API 补全。
6. 从当前连接服务器下载编辑器结构提示文件，并更新 `.vscode/settings.json`，为 `.dash`、`.spg`、`.rpt`、`.fapp`、`.tbl`、`.query`、`.kdb`、`.wfl`、`.afl`、`.agent`、`.theme`、`.tpg`、`.meta`、`.jdbc`、`settings.json`、`capabilities.json` 和扩展 `package.json` 等文件提供结构提示。
7. 写入推荐的 Git 忽略和 SuccApp 同步忽略配置，避免本地运行时文件进入 Git，并避免 IDE 辅助文件同步回元数据服务器。
8. 初始化常用 AI 开发工具可识别的入口文件，并在 `.agents/` 下创建计划、评审、报告、临时文件和团队规则目录。官方离线文档同步成功后，SuccApp 会写入 `.agents/skills/succapp-docs/`，并把前端运行时内置依赖清单作为文档 skill 的资源下载到本地，供 AI 辅助编写 FTL、浏览器脚本和 CSS 时参考。
SuccApp 会尽量保留团队已有的工作区配置：根 `tsconfig.json` 只追加缺失的项目引用，`.vscode/settings.json` 只补齐缺失的推荐项。`.succapp` 下由 SuccApp 生成的辅助配置会在初始化工作区时刷新。
## 工作区文件说明{#workspace-files}
SuccApp 工作区中常见文件如下：
```text
workspace/
├── AGENTS.md # Codex 等 AI 工具可读取的工作区说明
├── CLAUDE.md # Claude Code 入口，默认引用 AGENTS.md
├── .github/
│ └── copilot-instructions.md # GitHub Copilot 仓库级说明
├── .agents/
│ ├── README.md # AI 工作区说明
│ ├── plans/ # AI 实施计划、迁移计划
│ ├── reviews/ # AI Code Review、设计评审记录
│ ├── reports/ # AI 调查、分析、验证报告
│ ├── rules/ # 团队长期 AI 协作规则
│ ├── skills/ # 官方离线文档同步成功后写入 succapp-docs/
│ └── tmp/ # AI 临时脚本、草稿和一次性排查文件
├── .gitignore # 根目录 Git 忽略配置，SuccApp 会写入系统临时文件忽略片段
├── .succapp/
│ ├── .gitignore # SuccApp 运行时文件的 Git 忽略配置
│ ├── config.json # 当前工作区的服务器地址簿和当前活跃服务器
│ ├── remote/ # 本地服务器基线副本
│ ├── locks/ # 同步任务锁
│ ├── cache/ # 本地缓存
│ ├── json-schemas/ # 编辑器结构提示辅助文件
│ ├── merge-base/ # 拉取和合并前保存的服务器基线副本
│ ├── merge-backup/ # 拉取和合并前保存的本地文件备份
│ ├── succ-types/ # 脚本 TypeScript 诊断使用的类型声明
│ ├── succ-types.tmp-*/ # 刷新类型声明时使用的临时目录
│ ├── tsconfig.action.json # 服务端脚本 TypeScript 诊断配置
│ ├── tsconfig.browser.json # 浏览器脚本 TypeScript 诊断配置
│ ├── typescript-support.json # TypeScript 诊断支持的服务器版本记录
│ ├── *.log # 日志文件
│ └── state.json # 本地同步状态文件
├── .vscode/
│ └── settings.json # VS Code 工作区设置
├── project1/ # 从服务器克隆下来的元数据项目
│ ├── .meta # 记录 project1 下直接子资源的服务器资源标识和版本信息
│ └── index.spg
├── project2/ # 同一个工作区中可以克隆多个元数据项目
│ └── .meta # 记录 project2 下直接子资源的服务器资源标识和版本信息
└── tsconfig.json # 脚本 TypeScript 诊断配置
```
## 服务器配置文件{#server-config}
添加服务器后，当前工作区会生成 `.succapp/config.json`。该文件保存服务器地址列表和当前活跃服务器。
示例结构如下：
```json
{
"version": 2,
"servers": [
"http://localhost:8080"
],
"activeServerUrl": "http://localhost:8080"
}
```
::: warning 注意
`.succapp/config.json` 只保存服务器地址，不保存 PAT、OAuth2 access token 或 refresh token。认证状态由 SuccApp 的本机认证文件管理，不应提交到 Git 仓库。
:::
## Git 忽略建议{#gitignore}
初始化工作区后，SuccApp 会自动补齐默认 `.gitignore` 配置，避免 `.succapp/remote/`、缓存、锁、日志、本机同步状态和临时文件进入 Git。提交前仍应检查 Git 状态，确认项目目录和目录级 `.meta` 会被提交，而 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/`、`.succapp/*.log`、`.succapp/state.json` 不会进入提交。
完整入库和忽略建议见[工作区版本管理](./git-versioning.md)。
## 初始化后检查{#checklist}
初始化完成后，建议检查：
1. `succapp workspace status --json` 能正常输出当前工作区状态。
2. 本地项目目录已经出现。
3. `.succapp/remote/` 没有进入 Git 提交。
4. 目录级 `.meta` 文件没有被 Git 忽略。
5. 需要脚本提示的工作区已经生成 `tsconfig.json` 和 `.succapp/succ-types/`。
6. `AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md` 和 `.agents/` 已生成，AI 临时文件会写到 `.agents/tmp/`。
7. 当前连接的是测试服务器，而不是生产服务器。
8. 如果使用 SuccApp for VS Code，服务器视图能看到当前服务器和项目，Changes 视图可以正常刷新。
下一步可以阅读[连接服务器与克隆项目](./connect-and-clone.md)和[修改、对比、拉取与推送](./sync-changes.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/git-versioning.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/git-versioning"
title: "工作区版本管理"
---
---
title: 工作区版本管理
navTitle: 工作区版本管理
---
# 工作区版本管理
工作区版本管理指用 Git 管理 SuccApp 工作区中的项目目录、目录级 `.meta`、脚本、资源文件和团队共享配置。SuccApp 负责把 SuccApp 服务器上的元数据同步到本地工作区，Git 负责记录这些本地文件的修改历史。
正式项目中，建议将工作区纳入 Git 管理。这样 AI 或人工修改元数据后，团队可以审查差异、追踪变更、回退历史版本，并把测试通过的内容沉淀为可发布版本。本文只说明 SuccApp 工作区和 Git 配合时需要注意的内容，不介绍通用 Git 分支模型或提交规范。
## 为什么要使用 Git{#why}
使用 Git 管理工作区可以解决以下问题：
1. 知道每次 AI 或人工修改了哪些元数据文件。
2. 通过 Git diff 和 SuccApp diff 双重检查，降低误改无关文件的风险。
3. 发布生产前可以确认版本范围。
4. 出现问题时可以从历史提交中恢复文件，再通过 SuccApp 同步回测试或生产环境。
SuccApp 的 Changes 视图关注“本地和服务器之间的同步差异”，Git 关注“团队代码库中的历史版本”。这两者不是一回事，正式项目中应同时使用。
## 推荐入库内容{#include}
建议提交到 Git 的内容包括：
| 内容 | 说明 |
| :--- | :--- |
| 项目目录 | 从 SuccApp 服务器克隆下来的元数据项目，例如 `sales-ops/` |
| 目录级 `.meta` 文件 | 记录目录直接子资源的服务器资源标识、版本和描述，是同步所需信息 |
| 脚本和资源文件 | 页面脚本、数据加工脚本、图片、模板等项目真实资源 |
| 团队共享配置 | 团队约定需要共享的 VS Code 设置、TypeScript 配置、AI 规则和项目说明 |
| 文档和说明 | 项目交付说明、变更说明、发布记录 |
目录级 `.meta` 文件不要随意排除。缺少相关 `.meta` 时，SuccApp 很难准确判断本地文件对应的服务器资源。
## 不应入库内容{#exclude}
以下内容通常不应提交到 Git：
| 内容 | 原因 |
| :--- | :--- |
| `.succapp/remote/` | 本地服务器基线副本，体积可能较大，且属于运行时数据 |
| `.succapp/cache/` | 本地缓存 |
| `.succapp/locks/` | 同步锁文件 |
| `.succapp/merge-base/` | 拉取和合并前保存的服务器基线副本 |
| `.succapp/merge-backup/` | 拉取和合并前保存的本地文件备份 |
| `.succapp/*.log` | 本地日志 |
| `.succapp/state.json` | 本地同步状态文件，只对当前机器有意义 |
| `.agents/plans/`、`.agents/reviews/`、`.agents/reports/`、`.agents/tmp/` | AI 计划、评审、报告、临时脚本和草稿默认作为未确认产物处理 |
| `.DS_Store`、`Thumbs.db` | 操作系统临时文件 |
| 个人临时文件 | 与项目交付无关 |
初始化工作区后，SuccApp 会帮助写入部分 `.gitignore` 规则。团队仍应根据项目实际情况检查和补充，特别是确认 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/` 没有进入 Git 提交。
AI 协作产物建议统一放在 `.agents/` 下。`.agents/plans/`、`.agents/reviews/`、`.agents/reports/` 和 `.agents/tmp/` 默认忽略其中的文件；需要长期保留的计划、评审或报告，应由团队确认后再调整忽略规则或移动到约定位置。
## 提交前检查{#before-commit}
提交 Git 前，先确认工作区内容和服务器状态：
1. 从 Git 拉取最新代码。
2. 通过 SuccApp 刷新变化，确认是否有远端变化或冲突。
3. 需要接受服务器变化时，先执行拉取，再继续修改。
4. 完成本地修改后，同时查看 SuccApp diff 和 Git diff。
5. 推送测试服务器并完成产品界面验证。
6. 再次检查 Git 状态，确认提交范围。
提交前应确认 Git 状态中没有 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/`、日志等运行时文件。目录级 `.meta` 如果跟随资源新增、移动、重命名或删除发生变化，应和对应资源一起检查，不要简单丢弃。
## 评审建议{#review}
评审时建议同时查看 Git diff 和 SuccApp 差异。
重点检查：
1. 是否只修改了需求相关文件。
2. 是否存在无关格式化。
3. 是否误删目录级 `.meta` 或资源文件。
4. 是否修改了权限、数据范围、流程等敏感配置。
5. 是否已经在测试环境验证。
6. 是否有生产发布说明和回退方案。
## 回退方式{#rollback}
如果修改尚未推送到服务器，可以通过 Git 回退本地文件，再刷新 SuccApp 同步状态。
如果修改已经推送到测试服务器，可以回退 Git 后再通过 SuccApp 推送回测试服务器。
如果修改已经发布到生产环境，应按项目发布流程回退，不要在不了解影响的情况下直接强制推送旧文件。
## Git 与 SuccApp 的关系{#relationship}
Git 和 SuccApp 各自负责不同问题：
| 工具 | 负责什么 |
| :--- | :--- |
| SuccApp | 连接服务器、克隆项目、查看同步差异、拉取、推送、文件历史 |
| Git | 团队版本历史、分支、提交、评审、回退 |
团队协作时，建议同时遵守 Git 流程和 SuccApp 同步流程。只使用其中一个，都可能留下协作风险。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/configure-auth.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/configure-auth"
title: "认证配置"
---
---
title: 认证配置
navTitle: 认证配置
---
# 认证配置
SuccApp 工具访问服务器时需要认证。当前支持 OAuth2 和 PAT 两种方式：日常人工使用推荐 OAuth2；脚本、CI、远程终端和 AI 自动化流程更适合使用 PAT。
认证状态按服务器地址保存在本机，不写入 SuccApp 工作区的 `.succapp/config.json`，也不应提交到 Git 仓库。
## 认证方式{#methods}
| 方式 | 适合场景 | 说明 |
| --- | --- | --- |
| OAuth2 | 日常开发、VS Code 图形化使用、有人值守的终端登录。 | 默认方式，需要打开浏览器完成人工授权。授权后工具会保存 access token 和 refresh token，并在 access token 过期时自动刷新。 |
| PAT | 脚本、CI、远程终端、AI Agent 自动化流程。 | 使用服务器签发的 Personal Access Token，不需要打开浏览器。建议按用途创建独立 PAT，并设置合适的有效期和权限范围。 |
CLI 默认使用 OAuth2：
```bash
succapp auth login
```
使用 PAT 时显式加 `--pat`：
```bash
succapp auth login --pat
```
自动化流程中，不要把 PAT 直接写进脚本文件。可以从受控密钥环境读取后通过标准输入传入：
```bash
printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat
```
## 本机认证文件{#files}
默认情况下，SuccApp 工具把认证状态放在当前系统用户的 `~/.succapp/` 目录中：
```text
~/.succapp/
├── auth.json
├── session.json
└── auth-state.lock
```
| 文件 | 用途 |
| --- | --- |
| `auth.json` | 保存稳定认证配置，例如服务器使用 OAuth2 还是 PAT、最近登录用户和更新时间。 |
| `session.json` | 保存当前认证材料，例如 PAT、OAuth2 access token、refresh token 和过期时间。 |
| `auth-state.lock` | 工具读写认证状态时使用的本机锁文件。 |
`auth.json` 和 `session.json` 都以规范化后的 server URL 作为 key。服务器地址、测试环境和生产环境不同，或同一服务器使用不同域名访问时，会保存为不同条目。
## `auth.json` 格式{#auth-json}
`auth.json` 不保存 token 原文，只保存稳定配置和登录摘要：
```json
{
"version": 1,
"servers": {
"https://succapp.example.com": {
"authType": "oauth",
"username": "admin",
"userId": "admin",
"lastLoginAt": "2026-06-05T10:00:00.000Z",
"updatedAt": "2026-06-05T10:00:00.000Z"
}
}
}
```
字段说明：
| 字段 | 说明 |
| --- | --- |
| `version` | 文件格式版本，当前为 `1`。 |
| `servers` | 按 server URL 分组的认证配置。 |
| `authType` | 认证方式，只支持 `oauth` 或 `pat`。 |
| `username`、`userId` | 最近一次登录成功的用户摘要。 |
| `lastLoginAt`、`updatedAt` | 最近登录和更新认证状态的时间，使用 ISO 8601 字符串。 |
## `session.json` 格式{#session-json}
`session.json` 保存真正用于请求服务器的认证材料。PAT 和 OAuth2 access token 都写在 `token.value` 中，因此这个文件属于敏感文件。
PAT 示例：
```json
{
"version": 1,
"servers": {
"https://succapp.example.com": {
"authType": "pat",
"token": {
"type": "Bearer",
"value": "personal-access-token"
},
"updatedAt": "2026-06-05T10:00:00.000Z"
}
}
}
```
OAuth2 示例：
```json
{
"version": 1,
"servers": {
"https://succapp.example.com": {
"authType": "oauth",
"token": {
"type": "Bearer",
"value": "access-token",
"expiresAt": "2026-06-05T18:00:00.000Z",
"scope": ["dev-tool"]
},
"refreshToken": "refresh-token",
"updatedAt": "2026-06-05T10:00:00.000Z"
}
}
}
```
字段说明：
| 字段 | 说明 |
| --- | --- |
| `authType` | 当前服务器的认证方式，只支持 `oauth` 或 `pat`。 |
| `token.type` | 当前为 `Bearer`。 |
| `token.value` | PAT 或 OAuth2 access token 原文。 |
| `token.expiresAt` | access token 过期时间；PAT 不一定有该字段。 |
| `token.scope` | token 的授权范围；由服务器返回。 |
| `refreshToken` | OAuth2 refresh token，仅 OAuth2 登录时存在。 |
| `updatedAt` | 当前认证材料最近更新时间。 |
::: warning 注意
`session.json` 包含可访问服务器的敏感 token。不要复制到工单、聊天记录、文档、日志或 Git 仓库中。
:::
## 自动化场景配置{#automation}
自动化流程建议使用 PAT，并把认证文件放到任务专用目录中，避免和人工开发环境共用 token。
可以通过环境变量指定认证文件位置：
```bash
export SUCCAPP_AUTH_SETTINGS_DIR=/path/to/succapp-auth
printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat
```
也可以只指定 `auth.json` 文件路径，`session.json` 和锁文件会放在同一目录：
```bash
export SUCCAPP_AUTH_SETTINGS_FILE=/path/to/succapp-auth/auth.json
printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat
```
自动化任务结束后，如果不再复用这份认证状态，可以删除该目录，或执行：
```bash
succapp auth logout
```
## 使用建议{#recommendations}
1. 日常人工使用优先 OAuth2，减少 PAT 长期散落在本机和脚本中的风险。
2. 自动化流程使用 PAT，并为不同任务、环境和账号创建独立 PAT。
3. 测试环境和生产环境分开登录，不要混用服务器地址和 token。
4. 不要手工编辑 `session.json`；需要刷新认证状态时重新执行登录命令。
5. 如果每次打开都需要重新认证，先检查 PAT 是否过期或被撤销，OAuth2 refresh token 是否失效，以及当前系统用户是否能读取原来的认证目录。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/configure-ai-context.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/configure-ai-context"
title: "我需要给我的 AI 工具设置提示词吗"
---
---
title: 我需要给我的 AI 工具设置提示词吗
navTitle: AI 提示词设置
---
# 我需要给我的 AI 工具设置提示词吗
需要，但不建议把所有规则都写成很长的个人提示词。更推荐把团队共同规则写在项目文档或 AI 规则文件中，个人提示词只补充当前任务目标和限制。
## 什么时候需要提示词{#when}
以下场景建议明确提示 AI：
1. 只允许修改某个项目、目录或文件。
2. 不允许推送服务器或执行 SQL。
3. 不允许修改权限、流程、数据范围等敏感内容。
4. 需要先解释影响范围，再开始修改。
5. 修改完成后需要列出文件清单和验证建议。
## 推荐写法{#recommended}
可以这样写：
```text
请在当前 SuccApp 工作区中查找和客户明细页面相关的元数据文件。
先不要修改。请说明候选文件、判断依据和可能影响范围。
```
确认范围后再写：
```text
请只修改客户明细页面标题，不要修改字段名、资源 ID、权限、流程和脚本逻辑。
修改后请列出变更文件，并提醒我需要检查哪些 diff。
```
## 团队规则放在哪里{#team-rules}
团队长期规则不建议只放在个人对话中。可以考虑放在：
1. 项目 README。
2. 团队实施规范文档。
3. `AGENTS.md`、`CLAUDE.md` 或 `.github/copilot-instructions.md` 这类 AI 工具支持的项目级规则文件。
4. 当前任务的需求说明或变更说明。
执行 `succapp workspace init` 后，SuccApp 会初始化常见 AI 协作入口和目录；官方离线文档同步成功后，才会写入 `.agents/skills/succapp-docs/`：
```text
workspace/
├── AGENTS.md
├── CLAUDE.md
├── .github/
│ └── copilot-instructions.md
└── .agents/
├── README.md
├── plans/
├── reviews/
├── reports/
├── rules/
├── skills/
│ └── succapp-docs/
└── tmp/
```
其中 `AGENTS.md` 是主要规则入口，`CLAUDE.md` 默认引用 `AGENTS.md`，`.github/copilot-instructions.md` 用于给 GitHub Copilot 提供仓库级说明。长期规则和 AI 产物建议统一放到 `.agents/`：
| 目录 | 用途 |
| :--- | :--- |
| `.agents/plans/` | 实施计划、迁移计划、多步骤任务计划 |
| `.agents/reviews/` | Code Review、设计评审、变更评审 |
| `.agents/reports/` | 调查报告、分析报告、验证报告 |
| `.agents/rules/` | 团队长期 AI 协作规则 |
| `.agents/skills/succapp-docs/` | 官方离线文档 skill，同步成功后生成，包含 SuccApp 手册索引、示例和配套资料 |
| `.agents/tmp/` | 临时脚本、草稿和一次性排查文件 |
`.agents/plans/`、`.agents/reviews/`、`.agents/reports/` 和 `.agents/tmp/` 默认忽略其中的文件，避免未确认的 AI 草稿进入 Git。需要长期保留的计划、评审或报告，应由团队确认后再调整忽略规则或移动到约定位置。
## 不建议交给 AI 自行决定的内容{#risks}
以下内容需要人工确认：
1. 是否推送生产环境。
2. 是否强制覆盖服务器变化。
3. 是否删除大量元数据文件。
4. 是否修改权限、流程、数据范围。
5. 是否执行高风险 SQL。
更多 AI 修改流程请阅读[任务驱动](../task-driven.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/connect-and-clone.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/connect-and-clone"
title: "连接服务器与克隆项目"
---
---
title: 连接服务器与克隆项目
navTitle: 连接服务器
---
# 连接服务器与克隆项目
本文介绍 SuccApp 中服务器和项目的日常操作，包括添加服务器、登录服务器、使用服务器、设置服务器地址、浏览远端文件、克隆项目、重置项目和移除本地项目。AI 修改元数据前，应先连接测试服务器并把目标项目克隆到本地工作区。
第一次准备本地目录、Git 和推荐工作区设置时，请先阅读[初始化工作区](./init-workspace.md)。
## 基本概念{#concepts}
### 服务器{#server}
服务器是一个 SuccApp 环境，可以是测试环境、预发布环境或生产环境。SuccApp 通过服务器地址访问项目、文件、历史版本和设计器页面。
### 活跃服务器{#active-server}
一个工作区可以保存多个服务器地址，但同一时间会有一个活跃服务器。同步、克隆、推送和拉取默认针对当前活跃服务器执行。
### 项目{#project}
项目是服务器上的顶层元数据目录。克隆项目后，工作区中会出现对应目录，目录中的文件可以本地编辑、对比、推送和提交 Git。
## 添加服务器{#add-server}
打开命令面板（Windows / Linux：`Ctrl+Shift+P`；macOS：`Cmd+Shift+P`），执行 **SuccApp: 添加服务器**（英文界面为 **SuccApp: Add Server**），输入服务器地址。例如：
```text
http://localhost:8080
```
地址输入后，SuccApp 会先检查服务器地址是否可访问。地址检查通过后，SuccApp 会把服务器保存到当前工作区的 `.succapp/config.json`，并要求登录。登录成功后，该服务器会成为当前活跃服务器。
如果当前工作区还没有克隆过项目，登录成功提示中会提供 **克隆项目**（英文界面为 **Clone Projects**）按钮。点击后可以继续选择远端项目并克隆到本地。
如果添加的是已有服务器，SuccApp 会提示服务器已存在。此时可以使用服务器或登录服务器。
## 登录服务器{#login}
添加服务器时会自动进入登录流程。默认方式是 OAuth2 浏览器授权；脚本、CI、远程终端或无浏览器环境可以选择使用服务器签发的 PAT。登录成功后，SuccApp 会保存本机认证状态，后续打开工作区时会尝试自动恢复连接。
如果 OAuth2 授权失效、PAT 被撤销或服务器要求重新授权，执行 **SuccApp: 登录服务器**（英文界面为 **SuccApp: Login Server**），重新选择 OAuth2 授权或 PAT 登录。
重新认证服务器只更新认证状态，不会删除服务器配置，也不会修改本地项目文件。
## 断开连接{#disconnect}
在服务器视图中可以断开当前服务器连接，也可以执行 **SuccApp: 断开服务器连接**（英文界面为 **SuccApp: Disconnect Server**）。
断开连接只影响当前 VS Code 窗口中的连接状态，不会删除 `.succapp/config.json`，也不会删除本地已克隆项目。
## 使用服务器{#switch-server}
一个工作区可以配置多个服务器。例如，同一个项目可以同时配置测试环境和生产环境。
执行 **SuccApp: 使用服务器**（英文界面为 **SuccApp: Use Server**），选择要使用的服务器。切换后，后续克隆、拉取、推送和服务器浏览都会针对新的活跃服务器。
::: warning 注意
切换到生产服务器后，任何 push 操作都会影响生产环境。发布前必须确认 Git 版本、差异和审批流程。
:::
## 修改服务器配置{#change-server-config}
SuccApp 将服务器操作拆成独立命令，可以在命令面板中直接执行：
| 操作 | 英文界面 | 说明 |
| :--- | :--- | :--- |
| 添加服务器 | Add Server | 添加服务器地址并登录 |
| 使用服务器 | Use Server | 切换当前工作区活跃服务器 |
| 登录服务器 | Login Server | 登录当前服务器，认证失效时重新认证 |
| 设置服务器地址 | Set Server URL | 在服务器地址或端口变化时替换地址，并迁移本地服务器基线 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置 |
| 打开服务器配置 | Open Server Config | 打开 `.succapp/config.json` 手工查看或调整 |
移除服务器配置只会从当前工作区移除该服务器地址，不会删除服务器上的项目，也不会删除本地 Git 仓库。
设置服务器地址适合服务器域名、IP 或端口变化的场景。执行前 SuccApp 会提示确认，说明该操作只会更新服务器配置并移动 `.succapp/remote/` 下的本地服务器基线，不会修改工作区中的项目文件，也不会修改服务器项目。确认后需要输入新地址并完成登录；只有登录成功且本地基线迁移成功后，SuccApp 才会写入新的服务器配置。
## 浏览服务器项目{#browse-project}
打开 SuccApp 侧边栏中的服务器视图，可以看到当前工作区配置的服务器。
连接成功后，展开服务器节点，可以看到服务器上的项目列表。项目节点通常显示项目名称和描述。
如果某个项目已经克隆到本地，服务器视图会显示相应状态。可以通过这个状态判断本地是否已经有该项目的工作副本。
## 浏览远端文件{#browse-files}
展开项目节点，可以继续浏览服务器上的远端文件和目录。
远端文件是服务器当前内容，不代表本地一定已经存在对应文件。打开远端文件时，SuccApp 会通过只读方式读取服务器内容。
远端文件常用操作包括：
1. 打开服务器源码。
2. 查看服务器文件历史。
3. 复制元数据路径。
4. 复制元数据 ID。
5. 打开服务器视图。
6. 打开服务器编辑页。
## 克隆项目到本地{#clone-project}
克隆项目是 SuccApp 将服务器元数据转换为本地文件系统的主要方式，也是 AI 低代码开发的起点。
可以通过以下入口克隆项目：
1. 执行 **SuccApp: 克隆项目**（英文界面为 **SuccApp: Clone Project**）。
2. 在服务器视图中选择项目节点，点击克隆按钮。
3. 使用 SuccApp CLI 执行 `succapp server project list` 查看当前登录可见的项目，再执行 `succapp workspace project clone ` 克隆指定项目。
克隆完成后，工作区根目录会出现项目目录。SuccApp 同时会在 `.succapp/remote/` 中建立该服务器项目的本地基线，用于后续差异判断。
如果新克隆的项目中包含旧版本元数据文件，SuccApp 会提示编辑前建议先升级。CLI 克隆命令只显示旧版文件总数和升级命令，不展开完整文件列表；需要先查看候选文件时，可以执行 `succapp workspace file upgrade --dry-run `。省略 `` 时，CLI 会预演当前 workspace 中所有本地已同步项目。克隆本身不会自动升级本地内容。
如果 CLI 提示项目不可用，通常表示项目名写错、当前账号没有权限，或当前活跃服务器不是目标服务器。先用 `succapp server project list` 确认可见项目，再使用准确的项目名重试。
::: tip 提示
首次使用某个服务器时，建议只克隆当前任务需要的项目，避免一次性下载过多无关项目。
:::
## 从服务器重置本地项目{#reset-project}
如果本地项目已经克隆过，可以在服务器视图中对已克隆项目执行 **从服务器重置本地项目**。
该操作会用服务器当前内容覆盖本地项目，本地已有修改会被放弃；如果本地存在服务器上没有的文件，也可能被删除。执行前应确认：
1. 本地未提交的修改是否已经保存或提交。
2. 当前服务器是否正确。
3. 是否真的希望放弃本地项目中的现有修改和本地新增文件。
::: warning 注意
这个操作接近于把本地项目恢复为服务器当前状态。执行前建议先查看 Git 状态，必要时先提交或备份本地修改。
:::
## 移除本地项目{#remove-project}
执行 **SuccApp: 移除本地项目**（英文界面为 **SuccApp: Remove Local Project**）可以从工作区和本地 mirror 中移除项目。
该操作只删除本地文件和本地基线，不会删除服务器项目。
如果项目已经纳入 Git，删除前应确认 Git 中是否仍需要保留这些文件。
## 多服务器使用建议{#multi-server}
测试环境和生产环境可以配置在同一个工作区中，但日常项目工作建议遵守以下规则：
1. 日常修改优先连接测试环境。
2. 生产环境只在发布窗口使用。
3. 使用服务器切换后先执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），再查看同步状态；需要接受服务器内容时再执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。
4. 推送生产前必须检查 Changes 视图中的差异。
5. 不要在没有 Git 记录的情况下直接覆盖生产环境。
## 常见问题{#faq}
### 登录成功后看不到项目怎么办{#no-project}
确认账号是否有访问项目的权限，并检查服务器地址是否指向正确环境。
### 克隆项目很慢怎么办{#slow-clone}
项目文件较多时，首次克隆会比较慢。建议只克隆当前任务需要的项目，并避免在网络不稳定时操作生产服务器。
### 远端文件能直接编辑吗{#remote-readonly}
服务器视图中的远端文件是只读浏览入口。需要修改文件时，应先克隆项目，在本地工作区中修改，再通过 push 同步到服务器。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/workspace/sync-changes.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/workspace/sync-changes"
title: "修改、对比、拉取与推送"
---
---
title: 修改、对比、拉取与推送
navTitle: 修改与同步
---
# 修改、对比、拉取与推送
本地修改和服务器同步是 SuccApp 的核心能力。AI 修改元数据后，项目成员应通过 SuccApp CLI 或 SuccApp for VS Code 查看差异，再选择拉取服务器变化或推送本地变化。
不要把 AI 修改完成视为交付完成。真正的交付闭环包括：检查本地变化、对比服务器基线、推送测试环境、产品界面验证、提交 Git 和必要的团队评审。
## 同步模型{#model}
SuccApp 使用三类内容判断同步状态：
| 内容 | 位置 | 说明 |
| :--- | :--- | :--- |
| 工作区文件 | 项目目录 | 用户实际编辑的本地元数据文件 |
| 本地 mirror | `.succapp/remote/` | 上次同步时记录的服务器基线 |
| 服务器当前内容 | SuccApp 服务器 | 服务器上正在生效的元数据 |
本地文件和 mirror 不一致时，会产生本地变化。本地 mirror 和服务器当前内容不一致时，会产生远端变化。如果本地和服务器都改了同一个资源，就可能产生冲突。
## 开始修改前{#before-edit}
开始修改前建议先完成以下检查：
1. 确认当前连接的是测试服务器。
2. 从 Git 拉取团队最新内容。
3. 在 SuccApp 中拉取服务器变化。
4. 确认 Changes 视图没有未处理的冲突。
5. 确认本次任务涉及的文件范围。
这样可以减少多人协作时互相覆盖的风险。
## 本地修改元数据{#edit-local}
克隆项目后，可以直接在 VS Code 中编辑项目目录下的元数据文件。
常见修改包括：
1. 修改页面、报表、仪表板等 JSON 元数据。
2. 修改前端脚本或后端脚本。
3. 新增或调整资源文件。
4. 使用 AI 辅助批量修改元数据字段。
5. 使用 CLI 或脚本生成小范围可审查的修改。
修改时应注意：
1. 不要随意删除目录级 `.meta` 文件或其中的资源条目。
2. 不要直接编辑 `.succapp/remote/` 下的文件。
3. 大范围格式化前，应确认团队是否接受格式化造成的差异。
4. 删除文件前，应确认服务器上也需要删除该资源。
## 刷新变化{#refresh-status}
修改后打开 SuccApp **变化** 视图，点击刷新按钮，或执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**）。
刷新后，Changes 视图会显示本地变化和远端变化；发生冲突时，相关资源会带有冲突标记。视图 badge 会显示当前需要处理的变化数量。
如果修改了 `.gitignore` 或同步忽略规则，建议刷新变化，让 SuccApp 重新计算变化列表。
## 处理服务器变化{#refresh-baseline}
SuccApp 会通过本地 mirror 和服务器当前内容判断远端变化。需要查看服务器是否有变化时，先执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），再在 Changes 视图中检查远端变化和冲突。
如果确认要接受服务器上的最新内容，执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。拉取会更新本地 mirror，并把可安全应用的服务器变化写入工作区；遇到同一路径本地也修改的情况，会返回冲突，等待用户确认。
如果远端变化分组中出现带 `?` 标记的项目，表示当前连接服务器或当前登录用户的项目列表没有返回该本地已跟踪项目。SuccApp 无法直接判断这是连错服务器、登录错用户、权限不足，还是服务器项目确实已删除；同名但项目身份不一致（例如连到了另一台服务器，或项目被删除后重建）也会归到这一类。这类项目不会被普通拉取或自动拉取直接删除本地内容；处理前应先核对服务器地址、登录用户、项目权限和项目名称。
如果服务器把整个项目重命名（项目身份不变、只是改名），远端变化中会显示为项目级的重命名。当前版本只展示该变化，不会在拉取或推送时自动把本地项目目录改名；直接对项目重命名执行拉取或推送会返回提示，请改用重新 clone 该项目或在本地改名以保持一致。
::: warning 注意
当前版本不提供单独只刷新 mirror、但不修改工作区文件的用户命令。拉取前如果本地已有重要修改，应先检查 Changes 视图中的本地变化，必要时先提交 Git。
:::
## 理解变化类型{#change-types}
常见变化类型如下：
| 类型 | 含义 | 常见处理 |
| :--- | :--- | :--- |
| 新增 | 本地或服务器新增文件 | 确认是否需要同步 |
| 修改 | 文件内容或目录级 `.meta` 信息变化 | 打开 diff 检查 |
| 删除 | 本地或服务器删除文件 | 确认是否真的删除 |
| 移动/重命名 | 文件路径发生变化 | 检查旧路径和新路径 |
| 冲突 | 本地和服务器都修改了同一资源 | 阅读[冲突处理](../troubleshoot/conflict-handling.md) |
对于 `.meta` 变化，需要结合资源操作理解。如果只是修改文件内容，通常不应出现大量无关 `.meta` 变化。
## 查看差异{#diff}
可以通过以下入口查看差异：
1. 在 Changes 视图中点击变化文件。
2. 在变化文件上选择 **与服务器版本对比**。
3. 在本地文件菜单中选择 **与服务器版本对比**。
4. 使用快捷键 `Ctrl+Alt+D`，macOS 使用 `Command+Alt+D`。
差异对比可能展示以下内容：
1. 本地文件和同步基线的差异。
2. 服务器当前内容和同步基线的差异。
3. 删除文件和空内容的差异。
4. 目录级 `.meta` 变化中的资源元信息差异。
检查差异时，应重点确认修改范围是否与任务一致，是否存在误删、误改、格式化噪声和无关文件。
## 拉取服务器变化{#pull}
拉取会把服务器上的远端变化应用到本地工作区。
常用入口：
1. 执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。
2. 点击 Changes 视图顶部的拉取按钮。
3. 在某个远端变化上选择 **拉取文件**。
拉取适合以下场景：
1. 开始工作前同步其他人的服务器修改。
2. push 被远端变化阻止后，先把服务器变化拉到本地。
3. 需要接受服务器上的最新内容。
::: warning 注意
拉取可能修改本地文件。拉取前如果有未提交的重要修改，应先确认 Changes 视图中的本地变化，必要时先提交 Git。
如果拉取到旧版本元数据文件，SuccApp 会提示编辑前建议先升级。拉取本身不会自动升级本地内容。
:::
## 推送本地变化{#push}
推送会把本地工作区变化提交到当前活跃服务器。
常用入口：
1. 执行 **SuccApp: 推送变化**（英文界面为 **SuccApp: Push Changes**）。
2. 点击 Changes 视图顶部的推送按钮。
3. 在某个本地变化上选择 **推送文件**。
4. 打开文件后执行 **SuccApp: 推送当前文件**（英文界面为 **SuccApp: Push Current File**）。
5. 使用快捷键 `Ctrl+Shift+Up`，macOS 使用 `Command+Shift+Up`。
通过 **SuccApp: 推送变化**（英文界面为 **SuccApp: Push Changes**）执行工作区推送时，SuccApp 会展示准备推送的文件列表。确认无误后再继续。
Changes 视图中的单文件推送、顶部批量推送，以及 **SuccApp: 推送当前文件**（英文界面为 **SuccApp: Push Current File**）更偏向快速操作，可能不会再次展示完整文件列表。使用这些入口前，应先在 Changes 视图和 diff 中确认变化范围。
如果本地修改的元数据内容版本和当前服务器版本不一致，推送不会自动升级，也不会因为内容版本差异阻止提交。推送成功后，SuccApp 会提示旧版本文件建议升级；如果本地内容版本高于当前服务器版本，会提示确认兼容性。可以手动执行 **SuccApp: 升级文件**（英文界面为 **SuccApp: Upgrade File**），不传目标时升级当前编辑器文件；在资源管理器中对文件或文件夹执行时，会升级对应文件或文件夹下可支持的元数据文件。手动升级只会改写本地 workspace 中的文件，不会修改远端服务器数据；只有后续执行推送时，升级后的本地文件才会提交到服务器。
使用 CLI 时，可以执行 `succapp workspace file upgrade --dry-run` 先查看所有本地已同步项目中的升级候选文件；指定 `sysdata`、项目名、目录或文件路径时，只预演对应范围。去掉 `--dry-run` 后会升级本地文件，但仍不会直接修改远端服务器数据。
推送成功后，服务器会立即使用新的元数据。测试环境推送后应及时在浏览器中预览效果。
## 推送被阻止怎么办{#push-blocked}
如果服务器上存在未拉取的远端变化，push 可能被阻止。此时通常会看到以下选择：
1. 查看差异。
2. 拉取服务器变化。
3. 强制推送。
推荐处理顺序：
1. 先查看差异，确认服务器上是谁改了什么。
2. 如果服务器变化需要保留，先拉取并解决冲突。
3. 如果确认服务器变化可以被覆盖，再由负责人决定是否强制推送。
::: danger 生产环境禁止随意强制推送
生产环境中出现 push 被阻止时，应先暂停发布，确认远端变化来源和业务影响。不要为了完成操作直接强制覆盖。
:::
如果本地和服务器都修改了同一个资源，可能需要处理冲突。详细步骤请阅读[冲突处理](../troubleshoot/conflict-handling.md)。
## 放弃修改{#discard}
如果本地修改不需要保留，可以在 Changes 视图中选择 **放弃修改**。
放弃修改会用本地同步基线恢复本地文件，必要时会删除本地新增文件。它不会实时从服务器重新下载最新内容。执行前请确认这些修改不再需要。
使用 SuccApp CLI 时，可以放弃指定路径的本地修改：
```bash
succapp workspace discard
```
如果不指定路径，表示放弃整个工作区中的本地修改，需要显式确认：
```bash
succapp workspace discard --force
```
如果希望先以服务器当前内容为准，应先拉取服务器变化，或对整个项目执行 **从服务器重置本地项目**。
对于已经提交到 Git 的修改，也可以通过 Git 回退，但需要注意 Git 回退和 SuccApp 同步状态是两套机制。回退后仍应刷新 SuccApp 同步状态。
## 自动推送和自动拉取{#auto-sync}
SuccApp 支持自动推送和自动拉取。
自动推送适合测试环境中快速调试脚本或元数据。开启后，保存文件会在延迟后自动推送到服务器。
自动推送可以通过 **SuccApp: 开启自动推送**（英文界面为 **SuccApp: Enable Auto Push**）和 **SuccApp: 关闭自动推送**（英文界面为 **SuccApp: Disable Auto Push**）控制，也可以通过 `succapp.sync.autoPush` 设置项配置。
自动拉取通过 `succapp.sync.autoPull` 和 `succapp.sync.autoPullInterval` 设置项控制。自动拉取会按配置间隔拉取服务器变化，可能修改本地文件，适合少数需要持续跟随服务器变化的协作场景。
::: warning 注意
不建议在生产环境中开启自动推送或自动拉取。多人协作场景中也应谨慎开启自动拉取，避免本地修改被未预期的服务器变化打断。生产环境应通过手工检查差异和发布确认后再同步。
:::
## 配置同步忽略规则{#ignore}
可以通过 `succapp.sync.ignore` 设置同步忽略规则，也可以执行 **SuccApp: 配置同步忽略规则**（英文界面为 **SuccApp: Configure Sync Ignore Rules**）打开配置。
适合忽略的内容包括：
1. 临时文件。
2. 日志文件。
3. 本地生成文件。
4. 与当前项目交付无关的辅助文件。
不要用忽略规则隐藏真实业务元数据变化。否则团队可能以为没有变化，实际服务器和本地已经不一致。
## 查看日志{#log}
执行 **SuccApp: 查看日志**（英文界面为 **SuccApp: Show Logs**）可以打开 SuccApp 日志面板。
当 push、pull、clone 或状态刷新失败时，日志通常能帮助判断原因，例如认证状态过期、网络失败、权限不足、文件过大或服务器返回错误。
需要查看更多诊断信息时，在 Output 面板的 SuccApp 日志通道右侧点击日志级别按钮，将级别临时调整为 **Debug**。
## 推荐流程{#recommended-flow}
日常修改建议按以下流程执行：
1. 从 Git 拉取最新代码。
2. 连接测试服务器。
3. 拉取服务器变化。
4. 修改本地元数据。
5. 刷新同步状态。
6. 查看差异。
7. 推送到测试服务器。
8. 预览效果。
9. 提交 Git。
10. 发起评审或通知团队。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/project/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/project"
title: "管理项目"
---
---
title: 管理项目
description: 说明 AI 接手 SuccApp 项目时如何识别元数据项目、目录、资源边界和指定文件修改范围。
navTitle: 管理项目
indexTitle: 概述
---
# 管理项目
管理项目用于处理“这个项目目录怎么组织”“新建什么资源”“只改这个文件”这类任务。AI 开始修改前，应先确认元数据项目、业务边界、目录结构、公共资源和不可修改范围。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要判断一个 `/项目/...` 路径下有什么文件、模型、页面或资源。
- 需要根据业务词查找资源文件、字段、引用和依赖。
- 需要确认 AI 本次应该修改哪些项目、目录或文件。
- 需要避免误改公共资源、共享模型、权限配置或其它业务范围。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 定位元数据 | [定位元数据](./find-resource.md) | 查找资源文件、模型文件、字段、路径和依赖，或判断某个 `/项目/...` 路径下有什么。 |
## 相关阅读
- [元数据项目](../../meta/rules/project.md)：理解 SuccApp 元数据项目、资源目录和文件组织方式。
- [工作区](../basics/workspace.md)：理解本地工作区与服务器项目的同步关系。
- [引用检查](../quality/reference-check.md)：修改前后检查文件、字段、组件、数据集和脚本引用。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/project/find-resource.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/project/find-resource"
title: "定位元数据"
---
---
title: 定位元数据
description: 说明 AI 如何查找 SuccApp 元数据路径、资源文件、模型、字段和依赖，并区分工作区、服务器、示例和其它工作区。
navTitle: 定位元数据
---
# 定位元数据
定位元数据用于处理“某个路径下有哪些模型”“找某个字段在哪个模型里”“查页面或报表引用了哪个模型”“根据业务词找资源文件”“判断 `/项目/...` 路径下有什么”等任务。
## 定位原则{#source-priority}
1. 用户给出 `/项目名/...` 形式的路径时，默认这是 SuccApp 服务器元数据路径，不是本地绝对文件路径。
2. 用户给出 SuccApp 页面 URL 时，可以从 URL 路径识别 `/项目名/...`，也可以从 `:open` 等参数中的资源 ID 反查服务器路径。
3. 回答业务问题、排查模型、查字段、查依赖、判断当前项目内容时，优先查当前工作区中已克隆的项目，其次查当前活跃服务器。
4. 用户要求修改页面、模型等元数据资源时，如果当前已经在 SuccApp 工作区，但目标项目尚未克隆，应询问用户是否先把项目克隆到当前工作区，再继续修改。
5. 示例只用于参考和学习。除非用户明确要求查询示例、DEMO 示例或参考写法，`.agents/skills/succapp-docs/metadata-examples/` 一般不是用户想找的目标。
6. 除非用户明确要求，不要向上级目录、相邻目录或其它 SuccApp 工作区搜索同名项目来回答当前项目问题。
7. 如果当前工作区和当前活跃服务器都找不到，或 CLI 不可用、未登录、无权限、服务器不可达，应明确说明无法确认真实元数据，并询问用户补充目标服务器、工作区、项目或更详细路径。
## 默认查询流程{#workflow}
1. 确认当前工作区和活跃服务器，例如执行：
```bash
succapp workspace status --json
```
2. 从 `/项目名/...` 路径中识别项目名和相对资源路径，例如 `/DEMO/data/tables/行业/企业法人` 对应项目 `DEMO`。
3. 如果用户给的是浏览器 URL，例如 `http://localhost:8180/DEMO/data?:open=O20vb6tsc4BF2i7PKKZFPB&:tblview=modelFields`，先尝试从 URL 路径得到 `/DEMO/data`，再用 `:open` 中的资源 ID 定位实际资源路径：
```bash
succapp server file locate http://localhost:8180 O20vb6tsc4BF2i7PKKZFPB --json
```
4. 如果当前工作区已克隆该项目，并且项目目录包含 `.meta`，优先在本地项目目录中查找同名目录、资源文件和目录级 `.meta`。
5. 如果当前工作区没有该项目或路径，不要到父目录、兄弟目录或其它工作区查找同名项目；使用 SuccApp CLI 的只读命令查询当前活跃服务器，例如：
```bash
succapp server file list /DEMO/data/tables/行业/企业法人 --json
succapp server file search 企业法人 --project=DEMO --type=tbl --limit=20 --json
succapp model list --project DEMO --contains=企业法人 --json
```
6. 找到候选 `.tbl` 模型后，再按任务需要查看模型摘要、字段或索引：
```bash
succapp model show /DEMO/data/tables/行业/企业法人/示例模型.tbl --json
succapp model fields /DEMO/data/tables/行业/企业法人/示例模型.tbl --json
succapp model indexes /DEMO/data/tables/行业/企业法人/示例模型.tbl --json
```
7. 如果用户要求修改已定位到的页面、模型、报表或脚本等元数据资源，而当前工作区尚未克隆目标项目，应先询问是否执行类似下面的命令克隆项目，不要直接改相邻工作区或绕过工作区直接写服务器：
```bash
succapp workspace project clone DEMO
```
8. 如果当前工作区和当前活跃服务器都找不到，或 CLI 不可用、未登录、无权限、未配置活跃服务器或服务器不可达，应明确说明无法确认真实元数据，并询问用户补充目标服务器、工作区、项目或更详细路径。
实际命令参数以当前 `succapp --help`、`succapp server file --help` 和 `succapp model --help` 输出为准。查询真实业务项目时优先使用只读命令，避免修改、删除、推送或导出大量数据。
## 查找方向{#search-directions}
| 任务 | 优先方法 |
| --- | --- |
| 判断某个路径下有什么 | 本地查项目目录和 `.meta`；本地没有时用 `succapp server file list` 查询服务器目录。 |
| 根据浏览器 URL 找资源 | 从 URL 路径提取 `/项目/...`；如果 URL 带 `:open` 资源 ID，用 `succapp server file locate` 反查路径。 |
| 修改未克隆项目中的资源 | 先询问用户是否把目标项目克隆到当前工作区，再在本地修改和检查 diff。 |
| 找某个资源文件 | 先按路径精确定位；路径不完整时用文件名、标题、业务词执行本地搜索或 `succapp server file search`。 |
| 找模型文件 | 本地搜索 `.tbl`；服务器查询用 `succapp model list` 或 `succapp server file search`。 |
| 找字段在哪个模型里 | 先筛选候选 `.tbl`，再用 `succapp model fields` 查看字段清单。 |
| 查页面、报表或仪表板依赖 | 先定位页面、报表、仪表板文件，再查看其中引用的模型、查询、脚本或组件路径。 |
| 根据业务词找资源 | 同时搜索资源路径、文件内容、模型标题、字段标题和 `.meta` 信息，并说明匹配依据。 |
## 输出要求{#output}
AI 回答时应说明：
1. 信息来源：当前工作区、服务器 CLI，还是用户明确要求的示例或其它工作区。
2. 已检查的项目、目录、命令或文件路径。
3. 候选文件、模型、字段或依赖，以及每个候选的判断依据。
4. 哪些内容可以确认，哪些内容因为未登录、无权限、CLI 不可用或服务器不可达而无法确认。
如果没有访问到当前工作区中的真实项目或当前活跃服务器，只能说“无法确认真实元数据”，不能把 `metadata-examples` 中的示例 DEMO 或相邻工作区里的同名项目当成当前服务器事实。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/data/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/data"
title: "处理数据"
---
---
title: 处理数据
description: 组织 AI 辅助完成数据连接、加工、调度、探查、查询、数据质量排查、测试数据和演示数据准备任务。
navTitle: 处理数据
indexTitle: 概述
---
# 处理数据
处理数据用于处理接数据源、查看库表结构、准备数据、建模型、加字段、做数据加工、提取输出和配置调度等任务，也覆盖数据探查、查询、排查数据质量问题、准备测试数据和构建演示数据。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要查看真实数据、库表结构、模型字段或业务口径。
- 需要准备测试数据、演示数据、取数逻辑或过滤条件。
- 需要让 AI 判断页面、报表或看板为什么没有数据或数据不对。
- 需要在修改数据源、数据模型或数据加工任务前确认影响范围。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 查询数据 | [查询数据](./query-data.md) | 需要用 SuccApp CLI 查询数据库物理层或 SuccApp 语义层模型数据。 |
| 准备数据 | [准备数据](./prepare-data.md) | 创建或修改数据模型、查询、字段、过滤条件、数据源配置或取数逻辑。 |
## 相关阅读
- [构建分析可视化](../analytics/README.md)：数据准备好后，继续制作仪表板、图表和指标卡。
- [构建报表](../report/README.md)：数据准备好后，继续制作统计表、明细表、参数和导出报表。
- 相关产品手册：数据连接、数据管理、数据加工、调度管理和数据质量排查。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/data/query-data.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/data/query-data"
title: "查询数据"
---
---
title: 查询数据
navTitle: 查询数据
---
# 查询数据
AI 辅助开发时，经常需要先查一小段真实数据来理解字段含义、验证过滤条件或确认页面展示结果。SuccApp CLI 提供两类查询入口：`db` 面向数据库物理层，适合查看数据源、schema、物理表和执行只读 SQL；`model` 面向 SuccApp 语义层模型，适合按 `.tbl` 模型、字段、权限和 Query DSL 查询业务口径数据。
## 查询前确认{#requirements}
请先确认：
1. 当前 AI 入口可以调用 SuccApp CLI，或团队提供了等价的受控工具入口。
2. SuccApp CLI 已登录目标服务器，命令行可访问当前账号有权限查看的数据源和模型。
3. 本次查询目标已经明确：是排查物理表数据，还是验证 SuccApp 模型口径。
4. 涉及生产数据、敏感数据或大范围导出时，已经确认数据范围和用途。
查询入口选择建议：
| 目标 | 推荐入口 | 适用场景 |
| --- | --- | --- |
| 查数据库连接、schema、物理表、字段和原始行 | `succapp db ...` | 排查物理表是否有数据、字段名是否正确、SQL 是否能在目标数据源执行。 |
| 查 `.tbl` 模型、模型字段、模型过滤后的业务数据 | `succapp model ...` | 验证页面、报表、仪表板或 Query DSL 使用的语义层口径。 |
| 查询少量样例数据给 AI 分析 | `db query` 或 `model select/query` | 返回有限行数，适合直接放到终端输出或 AI 上下文。 |
| 导出较多数据到文件 | `db export` 或 `model export` | 生成 CSV 文件，不把完整结果写入 stdout。 |
## 查询物理层数据{#physical-data}
物理层查询直接面向数据库和物理表。它适合在建模、排障或写 SQL 前确认数据源、schema、表结构和原始数据。
### 查看数据源和表结构{#physical-structure}
先让 AI 或命令行查看可访问的数据源，再逐步定位 schema、表和字段：
```bash
succapp db source list
succapp db source list --json
succapp db source show
succapp db schema list
succapp db table list
succapp db table describe
```
执行 SQL 前，应先通过 CLI 输出确认目标数据源的数据库产品或方言线索，例如数据库产品名、产品版本、连接器、JDBC 驱动、默认 schema 或 catalog。不同数据库的分页、日期函数、字符串拼接、大小写引用、schema 写法和类型转换语法可能不同，AI 不能在未确认数据库类型时直接套用通用 SQL。
如果命令输出中没有直接显示数据库产品名，也要根据 `dbConnector`、`driver`、`databaseProductVersion`、`defaultSchema` 等信息判断方言；仍无法判断时，先询问用户或让团队补充数据源说明，再生成 SQL。
如果目标表不在默认 schema 下，列出表时把 schema 作为第二个位置参数；描述表和执行 SQL 时再使用 `--schema`：
```bash
succapp db table list PUBLIC
succapp db table describe --schema=PUBLIC
succapp db query "select * from orders" --schema=PUBLIC --max-rows=20
```
### 预览 SQL 查询结果{#physical-preview}
使用 `db query` 执行只读 SQL 查询。预览结果默认只返回前 `100` 行，服务端上限为 `1000` 行；需要更少样例时用 `--max-rows` 明确限制。
```bash
succapp db query "select * from orders" --max-rows=20
succapp db query --file=./query.sql --schema=PUBLIC --timeout=10 --max-rows=100
cat query.sql | succapp db query --max-rows=100 --json
```
需要给 AI 稳定读取结果时，可以加 `--json`。JSON 结果中的 `fields` 描述字段，`rows` 是对象行数组，`rowCount` 是本次实际返回行数，`truncated` 表示结果是否被 `maxRows` 截断。
```bash
succapp db query "select id, name from orders" --max-rows=20 --json
```
`db query` 是只读入口。服务端会拒绝非只读 SQL，并通过只读查询连接执行，避免 AI 在查数场景误修改业务数据。
SQL 来源只能选择一种：命令位置参数 ``、`--file=./query.sql`，或管道 stdin。没有传 `` 和 `--file` 时，如果命令从管道接收到内容，会把 stdin 作为 SQL；交互终端中没有输入来源时，命令会提示缺少 SQL。
### 导出物理层查询结果{#physical-export}
预览命令适合小样本查询；需要较多数据时使用 `db export` 导出 CSV 文件。导出必须指定 `--output`，不会把完整数据写入 stdout。
```bash
succapp db export orders --output=orders.csv
succapp db export --query="select id, name from orders" --output=orders.csv
succapp db export --query-file=./query.sql --output=orders.csv
```
输出文件已存在时，命令会要求显式确认；确认覆盖时使用 `--force`。
```bash
succapp db export --query-file=./query.sql --output=orders.csv --force
```
导出目标只能选择一种：表名 ``、`--query` 或 `--query-file`。`--output` 是必填项，输出目录不存在时 CLI 会尝试创建；如果远端导出、网络或本地写入失败，目标文件不会被写成半截结果。
## 查询语义层模型{#semantic-model}
语义层查询面向 SuccApp 数据模型。它不要求 AI 直接理解底层物理表关系，而是通过 `.tbl` 模型、模型字段、模型过滤表达式和 Query DSL 查询业务口径数据。
当数据用于页面、报表、仪表板、应用组件或已有模型口径校验时，优先使用 `model` 命令。这样可以更贴近产品实际取数路径，也更容易发现模型字段、权限、过滤条件和物理表之间的不一致。
### 查看模型和字段{#model-structure}
先定位模型，再查看模型摘要、字段和索引：
```bash
succapp model list --project DEMO --limit=20
succapp model show /DEMO/data/tables/APP/客户.tbl
succapp model fields /DEMO/data/tables/APP/客户.tbl
succapp model indexes /DEMO/data/tables/APP/客户.tbl
```
字段较多时，可以按维度、度量或关键字过滤：
```bash
succapp model fields /DEMO/data/tables/APP/客户.tbl --dim
succapp model fields /DEMO/data/tables/APP/客户.tbl --measure
succapp model fields /DEMO/data/tables/APP/客户.tbl --contains=状态
```
### 查询单个模型{#model-select}
如果只需要查询一个 `.tbl` 模型，使用 `model select`。`--where` 使用 SuccApp 模型表达式，`--select` 指定返回字段，`--order` 指定排序，`--max-rows` 控制预览行数。
```bash
succapp model select /DEMO/data/tables/APP/客户.tbl --max-rows=20
succapp model select /DEMO/data/tables/APP/客户.tbl --select ID,NAME,STATUS --where "STATUS='ACTIVE'" --order "CREATE_TIME desc" --max-rows=20 --json
```
`model select` 的预览结果同样默认返回前 `100` 行，服务端上限为 `1000` 行。返回结构与 `db query` 保持一致，便于 AI 用同一种方式读取 `fields`、`rows`、`rowCount`、`maxRows` 和 `truncated`。
### 使用 Query DSL 查询模型{#model-query}
当查询涉及多个模型、分组、排序、聚合或已有 `.query` 逻辑时，使用 `model query` 执行 Query DSL JSON。
执行语义层查询前，先查看 Query DSL JSON 格式，再根据模型字段生成查询。Query DSL 描述的是 SuccApp 模型查询，不是数据库 SQL；`sources` 指向模型，`fields` 描述返回字段或表达式，`filter`、`sorts`、`options` 等属性用于表达过滤、排序和行数限制。
一个最小 Query DSL JSON 示例：
```json
{
"sources": ["/DEMO/data/tables/APP/客户.tbl"],
"fields": [
{
"alias": "NAME",
"exp": "NAME"
},
{
"alias": "STATUS",
"exp": "STATUS"
}
],
"filter": "STATUS='ACTIVE'",
"options": {
"enableLimit": true,
"limit": 20
}
}
```
```bash
succapp model query --query-file=./query.json --max-rows=100 --json
cat query.json | succapp model query --stdin --json
```
`model query` 的 Query DSL 来源只能选择一种：`--query`、`--query-file` 或 `--stdin`。JSON 较短时可以用 `--query` 直接传入；实际任务中更推荐使用文件或 stdin，便于 AI Agent 生成、检查和复用。
AI 生成或修改 Query DSL 前，应先执行 `model show` 和 `model fields` 查看相关模型、字段和字段类型，避免使用不存在的字段或绕开模型口径。需要复用已有查询文件时，先查看对应 `.query` 或 `query.json` 的结构，再局部调整字段、过滤条件或行数限制。
### 导出语义层查询结果{#model-export}
需要导出模型查询结果时使用 `model export`。它可以导出单模型 `select` 结果，也可以导出 Query DSL 查询结果。
```bash
succapp model export /DEMO/data/tables/APP/客户.tbl --select ID,NAME --output=customers.csv
succapp model export --query-file=./query.json --output=result.csv
cat query.json | succapp model export --stdin --output=result.csv
```
导出结果写入 CSV 文件；输出文件已存在时，使用 `--force` 明确覆盖。
`model export` 的导出目标只能选择一种：模型路径 ``、`--query`、`--query-file` 或 `--stdin`。导出单模型时，可以继续使用 `--select`、`--where` 和 `--order` 控制字段、过滤和排序；导出 Query DSL 时，这些查询条件应写在 Query DSL JSON 中。
## AI 查询建议{#ai-guidelines}
让 AI 查数时，建议在任务描述中写清：
1. 优先使用物理层还是语义层。
2. 数据源、schema、表名或模型路径。
3. 需要返回的字段、过滤条件和样例行数。
4. 输入来源是直接参数、本地文件，还是管道 stdin。
5. 是否允许导出 CSV 文件，以及允许写入的输出路径。
6. 是否涉及生产数据或敏感字段。
可以直接这样描述任务：
```text
请先用 succapp model fields 查看 /DEMO/data/tables/APP/客户.tbl 的字段，再用 model select 查询 STATUS='ACTIVE' 的 20 行样例数据。只允许只读查询，不要导出文件。
```
如果只是分析业务口径，优先让 AI 使用 `model` 命令；如果是排查数据库连接、字段名、SQL 方言或物理表数据，使用 `db` 命令。
## 安全边界{#security}
查数默认应遵守最小数据原则：
1. 预览查询先用 `--max-rows` 限制样例行数。
2. 大数据结果走 `export` 写文件，不把完整数据灌入 AI 对话。
3. 生产环境优先查汇总或脱敏字段，避免直接暴露敏感明细。
4. 不让 AI 在未确认的情况下执行写入、删除、建表、改表等 SQL。
5. 修改模型、查询文件或数据源配置前，先检查引用影响。
`db query` 和 `model select/query` 面向预览，适合验证和理解；`db export` 和 `model export` 面向文件导出，应在确认用途和范围后再执行。
## 常见排查{#troubleshooting}
| 现象 | 处理方式 |
| --- | --- |
| 找不到数据源 | 先执行 `succapp db source list`，确认当前账号和服务器能看到目标数据源。 |
| 找不到表或字段 | 查看 schema 是否正确；再执行 `db table list`、`db table describe` 或 `model fields` 确认名称。 |
| SQL 在数据库工具能跑，`db query` 失败 | 检查是否使用了非只读语句、数据库方言、schema 或当前账号权限。 |
| 模型查询结果和物理表不一致 | 优先检查 `.tbl` 模型字段、过滤条件、权限字段、计算字段和模型引用的数据源。 |
| `truncated` 为 `true` | 结果超过预览上限。减少过滤范围、提高 `--max-rows`，或改用 `export` 导出 CSV。 |
| 提示输入冲突 | 同一类输入传了多个来源，例如同时传 `` 和 `--file`，或同时传 `` 和 `--query-file`。保留一个来源后重试。 |
| 提示缺少输出文件 | `db export` 和 `model export` 必须传 `--output`。确认可以写入的本地路径后重试。 |
| 导出文件已存在 | 确认可以覆盖后加 `--force`，或换一个输出文件名。 |
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/data/prepare-data.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/data/prepare-data"
title: "准备数据"
---
---
title: 准备数据
navTitle: 准备数据
---
# 准备数据
“准备数据”通常指创建或修改数据模型、查询、字段、过滤条件、数据源配置或取数逻辑。AI 可以辅助理解表结构、生成查询草稿和检查字段引用，但涉及数据写入和数据源变更时必须人工确认。
## 阅读顺序{#reading-order}
1. 先读 [SuccApp 官方文档 Skill](../../../../SKILL.md) 中的 AI 低代码开发说明和[工作区中的 AI 协作文件](../basics/workspace.md#ai-files)，确认数据范围、环境、权限和是否只允许只读操作。
2. 再读[数据模型](../../meta/file-types/data/tbl.md)、[查询](../../meta/file-types/data/query.md)、[数据源连接](../../meta/file-types/config/jdbc.md)和[查询数据](./query-data.md)。
3. 使用 SuccApp CLI 只读命令前，先确认服务器、数据源和模型范围；物理库排查用 `db`，语义模型排查用 `model`。
4. 修改后按[引用检查](../quality/reference-check.md)、[元数据静态检查](../quality/metadata-check.md)和[产品验证](../quality/product-verification.md)验证影响范围。
## 常见文件和工具{#files}
| 对象 | 用途 |
| --- | --- |
| `.tbl` | 数据模型、字段、物理表和取数配置。 |
| `.query` | 查询 DSL 或数据准备逻辑。 |
| `.jdbc` | 数据源连接配置。 |
| SuccApp CLI `db` 命令 | 查看数据源、schema、表结构和执行只读查询。 |
| SuccApp CLI `model` 命令 | 查看 `.tbl` 模型摘要、字段、索引，并通过模型表达式或 Query DSL 查询模型数据。 |
## AI 修改前{#before}
明确告诉 AI：
1. 目标业务问题和数据口径。
2. 数据源、schema、表名和字段范围。
3. 是否只允许只读查询。
4. 是否允许修改 `.tbl`、`.query` 或 `.jdbc`。
5. 是否涉及生产数据、敏感数据或数据写入。
## 推荐流程{#workflow}
1. 使用 `succapp db source list`、`schema list`、`table describe` 读取物理结构；使用 `succapp model list`、`model show`、`model fields` 读取语义模型结构。
2. 让 AI 先解释字段和表关系，不要直接执行写 SQL。
3. 需要 SQL 或模型查询时先生成只读查询并限制行数；单模型查询优先用 `succapp model select --where "STATUS='ACTIVE'" --max-rows 20`。
4. 修改模型或查询文件前，搜索页面、报表和脚本引用。
5. 修改后验证依赖该模型的页面、看板和报表。
## 安全边界{#safety}
以下操作必须人工确认：
1. `succapp db exec`。
2. 导入、删除或更新业务数据。
3. 修改数据源配置。
4. 修改模型主键、物理表名、字段编码和权限相关字段。
5. 在生产数据源上执行大范围查询。
更多说明见[查询数据](./query-data.md)和[安全边界](../basics/safety.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/analytics/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/analytics"
title: "构建分析可视化"
---
---
title: 构建分析可视化
description: 组织 AI 辅助完成仪表板、图表、指标卡、筛选联动和可视化分析任务。
navTitle: 构建分析可视化
indexTitle: 概述
---
# 构建分析可视化
构建分析可视化用于处理仪表板、图表、指标卡、筛选器、联动、跳转、移动端分析和可视化展示效果调整等任务。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要新建或调整仪表板、图表、指标卡或分析页面。
- 需要配置筛选条件、联动、跳转或移动端展示效果。
- 需要让 AI 理解 `.dash` 等可视化元数据的结构和引用关系。
- 需要在推送前整理看板验证点和风险检查清单。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 做看板 | [做看板](./make-dashboard.md) | 创建或修改仪表板、图表、指标卡、筛选条件和数据可视化页面。 |
## 相关阅读
- [处理数据](../data/README.md)：先查询、准备或核对看板依赖的数据和模型。
- [质量检查](../quality/README.md)：修改后检查 diff、引用关系和产品运行效果。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/analytics/make-dashboard.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/analytics/make-dashboard"
title: "做看板"
---
---
title: 做看板
navTitle: 做看板
---
# 做看板
“做看板”通常指创建或修改仪表板、图表、指标卡、筛选条件和数据可视化页面。AI 适合辅助搭建结构、绑定数据集、调整展示文案和生成校验清单。
## 阅读顺序{#reading-order}
1. 先读 [SuccApp 官方文档 Skill](../../../../SKILL.md) 中的 AI 低代码开发说明和[工作区中的 AI 协作文件](../basics/workspace.md#ai-files)，确认目标、环境、范围、禁区和验收方式。
2. 再读[元数据系统](../../meta/README.md)、[仪表板文件类型](../../meta/file-types/ana/dash.md)、[数据模型](../../meta/file-types/data/tbl.md)和[查询](../../meta/file-types/data/query.md)。
3. 修改前参考当前项目同类看板、数据集、模型字段和组件 DTS；涉及脚本时补充阅读[脚本开发](../../script/README.md)。
4. 修改后检查字段、图表、筛选联动和产品页面效果，必要时按[引用检查](../quality/reference-check.md)、[产品验证](../quality/product-verification.md)和[Diff 审查](../quality/diff-review.md)验证。
## 常见文件{#files}
| 文件 | 用途 |
| --- | --- |
| `.dash` | 仪表板和可视化分析。 |
| `.tbl` | 数据模型。 |
| `.query` | 查询 DSL 或数据准备。 |
| `.theme` | 主题或样式资源。 |
| `.ts`、`.js` | 前端脚本或交互逻辑。 |
## AI 修改前{#before}
明确告诉 AI：
1. 看板主题和目标用户。
2. 指标口径、过滤条件和数据粒度。
3. 图表类型、布局和交互要求。
4. 数据模型或查询是否允许修改。
5. 是否需要保持现有主题和组件风格。
## 推荐流程{#workflow}
1. 先让 AI 列出候选数据模型、查询和已有看板。
2. 确认指标口径和字段来源。
3. 修改 `.dash` 中的数据集、组件和布局。
4. 必要时小步修改 `.tbl` 或 `.query`。
5. 检查引用路径、字段名和组件 ID。
6. 推送测试服务器，在浏览器中验证图表显示和筛选交互。
## 验证重点{#validation}
1. 指标数值与口径一致。
2. 过滤条件、联动和默认值正确。
3. 图表无空白、无脚本错误、无字段缺失。
4. 主题、布局和移动端显示符合要求。
5. 修改没有影响其他页面或报表引用同一模型的行为。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/report/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/report"
title: "构建报表"
---
---
title: 构建报表
description: 组织 AI 辅助完成报表、填报、参数、取数、打印、导出、模板和主题任务。
navTitle: 构建报表
indexTitle: 概述
---
# 构建报表
构建报表用于处理统计表、明细表、复杂表样、填报表样、参数栏、取数、浮动、分组、打印、导出、模板和主题等任务。报表填报暂不单独设任务目录，先在这里承接。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要创建或修改统计表、明细表、复杂表样、打印报表或导出报表。
- 需要配置报表参数、取数、浮动、分组、模板、主题或填报表样。
- 需要让 AI 检查报表依赖的数据模型、字段、参数和引用关系。
- 需要在产品中预览和验证报表样式、数据和导出效果。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 做报表 | [做报表](./make-report.md) | 创建或修改统计表、明细表、打印报表、导出报表或报表参数。 |
## 相关阅读
- [处理数据](../data/README.md)：先确认报表依赖的数据模型、查询、字段和过滤条件。
- [质量检查](../quality/README.md)：修改后检查 diff、引用关系、预览和产品运行效果。
- 相关产品手册：报表、报表填报和元数据中的 `.rpt`、`.fapp` 文件类型。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/report/make-report.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/report/make-report"
title: "做报表"
---
---
title: 做报表
navTitle: 做报表
---
# 做报表
“做报表”通常指创建或修改统计表、明细表、打印报表、导出报表或报表参数。AI 可以辅助生成结构和检查引用，但报表效果必须在产品中预览和验证。
## 阅读顺序{#reading-order}
1. 先读 [SuccApp 官方文档 Skill](../../../../SKILL.md) 中的 AI 低代码开发说明和[工作区中的 AI 协作文件](../basics/workspace.md#ai-files)，确认目标、环境、范围、禁区和验收方式。
2. 再读[元数据系统](../../meta/README.md)、[报表文件类型](../../meta/file-types/ana/rpt.md)和 [SuccApp Super JSON](../../meta/rules/super-json.md)。
3. 涉及取数时补充阅读[数据模型](../../meta/file-types/data/tbl.md)和[查询](../../meta/file-types/data/query.md)，并参考当前项目同类报表、参数和单元格配置。
4. 修改后检查报表预览、打印、导出、参数切换和引用关系，必要时按[产品验证](../quality/product-verification.md)和[Diff 审查](../quality/diff-review.md)验证。
## 常见文件{#files}
| 文件 | 用途 |
| --- | --- |
| `.rpt` | 报表。 |
| `.tbl` | 数据模型。 |
| `.query` | 查询或数据准备。 |
| `.spg` | 报表入口页或嵌入页面。 |
| `.ts`、`.action.ts` | 报表相关脚本。 |
## AI 修改前{#before}
明确告诉 AI：
1. 报表用途，是展示、打印还是导出。
2. 数据来源、统计口径、字段排序和分组方式。
3. 参数、过滤条件和默认值。
4. 是否允许修改模型或查询。
5. 需要验证的输出方式，例如网页预览、打印或 Excel 导出。
## 推荐流程{#workflow}
1. 让 AI 查找同类报表和数据模型。
2. 确认字段、参数、单元格区域和引用关系。
3. 小步修改 `.rpt`、`.tbl` 或 `.query`。
4. 检查 DTS、同类文件差异和元数据静态结构。
5. 推送测试服务器并预览报表。
6. 验证打印、导出、参数切换和权限数据范围。
## 验证重点{#validation}
1. 报表能打开并渲染。
2. 参数默认值和查询条件正确。
3. 分组、合计、排序和格式符合业务口径。
4. 打印和导出效果符合要求。
5. 大数据量场景下查询性能可接受。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/app/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/app"
title: "构建低代码应用"
---
---
title: 构建低代码应用
description: 组织 AI 辅助完成页面、业务应用、门户、程序流、工作流和移动端低代码应用任务。
navTitle: 构建低代码应用
indexTitle: 概述
---
# 构建低代码应用
构建低代码应用用于处理 SuperPage 页面、业务表单、门户入口、移动端页面、按钮交互、程序流、工作流和企业级业务应用等任务。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要创建或修改 SuperPage、模板页面、入口页或业务操作页面。
- 需要配置页面组件、按钮交互、事件、程序流或工作流入口。
- 需要让 AI 查找页面文件、生成组件结构或调整页面文案。
- 需要在产品界面或设计器中验证页面运行效果。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 做页面 | [做页面](./make-page.md) | 创建或修改 SuperPage、模板页面、报表填报应用、入口页或业务操作页面。 |
## 相关阅读
- [处理数据](../data/README.md)：先确认页面依赖的数据模型、查询和字段。
- [质量检查](../quality/README.md)：修改后检查 diff、引用关系、预览和产品效果。
- 相关产品手册：低代码应用、SuperPage、程序流、工作流、移动端和元数据中的 `.spg`、`.tpg`、`.afl` 文件类型。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/app/make-page.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/app/make-page"
title: "做页面"
---
---
title: 做页面
navTitle: 做页面
---
# 做页面
“做页面”通常指创建或修改 SuperPage、模板页面、报表填报应用、入口页或业务操作页面。AI 可以辅助查找文件、生成组件结构、调整文案和事件，但必须用产品页面或设计器验证效果。
## 阅读顺序{#reading-order}
1. 先读 [SuccApp 官方文档 Skill](../../../../SKILL.md) 中的 AI 低代码开发说明和[工作区中的 AI 协作文件](../basics/workspace.md#ai-files)，确认目标、环境、范围、禁区和验收方式。
2. 再读[元数据系统](../../meta/README.md)、[文件类型](../../meta/file-types/README.md)、[SuccApp Super JSON](../../meta/rules/super-json.md)。
3. 根据目标文件类型继续读 [SuperPage 页面](../../meta/file-types/views/spg.md)、[超级模板页面](../../meta/file-types/views/tpg.md) 或[报表填报应用](../../meta/file-types/views/fapp.md)。
4. 修改前参考当前项目同类页面、组件、数据集和相关 DTS；修改后按[引用检查](../quality/reference-check.md)、[产品验证](../quality/product-verification.md)和[Diff 审查](../quality/diff-review.md)验证。
## 先判断文件类型{#file-types}
常见文件包括：
| 文件 | 用途 |
| --- | --- |
| `.spg` | SuperPage 页面。 |
| `.tpg` | 超级模板页面。 |
| `.fapp` | 报表填报应用。 |
| `.afl`、`.wfl` | 页面动作、流程或工作流相关逻辑。 |
| `.ts`、`.js`、`.action.ts`、`.ftl` | 前端脚本、后端脚本和模板逻辑。 |
## AI 修改前{#before}
给 AI 的任务应说明：
1. 目标页面或业务入口。
2. 是否新建页面，还是修改已有页面。
3. 数据来源、字段、按钮、跳转和权限限制。
4. 不允许修改的范围，例如数据模型、流程、权限或生产配置。
5. 验证方式，例如打开哪个页面、执行哪个按钮或检查哪个字段。
## 推荐流程{#workflow}
1. 让 AI 先查找候选页面和同类文件，不要立即修改。
2. 确认目标文件、数据集、组件和动作范围。
3. 小步修改页面 JSON、脚本或 `.meta`。
4. 使用 DTS、同类文件和元数据静态检查确认结构。
5. 查看 SuccApp diff，确认没有无关格式化。
6. 推送测试服务器并打开页面预览。
7. 测试通过后提交 Git。
## 验证重点{#validation}
1. 页面能打开，没有 JSON 或脚本报错。
2. 参数、数据集和组件绑定正确。
3. 按钮、跳转、弹窗和动作流符合需求。
4. 引用的模型、图片、脚本和页面路径有效。
5. 权限和数据范围没有被误改。
相关验证方法见[引用检查](../quality/reference-check.md)、[产品验证](../quality/product-verification.md)和[Diff 审查](../quality/diff-review.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/permission/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/permission"
title: "管理权限"
---
---
title: 管理权限
description: 说明 AI 辅助配置和检查用户、用户组、资源权限和数据范围时的阅读入口。
navTitle: 管理权限
indexTitle: 概述
---
# 管理权限
管理权限用于处理给用户或用户组开权限、检查资源权限、配置数据范围、评审过度授权和解释“为什么看不到资源或数据”等任务。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要给用户、用户组或角色配置资源访问权限。
- 需要排查用户为什么看不到资源、页面、报表、数据或菜单。
- 需要配置或检查数据范围、组织范围和过度授权风险。
- 需要让 AI 整理权限任务的对象、环境、资源层级和人工确认点。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 权限管理 | [权限管理](../../../permission/README.md) | 了解用户、组织、角色、资源权限和数据范围等权限体系。 |
| 分配权限 | [分配权限](../../../permission/grant/README.md) | 给用户或用户组配置资源权限、数据范围和访问控制。 |
## 相关阅读
- [安全边界](../basics/safety.md)：权限和数据范围属于高风险配置，AI 不能替代人工确认。
- [产品验证](../quality/product-verification.md)：权限修改后应使用目标用户或等效账号验证访问结果。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/extension/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/extension"
title: "扩展平台能力"
---
---
title: 扩展平台能力
description: 组织 AI 辅助开发 SuccApp 平台扩展能力的任务入口。
navTitle: 扩展平台能力
indexTitle: 概述
---
# 扩展平台能力
扩展平台能力用于处理新数据库、新文件格式、新对象存储、新 AI 或语音平台、新组件、新布局、新程序流节点和表达式函数等平台级扩展任务。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要判断现有平台能力是否需要通过扩展实现。
- 需要了解数据库、文件格式、对象存储、AI 平台、组件或表达式函数的扩展方向。
- 需要让 AI 辅助整理扩展需求、影响范围和待确认接口。
- 需要确认当前扩展开发能力是否已经开放到可操作流程。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 扩展开发 | [扩展开发](./extension.md) | 了解 SuccApp 平台扩展开发能力的当前状态、适用边界和后续开放方向。 |
## 相关阅读
- [脚本开发](../../script/choose-script.md)：如果需求可以通过前端脚本、后端脚本、样式或程序流脚本节点完成，优先走脚本开发路径。
- [安全边界](../basics/safety.md)：涉及平台级能力、外部系统或生产环境时先确认风险边界。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/extension/extension.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/extension/extension"
title: "扩展开发"
---
---
title: 扩展开发
navTitle: 扩展开发
---
# 扩展开发
SuccApp 后续会提供面向产品扩展开发的能力，用于创建、调试和管理 SuccApp 产品扩展。当前扩展开发流程尚未完整开放，暂不提供完整的创建扩展、选择模板和发布扩展操作说明。
现阶段，可以先把扩展开发作为 AI 低代码开发的进阶方向：理解现有扩展资源、查看扩展模板能力、修改项目脚本，并在能力开放后再使用扩展打包和发布流程。
## 当前可使用能力{#available}
目前，项目成员可以使用 SuccApp 完成以下与二次开发相关的工作：
1. 克隆服务器项目到本地。
2. 修改元数据文件。
3. 修改前端脚本和后端脚本。
4. 使用 AI 辅助理解和修改元数据。
5. 将修改推送到测试服务器预览。
6. 将元数据纳入 Git 管理。
脚本相关内容请阅读：
1. [脚本开发](../../script/README.md)
## 推荐阅读{#related}
1. [AI 低代码开发](../README.md)
2. [修改、对比、拉取与推送](../workspace/sync-changes.md)
3. [使用 AI 修改元数据](../task-driven.md)
4. [SuccApp CLI](../basics/cli.md)
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot"
title: "排查问题"
---
---
title: 排查问题
description: 组织 AI 低代码开发中的同步冲突、登录失败、远端变化、丢失修改和运行异常排查任务。
navTitle: 排查问题
indexTitle: 概述
---
# 排查问题
排查问题用于处理“推不上去”“登录失败”“远端变化看不到差异”“修改丢了”“数据不对”“页面没反应”“调度没跑”这类阻塞交付的问题。排查前先保护现场，确认服务器、项目、本地变化和 Git 状态。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 推送、拉取、同步或登录被阻塞。
- 本地变化、远端变化、Git 状态或同步基线看起来不一致。
- 修改疑似丢失、被覆盖，或远端变化显示不出实际内容差异。
- 元数据文件在浏览器预览或设计器中报错，需要先用 CLI 校验本地内容。
- 页面、数据、权限或调度异常，需要先保护现场再定位问题。
## 任务入口
| 问题 | 先读 | 适用情况 |
| --- | --- | --- |
| 冲突处理 | [冲突处理](./conflict-handling.md) | 本地和服务器都修改了同一个资源，推送或拉取前需要判断保留哪一侧。 |
| 自动登录失败 | [自动登录失败](./auto-login-failed.md) | 每次打开工作区都需要重新认证，或服务器不再接受已保存的授权状态。 |
| 远端变化没有内容差异 | [远端变化没有内容差异](./remote-changes-no-diff.md) | SuccApp 显示远端变化，但文件正文看起来没有可见差异。 |
| 找回丢失修改 | [找回丢失修改](./recover-lost-changes.md) | 本地修改疑似被覆盖、被重置或找不到，需要先停止继续同步操作。 |
| 元数据合法性校验 | [元数据合法性校验](./metadata-validation.md) | AI 修改 `.dash`、`.spg`、`.tbl` 等元数据文件后，需要在推送或浏览器预览前检查本地内容是否能通过服务器编译。 |
## 相关阅读
- [修改与同步](../workspace/sync-changes.md)：理解拉取、推送、查看变化和同步基线。
- [Diff 审查](../quality/diff-review.md)：确认差异内容和风险范围。
- [元数据静态检查](../quality/metadata-check.md)：了解推送前的结构、类型、引用和编译检查组合。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/conflict-handling.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot/conflict-handling"
title: "冲突处理"
---
---
title: 冲突处理
navTitle: 冲突处理
---
# 冲突处理
冲突表示本地和服务器都修改了同一个资源，SuccApp 不能自动判断应保留哪一侧。AI 修改元数据后更容易出现“看起来只是格式化、实际覆盖了别人修改”的情况，处理冲突时不要急着推送，先看清两边分别改了什么。
## 什么情况下会产生冲突{#when}
常见场景包括：
1. 本地修改了某个文件，服务器上同一个文件也被其他人修改了。
2. 本地删除了文件，服务器上同一个文件被修改了。
3. 本地和服务器都修改了同一个目录级 `.meta` 中的资源元信息。
4. 拉取服务器变化时，SuccApp 无法自动合并两边内容。
如果只是服务器上有新变化，但本地没有修改同一个资源，通常不算冲突，可以直接拉取。
## 处理前检查{#before}
处理冲突前建议先确认：
1. 当前连接的是测试服务器还是生产服务器。
2. Git 中是否已经提交或暂存本地重要修改。
3. Changes 视图中哪些文件带有冲突标记。
4. 服务器上的变化是谁产生的、是否需要保留。
5. 本次任务是否允许覆盖服务器变化。
生产环境出现冲突时，应暂停操作并联系项目负责人确认。
## 查看本地和服务器差异{#diff}
可以通过 Changes 视图打开冲突文件的差异对比。检查时重点看：
1. 本地修改是否属于本次任务。
2. 服务器修改是否属于其他成员的有效修改。
3. 是否有误删、格式化噪声或目录级 `.meta` 异常变化。
4. 两边修改能否同时保留。
如果无法判断业务含义，不要直接选择覆盖，应先和相关成员确认。
## 选择处理方式{#resolution}
冲突通常有三种处理方式：
| 方式 | 适用场景 |
| :--- | :--- |
| 保留本地版本 | 确认本地修改应覆盖服务器当前内容 |
| 采用服务器版本 | 确认服务器内容正确，本地修改不再需要 |
| 手工合并 | 本地和服务器两边修改都需要保留 |
正式项目中，建议优先通过人工判断和 Git 记录确认来源，不要只看文件时间决定保留哪一侧。
## 手工合并冲突标记{#markers}
拉取发生冲突时，文件内容中可能出现类似标记。下面示例为了避免被 Git 误判为未处理冲突，在标记行前加了一个空格；实际文件中标记通常位于行首。
```text
<<<<<<< Local
本地内容
=======
服务器内容
>>>>>>> Remote
```
处理步骤：
1. 打开对应文件。
2. 判断最终应该保留的内容。
3. 删除冲突标记，例如以连续小于号、连续等号或连续大于号开头的行。
4. 保留最终需要生效的内容。
5. 保存文件。
6. 刷新 SuccApp 同步状态。
包含未解决冲突标记的文件不能继续 push。这样可以避免把冲突文本推送到服务器。
## 处理后检查{#after}
冲突处理完成后，请检查：
1. 文件中没有残留冲突标记。
2. Changes 视图中没有未处理冲突。
3. diff 结果符合最终决定。
4. 可以在测试服务器推送并验证。
5. Git 提交信息说明了冲突处理结果。
如果处理过程中发现本地修改不应继续保留，可以通过 SuccApp 放弃修改，或通过 Git 回退本地文件。两者区别请阅读[修改、对比、拉取与推送](../workspace/sync-changes.md#discard)。
## 推荐做法{#recommended}
多人协作项目中，建议遵守：
1. 开始工作前先拉取 Git 和服务器变化。
2. 避免多人同时修改同一个元数据文件。
3. push 被远端变化阻止时先看差异，不直接强制推送。
4. 合并冲突后先推送测试环境验证，再提交 Git。
5. 生产环境冲突必须走发布负责人确认。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/auto-login-failed.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot/auto-login-failed"
title: "为什么打开工作区后不能自动登录"
---
---
title: 为什么打开工作区后不能自动登录
navTitle: 自动登录失败
---
# 为什么打开工作区后不能自动登录
SuccApp 登录成功后会保存本机认证状态，后续打开同一个工作区时会尝试自动连接服务器。如果每次打开都需要重新认证，通常不是本地项目文件损坏，而是服务器已经不再接受上次保存的 OAuth2 授权状态或 PAT。
## 常见原因{#reasons}
常见原因包括：
1. OAuth2 refresh token 已失效，或 PAT 已过期。
2. PAT 被用户或管理员撤销、禁用。
3. 用户状态、权限或登录安全策略发生变化。
4. 服务器认证配置升级后，要求重新授权。
5. 当前工作区切换到了另一个服务器地址，或服务器地址写法不同，例如端口不同、域名和 IP 混用。
6. 当前系统用户、远程开发环境或认证配置目录发生变化，导致 SuccApp 读不到之前保存的认证状态。
::: tip 提示
SuccApp 只在本地工作区配置中保存服务器地址，不保存 PAT、OAuth2 access token 或 refresh token。认证状态保存在本机 SuccApp 认证文件中，应避免提交到 Git 仓库。
:::
## 为什么 token 会失效{#token-expired}
SuccApp 和浏览器访问的是同一个 SuccApp 服务器，但 SuccApp 不复用浏览器 Cookie。默认 OAuth2 登录会保存短期 access token 和可轮换的 refresh token；access token 过期时 SuccApp 会自动刷新。refresh token 失效、PAT 过期或撤销、对应用户状态变化后，SuccApp 下次自动连接服务器时会被拒绝，并要求重新认证。
## 怎么处理{#solutions}
遇到自动登录失败时，可以按以下顺序处理：
1. 在 SuccApp 中执行 **SuccApp: 登录服务器**（英文界面为 **SuccApp: Login Server**）。
2. 确认当前工作区连接的是正确服务器地址，特别是协议、域名、IP 和端口是否一致。
3. 如果服务器地址或端口确实发生了变化，执行 **SuccApp: 设置服务器地址**（英文界面为 **SuccApp: Set Server URL**）。该命令会先验证新地址可以登录，再迁移本地服务器基线，最后更新配置；不会修改工作区中的项目文件。
4. 如果同一个账号同时用于测试脚本和 SuccApp，建议分别创建用途明确的 PAT，并设置合适的有效期。
5. 如果团队经常需要多端同时使用 SuccApp，请联系管理员检查 PAT、OAuth2 refresh token 和用户安全策略。
6. 如果重新认证后仍马上失效，检查服务器日志中是否存在 token 被拒绝、用户被禁用或权限不足记录。
重新认证不会删除服务器配置，也不会修改本地项目文件。服务器连接和登录服务器的入口，请阅读[连接服务器与下载元数据](../workspace/connect-and-clone.md#login)。
## 管理员可以检查什么{#admin-check}
管理员可以重点检查：
1. PAT 是否已过期、禁用或被撤销。
2. OAuth2 refresh token 的有效期和轮换策略是否符合团队使用方式。
3. 用户是否被禁用、移除权限或切换了用户目录。
4. 是否有测试脚本、压测工具或其他自动化任务复用了同一个 PAT。
5. 服务器日志中是否存在 token 校验失败、用户状态异常或权限不足记录。
如果现场有安全合规要求，不建议单纯为了减少重新认证而放宽 token 策略。可以优先使用专用账号、为不同自动化任务创建独立 PAT，或让 SuccApp 用户和自动化任务使用不同账号。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/remote-changes-no-diff.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot/remote-changes-no-diff"
title: "为什么远端变化打开 diff 看不到内容差异"
---
---
title: 为什么远端变化打开 diff 看不到内容差异
navTitle: 远端变化没有内容差异
---
# 为什么 Changes 视图里有很多远端变化，但打开 diff 看不到内容差异
这通常不是本地文件被误改了，而是服务器当前状态和 SuccApp 本地同步基线不一致。SuccApp 会把这类差异显示为远端变化，即使文件正文看起来没有可见差异。
## 先看变化方向{#direction}
Changes 视图中有两类常见变化：
| 变化方向 | 对比对象 | 含义 |
| :--- | :--- | :--- |
| 本地变化 | 工作区文件 vs 本地 mirror | 本地文件相对上次同步基线发生了变化 |
| 远端变化 | 服务器当前内容 vs 本地 mirror | 服务器相对上次同步基线发生了变化 |
如果变化显示在远端变化分组中，说明 SuccApp 认为服务器比本地 mirror 更新。它不表示工作区文件一定被修改。
## 为什么 diff 可能看不到差异{#why}
SuccApp 检测远端变化时，为了避免每次刷新都下载大量服务器文件，不会对所有远端文件正文做完整内容对比。它主要根据服务器返回的资源版本、修改时间和元数据判断服务器是否变化。
因此可能出现以下情况：
1. 服务器重新保存、升级或批量处理了资源，推进了文件版本或修改时间，但文件正文没有实际变化。
2. 服务器只更新了 `.meta` 中的资源标识、版本、修改人、修改时间等同步字段。
3. 文件内容发生了格式等价的重写，打开文本 diff 时看不出业务差异。
4. 本地 mirror 还是旧基线，服务器已经被其他人、浏览器设计器、脚本或环境同步流程更新过。
这时 Changes 视图会提示远端变化，但打开 diff 可能没有可见内容差异。
## 应该如何处理{#handle}
建议按以下顺序处理：
1. 先刷新 SuccApp 同步状态，确认变化仍然存在。
2. 确认这些变化是远端变化，不是本地变化或冲突。
3. 打开几个代表性文件的 diff，确认是否真的没有可见内容差异。
4. 如果服务器变化需要同步到本地，执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。
5. 再次执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），确认变化列表符合预期。
::: warning 注意
不要为了清空远端变化直接强制推送。远端变化表示服务器当前状态和本地基线不一致，生产环境或多人协作场景中，应先确认变化来源。
:::
## 什么时候需要继续排查{#troubleshoot}
如果出现大量远端变化，且不确定来源，可以继续检查：
1. 最近是否有人在浏览器设计器中保存过相关资源。
2. 是否执行过元数据升级、初始化、导入导出或环境同步脚本。
3. 当前工作区是否刚切换过服务器地址或连接到另一个环境。
4. 是否在生产发布前还没有连接生产服务器并刷新变化。
需要定位具体原因时，可以在 Output 面板的 SuccApp 日志通道中把日志级别切到 **Debug**，再刷新变化。日志中会记录远端变化的路径、类型、服务器版本、mirror 版本、修改时间和修改人，便于判断是内容变化、元数据变化，还是仅同步基线落后。
更多同步模型和操作说明，请阅读[修改、对比、拉取与推送](../workspace/sync-changes.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/recover-lost-changes.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot/recover-lost-changes"
title: "不小心把我的修改搞丢了，怎么找回来"
---
---
title: 不小心把我的修改搞丢了，怎么找回来
navTitle: 找回丢失修改
---
# 不小心把我的修改搞丢了，怎么找回来
先不要继续 push、pull 或重置项目。越早停止操作，找回修改的可能性越高。
## 先确认丢失范围{#scope}
先确认：
1. 丢失的是本地文件修改，还是服务器上的修改。
2. 文件是否已经提交过 Git。
3. 文件是否曾经推送到服务器。
4. 是否执行过拉取、放弃修改、从服务器重置本地项目或 Git 回退。
## 按顺序查找{#steps}
建议按以下顺序找回：
1. 查看 Git 历史和本地未提交记录。
2. 查看 VS Code 本地文件历史。
3. 查看 SuccApp 文件历史，确认服务器是否曾保存过对应版本。
4. 检查 `.succapp/merge-backup/` 中是否有合并前备份。
5. 检查 `.succapp/remote/` 中的服务器基线是否仍保留旧内容。
::: warning 注意
`.succapp/remote/` 是同步基线，不是正式备份目录。只在排查时参考，不建议直接编辑其中内容。
:::
## 已提交 Git 的修改{#git}
如果修改已经提交到 Git，可以通过 Git 历史找回。找回后刷新 SuccApp 同步状态，再决定是否推送到服务器。
常用排查方式：
```bash
git status
git log --oneline --decorate -- path/to/file
git show :path/to/file
git reflog
```
建议先用 `git show` 查看历史内容，确认是需要的版本后再恢复到工作区。恢复时优先复制需要的片段，避免整文件覆盖掉当前有效修改。需要回退整文件时，先和项目负责人确认风险。
## 已推送到服务器的修改{#server-history}
如果修改曾经推送到服务器，可以在服务器文件历史中查找对应版本。找到后先对比内容，再决定是否恢复。
在 SuccApp 中可以按下面顺序排查：
1. 在项目树中选中目标文件。
2. 打开文件历史或服务器历史视图。
3. 找到丢失前的版本。
4. 先使用对比功能确认差异。
5. 将需要恢复的内容保存到本地工作区。
6. 刷新变化视图，确认恢复后的差异只包含目标内容。
不要在未对比的情况下直接覆盖服务器版本。多人协作时，先确认服务器上是否已经有其他人的新修改。
## 刚刚拉取或处理冲突后丢失{#merge-backup}
如果是在 pull 或冲突处理后发现内容丢失，可以检查 `.succapp/merge-backup/` 是否保存了合并前的本地文件备份。
`.succapp/merge-backup/` 用于保存部分同步或合并操作前的本地备份。恢复时按下面方式处理：
1. 先复制 `.succapp/merge-backup/` 中疑似相关文件到临时目录。
2. 用 VS Code 或 diff 工具和当前工作区文件对比。
3. 只把确认需要的片段合并回正式文件。
4. 保存后刷新 SuccApp 变化视图。
5. 验证无误后再提交 Git 或推送服务器。
不要直接把整个 `.succapp/merge-backup/` 目录复制回项目目录。备份文件可能对应旧基线，也可能只适合人工对比。
## 找回后怎么做{#after}
找回后建议：
1. 先保存到本地文件。
2. 刷新 SuccApp 同步状态。
3. 查看 diff，确认只恢复了需要的内容。
4. 推送测试服务器验证。
5. 提交 Git。
如果不确定应该恢复哪个版本，先联系项目负责人，不要直接覆盖服务器。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/troubleshoot/metadata-validation.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/troubleshoot/metadata-validation"
title: "如何校验元数据文件的合法性"
---
---
title: 如何校验元数据文件的合法性
description: 说明 AI 修改 SuccApp 元数据文件后，如何使用 SuccApp CLI 把本地内容发送到服务器编译校验，并根据错误信息定位问题。
navTitle: 元数据合法性校验
---
# 如何校验元数据文件的合法性
AI 修改 `.dash`、`.spg`、`.tbl`、`.rpt` 等元数据文件后，如果不想等到浏览器预览时才发现表达式、组件配置或模型结构错误，可以先用 SuccApp CLI 做一次服务器编译校验。校验会把本地文件内容发送到当前服务器编译，不保存文件，也不修改服务器上的元数据内容。
## 适用场景{#scenarios}
遇到以下情况时，先做元数据合法性校验：
1. AI 修改了仪表板、页面、报表、模型、表单或主题等 JSON 元数据文件。
2. 浏览器预览或设计器打开时报错，需要在终端里拿到结构化错误信息。
3. 推送测试服务器前，希望先拦截 JSON 语法、版本升级、表达式和编译阶段的错误。
4. 需要让 AI Agent 读取 `--json` 结果并继续修复文件。
图片、附件、普通脚本和非 JSON 文件不适合使用这个命令校验。它也不能证明业务口径、数据结果、权限和页面交互一定正确。
## 前置条件{#prerequisites}
执行校验前确认：
1. 当前目录在 SuccApp 工作区内。
2. 工作区已经配置活跃服务器，并已完成登录。
3. 要校验的文件在本地工作区中存在。
4. 文件路径属于当前服务器已知的元数据项目范围。
如果还没有准备工作区，先阅读[连接服务器与下载元数据](../workspace/connect-and-clone.md)。
## 执行校验{#run}
在工作区根目录或子目录执行：
```bash
succapp workspace file compile path/to/file.dash
```
也可以一次校验多个文件：
```bash
succapp workspace file compile path/to/page.spg path/to/model.tbl
```
需要给 AI Agent 或脚本读取时，使用 JSON 输出：
```bash
succapp workspace file compile path/to/file.dash --json
```
命令会读取本地文件内容，按文件路径确定服务器上的元数据类型和编译上下文，然后调用服务器编译逻辑。服务器会先按当前版本尝试升级传入内容，再执行对应的编译校验。
::: tip 提示
`workspace file compile` 不会把本地内容保存到服务器。校验通过后，仍然需要执行 `succapp workspace push `，浏览器预览才能看到本地修改后的服务器版本。
:::
## 查看校验结果{#result}
校验通过时，结果会显示通过文件数和失败文件数。校验失败时，CLI 会返回非 0 退出码，并展示失败文件、编译器和错误信息。
JSON 输出中重点看这些字段：
| 字段 | 说明 |
| :--- | :--- |
| `summary.files` | 本次校验的文件数量。 |
| `summary.passed` | 通过校验的文件数量。 |
| `summary.failed` | 未通过校验的文件数量。 |
| `items[].remotePath` | 文件对应的服务器元数据路径。 |
| `items[].type` | 服务器识别到的元数据类型，例如 `dash`、`spg`、`tbl`。 |
| `items[].compiler` | 本次使用的编译器，常见为 `nodejs` 或 `java`。 |
| `items[].success` | 当前文件是否通过编译校验。 |
| `items[].errorInfo` | 服务器返回的结构化错误信息。 |
`success: false` 表示文件内容没有通过校验。此时命令退出码非 0 是预期行为，不要把它当作 CLI 连接失败或程序崩溃。
## 根据错误修复{#fix}
定位问题时按以下顺序看：
1. 先看 `items[].remotePath`，确认是哪一个文件失败。
2. 再看 `items[].errorInfo.message`、`errorCode` 或 `className`，确认错误类型。
3. 如果 `errorInfo.locationPath` 中包含文件路径、组件、字段或表达式位置，优先按该位置检查。
4. 修改本地文件后重新执行 `succapp workspace file compile `。
5. 校验通过后，再执行 `succapp workspace push ` 并打开浏览器验证。
常见修复方向：
| 错误现象 | 处理方向 |
| :--- | :--- |
| JSON 解析失败 | 检查逗号、引号、括号、注释和文件编码。 |
| 版本升级失败 | 对照同类文件或先执行 `succapp workspace file upgrade --dry-run `。 |
| 表达式报错 | 检查参数、字段名、函数名、运算符和字符串引号。 |
| 组件或布局配置报错 | 对照同类型页面、仪表板或报表中的组件结构。 |
| 模型结构报错 | 检查 `.tbl` 的模型类型、字段、维键、度量、数据源和物理表配置。 |
## 校验通过后还要做什么{#after}
元数据合法性校验只说明文件能通过服务器编译。继续交付前还需要：
1. 用 [Diff 审查](../quality/diff-review.md) 确认修改范围。
2. 用 [引用检查](../quality/reference-check.md) 确认资源、字段、数据集和脚本引用没有被破坏。
3. 执行 `succapp workspace push ` 推送到测试服务器。
4. 按[预览文件](../quality/preview-file.md)在浏览器或设计器中验证运行效果。
5. 关键业务流程继续做[产品验证](../quality/product-verification.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality"
title: "质量检查"
---
---
title: 质量检查
description: 说明 AI 修改 SuccApp 元数据后的变化评审、diff 审查、元数据静态检查、引用检查、产品验证和风险评审方法。
navTitle: 质量检查
indexTitle: 概述
---
# 质量检查
质量检查用于判断 AI 修改是否符合需求、是否影响无关范围，以及是否可以进入提交、协作评审或发布流程。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- AI 已经修改元数据，需要判断改动是否符合需求。
- 需要检查 diff、引用关系、元数据结构、预览结果或产品运行效果。
- 需要在推送测试、提交 Git、协作评审或发布生产前做风险确认。
- 需要把 AI 总结转换为可人工复核的检查清单。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 评审变化 | [评审变化](./review-changes.md) | 综合检查 SuccApp 同步差异、Git diff、元数据结构、引用关系和产品效果。 |
| Diff 审查 | [Diff 审查](./diff-review.md) | 确认 AI 修改范围是否符合需求，是否包含无关格式化或覆盖风险。 |
| 元数据静态检查 | [元数据静态检查](./metadata-check.md) | 在推送测试前检查 JSON 语法、文件类型、关键字段、DTS 类型和引用路径。 |
| 引用检查 | [引用检查](./reference-check.md) | 确认文件、字段、组件、数据集、动作节点、图片、模型、页面、权限和脚本关系没有被破坏。 |
| 预览文件 | [预览文件](./preview-file.md) | 需要理解本地文件、服务器版本、浏览器预览和设计器验证之间的关系。 |
| 产品验证 | [产品验证](./product-verification.md) | 在 SuccApp 运行环境中确认页面、报表、看板、流程和数据结果真正生效。 |
## 相关阅读
- [修改与同步](../workspace/sync-changes.md)：把本地修改同步到测试服务器前后，配合检查差异和远端变化。
- [管理发布](../release/README.md)：质量检查通过后，继续走团队协作、测试到生产发布和回退流程。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/review-changes.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/review-changes"
title: "评审变化"
---
---
title: 评审变化
navTitle: 评审变化
---
# 评审变化
AI 修改完成后，必须评审变化范围和风险。评审不是只看 AI 的总结，而是同时检查 SuccApp 同步差异、Git diff、元数据静态结构、引用关系和产品运行效果。
## 阅读顺序{#reading-order}
1. 先读 [SuccApp 官方文档 Skill](../../../../SKILL.md) 中的 AI 低代码开发说明、[工作区中的 AI 协作文件](../basics/workspace.md#ai-files)和本次任务的需求说明，确认原始目标与验收标准。
2. 再读 [Diff 审查](./diff-review.md)、[元数据静态检查](./metadata-check.md)、[引用检查](./reference-check.md)和[产品验证](./product-verification.md)。
3. 涉及具体文件类型时，回到对应任务页阅读验证重点，例如[做页面](../app/make-page.md)、[做看板](../analytics/make-dashboard.md)、[做报表](../report/make-report.md)、[准备数据](../data/prepare-data.md)或[判断是否需要脚本](../../script/choose-script.md)。
4. 涉及发布生产时，继续阅读[发布到生产环境](../release/release-to-prod.md)，不要只凭本地 diff 下结论。
## 评审输入{#inputs}
评审前准备：
1. 用户需求和验收标准。
2. AI 修改说明和文件清单。
3. `succapp workspace status` 或 Changes 视图。
4. SuccApp diff。
5. Git diff。
6. 产品页面、设计器或脚本日志验证结果。
## 推荐流程{#workflow}
1. 先确认当前连接的是测试服务器。
2. 查看 SuccApp Changes，确认本地变化、远端变化和冲突。
3. 逐个打开 diff，检查是否只改了需求相关内容。
4. 查看 Git diff，确认没有运行时文件、临时文件和无关格式化。
5. 检查 `.meta`、引用路径、字段名、组件 ID、数据集 ID 和动作节点 ID。
6. 推送测试服务器并验证效果。
7. 需要发布生产时，按[发布到生产环境](../release/release-to-prod.md)执行。
## 风险清单{#risks}
重点关注：
1. 大范围格式化导致真实修改难以识别。
2. 误删 `.meta` 或资源文件。
3. 修改稳定字段名、组件 ID、数据集 ID、动作节点 ID。
4. 修改权限、流程、数据范围或系统配置。
5. 生成不存在的引用路径。
6. SQL 或脚本只验证了成功路径。
7. 只在本地检查，没有推送测试服务器验证。
## 交付结论{#result}
评审结论建议包含：
1. 修改了哪些业务能力。
2. 关键文件清单。
3. 已完成的验证。
4. 已知风险和限制。
5. 是否可以提交 Git 或进入发布流程。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/diff-review.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/diff-review"
title: "Diff 审查"
---
---
title: Diff 审查
navTitle: Diff 审查
---
# Diff 审查
Diff 审查用于确认 AI 修改范围是否符合需求。正式项目中，推送测试、提交 Git 和发布生产前都应检查 diff。
## 看哪几类 diff{#types}
| Diff | 说明 |
| --- | --- |
| SuccApp 本地变化 diff | 本地文件相对服务器基线的变化，决定推送测试服务器的内容。 |
| SuccApp 远端变化 diff | 服务器相对本地 mirror 的变化，决定是否需要先拉取或处理冲突。 |
| Git diff | 本地文件相对 Git 版本的变化，决定提交和评审内容。 |
| 文件历史 diff | 当前版本与服务器历史版本的差异，适合排查回退和丢失修改。 |
SuccApp diff 和 Git diff 关注的问题不同，不能互相替代。
## 审查重点{#checkpoints}
1. 是否只修改了需求相关文件。
2. 是否出现无关格式化、大段重排或排序变化。
3. 是否误删目录级 `.meta`、资源文件或脚本。
4. 是否修改了稳定标识，例如字段名、组件 ID、数据集 ID、动作节点 ID。
5. 是否修改了权限、流程、数据范围、数据源或系统设置。
6. 是否包含 `.succapp/remote/`、缓存、日志、临时文件或未确认的 AI 草稿。
7. 是否有远端变化或冲突未处理。
## CLI 和 VS Code 用法{#usage}
CLI:
```bash
succapp workspace status
succapp workspace status --json
succapp workspace file diff path/to/file
git diff
```
VS Code:
1. 打开 SuccApp **变化** 视图。
2. 点击变化文件或选择 **与服务器版本对比**。
3. 打开 Git 视图检查 Git diff。
4. 对高风险文件查看服务器文件历史。
## AI 自查提示词{#prompt}
```text
请审查当前本地变化，按文件说明修改原因。
重点检查是否有无关格式化、误删、.meta 异常、稳定 ID 变化、权限/流程/数据范围风险。
不要继续修改文件。
```
AI 的自查结论只能作为参考，最终仍应由项目成员查看 diff。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/metadata-check.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/metadata-check"
title: "元数据静态检查"
---
---
title: 元数据静态检查
navTitle: 元数据静态检查
---
# 元数据静态检查
元数据静态检查用于在推送测试服务器前发现明显结构问题，例如 JSON 语法错误、文件类型不匹配、关键字段缺失、DTS 类型不一致、引用路径异常和脚本入口配置错误。它适合在 AI 修改后快速拦截低级错误，但不能替代产品验证。
## 检查依据{#source}
静态检查通常结合以下依据：
1. 元数据手册中的文件类型、通用结构、`.meta` 和引用路径说明。
2. [`/dev-types/`](../../../../dev-types/index.json) 中发布的 DTS 类型声明。
3. 当前工作区中的同类文件和历史写法。
4. SuccApp CLI 当前可用的工作区检查能力。
5. SuccApp CLI 的服务器编译校验能力，用于检查 JSON 配置、表达式等元数据语义。
## 使用方式{#usage}
常见检查方式：
1. 在 VS Code 中打开元数据文件，查看 JSON 语法、类型提示和编辑器诊断。
2. 执行 **SuccApp: 初始化工作区**，刷新类型声明和编辑器辅助配置。
3. 使用 `succapp workspace repair --dry-run --only=workspace-support` 检查推荐设置是否缺失。
4. 对旧版本元数据先执行 `succapp workspace file upgrade --dry-run` 查看升级候选。
5. 对需要编译的元数据文件执行 `succapp workspace file compile `，把本地内容发送到当前服务器做编译校验。
6. 执行 `succapp workspace repair --dry-run` 预演工作区结构、本地同步基线和同步状态修复。
## 局限{#limits}
静态检查不能证明：
1. 引用路径一定存在。
2. 字段名、组件 ID、数据集 ID 一定被正确引用。
3. SQL、脚本、表达式和权限配置运行正确。
4. 产品设计器一定能按预期渲染。
5. 业务口径和客户需求正确。
因此静态检查通过后，还要继续做[引用检查](./reference-check.md)、[产品验证](./product-verification.md)和[Diff 审查](./diff-review.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/reference-check.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/reference-check"
title: "引用检查"
---
---
title: 引用检查
navTitle: 引用检查
---
# 引用检查
引用检查用于确认 AI 修改没有破坏文件、字段、组件、数据集、动作节点、图片、模型、页面、权限和脚本之间的关系。
## 常见引用{#references}
| 引用 | 常见位置 |
| --- | --- |
| 文件路径 | `referenceResources`、跳转动作、数据集路径、模板引用。 |
| 字段名 | `.tbl`、`.query`、数据集过滤、报表单元格、脚本。 |
| 组件 ID | 页面事件、联动、表达式、状态保存。 |
| 数据集 ID 或名称 | 组件绑定、过滤条件、脚本、报表区域。 |
| 动作节点 ID | `.afl`、页面事件、流程节点参数。 |
| `.meta` | 目录直接子资源的描述、排序、资源 ID 和同步关系。 |
## 检查方法{#methods}
1. 修改文件名、字段名、组件 ID 或数据集 ID 前，先全局搜索旧值。
2. 修改 `referenceResources` 后，确认 `targetPath` 指向的文件存在。
3. 新增或删除文件后，检查所在目录的 `.meta`。
4. 修改模型字段后，检查页面、报表、查询、权限和脚本引用。
5. 修改动作节点后，检查入口、参数传递和错误处理。
6. 使用产品设计器打开页面、报表或程序流，检查是否有缺失引用提示。
## AI 提示词{#prompt}
可以让 AI 做一次引用自查：
```text
请检查当前修改是否影响引用关系。
重点看 referenceResources、.meta、字段名、组件 ID、数据集 ID、动作节点 ID 和脚本调用。
只输出风险和需要人工确认的文件，不要继续修改。
```
## 常见风险{#risks}
1. 改了显示名，同时误改稳定字段名。
2. 复制组件后没有调整组件 ID。
3. 删除文件后，所在目录 `.meta` 中的对应条目或引用路径仍保留。
4. 移动页面后跳转或图片引用失效。
5. 改模型字段后，报表和脚本仍引用旧字段。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/preview-file.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/preview-file"
title: "预览文件"
---
---
title: 预览文件
description: 说明 AI 修改 SuccApp 元数据文件后，如何编译、推送并在浏览器或设计器中打开服务器版本。
navTitle: 预览文件
---
# 预览文件
浏览器、预览页和设计器打开的是服务器上的元数据版本，不是本地工作区文件。AI 修改本地文件后，需要先把文件同步到测试服务器，再打开页面验证。
## 推荐顺序{#flow}
1. 编译：先执行 `succapp workspace file compile `，校验当前文件或相关文件是否能通过服务器编译。
2. 推送：编译通过后执行 `succapp workspace push `，把本地修改提交到测试服务器。
3. 打开：推送成功后执行 `succapp workspace file open `，在浏览器中验证服务器版本。
```bash
succapp workspace file compile path/to/file.dash
succapp workspace push path/to/file.dash
succapp workspace file open path/to/file.dash
```
## 打开方式{#open}
| 场景 | 命令 |
| --- | --- |
| 打开页面、仪表板、报表或应用的运行效果 | `succapp workspace file open ` |
| 打开设计器或编辑页 | `succapp workspace file open --edit ` |
| 只查看本地路径、服务器路径和浏览器 URL | `succapp workspace file resolve ` |
| 只输出可分享的查看 URL | `succapp workspace file resolve --url=view` |
| 只输出可分享的编辑 URL | `succapp workspace file resolve --url=edit` |
## 本地变化提示{#local-changes}
本地新增文件还没有 push 时，服务器上没有对应资源，浏览器可能返回 404。本地修改文件还没有 push 时，浏览器看到的是服务器旧版。
`succapp workspace file open ` 会在打开前检查本地文件和同步状态。如果本地有未推送变化，先 push 再 open；只有明确需要打开服务器旧版排查问题时，才使用：
```bash
succapp workspace file open --force
```
更多产品运行效果检查见[产品验证](./product-verification.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/quality/product-verification.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/quality/product-verification"
title: "产品验证"
---
---
title: 产品验证
navTitle: 产品验证
---
# 产品验证
产品验证用于确认元数据修改在 SuccApp 运行环境中真正生效。AI 和静态检查只能辅助判断，最终仍要用产品界面、设计器、日志和业务流程验证。
## 验证入口{#entries}
| 修改类型 | 验证入口 |
| --- | --- |
| 页面、表单、模板 | 打开服务器视图或编辑页，完成核心操作。 |
| 仪表板 | 打开看板，检查图表、筛选、联动和指标数值。 |
| 报表 | 打开报表，检查参数、分页、打印和导出。 |
| 数据模型 | 打开建模或依赖页面，检查字段、查询和权限。 |
| 程序流、工作流 | 触发入口动作，检查节点执行和错误处理。 |
| 前端脚本 | 浏览器 DevTools、页面交互和控制台错误。 |
| 后端脚本 | 系统控制台、脚本日志、批处理结果和返回结构。 |
## 使用 SuccApp 打开页面{#open}
在 SuccApp for VS Code 中，可以通过本地文件菜单或 Changes 视图选择 **打开服务器视图** 或 **打开服务器编辑页**。
在 CLI 中，可以使用：
```bash
succapp workspace file resolve path/to/file.spg
succapp workspace file open path/to/file.spg
succapp workspace file open --edit path/to/file.spg
```
## 验证清单{#checklist}
1. 页面或报表能打开。
2. 核心业务流程能完成。
3. 数据口径、字段显示和过滤条件正确。
4. 浏览器控制台和系统日志无新增异常。
5. 权限、数据范围和生产配置没有被误改。
6. 测试结果已记录到 Git 提交、评审说明或发布说明中。
如果验证失败，应先定位是元数据结构、引用、脚本、数据、权限还是缓存问题，再让 AI 小步修复。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/release/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/release"
title: "管理发布"
---
---
title: 管理发布
description: 组织 AI 低代码开发中的团队协作、Git 提交、测试到生产发布、生产验证和回退任务。
navTitle: 管理发布
indexTitle: 概述
---
# 管理发布
管理发布用于处理多人协作、Git 提交、团队评审、测试到生产同步、生产验证和回退方案。涉及生产环境时，应先确认 Git 版本、测试结果、影响范围、回退方案和人工确认点。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要多人协作处理同一个 SuccApp 项目或同一批元数据修改。
- 需要约定 AI 可修改范围、Git 提交、评审方式和同步顺序。
- 需要把测试环境验证通过的修改发布到生产环境。
- 需要在生产发布前确认影响范围、回退方案和人工确认点。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| 协作规范 | [协作规范](./team-collaboration.md) | 约定团队分工、同步顺序、AI 修改范围、Git 提交和生产发布规则。 |
| 发布生产 | [发布生产](./release-to-prod.md) | 将测试环境确认过的 Git 版本同步到生产环境，并安排生产验证和回退方案。 |
## 相关阅读
- [质量检查](../quality/README.md)：发布前检查 diff、元数据结构、引用关系和产品验证结果。
- [安全边界](../basics/safety.md)：生产发布、覆盖远端和回退操作必须保留人工确认。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/release/team-collaboration.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/release/team-collaboration"
title: "项目团队协作规范"
---
---
title: 项目团队协作规范
navTitle: 协作规范
---
# 项目团队协作规范
SuccApp 让多人可以像管理代码一样管理元数据。AI 加入后，团队更需要约定清楚分工、同步顺序、AI 可修改范围、Git 提交和生产发布规则，避免互相覆盖、发布错误和版本混乱。
## 角色分工{#roles}
项目团队中常见角色如下：
| 角色 | 职责 |
| :--- | :--- |
| 项目负责人 | 确认需求范围、评审变更、决定生产发布 |
| 项目成员 | 修改元数据、验证功能、提交 Git |
| 脚本人员 | 修改脚本、排查脚本问题 |
| 发布人员 | 按流程同步生产环境 |
| 评审人员 | 检查变更范围、风险和测试结果 |
一个人可以承担多个角色，但职责仍应清楚。
## 分工原则{#division}
多人协作时，建议按以下方式分工：
1. 按页面、模块或业务流程分工。
2. 避免多人同时修改同一个元数据文件。
3. 大范围重构前先通知团队。
4. 脚本、权限、流程等高风险文件由负责人确认。
5. 生产发布只由指定人员执行。
## 开始工作前{#before-work}
每位成员开始工作前应完成：
1. 从 Git 拉取最新内容。
2. 打开 VS Code 工作区。
3. 连接测试服务器。
4. 使用 SuccApp 拉取服务器变化。
5. 检查 Changes 视图是否已有冲突。
6. 确认自己的修改范围。
如果发现本地或服务器已有其他人的变化，应先沟通再继续。
## 修改过程中{#during-work}
修改过程中建议：
1. 小步修改，不要一次改太多文件。
2. 每次修改后查看 Changes 差异。
3. 推送测试环境前确认当前服务器。
4. 测试通过后及时提交 Git。
5. 在提交信息中写清业务目的。
6. 重要修改在团队群或任务中说明。
不要长时间持有大量未提交修改，否则团队很难判断真实进度和风险。
## 交换数据和修改{#exchange}
团队成员之间交换修改，应优先使用 Git。
推荐方式：
1. 修改者提交到个人分支。
2. 发起合并请求或通知评审。
3. 评审通过后合并到团队分支。
4. 其他成员从 Git 拉取。
5. 需要在测试服务器验证时，再通过 SuccApp 推送。
测试服务器可以作为团队集成验证环境，但不应替代 Git。只在服务器上改、不提交 Git，会导致版本不可追踪。
## 处理远端变化{#remote-change}
如果 push 时提示服务器已有远端变化：
1. 不要直接强制推送。
2. 先查看远端变化差异。
3. 确认远端变化是谁产生的。
4. 如果远端变化需要保留，先 pull 并处理冲突。
5. 如果确认远端变化可以覆盖，由负责人决定是否强制推送。
生产环境中出现远端变化时，应暂停发布并确认原因。
## 冲突处理{#conflict}
冲突处理建议：
1. 打开 diff，确认本地和服务器各自改了什么。
2. 找到对应修改人员沟通。
3. 决定保留本地、保留服务器，或手工合并。
4. 合并后重新推送测试环境。
5. 提交 Git 并说明冲突处理结果。
不要在不了解业务含义时随意选择一侧覆盖。
## 命名和目录规范{#naming}
团队应约定元数据命名和目录规则。
建议：
1. 按业务模块组织目录。
2. 文件名尽量稳定，避免频繁重命名。
3. 页面标题、描述和文件名含义一致。
4. 删除测试文件和临时文件前先确认没有引用。
5. 被同步的目录应保留有效 `.meta`，文件资源应在父目录 `.meta` 中保留对应条目。
## 提交和评审规范{#review}
提交前自查：
1. Changes 视图无无关变化。
2. Git diff 无临时文件。
3. 测试环境已验证。
4. 说明了本次修改目的。
5. 高风险修改已通知负责人。
评审时重点看：
1. 是否符合需求。
2. 是否修改了无关文件。
3. 是否有误删和格式化噪声。
4. 是否会影响生产数据、权限或流程。
5. 是否有回退方式。
## 禁止事项{#forbidden}
正式项目中不建议：
1. 直接在生产环境中调试。
2. 未查看差异就 push。
3. push 被阻止后直接强制覆盖。
4. 只改服务器不提交 Git。
5. 删除目录级 `.meta` 文件或误删其中的资源条目。
6. 提交 `.succapp/remote/`、日志、锁和缓存。
7. 让 AI 未经检查地发布生产。
## 协作检查清单{#checklist}
每日开始工作前：
1. 拉取 Git。
2. 拉取服务器变化。
3. 检查 Changes 视图。
4. 明确今日修改范围。
提交前：
1. 查看 SuccApp diff。
2. 推送测试环境验证。
3. 查看 Git diff。
4. 提交 Git。
5. 通知评审或相关成员。
发布前：
1. 确认 Git 版本。
2. 确认评审通过。
3. 确认生产差异。
4. 准备回退方案。
5. 安排业务验证。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/release/release-to-prod.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/release/release-to-prod"
title: "发布到生产环境"
---
---
title: 发布到生产环境
navTitle: 发布生产
---
# 发布到生产环境
项目通常先在测试环境由人和 AI 共同修改、验证，再将确认过的 Git 版本发布到生产环境。SuccApp 可以帮助用户对比和推送元数据，但生产同步必须配合 Git、评审和业务验证流程使用。
AI 可以参与整理发布说明、检查 diff 和生成回退建议，但不应在没有人工确认的情况下直接推送生产环境。
## 环境职责{#responsibility}
推荐将不同环境的职责区分清楚：
| 环境或工具 | 职责 |
| :--- | :--- |
| 测试环境 | 日常修改、调试、功能验证 |
| Git 仓库 | 保存经过验证的元数据版本 |
| 生产环境 | 客户正式使用环境，只接收已评审版本 |
| SuccApp | 在本地和服务器之间同步元数据 |
不要把生产环境当作日常调试环境。
## 推荐发布流程{#flow}
从测试环境同步到生产环境，建议按以下流程：
1. 在测试环境完成修改。
2. 使用 SuccApp 推送测试服务器并验证。
3. 提交 Git。
4. 团队评审本次变更。
5. 准备生产发布工作区。
6. 切换到已评审的 Git 版本。
7. 连接生产服务器。
8. 执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**）。
9. 对比生产差异。
10. 推送生产服务器。
11. 完成生产业务验证。
12. 记录发布结果和回退方式。
## 测试环境开发{#test-dev}
测试环境中可以使用较高频率的修改和推送流程：
1. 本地修改元数据。
2. 查看 Changes 差异。
3. 推送测试环境。
4. 在浏览器或设计器中预览。
5. 修复问题后继续小步推送。
测试通过后，再提交 Git。不要把未验证的临时修改提交到稳定分支。
## 准备生产工作区{#prod-workspace}
生产发布前建议使用干净的生产发布工作区。
生产工作区应满足：
1. Git 已切换到准备发布的版本。
2. 已配置生产服务器。
3. 未开启自动推送。
4. 已连接生产服务器，并按生产服务器刷新变化。
5. Git 工作区没有未提交本地修改。
如果是首次准备生产发布工作区，建议先从 Git 拉取已评审版本，确认本地已经存在要发布的项目目录，再连接生产服务器并执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**）。
::: warning 注意
当前版本不提供单独只刷新 mirror、但不修改工作区文件的用户命令。不要用 **从服务器重置本地项目** 代替生产发布前的差异检查，否则本地 Git 版本可能被生产服务器内容覆盖。
:::
如果同一个工作区同时配置测试和生产服务器，切换到生产服务器后应先执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），不要用测试服务器状态判断生产差异。
## 确认生产服务器差异{#prod-baseline}
SuccApp 会通过 Changes 视图展示“待发布 Git 版本”和“生产服务器当前版本”之间的差异。生产发布前应先连接生产服务器并刷新变化。
推荐按以下方式确认差异：
1. 打开干净的生产发布工作区。
2. 从 Git 切换到本次准备发布的版本。
3. 连接生产服务器。
4. 执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**）。
5. 打开 Changes 视图，确认本地变化、远端变化和冲突符合预期。
完成后，Changes 视图中看到的本地变化，表示本次 Git 版本准备推送到生产服务器的差异；远端变化或冲突需要先确认来源，不能直接忽略。
如果本地还没有项目目录，可以先从 Git 拉取项目文件。如果确实需要通过生产服务器创建初始工作区，可以先克隆生产项目，再初始化或切换到团队 Git 仓库中的发布版本，最后刷新变化。
## 对比生产差异{#compare-prod}
推送生产前，必须查看 SuccApp Changes 视图。
重点确认：
1. 本地变化是否就是本次发布内容。
2. 是否有生产服务器上的远端变化尚未处理。
3. 是否存在冲突。
4. 是否出现无关文件或大量格式化差异。
5. 是否包含不应发布的临时测试配置。
如果生产服务器有远端变化，应先确认这些变化来源。不要直接强制覆盖。
## 推送生产环境{#push-prod}
确认差异无误后，再执行推送。
推送生产前建议由发布负责人进行最后确认：
1. Git 版本正确。
2. 评审已通过。
3. 变更范围明确。
4. 已有回退方案。
5. 当前连接的是生产服务器。
推送完成后，应立即进行业务验证。
## 生产验证{#verify-prod}
生产验证至少应包含：
1. 打开受影响页面。
2. 完成一条核心业务流程。
3. 检查脚本控制台或系统日志是否有异常。
4. 确认权限、数据范围和页面显示符合预期。
5. 通知相关人员验证结果。
## 回退方案{#rollback}
生产发布前应准备回退方案。
常见回退方式：
1. 使用 Git 切回上一个稳定版本，再通过 SuccApp 推送。
2. 使用服务器文件历史对比问题文件，确认后恢复。
3. 使用客户现场既有备份或发布包恢复。
选择哪种回退方式，应由项目负责人根据现场制度决定。
## 发布前检查清单{#checklist}
发布生产前请确认：
1. 本次修改已在测试环境验证。
2. 本次修改已提交 Git。
3. 合并请求或评审已通过。
4. 发布人员清楚本次影响范围。
5. 生产服务器无未处理远端变化。
6. Changes 视图无冲突。
7. 未开启自动推送。
8. 已准备回退方案。
9. 已安排生产验证人员。
::: danger 生产环境操作
生产环境 push 是高风险操作。任何不确定的差异、冲突或远端变化，都应先暂停并确认原因。
:::
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/examples/README.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/examples"
title: "通过示例学习"
---
---
title: 通过示例学习
description: 汇总 AI 低代码开发可参考的 SuccApp 元数据示例。
navTitle: 通过示例学习
indexTitle: 概述
---
# 通过示例学习
通过示例学习用于让 AI 和项目成员查找 DEMO 元数据、同类页面、看板、报表、脚本和项目设置示例。
## 什么时候进入
遇到以下问题时，先阅读本目录：
- 需要给 AI 找一份可参考的同类元数据写法。
- 需要查看 DEMO 项目中的页面、仪表板、报表、模型、脚本或公共素材。
- 需要判断某类文件通常放在哪里、字段怎么写、引用怎么组织。
- 当前业务项目没有同类文件，需要用官方示例补充上下文。
## 任务入口
| 任务 | 先读 | 适用情况 |
| --- | --- | --- |
| DEMO 元数据 | [DEMO 元数据](./demo-metadata.md) | 查找 SuccApp 示例项目 `DEMO` 中的应用、页面、仪表板、报表、数据模型、程序流和脚本示例。 |
## 相关阅读
- [元数据即代码](../basics/metadata-as-code.md)：先理解示例元数据和真实项目元数据的区别。
- [定位元数据](../project/find-resource.md)：在当前项目中查找真实资源文件、字段、路径和依赖。
---
url: "https://docs.succapp.com/v5/guide/dev/ai-building/examples/demo-metadata.md"
htmlUrl: "https://docs.succapp.com/v5/ai-building/examples/demo-metadata"
title: "DEMO 元数据参考示例"
---
---
title: DEMO 元数据参考示例
description: 说明如何在线查看 DEMO 元数据示例，并在 SuccApp CLI 初始化的官方离线文档 skill 中使用这些示例。
navTitle: DEMO 元数据
---
# DEMO 元数据参考示例
DEMO 元数据示例来自 SuccApp 示例项目 `DEMO`。站点只发布已升级到当前元数据类型最新版本的示例文件，可作为 AI 理解 SuccApp 元数据结构、文件组织和同类写法的参考。
DEMO 元数据示例只用于学习结构和参考写法。回答当前业务项目内容、排查服务器路径、查模型字段或判断依赖时，应以当前工作区和 SuccApp 服务器上的真实元数据为准，不得把 `metadata-examples` 当成当前服务器事实。
## 在线查看{#online}
可以从下面的典型文件开始查看：
| 示例文件 | 可参考内容 |
| --- | --- |
| [`metadata-examples/DEMO/app/afl.app/index.tpg`](/metadata-examples/DEMO/app/afl.app/index.tpg) | 应用模板页面结构。 |
| [`metadata-examples/DEMO/app/afl.app/节点/URL路由/URL路由_基本功能.spg`](../../../../metadata-examples/DEMO/app/afl.app/节点/URL路由/URL路由_基本功能.spg) | SuperPage 页面配置。 |
| [`metadata-examples/DEMO/ana/case/film/film1copy.dash`](../../../../metadata-examples/DEMO/ana/case/film/film1copy.dash) | 仪表板页面配置。 |
| [`metadata-examples/DEMO/app/bi.app/报表风格.rpt`](../../../../metadata-examples/DEMO/app/bi.app/报表风格.rpt) | 报表页面配置。 |
| [`metadata-examples/DEMO/app/Course.app/data/DIM_KCXX_KCBQ.tbl`](../../../../metadata-examples/DEMO/app/Course.app/data/DIM_KCXX_KCBQ.tbl) | 数据表模型配置。 |
完整索引见 [`metadata-examples/DEMO/index.json`](../../../../metadata-examples/DEMO/index.json)。索引只列出适合在线查看和 AI 读取的最新版本文本元数据文件。
## 在离线 skill 中使用{#offline-skill}
执行 `succapp workspace init` 后，SuccApp CLI 会同步官方离线文档 skill 到当前工作区。DEMO 元数据示例会作为该 skill 的内部资源保存：
```text
.agents/skills/succapp-docs/
├── indexes/
│ └── metadata-demo-index.json
└── metadata-examples/
└── DEMO/
```
给 AI 安排任务时，可以让它优先读取 `indexes/metadata-demo-index.json`，再按任务类型选择同类文件。例如：
```text
请参考 .agents/skills/succapp-docs/metadata-examples/DEMO/app/ap.app/ 下的同类页面，
帮我判断当前工作区中这个 .spg 页面应如何调整。先说明候选文件和依据，不要直接修改。
```
## 使用建议{#usage}
1. 查文件类型时，先读[元数据系统](../../meta/README.md)和对应文件类型页，再打开 DEMO 同类文件对照。
2. 让 AI 参考 DEMO 时，明确允许参考的目录和目标文件类型，避免把 DEMO 中的历史测试页面误当成当前项目规范。
3. DEMO 示例用于理解结构和写法，正式项目仍应以当前工作区的同类文件、业务数据、DTS 和产品验证结果为准。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension"
title: "扩展开发介绍"
---
---
navTitle: 扩展开发
indexTitle: 概述
---
# 扩展开发介绍
扩展是一种插件，安装一个扩展可以提供 SuccApp 默认不具备的功能，可以改变产品的默认功能和行为。
扩展的开发是面向开发者的，需要开发者具备基础的 Web 开发技能，详见[开始前先判断](../README.md#before-you-start)。本章节介绍如何开发 SuccApp 扩展，包括新建扩展、开发、调试、运行等，包括以下内容：
- [扩展开发介绍](#扩展开发介绍)
- [扩展的原理](#expansion-principle)
- [扩展点](#extension-point)
- [开发环境准备](#preparation)
- [创建新的扩展](#new-extension)
- [开发语言](#language)
- [运行和调试扩展](#debug-extensions)
- [发布扩展](#publish-extension)
- [代码规范](#code-specification)
- [引用产品提供的前端API](#front-end-api)
- [引用扩展内的ts文件](#refer-ts-extension)
- [引用第三方开源js文件](#refer-ts-third)
- [支持国际化](#i18n)
## 扩展的原理{#expansion-principle}
SuccApp 是 B/S 架构的系统，支持扩展前端和后端的逻辑。当需要开发扩展时，需要先了解系统提供了哪些[扩展点](./extension-points/README.md)，只有通过系统提供的[扩展点](./extension-points/README.md)才能扩展希望的个性化逻辑，扩展点有前端和后端之分。
扩展开发有前端和后端之分，开始前先根据运行位置和影响范围判断扩展类型，详见[开始前先判断](../README.md#before-you-start)。
## 扩展点{#extension-point}
扩展点是系统提供的允许第三方开发者进行“扩展的的切入点”，详细信息参考[这里](./extension-points/README.md)。
支持的扩展点：
!!! children (./extension-points) !!!
## 开发环境准备{#preparation}
1. 扩展的开发需要用到 SuccApp for VS Code 或 SuccApp CLI，参见 [AI 低代码开发](../ai-building/README.md)。
2. 扩展的调试运行需要 SuccApp 产品环境，需要[下载](../../whatsnew/README.md)并启动 SuccApp（可以用已有的环境，但不要是生产环境）。
## 创建新的扩展{#new-extension}
创建新的扩展前，需要了解 SuccApp 提供了哪些[扩展点](./extension-points/README.md)，并根据具体需求选择要扩展的扩展点，一个扩展可以实现多个扩展点。SuccApp 提供了不同类型的扩展模板，模板包含必要的配置、目录结构和文件内容，基于模板可以加快扩展开发。
TODO 补充一个截图。
## 开发语言{#language}
扩展开发支持 JavaScript 或 TypeScript。前后端运行位置和影响范围的判断见[开始前先判断](../README.md#before-you-start)。
## 运行和调试扩展{#debug-extensions}
连接测试服务器进行调试（前端代码使用浏览器调试功能调试，后端使用日志调试）和测试
## 发布扩展{#publish-extension}
如果要分享给其他人使用，可发布到[产品社区](https://bbs.succbi.com/)中，审批通过后即可查看使用。
## 代码规范{#code-specification}
在开发一个扩展的时候，如果使用到了脚本，那么需要遵循一些规则，才能够让扩展最终在平台中正确运行。
### 引用产品提供的前端API{#front-end-api}
产品提供了一些api，这些api是产品提供的对外接口，在开发扩展脚本的过程中可以直接进行调用。
```ts
import { assign } from 'sys/sys';
```
### 引用扩展内的ts文件{#refer-ts-extension}
扩展内部可能会有多个脚本互相调用，假设扩展内部存在如下的两个脚本：
- main.ts
- impl
- template.ts
在`main.ts`中引用`template.ts`的方式是这样的，
```ts
import {Template} from './impl/template'
```
始终应该通过相对路径进行引用。
### 引用第三方开源js文件{#refer-ts-third}
在通过typescript或者javascript es6 编写代码的时候，会引用一些第三方的开源js/ts文件。
1. 第三方ts文件，无需做特殊处理，和扩展开发者自己写的的ts文件可以等同看待。
2. 第三方js文件，如jquery，与我们编写扩展的要求不同，这些文件一般是es5编写的，不能使用一般的处理方式，这里重点进行介绍。其进行引用的方式有如下两种。
**直接在扩展中加入第三方js文件：**
如果是通过模板创建的扩展，在扩展下一般都有lib目录，在扩展开发环境中的目录结构如下：
第三方的js文件应该都放在这个lib文件夹下。同时约定，在一个扩展下的任何地方建立的lib文件夹，均会被识别为第三方库。在扩展开发环境中，lib目录下的文件不会被编译，因此请确保添加的第三方文件是已经编译为能在浏览器中直接运行的版本。一般不建议定义额外的lib文件夹。
在扩展代码中引用第三方文件的时候，有两种情况，一种情况是第三方文件是按照模块组织的，另一种情况是文件未按照模块进行组织，对于没有按照模块组织的，如在lib目录下添加了`jquery-3.1.1.js`，它定义了全局变量而不是模块，在扩展主脚本main.ts中请这样进行引用：
```ts
import "./lib/jquery-3.1.1";
declare var $: any;
```
这样声明以后就可以在代码中使用jquery的`$`对象了。为了在ts代码中直接使用js对象而不报编译错误，需要进行`declare var $: any`这样的声明。需要注意的是，这里declare的的变量名必须与第三方文件提供的全局变量的名称保持一致，在这里的例子就是`$`。
对于按照模块组织的库，如有一个demo模块`demo.js`，在扩展主脚本main.ts中请这样进行引用：
```ts
import demo from "./lib/demo";
```
这样引用的demo的类型也是any，使用者可以自行查阅api使用它导出的内容。
**引用平台提供的第三方js文件：**
在平台中已经集成了一些常用点第三方文件，它们包括这些：
- `jquery`
- `TODO` 补充一些
这些第三方文件比如jquery在平台中均做了处理，不需要自己去再将文件放在lib目录下就可以使用，同时直接通过我们上面列出的名称就可以进行引用，不需要额外的路径或者版本后缀，如引用jquery可以像这样写：
```ts
import "jquery";
declare var $: any;
```
除了这里import的方式之外，对于不同js文件的使用要求同[直接加入第三方js库](#直接在扩展中加入第三方js文件)一致。
### 支持国际化{#i18n}
在实现扩展的时候，有时会提供一些在界面上显示的ui组件，这些组件在显示给用户时需要考虑国际化。
在扩展中实现国际化有下面几点需要注意：
- 扩展文件的存储。
- 扩展的国际化信息直接存储在每一个扩展的`package.json`的属性`i18n`中。
- 扩展文件内容格式。
- 国际化目前仅支持中文和英文两种，分别为`zh_CN`,代表中文环境的国际化和`en`代表英文环境。其中国际化的每个条目需要以当前的扩展的扩展名开头。
- 在代码中获取国际化信息。
- 在扩展中实现国际化，需要使用系统提供的`sys`模块的`message`函数，该模块的定义文件`sys.d.ts`可以在扩展开发环境下的`/api/sys`文件夹下找到，在扩展代码中可以按照上文中的[引用平台提供的前端API](#引用平台提供的前端API)直接使用。
例子1：假如想要给登录页面扩展增加一条版权信息的国际化，可以采取下面的方式。
首先在pacakge.json中增加如下的的信息：
```json
{
"i18n": {
"zh_CN": {
"succ-loginPage-default.copyright": "版权",
},
"en": {
"succ-loginPage-default.copyright": "copyright"
}
}
}
```
然后在代码中这样调用，在中文环境获取到的就是上面设置的`版权`,而在英文环境调用获取到的就是`copyright`：
```ts
message("succ-loginPage-default.copyright");
```
例子2: 假如想要设置带参数的中文国际化信息，如`正在加载，资源a、资源b`这样的信息显示给用户的时候。可以这样实现。
1. 首先在pacakge.json中增加如下的的信息。
```json
{
"i18n": {
"zh_CN": {
"succ-portalTemplate-pagedark.load.resources": "正在加载，资源{0}、资源{1}",
}
}
}
```
2. 然后在代码中这样调用，在中文环境获取到的就是将参数设置好的`正在加载，资源a、资源b`。
```ts
message("succ-portalTemplate-pagedark.load.resources", "a", "b");
```
更详细的`message`函数的使用请参考扩展开发环境中`sys.d.ts`的接口文档.
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points"
title: "概述"
---
---
order: 1
navTitle: 扩展点
indexTitle: 概述
---
# 概述
扩展点是系统提供的允许第三方开发者进行“扩展的的切入点”，通过扩展点，第三方开发者可以为 SuccApp 添加新的功能或个性化已有的产品功能，如新的可视化组件、新的主题、新的模版、新的单点登录方式……。
支持的扩展点：
!!! children !!!
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/animationEffect.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/aninationEffect"
title: "aninationEffect - 动效背景扩展"
---
---
navTitle: aninationEffect
---
# aninationEffect - 动效背景扩展
在制作仪表板或者其他页面时，往往存在这样一种需求：背景是一张带特效的图片效果，比如星空效果，里面的星星在闪动或者移动。
传统的做法是使用gif图片或者使用css脚本控制样式动起来。这样做的缺点比较明显：较难复用，大量的定制开发，动画卡顿。使用动效背景扩展，可以做到组件化开发特效，一次开发无限复用。
## 扩展文件结构
1. [package.json](#package.json) 定义扩展的配置信息。
2. [main.action](#main.action) 定义扩展的执行逻辑。
### package.json
properties中定义了这个扩展公布的属性名，按照属性栏的格式编写。
```json
{
"name": "succ-animationEffect-birds",
"displayName": "飞鸟特效",
"categories": ["animationEffect"],
"version": "1.0.0",
"compatibilities": {
"platform": "^4.0.0"
},
"author": {
"name": "succez"
},
"main": "main",
"thumbnail": "thumbnail.png",
"contributes": {
"animationEffect": {
"properties": [{
"propertyName": "backgroundColor",
"propertyType": "colorButton",
"gradientColorVisible" : false,
"defaultValue": "bgColor1",
"caption": "背景颜色"
}, {
"propertyName": "color1",
"propertyType": "colorButton",
"gradientColorVisible" : false,
"defaultValue": "color5",
"caption": "躯干颜色"
}, {
"propertyName": "color2",
"propertyType": "colorButton",
"defaultValue": "color3",
"gradientColorVisible" : false,
"caption": "两翼颜色"
}, {
"propertyName": "birdSize",
"propertyType": "slider",
"caption": "飞鸟大小",
"expandVisible": false,
"expend": true,
"step": 0.1,
"max": 3,
"min": 0.5,
"defaultValue": 1
}, {
"propertyName": "speedLimit",
"propertyType": "slider",
"caption": "飞鸟速度",
"expandVisible": false,
"expend": true,
"max": 10,
"min": 1,
"defaultValue": 3
}]
}
}
}
```
### main.action
动效扩展的main.ts中需要实现一个class继承IAnimationEffect接口，并默认导出。
```typescript
/**
*
* 动效扩展是用来扩展dom能力的一种扩展机制，可以为指定dom 赋予一些背景特效，动画特效等能力。
* 每个动效扩展应该实现AnimationEffect接口并在package.json中公布支持的属性列表，外界可以通过设置这些属性来调节特效的显示效果。
*
*/
interface IAnimationEffect {
/**
* 返回扩展的名称。定义在package.json中的name。
*/
getName(): string;
/**
* 渲染方法实现。
* 需要注意的是，调用的地方传递的是增量的opt,扩展实现的时候需要处理：合并默认值，对比上次的opt,决定是否增量渲染。
*/
render(opt:AnimationEffectOption): Promise;
/**
* dom大小改变，会调用resize方法来resize动效。
*/
resize():void;
/**
* 销毁动效。
*/
dispose():void;
}
```
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataTransform.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataTransform"
title: "dataTransform - 数据加工组件扩展"
---
---
navTitle: dataTransform
---
# dataTransform - 数据加工组件扩展
SuccApp 数据加工内置了大量常用的加工组件，如汇总、行转列、列加工等，能满足大部分的数据加工需求，一些个性化加工需求也可以通过SQL组件、脚本组件实现，但是SQL组件、脚本组件不方便复用，每个用到的地方都需要再次编写SQL或者脚本。
数据加工组件扩展组件可以做到和产品内置的加工组件一样的复用，由扩展开发者开发好数据加工组件扩展后，使用者可以像使用内置加工组件一样使用扩展组件。
本文讲述如何开发一个 SuccApp 数据加工组件扩展。
## 扩展文件结构
1. [package.json](#packagejson) 定义扩展的配置信息。
2. [main.action](#mainaction) 定义扩展的执行逻辑。
### package.json
每一个扩展都需要在根目录中有一个描述文件`package.json`。
示例如下：
<<< @/../../bi/com.succez.bi/web/static-file/extension/extensions/template-dataTransform-blank/package.json
详细说明：
在`dataTransform`属性中描述扩展组件的配置信息，包括下列属性：
1. `inputDataStreamTypes` 描述扩展组件可以接受哪些输入节点，是一个json字符串数组，可以设置这些类型：
1. `DbTable` 数据库表或视图
2. `ModelTable` 模型表
3. `Stream` 数据流、
4. `Sql` SQL查询
2. `inputDataStreamCount` 描述此组件可以接受几个输入节点，可以设置如下值：
1. `Any` 随便是否有输入节点，可以没有也可以有，输入节点只是控制执行顺序，输入节点不能是不落地数据的节点
2. `MustOne` 必须且只需要一个数据输入节点
3. `MustTwo` 必须要两个输入节点
4. `MustMore` 必须需要多个数据输入节点
3. `outputDataStreamType` 描述此组件的输出数据类型，可以设置如下值：
1. `DbTable` 输出数据在一个数据库表或视图中
2. `Stream` 输出数据是一个数据流
4. `scriptAction` 加工逻辑所在的后端脚本，默认是`main.action`，脚本中有一个`onProcessExtensionNode`函数。
5. `properties` 描述使用这个加工组件时可以设置测选项
1. `propertyItems` 选项列表，是一个json数组，每个元素说明一个选项的定义，可以包含如下属性：
1. `name` 属性名，应该是一个字母组成的标识符，用于在扩展组件运行的时候传递给扩展组件的加工逻辑
2. `type` 属性类型，描述用户输入此属性时的输入方式，具体见下文
3. `caption` 属性标题，应该是一个简短的描述，如：每月发放月限量
4. `desc` 属性描述，可选，一段文字描述如何使用此属性
5. `items` 可选值列表，可选，当属性类型是combobox时有效
属性类型可以有如下选项：
1. `filter` 过滤条件
2. `number` 数字输入
3. `combobox` 下拉选项输入
4. `checkbox` 勾选框输入
5. `text` 文本输入
6. `date` 日期输入，支持输入相对日期
7. `field` 字段选择下拉框
8. `fields` 字段选择下拉框，可以多选字段
### main.action
`main.action`文件是一个后端脚本文件，定义了数据加工扩展的执行逻辑。
入口函数是`onProcessExtensionNode`，会在如下2个时机被调用：
1. 用户在数据加工界面中选择使用此扩展组件，并进行数据预览时。
2. 定时调度包含了此扩展组件的加工流程时。
可以直接编辑`main.action`文件，也可以在 SuccApp for VS Code 或元数据项目设置中通过脚本编辑器直接编辑
ts语法的脚本文件`main.action.ts`，编辑器会自动编译并生成`main.action`。
脚本模版：
<<< @/../../bi/com.succez.bi/web/static-file/extension/extensions/template-dataTransform-blank/main.action.ts
## 示例
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization"
title: "README"
---
---
order: 1
navTitle: dataVisualization
indexTitle: 概述
---
# dataVisualization
SuccApp 的仪表板等模块默认提供了核心组件库，也可以从应用商店中下载组件扩展。如果这些组件都无法满足特定的需求，也可以通过扩展实现新的组件。
## 核心组件库
介绍核心组件库，包括有哪些，UI界面等。
## 应用商店
介绍应用商店中有哪些内容，如何从商店下载。
## 开发扩展组件
SuccApp 允许开发者通过组件扩展点开发组件。通过组件扩展，我们可以做到：
- 集成第三方组件到系统中，如`ElementUI`。
- 集成第三方库到系统中，如`d3.js`，并使用它开发组件。
- 开发一个拥有数据提交功能的组件，这样用户可以通过该组件修改数据。
- 开发一个个性化布局功能的组件，可以将其它组件拖入其中，并控制它们的显示。
### 如何开发组件
学习如何开发组件的最好方式是查看指南和示例代码。
- 通过[指南](./tutorials/README.md)你可以学习到不同类型组件的开发方式，从入门的[HelloWorld](./tutorials/tutorials-js-helloworld.md)到[柱形图可视化](./tutorials/tutorials-d3-histogram.md)，都可以在这里找到。
- 你还可以浏览我们公布在[github](https://github.com/succsoft)上的示例扩展，学习更多的扩展开发方式。
- 开发者们在[社区](https://www.succbi.com)中讨论扩展开发的相关问题，你也可以在[想法](https://www.succbi.com)中提出自己的需求或问题，让 SuccApp 的技术人员来为你解答。
开发一个扩展组件，通常包括如下几个步骤：
1. [准备开发环境](./setup-devenv.md)。
2. 配置[package.json](./package-json.md)。
3. 配置[capabilities.json](./capabilities-json.md)。
4. [编写组件代码](./component-render.md)。在`main.ts`中实现`IVisualComponent`接口。
5. [连接并发布到服务器](https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-publish)，新建或打开一个页面，拖入组件并测试。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/setup-devenv.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/setup-devenv"
title: "setup-devenv"
---
---
order: 2
navTitle: 准备开发环境
---
# 准备开发环境
在开始开发前，先准备 SuccApp for VS Code 或 SuccApp CLI，参见[扩展开发](../../../ai-building/extension/extension.md)，然后按如下步骤初始化一个组件开发的项目：
- [创建组件扩展](#创建组件扩展)
- [安装 succbi-api](#安装succbi-api)
- [安装依赖库](#安装依赖库)
## 创建组件扩展
在 SuccApp for VS Code 中执行 **SuccApp: 从模板新建扩展**，选择组件扩展点和合适的模板；也可以使用 SuccApp CLI 创建：
```bash
succapp workspace extension create
```
创建完成后的组件扩展目录结构如下：
```markdown
project
├───package.json
├───capabilities.json
├───tsconfig.json
├───src
│ └───main.ts
│ └───main.less
└───dist
```
### package.json
[package.json](./package-json.md)文件描述了组件扩展的基本信息，包括扩展点名称、作者、开发组件的依赖配置等信息。
### capabilities.json
[capabilities.json](./capabilities-json.md)文件描述了组件扩展的属性配置信息。
### tsconfig.json
`TypeScript`配置信息。
### main.ts
组件TS代码入口文件。
### main.less
组件样式文件。
### dist
`TypeScript`编译为`JavaScript`后输出的目录。发布扩展时可以选择只发布`dist`目录下的文件，不发布`src`目录的文件。
## 安装 succbi-api
组件扩展模板的`package.json`中已经包含了对`succbi-api`的依赖，执行`npm install`命令安装。也可以单独执行`npm install succbi-api`安装`succbi-api`的依赖。
## 安装依赖库
开发一个组件可能需要引入一些第三方库，如`d3`,`vuejs`等。可在本地下载需要引入的文件，复制到根目录下，或使用npm命令安装：
```shell
npm i d3@^5.0.0 --save
```
引入文件后的目录结构为：
```markdown
project
├───package.json
├───main.ts
├───main.less
└───node_modules
│ └───d3
```
在`main.ts`中，通过`import`引入第三方库：
```typescript
import * as d3 from d3;
```
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/package-json.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/pacakge-json"
title: "package-json"
---
---
order: 3
navTitle: package.json
---
# pacakge.json
`package.json`文件包含两部分信息：
- 扩展的基本信息，包含扩展名称、描述文字、作者、组件的npm依赖等。npm配置参考[npm package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json)。
- 组件扩展点的配置，包括组件的类名、分组、模板等。
组件扩展点中包含[通用扩展点配置](../../references/extension-contributor.md)的所有属性，并额外增加了下面的属性。
```json
{
"contributes": {
"dataVisualization": [{
"name": "",
"main": "",
"visualClassName": "...",
"supportTypes": ["..."],
"category": "...",
"subCategory": "...",
"subTypes": "...",
"themeCategory": "...",
"group": "...",
"focusable": true|false,
"accessableProperties": [{...}],
"accessableMethods": [{...}],
"conditionStyleTypes": ["..."],
"effectStyleTypes": ["..."],
"templates": [{...}]
}]
}
}
```
当创建一个组件扩展时，必须指定的配置包括：
```json
{
"name": "",
"supportTypes": ["..."],
"group": "...",
"visualClassName": "..."
}
```
## 组件扩展点配置选项{#dataVisualization}
下面是`dataVisualization`扩展点的配置选项。
#### name{#name}
组件扩展点的名称，也是组件的类型名称，用于唯一标识一个组件类型，全局唯一，如`barChart`。
#### main{#main}
组件依赖的主代码文件，不指定时，使用`main.ts`。
#### visualClassName{#component-class-name}
组件的类名，对应`main.ts`中的一个js类，该类继承自`IVisualComponent`接口，SuccApp 在初始化组件时会根据这里的配置对组件进行实例化。
#### supportTypes{#support-types}
扩展支持的模块类型。一个组件扩展可以同时支持多个模块，默认支持所有模块。如扩展一个输入框，可以在`报表`和`SuperPage`中使用，可配置为`["rpt", "spg"]`。
在属性栏配置中，通过[$global.objectType](../../references/component-ppteditor.md#objectType)可以获取到当前模块类型，可在属性栏属性配置的`visibleCondition`中控制在指定模块显示。
组件扩展中支持配置的模块包括：
- `dash`，仪表板
- `rpt`，报表
- `spg`，SuperPage
- `webform`，web表单
- `excelform`，excel表单
#### category{#category}
组件分类。一个模块中同一类别的组件可以相互转换。如果未指定则使用`name`，即一个组件一个分类。
组件分类并不代表组件在设计器组件面板中的位置。如文本组件在`SuperPage`中属于`常用`分组，而它的`category`是`text`。使用`group`指定组件在设计器组件面板中的位置。
系统中默认的分类包括：
- `visual`，可视化组件
- `container`，容器组件
- `input`，输入组件
- TODO
#### subCategory{#sub-category}
当组件是子组件时，设置子组件的分类，父组件通过这个分类查找子组件并显示在添加子项的列表中。子组件不显示在组件大纲中。
例如spg列表的列配置如下：
```json
{
"name": "customcolumn",
"subCategory": "list.column",
"capabilities": "columnCapabilities.json",
...
}
```
spg列表在初始化时会查找当前已经注册的组件扩展中所有类型为`list.column`的组件，并显示在列表子项面板的添加菜单中。
#### themeCategory{#theme-category}
主题的分类，同一个主题分类的组件公用一套组件风格，相同`themeCategory`的组件在风格选择面板中会显示相同的列表。
如果未指定则使用`category`，`category`也没指定则使用`name`。通常，只有非常相似的组件，如柱形图、折线图等，才指定相同的`themeCategory`，其它情况则无需指定。
#### group{#group}
组件分组。用于控制组件在设计器组件面板中显示的位置。
支持配置字符串或json，配置json，会按照不同模块指定的分组控制显示位置。组件显示在仪表板中时需要配置以`"@"`分隔的二级分组。
```json
{
"group": "chart@6_kpi", //显示在图形分组的kpi子分组下。
}
或
{
"group": { "dash": "chart@@6_kpi", "spg": "other" }, //仪表板模块显示在chart分组的kpi子分组下，SuperPage显示在other分组。
}
```
TODO 截图
#### focusable{#focusable}
组件是否可以被聚焦，默认为false。通常只有输入类组件才配置为true，如输入框。在对话框中打开时自动聚焦到`focusable`为`true`的组件。
#### accessableProperties{#accessable-properties}
`设置组件属性`交互可以访问的属性名称。系统核心组件库的组件支持的组件属性参考[设置组件属性](./component-accessability.md)。
此配置项的类型是一个`json数组`。数组中的一项代表一个组件属性的配置，组件属性支持以下配置项：
- `name`：属性的名称，必选。
- `desc`：属性的详细描述，可选，如果没有配置则取[国际化配置](TODO:)，国际化配置key为`ana.setComponentProperty.组件名.属性名`。
文本输入控件组件属性配置如下：
```json
{
"name": "input",
"accessableProperties":[
{
"name":"value",
"desc":"输入组件的值" //如果缺省，取值为message("ana.setComponentProperty.input.value")
},
...
],
...
}
```
#### accessableMethods{#accessable-methods}
`调用组件方法`交互可以访问的方法名称及相应的参数配置。系统核心组件库的组件支持的组件属性参考[调用组件方法](./component-accessability.md)。
此配置项的类型是一个`json数组`。数组中的一项代表一个组件方法的配置，组件方法支持以下配置项：
- `name`：方法名，可选。
- `desc`：方法描述，可选。如果没有配置则取[国际化配置](TODO:)，国际化配置key为`ana.invokeComponentMethod.组件名.方法名`。
- `params`：方法参数，可选，类型是`json数组`。数组中的一项代表一个参数的配置，支持以下属性：
- `name`：参数名称，必选。
- `desc`：参数描述，可选。如果没有配置则取[国际化配置](TODO:)，国际化配置key为`ana.invokeComponentMethod.组件名.params.参数名`。
- `items`：可选的枚举值数组，可选。如果一个参数只能在一些枚举项中取值则需要配置。数组中每一项支持的配置项如下：
- `value`：枚举项的值，必选。
- `desc`：枚举项描述，可选。如果没有配置则取[国际化配置](TODO:)，国际化配置key为`ana.invokeComponentMethod.组件名.params.参数名.枚举值`。
- `multiple`：是否可以多选，可选，类型为`boolean`。默认为false，一般配置了`items`项才需要配置是否可以多选。
- `defaultValue`：默认值，可选。
- `optional`：此参数是否可选，默认值为true。
- `funtion`,组件方法的函数名，可选，指定后会尝试在组件配置的`main`文件中查找该函数并调用，用于解决组件不显示就需要调用的逻辑。TODO:
嵌入报表组件方法属性配置如下：
```json
{
name:"embedreport",
"accessableMethods":[
{
"name":"print"
},
{
"name":"export",
"params":[
{
"name":"fileName"
},
{
"name":"sheet",
"defaultValue":"current",
"multiple":false,
"items":[
{
"value":"current"
},
{
"value":"all"
}
]
},
*...*
]
},
...
],
...
}
```
#### conditionStyleTypes{#condition-style-types}
组件允许添加的条件样式类型。
条件样式类型包括：
- `highlight`，突出显示
- `topn`，最前/最后。仅在报表和excel表单中可用。
- `dataBar`，数据条
- `iconBar`，图标条
- `colorGradation`，色阶
- `colorPalette`，色板
- `iconSet`，图标集
#### effectStyleTypes{#effect-style-types}
组件允许添加的状态样式类型。
状态样式类型包括：
- `hover`，悬停
- `active`，鼠标按下
- `selected`，选中
- `disabled`，禁用
- `busy`，忙碌
- `focus`，焦点
#### templates{#templates}
组件模板。一个组件类型可以配置多个组件模板，多个模板都会在组件列表中显示。
组件模板支持的配置：
##### name
模板名称，默认是组件的`name`。
##### displayName
模板显示的名称。
##### icon
模板图标。
##### group
模板分组，仪表板中需要配置以`"@"`分隔的二级分组。
##### after
当配置了`group`后，可以配置在分组中哪一个组件后面。
##### defaultContent
默认元数据。拖入组件时生成的元数据以该配置为基础。
##### deviceContents
组件在不同设备下的默认元数据。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/capabilities-json.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/capabilities-json"
title: "capabilities-json"
---
---
order: 4
navTitle: capabilities.json
---
# capabilities.json
`capabilities.json`文件定义了组件扩展的交互、查询和属性配置信息。
```json
{
"supportActions": true|false,
"actionTriggerTypes": ["..."],
"dataViewMappings": {...},
"properties": {...},
"ppteditor": {...}
}
```
## 配置选项
#### supportActions
是否支持添加交互，默认支持，如果不支持则属性栏面板不会显示交互标签。如菜单的分割线不支持添加交互。
#### actionTriggerTypes
组件支持的交互触发类型。包括：
- click - 单击
- dblclick - 双击
- contextmenu - 右键
- hover - 鼠标移入
- input - 输入。和change不同，input是用户输入后不需要失去焦点就会触发
- change - 内容变化
- beforechange - 内容变化前
- focus - 聚焦
- mouseover - 鼠标移入
- mouseout - 鼠标移出
- enter - 回车
- didloadfile - 页面加载完成
- beforeleave - 离开页面前
#### dataViewMappings
参考[数据映射配置](component-datamapping.md)。
#### properties
参考[组件属性配置](../../references/component-properties.md)。
#### ppteditor
参考[设计器属性面板配置](../../references/component-ppteditor.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-datasets.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-datasets"
title: "component-datasets"
---
---
order: 5
navTitle: 组件数据集
---
# 组件数据集
组件数据集描述组件如何发起数据查询。
通常，只有查询类组件才需要配置组件数据集，如柱形图、列表等，下拉框、按钮、文本等则无需配置组件数据集。一个组件通常只有一个数据集。
和页面的查询数据集类似，组件数据集可以定义单行或多行数据集，查询明细或分组统计。一个数据集的查询结果对应一个`DataView`，`IVisualComponent`使用`DataView`渲染组件数据。
组件配置`properties`中定义的属性默认在全局单行数据集或上级多行数据集中查询和计算。例如：
1. 画布中的按钮，标题属性在全局单行数据集计算。
2. 浮动面板中的按钮，标题属性在浮动面板的多行数据集中计算，因为每一行的按钮标题计算结果可能不同。
组件也可以在`datasets`中配置自己的数据集，并定义组件中的哪些属性在数据集中查询和计算。以柱形图为例：
1. 柱形图按数据区的`x`分组，按`y`选择数据。
2. 柱形图的`标题`和`显示`属性作为图形属性在上级数据集中计算。
组件数据集支持多种配置，一个组件可以配置多个数据集。组件数据集包含如下配置：
- `conditions`，查询条件
- `single`，单行统计查询
- `table`，列表查询
- `group`，分组查询
- `matrix`，交叉表查询
- `query`，自定义查询
- `queryTotal`，是否查询合计行
- `paging`，是否分页
- `pageSize`，分页大小
- `expand`，分组属性是否可按层次展开
- `queryTotalRowCount`，是否查询总行数
```json
{
"datasets": [{
"conditions": [...],
"single": {...},
"table": {...},
"group": {...},
"matrix": {...},
"queryTotal": false,
"paging": false,
"pageSize": 10,
"expand": false,
"queryTotalRowCount": false,
"query": {...}
}],
"dataDefinitions": {...},
"marks": [...]
}
```
:::tip 安全提示
组件数据集约束了组件能够发起的查询，在查看界面中，用户无法越过组件配置和页面设计。以柱形图为例，当用户拖入`销售单位`到`X`，`销售数量`字段到`Y`，那么查看界面中柱形图就只会发起按`销售单位`分组，选择`销售数量`的查询，无法通过修改ajax参数等方式越过该限制。
:::
## dataset
### conditions
`conditions`用于确定查询发起的条件。可以定义多组条件，当尝试拖入属性栏数据区的字段满足`conditions`中定义的条件时，字段才被允许放入。
在条件中，针对一个数据区可以指定允许放入字段的最大和最小数量，如果没有指定，则可以放入任意数量的字段。当所有条件都不满足时，不发起查询。
```json
{
"conditions": [{
"x": {
"min": 1,
"max": 1
},
"y": {
"min": 1
}
}, {
"x": {
"min": 2,
"max": 2
},
"y": {
"min": 1,
"max": 1
}
}]
}
```
- `max`，允许放入字段的最大个数。如果未指定则可以放入任意个数的字段。
- `min`，允许放入字段的最小个数。如果未指定则不放入字段也可以发起查询。
### single
单行统计查询。拖入维度时会被转换为度量。通常用于KPI等指标查看类型的组件。
*示例*
```json
{
"dataDefinitions": {
"measures": {
"kind": "measure",
"preferredTypes": ["number"]
}
},
"datasets": [{
//至多拖入2个字段
"conditions": [{
"measures": {
"max": 2
}
}],
"single": "measures"
}]
}
```
### table
列表查询。拖入的字段查询明细数据。通常用于列表等明细查询组件。
*示例*
```json
{
"dataDefinitions": {
"columns": {}
},
"datasets": [{
//至少拖入一个字段
"conditions": [{
"columns": {
"min": 1
}
}],
"table": {
"name": "columns"
}
}]
}
```
### group
分组查询。
- `group`，分组的字段。
- `select`，选择的字段。
*示例*
```json
{
"dataDefinitions": {
"dimensions": {
"kind": "dimension"
},
"measures": {
"kind": "measure"
}
},
"datasets": [{
//至少拖入一个至多拖入两个维度，至少拖入一个度量
"conditions": [{
"dimensions": {
"min": 1,
"max": 2
},
"measures": {
"min": 1
}
}],
"group": {
"group": ["dimensions"],
"select": ["measures"]
}
}]
}
```
### matrix
交叉表查询。
- `rowGroup`，行分组的字段。
- `colGroup`，列分组的字段。
- `select`，选择的字段。
*示例*
```json
{
"dataDefinitions": {
"row": {
"kind": "dimension"
},
"col": {
"kind": "dimension"
},
"measures": {
"kind": "measure"
}
},
"datasets": [{
"conditions": [{
"row": {
"min": 1
},
"col": {
"min": 1
},
"measures": {
"min": 1
}
}],
"matrix": {
"rowGroup": ["row"],
"colGroup": ["col"],
"select": ["measures"]
}
}]
}
```
### queryTotal
是否查询合计行，默认为`false`，可以指定一个属性控制是否查询合计的值。如果有多个分组字段，则每一级都查询合计。
*示例*
```json
{
"datasets": [{
// 需要查询合计行
"queryTotal": true
}]
}
```
```json
{
"datasets": [{
// 表示是否需要查询合计行由`queryTotalEnable`属性控制
"queryTotal": "queryTotalEnable"
}]
}
```
### paging
是否分页，默认为`false`，可以指定哪一个属性控制`paging`的值。
*示例*
```json
{
"datasets": [{
// 需要分页
"paging": true
}]
}
```
```json
{
"datasets": [{
// 表示是否需要分页由`pagingEnable`属性控制
"paging": "pagingEnable"
}]
}
```
### pageSize
分页大小，默认为`10`，可以指定哪一个属性控制`pageSize`的值。
*示例*
```json
{
"datasets": [{
// 分页大小为100
"pageSize": 100
}]
}
```
```json
{
"datasets": [{
// 表示分页大小由`pageSize`属性控制
"pageSize": "pageSize"
}]
}
```
### expand
分组属性是否可按层次展开，默认为`false`，可以指定哪一个属性控制`expand`的值。
*示例*
```json
{
"datasets": [{
// 分组属性需要按层次展开
"expand": true
}]
}
```
```json
{
"datasets": [{
// 表示是否需要按层次展开由`expandEnable`属性控制
"expand": "expandEnable"
}]
}
```
### queryTotalRowCount
是否查询总行数，默认为false，可以指定哪一个属性控制`queryTotalRowCount`的值。
*示例*
```json
{
"datasets": [{
// 需要查询总行数
"queryTotalRowCount": true
}]
}
```
```json
{
"datasets": [{
// 表示是否查询总行数由`queryTotalRowCountEnable`属性控制
"queryTotalRowCount": "queryTotalRowCountEnable"
}]
}
```
### query
自定义查询。当组件需要自己构造查询，但又不希望使用数据区的属性面板时，可以采用自定义查询的方式定义如何发起查询。
例如SuperPage中的地图图层、列表、浮动面板等，这些组件采用了和仪表板数据区不同的数据集定义方式，无法使用`数据区`的配置方式，需要配置自定义查询。
*配置*
- `datasetProperty`，指定查询要查询的数据集属性名，通常是`dataset`属性。
- `atomicQuery`，是否明细查询，默认为`true`。设置为`false`时表示分组查询，可以指定一个[条件表达式](../../references/component-conditionexp.md)，用于动态控制。
- `groupProperty`，分组属性设置，可以指定单个或多个分组属性。设置`groupProperty`时`atomicQuery`会被默认设置为`false`。
- `dimOption`，补全维项设置。
- `properties`，当前查询包含的属性，没有指定的属性会默认放到当前组件的上级组件构造的查询中。
系统中配置自定义查询的组件通常有两类：
1. 组件上配置了数据集和相关查询属性，查询属性在组件数据集中发起查询，其它属性加入到上级数据集中。大部分组件都属于这一类，如下拉框、图层等。
2. 组件上配置了数据集，组件有下级子组件，子组件上配置了查询属性，查询属性在组件数据集中发起查询，其它属性加入到上级数据集中。如列表、浮动面板等。
#### 配置数据集和查询字段
以系统内置的区块图层为例：
1. 区块图层自己发起查询，配置了位置属性，按该属性分组，查询`提示信息`属性和`交互`。
```json
{
"datasets": [
{
"query": {
"groupProperty": ["locationField"],
"actions": true,// 指定组件上的交互在customQuery中计算
"properties": {
"basic": ["@tooltip"]
}
}
}
]
}
```
#### 配置数据集和子组件
配置数据集和子组件时，组件上的属性默认会加入到上级数据集，子组件中查询属性默认加入到上级组件构造的数据集，如果不需要加入到上级组件构造的数据集，需要配置`excludeProperties`。
以系统内置的列表组件为例：
1. 列表组件以`dataset`属性作为数据集，设置了`hierarchy`时按`hierarchy`选择的层次展开数据，列表自身的属性默认加入到上级数据集。
2. 列表子组件中查询属性默认加入到列表构造的数据集中，列的`visibleCondition`属性需要加到列表的上级数据集，需要配置`excludeProperties`。
```json
{
"list":{
"datasets": [{
"query": {
"datasetProperty": "dataset",
"atomicQuery": "hierarchy != null",
"groupProperty": "hierarchy",
"queryTotalRowCountProperty": "totalCountVisible"
}
}]
}
}
```
列上的属性默认是加在列表的组件数据集中查询的，但是列的`visibleCondition`属性不能在列表构造的数据集中查询，此时需要配置`excludeProperties`，配置后此属性会放到列表的上级组件构造的数据集中计算。
```json
{
"column": {
"parentDataset": {
"actions": true, // 指定列上的交互在列表的数据集中查询和计算
"excludeProperties": {
"basic": ["visibleCondition"]
}
}
}
}
```
## dataDefinitions
`dataDefinitions`用于定义数据区属性。每一个数据区都可以拖入字段或输入表达式。当使用`group`、`table`和`single`时，需要结合`dataDefinitions`配置。
设计器属性面板中配置的数据区属性[dataDefinition](../../references/component-ppteditor.md#dataDefinition)会使用该配置生成界面。
`dataDefinitions`支持的配置属性如下：
- `name`，名称
- `kind`，允许拖入字段的类别，不指定时默认为`dimensionOrMeasure`
- `dimension`，维度
- `measure`，度量
- `dimensionOrMeasure`，维度或度量
- `preferredTypes`，支持的字段数据类型数组
- `string`，字符型
- `date`，日期型
- `number`，数值型
- `geoType`，地理角色
- `markable`，是否支持标记，有且只能有1个数据区配置为`true`
以系统内置的柱形图为例，数据区`x`可以拖入维度；数据区`y`可以拖入指标且可以被标记，配置如下：
```json
{
"dataDefinitions": {
"x": {
"kind": "dimension"
},
"y": {
"kind": "measure",
"markable": true
}
}
}
```
## marks
支持的标记类型。在数据区配置`markable`为true表示标记该数据区中的字段；否则表示对组件进行标记。
支持的标记类型：
- `color`，颜色标记
- `shape`，形状标记
- `size`，大小标记
- `label`，标签
- `tooltip`，提示信息
- `lob`，其它
以系统内置的柱形图配置为例：
```json
{
"marks": ["color", "shape", "size", "label", "tooltip", "lob"]
}
```
标记支持配置：
- `kind`，允许拖入字段的类别，不指定时默认为`dimensionOrMeasure`
- `dimension`，维度
- `measure`，度量
- `dimensionOrMeasure`，维度或度量
- `preferredTypes`，支持的字段数据类型数组
- `string`，字符型
- `date`，日期型
- `number`，数值型
- `geoType`，地理角色
- `properties`，自定义的[属性栏配置](../../references/component-ppteditor.md)
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-requestaccessapis.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-requestaccessapis"
title: "component-requestaccessapis"
---
---
order: 6
navTitle: 请求访问API
---
# 请求访问API
组件配置的`requestAccessAPIs`定义组件可以访问的后端API。
系统中包含的后端API包括：
1. `queryItems`，查询数据表/数据集数据。如下拉框可以按层次列出选择的数据集数据。
2. `searchItems`，搜索数据表/数据集数据。如快速搜索框可以使用关键字搜索指定的字段。
3. `exportData`，导出组件查询数据。如列表可以导出不分页的查询结果。
4. `upload`，上传附件。如附件组件可以上传附件。
配置支持直接使用类型和JSON配置两种方式。
1. 使用类型配置时，系统默认查找约定的属性名称构造API访问信息。
2. 使用JSON配置时，可以自定义API访问信息。
```json
{
"requestAccessAPIs": [ "queryItems", { "type": "searchItems", "searchFieldsProperty": "searchFields" } ]
}
```
## queryItems
查询数据表/数据集数据。API包含如下能力：
- 按层次查询数据。
- 按关键字搜索数据。
- 通过ID查找数据。
- 通过文字查找数据。
配置信息如下：
```json
{
"type": "queryItems",
"itemFilterProperty": "...",
"showRootPathProperty": "...",
"enableSearchProperty": "...",
"showCountProperty": "...",
"sortProperty": "..."
}
```
|属性名|类型|描述|
|---|---|---|
|itemFilterProperty|string|选项过滤属性名，默认为`itemFilter`。|
|showRootPathProperty|string|显示根路径属性名，默认为`showRootPath`。|
|enableSearchProperty|string|启用搜索属性名，默认为`enableSearch`。|
|showCountProperty|string|显示统计数属性名，默认为`showCount`。|
|sortProperty|string|选项排序属性名，默认为`sort`。|
*参考*
- [指南：选择列表](./tutorials/tutorials-d3-histogram.md)。
## searchItems
搜索数据表/数据集数据。API包含如下能力：
- 按关键字搜索指定的一个或多个字段。
- 搜索结果可以返回指定的一个或多个字段。
配置信息如下：
```json
{
"type": "searchItems",
"searchFieldsProperty": "...",
"outputFieldsProperty": "...",
"limitProperty": "..."
}
```
|属性名|类型|描述|
|---|---|---|
|searchFieldsProperty|string|搜索字段属性名，默认为`searchFields`。|
|showRootPathProperty|string|输出字段属性名，默认为`showRootPath`。|
|limitProperty|string|搜索结果条数属性名，默认为`limit`。|
*参考*
- [指南：搜索框](./tutorials/tutorials-d3-histogram.md)。
## exportData
导出组件定义的查询数据为excel文件。如果组件有多个查询，则每个sheet一个查询结果。
*参考*
- [指南：D3柱形图](./tutorials/tutorials-d3-histogram.md)。
## upload
上传文件。
配置信息如下：
```json
{
"type": "upload",
"saveTypeProperty": "...",
"submitFieldProperty": "...",
"genMD5Property": "...",
"fileMaxSizeProperty": "...",
"fileTypesProperty": "..."
}
```
|属性名|类型|描述|
|---|---|---|
|saveTypeProperty|string|附件存储方式属性名，默认为`saveType`。|
|submitFieldProperty|string|提交字段属性名，默认为`submitField`。|
|genMD5Property|string|是否生成附件的MD5属性名，默认为`genMD5`。|
|fileMaxSizeProperty|string|附件大小属性名，默认为`fileMaxSize`。|
|fileTypesProperty|string|文件类型属性名，默认为`fileTypes`。|
*参考*
- [指南：文件上传](./tutorials/tutorials-d3-histogram.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-render.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-render"
title: "component-render"
---
---
order: 7
navTitle: 组件渲染
---
# 组件渲染
当组件初始化、修改属性、改变大小、修改过滤参数等操作时，都会触发组件渲染。
下图描述了用户、页面和组件之间的核心交互逻辑。
## 用户、页面和组件的交互行为
- 设计器选中组件显示属性面板
用户选中组件时设计器会显示组件的属性面板。系统根据[capabilities.json](./capabilities-json.md)定义的属性和属性面板配置，显示当前选中组件的属性。
- 设计器通过属性面板修改组件属性
用户通过属性面板修改组件属性后，系统会触发组件的`render`函数渲染组件。组件渲染时通过`componentBuilder`获取组件的属性。
- 设计器预览
当`仪表板`和`SuperPage`这种所见即所得的模块在设计器中切换预览时，不会重新渲染组件，由于查看区域的视窗大小变化，会触发组件的`render`重新调整组件大小。
- 改变页面大小
用户改变了页面的视窗大小后，页面会从画布开始逐层向下分发大小变化事件，通知每一个组件`render`。
- 修改过滤参数
当改变了模型过滤条件引用的参数自动过滤的组件值后，使用模型查询数据的组件，需要重新发起查询。页面会通知这些组件数据变化，如果组件是`显示`的，那么先发起查询，查询完成后通知组件`render`。
## IVisualComponent
所有的扩展组件开发都需要实现`IVisualComponent`接口。实现类的名字和`package.json`中配置的`visualClassName`一致。
页面在初始化`IVisualComponent`时，会将其包装为一个`BOComponentWrapper`，`BOComponentWrapper`提供渲染组件位置、大小、标题、背景等通用能力，并创建一个包含`vc-body`class的`div`作为`domParent`传递给`IVisualComponent`的`render`函数作为`IVisualComponent`渲染的根DOM。
```typescript
export class MyVisualComponent implements IVisualComponent {
constructor(args: VisualComponentArgs) {
//初始化创建组件时调用一次，初始化组件的基本信息
}
public render(args: VisualComponentRenderArgs): void | Promise {
//渲染组件，创建DOM结构，输出样式，绑定事件...
}
}
```
### constructor
组件初始化时调用`constructor`。在构造函数中可以完成一些组件的初始化操作。
#### VisualComponentArgs
- `visualObject`，可视化页面对象，包含了一些通用服务
- `compBuilder`，组件的属性和对象访问接口，可以获取到组件元数据，下级组件等
### render
组件初始化、数据变化、主题变化等操作时都会调用`render`函数。
#### VisualComponentRenderArgs
- `domParent`，组件的父DOM，组件的DOM结构应该都创建在该DOM内。
- `renderType`，组件渲染类型，渲染时判断类型决定如何增量渲染。
- `viewPort`，组件渲染的大小和位置信息。
- `dataViews`，组件的数据对象，通过`package.json`的`dataViewMappings`配置的查询产生的查询结果。
- `viewMode`，页面的查看模式，包括编辑、预览、查看。
- `modifiedInfo`，组件的增量变化信息。组件在渲染时可以使用该信息进行增量渲染，不用每次都重新渲染整个组件。例如改变了组件的背景，传入的组件。
#### updateType
|名称|值|描述|
|---|---|---|
|None|0|无变化|
|Data|1|数据变化，`dataViews`和`modifiedInfo`中包含了变化的信息|
|Theme|2|主题变化|
|ViewMode|4|切换预览|
|Resize|8|尺寸变化|
|Visible|16|显示隐藏变化|
|All|128|全量刷新|
#### modifiedInfo
### dispose
销毁组件，组件被删除时调用。默认组件会将`IVisualComponent`移除出`domParent`，如有额外的销毁逻辑，可实现该函数。
## 增量渲染组件大小变化
当组件所在父容器尺寸变化时（比如用户拖动了浏览器窗口的大小），会触发组件渲染，`renderType`为`ComponentRenderType.Resize`。
如果组件本身就是自适应的，组件的尺寸变化时内部的DOM元素会自动重新布局，那么可以不处理该增量变化。
如果组件内部的布局需要由程序进行控制，比如用canvas绘制的图形，当组件尺寸变化时，canvas需要重新绘制，那么需要实现此函数。实现者可以简单的重新调用一下`render`函数，实现全量渲染，也可以按需自己实现更精细化的增量渲染机制。
```ts
export class MyVisualComponent implements IVisualComponent {
public render(args: VisualComponentRenderArgs): void {
let renderType = args.renderType;
if (renderType & ComponentRenderType.Resize) {
this.doResize();
}
}
private doResize(): void {
this.charts.resize();
}
}
```
## 弹出组件
弹出组件在没有弹出时不输出DOM，通过调用组件方法显示和隐藏组件。
弹出组件在隐藏时应该不响应任何事件，当显示时才一次性更新组件为最新状态。
在设计器中，弹出组件显示成一个带名称的方块，双击编辑后显示一个占据整个画布的编辑区。
TODO 截图
以菜单组件为例。通过调用组件方法交互，设置`show`显示菜单，`hide`隐藏菜单。
```json
{
"name": "MyMenu",
"popupComponent": true,
"accessableMethods": [{
"name": "show"
}, {
"name": "hide"
}]
}
```
```ts
export class MyMenu implements IVisualComponent {
private visible: boolean;
private menu: Menu;
public render(args: VisualComponentRenderArgs): void {
if(!visible || !this.menu) {
return;
}
//render menu when visible
}
public show(args: BOInvokeComponentMethodArgs): void {
this.visible = true;
let menu = this.menu;
if (!menu) {
menu = this.menu = new Menu();
}
//init items from data
let items;
menu.setItems(items);
menu.showAt(event);
}
public hide(args: BOInvokeComponentMethodArgs): void {
this.visible = false;
this.menu?.hide();
}
}
```
## 逻辑组件
逻辑组件不输出任何DOM元素，在`render`中执行程序逻辑，通常用于定时器等场景。
逻辑组件在初始化或数据变化时才调用`render`函数，不响应其它类型事件。
以定时器组件为例，页面全部加载完毕后开始计时，可以通过组件方法`start`和`stop`开始和停止计时。
```json
{
"name": "MyTimer",
"logicComponent": true,
"accessableMethods": [{
"name": "start"
}, {
"name": "stop"
}]
}
```
```ts
export class MyTimer implements IVisualComponent {
private stopped: boolean;
public render(args: VisualComponentRenderArgs): void {
this.start();
}
public start(args: BOInvokeComponentMethodArgs): void {
this.stopped = false;
// start timer
}
public stop(args: BOInvokeComponentMethodArgs): void {
this.stopped = true;
}
}
```
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-action.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-action"
title: "component-action"
---
---
order: 8
navTitle: 组件交互
---
# 组件交互
组件可以监听用户的操作，如点击、移入等事件，在事件处理函数中调用页面的`ActionManager.triggerActions()`触发组件上定义的交互。
## 配置交互
在`capabilities.json`中配置`supportActions`为`true`，设置`actionTriggerTypes`为支持的交互触发类型，如`["click"]`。配置后用户可以在设计器中操作组件的属性面板，在交互选项卡中添加交互。
TODO 补充截图
## 触发交互
在`IVisualComponent.render()`函数中，可以绑定组件支持的事件，并在事件中触发交互。
```typescript
export class MyVisualComponent implements IVisualComponent {
private visualObject: IVisualObject;
private componentBuilder: IVisualComponentBuilder;
private domBase: HTMLElement;
private clickHandler: (event: MouseEvent) => void;
public render(args: VisualComponentRenderArgs):void {
//... init dom
this.domBase.addEventListener('click', this.clickHandler = this.doClick.bind(this));
}
private doClick(event: MouseEvent): void {
let args: TriggerActionsArgs = {
event: event,
componentBuilder: this.componentBuilder,
visualComponent: this
};
this.visualObject.getActionManager().triggerActions(args);
}
public dispose(): void {
this.domBase.removeEventListener('click', this.clickHandler);
}
}
```
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-submit.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-submit"
title: "component-submit"
---
---
order: 9
navTitle: 组件提交数据
---
# 组件提交数据
在`SuperPage`和`表单`模块中，有绑定字段的组件可以通过`提交表单`交互提交数据。
## 配置组件的绑定字段
配置了绑定字段的组件，在触发提交表单交互时，会收集绑定组件的value提交到绑定字段定义的字段上。
TODO 配置步骤和截图
### 装载数据
### 提交数据
### 暂存
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/component-accessability.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/component-accessability"
title: "组件属性和方法"
---
---
order: 11
navTitle: 组件属性和方法
---
# 组件属性和方法
`SuccApp`允许用户通过设置组件属性和调用组件方法交互改变属性状态或触发组件行为。
## 设置组件属性{#set-component-property}
设置组件属性可以改变组件的数据状态，当组件数据状态变化后，页面会触发组件渲染，将组件刷新到最新状态。
在组件的[package.json](./package-json.md#accessable-properties)中配置`accessableProperties`后，用户可以在`设置组件属性`交互中选择组件，并在属性对话框中设置属性。
```json
{
"accessableProperties":[
{
name:"param"
}
]
}
```
```typescript
export class MyVisualComponent implements IVisualComponent {
public render(args: VisualComponentRenderArgs): void {
let componentData = args.componentData;
let paramValue = componentData.getProperty('param');
//do with paramValue
}
}
```
## 调用组件方法{#invoke-component-method}
在组件的[package.json](./package-json.md#accessable-methods)中配置`accessableMethods`后，用户可以在`调用组件方法`交互中选择组件和方法，并在参数对话框中设置方法参数。
组件方法可以返回`void`或`Promise`。当返回`Promise`时，`调用组件方法`交互会等待`Promise`结束才会继续执行后续交互。
*VisualComponentInvokeMethodArgs*
| 名称 | 类型 | 描述 |
| ------------------------ | ---------------------------------- | ------------------------------------------------------ |
| `visualObject` | [`IVisualObject`](TODO:) | 页面对象。 |
| `visualComponent` | [`IVisualComponent`](TODO:) | 组件对象。对于全局函数的实现，组件隐藏时该参数为null。 |
| `visualComponentBuilder` | [`IVisualComponentBuilder`](TODO:) | 组件构造器对象。 |
| `params` | `JSON` | 方法参数。用户在`调用组件方法`交互中配置的参数。 |
实现组件方法可有两种方式：
1. `IVisualComponent`的成员方法。改变组件UI状态的方法在此处实现，如弹出对话框、聚焦到某个地点等。这类方法需要组件处于显示状态。
2. 全局函数。和组件UI无关的方法在此处实现，如导出组件数据。这类方法不需要组件处于显示状态，直接基于组件的数据执行。
调用组件方法会先从`IVisualComponent`的成员方法中查找，如果没有找到，则从[main](./package-json.md#main)指定的`JS`模块中`export`出来的全局函数中查找。
### **成员方法**{#component-method}
在`IVisualComponent`上增加成员方法，可以访问到组件的`DOM`元素。
```json
{
"name":"myvisualcomponent",
"accessableMethods":[
{
"name":"addBlankRow",
"params":[
{
"name":"target",
"defaultValue":"current",
"items":[{"value":"current"},{"value":"children"}]
},
{
"name":"caption"
}
]
},
...
],
...
}
```
```typescript
export class MyVisualComponent implements IVisualComponent {
private tree: Tree;
public render(args: VisualComponentRenderArgs): void {
}
public addBlankRow(args: VisualComponentInvokeMethodArgs): void {
let visualObject: IVisualObject = args.visualObject;
let visualComponent: IVisualComponent = args.visualComponent
...
//根据visualObject、visualComponent的状态判断是否能在树上新加一行
if(canAddBlankRow) {
...
this.tree.addBlankRow(args.params);
...
}
...
}
}
```
### **全局函数**{#global-function}
在[main](./package-json.md#main)指定的JS文件模块中实现函数并`export`，这种实现方式通常被用于和`UI`无关的组件方法。
*嵌入报表*
```json
{
"name":"emebedReport",
"accessableMethods":[
{
"function":"exportTableData",
"params":[
{"name":"embedReportPath"}
]
}
]
}
```
```typescript
/**
* 嵌入报表导出数据方法实现。
*/
export function exportTableData(args:VisualComponentInvokeMethodArgs) {
let visualObject = args.visualObject;
//ui无关的组件方法，参数中visualComponent参数为null。
let visualComponentBuilder = args.visualComponent;
...
//嵌入报表路径，如："/DEMO/ana/报表/分组报表/单向分组.rpt"
let path =args.params.embedReportPath;
if(checkPathExist(path)){
...
exportReport(args.params);
...
}
...
}
```
## 通用属性{#common-properties}
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `visible` | `boolean` | 组件可见性。 |
## 通用方法{#common-methods}
## **树**{#tree}
### **属性**{#tree-properties}
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | string|string\[]|number|number\[] | 树的高亮或勾选值。可以用于提交、过滤。设置此属性会同步设置树的勾选或高亮，如果`value`为空`（null、[]）`代表清空勾选或高亮。设置此属性后，可以通过表达式属性[树.值](#)访问。 |
### **方法**{#tree-methods}
#### **addBlankNode**(){#tree-method-addBlankNode}
为树上增加一个空白节点。
**描述**
树上同时只能存在一个空白节点。当树上已经存在空白节点时，重复调用此函数不会继续添加。
选中的是多个节点，以最后一个选中的节点为准。
空白节点添加成功后会选中空白节点。
如果空白节点未被保存时切换选中，会删除空白节点。
如果添加后空白节点不可见，会将其滚动到可见区域。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| appendChild | boolean | 可选，默认为`false`。是否插入到选中节点的子节点。 |
| insertBefore | boolean | 可选，默认我`false`。是否插入到选中节点的前面。 |
| targetNode | number|string | 可选。插入到指定节点的同级或下级。 |
| value | number|string | 可选。节点值。 |
| caption | string | 可选，默认为`未命名`。节点标题，国际化key为`bo.tree.blankrow.caption`。 |
| data | Json | 可选。插入的字段数据。如`{field1: value, field2: value}`。 |
**返回值**
无。
#### **remove**BlankNode(){#tree-method-removeBlankNode}
删除树上空白节点。
**描述**
如果空白节点未被保存时切换选中，会删除空白节点。
删除后会自动选中树的其他节点的规则规则如下：
- 如果选中节点有同级节点，会选中最近的同级节点，优先选择选中节点的下一个节点。
- 如果选中节点没有同级节点，则选中父节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| autoSelect | boolean | 可选。默认为true。删除时是否自动选中其他节点。 |
**返回值**
无。
#### **find()**{#tree-method-find}
对树进行搜索。
**描述**
##### **方法参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `keyword` | `string` | 搜索关键字，为空是退出搜索。 |
| `mode` | `listSearch`|`treeSearch`|`treeLocate` |搜索模式，默认值为`listSearch`。搜索模式为`listSearch`（**列表搜索**）时，以列表的形式展示匹配的结果。搜索模式为`treeSearch`（**树搜索**）时，显示所有包含匹配结果的父节点，会层层展开第一个匹配结果的节点并选中。搜索模式为`treeLocate`（**树定位**）时，显示所有节点（不隐藏不匹配的节点），会层层展开第一个匹配的节点并选中。此时可以通过`locateNextFoundItem`定位所有搜索到的节点。 |
#### **locateFoundItem()**{#tree-method-locateNextFoundItem}
树处于搜索状态时，定位搜索结果。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| forward | boolean | 是否后定位。默认为`true`。 |
| cycle | boolean | 是否循环定位，默认为`true`。 |
#### **locate()**{#tree-method-locate}
定位指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 定位节点的值。 |
#### **select()**{#tree-method-select}
选中指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **unselect()**{#tree-method-unselect}
取消选中指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **selectAll()**{#tree-method-selectAll}
选中所有节点。
#### **unselectAll()**{#tree-method-unselectAll}
取消选中所有节点。
#### **check()**{#tree-method-check}
勾选指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **uncheck()**{#tree-method-uncheck}
取消勾选指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **checkAll()**{#tree-method-checkAll}
勾选所有节点。
#### **uncheckAll()**{#tree-method-uncheckAll}
取消勾选所有节点。
#### **expand**(){#tree-method-expand}
展开指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **expandAll**(){#tree-method-expandAll}
展开树所有节点。
**描述**
- 如果树有多级，会按层级依次展开树的节点。
#### **collapse**(){#tree-method-collapse}
折叠指定节点。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |
#### **collapseAll**(){#tree-method-collapseAll}
折叠树所有节点。
**描述**
- 如果树有多级，会按层级依次折叠树的节点。
## **富文本**{#richtext-input}
## **嵌入报表**{#embedreport}
### **方法**{#embedreport-methods}
#### **export**(){#embedreport-method-export}
导出报表。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | excel|pdf | 文件类型。 |
| allPage | boolean | 是否导出所有页，默认为`false`。|
| exportSheetType | current|all|select | `current`表示导出当前工作表；`all`表示导出所有工作表；`select`表示导出选择的工作表，默认为`current`。 |
| exportSheets | string | 当`exportSheetType`为`select`时，指定导出的sheet ID，多个时用逗号分割。|
#### **print**(){#embedreport-method-print}
打印报表。
**参数**
无
#### **refresh**(){#embedreport-method-refresh}
刷新报表。
报表的参数栏和表体都重置为初始状态，清空数据缓存，计算时重新查询数据。
**参数**
无
## **嵌入仪表板**{#embeddashboard}
### **方法**{#embeddashboard-methods}
#### **export**(){#embeddashboard-method-export}
导出仪表板。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | image||ppt|pdf | 文件类型。 |
#### **print**(){#embeddashboard-method-print}
打印仪表板。
**参数**
无
#### **refresh**(){#embeddashboard-method-refresh}
刷新仪表板。
仪表板重置为初始状态，清空数据缓存，计算时重新查询数据。
**参数**
无
## **嵌入SuperPage**{#embedsuperpage}
### **方法**{#embedsuperpage-methods}
#### **export**(){#embedsuperpage-method-export}
导出SuperPage。
**参数**
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | image||ppt|pdf | 文件类型。 |
#### **print**(){#embedsuperpage-method-print}
打印SuperPage。
**参数**
无
#### **refresh**(){#embedsuperpage-method-refresh}
刷新SuperPage。
SuperPage重置为初始状态，清空数据缓存，计算时重新查询数据。
**参数**
无
## **嵌入报表填报应用**{#embedfapp}
### **方法**{#embedfapp-methods}
#### **addRow**(){#embedfapp-method-addRow}
浮动区域增加一个浮动行。
**描述**
选中浮动区域的单元格时，在焦点单元格下方增加一个浮动行。
如果没有选中单元格，并且只有一个浮动区域，会在浮动区域最下面增加一行
**参数**
无。
#### **deleteRow**(){#embedfapp-method-deleteRow}
删除选中的浮动行。
**描述**
选中浮动区域的单元格时，会删除这些单元格所在的浮动行。
**参数**
无。
#### **validateForm**(){#embedfapp-method-validateForm}
校验当前填写的数据。
**描述**
对当前填写的数据做校验，如果校验不通过，会显示校验面板，查看和定位校验不通过组件。
校验不通过，数据会无法保存或提交。
**参数**
无。
#### **saveDraft**(){#embedfapp-method-saveDraft}
保存数据。
**描述**
数据会保存到服务器，并且会设置为草稿状态。
保存时会对必须填写的数据做校验，如果校验不通过，会无法保存。如模型主键不能为空，保存时必须有数据。
**参数**
无。
#### **submitData**(){#embedfapp-method-submitData}
提交数据。
**描述**
数据会保存到服务器，并且会设置为已提交。
提交时会对对数据做校验，如果校验不通过，会提交失败，并显示校验面板，可以按校验面板提示解决校验错误。
**参数**
无。
#### **importData**(){#embedfapp-method-importData}
导入数据。
**描述**
可以将excel文件中的数据导入到表单中，导入后，点击保存或提交，才会保存到服务器。
**参数**
无。
#### **exportData**(){#embedfapp-method-exportData}
导出Excel。
**描述**
将Excel表单和嵌入报表导出为Excel文件。
Web表单和嵌入的SuperPage不会导出。
**参数**
无。
#### **lockData**(){#embedfapp-method-lockData}
锁定数据。
**描述**
将已提交的数据锁定，锁定后，数据将不能再修改。
如果需要再次修改数据，需要先解锁。
**参数**
无。
#### **unlockData**(){#embedfapp-method-unlockData}
解锁数据。
**描述**
已锁定的数据是不能修改的，只有解锁后，才能再次修改。
**参数**
无。
#### **deleteData**(){#embedfapp-method-deleteFAppData}
删除数据。
**描述**
删除当前期，当前单位的已保存或提交数据。
**参数**
无。
## **嵌入表单**{#embedform}
### **方法**{#embedform-mthods}
#### **addRow**(){#embedform-method-addRow}
浮动区域增加一个浮动行。
**描述**
选中浮动区域的单元格时，在焦点单元格下方增加一个浮动行。
如果没有选中单元格，并且只有一个浮动区域，会在浮动区域最下面增加一行
**参数**
无。
#### **deleteRow**(){#embedform-method-deleteRow}
删除选中的浮动行。
**描述**
选中浮动区域的单元格时，会删除这些单元格所在的浮动行。
**参数**
无。
#### **importData**(){#embedform-method-importData}
导入数据。
**描述**
可以将excel文件中的数据导入到表单中，导入后，点击保存或提交，才会保存到服务器。
**参数**
无。
#### **exportData**(){#embedform-method-exportData}
导出Excel。
**描述**
将Excel表单和嵌入报表导出为Excel文件。
Web表单和嵌入的SuperPage不会导出。
**参数**
无。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/performance-tips.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/performance-tips"
title: "performance-tips"
---
---
order: 14
navTitle: 性能提示
---
# 性能提示
本文档涵盖开发者如何开发高性能的扩展组件的一些提示和建议。
## 使用Performance API
使用[Performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API)记录你的扩展组件在哪一块代码存在性能瓶颈。
## 避免频繁的DOM操作
### 缓存DOM节点
### 尽可能增量渲染
## 大数据量渲染使用canvas或WebGL
## 重新审查动画代码
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/tutorials/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/tutorials"
title: "README"
---
---
order: 16
navTitle: 开发指南
---
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/tutorials/tutorials-js-helloworld.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/tutorials-js-helloworld"
title: "tutorials-js-helloworld"
---
---
order: 1
navTitle: 指南：Hello World
---
# 指南：Hello World
在这篇文档中，你将学习开发一个入门的输出Hello World文本的组件。
在这片文档中，你将学习如何：
:heavy\_check\_mark: 创建一个组件扩展项目
:heavy\_check\_mark: 开发一个基础组件
:heavy\_check\_mark: 配置基本的package.json
:heavy\_check\_mark: 发布组件到服务器
:heavy\_check\_mark: 调试组件
完整的源代码示例：[sample hello world](https://github.com/succsoft/succbi-extensions-dataVisualization-samplehelloworld)。
## 创建一个组件扩展项目
## 编写组件代码
## 配置package.json
## 连接并发布到服务器
## 调试组件
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dataVisualization/tutorials/tutorials-d3-histogram.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dataVisualization/tutorials-d3-histogram"
title: "tutorials-d3-histogram"
---
---
order: 2
navTitle: 指南：基于D3的柱形图
---
# 指南：基于D3的柱形图
在这篇文档中，你将学习开发一个柱形图。
在这片文档中，你将学习如何：
- 定义capabilities.json
- 引入并使用d3开发可视化
- 在仪表板中配置和使用组件数据
- 配置和使用标记
- 使组件响应大小变化事件
完整的源代码示例：[sample bar chart](https://github.com/succsoft/succbi-extensions-dataVisualization-samplebarchart)。
## 创建一个组件扩展项目
## 定义capabilities.json
## 使用数据渲染图形
## 配置标记
## 渲染标记
## 响应大小变化事件
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector"
title: "README"
---
---
order: 1
navTitle: dbConnector
indexTitle: 概述
---
# dbConnector
SuccApp 数据模块默认提供一些数据库连接器，包含了大部分主流数据库，用户可以自行连接使用。若这些数据库连接器无法满足特定的数据库连接需求，也可以通过扩展方式创建新的数据库连接器。
## 开发扩展数据库连接器{#develop-connector}
SuccApp 允许开发者通过组件扩展方式新增数据库连接器。扩展数据库连接器和默认的数据库连接器拥有相同的能力。通过扩展数据库连接器，我们可以做到：
- 使用扩展数据库连接器连接新的数据库。
- 使用新数据库进行数据的加工处理。
### 如何开发扩展数据库连接器{#howto-develop-connector}
学习如何开发扩展数据库连接器的最好方式是查看指南和示例配置。
- 通过[数据库连接器扩展指南](./succ-dbconnector.md)你可以查到不同接口。
- 你可以下载[这里](https://www.jianguoyun.com/p/DZKpzN0Q3O-gChirgvsEIAA)（提取码：SuccBI）的示例扩展作为参考，学习如何进行扩展开发。
- 开发者们在[社区](https://www.succbi.com)中讨论扩展开发的相关问题，你也可以在[想法](https://www.succbi.com)中提出自己的需求或问题，让 SuccApp 的技术人员来为你解答。
开发一个扩展数据库连接器，通常包括如下几个步骤：
1. [准备配置环境](./setup-configuring.md)。
2. 配置[package.json](./package-json.md)。
3. 配置[capabilities.json](./capabilities-json.md)。
4. 点击[这里](http://localhost:8080/DEMO/app/dbconnector-test.app?:edit=true)访问本地配置环境，根据`README.md`配置测试数据源，进入`dbconnect-test.app`进行扩展数据库连接器用例测试。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/setup-configuring.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/setup-configuring"
title: "setup-configuring"
---
---
order: 2
navTitle: 准备配置环境
---
# 准备配置环境
在开始配置前，需要先在本地[安装DEMO体验版](../../../../devops/install/basic-install/trial-install.md)，然后[创建示例扩展](#extension-example)。
## 创建扩展示例{#extension-example}
登录DEMO试用版，进入**系统数据**->**资源**->**extensions**目录，创建扩展数据库连接器目录，目录结构如下：
```markdown
succ-dbconnector-xxx
├───package.json
├───capabilities.json
├───thumbnail.jpg
├───icon.svg
├───create-table.ftl
├───alter-table.ftl
├───create-view.ftl
├───merge.ftl
└───xxx.ftl
```
:::tip 提示
目录结构中列出的文件为常用示例文件，实际配置时可以添加更多脚本文件和`.ftl`文件。
:::
### package.json{#package.json}
[package.json](./package-json.md)文件描述了扩展数据库连接器的基本信息，包括扩展点名称、数据库名称、jdbc连接模板等信息。
### capabilities.json{#capabilities.json}
[capabilities.json](./capabilities-json.md)文件描述了扩展数据库连接器的属性配置信息，如支持版本、字段类型、SQL模板等。
### thumbnail.jpg{#thumbnail.jpg}
新建数据源对话框中的展示图片，一般从本地图片中导入。
### icon.svg{#icon.svg}
新建数据源后，在数据库页面显示的缩略图，一般从本地图片中导入。
### create-table.ftl{#create-table.ftl}
[create-table.ftl](./sqlTemplates/createtable-ftl.md)文件描述了构造`create table`语句的Freemaker模板。
### alter-table.ftl{#alter-table.ftl}
[alter-table.ftl](./sqlTemplates/altertable-ftl.md)文件描述了构造`alter table`语句的Freemaker模板。
### create-view.ftl{#create-view.ftl}
[create-view.ftl](./sqlTemplates/createview-ftl.md)文件描述了构造`create view`语句的Freemaker模板。
### merge.ftl{#merge.ftl}
[merge.ftl](./sqlTemplates/merge-ftl.md)文件描述了构造`merge into`语句的Freemaker模板。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/package-json.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/pacakge-json"
title: "package-json"
---
---
order: 3
navTitle: package.json
---
# pacakge.json
`package.json`文件包含两部分信息：
- 扩展数据库连接器的基本信息，包含扩展名称、描述文字、版本、展示图片等。配置参考[连接器配置信息](#connector-information)。
- 扩展数据库连接器的默认im
- 配置，包括扩展数据库库名、数据库类别、jdbc连接模板等。
以下是扩展数据库连接器的模板配置：
```json
{
"name": "succ-dbconnector-jdbc",
"displayName": "Common JDBC",
"version": "1.0.0",
"icon": "icon.svg",
"thumbnail": "thumbnail.jpg",
"compatibilities": {
"platform": "^5.0.0"
},
"categories": [
"data"
],
"contributes": {
"dbConnector": {
"name": "JDBC",
"dbKind": "TransactionalDB",
"compatibilityLevel": "All",
"displayOrder": 0,
"jdbcConfigTemplate": {}
}
}
}
```
## 连接器配置信息{#connector-information}
### name{#name}
扩展名称，需要和`package.json`的上层目录名字相同。
### displayName{#displayname}
显示名称，一般与数据库名称保持一致。
### version{#version}
扩展数据库连接器版本，一般默认为1.0.0。
### icon{#icon}
新建数据源后，在数据库页面显示的缩略图，此参数一般配置缩略图的路径，如`succ-dbconnector-Mysql\icon.svg`。
### thumbnail{#thumbnail}
新建数据源对话框中的展示图片，此参数一般配置图片路径，如`succ-dbconnector-Mysql\thumbnail.jpg`
### platform{#platform}
SuccApp 平台的版本，通常为5.0.0。
### categories{#categories}
扩展类别，默认为`data`，表示为数据库连接器扩展。
### contributes{#contributes}
描述扩展数据库连接器的默认配置信息，具体可参考[dbConnector](#dbconnector)。
## dbConnector{#dbconnector}
### name{#dbConnector-name}
SuccApp 新建数据源时的名称，一般为扩展数据库的名称，如`MySql`。
### dbKind{#dbkind}
设置数据库在新建数据源对话框中显示的类别，主要类别如下所示
- `TransactionalDB`：事务型
- `AnalyticalDB`：分析型
- `HadoopDB`：Hadoop类
- `ColumnarDB`：列式
- `NoSQL`：NoSQL型
- `Cube`：多维数据集
- `Search`：检索服务
- `Other`：其他
:::tip 提示
`dbKind`内可以配置多个参数，参数间用`,`隔开。
:::
### compatibilityLevel{#compatibilitylevel}
数据库的兼容级别，此属性决定扩展数据库能使用系统中的哪些功能，默认为`ALL`。
主要类别如下所示：
- `ALL`：完全兼容
- `OLTP`：事务型，可以用于低代码应用、元数据存储、日志记录等使用场景。
- `OLAP`：分析型，可以作为报表或仪表板的数据源，也可以作为数据仓库使用。
- `OdsSource`：只查询，兼容级别最低的类型，通常只能进行数据库连接、查询等操作，无法进行提取加工。
### displayOrder{#displayOrder}
配置1-100的整数，决定扩展数据库在数据源对话框中的排列位置，数值越大排列位置就越靠前。
### capabilities{#capabilities}
指定一个扩展目录的文件，用于描述和配置数据库的功能、兼容性选项，默认为[capabilities.json](./capabilities-json.md)文件。
### jdbcConfigTemplate{#jdbcconfigtemplate}
新建数据库连接的默认配置，通常包括[jdbcurl](#url)、[schema](schema)、[port](#port)等。
示例如下所示：
```json
"jdbcConfigTemplate": {
"schema": "testdb",
"url": "jdbc:mysql://{host}/{databaseName}?useUnicode=true&characterEncoding=utf8&allowLoadLocalInfile=true&zeroDateTimeBehavior=convertToNull&useSSL=false",
"port": 3306
}
```
#### url{#url}
新建数据库连接时默认的jdbc连接，也可以在url中设置连接属性，若[connectionProperties](#connectionproperties)中配置了相同的连接属性，以此处的属性为准。
#### driver{#driver}
数据库连接器的默认驱动，如mysql的驱动为`com.mysql.cj.jdbc.Driver`，若`capabilities.json`中也配置了[driver](./capabilities-json.md#driver)属性，以此处的配置为准。
#### port{#port}
数据库的默认端口，如mysql的默认端口为`3306`。
#### schema{#schema}
连接数据库时的默认显示的schema。
#### poolSize{#poolsize}
数据库连接池的最大连接数，默认为20。
#### connectionProperties{#connectionproperties}
连接器建立JDBC连接时的默认连接属性，有些数据库的属性必须通过Properties进行设置，设置到[url](#url)中无效。可以设置一个字符串，并用`&`分割多个属性，也可以设置为json字符串。
示例如下：
```json
"connectionProperties": {
"connectTimeout": {
"configProperty": "connectTimeout",
"timeUnit": "ms",
"inURL": true
},
"socketTimeout": {
"configProperty": "socketTimeout",
"timeUnit": "ms",
"inURL": true
}
}
```
:::tip 提示
若有些属性在[url](#url)中已经设置，以url中的配置为准。
:::
##### defaultValue{#defaultvalue}
数据库的连接属性名，名字一般与[configProperty](#configproperty)内的参数相同。
##### configProperty{#configproperty}
设置该属性的值由哪个参数传递过来，常用的有`connectTimeout`、`socketTimeout`、`waitTime`，详细参数可参考[数据库连接器扩展指南](./succ-dbconnector.md)的`configProperty`属性。
##### timeUnit{#timeunit}
时间单位参数，可以为`ms`或者`s`，默认为`ms`。
##### inURL{#inurl}
是否将连接属性设置到jdbc的[url](#url)中，`ture`表示设置到url中，默认为`false`。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/capabilities-json.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/capabilities-json"
title: "capabilities-json"
---
---
order: 4
navTitle: capabilities.json
---
# capabilities.json
`capabilities.json`文件描述了扩展数据库连接器的属性配置信息，如支持版本、字段类型、SQL模板等。
```json
{
"inheritConnector": "JDBC",
"matchDbVersion": ">=5.0.0",
"matchJdbcURL": "jdbc:mysql:",
"driver": "com.mysql.cj.jdbc.Driver",
"serverScript": "script.action",
"forbiddenSQLs": [...],
"connectionProperties": {...},
"dataTypes": {...},
"functionTemplates": {...},
"operatorTemplates": {...},
"displayFormats": {...},
"errorIdentifyConfs": [...],
"sqlTemplates": {...},
"supports": {...},
"compitableVersions": {...}
}
```
## 配置项{#conf-items}
#### inheritConnector{#inheritconnector}
指定一个其他数据库连接器，当前连接器会继承指定连接器的配置，默认为JDBC。
- 此参数填写Connector的标识ID，一般配置为指定数据库名字，且大小写敏感。
- 若想继承特定版本的配置，可以用`@`字符对数据库连接器和版本进行分隔，如`MySql@8.0.0`。
#### matchDbVersion{#matchdbversion}
指定该数据库连接器所能兼容的数据库的版本。
- 兼容版本通常为一个范围，且遵循[semver规范](https://docs.npmjs.com/cli/v6/using-npm/semver)。
- 版本号必须为3位数字，常见示例如下：
- `>=5.0.0` 表示兼容5.0.0及以后版本的数据库。
- `5.0.0 - 5.7.0` 表示兼容5.0.0和5.7.0之间的版本。
- `~5.6.0` 表示兼容5.6.x版本的数据库，包括5.6.0，5.6.2，但不包括5.7、6.0等以后版本的数据库。
- `^5.6.0` 表示兼容5.x.x版本的数据库，包括5.6.0、5.7.0、5.8.0，单不包括6.0及以后的版本。
#### matchJdbcURL{#matchjdbcurl}
配置一个正则表达式或字符串，判断是否兼容某个jdbc的url。
- 正则表达式通常用斜线括起来，如`/^jdbc:mysql:.+$/`。
- 若没有用斜线括起来，会判断url是否以该字符串开头，如`jdbc:mysql:`。
#### driver{#driver}
数据库连接器默认驱动，若`package.json`中也配置了[driver](./package-json.md#driver)属性，以`package.json`中的配置为准。
#### script{#script}
指定一个当前扩展目录的脚本文件，用于通过脚本代码实现一些数据库底层相关的逻辑，如使用数据库本地的jdbc api去流式导入数据，想洗可参考[数据库连接器扩展指南](./succ-dbconnector.md)中的`DbConnectorScript`接口。
#### forbiddenSQLs{#forbiddensqls}
配置一个正则表达式，禁止用户使用此连接器执行一些修改当前连接状态的SQL。正则表达式通常用斜线括起来。
示例： `/^\s*USE\s/` 表示禁用mysql中的`USE xxx`语句。
#### connectionProperties{#connectionproperties}
定义java的jdbc连接时需要用的一些默认链接参数，配置可参考[package.json](./package-json.md#connectionproperties)。
#### dataTypes{#datatypes}
定义数据库支持什么字段类型，具体配置参考[字段类型配置](./dataTypes.md)。
#### functionTemplates{#functiontemplates}
配置 SuccApp 中表达式函数对应的数据库执行SQL，具体配置参考[表达式函数配置](./functionTemplates.md)。
#### operatorTemplates{#operatortemplates}
当数据库中的表达式操作符与 SuccApp 中的表达式操作符有差异时，需要将差异的内容配置在这里，默认为空。
#### displayFormats{#displayformats}
定义与 SuccApp 的显示格式相匹配的数据库的显示格式，具体配置可参考[SuccApp 显示格式配置](./displayFormats.md)。
#### errorIdentifyConfs{#erroridentifyconfs}
用于配置数据库异常信息的匹配规则，具体配置可参考[异常信息配置](./errorIdentifyConfs.md)。
#### sqlTemplates{#sqltemplates}
数据库连接器的支持的SQL模板，详细配置参考[SQL模板配置](./sqlTemplates/README.md)。
#### supports{#supports}
配置一些数据库特性以及SQL方言，详细配置参考[配置数据库特性](./supports.md)。
#### compitableVersions{#compitableversions}
配置默认版本外数据库的兼容属性，详细配置可参考[配置其他版本兼容性](./compitableVersions.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/dataTypes.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/dataTypes"
title: "dataTypes"
---
---
order: 5
navTitle: dataTypes
---
# dataTypes - 字段类型配置
定义此数据库支持的所有支持的字段类型。
这里定义的字段类型，需要将当前数据库支持的字段类型描述清楚，并告诉 SuccApp 不同的字段在 SuccApp 中是什么数据类型，当跨库复制数据时，系统也许兼容识别javaJDBC的字段类型定义，这样在跨库迁移数据时能更准确的还原字段数据类型。
```json
"dataTypes": {
"TINYINT": {
"type": "...",
"dataType": "...",
"javaTypes": ["..."],
"matchLen": "...",
"storageBytes": "...",
"preffered": true|false,
"storeCharacter": true|false
}
}
```
## 配置项{#conf-items}
#### type{#type}
定义数据库的字段类型，一般为数据库实际支持的数据类型。
1. 字段类型可以是带有参数的字符串，如`VARCHAR(?)`、`VARCHAR(?) BINARY`、`DECIMAL(?,?)`。
2. 数据库的字段类型最好参考官方文档进行配置，如[MySql支持的数据类型](https://dev.mysql.com/doc/refman/8.0/en/other-vendor-data-types.html)。
#### dataType{#datatype}
定义该字段类型在 SuccApp 中是什么数据类型，通常用字母表示。
数据类型如下所示：
- `C`：字符型
- `N`：浮点型
- `I`：整型
- `D`：日期型
- `T`：时间型
- `P`：时间戳型
- `M`：Clob类型
- `X`：Blob类型
- `J`：Json类型
- `U`：其他类型
#### javaTypes{#javatypes}
定义java JDBC规范中的数据类型。
通常要与数据库实际字段类型尽量匹配，可以定义多个，用`,`分隔。当其他数据库迁移数据到此库时，会根据这里的数据类型在当前数据库新建字段。
数据类型如下所示：
- **整型**：`TINYINT`、`SMALLINT`、`INTEGER`、`BIGINT`
- **浮点型**：`FLOAT`、`REAL`、`DOUBLE`、`DECIMAL`、`NUMERIC`
- **字符型**：`BIT`、`NUMERIC`、`CHAR`、`VARCHAR`、`NCHAR`、`NVARCHAR`、`BOOLEAN`
- **日期型**：`DATE`
- **时间型**：`TIME`、`TIME_WITH_TIMEZONE`、`TIMESTAMP_WITH_TIMEZONE`
- **时间戳型**：`TIMESTAMP`
- **Clob类型**：`CLOB`、`NCLOB`、`LONGVARCHAR`、`LONGNVARCHAR`
- **Blob类型**：`BINARY`、`VARBINARY`、`LONGVARBINARY`、`BLOB`
- **Json类型**：`SQLXML`
- **其他类型**：`NULL`、`OTHER`、`JAVA_OBJECT`、`DISTINCT`、`STRUCT`、`ARRAY`、`REF`、`DATALINK`、`ROWID`、`REF_CURSOR`
#### matchLen{#matchlen}
定义整型字段的长度匹配范围，当整数长度与字段类型中`matchLen`定义的范围相匹配时，会选择此字段类型创建字段，此属性仅对整型字段有效。
示例：
```json
"TINYINT": {
"type": "TINYINT",
"dataType": "I",
"matchLen": "1~2",
"storageBytes": 1,
"javaTypes": ["TINYINT"]
}
```
:::tip 提示
用户修改整型字段长度后，若修改的长度超过了原来字段类型的最大长度，会重新根据`matchLen`定义的范围匹配合适的字段类型。
:::
#### storageBytes{#storagebytes}
定义字段类型实际存储的字节数，一般为数据库字段类型的字节数。
#### preffered{#preffered}
数据库创建字段时是否优先选择创建此类型的字段，默认为false。
数据库在创建字段时，会优先考虑定义了`preffered=true`的字段。对于整型字段，若定义了`matchLen`属性，先根据[matchLen](#matchlen)属性进行匹配，匹配不到就会使用定义了`preffered=true`的字段类型。
#### storeCharacter{#storecharacter}
说明此字段类型是否为字符存储，true表示字符存储，false表示byte存储，此属性对字符型字段有效。
:::tip 提示
SuccApp 通常会优先使用字符存储的字段，在进行跨库迁移时，从字符存储的字段迁移到目标库时也尽量使用字符存储的字段。
:::
#### alterTypes{#altertypes}
定义当前字段类型可以修改为哪些其他数据类型，默认为空。当此属性为空或者未定义时，修改字段类型遵循以下规则
1. 当表中存在数据时，blob、clob的字段类型总是不能修改为其他类型，其他类型也不能修改为blob或clob类型。
2. 一般默认除blob、clob字段以外的字段类型可以互相修改。
3. 对于不能修改的字段类型，若确实需要修改，系统将新建一个字段并尽量迁移老字段的数据过去。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/functionTemplates.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/functionTemplates"
title: "functionTemplates"
---
---
order: 6
navTitle: functionTemplates
---
# functionTemplates - 表达式函数配置
SuccApp 提供了很多[表达式函数](../../../../exp/func/README.md)，这里用于配置使用表达式函数时，系统在数据库中执行的SQL。详细配置可参考[数据库连接器扩展指南](./succ-dbconnector.md)中的`DbVersionCapabilities`方法。
示例：
```json
"functionTemplates":
{
"ABS": "..."
"COUNT":
{
"template": "COUNT(?)",
"templates":
[{
"matchArgsLen": 0,
"template": "COUNT(*)"
}]
}
}
```
### 配置表达式SQL{#expression-sql}
TODO
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/displayFormats.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/displayFormats"
title: "displayFormats"
---
---
order: 7
navTitle: displayFormats
---
# displayFormats - 显示格式配置
定义 SuccApp 的显示格式对应的数据库的显示格式。
示例：
```json
"displayFormats": {
"yy": "%y",
"yyyy": "%Y",
"m": "%c",
"mm": "%m",
"mmm": "%b",
"mmmm": "%M",
"d": "%e",
"dd": "%d",
"ddd": "%a",
"dddd": "%W",
"h": "%k",
"hh": "%H",
"mi1": "%i",
"mi2": "%i",
"s": "%S",
"ss": "%S",
"000": "%f",
"am/pm": "%p",
"a/p": "%p",
"%": "%%",
"iyyy": "%x",
"iw": "%v"
}
```
### 显示格式规范{#format-specification}
在 SuccApp 中，显示格式严格参考[Excel规范](https://support.microsoft.com/zh-cn/office/%E5%B0%86%E6%95%B0%E5%AD%97%E8%AE%BE%E7%BD%AE%E4%B8%BA%E6%97%A5%E6%9C%9F%E6%88%96%E6%97%B6%E9%97%B4-418bd3fe-0577-47c8-8caa-b4d30c528309#bm2)，详细介绍可参考[数据库连接器扩展指南](./succ-dbconnector.md)中的`DbDateDisplayFormatMappings`方法。
TODO
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/errorIdentifyConfs.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/errorIdentifyConfs"
title: "errorIdentifyConfs"
---
---
order: 8
navTitle: errorIdentifyConfs
---
# errorIdentifyConfs - 异常信息配置
配置数据库异常信息的识别规则，并将各个数据库的各种异常归一化为 SuccApp 的异常规则，给用户统一的异常提示。详细参数介绍可参考[数据库连接器扩展指南](./succ-dbconnector.md)中的`SQLExceptionIdentifyConf`方法。
```json
"errorIdentifyConfs": [{
"className": "...",
"errorCode": "...",
"sqlState": "...",
"errorMessage": "...",
"unifiedErrorCode": "...",
"extractPropertiesRegex": "...",
"regexCaptureProperties": "...",
"isFatalError": true|false
}]
```
### 配置参数介绍{#configuration-parameters}
TODO
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/sqlTemplates/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/sqlTemplates"
title: "README"
---
---
order: 9
navTitle: sqlTemplates
---
# sqlTemplates - SQL模板配置
配置扩展数据库连接器支持的SQL模板。
每一个SQL模板用于在数据库实现一个特定的功能，兼容各个数据库时会对不同的数据库配置一系列的SQL模板。一般可以直接写入SQL，若功能较为复杂，一般通过[Freemaker](https://freemarker.apache.org/docs/)文件实现SQL模板。
```json
"sqlTemplates": {
"getSchemas":"...",
"getProcedures": "...",
"getProcedureMeta": "...",
"dropTableIfExists": "...",
"dropViewIfExists": "...",
"renameTable": "...",
"getTableDDL":"...",
"getViewDDL": "...",
"getProcedureDDL": "...",
"nullFirstDescOrder": "...",
"getTableTriggers": "...",
"getTriggerMeta": "...",
"getTableStorageSpace": "...",
"insertOnDuplicate": "...",
"mergeInto": "...",
"createTable": "...",
"alterTable": "...",
"createView": "..."
}
```
:::tip 提示
SQL模板也支持使用sql文件进行
:::
## 配置选项{#properties}
### getSchemas{#getschemas}
查询当前数据库的schema列表。通常查询数据库的schema列表会调用驱动的`getSchemas()`函数，有些数据库的驱动没有实现这个方法，或者返回空列时，需要执行一个SQL来获取schema列表。
SQL示例：
```sql
SELECT SCHEMA_NAME AS TABLE_SCHEM, CATALOG_NAME AS TABLE_CATALOG FROM INFORMATION_SCHEMA.SCHEMATA;
```
字段列：
- `TABLE_SCHEM`：String schema名称。
- `TABLE_CATALOG`：String 列表名称。
### getProcedures{#getprocedures}
返回查询存储过程列表的SQL。
示例：
```sql
SELECT ROUTINE_SCHEMA AS PROCEDURE_SCHEMA,SPECIFIC_NAME AS PROCEDURE_NAME,ROUTINE_DEFINITION AS TEXT FROM information_schema.Routines where ROUTINE_TYPE = 'PROCEDURE' [AND ROUTINE_SCHEMA='?1'] order by ROUTINE_SCHEMA,SPECIFIC_NAME,ROUTINE_DEFINITION;
```
字段列：
- `PROCEDURE_SCHEMA`：string 存储过程所在SCHEMA名称
- `PROCEDURE_NAME`：string 存储过程名称
- `TEXT`：string 存储过程内容
SQL模板参数：
1. `storeSchema`：存储过程所在schema，如果是默认schema也会返回默认schema的名字。
2. `scheam`：当前schema，如果是默认schema则返回空值。
### getProcedureMeta{#getproceduremeta}
返回一个查询存储过程元数据内容的SQL，SQL中也会包括参数信息。
示例：
```sql
SELECT ROUTINE_DEFINITION AS TEXT FROM information_schema.Routines where ROUTINE_TYPE = 'PROCEDURE' [AND ROUTINE_SCHEMA='?1'] order by ROUTINE_SCHEMA,SPECIFIC_NAME,ROUTINE_DEFINITION;
```
SQL模板参数：
1. `procedure` 目标存储过程名。
2. `schema` 当前Schema，如果是默认schema则返回空值。
3. `procedureName` 不含schema的存储过程名。
4. `storeSchema` 存储过程所在的schema，如果是默认schema也会返回默认schema的名字。
### dropTableIfExists{#droptableifexists}
删除一个物理表（如果表已存在）。
示例：
```sql
DROP TABLE IF EXISTS ?;
```
SQL模板参数：
1. `table`：目标表名。
2. `schema`：当前Schema，如果是默认schema则返回空值。
3. `tableName`：不含schema的表名。
4. `storeSchema` 目标表所在schema，如果是默认schema也会返回默认schema的名字。
### dropViewIfExists{#dropviewifexists}
删除一个视图（如果视图已存在）。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
DROP VIEW IF EXISTS ?;
```
### renameTable{#renametable}
将指定schema下的表更名，更名为另一个表名，新的表也在原来的schema下。
```sql
RENAME TABLE ? to ?;
```
SQL模板参数：
1. oldTable 目标表表名，见{@link SQLTemplateParam\_Identifier}。
2. newTable 新表名，见{@link SQLTemplateParam\_Identifier}。
3. schema 原表所在schema，如果是默认schema则返回空值。
4. oldTableName 原表名，表名不包含schema。
5. newTableName 新表名，表名不包含schema。
### getTableDDL{#gettableddl}
返回一个目标表的ddl语句，通常为`create table ...`语句。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
SHOW CREATE TABLE ?;
```
:::tip 提示
1. 若配置了此SQL模板，则使用此SQL模板的结果当作ddl。
2. 若未配置此SQL模板，会使用[createTable](#createtable)模板的返回ddl结果。
:::
### getViewDDL{#getviewddl}
返回一个目标视图的DDL语句，通常为`create view ...`语句。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
SHOW CREATE VIEW ?;
```
### getProcedureDDL{#getprocedureddl}
返回一个查询存储过程的DDL的SQL语句。
示例：
```sql
SHOW CREATE PROCEDURE ?;
```
SQL模板参数：
1. `procedure`：目标存储过程名
2. `schema`：当前Schema，如果是默认schema则返回空值。
3. `procedureName`：不含schema的存储过程名
4. `storeSchema`：存储过程所在schema，如果是默认schema也会返回默认schema的名字。
### nullFirstDescOrder{#nullfirstdescorder}
返回一个根据字段排序的sql。
示例：
```sql
?1 is null desc, ?1 desc;
```
SQL模板参数：
`column`：排序字段名
### getTableTriggers{#gettabletriggers}
返回一个查询触发器信息的SQL。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
select TRIGGER_NAME,ACTION_STATEMENT TRIGGER_BODY,EVENT_OBJECT_TABLE TABLE_NAME,TRIGGER_SCHEMA,EVENT_OBJECT_SCHEMA from information_schema.TRIGGERS Where EVENT_OBJECT_SCHEMA='?1' and EVENT_OBJECT_TABLE='?2'
```
字段列：
- `TRIGGER_NAME`：String 触发器的名称
- `TRIGGER_BODY`：String 触发器定义的内容
- `TABLE_NAME`：String 表的名称
- `TRIGGER_SCHEMA`：String 触发器所在schema
:::tip 提示
SQL模板中必须包含`TRIGGER_NAME`、`TRIGGER_BODY`、`TABLE_NAME`此三个字段。
:::
### getTriggerMeta{#gettriggermeta}
返回一个用于查询查询触发器信息的SQL。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
SELECT TRIGGER_NAME,ACTION_STATEMENT TRIGGER_BODY,EVENT_OBJECT_TABLE TABLE_NAME from information_schema.TRIGGERS Where EVENT_OBJECT_SCHEMA='?4' and EVENT_OBJECT_TABLE='?1'
```
字段列：
- `TRIGGER_NAME`：String 触发器的名称
- `TRIGGER_BODY`：String 触发器定义的内容
- `TABLE_NAME`：String 表的名称
:::tip 提示
查询SQL返回的字段顺序以及字段名称必须和字段列中的字段一致。
:::
### getTableStorageSpace{#gettablestoragespace}
查询一个表占用的存储空间的大小，返回一个单行单列的查询结果，单位为byte。SQL模板参数参考[dropTableIfExists](#droptableifexists)属性。
示例：
```sql
SELECT data_length as TABLE_SPACE from information_schema.tables where TABLE_SCHEMA='?4' and TABLE_NAME='?1'
```
### insertOnDuplicate{#insertonduplicate}
保存一行数据，根据主键判断数据是否存在，不存在就执行insert语句，存在执行update语句。
示例：
```sql
INSERT INTO ?1 (?2) VALUES (?3) DUPLICATE KEY UPDATE ?5
```
SQL模板参数：
1. `tableName`：写入的目标表表名。
2. `insertFields`：insert写入的字段名列表。
3. `insertValues`：insertFields字段列表对应的值。
4. `keyFields`：主键列表。
5. `updateFields`：当数据已存在时执行的更新。
### mergeInto{#mergeinto}
构造一个`merge into`语句，将表或者SQL查询结果插入到目标表中，此语句较为复杂，一般通过Freemarker文件独立配置，并在这里指定配置文件路径。详细配置参考[merge.ftl](./merge-ftl.md)。
### createTable{#createtable}
构造一个`create table`语句，此语句较为复杂，一般通过Freemarker文件独立配置，并在这里指定配置文件路径。详细配置参考[create-table.ftl](./createtable-ftl.md)。
### alterTable{#altertable}
构造一个`alter table`语句，此语句较为复杂，一般通过Freemarker文件独立配置，并在这里指定配置文件路径。详细配置参考[alter-table.ftl](./altertable-ftl.md)。
### createView{#createview}
构造一个`create view`语句，此语句较为复杂，一般通过Freemarker文件独立配置，并在这里指定配置文件路径。详细配置参考[create-view.ftl](./createview-ftl.md)。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/sqlTemplates/merge-ftl.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/merge.ftl"
title: "merge-ftl"
---
---
order: 12
navTitle: merge.ftl
---
# merge.ftl
在merge.ftl文件中构造一个SQL模板，使数据库支持一个将表或SQL查询结果插入或更新到目标表的`merge into`语句以及一个将特定values插入或更新到目标表的`merge into`语句。
```json
INSERT<#if !(updateFields??)> IGNORE INTO ${tableName}<#if insertFields??> (${insertFields})
<#--来源是数据表-->
<#if usingTable??>
SELECT ${insertValues} FROM ${usingTable} ${usingAlias}<#lt>
<#elseif updateFields??><#--来源是sql，且有update列表，因为update列表中需要别名，需要包一层sql-->
SELECT ${insertValues} FROM (<#lt>
${usingSql}<#lt>
) ${usingAlias}<#lt>
<#else>
${usingSql}<#lt>
<#--有update-->
<#if updateFields??>ON DUPLICATE KEY UPDATE ${updateFields}
```
:::tip 提示
1. 若数据库不支持`merge into`语句，可以配置为类似功能的`insert into`语句。
2. 若不配置此模板，将默认使用标准的`merge into`语句。
:::
### SQL模板参数{#sql-template-parameters}
- `tableName`：目标数据表表名。
- `tableAlias`：目标数据表的别名。
- `insertFields`：插入的字段名列表，此参数不为空。直接引用此参数会输出经过逗号分割的字段名，如`field1,field2...`。
- `insertValues`：insertFields字段列表对应的值，引用此参数时的输出格式同`insertFields`。
- `updateFields`：当数据已存在时执行的更新，直接引用此参数可以输出对应的字段名和值，如`field1=value1,field2=value2...`；如果不存在此参数，表示忽略已存在的数据。
- `usingTable`：数据来源表表名，若此参数存在，表示需要将此表的数据合并到目标表，要求表中的字段名与目标表保持一致。
- `usingSql`：执行merge的数据来源sql，若`usingTable`为空，则取这个值的参数。
- `usingAlias`：数据来源表或者sql的别名，此参数不为空。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/sqlTemplates/createtable-ftl.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/createtable.ftl"
title: "createtable-ftl"
---
---
order: 13
navTitle: create-table.ftl
---
# create-table.ftl
在create-table.ftl文件中构造一个SQL模板，使数据库支持`create table`语句。
```json
<#--创建表-->
CREATE TABLE ${tableName} (
<#list columns as col>
<#--mysql的varchar,char类型字段值默认不区分大小写，不符合常规需求，需要设置BINARY使字段值区分大小写。-->
<#assign isVarchar = col.dbType=="VARCHAR"||col.dbType=="CHAR" || col.dbType=='LONGTEXT'>
${col.name+" "}<#rt>
<#if col.autoInc!false>
BIGINT NOT NULL AUTO_INCREMENT<#t>
<#else>
${col.typeDeclaration}<#if isVarchar> BINARY<#t>
<#if !col.nullable!true> NOT NULL<#t>
<#if col.defaultValue??> DEFAULT ${col.defaultValue}<#t>
<#if col.unique!false> UNIQUE<#t>
<#if col.comment??> COMMENT '${col.comment}'<#t>
<#if !col?is_last || primaryKey??>,<#lt>
<#if primaryKey??> PRIMARY KEY (<#rt>
<#list primaryKey.parts as part>
${part.column}<#sep>, <#t>
)<#lt>
)<#if tableComment??> COMMENT '${tableComment}' ENGINE=InnoDB;
<#--创建索引-->
<#if indexes??>
<#list indexes as index>
CREATE<#if index.unique!false> UNIQUE INDEX ${(index.name)!(index.aname)} ON ${tableName} (<#t>
<#list index.parts as part>
${part.column}<#sep>, <#t>
);<#lt>
```
### SQL模板参数{#sql-template-parameters}
#### tableName{#tablename}
需要新建的数据库表表名。
#### createIfNotExists{#createifnotexists}
TODO
#### selectStatement{#selectstatement}
查询sql，存在此参数时说明要构造`create table xxx as select ...`语句，根据查询的SQL新建数据表，并在创建表的同时写入表数据。
#### likeTableName{#liketablename}
要复制表结构的源表名称，存在此参数就表示要构造`create table xxx like...`语句，此参数类似[tableName](#tablename)参数是一个完整的表名。
#### tableComment{#tablecomment}
表注释，为null时表示该表没有表注释，在Freemaker文件中该属性已经进行转义，可以通过`tableComment.value`属性访问未经转义的原值。
#### tableType{#tabletype}
数据库表类型，具体类型如下所示：
- `TABLE`：物理表，可以select和update数据
- `LOCAL_TEMPTABLE`：本地临时表，只在当前连接可见，当前连接物理关闭时删除
- `GLOBAL_TEMPTABLE`：全局临时表，所有连接可见，通常是引用过它的连接关闭时自动删除
#### columns{#columns}
字段列表，是一个数组对象，每一个元素都是一个字段。
属性如下：
- `name`：数据库表字段名。
- `comment`：字段注释，没有时返回`null`。
- `length`：字段长度
- `scale`：小数位位数，一般用于浮点型字段。
- `dbType`：字段类型，如`INT`、`VARCHAR`。
- `typeDeclaration`：带长度的字段类型的定义，如如`VARCHAR(12)`。
- `autoInc`：是否为自增长，为true表示自增长。
- `nullable`：能否为空，为true表示可以为空。
- `unsigned`：是否带有符号，true表示无符号，当为false时，可以存储负数。
- `defaultValue`：默认值，一般为一个单引号括起来的字符串或者是表达式。
- `primaryKey`：是否为主键，为true表示是主键。
#### primarKey{#primarkey}
设置主键字段，此处为一个索引对象，属性与[indexes](#indexes)中的索引对象一致。
#### indexes{#indexes}
索引列表，一般为一个数组对象，每一个元素都是一个索引。
属性如下：
- `name`：推荐索引名，可以为空，这里是建议索引名，如果元数据是从其他的库中读取的，该属性可能是索引在源库的索引名，若该索引名无法使用，会使用下面的`aname`作为新的索引名。
- `uname`：强制索引名，可以为空，当此属性存在时创建表应直接使用这里指定的索引名。
- `aname`：自动索引名，不可为空，当上述`name`属性无法使用时会使用这里自动生成的索引名，此索引不会和其他对象的索引名冲突。
- `unique`：是否为唯一索引。
- `cluster`：是否为聚集索引。
- `enable`：是否启用。
- `columns`：索引的字段列表。
- `name`：索引的字段名。
- `sort`：排序情况，默认为空，可以为空、DESC或者ASC。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/sqlTemplates/altertable-ftl.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/altertable.ftl"
title: "altertable-ftl"
---
---
order: 14
navTitle: alter-table.ftl
---
# alter-table.ftl
在alter-table.ftl文件中用Freemaker构造一个SQL模板，使数据库支持`alter table`语句。
```json
<#--修改表ftl模板-->
<#--修改表注释-->
<#if (originAttributes.tableComment)?? && !(attributes.tableComment)??>
ALTER TABLE ${tableName} COMMENT '';
<#elseif (alterAttributes.tableComment)??>
ALTER TABLE ${tableName} COMMENT '${alterAttributes.tableComment}';
<#--新增字段-->
<#if newColumns??>
<#list newColumns as col>
<#assign isVarchar = col.dbType=="VARCHAR"||col.dbType=="CHAR"|| col.dbType=='LONGTEXT'>
ALTER TABLE ${tableName} ADD ${col.name+" "}<#t>
<#if col.autoInc!false>
BIGINT NOT NULL AUTO_INCREMENT<#t>
<#else>
${col.typeDeclaration}<#if isVarchar> BINARY<#t>
<#if !col.nullable!true> NOT NULL<#t>
<#if col.defaultValue??> DEFAULT ${col.defaultValue}<#t>
<#if col.unique!false> UNIQUE<#t>
<#if col.comment??> COMMENT '${col.comment}';<#lt>
<#--删除字段， `删除`放到`新增`的下面，避免既有添加又有删除的时候，因为删除所有字段，导致数据库抛出异常-->
<#if dropColumns??>
<#list dropColumns as col>
ALTER TABLE ${tableName} DROP COLUMN ${col};<#lt>
<#--删除主键-->
<#if (primaryKey.drop)?? && primaryKey.drop>
ALTER TABLE ${tableName} DROP PRIMARY KEY;<#lt>
<#--新增主键-->
<#if (primaryKey.parts)??>
ALTER TABLE ${tableName} ADD PRIMARY KEY (<#t>
<#list primaryKey.parts as part>
${part.column}<#sep>, <#t>
);<#lt>
<#--修改字段-->
<#if alterColumns??>
<#list alterColumns as col>
<#assign alterAttrs=col.alterAttributes>
<#assign originAttrs=col.originAttributes>
<#assign attrs=col.attributes>
<#assign isVarchar = originAttrs.dbType=="VARCHAR"||originAttrs.dbType=="CHAR"||originAttrs.dbType=='LONGTEXT'>
<#if alterAttrs.autoInc!false>
<#--修改自增长-->
ALTER TABLE ${tableName} MODIFY ${originAttrs.name} BIGINT NOT NULL AUTO_INCREMENT<#t>
<#if (originAttrs.comment)?? && !(attrs.comment)??> COMMENT ''<#elseif (alterAttrs.comment)??> COMMENT '${alterAttrs.comment}'<#elseif (originAttrs.comment)??> COMMENT '${originAttrs.comment}';<#lt>
<#elseif alterAttrs.originalName??>
<#--字段更名-->
ALTER TABLE ${tableName} CHANGE ${alterAttrs.originalName} ${alterAttrs.name} ${originAttrs.typeDeclaration}<#if isVarchar> BINARY<#t>
<#if !originAttrs.nullable!true> NOT NULL<#t>
<#if originAttrs.defaultValue??> DEFAULT ${originAttrs.defaultValue}<#t>
<#if originAttrs.unique!false> UNIQUE<#t>
<#if (originAttrs.comment)??> COMMENT '${originAttrs.comment}';<#lt>
<#elseif alterAttrs.typeDeclaration??>
<#--更改字段类型-->
ALTER TABLE ${tableName} MODIFY ${originAttrs.name} ${alterAttrs.typeDeclaration}<#if alterAttrs.dbType=="VARCHAR"||alterAttrs.dbType=="CHAR"> BINARY<#t>
<#if (alterAttrs.nullable)??><#if !alterAttrs.nullable> NOT NULL<#else><#if !originAttrs.nullable!true> NOT NULL<#t>
<#if (alterAttrs.defaultValue)??> DEFAULT ${alterAttrs.defaultValue}<#else><#if originAttrs.defaultValue??> DEFAULT ${originAttrs.defaultValue}<#t>
<#if (alterAttrs.unique)??><#if alterAttrs.unique> UNIQUE<#else><#if originAttrs.unique!false> UNIQUE<#t>
<#if (originAttrs.comment)?? && !(attrs.comment)??> COMMENT ''<#elseif (alterAttrs.comment)??> COMMENT '${alterAttrs.comment}'<#elseif (originAttrs.comment)??> COMMENT '${originAttrs.comment}';<#lt>
<#else>
<#--修改字段属性，比如长度，nullable，defaultValue，unique，comment-->
ALTER TABLE ${tableName} MODIFY ${originAttrs.name} ${originAttrs.typeDeclaration}<#if isVarchar> BINARY<#t>
<#if (alterAttrs.nullable)??><#if !alterAttrs.nullable> NOT NULL<#else><#if !originAttrs.nullable!true> NOT NULL<#t>
<#if (alterAttrs.defaultValue)??> DEFAULT ${alterAttrs.defaultValue}<#else><#if originAttrs.defaultValue??> DEFAULT ${originAttrs.defaultValue}<#t>
<#if (alterAttrs.unique)??><#if alterAttrs.unique> UNIQUE<#else><#if originAttrs.unique!false> UNIQUE<#t>
<#if (originAttrs.comment)?? && !(attrs.comment)??> COMMENT ''<#elseif (alterAttrs.comment)??> COMMENT '${alterAttrs.comment}'<#elseif (originAttrs.comment)??> COMMENT '${originAttrs.comment}';<#lt>
<#--删除索引-->
<#if dropIndexes??>
<#list dropIndexes as index>
DROP INDEX ${index} ON ${tableName};<#lt>
<#--新增索引-->
<#if newIndexes??>
<#list newIndexes as index>
CREATE<#if index.unique!false> UNIQUE INDEX ${(index.name)!("IDX_AUTO_NAME_" + index?index)} ON ${tableName} (<#t>
<#list index.parts as part>
${part.column}<#sep>, <#t>
);<#lt>
```
### SQL参数模板{#sql-template-parameters}
#### tableName{#tablename}
目标数据表表名。
#### tableType{#tabletype}
数据库表类型，具体类型如下所示：
- `TABLE`：物理表，可以select和update数据
- `LOCAL_TEMPTABLE`：本地临时表，只在当前连接可见，当前连接物理关闭时删除
- `GLOBAL_TEMPTABLE`：全局临时表，所有连接可见，通常是引用过它的连接关闭时自动删除
#### originAttributes{#originattributes}
数据库表修改前的表属性，包括表注释，存储引擎，分布列等属性。
- `catalog`：
- `schema`：数据库表所在schema
- `tableName`：目标数据表表名。
- `mixedCase`：查询表时是否需要转义，为true表示此表的大小写和数据库标准不一致，需要进行转义。
- `tableType`：返回数据表的类型，具体可参考
- `tableComment`：返回表的注释，没有注释时返回`null`。
- `distributionColumns`：当目标数据库是分布式存储数据库时，返回分布字段的名称。
- `primaryKeys`：返回主键的值，没有时返回`null`。
- `indexes`：返回索引列表。
- `columns`：返回全部字段列表。
#### alterAttributes{#alterattributes}
返回修改后数据表的属性，结构同[originAttributes](#originattributes)，未修改的属性没有值。
#### attributes{#attributes}
返回修改后的完整的表属性，结构同[originAttributes](#originattributes)。
#### newColumns{#newcolumns}
新增字段的字段列表，是一个数组对象，每个元素都是一个字段，字段属性和[createtable-columns](/dev/extension-points/dbConnector/createtable/#columns)中的字段对象一致。
#### dropColumns{#dropcolumns}
需要删除的字段列表，是一个字段名数组。
#### alterColumns{#altercolumns}
需要修改的字段列表，包含了字段需要修改的所有信息，是一个对象数组。
属性如下：
- [alterAttributes](#alterattributes)
- [originAttributes](#originattributes)
- [attributes](#attributes)
#### primarKey{#primarkey}
若SQL模板中存在此属性，表示主键有修改，此对象和索引对象可以访问的属性一致，并新增一下2个属性：
- `drop`：为true表示需要删除原主键，如果原来的表有主键，但是新主键是不同的字段，需要先`drop`掉原来的主键。
- `columns`：新主键的字段列表。
#### newIndexes{#newindexes}
新增的索引，是一个数组对象，每一个元素都是一个索引，可访问的属性参考[createtable-indexes](/dev/extension-points/dbConnector/createtable/#indexes)。
#### dropIndexes{#dropindexes}
要删除的索引列表，是一个数组对象，每个元素都是要删除的索引名称。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/sqlTemplates/createview-ftl.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/createview.ftl"
title: "createview-ftl"
---
---
order: 15
navTitle: create-view.ftl
---
# create-view.ftl
在create-view.ftl文件文件中用Freemaker构造一个SQL模板，使数据库支持`create view`语句。
```json
<#--创建视图。-->
CREATE <#if createOrReplace??>OR REPLACE VIEW ${tableName} AS
${selectStatement}
```
:::tip 提示
`create view`语句也可直接使用参数模板配置，如`CREATE[ ?2] VIEW ?1 AS ?3`。
:::
### SQL模板参数{#sql-template-parameters}
`create view`的模板参数与[createtable.ftl](/dev/extension-points/dbConnector/createtable/#sql-template-parameters)中的模板参数基本一致，差异参数如下所示：
#### selectStatement{#selectstatement}
查询sql，属性可参考[createtable.ftl](/dev/extension-points/dbConnector/createtable/#selectstatement)，此参数在模板中表示为`?3`，并总是在模板中存在。
#### tableType{#tabletype}
创建的视图类型，可以为`VIEW`、`MATERIALIZED_VIEW`。
#### createOrReplace{#createorreplace}
此参数在模板中表示为`?2`，在SQL中表现为`OR REPLACE`，表示如果视图存在则重新创建此视图。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/supports.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/supports"
title: "supports"
---
---
order: 10
navTitle: supports
---
# supports - SQL特性配置
配置一些数据库特性以及SQL方言，详细参数介绍可参考[数据库连接器扩展指南](./succ-dbconnector.md)中的`DbSupportsConf`方法。
### 配置项{#conf-items}
TODO
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/compitableVersions.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/compitableVersions"
title: "compitableVersions"
---
---
order: 11
navTitle: compitableVersions
---
# compitableVersions - 配置数据库其他版本兼容性
当数据库不同版本有一些配置不一致时，可以把默认配置以外的其他版本新增或修改的内容和选项配置在此属性中。
示例：
```json
"compitableVersions": {
">=8.0.0": {
"forbiddenSQLs": [...],
"compatibilityLevel": "...",
"errorIdentifyConfs": {...},
"sqlKeyWords": {...},
"dataTypes": {...},
"identifierTypes": {...},
"operatorTemplates": {...},
"sqlTemplates": [...],
"displayFormats": {},
"functionTemplates": {...},
"supports": {...}
}
}
```
:::tip 提示
1. `compitableVersions`中配置的顺序要保证高版本在前、低版本在后，系统会从上至下优先选用匹配的高版本的配置。
2. 版本号遵循[semver规范](https://docs.npmjs.com/cli/v6/using-npm/semver)，且必须为3位数字，示例可参考`capabilities.json`的[matchDbVersion](./capabilities-json.md#matchdbversion)属性。
:::
### 兼容性选项{#compatibility}
兼容性选项的配置与[capabilities.json](./capabilities-json.md)中的配置基本一致，下面列出一些不同的配置选项。
#### compatibilityLevel{#compatibilitylevel}
配置其他版本数据库的兼容级别，默认为`ALL`，详细配置可参考`pacakge.json`中的[数据库兼容级别](./package-json.md#compatibilitylevel)
#### sqlKeyWords{#sqlkeywords}
关键字列表，如果某个字段或表名是关键字，那么会需要转义。
1. 系统默认会读取JDBC驱动API提供的关键字列表，在这里的列表中加上`DONT_AUTO_INCLUDE_DRIVER_KEYWORDS`可禁用此功能。
2. 系统也会自动加上SQL 2003标准中的相关关键字，在这里的列表中加上`DONT_AUTO_INCLUDE_SQL2003_KEYWORDS`可禁用此功能。
3. 基于JDBC驱动API以及SQL 2003标准中的关键字，可以在这里补上自定义的关键字，形成一个完整的关键字列表。
#### identifierTypes{#identifiertypes}
描述数据库一个对象，如表、视图、存储过程等的类型信息。
示例：
```json
"identifierTypes"{
"type": "...",
"ignore": true|false
}
```
##### type{#type}
数据库对象在 SuccApp 内对应的对象类型，详细类型如下所示：
- `TABLE`：物理表，可以select和update数据
- `LOCAL_TEMPTABLE`：本地临时表，只在当前连接可见，当前连接物理关闭时删除
- `GLOBAL_TEMPTABLE`：全局临时表，所有连接可见，通常是引用过它的连接关闭时自动删除
- `CUBE`：多维数据集的查询对象类型
- `ESINDEX`：ES索引
- `VIEW`：视图
- `MATERIALIZED_VIEW`：物化视图
- `SYNONYM`：同义词
- `TRIGGER`：触发器
- `INDEX`：索引
- `CONSTRAINT`：约束
- `SEQUENCE`：序列
- `PROCEDURE`：存储过程
- `FUNCTION`：函数
- `UNKNOWN`：其他未知对象
##### ignore{#ignore}
每个数据库的对象类型可能有所区别，若数据库中没有指定的对象类型，可以配置`ignore`为true忽略这个类型，默认为false。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/dbConnector/succ-dbconnector.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/dbConnector/succ-dbconnector"
title: "succ-dbconnector - 数据库连接器扩展指南"
---
---
navTitle: succ-dbconnector
---
# succ-dbconnector - 数据库连接器扩展指南
<<< @/../../bi/com.succez.bi/web/static-file/types/extension/succ.dbconnector.d.ts
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/expressionFunction/README.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/expressionFunction"
title: "expressionFunction"
---
---
order: 1
navTitle: expressionFunction
indexTitle: 概述
---
# expressionFunction
表达式函数扩展可以扩展系统已有的函数列表，增加一个新的个性化的、业务化的、场景化的函数，方便用户使用，用户使用时可以和使用系统内部的函数一样。
系统提供了各种表达式函数（见[表达式函数](../../../../exp/func/README.md)），但在实际项目中，可能还是需要一些比较个性化的表达式函数，如：
1. 实现一个自定义的加密函数，如sm3、sm4，在前端、后端都需要用。
2. 实现一个便捷的从一段文本中提取出身份证号码的函数，在数据加工清洗过成中比较方便提取身份证。
3. 通过一个表达式函数获取用户的业务角色、岗位等信息，便于权限判断。
4. 实现时间由秒转时分秒格式自定义函数
## 快速开始
在开始之前，我们需要提前想好表达式函数的运行环境，运行环境包括前端浏览器环境、后端服务器环境、和数据库SQL环境，表达式函数不一定需要在每个环境中都能运行，能满足需求即可，可以都支持，也可以只在某个环境运行。
1. 如果能使用现有的表达式函数组合即可完成需求，那么可以直接配置[expTemplate](./package-json.md#exptemplate)，这样就不需要做其他的开发了，系统会自动适配各种运行环境。
2. 在前端浏览器环境运行，需要配置[jsScript](./package-json.md#jsscript)和[scriptFunc](./package-json.md#scriptfunc)。
3. 在后端服务器环境运行，需要配置[serverScript](./package-json.md#serverscript)和[scriptFunc](./package-json.md#scriptfunc)。
4. 在数据库SQL环境运行，需要配置[sqlTemplate](./package-json.md#sqltemplate)。
### 新建扩展{#create}
TODO
### 开发扩展{#dev}
1. 配置函数信息，见[package.json](./package-json.md)。
2. 开发需要的函数执行脚本，见[脚本开发](./script.md)。
### 测试和调试{#debug}
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/expressionFunction/package-json.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/expressionFunction/pacakge-json"
title: "package.json"
---
---
order: 3
navTitle: package.json
---
# package.json
`package.json`文件包含两部分信息：
- 扩展的基本信息，包含扩展名称、描述文字、作者、组件的npm依赖等。npm配置参考[npm package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json)。
- 组件扩展点的配置，包括组件的类名、分组、模板等。
组件扩展点中包含[通用扩展点配置](../../references/extension-contributor.md)的所有属性，并额外增加了下面的属性，可以配置一个或若干个表达式函数的信息。
```json
{
"contributes": {
"expressionFunction": [{
"name": "",
"description": "<函数的简短描述>",
"manURL": "<帮助文档，指向一个当前扩展目录下的md文件，如`GENDER.md`>",
"group": "<函数在函数列表中所在的分组，如string, math, others...>"
"arguments": [{
"name": "<参数名>",
"desc": "<参数描述>",
"type": "<参数类型，如C, N...>",
"optional": <参数是否可选>,
"repeatable": <参数是否可重复>
}],
"argumentsCount": <参数个数>,
"returnType" : "<返回类型，如C, N...>",
"returnArgType": <以第几个参数作为返回值类型，0开始>,
"expTemplate": "<表达式模板>",
"sqlTemplate": [{
"MySQL":"<在特定数据库使用的对应的SQL模板>"
}],
"jsScript": "<指定一个相对于当前扩展目录的前端脚本文件>",
"serverScript": "<指定一个相对于当前扩展目录的后端脚本文件>",
"scriptFunc": "<指定表达式在前端浏览器和后端运算时使用的脚本函数的函数名>",
"checkArgsFunc": "<指定一个js函数，用于检查函数参数的正确性>",
"renderSQLFunc": "<用于将表达式函数转换为可以执行的SQL表达式>",
"javaClass": "<指定一个java的实现类>"
},
{
...
}]
}
}
```
## 表达式函数扩展点配置选项{#expressionfunction}
下面是`expressionFunction`扩展点的配置选项。
### name
函数名，通常大写，用于唯一标识一个函数，不能和其他扩展函数或系统函数重名。
### description
函数的一句话简短描述，用于在表达式编辑器的函数列表中简要的提示函数的功能，如：`SM3加密函数`。
### manURL
帮助文档，指向一个当前扩展目录下的md文件，如`FUNC1.md`，用于在表达式编辑器的函数列表中现实函数的帮助信息，md文件的章节必须符合下面示例的规范（以函数名为`FUNC1`为示例）：
```markdown
# ****
<函数的一段简短的描述，用于快速了解函数的功能>
## 语法
<函数的一个简单的语法表述如`FUNC1(**str**, **start_index**, [**num**])`。>
<下面介绍参数列表：>
* **param1**：参数1的说明
* **param2**：参数2的说明
## 示例
<此处列出一些使用示例>
1. `FUNC1(...)` 示例1说明...
2. `FUNC1(...)` 示例2说明...
3. ...
```
### group
函数所在分组，用于在表达式编辑器的函数列表中把函数显示在合适的分组中，已有的分组包括：
1. analysis - 分析函数
2. aggregate - 聚集函数
3. string - 字符串函数
4. math - 数学函数
5. date - 日期函数
6. logic - 逻辑函数
7. transform - 转换函数
8. others - 其他函数
如有需要可输入任意分组。
### arguments
函数的参数列表，表示函数可以接受哪些参数，如果没有此定义，那么函数可以接受任意参数，参数列表是一个json数组，可以定义如下属性：
1. name 参数名
2. description 参数描述
3. type 参数的类型，可选项类似[returnType](#returntype)。
4. optional 为true表示参数是可选参数，如`find('test','es',1)`，第三个参数就可以不传，`find('test','es')`，表示从0开始查找。
5. repeatable 为true表示参数可以重复，如`caoncat`函数，其参数可以重复输入多个，如`caoncat('a')`、`caoncat('a','b','c')`、`caoncat('a','b')`……。
### argumentsCount
函数的参数个数，-1表示是不限个数但至少有一个，0表示无参数。不定义时根据[arguments](#arguments)中的信息自动判断参数个数。
### returnType
函数的返回值类型。函数的返回类型可以通过此属性明确定义，也可以来自某个参数的类型，见[returnArgType](#returnargtype)，也可以是动态判断的，见[checkArgsFunc](#checkargsfunc)。
如果要明确指定，那么可以配置此参数为下列值之一：
1. 'C' - 字符型
2. 'N' - 浮点型
3. 'I' - 整形
4. 'D' - 日期型
5. 'L' - 布尔型
6. 'R' - 数组
7. '\*' - 变体，匹配任意类型
### returnArgType
函数的返回值类型与某个参数的类型一致。只有当[returnType](#returntype)没有定义时，此参数才有效。
将此属性设置为对应参数在参数列表中的序号，从0开始。
### expTemplate
表示使用系统其他标准的函数来组装这个自定义函数。系统虽然提供了很多函数，在某些特定场景下也可以满足需要，但是写法可能不是那么业务化，此时可以利用系统已有的函数定义一些比较常用的、业务化的、场景化的函数，方便用户使用。
如果能使用函数组合完成扩展函数需求，那么可以直接配置`expTemplate`，这样就不需要做其他的函数脚本开发了，系统会自动适配各种运行环境。
示例：
1. 从文本中解析身份证号码，参数是S，函数模版：
```
REGEXP_EXTRACT(S,'([1-9]\\d{5}(18|19|([23]\\d))\\d{2}((0[1-9])|(10|11|12))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx])|[1-9]\\d{5}\\d{2}((0[1-9])|(10|11|12))(([0-2][1-9])|10|20|30|31)\\d{2}')
```
2. 从文本中解析电话号码，参数是S，函数模版：
```
REGEXP_EXTRACT(S,'(0\\d{2}-\\d{8}(-\\d{1,4})?)|(0\\d{3}-\\d{7,8}(-\\d{1,4})?)|((13[0-9])|(14[5|7])|(15([0-3]|[5-9]))|(1[7-8][0,5-9]))\\d{8}')
```
3. 15位身份证号码升级为18位，参数是P，函数模版：
```
IF(LEN(P)=15,CONCAT(MID(P,0,6),'19',MID(P,6,9),MID('10X98765432',((MID(P,0,1)*7+MID(P,1,1)*9+MID(P,2,1)*10+MID(P,3,1)*5+MID(P,4,1)*8+MID(P,5,1)*4+1*2+9*1+MID(P,6,1)*6+MID(P,7,1)*3+MID(P,8,1)*7+MID(P,9,1)*9+MID(P,10,1)*10+MID(P,11,1)*5+MID(P,12,1)*8+MID(P,13,1)*4+MID(P,14,1)*2)%11),1)),P)
```
说明：
1. 模版中可以通过引用[arguments](#arguments)中定义的参数的`name`来引用函数的参数。
### sqlTemplate
定义此函数"翻译"为数据库查询语言时使用的模版。
如果函数需要转换到SQL查询语言中在数据库中执行，那么需要配置此参数。此属性是一个JSON对象，key是数据库扩展的名字，见[数据库连接器扩展](../dbConnector/package-json.md#name)，如`MySQL`, `Oracle`, `OceanBase`, `OpenGauss`...。SQL模版的格式类似数据库连接器扩展中函数模版的格式，见[数据库扩展点配置选项](../dbConnector/capabilities-json.md#functiontemplates)。
说明：
1. 由于不同的数据库执行的SQL会有不同，所以需要针对不同的连接器分别定义，可以考虑按需定义。
2. 如果自定义函数不需要在DB中执行，那么不需要定义此属性。
3. 如果是通过[expTemplate](#exptemplate)配置的函数，那么不需要定义此属性，系统会自动根据模版引用的系统函数翻译SQL。
### jsScript
指定一个相对于当前扩展目录的前端脚本文件，用于提供[scriptFunc](#scriptfunc)指定的脚本函数。见[脚本开发](./script.md#frondend-script)。
默认`main.js`。
### serverScript
指定一个相对于当前扩展目录的后端脚本文件，用于提供[scriptFunc](#scriptfunc)指定的脚本函数。见[脚本开发](./script.md#backend-script)。
默认`main.action`。
### scriptFunc
指定表达式在前端浏览器和后端运算时使用的脚本函数的函数名。见[脚本开发](./script.md#frondend-script)。
### checkArgsFunc
指定一个js函数，用于检查函数参数的正确性。见[脚本开发](./script.md#frondend-script)。
### renderSQLFunc
指定一个js函数，用于将表达式函数转换为可以执行的SQL表达式。见[脚本开发](./script.md#frondend-script)。
### javaClass
指定一个java实现类。脚本在后端运行时，除了使用脚本开发，也可以选择使用java开发，脚本和java只需要选择一种。提供的java类需要实现`com.succez.commons.exp.ExtExpressionFuncContributor`接口。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/expressionFunction/script.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/expressionFunction/script"
title: "脚本开发"
---
---
order: 4
navTitle: 脚本开发
---
# 脚本开发
扩展表达式函数要完成自己的逻辑，就需要一些代码逻辑，本文介绍如何通过脚本语言开发扩展表达式函数。
表达式函数的运行环境包括前端浏览器环境、后端服务器环境、和数据库SQL环境，表达式函数不一定需要在每个环境中都能运行，能满足需求即可，可以都支持，也可以只在某个环境运行。
:::tip
如果能使用现有的表达式函数（见[表达式函数](../../../../exp/func/README.md)）组合即可完成需求，那么可以直接配置[expTemplate](./package-json.md#exptemplate)，这样就不需要做脚本开发了，系统会自动适配各种运行环境。
:::
## 前端脚本{#frondend-script}
如果函数要在前端浏览器环境运行，需要开发一个前端脚本文件，如 `script.ts`，代码示例如下：
```ts
export function func1(ctx: any, arg1: string, arg2: number): any | Promise {
//...
}
```
然后：
1. 配置[jsScript](./package-json.md#jsscript)为脚本的文件名，如 `script.js`，`script.ts` 编译后会生成 `script.js`。
2. 配置[scriptFunc](./package-json.md#scriptfunc)为函数名，如 `func1`。
如果在表达式编辑界面对于函数有些特殊的合法性检查机制，那么也可以开发一个前端脚本函数，专门用于检查函数参数的合法性，甚至根据参数返回动态的函数的类型，如：
```ts
export function checkfunc1Args(node: any, compileContext: any): void{
if (...){
//报告错误信息
compileContext.throwError("err.exp.expectArgument", node);
}
}
```
然后：
1. 配置[checkArgsFunc](./package-json.md#checkargsfunc)为函数名，如"func1"。
## 后端脚本{#backend-script}
如果函数要在后端服务器环境运行，需要开发一个后端脚本文件，如 `script.action.ts`，代码示例如下：
```ts
export function func1(ctx: any, arg1: string, arg2: number): any {
//...
}
```
:::tip
与前端函数不同，后端函数不支持返回异步结果。
:::
然后：
1. 配置[serverScript](./package-json.md#serverscript)为脚本的文件名，如 `script.action`，`script.action.ts` 编译后会生成 `script.action`。
2. 配置[scriptFunc](./package-json.md#scriptfunc)为函数名，如 `func1`。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/fappComponent.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/fappComponent"
title: "fappComponent - 报表填报应用组件扩展"
---
---
navTitle: fappComponent
---
# fappComponent - 报表填报应用组件扩展
报表填报应用内置了大量常用的组件，如文本输入、日期、密码输入组件等，能满足大部分的数据填报需求。在一些场景中也存在一些个性化的数据填报需求是内置组件无法满足的，此时就可以通过扩展一个新的表单输入组件来实现。
表单扩展组件可以做到和产品内置的组件一样的复用，由扩展开发者开发好组件扩展后，使用者可以像使用内置组件一样使用扩展组件。
本文讲述如何开发一个报表填报应用组件扩展。
## 扩展文件结构
1. [package.json](#package.json)定义扩展的配置信息
2. [main.ts](#main.ts)定义扩展组件
3. [api](#api)
4. [properties](#properties)
### package.json
示例如下：
#### 详细说明
属性 | 类型 | 必需 | 描述 |
| --- |---|---|---|
|id|string|是|组件类型id。|
|caption|string|是|组件标题，通过过国际化fapp.component.caption.xxxx.caption获得显示文字。|
|category|string|否|组件的分类。|
|group|string|否|分组，layout, input, other 通过国际化fapp.component.group.xxxx.caption 获得显示文字。|
|themeCategory|string|否|组件的主题分类。|
|icon|string|否|class或图片的url，icon-开头表示class，其他情况表示图片的url；当不传icon时，系统默认根据id传递图标。|
|depends|string|是|依赖的模块。|
|definitionClassName|string|是|组件定义的类名，来自公共依赖中。|
|implClass|string|是|实现类的名称或类本身。|
|storeEnabled|boolean|是|组件默认是否存储数据。|
|properties|JSON|是|属性栏配置。见][属性栏配置](#属性栏配置)。|
##### id
类型id，所有组件定义的类型id不能重复，比如edit表示文本输入组件，number表示数字输入，他们的category都是input。
如：`"id": "resselector"`,
##### caption
组件标题，通过过国际化fapp.component.caption.xxxx.caption获得显示文字。默认不配置，可以国际化信息中配置。
##### category
组件的分类。
如：`"category": "text"`
##### group
分组，layout, input, other 通过国际化fapp.component.group.xxxx.caption 获得显示文字。
如：`"group": "input"`
##### themeCategory
组件的主题分类。
##### icon
class或图片的url，icon-开头表示class，其他情况表示图片的url；当不传icon时，系统默认根据id传递图标。
如：`"icon": "resselector.svg"`
##### depends
依赖的模块。
如：`"depends": "main"`
##### definitionClassName
组件定义的类名，来自公共依赖中。
如：`"definitionClassName": "FAppResSelectorComponentBuilder"`
##### implClass
实现类的名称或类本身。
如：`"implClass": "FAppResSelectorComponent"`
##### storeEnabled
是否存储数据。
如：`"storeEnabled": true`
##### properties
组件属性栏的配置。
如：
```json
"properties": {
"formData": {
"propertyName": "formData",
"propertyType": "container",
"items": [
{
"propertyName": "type",
"propertyType": "combobox",
"layoutTheme": "formcombobox",
"itemIconVisible": true,
"captionIconVisible": true,
"captionTextField": "caption",
"multipleSelect": false,
"checkboxVisible": true
},
{
"propertyName": "titleSetting",
"expandVisible": false,
"propertyType": "group",
"items": [
{
"propertyName": "title",
"propertyType": "richTextEdit",
"saveTheme": true
},
{
"propertyName": "desc",
"propertyType": "textArea",
"layoutTheme": "formtextarea"
},
{
"propertyName": "visibleEnabled",
"propertyType": "checkbox"
},
{
"propertyName": "visibleCondition",
"propertyType": "expEdit",
"visibleCondition": "!!visibleEnabled",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
},
"showCaption": false
},
{
"propertyName": "editEnabled",
"propertyType": "checkbox"
},
{
"propertyName": "editCondition",
"propertyType": "expEdit",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
},
"showCaption": false,
"visibleCondition": "!!editEnabled"
},
{
"propertyName": "placeholder",
"propertyType": "edit"
}
]
},
{
"propertyName": "contentSetting",
"propertyType": "group",
"expand": false,
"inlineItem": {
"propertyName": "value",
"propertyType": "expEdit",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
}
},
"items": [
"defaultValue",
{
"propertyName": "calcCondition",
"propertyType": "expEdit",
"captionPosition": "top",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
}
}
]
},
{
"propertyName": "checkSetting",
"propertyType": "group",
"items": [
{
"propertyName": "notNull",
"propertyType": "checkbox"
},
{
"propertyName": "validEnabled",
"propertyType": "checkbox"
},
{
"propertyName": "validExp",
"propertyType": "expEdit",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
},
"visibleCondition": "!!validEnabled"
},
{
"propertyName": "validMessage",
"propertyType": "expEdit",
"contentType": "macro",
"fieldPanelImpl": {
"depends": "commons/tree",
"implClass": "Tree",
"iconVisible": true,
"dragable": true,
"dragMoveable": false
},
"visibleCondition": "!!validEnabled"
},
{
"propertyName": "setValidExp",
"propertyType": "link",
"showCaption": "false",
"enabled": true,
"visibleCondition": "!!validEnabled"
}
]
},
{
"propertyName": "advancedSetting",
"propertyType": "group",
"expand": false,
"items": [
{
"propertyName": "storeEnabled",
"propertyType": "checkbox"
},
{
"propertyName": "dbtable",
"propertyType": "combobox",
"itemIconVisible": true,
"captionIconVisible": false,
"visibleCondition": "!!storeEnabled"
},
{
"propertyName": "dbfield",
"propertyType": "combobox",
"itemIconVisible": true,
"captionIconVisible": false,
"arbitraryInputEnabled": true,
"type": "tree",
"visibleCondition": "!!storeEnabled"
},
{
"propertyName": "dbfieldConditionEnabled",
"propertyType": "checkbox",
"visibleCondition": "!!storeEnabled"
},
{
"propertyName": "dbfieldCondition",
"propertyType": "edit",
"visibleCondition": "!!dbfieldConditionEnabled"
},
{
"propertyName": "rememberLastValue",
"propertyType": "checkbox",
"visibleCondition": "!!storeEnabled"
},
{
"propertyName": "rootPath",
"propertyType": "edit"
},
{
"propertyName": "resourceType",
"propertyType": "combobox",
"multipleSelect": true,
"items": [
"all",
"tbl",
"fold"
]
}
]
}
]
},
"style": {
"propertyName": "style",
"propertyType": "container",
"items": [
"compStyle",
{
"propertyName": "inputTitleSetting",
"propertyType": "group",
"expand": true,
"items": [
{
"propertyName": "showTitle",
"propertyType": "checkbox",
"defaultValue": true,
"saveTheme": true
},
{
"propertyName": "titlePosition",
"propertyType": "combobox",
"items": [
"left",
"top"
],
"keyPrefix": "ppteditor.title.position",
"visibleCondition": "!!showTitle",
"saveTheme": true
},
{
"propertyName": "titleWidth",
"propertyType": "spinner",
"visibleCondition": "!!showTitle",
"suffix": "%",
"max": 50,
"min": 10,
"defaultValue": 30,
"saveTheme": true
}
]
},
{
"propertyName": "fontSetting",
"propertyType": "group",
"expand": false,
"items": [
{
"propertyName": "font",
"propertyType": "fontEditor",
"saveTheme": true,
"expand": false
}
]
},
{
"propertyName": "fill",
"propertyType": "fill",
"saveTheme": true
},
{
"propertyName": "border",
"propertyType": "border",
"saveTheme": true
},
{
"propertyName": "width",
"propertyType": "slider",
"saveTheme": true,
"visibleCondition": "widthVisible == true",
"max": 360,
"min": 70
},
{
"propertyName": "layoutSetting",
"propertyType": "group",
"expand": false,
"visibleCondition": "layoutVisible == true",
"inlineItem": {
"propertyName": "layout",
"propertyType": "combobox",
"saveTheme": true,
"items": [
"default",
"oneQuarter",
"oneThird",
"half",
"twoThirds",
"threeQuarters"
],
"defaultValue": "default",
"cleanIconVisible": true
},
"items": [
{
"propertyName": "inputBoxSize",
"propertyType": "selectPanel",
"captionPosition": "top",
"items": [
"small",
"middle",
"large"
],
"defaultValue": "middle",
"saveTheme": true
}
]
},
{
"propertyName": "padding",
"propertyType": "padding",
"saveTheme": true
},
{
"propertyName": "margin",
"propertyType": "padding",
"saveTheme": true
},
{
"propertyName": "conditionSetting",
"propertyType": "group",
"items": [
{
"propertyName": "conditionStyle",
"propertyType": "valueDecoratedButton"
}
]
}
]
}
}
```
### main.ts
示例如下：
#### 详细说明
一个组件包括数据对象Builder和UI对象Component。二者缺一不可。
##### 数据对象Builder
###### 数据对象Constructor
```typescript
constructor(args: FAppComponentBuilderArgs)
```
###### FAppComponentBuilderArgs
|属性名 | 类型 | 描述|
|--- | ---| ---|
|form|FAppFormBuilder|组件所属的表单。|
###### 组件编译Compile
```typescript
/**
* 分析组件中填报需要的属性。并且分析出模型字段信息。有可能一个组件需要对应多个字段。
*/
public compile(context: FAppExpContext): void;
```
##### UI对象Component
###### UI对象Constructor
```typescript
constructor(args: FAppComponentArgs)
```
当组件初始化时会通过构造函数初始化组件。
###### FAppComponentArgs
|属性名 | 类型 | 描述|
|--- | ---| ---|
|type|FAppComponentType|组件类型。扩展组件可自定义类型|
|builder|FAppComponentBuilder|组件的数据对象。|
|compiledInfo|FAppComponentCompiledInfo|组件编译信息，预览和填报界面需要传此参数。|
|viewMode|FAppViewMode|显示模式。包括编辑模式、预览模式和填报模式。|
|deviceType|DeviceType|设备类型。|
|dataManager|FAppFormsDataMgr|填写数据的管理对象。|
##### 加载数据
```typescript
/**
* 加载组件数据
*/
public loadData(data?: FAppComponentData): Promise;
/**
* 根据数据刷新状态和样式
*/
public doRefresh(compData: FAppComponentData, property?: string): void;
/**
* 值变化的事件,一般此时需要同步修改数据层数据。
*/
protected doChange(event: SZEvent, component?: Component, item?: any): void;
/**
* 增量刷新组件数据或属性
*/
public refreshData(data: FAppComponentData, property?: string): Promise;
/**
* 增量刷新组件内的浮动行。只有表格、列表、子表单等填报多行数据的组件才需要实现此方法。
* @param rows 发生修改的浮动行
*/
public refreshRows?(rows: Array<{
/** 浮动行数据 */
row: FAppFloatAreaDataRow,
/** 操作类型：`+`代表是新增的行，`-`代表是删除的行，无此属性代表是修改的行 */
op: '+' | '-'
}>): Promise
```
所有表单扩展组件都需要实现以上函数。
##### dispose
销毁组件，如清理组件DOM上绑定的事件。
#### 示例参考
示例 | 描述
| --- |---|
[resourceSelector](https://gitlab.succez.com/product/bi/tree/master/com.succez.bi/web/static-file/extension/extensions/succ-fappComponent-resourceSelector) | 资源选择组件。
### api
报表填报应用扩展开发接口中包括，`IFAppComponent`(组件扩展开发接口)。
场景一：如果想开发一个个性化输入组件，那么你需要实现`IFAppComponent`开发个性化组件。并实现该接口中一些方法。
### properties
#### 属性栏配置
表单扩展组件的属性栏配置定义在`fappComponent`下面的`properties`中，用于配置组件的属性名以及属性设置方式。
属性栏配置分为三个部分：
1. `data`,描述组件的数据。需要参与计算的属性应该放到分组下设置。
2. `style`,描述组件的样式。将组件存为一种组件风格时，会将该分组下的属性保存。
3. `action`,描述组件支持的交互行为，不配置时会提供全部的交互行为配置。系统默认提供了一系列的交互行为，这里设置组件支持哪些交互行为。
##### 基本结构
#### 国际化配置
国际化配置定义在`contributes`下面的`i18n`中。
如：
```json
"i18n": {
"zh_CN": {
"fapp.component.resselector.caption": "资源选择",
"fapp.component.resselector.defaultTitle": "资源选择",
"ppteditor.rootPath": "资源根目录",
"ppteditor.resourceType": "资源选择类型",
"ppteditor.resourceType.all":"全部",
"ppteditor.resourceType.tbl":"模型",
"ppteditor.resourceType.fold":"文件夹"
},
"en": {
"fapp.component.resselector.caption": "资源选择",
"fapp.component.resselector.defaultTitle": "资源选择",
"ppteditor.rootPath": "资源根目录",
"ppteditor.resourceType": "资源选择类型",
"ppteditor.resourceType.all":"全部",
"ppteditor.resourceType.tbl":"模型",
"ppteditor.resourceType.fold":"文件夹"
}
}
```
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/font.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/font"
title: "font - 字体扩展"
---
---
navTitle: font
---
# font - 字体扩展
为系统提供多个新的字体。在制作仪表板、报表等内容时可以选用合适的字体。一个字体文件扩展包需要包括以下内容：
1. [package.json](#package.json)定义扩展的配置信息
2. `字体.ttf` - 字体的ttf文件。格式为:`字体名.ttf`，可以有多个字体文件
3. `thumbnail.png` - 扩展缩略图。格式为：`图片名.png`
## package.json
```json
{
"name": "template-font-blank",/**扩展名，和扩展所在的目录同名**/
"displayName": "空白字体模板",/**扩展标题**/
"description": "一个空白的字体模板",/**扩展描述信息**/
"version": "1.0.0",/**扩展的版本**/
"thumbnail": "thumbnail.jpg",/**缩略图名称，可更改，建议用thumbnail.jpg**/
"compatibilities": {
"platform": "^4.0.0"
},
"author": {
"name": "YourName",/**发布者信息**/
"email": "name@xxx.com",
"homePage": "https://www.succez.com/"
},
"categories": [
"font"
], /**扩展所属类别，可以属于多个类别**/
"main": "main",
"contributes": {
"font": ["字体1","字体2"]
} /**扩展字体文件名称，可以有多个**/
}
```
:::tip
在`font`属性中是字体名称的数组。
:::
字体文件格式支持：eot、otf、ttf、woff、woff2，后缀名小写，如下表格所示：
| 字体文件格式 | 文件名 |
| :--------: | :-----: |
| eot | 字体.eot |
| otf | 字体.otf |
| ttf | 字体.ttf |
| woff | 字体.woff |
| woff2 | 字体.woff2 |
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/georole.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/georole"
title: "georole - 地理角色扩展"
---
---
navTitle: georole
---
# georole - 地理角色扩展
地理角色采用[GEOJSON](http://geojson.org/)格式，新增一个地理角色扩展后，数据表的字段可以选择使用该角色进行标记。
## 系统内置地理角色
## 增加自定义的地理角色
## 如何使用
### 场景一：使用静态地图显示湖北省各市的经济户口数量
- 展开行政区划字段，拖入市到地图的location数据区
- 地图控件判断拖入的是市，判断数据属于哪一个省，下载该省的地理数据并显示成地图
### 场景二：使用静态地图显示湖北省数据，并根据参数控制显示哪一个市的底图
不支持。
- 拖入行政区划字段到地图的location数据区
- 地图控件判断拖入的是行政区划，没有层次，那么显示全国地图
### 场景三：一开始显示湖北省的底图，点击市可以下钻到市
- 展开行政区划字段，拖入市到地图的location数据区
- 地图控件判断拖入的是市，判断数据属于哪一个省，下载该省的地理数据并显示成地图
- 下钻逻辑和其它图形一致
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/i18n.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/i18n"
title: "i18n - 国际化扩展"
---
---
navTitle: i18n
---
# i18n - 国际化扩展
为系统提供一个新的国际化语言或覆盖已有国际化语言中的部分内容。
```json
"contributes": {
"i18n": {
}
}
```
扩展目录结构如下：
1. `package.json`
2. `i18n/` 国际化相关的文件都放这个目录里（注意目录名必须是i18n，注意大小写）。
1. `en.properties` 英文国际化文件
2. `zh-CN.properties` 中文国际化文件
3. `ja.properties` 日文国际化文件
properties文件格式规范见。
TODO 补充更多关于国际化信息key的规范
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/icons.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/icons"
title: "icons - 图标扩展"
---
---
navTitle: icons
---
# icons - 图标扩展
为系统提供一个新的图标集。在制作仪表板、门户App等内容时都需要选用合适的图标，系统默认已经提供了一些可选字体图标，第三方也可以扩展新的图标。
## package.json
```json
{
// ...
"contributes": {
"font": "fontawesome", // 如果是字体图标，需要传递字体名称，不带后缀。支持eot、otf、ttf、woff、woff2后缀的文件。
"icons": {
"action": [ // 图标分类，可以是已有的图标分类，比如"action"、"tools"、"file"等等
{
"desc": "笑脸",
"code": "0xf118" // 字体图标编码，一般用0x开头的16进制，表示特殊编码的字体字符。
},
{
"desc": "篮球",
"image": "篮球.webp" // 图片图标路径，相对于扩展的icons目录。
},
// ...
],
"新分类1": [ // 图标分类，可以是新的自定义的分类，比如"新分类1"
{
"desc": "点赞",
"image": "thumbs-up.svg"
},
{
"desc": "点踩",
"image": "thumbs-down.svg"
}
// ...
],
// ...
}
}
}
```
扩展目录结构如下：
1. `package.json`
2. `fontawesome.ttf` - 字体图标的文件，支持ttf、woff，名称必须和`package.json`中的font设置相同。
3. `icons/` - 图标文件目录。
2\. `xxx.png` - 图片图标
3\. ... 可以有目录，目录里包含图片；如果有图片图标，那么一个文件一个图标
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/images.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/images"
title: "images - 图片扩展"
---
---
navTitle: images
---
# images - 图片扩展
为系统提供一个新的图片集。在制作仪表板、门户App等内容时都需要选用合适的图片，系统默认已经提供了一些可选图片，第三方也可以扩展新的图片。
## package.json
```json
{
// ...
"contributes": {
"images": {
"canvasBackground": [ // 图片分类，可以是已有的图片分类，比如"canvasBackground"、"containerBackground"等等
{
"image": "bg/1.png", // 图片图片路径，相对于扩展的images目录。
"labels": "color-blue", // 图片标签，以英文逗号分隔
"pictureFillInfo": { // 图片填充信息，可以不传
"type": "stretch", // 填充方式
}
},
{
"image": "bg/2.png",
"labels": "color-orange",
"pictureFillInfo": {
"type": "stretch"
}
}
],
"新分类1": [ // 图片分类，可以是新的自定义的分类，比如"新分类1"
{
"image": "animal/1.png"
},
{
"image": "animal/2.png"
},
]
// ...
}
}
}
```
扩展目录结构如下：
1. `package.json`
2. `images/` - 图片文件目录。
2\. `xxx.png` - 图片
3\. ... 可以有目录，目录里包含图片。
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/interaction.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/interaction"
title: "interaction - 交互行为扩展"
---
---
navTitle: interaction
---
# interaction - 交互行为扩展
分析模块内置了丰富的交互类型，同时用户还可以通过扩展交互类型提供更个性化的交互体验。
本文讲述如何开发一个 SuccApp 交互扩展。
## 扩展文件结构
1. [package.json](#package.json)定义扩展的配置信息
2. [api](#api) 定义扩展的执行逻辑
### package.json
TODO
### api
TODO
## 示例
TODO
---
url: "https://docs.succapp.com/v5/guide/dev/extension/extension-points/loginPage.md"
htmlUrl: "https://docs.succapp.com/v5/dev/extension-points/loginPage"
title: "loginPage - 登录页面扩展"
---
---
navTitle: loginPage
---
# loginPage - 登录页面扩展
为系统提供一个新的登录页面模版，登录页面扩展可以在[系统设置-登录页面设置](../../script/system-pages/login-page.md)中被选用，只有被选用后，登录页面扩展产生的登录页面才会真正生效。
登录页面扩展的机制就是提供一个模版给[系统设置-登录页面设置](../../script/system-pages/login-page.md)功能，并根据设置页面中用户的设置动态的生产一个HTML文件，最后将HTML存入元数据系统项目的指定位置（`/sysdata/public/login/index.html`）后登录页面就正式生效了。
## 扩展文件结构
```ts
/
├──package.json //定义扩展的配置信息
├──main.ts //扩展的主体代码，提供动态生产HTML文件内容的逻辑
├──thumbnail.png //缩略图
├──thumbnail-phone.png //系统设置中，选择登录页面模版时当用户切换到手机时使用
├──index.html //必须存在，可以使用响应式布局兼容多种设备
├──index.less //样式写这里
├──index.ts //默认不存在
└──images/ //图片存放目录
```
### package.json
```json
"contributes": {
"loginPage": {
/**
* 是否支持手机
*/
"supportPhone":boolean,
"properties":{
}
}
}
```
### index.html
`index.html`就是一个常规的html页面，开发者可以按需要自由进行编写，需要遵守一些约定，如需要存在一些约定了id或class的元素。
#### 系统自动注入到登录页面的内容
系统初始化一个登录页面时会先在后端加载 `index.html`内容并解析，然后自动注入一些内容到html页面后再发送给前端浏览器，注入的内容包括：
```html
xxx
...
...
```
#### 登录页面的典型DOM结构
开发者在开发自己的登录页面时可以不用自己在html中写上面自动注入的内容，一个典型的登录页面的结构如下：
```html