Como funcionam Bindings de Eventos de Formulário no KnockoutJs

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

• The data-bind syntax
• Binding context
• The "click" binding
• The "event" binding
• The "submit" binding
• The "enable" and "disable" bindings
• The "value" binding
• The "textInput" binding
• The "hasFocus" binding
• The "checked" binding
• The "options" binding
• The "selectedOptions" binding
• The "uniqueName" binding

---

Bindings

No KnockoutJs, bindings são a maneira de conectar a lógica do ViewModel (os dados e a lógica de negócios) com a View (HTML). Em resumo, é através dos bindings que é realizada a interface de usuário refletir automaticamente as mudanças nos seus dados, sem a necessidade de manipular diretamente o DOM.

Os bindings no KnockoutJs funcionam através do atributo data-bind em elementos HTML. Esse atributo é onde você especifica o binding que deseja usar e os valores associados.

Eventos de Formulário

Click

O binding click adiciona um manipulador de eventos para que a função JavaScript escolhida seja invocada quando o elemento DOM associado for clicado. Isso é mais comumente usado em elementos com tag <button>, <input> e <a>, mas na verdade funciona com qualquer elemento DOM visível. O KnockoutJs fornecerá o valor atual do modelo como o primeiro parâmetro.

Cada vez que for clicado no elemento, isso invocará o método que foi passado na ViewModel, que por sua vez altera o estado da ViewModel, o que faz com que a IU seja atualizada.

<div>
    You've clicked <span data-bind="text: numberOfClicks"></span> times
    <button data-bind="click: incrementClickCounter">Click me</button>
</div>

<script type="text/javascript">
        ko.applyBindings({
        numberOfClicks : ko.observable(0),
        incrementClickCounter : function() {
            var previousCount = this.numberOfClicks();
            this.numberOfClicks(previousCount + 1);
        }
    });
</script>

Por padrão, o KnockoutJs impedirá que o evento click execute qualquer ação padrão. Isso significa que ao usar o binding click em uma tag <a>, o navegador apenas chamará a função e não navegará até o href do link. A vinculação de clique é normalmente utilizada quando está usando o link como parte de uma UI que manipula a ViewModel, não como um hiperlink normal para outra página da web. Caso seja necessário que a ação de clique padrão continue, basta retornar true na função.

Event

O binding event permite adicionar um manipulador de eventos para um evento especificado para que a função JavaScript escolhida seja invocada quando esse evento for acionado para o elemento DOM associado. Isso pode ser usado para vincular a qualquer evento, como pressionamento de tecla, passagem do mouse ou saída do mouse.

<div>
    <div data-bind="event: { mouseover: enableDetails, mouseout: disableDetails }">
        Mouse over me
    </div>
    <div data-bind="visible: detailsEnabled">
        Details
    </div>
</div>

<script type="text/javascript">
        ko.applyBindings({
        detailsEnabled: ko.observable(false),
        enableDetails: function() {
            this.detailsEnabled(true);
        },
        disableDetails: function() {
            this.detailsEnabled(false);
        }
    });
</script>

Submit

O binding submit *é uma diretiva de vinculação de envio em um formulário impedirá a ação de envio padrão do navegador para esse formulário, em outras palavras, o navegador chamará a função de manipulador, mas não enviará o formulário ao servidor. A vinculação de *submit é normalmente utilizada quando está sendo usado o formulário como uma interface para a ViewModel, não como um formulário HTML normal. Caso seja necessário que o formulário seja enviado como um formulário HTML normal, basta retornar true do seu manipulador de envio.

<form data-bind="submit: doSomething">
    <button type="submit">Submit</button>
</form>

<script type="text/javascript">
        ko.applyBindings({
        this.doSomething = function(formElement) {
            // ... now do something
        }
    });
</script>

Enable/Disable

O binding enable faz com que o elemento DOM associado seja habilitado quando seu valor de parâmetro for verdadeiro. O binding disable funciona de forma oposta, fazendo com que o elemento DOM associado seja desabilitado quando seu valor for verdadeiro.

<p>
    <input type='checkbox' data-bind="checked: hasCellphone" />
    I have a cellphone
</p>
<p>
    Your cellphone number:
    <input type='text' data-bind="value: cellphoneNumber, enable: hasCellphone" />
</p>

<script type="text/javascript">
        ko.applyBindings({
        hasCellphone : ko.observable(false),
        cellphoneNumber: ""
    });
</script>

Value

O binding value *vincula o valor do elemento DOM associado a uma propriedade na *ViewModel. Isso normalmente é útil com elementos de formulário como <input>, <select> e <textarea>.

Quando o usuário editar o valor no controle de formulário associado, o valor será atualizado na ViewModel. Da mesma forma, quando a ViewModel atualiza o valor, isso atualizará o valor do controle de formulário na tela.

