53、Android 自定义文档打印与 App 链接开发指南

Android 自定义文档打印与 App 链接开发指南

1. Android 自定义文档打印

1.1 文档绘制

在自定义文档打印中，首先需要在文档上绘制内容。以下是绘制标题和正文的代码示例：

paint.setTextSize(14); 
canvas.drawText("This is some test content to verify that custom document printing works", leftMargin, titleBaseLine + 35, paint);

绘制完正文后，还会在页面中心绘制一个圆，偶数页的圆为红色，奇数页的圆为绿色：

if (pagenumber % 2 == 0)
       paint.setColor(Color.RED);
else
       paint.setColor(Color.GREEN);

PageInfo pageInfo = page.getInfo();

canvas.drawCircle(pageInfo.getPageWidth()/2,
                  pageInfo.getPageHeight()/2, 
                  150, paint);

1.2 启动打印任务

当用户点击“Print Document”按钮时，会触发 printDocument() 方法来启动打印任务。以下是该方法的代码：

package com.ebookfrenzy.customprint;
import android.print.PrintManager;
import android.view.View;

public class MainActivity extends AppCompatActivity {

       public void printDocument(View view)
       {
           PrintManager printManager = (PrintManager) this
                   .getSystemService(Context.PRINT_SERVICE);

           String jobName = this.getString(R.string.app_name) + 
                        " Document";

           printManager.print(jobName, new 
                    MyPrintDocumentAdapter(this),
                    null);
       }
}

1.3 测试应用程序

测试自定义文档打印应用程序的步骤如下：
1. 在 Android 设备或模拟器上编译并运行应用程序。
2. 应用程序加载完成后，点击“Print Document”按钮启动打印任务。
3. 选择合适的输出目标，例如“Save to PDF”选项，以避免浪费纸张和打印机墨水。
4. 检查打印输出，应该包含 4 页，包括文本和图形。
5. 尝试其他打印配置选项，如更改纸张大小、方向和页面设置，打印输出应反映每个设置的更改，表明自定义打印文档适配器功能正常。

2. Android App 链接简介

2.1 App 链接概述

App 链接是一种标准的 HTTP URL，可用于从外部源（如网站或应用程序）直接链接到应用程序中的特定位置。App 链接（也称为深度链接）主要用于鼓励用户与应用程序互动，并允许用户分享应用程序内容。实现 App 链接需要多个步骤，包括在项目清单中添加意图过滤器、在相关应用活动中实现链接处理代码，以及使用数字资产链接文件关联应用和基于 Web 的内容。这些步骤可以手动完成，也可以使用 Android Studio App Links Assistant 自动完成。

2.2 App 链接意图过滤器

要将 App 链接 URL 映射到应用项目中的特定活动，需要在项目的 AndroidManifest.xml 文件中添加意图过滤器。以下是一个示例，当检测到匹配 http://www.example.com/welcome 的 App 链接时，将启动名为 MyActivity 的活动：

<activity android:name="com.ebookfrenzy.myapp.MyActivity">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="http"
            android:host="www.example.com"
            android:pathPrefix="/welcome" />
    </intent-filter>
</activity>

2.3 处理 App 链接意图

当 App 链接启动活动时，活动需要获取 App 链接 URL 并根据 URL 的结构采取特定行动。以下是一个示例，根据 URL 的最后一个组件确定显示新用户还是现有用户的内容：

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

String userType = appLinkData.getLastPathSegment();

if (userType.equals("newuser")) {
    // display new user content
} else {
    // display existing user content
}

2.4 将应用与网站关联

在 App 链接生效之前，需要将 App 链接 URL 与基于该链接的网站关联起来。这可以通过创建一个名为 assetlinks.json 的数字资产链接文件，并将其安装在网站的 .well-known 文件夹中来实现。数字资产链接仅适用于基于 HTTPS 的网站。以下是一个典型的资产链接文件示例：

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target" : { "namespace": "android_app",
      "package_name": "<app package name here>",
                 "sha256_cert_fingerprints": ["<app certificate here>"] }
}]  

3. Android App 链接示例应用

3.1 示例应用简介

示例应用名为 AppLinking ，是一个基本的应用程序，用于让用户查找伦敦地标建筑的信息。该应用使用 SQLite 数据库，通过标准的 Android 内容提供器类进行访问。应用包含两个活动： AppLinkingActivity 和 LandmarkActivity 。 AppLinkingActivity 是应用启动时的主活动，允许用户输入搜索条件并向数据库添加记录。当搜索到匹配的记录时， LandmarkActivity 会启动并显示相关地标的信息。

3.2 数据库架构

