Web SDK

形状

在 Univer Sheets 中，形状（Shapes）可以用于绘制流程图、注释标记、提示框，以及在工作表上构建可视化说明。

预览

预设模式

形状功能包含在 @univerjs/preset-sheets-advanced 预设中。

安装

@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 在运行时依赖 UniverSheetsDrawingPreset，请先安装 @univerjs/preset-sheets-drawing。

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

使用

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'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'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDrawingZhCN,       UniverPresetSheetsAdvancedZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),     UniverSheetsAdvancedPreset(),   ],})

如果你持有 Univer 商业许可，请参考 客户端许可证使用说明 进行配置。

插件模式

安装

Shell
pnpm add @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui

形状插件依赖绘图插件，注册形状插件前必须先注册 UniverDrawingPlugin、UniverSheetsDrawingPlugin、UniverDrawingUIPlugin 和 UniverSheetsDrawingUIPlugin。

使用

TypeScript
import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape'import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui'import SheetsShapeUIZhCN from '@univerjs-pro/sheets-shape-ui/locale/zh-CN'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'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-pro/sheets-shape/facade'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs/sheets-drawing-ui/lib/index.css'import '@univerjs-pro/sheets-shape-ui/lib/index.css'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DrawingUIZhCN,       SheetsDrawingUIZhCN,       SheetsShapeUIZhCN,     ),  },})univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)univer.registerPlugin(UniverSheetsShapePlugin)univer.registerPlugin(UniverSheetsShapeUIPlugin)

如果你持有 Univer 商业许可，请参考 客户端许可证使用说明 进行配置。

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI。

引入

插件模式说明

只有插件模式需要手动导入 Facade 包。预设模式已经内置对应 Facade，无需额外导入。

TypeScript
import '@univerjs-pro/sheets-shape/facade'

插入基础形状

向 FWorksheet.insertShape 传入通用形状创建数据，它会返回一个可直接操作的 Facade 实例。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rectShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 80, width: 240, height: 120 },  shapeData: {    fill: {      fillType: univerAPI.Enum.ShapeFillEnum.SolidFill,      color: '#e6f4ff',    },    stroke: {      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,      color: '#1677ff',      width: 2,    },  },})if (!rectShape) throw new Error('Shape could not be inserted.')

插入并连接连接线形状

通过 FWorksheet.insertShape 插入连接线，再通过返回的 FConnectorShape Facade 绑定两端。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const leftShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,  transform: { left: 80, top: 80, width: 180, height: 100 },})const rightShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse,  transform: { left: 420, top: 200, width: 180, height: 100 },})const connectorShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.BentConnector3,  transform: { left: 240, top: 130, width: 240, height: 120 },})if (!leftShape || !rightShape || !connectorShape) {  throw new Error('Shapes could not be inserted.')}const startSite = leftShape.getConnectionSites()[0]const rightSites = rightShape.getConnectionSites()const endSite = rightSites[2] ?? rightSites[0]if (!startSite || !endSite) throw new Error('Connection site not found.')connectorShape  .bindStart(leftShape.getId(), startSite.index)  .bindEnd(rightShape.getId(), endSite.index)  .setEndArrow(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)

更新和删除形状

直接通过形状的 Facade 实例更新或删除形状。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const firstShape = fWorksheet.getShapes().find(shape => !shape.isConnectorShape())if (firstShape) {  firstShape    .setStrokeColor('#ff4d4f')    .setStrokeWidth(3)    .setSolidFill('#fff1f0')  // 如有需要，可在更新后删除该形状  const removed = firstShape.remove()  console.log(removed)}

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.