1. 概述
1.1 版本
| 報表伺服器版本 | 功能變更 |
|---|---|
| 11.0 | - |
| 11.0.6 |
|
| 11.0.7 |
|
| 11.0.30 | 標籤名稱支援使用公式，詳情參見 2.1.2 節 |
1.2 應用場景
1.2.1 填報元件
填報報表中可以透過該元件選擇具有多層樹狀結構的資料，錄入填報的資料，如下圖所示：
注：下拉樹元件不支援提交入庫
1.2.2 參數元件
參數面板處可以透過該元件選擇具有多層樹狀結構的資料，鍵入查詢參數，如下圖所示：
1.3 新增方式
1.3.1 填報元件
被菜儲存格後，點選右側屬性面板的「元件設定」，「選擇元件」處下拉選擇「下拉樹」元件，如下圖所示：
1.3.2 參數元件
將參數面板元件工具欄中的「下拉樹」元件拖入到參數面板中，如下圖所示：
1.4 注意事項
1）檢視表樹與下拉樹的差別：
檢視表樹與下拉樹的定義方法是一樣的，差別在於瀏覽器端預覽時顯示的效果不同。如下圖所示：
2）下拉樹的三種建構方式對比如下：
| 極速分層建構 | 自動建構 | 普通分層建構 | |
|---|---|---|---|
| 需要的資料集個數 | 一個或多個 | 一個 | 多個 |
| 需要的資料集類型 | 普通資料集 | 樹資料集 | 普通資料集 |
| 需要的資料結構 | 有對應關系的多列欄位，必須設定依賴關系。 | 有對應關系的一欄或兩列欄位，樹關系完整，支援存在多個根節點。 注：11.0.6 之前根節點的上代節點必須為空。 | 有對應關系的多列欄位，sql中需要用treelayer函式進行過濾。 |
| 效能 | 標準情況下效能優於普通分層建構。 | 因資料結構特殊，所以和其他兩種建構方式無對比性。 | 大數據量或者層級過多時效能一般 |
| 其他 | 無法自動過濾空節點 | 無法自動過濾空節點 | 支援不顯示空節點 |
| 範例文檔 | 下拉樹元件極速分層建構範例 | 下拉樹元件自動建構範例 | 下拉樹元件普通分層建構範例 |
2. 元件介紹
2.1 屬性
2.1.1 填報元件
「下拉樹」元件的屬性設定介面如下圖所示：
各屬性設定項的詳細介紹如下：
注：「下拉樹」元件在填報應用時，可透過在儲存格中新增值的方式設定預設值，如何設定可參考：下拉樹預設值設定
| 分類 | 設定項 | 詳細介紹 |
|---|---|---|
| 基本 | 元件名稱 | 元件的名稱，手動輸入，通常與參數結合使用，如透過元件名獲取元件後將元件值傳遞給對應參數，預設為無 |
| 可 用 | 元件是否可用，勾選後，填報時元件可編輯；不勾選，填報時元件灰化，不可編輯，預設勾選 | |
| 可 見 | 元件是否可見，勾選後，填報時頁面顯示元件；不勾選，填報時頁面不顯示元件，預設勾選 | |
| 資料字典 | 可以定義下拉樹實際值與顯示值，有 3 種建構方式，自動建構、普通分層建構、極速分層建構 1）自動建構：根據樹資料集層級關系自動建構出下拉樹，無需一層一層定義資料。詳細範例可參考：下拉樹自動建構2）普通分層建構：透過 資料字典 一層一層定義下拉樹，需要資料集中定義一些 layer 參數配合完成，將上一層的值作為參數值，過濾下一層的資料。詳細範例可參考：下拉樹普通分層建構
3）極速分層建構：透過「資料集 」來定義下拉樹的層級，相比「普通分層建構」，不需要 layer 參數配合，而是將資料按分類排列，每一層綁定資料列即可。詳細範例可參考：下拉樹極速分層建構 | |
| 進階 | 水 印 | 填報時元件內顯示的淺灰色水印文字，手動輸入，以提示使用者需要輸入資訊，點選元件編輯區域後消失，預設為空 |
| 多 選 | 勾選後，填報時可選擇下拉樹的多個選項；不勾選，填報時只可一個選項。預設不勾選
| |
非同步展開樹節點 | 節點載入邏輯，會影響效能，預設勾選。
不勾選，展開選項時所有子節點一次性展開，適用於資料量小的情況。當元件有預設值時，所有子節點一次性展開並選中預設值節點。
| |
| 只傳回葉子節點 | 多選時，選擇上代節點後，是否會自動選擇子節點。預設勾選 勾選後，勾選上代節點時自動勾選子節點
不勾選，當勾選上代節點時不自動勾選子節點
| |
| 結果傳回完整層次路徑 | 下拉樹是一種有層次結構的元件，每個最末端的葉子節點都有其完整的層次路徑。「結果傳回完整路徑」即選擇值後，要不要傳回其完整的層次路徑，傳回值為陣列型別的資料
不勾選後，只傳回葉子節點，如上選擇北京，傳回值為：部長 | |
| 傳回值型別 | 勾選「多選」和不勾選「結果傳回完整層次路徑」後才有此設定項。用來設定多選下拉樹傳回值的格式，分為陣列和字串兩種。 勾選「結果傳回完整層次路徑」後，傳回值型別已確定，所以對應情況下不會有此設定項。
1）陣列：傳回值型別是陣列型，例如：勾選三個值，傳回值為：["值 1","值 2","值 3"] 2）字串：傳回值型別為字串，需要定義分隔符、開始符和結束符，即將勾選的多個值根據分隔符連接成一個字串。例如：在輸入法為英文的狀態下，將分隔符，開始符和結束符分別定義成逗號，單引號和單引號，則傳回值為：'值 1,值 2,值 3'
| |
| 校驗 | 允許爲空 | 是否允許元件不選擇項： 勾選後，允許元件不選擇 不勾選，填報校驗和提交時會提示，預設勾選 注：如不勾選，行動端使用時元件將不會出現「清空」選項 |
| 錯誤提示 | 不勾選「允許為空」時出現的設定項，可自訂提示資訊。預設情況下將顯示：不能為空 | |
| 允許直接編輯 | 是否允許使用者直接輸入值，勾選後，使用者可以直接輸入值，實現模糊搜尋，預設勾選 注：此功能不支援行動端 | |
| 允許自訂值 | 是否允許使用者輸入不包含在下拉樹選項中的值
|
2.1.2 參數元件
「下拉樹」元件的屬性設定介面如下圖所示：
各屬性設定項的詳細介紹如下：
| 分類 | 設定項 | 詳細介紹 | ||
|---|---|---|---|---|
| 基本 | 元件名稱 | 元件的名稱，手動輸入，通常與參數結合使用，如透過元件名獲取元件後將元件值傳遞給對應參數，預設為 treeComboBoxEditor# | ||
| 可 用 | 元件是否可用，勾選後，填報時元件可編輯；不勾選，填報時元件灰化，不可編輯，預設勾選 | |||
| 可 見 | 元件是否可見，勾選後，填報時頁面顯示元件；不勾選，填報時頁面不顯示元件，預設勾選 | |||
| 進階 | 標簽名稱 | 元件的標簽屬性是用在行動端的，行動端不支援參數面板上的「標簽元件」，識別的是普通元件的「標簽名稱」屬性，所以行動端可以用元件的標簽章稱來實現標簽。 FineReport 11.0.30 及以上版本，標籤名稱支援使用公式。編輯框內輸入公式正文（等號開頭），自動計算公式結果作為最終標籤名稱 。 注：使用 i18n 函式實現標籤名稱根據語言顯示時，多語言插件需更新至 V2.2.2 版本。若範本中使用的 key (範本內或平台內的 key )更新，需手動重新整理範本才可生效 。 | ||
| 控 件 值 | 元件初始化時的預設值，可以為資料字典時綁定的實際值，也可以為顯示值。支援字串、欄位、公式，預設為空 注：11.0.7 之前版本下拉樹預設值必須寫節點實際值的完整路徑，11.0.7 及以後版本，新增 TREEDEFAULTPATH 函式，不用填寫完整路徑即可設定預設值。 1）字串：字元文字，例如：要選中北京，寫華北,北京,北京
多個值時，字上代節點之間用,隔開，多個值之間用 ;隔開，例如選中北京和上海，寫華北.北京,北京;華東,上海,上海
注：多選下拉樹不支援使用欄位來實現全選功能，如有此需求可參考 下拉樹元件預設全選 實現。
若欄位值符合多個值寫法，則會多選 3）公式：設計器支援的公式，例如： A1 儲存格的值，或者 =[[1,11,111],[1,11,112]]
若公式對應的值符合多個值寫法，則會多選 | |||
| 資料字典 | 可以定義下拉樹實際值與顯示值，有 3 種構建方式，自動構建、普通分層構建、極速分層構建 1）自動建構：根據樹數據集層級關系自動構建出下拉樹，無需一層一層定義數據。詳細示例可參考：下拉樹自動建構 2）普通分層建構：通過 資料字典 一層一層定義下拉樹，需要數據集中定義一些 layer 參數配合完成，将上一層的值作爲參數值，過濾下一層的數據。詳細示例可參考：下拉樹普通分層構建
勾選後，當有層目錄下沒有子節點，顯示的時候仍會是“+”，點開無數據項，如下圖所示： 3）極速分層建構：通過「數據集 」來定義下拉樹的層級，相比「普通分層建構」，不需要 layer 參數配合，而是将數據按分類排列，每一層綁定數據列即可。詳細示例可參考：下拉樹極速分層建構 | |||
| 水 印 | 填報時元件內顯示的淺灰色水印文字，手動輸入，以提示使用者需要輸入資訊，點選元件編輯區域後消失，預設為空 | |||
| 字體大小 | 被選中的，顯示在元件框中選項的字體大小，預設為 12 。 注1：下拉選項中的文字大小不隨此處的字體大小變化。 注2：此功能不支援行動端。 | |||
| 多選 | 勾選後，填報時可選擇下拉樹的多個選項；不勾選，填報時只可選擇下拉樹的一個選項。預設不勾選
| |||
| 非同步展開樹節點 注：11.0.6 之前名稱為非同步載入 | 節點載入邏輯，會影響效能，預設勾選。 勾選後，展開選項時只載入上代節點的資料，所有子節點預設不展開，適用於資料量大的情況。當元件有預設值時，預設值節點展開並選中，其他節點不展開。
不勾選，展開選項時所有子節點一次性展開，適用於資料量小的情況。當元件有預設值時，所有子節點一次性展開並選中預設值節點。
| |||
| 結果傳回葉子節點 | 多選時，選擇上代節點後，是否會自動選擇子節點。預設勾選 勾選後，勾選上代節點時自動勾選子節點；
不勾選，當勾選上代節點時不自動勾選子節點
| |||
| 結果傳回完整層次路徑 | 下拉樹是一種有層次結構的元件，每個最末端的葉子節點都有其完整的層次路徑。結果傳回完整路徑即選擇值後，要不要傳回其完整的層次路徑，傳回值為陣列型別的資料 勾選後，傳回完整路徑，如選擇北京，傳回值為：總部，人力資源部，部長
| |||
| 傳回值型別 注：此項為11.0.7 新增 | 勾選「多選」和不勾選「結果傳回完整層次路徑」後才有此設定項。用來設定多選下拉樹傳回值的格式，分為陣列和字串兩種。 勾選「結果傳回完整層次路徑」後，傳回值型別已確定，所以對應情況下不會有此設定項。
2）字串：傳回值型別為字串，需要定義分隔符、開始符和結束符，即將勾選的多個值根據分隔符連接成一個字串。例如：在輸入法為英文的狀態下，將分隔符，開始符和結束符分別定義成逗號，單引號和單引號，則傳回值為：'值 1,值 2,值 3'
| |||
| 校驗 | 允許爲空 | 是否允許元件不選擇項，勾選後，允許元件不選擇；不勾選，填報校驗和提交時會提示，預設勾選 | ||
| 錯誤提示 | 不勾選「允許為空」時出現的設定項，可自訂提示資訊。預設情況下將顯示：不能為空 | |||
| 允許直接編輯 | 是否允許使用者直接輸入值，勾選後，使用者可以直接輸入值，實現模糊搜尋，預設勾選 注：此功能不支援行動端。 | |||
| 允許自訂值 | 是否允許使用者輸入不包含在下拉樹選項中的值
| |||
| 座標.尺寸 | 元件位置 | 元件在參數面板中的位置，透過橫縱座標調整，座標會根據元件在參數面板中的位置自動顯示 | ||
| 元件大小 | 元件的大小，透過寬度、高度調整，若透過拖曳調整，高寬度也隨着自動調整 | |||
2.2 事件
事件設定介面可以為元件新增事件實現某些效果，「下拉樹」元件支援的事件有初始化後、編輯前、編輯後、編輯結束、點選、節點生成。如下圖所示：
選擇一種事件型別後，即可新增事件內容，「下拉樹」元件支援的事件響應方式有 JavaScript 腳本、提交入庫、傳送郵件。如下圖所示：
選擇對應的事件響應方式新增即可，不同響應方式差別可參考：事件響應方式
2.3 行動端
行動端無可配置項。
2.4 模糊搜尋
在元件「屬性」設定中，勾選了「允許直接編輯」，下拉樹選擇值時，使用者可以直接輸入值，實現模糊搜尋。如下圖所示：
「下拉樹」元件的模糊搜尋邏輯可參考：下拉框/下拉複選框/下拉樹的模糊搜尋
3. 應用範例
下拉樹元件的應用，可參見以下文檔：
| 應用場景 | 實際效果 |
|---|---|
場景描述： 下拉樹中分別有 地區，省份，城市 指標，可以實現同時選擇查詢出多個城市的資料參考文檔： 多選下拉樹實現多值查詢 | |
| 場景描述： 資料庫中有 3 個級別的資料，分別是地區，城市，以及客戶名稱，可以同下拉樹元件實現同時選擇查詢出華東地區下所有公司以及北京的某個公司的資料 參考文檔： 多選下拉樹實現不同級別之間的查詢 | |
| 場景描述： 下拉樹元件可以設定預設值 參考文檔： 下拉樹預設值設定 | |
| 場景描述： 下拉樹元件可以設定預設全選 參考文檔： 下拉樹元件預設全選 | |
