CoreXLSX

corexlsx

Excel 스프레드 시트 (XLSX) 형식 파서는 Pure Swift로 작성되었습니다

CoreXLSX는 XML 기반 XLSX 스프레드 시트 형식의 저수준 구조를 나타내는 데 중점을 둔 라이브러리입니다. .xlsx 확장 기능이있는 스프레드 시트 아카이브를 열고 내부 구조를 Swift로 직접 표현 된 모델 유형에 매핑 할 수 있습니다.

이 라이브러리는 .xlsx 형식에 대해서만 읽기 전용 지원을 제공합니다. 이전 레거시 .xls 스프레드 시트 형식은 내부 내부를 완전히 갖추고 있으므로 해당 유형의 파일로 작업 해야하는 경우 다른 라이브러리를 참조하십시오.

.xlsx 파일에서 ECMA-376 Agile 암호화 (가장 인기있는 품종 인 것처럼 보임)를 사용하는 경우 CryptoOffice 라이브러리를 살펴보십시오.

자동으로 생성 된 문서는 GitHub 페이지에서 확인할 수 있습니다.

질문과 친절한 헛소리를 위해 불화에 가입하십시오.

예

예제 프로젝트를 실행하려면 Repo를 복제하고 먼저 예제 디렉토리에서 pod install 실행하십시오.

CoreXLSX 의 모델 유형 직접 XLSX 형식의 내부 구조를 직접 매핑하여 몇 가지 속성에 더 현명한 이름 지정이 적용됩니다. API는 매우 간단합니다.

import CoreXLSX

let filepath = " ./categories.xlsx "
guard let file = XLSXFile ( filepath : filepath ) else {
  fatalError ( " XLSX file at ( filepath ) is corrupted or does not exist " )
}

for wbk in try file . parseWorkbooks ( ) {
  for (name , path ) in try file . parseWorksheetPathsAndNames ( workbook : wbk ) {
    if let worksheetName = name {
      print ( " This worksheet has a name: ( worksheetName ) " )
    }

    let worksheet = try file . parseWorksheet ( at : path )
    for row in worksheet . data ? . rows ?? [ ] {
      for c in row . cells {
        print ( c )
      }
    }
  }
}

이것은 주어진 XLSX 파일의 모든 워크 시트에서 원시 셀 데이터를 인쇄합니다. 구문 분석 파일에서 읽어야 할 더 많은 attributes에 대해서는 Worksheet 모델을 참조하십시오.

셀 참조

cells 어레이의 지수를 통해 세포를 다루지 않아야합니다. 모든 셀에는 reference 속성이 있으며, 주어진 셀이 어디에 있는지 이해하기 위해 읽을 수 있습니다. CellReference struct의 해당 특성은 셀의 정확한 위치를 제공합니다.

빈 셀

.xlsx 형식은 빈 셀과 셀의 부재를 명확하게 구분합니다. cells 어레이를 반복 할 때 셀이나 행이 없으면 문서에 그러한 셀이나 행이 없음을 의미합니다. .xlsx 문서에는 비어있는 셀과 행이 책을 읽을 수 있도록 처음으로 작성해야합니다.

이러한 차이를 만들면 특히 드문 스프레드 시트의 경우 형식을보다 효율적으로 만듭니다. 단일 셀 Z1000000의 스프레드 시트가 있다면 수백만 개의 빈 셀과 값이있는 단일 셀이 포함되어 있지 않습니다. 이 파일은 단일 셀 만 저장하므로 스파 스 스프레드 시트를 신속하게 저장하고로드 할 수 있으며 파일 시스템의 공간이 줄어 듭니다.

셀 기준으로 세포를 찾습니다

.xlsx 형식이 셀을 저장하는 방법을 감안할 때, 당신은 잠재적으로 모든 셀을 반복하고 셀 참조에서 실제 셀 값에 대한 자신의 매핑을 구축해야합니다. CoreXLSX 라이브러리는 현재 자동 으로이 작업을 수행하지 않으므로 필요한 경우 자체지도를 구현해야합니다. 구문 분석 중에 선택적 단계와 같은 기능을 추가하는 풀 요청을 제출할 수 있습니다.

공유 현

스프레드 시트 내부의 문자열은 종종 여러 워크 시트 사이에서 공유되는 문자열로 표시됩니다. 셀에서 문자열 값을 구문 분석하려면 XLSXFile 의 parseSharedString() 과 함께 Cell 에서 stringValue(_: SharedStrings) 함수를 사용해야합니다.

예를 들어 "C"열에서 모든 문자열을 얻는 방법은 다음과 같습니다.

if let sharedStrings = try file . parseSharedStrings ( ) {
  let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
    . compactMap { $0 . stringValue ( sharedStrings ) }
}

셀에서 날짜 값을 구문 분석하려면 Cell 유형에서 dateValue 속성을 사용하십시오.

 let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
  . compactMap { $0 . dateValue }

마찬가지로 Rich Strings를 구문 분석하려면 richStringValue 기능을 사용하십시오.

if let richStrings = try file . parseSharedStrings ( ) {
  let columnCRichStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
    . compactMap { $0 . richStringValue ( sharedStrings ) }
}

스타일

버전 0.5.0이므로 새로운 parseStyles() 함수로 아카이브에서 스타일 정보를 구문 분석 할 수 있습니다. 자세한 내용은 Styles 모델을 참조하십시오. 또한 모든 XLSX 파일에 스타일 정보가 포함되어 있지는 않으므로이 경우 parseStyles() 기능에서 발생하는 오류를 처리 할 준비를해야합니다.

다음은 사용 된 글꼴 목록을 가져 오는 짧은 예입니다.

 let styles = try file . parseStyles ( )
