Web 小程序的运行库

我们提供了 Web 小程序的运行库，可以方便的调用一些方法。

您可以通过包管理工具来安装：

npm

npm install @agilebot/extension-runtime

yarn

yarn add @agilebot/extension-runtime

pnpm

pnpm add @agilebot/extension-runtime

也可以直接在浏览器中引用：

<script src="https://unpkg.com/@agilebot/extension-runtime/dist/browser.js"></script>

当您使用 <script> 标签在浏览器中直接引入运行库时，所有的导出方法会挂载在全局命名空间 gbtExtension 上。

例如，如果您需要获取当前语言，不需要使用 import，而是可以直接调用：

<script>
  gbtExtension.getLanguage().then(function (lang) {
    console.log(`当前语言为：${lang}`);
  });
</script>

多语言

当 Web 小程序在 AgileLink 中打开时，需要获取 App 当前的语言，进而切换用户 Web 小程序的语言与 App 一致。可以采用下面的方式实现该功能。

示例代码：

import { getLanguage } from '@agilebot/extension-runtime';

const currentLang = await getLanguage();
console.log(`当前的语言: ${currentLang}`);

启用快捷按键

当插件的 Web 页打开时，一些快捷按键将被禁用，如工业示教器上的物理按钮。您可以通过以下方式启用快捷按键：

import { enableShortcut } from '@agilebot/extension-runtime';

enableShortcut();

危险

如不调用此方法，可能导致的后果：

• 工业示教器锁屏后，屏幕将无法通过物理按钮来唤醒
• 只能通过长按示教器电源按钮 15 秒以上，进行强制关机并重启

显示弹框等组件

为了与 AgileLink 保持一致的风格，我们提供了一些常用函数用于展示通知消息和弹框。

rtmNotification - 通知消息

通知消息用于向用户显示简短的提示信息，支持四种类型：

import { rtmNotification } from '@agilebot/extension-runtime';

// 显示信息通知
rtmNotification.info('这是一个信息消息');
// 显示错误通知
rtmNotification.error('这是一个错误消息');
// 显示成功通知
rtmNotification.success('操作成功');
// 显示警告通知
rtmNotification.warning('这是一个警告消息');

所有通知方法都支持可选的 detail 参数，用于显示详细信息：

// 带详细信息的通知
rtmNotification.error('操作失败', '请检查您的输入并重试');
rtmNotification.info('系统提示', '您有3条新消息');

API 参考

方法	参数	返回值	说明
info(message, detail?)	message: string detail?: string	void	显示信息通知
error(message, detail?)	message: string detail?: string	void	显示错误通知
success(message, detail?)	message: string detail?: string	void	显示成功通知
warning(message, detail?)	message: string detail?: string	void	显示警告通知

rtmMessageBox - 弹框对话框

弹框对话框用于需要用户确认或输入的场景，支持三种类型：

confirm - 确认对话框

import { rtmMessageBox } from '@agilebot/extension-runtime';

// 基础用法
rtmMessageBox
  .confirm('您确定要删除吗？')
  .then(() => {
    console.log('用户确认了操作');
  })
  .catch(() => {
    console.log('用户取消了操作');
  });

// 使用 async/await
async function deleteItem() {
  try {
    await rtmMessageBox.confirm('确定删除此项吗？');
    console.log('已确认删除');
    // 执行删除操作...
  } catch {
    console.log('已取消删除');
  }
}

alert - 警告对话框

// 显示警告对话框
rtmMessageBox
  .alert('请注意：此操作不可撤销！')
  .then(() => {
    console.log('用户已阅读警告');
  });

prompt - 输入对话框

// 获取用户输入
rtmMessageBox
  .prompt('请输入您的名字：', {
    inputPlaceholder: '在此输入名字',
    inputValue: '默认名字',
    inputValidator: (value: string) => {
      if (!value) return '名字不能为空';
      if (value.length < 2) return '名字至少需要2个字符';
      return true;
    },
    inputErrorMessage: '输入无效'
  })
  .then((result) => {
    // prompt 成功时返回 { value: string, action: string }
    console.log('用户输入:', result);
  })
  .catch(() => {
    console.log('用户取消了输入');
  });

高级配置选项

