Compartilhar via

Criar Controles de Cliente Personalizados AJAX

  • Artigo

Esta visão geral mostra como criar um controle de cliente ASP.NET AJAX personalizado e usá-lo em uma página.Durante esta explicação passo a passo, você aprenderá a fazer o seguinte:

  • Use o padrão de design de protótipo em ECMAScript (JavaScript) para definir uma classe de controle.

  • Registre um controle como uma classe que deriva de classe base de Sys.UI.Control.

  • Inicializar a classe base Control e chamar seus métodos.

  • Criar eventos personalizados que um desenvolvedor de página pode vincular e manipular.

  • Usar o controle de cliente em uma página e vincular a eventos do controle.

A visão geral fornece um exemplo de um controle de cliente completo que cria um botão com o comportamento de foco.

Esta visão geral se concentra nos controles de cliente.Há três tipos de objetos de componente cliente AJAX ASP.NET:

  • Componentes não visuais que derivam de classe base Sys.Component e que não possuem nenhuma representação na interface do usuário.

  • Comportamentos que derivar de Sys.UI.Behavior.

  • Controles que derivam de Control.

A tabela a seguir resume as diferenças entre componentes, comportamentos e controles.

Tipos de Objeto Componente Cliente

Resumo

Componentes

  • Derivam a partir da classe base Component.

  • Geralmente têm nenhuma representação interface do usuário, como um componente de timer que gera eventos em intervalos mas não está visível na página.

  • Não têm nenhum elemento DOM associado.

  • Encapsular código do cliente que deve ser reutilizável para todos os aplicativos.

Comportamentos

  • Derivado da classe base Behavior, que estende a classe base Component.

  • Estende o comportamento de elementos DOM, como um comportamento marca d´água que pode ser anexado a um caixa de texto existente.

  • Pode criar elementos de interface do usuário, embora eles normalmente não modificam a marcação do elemento DOM associado ao qual eles estão conectados.

  • Se uma identificação (ID) for atribuída, pode ser acessada diretamente do elemento DOM através um atributo personalizado (expando).

  • Não é necessário uma associação com outro objeto do cliente, como uma classe derivada das classes Control ou Behavior.

  • Pode fazer referência a um controle ou um elemento HTML não controle em suas propriedades elemento.

Controles

  • Derivado da classe base Control, que estende a classe base Component.

  • Representa um elemento DOM como um objeto de cliente, normalmente alterarando o comportamento comum do elemento DOM original para fornecer nova funcionalidade.Por exemplo, um controle de menu pode ler itens li de um elemento ul como o dados de origem, mas não exibir uma lista com marcadores.

  • São acessados a partir do elemento DOM diretamente por meio de controle expando.

Pré-requisitos

Para executar o exemplo de controle de cliente fornecido neste tópico, você precisará:

Criando a funcionalidade básica para um controle de cliente personalizado do ASP.NET AJAX

Um controle de cliente ASP.NET AJAX representa um elemento como um cliente objeto DOM e estende uma representação de marcação ou fornece funcionalidade adicional para o elemento.Por exemplo, um controle de cliente pode estender um elemento HTML para reagir a eventos de mouse aplicando estilos CSS diferentes.

Um controle de cliente encapsula o código JavaScript que destina-se a ser reutilizável para vários aplicativos.Pela derivação a partir da classe base Control, o controle personalizado automaticamente herda muitos recursos internos de navegador cruzados, que inclui o seguinte:

  • O recurso para adicionar e remover manipuladores de eventos para elementos DOM associados ao controle e manipuladores de eventos para o controle propriamente dito.

  • Registro automático do controle como uma objeto descartável que implementa a interface Sys.IDisposable.

  • A capacidade de disparar eventos de notificação quando as propriedades são alteradas.

  • A capacidade realizar processamento em lotes de configurações de propriedades de controle.Isso é mais eficiente no tamanho do script e tempo processamento do que o tratamento de toda a lógica nos acessores get e set de propriedades individuais.

Implementar um Controle de Cliente

A tabela a seguir resume as etapas para implementar um controle de cliente personalizado derivado de Control.Informações mais detalhadas sobre cada etapa seguem a tabela.

Por Etapa

Resumo

Defina uma classe de controle de cliente usando o padrão de design de protótipo.

  1. Registre o namespace de sua classe de controle.

  2. Defina a função de construtor do controle para receber um argumento elemento DOM e defina um protótipo.

  3. Registre a função do controle como uma classe que é derivada da classe base Control.

