• 数据可视化
• 图表库
• 移动开发

DGCharts 是著名 Android 图表库 MPAndroidChart 的 Apple 侧移植，为 iOS、tvOS、macOS 提供 8 种开箱即用的图表类型，并支持双指缩放、拖拽平移、组合图、双轴、高亮、动画与图片导出。本指南以仓库 README.md 为主线，结合 Source/Charts 源码与双端 Demo 工程，完整覆盖从环境要求、三种包管理器安装、手动集成，到各图表类型的实战配置与底层原理，读完即可在自己的 Swift/ObjC 项目中落地图表功能。

项目背景与版本现状

DGCharts 的前身是 Charts 库，其当前仓库版本为4.0.0（同步自 MPAndroidChart 的 #f6a398b 提交）。需要特别注意的是，Charts 5.0 引入了破坏性变更：库被更名为 DGCharts，目的是避免与 Apple 官方推出的 Swift Charts 框架产生命名冲突。因此从 5.x 开始，你在代码中看到的导入语句、框架名和 Pod 名都是DGCharts，而不是此前的Charts。

库的作者选择用 Swift 编写，因为 Swift 可以被编译器高度优化，且能同时用于 Swift 与 Objective-C 项目；仓库自带 Demo 工程则特意用 Objective-C 编写，用于演示它在 ObjC 项目中的工作方式。

环境与系统要求（以当前仓库为准）

README 明确列出 master 分支的要求：

• Xcode 14 / Swift 5.7（master 分支）；如未使用最新 Swift 编译器，应前往 Releases 页面挑选适配的发行版，而不是直接检出差分较大的 master
• iOS >= 12.0（作为EmbeddedFramework 使用）
• tvOS >= 12.0
• macOS >= 10.13

这些平台下限在 DGCharts.podspec 中同样得到印证（ios.deployment_target = "12.0"、tvos.deployment_target = "12.0"、osx.deployment_target = "10.13"，且swift_version = '5.7'）。Package.swift 的平台声明为.iOS(.v12)、.tvOS(.v12)、.macOS(.v10_12)，并以swiftLanguageVersions: [.v5]锁定 Swift 5 语言版本。

仓库结构速览

• Source/Charts：库的全部源码，按 Animation、Charts、Components、Data、Formatters、Highlight、Renderers、Utils 等模块组织
• ChartsDemo-iOS：iOS/tvOS 演示工程，同时包含 Swift 与 Objective-C 两个版本的 Demo
• ChartsDemo-macOS：macOS 演示工程与 Playground 图表示例
• Tests/ChartsTests：基于快照（snapshot）的图表渲染测试

快速体验：先跑起 Demo 工程

如果只想先看效果，README 给出了两个可直接打开的工程：

• ChartsDemo-iOS/ChartsDemo-iOS.xcodeproj—— iOS/tvOS 的演示工程
• ChartsDemo-macOS/ChartsDemo-macOS.xcodeproj—— macOS 的演示工程

运行前请确认：

1. 使用的 Xcode 版本受支持（通常是最新 Xcode）；
2. 工程支持 Swift 5.0；
3. 可选：在工程目录执行carthage checkout拉取测试依赖（如测试用框架）；未安装 Carthage 时需先自行获取。

Demo 列表（DemoListViewController）覆盖了折线、柱状、气泡、蜡烛、雷达、散点、饼图、组合图、水平柱状图等全部图表类型，Swift 版位于 ChartsDemo-iOS/Swift/Demos，Objective-C 版位于 ChartsDemo-iOS/Objective-C/Demos，两套代码一一对应，便于对照学习。

安装与集成：三种包管理器 + 手动集成

手动集成（拖入 Xcode 工程）

README 给出的手动集成步骤：

