CoreXLSX
0.14.2
COREXLSX es una biblioteca centrada en representar la estructura de bajo nivel del formato de hoja de cálculo XLSX basado en XML. Le permite abrir un archivo de hoja de cálculo con extensión .xlsx y asignar su estructura interna en tipos de modelos expresados directamente en Swift.
Es importante tener en cuenta que esta biblioteca proporciona soporte de solo lectura solo para el formato .xlsx . Como el formato de hoja de cálculo .xls Legacy anterior tiene internales completamente diferentes, consulte otras bibliotecas si necesita trabajar con archivos de ese tipo.
Si sus archivos .xlsx usan el cifrado ágil ECMA-376 (que parece ser la variedad más popular), eche un vistazo a la Biblioteca CryptoOffice.
La documentación generada automáticamente está disponible en nuestras páginas GitHub.
Únase a nuestra discordia para cualquier pregunta y bromas amistosas.
Para ejecutar el proyecto de ejemplo, clonar el repositorio y ejecutar pod install desde el directorio de ejemplo.
Los tipos de modelos en CoreXLSX mapear directamente la estructura interna del formato XLSX con nombres más sensibles aplicados a algunos atributos. La API es bastante 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 )
}
}
}
} Esto imprime datos de celda sin procesar de cada hoja de trabajo en el archivo XLSX dado. Consulte el modelo Worksheet para obtener más atributos que necesite leer desde un archivo analizado.
No debe abordar las células a través de sus índices en la matriz cells . Cada celda tiene una propiedad reference , que puede leer para comprender dónde se encuentra exactamente una celda determinada. Las propiedades correspondientes en la estructura CellReference le dan la posición exacta de una celda.
El formato .xlsx hace una clara distinción entre una celda vacía y la ausencia de una celda. Si no está obteniendo una celda o una fila al iterar a través de la matriz cells , esto significa que no existe dicha celda o fila en su documento. Su documento .xlsx debe tener celdas y filas vacías escritas en él en primer lugar para que pueda leerlas.
Hacer esta distinción hace que el formato sea más eficiente, especialmente para hojas de cálculo escasas. Si tuviera una hoja de cálculo con una sola celda Z1000000, no contendría millones de celdas vacías y una sola celda con un valor. El archivo solo almacena una sola celda, lo que permite que las hojas de cálculo escasas se guarden rápidamente y se carguen, también llevan menos espacio en el sistema de archivos.
Dado cómo el formato .xlsx almacena las células, potencialmente tiene que iterar a través de todas las células y construir su propio mapeo a partir de las referencias de células a los valores de las celdas reales. La biblioteca COREXLSX no lo hace actualmente automáticamente, y deberá implementar su propia asignación si la necesita. Puede enviar una solicitud de extracción que agrega dicha funcionalidad como un paso opcional durante el análisis.
Las cadenas en las hojas de cálculo internos se representan con frecuencia como cadenas compartidas entre múltiples hojas de trabajo. Para analizar un valor de cadena de una celda, debe usar la función stringValue(_: SharedStrings) en Cell junto con parseSharedString() en XLSXFile .
Así es como puede obtener todas las cadenas en la columna "C", por ejemplo:
if let sharedStrings = try file . parseSharedStrings ( ) {
let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . stringValue ( sharedStrings ) }
} Para analizar un valor de fecha de una celda, use la propiedad dateValue en el tipo Cell :
let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . dateValue } Del mismo modo, para analizar cadenas ricas, use la función richStringValue :
if let richStrings = try file . parseSharedStrings ( ) {
let columnCRichStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . richStringValue ( sharedStrings ) }
} Desde la versión 0.5.0, puede analizar la información de estilo del archivo con la nueva función parseStyles() . Consulte el modelo Styles para obtener más detalles. También debe tener en cuenta que no todos los archivos XLSX contienen información de estilo, por lo que debe estar preparado para manejar los errores lanzados desde la función parseStyles() en ese caso.
Aquí hay un breve ejemplo que obtiene una lista de fuentes utilizadas:
let styles = try file . parseStyles ( )
let fonts = styles . fonts ? . items . compactMap { $0 . name ? . value } Para obtener el formato para una celda determinada, use format(in:) y font(in:) funciones, transmitiendo el resultado 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 tropiece con un archivo que no se puede analizar, presente un problema publicando el mensaje de error exacto. Gracias al uso del protocolo Swift Codable estándar, se generan errores detallados que enumeran un atributo faltante, por lo que se puede agregar fácilmente al modelo que permite un soporte de formato más amplio. Adjuntar un archivo que no se puede analizar también ayudaría enormemente a diagnosticar problemas. Si estos archivos contienen datos confidenciales, sugerimos ofuscar o generar datos falsos con las mismas herramientas que generaron archivos originales, suponiendo que el problema aún se pueda reproducir de esta manera.
Si no se puede adjuntar todo el archivo, intente pasar un valor suficientemente grande (entre 10 y 20 generalmente funciona bien) a errorContextLength Argument of XLSXFile Inicializer. Esto agrupará el fragmento XML que falla con la descripción de depuración de los errores lanzados. También adjunte la descripción de depuración completa si es posible al informar problemas.
Dado que cada archivo XLSX es un archivo ZIP de archivos XML, CoreXLSX utiliza la biblioteca XMLCoder y los protocolos Codable estándar para asignar nodos XML y atrributos en estructuras rápidas simples. ZIPFoundation se usa para la descompresión en memoria de los archivos zip. Una descripción detallada está disponible aquí.
Plataformas de Apple
Linux
Swift Package Manager es una herramienta para administrar la distribución del código Swift. Está integrado con el sistema de compilación Swift para automatizar el proceso de descarga, compilación y vinculación de dependencias en todas las plataformas.
Una vez que tenga su paquete Swift configurado, agregar CoreXLSX como dependencia es tan fácil como agregarlo al valor de dependencies de su Package.swift .
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]Si está utilizando COREXLSX en una aplicación construida con Xcode, también puede agregarla como una dependencia directa utilizando la GUI de Xcode.
CoreXLSX está disponible a través de Cocoapods en las plataformas de Apple. Para instalarlo, simplemente agregue pod 'CoreXLSX', '~> 0.14.1' a su Podfile como se muestra aquí:
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 En MacOS, la forma más fácil de comenzar a trabajar en el proyecto es abrir el archivo Package.swift en Xcode 11 o posterior. Hay un extenso conjunto de pruebas que prueba los archivos de extremo a extremo y los fragmentos aislados contra sus valores de modelo correspondientes.
Si prefiere no trabajar con XCode, el proyecto admite plenamente SWIFTPM y el flujo de trabajo habitual con swift build y swift test debería funcionar, de lo contrario informa esto como un error.
Este proyecto utiliza SwiftFormat y Swiftlint para hacer cumplir el estilo de formato y codificación. Le recomendamos que ejecute SwiftFormat dentro de un clon local del repositorio de cualquier manera que mejor funcione para usted, ya sea de manera manual o automática, a través de una extensión de Xcode, fase de construcción o git de precomisco, etc.
Para garantizar que estas herramientas se ejecuten antes de cometer sus cambios en MacOS, se le recomienda ejecutar esto una vez para configurar el gancho previo al Commit:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Consulte la página de documentación previa al Comité para obtener más detalles e instrucciones de instalación para otras plataformas.
SwiftFormat y Swiftlint también se ejecutan en CI para cada PR y, por lo tanto, una construcción de CI puede fallar con formateo o estilo inconsistentes. Requerimos que las compilaciones de CI pasen para todos los PR antes de fusionarse.
Este proyecto se adhiere al Código de Conducta del Pacto de contribuyente. Al participar, se espera que mantenga este código. Informe un comportamiento inaceptable a [email protected].
COREXLSX está disponible bajo la licencia Apache 2.0. Consulte el archivo de licencia para obtener más información.
