---
navTitle: 系统提示页定制
---
# 系统提示页定制

<!--
维护说明：状态页定制路径来自 bi/com.succez.bi/src/main/java/com/succez/metadata/ActionServerStatus.java。
当前 403/404/500/maintenance 先查 /sysdata/public/{status}.action.ts，再查 /sysdata/public/{status}.ftl。
浏览器兼容页单独使用 /sysdata/public/incompatible-browser.ftl。
-->

系统提示页用于在浏览器不兼容、用户无权限、页面不存在、服务器异常或系统维护时向用户展示状态说明。SuccApp 支持在 `/sysdata/public/` 下放置约定文件，覆盖系统默认提示页。

## 可定制页面{#pages}

| 页面 | 默认访问入口 | 定制文件 |
| --- | --- | --- |
| 浏览器兼容提示页 | `/serverstatus/incompatible-browser` | `/sysdata/public/incompatible-browser.ftl` |
| 403 页面 | `/serverstatus/403` | `/sysdata/public/403.action.ts` 或 `/sysdata/public/403.ftl` |
| 404 页面 | `/serverstatus/404` | `/sysdata/public/404.action.ts` 或 `/sysdata/public/404.ftl` |
| 500 页面 | `/serverstatus/500` | `/sysdata/public/500.action.ts` 或 `/sysdata/public/500.ftl` |
| 维护提示页 | 系统维护状态自动进入 | `/sysdata/public/maintenance.action.ts` 或 `/sysdata/public/maintenance.ftl` |

其中 403、404、500 和维护提示页的查找顺序是：先查找 `.action.ts`，再查找 `.ftl`，都不存在时显示系统默认页面。

## 浏览器兼容提示页{#incompatible-browser}

SuccApp 需要较新的浏览器能力。用户使用低版本浏览器访问系统时，会进入浏览器兼容提示页：

![IE8 上的兼容性提示](./images/2020-03-25-13-49-18.png)

将自定义模板保存为 `/sysdata/public/incompatible-browser.ftl` 后，系统会优先展示该模板：

![incompatible-browser.ftl](./images/2020-03-25-14-07-49.png)

最终效果示例：

![个性化的提示页面](./images/2020-03-25-14-05-02.png)

### QQ 链接卡片优化{#qq-share-card}

通过 QQ 发送系统链接时，QQ 服务器可能使用低版本浏览器抓取页面信息。如果系统返回浏览器兼容提示页，链接卡片可能显示错误信息。

![QQ 链接卡片](./images/2020-08-13-21-53-19.png)

可以在兼容提示页中加入页面名称和描述：

```html
<meta itemprop="name" content="SuccApp">
<meta name="description" itemprop="description" content="SuccApp">
```

如果没有定制兼容提示页，可以在**系统设置** > **基本设置**中设置正确的**系统名称**，让链接卡片尽量显示友好的系统名称。

## 403 页面{#403}

403 页面用于提示当前登录用户没有权限访问当前页面。默认页面示例：

![默认 403 页面](./images/2020-11-13-10-01-59.png)

如果只需要替换展示内容，创建 `/sysdata/public/403.ftl`。如果需要按业务逻辑决定页面跳转或返回内容，创建 `/sysdata/public/403.action.ts`。

## 404 页面{#404}

404 页面用于提示当前访问 URL 在系统中不存在。默认页面示例：

![默认 404 页面](./images/2020-11-13-10-01-01.png)

如果需要在某些约定 URL 不存在时返回业务页面，可以使用 `/sysdata/public/404.action.ts`：

```javascript
"use strict";

exports.execute = function(request, response, params) {
    // 根据访问路径决定是否转到业务页面。
    let uri = request.getRequestURI();
    if (uri.indexOf('/code/') !== -1) {
        // 清除原本的 404 状态，避免浏览器和代理仍按错误响应处理。
        response.reset();
        return "forward:/BZLL/app/home.app/public/viewsource.spg";
    }
    return "forward:/serverstatus/default-status-page/404";
}
```

## 500 页面{#500}

500 页面用于提示服务器处理请求时发生异常。默认页面示例：

![默认 500 页面](./images/2021-11-26-16-34.png)

如果需要按业务逻辑处理异常页，可以使用 `/sysdata/public/500.action.ts`：

```javascript
"use strict";

exports.execute = function(request, response, params) {
    // 根据访问路径决定是否转到业务页面。
    let uri = request.getRequestURI();
    if (uri.indexOf('/code/') !== -1) {
        // 清除原本的 500 状态，避免浏览器和代理仍按错误响应处理。
        response.reset();
        return "forward:/BZLL/app/home.app/public/viewsource.spg";
    }
    return "forward:/serverstatus/default-status-page/500";
}
```

## 维护提示页{#maintenance}

系统处于维护状态、注册码过期且普通用户访问系统时，会展示维护提示页。需要替换维护页内容时，创建 `/sysdata/public/maintenance.ftl`；需要按用户、路径或业务状态控制展示内容时，创建 `/sysdata/public/maintenance.action.ts`。

维护页运行时会带有系统名称和维护说明。自定义模板中如果需要读取这些变量，应先在测试环境验证实际渲染效果。

## 默认页面入口{#default}

脚本中可以通过 `/serverstatus/default-status-page/{status}` 转到系统默认页面。例如：

```text
/serverstatus/default-status-page/404
/serverstatus/default-status-page/500
```

自定义 `.action.ts` 只处理部分业务场景时，可以把其他场景转回默认页面。