你的位置:首页 > Java教程

[Java教程]KnockoutJS 3.X API 第六章 组件 组件注册


要使Knockout能够加载和实例化组件,必须使用ko.components.register注册它们,从而提供如此处所述的配置。

注意:作为替代,可以实现一个自定义组件加载器(自定义加载器下一节介绍),通过自己的约定获取组件,而不是显式配置。

本节目录

  • 将组件注册为viewmodel/template
    • 指定视图模型
      • 构造函数
      • 共享对象实例
      • 一个createViewModel工厂函数
      • 一个AMD模块,其值描述一个viewmodel
    • 指定模板
      • 现有元素ID
      • 现有元素实例
      • 一串标记
      • DOM节点数组
      • 文档片段
      • 其值描述模板的AMD模块
    • 指定其他组件选项
      • 控制同步/异步加载
  • Knockout如何通过AMD加载组件
    • AMD模块只在需要时加载
  • 将组件注册为单个AMD模块
    • 推荐的AMD模块模式

将组件注册为viewmodel/template

您可以用如下方式注册组件:

ko.components.register('some-component-name', {  viewModel: <see below>,  template: <see below>});

  • 组件名称可以是任何非空字符串。 建议(但不是强制性的)使用小写分隔符的字符串(例如your-component-name),以便组件名称可用作自定义元素(例如<your-component-name>)。
  • viewModel是可选的,并且可以采用下面描述的任何viewModel格式。
  • template是必填的,并且可以采用下面描述的任何模板格式。

如果没有给出viewmodel,组件将被视为一个简单的HTML块,它将绑定到传递给组件的任何参数。

指定视图模型

视图模型可以通过以下任何形式指定:

构造函数:

