Componentes

Nesta página é possível acessar a documentação dos componentes de uso global da WebSDk. A página será atualizada conforme modificações forem feitas.

A estrutura típica de um componente é próxima do exemplo abaixo:

// import the styles, the html template and custom components
import './page.scss'
import template from './page.html'
import MyComponent from '../../components/my-component'

export default {
  template,
  components: {
    MyComponent
    // declaração dos componentes customizados que estão sendo utilizados no *.html
  },
  props: {
    // propriedades padrão do componente. Podem ser injetadas através da instância do componente.
    myProp: 1,
    myOtherProp: 'other'
  },
  state () {
    return {
      // variáveis de estado inicial do componente
      stateVariable: 15,
      otherStateVariable: true
    }
  },
  onCreate () {
    // callback executada quando o elemento HTML do componente está pronto pra uso
  },
  onUpdate() {
    // callback executada quando o estado do componente precisa ser atualizado
    // use esta callback para atualizar o DOM
  },
  onDestroy() {
    // callback executada antes de o componente ser destruído
  },
  onMount() {
    // callback executada antes de o componente aparecer na tela
  },
  onUnmount() {
    // callback executada antes de o componente ser removido da tela
  },
  methods: {
    // métodos do componente. Serão injetados na instância do componente.
    myMethod () {
      console.log('esse método é público e faz parte da API do componente')
    }
  }
}

API

props

Define as propriedades do componente. Desta forma, ao utilizar um componente, é possível configurá-lo

e.g.

Em my-component.js

{
  props: {
    myProp: '1'
  },
  onUpdate() {
    // Você pode acessar os props diretamente do componente
    console.log(this.myProp)
  }
}

No HTML de outro componente

<div class="my-other-component">
    <!-- Inicializa o prop da instância como 50 -->
    <my-component my-prop="50"></my-component>
    <!-- Inicializa o prop da instância como 9 -->
    <my-component my-prop="9"></my-component>
    <!-- Inicializa o prop da instância com seu valor padrão-->
    <my-component></my-component>
</div>

state

Define o estado do componente. Note que state é uma função que retorna um objeto. Desta forma, cada instância de um componente irá executar esta função para obter um novo estado

e.g.

Em my-component.js

{
  state () {
    return {
      stateVariable: 15,
      otherStateVariable: true
    }
  },
  onUpdate() {
    // Você pode acessar o state diretamente do componente
    console.log(this.stateVariable)
    console.log(this.otherStateVariable)
  }
}

methods

Define os métodos que o componente gostaria de expor para outros componentes

e.g.

Em my-component.js

{
  methods: {
    printSomething () {
      console.log('something')
    },
    changeTitle (title) {
      this.update({
          myComponentTitle: title
        })
    },
    changeSubtitle (subtitle) {
      this.subtitle = subtitle
      this.update()
    }
  }
}

Em my-other-component.js

onCreate () {
  this.$refs['my-component'].changeTitle('Meu título')
  this.$refs['my-component'].changeSubtitle('Meu subtítulo')
  this.$refs['my-component'].printSomething()
}

name

O nome do componente. Essa propriedade é definida quando um componente é cadastrado

e.g.

<div class="my-component">
  <my-componente-name ref="my-ref"></my-componente-name>
</div>

import MyComponent from '../../components/my-component.js'

{
  components: {
    MyComponentName: MyComponent // Será usado no HTML como my-component-name
  },
  methods: {
    printName () {
      console.log(this.$refs['my-ref'].name) // my-component-name
    }
  }
}

el

Guarda uma referência para o elemento HTML associado ao componente

e.g.

onCreate () {
  console.log(this.el) // HTMLElement
}

parent

Guarda uma referência para o componente pai

e.g.

onCreate () {
  console.log(this.parent) // Irá imprimir a instância do componente pai
}

children

Uma lista com uma referência para todos os componentes filhos

e.g.

onCreate () {
  console.log(this.children) // Irá imprimir uma lista contendo todas as instâncias dos componentes filhos
}

Métodos

mount(root: HTMLElement)

Monta o componente em um elemento HTML e muda a propriedade display do estilo do componente para torná-lo visível

e.g.

myComponent.mount(document.body)

unmount()

Desmonta o componente.

Atualmente, ao chamar o método unmount, somente a propriedade display é alterada para none. O parentElement do componente continua o mesmo

e.g.

myComponent.unmount()

update(props)

Atualiza o estado e os props do componente

e.g.

myComponent.update({
  prop1: 'novo valor',
  stateVar: 'novo estado'
})

console.log(myComponent.prop1) // 'novo valor'
console.log(myComponent.stateVar) // 'novo estado'

destroy()

Destroy um componente e todos os seus componentes filhos

e.g.

myComponent.destroy()

findChildren(componentName: string): Component[]

Retorna uma lista com todos os componentes filhos cujo o nome equivale ao componentName

import MyComponent from '../../components/my-component.js'

{
  components: {
    MyComponentName: MyComponent // Será usado no HTML como my-component-name
  },
  methods: {
    printChildren () {
      console.log(this.findChildren('my-component-name'))
    }
  }
}

Hooks

onCreate

Chamado somente uma vez, assim que um componente é criado.

onUpdate

Chamado sempre que o componente precisa ser atualizado. Logo após o onCreate ser chamado, o onUpdate será chamado logo em seguida

Use esta callback para atualizar o DOM

e.g.

{
  props: {
    text: 'Clique aqui'
  },
  onUpdate () {
    // Atualiza o botão com o texto correto
    this.$refs['button'].innerText = this.text
  },
  methods: {
    setText (text) {
      this.update({ text })
    }
  }
}

onMount

Chamado quando o elemento é adicionado ao DOM.

Note que na versão atual do framework, o método onMount só é chamado no componente ao qual o método mount é chamado; ou seja, os componentes filhos uma vez montados, não mudam seu estado. O mesmo se aplica para onUnmount

onUnmount

Chamado quando o elemento é removido do DOM

onDestroy

Chamado quando um componente é destruído. Atualmente, nunca é chamado pelo framework

Atributos especiais

ref

Um objeto contendo todas as referências apontadas no HTML

Caso um atributo ref seja aplicado a um componente, a referência será a instância do componente, caso contrário, a referência irá apontar para o HTMLElement correspondente. A referência é acessada através da propriedade $refs do componente

e.g.

No HTML do componente

<div class="my-component">
    <span ref="title"></span>
    <my-other-component ref="other-component"></my-other-component>
</div>

No JS do componente

{
  props: {
    title: 'My Default Title'
  },
  onUpdate () {
    // HTMLElement
    this.$refs['title'].innerText = this.title
    // Instância do componente
    this.$refs['other-component'].anyMethod()
  }
}

Tags Especiais

slot

Tag responsável por injetar código HTML dentro de um componente

e.g.

Componente 1

<div class="my-component-1">
  <span>Isso não será substituído</span>
  <slot>
    <span>Isso será substituído se um slot for provido </span>
  </slot>
</div>

Componente 2

<div class="my-component-2">
  <span>Esse é meu componente 2</span>
  <my-component-1>
    <button>Clique aqui</button>
  </my-component-1>
</div>

Irá resultar em

<div class="my-component-2">
  <span>Esse é meu componente 2</span>
  <div class="my-component-1">
    <span>Isso não será substituído</span>
    <button>Clique aqui</button>
  </div>
</div>