Constrain

Constrain 陳述式可以與 Let 或 Set 陳述式合併使用，以定義指令碼變數。Constrain 陳述式可讓您對這些變數的可能值定義限制。如果變數定義違反限制，則載入會失敗。透過限制，您可以要求變數值符合特定類型、屬於特定數字範圍內並符合您定義的可接受值。

語法：

Constrain variablename = json

其中：

variablename 是指令碼變數。
json 是指定限制的有效 JSON 物件。各個限制以索引鍵/值組的形式在此物件中新增。

限制類型
限制類型 (索引鍵)	意義	限制要求 (值)	範例
"type"	將變數值限制為特定的資料類型。	"text" 指定文字類型。 "number" 指定數字類型。	`CONSTRAIN vExampleText = {"type": "text"}` `CONSTRAIN vExampleNumeric = {"type": "number"}`
"maxnum"	設定變數的最大值。	僅數字 (整數或浮點)。允許使用科學標記法。	`CONSTRAIN vExample = {"maxnum": 5000}`
"minnum"	設定變數的最小值。	僅數字 (整數或浮點)。允許使用科學標記法。	`CONSTRAIN vExample = {"minnum": 250}`
"valuesnum"	為變數定義可接受的數值清單。	方括號內以逗號分隔的數字清單。例如︰[1,2,3]	`CONSTRAIN vExample = {"valuesnum": [1,2,3]}`
"valuestext"	為變數定義可接受的文字值清單。	方括號內以逗號分隔的字串清單。例如︰["a","b","c"]	`CONSTRAIN vExample = {"valuestext": ["Department A", "Department B", "Department C"]}`

何時使用 Constrain 陳述式

使用 Constrain 陳述式可以防止不需要的變數值載入到分析應用程式中。以下區段概述了具體使用方式。

載入時間變數更新

Constrain 與載入時間變數更新合併使用時，特別實用。透過載入時間變數更新，您可以在應用程式載入期間使用 Reloads API 上的 variables 屬性動態更新變數。Constrain 陳述式可防止在分析載入中納入惡意或格式不正確的變數定義。

載入時間變數更新以及 Constrain 陳述式支援以下使用情況：

範本應用程式根據客戶 ID 或名稱等條件選擇性地載入資料 (可以在載入時間作為變數傳遞)
集中控制分佈在多個 Qlik Cloud 租用戶的應用程式
將變數導向的工作流程和任務從 QlikView 和 Qlik Sense 用戶端管理遷移到雲端

安全性、可靠性和共同作業

即使在載入時間變數更新情境之外使用，Constrain 也能增強載入指令碼撰寫的安全性控制——例如，在共同作業載入指令碼開發期間。例如，應用程式擁有者可以定義變數值的限制，告知共同作業者需要滿足的特定條件，才能可靠地成功載入應用程式。

考慮事項

變數的 Constrain 定義必須是有效的 JSON 物件。
您可以為單一變數指定多個限制。變數的所有限制都需要包含在單一限制物件內。如需範例，請參閱 範例 - 多個限制。
如果您已經將具有特定名稱的指令碼變數載入到應用程式中，則將來嘗試為該變數定義限制和值時，可能會因為原始變數和重新定義的變數之間發生衝突而失敗。

若要解決這些衝突，請插入空白定義，以重設變數限制和值。範例：
```
CONSTRAIN x;
LET x;
```
```
CONSTRAIN x;
SET x;
```
然後，您可以在載入指令碼的後續區段中重新定義變數及其限制。有關長格式範例，請參閱 範例 - 解決變數定義衝突。
變數定義和限制定義的順序並不重要。不過，如果與變數相關的載入失敗，則發生斷點的行將會有所不同。
Constrain 指令碼陳述式僅限制指令碼變數的變數定義。您也可以使用公用 API 對指令碼和最終使用者變數 (在工作表檢視中建立或更新的變數或使用 API 作為工作階段變數的變數) 套用限制。如需詳細資訊，請參閱定義變數限制的開發人員替代方案。
限制會經過驗證，以避免變數無法比對任何值的情境。無效限制的範例：
- {"minnum": 5000, "maxnum": 4}
- {"type": "text", "maxnum": 4}

定義變數限制的開發人員替代方案

您也可以使用公用 API 來定義變數限制，而不是使用載入指令碼中的 Constrain 陳述式。透過 API 定義限制時，所有更新變數值的嘗試 (無論是直接在載入指令碼中、在工作表檢視中或透過 Reloads API) 都會受到限制。

若要透過公用 API 定義變數限制，請使用 Qlik Sense Engine (qix) API 中的 GenericVariableConstraints 物件：GenericVariableConstraints。

範例 - type

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 a 的變數定義需要具有 number 類型。
定義變數 a 的 LET 的陳述式。

載入指令碼

CONSTRAIN a = {"type": "text"};
LET a = 1000;

結果

載入資料。

載入失敗，因為限制要求變數 a 為文字類型。變數定義是一個數字。

相較之下，在限制中指定 number 的 type 將導致載入成功。

範例 - maxnum

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 b 的變數定義的最大值為 3000。
定義變數 b 的 LET 的陳述式。

CONSTRAIN b = {"maxnum": "3000"};
LET b = 3001;

結果

載入資料。

載入失敗，因為限制要求變數 b 的最大值為 3000。變數定義評估為 3001。

相較之下，將 b 指定為 2999 將導致載入成功。

範例 - minnum

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 b 的變數定義的最小值為 3000。
定義變數 c 的 LET 的陳述式。

CONSTRAIN c = {"minnum": "3000"};
LET c = 2999;

結果

載入資料。

載入失敗，因為限制要求變數 c 的最小值為 3000。變數定義評估為 2999。

