陣列

本説明頁面上的資訊同時適用於 CXone StudioDesktop Studio

陣列是一種儲存一組值的資料結構。當您擁有相似類型的項目清單時,陣列很有用。例如,區號、電話號碼或客戶姓名清單。

Studio 中可以使用兩種陣列:

  • 字串陣列:變數中以豎線分隔的字串。其儲存字串值,這些值可以由英數字元組成。
  • 動態陣列:儲存在動態資料物件中的陣列。

如果您有一個清單,其中的資料是關於單個實體的所有不同類型的資訊,動態資料物件是更適合使用的資料結構。有關陣列和物件的比較可在資料結構説明頁面上找到。

有關陣列的重要資訊

  • 陣列必須至少有兩個元素。只有一個元素的陣列類似一個常規變數。這仍然是一個陣列,可以作為陣列調用。動態陣列也是如此。
  • Studio 中,陣列索引從 1 開始。

  • 有些 函數 可用於陣列,如 index()indexof()

  • 您可以在字串陣列中使用任何分隔符號。不過,要進行本地讀取,字串陣列必須使用豎線字元作為分隔符號。

嘗試一下

下載 陣列範例指令碼並將其匯入Studio中。本說明頁面中的許多範例可在範例指令碼中的 Snippet 動作中找到。您可以開啟 Snippet 編輯器視窗並運行偵錯程式來查看範例。

陣列文法摘要

使用以下文法之一建立字串陣列。

使用其索引為每個元素賦值:

ASSIGN <var>[<index1>] = "<value1>"

ASSIGN <var>[<index2>] = "<value2>"

ASSIGN <var>[<index3>] = "<value3>"

將所有元素值指派給以豎線分隔的字串中的變數:

ASSIGN <var> = "<value1> | <value2> | <value3>"

使用以下文法建立動態陣列:

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

支援動態陣列的其他形式

要引用字串陣列中的特定元素,請使用此文法:

<var>[index]

要引用動態陣列中的特定元素,請使用此文法:

ASSIGN <var> = <object>.<member>[<index>].<arrayElement>

元素和索引

陣列保留的值稱為元素。指令碼會記錄陣列中元素的順序。陣列中的每個元素都有一個數字識別碼,稱為索引號。索引是根據每個元素在陣列中的位置自動指派。如果重新排列、新增或刪除元素,其索引可能會變更。

Studio 中,陣列索引從 1 開始。索引必須是正整數。需要知道索引才能與陣列中的特定元素交互。如果不知道元素的索引,可以使用 indexof() 函數 來確定。

參見字串陣列的單個元素

在引用字串陣列中的單個元素時,請使用此文法:<arrayElement>[<index>].您可以在等號的兩側使用此文法。例如,您可以用其為元素賦值或引用元素的值,如 為另一個變數賦值時

例如:

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

在這個範例中,Beowulf 的索引是 1,Sir Gawain 的索引是 2,Byrtnoth 的索引是 3。以豎線分隔陣列時,這些元素的索引相同:name = "Beowulf|Sir Gawain|Byrhtnoth"。要確定這種格式陣列的索引,從 1 開始,從左到右數元素。

索引是按數字順序填充

索引是按數字順序逐個填充。如果您引用了陣列中目前不存在的索引,指令碼將建立該索引,除非您為其賦值,否則該索引將為空。如果在陣列中引用的元素和前一元素之間不存在索引,指令碼會建立索引。指令碼新增來填充索引的元素為空。例如:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth" 
ASSIGN heroes[6] = "Lancelot"

結果陣列為 heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot"。指令碼為索引 4 和 5 新增了元素,但由於沒有賦值,所以這些元素是空的。

同樣,如果嘗試從一個不存在的元素中提取值,則會建立該元素。您試圖引用的元素和上一個元素之間的所有元素也會被建立,並且都是空的。

如果在期望使用數字的上下文中引用了空陣列元素,指令碼會將該值視為零。

