文档首页/ Astro轻应用 AstroZero/ API参考/ 预置API/ 高级页面中预置的API
更新时间:2024-06-28 GMT+08:00
分享

高级页面中预置的API

在开发高级页面过程中,系统为页面组件和桥接器提供了一些预置API。

组件

在开发自定义组件时,需要定义“组件名.js”文件,该文件为组件逻辑文件,是整个组件的渲染核心JS,在组件编辑状态和页面最终的发布运行态都会被加载执行。主要包含的预置API说明,请参见表1

表1 组件名.js中预置API说明

分类

API及说明

组件实例预置API

  • init方法:主要包含组件渲染需要初始化数据的入口函数。
  • render方法:负责整个组件渲染的业务逻辑方法。
  • getConnectorProperties:获取桥接器属性的配置值。
  • getConnectorInstanceByName:通过桥接器的变量名称获取桥接器实例,其中“APIConnector”类型为String,表示桥接器的变量名称。
  • ConnectorIns.process(renderCbk, errCbk):通过桥接器实例调用process函数,主要作用为发起调用服务的请求和处理返回结果信息。
    • 在通过process函数发起请求前,需设置桥接器实例的requestParams属性为请求的参数,例如:ConnectorIns.requestParams = param;
    • 参数renderCbk,类型为Function,当返回结果信息后调用该函数,用于处理返回信息。
    • 参数errCbk,类型为Function,调用该函数来处理错误。
  • ConnectorIns.query(param):通过桥接器实例调用query函数,主要作用为发起调用服务的请求和处理返回结果信息,参数说明如下:
    • param:请求参数。
    • 其返回结果为Promise对象。
  • getProperties:用于返回该组件的自定义属性值。

    开发Widget时,可以给组件自定义属性,在开发界面可对这些属性进行配置,通过getProperties方法可返回自定义属性值。例如,var properties = thisObj.getProperties()。

  • getContainer:用于返回渲染该组件的容器dom节点。

    代码示例:var elem = thisObj.getContainer (),然后通过jquery去查询组件中某个dom节点时,可通过$("#id", elem)的方式来获取。

  • getWidgetBasePath:用于返回该组件静态资源的根路径。

    例如,某个组件的静态资源路径为“https://10.10.10.1:12900/default/0000000000NABzEjpNIH/assets/bundle/widget/172a6056501-a6f8ce1f-2ed9-4a9a-b883-251aaac14e0a/v1591923270914/test0609.js”,执行thisObj.getWidgetBasePath()返回“https://10.10.10.1:12900/default/0000000000NABzEjpNIH/assets/bundle/widget/172a6056501-a6f8ce1f-2ed9-4a9a-b883-251aaac14e0a/v1591923270914” 。

  • getMessages:返回该组件国际化配置文件中定义的国际化文件内容,需要配置vue和vueI18n使用。

    例如,开发组件时定义了messages-en.json和messages-zh.json国际化文件。thisObj.getMessages()返回的就是这两个文件中定义的国际化内容。

  • hideWidget:隐藏该组件的dom结构,预览时调用该方法可以隐藏Widget。

    例如,执行thisObj.hideWidget()方法,隐藏该组件的dom结构。

  • showWidget:显示该组件的dom结构,预览时调用该方法可以展示Widget。

    例如,执行thisObj.showWidget()方法,显示该组件的dom结构。

  • SITE_ROOT_PATH:为AstroZero预置的参数,用于获取当前站点URL地址的根路径。站点和应用是一对一的关系,当创建应用时,系统默认会创建并分配一个站点。

    假如,某个页面的URL地址为“https://10.10.10.1:12900/magno/render/cool__app_0000000000NABzEjpNIH/page1”,则使用SITE_ROOT_PATH获取的根路径为“/magno/render/cool__app_0000000000NABzEjpNIH”。

  • triggerEvent:用于触发事件,参数说明如下:
    • eventName:指定触发的事件名称。
    • {}:为事件触发时传递的参数赋值,例如{param: value}。

Studio对象预置API

  • Studio.registerWidget:用来定义组件。
  • Studio.registerConnector:用来定义桥接器。
  • Studio.registerEvents:用于注册事件,只有通过此API注册后的事件才会在组件的事件列表中展现。
    • thisObj:当前组件实例对象,指为该组件注册事件。
    • "eventName":事件名称,应该与触发事件API中的第一个参数保持一致。
    • "Event Label":事件标签名,在事件列表中展示的事件标题。
    • []:定义该事件触发时传递的参数模型,例如[{"name": "param"}] 。
  • Studio.registerAction:用来注册动作。只有通过此API注册后的事件,才会在组件的动作列表中展现。
    • thisObj:当前组件实例对象,指为该组件注册动作。
    • actionName:动作名称。
    • Action Label:动作标签名,在动作列表中展示的动作标题。
    • []:事件触发时传入的参数。
    • $.proxy(this.receiveActionCbk, this):该动作的回调函数,在回调函数中定义该动作的执行逻辑。
    • []:此参数在开发过程中置为空数组即可。
  • Studio.registerRouter:用来定义路由。
  • Studio.inReader:判断当前页面状态是开发态或预览态。其中,“true”表示在预览态(即运行态),“false”表示在开发态。
  • StudioToolkit.getCatalogProperties():用于获取当前站点的元数据。

magno对象预置API

savePropertiesForWidget(props):用于在开发态中保存当前组件的高级设置属性信息,参数为要设置的相关属性集对象。

