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系列文章总目录