Web SDK

形状

插件信息

形状功能允许您在文档中插入和编辑形状与绘图，包括基本几何形状、箭头和流程图元素。

介绍

在 Univer Docs 中，形状使您能够：

  • 插入几何形状：添加矩形、圆形、箭头等。
  • 自定义外观：调整填充颜色、边框和文本。
  • 自由定位：将形状放置在文档中的任意位置。

插件模式

安装

Shell
pnpm add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui

形状还依赖 @univerjs-pro/engine-formula 中的 UniverProFormulaEnginePlugin。请将基础初始化代码中原有的 UniverFormulaEnginePlugin 导入和注册替换为该插件。不要同时注册两种公式引擎，否则插入形状时可能出现依赖未注册错误。

使用

TypeScript
import { UniverDocsShapePlugin } from '@univerjs-pro/docs-shape'import { UniverDocsShapeUIPlugin } from '@univerjs-pro/docs-shape-ui'import DocsShapeUIZhCN from '@univerjs-pro/docs-shape-ui/locale/zh-CN'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/docs-shape-ui/lib/index.css'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DocsShapeUIZhCN,     ),  },})univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverDocsShapePlugin)univer.registerPlugin(UniverDocsShapeUIPlugin)

如果您拥有 Univer 商业许可证，请参阅在客户端使用许可证进行配置。

移动端适配

先配置移动端编辑器。在本页插件模式的初始化代码中，将下列桌面端注册替换为同一个包导出的移动端插件，并在打开文档前完成。保留模型插件、样式、语言包和 Facade 导入，不要同时注册两个版本。

来源包桌面端注册移动端注册
@univerjs-pro/docs-shape-uiUniverDocsShapeUIPluginUniverDocsShapeMobileUIPlugin

编辑形状文字

使用下方或前面示例中 insertShape() 返回的形状对象。getText() 返回实时的 FShapeText 对象，可通过 getPlainText() 读取纯文本、setText() 替换全部文字，并设置字体、颜色和对齐方式。

TypeScript
import '@univerjs-pro/docs-shape/facade'const document = univerAPI.getActiveDocument()const paragraph = document?.getParagraphs()[0]if (!document || !paragraph) throw new Error('No active document paragraph')const shape = document.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  placement: {    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,    anchor: { paragraphId: paragraph.getId(), segmentId: paragraph.getSegmentId() },  },})if (!shape) throw new Error('Shape is not available')const shapeText = shape.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)

形状格式刷

选中源形状，启用格式刷，再选择目标形状。格式刷复制填充、描边、效果及受支持的文字格式，保留目标的标识、几何信息、文字内容和公式绑定。清除格式会恢复插入时的默认样式。SmartArt 不参与此操作；对应的形状 UI 插件会自动注册该行为。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.