Module 開發 – illuTrans

圖片上傳一直都是筆者感興趣的 module, 從早期單一檔案到借助 Flash 來達成複檔上傳, 甚至是現在的 HTML5 原生 support, 它可以說是一段活生生的 Web 進化史.

由 HTML5 和 CSS3 的交錯渲染下, Image upload 也變的更加活潑有趣, 連帶的也大大的增進了使用者體驗, 選取待上傳檔案的方式更是一大進化, User 除了點擊 input button 的選項之外, 更可以直接從檔案總管 drag / drop 檔案進來, 亦或 drag 其他視窗的網頁內容進來都不是問題.

筆者經手的幾個服務中都有 image upload 的需求, 為了能可以快速 plug 這樣的 feature 到不同的 property 上, 便開發了 illuTrans 這個 module, illuTrans 是由 illusion 和 transition 這兩個字作變形且結合, 除此之外, 更把幾個這些年來開發經驗去蕪存菁通通融入到這個 module 中, 除了基本的上傳功能外, 更是多了拖曳排序, 圖片預覽等功能, 亦抽出一些常用的 method / property 出來, 讓 developer 可以做更多元的變化與監控, 可以說集力與美於一身的強力 module, 接下來藉由以下的篇幅, 讓筆者為你慢慢揭開 illuTrans 一切一切.

歡迎點擊下方連結進行一覽 (demo page 的 web service 不會做任何圖片的處理, 更不儲存 user 所上傳的任何圖片, 所回傳也僅僅是預設的 dummy data)

illuTrans 的各項特色解析

  • 支援多種選取圖片的方法, 除了既有的 input button 之外, 本 module 更支援了 DD (Drag & Drop) 操作, 待檔案選取完成便會自動進行圖片上傳, 不需要額外攏贅的動作, 讓整體操作體驗一氣呵成

直接點擊圖中的 “+” 符號, 便可以進行圖片的選取, 支援複選

亦可直接將圖片拖曳進 illuTrans 區塊, 系統會清楚的標示 drop 的的區塊範圍

直接拖曳圖片進來

除此之外, 也可以直接拖曳 web page 的圖片進來喔!

也可以直接拖曳 web page 的圖片進來進行上傳

  • 具備 client side 繪製 thumbnail 功能, 讓 user 可以清楚的知道當前上傳圖片的內容以及上傳進度

當圖片進行上傳的當下, 選取檔案的 “+” 將會隱藏, 待整個 upload 過程結束才會置入 available block

當過程中出現錯誤時, user 可以清楚的知道哪些圖片上傳失敗, 只要點擊失敗的圖片縮圖或者靜置待系統 timeout, 便會將發生錯誤的區塊進行移除讓 user 可以繼續作上傳的動作

傳輸過程出現錯誤

  • 支援拖曳排序功能, 直接對已上傳的圖片區塊進行 Drag & Drop, 即可調整其排序(由左至右, 由上至下), sorting 過程中, 上傳以及選取檔案的動作將被 block

拖曳圖片進行排序

  • 支援 preview 以及刪除功能, 已經成功上傳的圖片, 可以透過點擊圖片區塊的 “放大鏡” 以及 “刪除” 圖示, 來使用這些功能, 如果對系統的 preview 功能不甚滿意, 亦可透過 config 來將該功能進行 disabled 的動作

預覽效果

  • illuTrans 為 web componets based, 在使用超獨然, 只要在頁面上置入相關的 HTML tag – <illu-trans>, 以及 require 相關的 javascript file, 便可以自動 init 並且不受當前 js framework 所致約或造成不同 framework 所帶來的衝擊和意外
  • illuTrans 支援 CROS, 我們可以把圖片處理的 web service 放在不同網域, 透過 config 的設置來決定傳輸過程中是否攜帶隱密的資料
  • Developer friendly, illuTrans 提供了很多的 method 以及 property 供 developer 使用, 讓 developer 可以更加靈活的應用, 且支援 addCallback / removeCallback, 透過回呼函式的導入, 我們可以在不同階段 (pick, upload, view, delete … etc) 接收到 user 的使用狀態, 讓不同 module 可以更緊密的作結合
  • end to end test ready, 透過ㄧ些狀態以及入口的揭露, 讓 end to end test 可以有效的測出上傳過程是否順暢
  • 內建 i13n tracking 機制, 只要搭配 gaExt.js, 便可以自動完成 mouleView 以及 click 的 tracking, 不需要做任何額外的設置, 輕輕鬆鬆完成成效追蹤
  • illuTrans 為 responsive design, 會隨著 container 的寬度自動作調整, 不需要做任何的處理, 更不用擔心破版的情況發生

