表达式

表达式可以配置的位置

表达式在 DeepUX 中可以出现在多个位置，不同位置对应的推荐用法如下：

• 控件属性

  • 常见属性：显示/隐藏、禁用、只读、默认值、动态值、选项来源等。

  • 典型用法：

    • 根据其他控件的值控制本控件是否展示或可编辑；

    • 根据筛选器或变量给控件带出默认值；

    • 根据数据源返回结果动态设置选项列表、占位提示等。

• 数据源配置

  • 常见位置：过滤条件、取数范围、查询参数、排序脚本等。

  • 典型用法：

    • 将筛选器/POV 的值作为数据源查询条件，实现“改条件即改结果”的效果；

    • 使用页面变量（如年份、组织）作为全局查询参数；

    • 在脚本模式下拼接复杂的维度表达式。

• 事件与动作配置

  • 常见位置：动作参数（跳转目标、传参内容、弹窗开关条件、批量操作明细等）。

  • 典型用法：

    • 点击按钮时，根据表单内容构造跳转参数；

    • 点击图表时，读取点击项的数据，修改筛选器控件的值，实现图表联动；

    • 在动作链中使用上一个动作的结果，决定后续是否继续执行或执行哪一条分支。

• 图表与样式相关配置

  • 常见位置：图表的轴/颜色配置、显示范围、数据标签内容、样式细节等。

  • 典型用法：

    • 根据数据动态计算坐标轴最大/最小值；

    • 按业务规则决定数据标签显示内容或颜色；

    • 根据当前筛选条件调整图表标题、副标题等。

常见的表达式变量

在表达式选择处，预置了固定值、控件值、UX变量等多个选择项以便快速配置，其本质都是转换成JS表达式来执行。

例如选择控件值后选择某一个控件，则代表填入了 $components.控件编码.value ，即获取该控件的值。

选择变量后选择某一个变量，则代表填入了 $var.变量编码 ，即获取该变量的值。

下方为不同变量对应的含义和用法，在表达式编辑器中可以看到所有支持的语法形式。 此外由于是基于JavaScript语言，因此也可以使用JavaScript的语法来编写表达式，例如执行循环、判断等复杂操作。

在UX中很多地方都可以使用表达式，例如禁用、隐藏属性，动态值、默认值，以及动作，在表达式编辑器中，我们将常用的变量和属性做成了属性树，展开不同的变量我们可以看到可以使用的属性：

例如，展开$components变量，会罗列画布中所有的控件，展开某个控件可以看到该控件下可用的属性，插入value属性，可以直接生成获取该控件值的表达式：

也可以使用数据源变量，插入某个数据源下的属性，直接生成获取该数据源属性数据的表达式：

除了插入属性直接生成表达式，也可以点击复制按钮，复制对应层级的变量名。

表达式编写建议

为了保证页面易维护、性能可控，建议在编写表达式时注意：

• 让表达式尽量“轻量、纯粹”

  • 适合放在表达式中的：简单的计算、拼接、条件判断、从控件/数据源中取值等；

  • 复杂的业务运算、跨多数据源的大量计算，建议放到模型/财务模型或 Python 数据源中处理，表达式只负责取结果并展示。

• 优先使用现有变量和模板

  • 通过表达式编辑器插入 $components、$dataSources、$system 等变量，可以减少手写错误；

  • 对于常见场景（联动筛选、级联选择、列表取当前行等），优先参考“常用示例”和模板，避免从零开始编写。

• 注意空值与异常情况

  • 写表达式时需考虑控件尚未填写、数据源尚未返回数据、变量为空等情况，必要时增加判空逻辑，避免表达式报错导致页面无法渲染；

  • 对于关键逻辑，建议在“如何调试”章节介绍的方式下先进行调试和验证。

• 避免在表达式中做副作用操作

  • 表达式应主要用于“根据当前状态计算一个值”，不建议在表达式中执行会改变外部状态的操作（例如主动调用接口、修改其他控件），此类逻辑更适合放在事件动作中配置。

常用示例

