# 对象转换详情

QV2QS 在转换过程中处理一系列 QlikView 特有的功能。

## 表达式

QV2QS 将 QlikView 表达式传递给 Qlik Sense，仅进行少量转换。表达式语言在 QlikView 和 Qlik Sense 之间基本共享，因此大多数表达式无需修改即可工作。

QV2QS 应用以下转换：

* 等号前缀 — Qlik Sense 要求在度量表达式和某些属性表达式前使用一个前导的`=`。QV2QS 会在需要时添加前缀，如果原始 QlikView 表达式不包含前缀。
* 注释剥离 — 以`//`、`#`或`REM`开头的整行注释将从内联表达式中移除。Qlik Sense 属性表达式并非始终支持注释语法，因此剥离可以防止评估错误。块注释 (`/* */`) 不会被剥离。内联`//`代码行内的注释也不会被剥离。

以下表达式功能按原样传递，并在 Qlik Sense 中无需修改即可运行：

* 集合分析表达式（例如，`{<Year={2024}>}`）
* 美元符号扩展和变量引用（例如，`$(vMyVar)`）
* 嵌套 `Aggr()` 表达式
* `If()` 表达式，包括条件格式表达式
* `Pick()`、`Match()`和`Dual()`模式
* 计算维度

### 设置分析引用

QlikView（2017 年 11 月之前）将集合修饰符中的单引号值视为不区分大小写的搜索，与双引号值相同。Qlik Sense 将单引号值视为区分大小写的字面量。这种差异可能会破坏依赖于通配符、比较运算符或数字匹配的表达式。

QV2QS 扫描所有对象表达式和变量定义，以查找在 Qlik Sense 中行为方式不同的集合分析引用模式。检测到的模式包括单引号通配符(`'*US*'`)、单引号比较运算符(`'>=5'`)、数值字段上的单引号值以及未加引号的裸字符串值。结果显示在 Excel 报告的 Expression\_Findings 工作表中。

QV2QS 自动修复转换过程中的单引号搜索值。一个针对未加引号的裸字符串值的实验性修复也已提供，但默认禁用。

* 单引号搜索值（默认启用）将转换为双引号：`{<Country={'*US*'}>}` 变为 `{<Country={"*US*"}>}`。检测到的搜索模式包括通配符 (`*`, `?`, `^`), 比较运算符, 模糊搜索 (`~`), 表达式搜索 (`=`), 搜索修饰符 (`+`, `-`), 和复合搜索。在不包含搜索语法的数值字段上的单引号值会被标记以供手动审查，但不会自动修复。
* 未加引号的裸字符串值 (实验性，默认禁用) 会用单引号括起来：`{<Country={USA}>}` 变为 `{<Country={'USA'}>}`。传入 `--fixUnquotedSetValues` 以启用。

修复仅在集合修饰符值列表内通过位置替换应用。字段名称、函数名称以及其他表达式文本绝不修改。这两个修复是独立控制的。传入 `--noFixSingleQuotedSearch` 以禁用单引号修复。不支持的功能发现未被修改。

《Expression\_Findings》工作表和执行摘要仪表板包含一个Source列，指示每个发现是源自变量定义还是图表对象表达式。一个状态列显示发现结果是否已自动修复、需要手动审查，或者没有可用的自动修复。

有关检测到的模式的完整列表，请参阅[分析](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/analysis.htm)。有关集合分析语法参考，请参阅 [集合分析](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Scripting/set-analysis-set-operators-modifiers.htm) 中的 Qlik Cloud 帮助。

信息注释

QV2QS 扫描所有表达式字段（维度、度量、显示条件、颜色表达式、标题、计算条件及其他），以及变量定义和加载脚本，以查找不支持的函数。检测到的实例列在分析报告中。

以下 QlikView 专用函数在 Qlik Sense 中不可用：

* `GetCurrentField`, `GetExtendedProperty`
* `Input`, `InputSum`, `InputAvg`
* `MsgBox`
* `Image_Size`
* `NoOfReports`, `ReportComment`, `ReportId`, `ReportName`, `ReportNumber`

要查看检测到的加载脚本模式列表，请参阅[分析](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/analysis.htm)。

## 数字格式

