Paginação

Escolha o tipo certo#

Tipo	Fonte	Melhor uso
Estática	Lista pronta de templates	Tutoriais, painéis e páginas com layout diferente
Dinâmica	Array dividido por `pageSize`	Usuários, logs, ranking e resultados de banco
Híbrida	Introdução fixa + array dinâmico	Catálogo com capa ou instruções antes dos itens

Paginação estática#

Registre uma lista quando cada página já é conhecida durante o carregamento.

1const page = (title: string, content: string) =>2  new MessageBuilder()3    .addComponents(4      new ContainerBuilder()5        .setAccentColor(0xa571f4)6        .addTextDisplayComponents(7          new TextDisplayBuilder().setContent(8            '## ' + title + '9' + content + '1011Página ${pages.current}/${pages.total}'12          )13        )14    )15    .template()1617Client.registerPaginator('guide-pages', [18  { id: 'intro', name: 'Introdução', template: page('Introdução', 'Como usar o painel.') },19  { id: 'config', name: 'Configuração', template: page('Configuração', 'Escolha seus canais.') },20  { id: 'finish', name: 'Finalização', template: page('Tudo pronto', 'Revise e confirme.') }21])

1Client.slash({2  data: new SlashCommandBuilder()3    .setName('guide')4    .setDescription('Abre o guia paginado.'),5  execute: async interaction => {6    await interaction.paginatorRequest('guide-pages', {7      ephemeral: true,8      pageIndex: 09    })10  }11})

Paginação dinâmica#

O paginator divide data, chama render para a fatia atual e injeta o contexto da página.

1type UserRecord = {2  id: string3  name: string4  level: number5}67const users: UserRecord[] = await userRepository.list()89const paginator = Paginator.dynamic({10  id: 'users-pages',11  data: users,12  pageSize: 5,13  render: async (items, context) => {14    const rows = items.map((user, index) =>15      (context.pageIndex * 5 + index + 1) +16      '. **' + user.name + '** — nível ' + user.level17    )1819    return new MessageBuilder()20      .addComponents(21        new ContainerBuilder().addTextDisplayComponents(22          new TextDisplayBuilder().setContent(23            '## Usuários24' + rows.join('25') +26            '2728Página ' + context.page + '/' + context.pageCount29          )30        )31      )32      .template()33  }34})3536Client.registerPaginator('users-pages', paginator)

Contexto	Valor
`items`	Itens da página atual
`page`	Número amigável, começando em 1
`pageIndex`	Índice interno, começando em 0
`pageCount`	Quantidade total de páginas
`totalItems`	Quantidade total de registros

Dados novos a cada solicitação#

Use uma definição factory para consultar banco ou API quando o usuário abre a paginação, não durante o boot.

1Client.registerPaginator('audit-pages', async context => {2  const guildId = context.guildId3  const records = guildId ? await auditRepository.list(guildId) : []45  return Paginator.dynamic({6    id: 'audit-pages',7    data: records,8    pageSize: 10,9    ownerId: context.ownerId,10    guildId,11    render: (items, page) => new MessageBuilder()12      .addComponents(13        new ContainerBuilder().addTextDisplayComponents(14          new TextDisplayBuilder().setContent(15            '## Auditoria16' +17            items.map(item => '- ' + item.summary).join('18') +19            '2021' + page.page + '/' + page.pageCount22          )23        )24      )25      .template()26  })27})

Paginação híbrida#

A primeira página é fixa; as seguintes vêm de uma coleção dinâmica.

1const intro = new MessageBuilder()2  .addComponents(3    new ContainerBuilder()4      .setAccentColor(0x6485ff)5      .addTextDisplayComponents(6        new TextDisplayBuilder().setContent(7          '## Catálogo Ninenity8Use **Próxima** para explorar os projetos.'9        )10      )11  )12  .template()1314const paginator = Paginator.hybrid({15  id: 'catalog-pages',16  intro,17  data: projects,18  pageSize: 3,19  render: (items, context) => new MessageBuilder()20    .addComponents(21      new ContainerBuilder().addTextDisplayComponents(22        new TextDisplayBuilder().setContent(23          items.map(project => '### ' + project.name + '24' + project.summary).join('2526') +27          '2829Página ' + context.page + '/' + context.pageCount30        )31      )32    )33    .template()34})3536Client.registerPaginator('catalog-pages', paginator)

Botões de paginação personalizados#

Inclua uma action row no próprio template e marque a ação de cada botão. O runtime detecta os controles e não adiciona uma segunda linha.

1const controls = new ActionRowBuilder<MessageActionRowComponentBuilder>()2  .addComponents(3    new ButtonBuilder()4      .setCustomId('guide-pages:first')5      .setLabel('Primeira')6      .setEmoji('⏮')7      .setStyle(ButtonStyle.Secondary)8      .setPaginationAction('first'),9    new ButtonBuilder()10      .setCustomId('guide-pages:back')11      .setLabel('Voltar')12      .setEmoji('◀')13      .setStyle(ButtonStyle.Secondary)14      .setPaginationAction('back'),15    new ButtonBuilder()16      .setCustomId('guide-pages:next')17      .setLabel('Próxima')18      .setEmoji('▶')19      .setStyle(ButtonStyle.Primary)20      .setPaginationAction('next'),21    new ButtonBuilder()22      .setCustomId('guide-pages:last')23      .setLabel('Última')24      .setEmoji('⏭')25      .setStyle(ButtonStyle.Secondary)26      .setPaginationAction('last')27  )2829const page = new MessageBuilder()30  .addComponents(31    new ContainerBuilder()32      .addTextDisplayComponents(33        new TextDisplayBuilder().setContent(34          'Página ${pages.current} de ${pages.total}'35        )36      )37      .addActionRowComponents(controls)38  )39  .template()

O prefixo do customId deve ser exatamente o ID registrado no paginator.
back e previous são entendidos como a página anterior; no builder use setPaginationAction('back').
Use first e last apenas quando a quantidade de páginas justifica esses atalhos.
O runtime hidrata os tokens pages.current e pages.total antes de enviar.

Personalizar rótulos automáticos#

Se as páginas não incluem controles, Paginator cria a linha e você pode trocar os rótulos.

1const paginator = Paginator.static({2  id: 'help-pages',3  pages: [introPage, commandsPage, settingsPage],4  controls: {5    first: 'Início',6    previous: 'Voltar',7    next: 'Avançar',8    last: 'Fim'9  }10})1112Client.registerPaginator('help-pages', paginator)