Web SDK

超連結

超連結用於實現電子表格內部工作表、單元格，以及外部網頁、電子郵件地址等內容的快速跳轉與訪問。

外掛模式

安裝

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 SheetsHyperLinkUIZhTW from '@univerjs/sheets-hyper-link-ui/locale/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      SheetsHyperLinkUIZhTW,     ),  },})univer.registerPlugin(UniverSheetsHyperLinkPlugin)univer.registerPlugin(UniverSheetsHyperLinkUIPlugin)

外掛與配置

TypeScript
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {  // 自訂外部連結跳轉方式  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完整的配置項參考 IUniverSheetsHyperLinkUIConfig。

行動裝置支援

先設定行動版編輯器。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在開啟文件前完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

套件桌面版註冊行動版註冊
@univerjs/sheets-hyper-link-uiUniverSheetsHyperLinkUIPluginUniverSheetsHyperLinkMobileUIPlugin

預設模式

安裝

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

使用

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsHyperLinkPreset } from '@univerjs/preset-sheets-hyper-link'import UniverPresetSheetsHyperLinkZhTW from '@univerjs/preset-sheets-hyper-link/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsHyperLinkZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsHyperLinkPreset(),   ],})

預設與配置

TypeScript
UniverSheetsHyperLinkPreset({  // 自訂外部連結跳轉方式  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完整的配置項參考 IUniverSheetsHyperLinkPresetConfig。

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// 在 A1 單元格建立一個指向 Univer 的超連結const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('//', 'Univer')// 在 A2 單元格建立一個指向 Sheet1 的 B2:D4 區域的超連結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.