示例应用的数据存储在位于项目层次结构 app -> assets –> databases 文件夹中的 landmarks.db 文件中。数据库包含一个名为 locations 的表，其结构如下：
| 列名 | 类型 | 描述 |
| ---- | ---- | ---- |
| _id | String | 主键索引，包含唯一标识数据库中地标的字符串值 |
| title | String | 地标的名称（如伦敦桥） |
| description | String | 地标的描述 |
| personal | Boolean | 指示记录是个人的还是公共的，用户添加的所有记录设置为 true，数据库中提供的现有记录设置为 false |

3.3 加载和运行项目

加载和运行示例项目的步骤如下：
1. 从以下 URL 下载示例源代码： https://www.ebookfrenzy.com/retail/giraffejava/index.php 。
2. 在 Android Studio 中打开 AppLinking 文件夹。
3. 在设备或模拟器上运行应用程序。
4. 如果出现“kotlin.collections.jdk8.CollectionsJDK8Kt”错误，对 build.gradle.kts (Module: app) 文件进行以下更改并同步项目：

dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
}

5. 测试搜索功能，在 ID 字段中输入 londonbridge ，然后点击“Find”按钮，当找到匹配的记录时， LandmarkActivity 会启动并显示相关地标的信息。

3.4 添加 URL 映射

为了使 LandmarkActivity 能够响应 App 链接点击并显示信息，需要将 URL 映射到该活动。示例中 URL 的格式为： http://<website domain>/landmarks/<landmarkId> 。添加 URL 映射的步骤如下：
1. 使用 Tools -> App Links Assistant 菜单选项打开 App Links Assistant。
2. 点击“Open URL Mapping Editor”按钮，在映射屏幕中点击“+”按钮添加新的 URL。
3. 在“Host”字段中输入自己网站的 URL，如果没有网站，可以使用 http://www.example.com 。
4. 在“Path”字段中输入 /landmarks ，并选择 pathPrefix 菜单选项。
5. 使用“Activity”菜单选择 LandmarkActivity 作为响应 App 链接的活动。
6. 完成对话框中的设置后，点击“OK”按钮提交更改。
7. 在映射屏幕的“Check URL Mapping”字段中输入 http://<your domain>/landmarks/toweroflondon ，检查 URL 是否正确格式化并分配给了适当的活动。
8. 由于最新版本的 Android 要求为 HTTP 和 HTTPS 协议声明 App 链接，因此需要重复上述步骤添加 HTTPS 版本的 URL。

3.5 添加意图过滤器

当添加 URL 映射时，App Links Assistant 会自动在项目清单文件中添加意图过滤器。但可能需要手动添加 autoVerify 设置，以下是添加该设置后的意图过滤器代码：

<intent-filter android:autoVerify="true">
    <data
        android:scheme="http"
        android:host="www.ebookfrenzy.com"
        android:pathPrefix="/landmarks" />
</intent-filter>
<intent-filter android:autoVerify="true">
    <data
        android:scheme="https"
        android:host="www.ebookfrenzy.com"
        android:pathPrefix="/landmarks" />
</intent-filter>

3.6 添加意图处理代码

为了使 LandmarkActivity 能够处理 App 链接意图，需要对现有代码进行修改。以下是修改后的 onCreate() 方法：

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    binding = ActivityLandmarkBinding.inflate(getLayoutInflater());
    View view = binding.getRoot();
    setContentView(view);

    // ATTENTION: This was auto-generated to handle app links.
    Intent appLinkIntent = getIntent();
    String appLinkAction = appLinkIntent.getAction();
    Uri appLinkData = appLinkIntent.getData();

    String landmarkId = appLinkData.getLastPathSegment();

    if (landmarkId != null) {
        displayLandmark(landmarkId);
    }
}

通过以上步骤，就可以实现 Android 自定义文档打印和 App 链接功能。

总结

自定义文档打印虽然比 Android 打印框架的 HTML 和图像打印选项更复杂，但在 Android 应用程序中打印复杂内容时提供了相当大的灵活性。实现自定义文档打印的大部分工作涉及创建一个自定义的打印适配器类，该类不仅要在文档页面上绘制内容，还要在用户更改打印设置（如页面大小和打印页面范围）时正确响应。App 链接则允许通过外部网站和其他应用程序的 URL 链接启动应用活动，通过在项目清单文件中使用意图过滤器和在启动活动中实现意图处理代码来实现。使用数字资产链接文件还可以将 App 链接中使用的域名与相应的网站关联起来，一旦建立关联，Android 在使用 App 链接时就不再需要询问用户选择目标应用程序。

4. 技术点分析

4.1 自定义文档打印技术点

• 文本绘制 ：在自定义文档打印中，通过 paint.setTextSize() 设置文本大小，再使用 canvas.drawText() 方法在指定位置绘制文本。例如：

paint.setTextSize(14); 
canvas.drawText("This is some test content to verify that custom document printing works", leftMargin, titleBaseLine + 35, paint);

