（五）列表?xiàng)l目（SPListItem）

SharePoint中數(shù)據(jù)的存儲(chǔ)基本上都是通過(guò)列表?xiàng)l目來(lái)完成（文檔庫(kù)中的文檔也是一種特殊的列表?xiàng)l目），因此在SharePoint應(yīng)用開(kāi)發(fā)中，最終是要和列表?xiàng)l目打交道的。在SharePoint對(duì)象模型中，使用SPListItem表示列表?xiàng)l目，使用SPListItemCollection表示列表?xiàng)l目集合。

?

1、列表?xiàng)l目的獲取

列表?xiàng)l目的獲取有多種方式，一些常用方式如下：

（1） 通過(guò)SPList的Items屬性，獲取列表中的所有條目（不包括文件夾本身對(duì)應(yīng)的條目），再通過(guò)foreach遍歷的形式遍歷其中的所有條目；或使用形如[idx]的int型索引器獲取其中的某個(gè)條目。當(dāng)我們需要遍歷一個(gè)列表中所有條目、或文檔庫(kù)中所有文檔的時(shí)候（不論它們屬于哪個(gè)子文件夾），我們就可以使用Items屬性獲取到全部列表?xiàng)l目（或文檔）的集合。關(guān)于SharePoint列表中文件夾的一些特性，會(huì)在下一節(jié)進(jìn)行詳細(xì)介紹。

（2） 當(dāng)已知列表?xiàng)l目ID的時(shí)候，可以通過(guò)SPList的GetItemById(int ID)方法，或SPListItemCollection的GetItemById(int ID)方法，獲取到對(duì)應(yīng)的列表?xiàng)l目。每個(gè)列表?xiàng)l目在本列表中都有一個(gè)唯一的整型ID。

需要說(shuō)明的是，使用GetItemById方法獲取到的條目，是包含列表中所有字段的值的。因此，在SharePoint 2010種，提供了一個(gè)名為GetItemByIdSelectedFields的方法，只返回其中某些指定字段的值以減少數(shù)據(jù)庫(kù)操作來(lái)提高讀取效率（嚴(yán)格的說(shuō)，該方法其實(shí)并非只會(huì)返回我們所指定的字段內(nèi)容，而是會(huì)忽略掉列表中除我們指定字段之外的所有查閱項(xiàng)（包括用戶和用戶組）類型的字段，因?yàn)樵诜祷夭殚嗧?xiàng)類型值的時(shí)候，底層數(shù)據(jù)庫(kù)需要一些額外的查詢）。該方法的定義為：

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

其中fields參數(shù)需要定義為內(nèi)部名稱。例如，當(dāng)我們僅需要獲取某列表中ID為23的條目的“標(biāo)題”字段（內(nèi)部名稱為“Title”）時(shí)，可以使用如下的代碼：

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

（3） 當(dāng)已知列表?xiàng)l目的Guid的時(shí)候，可以通過(guò)SPList的GetItemByUniqueId(Guid id)方法，獲取到對(duì)應(yīng)的列表?xiàng)l目。

（4） 通過(guò)SPList的GetItems(SPView view)方法，獲取某個(gè)列表的某個(gè)特定視圖下的所有列表?xiàng)l目集合（返回SPListItemCollection類型）。注意這種方法獲取到的列表?xiàng)l目集合只包含該視圖中所包含的那些字段，而無(wú)法獲取其他字段的內(nèi)容。

（5）通過(guò)SPList的GetItems(SPQuery query)方法，根據(jù)指定的查詢條件返回列表中滿足該查詢條件的列表?xiàng)l目集合（返回SPListItemCollection類型）。這種方法在開(kāi)發(fā)過(guò)程中經(jīng)常會(huì)使用到，應(yīng)當(dāng)熟練掌握，在本章第四節(jié)終會(huì)詳細(xì)講解SPQuery的用法。

?

?

2、列表?xiàng)l目的內(nèi)容訪問(wèn)

當(dāng)?shù)玫揭粋€(gè)列表?xiàng)l目對(duì)應(yīng)的SPListItem對(duì)象后，可以使用索引器來(lái)訪問(wèn)條目中相應(yīng)字段的內(nèi)容：

