# FPageElement

- Human documentation: [https://docs.univer.ai/reference/facade/page-element](https://docs.univer.ai/reference/facade/page-element)

- Agent Markdown: [https://docs.univer.ai/reference/facade/page-element.md](https://docs.univer.ai/reference/facade/page-element.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

The facade class for a slide page element.

## Setup

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

## `@univerjs-pro/slides`

### `FPageElement.getData`

Get the raw slide element data.

```typescript
getData(): T
```

**Returns**

The slide element data.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
if (element && 'getType' in element) {
  console.log(element.getData())
}
```

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

### `FPageElement.getId`

Get the element id.

```typescript
getId(): string
```

**Returns**

The element id.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const elements = fSlide.getElements()
console.log(elements[0]?.getId())
```

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

### `FPageElement.getPermission`

Returns this ordinary Slide element's permission facade.

```typescript
getPermission(): FSlideObjectPermission
```

**Returns**

Permission facade combining Presentation, Slide, and Element Edit points.

**Examples**

```ts
const element = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getElements()[0]
if (!element) throw new Error('Slide element not found.')
await element.getPermission().setReadOnly()
```

**Types:** [`FSlideObjectPermission`](https://docs.univer.ai/reference/facade/slide-object-permission.md)

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

### `FPageElement.getRichText`

Returns this element's text as a detached rich-text value.

Text and placeholder elements are supported. Legacy plain text is normalized to the same document model.
Shapes returned by `FSlide.getElements()` use the common Shape facade and expose rich text through
`FShape.getText().getRichText()`. Images, groups, and other non-text elements return `null`.

Call `RichTextValue.copy` before editing. The detached builder can update text-run lengths without changing
this slide until it is passed to `setRichText`.

```typescript
getRichText(): RichTextValue | null
```

**Returns**

A detached rich-text value, or `null` when this element cannot contain text.

**Examples**

```ts
const presentation = univerAPI.getActivePresentation()
if (!presentation) throw new Error('No active presentation')

const slide = presentation.getSlideByIndex(0)
if (!slide) throw new Error('The presentation has no slides')
for (const element of slide.getElements()) {
  const richText = (
    'getType' in element ? element.getRichText() : element.getText().getRichText()
  )?.copy()
  if (!richText) continue

  for (const paragraph of richText.getParagraphs()) {
    for (const run of paragraph.getTextRuns()) {
      console.log(run.getText())
    }
  }
}
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

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

### `FPageElement.getTransform`

Get the transform of this element.

```typescript
getTransform(): ISlideDrawingTransform
```

**Returns**

The transform data, including position, size, rotation, and flip state.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
console.log(element.getTransform())
```

**Types:** [`ISlideDrawingTransform`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

### `FPageElement.getType`

Get the element type.

```typescript
getType(): T['type']
```

**Returns**

The slide element type.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
if (element && 'getType' in element) {
  console.log(element.getType())
}
```

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

### `FPageElement.setDescription`

Set the element description.

```typescript
setDescription(description: string): this
```

**Parameters**

* `description` — Required. The element description, usually used as accessibility text.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setDescription('Company logo')
```

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

### `FPageElement.setName`

Set the element name.

```typescript
setName(name: string): this
```

**Parameters**

* `name` — Required. The element name.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setName('Title shape')
```

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

### `FPageElement.setPosition`

Set the element position by absolute slide coordinates.

```typescript
setPosition(left: number, top: number): this
```

**Parameters**

* `left` — Required. The x-coordinate of the element's top-left corner.
* `top` — Required. The y-coordinate of the element's top-left corner.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
if (element && 'getType' in element) {
  element.setPosition(80, 120)
}
```

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

### `FPageElement.setRichText`

Replaces this element's text document with a detached rich-text value.

Only text content and its document metadata are replaced. The existing element transform, size, rotation, fill,
stroke, text-box padding, wrapping, direction, and auto-fit behavior are preserved. The live update is executed
through `UpdateSlideDrawingCommand`, so it participates in the standard Slide command/mutation and undo-redo path.

```typescript
setRichText(richText: RichTextValue): this
```

**Parameters**

* `richText` — Required. Rich text normally obtained from `getRichText().copy()` or `univerAPI.newRichText()`.

**Returns**

This element for chaining.

**Throws**

When this element type cannot contain text.

**Examples**

```ts
const presentation = univerAPI.getActivePresentation()
if (!presentation) throw new Error('No active presentation')

const slide = presentation.getSlideByIndex(0)
if (!slide) throw new Error('The presentation has no slides')
for (const element of slide.getElements()) {
  const richText = (
    'getType' in element ? element.getRichText() : element.getText().getRichText()
  )?.copy()
  if (!richText) continue

  for (const paragraph of richText.getParagraphs()) {
    for (const run of paragraph.getTextRuns()) {
      // The agent supplies the new value directly. It may be longer or shorter.
      run.setText('New English text')
    }
  }

  if ('getType' in element) {
    element.setRichText(richText)
  } else {
    element.getText().setRichText(richText)
  }
}
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

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

### `FPageElement.setSelectable`

Set whether the element can be selected.

```typescript
setSelectable(selectable: boolean): this
```

**Parameters**

* `selectable` — Required. Whether the element can be selected.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setSelectable(false)
```

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

### `FPageElement.setSize`

Set the element size.

```typescript
setSize(width: number, height: number): this
```

**Parameters**

* `width` — Required. The element width.
* `height` — Required. The element height.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setSize(320, 180)
```

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

### `FPageElement.setTransform`

Update the transform of this element.

```typescript
setTransform(transform: Partial<ISlideDrawingTransform>): this
```

**Parameters**

* `transform` — Required. The transform fields to update.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setTransform({ left: 80, top: 120, width: 320, height: 180 })
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`ISlideDrawingTransform`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

### `FPageElement.setVisible`

Set whether the element is visible.

```typescript
setVisible(visible: boolean): this
```

**Parameters**

* `visible` — Required. Whether the element is visible.

**Returns**

This element, for chaining.

**Examples**

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const element = fSlide.getElements()[0]
element.setVisible(false)
```

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

## `@univerjs-pro/slides-thread-comment`

### `FPageElement.createCommentAsync`

Creates a comment anchored to this slide element.

```typescript
createCommentAsync(content: ThreadComment.ThreadCommentContent, options?: ISlideCommentCreateOptions): Promise<boolean>
```

**Parameters**

* `content` — Required. Plain text or a Univer document body for rich comment content.
* `options` — Optional. Default: `{}`. Optional stable IDs, author, attachments, and creation time.

**Returns**

`true` when the create command succeeds; otherwise, `false`.

**Throws**

If the content is empty.

**Examples**

```ts
const element = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getElements()[0]
await element?.createCommentAsync('Check this element.', { id: 'review-element-1' })
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`ISlideCommentCreateOptions`](https://unpkg.com/@univerjs-pro/slides-thread-comment@1.0.0-rc.0/lib/types/facade/f-slide.d.ts)

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

### `FPageElement.getComments`

Returns locally loaded comments anchored to this slide element.

```typescript
getComments(): ThreadComment.IFacadeThreadCommentInfo[]
```

**Returns**

Matching comment threads for this exact element ID.

**Examples**

```ts
const element = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getElements()[0]
console.log(element?.getComments().length ?? 0)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts)

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

### `FPageElement.listCommentsAsync`

Synchronizes known threads and returns comments anchored to this slide element.

```typescript
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Returns**

A promise resolving to matching synchronized comment threads.

**Examples**

```ts
const element = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getElements()[0]
const comments = element ? await element.listCommentsAsync() : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

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