• 图形绘制 ：以绘制圆形为例，根据页面的奇偶性设置不同颜色，然后获取页面的宽度和高度，计算圆心位置进行绘制。

if (pagenumber % 2 == 0)
       paint.setColor(Color.RED);
else
       paint.setColor(Color.GREEN);

PageInfo pageInfo = page.getInfo();

canvas.drawCircle(pageInfo.getPageWidth()/2,
                  pageInfo.getPageHeight()/2, 
                  150, paint);

• 打印任务启动 ：通过 PrintManager 获取系统的打印服务，创建打印任务名称，调用 print() 方法启动打印任务。

PrintManager printManager = (PrintManager) this
       .getSystemService(Context.PRINT_SERVICE);

String jobName = this.getString(R.string.app_name) + 
            " Document";

printManager.print(jobName, new 
         MyPrintDocumentAdapter(this),
         null);

4.2 App 链接技术点

• 意图过滤器 ：在 AndroidManifest.xml 中添加意图过滤器，将 App 链接 URL 映射到特定活动。意图过滤器包含 action 、 category 和 data 等元素，用于指定匹配的条件。

<activity android:name="com.ebookfrenzy.myapp.MyActivity">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="http"
            android:host="www.example.com"
            android:pathPrefix="/welcome" />
    </intent-filter>
</activity>

• 意图处理 ：在活动中获取 App 链接的意图对象，提取 URL 信息，根据 URL 的结构采取不同的行动。

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

String userType = appLinkData.getLastPathSegment();

if (userType.equals("newuser")) {
    // display new user content
} else {
    // display existing user content
}

• 数字资产链接 ：创建 assetlinks.json 文件并放置在网站的 .well-known 文件夹中，用于关联应用和网站。

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target" : { "namespace": "android_app",
      "package_name": "<app package name here>",
                 "sha256_cert_fingerprints": ["<app certificate here>"] }
}]  

5. 操作流程总结

5.1 自定义文档打印操作流程

graph TD;
    A[设置文本和图形绘制] --> B[创建打印适配器类];
    B --> C[实现 drawPage() 方法绘制内容];
    C --> D[在 MainActivity 中添加 printDocument() 方法];
    D --> E[启动打印任务];
    E --> F[测试打印输出];

具体步骤如下：
1. 设置文本和图形绘制，如设置文本大小、颜色，绘制圆形等。
2. 创建自定义的打印适配器类，实现 drawPage() 方法，在该方法中完成文档内容的绘制。
3. 在 MainActivity 中添加 printDocument() 方法，获取打印服务，创建打印任务名称，启动打印任务。
4. 编译并运行应用程序，点击“Print Document”按钮，选择输出目标，检查打印输出。

5.2 App 链接操作流程

graph TD;
    A[添加 URL 映射] --> B[添加意图过滤器];
    B --> C[添加意图处理代码];
    C --> D[关联应用和网站];
    D --> E[测试 App 链接];

具体步骤如下：
1. 使用 App Links Assistant 添加 URL 映射，将 URL 与特定活动关联。
2. 在 AndroidManifest.xml 中添加意图过滤器，确保活动能够响应 App 链接。
3. 在活动中添加意图处理代码，根据 App 链接的 URL 采取相应行动。
4. 创建 assetlinks.json 文件，将应用与网站关联。
5. 测试 App 链接，确保能够通过 URL 正确启动活动并显示相应内容。

6. 注意事项

6.1 自定义文档打印注意事项

• 页面布局 ：在绘制文档内容时，需要考虑页面的布局和尺寸，确保文本和图形能够正确显示。
• 打印设置响应 ：自定义打印适配器类需要正确响应打印设置的更改，如页面大小、方向等。

6.2 App 链接注意事项

• URL 格式 ：确保 App 链接的 URL 格式正确，包括协议、主机和路径等。
• 数字资产链接文件 ：数字资产链接仅适用于基于 HTTPS 的网站，创建和配置 assetlinks.json 文件时需要注意格式和内容的正确性。
• 意图处理 ：在处理 App 链接意图时，需要考虑各种可能的 URL 结构，确保活动能够正确处理不同的链接。

7. 总结与展望

通过上述内容，我们详细介绍了 Android 自定义文档打印和 App 链接的实现方法。自定义文档打印为 Android 应用程序提供了强大的打印功能，能够满足复杂内容的打印需求。而 App 链接则增强了应用程序的可访问性和分享性，使用户能够更方便地通过 URL 链接访问应用内的特定内容。

在未来的 Android 开发中，随着技术的不断发展，自定义文档打印和 App 链接可能会有更多的优化和扩展。例如，自定义文档打印可能会支持更多的打印格式和功能，App 链接可能会与更多的第三方平台进行集成，提供更丰富的用户体验。开发者可以根据实际需求，灵活运用这些技术，为用户打造更加优质的 Android 应用程序。