QV2QS 将 QlikView 数字格式定义转换为 Qlik Sense 数字格式类型。格式类型映射到 Qlik Sense 等效项，并且自定义格式字符串 (`Fmt`)、小数位分隔符、千位分隔符和小数位精确度都按原样保留。自定义格式字符串，例如 `#,##0.00;(#,##0.00)` 或 `'$'#,##0`，会在 `qFmt` 字段中原样传递。

以下 QlikView 格式类型已映射：

| QlikView 类型 | Qlik Sense 类型 |
| --- | --- |
| 定点, 实数, 整数 | 固定 (F) |
| MONEY | 货币 (M) |
| DATE | 日期 (D) |
| TIME | 时间 (T) |
| TIMESTAMP | 时间戳 (时间戳) |
| INTERVAL | 间隔 (IV) |

## 排序

QV2QS 将所有 QlikView 排序条件转换为 Qlik Sense 等效项。以下排序设置是一一对应的：按状态排序、按频率排序、按数值排序、按字母顺序排序、按加载顺序排序、按表达式排序（包括表达式文本）和按灰度排序。

对于列表框字段，QV2QS 会应用额外的启发式算法来抑制在日期类字段上基于状态的排序。有关详细信息，请参阅[参数参考](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)。

## 视觉提示和条件着色

QlikView 视觉提示 (基于阈值的度量条件颜色) 将转换为 Qlik Sense 颜色表达式，用于表格和透视表可视化。QV2QS 生成嵌套的 `If()` 表达式，其中包含 `RGB()` 或 `ARGB()` 颜色函数，用于复制原始的低/正常/高 阈值 行为。文本颜色和背景颜色提示都已转换。图表可视化中的视觉提示（条形图、折线图、组合图及其他）未转换。

## 基于表达式的着色

QV2QS 将每个维度和每个度量的颜色表达式（背景颜色和文本颜色）转换为 Qlik Sense 属性表达式。对于表格和透视表可视化，背景色和文本颜色表达式都将保留 (`cellBackgroundColor` 和 `cellForegroundColor`)。对于图表可视化，度量背景颜色表达式被转换为 `colorByExpression` 模式。维度颜色表达式和度量文本颜色表达式不会针对图表类型进行转换，因为 Qlik Sense 图表不支持按维度颜色属性表达式或按度量文本颜色属性。

对于表格和透视表可视化，如果度量上没有明确的颜色表达式，但定义了视觉提示，QV2QS 会根据视觉提示阈值自动生成一个颜色表达式。

## 趋势线

QlikView 图表度量上的趋势线将转换为 Qlik Sense 趋势线。支持以下趋势线类型：

* 平均、线性、指数、对数、幂
* 多项式 (2次、3次和4次)

## 基准线

QlikView 参考线在图表轴上转换为 Qlik Sense 参考线。标签、值表达式、颜色、线条样式和显示条件（条件可见性表达式）将被保留。如果一个基准线没有显示条件，则默认可见性始终显示。组合图支持在主轴和次轴上使用参考线。

## 组合图表轴分配

QV2QS 保留 QlikView 组合图轴分配。每个度量都保留了原始 QlikView 图表的主轴或次轴绑定。测量系列类型（条形、折线、标记）也得到保留。

## 维度组

QV2QS 将 QlikView 循环组和钻取组转换为 Qlik Sense 主维度。循环组成为循环主维度。钻取组成为钻取主维度。引用组维度的图表连接到转换后的应用程序中相应的主维度。

## 字体处理

Qlik Sense 支持一组固定的网络安全字体。QV2QS 将 QlikView 字体映射到最接近的可用 Qlik Sense 字体。无法映射的字体使用备用字体 (Source Sans Pro)。

以下 QlikView 字体具有明确的映射：

| QlikView 字体 | Qlik Sense 字体 |
| --- | --- |
| Arial, Helvetica, Tahoma, Calibri | Source Sans Pro |
| Segoe UI | 国际 |
| Verdana | Open Sans |
| Times New Roman, Times, Georgia | PT Serif |
| Courier New, Consolas | Source Sans Pro |

不在 Qlik Sense 字体库中的自定义字体将映射到 Source Sans Pro。

信息注释

等宽字体 (Courier New, Consolas) 映射到比例字体 Source Sans Pro。等宽字符对齐未保留。

