在 .NET 中管理簡報的標記與自訂資料
概述
本文說明 Aspose.Slides 如何在 PowerPoint 簡報中使用標記與自訂資料。簡報特定的資料可以儲存為標記或自訂 XML 部分。標記是簡單的鍵值字串對,而自訂 XML 部分可以儲存結構化的中繼資料和應用程式特定的 XML 負載。
Aspose.Slides 提供用於在簡報、投影片和圖形層級新增、讀取、更新、稽核和移除自訂 XML 部分的 API。自訂 XML 部分對於整合儲存文件管理識別碼、工作流程狀態、合規性中繼資料、範本綁定資料或其他結構化應用程式資料等資訊於簡報中非常有用。
簡報檔案中的資料儲存
PPTX 檔案(副檔名為 .pptx)採用 PresentationML 格式儲存,該格式是 Office Open XML 規範的一部份。Office Open XML 定義了用於儲存簡報內容及相關資料的封裝結構與關係。
一個簡報包含多個以關係相連的部件。例如,投影片部件包含單一投影片的內容,並可與 ISO/IEC 29500 定義的其他部件建立明確的關係。
自訂資料可以儲存為標記(ITagCollection)或自訂 XML 部分(ICustomXmlPartCollection)。兩者皆可透過 ICustomData 介面取得。
使用自訂 XML 部分
ICustomData.CustomXmlParts 屬性會回傳與特定簡報物件相關聯的自訂 XML 部分集合。例如:
presentation.CustomData.CustomXmlParts包含與簡報本身相關聯的自訂 XML 部分。slide.CustomData.CustomXmlParts包含與特定投影片相關聯的自訂 XML 部分。shape.CustomData.CustomXmlParts包含與特定圖形相關聯的自訂 XML 部分。
當您需要檢查簡報中所有自訂 XML 部分(無論其關聯位置)時,使用 Presentation.AllCustomXmlParts。
將自訂 XML 部分新增至簡報
使用 ICustomXmlPartCollection.Add 將 XML 資料新增至自訂 XML 部分集合。XML 必須為有效且非空的。
以下範例將結構化的中繼資料新增至簡報層級的自訂資料集合:
using System;
using Aspose.Slides;
var customXmlContent =
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<metadata xmlns=\"urn:example:metadata\">" +
"<documentId>DOC-1001</documentId>" +
"<workflowState>Draft</workflowState>" +
"</metadata>";
using var presentation = new Presentation();
var customXmlPart = presentation.CustomData.CustomXmlParts.Add(customXmlContent);
// Add 會自動指派識別碼。只有在需要時才設定特定的 GUID。
customXmlPart.ItemId = Guid.NewGuid();
presentation.Save("presentation_with_custom_xml.pptx", SaveFormat.Pptx);
Add 方法也可接受 XML 的位元組陣列或串流,這在 XML 內容已以二進位形式存在時十分有用。
將自訂 XML 部分新增至投影片或圖形
自訂 XML 資料可以與特定投影片或圖形關聯,而非整個簡報。當中繼資料僅描述單一物件(例如範本鍵、外部記錄識別碼或綁定資訊)時,這非常有用。
以下範例將一個自訂 XML 部分新增至投影片,另一個新增至圖形:
using Aspose.Slides;
using var presentation = new Presentation();
var slide = presentation.Slides[0];
slide.CustomData.CustomXmlParts.Add(
"<slideMetadata xmlns=\"urn:example:slides\">" +
"<templateKey>TitleSlide</templateKey>" +
"</slideMetadata>");
var shape = slide.Shapes.AddAutoShape(ShapeType.Rectangle, 50, 50, 250, 80);
shape.TextFrame.Text = "Customer data";
shape.CustomData.CustomXmlParts.Add(
"<shapeMetadata xmlns=\"urn:example:shapes\">" +
"<recordId>CRM-4281</recordId>" +
"</shapeMetadata>");
presentation.Save("object_custom_xml.pptx", SaveFormat.Pptx);
部件新增的層級決定了哪個物件的 CustomData.CustomXmlParts 集合包含對該部件的關係。簡報層級的資料適用於全文件的中繼資料,投影片層級的資料適用於屬於特定投影片的資訊,圖形層級的資料則用於與單一圖形相關聯的中繼資料。
列出並稽核所有自訂 XML 部分
使用 Presentation.AllCustomXmlParts 可從簡報中取得所有自訂 XML 部分。每個 ICustomXmlPart 會公開其識別碼、XML 內容以及相關的命名空間結構描述。
以下範例列出所有自訂 XML 部分及其命名空間結構描述:
using System;
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
foreach (var customXmlPart in presentation.AllCustomXmlParts)
{
Console.WriteLine("ItemId: " + customXmlPart.ItemId);
Console.WriteLine("XML:");
Console.WriteLine(customXmlPart.XmlAsString);
foreach (var namespaceSchema in customXmlPart.NamespaceSchemas)
{
Console.WriteLine("Namespace schema: " + namespaceSchema);
}
Console.WriteLine();
}
ICustomXmlPart.NamespaceSchemas 會回傳與自訂 XML 部分相關聯的 XML 結構描述。此資訊在稽核包含外部系統產生的 XML 的簡報時可能很有用。
讀取與更新 XML 內容及 ItemId
使用 ICustomXmlPart.XmlAsString 以 UTF-8 字串方式處理 XML,或使用 ICustomXmlPart.XmlData 以原始 XML 位元組處理。兩個屬性皆可讀取與更新。
ICustomXmlPart.ItemId 屬性包含在 Office Open XML 文件中識別自訂 XML 部分的 GUID。當整合需要新識別碼時,也可以更改此屬性。
以下範例更新 XML 內容與識別碼:
using System;
using System.Text;
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
var customXmlPart = presentation.AllCustomXmlParts[0];
// Read the current XML as text.
var currentXmlContent = customXmlPart.XmlAsString;
Console.WriteLine(currentXmlContent);
// Update the XML as a UTF-8 string.
customXmlPart.XmlAsString =
"<metadata xmlns=\"urn:example:metadata\">" +
"<documentId>DOC-1001</documentId>" +
"<workflowState>Approved</workflowState>" +
"</metadata>";
// XmlData provides the same XML content as raw bytes.
var customXmlData = customXmlPart.XmlData;
Console.WriteLine(Encoding.UTF8.GetString(customXmlData));
// Replace the identifier when required by the integration.
customXmlPart.ItemId = Guid.NewGuid();
presentation.Save("updated_custom_xml.pptx", SaveFormat.Pptx);
在指派 XmlAsString 或 XmlData 時,請提供有效且非空的 XML。根據應用程式主要使用字串或位元組資料,選擇其中一種表示方式。
移除自訂 XML 部分
Aspose.Slides 提供多種移除自訂 XML 資料的方法:
ICustomXmlPart.Remove會從簡報中移除自訂 XML 部分。ICustomXmlPartCollection.Remove會從自訂 XML 部分集合中移除特定部件。ICustomXmlPartCollection.RemoveAt會移除集合中指定索引的部件。ICustomXmlPartCollection.Clear會清除特定集合中的所有部件。
以下範例依參考移除一個簡報層級的自訂 XML 部分:
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
var customXmlParts = presentation.CustomData.CustomXmlParts;
if (customXmlParts.Count > 0)
{
var customXmlPart = customXmlParts[0];
customXmlParts.Remove(customXmlPart);
}
presentation.Save("custom_xml_removed.pptx", SaveFormat.Pptx);
如果您已持有 ICustomXmlPart,且想直接從簡報中移除該部件,而非針對特定集合,請呼叫 customXmlPart.Remove()。
也可以依索引移除項目:
presentation.CustomData.CustomXmlParts.RemoveAt(0);
清除集合中的所有自訂 XML 部分
當需要移除與特定簡報物件相關聯的所有自訂 XML 部分時,使用 Clear。
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
presentation.Slides[0].CustomData.CustomXmlParts.Clear();
presentation.Save("slide_custom_xml_cleared.pptx", SaveFormat.Pptx);
Clear 只會影響所選的集合。例如,清除投影片的集合不會清除簡報層級或圖形層級的集合。
若要移除簡報中的所有自訂 XML 部分,可遍歷 AllCustomXmlParts 並逐一移除每個部件:
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
foreach (var customXmlPart in presentation.AllCustomXmlParts)
{
customXmlPart.Remove();
}
presentation.Save("all_custom_xml_removed.pptx", SaveFormat.Pptx);
處理連結或共享的自訂 XML 部分
在 Office Open XML 簡報中,同一個自訂 XML 部分可能被多個簡報物件參照。例如,現有檔案可能包含多個投影片或圖形與相同底層自訂 XML 部分的關係。
共享的部件應視為具有多個參照的單一資料物件:
- 更新其
XmlAsString、XmlData或ItemId會變更底層的自訂 XML 部分,因而在所有參照該部件的地方都會生效。 ItemId可用於在稽核物件層級集合時識別相同的自訂 XML 部分。- 從特定的
CustomXmlParts集合移除部件,只會從該集合中移除。若要將部件本身從簡報中移除,請使用ICustomXmlPart.Remove()。 - 在刪除或取代共享部件之前,請檢查物件層級的集合,以確認是否仍有其他投影片或圖形參照該部件。
Add 的多載會根據 XML 內容建立新的自訂 XML 部分;它們不接受現有的 ICustomXmlPart。因此,當載入已包含共享關係的簡報時,最常會遇到此情況。
以下範例依 ItemId 稽核簡報、投影片與圖形層級的集合,並報告被多處參照的部件:
using System;
using System.Collections.Generic;
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
var referencesByItemId = new Dictionary<Guid, List<string>>();
var registerCustomXmlParts = (string ownerName, ICustomXmlPartCollection customXmlParts) =>
{
foreach (var customXmlPart in customXmlParts)
{
if (!referencesByItemId.ContainsKey(customXmlPart.ItemId))
{
referencesByItemId[customXmlPart.ItemId] = new List<string>();
}
referencesByItemId[customXmlPart.ItemId].Add(ownerName);
}
};
registerCustomXmlParts("Presentation", presentation.CustomData.CustomXmlParts);
for (var slideIndex = 0; slideIndex < presentation.Slides.Count; slideIndex++)
{
var slide = presentation.Slides[slideIndex];
registerCustomXmlParts("Slide " + (slideIndex + 1), slide.CustomData.CustomXmlParts);
for (var shapeIndex = 0; shapeIndex < slide.Shapes.Count; shapeIndex++)
{
var shape = slide.Shapes[shapeIndex];
registerCustomXmlParts("Slide " + (slideIndex + 1) + ", shape " + shapeIndex, shape.CustomData.CustomXmlParts);
}
}
foreach (var referenceEntry in referencesByItemId)
{
if (referenceEntry.Value.Count > 1)
{
Console.WriteLine("Shared custom XML part: " + referenceEntry.Key);
foreach (var ownerName in referenceEntry.Value)
{
Console.WriteLine(" Referenced by: " + ownerName);
}
}
}
此類稽核在修改或刪除外部系統建立的簡報中的自訂 XML 資料之前非常有用,因為相同的中繼資料部件可能參與多個關係。
取得標記的值
在 Slides 中,標記對應到 IDocumentProperties.Keywords 屬性。以下範例代碼示範如何使用 Aspose.Slides for .NET 取得 Presentation 的標記值:
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
var keywords = presentation.DocumentProperties.Keywords;
將標記新增至簡報
Aspose.Slides 允許您在簡報中新增標記。標記通常由兩個項目組成:
- 自訂屬性的名稱,例如
MyTag; - 自訂屬性的值,例如
My Tag Value。
如果需要依特定規則或屬性對簡報進行分類,您可以新增相應的標記。例如,若要將北美國家的簡報分類,您可以建立「North American」標記,並將相應的國家指定為其值。
以下範例代碼示範如何使用 Aspose.Slides for .NET 為 Presentation 新增標記:
using Aspose.Slides;
using var presentation = new Presentation("presentation.pptx");
var tags = presentation.CustomData.Tags;
tags["MyTag"] = "My Tag Value";
標記也可以設定於 Slide:
using Aspose.Slides;
using var presentation = new Presentation();
var slide = presentation.Slides[0];
slide.CustomData.Tags["tag"] = "value";
或是個別的 Shape:
using Aspose.Slides;
using var presentation = new Presentation();
var slide = presentation.Slides[0];
var shape = slide.Shapes.AddAutoShape(ShapeType.Rectangle, 10, 10, 100, 50);
shape.TextFrame.Text = "My text";
shape.CustomData.Tags["tag"] = "value";
限制
透過 CustomData.Tags 集合新增的標記僅儲存於 PowerPoint 檔案中。當簡報匯出為 PDF 時,這些標記 不會 轉移至 PDF 的標記結構。因此,作為標記指派的自訂識別碼無法從已標記的 PDF 中取得。
解決方法:您可以將自訂識別碼儲存在物件的 Alt Text(例如 shape.AlternativeText = "MyId")。匯出為 PDF 後,Alt Text 可能會出現在 PDF 的標記結構中。
常見問題
我可以一次移除簡報、投影片或圖形的所有標記嗎?
可以。tag collection 支援 Clear 作業,可一次刪除所有鍵值對。
如何在不遍歷整個集合的情況下,依名稱刪除單一標記?
在 TagCollection 上使用 Remove(name) 即可依鍵刪除標記。
如何取得完整的標記名稱清單以進行分析或過濾?
在 tag collection 上使用 GetNamesOfTags,會回傳所有標記名稱的陣列。
如何找出所有自訂 XML 部分,無論其儲存位置?
使用 Presentation.AllCustomXmlParts 可取得簡報中所有自訂 XML 部分。
在更新自訂 XML 部分時,我應該使用 XmlAsString 還是 XmlData?
當應用程式使用 UTF-8 XML 文字時,使用 XmlAsString。當 XML 已以位元組陣列形式存在,或以二進位方式處理較為方便時,使用 XmlData。兩個屬性皆代表同一自訂 XML 部分的 XML 內容。