ArOZ Online 檔案選擇器
Toby
Toby

說到要在 WebApp 上讓使用者選擇檔案你會怎樣設計?
不少開發者都直接在 WebApp 裡面創建一個可以點選的列表就算數,能用但是不完美;所以在 ArOZ Online Base 系統架構裡面,我們在設計 File System 的時候就設計了一個可以輕易讓開發者使用的 檔案選擇器 ( File Selector ) 了。

ArOZ Online 系統下的 File Selector

所以,為啥我要用 FIle Selector?我自己幹一個就好了啊?

對,你也可以自己幹一個檔案選擇器,可是系統內建的 File Selector 有幾點用起來真的滿方便的。

預設支援 UM-FILENAME 及 HEX-FOLDERNAME

由於內建的檔案選擇器內建了 UM-Filename 跟 Hex-Foldername 的轉換程式,所以寫起來不必要特別自行處理這些特別的檔案命名方式。

Hex-foldername 顯示方法
UM-Filename 顯示方法

支援新增文件或資料夾

如果你需要新增一個文件或資料夾的時候,你可能要在 WebApp 裡面多加一個 <form> 元素,之後又需要增加一個處理的 php 甚麼的不是很麻煩嗎?
用系統內置的 File Selector 就能直接省略這些問題,使用 Javascript callback 來取得使用者新建的文件名或資料夾名稱及位置。

新建文件的 File Selector 界面

使用方法

一般來說我們會建議使用者使用 Float Window 模式啟用 File Selector。然而,在一般網頁模式下啟動 File Selector 也是可以的,只不過使用體驗上會感覺到有點奇怪。首先,我們先從由 Float Window Mode 啟動 File Selector 的教學開始:

在 Float Window 模式下啟動檔案選擇器

先假設我們有這麼一個 function 來接收使用者選擇的檔案

  function addFileFromSelector(fileData){
   result = JSON.parse(fileData);
    for (var i=0; i < result.length; i++){
     var filename = result[i].filename;
     var filepath = result[i].filepath;
     //DO SOMETHING HERE
    }
   }

以下是功能的啟動參數

ao_module_openFileSelector(uid,callBackFunctionName, windowWidth = 1080, windowHeight = 645, allowMultiple = false, selectMode = "file", newfname = "newfile.txt", umf = true)

allowMultiple : 充許選擇多個檔案
selectMode : (file / folder / mix / new),其意思為:只選擇檔案 / 只選擇資料夾 / 可選擇資料夾或檔案 / 新增文件或資料夾
newfname : 新增檔案的預設名字(只在 selectMode = new 時有效)
umf : 使用 UM-Filename 編碼檔案名字(只在 selectMode = new 時有效)

//最基本的例子
var uid = ao_module_utils.getRandomUID();
ao_module_openFileSelector(uid,"addFileFromSelector",undefined,undefined,true);
//自定義選擇器大小
var uid = ao_module_utils.getRandomUID();
ao_module_openFileSelector(uid,"addFileFromSelector",720,480,true);

你也可以透過 File Selector 為建立新的檔案名命,例子如下:

var uid = ao_module_utils.getRandomUID();
ao_module_openFileSelector(uid,"addFileFromSelector",undefined,undefined,true,"new","dummy.txt",false);

!! 不過值得注意的是這並不會真的新增一個檔案在伺服器端,這只是為你之後的程式提供一個儲存檔案的名字及路徑而已。

而在非 Float Window 模式下,啟動的 function 由 ao_module_openFileSelector 改變成了 ao_module_openFileSelectorTab,啟動參數也有不同,但是大致上使用方法都是一樣的。

ao_module_openFileSelectorTab(uid, aor,allowMultiple = false, selectMode = "file",callBack=console.log, newfname = "newfile.txt", umf = true)

而這裡的 aor 即是 ArOZ Online Root,如果你的程式碼是位於 AOB/MyModule/index.php,那 AOR 就是 AOB/ 的位置即是 “../”。
同時開發者亦應該注意這功能只能在有支援 localStorage 的瀏覽器內使用。

Callback Function 注意事項

有一點需要特別注意,就是 ao_module_openFileSelectorTab 跟ao_module_openFileSelector 在 callback function name 的一項是有一點不同的。在 ao_module_openFileSelector 時,你需要傳入的是function 名稱的 String,例子如下:

//ao_module_openFileSelector 的 callback 傳入方式:
function addFileFromSelector(fileData){
    console.log(fileData);
}
ao_module_openFileSelector(uid,"addFileFromSelector",undefined,undefined,true); //傳入 String 而非 function object 本身

而在 ao_module_openFileSelectorTab 時則是這樣:

//ao_module_openFileSelectorTab 的 callback 傳入方式
function addFileFromSelector(fileData){
    console.log(fileData);
}
ao_module_openFileSelectorTab(uid,"../",true,"file",addFileFromSelector); //傳入 function object 本身而非 String

唯獨這一點敬請要注意喔!

備注:更改選擇器側欄的捷徑

這個 ArOZ Online 系統內置的 File Selector 位於 SystemAOB/functions/file_system 內,跟 檔案管理員 (file_explorer) 使用同一套的捷徑設定。所以如果你要更改 File Selector 的捷徑設定你可以到 系統設定 > 檔案與儲存 > 檔案管理員捷徑 中更改。

File Selector 的捷徑設定