## 系统变量

QV2QS 从转换后的变量列表中排除系统变量。这些变量由 Qlik 引擎管理，并且不需要包含在 `variables.json` 中。示例包括`DateFormat`、`ThousandSep`、`DecimalSep`、`TimestampFormat`、`ErrorMode`和`NullDisplay`。

在加载脚本中明确设置的系统变量（例如，`SET DateFormat='YYYY-MM-DD';`）会在加载脚本中保留，并在重新加载时生效。此排除仅适用于转换后的应用程序中的变量定义，而不适用于加载脚本中的 `SET` 或 `LET` 语句。

用户定义的变量会转换。

## 网格模式

QlikView 图表，在启用晶格模式时 (`EnablePrimaryDimension`)，使用第一个维度作为分面字段来显示一个迷你图表网格。Qlik Sense 在标准图表上没有原生网格模式。QV2QS 使用可视化捆绑包中的 Qlik Sense 网格容器扩展 (`qlik-trellis-container`) 自动转换网格图。

在转换过程中，QV2QS 执行以下步骤：

1. 创建主可视化 — 原始图表在不包含网格维度的情况下进行转换。对于仅主轴网格，维度 0 已移除。当次级 Trellis 也启用时，维度 0 和 1 都被移除。剩余的图表在应用程序中保存为主可视化。
2. 创建网格容器 — 一个 `qlik-trellis-container` 对象放置在工作表上的原始图表位置。该容器引用主可视化，并使用已移除的维度作为其数据定义中的分面字段。当主和次级网格都启用时，容器数据定义包含两个分面维度。
3. 配置网格 — QlikView 的列和行设置映射到 trellis 容器的列数和最大图表数。图表的最大数量计算方式为列数乘以行数。当分面维度的基数超过网格大小时，QV2QS 会增加最大图表计数，以容纳所有维度值。对于次级网格，总基数是主维度和次维度基数的乘积。该值向上取整到列数的最近倍数，以便网格均匀填充。此扩展记录为图表调整。

Trellis 容器使用与原始图表相同的 qv\_id 映射，因此它在工作表上占据相同的位置。

仅主轴网格至少需要两个维度（一个用于网格分面，一个用于主图表）。主次交错网格至少需要三个维度（其中两个用于网格分面，一个用于主图表）。维度少于要求的图表会被跳过。

## 测量累积

QlikView 度量累加（运行总计）转换为 Qlik Sense 累加修饰符。支持以下累积模式：

* 完全累积 — 度量表达式使用 `RangeSum()` 与 `Above()` 和 `RowNo()` 重写，以生成所有行的运行总计。修饰符 `fullAccumulation` 标志设置为 `true`，`steps` 值为 6。
* 步长累积 — 当 QlikView 累积步长计数大于 1 时，度量表达式使用 `RangeSum()` 结合 `Above()` 以及指定的步长计数。修饰符 `fullAccumulation` 标志设置为 `false`。

生成的累积表达式适应维度字段类型：

* 数值维度 — 设置分析边界使用 `Min()` 和 `Max()` 用于该字段。
* 文本尺寸 — 设置分析边界，使用 `MinString()` 和 `MaxString()` 用于该字段。
* 二维图表 — 生成一个`Aggr()`包装器，以将累积嵌套在外层维度上下文中。

当应用累积时，QV2QS 禁用连续轴模式 (`preferContinuousAxis=false`) 并将 `nullMode` 设置为 `connect` 以确保正确的视觉渲染。原始度量表达式和标签保留在修饰符`base`属性中。

## 选项卡容器

QV2QS 会根据容器配置和上下文，使用三种策略转换 QlikView 选项卡容器。在所有情况下，子对象保留在与容器相同的 Qlik Sense 工作表中。

* 选项卡式容器 — 不与其他对象重叠的独立多个选项卡式容器将转换为原生 Qlik Sense 选项卡式容器 (`sn-tabbed-container`)。每个选项卡成员都会成为容器内的一个选项卡。选项卡顺序遵循原始的 QlikView 成员顺序。
* 伪选项卡 — 当多选项卡容器与其他对象重叠或嵌套在另一个容器中时，QV2QS 会将选项卡展平为一个布局容器。生成一个按钮条，其中包含一个`action-button`，每个选项卡对应一个。每个按钮设置一个导航变量，使用一个 `SetVariable` 动作。子对象上的显示条件（例如，`=If('$(vCT01Tab)'='1',1,0)`）控制哪些选项卡内容可见。一次只能看到一个选项卡。按钮条重现了原始 QlikView 容器的选项卡切换行为。
* 布局容器 — 网格模式下的容器被转换为布局容器 (`sn-layout-container`)。

