Guides

背景

背景指文档页面的底层图层或底纹，用于呈现文档的基础视觉效果。添加背景可以改变文档的外观，使其更具个性化或专业性，可以用于强调品牌，保护版权，或提高文档的阅读体验。

在 PDF 文档中只能存在一个背景，对包含背景的文档页面添加背景会覆盖旧的背景。

设置颜色背景

设置颜色背景的步骤如下：

1. 获取文档背景对象。

2. 设置背景类型为颜色。

3. 设置背景的属性。

4. 将背景更新到文档上。

以下是设置颜色背景的示例代码：

java

// 通过文件路径打开文档
CPDFDocument document = new CPDFDocument(context);
document.open(pdfPath, password);

// 获取文档背景对象
CPDFBackground background = document.getBackground();

// 设置背景类型为纯色背景
background.setType(CPDFBackground.Type.Color);

// 设置背景颜色（当前仅支持颜色背景，图片背景暂不生效）
background.setColor(Color.BLACK);

// 设置背景透明度，取值范围为 0 ~ 1，默认值为 1
background.setOpacity(1.0F);

// 设置背景平铺缩放比例
background.setScale(1.0F);

// 设置背景旋转角度，取值范围为 0 ~ 360，默认值为 0
// 以页面中心点为旋转中心
background.setRotation(0);

// 设置背景在水平方向上的对齐方式
background.setHorizalign(CPDFBackground.CPDFBackgroundAlign.Left);

// 设置背景在垂直方向上的对齐方式
background.setVertalign(CPDFBackground.CPDFBackgroundAlign.Bottom);

// 设置背景的水平偏移量
// 正值表示向右偏移，负值表示向左偏移
background.setXOffset(0);

// 设置背景的垂直偏移量
// 正值表示向下偏移，负值表示向上偏移
background.setYOffset(0);

// 设置背景应用的页码范围
// 通过字符串指定，例如："0,3" 或 "5-7"
background.setPages("0,1,2");

// 更新并应用背景设置
background.update();
// 释放背景资源
background.release();

kotlin

// 通过文件路径打开文档
val document = CPDFDocument(context)
document.open(pdfPath, password)

// 获取文档背景对象
val background = document.background

background.apply {
    // 设置背景类型为纯色背景
    type = CPDFBackground.Type.Color

    // 设置背景图片
    setImage(bitmap, CPDFImageScaleType.SCALETYPE_fitCenter)

    // 设置背景透明度，取值范围为 0 ~ 1，默认值为 1
    opacity = 1.0F

    // 设置背景平铺缩放比例
    scale = 1.0F

    // 设置背景旋转角度，取值范围为 0 ~ 360，默认值为 0
    // 以页面中心点为旋转中心
    rotation = 0F

    // 设置背景在水平方向上的对齐方式
    horizalign = CPDFBackground.CPDFBackgroundAlign.Left

    // 设置背景在垂直方向上的对齐方式
    vertalign = CPDFBackground.CPDFBackgroundAlign.Bottom

    // 设置背景的水平偏移量
    // 正值表示向右偏移，负值表示向左偏移
    xOffset = 0F

    // 设置背景的垂直偏移量
    // 正值表示向下偏移，负值表示向上偏移
    yOffset = 0F

    // 通过字符串设置背景应用的页码范围
    // 例如："0,3" 或 "5-7"
    pages = "0,1,2"

    // 更新并应用背景设置
    update()

    // 释放背景资源
    release()
}

当文档已绑定并通过 CPDFReaderView 显示时，在对文档页面进行修改后，需要调用以下接口刷新视图，使变更立即生效：

cpdfReaderView.reloadPages();

设置图片背景

设置图片背景的步骤如下：

1. 获取文档背景对象。

2. 设置背景类型为图片。

3. 设置背景属性。

4. 将背景更新到文档上。

以下是设置图片背景的代码：

java

// 通过文件路径打开文档
CPDFDocument document = new CPDFDocument(context);
document.open(pdfPath, password);

// 获取文档背景对象
CPDFBackground background = document.getBackground();

// 设置背景类型为图片背景
background.setType(CPDFBackground.Type.Image);

// 设置背景图片
background.setImage(bitmap, CPDFImageScaleType.SCALETYPE_fitCenter);

// 设置背景透明度，取值范围为 0 ~ 1，默认值为 1
background.setOpacity(1.0F);

// 设置背景平铺缩放比例
background.setScale(1.0F);

// 设置背景旋转角度，取值范围为 0 ~ 360，默认值为 0
// 以页面中心点为旋转中心
background.setRotation(0);

// 设置背景在水平方向上的对齐方式
background.setHorizalign(CPDFBackground.CPDFBackgroundAlign.Left);

// 设置背景在垂直方向上的对齐方式
background.setVertalign(CPDFBackground.CPDFBackgroundAlign.Bottom);

// 设置背景的水平偏移量
// 正值表示向右偏移，负值表示向左偏移
background.setXOffset(0);

// 设置背景的垂直偏移量
// 正值表示向下偏移，负值表示向上偏移
background.setYOffset(0);

// 通过字符串设置背景应用的页码范围
// 例如："0,3" 或 "5-7"
background.setPages("0,1,2");

// 更新并应用背景设置
background.update();

// 释放背景资源
background.release();

java

// 通过文件路径打开文档
val document = CPDFDocument(context)
document.open(pdfPath, password)

// 获取文档背景对象
val background = document.background

background.apply {
    // 设置背景类型为图片背景
    type = CPDFBackground.Type.Image

    // 设置背景图片
    setImage(bitmap, CPDFImageScaleType.SCALETYPE_fitCenter)

    // 设置背景透明度，取值范围为 0 ~ 1，默认值为 1
    opacity = 1.0F

    // 设置背景平铺缩放比例
    scale = 1.0F

    // 设置背景旋转角度，取值范围为 0 ~ 360，默认值为 0
    // 以页面中心点为旋转中心
    rotation = 0F

    // 设置背景在水平方向上的对齐方式
    horizalign = CPDFBackground.CPDFBackgroundAlign.Left

    // 设置背景在垂直方向上的对齐方式
    vertalign = CPDFBackground.CPDFBackgroundAlign.Bottom

    // 设置背景的水平偏移量
    // 正值表示向右偏移，负值表示向左偏移
    xOffset = 0F

    // 设置背景的垂直偏移量
    // 正值表示向下偏移，负值表示向上偏移
    yOffset = 0F

    // 通过字符串设置背景应用的页码范围
    // 例如："0,3" 或 "5-7"
    pages = "0,1,2"

    // 更新并应用背景设置
    update()

    // 释放背景资源
    release()
}

当文档已绑定并通过 CPDFReaderView 显示时，在对文档页面进行修改后，需要调用以下接口刷新视图，使变更立即生效：

cpdfReaderView.reloadPages();

删除背景

删除背景的步骤如下：

1. 获取文档背景对象。

2. 删除文档背景。

以下是删除背景的代码：

java

CPDFBackground background = document.getBackground();
//remove all pages background
background.clear();

kotlin

document.background.clear()

当文档已绑定并通过 CPDFReaderView 显示时，在对文档页面进行修改后，需要调用以下接口刷新视图，使变更立即生效：

cpdfReaderView.reloadPages();