Guides

快速开始

完成集成后，可通过 CPDFDocumentActivity 或 CPDFDocumentFragment 启动完整的 PDF 文档界面。UI 与功能行为通过 CPDFConfiguration 控制，默认配置文件为 tools_default_configuration.json。

存储访问提示（Android 10/11+）

• 推荐优先通过 Uri（SAF / MediaStore）方式打开与保存文档。
• 直接使用文件路径在新系统上可能受分区存储（Scoped Storage）限制。
• tools_default_configuration.json 默认已打包在 Tools 模块 assets 中，可直接使用或复制到应用 assets 目录覆盖。

使用 CPDFDocumentActivity

CPDFDocumentActivity 是开箱即用的全屏 PDF 文档 Activity。

通过 Uri 打开

java

Intent intent = new Intent(context, CPDFDocumentActivity.class);
intent.setData(uri); // SAF 选择器返回的 Uri
intent.putExtra(CPDFDocumentActivity.EXTRA_FILE_PASSWORD, password); // 可为空
CPDFConfiguration configuration = CPDFConfigurationUtils.normalConfig(
    context, "tools_default_configuration.json");
intent.putExtra(CPDFDocumentActivity.EXTRA_CONFIGURATION, configuration);
intent.putExtra(CPDFDocumentActivity.EXTRA_PAGE_INDEX, 0); // 默认页码
context.startActivity(intent);

kotlin

val intent = Intent(context, CPDFDocumentActivity::class.java).apply {
    data = uri
    putExtra(CPDFDocumentActivity.EXTRA_FILE_PASSWORD, password)
    val configuration = CPDFConfigurationUtils.normalConfig(
        context, "tools_default_configuration.json")
    putExtra(CPDFDocumentActivity.EXTRA_CONFIGURATION, configuration)
    putExtra(CPDFDocumentActivity.EXTRA_PAGE_INDEX, 0)
}
context.startActivity(intent)

通过文件路径打开

java

Intent intent = new Intent(context, CPDFDocumentActivity.class);
intent.putExtra(CPDFDocumentActivity.EXTRA_FILE_PATH, filePath);
intent.putExtra(CPDFDocumentActivity.EXTRA_FILE_PASSWORD, password);
CPDFConfiguration configuration = CPDFConfigurationUtils.normalConfig(
    context, "tools_default_configuration.json");
intent.putExtra(CPDFDocumentActivity.EXTRA_CONFIGURATION, configuration);
intent.putExtra(CPDFDocumentActivity.EXTRA_PAGE_INDEX, 0);
context.startActivity(intent);

kotlin

val intent = Intent(context, CPDFDocumentActivity::class.java).apply {
    putExtra(CPDFDocumentActivity.EXTRA_FILE_PATH, filePath)
    putExtra(CPDFDocumentActivity.EXTRA_FILE_PASSWORD, password)
    val configuration = CPDFConfigurationUtils.normalConfig(
        context, "tools_default_configuration.json")
    putExtra(CPDFDocumentActivity.EXTRA_CONFIGURATION, configuration)
    putExtra(CPDFDocumentActivity.EXTRA_PAGE_INDEX, 0)
}
context.startActivity(intent)

支持的 Intent 参数

Extra 常量	类型	说明
EXTRA_FILE_PATH	String	PDF 文件的绝对路径
EXTRA_FILE_URI	Uri（通过 setData()）	SAF / MediaStore Uri
EXTRA_FILE_PASSWORD	String	文档密码，可为 null
EXTRA_CONFIGURATION	CPDFConfiguration	UI 与功能配置对象
EXTRA_PAGE_INDEX	int	打开时默认显示的页码（从 0 开始）

使用 CPDFDocumentFragment

CPDFDocumentFragment 可嵌入任意 Activity，提供更灵活的界面定制能力。

基本用法

java

CPDFConfiguration configuration = CPDFConfigurationUtils.normalConfig(
    context, "tools_default_configuration.json");
CPDFDocumentFragment documentFragment = CPDFDocumentFragment.newInstance(
    uri, "password", configuration);
getSupportFragmentManager()
    .beginTransaction()
    .replace(R.id.fragment_container_view, documentFragment, "documentFragment")
    .commit();

kotlin

val configuration = CPDFConfigurationUtils.normalConfig(
    context, "tools_default_configuration.json")
val documentFragment = CPDFDocumentFragment.newInstance(
    uri, "password", configuration)
supportFragmentManager
    .beginTransaction()
    .replace(R.id.fragment_container_view, documentFragment, "documentFragment")
    .commit()

工厂方法

CPDFDocumentFragment 提供以下静态方法创建实例：

方法	说明
newInstance(String filePath, String password, CPDFConfiguration config)	通过文件路径创建
newInstance(Uri uri, String password, CPDFConfiguration config)	通过 Uri 创建
newInstance(Bundle bundle)	通过 Bundle 创建（高级用法）

初始化回调

通过 setInitListener() 可监听 Fragment 初始化完成事件，获取 CPDFViewCtrl 实例：

java

documentFragment.setInitListener(pdfView -> {
    // pdfView 已就绪，可进行进一步操作
    // 例如：pdfView.getCPdfReaderView().setDisplayMode(...)
});

kotlin

documentFragment.setInitListener { pdfView ->
    // pdfView 已就绪
}

运行效果