---
order: 4
navTitle: 第三方前端库
---
# 引用第三方前端库

在 SuccApp 前端页面开发中，可以按需使用图表、UI 组件、地图、编辑器等第三方前端库。开发前应先确认目标代码运行在浏览器端，例如 `custom.ts`、页面级 `.ts` / `.js`、`.html` 或 HTML 型 `.ftl` 页面；服务端 `.action.ts` 脚本不能使用浏览器 DOM、页面资源或前端 importmap。

## 选择引用方式{#choose}

引用第三方前端库时，按下面顺序判断：

1. 优先使用 SuccApp 前端运行时已经提供的依赖。内置依赖由系统 importmap 管理，版本和资源路径与当前服务器匹配。
2. 内置依赖不能满足需求时，再把浏览器可直接运行的第三方发行文件放到当前页面目录或子目录中，用相对路径引用。
3. 不要在 SuccApp 元数据工作区中提交 `node_modules/`，也不要直接引用本机开发目录、构建缓存或 `/dist/node_modules/**` 这类运行时产物路径。

可用内置依赖清单见 [`succ-frontend-frameworks.json`](../../../../dev-resources/script/frontend/succ-frontend-frameworks.json)。执行 `succapp workspace init --scope agent-docs` 后，这个文件也会随官方离线文档 skill 同步到当前工作区，供 AI Agent 和开发者本地查看。

## 使用内置依赖{#builtin}

查看 `succ-frontend-frameworks.json` 时，重点确认这些字段：

| 字段 | 说明 |
| --- | --- |
| `status` | 依赖状态。新功能优先选择 `recommended`；`available` 表示可用；`legacy` 只适合兼容旧代码。 |
| `imports.js` | JavaScript / TypeScript 中可使用的 import specifier。 |
| `imports.css` | 需要同步引入的 CSS 资源 specifier。 |
| `dependsOn` | 依赖的其它前端库。 |
| `imports.prefixes` | worker、字体、子资源等可用的资源前缀。 |
| `notes` | 使用限制、推荐场景和额外说明。 |

常用推荐依赖包括：

| 依赖 | 适合场景 | JS specifier | CSS specifier |
| --- | --- | --- | --- |
| `echarts` | 常规图表。 | `echarts`、`echarts/dist/echarts.esm` | - |
| `ant-design-vue` | Vue 3 表单、表格、弹窗和布局。 | `ant-design-vue` | `ant-design-vue/dist/reset.css` |
| `antd` | React 表单、表格、弹窗和布局。 | `antd` | - |
| `react` | React 组件化界面。 | `react`、`react-dom`、`react-dom/client` | - |
| `three` | WebGL 3D 场景。 | `three`、`three/build/three.module` | - |
| `succ-monaco-editor` | 代码编辑器、脚本编辑器和语法高亮输入区。 | `succ-monaco-editor` | `succ-monaco-editor/min/vs/editor/editor.main.css` |

在支持 importmap 的前端脚本中，使用清单里的 specifier 引入：

```ts
import * as echarts from 'echarts';

export function initChart(container: HTMLElement) {
	const chart = echarts.init(container);
	chart.setOption({
		xAxis: {
			type: 'category',
			data: ['一月', '二月', '三月']
		},
		yAxis: {
			type: 'value'
		},
		series: [
			{
				type: 'bar',
				data: [120, 200, 150]
			}
		]
	});
}
```

如果依赖需要 CSS，也按清单记录的 CSS specifier 引入。不同页面类型的资源加载方式可能不同，写法应沿用当前页面或相邻页面的现有模式。

## 在 HTML/FTL 页面中加载脚本{#html-ftl}

`.html` 和 HTML 型 `.ftl` 页面可以继续使用系统注入的前端运行环境加载同目录脚本。页面脚本内部再按需要 import 内置依赖。

```html
<div id="chart" style="height: 320px;"></div>

<script type="text/javascript">
	require(["sys/sys"], function(sys) {
		sys.ready("./index").then(function(page) {
			page.initChart(document.getElementById("chart"));
		});
	});
</script>
```

FTL 页面中已有 `<@html>`、`<@head>`、`<@body>` 等指令时，按相邻文件的写法组织页面，不要改成独立 HTML 骨架。`<@useScript>` 用于服务端模板渲染阶段引入 `.action.ts`，不等同于浏览器端前端库加载。

## 自带第三方文件{#vendor}

如果内置依赖清单中没有合适的库，可以把第三方前端库的浏览器发行文件放到当前页面目录或子目录中。推荐放在 `vendor/` 下，和页面脚本、样式保持在同一个元数据目录范围内：

```text
demo-page/
├── index.ftl
├── scripts/
│   └── page.js
├── styles/
│   └── page.css
└── vendor/
    └── some-lib/
        ├── some-lib.min.js
        ├── some-lib.min.css
        └── LICENSE
```

在页面中用相对路径引用：

```html
<link rel="stylesheet" href="./vendor/some-lib/some-lib.min.css">
<link rel="stylesheet" href="./styles/page.css">
<script src="./vendor/some-lib/some-lib.min.js"></script>
<script src="./scripts/page.js"></script>
```

选择第三方文件时，优先使用 UMD、IIFE 或明确支持浏览器 `<script>` / ESM 的发行文件。不要直接拷贝只面向 Node.js、Webpack、Vite 等构建器的源码入口。

## 更多说明{#more}

- 前端脚本只处理当前页面交互，不建议把服务端查询、权限判断或大批量数据加工逻辑搬到浏览器端。
- 页面已有 class 命名、CSS 变量和响应式断点时，优先沿用现有样式体系。
- 需要开发 `.html` 或 `.ftl` 页面时，先阅读 [HTML 和 FTL 自定义页面](./html-ftl-pages.md)。
- 需要查前端脚本接口时，先从[前端脚本 API 索引](./api-index.md)进入。