形状
在 Univer Sheets 中，形状（Shapes）可以用于绘制流程图、注释标记、提示框，以及在工作表上构建可视化说明。
插件模式
安装
Shell
pnpm add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
npm install @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
yarn add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
bun add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui形状还依赖 @univerjs-pro/engine-formula 中的 UniverProFormulaEnginePlugin。请将基础初始化代码中原有的 UniverFormulaEnginePlugin 导入和注册替换为该插件。不要同时注册两种公式引擎，否则插入形状时可能出现依赖未注册错误。
形状插件依赖绘图插件，注册形状插件前必须先注册 UniverDrawingPlugin、UniverSheetsDrawingPlugin、UniverDrawingUIPlugin 和 UniverSheetsDrawingUIPlugin。
使用
TypeScript
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'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(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)univer.registerPlugin(UniverSheetsShapePlugin)univer.registerPlugin(UniverSheetsShapeUIPlugin)如果你持有 Univer 商业许可，请参考 客户端许可证使用说明 进行配置。
移动端适配
先配置移动端编辑器。在本页插件模式的初始化代码中，将下列桌面端注册替换为同一个包导出的移动端插件，并在打开文档前完成。保留模型插件、样式、语言包和 Facade 导入，不要同时注册两个版本。
| 来源包 | 桌面端注册 | 移动端注册 |
|---|---|---|
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
@univerjs-pro/sheets-shape-ui | UniverSheetsShapeUIPlugin | UniverSheetsShapeMobileUIPlugin |
预设模式
形状功能包含在 @univerjs/preset-sheets-advanced 预设中。该预设已注册 UniverProFormulaEnginePlugin，无需手动替换公式引擎。
安装
@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 在运行时依赖 UniverSheetsDrawingPreset，请先安装 @univerjs/preset-sheets-drawing。
Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
bun 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 商业许可，请参考 客户端许可证使用说明 进行配置。
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.')编辑形状文字
使用下方或前面示例中 insertShape() 返回的形状对象。getText() 返回实时的 FShapeText 对象，可通过 getPlainText() 读取纯文本、setText() 替换全部文字，并设置字体、颜色和对齐方式。
TypeScript
if (!rectShape) throw new Error('Shape is not available')const shapeText = rectShape.getText()console.log(shapeText.getPlainText())shapeText .setText('Quarterly review') .setFontSize(18) .setColor('#2563eb') .setBold(true) .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER) .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)setText() 会替换已有文字；同一形状需要多种文字样式时，使用 setRichText()。编辑现有富文本时，先调用 getRichText()?.copy()，修改构建器后再传给 setRichText()，仅修改构建器不会自动写回。更多选项见文字样式和文本框内边距与布局。
TypeScript
const richText = univerAPI.newRichText() .text('Quarterly ') .bold('review')shapeText.setRichText(richText)插入并连接连接线形状
通过 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)}形状格式刷
选中源形状，启用格式刷，再选择目标形状。格式刷复制填充、描边、效果及受支持的文字格式，保留目标的标识、几何信息、文字内容和公式绑定。清除格式会恢复插入时的默认样式。SmartArt 不参与此操作；对应的形状 UI 插件会自动注册该行为。
你觉得这篇文档如何？