HyperLink
Facade API | Has Paid Plan | Univer Server | Univer on Node.js | Preset |
---|---|---|---|---|
✅ | - | - | ✅ | UniverSheetsHyperLinkPreset |
- The hyperlink feature allows jumping to worksheets and cells, supporting adding, updating, parsing, and removing links.
- Supports inserting hyperlinks within rich text.
- Hyperlinks support sub-sheets, ranges/cells, defined names, and standard links (http, mailto, etc.).
This feature includes the following plugin packages:
@univerjs/sheets-hyper-link
- HyperLink Plugin@univerjs/sheets-hyper-link-ui
- HyperLink UI Plugin
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
Build/Parse/Jump HyperLink
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');
Manipulating Hyperlinks in Cells
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()
:
Link Addition Event
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;
});
Link Update Event
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;
});
Link Deletion Event
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 instanceworksheet
: Current worksheet instancerow
: Row index of the cell containing the linkcolumn
: Column index of the cell containing the link
Special parameters:
BeforeSheetLinkAdd
event includeslink
: The link to be addedBeforeSheetLinkUpdate
event includes:id
: Link identifierpayload
: New link data
BeforeSheetLinkCancel
event includesid
: Link identifier to be removed
All event callbacks can return false
to prevent the corresponding operation.
Last updated on