CoreXLSX
0.14.2
O Corexlsx é uma biblioteca focada em representar a estrutura de baixo nível do formato de planilha XLSX baseado em XML. Ele permite que você abra um arquivo de planilha com extensão .xlsx e mapeie sua estrutura interna em tipos de modelos expressos diretamente no Swift.
Importante observar que esta biblioteca fornece suporte somente leitura apenas para o formato .xlsx . Como o formato de planilha .xls mais antigo Legacy possui internos completamente diferentes, consulte outras bibliotecas se precisar trabalhar com arquivos desse tipo.
Se seus arquivos .xlsx usarem a criptografia ágil do ECMA-376 (que parece ser a variedade mais popular), dê uma olhada na biblioteca do CryptoOffice.
A documentação gerada automaticamente está disponível em nossas páginas do GitHub.
Junte -se à nossa discórdia para qualquer dúvida e brincadeira amigável.
Para executar o projeto de exemplo, clone o repo e execute pod install no diretório Exemplo primeiro.
Os tipos de modelo no CoreXLSX mapeiam diretamente a estrutura interna do formato XLSX com nomeação mais sensata aplicada a alguns atributos. A API é bem simples:
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 )
}
}
}
} Isso imprime dados de células cruas de todas as planilhas do arquivo XLSX fornecido. Consulte o modelo Worksheet para obter mais atttributes que você pode precisar ler em um arquivo analisado.
Você não deve abordar as células por meio de seus índices na matriz cells . Cada célula possui uma propriedade reference , que você pode ler para entender onde exatamente uma determinada célula está localizada. As propriedades correspondentes na estrutura CellReference fornecem a posição exata de uma célula.
O formato .xlsx faz uma distinção clara entre uma célula vazia e a ausência de uma célula. Se você não está recebendo uma célula ou uma linha ao iterar através da matriz cells , isso significa que não existe essa célula ou linha no seu documento. Seu documento .xlsx deve ter células e linhas vazias escritas nele em primeiro lugar para você poder lê -las.
Fazer essa distinção torna o formato mais eficiente, especialmente para planilhas escassas. Se você tivesse uma planilha com uma única célula Z1000000, ela não conteria milhões de células vazias e uma única célula com um valor. O arquivo armazena apenas uma única célula, que permite que as planilhas esparsas sejam salvas e carregadas rapidamente, também ocupando menos espaço no sistema de arquivos.
Dado como o formato .xlsx armazena células, você potencialmente precisa iterar em todas as células e criar seu próprio mapeamento a partir de referências de células para valores celulares reais. A biblioteca Corexlsx atualmente não faz isso automaticamente e você precisará implementar seu próprio mapeamento, se precisar. Você pode enviar uma solicitação de tração que adiciona essa funcionalidade como uma etapa opcional durante a análise.
As cordas nas planilhas internas são frequentemente representadas como seqüências compartilhadas entre várias planilhas. Para analisar um valor de string de uma célula, você deve usar a função stringValue(_: SharedStrings) na Cell juntamente com parseSharedString() no XLSXFile .
Veja como você pode obter todas as cordas na coluna "C", por exemplo:
if let sharedStrings = try file . parseSharedStrings ( ) {
let columnCStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . stringValue ( sharedStrings ) }
} Para analisar um valor de data de uma célula, use a propriedade dateValue no tipo Cell :
let columnCDates = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . dateValue } Da mesma forma, para analisar strings ricos, use a função richStringValue :
if let richStrings = try file . parseSharedStrings ( ) {
let columnCRichStrings = worksheet . cells ( atColumns : [ ColumnReference ( " C " ) ! ] )
. compactMap { $0 . richStringValue ( sharedStrings ) }
} Desde a versão 0.5.0, você pode analisar as informações do estilo do arquivo com a função New parseStyles() . Consulte o modelo Styles para obter mais detalhes. Você também deve observar que nem todos os arquivos XLSX contêm informações de estilo, portanto, você deve estar preparado para lidar com os erros lançados da função parseStyles() nesse caso.
Aqui está um pequeno exemplo que busca uma lista de fontes usadas:
let styles = try file . parseStyles ( )
let fonts = styles . fonts ? . items . compactMap { $0 . name ? . value } Para obter formatação para uma determinada célula, use format(in:) e font(in:) funções, passando o resultado do 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 ) Se você tropeçar em um arquivo que não pode ser analisado, registre um problema postando a mensagem de erro exata. Graças ao uso do protocolo Codable SWIFT padrão, erros detalhados são gerados listando um atributo ausente, para que ele possa ser facilmente adicionado ao modelo que permite o suporte mais amplo de formato. Anexar um arquivo que não pode ser analisado também ajudaria muito a diagnosticar problemas. Se esses arquivos contiverem dados confidenciais, sugerimos ofuscar ou gerar dados falsos com as mesmas ferramentas que geraram arquivos originais, assumindo que o problema ainda possa ser reproduzido dessa maneira.
Se o arquivo inteiro não puder ser anexado, tente passar um valor suficientemente grande (entre 10 e 20 geralmente funcionará bem) para o argumento errorContextLength do XLSXFile . Isso agrupará o snippet XML com a descrição de depuração dos erros lançados. Anexe também a descrição completa da depuração, se possível, ao relatar problemas.
Como cada arquivo XLSX é um arquivo zip de arquivos XML, CoreXLSX usa a biblioteca XMLCoder e os protocolos Codable padrão para mapear nós XML e atributos em estruturas rápidas simples. ZIPFoundation é usado para descompressão na memória dos arquivos do ZIP. Uma descrição detalhada está disponível aqui.
Plataformas da Apple
Linux
O Swift Package Manager é uma ferramenta para gerenciar a distribuição do código SWIFT. Está integrado ao sistema SWIFT Build para automatizar o processo de download, compilação e vinculação dependências em todas as plataformas.
Depois de configurar seu pacote SWIFT, adicionar CoreXLSX como uma dependência é tão fácil quanto adicioná -lo ao valor de dependencies do seu Package.swift .
dependencies: [
. package ( url : " https://github.com/CoreOffice/CoreXLSX.git " ,
. upToNextMinor ( from : " 0.14.1 " ) )
]Se você estiver usando o Corexlsx em um aplicativo construído com o Xcode, também poderá adicioná -lo como uma dependência direta usando a GUI do Xcode.
O Corexlsx está disponível através de Cocoapods nas plataformas da Apple. Para instalá -lo, basta adicionar pod 'CoreXLSX', '~> 0.14.1' ao seu Podfile , como mostrado aqui:
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 No MacOS, a maneira mais fácil de começar a trabalhar no projeto é abrir o arquivo Package.swift no Xcode 11 ou posterior. Há um extenso conjunto de testes que ambos os testes arquivos de ponta a ponta e snippets isolados em relação aos valores correspondentes do modelo.
Se você preferir não trabalhar com o Xcode, o projeto suporta totalmente o SWIFTPM e o fluxo de trabalho usual com o teste swift build e swift test deve funcionar; caso contrário, relate isso como um bug.
Este projeto usa SwiftFormat e Swiftlint para aplicar o estilo de formatação e codificação. Incentivamos você a executar o SwiftFormat dentro de um clone local do repositório da maneira que funcionar melhor para você manual ou automaticamente por meio de uma extensão Xcode, fase de construção ou gancho de pré-compromisso Git etc.
Para garantir que essas ferramentas sejam executadas antes de cometer suas alterações no macOS, você é incentivado a executar isso uma vez para configurar o gancho de pré-compromisso:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Consulte a página de documentação de pré-compromisso para obter mais detalhes e instruções de instalação para outras plataformas.
Swiftformat e Swiftlint também são executados no CI para cada PR e, portanto, uma construção de IC pode falhar com formatação ou estilo inconsistente. Exigimos que as compilações de IC passem para todos os PRs antes de se fundir.
Este projeto segue o Código de Conduta do Covenant Colaborador. Ao participar, você deve defender este código. Por favor, relate um comportamento inaceitável a [email protected].
Corexlsx está disponível sob a licença Apache 2.0. Consulte o arquivo de licença para obter mais informações.
