Расширение экспорта Office PDF

2025-02-05

Сводка: Создайте надстройку COM для приложений Office 2024 Office LTSC 2024 и Microsoft 365 версии 2408 и более поздних версий с собственной логикой экспорта в формат PDF. Описанный метод требует знания C++ и COM.

Применимо к: Excel, OneNote, PowerPoint, Publisher, Visio и Word в Office 2024, Office LTSC 2024, Microsoft 365 версии 2408 и более поздних.

Общие сведения о функции экспорта Fixed-Format Office (2024)

В этой статье объясняется, как сторонние разработчики программного обеспечения могут подключиться к функции экспорта фиксированного формата, доступной в приложениях Office 2024, Office LTSC 2024, Microsoft 365 версии 2408 и более поздних версий, чтобы добавить собственный экспортер.

Приложения включают встроенные средства экспорта для спецификации бумаги Microsoft XML (XPS) и переносимого формата документов (PDF). Форматы фиксированных файлов предоставляют содержимое документа в форме с разбивкой на страницы, которая не зависит от приложений и платформы.

Разработчики программного обеспечения могут добавить собственный экспорт, написав надстройку Office, которая реализует COM-интерфейс IMsoDocExporter . В этой статье описывается IMsoDocExporter и его взаимодействие с приложением Microsoft 365, например с Word.

Экспорт в фиксированном формате доступен с момента выпуска Office 2007, и в этой статье содержатся сведения о новых возможностях Office 2024, Office LTSC 2024, Microsoft 365 версии 2408.

Важно!
Функция экспорта в фиксированном формате доступна во всех приложениях, перечисленных в предыдущем разделе Применимо к. Однако в приведенном ниже обсуждении в качестве примера приложения используется Publisher, за исключением тех случаев, когда объяснение больше относится к другому приложению.

Функция экспорта в фиксированном формате доступна во всех приложениях, перечисленных в предыдущем разделе Применимо к. Однако в приведенном ниже обсуждении в качестве примера приложения используется Publisher, за исключением тех случаев, когда объяснение больше относится к другому приложению.

Инициализация Add-Ins

Для доступа пользователя к функциям надстройки надстройка должна добавить в приложение новый пункт меню или новую кнопку панели инструментов. Когда пользователь выбирает этот пункт меню или кнопку, надстройка должна использовать объектную модель Microsoft Office для получения указателя на активный документ. Затем он должен вызвать метод ExportAsFixedFormat активного документа с указателем интерфейса IUnknown , поддерживающим интерфейс IMsoDocExporter , путем вызова метода QueryInterface . Параметр объектной модели для указателя интерфейса — это VARIANT с типом VT_UNKNOWN.

Примечание
Для OneNote надстройка вызывает метод Publish со строковым параметром, который является идентификатором класса реализации интерфейса IMsoDocExporter надстройки. Затем OneNote вызывает CoCreateInstance с идентификатором класса, чтобы получить указатель интерфейса IUnknown из фабрики классов надстройки.

Для OneNote надстройка вызывает метод Publish со строковым параметром, который является идентификатором класса реализации интерфейса IMsoDocExporter надстройки. Затем OneNote вызывает CoCreateInstance с идентификатором класса, чтобы получить указатель интерфейса IUnknown из фабрики классов надстройки.

После того как Publisher имеет указатель на интерфейс IMsoDocExporter , он вызывает надстройку обратно через методы, предоставляемые IMsoDocExporter. С помощью этих обратных вызовов Word предоставляет надстройке содержимое документа и другие сведения о документе.

Отличным источником информации о создании надстроек COM для приложений Microsoft Office является codeproject.com статья Создание надстройки COM Office2K с помощью VC++/ATL.

IMsoDocExporter

Интерфейс IMsoDocExporter предоставляет следующие методы.

Таблица 1. Методы, предоставляемые интерфейсом IMsoDocExporter

Метод	Описание
HrCreateDoc	Вызывается в начале процесса экспорта фиксированного формата.
HrAddPageFromEmf	Вызывается для передачи надстройке расширенного метафайла (EMF), представляющего отображаемое представление экспортированного содержимого.
HrAddDocumentMetadataString	Вызывается для указания метаданных в формате строки для документа.
HrAddDocumentMetadataDate	Вызывается для указания метаданных формата даты для документа.
HrSetDefaultLcid	Вызывается для указания идентификатора языкового стандарта по умолчанию (LCID) для экспортируемого содержимого.
HrAddOutlineNode	Вызывается для указания перемещаемых пользователем сведений о структуре документа.
HrGetPageBreaks	Вызывается для получения сведений о разбиении на страницы из надстройки.
HrSetPageHeightForPagination	Вызывается для указания высоты страницы, чтобы разрешить надстройке разложить документ на страницы.
HrFinalize	Вызывается в конце процесса экспорта фиксированного формата. Позволяет надстройке выполнять любую окончательную обработку.
HrBeginStructNode	Вызывается для передачи надстройки начальной структуры для узла структуры документа, охватывающего несколько страниц.
HrEndStructNode	Вызывается для передачи надстройки конечной структуры для узла структуры документа, охватывающего несколько страниц.
EnableCancel	Вызывается для передачи надстройки указателя на интерфейс IDocExCancel .
GetOutputOption	Вызывается для получения параметров вывода фиксированного формата.
SetOutputOption	Вызывается Office для задания параметров вывода фиксированного формата.
SetDocExporterSite	Вызывается для предоставления надстройке указателя на интерфейс IMsoDocExporterSite для расширенной поддержки цвета.

Кроме того, IMsoDocExporter также предоставляет следующие методы, унаследованные от интерфейса IUnknown .

Табл. 2. Методы, наследуемые от интерфейса IUnknown

Метод	Описание
AddRef	Увеличивает счетчик ссылок.
QueryInterface	Возвращает указатели на поддерживаемые интерфейсы. Реализация надстройки QueryInterface должна поддерживать возврат указателя интерфейса IMsoDocExporter из IID_IMsoPdfWriter.
Выпуск	Уменьшает счетчик ссылок.

Сведения о реализации методов интерфейса IUnknown см. в разделе IUnknown (COM).

Поток вызовов

На следующей схеме показана последовательность, в которой Publisher вызывает методы, предоставляемые в IMsoDocExporter. Не все методы используются каждым приложением Microsoft Office и не все методы используются для каждого экспортированного документа.

Рис. 1. Вызов методов из интерфейса IMsoDocExporter

Вызов методов из интерфейса IMsoDocExporter

В следующих разделах описаны методы, предоставляемые интерфейсом IMsoDocExporter . Методы описываются примерно в том порядке, в котором они будут вызываться издателем.

GetOutputOption и SetOutputOption

Издатель вызывает методы GetOutputOption и SetOutputOption для получения и задания параметров вывода для процесса экспорта фиксированного формата.

void GetOutputOption(
    MSODOCEXOPTION docexoption, 
    DWORD* pdwVal 
);
void SetOutputOption(
    MSODOCEXOPTION docexoption, 
    DWORD dwVal 
);

Параметр docexoption указывает выходной параметр, а параметр (p)dwVal — значение параметра .

Хотя встроенный экспортер в Office использует GetOutputOption и SetOutputOption, надстройка может реализовать собственный метод получения и настройки параметров, а также собственный пользовательский интерфейс для параметров.

Microsoft Office вызывает getOutputOption только с помощью msodocexOptionTargetDPIColor для Fixed-Format Add-Ins

Для реализации экспорта в фиксированном формате в Office Издатель вызывает метод GetOutputOption , чтобы получить параметры вывода для отображения пользователю в диалоговом окне Публикация в формате PDF или XPS . Для надстроек, разработанных сторонними разработчиками программного обеспечения, Издатель вызывает GetOutputOption только со значением msodocexOptionTargetDPIColor. Это единственное значение, которое необходимо поддерживать надстройке. Если реализация надстройки GetOutputOption вызывается с этим значением, она должна возвращать целевые точки на дюйм (DPI) для растеризации трехмерного эффекта.

Вызовы Microsoft Office SetOutputOption для надстроек Fixed-Format

