Table of Contents

Class OdfImageDocument

Namespace
OdfKit.Image
Assembly
OdfKit.dll

Minimal packaging wrapper representing an ODF image document (.odi). 表示 ODF 影像文件 (.odi) 的最小封裝 wrapper。

public class OdfImageDocument : OdfDocument, IDisposable, IAsyncDisposable
Inheritance
OdfImageDocument
Implements
Derived
Inherited Members

Constructors

OdfImageDocument(OdfPackage)

Initializes a new instance of the OdfImageDocument class with the specified ODF package. 使用指定的 ODF 封裝初始化 OdfImageDocument 類別的新執行個體。

public OdfImageDocument(OdfPackage package)

Parameters

package OdfPackage

The ODF package. / ODF 封裝。

Properties

FrameDescription

Gets or sets the description of the main image frame. 取得或設定主要影像框架描述。

public string? FrameDescription { get; set; }

Property Value

string

FrameHeight

Gets or sets the height of the main image frame. 取得或設定主要影像框架高度。

public OdfLength? FrameHeight { get; set; }

Property Value

OdfLength?

FrameName

Gets or sets the name of the main image frame. 取得或設定主要影像框架名稱。

public string? FrameName { get; set; }

Property Value

string

FrameTitle

Gets or sets the title of the main image frame. 取得或設定主要影像框架標題。

public string? FrameTitle { get; set; }

Property Value

string

FrameWidth

Gets or sets the width of the main image frame. 取得或設定主要影像框架寬度。

public OdfLength? FrameWidth { get; set; }

Property Value

OdfLength?

FrameX

Gets or sets the X-axis position of the main image frame. 取得或設定主要影像框架的 X 軸座標位置。

public OdfLength? FrameX { get; set; }

Property Value

OdfLength?

FrameY

Gets or sets the Y-axis position of the main image frame. 取得或設定主要影像框架的 Y 軸座標位置。

public OdfLength? FrameY { get; set; }

Property Value

OdfLength?

ImageFrame

Gets the main image frame node. 取得主要影像框架節點。

public OdfNode? ImageFrame { get; }

Property Value

OdfNode

ImageHref

Gets the main image reference path. 取得主要影像參照路徑。

public string? ImageHref { get; }

Property Value

string

ImageInfo

Gets summary packaging information for the main image. 取得主要影像的封裝摘要資訊。

public OdfImageInfo? ImageInfo { get; }

Property Value

OdfImageInfo

ImageNode

Gets the main image container node. 取得主要影像容器節點。

public OdfNode ImageNode { get; }

Property Value

OdfNode

Methods

AddImageFrame(byte[], OdfLength, OdfLength, OdfLength, OdfLength)

Short overload of AddImageFrame that accepts imageBytes, x, y, width, and height; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 imageBytes、x、y、width 與 height；其餘可選參數使用預設值並轉呼叫最長 AddImageFrame 多載。

public string AddImageFrame(byte[] imageBytes, OdfLength x, OdfLength y, OdfLength width, OdfLength height)

Parameters

imageBytes byte[]
x OdfLength
y OdfLength
width OdfLength
height OdfLength

Returns

string

AddImageFrame(byte[], OdfLength, OdfLength, OdfLength, OdfLength, string?)

Short overload of AddImageFrame that accepts imageBytes, x, y, width, height, and preferredName; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 imageBytes、x、y、width、height 與 preferredName；其餘可選參數使用預設值並轉呼叫最長 AddImageFrame 多載。

public string AddImageFrame(byte[] imageBytes, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? preferredName)

Parameters

imageBytes byte[]
x OdfLength
y OdfLength
width OdfLength
height OdfLength
preferredName string

Returns

string

AddImageFrame(byte[], OdfLength, OdfLength, OdfLength, OdfLength, string?, string?)

Short overload of AddImageFrame that accepts imageBytes, x, y, width, height, preferredName, and name; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 imageBytes、x、y、width、height、preferredName 與 name；其餘可選參數使用預設值並轉呼叫最長 AddImageFrame 多載。

