使用 JavaScript 在演示文稿中管理图像变换效果

本页内容简介

使用 Aspose.Slides for Node.js（通过 Java）对图片框的图像变换效果进行应用、链式操作、检查、移除和验证。

概述

Aspose.Slides 将图片调整表示为有序的图像变换操作集合。对于图片框，首先使用框的Picture并访问Picture.getImageTransform。返回的ImageTransformOperationCollection允许您追加、枚举、检查、移除和清除效果，而无需重写原始图像字节。

本文演示了亮度和对比度、颜色变换、模糊、透明度、有序效果链、有效值、移除以及 PPTX 循环验证的完整工作流。

了解效果所有权和图像复用

图像资源和显示它的图片是不同的对象：

PPImage 存储或引用演示文稿拥有的源图像数据。
Picture 属于图片填充，引用图像资源并存储图像变换集合。
PictureFrame 是拥有相关图片填充、几何形状、裁剪设置以及其他框级格式的幻灯片形状。

因此，图像变换操作并不会修改PPImage中的字节。当相同的PPImage多次传递给ShapeCollection.addPictureFrame时，每个新图片框都会获得自己的Picture和自己的变换集合。对一个框应用灰度并不会使其他框也变为灰度，即使它们复用了同一嵌入图像资源。

相同的Picture.getImageTransform模型也被其他图片填充使用，例如形状或幻灯片背景。下面的示例侧重于图片框。

使用有效的参数范围和单位

所示方法使用以下语义范围和单位。即使特定库版本未立即拒绝每个超出范围的值，也请在这些范围内保持值；目标演示文稿格式可能在保存时或 PowerPoint 打开文件时对无效数据进行规范化、忽略或拒绝。

操作	参数	有效范围和单位
addBrightnessContrastEffect	`brightness`, `contrast`	`-100` 到 `100`，百分比；`0` 表示保持组件不变。
addGrayScaleEffect	无	无数值参数。Alpha 保持不变。
addDuotoneEffect	`color1`, `color2`	两种颜色分别用于暗像素和亮像素。`java.awt.Color` 中的 RGB 和 Alpha 通道使用 `0` 到 `255`。
addTintEffect	`hue`, `amount`	色相为 `0`（含）到 `360`（不含）度；`amount` 为 `-100` 到 `100`，百分比。
addHSLEffect	`hue`, `saturation`, `luminance`	色相为 `0`（含）到 `360`（不含）度；饱和度和亮度为 `-100` 到 `100`，百分比。
addColorReplaceEffect	`color`	替换颜色的通道值为 `0` 到 `255`。现有的 Alpha 值保持不变。
addBlurEffect	`radius`, `grow`	半径为非负，单位为磅；`grow` 为布尔值，控制模糊内容是否可以超出原始边界。
addAlphaModulateFixedEffect	`amount`	非负百分比。使用 `0` 到 `100` 表示普通的不透明度缩放：`0` 为完全透明，`100` 保持现有 Alpha。
addAlphaReplaceEffect	`alpha`	`0` 到 `100`，百分比不透明度。
addAlphaBiLevelEffect	`threshold`	`0` 到 `100`，百分比 Alpha 阈值。低于阈值的像素变为透明，等于或高于阈值的像素变为不透明。

对于固定 Alpha 调制，透明度与不透明度是互补的。例如，35% 透明度对应 65% 的 Alpha 调制量。

应用亮度和对比度

ImageTransformOperationCollection.addBrightnessContrastEffect 返回一个BrightnessContrast 操作。其标量设置在创建操作时提供。BrightnessContrast.getEffective 返回计算后的只读值，可用于检查或记录。

以下示例将亮度提高 15%，对比度提高 20%，随后在不修改嵌入图像的情况下渲染预览：

const aspose = {};
aspose.slides = require("aspose.slides.via.java");