• 使用item[fieldName]，根據(jù)字段的顯示名稱或內(nèi)部名稱獲取該條目該字段的內(nèi)容，返回值為object類型。
• 使用item[fieldID]，根據(jù)字段的Guid獲取該條目該字短的內(nèi)容，返回值為object類型。

上述兩種方法是一般獲取列表?xiàng)l目?jī)?nèi)容最常用的兩種手段（第一種更常用），但是獲取的值都是object類型，需要轉(zhuǎn)換為相應(yīng)的實(shí)際類型后再進(jìn)行輸出。如果我們直接將這個(gè)object轉(zhuǎn)換成字符串，我們會(huì)發(fā)現(xiàn)有些字段類型的值并不是在頁(yè)面中顯示的那樣：比如對(duì)于一個(gè)多選類型字段，它的值可能是“;#選項(xiàng)1;#選項(xiàng)2;#”；而一個(gè)用戶和用戶組類型的字段，它的值可能會(huì)是“1;#Administrator”（1是該用戶的ID，Administrator則是顯示名稱）。

當(dāng)然，當(dāng)我們了解了這些字段類型的內(nèi)置格式之后，我們可以通過(guò)各種字符串處理的方法來(lái)得到我們所需要的顯示結(jié)果。不過(guò)在SharePoint中還有一些更標(biāo)準(zhǔn)的方法。在欄/字段（SPField）章節(jié)的示例程序中，已經(jīng)介紹了如何將object類型的值轉(zhuǎn)換為相應(yīng)的數(shù)據(jù)類型。除此之外，SharePoint的內(nèi)置字段類型都提供了兩個(gè)方法，可以直接將列表?xiàng)l目的內(nèi)容轉(zhuǎn)換為可以直接輸出的內(nèi)容，這兩個(gè)方法是SPField的GetFieldValueAsText(object value)和GetFieldValueAsHtml(object value)，其區(qū)別在于前者顯示純文本的內(nèi)容，而后者顯示Html的內(nèi)容（某些字段中可能會(huì)包含一些格式或超鏈接等Html內(nèi)容）。例如，下面的程序展示了如何使用這種方法獲取字段的顯示內(nèi)容（假設(shè)存在Chapters列表，其中包含標(biāo)題、鏈接、創(chuàng)建者等字段）：

1: using(SPSite site = new SPSite("http://sp2010/book")) 2: { 3: using(SPWeb web = site.OpenWeb()) 4: { 5: SPList list = web.Lists["Chapters"]; 6: SPField txtField = list.Fields["標(biāo)題"], 7: lnkField = list.Fields["鏈接"], 8: userField = list.Fields["創(chuàng)建者"]; 9: foreach(SPListItem item in list.Items) 10: { 11: Console.WriteLine(string.Format("{0}:{1} by {2}", 12: txtField.GetFieldValueAsText(item["標(biāo)題"]), 13: lnkField.GetFieldValueAsHtml(item["鏈接"]), 14: userField.GetFieldValueAsText(item["創(chuàng)建者"]))); 15: } 16: } 17: }

需要說(shuō)明的是，SPField的這兩個(gè)方法并不能保證顯示的樣式和SharePoint內(nèi)置的顯示樣式完全一致，而且在某些情況下，這種顯示樣式的輸出是有問(wèn)題的（比如“超鏈接和圖片”類型中的圖片）。實(shí)際上，SharePoint內(nèi)置的顯示樣式控制是通過(guò)另外一種機(jī)制來(lái)實(shí)現(xiàn)的。

?

3、其他形式的內(nèi)容訪問(wèn)

除了上述方法能夠獲取列表?xiàng)l目的內(nèi)容之外，SharePoint對(duì)象模型中也提供了使用Xml形式以及DataTable形式訪問(wèn)列表?xiàng)l目?jī)?nèi)容的方法。

