# FSheetShape

> Language fallback: requested `zh-CN`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/zh-CN/reference/facade/sheet-shape](https://docs.univer.ai/zh-CN/reference/facade/sheet-shape)

- Agent Markdown: [https://docs.univer.ai/zh-CN/reference/facade/sheet-shape.md](https://docs.univer.ai/zh-CN/reference/facade/sheet-shape.md)

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/sheet-shape.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/sheet-shape.mdx)

---

A shape attached to a worksheet. Use this class to control its cell anchoring, and the inherited [`FShape`](https://docs.univer.ai/zh-CN/reference/facade/shape.md) methods for geometry, styling, text, and other shape operations.

## Access

Access through:

* [`FWorksheet.insertShape()`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#insertshape)
* [`FWorksheet.getShape()`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#getshape)
* [`FWorksheet.getShapes()`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#getshapes)

## Inheritance

Extends [`FShape`](https://docs.univer.ai/zh-CN/reference/facade/shape.md). Its inherited members are available on this object.

## Setup

Register [`@univerjs-pro/sheets-shape`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/sheets-shape.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/sheets-shape/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/sheets-shape`

### `FSheetShape.getPlacement`

Returns this Shape's current Sheet placement.

Position is OneCell (`from + width + height`), Both is TwoCell
(`from + to`), and None is an absolute Sheet rectangle.

```typescript
getPlacement(): ISheetDrawingPlacement | null
```

**Returns**

The current placement, or `null` when the Shape no longer exists.

**Examples**

```ts
const workbook = univerAPI.getActiveWorkbook()
const worksheet = workbook?.getActiveSheet()
const shape = worksheet?.getShapes()[0]
console.log(shape?.getPlacement())
```

**Types:** [`ISheetDrawingPlacement`](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/services/sheet-drawing-placement.d.ts)

**Package:** [`@univerjs-pro/sheets-shape`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/sheets-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-shape@1.0.0-rc.0/lib/types/facade/f-shape.d.ts)

### `FSheetShape.setPlacement`

Updates this Shape's Sheet placement through `SetSheetDrawingPlacementCommand`.

Use exact markers when the caller owns the cell relationship. Use
`{ kind, bounds }` when the caller owns a rectangle and wants Univer to
infer the markers from the current Sheet grid. Position is appropriate
for a fixed-size object that moves with its start cell; Both is
appropriate when both position and size follow the grid; None is
appropriate for a free absolute object.

```typescript
setPlacement(placement: ISheetDrawingPlacementInput): boolean
```

**Parameters**

* `placement` — Required. Exact markers or model-space bounds with an explicit anchor type.

**Returns**

Whether the command succeeded.

**Examples**

Position inferred from bounds

```ts
shape.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
  bounds: { left: 120, top: 80, width: 240, height: 120 },
})
```

Position with exact marker

```ts
shape.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,
  from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
  width: 240,
  height: 120,
})
```

Both inferred from bounds

```ts
shape.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
  bounds: { left: 120, top: 80, width: 360, height: 180 },
})
```

Both with exact markers

```ts
shape.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
  from: { row: 2, column: 2, rowOffset: 8, columnOffset: 8 },
  to: { row: 8, column: 6, rowOffset: 0, columnOffset: 0 },
})
```

Absolute

```ts
shape.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.None,
  left: 640,
  top: 96,
  width: 240,
  height: 120,
})
```

**Types:** [`ISheetDrawingPlacementInput`](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/services/sheet-drawing-placement.d.ts)

**Package:** [`@univerjs-pro/sheets-shape`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/sheets-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-shape@1.0.0-rc.0/lib/types/facade/f-shape.d.ts)

### `FSheetShape.setPosition`

Sets the Shape position from a zero-based Sheet cell anchor and pixel offsets.

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

**Parameters**

* `anchorRowPos` — Required. Row containing the Shape's top edge.
* `anchorColPos` — Required. Column containing the Shape's left edge.
* `rowOffset` — Required. Vertical pixel offset from the row's top edge.
* `columnOffset` — Required. Horizontal pixel offset from the column's left edge.

**Returns**

This Shape, for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
})
fShape.setPosition(6, 6, 10, 10)
```

**Package:** [`@univerjs-pro/sheets-shape`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/sheets-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-shape@1.0.0-rc.0/lib/types/facade/f-shape.d.ts)