Skip to Content
🎉 Univer 0.5.5 is released.Read more →
GuidesUniver SheetsFeaturesHyperlink

HyperLink

Facade APIHas Paid PlanUniver ServerUniver on Node.jsPreset
--UniverSheetsHyperLinkPreset
  1. The hyperlink feature allows jumping to worksheets and cells, supporting adding, updating, parsing, and removing links.
  2. Supports inserting hyperlinks within rich text.
  3. Hyperlinks support sub-sheets, ranges/cells, defined names, and standard links (http, mailto, etc.).

This feature includes the following plugin packages:

Presets Installation

import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets'; import { UniverSheetsCorePreset } from '@univerjs/presets/preset-sheets-core'; import UniverPresetSheetsCoreEnUS from '@univerjs/presets/preset-sheets-core/locales/en-US'; import { UniverSheetsHyperLinkPreset } from '@univerjs/presets/preset-sheets-hyper-link'; import UniverPresetSheetsHyperLinkEnUS from '@univerjs/presets/preset-sheets-hyper-link/locales/en-US'; import '@univerjs/presets/lib/styles/preset-sheets-core.css' import '@univerjs/presets/lib/styles/preset-sheets-hyper-link.css' const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: merge( {}, UniverPresetSheetsCoreEnUS, UniverPresetSheetsHyperLinkEnUS ), }, theme: defaultTheme, presets: [ UniverSheetsCorePreset(), UniverSheetsHyperLinkPreset() ] });

Piecemeal Installation

npm install @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui
import { LocaleType, merge, Univer } from '@univerjs/core'; import { defaultTheme } from "@univerjs/design"; 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({ theme: defaultTheme, locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: merge( SheetsHyperLinkUIEnUS ), }, }); univer.registerPlugin(UniverSheetsHyperLinkPlugin); univer.registerPlugin(UniverSheetsHyperLinkUIPlugin);

Univer on Node.js Piecemeal Installation

npm install @univerjs/sheets-hyper-link
import { LocaleType, Univer } from '@univerjs/core'; import { defaultTheme } from "@univerjs/design"; import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link'; import '@univerjs/sheets-hyper-link/facade'; const univer = new Univer({ theme: defaultTheme, locale: LocaleType.EN_US, }); univer.registerPlugin(UniverSheetsHyperLinkPlugin);

Facade API

To get full defination of facade api, please refer to @univerjs/sheets-hyper-link/facade and @univerjs/sheets-hyper-link-ui/facade

const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook.getActiveSheet(); const range = sheet.getRange(0, 0, 1, 1); // Get the URL of a sheet const sheetUrl = sheet.getUrl(); // Get the URL of a range or cell const rangeUrl = range.getUrl(); // Parse the link, returning information including the link's name, url, and type const linkInfo = workbook.parseSheetHyperlink('#gid=sheet&range=A1'); console.log(linkInfo); // Jump to the link workbook.navigateToSheetHyperlink('#gid=sheet&range=A1');
const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook.getActiveSheet(); const range = sheet.getRange(0, 0, 1, 1); // Add a link const url = sheet.getUrl(); const label = '123'; // Create a rich text value with link const richText = univerAPI.newRichText().insertLink(label, url); await range.setRichTextValueForCell(richText); // Query the hyperlinks in the current cell const value = range.getValue(true); const links = value.getLinks(); console.log(links); // Update a hyperlink const linkId = links[0].id; const newLabel = '456'; const newRichText = value.copy().updateLink(linkId, url, newLabel); await range.setRichTextValueForCell(newRichText); // Remove a hyperlink const updatedValue = range.getValue(true); const updatedRichText = updatedValue.copy().cancelLink(linkId); await range.setRichTextValueForCell(updatedRichText);

Event Listening

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

  • univerAPI.Event.BeforeSheetLinkAdd: Triggered before adding a link
// Listen for before link add event univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (event) => { const { workbook, worksheet, row, col, link } = event; console.log('About to add link:', { row, col, link }); // Return false to prevent link addition return true; });
  • univerAPI.Event.BeforeSheetLinkUpdate: Triggered before updating a link
// Listen for before link update event univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (event) => { const { workbook, worksheet, row, column, id, payload } = event; console.log('About to update link:', { row, column, id, payload }); // Return false to prevent link update return true; });
  • univerAPI.Event.BeforeSheetLinkCancel: Triggered before canceling a link
// Listen for before link cancel event univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (event) => { const { workbook, worksheet, row, column, id } = event; console.log('About to cancel link:', { row, column, id }); // Return false to prevent link cancellation return true; });

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 return false to prevent the corresponding operation.

Last updated on

Was this page helpful?