JS-API

本文档主要介绍盘古平台在事件 JS 面板中可以直接调用的 API 及其使用方法，每一个 API 都会配备一个示例用于展示 API 的具体使用方式，在示例中，我们都会通过以下函数结构来模拟动作面板的真实使用场景。

function action(ctx, parmas) {
  ...
}

全局变量 API

获取变量 state

#内置

该方法用于获取在参数面板中定义的参数。

function action(ctx) {
  console.log(ctx.state);
}

修改变量 setState

#内置

参数类型为对象类型，对象属性名为变量名称，属性值是修改的数据。

function action(ctx) {
  ctx.setState({
    form: {
      name: "老高",
      age: 18
    }
  })
}

调用api loadApi

#内置

该方法用于调用API面板中定义的api接口，该方法有两个参数，分别为api名称和api需要传递的参数。

function action(ctx) {
  ctx.loadApi("dp1", { name: "老高" }).then(res => {
    console.log(res);  
  })
}

获取组件的属性值 getProp

#内置

用于获取组件配置的属性值，该方法有两个参数，分别为组件key和属性名称。

function action(ctx, params) {
  ctx.getProp('1711501379446', 'props');
}

主动触发组件的事件 triggerEvent

#内置

用于主动触发组件的事件，该方法有两个参数，分别为组件key和事件名称。

function action(ctx, params) {
  ctx.triggerEvent('1711501379446', 'focus');
}

消息提示

全局反馈 message

#内置

由用户的操作触发的轻量级全局反馈。

可通过 ctx.message(config) 进行反馈提示，全局提示有 4 种不同的类型，分别为：info（信息）, success（成功）, warning（警告）, error（错误）。

config参数定义如下所示：

参数名称	描述	类型	默认值
closable	是否显示关闭按钮	boolean	false
content	内容	string	-
duration	消息显示的持续时间	number	-

function action(ctx) {
	ctx.message.success({ content: "提示内容"});
}

确认提示 confirm

#内置

点击元素，弹出确认框。

可通过 ctx.confirm(config) 进行确认提示，全局提示有 4 种不同的类型，分别为：info（信息）, success（成功）, warning（警告）, error（错误）。

config参数定义如下所示：

参数名称	描述	类型	默认值
title	标题	string	-
content	内容	string	-
closable	是否显示关闭按钮	boolean	false
okText	确认按钮文案	string	-
cancelText	取消按钮文案	string	-
hideCancel	是否隐藏取消按钮	boolean	true
width	弹框宽度	string | number	-
top	对话框的距离顶部的高度，居中显示开启的情况下不生效	string | number	-
onOk	点击确认回调	function	-
onCancel	点击取消回调	function	-

function action(ctx) {
	ctx.confirm.info({ title: "确认标题", content: "确认内容" });
}

表单方法

校验表单值 validate

#内置

用于校验表单数据，参数为表单容器的key和回调函数，回调函数有两个参数，分别为是否通过校验和表单数据。

function action(ctx) {
	ctx.validate("1658997822617", function(res, data) {
		console.log(res, data);
	})
}

清除校验结果 clearValidate

#内置

用于清除校验结果，参数为表单容器的key。

function action(ctx) {
	ctx.clearValidate("1658997822617")
}

获取表单值 getValue

#内置

参数为表单容器的key。该方法可用于表单容器表单项未绑定变量的场景中。

function action(ctx) {
	console.log(ctx.getValue("1658997822617"))
}

设置表单值 setValue

#内置

参数为表单容器的key和需要赋值的表单数据对象。该方法可用于表单容器表单项未绑定变量的场景中。

function action(ctx) {
	ctx.setValue("1658997822617", {
		name: "老高",
		age: 18
	})
}

其它

刷新表格 fetchTableData

#内置

参数为表格容器的key和表格请求数据的参数，可以不传就按当前搜索条件和页码进行刷新。该方法可用于表格为api数据且需要刷新场景中。

function action(ctx) {
	ctx.fetchTableData("1658997822617",{
		pageSize: 10,
		pageNum: 1,
		...param
	})
}

全局数据

获取用户信息 getUserInfo()

#盘古3 #盘古2

获取登录人员信息对象，包含用户账号、用户名等。

function action(ctx) {
  const userObj = ctx.injected.getUserInfo();
}

获取请求头信息 getHttpHeaders()

#盘古3 #盘古2

获取 token、Authorization、current_id、default_language 等 header 信息。

function action(ctx) {
  const headers = ctx.injected.getHttpHeaders();
}

获取语言种类 getLangList()

#盘古3

获取当前系统的语言种类列表。

function action(ctx) {
  const langList = ctx.injected.getLangList();
}

---

全局动作

路由跳转 navigateTo(path, params)

#盘古3 #盘古2

跳转到指定路由路径。

ctx.injected.navigateTo("/user/list", { id: 1 });

• path: 路由路径
• params: 路由参数

路由回退 navigateBack()

#盘古2

返回上一个路由。

ctx.injected.navigateBack();

路由前进/后退 navigateGo(n)

#盘古2

前进或后退指定层级（正数前进，负数后退）。

ctx.injected.navigateGo(-1);

关闭当前标签页 closeCurrentTab()

#盘古3 #盘古2

仅用于 PC 端。

ctx.injected.closeCurrentTab();

关闭指定标签页 closeTargetTab(tabKey)

