匯出簡報為 HTML 並使用外部連結圖片

概觀

預設情況下，Aspose.Slides 會將簡報匯出為單一的 HTML 檔案。圖片與其他資源會直接寫入 HTML，通常以 Base64 資料形式呈現。當您需要一個可攜帶的檔案時這很方便，但對於 Web 檢視、CMS 或之後發布輸出的伺服器端轉換流程而言，未必是最佳格式。

在以下情況下請使用外部連結資源：

減少 HTML 文件的大小；
在瀏覽器或 CDN 中單獨快取圖片、字型、音訊或影片；
匯出後檢查、取代、壓縮或後處理產生的資源；
讓輸出結構更接近 Web 應用程式的預期。

一般的 HTML 轉換工作流程，請參閱Convert PowerPoint Presentations to HTML。本文聚焦於匯出的資源連結部分。

連結資源匯出的運作方式

ILinkEmbedController 讓您的應用程式逐一決定每個資源是嵌入於 HTML，還是另存為外部檔案並寫入連結。

此介面包含三個方法：

ILinkEmbedController.getObjectStoringLocation 決定資源應該被連結或嵌入。
ILinkEmbedController.getUrl 回傳要寫入產生的 HTML 或其他連結資源的 URL。
ILinkEmbedController.saveExternal 將連結資源的資料寫入磁碟或其他儲存目標。

檔案系統路徑與瀏覽器 URL 是不同的概念。例如，下列示範會將資源檔案寫入應用程式檔案儲存區的 html-output/assets，而 HTML 內則包含 assets/resource-1.svg 等相對 URL。瀏覽器會以包含連結的檔案為基準解析這些 URL。因此，presentation.html 到 SVG 檔案的連結使用 assets/resource-1.svg，而該 SVG 檔案再連結同一 assets 資料夾內的圖片時，則使用 resource-4.jpg。

使用連結資源匯出 HTML

以下 Android Java 範例會建立輸出目錄、將 HTML 檔案儲存在該目錄，並將連結資源存放於 assets 子目錄。請將 context.getFilesDir() 等應用程式擁有的目錄傳入 applicationFilesDirectory。程式碼避免使用 java.nio.file API，以維持 Android minSdk 19 的相容性。

控制器會在 Aspose.Slides 提供或能推斷安全副檔名時，連結常見的圖片、字型、音訊、影片與 CSS 資源。未被辨識的資源仍會以嵌入方式處理。

import com.aspose.slides.HtmlFormatter;
import com.aspose.slides.HtmlOptions;
import com.aspose.slides.ILinkEmbedController;
import com.aspose.slides.LinkEmbedDecision;
import com.aspose.slides.Presentation;
import com.aspose.slides.SVGOptions;
import com.aspose.slides.SaveFormat;
import com.aspose.slides.SlideImageFormat;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;

public class ExportToHtmlWithLinkedResources {
    public static void exportPresentation(File applicationFilesDirectory) {
        if (applicationFilesDirectory == null) {
            throw new IllegalArgumentException("The application files directory must not be null.");
        }

        File inputFile = new File(applicationFilesDirectory, "presentation.pptx");
        File outputDirectory = new File(applicationFilesDirectory, "html-output");
        String assetDirectoryName = "assets";
        File assetDirectory = new File(outputDirectory, assetDirectoryName);

        createDirectory(outputDirectory, "HTML output");
        createDirectory(assetDirectory, "asset output");

        String assetUrlPrefix = assetDirectoryName + "/";
        ExternalResourceController controller = new ExternalResourceController(assetDirectory, assetUrlPrefix);
        SVGOptions svgOptions = new SVGOptions(controller);
        SlideImageFormat slideImageFormat = SlideImageFormat.svg(svgOptions);

        HtmlOptions htmlOptions = new HtmlOptions(controller);
        htmlOptions.setHtmlFormatter(HtmlFormatter.createDocumentFormatter("", false));
        htmlOptions.setSlideImageFormat(slideImageFormat);

        Presentation presentation = new Presentation(inputFile.getAbsolutePath());
        try {
            File htmlFile = new File(outputDirectory, "presentation.html");
            presentation.save(htmlFile.getAbsolutePath(), SaveFormat.Html, htmlOptions);
        } finally {
            presentation.dispose();
        }
    }

    private static final class ExternalResourceController implements ILinkEmbedController {
        private static final Map<String, String> EXTENSIONS_BY_CONTENT_TYPE = createExtensionsByContentType();

        private final File assetDirectory;
        private final String assetUrlPrefix;
        private final Map<Integer, String> fileNamesByResourceId = new HashMap<Integer, String>();

        private ExternalResourceController(File assetDirectory, String assetUrlPrefix) {
            if (assetDirectory == null) {
                throw new IllegalArgumentException("The asset output directory must not be null.");
            }

            this.assetDirectory = assetDirectory;
            this.assetUrlPrefix = normalizeUrlPrefix(assetUrlPrefix);
        }

