Use este artigo para saber como criar componentes personalizados para HTML5 Canvas.

O Animate CC vem com um conjunto de componentes padrão. Contudo, são insuficientes para o seu projeto. Este tópico ajuda a entender como criar componentes HTML5 personalizados para o Animate CC.

Uma definição de componente consiste em três partes importantes:

  • Metadados: fornece informações sobre o componente, como o nome de exibição, a versão, o conjunto de propriedades configuráveis, o ícone e assim por diante. Essas informações são capturadas em um arquivo chamado components.js. Você pode agrupar os componentes como uma categoria e este arquivo permite fornecer metadados para todos os componentes em uma categoria.
  • Origem: fornece informações sobre a origem do componente real. Isso é incorporado no tempo de execução ao visualizar ou publicar um filme usando componentes.
  • Ativos: fornece informações sobre qualquer dependência do tempo de execução, como a biblioteca JavaScript ou CSS ou ativos e ícones de tempo de execução. Os ativos podem ser usados no ambiente de criação do Animate.

Observação:

Uma definição de componente também tem recursos relacionados à localização.

componentsJS
Exemplo de configuração de pasta para uma categoria de componentes personalizados

O Animate CC verifica as seguintes pastas quanto a componentes HTML5 personalizados e os carrega na inicialização:

• Windows:

<AppData>/Local/Adobe/Adobe Animate CC 2017/pt_BR/Configuration/HTML5Components

 

• MAC:

 

~/Library/Application Support/Adobe/Animate CC 2017/pt_BR/Configuration/HTML5Components/

Observação:

O caminho da pasta acima é aplicável para inglês dos EUA. Se você estiver usando o Animate em qualquer outro idioma, procure o nome da pasta específica do seu idioma que substitui en_US.

Para cada pasta dentro do local que contém o arquivo “components.js”, o Animate CC cria uma categoria e carrega todos os componentes.

Metadados do componente

Os metadados do Componente são capturados em um arquivo chamado components.js que é colocado em uma pasta separada dentro do diretório ComponentesHTML5

metadata-code
Exemplo de metadados para um componente de vídeo.

Components.js

Components.js

é um arquivo JSON que contém as seguintes seções:

  • Categoria: nome no painel Componentes para esse conjunto de componentes e pode ser localizado.
  • Componentes: arranjo em que cada entrada contém metadados sobre um componente. O exemplo acima tem apenas um elemento no arranjo. Os metadados têm as seguintes seções:

Nome

Obrigatório

Descrição

ClassName

Sim

Nome da classe do componente especificado no arquivo de origem. O nome da classe suporta um nível de namespaces. Por exemplo, Vídeo.

 

Versão

Não

Número de versão do componente. É usado para futuras atualizações do componente. Entretanto, o fluxo não é definido neste momento.

Origem

Sim

Caminho relativo do arquivo de origem principal do componente. Mais detalhes sobre o conteúdo da origem são fornecidos na próxima seção.

Ícone

Não

Caminho relativo para o ícone do componente. Esse ícone é usado no painel de componentes e no palco quando uma instância é criada para o componente junto com seu nome. Se nenhum for fornecido, um ícone padrão será usado.

Você pode especificar o nome do png do ícone a ser carregado (geralmente 32x32). Ou, se você quiser oferecer suporte a ícones diferentes para uma UI clara e uma UI escura, forneça dois .pngs com a seguinte convenção de nomeação:

 

custom_icon_N.png – Ícone para a UI escura

custom_icon_D.png – Ícone para a UI clara

 

e especifique o nome “custom_icon” como o valor para esse campo. Os sufixos são adicionados automaticamente com base na configuração do usuário atual.

Dimensões

Não

Tamanho padrão para as instâncias do componente. Sempre que o usuário arrasta e solta um componente do painel Componentes para o palco, uma nova instância é criada. Esse campo especifica o tamanho inicial padrão para a instância do componente. O valor deve ser um arranjo [largura, altura]. Se não nenhum valor for especificado, o Animate seleciona um tamanho padrão. Além disso, o Animate restringe o tamanho para o intervalo de [2,2] e [1000, 1000].

Dependências

Não

O conjunto de dependências do componente. Este é um arranjo em que cada entrada fornece o caminho relativo para uma fonte local (com chave = “src”) e o caminho de CDN (com chave = “cdn”). O caminho de CDN não é obrigatório. Esse caminho é usado quando você usa bibliotecas hospedadas nas configurações de publicação. Caso contrário, a fonte local será usada ao visualizar ou publicar.

 