const presentation = new aspose.slides.Presentation();
try {
    const slide = presentation.getSlides().get_Item(0);

    let image;
    const sourceImage = aspose.slides.Images.fromFile("photo.png");
    try {
        image = presentation.getImages().addImage(sourceImage);
    } finally {
        sourceImage.dispose();
    }

    const pictureFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 50, 50, 400, 260, image);
    const imageTransform = pictureFrame.getPictureFormat().getPicture().getImageTransform();
    const brightnessContrast = imageTransform.addBrightnessContrastEffect(15, 20);

    const effectiveValues = brightnessContrast.getEffective();
    console.log("Brightness: " + effectiveValues.getBrightness() + "%");
    console.log("Contrast: " + effectiveValues.getContrast() + "%");

    const preview = slide.getImage();
    try {
        preview.save("brightness-contrast-preview.png", aspose.slides.ImageFormat.Png);
    } finally {
        preview.dispose();
    }
} finally {
    presentation.dispose();
}

BrightnessContrast 是 Office 2010 的图片效果扩展，便携性不如标准 DrawingML 亮度效果。当亮度和对比度必须在 PPTX 循环后保持可编辑时，请使用ImageTransformOperationCollection.addLuminanceEffect 并在重新打开文件后验证结果。格式限制章节对此区分作了更详细的说明。

应用颜色变换

颜色效果可以独立应用于复用同一图像资源的不同图片框。下面的示例创建五个框并分别应用灰度、双调、色调、HSL 调整和颜色替换。

Duotone 包含两个可独立编辑的颜色参数：color1 映射暗像素，color2 映射亮像素。这使它成为一个设置比单一标量值更复杂的示例。

const aspose = {};
aspose.slides = require("aspose.slides.via.java");
const java = require("java");