function SomeComponentViewModel(params) {  // 'params' is an object whose key/value pairs are the parameters  // passed from the component binding or custom element.  this.someProperty = params.something;} SomeComponentViewModel.prototype.doSomething = function() { ... }; ko.components.register('my-component', {  viewModel: SomeComponentViewModel,  template: ...});

Knockout将为组件的每个实例调用一次构造函数,为每个实例生成一个单独的viewmodel对象。 生成的对象或其原型链上的属性(例如,上面示例中的someProperty和doSomething)可用于在组件视图中绑定。

共享对象实例:

如果你想要你的组件的所有实例共享同一个viewmodel对象实例(这通常是不可取的):

var sharedViewModelInstance = { ... }; ko.components.register('my-component', {  viewModel: { instance: sharedViewModelInstance },  template: ...});

注意,有必要指定viewModel:{instance:object},而不仅仅是viewModel:object。 这与下面的其他情况不同。

一个createViewModel工厂函数:

如果要在关联元素绑定到viewmodel之前运行任何设置逻辑,或使用任意逻辑来决定要实例化哪个viewmodel类:

ko.components.register('my-component', {  viewModel: {    createViewModel: function(params, componentInfo) {      // - 'params' is an object whose key/value pairs are the parameters      //  passed from the component binding or custom element      // - 'componentInfo.element' is the element the component is being      //  injected into. When createViewModel is called, the template has      //  already been injected into this element, but isn't yet bound.      // - 'componentInfo.templateNodes' is an array containing any DOM      //  nodes that have been supplied to the component. See below.       // Return the desired view model instance, e.g.:      return new MyViewModel(params);    }  },  template: ...});

注意,通常,最好仅通过自定义绑定执行直接DOM操作,而不是从createViewModel内部对componentInfo.element执行操作。 这导致更多的模块化,可重用的代码。

如果要构建一个接受任意标记以影响其输出的组件(例如,将提供的标记插入到其自身中的网格,列表,对话框或选项卡集),则componentInfo.templateNodes数组很有用。 有关完整的示例,请参阅将标记传递到组件(将在以后的章节介绍)。

一个AMD模块,其值描述一个viewmodel

如果您的页面中已经有一个AMD加载器(例如require.js),那么您可以使用它来获取一个viewmodel。 有关如何工作的更多细节,看看Knockout如何通过AMD加载组件下面。 例:

ko.components.register('my-component', {  viewModel: { require: 'some/module/name' },  template: ...});

返回的AMD模块对象可以是允许用于viewmodels的任何形式。 因此,它可以是一个构造函数,例如:

// AMD module whose value is a component viewmodel constructordefine(['knockout'], function(ko) {  function MyViewModel() {    // ...  }   return MyViewModel;});

..或共享对象实例,例如:

// AMD module whose value is a shared component viewmodel instancedefine(['knockout'], function(ko) {  function MyViewModel() {    // ...  }   return { instance: new MyViewModel() };});

..或createViewModel函数,例如:

// AMD module whose value is a 'createViewModel' functiondefine(['knockout'], function(ko) {  function myViewModelFactory(params, componentInfo) {    // return something  }     return { createViewModel: myViewModelFactory };});

...甚至,虽然你不太可能想要这样做,一个参考不同的AMD模块,例如:

// AMD module whose value is a reference to a different AMD module,// which in turn can be in any of these formatsdefine(['knockout'], function(ko) {  return { module: 'some/other/module' };});

指定模板

模板可以以下列任何形式指定。 最常用的是现有的元素ID和AMD模块。

现有的元素ID

例如,以下元素:

<template id='my-component-template'>  <h1 data-bind='text: title'></h1>  <button data-bind='click: doSomething'>Click me right now</button></template>

..可以通过指定其ID用作组件的模板:

ko.components.register('my-component', {  template: { element: 'my-component-template' },  viewModel: ...});

注意,只有指定元素内的节点将被克隆到组件的每个实例中。 容器元素(在此示例中为<template>元素)不会被视为组件模板的一部分。

您不仅限于使用<template>元素,但这些方法(在支持它们的浏览器上)很方便,因为它们不会自己呈现。 任何其他元素类型也工作。

现有元素实例

如果你有一个对代码中的DOM元素的引用,你可以使用它作为模板标记的容器:

var elemInstance = document.getElementById('my-component-template'); ko.components.register('my-component', {  template: { element: elemInstance },  viewModel: ...});

同样,只有指定元素中的节点将被克隆用作组件模板。

一串标记

ko.components.register('my-component', {  template: '<h1 data-bind="text: title"></h1>\        <button data-bind="click: doSomething">Clickety</button>',  viewModel: ...});

当你从编程方式(例如,AMD )获取标记,或者作为一个构建系统输出打包组件进行分发时,这是非常有用的,因为手动编辑HTML作为JavaScript字符串文字并不是很方便。

DOM节点数组

如果您以编程方式构建配置,并且具有DOM节点数组,则可以将它们用作组件模板:

var myNodes = [  document.getElementById('first-node'),  document.getElementById('second-node'),  document.getElementById('third-node')]; ko.components.register('my-component', {  template: myNodes,  viewModel: ...});

在这种情况下,所有指定的节点(及其后代)将被克隆并连接到实例化的组件的每个副本。

文档片段

如果您以编程方式构建配置,并且具有Document Fragment对象,则可以将其用作组件模板:

ko.components.register('my-component', {  template: someDocumentFragmentInstance,  viewModel: ...});

由于文档片段可以具有多个顶级节点,因此整个文档片段(不仅仅是顶级节点的后代)被视为组件模板。

其值描述模板的AMD模块

如果您的页面中已经有一个AMD加载器(例如require.js),那么您可以使用它来获取模板。 有关如何工作的更多细节,看看Knockout如何通过AMD加载组件下面。 例:

ko.components.register('my-component', {  template: { require: 'some/template' },  viewModel: ...});

返回的AMD模块对象可以是允许用于viewmodels的任何形式。 因此,它可以是一串标记,例如。 使用requirejs文本插件获取:

ko.components.register('my-component', {  template: { require: 'text!path/my-html-file.html' },  viewModel: ...});

...或这里描述的任何其他形式,虽然它是不常用的,其他人在通过AMD抓取模板时有用。

指定其他组件选项

除了(或代替)template和viewModel,您的组件配置对象可以具有任意其他属性。 此配置对象可用于您可能正在使用的任何自定义组件加载器。

控制同步/异步加载

如果您的组件配置具有布尔同步属性,Knockout使用此属性来确定是否允许同步加载和注入组件。 默认值为false(即,强制为异步)。 例如,

ko.components.register('my-component', {  viewModel: { ... anything ... },  template: { ... anything ... },  synchronous: true // Injects synchronously if possible, otherwise still async});

为什么组件加载通常被强制为异步?

通常,Knockout确保组件加载和组件注入总是异步完成,因为有时它不得不异步(例如,因为它涉及到服务器的请求)。 即使特定组件实例可以被同步注入(例如,因为组件定义已经被加载),它也会这样做。 这种始终异步的策略是一致性的问题,是一种从其他现代异步JavaScript技术(如AMD)继承而来的公认惯例。 约定是一个安全的默认 - 它减轻了潜在的错误,在这种情况下,开发人员可为什么会启用同步加载?能不会考虑通常异步过程有时完成同步或反之亦然的可能性。

为什么会启用同步加载?

如果要更改特定组件的策略,可以在该组件的配置上指定synchronous:true。 然后,它可能在第一次使用时异步加载,随后在所有后续使用上同步加载。 如果这样做,那么您需要在任何等待加载组件的代码中考虑这种可更改的行为。 但是,如果您的组件始终可以同步加载和初始化,则启用此选项将确保一致的同步行为。 如果您在foreach绑定中使用组件并想要使用afterAdd或afterRender选项执行后处理,这可能很重要。

在Knockout 3.4.0之前,您可能需要使用同步加载来防止多个DOM回流同时包含多个组件(例如使用foreach绑定)。 使用Knockout 3.4.0,组件使用Knockout的微任务来确保异步,因此通常会执行和同步加载一样好。

Knockout如何通过AMD加载组件

当您通过require声明加载视图模型或模板时,例如,

ko.components.register('my-component', {  viewModel: { require: 'some/module/name' },  template: { require: 'text!some-template.html' }});

...所有Knockout是调用require(['some / module / name'],回调)和require(['text!some-template.html'],回调),并使用异步返回的对象作为viewmodel和模板 定义。 所以,

  • 这不需要严格依赖require.js或任何其他特定的模块加载器。 任何提供AMD风格的require API的模块加载器都可以。 如果要与API的模块加载器集成,可以实现自定义组件加载器。
  • Knockout不以任何方式解释模块名称 - 它只是将它传递给require()。 所以当然Knockout不知道或关心你的模块文件从哪里加载。 这取决于你的AMD加载器和你如何配置它。
  • Knockout不知道或关心您的AMD模块是否是匿名的。 通常,我们发现最方便的组件被定义为匿名模块,但这个问题完全独立于KO。

AMD模块只在需要时加载

Knockout不调用require([moduleName],...),直到组件被实例化。 这是组件如何按需加载,而不是前面。

例如,如果你的组件里面有一个if绑定(或另一个控制流绑定)的其他元素,那么它不会导致AMD模块加载,直到if条件为真。 当然,如果AMD模块已经加载(例如,在预加载的bundle中),则require调用不会触发任何额外的HTTP请求,因此您可以控制预加载的内容和按需加载的内容。

将组件注册为单个AMD模块

为了更好的封装,您可以将组件封装到一个自我描述的AMD模块中。 然后你可以简单地引用一个组件:

ko.components.register('my-component', { require: 'some/module' });

注意,没有指定viewmodel / template对。 AMD模块本身可以使用上面列出的任何定义格式提供viewmodel /template对。 例如,文件some / module.js可以声明为:

// AMD module 'some/module.js' encapsulating the configuration for a componentdefine(['knockout'], function(ko) {  function MyComponentViewModel(params) {    this.personName = ko.observable(params.name);  }   return {    viewModel: MyComponentViewModel,    template: 'The name is <strong data-bind="text: personName"></strong>'  };});

推荐的AMD模块模式

在实践中最有用的是创建具有内联viewmodel类的AMD模块,并显式地将AMD依赖关系放在外部模板文件上。

例如,如果以下是在路径/ my-component.js的文件中,

// Recommended AMD module pattern for a Knockout component that:// - Can be referenced with just a single 'require' declaration// - Can be included in a bundle using the r.js optimizerdefine(['knockout', 'text!./my-component.html'], function(ko, htmlString) {  function MyComponentViewModel(params) {    // Set up properties, etc.  }   // Use prototype to declare any public methods  MyComponentViewModel.prototype.doSomething = function() { ... };   // Return component definition  return { viewModel: MyComponentViewModel, template: htmlString };});

...并且模板标记位于文件路径/ my-component.html中,则您具有以下好处:

  • 应用程序可以简单地引用它,即ko.components.register('my-component',{require:'path / my-component'});
  • 你只需要两个文件的组件 - 一个viewmodel(path / my-component.js)和一个模板(path / my-component.html) - 这是一个非常自然的安排在开发过程中。
  • 因为在define调用中明确声明了对模板的依赖,所以这自动与r.js优化器或类似的捆绑工具配合使用。 因此,在构建步骤期间,整个组件 - 视图模型和模板 - 可以轻易地包含在包文件中。