圖片

圖片功能允許使用者在電子表格中插入和管理圖片,以便更好地展示資料和資訊。它支援多種圖片格式和操作,幫助使用者建立更豐富的文件。

目前支援插入的圖片型別為:浮動圖片、單元格圖片

外掛模式

安裝

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 DrawingUIZhTW from '@univerjs/drawing-ui/locale/zh-TW'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIZhTW from '@univerjs/sheets-drawing-ui/locale/zh-TW'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.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      DrawingUIZhTW,       SheetsDrawingUIZhTW,     ),  },})univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)

如使用協同編輯功能,需要新增 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 UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW'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.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsDrawingZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),   ],})

如使用協同編輯功能,請確保在 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 套件。預設模式已內建對應的 Facade 套件,無需額外引入。

TypeScript
import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'

新增浮動 DOM

FWorksheet.addFloatDomToPosition(layer) 方法可以新增一個浮動的 DOM 元素到指定位置。

TSX
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()// 你應該在合適的時機註冊元件(例如 Univer 載入完成時)// 這是一個 React 元件。對於 Vue3 元件,第三個參數應該是 `{ framework: 'vue3' }`univerAPI.registerComponent(  'myFloatDom',  ({ data }) => (    <div style={{ width: '100%', height: '100%', background: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' }}>      popup content:      {' '}      {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 秒後移除浮動 DOMsetTimeout(() => {  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}>      Loading...    </div>  )}univerAPI.registerComponent('RangeLoading', RangeLoading)// 新增範圍載入元件覆蓋範圍 A1:C3const fRange = fWorksheet.getRange('A1:C3')const disposable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading')// 2 秒後移除浮動 DOMsetTimeout(() => {  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}>      FloatButton    </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}>      FloatButton    </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設定 image 的來源
setColumn設定 image 的水平方向位置
setRow設定 image 的垂直方向位置
setColumnOffset設定 image 的水平方向偏移
setRowOffset設定 image 的垂直方向偏移
setWidth設定 image 的寬度
setHeight設定 image 的高度
setAnchorType設定 image 的錨點型別,是否隨單元格位置和大小變化
setCropTop設定 image 的裁剪區域,定義頂部邊緣,從而顯示你想要的影象的特定部分
setCropLeft設定 image 的裁剪區域,定義左邊緣,從而顯示你想要的影象的特定部分
setCropBottom設定 image 的裁剪區域,定義底部邊緣,從而顯示你想要的影象的特定部分
setCropRight設定 image 的裁剪區域,定義右邊緣,從而顯示你想要的影象的特定部分
setRotate設定 image 的旋轉角度
TypeScript
// 建立一個新的圖片構建器並設定圖片來源。// 然後構建 `ISheetImage` 並插入到工作表中,位置從 F6 單元格開始,寬度為 500px,高度為 300pxconst 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,偏移為 10pxconst 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()})

亦可以透過 FWorksheet.getImageById(id) 方法獲取指定 id 的浮動圖片。

更新浮動圖片

FWorksheet.updateImages(sheetImages) 方法可以更新浮動圖片的位置和大小等屬性。

TypeScript
// 建立一個新的圖片構建器並設定圖片來源。// 然後構建 `ISheetImage` 並插入到工作表中,位置從 F6 單元格開始,寬度為 500px,高度為 300pxconst 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,高度為 50pxsetTimeout(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')

工作表背景圖

工作表另支援一張平鋪背景圖,繪製於儲存格下方,獨立於浮動與儲存格圖片,儲存在 IWorksheetData.backgroundImage。繪圖預設已包含此功能;外掛模式需要 @univerjs/sheets-drawing 與其 Facade,並由繪圖 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())}

圖片尺寸與錨點

透過內建檔案選擇器插入圖片時,保留原始長寬比,必要時縮小至 500 × 500 像素以內,不放大小圖。這是顯示尺寸,與限制上傳位元組數的 allowImageSize 不同。透過 Facade 插入時可自行指定尺寸。

使用 SheetDrawingAnchorType.Position 隨儲存格移動但保持尺寸,Both 隨錨定範圍移動並縮放,None 固定位置與尺寸。隱藏與顯示列欄會保留錨點定義:隨範圍縮放的圖片可能暫時收縮,重新顯示後恢復。請勿將隱藏列欄產生的暫時幾何尺寸回寫為錨點。

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.