確定下一個未使用的索引

為了避免在陣列中建立不必要的空元素,可以確定下一個未使用的索引。您必須數出陣列中的元素,然後在這個數字上加 1。這樣就得到了下一個開啟的索引號。

要做到這一點,請使用 size() 函數。例如:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"  
ASSIGN nextIndex = heroes.size() + 1
ASSIGN heroes[nextIndex] = Roland

在本例中,heroes.size() 返回名稱陣列中元素的個數。totalNames 的值是 3。在陣列中新增一個元素,並用 nextIndex 變數代替索引號,就可以在陣列中新增一個元素。

您還可以使用 count() 功能。

字串陣列

字串陣列有兩種定義方式。第一種是為每個元素單獨明確命名。下面的範例顯示了一個字串陣列,其中包含逐個元素定義的文字值。

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

陣列名稱之後方括號中的數字是元素的索引號。這是每個元素的識別碼。

定義字串陣列的第二種方法是使用豎線分隔字串,在每個元素之間使用一個豎線字元 (|)。該範例顯示了第一個範例中以豎線分隔字串定義的陣列。建立豎線分隔字串陣列時,語句右側的值必須用雙引號括起來。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

這兩個函數之間沒有區別,可以替換使用。定義字串陣列的兩種方法都會產生相同的結果,即一個包含陣列元素的變數。

在聲明字串陣列時,不要求使用ASSIGN關鍵字。但是,用其會有幫助。包括ASSIGN使您在指令碼中引入陣列的地方易於使用高級搜尋定位。沒有ASSIGN,您必須搜尋陣列的名稱。搜尋結果將包含對指令碼中陣列的每一個參考。如果在搜尋術語中包含 ASSIGN,搜尋將只返回明確指派變數的結果。要聲明不含 ASSIGN 的變數,請使用以下文法:<name> = "<value>"

動態陣列

動態陣列有以下幾種形式:

  • 動態資料物件包含一個陣列。每個陣列元素也是一個物件成員。

    DYNAMIC beowulfLocations 
    ASSIGN beowulfLocations[1] = "Land of the Geats"
    ASSIGN beowulfLocations[2] = "Heorot" 
    ASSIGN beowulfLocations[3] = "Earnanæs"
  • 動態物件包含一個儲存陣列的成員。物件的其他成員可能儲存字串或數值,也可能是其他陣列。

    DYNAMIC beowulfCharacteristics 
    ASSIGN beowulfCharacteristics.foe[1].characteristics[1] = "Grendel"
    ASSIGN beowulfCharacteristics.foe[1].characteristics[2] = "son of Cain"
    ASSIGN beowulfCharacteristics.foe[2] = $"Grendel\'s mother" 
    ASSIGN beowulfCharacteristics.foe[3] = "Dragon"
  • 字串陣列中的每個元素都包含一個動態資料物件。

    DYNAMIC epicPoems
    ASSIGN epicPoems.poemName = "Beowulf"
    DYNAMIC heroes 
    ASSIGN heroes.heroName = "Beowulf"
    DYNAMIC monsters
    ASSIGN monsters.monsterName = "Grendel"
    ASSIGN oldEnglish[1] = epicPoems
    ASSIGN oldEnglish[2] = heroes
    ASSIGN oldEnglish[3] = monsters

    運行偵錯程式時,您可以在 Snippet 編輯器視窗內的「變數為樹」標籤上查看動態物件和字串陣列的內容

    當您需要您的指令碼用於其他系統時,例如連接到 API 時,不能使用這種類型的動態陣列。字串陣列儲存的資料無法序列化或轉換為 JSON 或 XML 字串。

依據位置引用陣列元素

您可以使用陣列中元素的位置(由其索引指定)來引用字串或動態陣列中的元素。例如:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN currentName = heroes[2]

currentName 的值是 Sir Gawain