Для реализации экспорта фиксированного формата в Office и для реализации надстроек Издатель вызывает SetOutputOption в начале процесса экспорта фиксированного формата. В реализации в Office значения параметров, переданные в, указывают параметры вывода фиксированного формата. Однако если надстройка реализует собственный набор параметров, надстройка может игнорировать параметры, переданные ей издателем.

EnableCancel

Publisher вызывает метод EnableCancel , чтобы передать надстройке указатель на интерфейс IMsoDocExCancel . Надстройка может использовать этот интерфейс для запроса, решит ли пользователь отменить длинную операцию экспорта документов.

void EnableCancel(
    IMsoDocExCancel* pdec
);

HrBeginStructNode

Издатель вызывает метод HrBeginStructNode , чтобы указать начало узла структуры документа для содержимого, охватывающего несколько полных страниц документа. Узлы структуры документа для элементов документа, которые полностью находятся на странице (например, абзацы), внедряются издателем в сам расширенный метафайл (EMF), используя структуры DocExComment_BeginStructNode и DocExComment_EndStructNode . Дополнительные сведения об узлах структуры документов см. в разделах HrAddPageFromEmf и DocExComment_BeginStructNode этой статьи.

HRESULT HrBeginStructNode(
    int idNodeParent, 
    int iSortOrder, 
    const MSODOCEXSTRUCTNODE* pnode, 
    BOOL fNoEndNode
);

Параметр idNodeParent указывает идентификатор узла, который является родительским для узла, передаваемого надстройке. Если этот параметр равен 0, узел находится под корнем дерева структуры документа. Под корнем может находиться несколько одноуровневых узлов. Если этот параметр имеет значение -1, узел находится под открытым в данный момент узлом, то есть под последним узлом, указанным hrBeginStructNode , который не был закрыт вызовом HrEndStructNode.

Параметр iSortOrder задает порядок сортировки узла структуры среди его одноуровневых элементов. Два узла не могут иметь одинаковый порядок сортировки. Однако набор целых чисел, составляющих порядок сортировки, не обязательно должен быть смежным. Значение -1 указывает, что порядок сортировки одноуровневого элемента совпадает с порядком, в котором узлы отображаются в комментариях EMF.

Параметр pnode указывает на структуру MSODOCEXSTRUCTNODE , которая имеет следующее объявление:

typedef struct _MsoDocexStructNode
{
    int idNode;
    MSODOCEXSTRUCTTYPE nodetype;
    WCHAR* pwchAltText;
    union
    {
        int iHeadingLevel;
        ULONG idPara;
        ULONG idDropCap;
        int iPage;
        WCHAR* pwchActualText;
        MSODOCEXLINEBREAKTYPE bt;
        int iListLevel;
        MSODOCEXLISTTYPE listType;
        ULONG idAtn;
        long cpLim;
        int shapeProperty;
        MsoDocexTableAttr tableAttr;
        long cpNoteRef;
        WCHAR* idTableHeader;
        long cpXchAtnMainDod;
        int iTargetParentId;
        WCHAR* wzMathMlText;
        MsoDocexListAttr* pListAttr;
    };
} MSODOCEXSTRUCTNODE;

Элемент idNode указывает идентификатор узла, передаваемого в вызове HrBeginStructNode. Этот элемент может не иметь значение 0. Значение -1 указывает, что дочерние узлы не используют параметр idNodeParent для указания этого узла в качестве родительского узла. Вместо этого этот узел может быть родительским, только заключив дочерние узлы в EMF. Несколько узлов могут иметь идентификатор -1. Если идентификатор не равен -1, значение является уникальным в документе.

Внедренное объединение в конце MSODOCEXSTRUCTNODE интерпретируется по-разному в зависимости от типа узла:

iHeadingLevel — это уровень заголовка для msodocexStructTypeTypeHeading.
idPara — это идентификатор абзаца для P, TOCI или ListBody.
idDropCap — это идентификатор msodocexStructTypeDropCap.
iPage — это номер страницы для msodocexStructTypePage.
bt — это тип разрыва строки для msodocexStructTypeTextLine.
iListLevel — это уровень списка для msodocexStructTypeList или msodocexStructTypeListItem.
listType — это тип списка для msodocexStructTypeTypeListItem.
idAtn — это идентификатор msodocexStructTypeAnnotationBegin или msodocexStructTypeAnnotationEnd.
cpLim используется для определения порядка вложенности таблиц в таблицах для msodocexStructTypeTable, msodocexStructTypeTOC или msodocexStructTypeListBody.
shapeProperty предназначен для msodocexStructTypeFigure, где содержимое представляет собой фигуру, текстовое поле или ячейку таблицы и содержит битовые поля из перечисления MSODOCEXSHAPEPROPERTY.
tableAttr — это атрибуты ячейки таблицы для msodocexStructTypeTH или msodocexStructTypeTD.
cpNoteRef используется для связывания msodocexStructTypeIntLinkNoteRef с msodocexStructTypeFootnote/msodocexStructTypeEndnote. Более подробно это описано далее в этом разделе.
idTableHeader — это уникальный идентификатор msodocexStructTypeTH или msodocexStructTypeTD.
cpXchAtnMainDod используется для связывания msodocexStructTypeCommentAnchor с msodocexStructTypeAnnot. Более подробно это описано далее в этом разделе.
iTargetParentId — это идентификатор узла, в который повторно выполняется msodocexStructTypeDiagram.
wzMathMlText — это строка MathML для msodocexStructTypeEquation.
pListAttr — это атрибуты списка для msodocexStructTypeList.

Примечание. cpNoteRef, cpXchAtnMainDod, wzMathMlText и pListAttr доступны при Word. Метод Document.ExportAsFixedFormat3 вызывается с параметром ImproveExportTagging = true. Минимальная требуемая версия — Microsoft 365 Beta Channel 16.0.18720.20000.

Табл. 3. Перечисляемые значения MSODOCEXLINEBREAKTYPE

Значение	Описание
msodocexLineBreakTypeNormal	Обычный разрыв строки.
msodocexLineBreakTypeManual	Разрыв строки вручную.
msodocexLineBreakTypeEOP	Конец абзаца.

Табл. 4. Перечисляемые значения MSODOCEXLISTTYPE

Значение	Описание
msodocexListTypeNone	Без маркеров или нумеров.
msodocexListTypeBulletDisc	Маркеры в форме диска.
msodocexListTypeBulletCircle	Кругообразные маркеры.
msodocexListTypeBulletSquare	Пули квадратной формы.
msodocexListTypeBulletDecimal	Десятичная нумеровка.
msodocexListTypeUpperRoman	Прописная римская нумераторная нумеровка.
msodocexListTypeLowerRoman	Строчная римская нумеровка.
msodocexListTypeUpperAlpha	Прописная нумеровка по алфавиту.
msodocexListTypeLowerAlpha	Нумеровка в алфавитном формате в нижнем регистре.

Табл. 5. Перечисляемые значения битовых полей MSODOCEXSHAPEPROPERTY

Значение	Числовое значение	Описание
msodocexShape	0x00000001	Объект является фигурой или текстовым полем.
msodocexShapeText	0x00000002	Объект содержит текст, отличный от пробелов.
msodocexShapePath	0x00000004	Объект имеет заливку и (или) структуру.
msodocexShapeAltText	0x00000008	Объект имеет замещающий текст.
msodocexShapeEquation	0x00000010	Объект содержит текст, содержащий уравнение.
msodocexShapeTabelCell	0x00000020	Объект является ячейкой в таблице.

MsoDocexTableAttr

Структура MsoDocexTableAttr помещается в 32 бита и включает в себя диапазон строк и столбцов, а также заголовок область сведения для ячейки таблицы.

struct MsoDocexTableAttr
{
    static constexpr unsigned int MaxSpanBits = sizeof(unsigned int) * 8 / 2 - 1;
    static constexpr unsigned int MaxSpanValue = (1u << MaxSpanBits) - 1;

    unsigned int rowSpan : MaxSpanBits;
    unsigned int fRowScope : 1;
    unsigned int colSpan : MaxSpanBits;
    unsigned int fColScope : 1;
};