通過(guò)使用SPListItemCollection的Xml屬性或SPListItem的Xml屬性，可以獲得一組或一個(gè)列表?xiàng)l目?jī)?nèi)容的Xml形式表示。在Xml形式的表示中，所有字段類型均使用字符串的格式輸出其內(nèi)容，而所有字段均使用內(nèi)部名稱，并在字段的內(nèi)部名稱前加上“ows_”這一前綴，例如：“ows_Title='Chapter1'”等。實(shí)際上，這種Xml的表示和使用Web Services的方式獲取到的列表?xiàng)l目的內(nèi)容是完全一致的。

在傳統(tǒng)的ASP.NET開(kāi)發(fā)過(guò)程中，開(kāi)發(fā)人員最熟悉的數(shù)據(jù)結(jié)構(gòu)是DataSet、DataTable等，因?yàn)樗梢院芊奖愕亟壎ǖ礁鞣N數(shù)據(jù)顯示控件中。在SharePoint中，雖然使用了自己特有的一套對(duì)象模型來(lái)表示數(shù)據(jù)，但是為了和傳統(tǒng)的數(shù)據(jù)綁定方式兼容，也提供了以DataTable形式獲取列表數(shù)據(jù)的方法。

在通過(guò)各種方式獲得到列表?xiàng)l目集合之后，可以調(diào)用SPListItemCollection的GetDataTable方法（不需要任何參數(shù)），將這些列表數(shù)據(jù)轉(zhuǎn)換為DataTable。但是需要說(shuō)明的是，轉(zhuǎn)換出來(lái)的DataTable中的DataColumn的名稱都是列表字段的內(nèi)部名稱；其次，使用該方法獲得的DataTable中的數(shù)據(jù)格式，SharePoint會(huì)根據(jù)字段類型進(jìn)行一些處理，例如將查閱項(xiàng)的文本獲取出來(lái)隱去ID等，但是對(duì)于多選類型，依然沒(méi)有進(jìn)行很好的處理，在進(jìn)行數(shù)據(jù)綁定的時(shí)候這些數(shù)據(jù)格式需要加以注意。雖然在控制臺(tái)程序中沒(méi)有辦法很方便地輸出DataTable中的數(shù)據(jù)，但是憑借Visual Studio的可視化調(diào)試功能，我們可以直觀地在調(diào)試過(guò)程中查看整個(gè)DataTable的內(nèi)容，如下圖所示：

此外，在SharePoint 2010中為了更加方便何高效地使用DataTable來(lái)查看列表數(shù)據(jù)，在SPList中新增了GetDataTable和AppendDataTable兩個(gè)方法，這兩個(gè)方法的定義如下：

?

1: public DataTable GetDataTable(SPQuery query, 2: SPListGetDataTableOptions flags, 3: out SPListItemCollectionPosition position) 4:? 5: public void AppendDataTable(SPQuery query, 6: SPListGetDataTableOptions flags, 7: DataTable dataTable, 8: out SPListItemCollectionPosition position)

從命名中就可以很直觀地了解到這兩個(gè)方法的作用：獲取DataTable、追加內(nèi)容到DataTable中。其中的幾個(gè)通用參數(shù)的含義如下：

• query（SPQuery）：指定返回列表?xiàng)l目時(shí)的查詢、排序條件、條目數(shù)量限制等，并指定需要返回哪些字段的值。和查詢相關(guān)的內(nèi)容，將在本章第四節(jié)中進(jìn)行詳細(xì)介紹。
• flags（SPListGetDataTableOptions）：返回DataTable數(shù)據(jù)時(shí)的一些選項(xiàng)，指定了如何返回布爾類型、查閱項(xiàng)類型和計(jì)算值類型的字段值。
• position（SPListItemCollectionPosition）：返回查詢后的分頁(yè)信息。關(guān)于分頁(yè)查詢的詳細(xì)內(nèi)容，也將在本章第四節(jié)中進(jìn)行詳細(xì)介紹。

4、新建列表?xiàng)l目

列表?xiàng)l目的新建與其他類型對(duì)象的新建編輯有些不同（見(jiàn)第一節(jié)中集合操作的部分），列表?xiàng)l目新建的大致過(guò)程是：（1）調(diào)用SPListItemCollection的Add方法，返回一個(gè)待添加的條目（SPListItem類型），也可以使用SPList的AddItem方法（SharePoint 2010新增的方法），在執(zhí)行該方法之后，列表?xiàng)l目并沒(méi)有被添加到SharePoint中；（2）為各個(gè)需要設(shè)置值的字段設(shè)置值；（3）調(diào)用SPListItem的Update方法將新的列表?xiàng)l目添加到SharePoint中。