const presentation = new aspose.slides.Presentation();
try {
    const slide = presentation.getSlides().get_Item(0);

    let image;
    const sourceImage = aspose.slides.Images.fromFile("photo.png");
    try {
        image = presentation.getImages().addImage(sourceImage);
    } finally {
        sourceImage.dispose();
    }

    const grayFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 20, 20, 180, 120, image);
    grayFrame.getPictureFormat().getPicture().getImageTransform().addGrayScaleEffect();

    const duotoneFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 220, 20, 180, 120, image);
    const duotone = duotoneFrame.getPictureFormat().getPicture().getImageTransform().addDuotoneEffect();
    duotone.getColor1().setColor(java.newInstanceSync("java.awt.Color", 0, 0, 128));
    duotone.getColor2().setColor(java.newInstanceSync("java.awt.Color", 255, 215, 0));

    const tintFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 420, 20, 180, 120, image);
    tintFrame.getPictureFormat().getPicture().getImageTransform().addTintEffect(210, 35);

    const hslFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 120, 170, 180, 120, image);
    hslFrame.getPictureFormat().getPicture().getImageTransform().addHSLEffect(30, 20, -10);

    const replacementFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 320, 170, 180, 120, image);
    const colorReplacement = replacementFrame.getPictureFormat().getPicture().getImageTransform().addColorReplaceEffect();
    colorReplacement.getColor().setColor(java.newInstanceSync("java.awt.Color", 100, 149, 237));

    presentation.save("color-transformations.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

addColorReplaceEffect 将每个像素的颜色替换为固定颜色，同时保留 alpha。它不同于addColorChangeEffect，后者将一种源颜色映射到另一种颜色，并暴露源色和目标色的格式。

添加模糊、透明度和 Alpha 效果

addBlurEffect 影响所有颜色通道，包括 alpha。当模糊边缘可能延伸超出原始图片边界时，将 grow 设为 true。

要实现统一透明度，请使用addAlphaModulateFixedEffect。它会乘以每个现有的 alpha 值，从而使部分透明像素保持比例差异。addAlphaReplaceEffect 则为所有像素分配相同的 alpha 值。addAlphaBiLevelEffect 根据阈值将 alpha 转换为两级。

const aspose = {};
aspose.slides = require("aspose.slides.via.java");

const presentation = new aspose.slides.Presentation();
try {
    const slide = presentation.getSlides().get_Item(0);

    let image;
    const sourceImage = aspose.slides.Images.fromFile("photo.png");
    try {
        image = presentation.getImages().addImage(sourceImage);
    } finally {
        sourceImage.dispose();
    }

    const blurredFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 20, 20, 200, 140, image);
    const blur = blurredFrame.getPictureFormat().getPicture().getImageTransform().addBlurEffect(4.5, true);
    blur.setRadius(5);

    const transparentFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 240, 20, 200, 140, image);
    const alphaModulate = transparentFrame.getPictureFormat().getPicture().getImageTransform().addAlphaModulateFixedEffect(65);
    alphaModulate.setAmount(60);

    const uniformAlphaFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 20, 180, 200, 140, image);
    uniformAlphaFrame.getPictureFormat().getPicture().getImageTransform().addAlphaReplaceEffect(55);

    const binaryAlphaFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 240, 180, 200, 140, image);
    const alphaBiLevel = binaryAlphaFrame.getPictureFormat().getPicture().getImageTransform().addAlphaBiLevelEffect(50);
    alphaBiLevel.setThreshold(45);
    binaryAlphaFrame.getPictureFormat().getPicture().getImageTransform().addAlphaInverseEffect();

    presentation.save("blur-and-alpha-effects.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

其他无参 Alpha 操作包括addAlphaCeilingEffect，它使所有非零 alpha 完全不透明；addAlphaFloorEffect，它使低于 100% 的 alpha 完全透明；以及addAlphaInverseEffect，它将 alpha 改为 100% - alpha。

构建有序效果链

每个 add...Effect 方法都会将新操作追加到集合末尾。渲染器将集合视为有序管线：操作 0 的输出成为操作 1 的输入，依此类推。因此，以不同顺序排列相同操作可能产生不同图像。

例如，先灰度后色调会先去除色彩信息再对亮度结果重新着色。先色调后灰度则会再次去除色调。类似地，Alpha 替换可以覆盖先前操作计算的 alpha 值，而 Alpha 调制则保留它们的相对差异。

以下示例构建一个由四个操作组成的链，保存为 PPTX，重新打开演示文稿，检查操作类型及其顺序，并渲染重新打开的结果：

const aspose = {};
aspose.slides = require("aspose.slides.via.java");
const java = require("java");

const presentation = new aspose.slides.Presentation();
try {
    const slide = presentation.getSlides().get_Item(0);

    let image;
    const sourceImage = aspose.slides.Images.fromFile("photo.png");
    try {
        image = presentation.getImages().addImage(sourceImage);
    } finally {
        sourceImage.dispose();
    }

    const pictureFrame = slide.getShapes().addPictureFrame(aspose.slides.ShapeType.Rectangle, 50, 50, 400, 260, image);
    const imageTransform = pictureFrame.getPictureFormat().getPicture().getImageTransform();
    imageTransform.addGrayScaleEffect();
    imageTransform.addTintEffect(220, 25);
    imageTransform.addBlurEffect(2.5, false);
    imageTransform.addAlphaModulateFixedEffect(80);

    presentation.save("image-transform-chain.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

const reopenedPresentation = new aspose.slides.Presentation("image-transform-chain.pptx");
try {
    const reopenedShape = reopenedPresentation.getSlides().get_Item(0).getShapes().get_Item(0);

    if (java.instanceOf(reopenedShape, "com.aspose.slides.IPictureFrame")) {
        const reopenedTransform = reopenedShape.getPictureFormat().getPicture().getImageTransform();
        const orderIsPreserved = reopenedTransform.size() === 4 &&
            java.instanceOf(reopenedTransform.get_Item(0), "com.aspose.slides.IGrayScale") &&
            java.instanceOf(reopenedTransform.get_Item(1), "com.aspose.slides.ITint") &&
            java.instanceOf(reopenedTransform.get_Item(2), "com.aspose.slides.IBlur") &&
            java.instanceOf(reopenedTransform.get_Item(3), "com.aspose.slides.IAlphaModulateFixed");
        console.log(orderIsPreserved ? "The effect chain was preserved." : "The effect chain changed during the round trip.");

        const renderedSlide = reopenedPresentation.getSlides().get_Item(0).getImage();
        try {
            renderedSlide.save("reopened-effect-chain.png", aspose.slides.ImageFormat.Png);
        } finally {
            renderedSlide.dispose();
        }
    } else {
        console.log("The reopened shape is not a picture frame.");
    }
} finally {
    reopenedPresentation.dispose();
}

该集合并未强制兼容矩阵将颜色、alpha 和模糊操作限制在不同链中。它们可以组合，但组合未必总有用处。固定颜色替换会消除先前颜色效果产生的 RGB 变化；双调后灰度会去除两个选定颜色；Alpha ceiling、floor、replacement 或 bi‑level 操作可能丢弃早前创建的 alpha 细节。请根据所需的像素处理顺序构建链，而不是将其视为无序的格式标志。

检查可编辑和有效值

可编辑操作是存储在Picture.getImageTransform中的对象。根据具体效果，它可能直接公开可写成员。例如，Blur 公开可写的 radius 和 grow，AlphaModulateFixed 公开可写的 amount，而AlphaBiLevel 公开可写的 threshold。像Duotone 这样的颜色效果会公开可变的ColorFormat 对象。

某些操作（包括BrightnessContrast、HSL、Tint 和AlphaReplace）不将其创建时的标量暴露为可写属性。要更改这些设置，需要移除该操作并在所需位置添加替代操作。

getEffective() 返回的有效数据是计算后的只读对象。它有助于解析主题相关颜色并读取渲染器使用的归一化值，但并不是另一个编辑面板。下面的示例枚举链并在对应 API 提供时检查有效值：

const aspose = {};
aspose.slides = require("aspose.slides.via.java");
const java = require("java");

const presentation = new aspose.slides.Presentation("image-transform-chain.pptx");
try {
    const shapes = presentation.getSlides().get_Item(0).getShapes();
    let pictureFrame = null;

    for (let index = 0; index < shapes.size(); index++) {
        const shape = shapes.get_Item(index);
        if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
            pictureFrame = shape;
            break;
        }
    }

    if (pictureFrame != null) {
        const imageTransform = pictureFrame.getPictureFormat().getPicture().getImageTransform();

        for (let index = 0; index < imageTransform.size(); index++) {
            const operation = imageTransform.get_Item(index);
            console.log(index + ": " + operation.getClass().getSimpleName());

            if (java.instanceOf(operation, "com.aspose.slides.IBrightnessContrast")) {
                const data = operation.getEffective();
                console.log("  Brightness: " + data.getBrightness());
                console.log("  Contrast: " + data.getContrast());
            } else if (java.instanceOf(operation, "com.aspose.slides.ILuminance")) {
                const data = operation.getEffective();
                console.log("  Brightness: " + data.getBrightness());
                console.log("  Contrast: " + data.getContrast());
            } else if (java.instanceOf(operation, "com.aspose.slides.IDuotone")) {
                const data = operation.getEffective();
                console.log("  Dark color: " + data.getColor1());
                console.log("  Light color: " + data.getColor2());
            } else if (java.instanceOf(operation, "com.aspose.slides.IColorReplace")) {
                const data = operation.getEffective();
                console.log("  Replacement color: " + data.getColor());
            } else if (java.instanceOf(operation, "com.aspose.slides.IHSL")) {
                const data = operation.getEffective();
                console.log("  HSL: " + data.getHue() + ", " + data.getSaturation() + ", " + data.getLuminance());
            } else if (java.instanceOf(operation, "com.aspose.slides.ITint")) {
                const data = operation.getEffective();
                console.log("  Tint: " + data.getHue() + ", " + data.getAmount());
            } else if (java.instanceOf(operation, "com.aspose.slides.IBlur")) {
                const data = operation.getEffective();
                console.log("  Blur radius: " + data.getRadius() + " pt");
            } else if (java.instanceOf(operation, "com.aspose.slides.IAlphaModulateFixed")) {
                const data = operation.getEffective();
                console.log("  Alpha amount: " + data.getAmount() + "%");
            } else if (java.instanceOf(operation, "com.aspose.slides.IAlphaReplace")) {
                const data = operation.getEffective();
                console.log("  Replacement alpha: " + data.getAlpha() + "%");
            } else if (java.instanceOf(operation, "com.aspose.slides.IAlphaBiLevel")) {
                const data = operation.getEffective();
                console.log("  Alpha threshold: " + data.getThreshold() + "%");
            }
        }
    }
} finally {
    presentation.dispose();
}

像灰度、Alpha ceiling 和 Alpha inverse 这样的无参效果仍然拥有有效数据对象，只是没有可打印的标量设置。它们在集合中的存在和位置即为重要信息。

移除或清除图像变换

使用ImageTransformOperationCollection.removeAt 按索引移除单个操作。由于移除后索引会变化，建议先搜索目标再在枚举后移除。使用ImageTransformOperationCollection.clear 删除整个链。

const aspose = {};
aspose.slides = require("aspose.slides.via.java");
const java = require("java");

const presentation = new aspose.slides.Presentation("image-transform-chain.pptx");
try {
    const shapes = presentation.getSlides().get_Item(0).getShapes();
    let pictureFrame = null;

    for (let index = 0; index < shapes.size(); index++) {
        const shape = shapes.get_Item(index);
        if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
            pictureFrame = shape;
            break;
        }
    }

    if (pictureFrame != null) {
        const imageTransform = pictureFrame.getPictureFormat().getPicture().getImageTransform();
        let blurIndex = -1;

        for (let index = 0; index < imageTransform.size(); index++) {
            if (java.instanceOf(imageTransform.get_Item(index), "com.aspose.slides.IBlur")) {
                blurIndex = index;
                break;
            }
        }

        if (blurIndex >= 0) {
            imageTransform.removeAt(blurIndex);
            console.log("The blur operation was removed.");
        }

        imageTransform.clear();
        console.log("Remaining operations: " + imageTransform.size());
        presentation.save("image-transforms-cleared.pptx", aspose.slides.SaveFormat.Pptx);
    }
} finally {
    presentation.dispose();
}

移除或清除变换只会改变图片格式。它不会删除、重新压缩或以其他方式修改复用的PPImage资源。

考虑演示文稿格式和导出目标

图像变换源自 DrawingML，因此 PPTX 是效果链的首选可编辑格式。即使使用 PPTX，也并非每个操作都具有相同的可移植性：

标准 DrawingML 操作（如 luminance、grayScale、duotone、tint、HSL、blur 和常见 alpha 操作）最有可能在 PPTX 循环后仍然存在。要求保留时，请始终重新打开生成的文件并检查集合。
BrightnessContrast 是 Office 2010 的扩展，而非标准 DrawingML luminance 操作。它可用于内存渲染，但保存并重新打开 PPTX 后不保证仍为可编辑的BrightnessContrast 操作。请优先使用addLuminanceEffect 以实现持久的亮度和对比度调整。
二进制 PPT 格式早于完整的 DrawingML 效果模型。保存为 PPT 可能会省略不受支持的操作、将链缩减为受支持的子集或近似外观。不要将 PPT 用作复杂可编辑链的验证格式。
渲染为 PNG、JPEG、TIFF、PDF、SVG、HTML 或其他可视输出时，会将支持的链应用于渲染外观。这些输出不包含可编辑的ImageTransformOperationCollection；光栅格式会将结果平铺为像素，文档/矢量导出则存储各自的渲染表示。
效果不会使链接的图像自包含。渲染链接图片仍然依赖于加载演示文稿时链接资源的可用性。

不同的演示文稿使用者在组合多个 alpha 或颜色量化操作时可能会有不同的渲染结果。对于关键输出，请使用生产环境中相同的 Aspose.Slides 版本同时测试可编辑循环和最终导出格式。

常见问题解答

图像变换效果会修改嵌入的图像数据吗？

不会。操作属于用于图片填充的Picture。底层的PPImage字节保持不变。

复用同一图像的两个图片框会共享它们的效果吗？

不会。复用PPImage可以避免重复的图像数据，但每个图片框通常拥有各自的Picture和图像变换集合。

可以组合颜色、模糊和 alpha 效果吗？

可以。集合接受它们在同一有序链中。请考虑每个操作对前一个输出的影响，因为替换和阈值操作可能会丢弃早前的颜色或 alpha 细节。

为什么有效值是只读的？

有效数据代表用于渲染的计算值，包括已解析的颜色。请在变换集合中编辑具有可写成员的操作；否则请移除它并使用新的创建参数添加替代操作。

应使用哪种格式来保留变换链？

使用 PPTX 并通过重新打开文件进行验证。旧版 PPT 无法完整表示 DrawingML 效果模型，渲染导出格式仅保留外观而不是可编辑的变换操作。

演示文稿查看器