Calligraphy:Android自定义字体简易方案

Calligraphy：Android自定义字体简易方案

做安卓开发的朋友，应该都经历过给 TextView 设置自定义字体的痛苦。要么写一堆自定义 View，要么遍历 ViewTree 找 TextView，烦得很。Calligraphy 这个开源库就是来解决这个问题的，它让你直接在 XML 布局里写一个 fontPath 属性就能搞定字体，不用再写那些重复代码。

这个项目在 GitHub 上有 8515 个 star，创建于 2013 年，虽然原版已经停止维护（官方建议迁移到 Calligraphy 3），但它的思路和用法至今仍有参考价值。下面我从开发者角度拆解一下这个库。

适合谁

安卓应用开发者：尤其是那些需要在应用里使用多种自定义字体的团队。不管是做阅读类 App、电商 App 还是工具类应用，只要你有品牌字体或设计规范要求，这个库都能帮你省事。

维护老项目的开发者：如果你的项目里已经有一堆自定义 View 或者 Activity 里写满了设置字体的代码，Calligraphy 可以帮你把这些零散的逻辑统一收口，代码会干净不少。

喜欢轻量方案的技术爱好者：这个库本身很小，就是一个 AAR 包，不依赖其他重型框架，接入成本低，适合喜欢精简依赖的人。

能解决什么问题

告别自定义 View：以前要做一个带自定义字体的 TextView，你得继承 TextView 然后重写构造方法，每个控件都要写一个类。用 Calligraphy，直接在 XML 里写 fontPath="fonts/MyFont.ttf" 就行，不需要新建任何 Java 类。

统一管理字体：你可以在 Application 的 onCreate() 里通过 CalligraphyConfig 设置默认字体路径，这样整个应用里没单独指定字体的 TextView 都会自动用上默认字体。比如你定义了 setDefaultFontPath("fonts/Roboto-RobotoRegular.ttf")，那所有没指定字体的地方都会用这个字体。

支持多种设置层级：Calligraphy 的字体解析顺序和 Android 框架的属性解析很像——View 上的 XML 属性优先级最高，然后是 Style、TextAppearance，接着是 Theme，最后才是默认配置。这意味着你可以灵活地在不同层级设置字体，不用每个控件都写一遍。

怎么开始用

在 build.gradle 里加依赖：

dependencies {
    compile 'uk.co.chrisjenx:calligraphy:2.3.0'
}

把你的字体文件放到 assets/ 目录下，建议建一个 fonts/ 子目录。用 Gradle 的话路径一般是 app/src/main/assets/fonts/。

在 Application 类里初始化默认配置：

@Override
public void onCreate() {
    super.onCreate();
    CalligraphyConfig.initDefault(new CalligraphyConfig.Builder()
                            .setDefaultFontPath("fonts/Roboto-RobotoRegular.ttf")
                            .setFontAttrId(R.attr.fontPath)
                            .build()
            );
}

在 Activity 里包装 Context：

@Override
protected void attachBaseContext(Context newBase) {
    super.attachBaseContext(CalligraphyContextWrapper.wrap(newBase));
}

然后在布局里直接用：

<TextView
    android:text="@string/hello_world"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    fontPath="fonts/Roboto-Bold.ttf"/>

注意 fontPath 这个属性故意没有命名空间，这是设计如此。不过 Android Studio 可能会把它标红报错，你可以在布局根节点加 xmlns:tools="http://schemas.android.com/tools"，然后给 TextView 加上 tools:ignore="MissingPrefix" 来消除报错。

优点和坑

优点：

• 接入简单，依赖就一行，初始化代码也就几行
• 支持在 View、Style、TextAppearance、Theme 多个层级设置字体，灵活度高
• 字体解析顺序和 Android 框架一致，符合直觉

坑：

• 原版已停止维护。README 开头就写了 "This version of Calligraphy has reached its end-of-life and is no longer maintained"，官方建议迁移到 Calligraphy 3（仓库在 InflationX/Calligraphy）。如果你现在新开项目，直接用新库比较好。
• IDE 会误报错误。fontPath 属性没有命名空间，Android Studio 和 IntelliJ 会把它标记为错误，虽然运行没问题，但看着闹心，还得加 tools:ignore 来压掉。
• 只能发 AAR 不能发 JAR。因为库内部需要自定义 ID 来优化字体注入流程，所以只能以 AAR 形式发布。不过现在大家都用 Gradle，这也不算大问题。
• 字体解析有个小坑。如果你在 Style 里定义了字体，又在 View 上设置了 TextAppearance，Style 里的字体会被优先使用，而不是 TextAppearance 里的。这个顺序和直觉有点不一样，容易踩到。

适合你吗

适合你：如果你在维护一个老项目，里面充斥着各种自定义字体 View 或者 Activity 里 setTypeface 的代码，想找个轻量方式统一收口，Calligraphy 2.x 可以帮你过渡。它的用法简单，迁移成本不高。

不适合你：如果你开新项目，别用这个老版本了，直接上 Calligraphy 3（InflationX/Calligraphy）。另外如果你只是给一两个 TextView 设置特殊字体，也没必要引入这个库，直接 setTypeface 反而更直接。

---

常见问题

Calligraphy是什么意思，中文怎么翻译？

Calligraphy原意是“书法”，在Android开发领域，它特指一个用于简化自定义字体设置的开源库。这个库允许开发者直接在XML布局文件中通过fontPath属性指定字体文件路径，从而告别为每个TextView编写重复代码的繁琐过程。

Calligraphy这个库现在还能用吗？

文章提到的原版Calligraphy（2.3.0版本）已停止维护，官方建议新项目迁移到Calligraphy 3。但对于维护包含大量自定义字体代码的老项目，它仍是一个轻量、接入简单的过渡方案，可以统一管理字体设置。

Calligraphy怎么安装和集成到Android项目？

集成Calligraphy非常简单。首先，在项目的build.gradle文件依赖中添加一行：compile 'uk.co.chrisjenx:calligraphy:2.3.0'。然后将字体文件放入assets/fonts/目录，并在Application类中初始化默认字体配置即可。

使用Calligraphy库有什么优点？

主要优点有：1. 接入简单，仅需一行依赖和几行初始化代码。2. 支持在View、Style、TextAppearance、Theme多个层级灵活设置字体。3. 字体解析顺序与Android框架一致，符合开发直觉。4. 能统一管理应用字体，告别自定义View。

Calligraphy和直接setTypeface比，哪个更好？

如果只是给一两个TextView设置特殊字体，直接使用setTypeface更直接，无需引入额外库。但如果需要在应用全局或大量控件中使用多种自定义字体，Calligraphy能极大减少重复代码，实现统一管理，更适合团队和品牌化项目。

相关工具推荐

• 使用MDB UI Kit套件快速打包做界面
• 为详情页挑选免费SVG图标：Heroicons图标集
• Lucide免费商用图标库：1600+个详情页图标选择