public string AddImageFrame(byte[] imageBytes, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? preferredName, string? name)

Parameters

imageBytes byte[]
x OdfLength
y OdfLength
width OdfLength
height OdfLength
preferredName string
name string

Returns

string

AddImageFrame(byte[], OdfLength, OdfLength, OdfLength, OdfLength, string?, string?, string?)

Short overload of AddImageFrame that accepts imageBytes, x, y, width, height, preferredName, name, and title; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 imageBytes、x、y、width、height、preferredName、name 與 title；其餘可選參數使用預設值並轉呼叫最長 AddImageFrame 多載。

public string AddImageFrame(byte[] imageBytes, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? preferredName, string? name, string? title)

Parameters

imageBytes byte[]
x OdfLength
y OdfLength
width OdfLength
height OdfLength
preferredName string
name string
title string

Returns

string

AddImageFrame(byte[], OdfLength, OdfLength, OdfLength, OdfLength, string?, string?, string?, string?)

Adds an image frame (without replacing existing frames). 新增一個影像框架（不取代既有框架）。

public string AddImageFrame(byte[] imageBytes, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? preferredName, string? name, string? title, string? description)

Parameters

imageBytes byte[]

The image byte array. / 圖片位元組陣列。

x OdfLength

The X-axis position. / X 軸座標位置。

y OdfLength

The Y-axis position. / Y 軸座標位置。

width OdfLength

The frame width. / 框架寬度。

height OdfLength

The frame height. / 框架高度。

preferredName string

The optional preferred file name. / 選用的偏好檔名。

name string

The optional frame name. / 選用的框架名稱。

title string

The optional frame title. / 選用的框架標題。

description string

The optional frame description. / 選用的框架描述。

Returns

string

The path of the image within the ODF package. / 影像在 ODF 封裝中的路徑。

AddImageFrames(IEnumerable<OdfImageFrameRequest>)

Batch-adds multiple image frames (without replacing existing frames). 批次新增多個影像框架（不取代既有框架）。

public IReadOnlyList<string> AddImageFrames(IEnumerable<OdfImageFrameRequest> requests)

Parameters

requests IEnumerable<OdfImageFrameRequest>

The list of image frame requests to add. / 要新增的影像框架請求清單。

Returns

IReadOnlyList<string>

The list of image paths within the ODF package, in request order. / 依請求順序排列的影像在 ODF 封裝中的路徑清單。

Exceptions

ArgumentNullException

When requests or any request within it is null. / 當 requests 或其中任一筆請求為 null 時擲出。

AddImages(IEnumerable<OdfImageFrameRequest>)

Adds multiple image frames and returns their package hrefs. 新增多個影像框架並回傳其封裝 href。

public IReadOnlyList<string> AddImages(IEnumerable<OdfImageFrameRequest> requests)

Parameters

requests IEnumerable<OdfImageFrameRequest>

The image frame requests. / 影像框架要求。

Returns

IReadOnlyList<string>

The package hrefs written for the added images. / 新增影像寫入的封裝 href。

Create()

Creates a new ODI image document. 建立新的 ODI 影像文件。

public static OdfImageDocument Create()

Returns

OdfImageDocument

A new OdfImageDocument instance. / 新的 OdfImageDocument 執行個體。

CreateFromFlatDocument(FlatImageDocument)

Creates an equivalent ODI (ZIP package) image document from a FODI flat XML image document, with identical content. 從 FODI 扁平 XML 影像文件建立等價的 ODI（ZIP 封裝）影像文件，內容完全相同。

public static OdfImageDocument CreateFromFlatDocument(FlatImageDocument document)

Parameters

document FlatImageDocument

The source FODI flat XML image document. / 來源 FODI 扁平 XML 影像文件。

Returns

OdfImageDocument

The created OdfImageDocument instance. / 建立完成的 OdfImageDocument 執行個體。

CreateFromTemplate(ImageTemplateDocument)

Creates a new ODI image document from the specified image template document. 從指定的影像範本文件建立新的 ODI 影像文件。

public static OdfImageDocument CreateFromTemplate(ImageTemplateDocument template)

