Web SDK

ハイパーリンク

ハイパーリンクは、スプレッドシート内の内部ワークシートやセル、外部のウェブページやメールアドレスなどのコンテンツへ素早く移動・アクセスするために使用されます。

プラグインモード

インストール

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

使い方

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link'import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui'import SheetsHyperLinkUIJaJP from '@univerjs/sheets-hyper-link-ui/locale/ja-JP'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.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      SheetsHyperLinkUIJaJP,     ),  },})univer.registerPlugin(UniverSheetsHyperLinkPlugin)univer.registerPlugin(UniverSheetsHyperLinkUIPlugin)

プラグインと設定

TypeScript
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {  // 外部リンクの開き方をカスタマイズします  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完全な設定オプションは IUniverSheetsHyperLinkUIConfig で確認できます。

モバイル対応

まずモバイルエディターを設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、文書を開く前に完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。

パッケージデスクトップの登録モバイルの登録
@univerjs/sheets-hyper-link-uiUniverSheetsHyperLinkUIPluginUniverSheetsHyperLinkMobileUIPlugin

プリセットモード

インストール

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

使い方

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreJaJP from '@univerjs/preset-sheets-core/locales/ja-JP'import { UniverSheetsHyperLinkPreset } from '@univerjs/preset-sheets-hyper-link'import UniverPresetSheetsHyperLinkJaJP from '@univerjs/preset-sheets-hyper-link/locales/ja-JP'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.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      UniverPresetSheetsCoreJaJP,      UniverPresetSheetsHyperLinkJaJP,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsHyperLinkPreset(),   ],})

プリセットと設定

TypeScript
UniverSheetsHyperLinkPreset({  // 外部リンクの開き方をカスタマイズします  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

完全な設定オプションは IUniverSheetsHyperLinkPresetConfig で確認できます。

Facade API

完全な Facade API の型定義は FacadeAPI で確認できます。

インポート

プラグインモード注意

Facade パッケージの手動 import が必要なのはプラグインモードのみです。プリセットモードには対応する Facade パッケージが内蔵されているため、追加の import は不要です。

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

navigateToSheetHyperlink API は UI プラグインに含まれるため、次をインポートしてください:

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

ハイパーリンクの作成

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// セル A1 に Univer へのハイパーリンクを作成しますconst fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('//', 'Univer')// セル A2 に Sheet1 の範囲 B2:D4 へのハイパーリンクを作成しますconst fRange2 = fWorksheet.getRange('A2')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')// セル A3 に別のシート範囲へのハイパーリンクを作成しますconst anotherSheet = fWorkbook.getSheetByName('Another Sheet')if (anotherSheet) {  const fRange3 = fWorksheet.getRange('A3')  const anotherSheetUrl = anotherSheet.getUrl()  await fRange3.setHyperLink(anotherSheetUrl, 'Link to Another Sheet')}// セル A4 に定義名へのハイパーリンクを作成しますconst fRange4 = fWorksheet.getRange('A4')const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')

ハイパーリンクの取得・更新・解除

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// 範囲 A1:D10 内のすべてのハイパーリンクを取得しますconst fRange = fWorksheet.getRange('A1:D10')const hyperlinks = fRange.getHyperLinks()console.log(hyperlinks)// セル A1 のハイパーリンクを更新しますconst cellA1 = fWorksheet.getRange('A1')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await cellA1.updateHyperLink(rangeUrl, 'Link to B2:D4')// 範囲 A1:D10 内のすべてのハイパーリンクを解除しますfRange.cancelHyperLink()// または、範囲 A1:D10 内の特定のハイパーリンクを解除しますif (hyperlinks.length > 1) {  fRange.cancelHyperLink(hyperlinks[1])}

ハイパーリンクの構築・解析・ジャンプ

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const sheets = fWorkbook.getSheets()// 最初のシートのセル F6 を指すハイパーリンク URL を構築しますconst hyperlinkUrl = sheets[0].getRange('F6').getUrl()// ハイパーリンクを解析しますconst hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlinkUrl)console.log(hyperlinkInfo)// 2 番目のシートに切り替えますfWorkbook.setActiveSheet(sheets[1])console.log(fWorkbook.getActiveSheet().getSheetName())// 3 秒後にハイパーリンクへ移動しますawait new Promise(resolve => setTimeout(resolve, 3000))fWorkbook.navigateToSheetHyperlink(hyperlinkUrl)console.log(fWorkbook.getActiveSheet().getSheetName())

イベントリスナー

イベントの型定義は Events を参照してください。

ハイパーリンクに関するイベントは univerAPI.addEvent() で監視できます。

リンク追加イベント

univerAPI.Event.BeforeSheetLinkAdd: リンク追加の前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (params) => {  const { workbook, worksheet, row, col, link } = params  // シートへのリンク追加操作をキャンセルします  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

リンク更新イベント

univerAPI.Event.BeforeSheetLinkUpdate: リンク更新の前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (params) => {  const { workbook, worksheet, row, column, id, payload } = params  // シートのリンク更新操作をキャンセルします  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

リンク削除イベント

univerAPI.Event.BeforeSheetLinkCancel: リンクを解除する前にトリガーします

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (params) => {  const { workbook, worksheet, row, column, id } = params  // シートのリンク解除操作をキャンセルします  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

各イベントは次の共通パラメータを含みます:

  • workbook: 現在のワークブックインスタンス
  • worksheet: 現在のワークシートインスタンス
  • row: リンクを含むセルの行インデックス
  • column: リンクを含むセルの列インデックス

特殊パラメータ:

  • BeforeSheetLinkAdd イベントには link が含まれます: 追加されるリンク
  • BeforeSheetLinkUpdate イベントには次が含まれます:
    • id: リンク識別子
    • payload: 新しいリンクデータ
  • BeforeSheetLinkCancel イベントには id が含まれます: 削除されるリンクの識別子

すべてのイベントコールバックで params.cancel = true を設定することで、該当する操作を防止できます。

このガイドはいかがですか？

© 2026 DreamNum Co., Ltd.