相較之下，將 c 指定為 3000 將導致載入成功。

範例 - valuesnum

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 d 的變數定義必須是數字，且必須是 2、3 或 4。
定義變數 d 的 LET 的陳述式。

CONSTRAIN d = {"valuesnum": [2,3,4]};
LET d = 1;

結果

載入資料。

載入失敗，因為變數 d 評估為 1，而這不在三個可能值的清單中。

相較之下，將 d 指定為 2 將導致載入成功。

範例 - valuestext

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 e 的變數定義必須是下列文字值之一：
- Department A
- Department B
- Department C
定義變數 e 的 SET 的陳述式。

CONSTRAIN e = {"valuestext": ["Department A", "Department B", "Department C"]};
SET e = Department D;

結果

載入資料。

載入失敗，因為變數 e 是 Department D，這不在限制定義的允許值清單中。

相較之下，將 e 指定為 Department C 將導致載入成功。

範例 - SET 與 LET

這些範例顯示了在變數定義期間使用 SET 或 LET 時套用限制的方式之差異。所有範例都使用套用 type 要求的限制，但這些原則通常適用於所有限制類型。

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 f 的變數定義需要具有 number 類型。
定義變數 f 的 SET 的陳述式。

載入指令碼

CONSTRAIN f = {"type": "number"};
SET f = 500*2;

結果

載入資料。

載入失敗，因為限制要求變數 f 為數字類型。變數定義包含數字運算式，但由於使用了 SET 陳述式，因此將定義評估為文字。

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 g 的變數定義需要具有 text 類型。
定義變數 g 的 LET 的陳述式。

載入指令碼

CONSTRAIN g = {"type": "text"};
LET g = 500*2;

載入資料。

載入失敗，因為限制要求變數 g 為文字類型。變數定義包含數字運算式，並使用了 LET 陳述式，導致將定義評估為數字。

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 h 的變數定義需要具有 text 類型。
定義變數 h 的 SET 的陳述式。

載入指令碼

CONSTRAIN h = {"type": "text"};
SET h = 500*2;

載入資料。

載入成功。限制要求變數 h 為文字類型。變數定義包含數字運算式，但由於使用了 SET 陳述式，因此將定義評估為文字。

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 i 的變數定義需要具有 number 類型。
定義變數 i 的 LET 的陳述式。

載入指令碼

CONSTRAIN i = {"type": "number"};
LET i = 500*2;

載入資料。

載入成功。限制要求變數 i 為數字類型。變數定義包含數字運算式，並使用了 LET 陳述式，導致將定義評估為數字。

範例 - 多個限制

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式用來指定 j 的變數定義需要介於 1 和 5 之間。
定義變數 j 的 LET 的陳述式。

載入指令碼

CONSTRAIN j = {"minnum": 1, "maxnum": 5};
LET j = 2;

載入資料。

載入成功。變數 f 評估為 2，在可接受的範圍內。

概述

開啟資料載入編輯器並將下面的載入指令碼新增至新的區段。

載入指令碼包含：

Constrain 陳述式允許變數為文字或數字，只要是可接受的值之一即可。
定義變數 k 的 LET 的陳述式。

載入指令碼

CONSTRAIN k = {"valuestext": ["abc","def","ghi"], "valuesnum": [0,1,3,5]};
LET k = 'def';

載入資料。

載入成功。變數 k 的值在可接受的值清單中找到。同樣地，將 k 指定為 3 會導致載入成功。

範例 - 解決變數定義衝突

概述

此範例顯示了在為應用程式中已從先前載入定義的變數新增限制時，如何發生變數定義衝突。

載入指令碼 1：設定指令碼變數

開啟資料載入編輯器。新增下列指令碼：

LET vConflictExample = 'Department C';

載入資料。載入成功。已在應用程式中建立變數 vConflictExample 作為指令碼變數。

載入指令碼 2：嘗試對先前載入的指令碼變數進行限制定義

刪除載入指令碼 1。新增以下指令碼：

CONSTRAIN vConflictExample = {"type": "number"};
LET vConflictExample = 123;

載入資料。

即使新的限制和值定義相容，載入也會因限制錯誤而失敗。這是因為載入指令碼 1 已經將變數載入到應用程式中，其中含有文字值，並且此值仍然保留在應用程式中。為了解決這個問題，我們需要重設變數限制和定義。請參閱載入指令碼 3。

載入指令碼 3：重設限制和值定義

刪除載入指令碼 2。新增以下指令碼：

CONSTRAIN vConflictExample;
LET vConflictExample;

CONSTRAIN vConflictExample = {"type": "number"};
LET vConflictExample = 123;

MockData:
LOAD 
* 
Inline [
id, date, amount
1, 05/30/2025, 23.56
];

載入資料。

載入成功。上面的指令碼可以分成三個部分，每個部分都以空白行分隔：

第一部分重設 vConflictExample 的限制和值定義。這會移除使用載入指令碼 1 載入到應用程式中的定義。
第二部分重新套用在載入指令碼 2 中失敗的新限制和值定義。
第三部分簡單地新增模擬資料，以便我們可以開啟工作表檢視並檢查變數值 (見下文)。

以編輯模式開啟工作表檢視，然後開啟變數對話方塊。我們可以看到成功建立了變數 vConflictExample。

工作表檢視中的變數對話方塊顯示已成功建立指令碼變數。 — 工作表檢視中的變數對話方塊顯示已解決 vConflictExample 的變數定義衝突。

瞭解更多資訊

此頁面是否對您有幫助？

若您發現此頁面或其內容有任何問題——錯字、遺漏步驟或技術錯誤——請告知我們！

在此留下意見回饋