Android 开发实战：如何从零开始生成自定义 PDF 文件

在移动应用开发中，我们经常遇到需要将应用内的数据导出为更加正式、不易篡改格式的场景。PDF（Portable Document Format）文件因其跨平台兼容性和版面固定性，成为了许多应用（如电子发票、账单、报告生成器）的首选方案。你有没有想过，如何在 Android 应用中通过代码动态生成一个包含图片、文本和复杂排版的 PDF 文件呢？

在这篇文章中，我们将深入探讨如何在 Android 应用中从零开始创建 PDF 文件。我们将绕过那些繁重的第三方库，直接利用 Android 原生提供的强大 API——INLINECODE111a6fcf 和 INLINECODE6ab2ea9c——来实现这一功能。这不仅能减少应用的体积，还能让你对生成的每一个像素都拥有完全的控制权。准备好了吗？让我们一起踏上这段从屏幕到文档的探索之旅。

为什么选择原生 Canvas 绘制 PDF？

在开始编写代码之前，我想先和你聊聊为什么我们要选择使用 Canvas 来绘制 PDF。简单来说，Android 中的 PDF 生成机制其实就是把我们平时在屏幕上绘制 UI 的过程，搬到了一张虚拟的“纸”上。当我们使用 Canvas 时，我们实际上是在告诉系统：“在这里画一行字，在那里画一张图片，再画一个矩形”。

这种方法的强大之处在于它的灵活性。如果我们只是简单地生成纯文本，那可能有很多现成的库可以用。但一旦你需要添加公司 Logo、调整字体样式、改变颜色，或者按照特定排版（比如居中、左对齐）来组织内容，直接使用 Canvas 绘制就是最高效、最直观的方式。这就好比我们是在代码里拿着一支画笔，在一张白纸上自由创作。

项目概览：我们将要构建什么

为了让你更直观地理解，我们将构建一个简单的示例应用。这个应用的主界面上只有一个按钮——"生成 PDF"。当你点击这个按钮时，应用会悄悄地在后台做很多工作：它会获取一张应用内的图片，获取一段文本，创建一个新的 PDF 文档页面，把这些内容通过画笔画上去，最后将生成的 PDF 文件保存到你设备的外部存储目录中。你可以在文件管理器中找到它，并在任何 PDF 阅读器中打开查看。

下面，让我们进入实际的编码环节，看看每一步是如何实现的。

步骤 1：搭建项目基础

首先，我们需要在 Android Studio 中创建一个新的项目。这一步是所有 Android 开发的起点。你可以选择 "Empty Activity" 模板，为了保持代码的清晰和兼容性，我们在本示例中继续使用 Java 语言。

创建好项目后，我们需要确保应用的依赖库是完整的。虽然我们使用的是原生 API，但涉及到一些 AndroidX 的组件（如 INLINECODE85094a4f），所以请确保你的 INLINECODE7a170a9f 文件中已经配置了基本的依赖。

步骤 2：设计用户界面

虽然我们的重点是后端的 PDF 生成，但一个友好的用户界面是触发这个功能的入口。让我们进入 res/layout/activity_main.xml 文件，设计一个简洁的界面。

我们将使用 INLINECODEf1562851 作为根布局，并在其中放置一个 INLINECODEfff246c6 和一个 Button。代码如下：

在这个布局中，我们添加了一个居中的按钮。这个按钮将是我们交互的起点。当用户点击它时，我们就触发 PDF 生成的逻辑。

步骤 3：配置存储权限

这是 Android 开发中非常关键的一步。由于我们要将生成的 PDF 文件保存到外部存储（External Storage）中，根据 Android 的安全机制，我们必须在 AndroidManifest.xml 文件中显式声明权限，并在运行时请求用户授权（针对 Android 6.0 及以上版本）。

首先，打开 INLINECODE91404100，在 INLINECODE86367dc0 标签之前添加以下权限声明：

步骤 4：准备资源文件

为了展示 PDF 生成过程中对图片的处理，我们需要一张图片。你可以将一张名为 INLINECODEdb3b8176 的图片文件复制到项目的 INLINECODE4a6676ff 文件夹下。在后续的代码中，我们将通过资源 ID 引用这张图片，并将其绘制在 PDF 的顶部，作为模拟的“公司 Logo”或“文档标题图片”。

步骤 5：核心逻辑实现 —— MainActivity.java

这是本文最核心的部分。我们将深入 MainActivity.java 文件，一步步拆解代码的执行流程。为了保证代码的健壮性，我们还实现了运行时权限检查的逻辑。

以下是完整的代码实现，我已在代码中添加了详细的中文注释来帮助你理解每一个步骤：

package com.example.pdfgenerationapp;

import android.Manifest;
import android.content.Context;
import android.content.pm.PackageManager;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Typeface;
import android.graphics.pdf.PdfDocument;
import android.os.Bundle;
import android.os.Environment;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;

public class MainActivity extends AppCompatActivity {

