CoreXLSX
0.14.2
CorexLSX adalah perpustakaan yang berfokus pada mewakili struktur tingkat rendah dari format spreadsheet XLSX berbasis XML. Ini memungkinkan Anda untuk membuka arsip spreadsheet dengan ekstensi .xlsx dan memetakan struktur internalnya menjadi jenis model yang diekspresikan langsung di Swift.
Penting untuk dicatat bahwa perpustakaan ini memberikan dukungan hanya baca hanya untuk format .xlsx . Karena format spreadsheet .xls yang lebih lama memiliki internal yang sama sekali berbeda, silakan merujuk ke perpustakaan lain jika Anda perlu bekerja dengan file dari jenis itu.
Jika file .xlsx Anda menggunakan enkripsi gesit ECMA-376 (yang tampaknya menjadi varietas yang paling populer), lihat Perpustakaan CryptoOffice.
Dokumentasi yang dihasilkan secara otomatis tersedia di halaman GitHub kami.
Bergabunglah dengan perselisihan kami untuk pertanyaan dan olok -olok ramah.
Untuk menjalankan proyek contoh, klon repo, dan menjalankan pod install dari direktori contoh terlebih dahulu.
Jenis Model dalam CoreXLSX secara langsung memetakan struktur internal format XLSX dengan penamaan yang lebih masuk akal diterapkan pada beberapa atribut. API cukup sederhana:
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 )
}
}
}
} Ini mencetak data sel mentah dari setiap lembar kerja dalam file XLSX yang diberikan. Silakan merujuk ke model Worksheet untuk atttribute lebih lanjut yang mungkin perlu Anda baca dari file parsed.
Anda tidak boleh mengatasi sel melalui indeksnya dalam array cells . Setiap sel memiliki properti reference , yang dapat Anda baca untuk memahami di mana tepatnya sel yang diberikan. Sifat yang sesuai pada struct CellReference memberi Anda posisi yang tepat dari sel.
Format .xlsx membuat perbedaan yang jelas antara sel kosong dan tidak adanya sel. Jika Anda tidak mendapatkan sel atau barisan saat mengulangi array cells , ini berarti tidak ada sel atau baris seperti itu dalam dokumen Anda. Dokumen .xlsx Anda harus memiliki sel dan baris kosong yang ditulis di dalamnya di tempat pertama agar Anda dapat membacanya.
Membuat perbedaan ini membuat format lebih efisien, terutama untuk spreadsheet yang jarang. Jika Anda memiliki spreadsheet dengan sel tunggal Z1000000, itu tidak akan mengandung jutaan sel kosong dan satu sel tunggal dengan nilai. File hanya menyimpan satu sel, yang memungkinkan spreadsheet yang jarang disimpan dengan cepat dan dimuat, juga mengambil lebih sedikit ruang pada sistem file.
Mengingat bagaimana format .xlsx menyimpan sel, Anda berpotensi mengulangi semua sel dan membangun pemetaan sendiri dari referensi sel ke nilai sel yang sebenarnya. Perpustakaan CorexLSX saat ini tidak melakukan ini secara otomatis, dan Anda harus mengimplementasikan pemetaan Anda sendiri jika Anda membutuhkannya. Anda dipersilakan untuk mengirimkan permintaan tarik yang menambahkan fungsionalitas seperti itu sebagai langkah opsional selama penguraian.
String dalam internal spreadsheet sering direpresentasikan sebagai string yang dibagikan di antara beberapa lembar kerja. Untuk mengurai nilai string dari sel Anda harus menggunakan fungsi stringValue(_: SharedStrings) pada Cell bersama dengan parseSharedString() pada XLSXFile .
Inilah cara Anda bisa mendapatkan semua string di kolom "C" misalnya:
if let sharedStrings = try file . parseSharedStrings ( ) {
let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . stringValue ( sharedStrings ) }
} Untuk menguraikan nilai tanggal dari sel, gunakan properti dateValue pada tipe Cell :
let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . dateValue } Demikian pula, untuk menguraikan string kaya, gunakan fungsi richStringValue :
if let richStrings = try file . parseSharedStrings ( ) {
let columnCRichStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . richStringValue ( sharedStrings ) }
} Karena versi 0.5.0 Anda dapat menguraikan informasi gaya dari arsip dengan fungsi parseStyles() yang baru. Silakan merujuk ke model Styles untuk detail lebih lanjut. Anda juga harus mencatat bahwa tidak semua file XLSX berisi informasi gaya, jadi Anda harus siap untuk menangani kesalahan yang dilemparkan dari fungsi parseStyles() dalam kasus itu.
Berikut adalah contoh singkat yang mengambil daftar font yang digunakan:
let styles = try file . parseStyles ( )
let fonts = styles . fonts ? . items . compactMap { $0 . name ? . value } Untuk mendapatkan pemformatan untuk sel tertentu, gunakan format(in:) dan font(in:) fungsi, meneruskannya hasil 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 ) Jika Anda menemukan file yang tidak dapat diuraikan, silakan mengajukan masalah yang memposting pesan kesalahan yang tepat. Berkat penggunaan protokol Codable Swift standar, kesalahan terperinci dihasilkan mendaftarkan atribut yang hilang, sehingga dapat dengan mudah ditambahkan ke model yang memungkinkan dukungan format yang lebih luas. Melampirkan file yang tidak dapat diuraikan juga akan sangat membantu dalam mendiagnosis masalah. Jika file -file ini berisi data sensitif apa pun, kami menyarankan untuk mengaburkan atau menghasilkan data palsu dengan alat yang sama yang menghasilkan file asli, dengan asumsi masalah tersebut masih dapat direproduksi dengan cara ini.
Jika seluruh file tidak dapat dilampirkan, cobalah memberikan nilai yang cukup besar (antara 10 dan 20 biasanya berfungsi dengan baik) ke Argumen errorContextLength dari XLSXFile Initializer. Ini akan menggabungkan cuplikan XML yang gagal dengan deskripsi debug tentang kesalahan yang dilemparkan. Harap lampirkan deskripsi debug lengkap jika memungkinkan saat melaporkan masalah.
Karena setiap file XLSX adalah arsip ZIP dari file XML, CoreXLSX menggunakan perpustakaan XMLCoder dan protokol Codable standar untuk memetakan node XML dan atrribut ke dalam struktur cepat biasa. ZIPFoundation digunakan untuk dekompresi dalam memori arsip ZIP. Deskripsi terperinci tersedia di sini.
Platform Apple
Linux
Swift Package Manager adalah alat untuk mengelola distribusi kode Swift. Ini terintegrasi dengan sistem pembuatan Swift untuk mengotomatisasi proses mengunduh, menyusun, dan menghubungkan dependensi pada semua platform.
Setelah Anda mengatur paket Swift, menambahkan CoreXLSX sebagai ketergantungan semudah menambahkannya ke nilai dependencies Package.swift Anda.
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]Jika Anda menggunakan CorexLSX di aplikasi yang dibangun dengan XCODE, Anda juga dapat menambahkannya sebagai ketergantungan langsung menggunakan GUI Xcode.
CoreXLSX tersedia melalui cocoapods di platform Apple. Untuk menginstalnya, cukup tambahkan pod 'CoreXLSX', '~> 0.14.1' ke Podfile Anda seperti yang ditunjukkan di sini:
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 Pada macOS cara termudah untuk mulai mengerjakan proyek adalah dengan membuka file Package.swift di xcode 11 atau lebih baru. Ada rangkaian uji yang luas yang kedua pengujian file end-to-end dan cuplikan terisolasi terhadap nilai model yang sesuai.
Jika Anda lebih suka untuk tidak bekerja dengan XCODE, proyek ini sepenuhnya mendukung SwiftPM dan alur kerja yang biasa dengan swift build dan swift test harus berfungsi, jika tidak, harap laporkan ini sebagai bug.
Proyek ini menggunakan SwiftFormat dan Swiftlint untuk menegakkan format dan gaya pengkodean. Kami mendorong Anda untuk menjalankan SwiftFormat dalam klon lokal repositori dengan cara apa pun yang paling cocok untuk Anda baik secara manual maupun otomatis melalui ekstensi xcode, fase build atau git hook pra-komit dll.
Untuk menjamin bahwa alat-alat ini berjalan sebelum Anda melakukan perubahan pada macOS, Anda didorong untuk menjalankan ini sekali untuk mengatur kait pra-komit:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Lihat halaman dokumentasi pra-komit untuk detail lebih lanjut dan instruksi instalasi untuk platform lain.
Swiftformat dan Swiftlint juga berjalan pada CI untuk setiap PR dan dengan demikian bangunan CI dapat gagal dengan pemformatan atau gaya yang tidak konsisten. Kami membutuhkan build CI untuk melewati semua PR sebelum bergabung.
Proyek ini mematuhi Kode Etik Kovenan Kontributor. Dengan berpartisipasi, Anda diharapkan untuk menegakkan kode ini. Harap laporkan perilaku yang tidak dapat diterima ke [email protected].
CorexLSX tersedia di bawah lisensi Apache 2.0. Lihat file lisensi untuk info lebih lanjut.