#盘古3 #盘古2

关闭指定标签页（tabKey 通常为路由路径）。

ctx.injected.closeTargetTab("user/list");

关闭所有标签页 (仅用于 pc 端) closeAllTab()

#盘古3 #盘古2

关闭所有标签页（PC 端）。

ctx.injected.closeAllTab();

设置Store全局参数 setStoreParam

#盘古2

该方法用于将数据存储到全局store中，其他页面也可获取到

function action(ctx) {
  ctx.injected.setStoreParam(params);
}
// 示例
ctx.injected.setStoreParam({code: "xxx"})

params 数据类型为对象，key为存储的字段名，value为存储的数据;

获取Store全局参数 getStoreParam(paramsName)

#盘古2

该方法用于获取存储在全局store中的参数

function action(ctx) {
  ctx.injected.getStoreParam(paramsName);
}
// 示例
ctx.injected.getStoreParam("code")

paramsName 数据类型为字符串，为获取的字段名;

监听事件 (仅用于pc) onEvent(eventName, callback)

#盘古3 #盘古2

监听指定事件。

ctx.injected.onEvent("refreshData", (data) => {
  console.log("Refresh event triggered", data);
});

触发事件 (仅用于pc) emitEvent(eventName, params)

#盘古3 #盘古2

触发指定事件并传递参数。

ctx.injected.emitEvent("refreshData", { force: true });

取消监听事件 (仅用于pc) offEvent(eventName)

#盘古3 #盘古2

取消对指定事件的监听。

ctx.injected.offEvent("refreshData");

获取环境变量 getNodeEnv(nodeEnv)

#盘古2

该方法用于获取当前环境变量

function action(ctx){
  ctx.injected.getNodeEnv(nodeEnv);
}
//示例
ctx.injected.getNodeEnv("Node_Env");

nodeEnv数据类型为字符串，为当前环境变量的属性名

---

工具方法

获取 URL 参数 getUrlParam(name)

#盘古3 #盘古2

获取当前 URL 中指定参数的值。

const id = ctx.injected.getUrlParam("id");

日期格式化 dateFormat(date, formatStr)

#盘古3 #盘古2

格式化日期字符串、时间戳或 Date 对象。

const formatted = ctx.injected.dateFormat(new Date(), "YYYY-MM-DD");

• date: 可为 Date、string、number，null 表示当前时间
• formatStr: 格式字符串，如 "YYYY-MM-DD HH:mm:ss"

流数据下载 download(blobData, fileName)

#盘古3 #盘古2

将接口返回的 blob 数据下载为文件。

ctx.injected.download(blob, "用户列表.xlsx");

• blobData: 接口返回的 Blob 数据
• fileName: 下载的文件名

将列表数据转换为 Excel 下载(仅用于 pc 端) exportToExcel

#盘古3 #盘古2

该方法用于处理列表数据导出为 excel 文件。该方法仅用于数据转换不进行接口处理，用户自行从接口中获取列表数据并处理，将处理好的列表数据传入此方法中导出为 Excel。

function action(ctx) {
  ctx.injected.exportToExcel(option);
}

option 为对象参数如下：

{
  data: Array,  // 要导出为Excel的列表数据
  columns: ColumnConfig, // Excel列名配置
  fileName: String // 导出的文件名
}
ColumnConfig:
{
  name: String, // 数据字段名称
  title: String // 数据字段标题
}

示例如下：

ctx.injected.exportToExcel({
  data: [
    {
      loginName: "xxx",
      userName: "yyy",
    },
  ],
  columns: [
    {
      name: "userName",
      title: "用户名",
    },
    {
      name: "loginName",
      title: "账号",
    },
  ],
  fileName: "用户信息",
});

注册国际化数据 registerMessage(intlValues)

#盘古3

注册当前系统的国际化数据。

ctx.injected.registerMessage([
  { LANGUAGE_KEY: "intlKey", zh_CN: "intlValue1", en_GB: "intlValue2" },
]);

• intlValues: 数组，包含国际化 LANGUAGE_KEY 和 各语言文案

国际化渲染 showAlias(intlKey)

#盘古3

根据国际化 key 获取对应语言的值。

const label = ctx.injected.showAlias("user.name");

• intlKey: 国际化 key，如 "user.name"

设置国际化数据 setLocalMessage(intlValues)

#盘古3

设置当前系统的国际化数据。

ctx.injected.setLocalMessage([
  { languageKey: "user.name", displayName: "用户名" },
]);

• intlValues: 数组，包含 languageKey 和 displayName

---

设置 Cookie setCookie(name, value, expires)

#盘古2

ctx.injected.setCookie("token", "abc123", 7);

• name: Cookie 名
• value: 值
• expires: 可为数字（天数）或 Date（过期时间）

获取 Cookie getCookie(name)

#盘古2

const token = ctx.injected.getCookie("token");

全局提示(仅用于移动端) showToast

#盘古2

该方法用于全局提示信息

function action(ctx) {
  ctx.injected.showToast({
    type: "text" | "loading" | "success" | "fail", // 提示类型
    message: "内容", // 提示内容
    duration: 2000, // 展示时长(ms)，值为 0 时，toast 不会消失
  });
}

关闭全局提示(仅用于移动端) closeToast

#盘古2

该方法用于关闭全局提示信息

function action(ctx) {
  ctx.injected.closeToast();
}