# 画像

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

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

---

#### Package metadata

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

画像は、スプレッドシートのコンテンツを豊かにし、視覚的な表現を強化し、重要な情報を説明・強調するのに使用できます。

現在サポートされている画像の種類は、浮動画像（floating images）とセル内画像（cell images）です。

> Interactive example: [Open the playground](/playground/sheets/images)

## プラグインモード

### インストール

#### npm

```bash
npm install @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### pnpm

```bash
pnpm add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### yarn

```bash
yarn add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### bun

```bash
bun add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

### 使い方

```typescript
import { IImageIoService, LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverDocsDrawingPlugin } from '@univerjs/docs-drawing' // [!code ++]
import { UniverDrawingPlugin } from '@univerjs/drawing' // [!code ++]
import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui' // [!code ++]
import DrawingUIJaJP from '@univerjs/drawing-ui/locale/ja-JP' // [!code ++]
import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing' // [!code ++]
import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui' // [!code ++]
import SheetsDrawingUIJaJP from '@univerjs/sheets-drawing-ui/locale/ja-JP' // [!code ++]
import '@univerjs/drawing-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-drawing-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-drawing/facade' // [!code ++]
import '@univerjs/sheets-drawing-ui/facade' // [!code ++]

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

univer.registerPlugin(UniverDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverDrawingUIPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingUIPlugin) // [!code ++]
```

