CoreXLSX
0.14.2
Corexlsx เป็นไลบรารีที่มุ่งเน้นไปที่การแสดงโครงสร้างระดับต่ำของรูปแบบสเปรดชีต XLSX ที่ใช้ XML ช่วยให้คุณสามารถเปิดคลังเก็บสเปรดชีตด้วยส่วนขยาย .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 ที่กำหนด โปรดดูโมเดล Worksheet สำหรับ atttributes เพิ่มเติมที่คุณอาจต้องอ่านจากไฟล์ที่แยกวิเคราะห์
คุณไม่ควรจัดการกับเซลล์ผ่านดัชนีในอาร์เรย์ cells ทุกเซลล์มีคุณสมบัติ reference ซึ่งคุณสามารถอ่านเพื่อทำความเข้าใจว่าเซลล์ที่กำหนดอยู่ตรงไหน คุณสมบัติที่สอดคล้องกันใน struct CellReference ให้ตำแหน่งที่แน่นอนของเซลล์
รูปแบบ .xlsx ทำให้เกิดความแตกต่างที่ชัดเจนระหว่างเซลล์ที่ว่างเปล่าและไม่มีเซลล์ หากคุณไม่ได้รับเซลล์หรือแถวเมื่อวนซ้ำผ่านอาเรย์ของ cells นั่นหมายความว่าไม่มีเซลล์หรือแถวดังกล่าวในเอกสารของคุณ เอกสาร .xlsx ของคุณควรมีเซลล์ว่างและแถวที่เขียนไว้ในตอนแรกเพื่อให้คุณสามารถอ่านได้
การทำให้ความแตกต่างนี้ทำให้รูปแบบมีประสิทธิภาพมากขึ้นโดยเฉพาะอย่างยิ่งสำหรับสเปรดชีตที่กระจัดกระจาย หากคุณมีสเปรดชีตที่มีเซลล์เดียว Z1000000 มันจะไม่มีเซลล์ว่างหลายล้านเซลล์และเซลล์เดียวที่มีค่า ไฟล์เก็บเฉพาะเซลล์เดียวซึ่งช่วยให้สเปรดชีตเบาบางสามารถบันทึกและโหลดได้อย่างรวดเร็วและใช้พื้นที่น้อยลงในระบบไฟล์
ด้วยวิธีที่รูปแบบ .xlsx เก็บเซลล์คุณอาจต้องวนซ้ำผ่านเซลล์ทั้งหมดและสร้างการแมปของคุณเองจากการอ้างอิงเซลล์ไปยังค่าเซลล์จริง ห้องสมุด CorexLSX ไม่ได้ทำสิ่งนี้โดยอัตโนมัติและคุณจะต้องใช้การแมปของคุณเองหากคุณต้องการ คุณสามารถส่งคำขอดึงที่เพิ่มฟังก์ชั่นดังกล่าวเป็นขั้นตอนเสริมในระหว่างการแยกวิเคราะห์
สตริงในสเปรดชีตภายในมักจะแสดงเป็นสตริงที่ใช้ร่วมกันระหว่างแผ่นงานหลายแผ่น ในการแยกวิเคราะห์ค่าสตริงจากเซลล์คุณควรใช้ฟังก์ชัน stringValue(_: SharedStrings) บน Cell พร้อมกับ parseSharedString() บน XLSXFile
นี่คือวิธีที่คุณจะได้รับสตริงทั้งหมดในคอลัมน์ "C" ตัวอย่างเช่น:
if let sharedStrings = try file . parseSharedStrings ( ) {
let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . stringValue ( sharedStrings ) }
} ในการแยกวิเคราะห์ค่าวันที่จากเซลล์ให้ใช้คุณสมบัติ dateValue บนประเภท Cell :
let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . dateValue } ในทำนองเดียวกันในการแยกแยะสตริงที่อุดมไปด้วยใช้ฟังก์ชัน 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 ) หากคุณสะดุดกับไฟล์ที่ไม่สามารถแยกวิเคราะห์ได้โปรดยื่นปัญหาการโพสต์ข้อความแสดงข้อผิดพลาดที่แน่นอน ด้วยการใช้โปรโตคอล Swift Codable มาตรฐานข้อผิดพลาดโดยละเอียดถูกสร้างขึ้นในรายการแอตทริบิวต์ที่ขาดหายไปดังนั้นจึงสามารถเพิ่มได้อย่างง่ายดายในรุ่นที่เปิดใช้งานการสนับสนุนรูปแบบที่กว้างขึ้น การแนบไฟล์ที่ไม่สามารถแยกวิเคราะห์ได้จะช่วยในการวินิจฉัยปัญหาได้อย่างมาก หากไฟล์เหล่านี้มีข้อมูลที่ละเอียดอ่อนใด ๆ เราขอแนะนำให้ทำให้งงงวยหรือสร้างข้อมูลปลอมด้วยเครื่องมือเดียวกันกับที่สร้างไฟล์ต้นฉบับโดยสมมติว่าปัญหายังสามารถทำซ้ำด้วยวิธีนี้
หากไฟล์ทั้งหมดไม่สามารถแนบได้ให้ลองส่งผ่านค่าที่มีขนาดใหญ่เพียงพอ (ระหว่าง 10 ถึง 20 มักจะทำงานได้ดี) ไปยังอาร์กิวเมนต์ errorContextLength ของ XLSXFile Initializer สิ่งนี้จะรวมตัวอย่าง XML ที่ล้มเหลวด้วยคำอธิบายการดีบักของข้อผิดพลาดที่ถูกโยนทิ้ง โปรดแนบคำอธิบายการดีบักเต็มรูปแบบหากเป็นไปได้เมื่อรายงานปัญหา
เนื่องจากไฟล์ XLSX ทุกไฟล์เป็นไฟล์เก็บถาวร ZIP ของไฟล์ XML CoreXLSX จึงใช้ไลบรารี XMLCoder และโปรโตคอล Codable มาตรฐานเพื่อแมปโหนด XML และ Atrributes ลงในโครงสร้างที่รวดเร็ว ZIPFoundation ใช้สำหรับการบีบอัดในหน่วยความจำของคลังเก็บซิป คำอธิบายโดยละเอียดมีอยู่ที่นี่
แพลตฟอร์ม Apple
ลินเวกซ์
Swift Package Manager เป็นเครื่องมือในการจัดการการกระจายรหัส Swift มันรวมเข้ากับระบบการสร้าง Swift เพื่อทำให้กระบวนการดาวน์โหลดรวบรวมและเชื่อมโยงการพึ่งพาในทุกแพลตฟอร์มโดยอัตโนมัติ
เมื่อคุณตั้งค่าแพ็คเกจ Swift แล้วการเพิ่ม CoreXLSX เป็นการพึ่งพานั้นง่ายพอ ๆ กับการเพิ่มลงในค่า dependencies ของ Package.swift ของคุณ
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]หากคุณใช้ corexlsx ในแอพที่สร้างด้วย XCode คุณสามารถเพิ่มการพึ่งพาโดยตรงโดยใช้ GUI ของ Xcode
Corexlsx มีให้บริการผ่าน Cocoapods บนแพลตฟอร์มของ Apple ในการติดตั้งเพียงเพิ่ม 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 วิธีที่ง่ายที่สุดในการเริ่มทำงานในโครงการคือการเปิดไฟล์ Package.swift ใน Xcode 11 หรือใหม่กว่า มีชุดทดสอบที่กว้างขวางว่าทั้งสองไฟล์ทดสอบไฟล์แบบ end-to-end และแยกส่วนกับค่าโมเดลที่สอดคล้องกัน
หากคุณไม่ต้องการทำงานกับ XCode โครงการสนับสนุน SwiftPM อย่างเต็มที่และเวิร์กโฟลว์ปกติด้วยการทดสอบ swift build และ swift test ควรทำงานมิฉะนั้นโปรดรายงานสิ่งนี้เป็นข้อผิดพลาด
โครงการนี้ใช้ SwiftFormat และ Swiftlint เพื่อบังคับใช้รูปแบบการจัดรูปแบบและการเข้ารหัส เราขอแนะนำให้คุณเรียกใช้ SwiftFormat ภายในโคลนท้องถิ่นของที่เก็บไม่ว่าจะด้วยวิธีใดก็ตามที่ดีที่สุดสำหรับคุณด้วยตนเองหรือโดยอัตโนมัติผ่านส่วนขยาย Xcode, สร้างเฟสหรือ hook git pre-commit ฯลฯ
เพื่อรับประกันว่าเครื่องมือเหล่านี้ทำงานก่อนที่คุณจะทำการเปลี่ยนแปลงบน MacOS คุณได้รับการสนับสนุนให้เรียกใช้สิ่งนี้เพียงครั้งเดียวเพื่อตั้งค่าเบ็ดล่วงหน้า:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
อ้างถึงหน้าเอกสารล่วงหน้าสำหรับรายละเอียดเพิ่มเติมและคำแนะนำการติดตั้งสำหรับแพลตฟอร์มอื่น ๆ
SwiftFormat และ Swiftlint ยังทำงานบน CI สำหรับทุก ๆ PR และการสร้าง CI สามารถล้มเหลวได้ด้วยการจัดรูปแบบหรือสไตล์ที่ไม่สอดคล้องกัน เราต้องการ CI Builds เพื่อผ่าน PRS ทั้งหมดก่อนที่จะรวมกัน
โครงการนี้ปฏิบัติตามจรรยาบรรณผู้สนับสนุน โดยการเข้าร่วมคุณคาดว่าจะสนับสนุนรหัสนี้ โปรดรายงานพฤติกรรมที่ยอมรับไม่ได้ถึง [email protected]
Corexlsx มีให้ภายใต้ใบอนุญาต Apache 2.0 ดูไฟล์ใบอนุญาตสำหรับข้อมูลเพิ่มเติม