let fonts = styles . fonts ? . items . compactMap { $0 . name ? . value }

주어진 셀에 대한 서식을 얻으려면 format(in:) 및 font(in:) 함수를 사용하여 parseStyles 의 결과를 전달하십시오.

 let styles = try file . parseStyles ( )
let format = worksheet . data ? . rows . first ? . cells . first ? . format ( in : styles )
let font = worksheet . data ? . rows . first ? . cells . first ? . font ( in : styles ) 

호환성 문제보고

구문 분석 할 수없는 파일을 우연히 발견하면 정확한 오류 메시지를 게시하는 문제를 제출하십시오. Standard Swift Codable 프로토콜 사용 덕분에 세부 오류가 생성되어 누락 된 속성을 나열하므로 더 넓은 형식 지원을 가능하게하는 모델에 쉽게 추가 할 수 있습니다. 구문 분석 할 수없는 파일을 첨부하면 문제를 진단하는 데 큰 도움이됩니다. 이러한 파일에 민감한 데이터가 포함 된 경우 문제가 여전히이 방식으로 재현 될 수 있다고 가정 할 때 원본 파일을 생성 한 동일한 도구로 가짜 데이터를 난독 화하거나 생성하는 것이 좋습니다.

전체 파일을 첨부 할 수없는 경우 XLSXFile 이니셜 라이저의 errorContextLength 인수에 충분히 큰 값 (10에서 20 사이)을 전달해보십시오. 이렇게하면 실패한 XML 스 니펫을 디버그 오류에 대한 디버그 설명과 함께 번들로 묶습니다. 문제를보고 할 때 가능한 경우 전체 디버그 설명을 첨부하십시오.

어떻게 작동합니까?

모든 XLSX 파일은 XML 파일의 zip 아카이브이므로 CoreXLSX XMLCoder 라이브러리와 표준 Codable 프로토콜을 사용하여 XML 노드를 매핑하고 방해물을 일반 신속한 스트러크로 매핑합니다. ZIPFoundation Zip 아카이브의 메모리 감압에 사용됩니다. 자세한 설명은 여기에서 제공됩니다.

요구 사항

애플 플랫폼

• Xcode 11.3 이상
• 스위프트 5.1 이상
• iOS 9.0 / WATWOS 2.0 / TVOS 9.0 / MACOS 10.11 이상 배포 대상

리눅스

• 우분투 16.04 이상
• 스위프트 5.1 이상

설치

스위프트 패키지 관리자

Swift Package Manager는 Swift 코드 배포를 관리하는 도구입니다. Swift 빌드 시스템과 통합되어 모든 플랫폼에서 종속성을 다운로드, 컴파일 및 연결하는 프로세스를 자동화합니다.

신속한 패키지를 설정하면 CoreXLSX 종속성으로 추가하는 것은 Package.swift 의 dependencies 값에 추가하는 것만 큼 쉽습니다.

dependencies: [
  . package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
           . upToNextMinor ( from : " 0.14.1 " ) )
]

Xcode로 구축 된 앱에서 CoreXLSX를 사용하는 경우 Xcode의 GUI를 사용하여 직접 의존성으로 추가 할 수도 있습니다.

코코 포드

CoreXLSX는 Apple 플랫폼의 Cocoapods를 통해 제공됩니다. 설치하려면 여기에 표시된 것처럼 pod 'CoreXLSX', '~> 0.14.1' Podfile 하십시오.

 source 'https://github.com/CocoaPods/Specs.git'
# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
use_frameworks!
target '<Your Target Name>' do
  pod 'CoreXLSX' , '~> 0.14.1'
end 

기여

개발 워크 플로

MACOS에서 프로젝트 작업을 시작하는 가장 쉬운 방법은 Xcode 11 이상에서 Package.swift 파일을 여는 것입니다. 두 가지 테스트를 해당 모델 값에 대비하여 엔드 투 엔드 및 분리 된 스 니펫을 파일하는 광범위한 테스트 스위트가 있습니다.

Xcode로 작업하지 않으려면 프로젝트가 SwiftPM을 완전히 지원하고 swift build 및 swift test 통한 일반적인 워크 플로우가 작동합니다. 그렇지 않으면 버그로보고하십시오.

코딩 스타일

이 프로젝트는 SwiftFormat 및 SwiftLint를 사용하여 형식 및 코딩 스타일을 시행합니다. Xcode Extension, Build Phase 또는 Git Pre-Commit Hook 등을 통해 수동 또는 자동으로 가장 적합한 방법으로 저장소의 로컬 클론 내에서 SwiftFormat을 실행하는 것이 좋습니다.

MacOS에서 변경 사항을 커밋하기 전에 이러한 도구가 실행되도록 보장하려면 사전 커밋 후크를 설정하기 위해이 작업을 한 번 실행하는 것이 좋습니다.

 brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit

다른 플랫폼에 대한 자세한 내용 및 설치 지침은 사전 커밋 문서 페이지를 참조하십시오.

Swiftformat 및 SwiftLint는 모든 PR에 대해 CI에서 실행되므로 CI 빌드는 일관되지 않은 형식 또는 스타일로 실패 할 수 있습니다. 병합하기 전에 CI 빌드가 모든 PR에 전달해야합니다.

행동 강령

이 프로젝트는 기고자 언약 행동 강령을 준수합니다. 참여 함으로써이 코드를지지해야합니다. 허용 할 수없는 행동을 [email protected]에보고하십시오.

특허

CoreXLSX는 Apache 2.0 라이센스로 제공됩니다. 자세한 내용은 라이센스 파일을 참조하십시오.