如何：使用自定义属性自定义内容查询 Web 部件
上次修改时间： 2015年3月9日
适用范围： SharePoint Server 2010
您可以使用内容查询 Web 部件创建从多个源查询到的数据的自定义视图，并在一个位置集中显示所有数据。将内容查询 Web 部件添加到网页后，您可以通过设置自定义属性来自定义该 Web 部件的查询行为、自定义列表和内容类型。ContentByQueryWebPart 类有 60 个可用的属性和方法，您可以自定义其中的许多属性和方法。本主题介绍其中的一些属性，并包括您可以添加到 .webpart 文件的协作应用程序标记语言 (CAML) 格式的语法和用法示例。
一些 Microsoft SharePoint Server 2010 内容查询 Web 部件属性是从 Microsoft SharePoint Foundation 继承的，而其他属性是 SharePoint Server 2010 所特有的。本主题重点介绍 SharePoint Server 2010 中引入的属性。下面是 SharePoint Server 2010 内容查询 Web 部件属性的两个基本类别：
设置或替代 Web 部件基础行为的某一个方面的属性。在某些情形下，这些属性还会影响用户界面 (UI)。
修改 Web 部件 UI 而不设置或替代基础行为的属性。
修改 UI 和行为的属性
第一组中的属性（如替代）通常功能较强，因为您可以使用它们修改 Web 部件的行为。如果用户尝试修改 UI 或设置可影响此属性所影响的行为的其他属性，则此属性在 UI 中"优先"；它会替代其他设置，并决定内容查询 Web 部件的行为。当您要执行下列操作时，这些属性非常有用：
添加永久性字段和字段选项
替代默认跨列表查询行为，以使对 UI 中的字段和字段选项所做的更改持续存在，并且无法被其他更改覆盖或破坏
将较长的复合列名重命名为更常见的 XSLT 转换变量名，并避免为每个架构创建自定义 XSLT 转换
表 1 描述一些用于修改 UI 和行为的属性。
表 1. 用于修改 UI 和行为的属性
属性 |
说明 |
|---|---|
请求其他字段，由于内容查询 Web 部件不自动返回所有项的所有字段，因此该属性是必需的。您必须请求要在 XSLT 转换中呈现的字段。 此属性为附加的，这意味着您可以将多个 CommonViewField 添加到内容查询 Web 部件并扩展其基本属性，如 FieldDescription 和 FieldLabel。 |
|
绕过内容查询 Web 部件 UI 对查询行为施加的限制。这样便能指定 CAML 中跨列表查询的查询部分。 当设置 QueryOverride 属性时，用于筛选、排序和分组的 UI 在工具窗格中将灰显。例如，默认情况下，内容查询 Web 部件将启用三个筛选器，您可能需要添加更多的筛选器并确保自定义字段和行为在 UI 中持续存在。 |
|
确定跨列表查询是否应递归子网站。默认情况下，SharePoint Server 2010 会递归子网站，意味着将显示父网站及其子网站。 当设置 WebsOverride 属性时，内容查询 Web 部件将不进行递归，而只显示指定网站的结果。 |
|
替代 SharePoint Server 2010 中的列表行为，支持多种类型的列表，如网页库、常规列表基本类型和特定列表类型。您可以使用此自定义属性设置任何列表类型，甚至那些因该模板未在根目录中定义或它是基本类型而未在 UI 中枚举的列表类型。 Windows SharePoint Services 3.0 SDK 中的 List 元素参考主题中定义了列表类型。 |
|
使内容查询 Web 部件能够从您指定的查询请求一组字段，而不是在 SharePoint Server 2010 中发出针对基本字段的自动请求。 |
|
使内容查询 Web 部件能够在将数据传递到 XSLT 转换以进行呈现前重命名列。 |
修改 UI 而不替代行为的属性
此外，您可能需要权重较小的选项来自定义 UI 中的字段、字段选项、分组和排序选项以及筛选器选项。这些自定义不会影响基础行为，且可以由第一组中的属性替代，这些属性能够替代行为。如果您想要执行下列操作，则这样的自定义非常有用：
通过内容查询 Web 部件，添加比最初将 Web 部件的实例添加到页面时设置的更多的选项
仅影响一个不太可能被替代的 Web 部件
为最终用户提供多个可用选项
表 2 描述了此组中的一些属性。
表 2. 不替代行为的属性
属性 |
说明 |
|---|---|
包括一个或多个通常不在 UI 中的筛选器下拉列表中显示的其他字段（AdditionalFilterFields 属性）或分组和排序选项（AdditionalGroupAndSortFields 属性）。如果未将某字段作为网站栏配置，但它在一些列表中显示并且应在 UI 中可用，则此属性非常有用。当设置此属性时，UI 提供此列用于筛选。 |
|
包括筛选 UI 不支持的值的功能。使用这些属性可预填充一些 UI 值，如首次将 Web 部件添加到页面时。例如，您可能希望指定默认值，及筛选与今天的日期相对的日期范围。 |
自定义内容查询 Web 部件的方法
可通过多种方法设置或修改内容查询 Web 部件中的自定义属性，所选方法取决于您的目标以及您在网站和网站设计流程中的位置。例如，如果自定义现有页面布局，则可在自定义页面布局时使用 Microsoft SharePoint Designer 2010 并自定义内容查询 Web 部件。如果为现有页面布局创建新的自定义内容查询 Web 部件，则可以使用 SharePoint Designer 2010 添加或修改自定义属性。
若要修改现有内容查询 Web 部件的自定义属性，则可导出 .webpart 文件，创建该文件的副本并重命名原件，修改 .webpart 文件副本中的自定义属性，然后将其导入页面中的 Web 部件区域。重命名原始 .webpart 文件可确保留原始 .webpart 文件的副本以用于将来升级。
导出 .webpart 文件，设置其自定义属性，然后将其导入
登录到您的网站。
在"网站操作"菜单上，单击"编辑页面"。
在页面上找到内容查询 Web 部件，然后在该 Web 部件的"编辑"菜单上，单击"导出"。
保存该 .webpart 文件。
重命名该 .webpart 文件，然后使用文本编辑器或 SharePoint Designer 2010 打开重命名的文件。
备注
重命名原始 .webpart 文件可确保留原始 .webpart 文件的副本以用于将来升级。
添加或修改属性和属性值，然后保存更改。
在"页面"菜单上，指向"添加 Web 部件"，然后单击"浏览"。
从"Web 部件列表"选择要导入的 Web 部件，然后单击"确定"。
将该 Web 部件拖到页面上的 Web 部件区域。
示例
说明
本节描述了自定义属性，并包含针对内容查询 Web 部件中的自定义属性语句和 CAML 查询的格式设置和代码示例。首先，我们介绍了格式设置、基本字段信息和有关使用 CommonViewFields 属性的提示。紧接着，我们将呈现了一个完整的 CAML 查询，然后演练该查询设置的 QueryOverride、ListsOverride、WebsOverride 和 ViewFieldsOverride 属性。可以将 CAML 查询中呈现的每个属性值添加到 .webpart 文件中与该属性值对应的 <property value> 语句。最后，我们将呈现 DataColumnRenames 属性以及筛选器、分组和排序选项属性。
CommonViewFields 属性
自定义 CommonViewFields 属性时，您可以使用两种格式。可以按其内部名称或者内部名称和域名的组合来指定字段，如下所示：
字段的内部名称
字段的内部名称, 字段类型
用于特殊字符的批注可区分内部名称和 UI 中使用的名称。例如，在内部名称中，字与字之间的空格由 _x0020_ 表示。您可以通过查看"网站栏"页面中的查询字符串参数或者在创建字段后查看 Web 部件代码来查看内部名称。可以通过设置用于筛选字段的 Web 部件来查看 Web 部件代码，方法是导出该 Web 部件，然后查看筛选器属性。
备注
有关 CommonViewField 属性可请求的其他 field types 的列表，请参阅 SharePoint Foundation 2010 SDK 中的 SPFieldType 枚举。SharePoint Server 2010 包括您可以请求的四个其他字段：HTML、Image、Link 和 SummaryLink。本主题列出的常量用于标识 CommonViewFields 属性可包括的数据类型。
您还可以将 CommonViewFields 定义合并到复合语句中，在一个属性语句中设置多个字段时，这样做非常有用。在一个语句中合并定义时，请使用分号分隔这些字段。例如：
字段的内部名称; 字段的内部名称, 字段类型
CommonViewFields 是附加属性，这意味着您可以在内容查询 Web 部件始终请求的基本字段的顶部添加一个常用视图字段。基本字段按 GUID 请求默认列，这些字段在 UI 中显示为网站栏名称。表 3 列出了基本字段名称和类型。
表 3. 基本字段名称和类型
名称 |
类型 |
|---|---|
Title |
Text |
FileRef |
Lookup |
ID |
Counter |
Modified |
DateTime |
Author |
"User" |
Editor |
User |
Created |
DateTime |
PublishingRollupImage |
Image |
Level |
"Number" |
Note |
"Note" |
在下面的示例中，CommonViewFields 属性用于设置 GUID，SharePoint Server 2010 可内部使用该 GUID 来引用字段的内部名称、字段类型、CommonViewField 的内部名称及其基本类型，后面跟基本类型的 GUID。
<property name="CommonViewFields" type="string">_Level,Number;PublishingRollupImage;</property>
QueryOverride、ListsOverride、WebsOverride 和 ViewFieldsOverride 属性
每个替代属性（QueryOverride、ListsOverride、WebsOverride 和 ViewFieldsOverride）可替代默认的内容查询 Web 部件的行为。若要替代某行为，请构造可定义您要设置的条件的 CAML 查询。
备注
若要了解有关 CAML 语法和命令的详细信息，请参阅 SharePoint Foundation 2010 SDK 中的 协作应用程序标记语言核心架构。
在下面的示例中，我们演示使用 CAML 查询为内容查询 Web 部件设置自定义属性。CAML 查询可执行下列操作：
检索 Created 字段
设置用于检索前 7 天更新的项目的查询并按降序顺序对这些项目进行排序
指定要从中查询的列表类型
以递归方式从指定网站及其子网站检索数据
检索要为每个项目显示的特定字段的值
将显示整个查询，下面几部分会详细进行描述。
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
5 <Lists ServerTemplate="850"></Lists>
6 <Webs Recursive="True" />
7 <RowLimit>15</RowLimit>
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>]]>
QueryOverride 属性
第 8 至 19 行用于定义 QueryOverride 属性。
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>
19 </Query>]]>
在上面的示例中：
第 8 至 10 行用于定义查询并打开 <where> 子句。
第 11 行引用名称为"Created"的基本字段类型，并且其字段类型为 DateTime。
第 12 行用于将此字段的值设置为 DateTime，并设置偏移量 -7，意味着要从查询筛选的日期减去 7。
第 13 和 14 行用于关闭 <where> 子句。
第 15 行用于打开 <OrderBy> 子句，该子句为在其中指定的字段确定排序顺序。
第 16 和 17 行用于设置"Created"字段的排序顺序。Web 部件以降序显示此数据。
ListsOverride 属性
您还可以使用 CAML 查询从 SharePoint Foundation 2010 和 SharePoint Server 2010 列表检索项目。表 4 演示三个从不同的列表类型检索项目的 CAML 语句示例。
表 4. 从不同的列表类型检索项目的三个 CAML 语句示例
列表类型 |
Property 语句 |
|---|---|
网页库 |
|
常规列表基本类型 |
|
特定列表类型 |
|
在此示例中，第 5 行用于定义 ListsOverride 属性。
5 <Lists ServerTemplate="850"></Lists>
在此示例中，查询使用 ServerTemplate="850" 替代当前使用的列表。您可以在 SharePoint Foundation 2010 SDK 的 Lists 属性中查找可用列表类型的枚举。
WebsOverride 属性
您可以使用 CAML 设置 WebsOverride 属性，从而以递归方式检索项目，如下面的代码示例所示。
<![CDATA[
<Webs Recursive="True"/>
]]>
或者仅从指定的网站检索项目。
<![CDATA[
<Webs/>
]]>
在此示例的第 6 行，我们将属性设置为以递归方式检索项目。
6 <Webs Recursive="True"/>
ViewFieldsOverride 属性
若要在 Web 部件中显示任何项目的值，请将 ViewFieldsOverride 属性设置为从指定字段检索指定类型的数据，如下面的代码示例所示。
<![CDATA[
<FieldRef Name="Comments" Nullable="True" Type="Note"/>
<FieldRef Name="Created" Nullable="False" Type="User"/>
]]>
设置 Nullable="True" 将返回不包含此列的项目。
在此代码示例中，第 1 至 4 行用于设置 ViewFieldsOverride 属性：
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
第 1 行打开 <ViewFields> 子句，该子句可设置 ViewFieldsOverride 属性。
第 2 和 3 行引用 Title 字段（文本字段）和 Comments 字段（说明字段）。
第 4 行关闭 <ViewFields> 部分。
DataColumnRename 属性
使用 DataColumnRename 属性可以编程方式重命名列。此属性可帮助您最小化 XSLT 和架构自定义，可执行批量或自定义列重命名操作。例如，您可以将复合列名称（如 KBArticleTitle）重命名为一般 XSLT 转换变量名（如 Title），且无需为每个自定义架构创建自定义 XSLT 转换。
使用分号分隔列命名值，并使用如下格式：originalName,newName。
<![CDATA[<property name="DataColumnRenames" type="string">KBArticleTitle,Title</property>]]
备注
如果您使用已存在的名称重命名某列，则重命名操作失败。
其他字段、筛选器、分组和排序选项
设置此组中的属性可添加字段、分组、分组和排序选项、筛选器和筛选器选项。您可以按字段的内部名称、GUID、内部名称和显示名称的组合或 GUID 和显示名称来指定字段。
通过使用以下任一格式定义 AdditionalFilterFields 和 AdditionalGroupAndSortFields 属性：
internalName
internalName,DisplayName
GUID
GUID,DisplayName
您还可以将 AdditionalFilterFields 和 AdditionalGroupAndSortFields 定义合并到复合语句中，在一个属性语句中设置多个字段时，这样做非常有用。在一个语句中合并定义时，可使用分号分隔这些字段，如下所示：
internalName;GUID; internalName,DisplayName;GUID,DisplayName
通过设置 AdditionalFilterFields 属性，您可以将 Created 筛选器字段添加到 UI，如下面的代码示例所示。
<![CDATA[<property name="AdditionalFilterFields" type="string">Created</property>]]
通过设置 AdditionalGroupAndSortFields 属性，您可以将"创建时间"选项添加到 UI 中的分组和排序列表中。
<!CDATA[<property name="AdditionalGroupAndSortFields" type="string">Created</property>]]
筛选器属性
您可以使用自定义属性来扩展 UI 不支持的筛选器值。设置或修改任意筛选器字段、筛选器类型、筛选器值或筛选器链接运算符属性，可添加或更改 UI 中的筛选器行为。
备注
筛选器属性不会替代 UI；它们会使用默认值预填充 UI。
筛选器字段、筛选器类型和筛选器值属性的类型通常为 string：
<property name="FilterField1" type="string" />
<property name="FilterType1" type="string" />
<property name="FilterValue1" type="string" />
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
下面的示例筛选器代码显示 DateTime 格式的"创建时间"筛选器，并显示在 2011 年 10 月 25 日之后创建的项目：
<property name="FilterField1" type="string">Created</property>
<property name="FilterType1" type="string">DateTime</property>
<property name="FilterValue1" type="string">Today-7</property>
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
可使用下面的格式在筛选器运算符和筛选器链接运算符属性语句中设置 type 参数：PropertyName、namespace、Version、Culture、PublicKeyToken。
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
<property name="Filter1ChainingOperator" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterField, Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Eq</property>
筛选器运算符和筛选器链接运算符属性的有效值是不同的，如下所示：
筛选器运算符属性在 UI 中显示"And"和"Or"按钮。
筛选器链接运算符属性填充 UI 的"其他筛选器"部分中的"以下情况下显示项目"中的第二个字段。
表 5 提供了筛选器运算符属性的有效值。
表 5. 筛选器运算符属性的有效值
值 |
显示值 |
|---|---|
And |
And |
Or |
或者 |
表 6 提供了筛选器链接运算符属性的有效值。
表 6. 筛选器链接运算符属性的有效值
值 |
显示值 |
|---|---|
Eq |
等于 |
Neq |
不等于 |
Gt |
大于 |
Geq |
大于或等于 |
Lt |
小于 |
Leq |
小于或等于 |
BeginsWith |
始于 |
Contains |
包含 |