Anote o caminho relativo usado no exemplo acima (vídeo). Ele carrega as dependências de um nível acima, o que nos permite compartilhar algumas dependências nos vários conjuntos de componentes.

 

Propriedades

Sim

Este é um arranjo de propriedades. Quando você cria uma instância desse componente no palco, o conjunto de propriedades configurado aqui será mostrado automaticamente no Inspetor de propriedade (PI). Os usuários deste componente podem configurar as propriedades no Animate CC e as propriedades configuradas são disponibilizadas durante a instanciação do componente no tempo de execução.

 

Cada entrada de propriedade contém as seguintes chaves:

  1. nome: o nome exibido no inspetor de propriedade (PI) para essa propriedade. Esse valor deve ser um nome amigável. Ele pode ser localizado.
  2. variável: o nome interno usado para essa propriedade. Os valores configurados estarão disponíveis com esse nome de variável no tempo de execução. Mais detalhes sobre isso são fornecidos nas seções posteriores.
  3. Tipo: especifica o tipo de propriedade. O Animate CC permite os seguintes tipos:
    1. Booleano - Caixa de seleção no PI
    2. Número - Caixa numérica no PI
    3. String - Caixa de texto no PI
    4. Lista - Permite que o usuário configure um arranjo de valores.
    5. Coleção - Permite que os usuários configurem uma lista de pares <chave, valor>. (Consulte a caixa de combinação)
    6. Caminho do arquivo - Permite que o usuário navegue e selecione qualquer arquivo local. O valor da string é fornecido no tempo de execução. O arquivo é copiado automaticamente na saída publicada na pasta “assets” e o caminho relativo é disponibilizado no tempo de execução.
    7. Caminho da imagem - Permite que o usuário navegue e selecione qualquer imagem. O arquivo é copiado automaticamente na saída publicada na pasta de imagens configurada e o caminho relativo é disponibilizado no tempo de execução.
    8. Caminho do conteúdo de vídeo- Permite que o usuário navegue e selecione qualquer fonte de vídeo no formato para a Web (mp4, ogg, ogv, webm). O ativo configurado será copiado para a pasta “videos na saída publicada.
    9. Cor - Seletor de cores no PI

4. Padrão: valor padrão da propriedade. O padrão deve ter o mesmo tipo da propriedade.

Origem do componente

Cada componente deve ter um arquivo de origem associado que forneça o código para manipular o seguinte:

  • Criação da instância do componente no tempo de execução com o conjunto configurado de valores de propriedade
  • Associar e desassociar ao DOM.
  • Atualizações de propriedade em cada quadro

São fornecidas uma classe de base e uma função de utilitário no arquivo anwidget.js para facilitar o desenvolvimento de componentes personalizados. Esta interface será aprimorada no futuro, mas será compatível com as versões anteriores. Atualmente, somente os componentes baseados em DOM são compatíveis; no entanto, o suporte a componentes de canvas será expandido. Apenas widgets são suportados atualmente. Entretanto, a estrutura será aprimorada para oferecer suporte à associação de comportamentos (componentes não relacionados à UI).

O arquivo anwidget.js está presente na pasta ComponentesHTML5/sdk na sua primeira execução. Fornece a classe de base AnWidget para componentes personalizados e o método de utilitário $.anwidget(<className>, {Object Prototype}) para registrar um componente personalizado. A implementação atual usa jQuery; portanto, o jQuery é sempre adicionado como uma dependência quando você usa os serviços fornecidos por um widget. Entretanto, se você não deseja adicionar uma dependência implícita no jQuery, poderá precisar implementar uma classe de Componente sem jQuery, a qual fornece a mesma interface de um Widget.

 

AnWidget
Modelo HTML

O html contém essas seções (com exceção da div pré-carregadora) por padrão:

animation_container
Seções HTML padrão (com exceção da div pré-carregadora)

Observe que a figura anterior ilustra a ordem na qual os elementos são adicionados no DOM. Assim, a div dom_overlay_container é mostrada acima da tela de desenho.

Observação:

Não altere a identificação da div dom_overlay_container como em na primeira versão, pois há alguns recursos que dependem desta identificação, como os snippets de código.