        @Override
        public int getObjectStoringLocation(
                int resourceId,
                byte[] entityData,
                String semanticName,
                String contentType,
                String recommendedExtension) {
            String extension = resolveExtension(contentType, recommendedExtension);
            if (extension == null) {
                return LinkEmbedDecision.Embed;
            }

            fileNamesByResourceId.put(resourceId, "resource-" + resourceId + extension);
            return LinkEmbedDecision.Link;
        }

        @Override
        public String getUrl(int resourceId, int referrer) {
            String fileName = fileNamesByResourceId.get(resourceId);
            if (fileName == null) {
                return null;
            }

            if (fileNamesByResourceId.containsKey(referrer)) {
                return fileName;
            }

            return assetUrlPrefix + fileName;
        }

        @Override
        public void saveExternal(int resourceId, byte[] entityData) {
            String fileName = fileNamesByResourceId.get(resourceId);
            if (fileName == null) {
                throw new IllegalStateException(
                        "Resource " + resourceId + " was not registered for external storage.");
            }

            if (entityData == null || entityData.length == 0) {
                throw new IllegalStateException(
                        "Resource " + resourceId + " contains no data and cannot be saved.");
            }

            createDirectory(assetDirectory, "asset output");

            File outputFile = new File(assetDirectory, fileName);
            FileOutputStream outputStream = null;
            try {
                outputStream = new FileOutputStream(outputFile);
                outputStream.write(entityData);
            } catch (IOException exception) {
                throw new IllegalStateException(
                        "Failed to save external resource " + resourceId +
                                " to " + outputFile.getAbsolutePath() + ".",
                        exception);
            } finally {
                closeOutputStream(outputStream, outputFile);
            }
        }

        private static Map<String, String> createExtensionsByContentType() {
            Map<String, String> extensionsByContentType = new HashMap<String, String>();
            extensionsByContentType.put("image/jpeg", ".jpg");
            extensionsByContentType.put("image/png", ".png");
            extensionsByContentType.put("image/gif", ".gif");
            extensionsByContentType.put("image/bmp", ".bmp");
            extensionsByContentType.put("image/svg+xml", ".svg");
            extensionsByContentType.put("image/tiff", ".tiff");
            extensionsByContentType.put("image/x-emf", ".emf");
            extensionsByContentType.put("image/x-wmf", ".wmf");
            extensionsByContentType.put("font/woff", ".woff");
            extensionsByContentType.put("font/woff2", ".woff2");
            extensionsByContentType.put("font/ttf", ".ttf");
            extensionsByContentType.put("application/font-woff", ".woff");
            extensionsByContentType.put("application/vnd.ms-fontobject", ".eot");
            extensionsByContentType.put("application/x-font-ttf", ".ttf");
            extensionsByContentType.put("text/css", ".css");
            extensionsByContentType.put("audio/mpeg", ".mp3");
            extensionsByContentType.put("audio/mp4", ".m4a");
            extensionsByContentType.put("audio/wav", ".wav");
            extensionsByContentType.put("video/mp4", ".mp4");
            extensionsByContentType.put("video/webm", ".webm");
            return extensionsByContentType;
        }

        private static String resolveExtension(String contentType, String recommendedExtension) {
            if (contentType != null && !contentType.trim().equals("")) {
                String normalizedContentType = contentType.toLowerCase(Locale.US);
                String mappedExtension = EXTENSIONS_BY_CONTENT_TYPE.get(normalizedContentType);
                if (mappedExtension != null) {
                    return mappedExtension;
                }
            }

            if (!isSupportedContentType(contentType)) {
                return null;
            }

            return normalizeExtension(recommendedExtension);
        }

        private static boolean isSupportedContentType(String contentType) {
            return contentType != null &&
                    (contentType.regionMatches(true, 0, "image/", 0, "image/".length()) ||
                     contentType.regionMatches(true, 0, "font/", 0, "font/".length()) ||
                     contentType.regionMatches(true, 0, "audio/", 0, "audio/".length()) ||
                     contentType.regionMatches(true, 0, "video/", 0, "video/".length()));
        }

        private static String normalizeExtension(String extension) {
            if (extension == null || extension.trim().equals("")) {
                return null;
            }

            String extensionCharacters = extension.trim();
            while (extensionCharacters.startsWith(".")) {
                extensionCharacters = extensionCharacters.substring(1);
            }

            if (extensionCharacters.equals("")) {
                return null;
            }

            int characterCount = extensionCharacters.length();
            for (int index = 0; index < characterCount; index++) {
                char character = extensionCharacters.charAt(index);
                if (!Character.isLetterOrDigit(character)) {
                    return null;
                }
            }

            return "." + extensionCharacters.toLowerCase(Locale.US);
        }

