批注概述

在纸质文档上编写说明或注释毫不稀奇，我们几乎认为这是理所当然的。 这些说明或注释就是“批注”，我们将其添加到文档，用于标注信息或突出显示兴趣项以供日后参考。 虽然在打印文档上编写注释很简单也很平常，但是就算在所有电子文档上添加个人注释，功能上却通常有很多限制。

本主题介绍几种常见类型的批注，重点介绍便笺和突出显示，并举例说明 Microsoft Annotations Framework 如何通过 Windows Presentation Foundation (WPF) 文档查看控件简化在应用程序中使用这些类型的批注。 支持批注的 WPF 文档查看控件包括 FlowDocumentReader 和 FlowDocumentScrollViewer，以及派生自 DocumentViewerBase 的控件，如 DocumentViewer 和 FlowDocumentPageViewer。

便笺

平常的便笺是将信息写在小块彩纸上，随后将这张彩纸“粘贴”到文档。 数字便笺为电子文档提供类似的功能，但灵活性更高，可包括许多其他类型的内容，如键入文本、手写注释（如 Tablet PC“墨迹”笔划）或 Web 链接。

下图显示了突出显示、文本便笺以及墨迹便笺批注的一些示例。

下面的示例演示了可用于在应用程序中启用批注支持的方法。

// ------------------------ StartAnnotations --------------------------
/// <summary>
///   Enables annotations and displays all that are viewable.</summary>
private void StartAnnotations()
{
    // If there is no AnnotationService yet, create one.
    if (_annotService == null)
        // docViewer is a document viewing control named in Window1.xaml.
        _annotService = new AnnotationService(docViewer);

    // If the AnnotationService is currently enabled, disable it.
    if (_annotService.IsEnabled == true)
        _annotService.Disable();

    // Open a stream to the file for storing annotations.
    _annotStream = new FileStream(
        _annotStorePath, FileMode.OpenOrCreate, FileAccess.ReadWrite);

    // Create an AnnotationStore using the file stream.
    _annotStore = new XmlStreamStore(_annotStream);

    // Enable the AnnotationService using the new store.
    _annotService.Enable(_annotStore);
}// end:StartAnnotations()

' ------------------------ StartAnnotations --------------------------
''' <summary>
'''   Enables annotations and displays all that are viewable.</summary>
Private Sub StartAnnotations()
    ' If there is no AnnotationService yet, create one.
    If _annotService Is Nothing Then
        ' docViewer is a document viewing control named in Window1.xaml.
        _annotService = New AnnotationService(docViewer)
    End If

    ' If the AnnotationService is currently enabled, disable it.
    If _annotService.IsEnabled = True Then
        _annotService.Disable()
    End If

    ' Open a stream to the file for storing annotations.
    _annotStream = New FileStream(_annotStorePath, FileMode.OpenOrCreate, FileAccess.ReadWrite)

    ' Create an AnnotationStore using the file stream.
    _annotStore = New XmlStreamStore(_annotStream)

    ' Enable the AnnotationService using the new store.
    _annotService.Enable(_annotStore)
End Sub

要点

当人们在纸质文档上作标记时，往往使用创造性的方法来突出显示兴趣项，例如对于句子中的某些字词，加下划线、高亮显示、圈出，或者将在空白的地方绘制标记或符号。 Microsoft Annotations Framework 中的突出显示批注具有类似的功能，用于标记在 WPF 文档查看控件中显示的信息。

下图演示了一个突出显示批注的示例。

用户通常以如下方法创建批注：首先选择感兴趣的文本或者项，然后单击右键显示批注选项的 ContextMenu。 在下面的示例中，你可以使用 Extensible Application Markup Language 声明包含路由命令的 ContextMenu，用户可以访问这些命令来创建和管理批注。

<DocumentViewer.ContextMenu>
  <ContextMenu>
    <MenuItem Command="ApplicationCommands.Copy" />
    <Separator />
    <!-- Add a Highlight annotation to a user selection. -->
    <MenuItem Command="ann:AnnotationService.CreateHighlightCommand"
              Header="Add Highlight" />
    <!-- Add a Text Note annotation to a user selection. -->
    <MenuItem Command="ann:AnnotationService.CreateTextStickyNoteCommand"
              Header="Add Text Note" />
    <!-- Add an Ink Note annotation to a user selection. -->
    <MenuItem Command="ann:AnnotationService.CreateInkStickyNoteCommand"
              Header="Add Ink Note" />
    <Separator />
    <!-- Remove Highlights from a user selection. -->
    <MenuItem Command="ann:AnnotationService.ClearHighlightsCommand"
              Header="Remove Highlights" />
    <!-- Remove Text Notes and Ink Notes from a user selection. -->
    <MenuItem Command="ann:AnnotationService.DeleteStickyNotesCommand"
              Header="Remove Notes" />
    <!-- Remove Highlights, Text Notes, Ink Notes from a selection. -->
    <MenuItem Command="ann:AnnotationService.DeleteAnnotationsCommand"
              Header="Remove Highlights &amp; Notes" />
  </ContextMenu>
</DocumentViewer.ContextMenu>

数据锚定

Annotations Framework 将批注与用户选择的数据绑定，而不仅仅是绑定到显示视图中的某个位置。 因此，如果文档视图更改（例如，当用户滚动显示窗口或者调整其大小时），批注将仍然跟随它绑定到的所选数据。 例如，下图显示了用户在所选文本上做的批注。 当文档视图更改时（滚动、调整大小、缩放或者移动），突出显示批注将与最初所选数据一起移动。

匹配批注与批注对象

你可以将批注与对应的批注对象匹配。 以具有注释窗格的简单文档读取器应用程序为例。 注释窗格可能是一个列表框，用于显示锚定到文档的批注列表的文本。 如果用户在列表框中选择一项，应用程序将显示相应的批注对象所锚定到的文档段落。

下面的示例演示如何实现充当注释窗格的此类列表框的事件处理程序。

void annotationsListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{

    Annotation comment = (sender as ListBox).SelectedItem as Annotation;
    if (comment != null)
    {
        // IAnchorInfo info;
        // service is an AnnotationService object
        // comment is an Annotation object
        info = AnnotationHelper.GetAnchorInfo(this.service, comment);
        TextAnchor resolvedAnchor = info.ResolvedAnchor as TextAnchor;
        TextPointer textPointer = (TextPointer)resolvedAnchor.BoundingStart;
        textPointer.Paragraph.BringIntoView();
    }
}

Private Sub annotationsListBox_SelectionChanged(ByVal sender As Object, ByVal e As SelectionChangedEventArgs)

    Dim comment As Annotation = TryCast((TryCast(sender, ListBox)).SelectedItem, Annotation)
    If comment IsNot Nothing Then
        ' service is an AnnotationService object
        ' comment is an Annotation object
        info = AnnotationHelper.GetAnchorInfo(Me.service, comment)
        Dim resolvedAnchor As TextAnchor = TryCast(info.ResolvedAnchor, TextAnchor)
        Dim textPointer As TextPointer = CType(resolvedAnchor.BoundingStart, TextPointer)
        textPointer.Paragraph.BringIntoView()
    End If
End Sub

另一示例方案涉及通过电子邮件在文档读取器之间实现交换批注和便笺的应用程序。 凭借此功能，这些应用程序可以将读取器导航到包含要交换的批注的页面。

另请参阅

• DocumentViewerBase
• DocumentViewer
• FlowDocumentPageViewer
• FlowDocumentScrollViewer
• FlowDocumentReader
• IAnchorInfo
• 注释架构
• ContextMenu 概述
• 命令概述
• 流文档概述
• 如何：将命令添加到菜单项