# ハイパーリンク

- Human documentation: [https://docs.univer.ai/ja-JP/guides/sheets/features/hyper-link](https://docs.univer.ai/ja-JP/guides/sheets/features/hyper-link)

- Agent Markdown: [https://docs.univer.ai/ja-JP/guides/sheets/features/hyper-link.md](https://docs.univer.ai/ja-JP/guides/sheets/features/hyper-link.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

- Source: [sheets/features/hyper-link.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/hyper-link.ja-JP.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-hyper-link",
      "locale": "@univerjs/preset-sheets-hyper-link/locales/ja-JP",
      "style": "@univerjs/preset-sheets-hyper-link/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/sheets-hyper-link",
      "facade": "@univerjs/sheets-hyper-link/facade",
      "locale": "@univerjs/sheets-hyper-link/locale/ja-JP"
    },
    {
      "client": "@univerjs/sheets-hyper-link-ui",
      "facade": "@univerjs/sheets-hyper-link-ui/facade",
      "locale": "@univerjs/sheets-hyper-link-ui/locale/ja-JP",
      "style": "@univerjs/sheets-hyper-link-ui/lib/index.css"
    }
  ],
  "server": false
}
```

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

> Interactive example: [Open the playground](/playground/sheets/hyper-link)

## プラグインモード

### インストール

#### npm

```bash
npm install @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui
```

#### pnpm

```bash
pnpm add @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui
```

#### yarn

```bash
yarn add @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui
```

#### bun

```bash
bun 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' // [!code ++]
import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui' // [!code ++]
import SheetsHyperLinkUIJaJP from '@univerjs/sheets-hyper-link-ui/locale/ja-JP' // [!code ++]
import '@univerjs/sheets-hyper-link-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-hyper-link/facade' // [!code ++]
import '@univerjs/sheets-hyper-link-ui/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.JA_JP,
  locales: {
    [LocaleType.JA_JP]: mergeLocales(
      SheetsHyperLinkUIJaJP, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsHyperLinkPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin) // [!code ++]
```

### プラグインと設定

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

完全な設定オプションは [`IUniverSheetsHyperLinkUIConfig`](https://docs.univer.ai/ja-JP/reference/packages/plugins/univerjs/sheets-hyper-link-ui.md) で確認できます。

## モバイル対応

まず[モバイルエディター](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md#mobile-support)を設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、**文書を開く前に**完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。

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

## プリセットモード

### インストール

#### npm

```bash
npm install @univerjs/preset-sheets-hyper-link
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-hyper-link
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-hyper-link
```

#### bun

```bash
bun 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' // [!code ++]
import UniverPresetSheetsHyperLinkJaJP from '@univerjs/preset-sheets-hyper-link/locales/ja-JP' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-hyper-link/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.JA_JP,
  locales: {
    [LocaleType.JA_JP]: mergeLocales(
      UniverPresetSheetsCoreJaJP,
      UniverPresetSheetsHyperLinkJaJP, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsHyperLinkPreset(), // [!code ++]
  ],
})
```

### プリセットと設定

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

完全な設定オプションは [`IUniverSheetsHyperLinkPresetConfig`](https://docs.univer.ai/ja-JP/reference/packages/presets/univerjs/preset-sheets-hyper-link.md) で確認できます。

## Facade API

完全な Facade API の型定義は [FacadeAPI](https://docs.univer.ai/ja-JP/reference/facade.md) で確認できます。

### インポート

> [!INFO: プラグインモード注意]
> 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](https://docs.univer.ai/ja-JP/reference/facade/events.md) を参照してください。

ハイパーリンクに関するイベントは `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` を設定することで、該当する操作を防止できます。