Ниже перечислены члены структуры MsoDocexTableAttr :

MaxSpanBits Указывает количество битов, доступных для значений rowSpan и colSpan, равное 15.
MaxSpanValue Указывает максимальное значение, которое можно указать для rowSpan и colSpan.
rowSpan Указывает количество строк, охватываемых ячейкой таблицы.
fRowScope Указывает, является ли заголовок строкой или столбцом.
colSpan Указывает количество столбцов, охватываемых ячейкой таблицы.
fColScope Указывает, является ли заголовок столбцом или строкой.

MsoDocexListAttr

Структура MsoDocexListAttr содержит сведения для списка.

struct MsoDocexListAttr
{
    int iListLevel;
    long cpLim;
};

Ниже перечислены члены структуры MsoDocexListAttr :

iListLevel Задает порядок вложенности списка.
cpLim Указывает позицию в документе, где заканчивается список.

Советы по постобработки

В некоторых случаях узлы должны быть обработаны после достижения желаемых результатов.

Постобработка сносок и концевых сносок

Во время экспорта ссылки на сноски и концевые сноски будут помечены как msodocexStructTypeIntLinkNoteRef. Тексты сносок и концевых сносок будут помечены как msodocexStructTypeFootnote и msodocexStructTypeEndnote соответственно, и они всегда будут узлами верхнего уровня в узле msodocexStructTypeDocument. Узел msodocexStructTypeIntLinkNoteRef и соответствующий узел msodocexStructTypeFootnote/msodocexStructTypeEndnote будут иметь одно и то же значение cpNoteRef. Его можно использовать для перемещения узлов сносок и концевых сносок под соответствующими узлами связи для поддержания логического порядка чтения.

Постобработка комментариев

Во время экспорта каждая привязка комментария будет помечена как msodocexStructTypeCommentAnchor. Тела комментариев будут помечены как msodocexStructTypeAnnot, и они всегда будут узлами верхнего уровня в узле msodocexStructTypeDocument. Узел msodocexStructTypeCommentAnchor и соответствующий узел msodocexStructTypeAnnot будут иметь одно и то же значение cpXchAtnMainDod. Его можно использовать для перемещения узлов заметок под соответствующими узлами привязки комментариев для поддержания логического порядка чтения.

Таблицы макета после обработки

Если во время экспорта мы обнаружим, что таблица является таблицей макета, мы помечаем ее как msodocexStructTypeTable, но присвоим cpLim узла значение -2 (наша константа указывает, что это таблица макета). Затем это значение можно использовать для определения того, следует ли повторно помечать узлы таблиц как узлы абзаца.

Узлы, охватывающие страницы постобработки (абзацы, списки, таблицы)

Для абзацев можно проверить значения idPara двух параметров, чтобы определить, представляют ли они один и тот же абзац на разных страницах. Для таблиц значения cpLim можно проверить, не совпадают ли они.

Для списков мы добавили в MsoDocexStructNode новый класс MsoDocexListAttr, который содержит cpLim списка. Это можно использовать для проверка, если два узла списка имеют одинаковый cpLim, что означает, что они оба представляют один и тот же список в документе.

Для узлов структуры таблиц объединение интерпретируется как упорядочение концов таблицы по отношению к другим таблицам с помощью cpLim, который можно использовать для определения порядка вложенности таблиц в таблицах.

В контексте DocExComment_BeginStructNode надстройка может игнорировать член pwchActualText этого объединения.

Элемент pwchAltText задает альтернативный текст для узла структуры.

Параметр fNoEndNode для HrBeginStructNode указывает, вызывает ли издатель метод HrEndStructNode , чтобы пометить конец узла структуры. Если параметр fNoEndNode имеет значение false, издатель вызывает HrEndStructNode , чтобы закрыть содержимое, ограниченное узлом. Если этот параметр имеет значение true , узел не связывает содержимое.

Параметр fNoEndNode влияет на интерпретацию значения родительского идентификатора последующих узлов. Если значение fNoEndNode имеет значение false, узлы, вставляемые между этим вызовом HrBeginStructNode и последующим вызовом HrEndStructNode и имеющие родительский идентификатор -1, являются дочерними для этого узла. Однако если значение fNoEndNode имеет значение true, то узлы, вставленные после этого вызова HrBeginStructNode и имеющие родительский идентификатор -1, не являются дочерними узлами этого узла, а являются дочерними узлами следующего последнего указанного узла с fNoEndNode равным false.

Узлы структуры документа могут быть вложены на произвольную глубину.

Узлы, указанные в HrBeginStructNode , и узлы, указанные DocExComment_BeginStructNode используют одно и то же пространство идентификаторов и существуют в одном дереве структуры документа. HrBeginStructNode и DocExComment_BeginStructNode являются двумя альтернативными способами добавления узлов в это дерево. Например, если последний открытый узел был открыт HrBeginStructNode , а следующий узел обнаружен из DocExComment_BeginStructNode EMFcommentrecord с idNodeParentравным -1, это означает, что узел из HrBeginStructNode является родительским для узла из записи DocExComment_BeginStructNode .

HrEndStructNode

Издатель вызывает метод HrEndStructNode , чтобы указать конец узла структуры документа для содержимого, охватывающего несколько страниц документа. Узел структуры, заканчивающийся hrEndStructNode , был начат ранее вызовом метода HrBeginStructNode . Дополнительные сведения см. в статье HrBeginStructNode.

HRESULT HrEndStructNode();

HrCreateDoc

Издатель вызывает метод HrCreateDoc , чтобы указать создание нового пустого документа фиксированного формата.

HRESULT HrCreateDoc(
    const WCHAR* wzDocExFile
);

Издатель вызывает метод HrCreateDoc в начале процесса экспорта фиксированного формата, чтобы указать создание пустого документа фиксированного формата. Параметр wzDocExFile указывает имя выходного файла, в который записывается документ фиксированного формата.

Для реализации надстройки Publisher вызывает HrCreateDoc с именем файла, указанным надстройкой в вызове метода ExportToFixedFormat в объектной модели Microsoft Office. Тем не менее, поскольку надстройки обычно предоставляют пользовательский интерфейс конфигурации, позволяющий пользователю указать имя выходного файла, надстройка может игнорировать это имя файла во время экспорта.

Для приложений Microsoft Office, которым требуется, чтобы надстройка разбивала документ на страницы, HrCreateDoc вызывается дважды, один раз в начале последовательности вызова разбиения на страницы, а затем после того, как надстройка разбила документ на страницы. Дополнительные сведения см. в описаниях методов HrSetPageHeightForPagination и HrGetPageBreaks.

HrSetDefaultLcid

Издатель вызывает метод HrSetDefaultLcid , чтобы указать идентификатор языкового стандарта по умолчанию (LCID) для экспортированного содержимого.

HRESULT HrSetDefaultLcid(
    DWORD lcid
);

Список допустимых идентификаторов LCID см. в разделе Список значений кодов языкового стандарта (LCID) как назначенных корпорацией Майкрософт.

HrAddPageFromEmf

Издатель вызывает метод HrAddPageFromEmf , чтобы передать дескриптор надстройки в память EMF, который представляет содержимое в документе для экспорта.

HRESULT HrAddPageFromEmf(
    HENHMETAFILE hemf
);

EMF, передаваемый Microsoft Office в надстройку, является основным источником содержимого, которое надстройка экспортирует в виде файла фиксированного формата. Microsoft Office вызывает HrAddPageFromEmf один раз для каждой страницы содержимого в исходном документе приложения.

Комментарии EMF передают семантические сведения

EMF — это последовательность команд рисования (GDI и GDI+), которые определяют способ отображения визуальных элементов документа. EMF не содержит никаких сведений за пределами этих команд (например, "нарисовать здесь изображение" или "нарисовать там линию"). В частности, обычные EMF не поддерживают семантические аспекты документа, такие как гиперссылки, сведения о языковом стандарте и сведения о специальных возможностях. Чтобы сохранить семантические сведения в экспортируемом документе, Publisher внедряет специальные записи в EMF. Эти записи содержат семантические сведения.