为了降低用户写JS表达式的成本以及方便用户更快速上手，我们将常见的表达式常见做成了示例模板，插入模板后只需替换控件编码/属性编码即可完成表达式的书写。

若不知道如何使用模板，可以点击模板，在下方会显示模板的说明和示例用法，参照说明替换对应的字符即可。

系统中的常见用法示例

以下示例来自一批实际 UX 页面配置，总结了在真实项目中高频出现的表达式用法，便于参考：

• 日期区间筛选 + DeepQL/分析查询联动

  • 场景：工单分析页面中，顶部有日期区间筛选器，底部多个图表和明细表需要按同一时间段过滤数据。

  • 配法：在多个数据源的查询配置中，将 datetime 等查询参数配置为日期区间控件的值（例如：$components.日期区间控件编码.value），并勾选“参数变化时自动执行”，实现用户一改时间区间，所有相关图表/表格同时刷新。

• 列表页筛选条件统一驱动多张图

  • 场景：一个页面中有“工单按项目”“工单按组件”“待处理工单按人”“工单按区域”等多个图表，共享相同的筛选条件（如项目、区域等）。

  • 配法：将筛选控件（如项目下拉、多选）配置在顶端，数据源的过滤条件统一引用这些控件值；表达式只负责取值（例如 $components.项目筛选器编码.value），图表本身只绑定数据源，不再单独维护筛选逻辑。

• 明细跳转与带参分析

  • 场景：从某个工单清单/统计图表跳转到工单详情页或其他分析页面，需要携带工单编号、项目编码等参数。

  • 事件与动作：

    • 事件：按钮的“点击”事件；或图表的“点击数值单元格”事件；

    • 动作：跳转内部页面 / 打开外部链接 / 跳转内部链接。

  • 配法：在上述事件下的跳转类动作参数中，通过表达式组合跳转参数，将当前行/当前点击项的数据（例如 $context.data.currentRow.字段编码 或 $components.表格编码.clickedRow.字段编码）拼到跳转链接或 UX 目标页面的参数中，在目标页面则通过 $urlQuery.参数名 或外部变量取回。

• 图表维度和标签的动态展示

  • 场景：工单分析中的柱状图/折线图，需要根据不同的维度（项目、组件、负责人等）展示不同标签或高亮部分数据。

  • 配法：在图表配置中，将维度和度量字段均来自同一个数据源，必要时通过表达式对标签内容进行简单拼接或格式化，例如显示“负责人名称 + 工单数量”，而不在表达式里做复杂统计。

• 默认查询时间范围

  • 场景：打开工单分析页面时，希望自动展示最近几个月的数据，而不是全部历史。

  • 配法：在数据源的过滤条件中使用固定值表达式配置默认时间范围（例如最近半年），同时为日期筛选控件配置相同的默认值。用户需要看其他时间段时，再通过控件修改并触发重新查询。

• 根据工单状态控制操作按钮可见性

  • 场景：工单列表或详情中，“关闭工单”“重新打开”“转派”等按钮，仅在特定状态下显示或可点击。

  • 配法：在按钮的“显示/隐藏”或“禁用”属性上配置表达式，例如：

    • 仅在待处理状态下显示关闭按钮：$components.status.value === 'open'；

    • 已关闭工单禁用编辑按钮：$components.status.value === 'closed'。

• 动态展示人名、项目名等说明性文本

  • 场景：页面顶部/卡片中展示“当前负责人：XXX”“当前项目：YYY”等说明文字，随筛选条件或当前行变化而更新。

  • 配法：在文本控件的内容中使用表达式拼接当前控件/数据源的值，例如：

    • 当前负责人：${$components.assignee_filter.value}；

    • 当前项目：${$dataSources.data_issue_list.currentPageData?.[0]?.project_name || '全部项目'}。

• 行内级联：选择项目后过滤负责人与组件

  • 场景：在工单创建/编辑表单中，先选择项目，再根据项目过滤“组件”“负责人”下拉框的可选项。

  • 配法：在组件、负责人下拉框的数据源或选项来源中，使用表达式引用项目控件值作为过滤条件，例如：

    • $components.project.value 作为数据源过滤条件中的一部分；

    • 或在选项表达式中用 filter/map 仅保留匹配当前项目的成员。

