CoreXLSX
0.14.2
Corexlsx est une bibliothèque axée sur la représentation de la structure de bas niveau du format de feuille de calcul XLSX basé sur XML. Il vous permet d'ouvrir une archive de feuille de calcul avec une extension .xlsx et de mapper sa structure interne en types de modèles exprimés directement dans Swift.
Important de noter que cette bibliothèque fournit une prise en charge en lecture seule uniquement pour le format .xlsx . Comme le format de table de calcul .xls plus ancien.
Si vos fichiers .xlsx utilisent ECMA-376 Agile Encryption (qui semble être la variété la plus populaire), jetez un œil à la bibliothèque CryptoOffice.
La documentation générée automatiquement est disponible sur nos pages GitHub.
Rejoignez notre discorde pour toutes les questions et les plaisanteries amicales.
Pour exécuter l'exemple de projet, clonez le repo et exécutez d'abord pod install à partir de l'exemple du répertoire.
Les types de modèles dans CoreXLSX mappent directement la structure interne du format XLSX avec une dénomination plus judicieuse appliquée à quelques attributs. L'API est assez simple:
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 )
}
}
}
} Cela imprime les données de cellules brutes de chaque feuille de calcul du fichier xlsx donné. Veuillez vous référer au modèle Worksheet pour plus d'attributs que vous devrez peut-être lire à partir d'un fichier analysé.
Vous ne devez pas aborder les cellules via leurs indices dans le tableau cells . Chaque cellule a une propriété reference , que vous pouvez lire pour comprendre où se trouve exactement une cellule donnée. Les propriétés correspondantes sur la structure CellReference vous donnent la position exacte d'une cellule.
Le format .xlsx fait une distinction claire entre une cellule vide et l'absence d'une cellule. Si vous n'obtenez pas de cellule ou de ligne lors de l'itération du tableau cells , cela signifie qu'il n'y a pas de cellule ou de ligne de ce type dans votre document. Votre document .xlsx devrait avoir des cellules et des lignes vides en premier lieu pour que vous puissiez les lire.
Faire cette distinction rend le format plus efficace, en particulier pour les feuilles de calcul clairsemées. Si vous aviez une feuille de calcul avec une seule cellule Z1000000, elle ne contiendrait pas de millions de cellules vides et une seule cellule avec une valeur. Le fichier stocke uniquement une seule cellule, ce qui permet à des feuilles de calcul clairsemées d'être enregistrées et chargées, prenant également moins d'espace sur le système de fichiers.
Compte tenu de la façon dont le format .xlsx stocke les cellules, vous devez potentiellement parcourir toutes les cellules et construire votre propre cartographie à partir de références cellulaires aux valeurs cellulaires réelles. La bibliothèque Corexlsx ne le fait pas actuellement automatiquement, et vous devrez implémenter votre propre mappage si vous en avez besoin. Vous êtes invités à soumettre une demande de traction qui ajoute une fonctionnalité telle qu'une étape facultative pendant l'analyse.
Les chaînes dans les internes de feuille de calcul sont fréquemment représentées comme des chaînes partagées entre plusieurs feuilles de calcul. Pour analyser une valeur de chaîne à partir d'une cellule, vous devez utiliser stringValue(_: SharedStrings) sur Cell avec parseSharedString() sur XLSXFile .
Voici comment vous pouvez obtenir toutes les chaînes dans la colonne "C" par exemple:
if let sharedStrings = try file . parseSharedStrings ( ) {
let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . stringValue ( sharedStrings ) }
} Pour analyser une valeur de date à partir d'une cellule, utilisez la propriété dateValue sur le type Cell :
let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . dateValue } De même, pour analyser les cordes riches, utilisez la fonction richStringValue :
if let richStrings = try file . parseSharedStrings ( ) {
let columnCRichStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . richStringValue ( sharedStrings ) }
} Depuis la version 0.5.0, vous pouvez analyser les informations de style de l'archive avec la nouvelle fonction parseStyles() . Veuillez vous référer au modèle Styles pour plus de détails. Vous devez également noter que tous les fichiers XLSX ne contiennent pas d'informations de style, vous devez donc être prêt à gérer les erreurs lancées à partir de la fonction parseStyles() dans ce cas.
Voici un court exemple qui récupère une liste de polices utilisées:
let styles = try file . parseStyles ( )
let fonts = styles . fonts ? . items . compactMap { $0 . name ? . value } Pour obtenir du formatage pour une cellule donnée, utilisez format(in:) et font(in:) fonctions, en la passant le résultat de 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 ) Si vous tombez sur un fichier qui ne peut pas être analysé, veuillez déposer un problème publiant le message d'erreur exact. Grâce à l'utilisation du protocole Codable SWIFT standard, des erreurs détaillées sont générées en répertoriant un attribut manquant, de sorte qu'il peut être facilement ajouté au modèle permettant une prise en charge de format plus large. La connexion d'un fichier qui ne peut pas être analysé aiderait également grandement à diagnostiquer les problèmes. Si ces fichiers contiennent des données sensibles, nous vous suggérons d'ébuscation ou de génération de fausses données avec les mêmes outils qui ont généré des fichiers originaux, en supposant que le problème peut toujours être reproduit de cette façon.
Si l'ensemble du fichier ne peut pas être joint, essayez de passer une valeur suffisamment grande (entre 10 et 20 fonctionne généralement bien) à l'argument errorContextLength de l'initialiseur XLSXFile . Cela regroupera l'extrait de XML défaillant avec la description de débogage des erreurs lancées. Veuillez également joindre la description complète du débogage lorsque possible lors de la déclaration des problèmes.
Étant donné que chaque fichier XLSX est une archive zip des fichiers XML, CoreXLSX utilise la bibliothèque XMLCoder et les protocoles Codable standard pour mapper les nœuds XML et les attibutes en structures simples. ZIPFoundation est utilisée pour la décompression en mémoire des archives zip. Une description détaillée est disponible ici.
Plateformes Apple
Linux
Swift Package Manager est un outil pour gérer la distribution du code SWIFT. Il est intégré au système Swift Build pour automatiser le processus de téléchargement, de compilation et de liaison des dépendances sur toutes les plateformes.
Une fois que vous avez configuré votre package SWIFT, l'ajout de CoreXLSX comme dépendance est aussi simple que de l'ajouter à la valeur dependencies de votre Package.swift .
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]Si vous utilisez Corexlsx dans une application construite avec Xcode, vous pouvez également l'ajouter en tant que dépendance directe à l'aide de l'interface graphique de Xcode.
CoreXLSX est disponible via Cocoapods sur les plates-formes d'Apple. Pour l'installer, ajoutez simplement pod 'CoreXLSX', '~> 0.14.1' à votre Podfile comme indiqué ici:
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 Sur MacOS, la façon la plus simple de commencer à travailler sur le projet est d'ouvrir le fichier Package.swift dans Xcode 11 ou version ultérieure. Il existe une vaste suite de tests qui teste les deux fichiers de bout en bout et des extraits isolés par rapport à leurs valeurs de modèle correspondantes.
Si vous préférez ne pas travailler avec Xcode, le projet prend en charge SWIFTPM et le flux de travail habituel avec swift build et swift test devrait fonctionner, sinon, veuillez le signaler comme un bogue.
Ce projet utilise SwiftFormat et Swiftlint pour appliquer le style de mise en forme et de codage. Nous vous encourageons à exécuter SwiftFormat dans un clone local du référentiel de quelque manière que ce soit le mieux pour vous manuellement ou automatiquement via une extension Xcode, une phase de construction ou un crochet pré-comiss GIT, etc.
Pour garantir que ces outils s'exécutent avant de valider vos modifications sur MacOS, vous êtes encouragé à exécuter cela une fois pour configurer le crochet pré-engagé:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Reportez-vous à la page de documentation de pré-engagement pour plus de détails et d'instructions d'installation pour d'autres plates-formes.
SwiftFormat et Swiftlint fonctionnent également sur CI pour chaque PR et donc une version CI peut échouer avec une mise en forme ou un style incohérents. Nous avons besoin de CI Builds pour passer pour tous les PR avant la fusion.
Ce projet adhère au Code de conduite de l'alliance des contributeurs. En participant, vous devez maintenir ce code. Veuillez signaler un comportement inacceptable à [email protected].
Corexlsx est disponible sous la licence Apache 2.0. Voir le fichier de licence pour plus d'informations.
