_ajax

Ajax专用模块

Ajax专用访问处理,其中包括两大类方法:

  1. Ajax方法
  2. Callback回调方法(带回调响应、消息、执行函数等)。
函数名 说明
ajax2Dialog 「回调」弹出窗口2阶函数。
ajax2Message 「回调」消息提示2阶函数。
ajax2True 「回调」存在检查2阶函数。
ajaxDelete DELETE请求。
ajaxDialog 「回调」弹出窗口函数。
ajaxDownload GET下载。
ajaxEager 「引擎」表格专用函数,提前执行Ajax读取执行数据渲染专用。
ajaxError 「回调」异常回调函数。
ajaxFetch 「非安全」GET读取远程数据。
ajaxGet GET请求。
ajaxMessage 「回调」消息提示函数。
ajaxPost POST请求。
ajaxPull POST下载。
ajaxPush 「非安全」POST提交远程数据。
ajaxPut PUT请求。
ajaxResource 「本地」当前站点,不带ENDPOINT的资源信息读取,一般读取HTML。
ajaxUpload 上传专用函数。
asyncAssist Assist辅助数据异步调用函数。
asyncData 数据执行异步调用函数。
asyncMagic 解析magic节点配置专用异步调用函数。
asyncPromise 构造异步Promise专用。
asyncTrue 存在检查异步执行函数。
messageCatch 「回调」远程系统异常消息提示。
messageFailure 「回调」远程业务异常消息提示。
messageSuccess 「回调」成功消息提示。
microDelete 「微服务」DELETE请求。
microFetch 「微服务非安全」GET请求。
microGet 「微服务」GET请求。
microPost 「微服务」POST请求。
microPush 「微服务非安全」POST请求。
microPut 「微服务」PUT请求。
rxEdict redux专用Ajax函数,执行Epic(遗留函数,后续也会使用,用于读取全局数据)

1. 基础方法表格说明

1.1. Ajax方法说明

维度 安全 非安全 「微」安全 「微」非安全
GET ajaxGet ajaxFetch microGet microFetch
POST ajaxPost ajaxPush microPost microPush
PUT ajaxPut (无) microPut (无)
DELETE ajaxDelete (无) microDelete (无)

非安全方法只支持GET和POST两种,而安全模式下会执行token的计算以及数字签名模式(为标准方法)。

1.2. 回调方法说明

维度 一阶 二阶
窗口 ajaxDialog ajax2Dialog
消息 ajaxMessage ajax2Message
存在检查 (无) ajax2True
异常 ajaxError (无)
直接消息模式 messageSuccess, messageFailure, messageCatch (无)

关于其他说明参考访问本身。

Methods

(static) ajax2Dialog(reference, key, redux) → {function}

「标准2阶」Ux.ajax2Dialog

直接封装 ajaxDialog 的2阶函数,函数参数如下:

参数名 类型 说明
data any 响应的核心数据信息,Object 或 Array
Parameters:
Name Type Default Description
reference React.Component

React组件引用。

key String

窗口所消费的资源文件中的 key 键值。

redux boolean false

是否启用 redux 流程。

Returns:

返回函数,该函数会消费响应信息得到 Promise。

Type
function

(static) ajax2Message(reference, key, redux) → {function}

「标准2阶」Ux.ajax2Message

直接封装 ajaxMessage 的2阶函数,函数参数如下:

参数名 类型 说明
data any 响应的核心数据信息,Object 或 Array
Parameters:
Name Type Default Description
reference React.Component

React组件引用。

key String

窗口所消费的资源文件中的 key 键值。

redux boolean false

是否启用 redux 流程。

Returns:

返回函数,该函数会消费响应信息得到 Promise。

Type
function

(static) ajax2True(consumer, content) → {function}

「标准2阶」Ux.ajax2True

当前 ajax 比较特殊,ajax 请求只会响应 true 或 false,根据最终结果执行相关操作

Parameters:
Name Type Description
consumer function

执行的核心函数,在响应数据为 true 时执行该函数

content String

消息中呈现的消息内容

Returns:

返回一个函数消费 true | false 的相关结果

Type
function

