README_CN.md

一个用 Swift 实现的普通的 IconFont 封装，帮助你更便捷地在你的工程中使用 IconFont，同时集成了一系列可免费使用的第三方图标库。

English Introduction

预览

1	2	3	4

示例

1. 利用 git clone 命令下载本仓库；
2. 利用 cd 命令切换到仓库目录下，执行 sh Startup.sh 命令；
3. 随后打开 Example 目录下的 Example.xcworkspace 编译即可。

或执行以下命令：

git clone git@github.com:EFPrefix/EFIconFont.git; cd EFIconFont; sh Startup.sh; open Example/Example.xcworkspace;

需求

版本	需求
<0.5	Xcode 10.0+ Swift 4.2+ iOS 8.0+
>=0.5	Xcode 10.2+ Swift 5.0+ iOS 8.0+

安装

CocoaPods

EFIconFont 可以通过 CocoaPods 进行获取。只需要在你的 Podfile 中添加如下代码就能实现引入，默认只包含 Core 部分，不含字体包：

pod 'EFIconFont'

可以通过 subspecs 方式引入本库已集成的图标库资源，如下示例引用了 AntDesign 和 FontAwesome 资源：

pod 'EFIconFont', :subspecs => ['AntDesign', 'FontAwesome']

也可以通过 Complete 引入本库已集成的所有图标库资源，示例：

pod 'EFIconFont', :subspecs => ['Complete']

然后，执行如下命令即可：

pod install

Swift Package Manager

Swift Package Manager 是一个集成在 Swift 编译器中的用来进行 Swift 代码自动化发布的工具。

如果你已经建立了你的 Swift 包，将 EFIconFont 加入依赖是十分容易的，只需要将其添加到你的 Package.swift 文件的 dependencies 项中即可：

dependencies: [
    .package(url: "https://github.com/EFPrefix/EFIconFont.git", .upToNextMinor(from: "1.2.1"))
]

使用

1. 核心

实现 EFIconFontProtocol 协议的对象，能够将自身转换为 NSAttributedString 或 UIImage，该协议内容如下：

public protocol EFIconFontProtocol {

    // `name` is not necessarily equal to .ttf file name
    var name: String { get }

    // `path` is path of .ttf file
    var path: String { get }

    // `attributes` is style of icon
    var attributes: [NSAttributedString.Key : Any] { set get }

    // `unicode` is unique identifier of particular icon
    var unicode: String { get }
    
    // `font` is UIFont of icon with input font size
    func font(size fontSize: CGFloat) -> UIFont?
}

• name：字体名，与 .ttf 文件名并不一定相等，可通过 BirdFont 等字体文件处理工具查看其 Name 属性取得；
• path：.ttf 文件路径，一般通过形如 Bundle.main.path(forResource: name, ofType: "ttf") 的方式获取（若文件名和 name 相同，则无须实现该属性，使用默认实现即可）；
• attributes: 某 icon 的样式（若无特殊需求，使用默认实现即可）；
• unicode：某符号的 unicode；
• font: 根据输入的 fontSize 对应的某图标的 UIFont。

实现该协议的对象，可通过调用下列方法进行转换输出为字符串和图片，可改变前景色和大小：

// MARK:- String
func attributedString(size fontSize: CGFloat, attributes: [NSAttributedString.Key : Any]?) -> NSAttributedString?
func attributedString(size fontSize: CGFloat, foregroundColor: UIColor? = nil, backgroundColor: UIColor? = nil) -> NSAttributedString?

// MARK:- Image
func image(size fontSize: CGFloat, attributes: [NSAttributedString.Key : Any]?) -> UIImage?
func image(size fontSize: CGFloat, foregroundColor: UIColor? = nil, backgroundColor: UIColor? = nil) -> UIImage?
func image(size imageSize: CGSize, attributes: [NSAttributedString.Key : Any]?) -> UIImage?
func image(size imageSize: CGSize, foregroundColor: UIColor? = nil, backgroundColor: UIColor? = nil) -> UIImage?

2. 自带图标库

本库已集成了 AntDesign、FontAwesome 等免费图标库资源，需要使用的同学引入即可，如下所示，会得到一个 EFIconFontProtocol 类型的返回值：

EFIconFontAntDesign.addteam

可通过遵循 EFIconFontProtocol 协议的对象获取 NSAttributedString 和 UIImage：

EFIconFontAntDesign.addteam.attributedString(size: 24)
EFIconFontFontAwesomeBrands.adobe.attributedString(size: 32, foregroundColor: UIColor.white, backgroundColor: UIColor.green)
EFIconFontFontAwesomeRegular.addressBook.image(size: 24, foregroundColor: UIColor.red)
EFIconFontFontAwesomeSolid.alignLeft.image(size: CGSize(width: 36, height: 48), foregroundColor: UIColor.white)

可通过如下方式获取某个图标库的全部项目，他会返回 [String : EFIconFontProtocol] 类型的 Dictionary：

EFIconFont.antDesign.dictionary

备注：虽为免费图标库，但还请自行确保您的使用方式遵循字库原始作者的使用协议规范：