所有 MessageBox 方法都支持第二个可选的 options 参数，用于自定义对话框的外观和行为：

rtmMessageBox.confirm('删除此项？', {
  title: '确认删除',
  type: 'warning',
  confirmButtonText: '确定删除',
  cancelButtonText: '取消',
  center: true,
  closeOnClickModal: false,
  closeOnPressEscape: false
});

配置选项说明

所有 MessageBox 方法都基于 Element UI 的 MessageBox 组件，支持以下配置选项：

参数	说明	类型	可选值	默认值
title	MessageBox 标题	string	—	—
message	MessageBox 消息正文内容	string / VNode	—	—
dangerouslyUseHTMLString	是否将 message 属性作为 HTML 片段处理	boolean	—	false
type	消息类型，用于显示图标	string	success / info / warning / error	—
iconClass	自定义图标的类名，会覆盖 type	string	—	—
customClass	MessageBox 的自定义类名	string	—	—
callback	若不使用 Promise，可以使用此参数指定 MessageBox 关闭后的回调	function(action, instance)	—	—
showClose	MessageBox 是否显示右上角关闭按钮	boolean	—	true
beforeClose	MessageBox 关闭前的回调，会暂停实例的关闭	function(action, instance, done)	—	—
distinguishCancelAndClose	是否将取消（点击取消按钮）与关闭（点击关闭按钮或遮罩层、按下 ESC 键）进行区分	boolean	—	false
lockScroll	是否在 MessageBox 出现时将 body 滚动锁定	boolean	—	true
showCancelButton	是否显示取消按钮	boolean	—	false（以 confirm 和 prompt 方式调用时为 true）
showConfirmButton	是否显示确定按钮	boolean	—	true
cancelButtonText	取消按钮的文本内容	string	—	取消
confirmButtonText	确定按钮的文本内容	string	—	确定
cancelButtonClass	取消按钮的自定义类名	string	—	—
confirmButtonClass	确定按钮的自定义类名	string	—	—
closeOnClickModal	是否可通过点击遮罩关闭 MessageBox	boolean	—	true（以 alert 方式调用时为 false）
closeOnPressEscape	是否可通过按下 ESC 键关闭 MessageBox	boolean	—	true（以 alert 方式调用时为 false）
closeOnHashChange	是否在 hashchange 时关闭 MessageBox	boolean	—	true
showInput	是否显示输入框	boolean	—	false（以 prompt 方式调用时为 true）
inputPlaceholder	输入框的占位符	string	—	—
inputType	输入框的类型	string	—	text
inputValue	输入框的初始文本	string	—	—
inputPattern	输入框的校验表达式	regexp	—	—
inputValidator	输入框的校验函数。可以返回布尔值或字符串，若返回一个字符串，则返回结果会被赋值给 inputErrorMessage	function	—	—
inputErrorMessage	校验未通过时的提示文本	string	—	输入的数据不合法！
center	是否居中布局	boolean	—	false
roundButton	是否使用圆角按钮	boolean	—	false

说明

• callback 参数：function (action, instance)，action 的值为 'confirm'、'cancel' 或 'close'，instance 为 MessageBox 实例
• beforeClose 参数：function (action, instance, done)，done 用于关闭 MessageBox 实例
• 更多详细信息请参考 Element UI MessageBox 文档

API 参考

方法	参数	返回值	说明
alert(message, options?)	message: string options?: ElMessageBoxOptions	Promise<MessageBoxData>	显示警告对话框
confirm(message, options?)	message: string options?: ElMessageBoxOptions	Promise<MessageBoxData>	显示确认对话框
prompt(message, options?)	message: string options?: ElMessageBoxOptions	Promise<MessageBoxData>	显示输入对话框

获取插件的状态

您可以通过以下方式获取某个插件的当前状态：

import { getExtensionState } from '@agilebot/extension-runtime';

const extension = await getExtensionState('myService');
console.log(
  `插件是否已经启用: ${extension.enabled}, 端口号：${extension.port}`
);

是否处于插件环境中

本地调试 Web 页面时，可以判断当前运行在插件环境还是本地电脑：

import { isInExtension } from '@agilebot/extension-runtime';

console.log(`当前是否处于插件环境：${isInExtension()}`);