KNOCKOUTJS DOCUMENTATION-绑定(BINDINGS)-自定义绑定

2023-08-23 08:41:34

除了ko内建的绑定，还可以自定义绑定，灵活地封装复杂的行为使之可重用。

自定义绑定

注册自定义绑定

向 ko.bindingHandles
添加一个子属性来注册一个绑定。

ko.bindingHandlers.yourBindingName = {
init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
  // This will be called when the binding is first applied to an element
  // Set up any initial state, event handlers, etc. here
  },
update: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
  // This will be called once when the binding is first applied to an element,
  // and again whenever any observables/computeds that are accessed change
  // Update the DOM element based on the supplied values here.
  }
};

然后就可以向DOM元素使用它了。

回调函数

创建自定义绑定时需要提供回调函数 init
和 update
，可以只提供其中一个。

ko会在绑定应用到元素上时调用 init
，之后便不再调用，一般用于初始化元素状态和注册事件的回调函数。

ko会在初始绑定应用到元素上时调用 update
，然后在其访问的任意依赖变化时也会调用。

回调函数的参数：

element：使用绑定的DOM元素。
valueAccessor：返回绑定的模型属性的js函数。例如调用 valueAccessor()
来获取当前模型属性值。为了能兼容监控变量和普通值，使用 ko.unwrap
，如 ko.unwrap(valueAccessor())
。
allBindings：可以用来访问DOM元素绑定的所有模型值的js对象。例如 allBindings.get(“name”)
获取 name
绑定的值，不存在时为 undefined
。可以用 allBindings.has(“name”)
来检测其是否存在。
bindingContext：包含该元素的绑定可用的上下文的对象。（在v3版本之前，该参数是绑定的试图模型 viewModel
，现在可用 bindingContext.$data
或 bindingContext.$rawData
来代替。）

例如，可以用 visible
绑定来控制元素的可见性，但希望在元素状态变化时添加动画。可以使用jQuery的 slideUp
/ slideDown
创建一个自定义绑定。

ko.bindingHandlers.slideVisible = {
update: function(element, valueAccessor, allBindings) {
  // First get the latest data that we"re bound to
  var value = valueAccessor();
  // Next, whether or not the supplied model property is observable, get its current value
  var valueUnwrapped = ko.unwrap(value);
  // Grab some more data from another binding property
  var duration = allBindings.get("slideDuration") || 400; // 400ms is default duration unless otherwise specified
  // Now manipulate the DOM element
  if (valueUnwrapped == true)
$(element).slideDown(duration); // Make the element visible
  else
$(element).slideUp(duration);   // Make the element invisible
  }
};

<div data-bind="slideVisible: giftWrap, slideDuration:600">You have selected the option</div>
<label><input type="checkbox" data-bind="checked: giftWrap" /> Gift wrap</label>

<script type="text/javascript">
var viewModel = {
giftWrap: ko.observable(true)
};
ko.applyBindings(viewModel);
</script>

如果希望 slideVisible
在页面第一次加载时不使用动画，只是在用户改变模型状态时才出现动画，可以添加 init
方法:

ko.bindingHandlers.slideVisible = {
init: function(element, valueAccessor) {
  var value = ko.unwrap(valueAccessor()); // Get the current value of the current property we"re bound to
$(element).toggle(value); // jQuery will hide/show the element depending on whether "value" or true or false
  },
update: function(element, valueAccessor, allBindings) {
  // Leave as before
  }
};

DOM变化后更新监控属性

上面展示了如何使用 update
来根据监控属性变化更新DOM元素，那怎样在用户操作DOM元素之后更新关联的监控属性呢？

可以在 init
中注册一些事件的回调函数来更新监控属性。

ko.bindingHandlers.hasFocus = {
init: function(element, valueAccessor) {
$(element).focus(function() {
  var value = valueAccessor();
value(true);
  });
$(element).blur(function() {
  var value = valueAccessor();
value(false);
  });
  },
update: function(element, valueAccessor) {
  var value = valueAccessor();
  if (ko.unwrap(value))
element.focus();
  else
element.blur();
  }
};

<p>Name: <input data-bind="hasFocus: editingName" /></p>


<div data-bind="visible: editingName">You"re editing the name</div>
<button data-bind="enable: !editingName(), click:function() { editingName(true) }">Edit name</button>

<script type="text/javascript">
var viewModel = {
editingName: ko.observable()
};
ko.applyBindings(viewModel);
</script>

