KnockoutJS 3.X API 第六章組件(2) 組件注冊

要使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 constructor
define(['knockout'], function(ko) {
    function MyViewModel() {
        // ...
    }
 
    return MyViewModel;
});

..或共享對象實例，例如：

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

..或createViewModel函數，例如：

// AMD module whose value is a 'createViewModel' function
define(['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 formats
define(['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 component
define(['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>'
    };
});

SmallProgram

Why join the navy if you can be a pirate!

KnockoutJS 3.X API 第六章組件(2) 組件注冊

本節目錄

將組件注冊為viewmodel/template

指定視圖模型

構造函數：

共享對象實例：

一個createViewModel工廠函數：

一個AMD模塊，其值描述一個viewmodel

指定模板

現有的元素ID

現有元素實例

一串標記

DOM節點數組

文檔片段

其值描述模板的AMD模塊

指定其他組件選項

控制同步/異步加載

Knockout如何通過AMD加載組件

AMD模塊只在需要時加載

將組件注冊為單個AMD模塊

推薦的AMD模塊模式

公告

SmallProgram

Why join the navy if you can be a pirate!

KnockoutJS 3.X API 第六章 組件(2) 組件注冊

本節目錄

將組件注冊為viewmodel/template

指定視圖模型

構造函數：

共享對象實例：

一個createViewModel工廠函數：

一個AMD模塊，其值描述一個viewmodel

指定模板

現有的元素ID

現有元素實例

一串標記

DOM節點數組

文檔片段

其值描述模板的AMD模塊

指定其他組件選項

控制同步/異步加載

Knockout如何通過AMD加載組件

AMD模塊只在需要時加載

將組件注冊為單個AMD模塊

推薦的AMD模塊模式

公告

KnockoutJS 3.X API 第六章組件(2) 組件注冊