形状

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

Playground

Live preview

预设模式

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

安装

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

npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

使用

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 商业许可，请参考客户端许可证使用说明进行配置。

插件模式

安装

npm install @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui

使用

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 '@univerjs-pro/sheets-shape/facade'

import '@univerjs-pro/sheets-shape-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsShapeUIZhCN, 
    ),
  },
})

univer.registerPlugin(UniverSheetsShapePlugin) 
univer.registerPlugin(UniverSheetsShapeUIPlugin)

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

Facade API

导入

插件模式说明

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

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

插入基础形状

通过 FWorksheet.newShape 创建形状构建器，然后调用 FWorksheet.insertShape 插入形状。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const rectShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(1, 1, 0, 0)
  .setWidth(240)
  .setHeight(120)
  .setShapeSolidFill('#e6f4ff')
  .setStrokeColor('#1677ff')
  .setStrokeWidth(2)
  .build()

await fWorksheet.insertShape(rectShape)

插入并连接连接线形状

通过 FWorksheet.newConnector 创建连接线，再使用 FWorksheet.connectShapes 将连接线两端挂接到目标形状的连接点。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const leftShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect)
  .setPosition(1, 1, 0, 0)
  .setWidth(180)
  .setHeight(80)
  .setShapeSolidFill('#f6ffed')
  .setStrokeColor('#52c41a')
  .build()
await fWorksheet.insertShape(leftShape)

const rightShape = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Diamond)
  .setPosition(1, 5, 0, 0)
  .setWidth(180)
  .setHeight(120)
  .setShapeSolidFill('#fffbe6')
  .setStrokeColor('#faad14')
  .build()
await fWorksheet.insertShape(rightShape)

const connector = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setPosition(2, 3, 0, 0)
  .setWidth(220)
  .setHeight(40)
  .setStartArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setEndArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setStrokeColor('#595959')
  .setStrokeWidth(2)
  .build()
await fWorksheet.insertShape(connector)

const shapes = fWorksheet.getShapes()
const basicShapes = shapes.filter(shape => !shape.isLineShape())
const connectorShape = shapes.find(shape => shape.isLineShape())

if (connectorShape && basicShapes.length >= 2) {
  await fWorksheet.connectShapes({
    connector: connectorShape,
    startTarget: { shape: basicShapes[0], connectionSiteIndex: 0 },
    endTarget: { shape: basicShapes[1], connectionSiteIndex: 2 },
  })
}

更新和删除形状

通过 FWorksheet.updateShape 更新已有形状，通过 FWorksheet.removeShape 删除形状。

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const shapes = fWorksheet.getShapes()
const firstShape = shapes.find(shape => !shape.isLineShape())

if (firstShape) {
  const updatedShape = fWorksheet.newShape(firstShape)
    .setStrokeColor('#ff4d4f')
    .setStrokeWidth(3)
    .setShapeSolidFill('#fff1f0')
    .build()

  await fWorksheet.updateShape(updatedShape)

  // 如有需要，可在更新后删除该形状
  await fWorksheet.removeShape(firstShape)
}

形状