협업 문서를 서버에 저장하고 함께 편집할지, 아니면 오프라인에서 파일을 변환할지에 따라 Univer의 unitId와 Snapshot 중 적합한 경로가 달라집니다. 두 방식의 서버 의존성, CSV와 TSV의 범위, 실제 문서로 왕복 검증하는 절차를 살펴봅니다.
공식 가져오기·내보내기 안내는 문서 처리 경로를 unitId와 Snapshot 두 가지로 구분합니다(Univer 공식 안내). 서버에 문서를 저장하고 협업 편집까지 이어 갈 SaaS라면 unitId를, 협업 문서가 필요 없는 오프라인 처리나 파일 변환이라면 Snapshot을 우선 검토하세요. 두 경로 모두 파일 변환 백엔드와 실제 파일 내보내기 검증을 생략할 수는 없습니다.
이 글은 Univer Sheets를 SaaS에 붙이는 프런트엔드 개발자와 풀스택 엔지니어를 위한 선택 기준입니다.
특히 오프라인 처리 도구나 파일 변환 기능을 만들며 Snapshot의 적용 범위를 확인하려는 기술팀에 적합합니다.
협업 문서 흐름에 맞는 unitId 경로
가져온 파일을 협업 편집이 가능한 문서로 관리하려면, 변환 결과를 서버에 저장하고 해당 문서를 식별하는 unitId를 연결하는 흐름이 적합합니다. 공식 문서는 가져오기·내보내기 기능과 협업 환경의 구성을 별도로 안내합니다. 따라서 파일을 읽어 화면에 표시하는 단계뿐 아니라 서버 저장, 문서 접근 권한, 재접속 후 다시 불러오기까지 하나의 문서 수명 주기로 설계해야 합니다.
가져오기가 성공해 unitId가 생성되더라도, 그것만으로 저장과 협업이 자동 구성되는 것은 아닙니다. Univer의 서버 문서와 협업 모듈 안내를 함께 살펴보고, 서비스의 인증 및 문서 접근 방식에 맞춰야 합니다. 빠른 시작 문서도 데이터 저장을 다루므로, 화면 상태와 서버에 저장된 문서 상태를 같은 것으로 간주하지 말고 공식 데이터 저장 설명을 기준으로 확인하세요.
오프라인 변환에 맞는 Snapshot 경로
Snapshot은 협업 문서 식별자를 기준으로 불러오는 대신, 워크북 데이터를 이용해 처리하는 경로입니다. 파일을 가져와 내용을 변환하거나 가공한 뒤 결과 파일을 제공하는 도구처럼, 서버에서 협업 상태를 유지할 필요가 없는 작업에 알맞습니다. Snapshot을 사용한다고 협업 편집 기능을 켜야 하는 것은 아니지만, 파일을 읽고 쓰는 변환 작업에 필요한 백엔드 구성은 별도로 검토해야 합니다.
| 확인 항목 | unitId 경로 | Snapshot 경로 |
|---|---|---|
| 적합한 흐름 | 서버에 문서를 저장하고 협업 편집을 이어 가는 SaaS | 오프라인 처리나 워크북 데이터 변환 |
| 불러올 때 확인할 점 | 가져온 문서의 unitId와 서버 저장 결과 | 가져오기 결과로 얻은 워크북 데이터 |
| 서버 측 점검 | 문서 저장, 접근 권한, 재접속 후 로드 | 파일 변환 요청을 처리할 서버 구성 |
| 내보내기 검증 | 저장 문서에서 파일을 다시 생성하는 흐름 | Snapshot 데이터에서 파일을 생성하는 흐름 |
| 선택 전 질문 | 여러 사용자가 같은 문서를 다시 열어야 하나요? | 문서 협업 없이 파일 결과만 필요하나요? |
Univer의 협업 서비스 구성 안내는 서버 측 가져오기·내보내기 구조를 설명합니다. 이 구조를 확인하지 않고 프런트엔드에서 파일 선택과 화면 표시만 구현하면, 실제 배포 환경에서 내보내기 요청이 처리되지 않거나 저장된 문서와 변환 결과가 연결되지 않는 문제가 생길 수 있습니다.
파일 형식과 변환 범위 구분
CSV와 TSV는 표 데이터를 텍스트 형태로 주고받을 때 유용하지만, 이를 여러 시트와 수식, 그림, 셀 서식을 포함한 전체 워크북의 보존 경로로 가정해서는 안 됩니다. 텍스트 형식으로 표현하기 어려운 워크북 요소가 있기 때문입니다. 따라서 CSV나 TSV를 지원하는지 확인할 때는 가져오기와 내보내기를 따로 살펴보고, 어느 쪽이든 대상 API와 현재 버전의 지원 형식을 확인해야 합니다.
| 파일 흐름 | 기대할 수 있는 범위 | 구현 전 확인할 점 |
|---|---|---|
| CSV 가져오기 | 텍스트 기반 표 데이터의 입력 | 시트 구성, 문자 인코딩, 구분자 처리 |
| TSV 가져오기 | 탭으로 구분된 텍스트 표의 입력 | 셀 안의 탭이나 줄바꿈 처리 |
| CSV·TSV 내보내기 | 대상 형식에 맞춘 표 데이터 출력 | 수식, 그림, 여러 시트, 서식의 표현 한계 |
| XLSX 왕복 | 워크북 형식으로 가져오고 다시 파일 생성 | 시트, 수식, 그림, 서식이 목표 앱에서 유지되는지 |
공식 가져오기·내보내기 문서의 지원 형식 설명을 구현에 사용하는 API와 함께 확인하세요. 형식 목록에 이름이 있다는 사실만으로 모든 워크북 기능이 양방향으로 보존된다고 결론 내리면 안 됩니다. 특히 CSV나 TSV를 다루는 기능과 XLSX 전체 워크북을 왕복하는 기능은 서로 다른 요구사항으로 정의하는 편이 안전합니다.
주의: 가져온 파일이 화면에서 정상적으로 보이는 것과, 저장 후 다시 내보낸 파일이 원본과 호환되는 것은 별개의 검증 항목입니다.
실제 파일로 왕복 검증하기
협업 여부를 정한 다음에는 서비스 사용자가 실제로 올릴 파일을 시험 자료로 삼습니다. Univer의 워크북 및 시트 API 설명은 워크북과 워크시트를 구분해 다루므로, 확인 기록도 파일 하나의 성공 여부에 그치지 않고 시트별로 남기는 것이 좋습니다. 수식 동작은 공식 수식 기능 안내와 대조하되, 특정 파일에서 같은 결과가 나오는지는 대상 환경에서 직접 확인해야 합니다.
- [ ] 서비스에서 받을 파일 형식과 현재 SDK의 가져오기 지원 형식을 대조합니다.
- [ ] 원본 파일의 시트 이름, 시트 구성, 수식 셀, 그림과 주요 서식을 기록합니다.
- [ ] 협업 문서 흐름이면 가져오기 뒤 unitId가 만들어지고 서버에 저장되는지 확인합니다.
- [ ] Snapshot 흐름이면 가져온 워크북 데이터가 변환 및 내보내기 과정에 전달되는지 확인합니다.
- [ ] 서버에서 파일 변환 요청이 처리되고 결과 파일을 내려받을 수 있는지 점검합니다.
- [ ] 내보낸 파일을 목표 사용 환경에서 열어 시트와 그림, 서식 상태를 비교합니다.
- [ ] 수식은 수식 문자열과 계산 결과를 나누어 기록하고, 달라진 항목은 별도 이슈로 남깁니다.
- [ ] CSV나 TSV를 제공한다면 해당 형식에서 표현할 수 없는 항목이 어떻게 처리되는지 확인합니다.
결과 기록에는 “성공”만 적지 말고, 수식 계산 결과의 차이, 서식 변화, 파일 열기 호환성을 각각 분리해 남기세요. 특정 파일이나 환경에서 확인한 결과를 모든 사용자 파일에 대한 보장으로 확대해서는 안 됩니다. SDK나 서버 버전을 바꾸거나 지원 형식 문서가 갱신되면 같은 시험 파일로 다시 검증해야 합니다.
자주 묻는 파일 흐름 질문
XLSX를 가져올 때 unitId와 Snapshot 중 무엇을 선택하나요?
가져온 문서를 서버에 저장하고 사용자가 협업 편집을 이어 가야 한다면 unitId 경로를 우선 검토합니다. 반대로 파일을 읽어 데이터를 가공하거나 변환 결과만 내려받고 협업 상태를 유지할 필요가 없다면 Snapshot 경로가 단순합니다. 어느 쪽이든 현재 SDK와 서버가 해당 파일 형식의 변환을 지원하는지 먼저 확인하고, 실제 서비스 문서로 내보내기 결과를 검증해야 합니다.
Snapshot에 협업 편집 기능이 필요한가요?
Snapshot은 협업 문서를 식별하는 unitId를 사용하는 흐름과 달리, 가져온 워크북 데이터를 이용하는 오프라인 처리나 변환 작업에 적용할 수 있습니다. 협업 기능을 쓰지 않아도 된다는 점과 변환 서버가 필요 없다는 점은 같은 의미가 아닙니다. 내보내기에 사용하는 SDK와 서버 구성이 필요한 변환 기능을 제공하는지 별도로 확인하세요.
XLSX 내보내기에 변환 서버가 필요한 이유는 무엇인가요?
파일 내보내기는 브라우저에 있는 데이터만 전달하는 과정으로 끝나지 않을 수 있습니다. Univer 공식 문서는 가져오기와 내보내기에 변환 백엔드가 필요한 구성을 안내하므로, 화면에서 워크북이 열리는지만 확인해서는 충분하지 않습니다. 서버 연결과 변환 요청 처리, 생성 파일 다운로드까지 한 흐름으로 시험해야 합니다. 구체적인 설정은 사용하는 SDK와 서버 버전의 공식 문서를 기준으로 확인하세요.
여러 시트와 수식이 보존되는지 어떻게 시험하나요?
원본 파일의 시트 구성과 수식 셀, 그림, 표시 형식을 기록한 뒤 가져오기와 저장을 거쳐 다시 내보낸 파일과 항목별로 비교합니다. 수식은 수식 문자열과 계산 결과를 구분하고, 그림과 복잡한 서식은 대상 앱에서도 열어 확인합니다. 모든 파일에서 같은 결과가 난다고 전제하지 말고, 실제 서비스에서 받을 파일을 시험 자료로 사용하세요.
선택 결과가 협업 문서라면 unitId의 저장과 접근 권한을 중심으로, 오프라인 변환이라면 Snapshot에서 파일 생성까지 이어지는 백엔드 흐름을 중심으로 구현을 검토하면 됩니다. 로컬 개발 환경만으로 macOS 전용 브라우저나 앱 동작을 확인하려는 경우에는 장비 유지와 원격 접근 준비가 부담이 될 수 있습니다. 반면 맥 환경 검증이 필요하지 않거나 장기간 안정적인 작업을 같은 환경에서 수행해야 한다면, 맥 렌탈이 꼭 맞는 선택은 아닙니다. 변환 백엔드 구성은 별도로 유지하면서 일시적인 맥 테스트 환경이 필요한 경우에 한해 nuvcloud의 한국 지역 이용 환경과 이용 가능한 맥 환경을 비교해 보세요.
문서 연동을 실제 맥 환경에서 점검해 보세요
유버 문서를 가져오고 내보내는 흐름을 확인하려면 nuvcloud의 전용 클라우드 맥을 활용해 보세요.
공유 가상 환경이 아닌 전용 하드웨어에서 개발과 검증 작업을 안정적으로 진행할 수 있습니다.