2016 年 2 月 26 日，星期五

省略符號渲染器

在使用 DataTables 的過程中，有時從來源資料取得的格式並非您希望呈現給終端使用者的格式。為此，DataTables 支援透過資料渲染器，並透過 columns.render 來進行設定。此選項可以用作執行資料轉換的函式（它是一個 Javascript 函式，因此您可以執行任何您想執行的操作！），並且會在 DataTables 需要該儲存格的資料時呼叫。實際上，此選項也是 DataTables 提供其正交資料支援的方式。

以下是渲染器可派上用場的簡短用例清單

將日期/時間轉換為本地化格式
格式化貨幣、可讀性和精度的數字
安全性，以防止 XSS 攻擊
縮短長字串

本文將詳細介紹渲染器如何運作，並通過實作上述清單中的最後一個選項作為範例來說明：長文字將被縮短，並使用省略符號來表示文字已遭截斷。

範例

下表顯示了一個範例 – 第一欄在 10 個字元處使用省略符號，且不允許斷字，而第二欄在 15 個字元處使用省略符號，且允許在字詞中間截斷。範例表格也啟用了 Responsive。

姓名	職稱	辦公室	年齡	開始日期	薪資
Tiger Nixon	系統架構師	愛丁堡	61	2011-04-25	$320,800
Garrett Winters	會計	東京	63	2011-07-25	$170,750
Ashton Cox	初級技術作者	舊金山	66	2009-01-12	$86,000
Cedric Kelly	資深 Javascript 開發人員	愛丁堡	22	2012-03-29	$433,060
Airi Satou	會計	東京	33	2008-11-28	$162,700
Brielle Williamson	整合專家	紐約	61	2012-12-02	$372,000
Herrod Chandler	銷售助理	舊金山	59	2012-08-06	$137,500
Rhona Davidson	整合專家	東京	55	2010-10-14	$327,900
Colleen Hurst	Javascript 開發人員	舊金山	39	2009-09-15	$205,500
Sonya Frost	軟體工程師	愛丁堡	23	2008-12-13	$103,600
Jena Gaines	辦公室經理	倫敦	30	2008-12-19	$90,560
Quinn Flynn	支援主管	愛丁堡	22	2013-03-03	$342,000
Charde Marshall	區域總監	舊金山	36	2008-10-16	$470,600
Haley Kennedy	資深行銷設計師	倫敦	43	2012-12-18	$313,500
Tatyana Fitzpatrick	區域總監	倫敦	19	2010-03-17	$385,750
Michael Silva	行銷設計師	倫敦	66	2012-11-27	$198,500
Paul Byrd	財務長 (CFO)	紐約	64	2010-06-09	$725,000
Gloria Little	系統管理員	紐約	59	2009-04-10	$237,500
Bradley Greer	軟體工程師	倫敦	41	2012-10-13	$132,000
Dai Rios	人事主管	愛丁堡	35	2012-09-26	$217,500
Jenette Caldwell	開發主管	紐約	30	2011-09-03	$345,000
Yuri Berry	行銷長 (CMO)	紐約	40	2009-06-25	$675,000
Caesar Vance	售前支援	紐約	21	2011-12-12	$106,450
Doris Wilder	銷售助理	雪梨	23	2010-09-20	$85,600
Angelica Ramos	執行長 (CEO)	倫敦	47	2009-10-09	$1,200,000
Gavin Joyce	開發人員	愛丁堡	42	2010-12-22	$92,575
Jennifer Chang	區域總監	新加坡	28	2010-11-14	$357,650
Brenden Wagner	軟體工程師	舊金山	28	2011-06-07	$206,850
Fiona Green	營運長 (COO)	舊金山	48	2010-03-11	$850,000
Shou Itou	區域行銷	東京	20	2011-08-14	$163,000
Michelle House	整合專家	雪梨	37	2011-06-02	$95,400
Suki Burks	開發人員	倫敦	53	2009-10-22	$114,500
Prescott Bartlett	技術作者	倫敦	27	2011-05-07	$145,000
Gavin Cortez	團隊領導	舊金山	22	2008-10-26	$235,500
Martena Mccray	售後支援	愛丁堡	46	2011-03-09	$324,050
Unity Butler	行銷設計師	舊金山	47	2009-12-09	$85,675
Howard Hatfield	辦公室經理	舊金山	51	2008-12-16	$164,500
Hope Fuentes	秘書	舊金山	41	2010-02-12	$109,850
Vivian Harrell	財務總監	舊金山	62	2009-02-14	$452,500
Timothy Mooney	辦公室經理	倫敦	37	2008-12-11	$136,200
Jackson Bradshaw	總監	紐約	65	2008-09-26	$645,750
Olivia Liang	支援工程師	新加坡	64	2011-02-03	$234,500
Bruno Nash	軟體工程師	倫敦	38	2011-05-03	$163,500
Sakura Yamamoto	支援工程師	東京	37	2009-08-19	$139,575
Thor Walton	開發人員	紐約	61	2013-08-11	$98,540
Finn Camacho	支援工程師	舊金山	47	2009-07-07	$87,500
Serge Baldwin	資料協調員	新加坡	64	2012-04-09	$138,575
Zenaida Frank	軟體工程師	紐約	63	2010-01-04	$125,250
Zorita Serrano	軟體工程師	舊金山	56	2012-06-01	$115,000
Jennifer Acosta	初級 Javascript 開發人員	愛丁堡	43	2013-02-01	$75,650
Cara Stevens	銷售助理	紐約	46	2011-12-06	$145,600
Hermione Butler	區域總監	倫敦	47	2011-03-21	$356,250
Lael Greer	系統管理員	倫敦	21	2009-02-27	$103,500
Jonas Alexander	開發人員	舊金山	30	2010-07-14	$86,500
Shad Decker	區域總監	愛丁堡	51	2008-11-13	$183,000
Michael Bruce	Javascript 開發人員	新加坡	29	2011-06-27	$183,000
Donna Snider	客戶支援	紐約	27	2011-01-25	$112,000
姓名	職稱	辦公室	年齡	開始日期	薪資