控制后代的自定义绑定

默认情况下，绑定只会作用于应用它的元素。如果希望作用于所有后代元素，只需在 init
中 return { controlsDescendantBindings: true }
。

ko.bindingHandlers.allowBindings = {
init: function(elem, valueAccessor) {
  // Let bindings proceed as normal *only if* my value is false
  var shouldAllowBindings = ko.unwrap(valueAccessor());
  return { controlsDescendantBindings: !shouldAllowBindings };
  }
};

<div data-bind="allowBindings: true">
  
  <div data-bind="text: "Replacement"">Original</div>
</div>
<div data-bind="allowBindings: false">
  
  <div data-bind="text: "Replacement"">Original</div>
</div>

向后代绑定传递额外参数

通常使用 controlsDescendantBindings
的绑定也会调用 ko.applyBindingsToDescendants(someBindingContext, element)
，使后代绑定应用于一些修改的上下文。

例如，自定义的绑定 withProperties
向绑定上下文附加一些额外的属性，以便在后代绑定中能访问。

ko.bindingHandlers.withProperties = {
init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
  // Make a modified binding context, with a extra properties, and apply it to descendant elements
  var innerBindingContext = bindingContext.extend(valueAccessor);
ko.applyBindingsToDescendants(innerBindingContext, element);
  // Also tell KO *not* to bind the descendants itself, otherwise they will be bound twice
  return { controlsDescendantBindings: true };
  }
};

可以看到，绑定上下文有个 extend
方法，返回一个复制的并带有额外属性的上下文。 extend
方法接受的参数要么是一个带有属性的对象，要么是能返回这样的对象的函数。建议使用函数作为参数，这样后续的绑定值变化也会更新到绑定上下文中，并且不影响当前的绑定上下文，也就是说不影响兄弟层级的元素，只会影响后代元素。

<div data-bind="withProperties: { emotion: "happy" }">
Today I feel <span data-bind="text: emotion"></span>. 
</div>
<div data-bind="withProperties: { emotion: "whimsical" }">
Today I feel <span data-bind="text: emotion"></span>. 
</div>

在绑定上下文中添加额外的层级

with
和 foreach
绑定会在绑定上下文中添加额外的层级。这意味着它们的后代能够使用 $parent
、 $parents
、 $root
或 $parentContext
来访问外层数据。

如果在自定义绑定中实现该功能，除了使用 bindingContext.extend()
，还可以使用 bindingContext.createChildContext(someData)
。它会返回一个新上下文，该上下文的视图模型是 someData
，父上下文 $parentContext
是 bindingContext
。如果需要，还可以使用 ko.utils.extend
为该子上下文扩展额外的属性。

ko.bindingHandlers.withProperties = {
init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
  // Make a modified binding context, with a extra properties, and apply it to descendant elements
  var childBindingContext = bindingContext.createChildContext(
bindingContext.$rawData,
  null, // Optionally, pass a string here as an alias for the data item in descendant contexts
  function(context) {
ko.utils.extend(context, valueAccessor());
  });
ko.applyBindingsToDescendants(childBindingContext, element);
  // Also tell KO *not* to bind the descendants itself, otherwise they will be bound twice
  return { controlsDescendantBindings: true };
  }
};

这样， withProperties
绑定就可以嵌套使用了，并且每个嵌套层级可以通过 $parentContext
访问父层。

<div data-bind="withProperties: { displayMode: "twoColumn" }">
The outer display mode is <span data-bind="text: displayMode"></span>.
<div data-bind="withProperties: { displayMode: "doubleWidth" }">
The inner display mode is <span data-bind="text: displayMode"></span>, but I haven"t forgotten
that the outer display mode is <span data-bind="text: $parentContext.displayMode"></span>.
</div>
</div>

支持虚拟元素的自定义绑定

使用 ko.virtualElements.allowedBindings
告诉ko自定义绑定能够识别虚拟元素。

例如，创建一个对DOM节点随机排序的自定义绑定：

ko.bindingHandlers.randomOrder = {
init: function(elem, valueAccessor) {
  // Pull out each of the child elements into an array
  var childElems = [];
  while(elem.firstChild)
childElems.push(elem.removeChild(elem.firstChild));
  // Put them back in a random order
  while(childElems.length) {
  var randomIndex = Math.floor(Math.random() * childElems.length),
chosenChild = childElems.splice(randomIndex, 1);
elem.appendChild(chosenChild[0]);
  }
  }
};

