65.9K
CodeProject 正在变化。 阅读更多。
Home

使用 Word 2007-2010 编写 WPF 的帮助文件

LukasX2
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.86/5 (6投票s)

2010 年 10 月 11 日

LGPL3

6分钟阅读

viewsIcon

39934

downloadIcon

1130

面向 WPF 驱动的帮助文件引擎的介绍， 可以选择从 Word 文档生成帮助内容

help-7.png

引言

本文介绍了一个应用程序，它将允许开发人员显示帮助文档并将其集成到他们的应用程序中。

背景

此工具背后的想法是，在 Windows 95 - XP 时代，有一种统一的方式为应用程序提供帮助内容：WinHelp 和 HtmlHelp 以及一些基于 Web 的解决方案。但 HtmlHelp 的这种形式的开发已经停止，较新版本只适用于在 Visual Studio 中显示帮助。目标是提供一个独立的帮助查看器，它可以很容易地扩展并与基于 WPF 的应用程序集成。

Sora HelpSystem 提供了一个可扩展的基础，用于显示任何基于 WPF 的应用程序的帮助内容，并能够从不同的来源生成帮助内容。目前，帮助内容可以手动创建，也可以使用基于 Word To XAML 的工具从 Microsoft Word 2007-2010 文档中导入。

将来，帮助内容可以直接从 Word 文档集合和程序集 XML 文档中生成。

Sora 帮助系统

Sora HelpSystem 是一个托管在 CodePlex 上的开源工具集合。它们采用 LGPL 许可，这意味着即使在商业应用程序中，您也可以自由使用这些工具。请注意，此许可适用于 HelpView、HelpEdit 和 基础库。WordToXaml 有自己的许可，应遵守，从而限制 XamlImport 的再分发。

帮助视图

help-xp.png

位于 HelpView.exe 中，这是用于显示帮助文件的查看器应用程序。要直接打开帮助文件，只需运行 HelpView.exe 并将帮助文件作为进程参数传入即可。

帮助编辑

help-edit.png

此应用程序允许对帮助文件进行一些基本的编辑操作。首选方法是从 Word 文档生成帮助内容。

基础库

由 Sora.Data.dll、Sora.FileSystem.dll 和 Sora.HelpSystem.dll 组成，这是帮助提供程序的运行时，运行查看器、编辑器或如果您在其中嵌入了某些帮助容器的应用程序都需要它。

从 Word 文档生成帮助内容

这种技术的主要优点是您可以使用您喜欢的富文本编辑器来编写您的帮助文件。当您有内容时，您将能够直接从文档生成帮助文件，并使用帮助编辑器对其进行最终确定。

请注意，只能导入 docx 文档（Word 2007 和 Word 2010）。此外，您必须安装 Microsoft Word...

您唯一需要注意的是，您必须为您正在编写的页面定义一些标记。在开始帮助页面内容之前，您必须包含以下文本

[DSHELPSECTION:] relative/page/uri | page title

The page content...

相对页面 URI 是不带开头的 ds-help://help.document/ 的 URI。此外，还有一些特殊页面

  • start：这是打开帮助文件时显示的第一页。在此页中，您可以简要介绍您的帮助文档并引入主题。
  • header：这是使用 HelpViewer 时显示在任何页面顶部的静态文本。
  • error404：这是在文档中找不到 URI 时显示的页面。
  • errorException：当查看器中发生错误时显示此页面。希望此页面永远不会可见...

您还可以在文档中定义指向其他页面的链接。当在文档中显示时，链接将在点击时解析。您可以（使用 Microsoft Word）创建指向网页的链接（通过使用标准链接，例如 http://www.google.com）和帮助页面（通过将相对页面 URI 指定为链接目标）。

编写完内容后，您可以使用 XamlImport 工具导入它。在安装程序中，它位于 Sora HelpSystem 的安装目录中（在开始菜单中有一个快捷方式）。XamlImport 语法如下：

XamlImport [-m] source_file [target_file]

-m 开关表示如果 target_file 已存在，则生成的文件将与 target_file 合并。这允许从多个源链式生成帮助文件。