簡單渲染器

首先，讓我們考慮最簡單的情況 - 一個 HTML 來源的表格，其中我們希望將第一欄中的字元數限制為不超過 10 個字元

$('#myTable').DataTable( {
    columnDefs: [ {
        targets: 0,
        render: function ( data, type, row ) {
            return data.substr( 0, 10 );
        }
    } ]
} );

上面的程式碼在 #myTable 元素上建立了一個 DataTable，並使用 columnDefs 將欄位選項僅指派給第一欄 (columnDefs.targets)。這裡最重要的部分是使用渲染函式 - columns.render。我們使用 substr() 將資料限制為僅 10 個字元。

這很容易實作，但有一些問題

沒有任何跡象表明資料已被截斷
搜尋和排序資料也將被截斷。

讓我們逐一解決這些問題 – 為了向終端使用者表示資料已被截斷，我們使用省略符號 (…)。一個簡單的檢查來查看字串是否會被截斷，使我們能夠決定是否應添加省略符號

render: function ( data, type, row ) {
    return data.length > 10 ?
        data.substr( 0, 10 ) +'…' :
        data;
}

為了解決第二點，我們可以使用傳遞到函式的第二個參數，它是 DataTables 的正交資料類型指示器 - 只有當它是 display 時，我們才希望顯示省略符號。現在我們有了

render: function ( data, type, row ) {
    return type === 'display' && data.length > 10 ?
        data.substr( 0, 10 ) +'…' :
        data;
}

簡單！

可重複使用的渲染器

以上是一些簡單的程式碼，但是如果您正在開發任何具有多個頁面的網站，您將希望遵循良好軟體開發的不要重複自己 (DRY) 原則。

由於函式是 Javascript 中的一級元素，我們可以將渲染函式儲存在變數中，然後根據需要將其指派給 columns.render 選項。DataTables 提供了一個物件，可以用作儲存所有渲染器的通用位置：DataTable.render。

如果我們繼續我們的省略符號範例，我們可能會得到

DataTable.render.ellipsis = function () {
    return function ( data, type, row ) {
        return type === 'display' && data.length > 10 ?
            data.substr( 0, 10 ) +'…' :
            data;
    }
};

然後，為了在 DataTables 中使用它，我們可以使用

$('#myTable').DataTable( {
    columnDefs: [ {
        targets: 0,
        render: DataTable.render.ellipsis()
    } ]
} );

然後，該渲染函式可以在多個頁面的多個表格中使用 – 只需將渲染器程式碼儲存到載入到您的頁面中的檔案中 (例如 dataTables.plugins.js)。

組態選項

您會注意到我們將 ellipsis 定義為傳回函式的函式 – 在這種簡單的情況下，這不是特別有用，但是對於更複雜的情況，以及為了繼續 DRY 的概念，外部函式可以用來組態渲染器。在我們的省略符號範例中，這可以是定義將顯示的字元數的能力 – 例如

DataTable.render.ellipsis = function ( cutoff ) {
    return function ( data, type, row ) {
        return type === 'display' && data.length > cutoff ?
            data.substr( 0, cutoff ) +'…' :
            data;
    }
};

現在，渲染器可以用來定義顯示的字元數

render: DataTable.render.ellipsis( 10 )
render: DataTable.render.ellipsis( 15 )
render: DataTable.render.ellipsis( 20 )
etc

即使在不需要組態選項的情況下，為了保持一致性，使用容器函式也是一個好主意。大多數渲染函式都需要某種組態，因此如果所有渲染外掛程式都以需要執行的函式形式呈現，則會更容易。

省略符號渲染外掛程式

現在已經奠定了如何建立 DataTables 渲染外掛程式的基礎，讓我們建立省略符號外掛程式以提供更多實用性，並具有以下功能

可變長度截斷
在工具提示中顯示完整字串
選擇不允許在單字中間斷開
能夠跳脫 HTML 以確保 XSS 安全性

以下函式提供所有這些功能

DataTable.render.ellipsis = function ( cutoff, wordbreak, escapeHtml ) {
    var esc = function ( t ) {
        return t
            .replace( /&/g, '&amp;' )
            .replace( /</g, '&lt;' )
            .replace( />/g, '&gt;' )
            .replace( /"/g, '&quot;' );
    };

    return function ( d, type, row ) {
        // Order, search and type get the original data
        if ( type !== 'display' ) {
            return d;
        }

        if ( typeof d !== 'number' && typeof d !== 'string' ) {
            return d;
        }

        d = d.toString(); // cast numbers

        if ( d.length < cutoff ) {
            return d;
        }

        var shortened = d.substr(0, cutoff-1);

        // Find the last white space character in the string
        if ( wordbreak ) {
            shortened = shortened.replace(/\s([^\s]*)$/, '');
        }

        // Protect against uncontrolled HTML input
        if ( escapeHtml ) {
            shortened = esc( shortened );
        }

        return '<span class="ellipsis" title="'+esc(d)+'">'+shortened+'&#8230;</span>';
    };
};

分解函式後，您會發現以上是相當基本的 Javascript。只有 display 資料類型才會截斷其長度（如上所述），並且僅會操作字串。如果啟用不允許斷字選項，則會截斷字串，並使用正規表示式縮短至最後一個單字。最後，會傳回一個 span，其中包含縮短的字串以及省略符號和由 title 屬性提供的瀏覽器工具提示（如果您喜歡，也可以使用 Javascript 工具提示函式庫）。

來源

省略符號資料渲染器在其外掛程式頁面上有詳細說明，並可在 DataTables CDN 上取得（請注意，您可能希望將多個外掛程式合併到一個檔案中以提高載入效率）

該來源也可在 GitHub 上取得，並且隨時歡迎提出改進的提取請求。

分享外掛程式

如果您建立了一個您想與 DataTables 社群分享的渲染外掛程式 - 首先 - 謝謝您！請將提取請求傳送至 DataTabels 外掛程式儲存庫中的 dataRender 目錄。還應包含一個文件區塊，詳細說明外掛程式的功能以及如何使用它（請參閱現有的外掛程式以取得範本）。

祝您使用愉快！