Inicializar instância base Control do controle e passar o elemento associado DOM como um argumento.

  • No construtor do controle, chamar seu método Type.initializeBase herdado e passar o elemento DOM recebido no argumento do construtor para a base.

Expor quaisquer acessores de propriedade e, opcionalmente, disparar um evento de notificação Sys.Component.propertyChanged.

  • Expor propriedades no protótipo do componente com métodos de assessor get e set.

  • Para quaisquer propriedades onde notificação de alteração pode ser importante, dispare um evento propertyChanged de notificação a partir do acessor set da propriedade.

Substituir o método Sys.UI.Control.Initialize para inicializar quaisquer propriedades e ouvintes de eventos.

Se houver quaisquer propriedades ou ouvintes de evento para o componente ou elementos DOM a serem inicializados, substitua o método initialize no protótipo do componente.No método substituído, faça o seguinte:

  • Adicione todos os representantes para eventos DOM do objeto window ou de um elemento chamando o método Sys.UI.DomEvent.addHandler.

  • Defina todas as propriedades iniciais do elemento DOM.

  • Defina todas as propriedades de acessibilidade, como a guia índice no elemento DOM ou do atributo role do controle.

  • Chame o método initialize da classe base.

Substitua o método Sys.UI.Control.Dispose para liberar recursos, como remover manipuladores de eventos DOM.

Se houver quaisquer recursos para liberar antes do controle ser descartado, substitua o método dispose no protótipo do componente.No método substituído, faça o seguinte:

  • Pare todos os processos que o controle pode colocar na fila internamente e desative todas as funcionalidade que são exposta aos chamadores.

  • Remova manipuladores de eventos DOM antes do controle ser descartado.Desmarcando todos os manipuladores elemento DOM que são definidas pelo seu controle, você remove qualquer referência circular a esses elementos DOM e libera a memória reservada para esses elementos.

  • Chame o método dispose base.Todo o código no método dispose deve poder ser chamado pelo várias vezes.Por exemplo, antes de tentar liberar um recurso, verifique se que o recurso ainda não foi liberado.

Definindo uma Classe de Controle usando o Protótipo de Design Padrão

Uma classe de cliente ASP.NET AJAX, que inclui uma classe de controle, é definida no JavaScript usando o padrão de design de protótipo.Para obter detalhes, consulte:Criando uma Classe de Componente de Cliente Usando o Modelo Protótipo.

Uma classe de controle de cliente deve ser derivada da classe base Control.Você registra uma classe de cliente ASP.NET AJAX como uma classe com o aplicativo cliente, usando o método Type.registerClass.Para obter mais informações, consulte Método tipo.registerClass.

Inicializando a Classe Base

O objeto Control base é inicializado no construtor do controle.No construtor do controle, você invoca o seu método initializeBase herdado e passa o elemento DOM recebido no argumento do construtor para a classe base.Normalmente o método initializeBase é chamado antes de qualquer outro código é executado no construtor.Quando a classe base Control é inicializada, seus métodos estão disponíveis para o controle, e ele automaticamente registra o controle como um objeto descartável com a instância Sys.Application.Para obter mais informações, consulte Interface sys.IDisposable.

O exemplo a seguir mostra uma função de construtor para um controle que é derivado de Control.O componente do construtor chama o método initializeBase herdado.

Samples.SimpleControl = function(element)
{
    Samples.SimpleControl.initializeBase(this, [element]);
}

Definindo Propriedades e Disparando Notificações de Alteração de Propriedade

Você definir propriedades na classe do controle do cliente que os desenvolvedores de página podem obter e definir.Você também pode disparar eventos de notificação propertyChanged para propriedades do seu componente.Desenvolvedores de página que usam o componente podem então vincular a esses eventos.Um componente do ASP.NET AJAX derivada da classe base Component, Behavior ou Control herda o método Sys.Component.raisePropertyChanged, que você chama para disparar um evento propertyChanged.Para obter mais informações, consulte Definindo Propriedades de Componente Personalizadas e Disparando Eventos PropertyChanged.

Inicializar Propriedades e Ouvintes de Eventos (Event Listeners)

