CoreXLSX

纯 Swift 编写的 Excel 工作表 (XLSX) 格式解析器

CoreXLSX 是一个专注于表示基于 XML 的 XLSX 工作表格式的底层结构的库。它允许您打开具有 .xlsx 扩展名的电子表格存档，并将其内部结构映射到直接在 Swift 中表达的模式类型。

请注意，此库仅提供对 .xlsx 格式 的只读支持。因为较旧的 旧版 .xls 电子表格格式 具有完全不同的内部结构，如果需要处理此类文件，请参阅 其他库。

如果您的 .xlsx 文件使用了 ECMA-376 动态加密（这似乎是最受欢迎的类型），请查看 CryptoOffice 库。

自动生成的文档可在我们的 GitHub Pages上获得。

示例

要运行示例项目，请克隆仓库，然后首先从 Example 目录运行 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 模型。

公共字符串

工作簿内部的字符串通常表示为多个工作表之间共享的字符串。要从一个单元格中解析字符串值，您应该在 Cell 上使用 stringValue(_: SharedStrings) 函数，并与 XLSXFile 上的 parseSharedString() 一起使用。

例如，以下是获取列 "C" 中所有字符串的方法

if let sharedStrings = try file.parseSharedStrings() {
  let columnCStrings = worksheet.cells(atColumns: [ColumnReference("C")!])
    .compactMap { $0.stringValue(sharedStrings) }
}

要解析单元格中的日期值，请使用 Cell 类型的 dateValue 属性

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 协议，详细的错误会生成，列出一个缺失的属性，可以轻松添加到模型中，从而支持更广泛的数据格式。附上无法解析的文件也将大大有助于诊断问题。如果这些文件包含任何敏感数据，我们建议使用生成原始文件的同一工具进行混淆或生成假数据，假设问题可以通过这种方式重新创建。

如果无法附件完整文件，请尝试向 XLSXFile 初始化器的 errorContextLength 参数传递一个足够大的值（通常在10至20之间效果较好）。这将将与错误相关的XML片段与抛出错误的调试描述捆绑在一起。如果在报告问题的情况下可能的话，请附加完整的调试描述。

它是如何工作的？

由于每个XLSX文件都是一个XML文件的zip存档，CoreXLSX使用XMLCoder库和标准的Codable协议将XML节点和属性映射到普通的Swift结构。使用ZIPFoundation进行zip存档的内存中解压缩。详细介绍在这里。

需求

Apple平台

• Xcode 11.3或更新版本
• Swift 5.1或更新版本
• iOS 9.0 / watchOS 2.0 / tvOS 9.0 / macOS 10.11或更新的部署目标

Linux

• Ubuntu 16.04或更新版本
• Swift 5.1或更新版本

安装

Swift包管理器

Swift包管理器是一个用于管理Swift代码分发的工具。它与Swift构建系统集成，以自动化所有平台的依赖项的下载、编译和链接过程。

在设置了您的Swift包之后，将CoreXLSX作为依赖项添加就像将其添加到Package.swift的dependencies值一样简单。

dependencies: [
  .package(url: "https://github.com/CoreOffice/CoreXLSX.git",
           .upToNextMinor(from: "0.14.0"))
]

如果您使用的是用Xcode构建的应用程序中的CoreXLSX，您也可以使用Xcode的GUI将其添加为直接依赖项使用Xcode的GUI。

CocoaPods

CoreXLSX可以通过CocoaPods在apple平台上使用。[CocoaPods] 安装它，只需在您的Podfile中添加以下代码 pod 'CoreXLSX', '~> 0.14.0'，如下所示

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.0'
end

贡献

赞助

如果这个库为您节省了任何时间或金钱，请考虑 赞助其维护者 的工作。虽然一些赞助等级会提供优惠支持甚至咨询时间，但任何金额都是受欢迎的，并有助于保持项目的运营。

开发流程

在macOS上，最简单的工作方式是使用Xcode 11或更高版本打开Package.swift文件。有一个完整的测试套件，它同时测试了文件端到端和独立片段与其对应的模型值。

如果您想不使用Xcode，该项目完全支持SwiftPM，使用swift build和swift test常规流程应该可以工作；否则，请将此作为问题报告。

编码规范

本工程使用SwiftFormat和SwiftLint来强制执行格式和编码风格。我们鼓励您以最适合您的方式在本地仓库副本中运行SwiftFormat，无论是手动运行还是通过Xcode扩展、构建阶段或Git预先提交钩子等方式自动运行。

为保证在macOS上提交更改前这些工具已运行，我们建议您运行此命令一次以设置pre-commit钩子。

brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit

有关更多信息和其他平台的安装说明，请参阅pre-commit文档页面。

SwiftFormat和SwiftLint还针对每个PR在CI（持续集成）上运行，因此CI构建可能会由于格式或不一致的风格而失败。我们要求在合并之前所有PR的CI构建都必须通过。

行为准则

本项目遵循贡献者行为准则。通过参与，您应遵守这一准则。如有不适当行为，请向[email protected]报告。

维护者

Max Desiatov，Matvii Hodovaniuk。

许可证

CoreXLSX采用Apache 2.0许可证。有关更多信息，请参阅LICENSE文件。