ASSIGN 語句中,您可以使用變數來代替等號兩側的索引號。這樣就可以引用特定索引,而無需在指令碼中硬編碼索引。例如:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN location = 2
ASSIGN currentHero = heroes[location]
ASSIGN nextIndex = heroes.count() + 1
ASSIGN heroes[nextIndex] = "Roland"

本例中 currentHero 的值為 Sir Gawain。上例的最後兩行顯示了使用變數作為 ASSIGN 語句左側的索引。其還顯示了使用 count() 函數返回陣列中元素的個數。該資訊用於在下一個空索引中新增新元素。

使用變數表示索引號時,不需要在變數名前後使用大括號。指令碼需要在陣列名稱的方括號之間輸入數值。其假定任何非數字都是變數,因此會尋找具有該名稱的變數。必須有相應的變數聲明,在聲明中賦值。如果沒有,則會出現以下錯誤:

_ERR=In Snippet line 12: Array index must be >= 1.

如果連接了 Snippet 動作的 Error 分支,指令碼會在出現此錯誤時使用此分支。

對字串陣列使用 FOREACH

您可以對字串陣列使用 FOREACH 語句 遍歷每個元素。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
 FOREACH elem IN heroes 
{
   ASSIGN aName = elem 
}

在本例中,elemaName 在每次反覆運算時都會更新。elem 變數儲存了 FOREACH 迴圈正在處理的目前元素。指令碼用 elem 的內容更新 aName。在每次反覆運算結束時,elemaName 保留相同的值,但在反覆運算中間,elem 保留新值,aName 保留舊值(或者在第一次反覆運算開始時沒有值)。

您可以在陣列範例指令碼中的 FOREACH Loop with a String Array snippet 中清楚地看到這一點。要查看變數的更新方式,請逐行查看 snippet。

對字串陣列使用 FOR

您可以對字串陣列使用 FOR 迴圈,遍歷陣列並按設定次數執行定義的動作。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
FOR i = 1 TO heroes.count 
   {    
      item = "{heroes[i]}" 
   } 
        

本例的結果是,ItemFOR 迴圈的每次反覆運算中都會更新 heroes 陣列中由 i 值指定的索引位置的內容。如 heroes.count 所示,FOR 迴圈在到達字串陣列的末尾後停止遍歷。

您可以在陣列範例指令碼中的 FOR Loop with a String Array snippet 中看到此迴圈。

在陣列中使用函數

您可以在陣列中使用 函數。使用陣列名稱和方括號中的索引,然後使用點符號新增函數名稱。如下範例所示:


ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN miniHero = "{heroes[2].lower}"
ASSIGN yellyHero = "{heroes[2].upper}"

此範例的結果為 miniHero = sir gawainyellyHero = SIR GAWAIN

並非所有函數都適用於所有陣列。某些函數僅適用於某些類型的值。使用函數時,請驗證要使用函數的值類型。

可以在動態陣列中使用函數。不過,根據具體的動態陣列及其包含的內容,您可能需要 使用特殊的物件屬性。$value。某些函數不適用於整個物件。例如,無法在物件陣列上使用 lower() 函數。如果您嘗試這樣做,指令碼將忽略該函數。在這些情況下,您必須採用變通方法。例如,可以將陣列中物件的特定值複製到一個單獨的變數中。然後,您可以對變數的內容使用 lower(),如果需要,還可以將轉換後的值複製回物件中。

下表中的函數專門用於陣列。您可以在 陣列範例指令碼Functions and Arrays snippet 中測試這些函數。

功能

描述

count()

返回陣列或物件中的元素個數。

index(indexValue)

根據指定的 indexValue 從變數內容中返回陣列元素。

indexof(text)

返回變數內容中指定 text 字元的位置。

size()

返回陣列中的元素數目。

split(delimiter)

將變數的內容轉換為適合作為陣列處理的豎線分隔字串。用豎線字元替換現有的指定delimiter