Se o controle personalizado deve inicializar quaisquer propriedades ou ouvintes de eventos, substituir o método initialize no protótipo do componente.Um controle de cliente que é derivado de classe base Control normalmente vincula qualquer manipuladores a seus eventos de elemento DOM e define as propriedades do elemento DOM para valores iniciais.Como uma etapa final, você chama o método initialize base para ativar o componente do classe base para concluir a inicialização.

Liberando recursos

Se o controle personalizado deve liberar recursos antes do controle ser descartado, substituir o método dispose e liberar os recursos no método substituído.Isso assegura que os recursos são liberados imediatamente antes do componente ser destruído.Recursos para liberar incluem manipuladores que são usados para vincular a eventos DOM.Verificando se quaisquer possíveis referências circulares entre elementos DOM e o componente objeto foram removidas, você certifica-se de que o objeto pode ser removido da memória.Para obter mais informações, consulte Liberando Recursos de Componentes.

Usando um Controle em uma Página

Para usar um controle de cliente personalizado um página da Web ASP.NET, faça o seguinte:

  • Registrar a biblioteca de script do controle de cliente na página da Web.

  • Crie uma instância do controle de cliente.

As seções a seguir fornecem detalhes sobre essas etapas.

Registrando uma Biblioteca de Script do Controle na página da Web

Você pode registrar os scripts necessários para um controle de cliente na página com um controle ScriptManager, declarativamente ou por meio de programação.

O exemplo a seguir mostra a marcação declarativa para um controle ScriptManager que registra um script de controle.

<form id="form1" >
  <asp:ScriptManager  ID="ScriptManager01">
    <scripts>
      <asp:ScriptReference path="HoverButton.js" />
    </scripts>
  </asp:ScriptManager>
</form>

O elemento asp:ScriptManager contém um elemento asp:ScriptReference dentro de um nó scripts.O atributo path do elemento asp:ScriptReference referencia o caminho do arquivo HoverButton.js que define uma classe de controle.Para obter mais informações, consulte Atribuindo Referências a Scripts Dinamicamente e a visão geral da classe ScriptManager .

Observação:

Todos os arquivos de script autônomo que serão registrados com o controle ScriptManager devem chamar o método notifyScriptLoaded para notificar o aplicativo que o script terminou o carregamento.Scripts incorporados em um conjunto de módulos (assembly) não devem chamar este método a maior parte do tempo.Para obter mais informações, consulte Método Sys.Aplicativo.notifyScriptLoaded.

Como uma alternativa para registrar os arquivos de script usando o controle ScriptManager, você pode gerenciar os componentes do cliente usando um controle de servidor personalizado que implementa a interface IScriptControl.Um controle de servidor personalizado pode registrar os scripts de componente necessários automaticamente e expor marcação declarativa para configuração de propriedades do componente e vinculações de eventos.Isso torna mais fácil para um desenvolvedor de página usar o controle personalizado.Para obter mais informações, consulte a visão geral da classe IScriptControl.

Criando uma instância de controle personalizado

Você instancia um controle de cliente personalizado chamando o Sys.componente.criar método ou a $ criar atalho durante o Sys.aplicativo.Init evento.A tabela a seguir descreve os parâmetros que você passa para o método $create quando você cria um controle de cliente.

Parâmetro

Descrição

type

O tipo de componente.

properties

Um objeto JSON que contém um valor de identificação (ID) do componente e, opcionalmente, quaisquer pares iniciais de nome da propriedade/valor.

events

Um objeto JSON opcional que contém nome do evento e pares de ligação evento/manipulador.

references

Um objeto JSON opcional que contém referências a componentes associados, passados como pares nome do componente/ID.

element

O elemento DOM para associar ao controle.

Este exemplo a seguir mostra como instanciar uma instância de controle chamando o método $create.

$create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));

Para obter mais informações, consulte Método Sys.componente.Criar e $ Sys.componente criar método.

Criando o Controle Personalizado HoverButton

Nesta seção você criará um simples controle de cliente personalizado chamado HoverButton que estende a classe base Control e, em seguida, usar o controle em uma página.O controle HoverButton intercepts os eventos click, focus e mouseover de um elemento button HTML associado.Ele também fornece os controles com os eventos que são associáveis através do método $create.Um desenvolvedor de página que usa o controle HoverButton pode vincular ao evento hover do controle.

