使用客户端呈现自定义字段类型

了解如何在 SharePoint 中使用客户端呈现技术自定义字段类型。

客户端呈现提供了一种机制，可用来为 SharePoint 页面中托管的一组控件生成你自己的输出。 利用此机制，您可以使用已知的技术（如 HTML 和 JavaScript）定义自定义域类型的呈现逻辑。 在客户端呈现中，您可以指定自己的 JavaScript 资源并在服务器场解决方案可用的数据存储选项（如 _layouts 文件夹）中承载这些资源。

使用本文中的示例的先决条件

若要按照此示例中的步骤操作，您需要：

• Microsoft Visual Studio 2012
• Visual Studio 2012 Office 开发人员工具
• SharePoint 开发环境

有关设置 SharePoint 开发环境的信息，请参阅 为 SharePoint 设置常规开发环境。

可帮助您了解域类型的客户端呈现的核心概念

下表列出了一些有价值的文章，这些文章可帮助你了解自定义操作方案中涉及的概念和步骤。

表 1. 域类型的客户端呈现的核心概念

代码示例：自定义视图窗体中的自定义域类型的呈现过程

按照以下步骤操作可自定义自定义域类型的呈现过程：

1. 创建服务器场解决方案项目。

2. 为自定义域类型添加类。

3. 为自定义域类型添加 XML 定义。

4. 为自定义域类型的呈现逻辑添加 JavaScript 文件。

   图 1. 视图窗体中的自定义客户端呈现域

创建服务器场解决方案项目

1. 以管理员身份打开 Visual Studio 2012（右键单击“开始”菜单中的 Visual Studio 2012 图标，再选择“以管理员身份运行”。）

2. 使用“SharePoint 项目”模板新建项目

   图 2 展示了“SharePoint 项目”模板在 Visual Studio 2012 中的位置，即在“模板”>“Visual C#”>“Office SharePoint”>“SharePoint 解决方案”下。

   图 2. SharePoint 项目 Visual Studio 模板

   

3. 提供要用于调试的 SharePoint 网站的 URL。

4. 选择"部署为场解决方案"选项。

为自定义域类型添加类

1. 右键单击服务器场解决方案项目并添加新类。 将类文件命名为 FavoriteColorFieldType.cs。

2. 复制以下代码并将其粘贴到 FavoriteColorFieldType.cs 文件中。 该代码执行以下任务：

   • 声明从 SPFieldText 继承的 FavoriteColorField 类。

   • 为 FavoriteColorField 类提供两个构造函数。

   • 重写 JSLink 属性。

     注意

     调查或事件列表不支持 JSLink 属性。 SharePoint 日历是事件列表。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

// Additional references for this sample.
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace Microsoft.SDK.SharePoint.Samples.WebControls
{
    /// <summary>
    /// The FavoriteColorField custom field type
    /// inherits from SPFieldText.
    /// Users can input the color in the field
    /// just like in any other text field.
    /// But the field will provide additional
    /// rendering logic when displaying
    /// the field in a view form.
    /// </summary>
    public class FavoriteColorField : SPFieldText
    {
        // The solution deploys the JavaScript
        // file to the CSRAssets folder
        // in the WFE's layouts folder.
        private const string JSLinkUrl =
            "~site/_layouts/15/CSRAssets/CSRFieldType.js";

        // You have to provide constructors for SPFieldText.
        public FavoriteColorField(
            SPFieldCollection fields,
            string name) :
            base(fields, name)
        {

        }
        public FavoriteColorField(
            SPFieldCollection fields,
            string typename,
            string name) :
            base(fields, typename, name)
        {

        }

        /// <summary>
        /// Override the JSLink property to return the
        /// value of our custom JavaScript file.
        /// </summary>
        public override string JSLink
        {
            get
            {
              return JSLinkUrl;
            }
            set
            {
              base.JSLink = value;
            }
        }
    }
}

添加自定义字段类型的 XML 定义的具体步骤