    // 定义按钮变量
    private Button generatePDFbtn;

    // 定义 PDF 页面的高度和宽度
    // 这里使用的是 A4 纸的大致尺寸（单位：点，1英寸约为72点）
    private int pageHeight = 1120;
    private int pageWidth = 792;

    // 权限请求码
    private static final int PERMISSION_REQUEST_CODE = 200;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 初始化视图
        generatePDFbtn = findViewById(R.id.idBtnGeneratePDF);

        // 设置按钮点击事件
        generatePDFbtn.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                // 在生成文件前，先检查权限
                if (checkPermission()) {
                    generatePDF();
                } else {
                    requestPermission();
                }
            }
        });
    }

    /**
     * 检查是否拥有存储权限
     */
    private boolean checkPermission() {
        // 检查写入权限
        int writePermission = ContextCompat.checkSelfPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE);
        // 注意：在较新的 Android 版本中，可能只需要请求写入权限即可涵盖读取，
        // 但为了兼容性，这里进行统一检查
        return writePermission == PackageManager.PERMISSION_GRANTED;
    }

    /**
     * 请求权限
     */
    private void requestPermission() {
        // 请求必要的权限
        ActivityCompat.requestPermissions(this, new String[]{
                Manifest.permission.WRITE_EXTERNAL_STORAGE
        }, PERMISSION_REQUEST_CODE);
    }

    /**
     * 处理权限请求的回调结果
     */
    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
        if (requestCode == PERMISSION_REQUEST_CODE) {
            if (grantResults.length > 0) {
                boolean writeStorage = grantResults[0] == PackageManager.PERMISSION_GRANTED;

                if (writeStorage) {
                    // 权限获取成功，生成 PDF
                    Toast.makeText(this, "权限已授予", Toast.LENGTH_SHORT).show();
                    generatePDF();
                } else {
                    // 权限被拒绝，提示用户
                    Toast.makeText(this, "权限被拒绝，无法保存 PDF", Toast.LENGTH_SHORT).show();
                }
            }
        }
    }

    /**
     * 核心：生成 PDF 文件的方法
     */
    private void generatePDF() {
        // 初始化 PdfDocument 对象
        PdfDocument pdfDocument = new PdfDocument();

        // 创建一个页面信息对象，指定页面的宽和高
        PdfDocument.PageInfo pageInfo = new PdfDocument.PageInfo.Builder(pageWidth, pageHeight, 1).create();

        // 启动一个新页面，获取 Canvas 对象
        PdfDocument.Page page = pdfDocument.startPage(pageInfo);

        Canvas canvas = page.getCanvas();
        Paint paint = new Paint();

        // --- 1. 绘制标题 ---
        // 设置标题文字颜色
        paint.setColor(Color.rgb(0, 114, 188)); // 蓝色
        // 设置文字大小
        paint.setTextSize(24);
        // 设置文字样式为粗体
        paint.setTypeface(Typeface.create(Typeface.DEFAULT, Typeface.BOLD));
        // 绘制标题文字（x坐标, y坐标, 文字内容, 画笔）
        canvas.drawText("这是一个 PDF 生成示例", 150, 100, paint);

        // --- 2. 绘制图片 ---
        // 解码 drawable 文件夹中的图片资源
        Bitmap bmp = BitmapFactory.decodeResource(getResources(), R.drawable.gfglogo);
        // 缩放图片以适应页面（这里按需缩放）
        Bitmap scaledBmp = Bitmap.createScaledBitmap(bmp, 100, 100, false);
        // 绘制图片（图片对象, 左边距, 顶边距, null）
        canvas.drawBitmap(scaledBmp, pageWidth / 2 - 50, 120, null);

        // --- 3. 绘制正文内容 ---
        // 重置画笔样式
        paint.setColor(Color.BLACK);
        paint.setTextSize(18);
        paint.setTypeface(Typeface.DEFAULT);
        
        String content = "在本文中，我们学习如何使用 Android 的 Canvas API 来创建 PDF。";
        // 绘制文本，注意控制换行和 Y 轴坐标
        canvas.drawText(content, 100, 250, paint);
        
        String subContent = "这个功能在生成发票、账单或电子书时非常有用。";
        canvas.drawText(subContent, 100, 280, paint);

        // --- 4. 绘制底部矩形和页码 ---
        // 设置一个半透明的灰色矩形作为底部背景
        paint.setColor(Color.parseColor("#D3D3D3"));
        paint.setStyle(Paint.Style.FILL);
        canvas.drawRect(0, pageHeight - 150, pageWidth, pageHeight, paint);

        // 绘制底部文字
        paint.setColor(Color.BLACK);
        canvas.drawText("感谢阅读本文！", 100, pageHeight - 100, paint);
        canvas.drawText("第 1 页", pageWidth - 100, pageHeight - 100, paint);

        // 结束当前页面的绘制
        pdfDocument.finishPage(page);

        // --- 5. 保存文件到存储 ---
        // 获取应用的外部文件目录
        // 注意：targetSdkVersion >= 29 时，推荐使用 Context.getExternalFilesDir
        // 这里为了兼容性展示，通常会保存在 Download 或 Documents 目录
        File file = new File(Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS), "Demo.pdf");

        try {
            // 创建文件输出流
            FileOutputStream fos = new FileOutputStream(file);
            // 将 PDF 文档写入文件
            pdfDocument.writeTo(fos);
            // 关闭流和文档
            fos.flush();
            fos.close();
            pdfDocument.close();

            Toast.makeText(this, "PDF 已生成并保存到: " + file.getAbsolutePath(), Toast.LENGTH_LONG).show();

        } catch (IOException e) {
            e.printStackTrace();
            Toast.makeText(this, "生成 PDF 失败: " + e.toString(), Toast.LENGTH_SHORT).show();
        }
    }
}

