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

（四）栏/字段

SharePoint中的字段（中文版中叫做“栏”）与传统的数据栏类似，也有不同类型的区别，不过SharePoint中内置的栏类型除了按照数据类型（如数字、日期和时间等）进行区分之外，更多的是从应用类型（货币、选项、查阅项等）进行分类。除内置的字段类型之外，SharePoint同样允许我们通过开发的方式实现自定义字段类型的扩展。在SharePoint中使用SPField表示字段，使用SPFieldCollection表示字段集合，内置的字段类型使用SPFieldType枚举表示。

 

1、字段相关类

在SharePoint中，SPField作为字段的基础类型，包括了字段的基本元素和基本属性。对于每一种特定的字段类型，在SharePoint中都有相应的类与之对应。这些类都是SPField直接或间接的字类，这些类的命名也都是以SPField开头。例如表示单行文本的SPFieldText、表示选项的SPFieldChoice、表示查阅项的SPFieldLookup等，完整的继承关系可以参看SDK中关于SPField的描述。不同的特定类中，包含了对相应字段类型的设置属性，例如针对数字字段类型的最大值、最小值属性，就包含在SPFieldNumber的MaximumValue和MinimumValue两个属性中。

对于一些普通字段类型，其值类型都是比较简单的数据，例如单行文本、多行文本字段是字符串类型（string）的值，数值字段是数值类型（double）的值，时间日期字段是时间日期类型（DateTime）的值。但是诸如超链接、查阅项、人员和组这些字段类型的值难以使用一个简单的类型表示，在SharePoint中，针对这些字段有专门的值类型，其名称为字段类+Value，例如表示超链接值的SPFieldUrlValue、表示查阅项值的SPFieldLookupValue等。

下面的程序展示了如何获取日期类型和人员和组类型的值，注意其区别（假设网站中存在一个叫做“Chapters”的列表，并且其中至少存在一个条目）：

using(SPSite site = new SPSite("http://sp2010/book"))
{
  using(SPWeb web = site.OpenWeb())
  {
    SPList list = web.Lists["Chapters"];
    SPListItem item = list.Items[0];
    foreach(SPField field in list.Fields)
    {
      if(field.Type == SPFieldType.DateTime)
      {
        DateTime dtValue = Convert.ToDateTime(item[field.Id]);
        // use dtValue
      }
      else if(field.Type == SPFieldType.Url)
      {
        SPFieldUrlValue urlValue = new SPFieldUrlValue(
          Convert.ToString(item[field.Id]));
        string url = urlValue.Url;
        // use url
      }
    }
  }
}

在上面的程序中，使用到了一些和列表条目相关的操作，虽然尚未介绍，但应当很容易理解其含义。

 

2、关于显示名称和内部名称

每一个SharePoint字段都有一个显示名称（SPField的Title属性）和一个内部名称（SPField的InternalName属性），这两个都是字符串类型的属性。

显示名称是在创建字段的时候，由用户指定的名称，没有特定的要求。通过网页创建字段的时候，显示名称是不允许重复的，但通过代码完全可以创建显示名称相同的多个字段，而实际上，每个列表中本身就包含了一些显示名称相同的字段（如自定义列表的“标题”字段、文档库的“名称”字段等），在Visual Studio的服务器资源管理器中，我们可以很直观地看到这些重名的字段（如下图）。

而内部名称则是由SharePoint根据用户输入的显示名称，按照一定的命名规律自动生成的（用户无法干预这个过程）。内部名称只能包含大小写英文字母、数字和下划线这三类字符，对于其他的字符，基本上以Unicode编码的形式表现（这里之所以说“基本上”，是因为其中还存在着许多例外情况，比如创建一个名叫“num1”的字段，内部名称会变成“_x006e_um1”。因此我们不能够以这种“基本上”的规则，去根据一个字段显示名称来“推测”出它的内部名称）。例如一个显示名称叫“My Field”的字段，其内部名称可能是“My_x0020_Field”，而一个显示名称为“中文”的字段，其内部名称可能是“_x4e2d__x6587_”。字段的内部名称在SharePoint网站中很少有机会被查看到，但是通过使用Visual Studio的服务器资源管理器，在编写程序的过程中就可以非常方便地查看到我们选定字段的内部名称（如下图所示）。

在字段创建之后，其内部名称是不会改变的，即使将该字段重命名之后，更改的也只是其显示名称，内部名称依然保留原有的名称。并且，在一个列表中，字段的内部名称是不可能重复的（读者可以自己做一些试验）。

虽然列表字段的内部名称在SharePoint使用过程中几乎体会不到，但是在SharePoint开发中，有很多场景必须要使用字段的内部名称来指定一个字段（比如列表查询），因此要熟悉内部名称的查看和使用方法。在实际项目中创建字段的时候，尽可能先使用英文创建字段（保证其内部名称看起来有意义而且容易记忆）再修改其显示名称为中文。

 

3、字段的获取

获取字段的方式一般都是先通过SPList的Fields属性获取到列表中所有字段的集合（SPFieldCollection类型），再使用如下方法获取其中某个特定的字段：

（1） Fields[idx]：int型索引器，使用下标获取字段，很少使用；

（2） Fields[displayName]：string型索引器，使用字段的显示名称获取；

（3） 使用Fields.GetField(string name)方法，使用字段的内部名称或显示名称获取（优先判断内部名称）；

（4） 使用Fields.GetFieldByInternalName(string internalName)方法，使用字段的内部名称获取字段。

除此之外，我们还可以通过SPFieldCollection的ContainsField方法，根据字段的显示名称或内部名称，来判断某个特定名称的字段是否存在。

 

4、字段的常用属性

SPField的常用属性如下：

名称	类型	说明
InternalName	string	字段的内部名称
Title	string	字段的显示名称
Type	SPFieldType	字段的类型
Required	bool	字段是否为必填
SchemaXml	string	字段的通用属性描述
ShowInDisplayForm	Nullable<bool>	是否在列表条目的查看页面显示此字段
ShowInEditForm	Nullable<bool>	是否在列表条目的编辑页面显示此字段
ShowInNewForm	Nullable<bool>	是否在列表条目的新建页面显示此字段

SPField的ShowInDisplayForm / ShowInEditForm / ShowInNewForm三个属性在实际项目中面临的需求中可能经常会使用到。使用SharePoint列表搭建的应用，在有些情况下，一些字段可能会要求不显示在查看界面中（仅供后台程序使用），或者不显示在新建界面中（由程序指定初始值），或者不显示在编辑界面中（不允许用户修改）。通过这三个属性就可以实现这些需求。