ABP(現代ASP.NET樣板開發框架)系列之2一、ABP展示層——Javascript函數庫

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

 

基於DDD的現代ASP.NET開發框架--ABP系列之2一、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這個項目，也許這其中有能幫助到您的地方，也許有您的參與，這個項目能夠發展得更好。

歡迎加QQ羣：

ABP架構設計交流羣：134710707       ABP架構設計交流2羣： 579765441

 

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