名称	版本	数量	文件大小	描述	使用规范	预览
AliCloudConsole	1.0	266	42KB	阿里云控制台官方图标库	Unknown	iconfont.cn
AntChain	1.0	77	17KB	AntChain 蚂蚁链官方图标库	未知	iconfont.cn
AntDesign		557	127KB	AntDesign 所属图标库	MIT	iconfont.cn
Dashicons	0.9.0	203	51 KB	WordPress admin 官方图标库	GPLv2	wordpress.org
Devicons	1.8.0	192	92KB	各种开发工具、编程语言的图标	MIT	vorillaz.github.io/devicons
ElusiveIcons	2.0.0	304	53KB	Elusive Icons	OFL	elusiveicons.com
EVAIcon		21	45 KB	EVA	OFL	EVA-icon
EvilIcons	1.10.1	70	16 KB	简洁的图标库	MIT	evil-icons.io
FontAwesome（Regular / Brands / Solid）	5.8.1	1516	356KB	FontAwesome 所属的免费图标库	Font Awesome Free License	fontawesome.com
FoundationIcons	3.0	283	68KB	Foundation Icon Fonts 3	-	zurb.com/playground/foundation-icon-fonts-3
Genericons	4.0.4	103	16KB	通用外观图标库，适用于博客 / 简单网站	GPLv2	genericons.com
Hawcons	1.0	1035	685KB	Hawcons 免费图标库，包括文档、体育、天气、表情、手势、文件类型等	Free	hawcons.com
IcoMoon	1.0	490	94KB	IcoMoon 免费图标库	CC BY 4.0 / GPL	ionicons.com
Ionicons	4.5.5	696	143KB	Ionicons 免费图标库	MIT	ionicons.com
LigatureSymbols	2.11	239	84KB	Ligature Symbols	OFL	kudakurage.com/ligature_symbols
MapIcons	3.0.0	192	48 KB	一系列可以配合地图使用的图标	OFL	map-icons.com
MaterialIcons	3.0.1	1057	695KB	Google 的 Material 图标库，4 种样式	Apache-2.0	material.io
Meteocons		47	15KB	一个天气图标库	Free	alessioatzeni.com/meteocons
MetrizeIcons	1.0	300	74KB	300 个给设计和开发人员的免费图标	Free	alessioatzeni.com/metrize-icons
OpenIconic	1.1.1	223	33KB	223 个开源矢量图标集	OFL	useiconic.com/open
StrawberryIcon	2.0.0	382	69KB	为开发者设计的一套免费开源图标库	OFL	chuangzaoshi.com/icon
Stroke7	1.2.0	202	44KB	Stroke 7 免费图标集	Free	themes-pixeden.com/font-demos
TaoBao	1.0	434	126KB	手机淘宝图标库	未知	iconfont.cn
ThemifyIcons	1.0	352	68KB	Handcrafted 免费图标库	Free	themify.me
Tmall	1.0	564	190KB	天猫图标库	未知	iconfont.cn
Typicons	2.0.9	336	82KB	336 个矢量图标集合在一个库内	OFL	s-ings.com/typicons
VSCodeIcons	1.0	133	24KB	Visual Studio Code 图标库	MIT	github.com/microsoft/vscode-icons
WeatherIcons	2.0.10	219	64KB	天气相关图标	OFL	erikflowers.github.io/weather-icons
Zocial	1.3.0	112	31KB	社交媒体相关图标	MIT	smcllns.github.io/css-social-buttons/

3. 自定义图标库

(1) 字体文件引入

将我们通过各种方式获取的图标库的 .ttf 文件拖入 Xcode 工程中，并确保 Build Phases 中的 Copy Bundle Resources 列表中包含这个字体文件（默认拖入工程就会被包含在内）。

另外，此文件会在运行时按需加载，无需添加到 Info.plist 文件中的 Fonts provided by application 项内。

(2) 实现 EFIconFontCaseIterableProtocol

可通过实现 EFIconFontCaseIterableProtocol 协议实现图标库的封装，本项目中 Example 以 GitHub 所有的 Octicons 为例 演示 了自定义方式：

import EFIconFont

public extension EFIconFont {
    public static let octicons = EFIconFontOcticons.self
}

extension EFIconFontOcticons: EFIconFontCaseIterableProtocol {
    public static var name: String {
        return "octicons"
    }
    public var unicode: String {
        return self.rawValue
    }
}

public enum EFIconFontOcticons: String {
    case thumbsup = "\u{e6d7}"
    case unverified = "\u{e6d6}"
    case unfold = "\u{e6d5}"
    case verified = "\u{e6d4}"
    // ...
}

有人要问这个巨长无比的枚举是怎么手打出来的？当然是代码生成的了...先把 .svg 图片上传到 iconfont.cn，然后看 这里。

(3) 调用

同上自带图标库的使用。

EFIconFontOcticons.thumbsup

(4) 注意事项

本项目 Example 中的 Octicons 图标库为 GitHub 所有，此处仅为演示，请勿用于任何违反其所有者所定规范的场合：

名称	版本	数量	文件大小	描述	使用规范	预览
Octicons	8.4.2	184	34KB	GitHub 所属图标库	GitHub Logos and Usage	octicons.github.com

4. 其它

一些 IconFont 资源站点素材的爬取以及代码生成方式：

• iconfont.cn
• fontawesome.com
• material.io/icons/

作者

EyreFree, eyrefree@eyrefree.org

协议

EFIconFont 基于 MIT 协议进行分发和使用，更多信息参见 协议文件。