Microsoft Help Viewer SDK
本文包含 Visual Studio 帮助查看器集成商的以下任务:
创建主题(F1 支持)
创建帮助查看器内容品牌包
部署一组文章
向 Visual Studio shell(集成或独立)添加帮助
其他资源
创建主题(F1 支持)
该部分概述了所呈现主题的组件、主题要求、如何创建主题的简短说明(包括对 F1 支持的要求),最后是带有呈现结果的示例主题。
帮助查看器主题概述
调用主题进行呈现时,帮助查看器会获取在安装或上次更新时与该主题关联的品牌包元素以及主题 XHTML,并将二者组合在一起以生成呈现的内容视图(品牌数据 + 主题数据)。 品牌包包含徽标、对内容行为的支持和品牌文本(版权等)。 有关品牌包元素的详细信息,请参阅下方“创建品牌包”。 如果没有与主题关联的品牌包,则帮助查看器将使用位于帮助查看器应用程序根目录中的回退品牌包 (Branding_en-US.mshc)。
帮助查看器主题要求
要在帮助查看器中正确呈现,原始主题内容必须是 W3C Basic 1.1 XHTML。
一个主题通常包含两个部分:
元数据(请参阅内容元数据参考):有关主题的数据,例如,主题唯一 ID、关键字 (keyword) 值、主题 TOC ID、父节点 ID 等。
正文内容:符合 W3C Basic 1.1 XHTML,其中包括支持的内容行为(可折叠区域、代码片段等,完整的列表如下所示)。
Visual Studio 品牌包支持的控件:
链接
CodeSnippet
CollapsibleArea
继承的成员
LanguageSpecificText
支持的语言字符串(不区分大小写):
javascript
csharp 或 c#
cplusplus、visualc++ 或 c++
jscript
visualbasic 或 vb
f#、fsharp 或 fs
其他 - 表示语言名称的字符串
创建帮助查看器主题
创建名为 ContosoTopic4.htm 的新 XHTML 文档,并包含标题标记(如下所示)。
<html>
<head>
<title>Contoso Topic 4</title>
</head>
<body>
</body>
</html>
接下来,添加数据以定义主题的呈现方式(自有品牌或非自有品牌),如何为 F1 引用该主题,该主题在 TOC 中的位置、该主题的 ID(供其他主题引用链接)等。有关支持的元数据的完整列表,请参阅下方“内容元数据”表。
本例中,我们将使用自有品牌包,其为 Visual Studio 帮助查看器品牌包的变体。
添加 F1 元名称和值(“Microsoft.Help.F1” content=“ ContosoTopic4”),该名称和值将与 IDE 属性包中提供的 F1 值相匹配。 (有关详细信息,请参阅 F1 支持部分)。这是与 IDE 中的 F1 调用匹配的值,在 IDE 中选择 F1 时显示该主题。
添加主题 ID。 这是其他主题用于链接到该主题的字符串。 这是该主题的帮助查看器 ID。
对于 TOC,请添加该主题的父节点以定义 TOC 节点的显示位置。
请为 TOC 添加该主题的节点顺序。 当父节点具有
n
个子节点时,请按子节点的顺序定义该主题的位置。 例如,该主题是 4 个子主题中的第 4 个。
元数据部分示例:
<html>
<head>
<title>Contoso Topic 4</title>
<meta name="SelfBranded" content="false" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="Microsoft.Help.Id" content="ContosoTopic4" />
<meta name="Microsoft.Help.F1" content=" ContosoTopic4" />
<meta name="Language" content="en-us" />
<meta name="Microsoft.Help.TocParent" content="ContosoTopic0" />
<meta name="Microsoft.Help.TocOrder" content="4" />
</head>
<body>
</body>
</html>
主题正文
主题的正文(不包括页眉和页脚)将包含页面链接、注释部分、可折叠区域、代码片段和特定于语言的文本部分。 所呈现主题的相关信息,请参阅品牌部分。
添加主题标题标记:
<div class="title">Contoso Topic 4</div>
添加节点部分:
<div class="alert"> add your table tag and text </div>
添加可折叠区域:
<CollapsibleArea Expanded="1" Title="Collapsible Area Test Heading"> add text </CollapsibleArea>
添加代码片段:
<CodeSnippet EnableCopyCode="true" Language="CSharp" ContainsMarkup="false" DisplayLanguage="C#" > a block of code </CodeSnippet>
添加特定于代码语言的文本:
<LanguageSpecificText devLangcs="CS" devLangvb="VB" devLangcpp="C++" devLangnu="F#" />
请注意,devLangnu=
支持输入其他语言。 例如,当代码片段 DisplayLanguage = Fortran 时,devLangnu="Fortran"
显示为 Fortran添加页面链接:
<a href="ms-xhelp:///?Id=ContosoTopic1">Main Topic</a>
注意
注意:对于不支持的新的“显示语言”(例如,F#、Cobol、Fortran)代码片段中的代码着色将为单色。
示例帮助查看器主题 该代码演示如何定义元数据、代码片段、可折叠区域和特定于语言的文本。
<?xml version="1.0" encoding="utf-8"?>
<html>
<head>
<title>Contoso Topic 4</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="Microsoft.Help.Id" content="ContosoTopic4" />
<meta name="Microsoft.Help.F1" content=" ContosoTopic4" />
<meta name="Language" content="en-us" />
<meta name="Microsoft.Help.TocParent" content="ContosoTopic0" />
<meta name="Microsoft.Help.TocOrder" content="4" />
<meta name="SelfBranded" content="false" />
</head>
<body>
<div class="title">Contoso Topic 4</div>
<div id="header">
<table id="bottomTable" cellpadding="0" cellspacing="0" width="100%">
<tr id="headerTableRow2"><td align="left">
<span id="nsrTitle">Contoso Topic 1</span>
</td>
<td align="right">
</td></tr>
<tr id="headerTableRow1"><td align="left">
<span id="runningHeaderText">Contoso Widgets & Sprockets</span>
</td></tr>
</table>
</div>
<h2>Table of Contents</h2>
<ul class="toc">
<li class="tocline1"><a href="#introduction" target="_self">1.0 Introduction</a></li>
<li class="tocline1"><a href="#related-content" target="_self">Related content</a></li>
</ul>
<div class="topic">
<div id="mainSection">
<div id="mainBody">
<a name="introduction"></a>
<h2>1.0 Introduction</h2>
<p>[This documentation is for sample purposes only.]</p>
<p>Contoso Topic 1 contains examples of:
<ul>
<li>Collapsible Area</li>
<li>Bookmark ("Related content")</li>
<li>Code Snippets from Branding Package</li>
</ul>
</p>
<div class="alert"><table><tr><th>
<strong>Note </strong></th></tr>
<tr><td>
<p>This is an example of a <span class="label">Note </span>section.
Call out important items for your reader in this <span class="label">Note </span>box.
</p></td></tr>
</table>
</div>
</div>
<CollapsibleArea Expanded="1" Title="Collapsible Area Test Heading">
<a id="sectionToggle0"><!----></a>
<div>
Example of Collapsible Area
<br/>
Lorem ipsum dolor sit amet...
</div>
</CollapsibleArea>
<div id="snippetGroup" >
<CodeSnippet EnableCopyCode="true" Language="VisualBasic" ContainsMarkup="false" DisplayLanguage="Visual Basic" >
Private Sub ToolStripRenderer1_RenderGrip(sender as Object, e as ToolStripGripRenderEventArgs) _ Handles ToolStripRenderer1.RenderGrip
Dim messageBoxVB as New System.Text.StringBuilder()
messageBoxVB.AppendFormat("{0} = {1}", "GripBounds", e.GripBounds)
messageBoxVB.AppendLine()
...
MessageBox.Show(messageBoxVB.ToString(),"RenderGrip Event")
End Sub
</CodeSnippet>
<CodeSnippet EnableCopyCode="true" Language="CSharp" ContainsMarkup="false" DisplayLanguage="C#" >
private void ToolStripRenderer1_RenderGrip(Object sender, ToolStripGripRenderEventArgs e)
{
System.Text.StringBuilder messageBoxCS = new System.Text.StringBuilder();
messageBoxCS.AppendFormat("{0} = {1}", "GripBounds", e.GripBounds );
messageBoxCS.AppendLine();
...
MessageBox.Show(messageBoxCS.ToString(), "RenderGrip Event" );
}
</CodeSnippet>
<CodeSnippet EnableCopyCode="true" Language="fsharp" ContainsMarkup="false" DisplayLanguage="F#" >
some F# code
</CodeSnippet>
</div>
<h4 class="subHeading">Example of code specific text</h4>Language = <LanguageSpecificText devLangcs="CS" devLangvb="VB" devLangcpp="C++" devLangnu="F#" />
<a name="related-content"></a>
<h1 class="heading">Related content</h1>
<div id="relatedcontentSection" class="section">
<div class="relatedcontentStyle">
<a href="ms-xhelp:///?Id=ContosoTopic1">Main Topic</a>
</div>
</div>
</div>
</div>
</body>
</html>
F1 支持
在 Visual Studio 中,选择 F1 将生成从光标在 IDE 中的位置提供的值,并使用提供的值填充“属性包”(基于光标位置)。 当光标悬停在要素 x 上时,要素 x 处于活动状态/处于焦点状态,并用值填充属性包。 选择 F1 时,将填充属性包,Visual Studio F1 代码将查看客户默认帮助源是本地还是联机(默认为联机),然后根据用户设置(联机是默认值)创建相应的字符串 - shell 执行(请参阅帮助管理员指南了解 exe 启动参数),其中包含本地帮助查看器的参数 + 属性包中的关键字(如果本地帮助是默认值),或参数列表中包含关键字的 MSDN URL。
如果 F1 返回三个字符串,称为多值字符串,取第一项,查找命中,如果找到,则完成;如果不是,移动到下一个字符串。 给事项排序。 多值关键字的呈现方式应为最长字符串到最短字符串。 若要在多值关键字的情况下验证这一点,请查看联机 F1 URL 字符串,其中将包含所选关键字。
在 Visual Studio 2012 中,我们特意在联机和脱机之间进行了明确的划分,因此,如果用户的设置为“联机”,则只需将 F1 请求直接传递到 MSDN 上的联机查询服务,而不是通过 Visual Studio 2010 中的帮助库代理进行路由。 然后,我们依靠“已安装的供应商内容 = true”的状态来确定是否在该上下文中执行不同的操作。 如果为 True,我们将根据为客户提供的目标支持内容执行此解析和路由逻辑。 如果为 False,则我们只需转到 MSDN。 如果用户的设置为“本地”,则所有调用都将转到本地帮助引擎。
F1 流关系图:
当帮助查看器默认帮助内容源设置为联机(在浏览器中启动)时:
Visual Studio 合作伙伴 (VSP) 功能向 F1 属性包(属性包 prefix.keyword 和注册表中找到的前缀的联机 URL)发出值:F1 向浏览器发送 VSP URL+ 参数。
Visual Studio 功能(语言编辑器、Visual Studio 特定菜单项等):F1 将 Visual Studio URL 发送到浏览器。
当帮助查看器默认帮助内容源设置为本地帮助(在帮助查看器中启动)时:
VSP 功能,其中 F1 属性包与本地存储索引之间的关键字匹配(即,属性包 prefix.keyword = 在本地存储索引中找到的值):F1 在帮助查看器中呈现主题。
Visual Studio 功能(VSP 无法替代从 Visual Studio 功能发出的属性包):F1 在帮助查看器中呈现 Visual Studio 主题。
设置以下注册表值以启用供应商帮助内容的 F1 回退。 F1 回退意味着帮助查看器设置为联机查找 F1 帮助内容,并且供应商内容安装在本地用户的硬盘驱动器上。 尽管默认设置是联机帮助,但帮助查看器应该查看本地帮助以查找内容。
在 Help 2.3 注册表项下设置 VendorContent 值:
对于 32 位操作系统:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.3\Catalogs\VisualStudio15
"VendorContent"=dword:00000001
对于 64 位操作系统:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Catalogs\VisualStudio15
"VendorContent"=dword:00000001
在 Help 2.3 注册表项下注册合作伙伴命名空间:
对于 32 位操作系统:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.3\Partner\<namespace>
"location"="offline"
对于 64 位操作系统:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Partner\<namespace>
"location"="offline"
原生命名空间解析
若要启用原生命名空间解析,请在注册表中添加一个名为:BaseNativeNamespaces 的新 DWORD,并将其值设置为 1(在要支持的目录项下)。 例如,如果要使用 Visual Studio 目录,可以将键添加到一下路径:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Catalogs\VisualStudio15
当遇到 HEADER/METHOD 格式的 F1 关键字时,“/”字符将被解析掉,从而产生以下结构:
HEADER:是可用于在注册表中注册的命名空间
方法:这将成为传递的关键字。
例如,提供一个名为 CustomLibrary 的自定义库和一个名为 MyTestMethod 的方法,当 F1 请求传入时,它将被格式化为 CustomLibrary/MyTestMethod
。
然后,用户可以将 CustomLibrary 注册为合作伙伴配置单元下的命名空间,并提供所需的任何位置键,传递给查询的关键字为 MyTestMethod。
启用 IDE 中的帮助调试工具
添加以下注册表项和值:
HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\16.0\Dynamic Help
Value: Display Debug Output in Retail Data: YES
在 IDE 的帮助菜单项下,选择调试帮助上下文。
内容元数据
在下表中,出现在括号之间的任何字符串都是占位符,必须将其替换为可识别的值。 例如,在 <meta name=“Microsoft.Help.Locale” content=“[language code]” / > 中,“[language code]” 必须替换为“en-us”等值。
属性(HTML 声明) | 说明 |
---|---|
< meta name="Microsoft.Help.Locale" content="[language-code]" /> | 为该主题设置区域设置。 如果在主题中使用此标记,则必须仅使用一次,并且必须将其插入到任何其他 Microsoft 帮助标记的上方。 如果未使用此标记,则使用与产品区域设置关联的断字符(如果指定)对主题的正文文本编制索引;否则,将使用 en-us 断字符。 此标记符合 ISOC RFC 4646。 若要确保 Microsoft 帮助正常工作,请使用此属性而不是常规语言属性。 |
< meta name="Microsoft.Help.TopicLocale" content="[anguage-code]" /> | 当还使用其他区域设置时,设置该主题的区域设置。 如果在主题中使用此标记,则只能使用一次。 当目录包含多种语言的内容时,请使用此标记。 目录中的多个主题可以具有相同的 ID,但每个主题必须指定唯一的 TopicLocale。 指定与目录区域设置匹配的 TopicLocale 的主题是内容列表中显示的主题。 但是,该主题的所有语言版本都会显示在搜索结果中。 |
< title>[Title]</title> | 指定该主题的标题。 该标签是必需的,在一个主题中只能使用一次。 如果主题正文不包含标题 <div> 部分,则该标题将显示在主题和目录中。 |
< meta name=" Microsoft.Help.Keywords" content="[aKeywordPhrase]"/> | 指定在帮助查看器的索引窗格中显示的链接的文本。 单击链接时,将显示主题。 可为一个主题指定多个索引关键字,或者如果不希望指向该主题的链接出现在索引中,则可以省略此标记。 早期版本的帮助中的“K”关键字可以转换为此属性。 |
< meta name="Microsoft.Help.Id" content="[TopicID]"/> | 设置该主题的标识符。 该标签是必需的,在一个主题中只能使用一次。 该 ID 在目录中具有相同区域设置的主题中必须是唯一的。 可在另一个主题中使用此 ID 创建到该主题的链接。 |
< meta name="Microsoft.Help.F1" content="[System.Windows.Controls.Primitives.IRecyclingItemContainerGenerator]"/> | 指定该主题的 F1 关键字。 可为一个主题指定多个 F1 关键字,或者如果不希望在应用程序用户按 F1 时显示该主题,则可以省略此标记。 通常情况下,一个主题只能指定一个 F1 关键字。 早期版本的帮助中的“F”关键字可以转换为此属性。 |
< meta name="Description" content="[topic description]" /> | 提供该主题内容的简短摘要。 如果在主题中使用此标记,则只能使用一次。 该属性由查询库直接访问;不存储在于索引文件中。 |
meta name="Microsoft.Help.TocParent" content="[parent_Id]"/> | 指定目录中该主题的父主题。 该标签是必需的,在一个主题中只能使用一次。 该值是父级的 Microsoft.Help.Id。 一个主题在目录中只能有一个位置。 “-1”被认为是 TOC 根的主题 ID。 该页在 Visual Studio 2013 中是帮助查看器主页。 这与我们专门将 TocParent=-1 添加到某些主题以确保它们显示在顶层的原因相同。 帮助查看器主页是一个系统页面,因此不可替换。 如果 VSP 尝试添加 ID 为 -1 的页面,则该页面可能会添加到内容集中,但帮助查看器将始终使用系统页面 - 帮助查看器主页 |
< meta name="Microsoft.Help.TocOrder" content="[positive integer]"/> | 指定该主题在目录中相对于其对等主题的显示位置。 该标签是必需的,在一个主题中只能使用一次。 该值是一个整数。 指定较低值整数的主题将显示在指定较高值整数的主题上方。 |
< meta name="Microsoft.Help.Product" content="[product code]"/> | 指定该主题描述的产品。 如果在主题中使用此标记,则只能使用一次。 该信息还可以作为传递给帮助索引器的参数提供。 |
< meta name="Microsoft.Help.ProductVersion" content="[version number]"/> | 指定该主题描述的产品版本。 如果在主题中使用此标记,则只能使用一次。 该信息还可以作为传递给帮助索引器的参数提供。 |
< meta name="Microsoft.Help.Category" content="[string]"/> | 产品用于识别内容的子部分。 可为一个主题标识多个子部分,或者如果不希望链接标识任何子部分,则可以省略此标记。 当主题从早期版本的帮助转换时,此标记用于存储 TargetOS 和 TargetFrameworkMoniker 的属性。 内容的格式为 AttributeName:AttributeValue。 |
< meta name="Microsoft.Help.TopicVersion content="[topic version number]"/> | 当目录中存在多个版本时,指定主题的该版本。 由于不能保证 Microsoft.Help.Id 是唯一的,因此当目录中存在多个版本的主题时,例如,当目录包含 .NET Framework 3.5 的主题和 .NET Framework 4 的主题并且两者具有相同的 Microsoft.Help.Id 时,必须设置此标记。 |
< meta name="SelfBranded" content="[TRUE or FALSE]"/> | 指定本主题是使用帮助库管理器启动品牌包还是特定于该主题的品牌包。 该标签必须是 TRUE 或 FALSE。 如果为 TRUE,则关联主题的品牌包将覆盖在帮助库管理器启动时设置的品牌包,以便主题按预期呈现,即使它与其他内容的呈现不同。 如果为 FALSE,则根据启动帮助库管理器时设置的品牌包呈现当前主题。 默认情况下,除非 SelfBranded 变量声明为 TRUE,否则帮助库管理器假定自品牌为 FALSE;因此,不必声明 <meta name=“SelfBranded” content=“FALSE”/>。 |
创建品牌包
Visual Studio 版本包含许多不同的 Visual Studio 产品,包括 Visual Studio 合作伙伴的独立和集成 shell。 每一个产品都需要一定程度的基于主题的帮助内容品牌支持,这是产品所独有的。 例如,Visual Studio 主题需要具有一致的品牌表示形式,而包装 ISO Shell 的 SQL Studio 需要为每个主题提供自己独特的帮助内容品牌。 集成命令行管理程序合作伙伴可能希望其帮助主题位于父 Visual Studio 产品帮助内容中,同时维护自己的主题品牌。
品牌包使用包含帮助查看器的产品安装。 对于 Visual Studio 产品:
帮助查看器语言包在帮助查看器 2.3 应用根目录(例如:C:\Program Files (x86)\Microsoft Help Viewer\v2.3)中安装了回退品牌包 (Branding_<locale>.mshc)。 其将用于未安装产品品牌包(未安装任何内容)或已安装的品牌包已损坏的情况。 使用应用根回退品牌包时,将忽略 Visual Studio 元素(徽标和反馈)。
从内容包服务安装 Visual Studio 内容时,还会安装品牌包(首次安装内容方案)。 如果品牌包有更新,则在下一次内容更新或其他包安装操作发生时安装更新。
Microsoft 帮助查看器支持基于主题元数据的主题品牌。
如果主题元数据定义自品牌 = TRUE,则按原样呈现主题,不执行任何操作(就品牌而言)。
如果主题元数据定义自品牌 = FALSE,则使用与 TopicVendor 元数据值关联的品牌包。
其中主题元数据定义名称 =“Microsoft.Help.TopicVendor” content= < 供应商 MSHA 中的品牌包名称 >,请使用内容值中定义的品牌包。
Visual Studio 目录中,有品牌包的优先级应用程序。 首先应用 Visual Studio 默认品牌,然后,如果在主题元数据中定义并受关联的品牌包(如安装 MSHA 中所定义)所支持,则供应商定义的品牌将作为替代应用。
品牌元素通常分为三大类:
标题元素(示例包括反馈链接、条件免责声明文本、徽标)
内容行为(示例包括展开/折叠控件文本元素和代码片段元素)
页脚元素(例如版权)
被视为品牌元素的物品包括(在本规范中详细说明):
目录/产品徽标(例如 Visual Studio)
反馈链接和电子邮件元素
免责声明文本
版权文本
Visual Studio 帮助查看器品牌包中的支持文件包括:
图形(徽标、图标等)
Branding.js - 支持内容行为的脚本文件
Branding.xml - 跨目录内容统一使用的字符串。 注意:对于 branding.xml 中的 Visual Studio 本地化文本元素,请包含 _locID=“<唯一值>”
Branding.css - 用于表示一致性的样式定义
Printing.css - 一致的打印样式定义
如上所述,品牌包与主题相关联:
元数据中定义 SelfBranded = FALSE 时,主题将继承目录品牌包
或者,当 SelfBranded = FALSE,并且 MSHA 中定义了唯一的品牌包,并在安装内容时可用
对于实现自定义品牌包(VSP 内容,SelfBranded=True)的 VSP,一种继续操作的方法是从回退品牌包(随帮助查看器一起安装)开始,并根据需要更改文件的名称。 Branding_<locale.mshc> 文件是文件扩展名更改为 .mshc 的 zip 文件,因此只需将扩展名从 .mshc 更改为.zip并提取内容即可。 请参阅下文,了解品牌包元素并根据需要进行修改(例如,将徽标更改为 VSP 徽标,并在 Branding.xml 文件中引用徽标,根据 VSP 特定信息更新 Branding.xml等)。
完成所有修改后,创建一个包含所需品牌元素的 zip 文件,并将扩展名更改为 .mshc。
要关联自定义品牌包,请创建 MSHA,其中包含对品牌 mshc 文件的引用以及内容 mshc(包含主题)。 请参阅下面的“MSHA”,了解如何创建基本的 MSHA。
Branding.xml 文件包含一个元素列表,用于在主题包含 <meta name=“Microsoft.Help.SelfBranded” content=“false”/> 时一致呈现主题中的特定项目。 下面列出了 Branding.xml 文件中元素的 Visual Studio 列表。 此列表旨在用作 ISO Shell 应用者的模板,应用者可在其中修改这些元素(例如徽标、反馈和版权)以满足自己的产品品牌需求。
注意:“{n}”标记的变量具有代码依赖关系 - 删除或更改这些值将导致错误,并可能导致应用程序崩溃。 本地化标识符(例如 _locID=“codesnippet.n”)包含在 Visual Studio 品牌包中。
Branding.xml
元素 | 说明 |
---|---|
特征: | CollapsibleArea |
使用: | 展开折叠内容控件文本 |
元素 | 值 |
ExpandText | 展开 |
CollapseText | 折叠 |
特征: | CodeSnippet |
使用: | 代码片段控制文本。 注意:带有“非中断”空格的代码片段内容将更改为空格。 |
元素 | 值 |
CopyToClipboard | 复制到剪贴板 |
ViewColorizedText | 查看着色 |
CombinedVBTabDisplayLanguage | Visual Basic(示例) |
VBDeclaration | 声明 |
VBUsage | 使用情况 |
特征: | 反馈、页脚和徽标 |
使用: | 为客户提供反馈控件,以便通过电子邮件提供有关当前主题的反馈。 内容的版权文本。 徽标定义。 |
元素 | 值(可以修改这些字符串以满足内容应用者的需求。) |
版权 | © 2013 微软公司。 保留所有权利。 |
SendFeedback | <a href="{0}" {1}>在此主题下向 Microsoft 发送反馈 </a>。 |
FeedbackLink | |
LogoTitle | Visual Studio 2013 |
LogoFileName | vs_logo_bk.gif |
LogoFileNameHC | vs_logo_wh.gif |
特征: | 免责声明 |
使用: | 一组针对机器翻译内容的特定情况免责声明。 |
元素 | 值 |
MT_Editable | 本文为机器翻译。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
MT_NonEditable | 本文为机器翻译。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
MT_QualityEditable | 本文为人工翻译。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
MT_QualityNonEditable | 本文为人工翻译。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
MT_BetaContents | 本文为机器翻译的初步版本。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
MT_BetaRecycledContents | 本文为人工翻译的初步版本。 如果可以连接互联网,请选择“联机查看本主题”以可编辑模式查看此页面,同时查看英文原文内容。 |
特征: | LinkTable |
使用: | 支持联机主题链接 |
元素 | 值 |
LinkTableTitle | 链接表 |
TopicEnuLinkText | 查看计算机上提供的本主题英文版本</a>。 |
TopicOnlineLinkText | 联机查看本主题 <a href="{0}" {1}></a> |
OnlineText | 联机 |
特征: | 视频音频控件 |
使用: | 视频内容的显示元素和文本 |
元素 | 值 |
MultiMediaNotSupported | 必须安装 Internet Explorer 9 或更高版本才能支持 {0} 内容。 |
VideoText | 显示视频 |
AudioText | 流音频 |
OnlineVideoLinkText | <p>要查看与本主题关联的视频,请单击 {0}<a href="{1}">{2}此处</a>。</p> |
OnlineAudioLinkText | <p>要侦听与本主题关联的音频,请单击 {0}<a href="{1}">{2}此处</a>。</p> |
特征: | 未安装的内容控件 |
使用: | 用于呈现contentnotinstalled.htm的文本元素(字符串) |
元素 | 值 |
ContentNotInstalledTitle | 计算机上没有找到任何内容。 |
ContentNotInstalledDownloadContentText | <p>要将内容下载到计算机,<a href="{0}" {1}>点击管理选项卡 </a>。</p> |
ContentNotInstalledText | <p>计算机上未安装任何内容。 有关本地帮助内容的安装,请与管理员联系。</p> |
特征: | 未找到主题控件 |
使用: | 用于呈现 topicnotfound.htm 的文本元素(字符串) |
元素 | 值 |
TopicNotFoundTitle | 无法在计算机上找到请求的主题。 |
TopicNotFoundViewOnlineText | <p>所请求主题未在计算机上找到,但可 <a href="{0}" {1}>联机查看主题</a>。</p> |
TopicNotFoundDownloadContentText | <p>有关指向类似主题的链接,请参阅导航窗格,或 <a href="{0}" {1}>单击管理选项卡</a> 以将内容下载到计算机。</p> |
TopicNotFoundText | <p>计算机上未找到请求的主题。</p> |
特征: | 主题已损坏控件 |
使用: | 用于呈现 topiccorrupted.htm 的文本元素(字符串) |
元素 | 值 |
TopicCorruptedTitle | 无法显示请求的主题。 |
TopicCorruptedViewOnlineText | <p>帮助查看器无法显示请求的主题。 主题的内容或底层系统依赖项中可能存在错误。</p> |
特征: | 主页控件 |
使用: | 支持显示帮助查看器顶级节点内容的文本。 |
元素 | 值 |
HomePageTitle | 帮助查看器主页 |
HomePageIntroduction | <p>欢迎使用 Microsoft 帮助查看器,该查看器是使用 Microsoft 工具、产品、技术和服务的每个人的重要信息来源。 可借助帮助查看器访问操作指南和参考信息、示例代码、技术文章等。 要查找所需内容,请浏览目录、使用全文搜索或使用关键字索引进行浏览。</p> |
HomePageContentInstallText | <p><br />使用 <a href=“{0}” {1}>管理内容</a> 选项卡执行以下操作:<ul><li>将内容添加到计算机。</li li><>检查本地内容的更新。</li li><>从计算机中删除内容。</li></ul></p> |
HomePageInstalledBooks | 已安装的书籍 |
HomePageNoBooksInstalled | 计算机上没有找到任何内容。 |
HomePageHelpSettings | 帮助内容设置 |
HomePageHelpSettingsText | <p>当前设置是本地帮助。 帮助查看器显示计算机上已安装的内容。<br />若要更改帮助内容的源,请在 Visual Studio 菜单栏上选择 <span style=“{0}帮助>, 设置帮助偏好</span>.<br /></p> |
MegaByte | MB |
branding.js
branding.js 文件包含 Visual Studio 帮助查看器品牌元素使用的 JavaScript。 下面是品牌元素和支持 JavaScript 函数的列表。 该文件中要本地化的所有字符串都在该文件顶部的“可本地化字符串”部分中定义。 已在 branding.js 文件中为 loc 字符串创建了 ICL 文件。
品牌功能 | JavaScript 函数 | 描述 |
---|---|---|
Var ... | 定义变量 | |
获取用户代码语言 | setUserPreferenceLang | 将索引 # 映射到代码语言 |
设置和获取 Cookie 值 | getCookie、setCookie | |
继承的成员 | changeMembersLabel | 展开/折叠继承的成员 |
当 SelfBranded=False | OnLoad | 读取查询字符串以检查是否为打印请求。 将所有代码片段设置为聚焦于用户首选选项卡。如果是打印请求,则将 isPrinterFriendly 设置为 true。 检查高对比度模式。 |
代码片段 | addSpecificTextLanguageTagSet | |
getIndexFromDevLang | ||
ChangeTab | ||
setCodesnippetLang | ||
setCurrentLang | ||
CopyToClipboard | ||
CollapsibleArea | addToCollapsibleControlSet | 将所有可折叠控制对象写入列表中。 |
CA_Click | 根据可折叠区域的状态,定义要呈现的图像和文本 | |
徽标对比度支持 | isBlackBackground() | 调用来确定背景是否为黑色。 仅在高对比度模式下准确。 |
isHighContrast() | 使用彩色跨度来检测高对比度模式 | |
onHighContrast(black) | 检测到高对比度时调用 | |
LST 功能 | ||
addToLanSpecTextIdSet(id) | ||
updateLST(currentLang) | ||
getDevLangFromCodeSnippet(lang) | ||
多媒体函数 | caption(begin, end, text, style) | |
findAllMediaControls(normalizedId) | ||
getActivePlayer(normalizedId) | ||
captionsOnOff(id) | ||
toSeconds(t) | ||
getAllComments(node) | ||
styleRectify(styleName, styleValue) | ||
showCC(id) | ||
subtitle(id) |
HTM 文件
品牌包包含一组 HTM 文件,这些文件支持将关键信息传达给帮助内容用户的方案,例如,主页包含描述已安装哪些内容集的部分,以及在本地主题集中找不到主题时告知用户的页面。 这些 HTM 文件可以针对每个产品进行修改。 ISO Shell 供应商能够采用默认的品牌包,并更改这些页面的行为和内容以满足他们的需要。 这些文件引用其各自的品牌包,以便品牌标签从branding.xml文件中获取相应的内容。
文件 | 用途 | 显示的内容来源 |
---|---|---|
homepage.htm | 此页面显示当前安装的内容,以及适合向用户显示的有关其内容的任何其他消息。 此文件具有附加的元数据属性“Microsoft.Help.Id”content=“-1”,该属性将此内容置于本地内容目录的顶部。 | |
<META_HOME_PAGE_TITLE_ADD /> | Branding.xml,标记 <HomePageTitle> | |
<HOME_PAGE_INTRODUCTION_SECTION_ADD /> | Branding.xml,标记 <HomePageIntroduction> | |
<HOME_PAGE_CONTENT_INSTALL_SECTION_ADD /> | Branding.xml,标记 <HomePageContentInstallText> | |
<HOME_PAGE_BOOKS_INSTALLED_SECTION_ADD /> | 标记 <HomePageInstalledBooks> 的标题部分Branding.xml未安装书籍时从应用程序 <HomePageNoBooksInstalled> 生成的数据。 | |
<HOME_PAGE_SETTINGS_SECTION_ADD /> | 标题部分 Branding.xml 标记 <HomePageHelpSettings>,部分文本 <HomePageHelpSettingsText>。 | |
topiccorrupted.htm | 当主题存在于本地集中,但由于某种原因无法显示(内容损坏)时。 | |
<META_TOPIC_CORRUPTED_TITLE_ADD /> | Branding.xml,标记 <TopicCorruptedTitle> | |
<TOPIC_CORRUPTED_SECTION_ADD /> | Branding.xml,标记 <TopicCorruptedViewOnlineText> | |
topicnotfound.htm | 当在本地内容集中找不到主题,也无法联机获得时 | |
<META_TOPIC_NOT_FOUND_TITLE_ADD /> | Branding.xml,标记 <TopicNotFoundTitle> | |
<META_TOPIC_NOT_FOUND_ID_ADD /> | Branding.xml,标记 <TopicNotFoundViewOnlineText> + <TopicNotFoundDownloadContentText> | |
<TOPIC_NOT_FOUND_SECTION_ADD /> | Branding.xml,标记 <TopicNotFoundText> | |
contentnotinstalled.htm | 当产品没有安装本地内容时。 | |
<META_CONTENT_NOT_INSTALLED_TITLE_ADD /> | Branding.xml,标记 <ContentNotInstalledTitle> | |
<META_CONTENT_NOT_INSTALLED_ID_ADD /> | Branding.xml,标记 <ContentNotInstalledDownloadContentText> | |
<CONTENT_NOT_INSTALLED_SECTION_ADD /> | Branding.xml,标记 <ContentNotInstalledText> |
CSS 文件
Visual Studio 帮助查看器品牌包包含两个 css 文件,以支持一致的 Visual Studio 帮助内容表示:
Branding.css - 包含用于呈现 SelfBranded=false 的 css 元素
Printer.css - 包含用于呈现 SelfBranded=false 的 css 元素
Branding.css 文件包括 Visual Studio 主题表示的定义(需要注意的是,包服务中 Branding_<locale>.mshc 中包含的 branding.css 可能会更改)。
图形文件
Visual Studio 内容显示 Visual Studio 徽标以及其他图形。 Visual Studio 帮助查看器品牌包中的图形文件的完整列表如下所示。
文件 | 用途 | 示例 |
---|---|---|
clear.gif | 用于呈现可折叠区域 | |
footer_slice.gif | 页脚演示文稿 | |
info_icon.gif | 显示信息时使用 | 免责声明 |
online_icon.gif | 此图标将与联机链接相关联 | |
tabLeftBD.gif | 用于呈现代码片段容器 | |
tabRightBD.gif | 用于呈现代码片段容器 | |
vs_logo_bk.gif | 用于Branding.xml 标记 <LogoFileName> 中定义的普通对比度徽标引用。 Visual Studio 产品的徽标名称为 vs_logo_bk.gif。 | |
vs_logo_wh.gif | 用于 Branding.xml 标记 <LogoFileNameHC> 中定义的高对比度徽标引用。 Visual Studio 产品的徽标名称为 vs_logo_wh.gif。 | |
ccOff.png | 辅助字幕图形 | |
ccOn.png | 辅助字幕图形 | |
ImageSprite.png | 用于呈现可折叠区域 | 展开或折叠图形 |
部署一组主题
这是一个简单而快速的教程,用于创建由 MSHA 文件和包含主题的 cab 或 MSHC 集组成的帮助查看器内容部署集。 MSHA 是一个 XML 文件,描述了一组 cab 或 MSHC 文件。 帮助查看器可以读取 MSHA 以获得可用于本地安装的内容列表(. cab 或. mshc 文件)。
这只是描述帮助查看器 MSHA 的基本 XML 架构的入门指南。 此处提供一个示例实现,下面是一个简短的概述和示例 HelpContentSetup.msha。
在本入门教程中,MSHA 的名称是 HelpContentSetup.msha(文件的名称可以是任何名称,扩展名为 .msha)。 HelpContentSetup.msha(如下所示)应包含相应的 cabs 或 MSHC 列表。 文件类型在 MSHA 中必须一致(不支持 MSHA 和 CAB 文件类型的组合)。 对于每个 CAB 或 MSHC,应有 div <class=“包”>...</div> (请参阅下方示例)。
注意:下方的的实现示例中包含了品牌包。 为了获取所需的 Visual Studio 内容呈现元素和内容行为,必须包含这一点。
示例 HelpContentSetup.msha 文件:(将“内容集名称 1”和“内容集名称 2”等替换为文件名。)
<html>
<head />
<body class="vendor-book">
<div class="details">
<span class="vendor">Your Company</span>
<span class="locale">en-us</span>
<span class="product">Your Company Help Content</span>
<span class="name">Your Company Help Content</span>
</div>
<div class="package-list">
<div class="package">
<span class="name">Your_Company _Content_Set_1</span>
<span class="deployed">True</span>
<a class="current-link" href="Your_Company _Content_Set_1.mshc">Your_Company _Content_Set_1.mshc </a>
</div>
<div class="package">
<span class="name">Your_Company _Content_Set_2</span>
<span class="deployed">True</span>
<a class="current-link"href=" Your_Company _Content_Set_2.mshc "> Your_Company _Content_Set_2.mshc </a>
</div>.
创建类似于“C:\SampleContent”的本地文件夹
在本例中,我们将使用 MSHC 文件来包含主题。 MSHC 是一个 zip 文件,文件扩展名从 .zip 更改为 .MSHC。
将下面的 HelpContentSetup.msha 创建为文本文件(使用记事本创建文件),并将其保存到上述文件夹中(请参阅步骤 1)。
类“品牌”存在且唯一。 品牌 mshc 包含在本入门中,以便安装的内容具有品牌,并且 MSHC 中包含的内容行为具有品牌包中包含的适当支持元素。 如果没有该品牌包,当系统寻找不属于已下载(已安装)内容的支持项时,将产生错误。
获取 Visual Studio 品牌包,请将 C:\Program Files (x86)\Microsoft Help Viewer\v2.3\ 下的 Branding_en-US.mshc 文件复制到工作文件夹。
<html>
<head />
<body class="vendor-book">
<div class="details">
<span class="vendor">Your Company</span>
<span class="locale">en-us</span>
<span class="product">Your Company Help Content</span>
<span class="name">Your Company Help Content</span>
</div>
<div class="package-list">
<div class="package">
<span class="name">Your_Company _Content_Set_1</span>
<span class="deployed">True</span>
<a class="current-link" href="Your_Company _Content_Set_1.mshc">Your_Company _Content_Set_1.mshc </a>
</div>
<div class="package">
<span class="name">Your_Company _Content_Set_2</span>
<span class="deployed">True</span>
<a class="current-link"href=" Your_Company _Content_Set_2.mshc "> Your_Company _Content_Set_2.mshc </a>
</div>
<div class="package">
<span class="packageType">branding</span>
<span class="name">Branding_en-US</span>
<span class="deployed">True</span>
<a class="current-link" href="Branding_en-US.mshc">Branding_en-US.mshc</a>
</div>
</div>
</body>
</html>
总结
使用和扩展上述步骤将使 VSP 能够为 Visual Studio 帮助查看器部署其内容集。
向 Visual Studio Shell(集成或独立)添加帮助
介绍
本演练演示如何将帮助内容合并到 Visual Studio Shell 应用程序中并进行部署。
要求
Visual Studio 2013
概述
Visual Studio 2013 Shell 是 Visual Studio 2013 IDE 的一个版本,你可基于该版本构建应用程序。 此类应用程序包含独立 Shell 以及所创建的扩展。 使用 Visual Studio 2013 SDK 中包含的独立 Shell 项目模板构建扩展。
创建基于 Shell 的独立应用程序及其帮助的基本步骤:
获取 Visual Studio 2013 ISO Shell 可再发行组件(Microsoft 下载)。
在 Visual Studio 中,创建一个基于独立 Shell 的帮助扩展,例如,本演练后面介绍的 Contoso 帮助扩展。
将扩展和 ISO Shell 可再发行组件包装到部署 MSI(应用程序设置)中。 本演练不包括安装步骤。
创建 Visual Studio 内容存储。 对于集成 Shell 方案,请将 Visual Studio12 更改为产品目录名称,如下所示:
创建文件夹 C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio15.。
创建名为 CatalogType.xml 的文件并将其添加到文件夹中。 该 XML 文件应包含以下代码行:
<?xml version="1.0" encoding="UTF-8"?> <catalogType>UserManaged</catalogType>
在注册表中定义内容存储。 对于集成命令行管理程序,请将 VisualStudio15 更改为产品目录名称:
HKLM\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Catalogs\VisualStudio15
键:LocationPath 字符串值:C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio15\
HKLM\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Catalogs\VisualStudio15\en-US
键:CatalogName 字符串值:Visual Studio 2013 Documentation
创建项目
要创建独立 Shell 扩展,请执行以下操作:
在 Visual Studio 中,在文件下,选择新建项目,在其他项目类型下选择扩展性,然后选择 Visual Studio 独立 Shell。 将项目命名为
ContosoHelpShell
),以创建基于 Visual Studio 独立 Shell 模板的扩展性项目。在解决方案资源管理器的 ContosoHelpShellUI 项目的资源文件文件夹中,打开 ApplicationCommands.vsct。 请确保注释掉此行(search for "No_Help"):
<!-- <define name="No_HelpMenuCommands"/> -->
选择 F5 键来编译并运行调试。 在独立 Shell IDE 的实验实例中,选择帮助菜单。 确保显示查看帮助、添加和删除帮助内容和设置帮助首选项命令。
在解决方案资源管理器的ContosHelpShell项目的Shell 自定义文件夹中,打开 ContosoHelpShell.pkgdef。 要定义 Contoso 帮助目录,请添加以下行:
[$RootKey$\Help] "Product"="Contoso" "Catalog"="Contoso" "Version"="100" "BrandingPackage"="ContosoBrandingPackage.mshc"
在解决方案资源管理器的ContosHelpShell项目的Shell 自定义文件夹中,打开 ContosoHelpShell.Application.pkgdef。 要启用 F1 帮助,请添加以下行:
// F1 Help Provider [$RootKey$\HelpProviders\{C99BDC23-FF29-46bf-9658-ADD634CCAED8}] "Name"="13407" "Package"="{DA9FB551-C724-11d0-AE1F-00A0C90FFFC3}" @="Help3 Provider" [$RootKey$\HelpProviders] @="{C99BDC23-FF29-46bf-9658-ADD634CCAED8}" [$RootKey$\Services\{C99BDC23-FF29-46bf-9658-ADD634CCAED8}] "Name"="Help3 Provider" @="{4A791146-19E4-11D3-B86B-00C04F79F802}"
在解决方案资源管理器的关联菜单上,选择属性菜单项。 在配置属性下,选择配置管理。 在配置列中,将每个调试值更改为“Release”。
生成解决方案。 这将在发布文件夹中创建一组文件,这些文件将在下一节中使用。
参照部署过程进行测试:
在要部署 Contoso 的计算机上,安装下载的ISO Shell(如上所示)。
在 \\Program Files (x86)\ 中创建文件夹并将其命名为
Contoso
。将 ContosoHelpShell 发布文件夹中的内容复制到 \\Program Files (x86)\Contoso\ 文件夹。
通过选择开始菜单中的运行并输入
Regedit
来启动注册表编辑器。 在注册表编辑器中,选择文件,然后选择导入。 浏览 ContosoHelpShell 项目文件夹。 在 ContosoHelpShell 子文件夹中,选择 ContosoHelpShell.reg。创建内容存储:
对于 ISO Shell - 创建 Contoso 内容存储 C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\ContosoDev12
对于 Visual Studio 2013 集成 Shell,请创建文件夹 C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio15
创建 CatalogType.xml 并添加到内容存储(如上一步所述),其中包含:
<?xml version="1.0" encoding="UTF-8"?> <catalogType>UserManaged</catalogType>
添加以下注册表项:
HKLM\SOFTWARE\Wow6432Node\Microsoft\Help\v2.3\Catalogs\VisualStudio15 键:LocationPath 字符串值:
对于 ISO Shell:
C:ProgramDataMicrosoftHelpLibrary2CatalogsVisualStudio15
Visual Studio 2013 集成 Shell:
C:ProgramDataMicrosoftHelpLibrary2CatalogsVisualStudio15en-US
键:CatalogName 字符串值:Visual Studio 2013 Documentation。 对于 ISO Shell,这是目录的名称。
将内容(cabs 或 MSHC 和 MSHA)复制到本地文件夹。
用于测试内容存储的集成 Shell 命令行示例。 对于 ISO Shell,请根据需要更改目录和 launchingApp 值以匹配产品。
"C:\Program Files (x86)\Microsoft Help Viewer\v2.3\HlpViewer.exe" /catalogName VisualStudio15 /helpQuery method="page&id=ContosoTopic0" /launchingApp Microsoft,VisualStudio,12.0
启动 Contoso 应用程序(从 Contoso 应用程序根目录)。 在 ISO Shell 中,选择帮助菜单项,并将设置帮助首选项更改为使用本地帮助。
在 shell 中,选择 帮助菜单项,然后选择查看帮助。 将启动本地帮助查看器。 选择管理内容选项卡。在安装源下,选择磁盘选项按钮。 选择 ... 按钮并浏览到包含 Contoso 内容的本地文件夹(复制到上述步骤中的本地文件夹)。 选择 HelpContentSetup.msha。 现在,Contoso 应该在图书选择中显示为图书。 选择添加,然后选择更新按钮(右下角)。
在 Contoso IDE 中,选择 F1 键来测试 F1 功能。
其他资源
有关运行时 API,请参阅 Windows 帮助 API。
有关如何利用帮助 API 的详细信息,请参阅帮助查看器代码示例。
可在开发者社区提交功能建议。