Para criar o código para o controle HoverButton

  1. No diretório raiz de um site da Web ASP.NET com AJAX Habilitado, crie um arquivo denominado HoverButton.js.

  2. Adicione o seguinte código ao arquivo:

    Type.registerNamespace("Demo");

// Constructor
Demo.HoverButton = function(element) {

    Demo.HoverButton.initializeBase(this, [element]);

    this._clickDelegate = null;
    this._hoverDelegate = null;
    this._unhoverDelegate = null;
}
Demo.HoverButton.prototype = {

    // text property accessors.
    get_text: function() {
        return this.get_element().innerHTML;
    },
    set_text: function(value) {
        this.get_element().innerHTML = value;
    },

    // Bind and unbind to click event.
    add_click: function(handler) {
        this.get_events().addHandler('click', handler);
    },
    remove_click: function(handler) {
        this.get_events().removeHandler('click', handler);
    },

    // Bind and unbind to hover event.
    add_hover: function(handler) {
        this.get_events().addHandler('hover', handler);
    },
    remove_hover: function(handler) {
        this.get_events().removeHandler('hover', handler);
    },

    // Bind and unbind to unhover event.
    add_unhover: function(handler) {
        this.get_events().addHandler('unhover', handler);
    },
    remove_unhover: function(handler) {
        this.get_events().removeHandler('unhover', handler);
    },

    // Release resources before control is disposed.
    dispose: function() {

        var element = this.get_element();

        if (this._clickDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'click', this._clickDelegate);
            delete this._clickDelegate;
        }

        if (this._hoverDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'focus', this._hoverDelegate);
            Sys.UI.DomEvent.removeHandler(element, 'mouseover', this._hoverDelegate);
            delete this._hoverDelegate;
        }

        if (this._unhoverDelegate) {
            Sys.UI.DomEvent.removeHandler(element, 'blur', this._unhoverDelegate);
            Sys.UI.DomEvent.removeHandler(element, 'mouseout', this._unhoverDelegate);
            delete this._unhoverDelegate;
        }
        Demo.HoverButton.callBaseMethod(this, 'dispose');
    },

    initialize: function() {

        var element = this.get_element();

        if (!element.tabIndex) element.tabIndex = 0;

        if (this._clickDelegate === null) {
            this._clickDelegate = Function.createDelegate(this, this._clickHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'click', this._clickDelegate);

        if (this._hoverDelegate === null) {
            this._hoverDelegate = Function.createDelegate(this, this._hoverHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'mouseover', this._hoverDelegate);
        Sys.UI.DomEvent.addHandler(element, 'focus', this._hoverDelegate);

        if (this._unhoverDelegate === null) {
            this._unhoverDelegate = Function.createDelegate(this, this._unhoverHandler);
        }
        Sys.UI.DomEvent.addHandler(element, 'mouseout', this._unhoverDelegate);
        Sys.UI.DomEvent.addHandler(element, 'blur', this._unhoverDelegate);

        Demo.HoverButton.callBaseMethod(this, 'initialize');

    },
    _clickHandler: function(event) {
        var h = this.get_events().getHandler('click');
        if (h) h(this, Sys.EventArgs.Empty);
    },
    _hoverHandler: function(event) {
        var h = this.get_events().getHandler('hover');
        if (h) h(this, Sys.EventArgs.Empty);
    },
    _unhoverHandler: function(event) {
        var h = this.get_events().getHandler('unhover');
        if (h) h(this, Sys.EventArgs.Empty);
    }
}
Demo.HoverButton.registerClass('Demo.HoverButton', Sys.UI.Control);

// Since this script is not loaded by System.Web.Handlers.ScriptResourceHandler
// invoke Sys.Application.notifyScriptLoaded to notify ScriptManager 
// that this is the end of the script.
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

Discussão de Código

O código registra o namespace Demo chamando o método Type.registerNamespace.O construtor chama o método initializeBase herdado para que os métodos da classe base Control fiquem disponíveis.A classe base inicializada, por sua vez, registra a instância Demo.HoverButton com o aplicativo cliente como um objeto descartável.

No protótipo, o código declara os eventos públicos click, hover e unhover.O desenvolvedor de página pode adicionar e remover manipuladores que escutam esses eventos.Esses métodos por sua vez adicionam ou removem o manipulador especificado da coleção de manipulador de eventos do controle.Você adicionar e remover manipuladores em sua classe de controle por meio do objeto Sys.EventHandlerList do controle.O objeto EventHandlerList contém uma coleção de manipuladores de eventos do controle através da propriedade herdada Sys.Component.Events.No exemplo, o código chama os métodos Sys.EventHandlerList.addHandler e Sys.EventHandlerList.removeHandler do objeto EventHandlerList retornado para adicionar ou remover os manipuladores.

A classe HoverButton substitui o método base dispose para descartar com segurança todos os recursos de controle (como manipuladores de eventos DOM) antes do controle ser descartado.Finalmente, o código chama o método dispose base para permitir que o aplicativo libere o controle.

Usando o controle HoverButton em uma página da Web

Nesta seção, você aprenderá como criar uma instância de controle usando script de cliente em uma página da Web.

Para criar uma página para usar o controle HoverButton

  1. No diretório raiz do aplicativo em que você colocou o arquivo HoverButton.js, crie um arquivo denominado DemoHoverButton.aspx.

  2. Adicione a seguinte marcação e o código ao arquivo:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" >

    <style type="text/css">
        button {border: solid 1px black}
        #HoverLabel {color: blue}
    </style>
    <title>Control Demo</title>
</head>
<body>
    <form id="form1" >
        <div id="ResultDisplay"></div>

            <asp:ScriptManager  ID="ScriptManager01">
                <scripts>
                   <asp:ScriptReference Path="HoverButton.js" />
                </scripts>
            </asp:ScriptManager>

            <script type="text/javascript">
                var app = Sys.Application;
                app.add_init(applicationInitHandler);

                function applicationInitHandler(sender, args) {
                    $create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));
                }

                function doSomethingOnHover(sender, args) {
                    hoverMessage = "The mouse is over the button."
                    $get('HoverLabel').innerHTML = hoverMessage;
                }

                function doSomethingOnUnHover(sender, args) {
                   $get('HoverLabel').innerHTML = "";
                }

                function start(sender, args) {
                   alert("The start function handled the HoverButton click event.");
                }
            </script>

            <button type="button" id="Button1"></button>&nbsp;
        <div id="HoverLabel"></div>
    </form>