Parameters

template ImageTemplateDocument

The image template document. / 影像範本文件。

Returns

OdfImageDocument

The created OdfImageDocument instance. / 建立完成的 OdfImageDocument 執行個體。

FindImageFilter(string)

Finds the filter setting of the image frame with the specified name. 尋找指定名稱影像框架的濾鏡設定。

public OdfImageFilterInfo? FindImageFilter(string name)

Parameters

name string

The frame name. / 框架名稱。

Returns

OdfImageFilterInfo

The filter setting, or null if the frame does not exist or has no filter set. / 濾鏡設定；若框架不存在或未設定濾鏡則為 null。

GetDefaultContentXml()

Gets the default content XML string. 取得預設的內容 XML 字串。

protected override string GetDefaultContentXml()

Returns

string

The default content XML string. / 預設的內容 XML 字串。

GetDefaultStylesXml()

Gets the default styles XML string. 取得預設的樣式 XML 字串。

protected override string GetDefaultStylesXml()

Returns

string

The default styles XML string. / 預設的樣式 XML 字串。

GetImageBytes()

Gets the byte content of the main image. 取得主要影像的位元組內容。

public byte[]? GetImageBytes()

Returns

byte[]

The main image bytes, or null if the document does not reference an image within the package. / 主要影像位元組；若文件未參照封裝內影像則為 null。

GetImageFrames()

Gets a summary list of all image frames in the document. 取得文件中所有影像框架的摘要清單。

public IReadOnlyList<OdfImageFrameInfo> GetImageFrames()

Returns

IReadOnlyList<OdfImageFrameInfo>

InspectImages()

Inspects images for practical portable-editing risks. 檢查圖片的實務可攜編輯風險。

public OdfImageInspectionReport InspectImages()

Returns

OdfImageInspectionReport

The image inspection report. / 圖片檢查報告。

InspectImages(OdfImageInspectionOptions?)

Short overload of InspectImages that accepts options; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 options；其餘可選參數使用預設值並轉呼叫最長 InspectImages 多載。

public OdfImageInspectionReport InspectImages(OdfImageInspectionOptions? options)

Parameters

options OdfImageInspectionOptions

Returns

OdfImageInspectionReport

InspectImages(OdfImageInspectionOptions?, OdfPracticalCompatibilityProfile?)

Inspects images for practical portable-editing risks with a compatibility profile. 依相容性設定檔檢查圖片的實務可攜編輯風險。

public OdfImageInspectionReport InspectImages(OdfImageInspectionOptions? options, OdfPracticalCompatibilityProfile? profile)

Parameters

options OdfImageInspectionOptions

The inspection options. / 檢查選項。

profile OdfPracticalCompatibilityProfile?

The practical compatibility profile. / 實務相容性設定檔。

Returns

OdfImageInspectionReport

The image inspection report. / 圖片檢查報告。

Load(Stream)

Loads an ODI image document from the specified stream. 從指定資料流載入 ODI 影像文件。

public static OdfImageDocument Load(Stream stream)

Parameters

stream Stream

Returns

OdfImageDocument

The loaded OdfImageDocument instance. / 載入完成的 OdfImageDocument 執行個體。

Exceptions

InvalidOperationException

When the specified document is not an ODI image. / 當指定文件不是 ODI 影像時擲出。

Load(Stream, string?)

Full overload of Load that accepts stream and fileName. Load 完整多載：接受 stream 與 fileName。

public static OdfImageDocument Load(Stream stream, string? fileName)

Parameters

stream Stream
fileName string

Returns

OdfImageDocument

Load(string)

Loads an ODI image document from the specified path. 從指定路徑載入 ODI 影像文件。

public static OdfImageDocument Load(string path)

Parameters

path string

The ODI document path. / ODI 文件路徑。

Returns

OdfImageDocument

The loaded OdfImageDocument instance. / 載入完成的 OdfImageDocument 執行個體。

Exceptions

InvalidOperationException

When the specified document is not an ODI image. / 當指定文件不是 ODI 影像時擲出。