下面的程序展示了一個(gè)列表?xiàng)l目的創(chuàng)建過(guò)程。假設(shè)網(wǎng)站中存在Chapters列表，其中包含標(biāo)題（單行文本）、作者（用戶和用戶組）、計(jì)劃完成時(shí)間（日期和時(shí)間）等字段：

1: using(SPSite site = new SPSite("http://sp2010/book")) 2: { 3: using(SPWeb web = site.OpenWeb()) 4: { 5: SPList list = web.Lists["Chapters"]; 6: SPListItem newItem = list.Items.Add(); 7: newItem["標(biāo)題"] = "Ch02"; 8: newItem["作者"] = 19; // 19是某個(gè)用戶的ID 9: newItem["計(jì)劃完成時(shí)間"] = DataTime.Today.AddDays(10); 10: newItem.Update(); 11: } 12: }

需要指出的是，為列表?xiàng)l目的字段賦值的時(shí)候，并不強(qiáng)制要求所賦的值和列表字段的原始數(shù)據(jù)類型相同，例如對(duì)于“計(jì)劃完成時(shí)間”這個(gè)時(shí)間日期類型的字段，可以直接設(shè)置成DateTime類型的值，也可以設(shè)置為形如“2009-9-9 10:10”這樣的字符串（但是要保證格式正確），SharePoint會(huì)自動(dòng)進(jìn)行轉(zhuǎn)換。在設(shè)置查閱項(xiàng)和人員類型的字段值的時(shí)候，其正確的數(shù)據(jù)類型應(yīng)為SPFieldLookupValue / SPFieldUserValue（對(duì)于單選查閱項(xiàng)和單一的人員和組）或SPFieldLookupValueCollection / SPFieldUserValueCollection（對(duì)于多選查閱項(xiàng)和可以多選的人員和組），但是可以直接設(shè)置形如“1;#ItemTitle”或“1;#Administrator;#2;#”這樣的值，對(duì)于單選的查閱項(xiàng)及人員和組，甚至可以直接設(shè)置相應(yīng)的ID值，正如本例中所做的那樣。

對(duì)于列表?xiàng)l目的編輯操作，設(shè)置值的過(guò)程是完全相同的。

SPListItemCollection的Add方法，以及SPList的AddItem方法，都提供了一些重載，用以創(chuàng)建文件夾，或者在指定文件夾下創(chuàng)建列表?xiàng)l目。關(guān)于文件夾相關(guān)的內(nèi)容，將在本章第三節(jié)中進(jìn)行詳細(xì)介紹。

?

5、列表?xiàng)l目的常用屬性

SPListItem的一些常用屬性如下：

名稱	類型	說(shuō)明
Attachments	SPAttachmentCollection	列表?xiàng)l目的附件集合（詳見(jiàn)第三節(jié)）
ContentType	SPContentType	列表?xiàng)l目的內(nèi)容類型
DisplayName	string	列表?xiàng)l目的顯示標(biāo)題
Name	string	列表?xiàng)l目的名稱
Title	string	列表?xiàng)l目的“標(biāo)題”字段
Xml	string	列表?xiàng)l目的Xml表示
File	SPFile	列表?xiàng)l目對(duì)應(yīng)的文檔（詳見(jiàn)第三節(jié)）
Folder	SPFolder	列表?xiàng)l目對(duì)應(yīng)的文件夾（詳見(jiàn)第三節(jié)）

列表?xiàng)l目的DisplayName、Name和Title三個(gè)屬性有些類似，有興趣的讀者可以自行嘗試一下他們?cè)谄胀斜怼⑽臋n庫(kù)等類型的列表中各有什么關(guān)系和區(qū)別。

總結(jié)

以上是生活随笔為你收集整理的【转】2.5SharePoint服务器端对象模型 之 访问网站和列表数据（Part 5）的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。