Connector Shape

Packages	`@univerjs-pro/sheets-shape`

PRO

The connector shape builder. It extends FShape and adds connector-specific properties such as start/end arrow types and sizes. Use fWorksheet.newConnector() to create a new connector builder.

Overview

@univerjs-pro/sheets-shape

Method	Description
`build`	Builds the connector shape builder info
`drawId`	-
`getAdjustPoints`	Returns the adjust points (adjust handles) for this shape
`getConnectionSites`	Returns the connection sites (points where connectors can attach) for this shape
`getConnectorLinePoints`	Returns the connector line points for a line/connector shape
`getEndConnectInfo`	Returns the end connection info for this connector shape
`getPosition`	Returns the absolute pixel position of this shape's top-left corner
`getShapeData`	Returns the shape data containing fill and stroke styles
`getShapeId`	Returns the unique identifier of this shape
`getShapeType`	Returns the type of this shape
`getSize`	Returns the size of this shape in pixels
`getStartConnectInfo`	Returns the start connection info for this connector shape
`height`	-
`isLineShape`	Returns whether this shape is a line/connector shape (e
`setAbsolutePosition`	Sets the position by absolute pixel coordinates
`setEndArrowSize`	Sets the end arrow size of the connector line
`setEndArrowType`	Sets the end arrow type of the connector line
`setHeight`	Sets the height of the shape in pixels
`setNoneFill`	Removes the fill from the shape, making it transparent
`setPosition`	Sets the position, changing where the shape appears on the sheet
`setShapeGradientFill`	Sets the gradient fill style for the shape
`setShapeSolidFill`	Sets the solid fill style for the shape
`setShapeType`	Sets the type of the shape
`setStartArrowSize`	Sets the start arrow size of the connector line
`setStartArrowType`	Sets the start arrow type of the connector line
`setStrokeColor`	Sets the stroke color of the shape
`setStrokeLineCapType`	Sets the stroke line cap type of the shape
`setStrokeLineDashType`	Sets the stroke line dash type of the shape
`setStrokeLineJoinType`	Sets the stroke line join type of the shape
`setStrokeLineType`	Sets the stroke line type of the shape
`setStrokeOpacity`	Sets the stroke opacity of the shape
`setStrokeWidth`	Sets the stroke width of the shape
`setWidth`	Sets the width of the shape in pixels
`shapeData`	-
`shapeType`	-
`subUnitId`	-
`unitId`	-
`width`	-
`x`	-
`y`	-

Returns the adjust points (adjust handles) for this shape. Adjust points allow the user to change the geometry of the shape (e.g., corner radius, arrow size). The coordinates are in the shape's local coordinate space.

Signature

getAdjustPoints(): Array<{ x: number; y: number; adjName: string }>

Returns

{ x: number; y: number; adjName: string; }[] — An array of adjust point info, each containing x, y (local coordinates) and adjName (the adjust parameter name).

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

const shape = shapes[0];
const adjustPoints = shape.getAdjustPoints();
console.log('Adjust points:', adjustPoints);

Source: @univerjs-pro/sheets-shape

`getConnectionSites`

Returns the connection sites (points where connectors can attach) for this shape. Connection sites are only available for non-connector (basic) shapes. The coordinates are in the shape's local coordinate space (relative to shape bounds).

Signature

getConnectionSites(): Array<{ x: number; y: number; index: number; ang: number }>

Returns

{ x: number; y: number; index: number; ang: number; }[] — An array of connection site info. Each item contains x, y (local coordinates), index (site index), and ang (angle in 60000ths of a degree).

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

const basicShape = shapes.find((s) => !s.isLineShape());
if (basicShape) {
  const sites = basicShape.getConnectionSites();
  console.log('Connection sites:', sites);
}

Source: @univerjs-pro/sheets-shape

`getConnectorLinePoints`

Returns the connector line points for a line/connector shape. The coordinates are in the shape's local coordinate space. Returns an empty array if this shape is not a connector shape.

Signature

getConnectorLinePoints(): IShapePoint[]

Returns

IShapePoint[] — An array of line points { x, y }.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

const lineShape = shapes.find((s) => s.isLineShape());
if (lineShape) {
  const points = lineShape.getConnectorLinePoints();
  console.log('Connector points:', points);
}

Source: @univerjs-pro/sheets-shape

`getEndConnectInfo`

Returns the end connection info for this connector shape. If this connector's end point is connected to a basic shape, returns the target shape id and connection site index.

Signature

getEndConnectInfo(): IShapeRelationItem | null

Returns

any — The end connection info, or null if not connected.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();
const connector = shapes.find((s) => s.isLineShape());

if (connector) {
  const endInfo = connector.getEndConnectInfo();
  if (endInfo) {
    console.log(`End connected to shape ${endInfo.shapeId} at site ${endInfo.cxnIndex}`);
  }
}

Source: @univerjs-pro/sheets-shape

`getPosition`

Returns the absolute pixel position of this shape's top-left corner.

Signature

getPosition(): { x: number; y: number }

Returns

{ x: number; y: number; } — An object with x and y pixel coordinates.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

if (shapes.length > 0) {
  const pos = shapes[0].getPosition();
  console.log(`Position: (${pos.x}, ${pos.y})`);
}

Source: @univerjs-pro/sheets-shape

`getShapeData`

Returns the shape data containing fill and stroke styles.

Signature

getShapeData(): IShapeData

Returns

IShapeData — The shape data object.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

if (shapes.length > 0) {
  const data = shapes[0].getShapeData();
  console.log('Fill:', data.fill);
  console.log('Stroke:', data.stroke);
}

Source: @univerjs-pro/sheets-shape

`getShapeId`

Returns the unique identifier of this shape.

Signature

getShapeId(): string

Returns

string — The shape id.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

if (shapes.length > 0) {
  console.log('Shape ID:', shapes[0].getShapeId());
}

Source: @univerjs-pro/sheets-shape

`getShapeType`

Returns the type of this shape.

Signature

getShapeType(): ShapeTypeEnum | undefined

Returns

any — The shape type, or undefined if not set.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

if (shapes.length > 0) {
  console.log('Shape type:', shapes[0].getShapeType());
}

Source: @univerjs-pro/sheets-shape

`getSize`

Returns the size of this shape in pixels.

Signature

getSize(): { width: number; height: number }

Returns

{ width: number; height: number; } — An object with width and height in pixels.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

if (shapes.length > 0) {
  const size = shapes[0].getSize();
  console.log(`Size: ${size.width} x ${size.height}`);
}

Source: @univerjs-pro/sheets-shape

`getStartConnectInfo`

Returns the start connection info for this connector shape. If this connector's start point is connected to a basic shape, returns the target shape id and connection site index.

Signature

getStartConnectInfo(): IShapeRelationItem | null

Returns

any — The start connection info, or null if not connected.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();
const connector = shapes.find((s) => s.isLineShape());

if (connector) {
  const startInfo = connector.getStartConnectInfo();
  if (startInfo) {
    console.log(`Start connected to shape ${startInfo.shapeId} at site ${startInfo.cxnIndex}`);
  }
}

Source: @univerjs-pro/sheets-shape

`isLineShape`

Returns whether this shape is a line/connector shape (e.g., straight connector, bent connector, curved connector).

Signature

isLineShape(): boolean

Returns

boolean — true if the shape is a line/connector shape, false otherwise.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const shapes = fWorksheet.getShapes();

for (const shape of shapes) {
  console.log(`Shape ${shape.drawId} is line: ${shape.isLineShape()}`);
}

Source: @univerjs-pro/sheets-shape

Setters & Modifiers

`setAbsolutePosition`

Sets the position by absolute pixel coordinates.

Signature

setAbsolutePosition(x: number, y: number): this

Parameters

x number — No description
y number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setAbsolutePosition(100, 200)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setEndArrowSize`

Sets the end arrow size of the connector line.

Signature

setEndArrowSize(arrowSize: ShapeArrowSizeEnum): this

Parameters

arrowSize ShapeArrowSizeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const connectorInfo = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setEndArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setEndArrowSize(univerAPI.Enum.ShapeArrowSizeEnum.Large)
  .setStrokeWidth(3)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(connectorInfo);

Source: @univerjs-pro/sheets-shape

`setEndArrowType`

Sets the end arrow type of the connector line.

Signature

setEndArrowType(arrowType: ShapeArrowTypeEnum): this

Parameters

arrowType ShapeArrowTypeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const connectorInfo = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setEndArrowType(univerAPI.Enum.ShapeArrowTypeEnum.StealthArrow)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(connectorInfo);

Source: @univerjs-pro/sheets-shape

`setHeight`

Sets the height of the shape in pixels.

Signature

setHeight(height: number): this

Parameters

height number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setWidth(300)
  .setHeight(200)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setNoneFill`

Removes the fill from the shape, making it transparent.

Signature

setNoneFill(): this

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setNoneFill()
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setPosition`

Sets the position, changing where the shape appears on the sheet. anchorRowPos and anchorColPos are 0-indexed.

Signature

setPosition(anchorRowPos: number, anchorColPos: number, rowOffset: number, columnOffset: number): this

Parameters

anchorRowPos number — No description
anchorColPos number — No description
rowOffset number — No description
columnOffset number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(2, 5, 20, 20)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setShapeGradientFill`

Sets the gradient fill style for the shape.

Signature

setShapeGradientFill(shapeGradientType: ShapeGradientTypeEnum, colorStops: Array<{ position: number; color: string }>, gradientAngle?: number): this

Parameters

shapeGradientType ShapeGradientTypeEnum — No description
colorStops { position: number; color: string; }[] — No description
gradientAngle number (optional) — No description

Returns

this — this builder, for chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Gradient fill with angle and color stops
const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setShapeGradientFill(
    univerAPI.Enum.ShapeGradientTypeEnum.Linear,
    [
      { position: 0, color: '#ff0000' },
      { position: 0.5, color: '#00ff00' },
      { position: 1, color: '#0000ff' },
    ],
    90,
  )
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setShapeSolidFill`

Sets the solid fill style for the shape.

Signature

setShapeSolidFill(color: string, opacity?: number): this

Parameters

color string — No description
opacity number (optional) — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setShapeSolidFill('#f0f000', 0.8)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setShapeType`

Sets the type of the shape.

Signature

setShapeType(shapeType: ShapeTypeEnum): this

Parameters

shapeType ShapeTypeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStartArrowSize`

Sets the start arrow size of the connector line.

Signature

setStartArrowSize(arrowSize: ShapeArrowSizeEnum): this

Parameters

arrowSize ShapeArrowSizeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const connectorInfo = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setStartArrowType(univerAPI.Enum.ShapeArrowTypeEnum.OvalArrow)
  .setStartArrowSize(univerAPI.Enum.ShapeArrowSizeEnum.Large)
  .setPosition(1, 1, 0, 0)
  .setWidth(200)
  .build();
await fWorksheet.insertShape(connectorInfo);

Source: @univerjs-pro/sheets-shape

`setStartArrowType`

Sets the start arrow type of the connector line.

Signature

setStartArrowType(arrowType: ShapeArrowTypeEnum): this

Parameters

arrowType ShapeArrowTypeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const connectorInfo = fWorksheet.newConnector()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.StraightConnector1)
  .setStartArrowType(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(connectorInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeColor`

Sets the stroke color of the shape.

Signature

setStrokeColor(color: string): this

Parameters

color string — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeColor('#ff0000')
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeLineCapType`

Sets the stroke line cap type of the shape.

Signature

setStrokeLineCapType(lineCapType: ShapeLineCapEnum): this

Parameters

lineCapType ShapeLineCapEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeLineCapType(univerAPI.Enum.ShapeLineCapEnum.Round)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeLineDashType`

Sets the stroke line dash type of the shape.

Signature

setStrokeLineDashType(lineDashType: ShapeLineDashEnum): this

Parameters

lineDashType ShapeLineDashEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeLineDashType(univerAPI.Enum.ShapeLineDashEnum.Dash)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeLineJoinType`

Sets the stroke line join type of the shape.

Signature

setStrokeLineJoinType(lineJoinType: ShapeLineJoinEnum): this

Parameters

lineJoinType ShapeLineJoinEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeLineJoinType(univerAPI.Enum.ShapeLineJoinEnum.Round)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeLineType`

Sets the stroke line type of the shape.

Signature

setStrokeLineType(lineType: ShapeLineTypeEnum): this

Parameters

lineType ShapeLineTypeEnum — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeLineType(univerAPI.Enum.ShapeLineTypeEnum.SolidLine)
  .setStrokeColor('#000000')
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeOpacity`

Sets the stroke opacity of the shape.

Signature

setStrokeOpacity(opacity: number): this

Parameters

opacity number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeColor('#ff0000')
  .setStrokeOpacity(0.5)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setStrokeWidth`

Sets the stroke width of the shape.

Signature

setStrokeWidth(width: number): this

Parameters

width number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setStrokeWidth(3)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);

Source: @univerjs-pro/sheets-shape

`setWidth`

Sets the width of the shape in pixels.

Signature

setWidth(width: number): this

Parameters

width number — No description

Returns

this — this builder, for chaining.

Examples

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

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setWidth(300)
  .setHeight(200)
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertShape(shapeInfo);