LoadAsync(Stream)

Asynchronously loads an ODI image document from the specified stream. 非同步從指定資料流載入 ODI 影像文件。

public static Task<OdfImageDocument> LoadAsync(Stream stream)

Parameters

stream Stream

Returns

Task<OdfImageDocument>

A task representing the asynchronous load operation, whose result is the loaded OdfImageDocument. / 代表非同步載入作業的工作，其結果為載入完成的 OdfImageDocument。

LoadAsync(Stream, string?)

Short overload of LoadAsync that accepts stream and fileName; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 stream 與 fileName；其餘可選參數使用預設值並轉呼叫最長 LoadAsync 多載。

public static Task<OdfImageDocument> LoadAsync(Stream stream, string? fileName)

Parameters

stream Stream
fileName string

Returns

Task<OdfImageDocument>

LoadAsync(Stream, string?, CancellationToken)

Short overload of LoadAsync that accepts stream, fileName, and cancellationToken; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 stream、fileName 與 cancellationToken；其餘可選參數使用預設值並轉呼叫最長 LoadAsync 多載。

public static Task<OdfImageDocument> LoadAsync(Stream stream, string? fileName, CancellationToken cancellationToken)

Parameters

stream Stream
fileName string
cancellationToken CancellationToken

Returns

Task<OdfImageDocument>

LoadAsync(Stream, CancellationToken)

Asynchronously loads the document from a stream with a cancellation token. 以取消語彙基元非同步從資料流載入文件。

public static Task<OdfImageDocument> LoadAsync(Stream stream, CancellationToken cancellationToken)

Parameters

stream Stream

The document stream. / 文件資料流。

cancellationToken CancellationToken

The cancellation token. / 取消語彙基元。

Returns

Task<OdfImageDocument>

A task whose result is the loaded document. / 代表非同步載入作業的工作，其結果為載入完成的文件。

LoadAsync(string)

Asynchronously loads an ODI image document from the specified path. 非同步從指定路徑載入 ODI 影像文件。

public static Task<OdfImageDocument> LoadAsync(string path)

Parameters

path string

Returns

Task<OdfImageDocument>

A task representing the asynchronous load operation, whose result is the loaded OdfImageDocument. / 代表非同步載入作業的工作，其結果為載入完成的 OdfImageDocument。

LoadAsync(string, CancellationToken)

Short overload of LoadAsync that accepts path and cancellationToken; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 path 與 cancellationToken；其餘可選參數使用預設值並轉呼叫最長 LoadAsync 多載。

public static Task<OdfImageDocument> LoadAsync(string path, CancellationToken cancellationToken)

Parameters

path string
cancellationToken CancellationToken

Returns

Task<OdfImageDocument>

MergeContentNodes(OdfDocument, OdfMergeOptions, Dictionary<string, string>)

Merges the content nodes of a source image document into this document. 合併來源影像文件的內容節點至此文件。

protected override void MergeContentNodes(OdfDocument sourceDoc, OdfMergeOptions options, Dictionary<string, string> renameMap)

Parameters

sourceDoc OdfDocument

The source document. / 來源文件。

options OdfMergeOptions

The merge options. / 合併選項。

renameMap Dictionary<string, string>

The dictionary mapping renamed style names. / 樣式重新命名對照表。

Exceptions

ArgumentException

When the source document is not an OdfImageDocument. / 當來源文件不是 OdfImageDocument 時擲出。

RemoveImageFrame(string)

Removes the image frame with the specified name. 移除指定名稱的影像框架。

public bool RemoveImageFrame(string name)

Parameters

name string

The frame name. / 框架名稱。

Returns

bool

true if removed successfully; false if the frame is not found. / 若成功移除則為 true；找不到框架時為 false。

RemoveImageFrames(IEnumerable<string>)

Batch-removes the image frames for the specified list of names. 批次移除指定名稱清單的影像框架。

public int RemoveImageFrames(IEnumerable<string> names)

Parameters

names IEnumerable<string>

The list of frame names to remove. / 要移除的框架名稱清單。

Returns

int

