Как работать со ссылками и ссылками в .NET
Это руководство показывает, как вставлять гиперссылки, перекрестные ссылки на закладки, поля с запросом значений и поля цитирования в Aspose.Words FOSS для .NET, используя FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, и другие подклассы ссылок и ссылок Field подклассы в Aspose.Words.Fields пространстве имен. Руководство охватывает вставку простой гиперссылки, создание закладок и перекрестные ссылки на них, запрос значений при обновлении поля и цитирование источников библиографии.
Пошаговое руководство
Шаг 1: Установить пакет
Aspose.Words FOSS for .NET пока не публикует пакет NuGet — вместо этого соберите библиотеку из исходного кода. Клонируйте https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, затем соберите Aspose.Words.sln в конфигурации Release с помощью SDK .NET и добавьте полученную сборку Aspose.Words в ваш проект. Библиотека нацелена на .NET Standard 2.0, поэтому она работает на .NET Framework 4.6.2+ и .NET 6/8/10.
Шаг 2: Импортировать необходимые классы
Добавьте директиву using Aspose.Words; для Document и DocumentBuilder, а также директиву using Aspose.Words.Fields; для FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography и остальных классов полей, рассматриваемых в этом руководстве.
Шаг 3: Вставить гиперссылку
Для простой гиперссылки вызовите DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) — передайте isBookmark: false в качестве целевого URL или true для ссылки на закладку в том же документе. При необходимости напрямую создавать FieldHyperlink, когда ярлык не раскрывает нужные свойства: Address и SubAddress содержат целевой URL или расположение в документе, ScreenTip задаёт всплывающую подсказку, OpenInNewWindow и IsImageMap — флаги отображения, а Target задаёт имя фрейма браузера.
Шаг 4: Создать закладку для ссылки
Вызовите DocumentBuilder.StartBookmark(bookmarkName) перед содержимым, которое должна охватывать закладка, и DocumentBuilder.EndBookmark(bookmarkName) после него, используя одинаковое имя для обоих вызовов. DocumentBuilder.MoveToBookmark(bookmarkName) перемещает курсор к уже существующей закладке — удобно для перехода к месту перед вставкой поля перекрёстной ссылки рядом с ней.
Шаг 5: Вставить перекрёстную ссылку на эту закладку
FieldRef (поле REF), FieldPageRef (PAGEREF) и FieldNoteRef (NOTEREF) каждый разрешают контент в именованной закладке через их свойство BookmarkName. Установите InsertHyperlink, чтобы сделать ссылку кликабельной, и InsertRelativePosition, чтобы выводить относительное положение («выше» / «ниже») вместо самого текста ссылки. FieldRef дополнительно поддерживает варианты нумерации абзацев — InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator — и IncludeNoteOrComment. FieldStyleRef (STYLEREF) разрешает ближайший абзац, отформатированный заданным StyleName вместо закладки, с SearchFromBottom для поиска назад от позиции поля. FieldSet (SET) определяет значение текста в закладке — BookmarkName и BookmarkText — которое может разрешить поле REF в другом месте.
Шаг 6: Запросить значение во время обновления
FieldAsk (ASK) и FieldFillIn (FILLIN) запрашивает значение у того, кто обновляет поле: установить PromptText к тексту, отображаемому пользователю, DefaultResponse для резервного значения, и PromptOnceOnMailMerge чтобы ограничить повторные запросы во время слияния писем. FieldAsk дополнительно сохраняет свой ответ в BookmarkName чтобы другие поля могли ссылаться на него. Для автоматических обновлений полей предоставляйте ответы программно, а не запрашивая их интерактивно; см. руководство по полям для интерфейса обратного вызова, который делает это.
Шаг 7: Ссылка на внешнее или связанное содержимое
FieldDde (DDE) и FieldDdeAuto (DDEAUTO) связываются с содержимым в другом приложении через ProgId, SourceFullName и SourceItem, при этом InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode и InsertAsBitmap выбирают вставленное представление, а AutoUpdate / IsLinked управляют поведением обновления. FieldLink (LINK) является эквивалентом OLE-ссылки, добавляя FormatUpdateType. FieldImport (IMPORT) и FieldIncludePicture (INCLUDEPICTURE) импортируют внешнюю графику через SourceFullName и GraphicFilter. FieldInclude (INCLUDE) и FieldIncludeText (INCLUDETEXT) импортируют внешнее содержимое документа, при этом BookmarkName задаёт диапазон включения, а LockFields предотвращает его обновление; FieldIncludeText дополнительно поддерживает источники XML через Encoding, MimeType, NamespaceMappings, XPath и XslTransformation.
Шаг 8: Ссылка на строительные блоки и элементы глоссария
FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) и FieldGlossary (GLOSSARY) все ссылаются на именованную запись строительного блока через EntryName; FieldAutoTextList добавляет ListStyle и ScreenTip для её представления в виде списка.
Шаг 9: Вставка полей цитирования и библиографии
FieldCitation (CITATION) и FieldBibliography (BIBLIOGRAPHY) отобразить содержимое, полученное из данных библиографии документа. Установить FieldCitation.SourceTag (или альтернативный AnotherSourceTag) чтобы определить, какой источник цитируется, и использовать Prefix, Suffix, PageNumber, VolumeNumber, и Suppress* флаги (SuppressAuthor, SuppressTitle, SuppressYear) чтобы управлять тем, как форматируется ссылка. FieldBibliography.SourceTag, FilterLanguageId, и FormatLanguageId контролировать, какие источники появляются в отрисованной библиографии и на каком языке. Эти поля корректно отобразятся только после совпадения Source записи существуют – см. руководство по библиографии для их создания.
Распространённые проблемы и решения
Поле REF, PAGEREF или NOTEREF показывает ошибочный результат Эта BookmarkName целевой объект не существует в документе. Создайте закладку с DocumentBuilder.StartBookmark() / EndBookmark() перед обновлением поля.
Поле ASK или FILLIN блокирует автоматическое обновление Обратный вызов не назначен для программного предоставления ответа. Назначьте обратный вызов обновления поля, описанный в руководство по полям, или установить DefaultResponse на поле, чтобы у него было резервное значение.
Поле CITATION или BIBLIOGRAPHY отображается пустым Это SourceTag не соответствует ни одному Source в данных библиографии документа. Добавьте соответствующий Source – см. руководство по библиографии.
Поле DDE, DDEAUTO или LINK не обновляется Эти поля ссылаются на внешний источник OLE, который недоступен за пределами оригинального контекста Windows/OLE. Рассматривайте сохранённый результат поля как последнее известное значение в такой ситуации.
Гиперссылка, вставленная с помощью InsertHyperlink, не содержит свойства, которое мне требуется DocumentBuilder.InsertHyperlink() является ярлыком, который не раскрывает каждый FieldHyperlink свойство. Создайте или получите FieldHyperlink непосредственно, чтобы задать свойства, такие как ScreenTip or IsImageMap.
Часто задаваемые вопросы
В чём разница между FieldRef и FieldStyleRef?
FieldRef разрешается к содержимому в именованной закладке (BookmarkName); FieldStyleRef же разрешается к ближайшему абзацу, отформатированному с заданным StyleName, независимо от закладок.
Как вставить простую гиперссылку, не создавая поле вручную?
Вызовите DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
Эти классы полей link и reference находятся в отдельном пространстве имён от остальных полей?
Нет — FieldHyperlink, FieldRef, FieldCitation и остальные классы, рассмотренные здесь, являются обычными подклассами Field в пространстве имён Aspose.Words.Fields, том же пространстве имён, которое используется для всех остальных типов полей.
Как поля цитирования относятся к модели данных библиографии?
FieldCitation and FieldBibliography отображать контент, осуществляя поиск SourceTag против Source записей, описанных в руководстве по библиографии – эти классы полей отвечают за рендеринг, в то время как Source and Contributor классы содержат базовые данные.
Как создать закладку перед её использованием?
Вызовите DocumentBuilder.StartBookmark(bookmarkName) перед содержимым и DocumentBuilder.EndBookmark(bookmarkName) после него, используя одно и то же имя для обоих вызовов.