这对普通DOM元素是可用的：

<div data-bind="randomOrder: true">
  <div>First</div>
  <div>Second</div>
  <div>Third</div>
</div>

但是对虚拟元素却不起作用，会报错“The binding “randomOrder” cannot be used with virtual elements”：

<div>First</div>
  <div>Second</div>
  <div>Third</div>

要想 randomOrder
支持虚拟元素，需要配置ko：

ko.virtualElements.allowedBindings.randomOrder = true;

这样就不会报错了，但仍然不起作用，因为绑定中调用的是普通DOM的API，不识别虚拟元素。这就是为什么ko要求显式地声明支持虚拟元素。使用虚拟元素API更新自定义绑定：

ko.bindingHandlers.randomOrder = {
init: function(elem, valueAccessor) {
  // Build an array of child elements
  var child = ko.virtualElements.firstChild(elem),
childElems = [];
  while (child) {
childElems.push(child);
child = ko.virtualElements.nextSibling(child);
  }
  // Remove them all, then put them back in a random order
ko.virtualElements.emptyNode(elem);
  while(childElems.length) {
  var randomIndex = Math.floor(Math.random() * childElems.length),
chosenChild = childElems.splice(randomIndex, 1);
ko.virtualElements.prepend(elem, chosenChild[0]);
  }
  }
};

现在该绑定对普通DOM元素和虚拟元素都支持了，因为 ko.virtualElements
的API是兼容普通DOM元素的。

虚拟元素API

ko.virtualElements.allowedBindings

该对象的key决定哪些绑定可用于虚拟元素。如 ko.virtualElements.allowedBindings.mySuperBinding = true
意味着允许 mySuperBinding
用于虚拟元素。
ko.virtualElements.emptyNode(containerElem)

移除真实或虚拟元素 containerElem
的所有子节点（通过清除他们关联的任何数据来避免内存泄露）。

ko.virtualElements.firstChild(containerElem)

返回真实或虚拟元素 containerElem
的第一个子节点，不存在时返回null。

ko.virtualElements.insertAfter(containerElem, nodeToInsert, insertAfter)

添加 nodeToInsert
为真实或虚拟元素 containerElem
的子节点，位置在 insertAfter
之后（ insertAfter
必须是 containerElem
的子节点）。

ko.virtualElements.nextSibling(node)

返回真实或虚拟元素的 node
的后的兄弟节点，不存在时返回null。

ko.virtualElements.prepend(containerElem, nodeToPrepend)

将 nodeToPrepend
添加为真实或虚拟元素 containerElem
的第一个子节点。

ko.virtualElements.setDomNodeChildren(containerElem, arrayOfNodes)

移除真实或虚拟元素 containerElem
的所有子节点（通过清除他们关联的任何数据来避免内存泄露），并将 arrayOfNodes
中的节点作为的新的子节点插入。

自定义DISPOSE

在使用模板绑定或流程控制绑定时，一些DOM元素会被动态添加或移除。当创建自定义绑定时，通常需要添加ko移除关联的元素时的清除逻辑。

为元素的释放注册回调函数

调用 ko.utils.domNodeDisposal.addDisposeCallback(node, callback)
来注册节点被删除的回调函数。

ko.bindingHandlers.myWidget = {
init: function(element, valueAccessor) {
  var options = ko.unwrap(valueAccessor()),
  $el = $(element);
  $el.myWidget(options);
ko.utils.domNodeDisposal.addDisposeCallback(element, function() {
  // This will be called when the element is removed by Knockout or
  // if some other part of your code calls ko.removeNode(element)
  $el.myWidget("destroy");
  });
  }
};

覆盖外部数据的清除逻辑

当ko移除元素时会执行清除逻辑来清除该元素关联的任何数据。在清除逻辑中，如果jQuery可用，那么是通过调用jQuery的 cleanData
方法。在一些高级的应用场景中，可能希望阻止或自定义数据移除的方式。可以通过覆盖 ko.utils.domNodeDisposal.cleanExternalData(node)
支持自定义逻辑。例如，要阻止调用 cleanData
，可以用一个空函数来替代标准的 cleanExternalData
实现。

ko.utils.domNodeDisposal.cleanExternalData = function () {
// Do nothing. Now any jQuery data associated with elements will
// not be cleaned up when the elements are removed from the DOM.
};

使用预处理（PREPROCESSING）扩展KO的绑定语法