The number of frames actually removed (names not found are ignored without throwing). / 實際成功移除的框架數量（找不到的名稱會被忽略，不會擲出例外）。

Exceptions

ArgumentNullException

When names is null. / 當 names 為 null 時擲出。

SetImage(byte[])

Short overload of SetImage that accepts imageBytes; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 imageBytes；其餘可選參數使用預設值並轉呼叫最長 SetImage 多載。

public string SetImage(byte[] imageBytes)

Parameters

imageBytes byte[]

Returns

string

SetImage(byte[], string?)

Sets the main image of the ODI document. 設定 ODI 文件的主要影像。

public string SetImage(byte[] imageBytes, string? preferredName)

Parameters

imageBytes byte[]

The image byte array. / 圖片位元組陣列。

preferredName string

The optional preferred file name. / 選用的偏好檔名。

Returns

string

The path of the image within the ODF package. / 影像在 ODF 封裝中的路徑。

SetImageCrop(string, OdfImageCropInfo?)

Sets the crop bounds of the image frame with the specified name. 設定指定名稱影像框架的裁切邊界。

public bool SetImageCrop(string name, OdfImageCropInfo? crop)

Parameters

name string

The frame name. / 框架名稱。

crop OdfImageCropInfo

The crop bounds; null removes the existing crop setting. / 裁切邊界；null 表示移除既有裁切設定。

Returns

bool

true if set successfully; false if the frame is not found. / 若成功設定則為 true；找不到框架時為 false。

SetImageCrops(IEnumerable<string>, OdfImageCropInfo?)

Batch-sets crop bounds for image frames. 批次設定影像框架的裁切邊界。

public OdfImageBatchUpdateResult SetImageCrops(IEnumerable<string> names, OdfImageCropInfo? crop)

Parameters

names IEnumerable<string>

The frame names. / 框架名稱清單。

crop OdfImageCropInfo

The crop bounds; null removes crop settings. / 裁切邊界；null 表示移除裁切設定。

Returns

OdfImageBatchUpdateResult

The batch update result. / 批次更新結果。

Exceptions

ArgumentNullException

When names is null. / 當 names 為 null 時擲出。

SetImageFilter(string, OdfImageFilterInfo?)

Sets the filter of the image frame with the specified name. 設定指定名稱影像框架的濾鏡。

public bool SetImageFilter(string name, OdfImageFilterInfo? filter)

Parameters

name string

The frame name. / 框架名稱。

filter OdfImageFilterInfo

The filter setting; pass null to remove the existing filter. / 濾鏡設定；傳入 null 表示移除既有濾鏡。

Returns

bool

true if set successfully; false if the frame is not found. / 若成功設定則為 true；找不到框架時為 false。

SetImageLayout(OdfLength, OdfLength, OdfLength, OdfLength)

Short overload of SetImageLayout that accepts x, y, width, and height; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 x、y、width 與 height；其餘可選參數使用預設值並轉呼叫最長 SetImageLayout 多載。

public void SetImageLayout(OdfLength x, OdfLength y, OdfLength width, OdfLength height)

Parameters

x OdfLength
y OdfLength
width OdfLength
height OdfLength

SetImageLayout(OdfLength, OdfLength, OdfLength, OdfLength, string?)

Short overload of SetImageLayout that accepts x, y, width, height, and name; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 x、y、width、height 與 name；其餘可選參數使用預設值並轉呼叫最長 SetImageLayout 多載。

public void SetImageLayout(OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? name)

Parameters

x OdfLength
y OdfLength
width OdfLength
height OdfLength
name string

SetImageLayout(OdfLength, OdfLength, OdfLength, OdfLength, string?, string?)

Short overload of SetImageLayout that accepts x, y, width, height, name, and title; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 x、y、width、height、name 與 title；其餘可選參數使用預設值並轉呼叫最長 SetImageLayout 多載。

public void SetImageLayout(OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? name, string? title)

Parameters

x OdfLength
y OdfLength
width OdfLength
height OdfLength
name string
title string

SetImageLayout(OdfLength, OdfLength, OdfLength, OdfLength, string?, string?, string?)