Записи, представляющие семантические сведения, реализуются в виде комментариев EMF в специальном формате. Формат EMF позволяет использовать типы записей комментариев, которые игнорируются обработчиком отрисовки для интерфейса графического устройства (GDI), но могут содержать произвольные сведения.

В качестве примера рассмотрим документ, содержащий альтернативный текст. (Альтернативный текст используется средствами чтения документов для описания изображений для пользователей с нарушениями зрения.) Издатель внедряет примечания EMF до и после отрисовки изображения, и эти примечания EMF указывают альтернативный текст для изображения. Надстройка интерпретирует комментарии и записывает информацию в файл экспорта фиксированного формата.

В следующей таблице показаны типы семантических записей, поддерживаемые функцией экспорта фиксированного формата Microsoft Office. Эти типы перечисляются перечислением MSODOCEXSTRUCTTYPE . Каждый тип соответствует типу структуры, описывающей формат записи.

Табл. 6. Семантические типы записей, поддерживаемые экспортом фиксированного формата

Значение комментария	Тип структуры
msodocexcommentExternalHyperlink	DocExComment_ExternalHyperlink
msodocexcommentExternalHyperlinkRctfv	DocExComment_ExternalHyperlink
msodocexcommentInternalHyperlink	DocExComment_InternalHyperlink
msodocexcommentInternalHyperlinkRctfv	DocExComment_InternalHyperlink
msodocexcommentColorInfo	DocExComment_ColorInfo
msodocexcommentColorMapEnable	DocExComment_ColorEnable
msodocexcommentBeginTextRun	DocExComment_BeginTextRun
msodocexcommentBeginTextRunRTL	DocExComment_BeginTextRun
msodocexcommentEndTextRun	DocExComment_EndTextRun
msodocexcommentBeginStructNode	DocExComment_BeginStructNode
msodocexcommentEndStructNode	DocExComment_EndStructNode
msodocexcommentUnicodeForNextTextOut	DocExComment_UnicodeForNextTextOut
msodocexcommentUnicodeForNextTextOutRTL	DocExComment_UnicodeForNextTextOut
msodocexcommentEPSColor	DocExComment_EPSColor
msodocexcommentEPSCMYKJPEG	DocExComment_EPSColorCMYKJPEG
msodocexcommentEPSSpotImage	DocExComment_EPSColorSpotImage
msodocexcommentEPSStart	DocExComment_EPSStart
msodocexcommentPageName	DocExComment_PageName
msodocexcommentTransparent	DocExComment_Transparent

DocExComment_ExternalHyperlink(Rctfv)

Структура DocExComment_ExternalHyperlink (Rctfv) описывает гиперссылку, которая ссылается на внешний документ, например на веб-сайт в Интернете.

struct DocExComment_ExternalHyperlink
{
    DWORD ident {};
    DWORD iComment {};
    union
    {
        RECT  rcdvRegion;
        struct
        {
            float xLeft;
            float yTop;
            float dxWidth;
            float dyHeight;
        } rctfvRegion;
    };
    WCHAR wzLink[MAX_PATH];
};

Ниже перечислены члены структуры DocExComment_ExternalHyperlink(Rctfv ).

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentExternalHyperlink или msodocexcommentExternalHyperlinkRctfv.
rcdvRegion и rctfvRegion — объединение, указывающее область страницы, которая является исходным расположением гиперссылки. Область может быть представлена как тип RECT (rcdvRegion), в котором пиксели устройства используются в качестве единицы измерения, или как структура, содержащая координаты с плавающей запятой (rctfvRegion), в этом случае единицей измерения являются точки.

Если член iComment равен msodocexcommentExternalHyperlink, надстройка должна использовать rcdvRegion. В этом случае надстройке необходимо применить текущую матрицу преобразования EMF к rcdvRegion , чтобы преобразовать ее в пространство страницы.

Если член iComment равен msodocexcommentExternalHyperlinkRctfv, надстройка должна использовать rctfvRegion. В этом случае rctfvRegion уже находится в пространстве страницы, поэтому преобразование не требуется.
wzLink[MAX_PATH] Указывает URL-адрес назначения для этой гиперссылки.

DocExComment_InternalHyperlink(Rctfv)

Структура DocExComment_InternalHyperlink (Rctfv) описывает гиперссылку, которая ссылается на расположение в документе. Обратите внимание, что, хотя publisher передает отдельный EMF для каждой страницы документа, назначение гиперссылки, указанной в DocExComment_InternalHyperlink(Rctfv), может находиться на странице, отличной от исходного расположения.

struct DocExComment_InternalHyperlink
{
    DWORD ident {};
    DWORD iComment {};
    union
    {
        RECT  rcdvRegion;
        struct
        {
            float xLeft;
            float yTop;
            float dxWidth;
            float dyHeight;
        } rctfvRegion;
    };
    DWORD iTargetPage {};
    float xtfvTarget {};
    float ytfvTarget {};
    float dytfTargetPage {};
};

Ниже перечислены члены структуры DocExComment_InternalHyperlink(Rctfv ):

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentInternalHyperlink или msodocexcommentInternalHyperlinkRctfv.
rcdvRegion и rctfvRegion . Как и в структуре DocExComment_ExternalHyperlink , этот элемент является объединением, указывающим область страницы, которая является исходным расположением гиперссылки. Область может быть представлена как тип RECT (rcdvRegion), в котором пиксели устройства используются в качестве единицы измерения, или как структура, содержащая координаты с плавающей запятой (rctfvRegion), в этом случае единицей измерения являются точки.

Если член iComment равен msodocexcommentInternalHyperlink, надстройка должна использовать rcdvRegion. В этом случае надстройке необходимо применить текущую матрицу преобразования EMF к rcdvRegion , чтобы преобразовать ее в пространство страницы.

Если член iComment равен msodocexcommentInternalHyperlinkRctfv, надстройка должна использовать rctfvRegion. В этом случае rctfvRegion уже находится в пространстве страницы, поэтому преобразование не требуется.
iTargetPage Указывает номер страницы назначения в документе.
xtfvTarget Указывает координату X целевого расположения на целевой странице. Единица измерения для этого значения — точек.
ytfvTarget Указывает координату Y целевого расположения на целевой странице. Единица измерения для этого значения — точек.
dytfTargetPage Высота целевой страницы в точках. Смещение, указанное элементом ytfvTarget , относится к левому верхнему углу страницы. Однако некоторые типы фиксированного формата используют систему координат относительно левого нижнего угла страницы. Для этих типов документов для преобразования смещения требуется высота страницы.

DocExComment_ColorInfo

Структура DocExComment_ColorInfo указывает сведения о состоянии цвета для EMF. Дополнительные сведения об этой структуре см. в разделе Расширенная поддержка цветов.

struct DocExComment_ColorInfo
{
    DWORD ident {};
    DWORD iComment {};
    COLORREF clr { 0 };
    BOOL fForeColor {};
};

Ниже перечислены элементы структуры DocExComment_ColorInfo .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentColorInfo.
среда clr Указывает идентификатор цвета, представляющий текущее состояние цвета в EMF.
fForeColor Указывает, представляет ли идентификатор цвета в элементе clr цвет переднего плана или цвет фона. Если этот элемент имеет значение true, идентификатор цвета представляет цвет переднего плана. Если этот элемент имеет значение false, идентификатор цвета представляет цвет фона.

DocExComment_ColorEnable

Структура DocExComment_ColorEnable указывает, включено ли сопоставление цветов для последующего содержимого в EMF. Дополнительные сведения об этой структуре см. в разделе Расширенная поддержка цветов.

struct DocExComment_ColorEnable
{
    DWORD ident {};
    DWORD iComment {};
    BOOL fEnable {};
};

Ниже перечислены элементы структуры DocExComment_ColorEnable .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentColorMapEnable.
fEnable Указывает, включено ли сопоставление цветов для последующего содержимого. Значение true указывает, что цветовое сопоставление включено. Значение false указывает, что цветовое сопоставление отключено.

DocExComment_BeginStructNode

