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 FacadeAPI
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);
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);
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();
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()
:
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;
console.log(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;
console.log('before sheet link update', 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;
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 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 use params.cancel = true
to prevent the corresponding operation.
Last updated on