<p>Login name: <input data-bind="value: userName" /></p>
<p>Password: <input type="password" data-bind="value: userPassword" /></p>

<script type="text/javascript">
        ko.applyBindings({
        userName: ko.observable(""),        // Initially blank
        userPassword: ko.observable("abc"), // Prepopulate
    });
</script>

O binding value funciona em conjunto com a vinculação de <options> para permitir a leitura e gravação de valores que são objetos JavaScript arbitrários, e não apenas valores de string.

TextInput

O binding textInput vincula um campo (<input> ou <textarea>) a uma propriedade ViewModel, fornecendo atualizações bidirecionais entre a propriedade ViewModel e o valor do elemento. O binding textInput fornece atualizações instantâneas do DOM para todos os tipos de entrada do usuário, incluindo preenchimento automático, arrastar e soltar e eventos da área de transferência.

<p>Login name: <input data-bind="textInput: userName" /></p>
<p>Password: <input type="password" data-bind="textInput: userPassword" /></p>

ViewModel:
<pre data-bind="text: ko.toJSON($root, null, 2)"></pre>

<script type="text/javascript">
    ko.applyBindings({
        userName: ko.observable(""),        // Initially blank
        userPassword: ko.observable("abc"), // Prepopulate
    });
</script>

O binding textInput, por padrão, só atualiza seu modelo quando o usuário move o foco para fora da caixa de texto. O binding textInput atualiza seu modelo imediatamente a cada pressionamento de tecla ou outro mecanismo de entrada de texto.

HasFocus

O binding hasFocus vincula o estado de foco de um elemento DOM a uma propriedade ViewModel. É uma ligação bidirecional que ao ser definida a propriedade ViewModel como true ou false, o elemento associado ficará focado ou desfocado.

<input data-bind="hasFocus: isSelected" />
<button data-bind="click: setIsSelected">Focus programmatically</button>
<span data-bind="visible: isSelected">The textbox has focus</span>

<script type="text/javascript">
        ko.applyBindings({
            isSelected: ko.observable(false),
            setIsSelected: function() { this.isSelected(true) }
        });
</script>

Checked

O binding checked vincula um controle de formulário verificável, ou seja, uma caixa de seleção (<input type='checkbox'>) ou um botão de opção (<input type='radio'>) com uma propriedade na ViewModel.

<p>Check 1 (checked): <input type="checkbox" data-bind="checked: checkYes" /></p>
<p>Check 2 (unchecked): <input type="checkbox" data-bind="checked: checkNo" /></p> 

<script type="text/javascript">
    ko.applyBindings({
        checkYes: ko.observable(true),
        checkNo: ko.observable(false)
    });
</script>

Options

O binding options controla quais opções devem aparecer em uma lista suspensa (<select>) ou lista de seleção múltipla (<select size='6'>). Esta ligação não pode ser usada com nada além de elementos <select>.

O valor atribuído deve ser um array (ou Observable Array). O elemento <select> exibirá então um item para cada item do seu array.

<p>
    Destination country:
    <select data-bind="options: availableCountries"></select>
    <input data-bind="value: newCountry"/>
    <button data-bind="click: addCountry">Add country</button>
</p>

<script type="text/javascript">
    ko.applyBindings({
        addCountry: function() {
            this.availableCountries.push(this.newCountry());
        },
        newCountry: ko.observable(),        
        availableCountries: ko.observableArray(['Argentina', 'Brazil', 'Chile'])
    });
</script>

SelectedOptions

O binding selectedOptions controla quais elementos em uma lista de seleção múltipla estão selecionados no momento. Destina-se a ser usado em conjunto com um elemento <select> e a ligação de opções.

Quando o usuário seleciona ou desmarca um item na lista de seleção múltipla, isso adiciona ou remove o valor correspondente a uma matriz na ViewModel. Da mesma forma, supondo que seja um Observable Array na ViewModel, sempre que adicionar ou remover itens desse array, os itens correspondentes na UI serão selecionados ou desmarcados. É uma ligação bidirecional.

<p>Choose some countries you'd like to visit:</p>
<select data-bind="options: availableCountries, selectedOptions: chosenCountries" size="5" multiple="true"></select>

<script type="text/javascript">
    ko.applyBindings({
        availableCountries : ko.observableArray(['France', 'Germany', 'Spain']),
        chosenCountries : ko.observableArray(['Germany']) // Initially, only Germany is selected
    });
</script>

UniqueName

O binding uniqueName garante que o elemento DOM associado tenha um atributo de nome não vazio. Se o elemento DOM não tiver um atributo name, essa ligação fornecerá um e o definirá como algum valor de string exclusivo.

<input data-bind="value: someModelProperty, uniqueName: true" />