Структура DocExComment_BeginStructNode помечает начало узла структуры документа. Узлы структуры служат одной из двух возможных целей:

Узлы структуры могут определить тип содержимого, которое они содержат, и указать иерархическую связь между этим содержимым и другим содержимым в документе.
Узлы структуры могут указывать альтернативный текст для элементов в документе.

Если элемент fContentNode имеет значение true , DocExComment_BeginStructNode далее в документе следует DocExComment_EndStructNode. DocExComment_EndStructNode помечает конец содержимого, которое упаковывается в DocExComment_BeginStructNode.

Коллекция узлов структуры в документе образует дерево; Каждый узел имеет родительский узел, а также может иметь одноуровневые узлы. Элементы idNodeParent и iSortOrder описывают структуру этого дерева. Обратите внимание, что дочерний узел может отображаться между DocExComment_BeginStructNode и DocExComment_EndStructNode структурами родительского узла в EMF.

struct DocExComment_BeginStructNode
{
    DWORD ident {};
    DWORD iComment {};
    int idNodeParent {};
    int iSortOrder {};
    MSODOCEXSTRUCTNODE desn;
    BOOL fContentNode {};
    int cwchAltText {};
};

Ниже перечислены элементы структуры DocExComment_BeginStructNode .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentBeginStructNode.
idNodeParent Указывает идентификатор родительского узла. Значение 0 указывает корневой узел. Значение -1 указывает открытый в настоящее время узел структуры, то есть включающий узел структуры.
iSortOrder Задает порядок сортировки узла структуры среди его одноуровневых узлов. Порядок сортировки позволяет надстройке правильно упорядочивать содержимое в экспортируемом документе.

Два узла не могут иметь одинаковый порядок сортировки. Однако набор целых чисел, составляющих порядок сортировки, не обязательно должен быть смежным.

Значение -1 указывает, что одноуровневый порядок совпадает с порядком, в котором узлы отображаются в комментариях EMF. Обратите внимание, что порядок, в котором содержимое отображается в EMF, не обязательно является порядком, в котором содержимое используется пользователем документа.
desn Задает структуру MSODOCEXSTRUCTTYPE , определенную ранее в документе.

Элемент idNode указывает идентификатор узла. Этот элемент может не иметь значение 0. Значение -1 указывает, что дочерние узлы не используют элемент idNodeParent для указания этого узла в качестве родительского узла. Вместо этого этот узел может быть родительским, только заключив дочерние узлы в EMF. Несколько узлов могут иметь идентификатор -1. Если идентификатор не равен -1, значение является уникальным в документе.

Тип узла указывает тип узла структуры. Этот член равен одному из значений типа перечисления MSODOCEXSTRUCTTYPE . В следующей таблице перечислены примеры типов узлов структуры документов.

Табл. 7. Типы узлов структуры документа

Значение типа	Описание
msodocexStructTypePara	Блок текста в статье. Его родительским узлом должна быть статья.
msodocexStructTypeFigure	Графический элемент (например, изображение или коллекция фигур), имеющий текстовое представление. Текстовое представление — это альтернативный текст, используемый для чтения или поиска в документе.
msodocexStructTypeArticle	Группа узлов, образующих единый поток текста, который следует читать или искать в виде непрерывного блока содержимого. В некоторых документах есть одна статья, а в других — несколько.
msodocexStructTypeHeading	Заголовок в тексте.
msodocexStructTypeTable	Блок текста, формируя таблицу.
msodocexStructTypeTR	Блок текста, формируя одну строку таблицы.
msodocexStructTypeTD	Блок текста, образующий одну ячейку в строке таблицы.
msodocexStructTypeTH	Блок текста, образующий одну ячейку заголовка в строке таблицы.
msodocexStructTypeList	Блок текста, формируя список.
msodocexStructTypeListItem	Блок текста, формируя элемент списка.
msodocexStructTypeListBody	Блок текста, формируя текст элемента списка.
msodocexStructTypeDocument	Документ.
msodocexStructTypePage	Страница в документе.
msodocexStructTypeTOC	Оглавление.
msodocexStructTypeTOCI	Элемент в оглавлении.
msodocexStructTypeExtLink	Ссылка на внешний ресурс.
msodocexStructTypeIntLink	Ссылка на внутренний ресурс.
msodocexStructTypeFootnote	Сноска.
msodocexStructTypeEndnote	Концевая сноска.
msodocexStructTypeTextbox	Текстовое поле.
msodocexStructTypeHeader	Блок текста, формируя заголовок.
msodocexStructTypeFooter	Нижний колонтитул.
msodocexStructInlineShape	Встроенная фигура.
msodocexStructAnnotation	Заметка.
msodocexStructTypeSpanBlock	Блок текста.
msodocexStructTypeWorkbook	Книга.
msodocexStructTypeWorksheet	Лист.
msodocexStructTypeMacrosheet	Таблица макросов.
msodocexStructTypeChartsheet	Таблица диаграмм.
msodocexStructTypeDialogsheet	Диалоговое окно.
msodocexStructTypeSlide	Слайд.
msodocexStructTypeChart	Диаграмма.
msodocexStructTypeDiagram	Схема SmartArt.
msodocexStructTypeBulletText	Текст Буллера.
msodocexStructTypeTextLine	Строка текста.
msodocexStructTypeDropCap	Крышка капли.
msodocexStructTypeSection	Раздел.
msodocexStructTypeAnnotationBegin	Начало заметки.
msodocexStructTypeAnnotationEnd	Конец заметки.
msodocexStructTypeParaRTLAttr	Блок текста в статье с макетом справа налево.
msodocexStructTypeTableRTLAttr	Блок текста, формируя таблицу с макетом справа налево.
msodocexStructTypeHeadingRTLAttr	Заголовок в тексте с макетом справа налево.
msodocexStructTypeListItemRTLAttr	Блок текста, формируя элемент списка с макетом справа налево.
msodocexStructTypeParaUnannotatableAttr	Блок текста в статье, который не можно примечать.
msodocexStructTypeTHead	Область строки заголовка в таблице.
msodocexStructTypeTBody	Область тела в таблице, т. е. часть между THead и TFoot.
msodocexStructTypeLabel	Метка.
msodocexStructTypeEquation	Уравнение.
msodocexStructTypeIntLinkNoteRef	Ссылка на ссылочный знак сноски или концевая сноска.
msodocexStructTypeTFoot	Область строки нижнего колонтитула в таблице.
msodocexStructTypeTitle	Заголовок в тексте.
msodocexStructTypeBlockQuote	Цитата абзаца или интенсивные кавычки.
msodocexStructTypeCommentAnchor	Некоторый текст, связанный с комментарием.
msodocexStructTypeAnnot	Содержимое одного комментария.
msodocexStructTypeQuote	Встроенная цитата.
msodocexStructTypeCaption	подпись для уравнения, рисунка или таблицы.

Примечание. msodocexStructTypeTitle, msodocexStructTypeBlockQuote, msodocexStructTypeCommentAnchor, msodocexStructTypeAnnot, msodocexStructTypeQuote и msodocexStructTypeCaption доступны при Word. Метод Document.ExportAsFixedFormat3 вызывается с параметром ImproveExportTagging = true. Минимальная требуемая версия — Microsoft 365 Beta Channel 16.0.18720.20000.

fContentNode Указывает, помечает ли DocExComment_EndStructNode структура конец этого узла структуры. Если fContentNode имеет значение true, структура DocExComment_EndStructNode закрывает содержимое, ограниченное узлом. Если этот fContentNode имеет значение false , узел не связывает содержимое.

Элемент fContentNode влияет на интерпретацию значения родительского идентификатора последующих узлов. Если параметр fContentNodeимеет значение true, узлы, которые вставляются между этим DocExComment_BeginStructNode и последующим DocExComment_EndStructNode и имеют родительский идентификатор -1, являются дочерними для этого узла. Однако если fContentNode имеет значение true, узлы, вставленные после этого DocExComment_BeginStructNode и имеющие родительский идентификатор -1, не являются дочерними узлами этого узла. Они являются дочерними элементами следующего последнего указанного узла с fContentNode , равным false.

