Web SDK

超链接

超链接用于实现电子表格内部工作表、单元格，以及外部网页、电子邮件地址等内容的快速跳转与访问。

预览

预设模式

安装

Shell
pnpm add @univerjs/preset-sheets-hyper-link

使用

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsHyperLinkPreset } from '@univerjs/preset-sheets-hyper-link'import UniverPresetSheetsHyperLinkZhCN from '@univerjs/preset-sheets-hyper-link/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-hyper-link/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsHyperLinkZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsHyperLinkPreset(),   ],})

预设与配置

TypeScript
UniverSheetsHyperLinkPreset({  // 自定义外部链接跳转方式  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完整的配置项参考 IUniverSheetsHyperLinkPresetConfig。

插件模式

安装

Shell
pnpm add @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui

使用

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link'import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui'import SheetsHyperLinkUIZhCN from '@univerjs/sheets-hyper-link-ui/locale/zh-CN'import '@univerjs/sheets-hyper-link-ui/lib/index.css'import '@univerjs/sheets-hyper-link/facade'import '@univerjs/sheets-hyper-link-ui/facade'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsHyperLinkUIZhCN,     ),  },})univer.registerPlugin(UniverSheetsHyperLinkPlugin)univer.registerPlugin(UniverSheetsHyperLinkUIPlugin)

插件与配置

TypeScript
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {  // 自定义外部链接跳转方式  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完整的配置项参考 IUniverSheetsHyperLinkUIConfig。

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

TypeScript
import '@univerjs/sheets-hyper-link/facade'

navigateToSheetHyperlink api 在 ui 插件中，需引入：

TypeScript
import '@univerjs/sheets-hyper-link-ui/facade'

创建超链接

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// 创建一个指向 Univer 的超链接在 A1 单元格const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('//', 'Univer')// 创建一个指向 Sheet1 的 B2:D4 区域的超链接在 A2 单元格const fRange2 = fWorksheet.getRange('A2')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')// 创建一个指向另一个工作表区域的超链接在 A3 单元格const anotherSheet = fWorkbook.getSheetByName('Another Sheet')if (anotherSheet) {  const fRange3 = fWorksheet.getRange('A3')  const anotherSheetUrl = anotherSheet.getUrl()  await fRange3.setHyperLink(anotherSheetUrl, 'Link to Another Sheet')}// 创建一个指向定义名称的超链接在 A4 单元格const fRange4 = fWorksheet.getRange('A4')const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')

获取/更新/取消超链接

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// 获取 A1:D10 区域内的所有超链接const fRange = fWorksheet.getRange('A1:D10')const hyperlinks = fRange.getHyperLinks()console.log(hyperlinks)// 更新 A1 单元格上的超链接const cellA1 = fWorksheet.getRange('A1')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await cellA1.updateHyperLink(rangeUrl, 'Link to B2:D4')// 取消 A1:D10 区域内的所有超链接fRange.cancelHyperLink()// 或者取消 A1:D10 区域内的特定超链接if (hyperlinks.length > 1) {  fRange.cancelHyperLink(hyperlinks[1])}

构建/解析/跳转

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const sheets = fWorkbook.getSheets()// 构建一个指向第一个工作表的 F6 单元格的超链接 urlconst hyperlinkUrl = sheets[0].getRange('F6').getUrl()// 解析超链接const hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlinkUrl)console.log(hyperlinkInfo)// 切换到第二个工作表fWorkbook.setActiveSheet(sheets[1])console.log(fWorkbook.getActiveSheet().getSheetName())// 3 秒后跳转到超链接await new Promise(resolve => setTimeout(resolve, 3000))fWorkbook.navigateToSheetHyperlink(hyperlinkUrl)console.log(fWorkbook.getActiveSheet().getSheetName())

事件监听

完整事件类型定义，请查看 Events。

通过 univerAPI.addEvent() 可以监听超链接相关的事件：

链接添加事件

univerAPI.Event.BeforeSheetLinkAdd: 添加链接前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (params) => {  const { workbook, worksheet, row, col, link } = params  // 取消添加链接操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

链接更新事件

univerAPI.Event.BeforeSheetLinkUpdate: 更新链接前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (params) => {  const { workbook, worksheet, row, column, id, payload } = params  // 取消更新链接操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

链接删除事件

univerAPI.Event.BeforeSheetLinkCancel: 取消链接前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (params) => {  const { workbook, worksheet, row, column, id } = params  // 取消取消链接操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

每个事件都包含以下通用参数：

  • workbook: 当前工作簿实例
  • worksheet: 当前工作表实例
  • row: 包含链接的单元格行索引
  • column: 包含链接的单元格列索引

特殊参数：

  • BeforeSheetLinkAdd 事件包含 link: 即将添加的链接
  • BeforeSheetLinkUpdate 事件包含：
    • id: 链接标识符
    • payload: 新的链接数据
  • BeforeSheetLinkCancel 事件包含 id: 即将删除的链接标识符

所有事件回调函数都可以使用 params.cancel = true 来阻止对应的操作。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.