SharePoint服务器端对象模型 之 访问网站和列表数据（Part 5）

（五）列表条目（SPListItem）

SharePoint中数据的存储基本上都是通过列表条目来完成（文档库中的文档也是一种特殊的列表条目），因此在SharePoint应用开发中，最终是要和列表条目打交道的。在SharePoint对象模型中，使用SPListItem表示列表条目，使用SPListItemCollection表示列表条目集合。

 

1、列表条目的获取

列表条目的获取有多种方式，一些常用方式如下：

（1） 通过SPList的Items属性，获取列表中的所有条目（不包括文件夹本身对应的条目），再通过foreach遍历的形式遍历其中的所有条目；或使用形如[idx]的int型索引器获取其中的某个条目。当我们需要遍历一个列表中所有条目、或文档库中所有文档的时候（不论它们属于哪个子文件夹），我们就可以使用Items属性获取到全部列表条目（或文档）的集合。关于SharePoint列表中文件夹的一些特性，会在下一节进行详细介绍。

（2） 当已知列表条目ID的时候，可以通过SPList的GetItemById(int ID)方法，或SPListItemCollection的GetItemById(int ID)方法，获取到对应的列表条目。每个列表条目在本列表中都有一个唯一的整型ID。

需要说明的是，使用GetItemById方法获取到的条目，是包含列表中所有字段的值的。因此，在SharePoint 2010种，提供了一个名为GetItemByIdSelectedFields的方法，只返回其中某些指定字段的值以减少数据库操作来提高读取效率（严格的说，该方法其实并非只会返回我们所指定的字段内容，而是会忽略掉列表中除我们指定字段之外的所有查阅项（包括用户和用户组）类型的字段，因为在返回查阅项类型值的时候，底层数据库需要一些额外的查询）。该方法的定义为：

public SPListItem GetItemByIdSelectedFields(
                int id, params string[] fields)

其中fields参数需要定义为内部名称。例如，当我们仅需要获取某列表中ID为23的条目的“标题”字段（内部名称为“Title”）时，可以使用如下的代码：

