在 Python via Java 中管理簡報超連結

簡介

超連結將簡報內容連結至網站或簡報內的某個位置。在 PowerPoint 中,超連結通常有兩個用途:

  • 從文字、圖形或媒體框架開啟網站。
  • 導航至另一張投影片,例如從目錄表。

Aspose.Slides for Python via Java 讓您可以新增這些連結、控制其外觀與音效、更新其屬性,並將其移除。以下範例示範如何在單一元素上操作超連結,以及如何在簡報、投影片或文字框層級存取超連結。

新增 URL 超連結

您可以將網站 URL 分配給文字、圖形或媒體框架。您指派超連結的元素決定可點擊的範圍:文字部分會將所選文字連結起來,而圖形或框架則會將投影片物件連結。

若簡報包含相對超連結,請參閱管理超連結基礎以讀取、變更或清除文件層級的基礎。

將 URL 超連結新增至文字

若要將文字連結至網站,將Hyperlink傳遞給文字部分的setHyperlinkClick方法,如下所示。只有該文字部分會變成可點擊。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Hyperlink, Presentation, SaveFormat, ShapeType

presentation = Presentation()
try:
    shape = presentation.getSlides().get_Item(0).getShapes().addAutoShape(ShapeType.Rectangle, 100, 100, 600, 50, False)
    shape.addTextFrame("Aspose: File Format APIs")

    portion_format = shape.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat()
    portion_format.setHyperlinkClick(Hyperlink("https://www.aspose.com/"))
    portion_format.getHyperlinkClick().setTooltip("Explore Aspose file format APIs")
    portion_format.setFontHeight(32)

    presentation.save("presentation-out.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

將 URL 超連結新增至圖形與媒體框架

若要使圖形或框架可點擊,請呼叫其setHyperlinkClick方法。此超連結屬於物件本身,而非其中的文字部分。

相同的作法也適用於圖片、音訊與影片框架:將超連結指派給框架,必要時呼叫setTooltip。

以下範例使矩形可點擊:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Hyperlink, Presentation, SaveFormat, ShapeType

presentation = Presentation()
try:
    shape = presentation.getSlides().get_Item(0).getShapes().addAutoShape(ShapeType.Rectangle, 100, 100, 600, 50)

    shape.setHyperlinkClick(Hyperlink("https://www.aspose.com/"))
    shape.getHyperlinkClick().setTooltip("Explore Aspose file format APIs")

    presentation.save("presentation-out.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

使用超連結建立目錄

內部超連結讓讀者可從目錄跳至特定投影片。以下範例使用setInternalHyperlinkClick將第一張投影片上的「Page 2」文字連結至第二張投影片。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, Paragraph, Portion, Presentation, SaveFormat, ShapeType

Color = jpype.JClass("java.awt.Color")

presentation = Presentation()
try:
    first_slide = presentation.getSlides().get_Item(0)
    second_slide = presentation.getSlides().addEmptySlide(first_slide.getLayoutSlide())

    table_of_contents = first_slide.getShapes().addAutoShape(ShapeType.Rectangle, 40, 40, 300, 100)
    table_of_contents.getFillFormat().setFillType(FillType.NoFill)
    table_of_contents.getLineFormat().getFillFormat().setFillType(FillType.NoFill)
    table_of_contents.getTextFrame().getParagraphs().clear()

    paragraph = Paragraph()
    paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    paragraph.setText("Title of slide 2 .......... ")

    link_portion = Portion()
    link_portion.setText("Page 2")
    link_portion.getPortionFormat().getHyperlinkManager().setInternalHyperlinkClick(second_slide)

    paragraph.getPortions().add(link_portion)
    table_of_contents.getTextFrame().getParagraphs().add(paragraph)

    presentation.save("link_to_slide.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

格式化超連結

顏色

setColorSource方法屬於Hyperlink,用以判斷超連結是使用簡報的超連結顏色或文字部分的格式。若要套用自訂文字顏色,請選取HyperlinkColorSource.PortionFormat並設定該部分的填色。此功能於 PowerPoint 2019 之後推出;較舊版本不會套用此設定。

以下範例在同一張投影片上新增兩個文字超連結。第一個使用紅色文字填色,第二個則保留預設的超連結顏色。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, Hyperlink, HyperlinkColorSource, Presentation, SaveFormat, ShapeType

Color = jpype.JClass("java.awt.Color")

presentation = Presentation()
try:
    colored_link_shape = presentation.getSlides().get_Item(0).getShapes().addAutoShape(ShapeType.Rectangle, 100, 100, 450, 50, False)
    colored_link_shape.addTextFrame("This hyperlink uses a custom color.")
    portion_format = colored_link_shape.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat()
    portion_format.setHyperlinkClick(Hyperlink("https://www.aspose.com/"))
    portion_format.getHyperlinkClick().setColorSource(HyperlinkColorSource.PortionFormat)
    portion_format.getFillFormat().setFillType(FillType.Solid)
    portion_format.getFillFormat().getSolidFillColor().setColor(Color.RED)

    default_link_shape = presentation.getSlides().get_Item(0).getShapes().addAutoShape(ShapeType.Rectangle, 100, 200, 450, 50, False)
    default_link_shape.addTextFrame("This hyperlink uses the default color.")
    default_link_shape.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat().setHyperlinkClick(Hyperlink("https://www.aspose.com/"))

    presentation.save("presentation-out-hyperlink.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

音效

超連結在被啟動時可以播放音效,或停止已在播放的音效。使用以下方法設定這些行為:

新增超連結音效

以下範例載入 sampleaudio.wav 並將其關聯到第一張投影片上的按鈕。點擊按鈕會播放音效並導向下一張投影片。該投影片上的第二個圖形在點擊時會停止先前的音效,且不執行導向動作。

from pathlib import Path

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Hyperlink, Presentation, SaveFormat, ShapeType

presentation = Presentation()
try:
    audio_data = Path("sampleaudio.wav").read_bytes()
    java_audio_data = jpype.JArray(jpype.JByte)(audio_data)
    hyperlink_sound = presentation.getAudios().addAudio(java_audio_data)
    first_slide = presentation.getSlides().get_Item(0)
    play_button = first_slide.getShapes().addAutoShape(ShapeType.SoundButton, 100, 100, 100, 50)
    play_button.setHyperlinkClick(Hyperlink.getNextSlide())
    if not play_button.getHyperlinkClick().getStopSoundOnClick() and play_button.getHyperlinkClick().getSound() is None:
        play_button.getHyperlinkClick().setSound(hyperlink_sound)
    second_slide = presentation.getSlides().addEmptySlide(first_slide.getLayoutSlide())
    stop_button = second_slide.getShapes().addAutoShape(ShapeType.Rectangle, 100, 100, 100, 50)
    stop_button.setHyperlinkClick(Hyperlink.getNoAction())
    stop_button.getHyperlinkClick().setStopSoundOnClick(True)
    presentation.save("hyperlink-sound.pptx", SaveFormat.Pptx)
except OSError as exception:
    print(f"Unable to read the audio file: {exception}")
finally:
    presentation.dispose()

擷取超連結音效

以下範例開啟上述建立的簡報,並透過getSound與getBinaryData將第一個圖形的超連結音訊讀取至記憶體。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation

presentation = Presentation("hyperlink-sound.pptx")
try:
    if presentation.getSlides().size() > 0 and presentation.getSlides().get_Item(0).getShapes().size() > 0:
        hyperlink = presentation.getSlides().get_Item(0).getShapes().get_Item(0).getHyperlinkClick()
        sound = hyperlink.getSound() if hyperlink is not None else None
        if sound is not None:
            audio_data = bytes(sound.getBinaryData())
            print(f"Extracted {len(audio_data)} bytes of hyperlink audio.")
        else:
            print("The first shape has no hyperlink sound.")
    else:
        print("The presentation has no first slide or shape to inspect.")
finally:
    presentation.dispose()

工具提示與互動設定

在將超連結指派給文字或圖形後,您可以呼叫以下Hyperlink方法:

  • setTooltip 設定觀眾可顯示的提示文字。
  • setTargetFrame 在適用時指定父 HTML 框架集中的目標框架。
  • setHistory 控制啟動連結時是否將其目的地加入已檢視超連結清單。
  • setHighlightClick 控制點擊時是否突顯超連結。

從簡報中移除超連結

使用getAnyHyperlinks收集超連結容器,包括文字部分的連結,於修改前先行取得。以下範例從第一張投影片移除兩種啟動方式。若僅要移除單一類型,僅呼叫removeHyperlinkClick或removeHyperlinkMouseOver;移除點擊動作不會移除其滑鼠懸停對應項目。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat

presentation = Presentation("pres.pptx")
try:
    if presentation.getSlides().size() > 0:
        containers = list(presentation.getSlides().get_Item(0).getHyperlinkQueries().getAnyHyperlinks())
        for container in containers:
            container.getHyperlinkManager().removeHyperlinkClick()
            container.getHyperlinkManager().removeHyperlinkMouseOver()
        presentation.save("pres-removed-hyperlinks.pptx", SaveFormat.Pptx)
    else:
        print("The presentation has no slides to process.")
finally:
    presentation.dispose()

若要無條件移除,可使用removeAllHyperlinks一次呼叫即在選取範圍內移除兩種啟動方式。若需選擇性清理並涵蓋母片、版面配置與備註,請參閱Report, Sanitize, and Verify Hyperlinks。

建立完整的超連結清單

在發佈簡報前,請先盤點其互動動作及網路連結。getAnyHyperlinks會回傳超連結容器,如Shape與PortionFormat物件,而非單純的 URL 字串清單。請檢查每個容器的getHyperlinkClick與getHyperlinkMouseOver。它們是獨立的:相同容器可同時提供兩種動作,因此完整報告可能需要每個容器最多兩列。

僅掃描圖形層級的超連結可能會遺漏附加於文字部分的連結。請改為查詢適當的範圍,並保留回傳的容器,以便之後更新或移除其動作。

查詢簡報、投影片與文字框範圍

HyperlinkQueries 類別可透過Presentation.getHyperlinkQueries、BaseSlide.getHyperlinkQueries與TextFrame.getHyperlinkQueries取得。每個範圍支援相同的查詢:

以下範例建立 hyperlink-audit-input.pptx,其中包含外部點擊連結、檔案滑鼠懸停連結、內部投影片導航、文字滑鼠懸停連結,以及巨集動作。這些動作均不會被執行。相同的三種查詢在每個範圍皆可使用;計數描述的是容器數量,而非動作總數。文字框範圍會排除其所屬圖形本身的連結。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, SaveFormat, ShapeType


def print_counts(scope, queries):
    click_count = queries.getHyperlinkClicks().size()
    mouse_over_count = queries.getHyperlinkMouseOvers().size()
    any_count = queries.getAnyHyperlinks().size()
    print(f"{scope}: click={click_count}, mouse-over={mouse_over_count}, any={any_count}")


presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)
    destination = presentation.getSlides().addEmptySlide(slide.getLayoutSlide())
    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 20, 20, 400, 60)
    shape.getTextFrame().setText("Click the text to go to slide 2")
    shape.getHyperlinkManager().setExternalHyperlinkClick("https://example.com/")
    shape.getHyperlinkClick().setTooltip("Public website")
    shape.getHyperlinkManager().setExternalHyperlinkMouseOver("file:///C:/private/report.xlsx")
    portion_format = shape.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat()
    portion_format.getHyperlinkManager().setInternalHyperlinkClick(destination)
    portion_format.getHyperlinkManager().setExternalHyperlinkMouseOver("https://example.com/help")
    macro_button = slide.getShapes().addAutoShape(ShapeType.Rectangle, 20, 120, 200, 60)
    macro_button.getHyperlinkManager().setMacroHyperlinkClick("ReviewPresentation")
    print_counts("Presentation", presentation.getHyperlinkQueries())
    print_counts("Slide 1", slide.getHyperlinkQueries())
    print_counts("Text frame", shape.getTextFrame().getHyperlinkQueries())
    presentation.save("hyperlink-audit-input.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

在此範例中,簡報與投影片的查詢各回報三個點擊容器、兩個滑鼠懸停容器,以及三個任一動作的容器。文字框的查詢則在每個類別各回報一個容器。

分類動作與目的地

使用Hyperlink.getActionType判斷動作類型,再解析其目的地。HyperlinkActionType 的值涵蓋了超出網頁導向的情況:

值 審核說明
Hyperlink 外部超連結;檢查 URL 及其協議。
JumpSpecificSlide 內部導航至特定投影片。
JumpFirstSlide, JumpPreviousSlide, JumpNextSlide, JumpLastSlide, JumpLastViewedSlide 內建投影片放映導航,於放映環境中解析。
JumpEndShow, StartCustomSlideShow 結束目前的放映或啟動自訂放映。
StartMacro 執行巨集。
StartProgram 啟動程式。
OpenFile, OpenPresentation 開啟檔案或其他簡報;需與網路 URL 分別檢查。
StartStopMedia 開始或停止媒體播放。
NoAction, Unknown 無導航動作,或未識別的動作需檢查。

從getExternalUrl讀取外部目的地,從getTargetSlide讀取特定的內部目的地。內部動作與內建指令可能沒有外部 URL;空的 URL 並不表示容器沒有動作。若getExternalUrlOriginal回傳的值與正規化的 URL 不同,請保留該值;若有返回的工具提示,亦請包含由getTooltip提供的文字。

報告、清理與驗證超連結

以下 Python 範例讀取既有的簡報(使用上述建立的檔案),寫入 hyperlink-audit.json,套用政策,儲存為 hyperlink-sanitized.pptx,並再次開啟以檢查兩種啟動方式。它在變更之前收集容器,並使用參考相等性避免重複處理同一容器。簡報查詢涵蓋普通投影片;若要進行整個套件的清點,亦會明確查詢母片、版面配置、備註,以及存在時的備註與講義母片。

報告會記錄以 1 為起點的投影片索引與getSlideId(如有)。getSlide 為支援的容器提供其所屬投影片。母片、版面配置與備註沒有普通的投影片索引,會以其範圍辨識。圖形容器與文字部分格式容器分別標記;其他容器類型保留其執行時類型名稱。每個容器獲得報告本地的 ID,以便將其兩個動作關聯。報告將動作類型儲存為 Java 列舉定義的整數常數。

此刻意嚴格的應用政策僅允許絕對的 HTTPS URL 與有效的內部投影片目標。它會拒絕巨集、程式、檔案動作、其他投影片放映動作、未知動作以及其他 URL 協定。這些拒絕屬於政策決策,而非 Aspose.Slides 安全性判斷。僅有 HTTPS 並不保證可信任:請為您的應用程式加入主機白名單與其他檢查。原始與正規化的外部 URL 都會被檢查。此範例僅稽核中繼資料,未會追蹤連結或執行動作。

若要修正,容器的getHyperlinkManager支援setExternalHyperlinkClick、removeHyperlinkClick與removeHyperlinkMouseOver。此處,禁止的外部點擊連結會被替換為固定的 HTTPS 登陸頁面;其他禁止的點擊與禁止的滑鼠懸停動作則分別被移除。將 replace_external_clicks 設為 False 可改為移除所有政策違規。請在部署前選擇由應用程式擁有的替代頁面。

報告的匯出旗標採用保守的 PDF 檢查政策:將滑鼠懸停動作以及除外部連結或特定投影片跳轉之外的任何項目標記為可能不支援。這僅是檢查提示,非功能測試或保證未標記的連結在匯出時仍會保留。支援的PDF與HTML匯出可能會保留超連結,視動作、匯出選項與檢視器而定。點陣圖像與影片無法保留互動式超連結;在針對這些輸出稽核時請將每個動作皆標記。

import json
from pathlib import Path
from urllib.parse import urlsplit

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import HyperlinkActionType, PortionFormat, Presentation, SaveFormat, Shape

IdentityHashMap = jpype.JClass("java.util.IdentityHashMap")


def slide_index(presentation, slide):
    for index, candidate in enumerate(presentation.getSlides(), start=1):
        if candidate == slide:
            return index
    return None


def is_https(value):
    if not value:
        return False
    value = str(value)
    if any(character.isspace() or ord(character) < 32 for character in value):
        return False
    try:
        uri = urlsplit(value)
        return uri.scheme.lower() == "https" and bool(uri.hostname)
    except ValueError:
        return False


def policy_violation(link):
    if link is None:
        return None
    if link.getActionType() == HyperlinkActionType.JumpSpecificSlide:
        return "Missing target slide" if link.getTargetSlide() is None else None
    if link.getActionType() != HyperlinkActionType.Hyperlink:
        return "Action is not allowed"
    if not is_https(link.getExternalUrl()):
        return "Normalized URL is not absolute HTTPS"
    original = link.getExternalUrlOriginal()
    if original and not is_https(original):
        return "Original URL is not absolute HTTPS"
    return None


def collect_containers(presentation):
    found = list(presentation.getHyperlinkQueries().getAnyHyperlinks())
    scopes = list(presentation.getMasters()) + list(presentation.getLayoutSlides())
    for slide in presentation.getSlides():
        scopes.append(slide.getNotesSlideManager().getNotesSlide())
    scopes.append(presentation.getMasterNotesSlideManager().getMasterNotesSlide())
    scopes.append(presentation.getMasterHandoutSlideManager().getMasterHandoutSlide())
    for scope in scopes:
        if scope is not None:
            found.extend(scope.getHyperlinkQueries().getAnyHyperlinks())
    seen = IdentityHashMap()
    unique = []
    for container in found:
        if not seen.containsKey(container):
            seen.put(container, True)
            unique.append(container)
    return unique


def text_or_none(value):
    return str(value) if value is not None else None


def add_row(rows, presentation, link, activation, container, container_id):
    if link is None:
        return
    owner_slide = container.getSlide() if hasattr(container, "getSlide") else None
    target_slide = link.getTargetSlide()
    violation = policy_violation(link)
    if isinstance(container, Shape):
        owner_type = "Shape"
    elif isinstance(container, PortionFormat):
        owner_type = "Text portion"
    else:
        owner_type = str(container.getClass().getSimpleName())
    ordinary_action = link.getActionType() in (HyperlinkActionType.Hyperlink, HyperlinkActionType.JumpSpecificSlide)
    original = link.getExternalUrlOriginal()
    rows.append({
        "ContainerId": container_id,
        "SlideIndex": slide_index(presentation, owner_slide),
        "SlideId": int(owner_slide.getSlideId()) if owner_slide is not None else None,
        "Scope": str(owner_slide.getClass().getSimpleName()) if owner_slide is not None else None,
        "OwnerType": owner_type,
        "Activation": activation,
        "ActionType": int(link.getActionType()),
        "ExternalUrl": text_or_none(link.getExternalUrl()),
        "TargetSlideIndex": slide_index(presentation, target_slide),
        "TargetSlideId": int(target_slide.getSlideId()) if target_slide is not None else None,
        "Tooltip": text_or_none(link.getTooltip()),
        "OriginalExternalUrl": text_or_none(original) if original != link.getExternalUrl() else None,
        "PotentiallyUnsafe": violation is not None,
        "PolicyViolation": violation,
        "TargetExport": "PDF",
        "PotentiallyUnsupportedByExport": activation == "mouse-over" or not ordinary_action,
    })


replace_external_clicks = True
replacement_url = "https://example.com/blocked-link"
presentation = Presentation("hyperlink-audit-input.pptx")
try:
    containers = collect_containers(presentation)
    rows = []
    for container_id, container in enumerate(containers, start=1):
        add_row(rows, presentation, container.getHyperlinkClick(), "click", container, container_id)
        add_row(rows, presentation, container.getHyperlinkMouseOver(), "mouse-over", container, container_id)
    report = json.dumps(rows, indent=2)
    Path("hyperlink-audit.json").write_text(report, encoding="utf-8")

    for container in containers:
        click = container.getHyperlinkClick()
        if policy_violation(click) is not None:
            if replace_external_clicks and click.getActionType() == HyperlinkActionType.Hyperlink:
                container.getHyperlinkManager().setExternalHyperlinkClick(replacement_url)
            else:
                container.getHyperlinkManager().removeHyperlinkClick()
        if policy_violation(container.getHyperlinkMouseOver()) is not None:
            container.getHyperlinkManager().removeHyperlinkMouseOver()
    presentation.save("hyperlink-sanitized.pptx", SaveFormat.Pptx)

    reopened = Presentation("hyperlink-sanitized.pptx")
    try:
        remaining_containers = collect_containers(reopened)
        violations = 0
        for container in remaining_containers:
            if policy_violation(container.getHyperlinkClick()) is not None:
                violations += 1
            if policy_violation(container.getHyperlinkMouseOver()) is not None:
                violations += 1
        print(f"Audit rows: {len(rows)}; prohibited actions after reopening: {violations}")
        if violations != 0:
            print("Verification failed: do not distribute the saved presentation.")
    finally:
        reopened.dispose()
except OSError as exception:
    print(f"Unable to write the audit report: {exception}")
finally:
    presentation.dispose()

使用上述建立的輸入,報告包含五列動作。檔案滑鼠懸停連結與巨集點擊被移除,HTTPS 連結與內部投影片導航則保留。驗證顯示零項禁止動作。若輸入含有被禁止的外部點擊 URL,亦會觸發取代分支。容器若同時具備允許的點擊與被禁止的滑鼠懸停,則保留其點擊動作。

此選擇性清理不同於removeAllHyperlinks,後者會不顧政策在選取範圍內移除兩種啟動方式。此處的驗證僅檢查超連結動作;不會移除內嵌的 VBA 專案、OLE 物件或其他活動內容,也不會驗證匯出的 PDF 或 HTML 檔案。

常見問題

如何連結至章節或其第一張投影片?

PowerPoint 的章節會將投影片分組,但內部超連結只能鎖定單一投影片。若要導向章節,請將連結指向該章節的第一張投影片。

我可以將超連結附加至母片元素,使其在所有投影片上都有效嗎?

可以。母片與版面配置的元素支援超連結。這些元素上的連結會在投影片放映時,於使用相應母片或版面配置的投影片上可用。

匯出為 PDF、HTML、圖像或影片時,超連結會被保留嗎?

支援的 PDF 與 HTML 匯出可能會保留超連結;點陣圖像與影片則無法。請參閱報告、清理與驗證超連結中的匯出注意事項。