CoreXLSX
0.14.2
Corexlsx هي مكتبة تركز على تمثيل الهيكل منخفض المستوى لتنسيق جدول بيانات XLSX المستند إلى XML. يتيح لك فتح أرشيف جدول البيانات مع امتداد .xlsx ورسم خريطة بنيةه الداخلية في أنواع النماذج المعبر عنها مباشرة في Swift.
من المهم أن نلاحظ أن هذه المكتبة توفر دعمًا للقراءة فقط لتنسيق .xlsx . نظرًا لأن تنسيق جدول بيانات Legacy الأقدم .xls يحتوي على الداخلية مختلفة تمامًا ، يرجى الرجوع إلى المكتبات الأخرى إذا كنت بحاجة إلى العمل مع ملفات من هذا النوع.
إذا استخدمت ملفات .xlsx تشفير ECMA-376 Agile (الذي يبدو أنه أكثر التنوع شعبية) ، فاحرص على إلقاء نظرة على مكتبة CryptOoffice.
تتوفر الوثائق التي تم إنشاؤها تلقائيًا على صفحات GitHub الخاصة بنا.
انضم إلى خلافنا عن أي أسئلة ومزاح ودي.
لتشغيل Project Example ، استنساخ REPO ، وتثبيت pod install من الدليل المثال أولاً.
أنواع النماذج في CoreXLSX قم بتخطيط التركيب الداخلي لتنسيق XLSX مباشرة مع تسمية أكثر عقلانية مطبق على بعض السمات. واجهة برمجة التطبيقات بسيطة جدا:
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 لمزيد من العدادات التي قد تحتاج إلى القراءة من ملف محسّن.
يجب ألا تعالج الخلايا عبر مؤشراتها في مجموعة cells . كل خلية لها خاصية reference ، يمكنك قراءتها لفهم مكان وجود خلية معينة بالضبط. الخصائص المقابلة على بنية 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 . سيؤدي ذلك إلى تجميع مقتطف XML الفاشل مع وصف التصحيح للأخطاء التي تم إلقاؤها. يرجى أيضًا إرفاق وصف التصحيح الكامل إذا كان ذلك ممكنًا عند الإبلاغ عن المشكلات.
نظرًا لأن كل ملف XLSX عبارة عن أرشيف مضغوط لملفات XML ، يستخدم CoreXLSX مكتبة XMLCoder والبروتوكولات Codable القياسية لرسم خريطة العقد XML و Atrrributes في هياكل سريعة عادية. يتم استخدام ZIPFoundation لإزالة الضغط في الذاكرة من المحفوظات الرمز البريدي. وصف مفصل متاح هنا.
منصات Apple
Linux
Swift Package Manager هي أداة لإدارة توزيع الكود السريع. تم دمجها مع نظام Build Swift لأتمتة عملية تنزيل وتجميع وربط التبعيات على جميع المنصات.
بمجرد إعداد حزمة Swift الخاصة بك ، فإن إضافة CoreXLSX كاعتماد سهلة مثل إضافتها إلى قيمة dependencies الخاصة Package.swift الخاصة بك.
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]إذا كنت تستخدم COREXLSX في تطبيق تم تصميمه باستخدام XCODE ، فيمكنك أيضًا إضافته كاعتماد مباشر باستخدام واجهة المستخدم الرسومية 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 أو أحدث. هناك مجموعة اختبار واسعة النطاق التي يختبر كلا الملفات قصاصات من طرف إلى طرف ومعزولة مقابل قيم النماذج المقابلة لها.
إذا كنت تفضل عدم العمل مع XCode ، فإن المشروع يدعم تمامًا SwiftPM وسير العمل المعتاد مع swift build swift test ، وإلا يرجى الإبلاغ عن ذلك كخشب.
يستخدم هذا المشروع SwiftFormat و SwiftLint لفرض نمط التنسيق والترميز. نحن نشجعك على تشغيل SwiftFormat داخل استنساخ محلي للمستودع بأي طريقة تعمل بشكل أفضل بالنسبة لك إما يدويًا أو تلقائيًا عبر تمديد Xcode ، أو مرحلة البناء أو خطاف GIT قبل الالتزام وما إلى ذلك.
لضمان أن هذه الأدوات تعمل قبل ارتكاب التغييرات الخاصة بك على 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 بناء لجميع PRS قبل الاندماج.
يلتزم هذا المشروع بقواعد سلوك العهد المساهم. من خلال المشاركة ، من المتوقع أن تدعم هذا الرمز. يرجى الإبلاغ عن سلوك غير مقبول إلى [email protected].
يتوفر Corexlsx بموجب ترخيص Apache 2.0. انظر ملف الترخيص لمزيد من المعلومات.
