抠丁客 抠丁客
项目
编辑 (2025/12/24)

ASP.NET Core MVC / Razor Pages UI JavaScript AJAX API

abp.ajax API 提供了一种便捷的方式向服务器执行AJAX调用。它内部使用JQuery的$.ajax，但自动处理了一些常见任务：

  • 自动处理并本地化错误，并通知用户（使用abp.message）。因此通常无需关心错误处理。
  • 自动在HTTP头部添加防伪令牌以满足服务端的CSRF保护验证。
  • 自动设置默认选项，并允许在统一位置配置默认值。
  • 可在AJAX操作期间锁定部分UI（或整个页面）。
  • 通过标准$.ajax选项允许完全自定义任何AJAX调用。

虽然abp.ajax使AJAX调用更加简便，但通常建议使用动态JavaScript客户端代理系统来调用服务端HTTP API。当需要进行底层AJAX操作时，可使用abp.ajax。

基础用法

abp.ajax接受标准$.ajax所支持的选项对象。所有标准选项均有效，返回值是一个promise对象。

示例：获取用户列表

abp.ajax({
  type: 'GET',
  url: '/api/identity/users'
}).then(function(result){
  console.log(result);
});

如果用户已登录应用且具有Identity模块用户管理页面的授权权限，此命令会将用户列表输出到控制台。

错误处理

如果未登录应用或没有执行此请求的必要权限，上述AJAX调用示例会显示错误信息：

ajax-error

除非主动禁用，否则所有类型的错误都会被abp.ajax自动处理。

标准错误响应

abp.ajax与ABP的异常处理系统兼容，能正确处理服务端返回的标准错误格式。典型错误信息为如下JSON格式：

{
  "error": {
    "code": "App:010042",
    "message": "该主题已锁定，无法添加新消息",
    "details": "关于错误的更详细信息..."
  }
}

系统会使用message和details属性直接向用户显示错误信息。

非标准错误响应与HTTP状态码

即使服务端未发送标准错误格式，该API也能处理错误。这种情况可能发生在绕过ABP异常处理系统并手动构建HTTP响应时。此时会依据HTTP状态码进行处理。

预定义的HTTP状态码处理规则：

  • 401：显示“需要认证（登录）才能执行此操作”的提示。用户点击确定按钮后，将被重定向到应用首页重新登录。
  • 403：显示“您无权执行此操作”的提示。
  • 404：显示“未在服务器上找到请求的资源”的提示。
  • 其他状态码：显示“发生错误。服务器未发送错误详情”的通用提示。

所有提示信息会根据当前用户语言进行本地化。

手动处理错误

由于abp.ajax返回promise对象，可通过链式调用.catch(...)注册AJAX请求失败时的回调函数。

示例：AJAX请求失败时显示警告框

abp.ajax({
  type: 'GET',
  url: '/api/identity/users'
}).then(function(result){
  console.log(result);
}).catch(function(){
  alert("请求失败 :(");
});

虽然自定义回调会被触发，但ABP仍会自行处理错误。如需禁用自动错误处理，可在abp.ajax选项中传入abpHandleError: false。

示例：禁用自动错误处理

abp.ajax({
  type: 'GET',
  url: '/api/identity/users',
  abpHandleError: false //禁用自动错误处理
}).then(function(result){
  console.log(result);
}).catch(function(){
  alert("请求失败 :(");
});

若设置abpHandleError: false但未自定义错误捕获，错误将被静默忽略。abp.ajax仍会将错误记录到浏览器控制台（可通过配置章节进行重写）。

配置

abp.ajax提供全局配置，可根据需求进行自定义。

默认AJAX选项

abp.ajax.defaultOpts对象用于配置执行AJAX调用时的默认选项（除非被显式覆盖）。该对象的默认值如下：

{
    dataType: 'json',
    type: 'POST',
    contentType: 'application/json',
    headers: {
        'X-Requested-With': 'XMLHttpRequest'
    }
}

如需修改默认请求类型，可按如下方式操作：

abp.ajax.defaultOpts.type = 'GET';

此代码需在所有JavaScript代码之前执行。通常建议将此类配置置于独立的JavaScript文件中，并通过全局打包系统添加到布局中。

日志/错误显示

以下函数可被重写以自定义错误记录和显示方式：

  • abp.ajax.logError函数默认使用abp.log.error(...)记录错误。
  • abp.ajax.showError函数默认使用abp.message.error(...)显示错误信息。
  • abp.ajax.handleErrorStatusCode处理不同HTTP状态码并显示对应提示。
  • abp.ajax.handleAbpErrorResponse处理符合ABP标准格式的错误响应。
  • abp.ajax.handleNonAbpErrorResponse处理非标准错误响应。
  • abp.ajax.handleUnAuthorizedRequest处理401状态码响应，并重定向用户至应用首页。

示例：重写logError函数

abp.ajax.logError = function(error) {
    //...
}

其他选项

  • abp.ajax.ajaxSendHandler函数用于拦截AJAX请求并向HTTP头部添加防伪令牌。注意此功能对所有AJAX请求生效（即使未使用abp.ajax）。
在本文档中