参数props示例:

{
  "prop1": "value1",
  "prop2": ""value2"
}

HttpUtils工具类预置API

AstroZero平台内置了HttpUtils工具类,预置API如下:

  • HttpUtils.getCookie:用于获取某个cookie的值。

    代码示例:HttpUtils.getCookie()

  • HttpUtils.setCookie:用于设置cookie的值。

    代码示例:HttpUtils.setCookie("key","value")

  • HttpUtils.getI18n:返回一个Vue18n的实例,配合Vue和VueI18n使用。该Vue18n实例可以在new一个Vue实例时赋值为i18n参数。

    代码示例:HttpUtils.getI18n({locale: HttpUtils.getLocale(), messages: thisObj.getMessages()})

  • HttpUtils.getCsrfToken:通过ajax的方式去调用平台的接口时使用。如果使用平台桥接器的方式,平台会自动在请求header中,添加csrf-token头。
    HttpUtils.getCsrfToken(function(csrfToken) {
      $.ajax({
        ….
        headers: {
          CSRF-Token: csrfToken
        },
      })
    })
  • HttpUtils.refreshToken:用于手动刷新页面的accesstoken,通常用在执行退出逻辑时,执行该方法刷新页面的access token。
  • HttpUtils.getUrlParam:用于获取查询字符串中的参数。

    例如,某个页面的URL为“https://10.10.10.1:12900/magno/render/cool__app_0000000000NABzEjpNIH/page1?param=1”, 通过执行HttpUtils.getUrlParam("param")返回该参数的值“1”。

  • HttpUtils.getLocalStorage:用于获取某个localStorage的值。

    代码示例:HttpUtils.getLocalStorage("key")

  • HttpUtils.setLocalStorage:用于设置某个localStorage的值。

    代码示例:HttpUtils.setLocalStorage("key","value")

桥接器

用户不需要自定义开发桥接器,使用系统预置的“通用AstroZero API数据桥接器”即可调用应用的服务接口。AstroZero也支持用户自定义桥接器,并上传到平台中,提供给页面组件使用。在桥接器中,AstroZero对外开放的自定义部分主要执行流程如图1所示:

图1 桥接器执行流程图

桥接器中主要的自定义函数为constructUrltransform,您可以按需求封装上述函数,以此实现不同功能的桥接器。自定义桥接器中常用的API如表2所示,在经典版应用设计器左侧列表中,单击,选择“高级页面 > 桥接器模板”,下载模板解压后可查看API调用示例。

表2 自定义桥接器中常用的API列表

API名称

详细说明

init()

桥接器初始化函数,在该函数中主要实现为对setInputParams函数的调用,设置桥接器的自定义配置项。

setUrl(url)

在constructUrl(params)中必须要调用该API,用于设置该桥接器请求的URL。

setLoadMethod(type, dataType, callback, callbackName, ajaxOptions)

在constructUrl(params)中调用该API,用于对请求constructUrl(params)的参数做处理。该API中参数说明如下:

  • type:表示请求方式,支持POST、GET、PUT和DELETE。默认值为GET。
  • dataType:预期服务器返回的数据类型。一般取值为json,表示返回JSON格式的数据。
  • callback:dataType取值为“jsonp”的场景使用,表示在一个jsonp请求中重写回调函数的名字。
  • callbackName:dataType取值为“jsonp”的场景使用,表示为jsonp请求指定一个回调函数名。
  • ajaxOptions:AJAX请求设置,示例如下:
    {
    	data: JSON.stringify(inputParamsObj.input),
    	contentType: "text/html;charset=utf-8",
    	beforeSend: function(xhr) {
    		xhr.setRequestHeader("bass-method", "post");
    		xhr.setRequestHeader("Content-Type", "application/json");
    	}
    }

constructUrl(params)

在发起请求前执行该API,该API用于构造请求的URL。其中,“params”为请求参数。

使用说明:在该API中必须要调用setUrl(url)对URL赋值,还可调用setLoadMethod对请求参数做处理,该操作为可选。

transform(resultData, renderCbk)

处理请求响应,参数说明如下:

  • resultData:请求的响应结果。
  • renderCbk:组件中定义的当请求获取响应信息后的回调函数。

getUrl()

获取该桥接器请求的URL。

setInputParams([{},...,{}])

设置桥接器的自定义配置项。

  • type:配置项的类型,常用类型包含“text”、“option”。
  • name:配置项的变量名称。
  • label:配置项的显示标题。
  • value:配置项的默认值。
  • validation:配置项的验证规则。

桥接器自定义配置项代码示例:

this.setInputParams([
    {
        "type": "select",
        "name": "requestMethod",
        "label": JSON.stringify({zh_CN: "请求方法", en_US: "Request Method"}),
        "options": [
            {
                "label": "post",
                "value": "post",
                "selected": "true"
            },
            {
                "label": "get",
                "value": "get"
            },
            {
                "label": "put",
                "value": "put"
            },
            {
                "label": "delete",
                "value": "delete"
            }],
        "validation": {
            "rules": {}
        }
    },
    {
        "type": "text",
        "name": "prefix",
        "label": JSON.stringify({zh_CN: "前缀", en_US: "prefix"}),
        "value": "",
        "validation": {
            "rules": {}
        }
    }]);

getInputParams()

获取桥接器的自定义配置项的设置值。

相关文档