Skip to Content
🎉 Univer 0.6.6 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 FacadeAPI

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); console.log(hyperlinkInfo); // Switch to the second sheet fWorkbook.setActiveSheet(sheets[1]); console.log(fWorkbook.getActiveSheet().getSheetName()); // Navigate to the hyperlink after 3 seconds setTimeout(() => { fWorkbook.navigateToSheetHyperlink(hyperlink); console.log(fWorkbook.getActiveSheet().getSheetName()); }, 3000);
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(); console.log(hyperlinks); // 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 Listening

Full event type definitions, please refer to Events.

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

  • univerAPI.Event.BeforeSheetLinkAdd: Triggered before adding a link
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (params) => { const { workbook, worksheet, row, col, link } = params; console.log(params); // Cancel the sheet link add operation params.cancel = true; }); // Remove the event listener, use `disposable.dispose()`
  • univerAPI.Event.BeforeSheetLinkUpdate: Triggered before updating a link
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (params) => { const { workbook, worksheet, row, column, id, payload } = params; console.log('before sheet link update', params); // Cancel the sheet link update operation params.cancel = true; }); // Remove the event listener, use `disposable.dispose()`
  • univerAPI.Event.BeforeSheetLinkCancel: Triggered before canceling a link
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (params) => { const { workbook, worksheet, row, column, id } = params; console.log('before sheet link cancel', 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.


Was this page helpful?
Last updated on