# 轉換運作方式

轉換管道包含以下階段：

* 擷取 — 如果 `--generatePrj` 已啟用，QV2QS 會啟動 QlikView Desktop 以將 QVW 檔案擷取到 PRJ 資料夾中。QV2QS 使用隨附的可攜式引擎，除非偵測到 QlikView Desktop 的系統安裝。如需詳細資訊，請參閱 [QlikView Desktop 引擎](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/getting-started/qlikview-desktop-engine.htm)。
* 剖析 — QV2QS 會讀取 PRJ 資料夾並剖析每個物件定義、工作表版面配置、載入指令碼、變數以及文件屬性。QV2QS 也直接讀取 QVW/QVF 二進位檔，以擷取中繼資料、變數以及檔案中任何隱藏的載入指令碼。
* 轉換 — 每個 QlikView 物件會對應至一種 Qlik Sense 視覺化類型。維度、量值、運算式、樣式和版面配置位置會轉譯為 Qlik Sense JSON 格式。
* 寫入 — QV2QS 將轉換後的應用程式結構寫入輸出資料夾，作為一組 JSON 檔案。
* 部署 (僅限雲端模式) — QV2QS 會在租用戶上建立應用程式、上傳媒體、建置應用程式，並選擇性地使用資料重新載入應用程式。
* 報告 — QV2QS 會產生一份轉換報告，其中摘要了結果、自動化評分，以及任何需要手動追蹤的項目。

部署階段在建置至 Qlik Cloud 和匯出 QVF 模式下執行。在僅限本機模式中，QV2QS 會將轉換後的輸出寫入磁碟，而不會連線到 Qlik Cloud。報告階段在所有模式中執行。

## 轉換模式

QV2QS 支援三種轉換模式。在精靈的 設定 步驟中選擇模式，或使用對應的 CLI 旗標。

| 模式 | CLI 旗標 | Qlik Cloud 必要 | 輸出 | 部署階段 |
| --- | --- | --- | --- | --- |
| 建置至 Qlik Cloud | *(預設)* | 是 | 應用程式部署到租用戶 | 是 — 建立應用程式、上傳媒體、建置、發佈工作表 |
| 匯出 QVF | `--exportQvf` | 是 | 磁碟上的 QVF 檔案 | 是 — 在 Qlik Cloud 中建置應用程式，匯出為 QVF，然後刪除雲端應用程式 |
| 僅限本機 | `--unbuildOnly` | 否 | 建置資料夾與磁碟上的轉換報告 | 否 |

建置至 Qlik Cloud 是建議的移轉模式。匯出 QVF 有助於產生可攜式檔案，以便共用或匯入至不同的租用戶。僅限本機模式旨在用於評估與檢閱。如需僅限本機限制的詳細資訊，請參閱下方的區段。

資訊備註

使用者介面預設為固定畫布模式、重新載入已啟用和自動二進位已啟用。CLI 預設為動態格線模式、重新載入已停用，且自動二進位已停用。從精靈模式切換到 CLI 時，請明確指定這些旗標以符合精靈模式的行為。如需引數和預設值的完整清單，請參閱 [引數參考](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)。

## 本機專用模式

本機專用模式 (`--unbuildOnly`) 執行解析、轉換、寫入和報告階段，無需連線至 Qlik Cloud。不需要租用戶或 API 金鑰。QV2QS 會在磁碟上生成完整的轉換報告、執行摘要和建置輸出資料夾。

### 使用案例

* 移轉評估 — 執行僅限本機模式，以產生轉換報告、執行摘要、自動化分數和運算式發現，而無需 Qlik Cloud 存取權。在設定租用戶憑證之前，評估整個 QVW 資產的轉換品質。
* 部署前檢閱 — 在提交至雲端部署之前，檢查產生的輸出 (載入指令碼、物件定義、變數、維度)。具有變更控制流程的組織可以將輸出視為中間產物進行審查。
* 離線或受限環境 — 當託管 QVW 檔案的機器沒有對外網際網路存取權時，請執行「僅限本機」模式以在本機產生轉換報告。若要部署已轉換的應用程式，請將 QVW 檔案複製到可存取 Qlik Cloud 的機器，並從已連線的機器以建置至 Qlik Cloud 模式執行 QV2QS。

### 限制