如何套用 <illu-trans> 到 web page 中 ?

illuTrans 是一個獨立的 web component, 所有的行為和樣式都完整的封裝起來, developer 只要將特定的 HTML tag – <illu-trans> 放入頁面上任何想要擺放的位置即可, 不需要額外作任何 JavaScript init 的動作

HTML:

<illu-trans data-conf='JSON String'>    <h3>illuTrans</h3>
</illu-trans>

另外, JavaScript 也要將之 require 進來

<script async src="pack-illu-trans.js"></script>  

由於 illuTrans designed by native JavaScript, 所以不管當前 website 是使用什麼樣的 framework, 皆可以正常運作, 不會受到任何影響

illuTrans 初始化資料的餵入可以透過 attribute: data-conf 來取得, 如上例所示, 我們可以將資料以 JSON String 的方式置入該 attribute, 透過 config 的設置, 讓 developer 有更多元應用以及控制權, 接下來我們來看看 data-conf 的內容吧! (以下將以 PHP 來設定相關的內容)

PHP:

$data = array(    'max' => 9,    'legal' => array('png', 'jpeg', 'jpg', 'gif'),    'limitSize' => 31457280,    'col' => 5,    'inputName' => 'illusion',    'stripWidth' => 200,    'stripAmount' => 10,    'uri' => 'illuTransFunc.php',    'withCredentials' => true,    'useLightbox' => true,    'coolTime' => 10000,    'params' => array(        'id' => 'mei',        'type' => 'item-preview'    ),    'placeholder' => array(        array(            'icon' => 'img/illuTrans/shiseido_jojo_1_150.jpg',            'preview' => 'img/illuTrans/shiseido_jojo_1.jpg'        ),        ...        ...        ...        array(            'icon' => 'img/illuTrans/shiseido_jojo_1_150.jpg',            'preview' => 'img/illuTrans/shiseido_jojo_1.jpg'        )    ));

各欄位相對應的關係如下:

  • max: 設定上傳檔案量的上限 (default: 5), illuTrans 會依照該數值來產生相關的 UI
  • legal: 設定上傳檔案格式 (default: png, jpeg 和 gif), 當 user 選取的檔案不符合這些格式時, 則不做任何處理
  • limitSize: 設定單一檔案大小 (default: 10485760, 1024x1024x10), 當 user 選取的檔案大小超過該限制時, 則不做任何處理
  • col: 設置每一列想要呈現的個數 (default: 5)
  • inputName: 設置 input 的 name (default: FieldData), 提供前後端界接的自由度, illuTrans 會 web service 所回送的 data 以 array 的方式將之串接起來, 方便作 form 表單傳遞, 如下圖所示
  • stripWidth: 設置 client side 縮圖製作的寬高解析度 (default: 150), 其單位為 px, 開放這各設定, 主要是希望 developer 可以依照自己的需求來做最適的調整, 避免因為 放大 / 縮小 所產生的模糊失真過大
  • stripAmount:設置上傳進度顯示的 image strip 數量 (default: 10), illuTrans 會依照該數值的設置等分 thumbnail, 並依照當前上傳進度, 透過 animation 降下相對應等份的 strips, 讓 user 可以透過該呈現清楚的知道當前上傳進度
  • uri: 設置 web service 的位址
  • withCredentials: 當設置 web service 於不同網域時, 可以透過這項設置, 來決定傳輸過程中是否要攜帶隱密資訊 (default: true)
  • useLightbox: 設置使用 illuTrans 的 lightbox 來當作 preview 呈現與否 (default: true), 如果有自己預設的呈現方式, 可以將該值設為 false, 並且搭配 addCallback 來增加回呼函式
  • coolTime: 設置錯誤訊息清除的時間 (default: 3000), 其單位為 ms, 當傳輸過程出現錯誤時, illuTrans 會有清楚的標示, 讓 user 可以知道哪些圖片有問題, 透過該時間的設置, 讓 developer 可以決定多久時間後要把錯誤狀態更正為正常狀態, 方能繼續作上傳圖片的動作
  • params: 為了能夠增加前後端銜接的協調性, 特別設置了這個變數, 讓 developer 可以決定是否有其它變數希望在傳輸過程中一併攜帶過去
  • placeholder: 如果希望 illuTrans default 便可以有預設的上傳資訊, 便可以透過 placeholder 來設置,適合編輯狀態來使用, 會依照 placeholder.lenght 來決定預設的數量, 需要特別注意的是 icon 和 preview 是必須的, 如果有缺均視為不合法資料且不做任何處理

