ABP展現層——Javascript函數庫

標籤：

ABP展現層——Javascript函數庫

點這裡進入ABP系列文章總目錄

 

基於DDD的現代ASP.NET開發架構--ABP系列之21、ABP展現層——Javascript函數庫

 

ABP是“ASP.NET Boilerplate Project (ASP.NET樣板項目)”的簡稱。

ABP的官方網站：http://www.aspnetboilerplate.com

ABP在Github上的開源項目：https://github.com/aspnetboilerplate

 

 

ASP.NET Boilerplate的js庫提供了一些讓javascript開發更方便的方法和對象,以下介紹一下庫中的API列表。

Ajax

現代的應用經常會使用AJAX，尤其是單頁應用，幾乎是和伺服器通訊的唯一手段，執行AJAX通常會有以下步驟：

在用戶端，你需要提供一個URL，選擇一個和伺服器通訊的方法（GET,POST,PUT,DELETE）。在請求完成後執行回呼函數，請求結果可更是成功或失敗，失敗時你需要給出提示，成功時你需要根據傳回值執行操作。通常情況下，在請求開始時，你需要給出類似正在處理或者相關的繁忙等待資訊（如頁面遮蓋），請求完成後恢複。

服務端接收到請求後，對請求參數進行驗證，執行服務端代碼，如果發生錯誤或者驗證失敗，應給出具體的原因，成功時返回用戶端想要的資料。

ABP服務端支援標準的ajax的請求/輸出。建議大家使用abp.jquery.js中提供的ajax要求方法，這個方法基於jquery的ajax方法，可以自動處理服務端的異常資訊，當然，如果你對js很熟練的話，也可以根據自己的需要寫ajax。

ASP.NET Boilerplate的ajax請求執行個體：

//構建要傳輸的參數對象var newPerson = {    name: ‘Dougles Adams‘,    age: 42};//調用abp的ajax方法abp.ajax({    url: ‘/People/SavePerson‘,    data: JSON.stringify(newPerson) //轉換成json字串}).done(function(data) {abp.notify.success(‘created new person with id = ‘ + data.personId);});

你也可以使用jquery的ajax方法調用，但是需要設定一下預設請求參數，dataType 設定為 ‘json‘, type 設定為 ‘POST‘ and contentType 設定為 ‘application/json，在發送請求時需要將js對象轉換成json字串，和$.ajax一樣，你也可以傳遞參數覆蓋abp.ajax的預設參數abp.ajax返回一個promise類型，你可以鏈式編程寫如下的方法：

.done() //成功,.fail() //失敗，.then() //回調嵌套。

下面的一個簡單的例子展示ajax請求PeopleController的SavePerson方法，在.done()中可以擷取到服務端建立記錄成功後返回的記錄id。

public class PeopleController : AbpController{    [HttpPost]    public JsonResult SavePerson(SavePersonModel person)    {        //TODO: save new person to database and return new person‘s id//TODO: 建立一個新的person記錄並返回此記錄的id        return Json(new {PersonId = 42});    }}

SavePersonModel 包含name,age等屬性. SavePerson 上標記了 HttpPost 特性 abp.ajax預設以 POST 方式請求. 傳回值被簡化成了一個匿名對象。

SavePersonModel 包含name,age等屬性. SavePerson 上標記了 HttpPost 特性 abp.ajax預設以 POST 方式請求. 傳回值被簡化成了一個匿名對象。

AJAX 傳回值(AJAX return messages)

我們直接返回了一個匿名對象, ABP 通過 MvcAjaxResponse 類型封裝了傳回值. 實際的傳回值類型如下:

{  "success": true, //正確處理標誌  "result": {    "personId": 42 //返回的資料  },  "error": null, //如果發生錯誤，result為null，此處為錯誤資訊的對象，包含message和details兩個屬性  "targetUrl": null, //可以提供一個url供用戶端重新導向，例如自動構建下一頁的url  "unAuthorizedRequest": false //是否通過了授權，如果返回true，用戶端應重新登入}

如果你繼承了AbpController，Json方法返回的對象總會被這樣封裝，如果未發生錯誤，你在abp.ajax的done(function(result,data){})中，第一個參數result是{"personId": 42}對象，data是原始對象,WebApi中繼承AbpApiController也是同樣的機制。

錯誤處理(Handling errors)

傳回值如下:

{  "targetUrl": null,  "result": null,  "success": false, //代表出現異常  "error": {    "message": "An internal error occured during your request!", //未捕捉到的異常，通常為系統異常，會自動記錄日誌，具體提示資訊在設定檔配置，可以搜尋一下，如果是業務拋出的UserFriendlyException異常，message為具體的錯誤資訊    "details": "..." //發生異常時預設會調用abp.message.error函數，你可以在abp.jquery.js修改，統一處理錯誤資訊。  },  "unAuthorizedRequest": false}

動態WebAPI（Dynamic Web API Layer）

此處會根據Services動態產生WebAPI調用函數:

//通常我們使用ajax會按照如下寫法，做一個簡單的封裝來重用ajax，此處架構可以幫你產生簡單的調用方法var savePerson = function(person) {    return abp.ajax({        url: ‘/People/SavePerson‘,        data: JSON.stringify(person)    });};//調用時你需要構建參數var newPerson = {    name: ‘Dougles Adams‘,    age: 42};//直接調用方法，如何產生上面的調用方法可以參考源碼中的Abp.Web.Api項目中/ WebApi/ Controllers/ Scripting/ jQuery下的實現savePerson(newPerson).done(function(data) {    abp.notify.success(‘created new person with id = ‘ + data.personId);});

通知

通知會顯示在右下角，稍後自動消失

abp.notify.success(‘a message text‘, ‘optional title‘);abp.notify.info(‘a message text‘, ‘optional title‘);abp.notify.warn(‘a message text‘, ‘optional title‘);abp.notify.error(‘a message text‘, ‘optional title‘);

通知API是依賴於toastr庫，你需要在項目中引用toastr的js和css，然後引用ABP項目的abp.toastr.js，notify.success調用後的樣子:

你可以運行樣板項目，在瀏覽器的控制台測試這幾種提示訊息，另外，當ajax出現異常時，你可以修改abp.jquery.js的源檔案，來調用abp.notify.error方法實現友好的提示資訊。

如果你有其他的的通知外掛程式也可以使用，引用相應的js庫就可以了，提示訊息的js是可選的。

訊息

用於向使用者顯示對話方塊，展示訊息或者得到使用者的確認,ABP預設採用的sweetalert庫實現的對話方塊資訊，使用時你需要引用sweetalert的樣式和js，並且引用abp.sweet-alert.js就可以使用下列API了:

abp.message.info(‘some info message‘, ‘some optional title‘);abp.message.success(‘some success message‘, ‘some optional title‘);abp.message.warn(‘some warning message‘, ‘some optional title‘);abp.message.error(‘some error message‘, ‘some optional title‘);

調用abp.message.success會展示如下的對話方塊:

Confirmation 確認對話方塊:

abp.message.confirm(    ‘User admin will be deleted.‘, //確認提示    ‘Are you sure?‘,//確認提示（選擇性參數）    function (isConfirmed) {        if (isConfirmed) {            //...delete user 點擊確認後執行        }    });

預設ABP的js庫中可能會引用到訊息API，比如ajax調用失敗會調用abp.message.error。

使用者介面的繁忙提示

ABP提供了設定頁面的某部分繁忙的API。

UI Block API

設定一個半透明層，阻止點擊頁面元素，可以覆蓋局部或者整個頁面，例子如下:

abp.ui.block(); //覆蓋整個頁面abp.ui.block($(‘#MyDivElement‘)); //覆蓋指定元素，可以把jquery對象作為參數abp.ui.block(‘#MyDivElement‘); //或者直接使用選取器參數abp.ui.unblock(); //整個頁面解除覆蓋abp.ui.unblock(‘#MyDivElement‘); //指定元素解除覆蓋

UI Block API使用blockUI這個js庫來實現效果的，如果使用這個api需要在頁面引用blockUI的js庫和abp.blockUI.js檔案。

UI Busy API 指示頁面繁忙的API，如ajax請求中:

abp.ui.setBusy(‘#MyLoginForm‘);abp.ui.clearBusy(‘#MyLoginForm‘);

第一個參數可以直接使用jquery選取器如’#id’或者使用jquery對象如$(‘#id’),如果傳null或者‘body’則標記整個頁面為繁忙狀態，第二個參數可以接收一個promise，promise完成後會自動解除頁面繁忙狀態。

abp.ui.setBusy(    $(‘#MyLoginForm‘),     abp.ajax({ ... })   //傳回值是promise，如果需要瞭解promise的更多資訊，可以參考jQuery的 Deferred );

UI Busy API 使用的是spin.js，你需要在頁面中引用spin.js和abp.spin.js。

Js日誌介面

這個主要是對瀏覽器console.log(‘...‘) 進行的封裝，可以支援所有瀏覽器，例子如下:

abp.log.debug(‘...‘);abp.log.info(‘...‘);abp.log.warn(‘...‘);abp.log.error(‘...‘);abp.log.fatal(‘...‘);

你可以通過設定abp.log.level來控制日誌輸出，和服務端一樣，如設定了abp.log.levels為INFO時就不會輸出debug日誌了，你也可以根據你的需要定製重新這些API。

Javascript公用方法

ABP提供了一些常用的公用方法。

建立命名空間別名(abp.utils.createNamespace)

通過建立命名空間讓js方法分類更加明確，使用更加方便，下面是例子：

//建立或者擷取命名空間abp.utils = abp.utils || {};abp.utils.strings = abp.utils.strings || {};abp.utils.strings.formatting = abp.utils.strings.formatting || {};//在命名空間中增加一個方法abp.utils.strings.formatting.format = function() { ... };你可以向下面一樣用//建立命名空間別名var formatting = abp.utils.createNamespace(abp, ‘utils.strings.formatting‘;//在formatting命名空間下增加/修改一個方法formatting.format = function() { ... };

別名簡化了以前長長的名字，需要注意的是，第一個參數是必須存在的根命名空間。

格式化字串(abp.utils.formatString)

和C#的string.Format一樣的用法

var str = abp.utils.formatString(‘Hello {0}!‘, ‘World‘); //str = ‘Hello World!‘var str = abp.utils.formatString(‘{0} number is {1}.‘, ‘Secret‘, 42); //str = ‘Secret number is 42‘ 

 

ABP展現層——Javascript函數庫