Conforme mostrado na ilustração anterior, a div dom_overlay_container é mostrada no topo da tela como uma sobreposição. Para garantir que os eventos do mouse também sejam propagados corretamente na tela subjacente, usamos a propriedade CSS {pointer-events: none} para esta div, de forma que os eventos do mouse são propagados na tela subjacente. Todas as instâncias de componente que estão configuradas no seu projeto do Animate CC são instanciadas e associadas como filhas desta div dom_overlay_container. A ordem relativa das instâncias de componente é mantida no tempo de execução, mas atualmente todas as instâncias de componente são mostradas como uma sobreposição. Ajustamos {pointer-events: all} para todas as instâncias de componente no tempo de execução, de modo a também receberem os eventos do mouse.

Ciclo de vida do componente

component_lifecycle
Ciclo de vida do componente

  1. A instância de componente é criada quando o DOM é incorporado ao contêiner.

  2. A instância é associada ao DOM quando o indicador de reprodução atinge o quadro em que a instância do componente é usada. Associa um manipulador de atualização que é chamado a cada marcação no tempo de execução. O componente também dispara um evento “associado” neste momento, com os seguintes dados de evento {id: id_of_the_instance} no elemento principal.

  3. As Propriedades são atualizadas em cada retorno de atualização. Todas as atualizações de propriedade são armazenadas em cache e aplicadas uma vez durante uma manipulação de marcação. As interpolações de propriedades não são suportadas no momento. Somente as propriedades básicas, como transformação e visibilidade, são atualizadas.

  4. Quando o indicador de reprodução atinge o quadro em que a instância do componente foi removida, nós o desconectamos do DOM. Um evento ‘desconectado’ é disparado, desta vez no elemento principal.

A classe base é chamada $.AnWidget e fornece as seguintes substituições:

Nome

Obrigatório

Descrição

getCreateOptions()

Não

Retorna algumas opções que o componente deseja aplicar durante a instanciação do componente. Uma substituição típica geralmente utiliza isso para atribuir uma identificação exclusiva para cada instância, utilizando a variável global _widgetID. O exemplo na próxima seção esclarecerá o seu uso.

getCreateString()

Sim

Retorna a string para a criação da instância de DOM. Esta string é transmitida para o jQuery para criar o elemento DOM real que será associado posteriormente ao DOM de base.

 

Por exemplo, para um componente de imagem, deve retornar “<image>”.

 

No tempo de execução, o elemento é criado e a referência ao empacotador do jQuery é armazenada da seguinte forma na instância do componente:

 

this._element =  $(this.getCreateElement())

 

// this._element – Empacotador do jQuery para o elemento DOM subjacente criado.

 

Se preferir, podemos criar elementos compostos; os detalhes serão abordados em uma seção de exemplos.

getProperties()

Não

Retorna um arranjo de nomes de propriedades CSS configuráveis. Normalmente, isso corresponde a todas as propriedades configuradas em components.json.

 

Por exemplo, para o componente de vídeo, o arranjo contém as seguintes entradas:

 

["left", "top", "width", "height", "position", "transform-origin", "transform"]

getAttributes()

Não

Retorna um arranjo de atributos configuráveis. Normalmente, isso corresponde a todos os atributos que podem ser configurados em components.json.

 

Por exemplo, para o componente de vídeo, o arranjo contém as seguintes entradas:

 

["id", "src", "controls", "autoplay", "loop", "class"]

attach(parent)

Não

Esta função é chamada sempre que a instância do componente está prestes a ser associada ao elemento DOM “principal”.

 

A implementação padrão faz o seguinte (e um pouco mais):

 

// Adiciona o elemento ao DOM principal

$(parent).append(this._element);

 

//Armazena a ref em this._$this

this._$this = $(this._element);

 

//Chama uma atualização forçada para aplicar todas as propriedades

this.update(true);

this._attached = true;

 

//Dispara o evento associado no principal

$(parent).trigger("attached", this.getEventData("attached"))

 

Não é necessário substituir essa função. Entretanto, para elementos compostos, talvez seja. Mais detalhes serão abordados na seção de exemplos.

 

Observação: você pode usar this._superApply(arguments) para chamar qualquer método da classe de base de qualquer substituição.

detach()

Não

Esta função é chamada sempre que a instância do componente está prestes a ser removida do DOM. A implementação padrão faz o seguinte:

 

//Remove o elemento do DOM

this._$this.remove();

//Dispara o evento desassociado no principal

$(parent).trigger("detached", this.getEventData("detached"));

setProperty(k,v)