Узлы структуры документа можно вложить на произвольную глубину.

cwchAltText Указывает количество символов Юникода в блоке альтернативного текста, следующего за структурой. Эта строка Юникода задает альтернативный текст для узла (например, альтернативный текст для изображения).

DocExComment_EndStructNode

Структура DocExComment_EndStructNode помечает конец содержимого, которое украшается информацией в DocExComment_BeginStructNode.

struct DocExComment_EndStructNode
{
    DWORD ident {};
    DWORD iComment {};
};

Ниже перечислены члены структуры DocExComment_EndStructNode .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentEndStructNode.

DocExComment_BeginTextRun

Структура DocExComment_BeginTextRun определяет язык последовательности текста в документе и предоставляет кодовые точки Юникода для текста.

Хотя некоторые записи EMF, отрисовывающие текст, используют Юникод в качестве текстового представления, другие используют глифы, нарисованные на экране, а не исходный текст. Глиф — это индекс заданной фигуры в шрифте, который может отличаться от шрифта к шрифту.

Могут быть случаи, когда несколько кодовых точек Юникода объединяются в один глиф или одна кодовая точка Юникода разбивается на несколько глифов. Так как сопоставление от кодовых точек к глифам зависит от контекста, пользователь не может выполнять поиск текста или копировать или вставлять в документ, содержащий только глифы. Поэтому иногда publisher предоставляет текст Юникода, а также глифы.

struct DocExComment_BeginTextRun
{
    DWORD ident {};
    DWORD iComment {};
    DWORD lcid {};
    int cGlyphIndex {};
    int cwchActualText {};
};

Ниже перечислены члены структуры DocExComment_BeginTextRun .

Идентификатор Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentBeginTextRun.
lcid Указывает LCID для текстовой последовательности.
cGlyphIndex Задает размер массива, следующего за этой структурой. Этот массив реализует таблицу индексов глифов, которая сопоставляет кодовые точки Юникода в фактическом тексте с соответствующими глифами в EMF. Каждый элемент массива соответствует кодовой точке в тексте. Значение этого элемента указывает первый глиф, используемый для отрисовки этой кодовой точки в EMF. Две или более смежных кодовых точек могут иметь одно и то же значение в массиве, что означает, что они оба разрешаются в один и тот же глиф. Значение также может быть равным 0, что означает, что эта кодовая точка не сопоставляется ни с каким глифом.
cwchActualText Задает размер последовательности кодовых точек Юникода, следующих за таблицей индексов глифов. Это текст, который потребитель документа может использовать для поиска, копирования и вставки, а также для специальных возможностей. Значение этого элемента может быть равно 0, что означает, что текст Юникода не предоставляется.

DocExComment_EndTextRun

Структура DocExComment_EndTextRun помечает конец текстовой последовательности, начало которой отмечено DocExComment_BeginTextRun структурой.

struct DocExComment_EndTextRun
{
    DWORD ident {};
    DWORD iComment {};
};

Ниже перечислены элементы структуры DocExComment_EndTextRun :

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentEndTextRun.

DocExComment_UnicodeForNextTextOut

Структура DocExComment_UnicodeForNextTextOut функционирует аналогично структурам DocExComment_BeginTextRun и DocExComment_EndTextRun . Однако DocExComment_UnicodeForNextTextOut указывает кодовые точки Юникода только для следующей записи EMF TextOut, а не для блока содержимого EMF, ограниченного начальными и конечными структурами.

struct DocExComment_UnicodeForNextTextOut
{
    DWORD ident {};
    DWORD iComment {};
    int cGlyphIndex {};
    int cwchActualText {};
};

Ниже перечислены элементы структуры DocExComment_UnicodeForNextTextOut .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentUnicodeForNextTextOut.
cGlyphIndex Задает размер массива, следующего за этой структурой. Этот массив реализует таблицу индексов глифов, которая сопоставляет кодовые точки Юникода в фактическом тексте с соответствующими глифами в EMF. Каждый элемент массива соответствует кодовой точке в тексте. Значение этого элемента указывает первый глиф, используемый для отрисовки этой кодовой точки в EMF. Две или более смежных кодовых точек могут иметь одно и то же значение в массиве, что означает, что они оба разрешаются в один и тот же глиф.
cwchActualText Задает размер последовательности кодовых точек Юникода, следующих за таблицей индексов глифов. Это текст, который потребитель документа может использовать для поиска, копирования и вставки, а также для специальных возможностей.

DocExComment_EPSColor

Структура DocExComment_EPSColor задает сведения о цвете для инкапсулированного файла PostScript (EPS), внедренного в EMF. Дополнительные сведения об этой структуре см. в разделе Расширенная поддержка цветов.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
    BYTE colorInfo[];
} DocExComment_EPSColor;

Ниже перечислены члены структуры DocExComment_EPSColor .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentEPSColor.
colorInfo[] Задает сведения о цвете файла EPS. Надстройка должна передать эти сведения издателю с помощью метода IMsoDocExporterSite::SetEPSInfo .

DocExComment_EPSColorCMYKJPEG

Структура DocExComment_EPSColorCMYKJPEG указывает начало в EMF двоичного объекта, который является потоком файлов CMYKJPEG. Дополнительные сведения об этой структуре см. в разделе Расширенная поддержка цветов.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
} DocExComment_EPSColorCMYKJPEG;

Ниже перечислены элементы структуры DocExComment_EPSColorCMYKJPEG .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Указывает значение MSODOCEXCOMMENT, msodocexcommentEPSCMYKJPEG;

DocExComment_EPSColorSpotImage

Структура DocExComment_EPSColorSpotImage предоставляет информацию о плашечном цвете для последующего изображения RGB. Дополнительные сведения об этой структуре см. в разделе Расширенная поддержка цветов.

typedef struct
{
    DWORD ident {};
    DWORD iComment {};
    COLORREF cmykAlt { 0 };
    COLORREF rgbAlt { 0 };
    float flTintMin {};
    float flTintMax {};
    char szSpotName[1];
} DocExComment_EPSColorSpotImage;

Ниже перечислены элементы структуры DocExComment_EPSColorSpotImage .

ident Задает значение константы msodocexsignature, которое определяет этот комментарий EMF как содержащий семантические сведения.
iComment Задает значение MSODOCEXCOMMENT, msodocexcommentEPSSpotImage.
cmykAlt Указывает идентификатор цвета CMYK.
rgbAlt Указывает идентификатор цвета RGB.
flTintMin Задает минимальный оттенок.
flTintMax Задает максимальный оттенок.
szSpotName[1] Указывает переменную длины, строку с отсчитываемой от нуля, которая содержит имя точки.

Расширенная поддержка цветов

Для поддержки расширенных цветовых пространств в Publisher требуются дополнительные семантические записи и интерфейсы EMF, так как EMF поддерживает только цвета RGB (красно-зеленый-черный). Расширенные цветовые пространства включают CMYK (голубо-пурпурный-желто-черный) и плашечное цветовое пространство, которые обычно используются в коммерческой печати.

Издатель использует сопоставление цветов для представления расширенных цветов в документе EMF. Издатель создает таблицу цветов для всех цветов, используемых в документе, и заменяет фактические цвета идентификаторами цветов в EMF. Тип для идентификатора цвета — COLORREF, который является тем же типом, который используется для цвета RGB. Сведения о структуре COLORREF см. в разделе COLORREF.

Чтобы разрешить идентификаторы цветов в EMF обратно в расширение цветового пространства, надстройка вызывает издателю с помощью метода HrResolveColor интерфейса IMsoDocExporterSite . Надстройка передает publisher указатель интерфейса на интерфейс IDOCEXCOLOR в качестве одного из параметров в HrResolveColor. Издатель принимает идентификаторы цветов, также указанные в вызове HrResolveColor, преобразует их в расширенный цвет (RGB, CMYK или плашечное цвет) и передает их обратно в надстройку с помощью методов в интерфейсе IDOCEXCOLOR .

Цвет векторов и перекрашенные изображения

