SharePoint 2013 客户端渲染：列表表单 + KnockoutJs

现在我们有了基本 UI，让我们让“确定”和“取消”按钮生效。

向查找项添加条目

单击“确定”按钮时，应发生 3 件主要事情：

1. 新国家/地区应添加到“国家/地区”列表中。
2. 新国家/地区也应出现在下拉列表中（因为我们不想刷新整个页面！）。
3. 字段应返回到初始模式。

向列表添加条目很简单，例如可以使用一小段 JSOM 来完成：

var context = SP.ClientContext.get_current();
var list = context.get_web().get_lists().getByTitle("Country");
var item = list.addItem(new SP.ListItemCreationInformation());
item.set_item("Title", model.countryName());
item.update();
context.executeQueryAsync(
    function() {
      alert("item added");
    },
    function() {
      alert("error");
    });

这里 `model.countryName` 应该是绑定到文本框值的 KnockoutJs 可观察对象，因此它包含用户在字段中输入的内容。

现在，在添加条目后，我们还应该将新国家/地区添加到下拉列表中，但不幸的是，没有现成的 API 或受支持的方法可以做到这一点。默认模板就像黑盒子一样，因此我们拥有的选项要么是重新实现整个字段（这是正确的方法，但涉及相当多的代码），要么通过 DOM 来 hack 下拉列表。

今天，为了保持示例简单，我将采用第二种方法，但请记住，任何 DOM hack 本质上都是糟糕的做法，在下次更新后（O365 更新非常频繁）它可能突然停止工作，仅此而已...

通过 DOM，向下拉列表添加元素是一项非常简单的任务。首先，让我们看一下下拉列表元素的源代码：

值显然等于条目 ID。现在创建适当的代码很容易：

var context = SP.ClientContext.get_current();
var list = context.get_web().get_lists().getByTitle("Countries");
var item = list.addItem(new SP.ListItemCreationInformation());
item.set_item("Title", model.countryName());
item.update();
context.load(item,"ID");
context.executeQueryAsync(
    function() {
      
      // add new country to dropdown
      var option = document.createElement("option");
      option.value = item.get_id();
      option.innerHTML = model.countryName();
    
      var select = document.querySelector("#countryTD select");
      select.appendChild(option);
      
      // turn off the edit mode and clear input
      model.editMode(false);
      model.countryName('');
    },
    function() {
      alert("error");
    });

注意几点：

