Ir para o conteúdo principal

Componentes de Mensagem

Componentes de mensagem — os quais chamaremos "componentes" daqui em diante — são um framework para adicionar elementos interativos às mensagens que o seu aplicativo ou bot envia. Eles são acessíveis, personalizáveis e fáceis de usar.

Existem vários tipos diferentes de componentes; esta documentação descreverá os fundamentos deste novo framework e cada exemplo.

Botão​

Botões são componentes interativos que renderizam em mensagens. Eles podem ser clicados por usuários e enviar um interação para seu aplicativo quando clicados.

Button

app.components.ts
import { Injectable } from '@nestjs/common';
import { Context, Button, ButtonContext } from 'necord';

@Injectable()
export class AppComponents {
    @Button('BUTTON')
    public onButton(@Context() [interaction]: ButtonContext) {
        return interaction.reply({ content: 'Botão pressionado!' });
    }
}

Botão Dinâmico​

Você pode criar botões com o campo dinâmico 'id'. Isso é útil para passar metadados para botões.

Botões dinâmicos usam um formato path-to-regexp para realizar a correspondência de expressão regular. Transforme uma string de caminho como user/:name em uma expressão regular.

Para criar um botão dinâmico

new ButtonBuilder()
  .setCustomId('click/12345')
  .setLabel('LABEL')
  .setStyle(ButtonStyle.Primary)

Para receber um botão dinâmico

import { Injectable } from '@nestjs/common';
import { Context, Button, ButtonContext } from 'necord';

@Injectable()
export class AppComponents {
  @Button('click/:valor')
  public onButton(
    @Context() [interaction]: ButtonContext,
    @ComponentParam('valor') valor: string
  ) {
    return interaction.reply({ content: `Botão pressionado! Valor: ${valor}` });
  }
}

Menu de Seleção​

Menus de Seleção são outro componente interativo que renderiza em mensagens. No desktop, clicar em um menu de seleção abre uma interface de usuário no estilo dropdown; no celular, tocar em um menu de seleção abre uma half-sheet com as opções.

Select Menu

O Discord introduziu novos componentes de menu de seleção:

  • String Select
  • User Select
  • Role Select
  • Mentionable Select
  • Channel Select

String Select​

String Select é um Menu de Seleção para escolher as opções de texto definidas

Para criar a String Select:

new StringSelectMenuBuilder()
  .setCustomId('STRING_SELECT_MENU') // coloque seu customId
  .setPlaceholder('Selecione sua corr')
  .setMaxValues(1)
  .setMinValues(1)
  .setOptions([
    { label: 'Vermelhor', value: 'Vermelho' },
    { label: 'Azul', value: 'Azul' },
    { label: 'Amerelo', value: 'Amarelo' }
  ])

Para receber uma seleção de string:

import { Injectable } from '@nestjs/common';
import { Context, StringSelect, StringSelectContext, SelectedStrings } from 'necord';

@Injectable()
export class AppComponents {
    @StringSelect('STRING_SELECT_MENU')
    public onStringSelect(
      @Context() [interaction]: StringSelectContext,
      @SelectedStrings() selected: string[]
    ) {
      return interaction.reply({
        content: `Você selecionou a cor - ${selected.join(' ')}`
      });
    }
}

User Select​

User Select são Menus de seleção para selecionar usuários

Para criar um User Select:

new UserSelectMenuBuilder()
  .setCustomId('USER_SELECT_MENU')
  .setPlaceholder('Selecione um usuário')
  .setMaxValues(1)
  .setMinValues(1)

Para receber um User Select:

import { Injectable } from '@nestjs/common';
import {
  Context,
  UserSelect,
  UserSelectContext,
  SelectedUser,
  ISelectedUser,
  SelectedMembers,
  ISelectedMembers
} from 'necord';

@Injectable()
export class AppComponents {
    @UserSelect('USER_SELECT_MENU')
    public onUserSelect(
      @Context() [interaction]: UserSelectContext,
      @SelectedUsers() users: ISelectedUsers, // Coleção de usuários
      @SelectedMembers() members: ISelectedMembers // Coleção de membros
    ) {
      interaction.reply({
        content: `
        Usuários selecionados - ${users.map(user => user.username).join(',')}\n
        Membros selecionados - ${members.map(member => member.user?.username).join(',')}
        `
      });
    }
}

Role Select​

Role Select são Menus de seleção para selecionar cargos

Para criar um Role Select:

new RoleSelectMenuBuilder()
  .setCustomId('ROLE_SELECT_MENU')
  .setPlaceholder('Selecione um cargo')
  .setMaxValues(1)
  .setMinValues(1)

Para receber um Role Select:

import { Injectable } from '@nestjs/common';
import {
  Context,
  RoleSelect,
  RoleSelectContext,
  SelectedRole,
  ISelectedRole,
} from 'necord';

@Injectable()
export class AppComponents {
    @RoleSelect('ROLE_SELECT_MENU')
    public onRoleSelect(
      @Context() [interaction]: RoleSelectContext,
      @SelectedRoles() roles: ISelectedRoles, // Coleção de cargos
    ) {
      interaction.reply({
        content: `
        Cargos selecionados - ${roles.map(role => role.id).join(',')}
        `
      });
    }
}

Channel Select​

Channel Select são Menus de seleção para selecionar canais

Para criar um Channel Select:

new ChannelSelectMenuBuilder()
  .setCustomId('CHANNEL_SELECT_MENU')
  .setPlaceholder('Selecione um canal')
  .setMaxValues(1)
  .setMinValues(1)

Para receber um Channel Select:

import { Injectable } from '@nestjs/common';
import {
  Context,
  ChannelSelect,
  ChannelSelectContext,
} from 'necord';

@Injectable()
export class AppComponents {
    @ChannelSelect('CHANNEL_SELECT_MENU')
    public onChannelSelect(
      @Context() [interaction]: ChannelSelectContext,
      @SelectedChannels() channels: ISelectedChannels, // Coleção de canais
    ) {
      interaction.reply({
        content: `
        Canais selecionados - ${channels.map(channel => channel.id).join(',')}
        `
      });
    }
}

Mentionable Select​

Seleção mencionável é um Menu de seleção para selecionar menções (usuários e cargos)

Para criar um Mentionable Select:

new MentionableSelectMenuBuilder()
  .setCustomId('MENTIONABLE_SELECT_MENU')
  .setPlaceholder('Selecione um usuário/cargo')
  .setMaxValues(1)
  .setMinValues(1)

Para receber um Mentionable Select:

import { Injectable } from '@nestjs/common';
import {
  Context,
  MentionableSelect,
  MentionableSelectContext,
  SelectedUsers,
  ISelectedUsers,
  SelectedMembers,
  ISelectedMembers,
  SelectedRoles,
  ISelectedRoles,
} from 'necord';

@Injectable()
export class AppComponents {
    @MentionableSelect('MENTIONABLE_SELECT_MENU')
    public onMentionableSelect(
      @Context() [interaction]: MentionableSelectContext,
      @SelectedUsers() users: ISelectedUsers,
      @SelectedMembers() members: ISelectedMembers,
      @SelectedRoles() roles: ISelectedRoles
    ) {
      return interaction.reply({
        content: `
        Usuários selecionados - ${users.map(user => user.username).join(',')}\n
        Membros selecionados - ${members.map(member => member.user?.username).join(',')}\n
        Cargos selecionados - ${roles.map(role => role.name).join(',')}
        `
      });
    }
}

Menu de Seleção Dinâmico​

Todos os tipos de Menu, suportem o formato dinâmico id usando path-to-regexp.

Para criar um menu de seleção dinâmico

new StringSelectMenuBuilder()
  .setCustomId('preferences/color')
  .setPlaceholder('Selecione uma cor')
  .setMaxValues(1)
  .setMinValues(1)
  .setOptions([
    { label: 'Vermelho', value: 'Vermelho' },
    { label: 'Azul', value: 'Azul' },
    { label: 'Amarelo', value: 'Amarelo' }
  ])

Para receber um menu de seleção dinâmico

import { Injectable } from '@nestjs/common';
import { Context, StringSelect, StringSelectContext,SelectedStrings } from 'necord';

@Injectable()
export class AppComponents {
    @StringSelect('preferences/:item')
	public onPreferenceSelect(
		@Context() [interaction]: StringSelectContext,
		@SelectedStrings() values: string[],
		@ComponentParam('item') item: string
	) {
		return interaction.reply({
			content: `
      ${item} = ${values.join(',')}\n
      `
		});
	}
}

Os menus de seleção dinâmica são compatíveis com :

  • StringSelect
  • UserSelect
  • RoleSelect
  • MentionableSelect
  • ChannelSelect

Você pode ver um exemplo funcional aqui.