从ko V3.0版本开始，ko支持通过添加一个可以在绑定过程中重写DOM节点并绑定字符串的回调函数来定义一个自定义语法。

预处理绑定字符串

可以为某个绑定处理器（click、visible或自定义绑定）提供一个绑定预处理器（binding preprocessor）来链接到ko的 data-bind
解释逻辑中。

通过对绑定处理器添加 preprocess
函数。

ko.bindingHandlers.yourBindingHandler.preprocess = function(stringFromMarkup) {
  // Return stringFromMarkup if you don"t want to change anything, or return
  // some other string if you want Knockout to behave as if that was the
  // syntax provided in the original HTML
}

例1：为绑定设置默认值

如果绑定是没有指定value，会默认为 undefined
。可以使用预处理器使绑定有个初始值。

ko.bindingHandlers.uniqueName.preprocess = function(val) {
return val || "true";
}

uniqueName
将允许绑定时不指定value，而默认为 true
。

例2：为事件绑定表达式

如果希望为 click
事件绑定表达式（而不是ko期望的函数引用），可以使用预处理器。

ko.bindingHandlers.click.preprocess = function(val) {
return "function($data,$event){ " + val + " }";
}

<button type="button" data-bind="click: myCount(myCount()+1)">Increment</button>

绑定预处理器

ko.bindingHandlers. .preprocess(value, name, addBindingCallback)

如果定义了该函数，那么在绑定被评估之前每个 <name>
的绑定时都会调用该函数。

preprocess
的参数如下：

value：ko试图解析绑定之前，绑定的值的语法。（例如 yourBinding: 1 + 1
中，关联的值是字符串"1 + 1"）
name：绑定的名称。（例如 yourBinding: 1 + 1
中，名称是字符串"yourBinding"）
addBinding：可选的回调函数，用于为当前元素添加另一个绑定。它有两个参数， name
和 value
。例如，在预处理方法中，调用 addBinding(“visible”, “acceptsTerms()”);
来让ko表现得看起来就像元素已经有了 visible: acceptsTerms()
绑定。

preprocess
必须返回一个新的字符串值来被解析并传递给绑定，或者返回 undefined
来移除绑定。返回非字符串值是没有意义的，因为HTML一定是字符串。例如将”value + ".toUpperCase()"”作为字符串返回，那么 yourBinding: "Bert"
会被解析成就像HTML中包含 yourBinding: "Bert".toUpperCase()
一样。ko会按照正常方式解析返回的值，因此必须是合法的js表达式。

预处理DOM节点

可以提供一个节点预处理器（node preprocessor）来链接到ko的DOM处理中。ko会在遍历每个DOM节点时调用该函数一次，包括初次绑定UI，和后续的任意DOM子树被注入时。

通过向 bindingProvider
提供一个 preprocessNode
：

ko.bindingProvider.instance.preprocessNode = function(node) {
  // Use DOM APIs such as setAttribute to modify "node" if you wish.
  // If you want to leave "node" in the DOM, return null or have no "return" statement.
  // If you want to replace "node" with some other set of nodes,
  // - Use DOM APIs such as insertChild to inject the new nodes
  // immediately before "node"
  // - Use DOM APIs such as removeChild to remove "node" if required
  // - Return an array of any new nodes that you"ve just inserted
  // so that Knockout can apply any bindings to them
}

例3：虚拟模板元素

用常规的语法在虚拟元素上使用模板时比较复杂。通过使用预处理，可以添加一个使用单注解的模板格式：

ko.bindingProvider.instance.preprocessNode = function(node) {
  // Only react if this is a comment node of the form 
  if (node.nodeType == 8) {
  var match = node.nodeValue.match(/^s*(templates*:[sS]+)/);
  if (match) {
  // Create a pair of comments to replace the single comment
  var c1 = document.createComment("ko " + match[1]),
c2 = document.createComment("/ko");
node.parentNode.insertBefore(c1, node);
node.parentNode.replaceChild(c2, node);
  // Tell Knockout about the new nodes so that it can apply bindings to them
  return [c1, c2];
  }
  }
}

然后可以在视图中这样使用模板：

KO.BINDINGPROVIDER.INSTANCE.PREPROCESSNODE(NODE)

在绑定处理前每个DOM节点都会调用该函数。它可以修改、移除或替换节点 node
。任何新节点回被立刻插入到 node
之前，并且如果有节点被添加或 node
被移除，该函数必须返回html文档中 node
位置的新的节点数组。

参考资料：

KnockoutJS Documentation

码农公寓