图片

图片功能允许用户在电子表格中插入和管理图片,以便更好地展示数据和信息。它支持多种图片格式和操作,帮助用户创建更丰富的文档。

目前支持插入的图片类型为:浮动图片、单元格图片

插件模式

安装

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 DrawingUIZhCN from '@univerjs/drawing-ui/locale/zh-CN'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIZhCN from '@univerjs/sheets-drawing-ui/locale/zh-CN'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_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DrawingUIZhCN,       SheetsDrawingUIZhCN,     ),  },})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 UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'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_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDrawingZhCN,     ),  },  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 服务处理。背景仅用于屏幕展示,不参与打印。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.