1. 我添加了 `context.load` 调用以确保返回创建项的 ID。
2. 成功回调最后的两行代码会将字段切换回初始模式并清除国家/地区名称文本框。显然，这两行代码也可以用于“取消”按钮处理程序。
3. `document.querySelector` 执行与 jQuery 相同的选择器工作，并且自 IE8 起得到原生支持，所以我一直使用它，但如果您在页面上部署了 jQuery，那么当然可以使用 jQuery 完成相同的目的。
4. `#countryTD` 指的是我添加到包含字段默认模板的 `

就这样！现在，如果您正确添加了 `data-bind` 属性，一切都应该正常工作！

完整的代码

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides({

      Templates: {

          Fields: {
              "Country": {
                  NewForm: function(ctx) {
                    var fieldType = ctx.CurrentFieldSchema.FieldType;
                    var defaultTemplates = SPClientTemplates._defaultTemplates.Fields.default.all.all;
                    return '<div data-bind="visible: !addMode()">'
                    	+ '<table><tr><td id='countryTD'>'
                        + defaultTemplates[fieldType]["NewForm"](ctx)
                    	+ '</td><td>'
                        + '<button data-bind="click: switchToAddMode">Add</button>'
                    	+ '</td></tr></table>'
                        + '</div>'
                        + '<div data-bind="visible: addMode()">'
                    	+ '<input type="text" data-bind="value: countryName" />'
                        + '<button data-bind="click: add">OK</button>'
                        + '<button data-bind="click: cancel">Cancel</button>'
                        + '</div>';
                  },
              }
          },

      },

      OnPostRender: function(ctx) {
        if (ctx.ListSchema.Field[0].Name == "Liked") // last field of the form
        {
          var model = {
            addMode: ko.observable(false),
            switchToAddMode: function() {
              model.addMode(true);
            },
            
            countryName: ko.observable(''),
            
            add: function() {
                var context = SP.ClientContext.get_current();
                var list = context.get_web().get_lists().getByTitle("Countries");
                var item = list.addItem(new SP.ListItemCreationInformation());
                item.set_item("Title", model.countryName());
                item.update();
                context.load(item,"ID");
                context.executeQueryAsync(
                    function() {
                      
                      // add new country to dropdown
                      var option = document.createElement("option");
                      option.value = item.get_id();
                      option.innerHTML = model.countryName();
                    
                      var select = document.querySelector("#countryTD select");
                      select.appendChild(option);
                      
                      // turn off the edit mode and clear input
                      model.editMode(false);
                      model.countryName('');
                    },
                    function() {
                      alert("error");
                    });
            },
            
            cancel: function() {
              model.editMode(false);
              model.countryName('');
            }
            
          };
          ko.applyBindings(model);
        }
      }

    });

这是您获得的结果：

是的，当然它也会将相应的条目添加到“国家/地区”列表中。

示例 3：联动字段

显然，可以使用同一个 KnockoutJs 模型控制多个字段。让我们这样做，并使字段相互关联。

因此，在我的示例窗体中，我有一些“Visited”和“Liked”字段。“Visited”字段标记是否访问过某个城市，而在“Liked”字段中，我可以选择我喜欢什么。逻辑上，我应该在访问过该城市之前看不到“Liked”字段。

为了实现此逻辑，我需要覆盖“Liked”和“Visited”这两个字段。对于“Liked”字段，自定义非常简单：只需将字段控件包装在一个 div 中，并将此字段的可见性绑定到模型中的 `visited` 字段（我稍后将创建该字段）。

return '<div data-bind="visible: visited()">' + defaultTemplates[fieldType]["EditForm"] + '</div>';

这里 `visited` 是一个可观察对象，它应该用“Visited”字段的值初始化。这样做非常简单：

var model = {
  visited: ko.observable(ctx.ListData.Items[0]["Visited"] == 1)
}

现在让我们处理“Visited”字段。

实际上，字段的显示方式没有任何问题，我们应该做的唯一事情就是实时跟踪此字段的变化（例如，用户清除了复选框 =>“Liked”字段立即消失）。不幸的是，同样，默认字段模板就像黑盒子一样，没有 API 可以订阅字段的变化。再次，最正确的方法是重新实现该字段，尽管 DOM hack 甚至字符串替换也可以工作。

这一次，让我们坚持正确的方法，并重新实现这个字段。在这种特定情况下，实际上非常容易做到：

"Visited": {
    EditForm: function(ctx) {
        ctx.FormContext.registerGetValueCallback(ctx.CurrentFieldSchema.Name, function() {
            return model.visited();
        });
        return '<input data-bind="checked: visited" type="checkbox" />';
    }
}

在这种情况下，我只提供 `GetValueCallback`，尽管在理想情况下，建议您也使用 `registerInitCallback`、`registerHasValueChangedCallback`、`registerFocusCallback` 和 `registerValidationErrorCallback`。

但无论如何，如果您曾经创建过字段模板，您肯定会注意到 KnockoutJs 在这里多么契合，以及它如何显著简化字段模板的创建。

为了完成这个示例，我稍微调整了一下代码，使模型变量在模板函数内部可见，但就这样，完成了，字段现在链接在一起了。

此示例的完整代码

    var model = {
      visited: function(){}
    };

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides({

      Templates: {

          Fields: {
              "Visited": {
                EditForm: function(ctx) {
                    ctx.FormContext.registerGetValueCallback(ctx.CurrentFieldSchema.Name, function() {
                      return model.visited();
                    });
                    return '<input type="checkbox" data-bind="checked: visited" />';
                }
              },
              "Liked": {
                EditForm: function(ctx) {
                    var fieldType = ctx.CurrentFieldSchema.FieldType;
                    var defaultTemplates = SPClientTemplates._defaultTemplates.Fields.default.all.all;
                    return '<div data-bind="visible: visited()">' + defaultTemplates[fieldType]["EditForm"](ctx) + '</div>';
                }
              }
          },

      },

      OnPostRender: function(ctx) {
        if (ctx.ListSchema.Field[0].Name == "Liked")
        {
          model.visited = ko.observable(ctx.ListData.Items[0]["Visited"] == 1);
          ko.applyBindings(model);
        }
      },

    });

源代码

像往常一样，您可以通过左侧面板的“浏览代码”链接浏览示例的源代码，或通过以下链接将其下载为 zip 存档：

• 下载源代码 - 2.5 KB

一些建议

如何将 HTML 标记与代码分离

上面的示例至少有一个明显的问题：HTML 标记是在 JS 字符串中管理的，而不是在单独的文件中。对于小型示例来说没问题，但对于较大的示例来说就不太好了。

一个简单的解决方案是创建一个KO 模板在 SharePoint 的单独文件中，然后通过内容编辑器 Web 部件或其他方法将其加载到页面上。

或者，如果您正在构建许多通用的字段控件并在不同窗体中重用它们，可以考虑KO 组件及其外部加载器。

为什么不使用 AngularJs 或其他框架？

KnockoutJs 只是一个例子，但当然许多现代 JavaScript 框架和库都可以胜任。特别是对于 AngularJs，对我来说，这就像用杀鸡的牛刀... :)

为什么不使用完全自定义的窗体 + JSOM？

好问题。在某些情况下，完全自定义的窗体实际上是个好主意，并且很有意义。

但是，我认为 CSR 在以下情况更好：

1. 您只需要自定义几个字段，而保留其他所有字段不变。
2. 您有一些字段不容易在您的窗体中重新实现（例如 Taxonomy、User 等）。
3. 您无法保证用户不会更改字段设置或向此特定列表添加其他字段。
4. 您自定义了在许多不同列表中重复使用的字段。

如何更快地开发 CSR 自定义

我曾经构建过一个工具，可以更快地创建 CSR 自定义。我的意思是，**快得多**。最初，这只是我为自己写的一个工具，因为我经常使用 CSR。现在它是开源的，您可以选择使用它。

该工具称为Cisar，本质上是 CSR 的实时编辑器。也就是说，您编写代码，然后立即看到您的窗体或列表视图如何根据您编写的内容进行转换。没有延迟，也没有页面重新加载。工作原理如下：

结论

SharePoint 2013 中的列表窗体是在客户端渲染的，这使我们能够利用 KnockoutJs 等现代框架的强大功能，使窗体自定义变得简单、易读且更有效。

重用默认 CSR 字段模板的可能性相当有限，但有了 KnockoutJs 的强大功能，即使重新实现这些模板也变成了一项相对容易的任务。

通过使用 CSR 和 KnockoutJs，可以创建灵活、易读且可维护的解决方案，这些解决方案将与 SharePoint 完全兼容，这在 SharePoint Online 中尤其重要，那里的更新一直在进行，而使用 DOM 技巧是一种非常危险的方法。