Hyperlink

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

Playground

Live 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'

Build/Parse/Jump HyperLink

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

// Create a hyperlink to the cell F6 in the first sheet
const sheet1 = sheets[0]
const range = sheet1.getRange('F6')
const hyperlink = range.getUrl()

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

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

// Navigate to the hyperlink after 3 seconds
setTimeout(() => {
  fWorkbook.navigateToSheetHyperlink(hyperlink)
  fWorkbook.getActiveSheet().getSheetName()
}, 3000)

Manipulating Hyperlinks in Cells

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a hyperlink to Univer on cell A1
const fRange = fWorksheet.getRange('A1')
const richText = univerAPI.newRichText().insertLink('Univer', 'https://univer.ai/')
fRange.setRichTextValueForCell(richText)

// Query the hyperlinks in the current cell
const cellValue = fRange.getValue(true)
const hyperlinks = cellValue.getLinks()

// Update hyperlink after 3 seconds
setTimeout(() => {
  const id = hyperlinks[0].rangeId
  const newUrl = 'https://insight.univer.ai/'
  const newRichText = cellValue.copy().updateLink(id, newUrl)
  fRange.setRichTextValueForCell(newRichText)
}, 3000)

// Cancel hyperlink after 6 seconds
setTimeout(() => {
  const newCellValue = fRange.getValue(true)
  const newHyperlinks = newCellValue.getLinks()
  const id = newHyperlinks[0].rangeId
  const newRichText = newCellValue.copy().cancelLink(id)
  fRange.setRichTextValueForCell(newRichText)
}, 6000)

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

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