Métodos e propriedades

Uma instancia da classe HTApi possui alguns métodos para que você consiga interagir com a biblioteca. Usando eles você tem controle total sobre as traduções, configurações e interações com os componentes internos, podendo criar seus próprios casos de uso e controle de fluxo.

Para se ter uma melhor noção sobre os métodos disponíveis em uma classe, considere a seguinte interface de exemplo:

interface IHTApi {
	stop(): void;
	active(): void;
	desactive(): void;
	setConfig(config: IConfig): void;
	translate(sentence: string): Promise<void>;
	changeAnimationSpeed(speed: CoreSpeed): void;
	registerToggleStateSubscriber(subscriber: (isOpen: boolean) => void): void;
	notifyPromptLink(promptLinkNotification: IPromptLinkNotification | null): void;

	isLoaded: boolean;
}

Propriedades

isLoaded

• tipo: boolean
• padrão: false

Propriedade que indica se a biblioteca está carregada.

ATENÇÃO

Essa propriedade não diz respeito ao estado de desativação da biblioteca, servindo para indicar que todos os dados necessários para a inicialização da biblioteca foram carregados corretamente.

Métodos

active()

• retorna: void

Método que inicia a biblioteca e permite as interações com a api, sem sua chamada, nenhum outro método tem efeito. Recomendamos utilizar esse método com o elemento personalizado ht-button.

desactive()

• retorna: void

Método que finaliza a biblioteca e desabilita as interações com a api. Esse método é útil quando você deseja desativar a biblioteca e permitir que o usuário continue usando sua aplicação sem o tradutor. O método também é chamado quando o usuário clica no botão desativar no widget.

setConfig(config: IConfig)

• retorna: void
• prop: IConfig:

  interface IConfig {
  	avatar: "HUGO" | "MAYA";
  	language: "ptBR" | "enUS" | "enES";
  	parentElement: HTMLElement;
  	signLanguage: "ptBR-bzs" | "en-ase";
  	token: string;
  	theme: {
  		translatorButtonBackground: string;
  		translatorButtonForeground: string;
  		translatorButtonBorder: string;
  		widgetBackground: string;
  		widgetForeground: string;
  		widgetBorder: string;
  		widgetPosition: "left" | "right";
  	};
  	enableComponents?: {
  		promptLink: boolean;
  		widget: boolean;
  	};
  }

Método que define as configurações da biblioteca. Este método é útil para mudar as configurações após instanciar o HTApi e mudar as propriedades que foram passadas ao construtor.

Casos de uso recomendados:

• alterar tema por interação do usuário;
• alterar idioma por interação do usuário;
• alterar idioma por interação do usuário;
• alterar idioma por interação do usuário.

translate(sentence: string)

• retorna: Promise<void>
• prop: string

Método que inicia a tradução de uma sentença de texto;

stop()

Método que para qualquer tradução em andamento. Esse método também é chamado quando o usuário clica no botão parar na janela de tradução.

changeAnimationSpeed(speed: CoreSpeed)

• retorna: void
• prop: CoreSpeed

type CoreSpeed = "slow" | "normal" | "fast";

Método que altera a velocidade da animação. Esse método é chamado quando o usuário clica no botão mudar velocidade na janela de tradução.

registerToggleStateSubscriber(subscriber: (isOpen: boolean) => void)

• retorna: void
• prop: (isOpen: boolean) => void

Método que fornece um observador para notificar quando a janela de tradução está aberta ou fechada. Ao utilizar esse método, é necessário passar uma função callback como parâmetro e sempre que ocorrer alguma mudança de estado, a callback passada será chamada com o valor atual do estado.

notifyPromptLink(promptLinkNotification: IPromptLinkNotification | null)

• retorna: void
• prop: IPromptLinkNotification | null

interface IPromptLinkNotification {
	allocatedElement: HTMLElement;
	isAnActionElement: boolean;
	elementToObserveScroll?: HTMLElement;
	handleCallAllocatedElementOnClick?: () => void;
	handleTranslate?: () => void;
	onClose?: () => void;
}

Método para realizar comunicação com o PromptLink. Como o PromptLink é um componente agnóstico, nenhuma funcionalidade está implementada nele, cabendo ao desenvolvedor criar os casos de uso para ele. Para fazer isso, disponibilizamos esse método para que seja possível torna-lo um componente controlado.

Sempre que desejar mudar o estado do PromptLink, fique atento as propriedades que você deve passar em IPromptLinkNotification:

• allocatedElement: elemento em que o PromptLink deve se alocar.;
• isAnActionElement: indica se o elemento passado é um elemento de ação (um botão, um link, etc);
• elementToObserveScroll: Quando o usuário realiza a ação de scroll em tela, o PromptLink desaparece, porém, é necessário indicar qual elemento deve ser observado. Caso o comportamento não seja necessário, basta não enviar o parâmetro;
• handleCallAllocatedElementOnClick: função do qual o PromptLink deve chamar quando o usuário clica no botão de ação no próprio PromptLink.;
• handleTranslate: função do qual o PromptLink deve chamar quando o usuário clicar no botão de tradução no próprio PromptLink.;
• onClose: função que é executada automaticamente ao fechar o PromptLink e serve para realizar tarefas de limpeza de estado se necessário.

Além das propriedades acima, caso deseje limpar completamente o estado atual do PromptLink, basta enviar null como parâmetro, fazendo com que o PromptLink fique limpo e desapareça.