Não

Essa função é usada para definir qualquer propriedade para a instância. Essas alterações são colocadas em cache e aplicadas imediatamente durante a chamada de atualização update() de cada quadro para cada propriedade que está suja.

update(force)

Não

Esta função será chamada a cada quadro, quando o componente fizer parte do DOM e estiver visível. A implementação padrão aplica todas as propriedades e atributos CSS que foram alterados ou se o parâmetro de aplicação for verdadeiro.

show()

Não

Mostra a instância do elemento. Normalmente, você não precisa substituir isso, mas para elementos compostos, isso é necessário.

hide()

Não

Oculta a instância do elemento. Normalmente, você não precisa substituir isso, mas para elementos compostos, isso é necessário.

getEventData(e)

Não

Retorna qualquer dado personalizado para o evento com o nome “e”. A implementação padrão passa os dados {id: instance_id} para eventos associados e desassociados.

destroy()

Não

Libera a memória quando a instância do componente é desassociada do DOM. Normalmente, não é necessário substituir isso.

applyProperties(e)

Não

API auxiliar para aplicar as propriedades CSS ao empacotador e do jQuery.

applyAttributes(e)

Não

API auxiliar para aplicar os atributos ao empacotador e do jQuery.

Localização

A string da categoria, o nome de exibição do componente e o nome da propriedade podem ser localizados. Crie um arquivo chamado strings.json em uma pasta com o nome localidade na pasta de componentes. Forneça os pares de valores principais para que todas as strings sejam localizadas e use a chave em components.js. Em outros locais, será necessário fornecer as strings nas pastas correspondentes na pasta local.

localization
string .json

Empacotar e distribuir componentes HTML5 personalizados

Os desenvolvedores ou designers do Animate podem permitir que os animadores instalem e usem componentes sem codificação, fornecendo componentes empacotados prontos para uso. Anteriormente, os animadores deviam saber estruturas de arquivo, programar e mover manualmente os arquivos para pastas específicas para ativar as extensões HTML5.

Pré-requisitos

Antes de empacotar seu componente, crie um arquivo MXI com os metadados da origem e do caminho de destino dos componentes. Por exemplo,

<file source="jquery-ui-1.12.0" destination="$FLASH\HTML5Components\jQueryUI\" file-type="ordinary" />

Essas informações de origem e caminho do arquivo de destino são necessárias para ativar o utilitário de extensões para a instalação exata do seu componente.

Empacotamento de componentes

Para empacotar os componentes HTML5 personalizados, execute as seguintes etapas: 

  1. Para criar um arquivo MXI, insira o conteúdo similar ao exemplo abc.mxi usando um editor de texto e salve-o com uma extensão MXI.

    Download

    Download

  2. Adicione seu arquivo do componente MXI e outros arquivos relacionados em uma pasta.

    Add-MXI-file-to-component
  3. Crie um ficheiro zip da extensão ZPX usando as ferramentas de assinatura nas extensões do CC (ZXPSignCmd.exe). Use os seguintes comandos na ferramenta Comando de assinatura ZXP para criar um arquivo ZXP:

    1. Crie um certificado autoassinado usando a opção -selfSignedCert.

    Você pode pular esta etapa se você já tiver um certificado.

    Self-signature
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12

    O arquivo FileName.p12 é gerado na pasta atual.

    2. Assine a extensão usando o seguinte comando: 

    Create-ZXP-file
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    o projectName é o nome do projeto da extensão. Na pasta atual, um arquivo com o nome projectName.zxp é gerado.

Distribuir componentes

Você pode distribuir este arquivo de componente empacotado projectName.zxp para qualquer usuário do Animate.

Observação:

O Adobe recomenda que você distribua seus produtos pelo site Complementos do Adobe. Você pode distribuir complementos publicamente (de forma gratuita ou paga) ou em particular (gratuitamente para usuários nomeados). Saiba mais sobre compartilhar produtos em particular.

Instalar componentes distribuídos

Os designers ou desenvolvedores do Animate podem instalar o componente do arquivo distribuído ZXP usando o utilitário Gerenciar extensões.

Para obter mais informações, consulte Instalar componentes distribuídos

Esta obra está licenciada sob uma licença não adaptada da Creative Commons Attribution-Noncommercial-Share Alike 3.0  As publicações do Twitter™ e do Facebook não são cobertas pelos termos do Creative Commons.

Avisos legais   |   Política de privacidade online