Hyperlink

Hyperlinks are used to quickly navigate and access content within spreadsheets, such as internal worksheets, cells, and external web pages or email addresses.

Preview

Preset Mode

Installation

npm install @univerjs/preset-sheets-hyper-link

Usage

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsHyperLinkPreset } from '@univerjs/preset-sheets-hyper-link'
import UniverPresetSheetsHyperLinkEnUS from '@univerjs/preset-sheets-hyper-link/locales/en-US'
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.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsHyperLinkEnUS, 
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsHyperLinkPreset(), 
  ],
})

Presets and Configuration

UniverSheetsHyperLinkPreset({
  // Customize the way external links are opened
  urlHandler: {
    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),
  },
})

Complete configuration options can be found in IUniverSheetsHyperLinkPresetConfig.

Plugin Mode

Installation

npm install @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui

Usage

import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link'
import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui'
import SheetsHyperLinkUIEnUS from '@univerjs/sheets-hyper-link-ui/locale/en-US'

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.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsHyperLinkUIEnUS, 
    ),
  },
})

univer.registerPlugin(UniverSheetsHyperLinkPlugin) 
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin)

Plugins and Configuration

univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {
  // Customize the way external links are opened
  urlHandler: {
    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),
  },
})

Complete configuration options can be found in IUniverSheetsHyperLinkUIConfig.

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

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

The navigateToSheetHyperlink API is provided by the UI plugin, so import:

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

Create HyperLink

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) return

// Create a hyperlink to Univer on cell A1
const fRange = fWorksheet.getRange('A1')
await fRange.setHyperLink('https://univer.ai/', 'Univer')

// Create a hyperlink to active sheet range B2:D4 on cell A2
const fRange2 = fWorksheet.getRange('A2')
const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()
await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')

// Create a hyperlink to another sheet range on cell 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')
}

// Create a hyperlink to a defined name on cell A4
const fRange4 = fWorksheet.getRange('A4')
const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')
await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')

Get/Update/Cancel HyperLink

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) return

// Get all hyperlinks in the range A1:D10
const fRange = fWorksheet.getRange('A1:D10')
const hyperlinks = fRange.getHyperLinks()
console.log(hyperlinks)

// Update the hyperlink on cell A1
const cellA1 = fWorksheet.getRange('A1')
const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()
await cellA1.updateHyperLink(rangeUrl, 'Link to B2:D4')

// Clear all hyperlinks in the range A1:D10
fRange.cancelHyperLink()

// Or clear a specific hyperlink in the range A1:D10
if (hyperlinks.length > 1) {
  fRange.cancelHyperLink(hyperlinks[1])
}

Build/Parse/Jump HyperLink

const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()

// Build a hyperlink url pointing to cell F6 of the first sheet
const hyperlinkUrl = sheets[0].getRange('F6').getUrl()

// Parse the hyperlink
const hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlinkUrl)
console.log(hyperlinkInfo)

// Switch to the second sheet
fWorkbook.setActiveSheet(sheets[1])
console.log(fWorkbook.getActiveSheet().getSheetName())

// Jump to the hyperlink after 3 seconds
await new Promise(resolve => setTimeout(resolve, 3000))
fWorkbook.navigateToSheetHyperlink(hyperlinkUrl)
console.log(fWorkbook.getActiveSheet().getSheetName())

Event Listeners

Full event type definitions, please refer to Events.

You can listen to hyperlink-related events using univerAPI.addEvent():

Link Addition Event

univerAPI.Event.BeforeSheetLinkAdd: Triggered before adding a link

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (params) => {
  const { workbook, worksheet, row, col, link } = params

  // Cancel the sheet link add operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`

Link Update Event

univerAPI.Event.BeforeSheetLinkUpdate: Triggered before updating a link

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (params) => {
  const { workbook, worksheet, row, column, id, payload } = params

  // Cancel the sheet link update operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`

Link Deletion Event

univerAPI.Event.BeforeSheetLinkCancel: Triggered before canceling a link

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (params) => {
  const { workbook, worksheet, row, column, id } = params

  // Cancel the sheet link cancel operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`

Each event includes the following common parameters:

workbook: Current workbook instance
worksheet: Current worksheet instance
row: Row index of the cell containing the link
column: Column index of the cell containing the link (note: BeforeSheetLinkAdd uses col instead of column)

Special parameters:

BeforeSheetLinkAdd event includes link: The link to be added
BeforeSheetLinkUpdate event includes:
- id: Link identifier
- payload: New link data
BeforeSheetLinkCancel event includes id: Link identifier to be removed

All event callbacks can use params.cancel = true to prevent the corresponding operation.

Table of Contents