        private static String normalizeUrlPrefix(String urlPrefix) {
            if (urlPrefix == null || urlPrefix.equals("")) {
                return "";
            }

            String normalizedUrlPrefix = urlPrefix.replace('\\', '/');
            return normalizedUrlPrefix.endsWith("/")
                    ? normalizedUrlPrefix
                    : normalizedUrlPrefix + "/";
        }
    }

    private static void createDirectory(File directory, String description) {
        if (directory.exists()) {
            if (!directory.isDirectory()) {
                throw new IllegalStateException(
                        "The " + description + " path exists but is not a directory: " +
                                directory.getAbsolutePath());
            }

            return;
        }

        if (!directory.mkdirs()) {
            throw new IllegalStateException(
                    "Failed to create the " + description + " directory: " +
                            directory.getAbsolutePath());
        }
    }

    private static void closeOutputStream(FileOutputStream outputStream, File outputFile) {
        if (outputStream == null) {
            return;
        }

        try {
            outputStream.close();
        } catch (IOException exception) {
            throw new IllegalStateException(
                    "Failed to close the external resource file: " +
                            outputFile.getAbsolutePath(),
                    exception);
        }
    }
}

匯出完成後，輸出資料夾的結構如下：

html-output/
  presentation.html
  assets/
    resource-1.svg
    resource-2.svg
    resource-3.svg
    resource-4.jpg
    resource-5.png

實際產生的檔案會依簡報內容與匯出選項而異。例如，點陣圖通常會匯出為 JPEG 或 PNG。Aspose.Slides 可能會選擇不同於來源簡報的影像編解碼方式，以獲得較小或較適合的檔案。具有透明度的圖片會匯出為 PNG。

部署時的 URL 選擇

範例使用相對 URL 前置字串 assets/。若 presentation.html 位於 html-output/presentation.html，瀏覽器會載入 html-output/assets/resource-1.svg。

當一個連結資源引用另一個連結資源時，範例在ILinkEmbedController.getUrl 中使用 referrer 參數，僅回傳檔名。例如，若 resource-1.svg 與 resource-4.jpg 同在 assets 資料夾，SVG 檔案應該引用 resource-4.jpg，而非 assets/resource-4.jpg。

若檔案部署於其他位置，請使用不同的 URL 前置字串：

資產目錄與 HTML 檔案相鄰時使用 assets/。
資產目錄位於 HTML 檔案上一層時使用 ../assets/。
若檔案上傳至 CDN 或靜態檔案伺服器，使用 https://cdn.example.com/presentations/job-123/assets/。

ILinkEmbedController.getUrl 回傳的 URL 必須與 ILinkEmbedController.saveExternal 所寫入檔案的最終部署位置相符。於 Android 應用程式中，可使用應用程式專屬儲存、快取目錄，或依發佈工作流程透過儲存存取框架取得的目錄。於伺服器應用程式中，請為每一次轉換工作使用唯一的輸出目錄或物件儲存前置字串，以避免覆寫其他匯出的檔案。

何時應改為嵌入

當輸出必須為單一檔案時（例如電子郵件附件、離線預覽，或需在沒有資產資料夾的情況下移動的文件），仍可使用嵌入 Base64 的 HTML。若 HTML 將由 Web 應用程式提供、儲存在 CMS、經過建置管線最佳化，或希望瀏覽器獨立快取資源，則連結資源較為合適。

常見問題集

我可以只將圖片外部化，而保留其他資源嵌入嗎？

可以。於ILinkEmbedController.getObjectStoringLocation 中，對想要另存為獨立檔案的內容類型回傳 Link（屬於 LinkEmbedDecision），其餘則回傳 Embed。

為什麼匯出的圖片副檔名與來源簡報不同？

Aspose.Slides 可能在 HTML 匯出過程中重新編碼點陣圖，以縮小尺寸或提升瀏覽器相容性。例如，來源檔案中的圖片可能會依最終渲染結果寫入為 JPEG 或 PNG。

搬移 HTML 檔案後相對 URL 仍然有效嗎？

相對 URL 僅在相同的相對資料夾結構被保留時有效。若 HTML 仍引用 assets/resource-1.png，則 assets 資料夾必須保持在 HTML 檔案旁，除非您產生了不同的 URL 前置字串。

我可以在 Android 上將資源寫入公共外部儲存嗎？

可以，只要您的應用程式對目標 Android 版本具備有效的目的地與權限模型。對於僅供應用程式使用的產生 HTML，使用應用程式專屬檔案或快取目錄通常較為簡易。若是供使用者可見的輸出，請使用使用者選取的位置或其他符合您應用程式的儲存方式。

伺服器應用程式應該重複使用相同的輸出資料夾嗎？

不應。請為每一次轉換工作使用唯一的輸出目錄或儲存前置字串。這可避免檔名衝突，並防止一個匯出覆寫另一個匯出的資源。

從簡報中取得整個投影片背景作為影像在 Aspose.Slides for Android via Java 中的多執行緒