Цвета векторов — это любые значения COLORREF , которые надстройка получает от издателя. Например, цвет текста, цвет штриха линии и цвет для перекраски метафайла. Если сопоставление цветов включено, издатель использует идентификатор цвета для COLORREF , а не реальное значение цвета RGB. Если Publisher предоставляет надстройке указатель интерфейса IMsoDocExporterSite путем вызова метода SetDocExporterSite интерфейса IMsoDocExporter, надстройка всегда должна вызывать метод IMsoDocExporterSite::HrResolveColor для преобразования COLORREF в расширенный цвет, который надстройка получает с помощью методов в интерфейсе IDOCEXCOLOR .

Для поддержки цветового сопоставления векторов надстройка должна выполнить следующие действия:

Реализуйте поддержку классов для интерфейса IDOCEXCOLOR . Методы в этом интерфейсе позволяют publisher передавать расширенный цвет обратно надстройке.
Кэшируйте следующие значения состояния цвета из семантических записей в EMF.
Задайте цвет переднего плана для перекраски. Это задается с помощью структуры DocExComment_ColorInfo .
Задайте цвет фона для перекраски. Это задается с помощью структуры DocExComment_ColorInfo .
Определите, включено ли сопоставление цветов. Это задается с помощью структуры DocExComment_ColorEnable .
Для цвета вектора создайте интерфейс IDOCEXCOLOR с идентификатором цвета, чтобы IDOCEXCOLOR::GetUnresolvedRGB возвращал идентификатор цвета. Надстройка должна вызывать метод IMsoDocExporterSite::HrResolveColor с интерфейсом IDOCEXCOLOR и кэшированными состояниями цвета. Издатель вызывает методы интерфейса IDOCEXCOLOR с окончательным цветом, который может быть RGB, CMYK, точечный или регистрационный оттенок.
Если цвет переднего плана или цвет фона для перекраски указан из семантической записи EMF, надстройка должна перекрасить изображения в надстройке (например, метафайлы или растровые изображения).

Неперекрашенные изображения

EMF поддерживает образы CMYK с помощью GDI+. Поэтому изображения в EMF могут быть либо RGB, либо CMYK. Если изображение является изображением CMYK, надстройке необходимо преобразовать изображение в целевое цветовое пространство.

Издатель поддерживает целевое цветовое пространство для документа. Надстройка может использовать это целевое цветовое пространство, вызвав метод IMsoDocExporterSite::HrConvertImageColorSpace с цветовым пространством изображения.

Цвет из EPS-файлов

Инкапсулированный postscript (EPS) — это тип метафайла, поддерживающий расширенные цветовые пространства. Пользователь, внедряющий изображения EPS в документ издателя, ожидает, что информация о цвете будет использоваться в выходных данных фиксированного формата. Внутри Publisher EPS преобразуется в EMF с семантическими записями, связанными с EPS. Затем этот EMF встраивается в файл EMF страницы, который приложение передает в надстройку.

Для поддержки цвета в EPS-файлах надстройке необходимо выполнить следующие действия:

Вызовите метод IMsoDocExporterSite::SetEPSInfo для DocExComment_EPSColor записей, встречающихся в EMF.
Извлеките образ CMYK из записи DocExComment_EPSColorCMYKJPEG в EMF. Эта запись содержит двоичный объект, который является фактическим потоком файлов CMYK JPEG. Используйте его для замены RGB-изображения, указанного в последующем вызове функции StretchDIBits .
Запись DocExComment_EPSColorSpotImage предоставляет сведения о плашечном цвете для последующего изображения RGB, которое всегда является индексным изображением. Надстройка должна преобразовать плашечное изображение в целевое цветовое пространство.
При необходимости надстройка может вызвать метод IMsoDocExporterSite:: HrGetSpotRecolorInfo , чтобы получить целевой цвет документа от издателя. Затем надстройка может перекрасить последующее изображение RGB, сопоставив цвета из палитры изображения RGB с оттенками flTintMin и flTintMax , указанными в записи DoxExComment_EPSColorSpotImage . Яркость для каждого цвета палитры используется для сопоставления.

Обратите внимание, что DocExComment_EPSStart запись является только информационной. Надстройка может игнорировать эту запись.

SetDocExporterSite

Publisher вызывает SetDocExporterSite , чтобы предоставить надстройке указатель на интерфейс IMsoDocExporterSite . Интерфейс IMsoDocExporterSite предоставляет методы, которые обеспечивают расширенную поддержку цвета.

void SetDocExporterSite(
    IMsoDocExporterSite* pDocExporterSite
);

Параметр pDocExporterSite указывает указатель интерфейса на интерфейс IMsoDocExporterSite .

HrSetPageHeightForPagination

Приложение может вызвать метод HrSetPageHeightForPagination , чтобы указать высоту страницы в точках.

HRESULT HrSetPageHeightForPagination(
    float dytfPageHeight
);

Некоторые приложения поддерживают документ пользователя в непагинированном формате. В таких случаях надстройка разбивает документ на страницы, используя высоту страницы, указанную приложением в вызове HrSetPageHeightForPagination. Параметр dytfPageHeight указывает высоту страницы в точках.

После указания сведений о высоте страницы приложение передает надстройку весь документ в виде одного файла EMF в памяти при вызове HrAddPageFromEmf. Затем надстройка использует высоту страницы и EMF-файл для разбивки документа на страницы.

Надстройка возвращает сведения о разбиении на страницы в приложение в последующих вызовах метода HrGetPageBreaks .

HrGetPageBreaks

Приложение может вызвать метод HrGetPageBreaks , чтобы получить количество и расположение разрывов страниц для документов, разбиенных надстройкой на страницы.

HRESULT HrGetPageBreaks(
    float* rgdytfPageBreaks,
    int* pcchPageBreaks,
    BOOL* pfCanTrustLastBreakIsEndOfDocument
);

После того как надстройка разбивает документ на страницы, используя высоту страницы, указанную методом HrSetPageHeightForPagination , она возвращает сведения о разбиении на страницы при последующих вызовах, выполняемых приложением к методу HrGetPageBreaks .

Параметр rgdytfPageBreaks является указателем на массив значений float, указывающих расположения разрывов страниц в точках. Первый элемент в массиве (индекс 0) — это расположение первого разрыва страницы, второй элемент — расположение второго разрыва страницы и т. д. Поэтому значения этих элементов последовательно увеличиваются.

Параметр pcchPageBreaks — это указатель на целочисленное значение, указывающее количество разрывов страниц в документе.

Параметр pfCanTrustLastBreakIsEndOfDocument указывает, является ли расположение последнего разрыва страницы концом документа или началом последней страницы документа. Значение true указывает, что последний разрыв страницы — конец документа.

Приложение дважды вызывает HrGetPageBreakдля получения сведений о разбиении на страницы. При первом вызове приложение вызывает HrGetPageBreaks , чтобы получить количество разрывов страниц.

HrGetPageBreaks(NULL, &nPageBreaks, NULL);

Затем приложение вызывает HrGetPageBreaks во второй раз, чтобы получить фактические расположения. Во втором вызове приложение передает буфер достаточного размера для хранения массива расположений разрывов страниц.

HrGetPageBreaks(rgPageBreaks, &nPageBreaks, fCanStopAtLastPageBreak);

После получения сведений о разрыве страницы из надстройки приложение повторно инициирует процесс экспорта в фиксированном формате, начиная с вызова метода HrCreateDoc , а затем вызова HrAddPageFromEmf для каждой страницы, заданной информацией о разрыве страницы.

HrAddOutlineNode

Издатель вызывает метод HrAddOutlineNode , чтобы передать надстройке структуру, которая описывает узел в пользовательской структуре экспортированного документа.

HRESULT HrAddOutlineNode(
    int idNodeParent 
    const MSODOCEXOUTLINENODE* pNode
);

Код экспорта фиксированного формата может использовать сведения, передаваемые методом HrAddOutlineNode , для создания настраиваемой структуры экспортированного документа. С точки зрения пользователя каждый узел в структуре представлен текстом заголовка, который сопоставляется с определенным расположением в документе.