以上便是 illuTrans 基本 conf 的設置與介紹, 接下來要跟大家分享 illuTrans 所支援的 method 和 property, 讓 developer 可以透過這些 method / property 激盪出更璀璨的火花

<illu-trans> 所支援的 method

  • set: 上述的這些 config 變數, 都可以透過 set 這個 method 作動態調整 (stripAmount 和 max 的屬於破壞性的設置, 當這兩變數有異動的話, 均會將當前已經上傳成功的 section 作一清除的動作)
var illTrans; illuTrans = document.querySelector('illu-trans');  illuTrans.set('max', 10);illuTrans.set('col', 4);illuTrans.set('withCredentials', true);
  • get: 透過這個 method 可以取得 illuTrans 當前的資料
var illTrans; illuTrans = document.querySelector('illu-trans');illuTrans.get('max');  illuTrans.get('activeAmount');illuTrans.get('stat);//'normal || upload] 
  • addCallback: 我們可以透過這個 method 來新增回呼函式, 擁有基本的防呆, 同樣的回呼函式只能被設置一次. illuTrans 會於 view, sorting, exceed, blockByUploading, blockByFull, empty, formatError, pick, upload, uploadFail, uploadSuccess, delete, drop 這些動作發生時, 呼叫所設置的 callback
function cb() {    console.log(arguments);} var illTrans; illuTrans = document.querySelector('illu-trans');illuTrans.addCallback(cb);
  • removeCallback: 移除所設置的回呼函式
function cb() {    console.log(arguments);} var illTrans; illuTrans = document.querySelector('illu-trans');illuTrans.addCallback(cb);.........illuTrans.removeCallback(cb);
  • refresh: 如果因為部分外力造成 container 的外觀有變化, 因而造成 illuTrans 部分功能產生不正常行為時, 可以呼叫這個 method 來做一重新取樣的動作
var illTrans; illuTrans = document.querySelector('illu-trans');illuTrans.refresh();
  • removeFails: 雖然說當傳輸過程出現錯誤時, illuTrans 會根據 coolTime 來設置 timeout 並且自動清除錯誤的 section, 特別抽出這個 method 來讓 developer 決定是否要立即清除錯誤 section
var illTrans; illuTrans = document.querySelector('illu-trans');illuTrans.removeFails();

<illu-trans> 所支援的 method & property

  • value: developer 可以透過直接存取這個 property 來取得當前上傳的的資訊或者重新設置 placeholder
var illTrans, data; illuTrans = document.querySelector('illu-trans');
console.log(illuTrans.value);
illuTrans.value = []; //reset all exist data
data = [ [ icon: ' img/illuTrans/shiseido_jojo_1_150.jpg ', preview: ' img/illuTrans/shiseido_jojo_1.jpg ' ] ];
illuTrans.value = data;
  • disabled: 可以透過這個 property 的設置來決定 illuTrans active 與否, 一旦設置成 true, 則 illuTrans 將處於 freeze 狀態, 無法作 新增 / 刪除 / 預覽的動作
var illTrans, data; illuTrans = document.querySelector('illu-trans');
console.log(illuTrans.disabled); //return true || falseilluTrans.disabled = true;.........illuTrans.disabled = false;

透過以上這些 method 的加入, 相信 developer 可以更加有效的掌控 illuTrans, 有興趣的朋友們請不用客氣, 可以直接使用, 也請不吝一同討論與指教喔!

Reference:

轉載文章 – Module 開發 – illuTrans

mei

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *