# 일반 API

- Human documentation: [https://docs.univer.ai/ko-KR/guides/slides/features/core/general-api](https://docs.univer.ai/ko-KR/guides/slides/features/core/general-api)

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

루트 Facade API는 공통 Univer 런타임과 이 애플리케이션에 등록된 Slides 플러그인을 하나로 결합합니다. 이 페이지에서는 다른 Univer 문서 유형을 사용해 봤다고 가정하지 않고 명령, 이벤트, 기록, Unit 수명 주기를 설명합니다. 프레젠테이션 객체는 [Univer Slides API](https://docs.univer.ai/ko-KR/guides/slides/features/core/slides-api.md)를 참고하세요.

## API 객체 만들기

Univer 인스턴스와 필요한 플러그인을 등록한 후 `FUniver` 래퍼를 만듭니다.

```ts
import { FUniver } from '@univerjs/core/facade'

const univerAPI = FUniver.newAPI(univer)
```

이 호출 전에 가져온 Facade 엔트리는 같은 객체에 Slides 메서드를 추가합니다.

## 명령

`executeCommand()`는 등록된 명령을 비동기로 실행합니다. `syncExecuteCommand()`는 해당 명령이 동기 실행을 명시적으로 지원할 때만 사용하세요. 일반적인 Slides 작업에는 Facade 메서드를 우선 사용합니다.

## 이벤트

```ts
const commandLog = univerAPI.addEvent(
  univerAPI.Event.CommandExecuted,
  ({ id }) => console.log('Executed:', id)
)

// 더 이상 필요하지 않은 리스너를 제거합니다.
commandLog.dispose()
```

명령을 검사하거나 취소해야 할 때는 `BeforeCommandExecute`를 사용합니다. `LifeCycleChanged`는 편집기가 `Rendered`, `Steady` 같은 단계에 도달했음을 알립니다.

## 실행 취소와 다시 실행

실행 취소와 다시 실행은 현재 포커스된 Univer Unit에 적용되며 Promise를 반환합니다.

```ts
await univerAPI.undo()
await univerAPI.redo()
```

Slides Facade 변경은 명령 파이프라인을 사용하므로 지원되는 변경은 같은 기록에 참여합니다.

## 시스템 클립보드

`UniverSlidesUIPlugin`을 등록하고 Slides 캔버스에 포커스를 두면 `copy()`가 현재 선택을 복사하고 `paste()`가 Slides UI 명령으로 클립보드 내용을 삽입합니다.

```ts
import '@univerjs/ui/facade'

await univerAPI.copy()
await univerAPI.paste()
```

캔버스 컨텍스트 메뉴는 일반 붙여넣기, 텍스트로 붙여넣기, 이미지로 붙여넣기를 지원합니다. 텍스트 모드는 편집 가능한 텍스트 상자를 만듭니다. 이미지 모드는 클립보드의 이미지 파일이나 HTML의 이미지 리소스를 사용하며, 임의의 내용을 이미지로 변환하지 않습니다.

도형이나 표의 텍스트를 편집할 때는 **원본 서식 유지**, **대상 서식에 맞춤**, **텍스트만 유지**와 붙여넣기 후 서식 메뉴를 사용할 수 있습니다.

브라우저 편집기 포커스와 클립보드 권한이 필요하며 모델 전용 Node.js 환경에서는 사용할 수 없습니다. 클립보드 읽기가 차단되면 시스템 붙여넣기 단축키를 사용하세요.

## UI

UI Facade는 메시지, 대화상자, 사이드바, 컴포넌트 등록, 기본 UI 영역 제어 기능을 제공합니다.

```ts
univerAPI
  .showMessage({ content: 'Presentation saved', type: 'success' })
  .setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, true)
```

이 메서드는 `UniverUIPlugin`이 필요하며 Slides 편집 컨트롤에는 `UniverSlidesUIPlugin`도 필요합니다.

## WebSocket

WebSocket은 Network Facade의 선택 기능입니다.

```ts
import { UniverNetworkPlugin } from '@univerjs/network'

import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)

const socket = univerAPI.createSocket('wss://example.com/slides')
socket.open$.subscribe(() => socket.send('ready'))
```

메시지 프로토콜, 인증, 재연결, 충돌 처리는 호스트 애플리케이션의 책임입니다.

## 열거형

`univerAPI.Enum`은 공통 열거형과 Slides가 추가한 열거형을 제공합니다.

```ts
const lifecycle = univerAPI.Enum.LifecycleStages.Steady
const transition = univerAPI.Enum.SlideTransitionTypeEnum.Fade
const elementType = univerAPI.Enum.SlidePageElementTypeEnum.Shape
```

## 유틸리티

`univerAPI.Util`은 숫자 서식, 사각형 연산 및 공통 도구 같은 공유 헬퍼를 제공합니다.

```ts
const payload = univerAPI.Util.tools.deepClone({
  slideId: 'slide-1',
  selectedElementIds: ['element-1'],
})
```