1. 右键单击服务器场解决方案项目，并添加 SharePoint 映射文件夹。 在对话框中，选择 {SharePointRoot}\Template\XML 文件夹。

2. 右键单击在上一步中创建的 XML 文件夹，并添加一个新的 XML 文件。 将该 XML 文件命名为 fldtypes_FavoriteColorFieldType.xml。

3. 复制以下标记并将其粘贴到该 XML 文件中。 标记执行以下任务：

   • 为域类型提供类型名称。
   • 指定域类型的完整类名称。 这是您在上一过程中创建的类。
   • 为域类型提供其他属性。

<?xml version="1.0" encoding="utf-8" ?>
<FieldTypes>
  <FieldType>
    <Field Name="TypeName">FavoriteColorField</Field>
    <Field Name="TypeDisplayName">Favorite color field</Field>
    <Field Name="TypeShortDescription">Favorite color field</Field>
    <Field Name="FieldTypeClass">Microsoft.SDK.SharePoint.Samples.WebControls.FavoriteColorField, $SharePoint.Project.AssemblyFullName$</Field>
    <Field Name="ParentType">Text</Field>
    <Field Name="Sortable">TRUE</Field>
    <Field Name="Filterable">TRUE</Field>
    <Field Name="UserCreatable">TRUE</Field>
    <Field Name="ShowOnListCreate">TRUE</Field>
    <Field Name="ShowOnSurveyCreate">TRUE</Field>
    <Field Name="ShowOnDocumentLibrary">TRUE</Field>
    <Field Name="ShowOnColumnTemplateCreate">TRUE</Field>
  </FieldType>
</FieldTypes>

为自定义域类型的呈现逻辑添加 JavaScript 文件

1. 右键单击服务器场解决方案项目，并添加 SharePoint Layouts 映射文件夹。 将一个新的 CSRAssets 文件夹添加到最近添加的 Layouts 文件夹中。

2. 右键单击您在上一步中创建的 CSRAssets 文件夹，并添加一个新的 JavaScript 文件。 将该 JavaScript 文件命名为 CSRFieldType.js。

3. 复制以下代码并将其粘贴到 JavaScript 文件中。 该代码执行以下任务：

   • 在视图窗体中显示字段时，为该字段创建模板。
   • 注册该模板。
   • 在视图窗体中显示域类型时为其提供呈现逻辑。

(function () {
  var favoriteColorContext = {};

  // You can provide templates for:
  // View, DisplayForm, EditForm and NewForm
  favoriteColorContext.Templates = {};
  favoriteColorContext.Templates.Fields = {
    "FavoriteColorField": {
      "View": favoriteColorViewTemplate
    }
  };

  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(favoriteColorContext);
})();

// The favoriteColorViewTemplate provides the rendering logic
// the custom field type when it is displayed in the view form.
function favoriteColorViewTemplate(ctx) {
  var color = ctx.CurrentItem[ctx.CurrentFieldSchema.Name];
  return "<span style='background-color : " + color +
         "' >&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;</span>&amp;nbsp;" + color;
}

生成并运行解决方案

1. 按 F5 键。

   注意

   按 F5 后，Visual Studio 便会生成并部署解决方案，并打开部署了解决方案的 SharePoint 网站。

2. 创建自定义列表并添加新的“常用颜色字段”列。

3. 向列表添加一个项，并为 Favorite Color 列提供值。

4. 图 3 显示了带新的自定义域类型的创建列页。

   图 3. 创建新的自定义域类型列

   

后续步骤

本文说明了如何自定义自定义域类型的呈现过程。 接下来，您可以了解有关自定义域类型的更多详细信息。 若要了解更多信息，请参阅：

• 如何：创建自定义字段类型
• 演练：创建自定义字段类型。
• 使用客户端呈现在 SharePoint 外接程序中自定义列表视图

另请参阅

• 设置 SharePoint 的常规开发环境
• 为 SharePoint 构建网站
• 添加 SharePoint 功能
• 在 SharePoint 中生成场解决方案