コラボレーション機能([collaboration](https://docs.univer.ai/ja-JP/guides/docs/features/collaboration.md))を使用する場合は、`override` 設定を追加する必要があります:

```typescript
univer.registerPlugin(UniverDrawingPlugin, {
  override: [[IImageIoService, null]], // [!code ++]
  // allowImageSize: 20 * 1024 * 1024, // アップロード画像の最大許容サイズを 20MB に設定します（任意）
})
```

### プラグインと設定

```typescript
interface IUniverDrawingConfig {
  /**
   * アップロード画像の最大許容サイズをバイト単位で設定します。
   * @default 5 * 1024 * 1024 (5MB)
   */
  allowImageSize?: number
}
```

## モバイル対応

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

| パッケージ                         | デスクトップの登録                     | モバイルの登録                             |
| ----------------------------- | ----------------------------- | ----------------------------------- |
| `@univerjs/drawing-ui`        | `UniverDrawingUIPlugin`       | `UniverDrawingMobileUIPlugin`       |
| `@univerjs/sheets-drawing-ui` | `UniverSheetsDrawingUIPlugin` | `UniverSheetsDrawingMobileUIPlugin` |

## プリセットモード

### インストール

#### npm

```bash
npm install @univerjs/preset-sheets-drawing
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing
```

### 使い方

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreJaJP from '@univerjs/preset-sheets-core/locales/ja-JP'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingJaJP from '@univerjs/preset-sheets-drawing/locales/ja-JP' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]

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

コラボレーション機能（[collaboration](https://docs.univer.ai/ja-JP/guides/sheets/features/collaboration.md)）を使用する場合は、`UniverSheetsDrawingPreset` に `collaboration: true` オプションを渡してください:

```typescript
UniverSheetsDrawingPreset({
  collaboration: true, // [!code ++]
})
```

### プリセットと設定

```typescript
interface IUniverSheetsDrawingPresetConfig {
  /**
   * コラボレーション編集機能を使用するかどうか。
   * @default false
   */
  collaboration?: boolean
  /**
   * アップロード画像の最大許容サイズをバイト単位で設定します。
   * @default 5 * 1024 * 1024 (5MB)
   */
  allowImageSize?: number
}
```

## Facade API

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

### インポート

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

```typescript
import '@univerjs/sheets-drawing/facade'
import '@univerjs/sheets-drawing-ui/facade'
```

### Floating DOM の追加

`FWorksheet.addFloatDomToPosition(layer)` メソッドは、指定した位置に浮動 DOM 要素を追加できます。

```tsx
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// コンポーネントは適切なタイミングで登録してください（例: Univer が読み込まれたとき）
// これは React コンポーネントです。Vue3 コンポーネントの場合、3 番目の引数は `{ framework: 'vue3' }` にしてください
univerAPI.registerComponent(
  'myFloatDom',
  ({ data }) => (
    <div style={{ width: '100%', height: '100%', background: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' }}>
      ポップアップ内容:
      {' '}
      {data?.label}
    </div>
  ),
)

// 浮動 DOM を追加します
// disposable が null の場合、浮動 DOM の追加に失敗しています
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'myFloatDom',
  initPosition: {
    startX: 100,
    endX: 300,
    startY: 100,
    endY: 200,
  },

  // コンポーネントのデータ
  data: {
    label: 'hahah',
  },
})

// 2 秒後に浮動 DOM を削除します
setTimeout(() => {
  disposable?.dispose()
}, 2000)
```

`FWorksheet.addFloatDomToRange(range, layer, domLayout)` メソッドは、指定した範囲に浮動 DOM 要素を追加できます。

```tsx
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 範囲ロード用コンポーネントを登録します
function RangeLoading() {
  const divStyle = {
    width: '100%',
    height: '100%',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    transformOrigin: 'top left',
  }

  return (
    <div style={divStyle}>
      読み込み中...
    </div>
  )
}
univerAPI.registerComponent('RangeLoading', RangeLoading)

// 範囲 A1:C3 を覆う範囲ロードコンポーネントを追加します
const fRange = fWorksheet.getRange('A1:C3')
const disposable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading')

// 2 秒後に浮動 DOM を削除します
setTimeout(() => {
  disposable?.dispose()
}, 2000)

// 別の例 -------------------
// フロートボタンコンポーネントを登録します
function FloatButton() {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  }

  const clickHandler = () => {
    console.warn('click')
  }

  return (
    <div style={divStyle} onClick={clickHandler}>
      フロートボタン
    </div>
  )
}
univerAPI.registerComponent('FloatButton', FloatButton)

// フロートボタンを範囲 A5:C7 に追加します。配置は A5 セルから開始、幅 100px、高さ 30px、マージンは範囲幅 / 高さ の 100% です
const fRange2 = fWorksheet.getRange('A5:C7')
const disposable2 = fWorksheet.addFloatDomToRange(
  fRange2,
  {
    componentKey: 'FloatButton',
  },
  {
    width: 100,
    height: 30,
    marginX: '100%', // 範囲幅に対するマージンの割合、またはピクセル指定
    marginY: '100%',
  },
  'myFloatButton',
)
```

`FWorksheet.addFloatDomToColumnHeader(column, layer, domPos)` メソッドは、指定した列見出しに浮動 DOM 要素を追加できます。

```tsx
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()

// フロートボタンコンポーネントを登録します
function FloatButton() {
  const divStyle = {
    width: '100px',
    height: '30px',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    cursor: 'pointer',
  }

  const clickHandler = () => {
    console.warn('click')
  }

  return (
    <div style={divStyle} onClick={clickHandler}>
      フロートボタン
    </div>
  )
}
univerAPI.registerComponent('FloatButton', FloatButton)

// 列 D の見出しにフロートボタンを追加します。配置は右寄せ、幅 100px、高さ 30px、マージンは 0
const disposable = fWorksheet.addFloatDomToColumnHeader(
  3,
  {
    componentKey: 'FloatButton',
    allowTransform: false,
  },
  {
    width: 100,
    height: 30,
    marginX: 0,
    marginY: 0,
    horizonOffsetAlign: 'right',
  },
  'myFloatButton',
)

// 2 秒後にフロートボタンを削除します
setTimeout(() => {
  disposable?.dispose()
}, 2000)
```

### 浮動画像の挿入

[`FWorksheet.newOverGridImage()`](https://docs.univer.ai/ja-JP/reference/facade/worksheet.md#newovergridimage) は浮動画像ビルダーを作成し、`FOverGridImageBuilder` のインスタンスを返します。チェーン呼び出しで `ISheetImage` オブジェクトを生成して画像を挿入できます。

以下は [`FOverGridImageBuilder`](https://docs.univer.ai/ja-JP/reference/facade/over-grid-image-builder.md) の主なメソッドです:

| メソッド            | 説明                                       |
| --------------- | ---------------------------------------- |
| buildAsync      | 画像をビルドして `ISheetImage` オブジェクトを返します       |
| setSource       | 画像のソースを設定します                             |
| setColumn       | 画像の水平位置を設定します                            |
| setRow          | 画像の垂直位置を設定します                            |
| setColumnOffset | 画像の水平オフセットを設定します                         |
| setRowOffset    | 画像の垂直オフセットを設定します                         |
| setWidth        | 画像の幅を設定します                               |
| setHeight       | 画像の高さを設定します                              |
| setAnchorType   | 画像のアンカータイプを設定します（セルに応じて位置・サイズが変わるかどうか）   |
| setCropTop      | 画像の上端を定義して切り取り領域を設定します。表示したい画像の部分を指定できます |
| setCropLeft     | 画像の左端を定義して切り取り領域を設定します。表示したい画像の部分を指定できます |
| setCropBottom   | 画像の下端を定義して切り取り領域を設定します。表示したい画像の部分を指定できます |
| setCropRight    | 画像の右端を定義して切り取り領域を設定します。表示したい画像の部分を指定できます |
| setRotate       | 画像の回転角度を設定します                            |

```typescript
// 新しい画像ビルダーを作成し、画像ソースを設定します。
// その後 `ISheetImage` をビルドしてシートに挿入します。配置は F6 セルから開始、幅 500px、高さ 300px です
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image = await fWorksheet.newOverGridImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])
```

`FWorksheet.insertImage(url, column, row, offsetX, offsetY)` メソッドでも画像を挿入できます。

```typescript
// 画像をシートに挿入します。配置は F6、オフセットは 10px です
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5, 10, 10)
```

### 浮動画像の取得

`FWorksheet.getImages()` メソッドはワークシート内のすべての浮動画像を取得し、[`FOverGridImage[]`](https://docs.univer.ai/ja-JP/reference/facade/chart.md) の配列を返します。

```typescript
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const images = fWorksheet.getImages()
images.forEach((image) => {
  image.getId()
})
```

ID によって `FWorksheet.getImageById(id)` メソッドで浮動画像を取得することもできます。

### 浮動画像の更新

`FWorksheet.updateImages(sheetImages)` メソッドは、浮動画像の位置やサイズを更新できます。

```typescript
// 新しい画像ビルダーを作成し、画像ソースを設定します。
// その後 `ISheetImage` をビルドしてシートに挿入します。配置は F6 セルから開始、幅 500px、高さ 300px です
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const image = await fWorksheet.newOverGridImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
  .setColumn(5)
  .setRow(5)
  .setWidth(500)
  .setHeight(300)
  .buildAsync()
fWorksheet.insertImages([image])

// 4 秒後に画像の幅を 100px、高さを 50px に更新します
setTimeout(async () => {
  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()
  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()
  fWorksheet.updateImages([newImage])
}, 4000)
```

### 浮動画像の削除

`FWorksheet.deleteImages(sheetImages)` メソッドは浮動画像を削除できます。

```typescript
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()
const image = fWorksheet.getImages()[0]

// シートの最初の画像を削除します
fWorksheet.deleteImages([image])
```

### セル内画像の挿入

`FRange.insertCellImageAsync(file)` メソッドはセル内画像を挿入できます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// セル A10 に画像を挿入します
const fRange = fWorksheet.getRange('A10')
const result = await fRange.insertCellImageAsync('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
```

## ワークシートの背景画像

ワークシートはセルの背面に 1 枚の画像をタイル表示できます。浮動画像やセル画像とは独立し、`IWorksheetData.backgroundImage` に保存されます。Drawing プリセットに含まれます。プラグイン方式では `@univerjs/sheets-drawing` と Facade、および描画・アップロード用の Drawing UI が必要です。

```ts
import '@univerjs/sheets-drawing/facade'

const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
if (!sheet) throw new Error('No active worksheet')

sheet.setBackgroundImage('https://example.com/background.png')
console.log(sheet.getBackgroundImage())
sheet.deleteBackgroundImage()
```

`setBackgroundImage()` は既定で `ImageSourceType.URL` を使い、既存の背景を置き換えます。`deleteBackgroundImage()` は背景を削除します。どちらも元に戻す・やり直す処理に対応します。UI のアップロードは設定された画像 I/O サービスを使用します。背景は画面表示用で、印刷されません。

## 画像の不透明度

浮動画像全体の不透明度を設定できます。`setOpacity()` は `0`（透明）から `1`（不透明）までの有限数を受け取り、既定値は `1` です。範囲外の値は `RangeError` になります。作成前の `FOverGridImageBuilder` と既存の `FOverGridImage` の両方で設定でき、`getOpacity()` で取得できます。画像のプロパティパネルにも透明度の操作項目があります。

```ts
const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()
const image = sheet?.getImages()[0]
if (image) {
  image.setOpacity(0.5)
  console.log(image.getOpacity())
}
```