代码深度解析与最佳实践

上面的代码虽然只是一个示例，但它包含了 PDF 生成流程中最重要的几个环节。让我们来深入挖掘一下其中的技术细节，这能帮助你在实际项目中更好地运用它。

#### 1. 关于坐标系统

在 Android 的 View 中，坐标原点 INLINECODEd7460094 在屏幕左上角，向右是 X 轴正方向，向下是 Y 轴正方向。PDF 的 Canvas 也是完全一样的规则。这意味着，如果你想在页面顶部留出 50px 的空白，你的绘制 Y 坐标应该从 50 开始。在上面的例子中，我们定义的 INLINECODEf4a50299 为 1120，这是一个比较接近 A4 纸比例的数值（如果不做任何缩放直接打印，可能会因为物理尺寸问题显得较小，但在屏幕阅读时是没问题的）。

#### 2. 如何处理文字换行？

细心的你可能会发现，INLINECODEb26067b4 方法并不会自动处理换行。如果你传入了一串很长的字符串，它会一直延伸到屏幕之外。在实际开发中，我们需要自己实现简单的换行逻辑。通常的做法是：创建一个辅助方法，测量字符串的宽度（INLINECODE1c47384c），如果超过设定的页面宽度（减去页边距），就手动截断字符串并移动到下一行继续绘制。这虽然增加了一些编码工作量，但也给了我们精确控制排版的自由。

#### 3. 内存管理与 Bitmap

在代码中，我们加载了一张图片并将其绘制到 Canvas 上。记得在使用 INLINECODEf2f089f0 后，如果不再需要使用该 Bitmap，应当调用 INLINECODE7d755cfd 方法（虽然 Java 机制会处理，但在高频处理大量图片时手动回收是个好习惯）。此外，直接绘制原始尺寸的大图片可能会导致 PDF 文件体积过大，甚至内存溢出（OOM）。因此，使用 Bitmap.createScaledBitmap() 进行适当的缩放是非常有必要的。

#### 4. 权限策略的演变

随着 Android 系统的更新（特别是 Android 10+ 和 Android 11+），对外部存储的访问变得越来越严格。上面的代码使用了 INLINECODEad0f4db4，这需要传统的存储权限。如果你的应用的目标 API 级别较高（API 29+），你可能需要考虑使用 INLINECODE20c22c8a API 或者将文件保存在应用专有的外部存储目录 Context.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS) 中，后者不需要权限声明，且更容易适配 Scoped Storage。

潜在的陷阱与解决方案

在实际项目中，你可能会遇到以下几个常见问题，这里我们提前给出解决方案：

• 中文乱码问题：Android 默认的 Canvas 绘制中文是可以正常显示的，但前提是你使用的字体支持中文。如果你引入了自定义的英文字体，可能会导致中文字符无法显示或显示为方框。解决办法是确保绘制中文时使用系统默认字体或包含中文字符集的自定义 TypeFace。

• 生成的文件无法打开：如果你在 INLINECODE3f3e83b2 之前就调用了 INLINECODE9eccef87，或者中途抛出了异常导致文件流没有正确关闭，生成的 PDF 文件就会损坏。使用 Java 的 try-catch-finally 块来确保 FileOutputStream 在任何情况下都能被正确关闭是一个好习惯。

结尾与展望

通过这篇文章，我们从零构建了一个完整的 PDF 生成工具。我们学习了如何创建项目、设计布局、处理 Android 运行时权限，最重要的是，我们掌握了如何使用 INLINECODEba2addd3 和 INLINECODEb6db5831 将代码转化为可视化的文档。

掌握这项技术后，你可以不仅仅局限于生成文本。你可以尝试绘制复杂的表格（使用 INLINECODE397e2c65 和 INLINECODE6ea67438），甚至将 Android 界面的 View 转换成 Bitmap 并绘制到 PDF 中（例如生成一份当前屏幕的截图报告）。希望这篇文章能为你打开一扇通往高级 Android 开发的大门，在你的下一个项目中，无论是生成电子票据还是学习资料报告，你都能游刃有余地应用这些知识。