圖片
圖片功能允許使用者在電子表格中插入和管理圖片,以便更好地展示資料和資訊。它支援多種圖片格式和操作,幫助使用者建立更豐富的文件。
目前支援插入的圖片型別為:浮動圖片、單元格圖片
外掛模式
安裝
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 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 配置:
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 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 選項。
UniverSheetsDrawingPreset({ collaboration: true, })預設與配置
interface IUniverSheetsDrawingPresetConfig { /** * 是否使用了協同編輯功能。 * @default false */ collaboration?: boolean /** * 設定上傳圖片的最大允許大小,以位元組為單位。 * @default 5 * 1024 * 1024 (5MB) */ allowImageSize?: number}Facade API
完整 Facade API 型別定義,請檢視 FacadeAPI。
引入
外掛模式提示
僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件,無需額外引入。
import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'新增浮動 DOM
FWorksheet.addFloatDomToPosition(layer) 方法可以新增一個浮動的 DOM 元素到指定位置。
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 元素到指定範圍。
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 元素到指定列頭。
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 的旋轉角度 |
// 建立一個新的圖片構建器並設定圖片來源。// 然後構建 `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) 方法插入圖片。
// 插入一個圖片到工作表,位置為 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[] 例項陣列。
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const images = fWorksheet.getImages()images.forEach((image) => { image.getId()})亦可以透過 FWorksheet.getImageById(id) 方法獲取指定 id 的浮動圖片。
更新浮動圖片
FWorksheet.updateImages(sheetImages) 方法可以更新浮動圖片的位置和大小等屬性。
// 建立一個新的圖片構建器並設定圖片來源。// 然後構建 `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) 方法可以刪除浮動圖片。
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')工作表背景圖
工作表另支援一張平鋪背景圖,繪製於儲存格下方,獨立於浮動與儲存格圖片,儲存在 IWorksheetData.backgroundImage。繪圖預設已包含此功能;外掛模式需要 @univerjs/sheets-drawing 與其 Facade,並由繪圖 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())}圖片尺寸與錨點
透過內建檔案選擇器插入圖片時,保留原始長寬比,必要時縮小至 500 × 500 像素以內,不放大小圖。這是顯示尺寸,與限制上傳位元組數的 allowImageSize 不同。透過 Facade 插入時可自行指定尺寸。
使用 SheetDrawingAnchorType.Position 隨儲存格移動但保持尺寸,Both 隨錨定範圍移動並縮放,None 固定位置與尺寸。隱藏與顯示列欄會保留錨點定義:隨範圍縮放的圖片可能暫時收縮,重新顯示後恢復。請勿將隱藏列欄產生的暫時幾何尺寸回寫為錨點。
你覺得這篇文檔如何?