# 요소

- Human documentation: [https://docs.univer.ai/ko-KR/guides/boards/features/core/elements](https://docs.univer.ai/ko-KR/guides/boards/features/core/elements)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/boards/features/core/elements.md](https://docs.univer.ai/ko-KR/guides/boards/features/core/elements.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [boards/features/core/elements.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/features/core/elements.ko-KR.mdx)

---

요소는 텍스트, 이미지, 도형, 커넥터처럼 Board에 표시되는 콘텐츠입니다. `FBoard` facade를 통한 요소 변경은 일반 명령 경로를 사용하므로 실행 취소, 다시 실행 및 공동 작업에 포함됩니다.

## 요소 읽기

활성 페이지를 읽기 전에 활성 Board를 가져옵니다. 전체 내부 스냅샷에 의존하지 않고 안정적인 ID, 유형, 경계 및 순서가 필요하면 설명자를 사용합니다.

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

const elements = board.describeElements()
const shapes = board.findElements({
  elementType: univerAPI.Enum.BoardElementType.Shape,
})
```

## 도형 및 텍스트 삽입

저수준 요소 스냅샷을 직접 만드는 대신 의미에 맞는 삽입 메서드를 사용하세요. `insertShape`의 기하 정보는 `transform`에 지정하며, 반환된 도형 핸들에서 텍스트와 스타일 API를 사용할 수 있습니다.

```ts
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 80, top: 80, width: 180, height: 100 },
  name: 'Review card',
})
if (!shape) throw new Error('Cannot insert shape')

shape.getText().setText('Review')
shape.setRotation(6)
```

독립 텍스트에는 `insertText`, 이미지에는 `insertImage`, 여러 요소를 하나의 명령으로 추가할 때는 일괄 메서드를 사용합니다.

## 도형 텍스트 편집

아래 또는 앞의 예제에서 `insertShape()`가 반환한 도형을 사용합니다. `getText()`는 실시간 [FShapeText](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md) 객체를 반환합니다. `getPlainText()`로 텍스트를 읽고, `setText()`로 전체 텍스트를 바꾸며 글꼴, 색상, 정렬을 설정할 수 있습니다.

```ts
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()`에 전달합니다. 빌더를 수정하는 것만으로는 반영되지 않습니다. [텍스트 스타일](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md#settextstyle)과 [텍스트 상자 여백 및 레이아웃](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md#settextboxoptions)도 참고하세요.

```ts
const richText = univerAPI.newRichText()
  .text('Quarterly ')
  .bold('review')
shapeText.setRichText(richText)
```

## 요소 연결

커넥터를 기존 요소 ID에 연결할 수 있습니다. 나중에 스타일, 레이블 또는 끝점을 수정하려면 반환된 커넥터나 ID를 보관하세요.

```ts
const target = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 360, top: 80, width: 180, height: 100 },
})
if (!target) throw new Error('Cannot insert target')

const connector = board.insertConnector({
  fromElementId: shape.getId(),
  toElementId: target.getId(),
  style: { endMarker: { type: 'filledTriangle', size: 'md' } },
})
if (!connector) throw new Error('Cannot insert connector')
```

## 요소 변형 및 배치

필요한 속성만 변경하세요. 쌓임 순서, 정렬, 분배 및 자동 레이아웃 메서드도 요소 ID를 받습니다.

```ts
if (!board.setElementTransform(shape.getId(), { left: 120, top: 140, rotation: 12 })) {
  throw new Error('Cannot transform shape')
}

if (!board.bringElementsToFront([shape.getId()])) {
  throw new Error('Cannot bring shape to front')
}
```

## 요소 삭제

요소 하나에는 `removeElement`, 여러 요소의 원자적 삭제에는 `removeElements`를 사용합니다. 두 메서드 모두 명령 성공 여부를 반환합니다.

```ts
if (!board.removeElements([connector.id, target.getId()])) {
  throw new Error('Cannot remove elements')
}
```

프레임 그룹과 스윔레인은 [컨테이너 및 스윔레인](https://docs.univer.ai/ko-KR/guides/boards/features/core/containers.md)을 참고하세요. [Boards facade 레퍼런스](https://docs.univer.ai/ko-KR/reference/facade/board.md)와 [Board 요소 데이터 모델](https://docs.univer.ai/ko-KR/guides/boards/model/board-elements.md)도 확인할 수 있습니다.