1. 将DGCharts.xcodeproj拖入你的工程；
2. 在 target 的Frameworks, Libraries, and Embedded Content一节点击 "+"，选择DGCharts.framework；
3. 在代码中@import DGCharts；
4. 在ObjC 工程中使用 Swift时：
   • 需要引入工程的 Bridging Header，通常为_YourProject-Swift.h（ChartsDemo 中是_ChartsDemo-Swift.h），注意不要真的把_ChartsDemo-Swift.h加进工程；
   • Xcode 8.1 及更早版本：在 Build Options 中勾选 "Embedded Content Contains Swift Code"；
   • Xcode 8.2+：在 Build Options 中勾选 "Always Embed Swift Standard Libraries"。

需要特别指出的是手动集成与包管理器集成的区别：前者是把源码/框架复制进工程，后者是引入预编译框架，两者在后续更新与编译行为上不同（README 的 Troubleshooting 中也强调过这一点）。

CocoaPods

在 Podfile 中添加：

pod 'DGCharts'

DGCharts是库的正式名称。如果需要 Realm 数据库支持，再追加：

pod 'ChartsRealm'

注意：旧的pod 'ios-charts'并不是本库的正确名称，它指向另一个作者的无关项目，切勿混淆。DGCharts.podspec 显示该 Pod 版本为 5.1.0，默认子规格为Core（source_files = "Source/Charts/**/*.swift"），并要求 CocoaPods >= 1.5.0；同时通过resource_bundles把 Source/Charts/PrivacyInfo.xcprivacy 打包进资源，以满足隐私清单要求。

Carthage

DGCharts 从 5.x 起附带Carthage 预构建二进制，在 Cartfile 中按需选择精确或兼容版本：

github "ChartsOrg/Charts" == 5.1.0 github "ChartsOrg/Charts" ~> 5.1.0

维护者发布新版本时构建二进制的命令为：

carthage build --no-skip-current && carthage archive Charts

Swift Package Manager

在 Package.swift 的 dependencies 中声明：

dependencies: [ .package(url: "https://github.com/ChartsOrg/Charts.git", .upToNextMajor(from: "5.1.0")) ]

仓库自身的 Package.swift 暴露了两个库产品：静态的DGCharts与动态的DGChartsDynamic，二者都指向Source/Charts目录下的同一个 target，你可以根据应用对动态库/静态库的需求选择引入。

核心特性一览（附源码印证）

README 的 Features 章节列举的核心能力，几乎都能在 Source/Charts 中找到直接实现：

• 8 种图表类型：折线、柱状、散点、蜡烛、气泡、饼图、雷达、水平柱状（另有组合图）；
• 双轴缩放：触摸手势下可分别缩放 x/y 轴，或双指捏合整体缩放；
• 拖拽 / 平移：触摸手势平移视图；
• 组合图：折线、柱状、散点、蜡烛、气泡可混搭；
• 双（独立）轴：左侧与右侧各一条 Y 轴，支持不同量纲；
• 可定制坐标轴：X 轴与 Y 轴均可深度定制；
• 高亮值：支持自定义弹出视图（Marker）；
• 保存图表：可导出 PNG/JPEG 到相册或文件；
• 预定义颜色模板：内置多套配色；
• 图例（Legend）：自动生成、可定制；
• 动画：x/y 轴方向的构建动画；
• 限制线（Limit Lines）：用于标注最大值、阈值等信息；
• 完全可定制：画笔、字体、图例、颜色、背景、手势、虚线等；
• Realm 数据直连：从 Realm.io 移动数据库直接绘图（位于独立的 ChartsRealm 扩展中）。

以最常用的折线/柱状图基类 BarLineChartViewBase.swift 为例，缩放与平移正是由内部的 Tap、Double-Tap、Pinch、Pan 四类手势识别器驱动（见 BarLineChartViewBase.swift），并对外暴露pinchZoomEnabled、doubleTapToZoomEnabled、dragXEnabled、dragYEnabled、scaleXEnabled、scaleYEnabled等开关（默认值为 pinchZoom 关闭、双击缩放开启、拖拽与缩放开启，见 BarLineChartViewBase.swift）。同时它还提供setVisibleXRange(minXRange:maxXRange:)、setVisibleYRange(minYRange:maxYRange:axis:)等 API，用于限制屏幕上可见的数据范围（见 BarLineChartViewBase.swift）。

