SPListItem的使用

 

在列表的实际操作中，最终要接触到的还是作为数据内容部分的列表条目（List Item）。一般来说，在访问列表的某个具体条目之前，都需要先获得一个列表条目的集合，在SharePoint对象模型中，提供了很多种方法来获取列表条目集合：

最直接地获取列表条目的方法为，使用SPList.Items属性，该属性返回列表中的所有列表条目。在需要得到或者遍历所有列表条目的时候，可以使用这种获取列表条目的方法。

如果有目的地要获得部分列表条目，可以使用SPList.GetItems方法，该方法有如下三种形式：

·      GetItems(SPView view)

返回指定视图中的列表条目，通过这种方法可以按照视图中所指定的筛选、排序及其他的条件按照顺序返回列表条目。在返回的条目中，也只有在视图中定义过的可查看字段中的数据才可以访问到。

·      GetItems(SPQuery query)

顾名思义，SPQuery是SharePoint中负责查询列表条目的一个类，通过定义一个查询，可以方便地获取想要得到的列表条目，SPQuery提供了两种构造函数，一种是无参数的，另外一种可以带有一个SPView类型的参数，即在指定的视图上进行二次的查找。SPQuery最核心的一个属性就是Query属性，它是一个字符串的类型，它通过一种特殊定义过的xml形式，即CAML（Collaborative Application Markup Language）的形式描述一个查询的条件，实际上，这个查询字符串和SPView.Query属性是相当的。在SPQuery中，也可以通过ViewFields属性来指定需要查看的字段（如果不加以指定，则查看所有字段）。在本节最后的示例中，将演示SPQuery的用法。

·      GetItems(SPQuery query, string viewID)

指定SPQuery查询和视图，获取列表条目。需要特别注意的是，虽然第二个参数为字符串类型，但是在使用的时候需要传入的是列表视图的Guid，而不是视图的名称，而且该Guid要以一种特殊的形式传入，即两边用“{}”包围起来，全大写形式，这种形式可以通过Guid.ToString("B").ToUpper()方法得到。

在使用SPQuery的时候，必须每使用一次都要重新进行构造（即使用new运算符重新生成一个新的对象），然后再指定Query属性。否则，如果不进行重新构造，即使指定了不同的Query属性，在每次查询的时候始终得到的是第一次指定的Query条件的查询结果。这一点非常容易被忽略。

以上几种方法所返回的都是SPListItemCollection类型的列表条目集合，获得该集合后，在获得某个具体的列表条目时，有下面两种方法。

·      items[int index]：通过在集合中的下标得到该条目，这种方法多在遍历集合的时候使用；

也可以使用SPListItemCollection.GetItemById方法。

·      GetItemById(int id)：在SharePoint中，每个列表条目都会有一个在该列表中唯一的id（int型），调用SPListItemCollection类的GetItemById方法，就可以通过该id来得到对应的列表条目。

在得到列表条目之后，就可以对该条目的内容进行访问或修改了，访问条目某个字段的方法最常用的方法为： item[string fieldName]，其中fieldName可以使用该字段的显示名称，也可以使用该字段的内部名称。还有一点需要注意的是，该方法所返回的是一个Object类型的变量，如果需要使用该变量的话，必须要对它进行强制类型转换，在转换的时候也要特别注意，如果该条目的该字段没有填写任何内容，那么该返回值是null，如果不加以检查就进行类型转换的话，会引发一个异常（NullReferenceException）。在使用这种方法填写或修改字段数据的时候，除了DateTime类型的数据之外，可以一律使用string类型写入（但是除非特殊需要，不建议使用这种做法）。

审批也是SharePoint列表的一个重要的特色，它允许一个列表条目呈现“已审批、待定、被拒绝”这三种状态，在默认视图中，只显示已审批的条目，在“我的提交”视图和“审批视图”中，可以看到其他的条目。

在SharePoint中，一个列表条目的审批信息并非是保存在某个字段中的，而是在对象模型中对应为SPModerationInformation类，并通过SPListItem.ModerationInfomation属性来访问，该类只有两个属性。

·      Comments：审批意见。即列表管理员进行审批操作的时候所填写的意见。

