（五）列表條目（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的方法，只返回其中某些指定字段的值以減少數據庫操作來提高讀取效率（嚴格的說，該方法其實并非只會返回我們所指定的字段內容，而是會忽略掉列表中除我們指定字段之外的所有查閱項（包括用戶和用戶組）類型的字段，因為在返回查閱項類型值的時候，底層數據庫需要一些額外的查詢）。該方法的定義為：

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

其中fields參數需要定義為內部名稱。例如，當我們僅需要獲取某列表中ID為23的條目的“標題”字段（內部名稱為“Title”）時，可以使用如下的代碼：

1: SPListItem item = spList.GetItemByIdSelectedFields(23, "Title"); 2: 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列表，其中包含標題、鏈接、創建者等字段）：

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["標題"], 7: lnkField = list.Fields["鏈接"], 8: userField = list.Fields["創建者"]; 9: foreach(SPListItem item in list.Items) 10: { 11: Console.WriteLine(string.Format("{0}:{1} by {2}", 12: txtField.GetFieldValueAsText(item["標題"]), 13: lnkField.GetFieldValueAsHtml(item["鏈接"]), 14: userField.GetFieldValueAsText(item["創建者"]))); 15: } 16: } 17: }

需要說明的是，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兩個方法，這兩個方法的定義如下：

?

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)

從命名中就可以很直觀地了解到這兩個方法的作用：獲取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列表，其中包含標題（單行文本）、作者（用戶和用戶組）、計劃完成時間（日期和時間）等字段：

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["標題"] = "Ch02"; 8: newItem["作者"] = 19; // 19是某個用戶的ID 9: newItem["計劃完成時間"] = DataTime.Today.AddDays(10); 10: newItem.Update(); 11: } 12: }

需要指出的是，為列表條目的字段賦值的時候，并不強制要求所賦的值和列表字段的原始數據類型相同，例如對于“計劃完成時間”這個時間日期類型的字段，可以直接設置成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三個屬性有些類似，有興趣的讀者可以自行嘗試一下他們在普通列表、文檔庫等類型的列表中各有什么關系和區別。

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。