八大图表类型实战导航

每个图表在 Demo 工程中都有对应的 Swift 与 ObjC 双版本控制器，这里给出类型、要点与可参考路径：

• LineChart（折线图）：支持普通折线、贝塞尔曲线（cubic）、渐变填充、阶梯线；参考 LineChart1ViewController.swift 与 MultipleLinesChartViewController.swift
• BarChart（柱状图）：支持单组与分组（grouped）DataSet；参考 BarChartViewController.swift、MultipleBarChartViewController.swift
• HorizontalBarChart（水平柱状图）：柱条横向绘制；参考 HorizontalBarChartViewController.swift
• PieChart（饼图）：支持选中扇区、半饼图、折线标注；参考 PieChartViewController.swift、HalfPieChartViewController.swift
• ScatterChart（散点图）：内置方形、三角、圆形、十字、X 形、箭头等 ShapeRenderer；形状渲染器位于 Source/Charts/Renderers/Scatter；参考 ScatterChartViewController.swift
• CandleStickChart（蜡烛图）：面向金融数据，绘制开高低收；参考 CandleStickChartViewController.swift
• BubbleChart（气泡图）：气泡面积代表数值大小；参考 BubbleChartViewController.swift
• RadarChart（雷达图）：蛛网式多维度对比；参考 RadarChartViewController.swift
• CombinedChart（组合图）：把多种图表叠加在同一坐标系；参考 CombinedChartViewController.swift

在 Source/Charts/Charts 目录下，每种图表都是独立视图类，例如 LineChartView.swift 仅需在initialize()中把renderer替换为LineChartRenderer（见 LineChartView.swift），即可复用基类的全部交互能力——这正体现了该库"API 高度一致"的设计：所有图表共享同一套数据、手势与渲染管线。

从 Demo 到源码：折线图的完整配置拆解

以 Demo 中的 LineChart1ViewController.swift 为例，看一个生产级折线图是如何配置出来的：