·      Status：审批状态。该属性为SPModerationStatusType枚举类型，对应三种状态。

需要注意的是，ModerationInfomation这一属性，只有当列表允许审批的时候（即列表SPList的EnableModeration属性为true的时候）才可以取得，否则，该值始终为null。

在使用允许审批的列表的时候，获取列表条目时会有一些不同。使用SPList.Items属性只能获得该列表中状态为“已通过”的那些列表条目，要获得其他条目，则必须通过“我的提交”或“审批视图”这两个视图，使用SPList.GetItems方法来取得。开启了审批的列表都会有这两个视图存在，这两个视图SPView对象的ModerationType属性分别为“Contributor”和“Moderator”，表明属于哪一个审批的视图。

在SPListItem中，还有一些比较常用的属性如下。

·      Attachments：该列表条目的附件集合；

·      File：如果该列表是文档库的话，得到该文件的对象（以上两个属性的使用请参考下一节“文件相关的对象模型”）；

·      ID：在该列表中唯一标识该列表条目的整型的id；

·      ModerationInfomation：该列表条目的审批信息；

·      ParentList：该列表条目所在列表的对象；

·      Xml：以Xml的格式返回该列表条目中的所有数据。

在列表条目的内容修改后，通过调用SPListItem.Update方法使修改生效。

添加一个列表条目的方法非常简单，只需要调用SPListItemCollection.Add方法，该方法不需要参数，直接返回一个空的SPListItem对象，通过对该对象对各字段的内容进行修改，再调用Update方法，即可将该条目添加到该列表中。

删除一个列表条目，有两种方法：

·      SPListItemCollection.DeleteById(int id)

通过列表条目的id来删除该条目；

·      SPListItemCollection.Delete(int index)

通过集合中的下标来删除该条目。

在通过Delete方法删除一个列表中的所有条目时，注意必须使用下面这种逆序的循环方法：

int total = items.Count;

for(int i=total-1; i>=0; i--)

    items.Delete(i);

而不能正向的循环，更不能使用foreach循环来进行，在初学者中，这是一个比较常见的错误。请读者自己思考这样做的原因。

 

<!------------------

SPWeb mySite = SPContext.Current.Web;

SPListItemCollection listItems = mySite.Lists[TextBox1.Text].Items;
int itemCount = listItems.Count;
for (int k=itemCount-1; k>=0; k--)
{
    SPListItem item = listItems[k];
    if (TextBox2.Text==item["Employee"].ToString())

    {

     listItems.Delete(k);

    }

}

------------------->

 

在SPListItemCollection类中，还有一个非常有用的方法：GetDataTable方法，即：

DataTable GetDataTable();

该方法可以返回由这些列表条目所组成的DataTable对象，以便将数据绑定到一些显示控件（如DataGrid）上。但是注意当列表中没有条目的时候，该函数返回的是null，而不是一个有效的DataTable对象。

【示例9-6】 通过SPQuery获得Score字段中大于等于60的列表条目，并且在这些条目的标题后加上“（合格）”字符串，然后再另一列表中，添加一个新条目，写入合格人数。

// 首先获取到SPWeb对象web

SPListCollection lists = web.Lists;

SPList scoreList = lists["Score"];

SPList passList = lists["Pass"];

SPQuery query = new SPQuery();

query.Query = "<Where><Geq><FieldRef Name='Score'/>" +

    "<Value Type='Number'>60</Value></Geq></Where>";

SPListItemCollection items = scoreList.GetItems(query);

foreach(SPListItem item in items)

{

    string title = item["Title"] + "（合格）";

    item["Title"] = title;

    item.Update();

}

SPListItem newItem = passList.Items.Add();

newItem["Count"] = items.Count;

newItem.Update();

在该例中，为了简化场景，没有考虑到不同人、不同科目的分数问题。另外，这个例子只是为了说明和列表条目有关对象模型的使用方法，在实际的应用场景中，类似于上面这种问题，可以通过视图的筛选、分组和汇总的功能在一张列表中直接完成，而且可以接受多人、多科目这种条件，分别统计每一科的合格人数，不需要进行任何编程，SharePoint中强大的视图功能便可以体现在其中。请读者自己思考视图设置的方法。