Web SDK

편집 기록

Plugin 정보

필드, 레코드 또는 뷰를 변경한 뒤 기록을 열면 이전 버전을 살펴보고 변경 사항을 비교하며, 권한이 있는 경우 버전을 복원할 수 있습니다. 기록은 서버에 영구 저장된 버전을 읽습니다. 실행 취소와 다시 실행은 현재 편집 세션에 적용되며 기록 서비스가 필요하지 않습니다.

공동 편집 및 기록 서비스 준비

공동 편집 통합과 라이선스 설정을 완료하세요. 두 세션에서 같은 Bases 문서를 편집할 수 있고 다시 로드해도 변경 사항이 유지되는지 확인하세요.

Office 공동 편집 확장과 기록 예제에 따라 기록 저장소와 권한을 연결하세요. 핵심 공동 편집 기능만으로 기록이 자동 활성화되지는 않습니다. 백엔드는 기록 목록, 버전 내용, 복원도 지원해야 합니다.

기록 플러그인 추가

기존 제품, 라이선스, 공동 편집 설정에 다음을 추가하세요. 프리셋이나 기존 설정이 이미 이 플러그인을 등록한다면 중복 등록하지 말고 해당 설정을 수정하세요.

Shell
pnpm add @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/bases-history @univerjs-pro/bases-history-ui
TypeScript
import { UniverEditHistoryPlugin } from '@univerjs-pro/edit-history'import EditHistoryLocale from '@univerjs-pro/edit-history-ui/locale/en-US'import { UniverBasesHistoryPlugin } from '@univerjs-pro/bases-history'import { UniverBasesHistoryUIPlugin } from '@univerjs-pro/bases-history-ui'import HistoryLocale from '@univerjs-pro/bases-history-ui/locale/en-US'import { LocaleType, mergeLocales } from '@univerjs/core'import '@univerjs-pro/edit-history-ui/lib/index.css'import '@univerjs-pro/bases-history-ui/lib/index.css'const historyServerUrl = '/api/history'univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(EditHistoryLocale, HistoryLocale))univer.registerPlugin(UniverEditHistoryPlugin, { historyServerUrl })univer.registerPlugin(UniverBasesHistoryPlugin)univer.registerPlugin(UniverBasesHistoryUIPlugin, {  univerContainerId: 'app',  historyServerUrl,})

/api/history를 애플리케이션의 기록 엔드포인트로 바꾸고 API가 클라이언트 요청과 일치하는지 확인하세요. 두 historyServerUrl 값은 같아야 합니다. univerContainerId를 편집기 컨테이너의 DOM ID로 설정하고 편집기와 일치하는 언어 팩을 로드하세요.

기록 뷰어는 별도의 읽기 전용 편집기를 생성합니다. 사용자 지정 콘텐츠에는 viewerPlugins를 사용해 뷰어에 아직 포함되지 않은 플러그인을 추가하세요. 내장 뷰어 플러그인을 다시 등록하지 마세요.

버전 보기 및 복원

편집기 메뉴에서 기록을 열고 버전을 선택하여 내용과 변경 사항을 확인하세요. 복원은 현재 공유 문서를 변경합니다. 복원 권한이 있는 사용자만 실행할 수 있어야 하며 서버에서도 이 권한을 강제해야 합니다.

통합을 검증하려면 필드, 레코드 또는 뷰를 변경하고 공동 편집 확인 응답을 기다린 후 기록 목록과 버전 내용을 확인하세요. 애플리케이션을 다시 열고 서비스를 재시작하여 영구 저장 여부를 확인하세요. 이전 버전을 복원한 뒤 다른 브라우저 세션에도 복원된 상태가 전달되는지 확인하세요.

목록이 비어 있으면 먼저 해당 문서의 기록이 생성되었는지 확인하고 문서 ID와 서비스 URL을 확인하세요. 조회는 되지만 복원에 실패한다면 복원 권한과 공동 편집 연결을 확인하세요. 이전 버전에는 삭제된 데이터가 포함될 수 있으므로 기록 읽기에도 권한 검사가 필요합니다.

스냅샷 비교

검토 화면을 만들거나 AI Agent에 변경 정보를 제공하려면 compareUnitData()를 사용하세요. prepareUnitComparison()으로 한 번 계산한 결과를 반복 조회할 수도 있습니다. 제품의 History 플러그인을 등록하고 Facade 진입점을 가져온 뒤, 같은 문서의 완전한 두 스냅샷을 beforeSnapshot과 afterSnapshot으로 전달합니다. 읽기 전용 비교에는 기록 서비스가 필요하지 않으며 내용을 복원하거나 병합하지 않습니다.

TypeScript
import { UnitComparisonDetailLevel, UnitComparisonFidelity } from '@univerjs-pro/edit-history'import { UniverInstanceType } from '@univerjs/core'import '@univerjs-pro/edit-history/facade'const comparison = univerAPI.prepareUnitComparison({  comparisonId: 'review-1',  unitId: beforeSnapshot.id,  type: UniverInstanceType.UNIVER_BASE,  fidelity: UnitComparisonFidelity.SNAPSHOT,  leftData: beforeSnapshot,  rightData: afterSnapshot,})const overview = comparison.query({ detail: UnitComparisonDetailLevel.SUMMARY })const scope = overview.scopes[0]const page = comparison.query({ scope, offset: 0, limit: 100 })console.log(page.items, page.page.hasMore, page.diagnostics)

scopes에서 사용 가능한 뷰를 찾고 선택한 범위를 query()에 전달하면 다시 계산하지 않고 결과를 필터링할 수 있습니다. 기본값은 100개이며 페이지당 최대 1,000개입니다. page.hasMore와 offset으로 다음 항목을 가져오세요. summary는 필터와 관계없이 전체 비교를 나타냅니다. diagnostics.readiness와 diagnostics.codes를 확인해 정확도가 저하된 결과를 완전한 비교로 취급하지 마세요. 편집기가 없는 Node.js 또는 CLI에서는 헤드리스 비교 API를 사용하세요.

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.