ABP-JavaScript API (轉)

標籤：.com   資料庫   $.ajax   dde   外掛程式   內部錯誤   com   item   defer   

轉自：http://www.cnblogs.com/zd1994/p/7689164.html

因經常使用，備查

一、AJAX

1，ABP採用的方式

ASP.NET Boilerplate通過用abp.ajax函數封裝AJAX調用來自動執行其中的一些步驟。 一個例子ajax調用：

var newPerson = {    name: ‘Dougles Adams‘,    age: 42};abp.ajax({    url: ‘/People/SavePerson‘,    data: JSON.stringify(newPerson)}).done(function(data) {    abp.notify.success(‘created new person with id = ‘ + data.personId);});

abp.ajax以一個對象作為接收選項。你可以傳遞任何在jQuery的$.ajax方法中有效任何參數。這裡有一些 預設的值：dataType是‘json’，type是‘POST’，contentType是‘application/json’（因此，在發送到伺服器之前，我們可以調用JSON.stringify將javascript對象轉成JSON字串）。你可以通過將選項傳給abp.ajax重寫預設值。

abp.ajax返回了promise。因此，你可以寫done,fail,then等處理函數。上面的例子中，我們向 PeopleController的SavePerson的action發送了簡單的Ajax請求。在 done處理函數中，我們獲得了新添加的person的資料庫Id，而且展示了一個成功的通知。讓我們看一下該Ajax請求的 MVC控制器

