Web SDK

Lien hypertexte

Les liens hypertextes permettent d’accéder rapidement à différents contenus depuis une feuille de calcul, notamment à des feuilles de calcul ou des cellules internes, ainsi qu’à des pages web ou des adresses e-mail externes.

Mode prédéfini

Installation

Shell
pnpm add @univerjs/preset-sheets-hyper-link

Utilisation

TypeScript
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(),   ],})

Préréglages et configuration

TypeScript
UniverSheetsHyperLinkPreset({  // Customize the way external links are opened  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

Toutes les options de configuration sont décrites dans IUniverSheetsHyperLinkPresetConfig.

Mode plug-in

Installation

Shell
pnpm add @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui

Utilisation

TypeScript
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)

Plug-ins et configuration

TypeScript
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {  // Customize the way external links are opened  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

Toutes les options de configuration sont décrites dans IUniverSheetsHyperLinkUIConfig.

Prise en charge mobile

Configurez d’abord l’éditeur mobile. Dans l’initialisation en mode plugin de cette page, remplacez les inscriptions de bureau ci-dessous par les exports mobiles des mêmes paquets avant d’ouvrir un document. Conservez modèles, styles, traductions et imports Facade ; n’enregistrez pas les deux variantes.

PaquetInscription de bureauInscription mobile
@univerjs/sheets-hyper-link-uiUniverSheetsHyperLinkUIPluginUniverSheetsHyperLinkMobileUIPlugin

Facade API

La définition complète des types de l’API Facade est disponible dans la documentation de l’API Facade.

Importation

Remarque sur le mode plug-in

Seul le mode plug-in nécessite d’importer manuellement le paquet Facade. En mode prédéfini, le paquet Facade correspondant est déjà inclus : aucune importation supplémentaire n’est nécessaire.

TypeScript
import '@univerjs/sheets-hyper-link/facade'

L’API navigateToSheetHyperlink est fournie par le plug-in d’interface utilisateur. Importez donc :

TypeScript
import '@univerjs/sheets-hyper-link-ui/facade'

Créer un lien hypertexte

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// Create a hyperlink to Univer on cell A1const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('//', 'Univer')// Create a hyperlink to active sheet range B2:D4 on cell A2const fRange2 = fWorksheet.getRange('A2')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')// Create a hyperlink to another sheet range on cell A3const anotherSheet = fWorkbook.getSheetByName('Another Sheet')if (anotherSheet) {  const fRange3 = fWorksheet.getRange('A3')  const anotherSheetUrl = anotherSheet.getUrl()  await fRange3.setHyperLink(anotherSheetUrl, 'Link to Another Sheet')}// Create a hyperlink to a defined name on cell A4const fRange4 = fWorksheet.getRange('A4')const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')

Obtenir, modifier ou supprimer un lien hypertexte

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// Get all hyperlinks in the range A1:D10const fRange = fWorksheet.getRange('A1:D10')const hyperlinks = fRange.getHyperLinks()console.log(hyperlinks)// Update the hyperlink on cell A1const cellA1 = fWorksheet.getRange('A1')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await cellA1.updateHyperLink(rangeUrl, 'Link to B2:D4')// Clear all hyperlinks in the range A1:D10fRange.cancelHyperLink()// Or clear a specific hyperlink in the range A1:D10if (hyperlinks.length > 1) {  fRange.cancelHyperLink(hyperlinks[1])}

Construire, analyser ou suivre un lien hypertexte

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const sheets = fWorkbook.getSheets()// Build a hyperlink url pointing to cell F6 of the first sheetconst hyperlinkUrl = sheets[0].getRange('F6').getUrl()// Parse the hyperlinkconst hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlinkUrl)console.log(hyperlinkInfo)// Switch to the second sheetfWorkbook.setActiveSheet(sheets[1])console.log(fWorkbook.getActiveSheet().getSheetName())// Jump to the hyperlink after 3 secondsawait new Promise(resolve => setTimeout(resolve, 3000))fWorkbook.navigateToSheetHyperlink(hyperlinkUrl)console.log(fWorkbook.getActiveSheet().getSheetName())

Écouteurs d’événements

Pour consulter la définition complète des types d’événements, reportez-vous à la page Events.

Vous pouvez écouter les événements liés aux liens hypertextes avec univerAPI.addEvent() :

Événement d’ajout d’un lien

univerAPI.Event.BeforeSheetLinkAdd : déclenché avant l’ajout d’un lien

TypeScript
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()`

Événement de modification d’un lien

univerAPI.Event.BeforeSheetLinkUpdate : déclenché avant la modification d’un lien

TypeScript
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()`

Événement de suppression d’un lien

univerAPI.Event.BeforeSheetLinkCancel : déclenché avant la suppression d’un lien

TypeScript
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()`

Chaque événement comprend les paramètres communs suivants :

  • workbook : instance actuelle du classeur
  • worksheet : instance actuelle de la feuille de calcul
  • row : indice de la ligne de la cellule contenant le lien
  • column : indice de la colonne de la cellule contenant le lien (remarque : BeforeSheetLinkAdd utilise col à la place de column)

Paramètres spécifiques :

  • l’événement BeforeSheetLinkAdd comprend link : le lien à ajouter
  • l’événement BeforeSheetLinkUpdate comprend :
    • id : identifiant du lien
    • payload : nouvelles données du lien
  • l’événement BeforeSheetLinkCancel comprend id : l’identifiant du lien à supprimer

Tous les rappels d’événements peuvent utiliser params.cancel = true pour empêcher l’opération correspondante.

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.