(async, static) ajaxDelete(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxDelete

安全方法(带token),DELETE开放性方法

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(static) ajaxDialog(reference, data, key, redux) → {Promise.<T>}

「标准」Ux.ajaxDialog

弹出窗口专用函数,调用 Ant Design 中的 Modal 的弹出框处理,success, error, confirm 专用处理函数。 在传入的 reference 引用中,props 属性中必须包含 config 对象(窗口配置信息),它的结构如下:

1. key 为 String

如果传入的 key 是字符串,config 的配置结果如,这份结果来自资源文件中的 shared.json

{
    "dialog": {
        "modal": "模式信息",
        "title": {
             "success": "信息",
             "failure": "警告",
             "error": "错误",
             "confirm": "提示"
        }
    }
}

执行了计算过后,会处理以下步骤

  1. 根据 mode 计算窗口标题,从 dialog中的三种窗口中去读。
  2. 根据 pattern 数据计算最终的格式,Modal需要的。

计算的最终配置格式如:

{
    "mode": "success | confirm | error",
    "title": "标题文本",
    "content": "内容使用 pattern 计算,执行 formatExpr 的格式化",
    "redux": "是否开启 redux 流程"
}

2. key 为 Object

这是第二种配置模式,传入的 key 转换成 configuration 过后的数据格式如:

{
    "title": "标题信息",
    "pattern": "未解析的模式",
    "content": "二选一,是否执行 formatExpr 的格式化操作",
    "model": "success | confirm | error",
    "redux": "是否开启 redux 流程"
}

3. 最终格式

不论 key 的传入类型是哪种,最终的处理格式如"

{
    "title": "",
    "content": "",
    "mode": ""
    "redux": ""
}
Parameters:
Name Type Description
reference React.Component

React组件引用。

data Object | Array

响应数据处理格式。

key String

窗口所消费的资源文件中的 key 键值。

redux boolean

是否启用 redux 流程。

Returns:

返回效应窗口之外最终的 Promise。

Type
Promise.<T>

(async, static) ajaxDownload(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxDownload

安全方法(带token),GET下载专用方法,下载内容会返回二进制数据

Parameters:
Name Type Description
uri String

远程上传开放的Api接口路径

params Object

下载文件的专用参数

options Object

Http请求头相关信息

Returns:

返回上传过后的 Promise

Type
Promise.<T>

(async, static) ajaxEager(reference, columns, data) → {Promise.<T>}

「引擎」Ux.ajaxEager

异步表格列渲染专用预处理函数。在表格渲染中,如果使用了字典如:

字典配置

[
     {
         "key": "9db923a3-e13b-4e4f-b468-8f026c9aa1ab",
         "name": "测试标签"
     },
     {
         "key": "72180b29-8c33-4419-a312-405d66a67521",
         "name": "正式标签"
     },
     {
         "key": "1dd8ff65-b570-483d-a98d-fe987fd25c03",
         "name": "特殊标签"
     }
]

上述结构中,表格列里存储的数据是 key,而不是 name,但在表格呈现时需要呈现 name字段的信息,这种情况下需要执行 ajaxEager 进行预处理。如配置和数据分别如下:

config 配置

[
     {
         "dataIndex": "labelKey",
         "title": "标签",
         "$render": "USER",
         "$config": {
             "uri": "异步专用Ajax",
             "expr": "呈现专用表达式",
             "field": "name,读取数据中需要解析的字段"
         }
     }
]

data 数据

[
     { labelKey:"9db923a3-e13b-4e4f-b468-8f026c9aa1ab", name:"记录1" },
     { labelKey:"9db923a3-e13b-4e4f-b468-8f026c9aa1ab", name:"记录2" },
     { labelKey:"72180b29-8c33-4419-a312-405d66a67521", name:"记录3" },
     { labelKey:"9db923a3-e13b-4e4f-b468-8f026c9aa1ab", name:"记录4" },
     { labelKey:"72180b29-8c33-4419-a312-405d66a67521", name:"记录5" },
     { labelKey:"72180b29-8c33-4419-a312-405d66a67521", name:"记录6" },
     { labelKey:"72180b29-8c33-4419-a312-405d66a67521", name:"记录7" },
     { labelKey:"72180b29-8c33-4419-a312-405d66a67521", name:"记录8" }
]

核心分析

上述数据中,只有两类labelKey出现,如果表格的每个单元格都调用 Ajax 异步处理数据,那么上述数据会执行8次异步访问记录 而 ajaxEager 函数就是为这种情况量身打造的异步渲染函数,如果调用ajaxEager则只会访问两次,通过这种方式在一页呈现数据 量大的时候会大规模减少和服务端的交互,为了性能考虑,可以使用这个函数来实现,上述例子中最终函数会返回如下数据格式。

{
     "9db923a3-e13b-4e4f-b468-8f026c9aa1ab": "测试标签",
     "72180b29-8c33-4419-a312-405d66a67521": "正式标签"
}

上述结构是当前页的数据中的数据,特殊标签由于在本页数据中没使用,所以不会读取到,ajaxEager函数主要的实现考虑有两点:

  • 减少和服务端交互的次数,根据本页数据直接分页构造分组型请求。
  • 减少所需数据量,只读取合法字典中的数据。
Parameters:
Name Type Description
reference ReactComponent

【保留】React组件引用

columns Array

表格配置中的 columns 属性

data Array

表格已经加载好的二维数据信息

Returns:

特殊结构处理表格渲染专用

Type
Promise.<T>

(static) ajaxError(reference, error, redux)

「标准」Ux.ajaxError

错误信息专用函数,注,这里的 Component 的引用必须是绑定了cab/cn/中的资源文件的组件, 资源文件中会自动包含 _dialog 的窗口键值,error的数据结构如:

{
    "code": "错误代码,整数",
    "message": "错误信息",
    "info": "前端可读信息"
}

处理最终的响应数据时候还需要考虑 redux 参数

  1. redux = true,启用 redux 流程
  2. redux = false,不启用 redux 流程,仅使用当前组件流程,React 中的 state 状态流程
Parameters:
Name Type Default Description
reference React.Component

React组件引用

error Object

Zero 的核心错误响应信息

redux boolean false

是否启用了 redux 流程写 redux 的树形数据

(async, static) ajaxFetch(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxFetch

非安全方法,GET开放性方法,从远程地址中直接读取远程请求数据的方法。

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) ajaxGet(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxGet

安全方法(带token),GET开放性方法。

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(static) ajaxMessage(reference, data, key) → {Promise.<T>}

「标准」Ux.ajaxMessage

该函数只支持一种格式,config 的配置结果如,这份结果来自资源文件中的 shared.json 但由于是 message 所以只考虑最终的 pattern 配置,并且使用 data 来执行 formatExpr 得到最终 的 content 相关数据,消息只执行两种模式

  • success:成功相关信息
  • :其他模式,直接执行 failure 的错误消息提示
Parameters:
Name Type Description
reference React.Component

React组件引用。

data Object | Array

响应数据处理格式。

key String

窗口所消费的资源文件中的 key 键值。

Returns:

返回效应窗口之外最终的 Promise。

Type
Promise.<T>

(async, static) ajaxPost(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxPost

安全方法(带token),POST开放性方法

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) ajaxPull(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxPull

安全方法(带token), POST下载专用方法,下载内容会返回二进制数据

Parameters:
Name Type Description
uri String

远程上传开放的Api接口路径

params Object

下载文件的专用参数,这种模式下一般存储于 Http 请求体 Body 中

options Object

Http请求头相关信息

Returns:

返回上传过后的 Promise

Type
Promise.<T>

(async, static) ajaxPush(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxPush

非安全方法,POST开放性方法,往远程地址推送数据的专用方法。

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) ajaxPut(uri, params, options) → {Promise.<T>}

「标准」Ux.ajaxPut

安全方法(带token),PUT开放性方法

Parameters:
Name Type Description
uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) ajaxResource(uri) → {Promise.<T>}

「标准」Ux.ajaxResource

非安全方法,直接从当前站点读取资源相关信息

这种模式只处理当前站点的 uri 路径,不结合 ENDPOINT 的路径执行远程请求

Parameters:
Name Type Description
uri String

资源路径

Returns:

返回最终的 Promise

Type
Promise.<T>

(async, static) ajaxUpload(uri, file, options) → {Promise.<T>}

「标准」Ux.ajaxUpload

安全方法(带token),上传专用的 Ajax 函数,文件上传专用的 Ajax 函数。

Parameters:
Name Type Description
uri String

远程上传开放的Api接口路径

file FormData

文件内容相关信息(Html中的数据)

options Object

Http请求头相关信息

Returns:

返回上传过后的 Promise

Type
Promise.<T>

(async, static) asyncAssist(assist, reference, state) → {Promise.<T>}

「标准」Ux.asyncAssist

新版的 assist 对应 ajax 解析专用函数,主要用于解析assist配置专用。

  1. 每一个assist都是一个Object配置,键会生成最终的assist数据。
  2. assist应用于很多地方的字典解析部分,如DATUM渲染,所以每一个元素的配置最终都会生成数据。
  3. 早期版本中包含了Assist / Tabular两种。
    1. Assist生成的变量名为:属性:a.x,那么变量名为:$a_a_x
    2. Tabular生成的变量名为:属性:a.x,那么变量名为:$t_a_x
  4. 最终构造的数据是DataArray类型。

响应处理器

该场景使用不多,也可忽略,直接以Assist配置为主就好。

新版的最后环节执行了响应处理器,可分组数据,可检索,可排序相关内容,这些内容作为Assist专用,详细内容参考seekData的源代码, 此处不做说明。(略)

参考配置

 "_assist": {
        "my.todo": {
            "uri": "/api/todo/search",
            "method": "POST",
            "magic": {
                "status,i": "ENUM:PENDING",
                "sigma": "PROP:app.sigma",
                "":"OPERATOR:AND"
            },
            "qr":true
        },
        "my.circle": {
            "uri": "/api/circle/search",
            "method": "POST",
            "magic": {
                "owner": "USER:key"
            },
            "qr":true
        }
    },
Parameters:
Name Type Description
assist Object

辅助数据配置信息。

reference ReactComponent

React对应组件引用。

state Object

处理的状态数据信息。

Returns:

返回Promise。

Type
Promise.<T>

(async, static) asyncData(config, params, callback, mock)

「标准」Ux.asyncData

异步读取专用函数

  • config 格式

{
    method: "get | post | put | fetch | push | delete",
    uri: "访问Ajax的路径信息",
}

callback 格式

回调函数,如果成功响应,则直接执行 callback 函数,将响应信息作为回调函数的参数。

mock 格式

该格式目前通常不使用,需要使用则直接传入 mock 完成。

{
    mock: "true | false,是否开启mock",
    data: "{} Mock的核心数据格式",
    processor: "是否执行响应格式的处理专用"
}
Parameters:
Name Type Description
config Object

异步验证配置信息

params Object

核心参数信息,传入 Ajax 的数据信息

callback function

回调函数结构,仅在成功时调用 callback,不执行失败处理

mock JObject

模拟数据格式信息

(async, static) asyncMagic(config, reference) → {Promise.<T>}

「标准」Ux.asyncMagic

新版的 magic 对应 ajax 解析专用函数,该函数用于配置信息读取,在不同配置中执行核心解析,config中的magic数据结构如:

{
    "field1": "expression1",
    "field2": "expression2",
    "...": "..."
}

解析流程可参考parseInput的API说明,除开magic数据以外剩余数据配置如:

{
    "uri": "访问Ajax的路径",
    "method": "默认为GET方法",
    "response": {
        "key": "数据提取的主键字段信,如果带有该字段,则给Array追加主键字段",
        "data": "数据字段,如果有该配置,解析响应数据。"
    }
}

响应配置是后期加的新配置,该新配置会在很多场景中使用,主要用于响应数据本身格式的转换和解析,Zero Ui中的标准格式如:

{
    "data": "Object|Array"
}

实际上response的配置是一个附加流程,如果不存在,则直接返回响应数据,如果存在则返回response的解析逻辑。

最后整理一下response的解析逻辑:

  1. 响应数据必须是一个Object类型,然后读取response[data]的数据。
  2. 如果读取的数据是Array,并且又配置了key属性,为不带key属性的元素设置key=field的数据为主键属性。
Parameters:
Name Type Description
config Object

包含了 magic 配置的异步函数。

reference ReactComponent

React对应组件引用。

Returns:

返回Promise。

Type
Promise.<T>

(async, static) asyncPromise(config, params, mock) → {Promise.<T>}

「标准」Ux.asyncPromise

无回调函数的直接执行,该函数和asyncData类似,只是是非回调模式,而是直接返回 Promise。

  • config 格式

{
    method: "get | post | put | fetch | push | delete",
    uri: "访问Ajax的路径信息",
}

mock 格式

该格式目前通常不使用,需要使用则直接传入 mock 完成。

{
    mock: "true | false,是否开启mock",
    data: "{} Mock的核心数据格式",
    processor: "是否执行响应格式的处理专用"
}
Parameters:
Name Type Description
config Object

异步验证配置信息

params Object

核心参数信息,传入 Ajax 的数据信息

mock JObject

模拟数据格式信息

Returns:

返回异步构造好的 Promise

Type
Promise.<T>

(async, static) asyncTrue(config, params, callback, mock)

「标准」Ux.asyncTrue

异步验证专用函数,不返回 Promise,直接使用 callback模式,主要在 validator 中使用,几个参数的格式如下:

config 格式

{
    method: "get | post | put | fetch | push | delete",
    uri: "访问Ajax的路径信息",
}

callback 格式

{
    success: "成功的回调函数",
    failure: "失败的回调函数"
}

如果 callback 返回值是 true,则执行 success;如果 callback 返回值是 false,则执行 failure,二选一的 callback 执行, 而这里其实不分 success / failure,仅根据成功响应过后的 true/false选择不同函数执行。

mock 格式

该格式目前通常不使用,需要使用则直接传入 mock 完成。

{
    mock: "true | false,是否开启mock",
    data: "{} Mock的核心数据格式",
    processor: "是否执行响应格式的处理专用"
}
Parameters:
Name Type Description
config Object

异步验证配置信息

params Object

核心参数信息,传入 Ajax 的数据信息

callback Object

回调函数结构

mock JObject

模拟数据格式信息

(static) messageCatch(error, callback)

「标准」Ux.messageCatch

和 Zero 框架中的数据规范配合的异常处理函数,Zero中的异常规范如下,code 为 Zero 的内部错误代码:

{
    "code": -100017,
    "message": "异常系统消息",
    "info": "可读的界面交互信息"
}
Parameters:
Name Type Description
error Object

Zero中的异常对象。

callback function

异常信息处理过后的回调函数。

(static) messageFailure(content, duration)

「标准」Ux.messageFailure

Ant Design 中的 message 响应消息调用,内部调用 message.error

  1. 如果 content 是 String,则直接呈现该消息。
  2. 如果 content 是 Object,则提取 model.failure 节点中的消息(旧代码兼容)。
Parameters:
Name Type Default Description
content String | Object

消息呈现的内容

duration Number 1.628

消息显示的时间,以秒为单位

(static) messageSuccess(content, duration)

「标准」Ux.messageSuccess

Ant Design 中的 message 响应消息调用,内部调用 message.success

  1. 如果 content 是 String,则直接呈现该消息。
  2. 如果 content 是 Object,则提取 model.success 节点中的消息(旧代码兼容)。
Parameters:
Name Type Default Description
content String | Object

消息呈现的内容

duration Number 1.628

消息显示的时间,以秒为单位

(async, static) microDelete(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microDelete

安全方法(带token),DELETE开放性方法

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) microFetch(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microFetch

非安全方法,GET开放性方法,微服务模式下读取远程请求数据的方法。

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) microGet(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microGet

安全方法(带token),GET开放性方法。

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) microPost(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microPost

安全方法(带token),POST开放性方法

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) microPush(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microPush

非安全方法,POST开放性方法,微服务模式下推送数据的专用方法。

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) microPut(service, uri, params, options) → {Promise.<T>}

「标准」Ux.microPut

安全方法(带token),PUT开放性方法

Parameters:
Name Type Description
service String

微服务模式中的服务名称

uri String

远程开放的Api接口路径

params Object

调用接口专用参数

options Object

Http请求头相关信息

Returns:

返回调用接口的 Promise

Type
Promise.<T>

(async, static) rxEdict(type, promise, responser) → {any}

「标准」Ux.rxEdict

基于 Observable 的 Redux 函数,和 Ajax 相关的响应式函数,框架内的使用代码如下:

export default {
    // 读取 tabular 的专用 redux 类型的响应式 Ajax 处理
    epicTabular: Ux.rxEdict(Types.epicTabular, I.tabular, data => Ux.rxDatum(data))
}

EmptyActionCreator 的原始创建代码如下:

import createAction from 'redux-act';
const action = createAction("REDUX//ACTION//NAME");
Parameters:
Name Type Description
type EmptyActionCreator

创建好的 Redux 中的 Action,和 redux-act 绑定

promise Promise.<T>

构造的Ajax类型的异步Promise

responser function

响应处理器,默认使用 data => data 不执行任何处理,需要转换则直接执行转换。

Returns:

返回 redux 和 rxjs 中的核心监听对象,用于执行最终输出

Type
any