</body>
</html>

Discussão de Código

O arquivo DemoHoverButton.aspx é um página da Web do ASP.NET que hospeda o controle personalizado.Na página, as funções que estão acopladas ao controle personalizado estão definidas no elemento script.No manipulador de eventos Sys.Application.Init, o controle HoverButton é instanciado no script de cliente chamando o método $create.O código passa os argumentos a seguir para o método $create:

  • O argumento tipo contém a classe Demo.HoverButton que você criou anteriormente.

  • O argumento properties contém um objeto JSON que contém o valor de identificação do controle necessário, seguido por pares nome da propriedade-valor que especificam nomes de propriedades com valores iniciais.

  • O argumento events contém um objeto que contém nomes de eventos combinados com seus identificadores.

No controle ScriptManager, o atributo caminho do nó asp:ScriptReference referencia o caminho do arquivo HoverButton.js que define uma classe de controle Demo.HoverButton.

Configuração de Manipuladores de Eventos de elementos DOM e Manipuladores de Eventos de Componente

Funcionalidade AJAX no ASP.NET inclui classes que fornecem gerenciamento de eventos padronizadas para componentes e para elementos DOM.Você gerencia os eventos de controle usando membros da classe Sys.EventHandlerList, como addHandler e removeHandler.Para obter mais informações, consulte a visão geral da classe Sys.EventHandlerList.

Você gerencia manipuladores de eventos de elementos DOM ou de eventos do objeto window usando métodos estáticos da classe Sys.UI.DomEvent, addHandler ou removeHandler.Para obter mais informações, consulte a visão geral da classe Sys.UI.DomEvent.

Acessando Propriedades de Elemento DOM

A classe Sys.UI.DomElement contém membros que permitem que você adicione, remova e alterne associações de classe CSS para controles de cliente e para elementos.Esses membros também fornecem acesso padronizado às propriedades do elemento DOM.Para obter mais informações, consulte Classe Sys.UI.DomElement.

Consulte também

Tarefas

Criando Componentes Não Visual de Cliente personalizados

Atribuindo Referências a Scripts Dinamicamente

Conceitos

Usando o controle ASP.NET UpdatePanel com controles associado a dados

Trabalhando com eventos PageRequestManager

Referência

Sys. Classe de Componente

ScriptManager