# 도형

- Human documentation: [https://docs.univer.ai/ko-KR/guides/sheets/features/shapes](https://docs.univer.ai/ko-KR/guides/sheets/features/shapes)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/sheets/features/shapes.md](https://docs.univer.ai/ko-KR/guides/sheets/features/shapes.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/engine-formula"
    },
    {
      "client": "@univerjs/drawing"
    },
    {
      "client": "@univerjs/drawing-ui",
      "locale": "@univerjs/drawing-ui/locale/en-US",
      "style": "@univerjs/drawing-ui/lib/index.css"
    },
    {
      "client": "@univerjs/sheets-drawing"
    },
    {
      "client": "@univerjs/sheets-drawing-ui",
      "locale": "@univerjs/sheets-drawing-ui/locale/en-US",
      "style": "@univerjs/sheets-drawing-ui/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-shape"
    },
    {
      "client": "@univerjs-pro/sheets-shape-ui",
      "facade": "@univerjs-pro/sheets-shape/facade",
      "locale": "@univerjs-pro/sheets-shape-ui/locale/en-US",
      "style": "@univerjs-pro/sheets-shape-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Univer Sheets의 도형을 사용하면 워크시트에서 직접 순서도, 주석, 설명선, 시각적 안내를 만들 수 있습니다.

> Interactive example: [Open the playground](/playground/sheets/shapes)

## 플러그인 모드

### 설치

#### npm

```bash
npm install @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui
```

#### yarn

```bash
yarn add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui
```

#### bun

```bash
bun add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui
```

> [!WARN]
> 도형에는 `@univerjs-pro/engine-formula`의 `UniverProFormulaEnginePlugin`도 필요합니다. 기본 초기화 코드에서 기존 `UniverFormulaEnginePlugin`의 가져오기와 등록을 이 플러그인으로 교체하세요. 두 수식 엔진을 함께 등록하면 도형을 삽입할 때 의존성 미등록 오류가 발생할 수 있습니다.
> 
> 도형 플러그인은 드로잉 플러그인에 의존합니다. 도형 플러그인을 등록하기 전에 `UniverDrawingPlugin`, `UniverSheetsDrawingPlugin`, `UniverDrawingUIPlugin`, `UniverSheetsDrawingUIPlugin`도 등록해야 합니다.

### 사용법

```typescript
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula' // [!code ++]
import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape' // [!code ++]
import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui' // [!code ++]
import SheetsShapeUIEnUS from '@univerjs-pro/sheets-shape-ui/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverDrawingPlugin } from '@univerjs/drawing' // [!code ++]
import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui' // [!code ++]
import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US' // [!code ++]
import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing' // [!code ++]
import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui' // [!code ++]
import SheetsDrawingUIEnUS from '@univerjs/sheets-drawing-ui/locale/en-US' // [!code ++]

import '@univerjs-pro/sheets-shape/facade' // [!code ++]

import '@univerjs/drawing-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-drawing-ui/lib/index.css' // [!code ++]
import '@univerjs-pro/sheets-shape-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      DrawingUIEnUS, // [!code ++]
      SheetsDrawingUIEnUS, // [!code ++]
      SheetsShapeUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverProFormulaEnginePlugin) // [!code ++]
univer.registerPlugin(UniverDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverDrawingUIPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingUIPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsShapePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsShapeUIPlugin) // [!code ++]
```

Univer 상용 라이선스가 있다면 [클라이언트에서 라이선스 사용](https://docs.univer.ai/ko-KR/server/license.md#in-plugin-mode)을 참고하여 설정하세요.

## 모바일 지원

먼저 [모바일 에디터](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md#mobile-support)를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 **문서를 열기 전에** 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

| 패키지                             | 데스크톱 등록                       | 모바일 등록                              |
| ------------------------------- | ----------------------------- | ----------------------------------- |
| `@univerjs/drawing-ui`          | `UniverDrawingUIPlugin`       | `UniverDrawingMobileUIPlugin`       |
| `@univerjs/sheets-drawing-ui`   | `UniverSheetsDrawingUIPlugin` | `UniverSheetsDrawingMobileUIPlugin` |
| `@univerjs-pro/sheets-shape-ui` | `UniverSheetsShapeUIPlugin`   | `UniverSheetsShapeMobileUIPlugin`   |

## 프리셋 모드

도형 기능은 `@univerjs/preset-sheets-advanced` 프리셋에 포함되어 있습니다. 이 프리셋은 이미 `UniverProFormulaEnginePlugin`을 등록하므로 수식 엔진을 수동으로 교체할 필요가 없습니다.

### 설치

> [!NOTE]
> `@univerjs/preset-sheets-advanced`의 `UniverSheetsAdvancedPreset` 프리셋은 런타임에 `UniverSheetsDrawingPreset` 프리셋에 의존합니다. 먼저 `@univerjs/preset-sheets-drawing`을 설치하세요.

#### npm

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

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 사용법

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

Univer 상용 라이선스가 있다면 [클라이언트에서 라이선스 사용](https://docs.univer.ai/ko-KR/server/license.md#in-preset-mode)을 참고하여 설정하세요.

## Facade API

전체 Facade API 타입 정의는 [FacadeAPI](https://docs.univer.ai/ko-KR/reference/facade/univer.md)에서 확인할 수 있습니다.

### 가져오기

> [!INFO: 플러그인 모드 참고 사항]
> Facade 패키지를 수동으로 가져와야 하는 것은 플러그인 모드뿐입니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

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

### 기본 도형 삽입

공통 도형 생성 데이터를 `FWorksheet.insertShape`에 전달합니다. 활성 Facade 핸들이 반환됩니다.

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

const rectShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 80, width: 240, height: 120 },
  shapeData: {
    fill: {
      fillType: univerAPI.Enum.ShapeFillEnum.SolidFill,
      color: '#e6f4ff',
    },
    stroke: {
      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
      color: '#1677ff',
      width: 2,
    },
  },
})

if (!rectShape) throw new Error('Shape could not be inserted.')
```

### 도형 텍스트 편집

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

```ts
if (!rectShape) throw new Error('Shape is not available')
const shapeText = rectShape.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)
```

### 커넥터 도형 삽입 및 연결

`FWorksheet.insertShape`로 커넥터를 삽입한 뒤 반환된 `FConnectorShape` Facade에서 양 끝을 연결합니다.

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

const leftShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 80, top: 80, width: 180, height: 100 },
})
const rightShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse,
  transform: { left: 420, top: 200, width: 180, height: 100 },
})
const connectorShape = fWorksheet.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.BentConnector3,
  transform: { left: 240, top: 130, width: 240, height: 120 },
})

if (!leftShape || !rightShape || !connectorShape) {
  throw new Error('Shapes could not be inserted.')
}

const startSite = leftShape.getConnectionSites()[0]
const rightSites = rightShape.getConnectionSites()
const endSite = rightSites[2] ?? rightSites[0]

if (!startSite || !endSite) throw new Error('Connection site not found.')

connectorShape
  .bindStart(leftShape.getId(), startSite.index)
  .bindEnd(rightShape.getId(), endSite.index)
  .setEndArrow(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)
```

### 도형 업데이트 및 제거

도형의 업데이트와 제거는 활성 Facade 핸들에서 직접 수행합니다.

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

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

if (firstShape) {
  firstShape
    .setStrokeColor('#ff4d4f')
    .setStrokeWidth(3)
    .setSolidFill('#fff1f0')

  // Remove the shape after update if needed
  const removed = firstShape.remove()
  console.log(removed)
}
```

## 도형 서식 복사

원본 도형을 선택하고 서식 복사를 활성화한 뒤 대상 도형을 선택하세요. 채우기, 선, 효과 및 지원되는 텍스트 서식을 복사하고 대상 ID, 기하 정보, 텍스트 내용 및 수식 연결은 유지합니다. 서식 지우기는 삽입 기본값을 복원합니다. SmartArt는 제외되며 해당 도형 UI 플러그인이 기능을 자동 등록합니다.