public class PeopleController : AbpController{    [HttpPost]    public JsonResult SavePerson(SavePersonModel person)    {        //TODO:將新的person儲存到資料庫，並返回該person的Id        return Json(new {PersonId = 42});    }}

SavePersonModel包含了Name和Age屬性。SavePerson標記有 HttpPost特性，因為abp.ajax預設的方法是POST。這裡通過返回一個匿名的對象簡化了方法的實現。

2，AJAX返回訊息
即使我們直接返回PersonId = 2的對象，ASP.NET Boilerplate也由MvcAjaxResponse對象封裝。 實際的AJAX響應是這樣的：

{  "success": true,  "result": {    "personId": 42  },  "error": null,  "targetUrl": null,  "unAuthorizedRequest": false}

這裡，所有的屬性都是camelCase的（因為在javascript中這是慣例），即使在服務端代碼中是PascalCased的。下面解釋一下所有的欄位：

• success:一個布爾值，表示操作的成功狀態。如果是true，abp.ajax會解析該promise，並調用 done處理函數。如果是false（如果在方法調用中發生了異常），它會調用 fail處理函數並使用abp.message.error函數展示一個 error訊息。
• result：控制器的action返回的實際值。如果success是true，而且伺服器發送了一個傳回值，它才有效。
• error：如果success是false，那麼該欄位是一個包含了 message和 detail欄位的對象。
• targetUrl:這為伺服器提供了一種重新導向用戶端到其他Url的可能性。
• unAuthorizedRequest:這為伺服器提供了通知用戶端該操作沒有授權或者使用者沒有認證的可能性。如果該值是true，那麼abp.ajax會 重新載入當前的頁面。

通過從AbpController類中派生就可以將傳回值轉換成一個封裝的Ajax響應。 abp.ajax會識別並計算該響應。因此，它們成對工作。如果沒有發生錯誤的話，那麼abp.ajax的done處理函數會獲得控制器返回的實際值（一個具有personId屬性的對象）。

當從AbpApiController類派生時，也會存在相同的機制。

3，處理錯誤

正如上面描述的，ABP會處理伺服器中的所有異常，並返回一個具有錯誤資訊的對象，如下所示：

{  "targetUrl": null,  "result": null,  "success": false,  "error": {    "message": "An internal error occured during your request!",    "details": "..."  },  "unAuthorizedRequest": false}

可以看到，success是false，result是null。abp.ajax處理該對象，而且使用abp.message.error函數展示一個錯誤資訊給使用者。如果你的服務端代碼拋出了一個UserFriendlyException類型的異常，它會直接給使用者顯示異常資訊。否則，它會隱藏實際的錯誤（將錯誤寫到日誌中），並展示一個標準的“伺服器內部錯誤...”資訊給使用者。所有的這些都是ABP自動處理的。

4，動態Web API層

雖然ABP提供了一種使得調用Ajax很簡單的機制，但是在真實世界的應用中，為每個Ajax調用編寫javascript函數是很經典的，比如：

//建立一個抽象了Ajax調用的functionvar savePerson = function(person) {    return abp.ajax({        url: ‘/People/SavePerson‘,        data: JSON.stringify(person)    });};//建立一個新的 personvar newPerson = {    name: ‘Dougles Adams‘,    age: 42};//儲存該personsavePerson(newPerson).done(function(data) {    abp.notify.success(‘created new person with id = ‘ + data.personId);});

 

二、Notification

展示自動關閉的通知。

我們喜歡一些事情發生時展示一些精緻的自動消失的通知，比如當儲存一條記錄或者問題發生時。ABP為這個定義了標準的APIs。

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生效，你應該引用toastr的css和javascript檔案，然後再在頁面中包含abp.toastr.js作為適配器。一個toastr成功通知如下所示：

 

你也可以用你最喜歡的通知庫中實現通知。只需要在自訂javascript檔案中重寫所有的函數，然後把它添加到頁面中而不是abp.toastr.js（你可以檢查該檔案看它是否實現，這個相當簡單）中。

 

三、Message

給使用者展示訊息對話方塊。

訊息API用於給使用者展示訊息或者獲得使用者的確認。

訊息API預設是使用sweetalert實現的。要讓sweetalert生效，你應該包含它的css和javascript檔案，然後再頁面中添加 abp.sweet-alert.js的引用作為適配器。

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.confirm(    ‘User admin will be deleted.‘,    ‘Are you sure?‘,    function (isConfirmed) {        if (isConfirmed) {            //...刪除使用者        }    });

這裡的第二個參數（title）是可選的，因此，回呼函數也可以是第二個參數。

一個確認訊息的例子如下所示：

 

ABP內部使用了Message API。比如，如果Ajax調用失敗了，那麼它會調用abp.message.error。

 

四、UI block和Busy API

使用一個地區（一個div，form，整個頁面等）阻塞使用者的輸入。此外，還使得一個地區處於繁忙狀態（具有一個繁忙的指標，如‘loading...’）。

1，UI Block API

該API使用一個透明的塗層（transparent overlay）來阻塞整個頁面或者該頁面上的一個元素。這樣，使用者的點擊就無效了。當儲存一個表單或者載入一個地區（一個div或者整個頁面）時這是很有用的，比如：

abp.ui.block(); //阻塞整個頁面abp.ui.block($(‘#MyDivElement‘)); //可以使用jQuery 選取器..abp.ui.block(‘#MyDivElement‘); //..或者直接使用選取器abp.ui.unblock(); //解除阻塞整個頁面abp.ui.unblock(‘#MyDivElement‘); //解除阻塞特定的元素

UI Block API預設使用jQuery的blockUI外掛程式實現的。要是它生效，你應該包含它的javascript檔案，然後在頁面中包含abp.blockUI.js作為適配器。

2，UI Busy API

該API用於使得某些頁面或者元素處於繁忙狀態。比如，你可能想阻塞一個表單，然後當提交表單至伺服器時展示一個繁忙的指標。例子：

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

該參數應該是一個選取器（如‘#MyLoginForm’）或者jQuery選取器（如$(‘#MyLoginForm‘)）。要使得整個頁面處於繁忙狀態，你可以傳入null（或者‘body‘）作為選取器。

setBusy函數第二個參數接收一個promise（約定），當該約定完成時會自動清除繁忙的狀態。例子：

abp.ui.setBusy(    $(‘#MyLoginForm‘),     abp.ajax({ ... })   );

因為abp.ajax返回promise，我們可以直接將它作為promise傳入。要學習慣於promise更多的東西，查看jQuery的Deferred。

UI Busy API是使用spin.js實現的。要讓它生效，應該包含它的javascript檔案，然後在頁面中包含abp.spin.js作為適配器。

 

五、事件匯流排

用於註冊和觸發用戶端的全域事件。

Pub/sub事件模型廣泛用於用戶端，ABP包含了一個簡單的全域事件匯流排來 註冊並 觸發事件。

1，註冊事件

可以使用abp.event.on來註冊一個全域事件。一個註冊的例子：

abp.event.on(‘itemAddedToBasket‘, function (item) {    console.log(item.name + ‘ is added to basket!‘);});

第一個參數是事件的唯一名稱。第二個是回呼函數，當特定事件被觸發時，會被調用。

可以使用abp.event.off方法來從一個事件中取消註冊。注意：要取消註冊，要提供相同的函數。因此，對於上面的例子，你應該將回呼函數設定為一個變數，然後在on和off方法中使用它。

2，觸發事件

abp.event.trigger用於觸發一個全域事件。觸發一個已經註冊的事件的代碼如下：

abp.event.trigger(‘itemAddedToBasket‘, {    id: 42,    name: ‘Acme Light MousePad‘});

第一個參數是該事件的唯一名稱。第二個是（可選的）事件參數。你可以添加任何數量的參數，並且在回調方法中獲得它們

 

六、日誌

在用戶端記錄日誌。

1，Javascript Logging API

當你想要在用戶端記錄一些簡單的日誌時，你可以使用console.log(‘...‘)API，這你已經知道了。但是這種寫法不是所有的瀏覽器都支援的，而且可能會破壞你的指令碼。因此，你應該首先檢查console是否可用，此外，你可能想在別的地方記錄日誌，甚至你想以某種層級記錄日誌。ABP定義了安全的日誌函數：

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

 

七、其他工具技能

ABP提供了一些通用的工具功能。

1，abp.utils.createNamespace

用於立即建立更深的命名空間。假設我們有一個基命名空間‘abp’，然後想要建立或者獲得‘abp.utils.strings.formatting’命名空間

var formatting = abp.utils.createNamespace(abp, ‘utils.strings.formatting‘;//給該namespace添加一個functionformatting.format = function() { ... };

這樣就簡化了安全地建立深入的命名空間了。注意，第一個參數是必須存在的根命名空間。

2，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 API (轉)