Каждый вызов HrAddOutlineNode указывает сведения для одного узла в этом контуре. Каждый узел идентифицируется идентификатором узла, уникальным в структуре. Идентификатор 0 зарезервирован для корневого узла. Структура является иерархической, то есть имеет древовидную структуру, в которой каждый узел имеет один родительский и ноль или несколько дочерних узлов.

Первый параметр hrAddOutlineNode предоставляет идентификатор узла, который является родительским для передаваемого узла.

Издатель всегда вызывает HrAddOutlineNode для родительского узла, прежде чем вызывать метод для любого из дочерних элементов родительского узла. Иными словами, экспортируемый код гарантирует наличие сведений об узле для узла, определяемого параметром idNodeParent . Единственным исключением является первоначальный вызов HrAddOutlineNode , указывающий корневой узел. Для этого вызова значение idNodeParent равно 0.

Дополнительные сведения, необходимые коду экспорта для каждого узла, передаются HrAddOutlineNode в структуре MSODOCEXOUTLINENODE , на которую указывает параметр pNode .

typedef struct _MsoDocexOutlineNode
{
    int idNode {};
    WCHAR rgwchNodeText[cwchMaxNodeText];
    int iDestPage {};
    float dytfvDestPage {};
    float dxtfvDestOffset {};
    float dytfvDestOffset {};
} MSODOCEXOUTLINENODE;

Члены MSODOCEXOUTLINENODE описаны следующим образом:

idNode Идентификатор узла. Значение -1 указывает, что этот узел не может иметь дочерние узлы в структуре. В противном случае этот элемент имеет уникальное значение в документе.
rgwchNodeText Строка Юникода, представляющая текст заголовка для каждого узла. Этот текст не обязательно должен быть уникальным по всей структуре.
iDestPage Номер страницы, содержащей целевое расположение в документе.
dytfvDestPage Высота целевой страницы в точках. Смещение, заданное элементом dytfvDestOffset , относится к левому верхнему углу страницы. Однако некоторые типы фиксированного формата используют систему координат относительно левого нижнего угла страницы. Для этих типов документов для преобразования смещения требуется высота страницы.
dxtfvDestOffset Горизонтальное смещение целевого расположения на целевой странице.
dytfvDestOffset Вертикальное смещение расположения назначения на целевой странице.

HrAddDocumentMetadataString

Издатель вызывает метод HrAddDocumentMetadataString для указания метаданных документа в виде строки Юникода.

HRESULT HrAddDocumentMetadataString(
    MSODOCEXMETADATA metadataType, 
    const WCHAR* pwchValue
);

Параметр metadatatype указывает тип метаданных, представленных строкой. Параметр metadatatype должен быть одним из следующих значений из типа перечисления MSODOCEXMETADATA.

Табл. 8. Перечисляемые значения MSODOCEXMETADATA

Значение	Описание
msodocexMetadataTitle	Заголовок документа.
msodocexMetadataAuthor	Автор документа
msodocexMetadataSubject	Строка, описывающая предмет документа (например, бизнес или наука).
msodocexMetadataKeywords	Ключевое слово, соответствующее содержимому документа.
msodocexMetadataCreator	Создатель документа, возможно, отличный от автора.
msodocexMetadataProducer	Производитель документа, возможно, отличный от автора или создателя.
msodocexMetadataCategory	Строка, описывающая тип документа (например, памятка, статья или книга).
msodocexMetadataStatus	Состояние документа. Это поле может отражать, где документ находится в процессе публикации (например, черновик или окончательный).
msodocexMetadataComments	Прочие комментарии, относящиеся к документу.

Для данного документа каждый тип метаданных может иметь только одну строку, связанную с ним. Например, если документ содержит несколько ключевых слов, они передаются надстройке в виде одной объединенной строки.

Параметр pwchValue указывает строку Юникода, содержащую метаданные.

То, как надстройка включает метаданные текстовой строки в экспортируемый документ, зависит от сведений о реализации кода экспорта и типа фиксированного формата, используемого в экспортируемом документе.

HrAddDocumentMetadataDate

Издатель вызывает метод HrAddDocumentMetadataDate , чтобы указать метаданные документа в виде структуры FILETIME.

HRESULT HrAddDocumentMetadataDate(
    MSODOCEXMETADATA metadataType, 
    const FILETIME* pftLocalTime
);

Параметр metadatatype указывает тип метаданных, представленных структурой FILETIME . Параметр metadatatype должен быть одним из следующих значений из типа перечисления MSODOCEXMETADATA.

Табл. 9. Перечисляемые значения MSODOCEXMETADATA

Значение	Описание
msodocexMetadataCreationDate	Дата создания документа.
msodocexMetadataModDate	Дата последнего изменения документа.

Параметр pftLocalTime указывает указатель на структуру FILETIME, содержащую сведения о дате и времени для метаданных. В следующем фрагменте кода показано, как извлечь эти сведения из структуры.

SYSTEMTIME st = { 0 };
WCHAR s[100];
FileTimeToSystemTime(pfiletime, &st);
swprintf(s, 99, L" %04d-%02d-%02dT%02d:%02d:%02dZ", st.wYear % 10000, 
    st.wMonth % 100, st.wDay % 100, st.wHour % 100, st.wMinute % 100, 
    st.wSecond % 100);

То, как надстройка включает метаданные даты и времени в экспортируемый документ, зависит от сведений о реализации кода экспорта и типа фиксированного формата, используемого в экспортируемом документе.

HrFinalize

Издатель вызывает метод HrFinalize в конце процесса экспорта документа.

HRESULT HrFinalize();

Код, реализующий экспорт в фиксированном формате, должен использовать HrFinalize для выполнения таких задач, как очистка буферов данных, запись оставшихся данных на диск и освобождение памяти и других ресурсов.

Заключение

Вы можете расширить функцию экспорта в фиксированных форматах приложений Office, реализовав интерфейс IMsoDocExporter . Методы этого интерфейса предоставляют для приложений Office канал для передачи надстройке визуального содержимого и семантических сведений в экспортируемом документе. Визуальное содержимое документа предоставляется надстройке в виде одного или нескольких расширенных метафайлов в памяти. Семантические сведения предоставляются в виде специально отформатированных записей комментариев в этом EMF. Дополнительные методы в интерфейсе позволяют приложениям Office передавать метаданные и структурную информацию о документе.

Дополнительные ресурсы

Дополнительные сведения см. в следующих источниках:

Поделиться через

Расширение экспорта Office PDF

Общие сведения о функции экспорта Fixed-Format Office (2024)

Инициализация Add-Ins

IMsoDocExporter

Поток вызовов

GetOutputOption и SetOutputOption

Microsoft Office вызывает getOutputOption только с помощью msodocexOptionTargetDPIColor для Fixed-Format Add-Ins

EnableCancel

HrBeginStructNode

MsoDocexTableAttr

MsoDocexListAttr

Советы по постобработки

Постобработка сносок и концевых сносок

Постобработка комментариев

Таблицы макета после обработки

Узлы, охватывающие страницы постобработки (абзацы, списки, таблицы)

HrEndStructNode

HrCreateDoc

HrSetDefaultLcid

HrAddPageFromEmf

Комментарии EMF передают семантические сведения

DocExComment_ExternalHyperlink(Rctfv)

DocExComment_InternalHyperlink(Rctfv)

DocExComment_ColorInfo

DocExComment_ColorEnable

DocExComment_BeginStructNode

DocExComment_EndStructNode

DocExComment_BeginTextRun

DocExComment_EndTextRun

DocExComment_UnicodeForNextTextOut

DocExComment_EPSColor

DocExComment_EPSColorCMYKJPEG

DocExComment_EPSColorSpotImage

Расширенная поддержка цветов

Цвет векторов и перекрашенные изображения

Неперекрашенные изображения

Цвет из EPS-файлов

SetDocExporterSite

HrSetPageHeightForPagination

HrGetPageBreaks

HrAddOutlineNode

HrAddDocumentMetadataString

HrAddDocumentMetadataDate

HrFinalize

Заключение

Дополнительные ресурсы

Дополнительные ресурсы