单对象容器已简化。未创建选项卡条或变量。单个子对象直接放置在容器位置，并应用了容器显示条件。

支持深度达 8 级的嵌套容器。如果一个容器创建了循环引用，QV2QS 会检测到循环并停止递归。

容器和单个子对象的显示条件使用逻辑与进行组合。子对象仅在容器条件、选项卡变量条件和子对象条件全部评估为真时可见。

## 显示条件

QlikView 中单个对象的显示条件得到保留。Qlik Sense 不支持直接在可视化对象上设置显示条件。QV2QS 将具有显示条件的对象包装在一个单子布局容器中，并将该条件作为`condition`条目应用到该容器上。已在布局容器内的对象（由于重叠）直接接收容器条目上的条件。

当显示条件评估为假时，布局容器保留在网格位置，但不显示任何内容。隐藏的容器不会折叠或导致相邻对象重排。在动态网格和固定画布两种模式下，隐藏对象会在其原始位置留下空白空间。空白空间行为与 QlikView 一致，隐藏对象也会留下空白空间。

## 备用状态

QV2QS 保留替代状态分配。绑定到 QlikView 中备用状态的对象在 Qlik Sense 中保留相同的状态绑定。州名会精确保留。QV2QS 在部署期间在 Qlik Cloud 应用程序中创建所需的备用状态。在集合分析表达式中的备用状态引用（例如，`{[State2]<Year={2024}>}`）会原样传递，并在 Qlik Sense 中无需修改即可运行。

在仅本地模式下 (`--unbuildOnly`)，备用状态名称会写入到 `cloud/alternate_states.json` 项目子文件夹中（例如，`<outputDir>/Sales/cloud/alternate_states.json`）。在将输出部署到 Qlik Cloud 租户时，状态必须手动创建或通过 `qlik app build` 工具创建。

## 对象操作

QV2QS 转换按钮 (BU, BT) 和文本对象 (TX) 上的操作。包含操作的文本对象会提升为操作按钮 (`action-button`)。支持的动作类型包括导航、`SetVariable`、`SelectField`，以及其他在[转化结果](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/conversion-outcomes.htm)中记录的。

其他对象类型（图表、列表框、滑块和容器）上的操作不会转换。QlikView 支持 `OnActivate` 对任何对象类型执行操作，但 QV2QS 仅从按钮和文本对象 XML 中解析操作。非宏操作 (`SetVariable`、`SelectField`、导航) 附加到图表、列表框或其他非按钮对象时，在转换期间会被删除，并且不会出现在转换报告中。要查找已删除的操作，请在 PRJ XML 文件中搜索非按钮对象定义中的 `<Actions>` 元素。

信息注释

间隙扫描器检测跨所有对象类型的宏调用，用于报告目的。宏交叉引用在“分析”工作表中反映所有对象，而不仅仅是按钮。非按钮对象上的非宏操作类型不会被报告。

## 计算条件

以下可视化类型保留计算条件：条形图、箱线图、组合图、仪表图、折线图、玛丽麦高图、饼图、散点图、网格图、透视表、表格、树状图和瀑布图。

条件表达式和自定义错误消息（当条件不满足时向用户显示的文本）都应用于超立方体定义。如果原始 QlikView 对象没有自定义消息，Qlik Sense 会显示默认的计算条件消息。

不在上述列表中的可视化类型（包括漏斗图、雷达图和KPI）不接收计算条件。如果 QlikView 对象具有计算条件，并且目标可视化类型不支持该功能, 特性，则条件和消息都将被静默丢弃。

## 了解更多

* [转换范围](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/known-limitations/conversion-scope.htm)
* [对象类型映射](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/object-type-mapping.htm)
* [转化结果](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/conversion-outcomes.htm)
* [维度和度量限制](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-reference/dimension-and-measure-limits.htm)