SPListItem item = spList.GetItemByIdSelectedFields(23, "Title");
Console.WriteLine(Convert.ToString(item["Title"]);

（3） 当已知列表条目的Guid的时候，可以通过SPList的GetItemByUniqueId(Guid id)方法，获取到对应的列表条目。

（4） 通过SPList的GetItems(SPView view)方法，获取某个列表的某个特定视图下的所有列表条目集合（返回SPListItemCollection类型）。注意这种方法获取到的列表条目集合只包含该视图中所包含的那些字段，而无法获取其他字段的内容。

（5）通过SPList的GetItems(SPQuery query)方法，根据指定的查询条件返回列表中满足该查询条件的列表条目集合（返回SPListItemCollection类型）。这种方法在开发过程中经常会使用到，应当熟练掌握，在本章第四节终会详细讲解SPQuery的用法。

 

2、列表条目的内容访问

当得到一个列表条目对应的SPListItem对象后，可以使用索引器来访问条目中相应字段的内容：

• 使用item[fieldName]，根据字段的显示名称或内部名称获取该条目该字段的内容，返回值为object类型。
• 使用item[fieldID]，根据字段的Guid获取该条目该字短的内容，返回值为object类型。

上述两种方法是一般获取列表条目内容最常用的两种手段（第一种更常用），但是获取的值都是object类型，需要转换为相应的实际类型后再进行输出。如果我们直接将这个object转换成字符串，我们会发现有些字段类型的值并不是在页面中显示的那样：比如对于一个多选类型字段，它的值可能是“;#选项1;#选项2;#”；而一个用户和用户组类型的字段，它的值可能会是“1;#Administrator”（1是该用户的ID，Administrator则是显示名称）。

当然，当我们了解了这些字段类型的内置格式之后，我们可以通过各种字符串处理的方法来得到我们所需要的显示结果。不过在SharePoint中还有一些更标准的方法。在栏/字段（SPField）章节的示例程序中，已经介绍了如何将object类型的值转换为相应的数据类型。除此之外，SharePoint的内置字段类型都提供了两个方法，可以直接将列表条目的内容转换为可以直接输出的内容，这两个方法是SPField的GetFieldValueAsText(object value)和GetFieldValueAsHtml(object value)，其区别在于前者显示纯文本的内容，而后者显示Html的内容（某些字段中可能会包含一些格式或超链接等Html内容）。例如，下面的程序展示了如何使用这种方法获取字段的显示内容（假设存在Chapters列表，其中包含标题、链接、创建者等字段）：

using(SPSite site = new SPSite("http://sp2010/book"))
{
  using(SPWeb web = site.OpenWeb())
  {
    SPList list = web.Lists["Chapters"];
    SPField txtField = list.Fields["标题"],
            lnkField = list.Fields["链接"],
            userField = list.Fields["创建者"];
    foreach(SPListItem item in list.Items)
    {
      Console.WriteLine(string.Format("{0}:{1} by {2}",
        txtField.GetFieldValueAsText(item["标题"]),
        lnkField.GetFieldValueAsHtml(item["链接"]),
        userField.GetFieldValueAsText(item["创建者"])));
    }
  }
}

需要说明的是，SPField的这两个方法并不能保证显示的样式和SharePoint内置的显示样式完全一致，而且在某些情况下，这种显示样式的输出是有问题的（比如“超链接和图片”类型中的图片）。实际上，SharePoint内置的显示样式控制是通过另外一种机制来实现的。

 

3、其他形式的内容访问

除了上述方法能够获取列表条目的内容之外，SharePoint对象模型中也提供了使用Xml形式以及DataTable形式访问列表条目内容的方法。

通过使用SPListItemCollection的Xml属性或SPListItem的Xml属性，可以获得一组或一个列表条目内容的Xml形式表示。在Xml形式的表示中，所有字段类型均使用字符串的格式输出其内容，而所有字段均使用内部名称，并在字段的内部名称前加上“ows_”这一前缀，例如：“ows_Title='Chapter1'”等。实际上，这种Xml的表示和使用Web Services的方式获取到的列表条目的内容是完全一致的。

在传统的ASP.NET开发过程中，开发人员最熟悉的数据结构是DataSet、DataTable等，因为它可以很方便地绑定到各种数据显示控件中。在SharePoint中，虽然使用了自己特有的一套对象模型来表示数据，但是为了和传统的数据绑定方式兼容，也提供了以DataTable形式获取列表数据的方法。

在通过各种方式获得到列表条目集合之后，可以调用SPListItemCollection的GetDataTable方法（不需要任何参数），将这些列表数据转换为DataTable。但是需要说明的是，转换出来的DataTable中的DataColumn的名称都是列表字段的内部名称；其次，使用该方法获得的DataTable中的数据格式，SharePoint会根据字段类型进行一些处理，例如将查阅项的文本获取出来隐去ID等，但是对于多选类型，依然没有进行很好的处理，在进行数据绑定的时候这些数据格式需要加以注意。虽然在控制台程序中没有办法很方便地输出DataTable中的数据，但是凭借Visual Studio的可视化调试功能，我们可以直观地在调试过程中查看整个DataTable的内容，如下图所示：

此外，在SharePoint 2010中为了更加方便何高效地使用DataTable来查看列表数据，在SPList中新增了GetDataTable和AppendDataTable两个方法，这两个方法的定义如下：

public DataTable GetDataTable(SPQuery  query,
                        SPListGetDataTableOptions flags,
                        out SPListItemCollectionPosition position)

public void AppendDataTable(SPQuery query,
                     SPListGetDataTableOptions flags,
                     DataTable dataTable,
                     out SPListItemCollectionPosition position)

从命名中就可以很直观地了解到这两个方法的作用：获取DataTable、追加内容到DataTable中。其中的几个通用参数的含义如下：

• query（SPQuery）：指定返回列表条目时的查询、排序条件、条目数量限制等，并指定需要返回哪些字段的值。和查询相关的内容，将在本章第四节中进行详细介绍。
• flags（SPListGetDataTableOptions）：返回DataTable数据时的一些选项，指定了如何返回布尔类型、查阅项类型和计算值类型的字段值。
• position（SPListItemCollectionPosition）：返回查询后的分页信息。关于分页查询的详细内容，也将在本章第四节中进行详细介绍。

4、新建列表条目

列表条目的新建与其他类型对象的新建编辑有些不同（见第一节中集合操作的部分），列表条目新建的大致过程是：（1）调用SPListItemCollection的Add方法，返回一个待添加的条目（SPListItem类型），也可以使用SPList的AddItem方法（SharePoint 2010新增的方法），在执行该方法之后，列表条目并没有被添加到SharePoint中；（2）为各个需要设置值的字段设置值；（3）调用SPListItem的Update方法将新的列表条目添加到SharePoint中。

下面的程序展示了一个列表条目的创建过程。假设网站中存在Chapters列表，其中包含标题（单行文本）、作者（用户和用户组）、计划完成时间（日期和时间）等字段：

using(SPSite site = new SPSite("http://sp2010/book"))
{
  using(SPWeb web = site.OpenWeb())
  {
    SPList list = web.Lists["Chapters"];
    SPListItem newItem = list.Items.Add();
    newItem["标题"] = "Ch02";
    newItem["作者"] = 19;        // 19是某个用户的ID
    newItem["计划完成时间"] = DataTime.Today.AddDays(10);
    newItem.Update();
  }
}

需要指出的是，为列表条目的字段赋值的时候，并不强制要求所赋的值和列表字段的原始数据类型相同，例如对于“计划完成时间”这个时间日期类型的字段，可以直接设置成DateTime类型的值，也可以设置为形如“2009-9-9 10:10”这样的字符串（但是要保证格式正确），SharePoint会自动进行转换。在设置查阅项和人员类型的字段值的时候，其正确的数据类型应为SPFieldLookupValue / SPFieldUserValue（对于单选查阅项和单一的人员和组）或SPFieldLookupValueCollection / SPFieldUserValueCollection（对于多选查阅项和可以多选的人员和组），但是可以直接设置形如“1;#ItemTitle”或“1;#Administrator;#2;#”这样的值，对于单选的查阅项及人员和组，甚至可以直接设置相应的ID值，正如本例中所做的那样。

对于列表条目的编辑操作，设置值的过程是完全相同的。

SPListItemCollection的Add方法，以及SPList的AddItem方法，都提供了一些重载，用以创建文件夹，或者在指定文件夹下创建列表条目。关于文件夹相关的内容，将在本章第三节中进行详细介绍。

 

5、列表条目的常用属性

SPListItem的一些常用属性如下：

名称	类型	说明
Attachments	SPAttachmentCollection	列表条目的附件集合（详见第三节）
ContentType	SPContentType	列表条目的内容类型
DisplayName	string	列表条目的显示标题
Name	string	列表条目的名称
Title	string	列表条目的“标题”字段
Xml	string	列表条目的Xml表示
File	SPFile	列表条目对应的文档（详见第三节）
Folder	SPFolder	列表条目对应的文件夹（详见第三节）

列表条目的DisplayName、Name和Title三个属性有些类似，有兴趣的读者可以自行尝试一下他们在普通列表、文档库等类型的列表中各有什么关系和区别。