Guia do Usuário Cancelar

Criar componentes HTML5 personalizados

Pesquisar

Última atualização em 24 de mai de 2023

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

O Animate 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.

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.

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 verifica as seguintes pastas quanto a componentes HTML5 personalizados e os carrega na inicialização:

• Windows:

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

• MAC:

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

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 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

é 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 são fornecidos no que a origem contém, 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 qualquer 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. Do 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. Ao criar qualquer 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 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: nome: o nome exibido no inspetor de propriedade (PI) para essa propriedade. Esse valor deve ser um nome amigável. Ele pode ser localizado. 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. Tipo: especifica o tipo de propriedade. O Animate permite os seguintes tipos: Booleano - Caixa de seleção no PI Número - Caixa numérica no PI Sequência de caracteres - Caixa de texto no PI Lista -permite que o usuário configure uma matriz de valores. Coleção - Permite que os usuários configurem uma lista de pares <chave, valor>. (Consulte a caixa de combinação) 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. 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. 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 “vídeos” na saída publicada. Cor - Seletor de cores no PI Padrão: valor padrão da propriedade. O padrão deve ser do mesmo tipo que o tipo de 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 AnWidgetpara 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.

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.

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 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

A instância de componente é criada quando o DOM é incorporado ao contêiner.
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.
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.
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.

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

Qualquer componente criado por um desenvolvedor. Clique aqui para obter instruções sobre a criação de componentes.
Conjunto de ferramentas para assinatura nas extensões do CC.

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=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />

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:

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

Obter arquivo
Faça o download de um arquivo abc.mxi de amostra.
Adicione seu arquivo do componente MXI e outros arquivos relacionados em uma pasta.
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.
```
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:
```
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 senha
```
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.

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).

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.

Mais itens similares

Adobe

Receba ajuda com mais rapidez e facilidade

Novo usuário?