画像
画像は、スプレッドシートのコンテンツを豊かにし、視覚的な表現を強化し、重要な情報を説明・強調するのに使用できます。
現在サポートされている画像の種類は、浮動画像(floating images)とセル内画像(cell images)です。
プラグインモード
インストール
pnpm add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uinpm install @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uiyarn add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uibun add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui使い方
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 設定を追加する必要があります:
univer.registerPlugin(UniverDrawingPlugin, { override: [[IImageIoService, null]], // allowImageSize: 20 * 1024 * 1024, // アップロード画像の最大許容サイズを 20MB に設定します(任意)})プラグインと設定
interface IUniverDrawingConfig { /** * アップロード画像の最大許容サイズをバイト単位で設定します。 * @default 5 * 1024 * 1024 (5MB) */ allowImageSize?: number}モバイル対応
まずモバイルエディターを設定します。このページのプラグインモードの初期化コードで、以下のデスクトップ登録を同じパッケージのモバイル版に置き換え、文書を開く前に完了してください。モデル、スタイル、言語ファイル、Facade は維持し、両方を同時に登録しないでください。
| パッケージ | デスクトップの登録 | モバイルの登録 |
|---|---|---|
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
プリセットモード
インストール
pnpm add @univerjs/preset-sheets-drawingnpm install @univerjs/preset-sheets-drawingyarn add @univerjs/preset-sheets-drawingbun add @univerjs/preset-sheets-drawing使い方
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 オプションを渡してください:
UniverSheetsDrawingPreset({ collaboration: true, })プリセットと設定
interface IUniverSheetsDrawingPresetConfig { /** * コラボレーション編集機能を使用するかどうか。 * @default false */ collaboration?: boolean /** * アップロード画像の最大許容サイズをバイト単位で設定します。 * @default 5 * 1024 * 1024 (5MB) */ allowImageSize?: number}Facade API
完全な Facade API の型定義は FacadeAPI で確認できます。
インポート
プラグインモード注意
Facade パッケージの手動 import が必要なのはプラグインモードのみです。プリセットモードには対応する Facade パッケージが内蔵されているため、追加の import は不要です。
import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'Floating DOM の追加
FWorksheet.addFloatDomToPosition(layer) メソッドは、指定した位置に浮動 DOM 要素を追加できます。
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 要素を追加できます。
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 要素を追加できます。
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 | 画像の回転角度を設定します |
// 新しい画像ビルダーを作成し、画像ソースを設定します。// その後 `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) メソッドでも画像を挿入できます。
// 画像をシートに挿入します。配置は 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[] の配列を返します。
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const images = fWorksheet.getImages()images.forEach((image) => { image.getId()})ID によって FWorksheet.getImageById(id) メソッドで浮動画像を取得することもできます。
浮動画像の更新
FWorksheet.updateImages(sheetImages) メソッドは、浮動画像の位置やサイズを更新できます。
// 新しい画像ビルダーを作成し、画像ソースを設定します。// その後 `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) メソッドは浮動画像を削除できます。
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const image = fWorksheet.getImages()[0]// シートの最初の画像を削除しますfWorksheet.deleteImages([image])セル内画像の挿入
FRange.insertCellImageAsync(file) メソッドはセル内画像を挿入できます。
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 が必要です。
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() で取得できます。画像のプロパティパネルにも透明度の操作項目があります。
const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()const image = sheet?.getImages()[0]if (image) { image.setOpacity(0.5) console.log(image.getOpacity())}このガイドはいかがですか?