import UIKit import DGCharts class LineChart1ViewController: DemoBaseViewController { @IBOutlet var chartView: LineChartView! override func viewDidLoad() { super.viewDidLoad() chartView.delegate = self chartView.chartDescription.enabled = false chartView.dragEnabled = true chartView.setScaleEnabled(true) chartView.pinchZoomEnabled = true // x 轴限制线 let llXAxis = ChartLimitLine(limit: 10, label: "Index 10") llXAxis.lineWidth = 4 llXAxis.lineDashLengths = [10, 10, 0] llXAxis.labelPosition = .rightBottom chartView.xAxis.gridLineDashLengths = [10, 10] // Y 轴上下限限制线 let ll1 = ChartLimitLine(limit: 150, label: "Upper Limit") ll1.lineWidth = 4 ll1.lineDashLengths = [5, 5] ll1.labelPosition = .rightTop let ll2 = ChartLimitLine(limit: -30, label: "Lower Limit") ll2.lineWidth = 4 ll2.lineDashLengths = [5, 5] ll2.labelPosition = .rightBottom let leftAxis = chartView.leftAxis leftAxis.removeAllLimitLines() leftAxis.addLimitLine(ll1) leftAxis.addLimitLine(ll2) leftAxis.axisMaximum = 200 leftAxis.axisMinimum = -50 leftAxis.gridLineDashLengths = [5, 5] leftAxis.drawLimitLinesBehindDataEnabled = true chartView.rightAxis.enabled = false // 本例关闭右轴 // ... 设置 DataSet 与 Entry 后 chartView.data = data } }

这段代码背后对应的源码机制包括：

• 限制线：ChartLimitLine定义于 Source/Charts/Components/ChartLimitLine.swift，可设置线宽、虚线样式、标签位置与字体，并可通过drawLimitLinesBehindDataEnabled控制绘制在数据之下还是之上；
• 坐标轴：leftAxis/rightAxis都是 YAxis 实例，分别持有独立的axisMaximum、axisMinimum与网格样式配置。在 BarLineChartViewBase.swift 中，左右轴被定义为两个独立对象，这正是"双（独立）轴"特性的实现基础：例如一条折线依赖左轴、另一条依赖右轴，即可在同一图内呈现不同量纲的数据；
• 手势与缩放：dragEnabled、pinchZoomEnabled、setScaleEnabled等属性最终都会映射到 BarLineChartViewBase.swift 内部手势识别器的启用状态（见 BarLineChartViewBase.swift 与 BarLineChartViewBase.swift）；
• 可见范围控制：setVisibleXRangeMaximum/setVisibleXRangeMinimum/setVisibleXRange以及对应的 Y 轴版本，可把缩放限制在合理区间（见 BarLineChartViewBase.swift）。

高亮与交互回调

高亮是图表的"选中反馈"机制。基类 ChartViewBase.swift 定义了ChartViewDelegate协议，包含chartValueSelected(_:entry:highlight:)、chartValueNothingSelected(_:)、chartScaled(_:scaleX:scaleY:)、chartTranslated(_:dX:dY:)、chartViewDidEndPanning(_:)等回调（见 ChartViewBase.swift），并且highlightPerDragEnabled默认开启，可在拖拽过程中持续高亮（见 BarLineChartViewBase.swift）。高亮弹窗通过自定义 Marker 实现，Demo 中可参考 XYMarkerView.swift。

动画与导出

动画 API 由 ChartViewBase.swift 提供一系列重载：animate(xAxisDuration:)、animate(yAxisDuration:)、animate(xAxisDuration:yAxisDuration:)及带easing/easingOption的版本（见 ChartViewBase.swift），底层由Animator驱动，且动画期间无需手动调用invalidate()刷新。

导出则通过getChartImage(transparent:)生成位图，再由save(to path:format:compressionQuality:)写入文件，支持ImageFormat指定的 PNG/JPEG 等格式（见 ChartViewBase.swift 与 ChartViewBase.swift）。Demo 中对应的saveToGallery选项即走此路径。

配色模板

ChartColorTemplates（定义于 Source/Charts/Utils/ChartColorTemplates.swift）内置liberty()、joyful()、pastel()等多套 5 色模板（见 ChartColorTemplates.swift），可直接赋给 DataSet 的colors属性，省去手工选色。

文档与进一步学习

• 当前 iOS/tvOS/macOS 版本暂无独立文档，因为其 API 与 Android 版95% 相同；可直接阅读 MPAndroidChart 的官方 Wiki 与文档，绝大多数内容可平移使用；
• 仓库内的 ChartsDemo-iOS（Swift + Objective-C 双版本）与 ChartsDemo-macOS 是"最佳教程"，所有类型的用法都能在其中找到完整代码；
• 需要验证渲染正确性时，可参考 Tests/ChartsTests 下的快照测试（如 BarChartTests.swift、LineChartTests.swift），它们覆盖了默认值、隐藏轴线、反转坐标轴、负值、堆叠柱等大量渲染场景；
• README 还整理了一份第三方视频教程与博客文章清单（涵盖 SwiftUI 集成、Realm + Charts、自定义 Marker 等主题），并在持续征集新的教程投稿。

常见问题排查

编译不过？按 README 的建议依次排查：

• 区分"从 CocoaPods/Carthage 安装编译好的框架"与"复制源码"两种方式，二者使用前提不同；
• 重新通读本文的安装与集成一节，重点核对 Embedded Framework、Bridging Header 与 Swift 标准库嵌入选项；
• 先在 Issues 中搜索关键词；
• 仍未解决时，在 Issues 中礼貌提问。

其他问题 / 功能请求：

• 先搜索 Issues（含已关闭的问题），确认没有重复再提问或提交新 issue。

许可证

DGCharts 遵循 Apache License 2.0，版权归 Daniel Cohen Gindi 与 Philipp Jahoda 所有（详见 LICENSE）。在遵守许可条款的前提下，可自由用于商业与开源项目。

• 数据可视化
• 图表库
• 移动开发