Sets the layout and alternative text of the main image frame. 設定主要影像框架的版面與替代文字。

public void SetImageLayout(OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? name, string? title, string? description)

Parameters

x OdfLength

The X-axis position. / X 軸座標位置。

y OdfLength

The Y-axis position. / Y 軸座標位置。

width OdfLength

The frame width. / 框架寬度。

height OdfLength

The frame height. / 框架高度。

name string

The optional frame name. / 選用的框架名稱。

title string

The optional frame title. / 選用的框架標題。

description string

The optional frame description. / 選用的框架描述。

SetImageRotation(string, double?)

Sets the rotation angle of the image frame with the specified name. 設定指定名稱影像框架的旋轉角度。

public bool SetImageRotation(string name, double? degrees)

Parameters

name string

The frame name. / 框架名稱。

degrees double?

The rotation angle in degrees; null removes the rotation setting. / 旋轉角度（度）；null 表示移除旋轉設定。

Returns

bool

true if set successfully; false if the frame is not found. / 若成功設定則為 true；找不到框架時為 false。

SetImageRotations(IEnumerable<string>, double?)

Batch-sets the rotation angle for image frames. 批次設定影像框架的旋轉角度。

public OdfImageBatchUpdateResult SetImageRotations(IEnumerable<string> names, double? degrees)

Parameters

names IEnumerable<string>

The frame names. / 框架名稱清單。

degrees double?

The rotation angle in degrees; null removes rotation. / 旋轉角度（度）；null 表示移除旋轉設定。

Returns

OdfImageBatchUpdateResult

The batch update result. / 批次更新結果。

Exceptions

ArgumentNullException

When names is null. / 當 names 為 null 時擲出。

TryGetImageFrame(string)

Finds an image frame summary by name. 依名稱尋找影像框架摘要。

public OdfImageFrameInfo? TryGetImageFrame(string name)

Parameters

name string

The frame name (draw:name). / 框架名稱（draw:name）。

Returns

OdfImageFrameInfo

The matching frame summary, or null if not found. / 符合名稱的框架摘要；找不到時為 null。

UpdateImageFrame(string, OdfLength, OdfLength, OdfLength, OdfLength)

Short overload of UpdateImageFrame that accepts name, x, y, width, and height; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 name、x、y、width 與 height；其餘可選參數使用預設值並轉呼叫最長 UpdateImageFrame 多載。

public bool UpdateImageFrame(string name, OdfLength x, OdfLength y, OdfLength width, OdfLength height)

Parameters

name string
x OdfLength
y OdfLength
width OdfLength
height OdfLength

Returns

bool

UpdateImageFrame(string, OdfLength, OdfLength, OdfLength, OdfLength, string?)

Short overload of UpdateImageFrame that accepts name, x, y, width, height, and title; remaining optional parameters use defaults and forward to the full overload. 便利多載：提供 name、x、y、width、height 與 title；其餘可選參數使用預設值並轉呼叫最長 UpdateImageFrame 多載。

public bool UpdateImageFrame(string name, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? title)

Parameters

name string
x OdfLength
y OdfLength
width OdfLength
height OdfLength
title string

Returns

bool

UpdateImageFrame(string, OdfLength, OdfLength, OdfLength, OdfLength, string?, string?)

Updates the layout and metadata of the image frame with the specified name. 更新指定名稱影像框架的版面與中繼資料。

public bool UpdateImageFrame(string name, OdfLength x, OdfLength y, OdfLength width, OdfLength height, string? title, string? description)

Parameters

name string

The frame name. / 框架名稱。

x OdfLength

The X-axis position. / X 軸座標位置。

y OdfLength

The Y-axis position. / Y 軸座標位置。

width OdfLength

The frame width. / 框架寬度。

height OdfLength

The frame height. / 框架高度。

title string

The optional frame title. / 選用的框架標題。

description string

The optional frame description. / 選用的框架描述。

Returns

bool

true if updated successfully; false if the frame is not found. / 若成功更新則為 true；找不到框架時為 false。