---
url: /v6.2/global-js.md
---
# 全局 JS 设置

衡石系统提供了全局 JS 设置功能，用户可以通过自定义 JS 代码实现系统的个性化需求，如使用第三方统计工具对系统平台的 PV 、UV 进行监测。

除了直接操作 DOM，系统还会在运行时注入一些可复用 Hook，适合更稳定地做文案覆盖和 Data Agent 能力扩展。

## 遇到需求时先怎么选

很多客户第一次接触全局 JS 时，最容易遇到的问题不是“代码怎么写”，而是“不知道该用哪种能力”。可以先按下面这张表选型：

|需求|优先使用|为什么|常见案例|
|-|-|-|-|
|隐藏按钮、隐藏 tab、调整颜色/字体/间距|[全局 CSS](global-css.md)|这是纯视觉层改动，用 CSS 更直接，也更稳定。|隐藏“忘记密码”、隐藏“导出”按钮、隐藏部分图表类型|
|替换系统固定文案、欢迎语、提示语|`window.customI18nPostProcessor()`|按 i18n key 改文案，不需要轮询 DOM，维护成本更低。|修改 Copilot 欢迎语、统一按钮文案、统一提示语|
|页面渲染后按路由或运行状态改内容|全局 JS|需要监听路由变化、等待页面渲染、按上下文动态处理。|图表无数据时替换提示语、固定浏览器 tab 标题、按页面位置隐藏下拉选项|
|登录/登出跳转、接第三方脚本、监听页面事件|全局 JS|这类需求依赖浏览器事件或外部脚本，不属于 CSS 能力范围。|登出后跳第三方地址、SSO 租户屏蔽登录页、接百度统计|
|让 Data Agent 访问企业知识库、内部 API、搜索引擎|`window.heisenberg.createTool()`|这是给 Agent 扩展“能力”，不是改页面展示。|接内部知识库、调用工单接口、查询外部搜索服务|

## 内置 Hook

|Hook|用途|说明|
|-|-|-|
|`window.customI18nPostProcessor(value, key, options)`|按 i18n key 覆盖页面文案|在系统完成 i18n 查找后调用；不需要改动的 key 直接返回原始 `value`。|
|`window.heisenberg.createTool(tool)`|给 Data Agent 注册自定义 Tool|代码同样写在“系统设置 → 全局 JS”中，保存并刷新后在网页端 Data Agent 的 Agent 模式下生效。完整参数说明见 [Data Agent 调试](agent-tune.md)。|

## 使用场景

### 场景1：接第三方统计或监听页面事件

这一类需求通常是“页面打开后要额外执行一段逻辑”，例如：

* 接百度统计、神策、Google Analytics 等第三方统计脚本。
* 用户点击退出登录后，自动跳转到企业统一门户或其它第三方页面。
* 监听 `hs_urlchange`、资源请求、浏览器 history 变化，做路由级联动作。

示例：增加百度统计

下图示例中使用 js 代码引用了百度网站统计功能对系统进行分析，开启 JS 功能后，可以在百度系统中查看到系统的流量分析及网站分析数据。

![](/images/sys-mgt/global-js-001.png)

### 场景2：页面渲染后再修改展示内容

这一类需求通常是“页面本身没有配置项，只能在元素渲染出来之后再改”，例如：

* 图表无数据时，将默认提示语替换成业务文案。
* 将浏览器 tab 标题长期固定为客户公司名称。
* 在指定页面中隐藏某个下拉选项，例如隐藏“新建数据集”。
* 对老页面中的面包屑、标题等 DOM 内容做定制替换。

如果只是改固定文案，优先看下一节的 `window.customI18nPostProcessor`；只有在拿不到 i18n key，或需要结合页面结构一起处理时，才建议直接操作 DOM。

以下示例中，通过自定义 JS 代码将系统中图表的无数据文案进行了替换。

```js
/**
 * 替换文案
 */
var replaceTimer;
function replace(element, from, to) {
    const cont = element.textContent;
    if (cont) element.textContent = cont.replace(from, to);
};
function setTimer() {
  if (!window.location.pathname.includes('dashboard')) return;
  clearInterval(replaceTimer);
  replaceTimer = setInterval(function () {
    var elements = document.querySelectorAll('.hst__chart__no__data hr ~ span');
    var len = elements.length;
    console.log('In timer');
    while (len--) {
      replace( // [!code highlight]
        elements[len],  // [!code highlight]
        new RegExp("图表无符合条件的数据", "g"), // [!code highlight]
        "暂无数据", // [!code highlight]
      ); // [!code highlight]
    }
  }, 300);
}
document.addEventListener('hs_urlchange', setTimer);
setTimer();
```

### 场景3：按 i18n key 定制页面文案

如果只是想覆盖某个固定文案，优先使用 `window.customI18nPostProcessor`。它比定时扫描 DOM 更稳定，也更容易维护，特别适合技术经验不多、但需要快速改欢迎语和按钮文案的场景。

```js
window.customI18nPostProcessor = function (value, key, options) {
  if (key === 'copilot.recommend_more') {
    return '你好，我是衡石AI数据助理，辅助您完成数据查询工作';
  }
  return value;
};
```

常见需求：

* 统一 Copilot / Data Agent 欢迎语。
* 覆盖按钮、空态、提示语等平台内置文案。
* 做租户级品牌化，让不同客户看到自己的业务表述。

使用建议：

1. 仅对需要覆盖的 key 返回新文案，其他情况直接返回 `value`。
2. 先通过浏览器开发者工具或现有语言包确认 key，再编写定制逻辑。
3. 如果文案会随着页面结构变化而变化，不要强行用这个 Hook，改用全局 JS 处理 DOM。

### 场景4：给 Data Agent 注册自定义 Tool

在“系统设置 → 全局 JS”的 `Data Agent` 页签中，可以使用 `window.heisenberg.createTool()` 给运行时 Agent 挂载自定义工具。它适合的不是“改页面”，而是“补能力”，也就是让 Agent 能访问平台外的数据和动作。

典型需求包括：

* 查询企业内部知识库、FAQ、制度文档。
* 接内部 HTTP API 查询业务数据，例如库存、订单、工单状态。
* 调外部搜索服务或 SaaS API，补充 Agent 的实时信息来源。
* 执行轻量动作，例如创建工单、发起审批、回写备注等。

```js
if (typeof window.heisenberg?.createTool === 'function') {
  window.heisenberg.createTool({
    name: 'hello_customer',
    description: '返回租户侧自定义欢迎语',
    parameters: window.heisenberg.zod.object({}),
    execute: async () => '你好，我是客户自定义 Tool',
  });
}
```

保存并刷新后，Data Agent 即可在网页端 Agent 模式中调用该 Tool。若要接入企业知识库、搜索引擎或内部 HTTP API，可继续参考 [Data Agent 调试](agent-tune.md) 中的完整示例。

如果你的诉求只是改欢迎语、改按钮文案、隐藏某个页面元素，不需要用 `createTool()`；那属于文案或界面定制，应该优先使用 `customI18nPostProcessor`、全局 JS 或全局 CSS。

## 从失控的 JS 代码中恢复

自定义 JS 代码的能力非常强大，同时也有风险，如果您在自定义 JS 代码时，由于代码错误或其它 JS 方面的原因，很可能会导致系统无法正常访问。

为此我们提供了 URL 参数辅助从失控的 JS 代码中恢复的能力，您可以访问 `https://{host}/setting/global-js?no-global-js=true` 来禁用 JS 代码并访问配置页面，从而能够恢复系统的访问。