• 列表中按当前人过滤“我的待处理工单”

  • 场景：在工单列表/统计中，直接显示当前登录用户需要处理的工单。

  • 配法：在数据源过滤条件中同时使用系统变量和控件值，例如：

    • $system.userId 作为默认的经办人过滤条件；

    • 若页面上允许手动选择经办人，则表达式可写成：$components.assignee_filter.value || $system.userId。

• 动作链中复用上一个动作的结果

  • 场景：点击按钮先调用后台接口更新状态，再根据接口返回结果决定是否刷新列表或弹提示。

  • 事件与动作：

    • 事件：按钮的“点击”事件；

    • 动作链：例如先“执行Python/提交表单/调用系统动作”，再“查询数据源/刷新页面/弹出提示”等多个动作串联。

  • 配法：在后续动作的表达式参数中使用 $context.event.lastActionResult 或 $context.event.actionResults，根据前一个动作返回字段判断是否继续执行后续动作，或构造提示信息。

• 多选筛选器转成 DeepQL 需要的字符串

  • 场景：多选项目/区域后，将勾选的多个成员传给 DeepQL 或分析查询，要求以分号拼接。

  • 配法：在数据源过滤条件中使用类似表达式：($components.project_multi.value || []).join(';')，将数组转换成后台约定格式。

• 预算项目页面中的状态驱动型表达式

  • 场景：项目预算 UX 中，页面顶部的操作选择框（如“保存”“提交审批”“驳回”等）决定后续按钮、校验规则和流程分支。

  • 配法：在多个按钮、动作条件和校验规则中复用同一个控件值，例如：

    • 只有当操作选择为“保存”时，才允许执行保存动作：$components.select_操作编码.value == "save"；

    • 当操作选择为“审批”时，启用审批相关字段或动作：$components.select_操作编码.value == "approve"；

    • 在校验表达式中用 != "save" 等条件，约束某些字段在非保存场景下必须符合特定规则。

• 行内金额差额计算

  • 场景：预算明细表中，有“预算金额”“预计投资数量”等字段，需要按行计算差额或推导某个字段的值。

  • 配法：在卡片列表/可添加卡片或表格行的字段上配置表达式，根据当前行路径获取同一行的多个字段值做简单运算，例如：

    • 当前行可用额度 = 总额度 - 已用额度；

    • 通过 get($context.data.levelPath).value 方式拿到当前行控件的值，做加减乘除计算。

• 根据行数据控制行内按钮或字段

  • 场景：在可添加卡片或嵌套表格中，某些行若类型为 Capex/OpEx，则对应的编辑按钮或字段行为不同。

  • 配法：在按钮的显隐或禁用表达式中使用当前行数据字段值，例如：

    • bud_type != "Capex" 时禁用某个 Capex 专属操作；

    • 根据行内字段组合判断是否允许删除或修改。

• 跳转参数与嵌套结构 ID 管理

  • 场景：从预算明细中的某一条子记录跳转到另一个页面，或在当前页面内对某条子记录做行内操作，需要准确传递当前行 ID。

  • 配法：在动作参数中，通过 getId($context.data.levelPath) 取到当前卡片/行对应的业务主键，再作为跳转参数或后端调用入参，保证操作落在正确记录上。

这些实践的共同特点是：表达式主要承担“取值 + 轻量拼接/判断”的职责，真正的统计逻辑和数据加工集中在模型、分析查询或 DeepQL 中完成，这样既保证了页面配置简单可读，也便于后续维护和扩展。

常见的表格类表达式使用

由于表格类与控件有区别，额外列示表格中的表达式常见用法。 其中，context表示上下文，仅能在上下文环境中获取到数据，例如按钮抛出事件（context.event.data）等，脱离该环境，例如在文本中直接引用是无法引到的。 components.xx.属性则是额外封装了一部分可以直接引用的数据，更加直观。

常见的卡片列表表达式使用

常见的可添加卡片表达式使用