源文件可以是 Word 文档 (DocX)，也可以是包含 FlowDocument 的 XAML 文件（例如由工具 WordToXaml Converter 生成的输出）。

如果未指定 target_file，则名称将通过将源文件的扩展名更改为 .dshelp 来构建。

生成的文件将在 HelpViewer 中可打开。如果结果帮助文件中存在一些不一致或需要更正的详细信息，您可以使用 HelpEdit 应用程序编辑您的帮助文档。

在 WPF 窗口中嵌入帮助内容

help-sample.png

开发人员的一项常见任务是在应用程序中直接提供帮助内容。此类内容包括工具提示或特定控件的描述。通常，您必须在 XAML 中编写此类文本（或使用神奇的方式从某些外部工具中检索它）。

这里的想法是直接从帮助文件中加载此内容。第一步是引用帮助提供程序。您需要添加对以下 4 个程序集的引用

  • Sora.Data.dll (数据库引擎)
  • Sora.FileSystem.dll (存储引擎)
  • Sora.HelpSystem.dll (帮助引擎)
  • Sora.HelpSystem.UI.WPF (WPF UI 工具)

添加这些引用后，您必须定义当前文档的 HelpSource。您可以有多个来源，但每个组件都将链接到唯一的来源。因此，您可以通过更改帮助来源来动态更改整个窗口的选定帮助文档（允许诸如根据应用程序的当前区域性提供本地化帮助文件等场景）。

<Window x:Class="SampleWPFApplication.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:help_ui="clr-namespace:Sora.HelpSystem.UI.WPF;
		assembly=Sora.HelpSystem.UI.WPF"
        Title="MainWindow" Height="450" Width="525">
    <Window.Resources>
        <!-- This object will provide the help document. 
		The source is relative to the current directory.
        If not found, the source is relative to the directory of the main assembly -->
        <help_ui:HelpDocumentSource x:Key="WindowHelp" Source="SampleHelp.dshelp"/>
    </Window.Resources>
 ... 
</Window>

然后，您可以通过两种方式提供内容

显示帮助文档中的完整页面

 <!-- This control can show help content from a document.
The document is linked to a HelpDocumentSource and the Uri is defined in CurrentPageUri -->
<help_ui:HelpContentDisplay Name="helpContent" 
Document="{Binding Source={StaticResource WindowHelp}, Path=Document}"
CurrentPageUri="ds-help://help.document/items/information" Height="100"/>

HelpContentDisplay 是帮助页面的宿主。您可以通过提供来源（Document 属性，它链接到窗口的帮助来源）和 URI（页面地址，在 HelpViewer 中浏览页面时显示）来显示页面。

请注意，您还可以使用 URI ds-help://help.document/search?words+to+search 将页面指定为搜索结果。然后，控件将显示一个包含搜索结果的页面，用户将能够通过单击超链接导航到结果。

此外，您可以通过提供像 http://www.google.com 这样的 URI 来指定网页。

从帮助文档加载纯文本

另一种方法是直接从帮助文档提供一些文本作为属性（例如 TextBlock 的 Text 属性）的来源。您可以使用以下语法实现：

 <TextBlock Text="{help_ui:HelpText DocumentSource={StaticResource WindowHelp}, 
	PageUri=ds-help://help.document/items}"/>

内容由绑定扩展提供，允许您将帮助内容提供给任何接受 string 值的属性。

请注意，只会显示文本。不会显示图像或链接。

进一步

将来，将有可能从更多来源生成帮助内容。下一步应该是像使用 Sandcastle 这样的工具一样，从程序集的 XML 注释中生成内容。

从源生成帮助内容基本上是编写一个 FlowDocument：这是运行时内部用于存储内容的格式。XamlImport 工具是这种过程的一个很好的例子（其中模糊的部分是处理生成的文档以获取标记）。

请随时查看 CodePlex 上的项目源代码。如果您有任何问题或评论，也可以将它们发布在项目的 CodePlex 页面或此处。

历史

  • 2010/12/10：初始版本
© . All rights reserved.