画像

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

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

プラグインモード

インストール

Shell
pnpm 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'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIJaJP from '@univerjs/drawing-ui/locale/ja-JP'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIJaJP from '@univerjs/sheets-drawing-ui/locale/ja-JP'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs/sheets-drawing-ui/lib/index.css'import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'const univer = new Univer({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      DrawingUIJaJP,       SheetsDrawingUIJaJP,     ),  },})univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)

コラボレーション機能(collaboration)を使用する場合は、override 設定を追加する必要があります:

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

プラグインと設定

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

モバイル対応

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

パッケージデスクトップの登録モバイルの登録
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/sheets-drawing-uiUniverSheetsDrawingUIPluginUniverSheetsDrawingMobileUIPlugin

プリセットモード

インストール

Shell
pnpm 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'import UniverPresetSheetsDrawingJaJP from '@univerjs/preset-sheets-drawing/locales/ja-JP'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      UniverPresetSheetsCoreJaJP,      UniverPresetSheetsDrawingJaJP,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),   ],})

コラボレーション機能(collaboration)を使用する場合は、UniverSheetsDrawingPreset に collaboration: true オプションを渡してください:

TypeScript
UniverSheetsDrawingPreset({  collaboration: true, })

プリセットと設定

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

Facade API

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

インポート

プラグインモード注意

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、マージンは 0const 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() は浮動画像ビルダーを作成し、FOverGridImageBuilder のインスタンスを返します。チェーン呼び出しで ISheetImage オブジェクトを生成して画像を挿入できます。

以下は FOverGridImageBuilder の主なメソッドです:

メソッド説明
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[] の配列を返します。

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 が必要です。

TypeScript
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() で取得できます。画像のプロパティパネルにも透明度の操作項目があります。

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

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

© 2026 DreamNum Co., Ltd.