「部署」階段處理了數項操作，這些操作是 `qlik app build` 本身無法執行的。執行僅限本機模式，然後手動部署 `build/` 資料夾，並使用獨立的 [qlik-cli](https://qlik.dev/toolkits/qlik-cli/) 安裝，會導致以下不足之處。

* 媒體檔案未上傳。背景圖片和按鈕圖片會被提取到`images/`資料夾，但不會包含在`build/`資料夾中。`qlik app build` 命令不會處理媒體檔案。所有背景圖片和按鈕圖片將會從已部署的應用程式中遺失。
* 工作表和物件背景參考未解析。QV2QS 在部署階段期間，使用雲端應用程式 ID 將背景圖片 URL 注入到工作表和物件 JSON 檔案中。本機建置輸出不包含背景圖片參考。工作表和物件在已部署的應用程式中將沒有背景。
* 按鈕圖片 URL 包含預留位置字串。本地建置輸出中的按鈕圖片使用內部預留位置值，而非已解析的媒體 URL。Qlik Sense 引擎無法解讀預留位置字串。按鈕圖片將會顯示為損壞。
* 未建立替代狀態。備用狀態名稱會寫入 `cloud/alternate_states.json`，位於 `build/` 資料夾之外。`qlik app build` 命令不處理替代狀態。參考非預設狀態的物件可能無法正確顯示。
* 工作表未發佈。該 `qlik app build` 指令會建立工作表，作為僅對應用程式擁有者可見的個人物件。QV2QS 在部署階段將工作表發佈為基礎工作表。在共用空間中，其他使用者將看不到任何工作表，直到工作表手動發佈為止。

資訊備註

若要進行完整的部署，包括媒體上傳、背景解析、替代狀態建立和工作表發佈，請使用「建置至 Qlik Cloud 模式」或「匯出 QVF 模式」，而非「僅限本機模式」。

## 原始檔案安全性

QV2QS 不會修改來源 QVW 或 QVF 檔案的內容。在擷取階段，QV2QS 會透過 QlikView Desktop 開啟來源文件，並將暫存複本儲存到系統暫存資料夾。QV2QS 接著關閉原始檔案，並從暫存副本產生 PRJ 資料夾。PRJ 產生完成後，QV2QS 會將產生的 `-prj` 資料夾複製回與來源檔案相同的目錄中，並刪除暫存副本。如果來源檔案旁邊已經存在一個 `-prj` 資料夾，QV2QS 會將該資料夾替換為新生成的版本。所有其他轉換輸出會寫入由 `--outputDir` 指定的獨立輸出目錄。

QlikView Desktop 在建立暫存複本時，會鎖定來源文件。針對目前正在 QlikView Desktop 中開啟或由 QlikView Server 提供服務的檔案執行 QV2QS，可能會導致檔案鎖定衝突或 PRJ 產生失敗。共享網路磁碟機上的檔案可能會導致相同的衝突。將 `-prj` 資料夾寫回網路共用或唯讀目錄也可能失敗。

為避免對生產環境造成任何風險，請務必使用原始文件的副本進行操作。請執行下列動作：

1. 將 QVW 或 QVF 檔案複製到執行 QV2QS 的機器上的本機工作資料夾。
2. 將 QV2QS 指向複製的檔案，而非原始檔案。
3. 在開始轉換之前，請關閉所有正在執行的 QlikView Desktop 執行個體。QV2QS 需要獨佔存取 QlikView Desktop。

警告備註

請勿直接針對 QlikView Server 文件資料夾、生產網路共用資料夾，或在 QlikView Desktop 中開啟的檔案執行 QV2QS。務必使用來源文件的本機副本。

## 典型時程

QV2QS 專為速度而設計。完整的管道在數分鐘內完成，而非數小時。下表顯示單一應用程式轉換的典型持續時間。

| 階段 | 典型持續時間 | 備註 |
| --- | --- | --- |
| 擷取 (PRJ 產生) | 5–15 秒 | 取決於 QVW 複雜度。如果 PRJ 資料夾已存在，則已跳過。 |
| 解析 + 轉換 + 寫入 | 不到 30 秒 | 核心 XML 轉 JSON 轉換。處理包含數百個物件的複雜應用程式。 |
| 部署 (雲端建置) | 1–3 分鐘 | 包含應用程式建立、媒體上傳，以及在租用戶上建置應用程式。 |
| 載入 | 因情況而異 | 視資料量、資料來源延遲以及租用戶資源而定。典型的 QVW 的二進位載入在一分鐘內完成。 |

單一應用程式轉換搭配雲端部署和資料重新載入，通常會在兩到五分鐘內完成端對端作業。僅限本機的轉換 (`--unbuildOnly`) 在 30 秒內完成。

在批次模式下，QV2QS 會平行轉換多個專案。總批次時間 取決於 專案數量 除以 工作者數量 的比例。對於包含四個工作者的 20 個應用程式批次，預計本機轉換階段所需時間約為單一應用程式的五倍，加上雲端部署時間。

## 輸出資料夾結構

此 `--outputDir` 引數指定輸出根目錄。QV2QS 會在輸出根目錄內建立一個子資料夾，其名稱與 QVW 檔案 (或 PRJ 資料夾) 相同。專案的所有轉換輸出都會寫入該子資料夾。如果兩個 QVW 檔案共用相同的名稱，QV2QS 會附加`_2`、`_3`以及後續數字以避免衝突。此行為與批次模式相符，在批次模式中，每個專案也會收到一個專用的子資料夾。

```
<outputDir>/
  <ProjectName>/
    build/
    images/
    reports/
    logs/
    cloud/
    qvf/
```

QV2QS 會建立輸出資料夾，如果該資料夾尚未存在。如果資料夾在相同 QVW 的先前執行中已存在，QV2QS 會重複使用該資料夾。資料夾中現有的日誌檔案將被保留，除非清除日誌已啟用。輸出目錄不得與任何來源目錄相同或為其父目錄。QV2QS 在開始轉換之前驗證輸出路徑，如果路徑重疊則報告錯誤。專案子資料夾包含以下內容：

| 資料夾 / 檔案 | 目錄 |
| --- | --- |
| `build/` | Qlik Sense 應用程式結構，適用於`qlik app build`。包含 `config.yml` (建置資訊清單)、`script.qvs` (載入指令碼)、`app-properties.json`、`connections.yml` (資料連線)、`dimensions.json` (主維度)、`measures.json` (主量值)、`variables.json`，以及一個 `objects/` 子資料夾，其中包含每個工作表和視覺效果的一個 JSON 檔案。 |
| `images/` | 已擷取媒體檔案（依內容雜湊去重複）以及`backgrounds.json`（背景資訊清單）。 |
| `reports/` | `executive_summary.json`、`executive_summary.html` 以及 Excel 轉換報告 (`*_conversion_report_*.xlsx`) (如果已啟用)。 |
| `logs/` | 每次執行的結構化日誌檔案。 |
| `cloud/` | `cloud_state.json` (應用程式 ID、媒體雜湊、工作表 ID 對應、時間戳記) 和 `alternate_states.json`。在雲端部署期間建立。 |
| `qvf/` | 匯出的 QVF 檔案 (當 `--exportQvf` 使用時建立)。 |
| `.qv2qs_source` | 標記檔案，記錄了是哪個 QVW 產生了這個子資料夾。QV2QS 使用標記來偵測名稱衝突，並在後續執行時重複使用正確的資料夾。 |

提示備註

在轉換完成後，直接從精靈開啟輸出資料夾。

## 轉換後

轉換完成後，請依優先順序處理以下項目。

發布前修正

1. 在 `reports/` 子資料夾中開啟 Excel 轉換報告，並檢閱 追蹤物件 工作表。請先修正所有標示為錯誤的項目 (轉換失敗的物件)，然後修正預留位置的項目 (需要重建的物件)，最後修正需要調整的項目 (部分轉換的物件)。
2. 檢閱位於 分析 工作表上的分析結果，包括巨集參考、區段存取使用方式，以及可能需要手動處理的載入指令碼模式。
3. 驗證表達式是否正確評估。QV2QS 自動修正轉換期間的集合分析引號問題。檢閱需要手動重寫的計算維度、條件式色彩和使用僅限 QlikView 的函數 (`GetCurrentField()`, `MsgBox()`) 的運算式。
4. 檢查 溢出動作 工作表，以找出多餘的維度或量值已移至替代集合的物件。

發佈前驗證

1. 在 Qlik Sense 中開啟轉換後的應用程式，並驗證工作表版面配置、物件位置和背景影像是否如預期顯示。
2. 確認分頁容器導覽 (按鈕條或分頁式容器) 能正確地在內容區域之間切換。
3. 測試使用維度群組的圖表上的向下鑽研與循環群組循環行為。
4. 驗證顯示條件是否如預期隱藏和顯示物件。
5. 檢查列表框和表格中的排序順序，尤其是日期類型的欄位。

波蘭文

1. 視需要調整 Qlik Sense 應用程式編輯器中的字型、色彩或物件位置。如需版面配置位置的指引，請參閱[轉換版面配置設定](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)。

如需報告內容的完整說明，請參閱[轉換報告](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-results/conversion-report.htm)。

## 了解更多

* [快速入門](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/getting-started/quick-start.htm)
* [使用者介面](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/user-interface/index.htm)
* [命令列介面](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/index.htm)
* [轉換版面配置設定](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)
* [轉換結果](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-results/conversion-outcomes.htm)