discord.ext.pages

Added in version 2.0.

This module provides an easy pagination system with buttons, page groups, and custom view support.

Example usage in a cog:

import asyncio

import discord
from discord.commands import SlashCommandGroup
from discord.ext import commands, pages


class PageTest(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.pages = [
            "Page 1",
            [
                discord.Embed(title="Page 2, Embed 1"),
                discord.Embed(title="Page 2, Embed 2"),
            ],
            "Page Three",
            discord.Embed(title="Page Four"),
            discord.Embed(title="Page Five"),
            [
                discord.Embed(title="Page Six, Embed 1"),
                discord.Embed(title="Page Seven, Embed 2"),
            ],
        ]
        self.pages[3].set_image(
            url="https://c.tenor.com/pPKOYQpTO8AAAAAM/monkey-developer.gif"
        )
        self.pages[4].add_field(
            name="Example Field", value="Example Value", inline=False
        )
        self.pages[4].add_field(
            name="Another Example Field", value="Another Example Value", inline=False
        )

        self.more_pages = [
            "Second Page One",
            discord.Embed(title="Second Page Two"),
            discord.Embed(title="Second Page Three"),
        ]

        self.even_more_pages = ["11111", "22222", "33333"]

    def get_pages(self):
        return self.pages

    pagetest = SlashCommandGroup("pagetest", "Commands for testing ext.pages")

    # These examples use a Slash Command Group in a cog for better organization - it's not required for using ext.pages.
    @pagetest.command(name="default")
    async def pagetest_default(self, ctx: discord.ApplicationContext):
        """Demonstrates using the paginator with the default options."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="hidden")
    async def pagetest_hidden(self, ctx: discord.ApplicationContext):
        """Demonstrates using the paginator with disabled buttons hidden."""
        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="loop")
    async def pagetest_loop(self, ctx: discord.ApplicationContext):
        """Demonstrates using the loop_pages option."""
        paginator = pages.Paginator(pages=self.get_pages(), loop_pages=True)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="strings")
    async def pagetest_strings(self, ctx: discord.ApplicationContext):
        """Demonstrates passing a list of strings as pages."""
        paginator = pages.Paginator(
            pages=["Page 1", "Page 2", "Page 3"], loop_pages=True
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="timeout")
    async def pagetest_timeout(self, ctx: discord.ApplicationContext):
        """Demonstrates having the buttons be disabled when the paginator view times out."""
        paginator = pages.Paginator(
            pages=self.get_pages(), disable_on_timeout=True, timeout=30
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="remove_buttons")
    async def pagetest_remove(self, ctx: discord.ApplicationContext):
        """Demonstrates using the default buttons, but removing some of them."""
        paginator = pages.Paginator(pages=self.get_pages())
        paginator.remove_button("first")
        paginator.remove_button("last")
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="init")
    async def pagetest_init(self, ctx: discord.ApplicationContext):
        """Demonstrates how to pass a list of custom buttons when creating the Paginator instance."""
        pagelist = [
            pages.PaginatorButton(
                "first", label="<<-", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", label="<-", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", label="->", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", label="->>", style=discord.ButtonStyle.green),
        ]
        paginator = pages.Paginator(
            pages=self.get_pages(),
            show_disabled=True,
            show_indicator=True,
            use_default_buttons=False,
            custom_buttons=pagelist,
            loop_pages=True,
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="emoji_buttons")
    async def pagetest_emoji_buttons(self, ctx: discord.ApplicationContext):
        """Demonstrates using emojis for the paginator buttons instead of labels."""
        page_buttons = [
            pages.PaginatorButton(
                "first", emoji="⏪", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", emoji="⬅", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", emoji="➡", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", emoji="⏩", style=discord.ButtonStyle.green),
        ]
        paginator = pages.Paginator(
            pages=self.get_pages(),
            show_disabled=True,
            show_indicator=True,
            use_default_buttons=False,
            custom_buttons=page_buttons,
            loop_pages=True,
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="custom_buttons")
    async def pagetest_custom_buttons(self, ctx: discord.ApplicationContext):
        """Demonstrates adding buttons to the paginator when the default buttons are not used."""
        paginator = pages.Paginator(
            pages=self.get_pages(),
            use_default_buttons=False,
            loop_pages=False,
            show_disabled=False,
        )
        paginator.add_button(
            pages.PaginatorButton(
                "prev", label="<", style=discord.ButtonStyle.green, loop_label="lst"
            )
        )
        paginator.add_button(
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            )
        )
        paginator.add_button(
            pages.PaginatorButton(
                "next", style=discord.ButtonStyle.green, loop_label="fst"
            )
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="custom_view")
    async def pagetest_custom_view(self, ctx: discord.ApplicationContext):
        """Demonstrates passing a custom view to the paginator."""
        view = discord.ui.View()
        view.add_item(discord.ui.Button(label="Test Button, Does Nothing", row=1))
        view.add_item(
            discord.ui.Select(
                placeholder="Test Select Menu, Does Nothing",
                options=[
                    discord.SelectOption(
                        label="Example Option",
                        value="Example Value",
                        description="This menu does nothing!",
                    )
                ],
            )
        )
        paginator = pages.Paginator(pages=self.get_pages(), custom_view=view)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="groups")
    async def pagetest_groups(self, ctx: discord.ApplicationContext):
        """Demonstrates using page groups to switch between different sets of pages."""
        page_buttons = [
            pages.PaginatorButton(
                "first", label="<<-", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", label="<-", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", label="->", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", label="->>", style=discord.ButtonStyle.green),
        ]
        view = discord.ui.View()
        view.add_item(discord.ui.Button(label="Test Button, Does Nothing", row=2))
        view.add_item(
            discord.ui.Select(
                placeholder="Test Select Menu, Does Nothing",
                options=[
                    discord.SelectOption(
                        label="Example Option",
                        value="Example Value",
                        description="This menu does nothing!",
                    )
                ],
            )
        )
        page_groups = [
            pages.PageGroup(
                pages=self.get_pages(),
                label="Main Page Group",
                description="Main Pages for Main Things",
            ),
            pages.PageGroup(
                pages=[
                    "Second Set of Pages, Page 1",
                    "Second Set of Pages, Page 2",
                    "Look, it's group 2, page 3!",
                ],
                label="Second Page Group",
                description="Secondary Pages for Secondary Things",
                custom_buttons=page_buttons,
                use_default_buttons=False,
                custom_view=view,
            ),
        ]
        paginator = pages.Paginator(pages=page_groups, show_menu=True)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="update")
    async def pagetest_update(self, ctx: discord.ApplicationContext):
        """Demonstrates updating an existing paginator instance with different options."""
        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False)
        await paginator.respond(ctx.interaction)
        await asyncio.sleep(3)
        await paginator.update(show_disabled=True, show_indicator=False)

    @pagetest.command(name="target")
    async def pagetest_target(self, ctx: discord.ApplicationContext):
        """Demonstrates sending the paginator to a different target than where it was invoked."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.respond(ctx.interaction, target=ctx.interaction.user)

    @commands.command()
    async def pagetest_prefix(self, ctx: commands.Context):
        """Demonstrates using the paginator with a prefix-based command."""
        paginator = pages.Paginator(pages=self.get_pages(), use_default_buttons=False)
        paginator.add_button(
            pages.PaginatorButton("prev", label="<", style=discord.ButtonStyle.green)
        )
        paginator.add_button(
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            )
        )
        paginator.add_button(
            pages.PaginatorButton("next", style=discord.ButtonStyle.green)
        )
        await paginator.send(ctx)

    @commands.command()
    async def pagetest_target(self, ctx: commands.Context):
        """Demonstrates sending the paginator to a different target than where it was invoked (prefix-command version)."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.send(ctx, target=ctx.author, target_message="Paginator sent!")


def setup(bot):
    bot.add_cog(PageTest(bot))

API Reference

Page

Attributes

• content
• custom_view
• embeds
• files

Methods

• asynccallback
• defupdate_files

class discord.ext.pages.Page(content=None, embeds=None, custom_view=None, files=None, **kwargs)

Represents a page shown in the paginator.

Allows for directly referencing and modifying each page as a class instance.

パラメータ:

• content (str | None) -- The content of the page. Corresponds to the discord.Message.content attribute.

• embeds (list[list[Embed] | Embed] | None) -- The embeds of the page. Corresponds to the discord.Message.embeds attribute.

• files (list[File] | None) -- A list of local files to be shown with the page.

• custom_view (View | None) -- The custom view shown when the page is visible. Overrides the custom_view attribute of the main paginator.

await callback(interaction=None)

This function is a coroutine.

The coroutine associated to a specific page. If Paginator.page_action() is used, this coroutine is called.

パラメータ:

interaction (Interaction | None) -- The interaction associated with the callback, if any.

update_files()

Updates discord.File objects so that they can be sent multiple times. This is called internally each time the page is sent.

戻り値の型:

list[File] | None

property content: str | None

Gets the content for the page.

property embeds: list[list[Embed] | Embed] | None

Gets the embeds for the page.

property custom_view: View | None

Gets the custom view assigned to the page.

property files: list[File] | None

Gets the files associated with the page.

Paginator

Attributes

• buttons
• current_page
• default_page_group
• get_page_content
• menu
• message
• page_count
• page_groups
• user

Methods

• clsPaginator.from_dict
• clsPaginator.from_message
• defadd_button
• defadd_default_buttons
• defadd_item
• defadd_menu
• asynccancel
• defclear_items
• defcopy_text
• asyncdisable
• defdisable_all_items
• asyncedit
• defenable_all_items
• defget_item
• defget_page_group_content
• asyncgoto_page
• asyncinteraction_check
• defis_components_v2
• defis_dispatching
• defis_finished
• defis_persistent
• asyncon_check_failure
• asyncon_error
• asyncon_timeout
• asyncpage_action
• defremove_button
• defremove_item
• asyncrespond
• asyncsend
• defstop
• asyncupdate
• defupdate_buttons
• defupdate_custom_view
• asyncwait

class discord.ext.pages.Paginator(pages, show_disabled=True, show_indicator=True, show_menu=False, menu_placeholder='Select Page Group', author_check=True, disable_on_timeout=True, use_default_buttons=True, default_button_row=0, loop_pages=False, custom_view=None, timeout=180.0, custom_buttons=None, trigger_on_display=None)

Creates a paginator which can be sent as a message and uses buttons for navigation.

パラメータ:

• pages (list[PageGroup] | list[Page] | list[str] | list[list[Embed] | Embed]) -- The list of PageGroup objects, Page objects, strings, embeds, or list of embeds to paginate. If a list of PageGroup objects is provided and show_menu is False, only the first page group will be displayed.

• show_disabled (bool) -- Whether to show disabled buttons.

• show_indicator (bool) -- Whether to show the page indicator when using the default buttons.

• show_menu (bool) -- Whether to show a select menu that allows the user to switch between groups of pages.

• menu_placeholder (str) -- The placeholder text to show in the page group menu when no page group has been selected yet. Defaults to "Select Page Group" if not provided.

• author_check (bool) -- Whether only the original user of the command can change pages.

• disable_on_timeout (bool) -- Whether the buttons get disabled when the paginator view times out.

• use_default_buttons (bool) -- Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

• default_button_row (int) -- The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

• loop_pages (bool) -- Whether to loop the pages when clicking prev/next while at the first/last page in the list.

• custom_view (View | None) -- A custom view whose items are appended below the pagination components. If the currently displayed page has a custom_view assigned, it will replace these view components when that page is displayed.

• timeout (float | None) -- Timeout in seconds from last interaction with the paginator before no longer accepting input.

• custom_buttons (list[PaginatorButton] | None) -- A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

• trigger_on_display (bool | None) -- Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.

menu

The page group select menu associated with this paginator.

Type:

Optional[List[PaginatorMenu]]

page_groups

List of PageGroup objects the user can switch between.

Type:

Optional[List[PageGroup]]

default_page_group

The index of the default page group shown when the paginator is initially sent. Defined by setting default to True on a PageGroup.

Type:

Optional[int]

current_page

A zero-indexed value showing the current page number.

Type:

int

page_count

A zero-indexed value showing the total number of pages.

Type:

int

buttons

A dictionary containing the PaginatorButton objects included in this paginator.

Type:

Dict[str, Dict[str, Union[PaginatorButton, bool]]]

user

The user or member that invoked the paginator.

Type:

Optional[Union[User, Member]]

message

The message the paginator is attached to.

Type:

Union[Message, WebhookMessage]

await update(pages=None, show_disabled=None, show_indicator=None, show_menu=None, author_check=None, menu_placeholder=None, disable_on_timeout=None, use_default_buttons=None, default_button_row=None, loop_pages=None, custom_view=None, timeout=None, custom_buttons=None, trigger_on_display=None, interaction=None, current_page=0)

Updates the existing Paginator instance with the provided options.

パラメータ:

• pages (None | list[PageGroup] | list[Page] | list[str] | list[list[Embed] | Embed]) -- The list of PageGroup objects, Page objects, strings, embeds, or list of embeds to paginate.

• show_disabled (bool | None) -- Whether to show disabled buttons.

• show_indicator (bool | None) -- Whether to show the page indicator when using the default buttons.

• show_menu (bool | None) -- Whether to show a select menu that allows the user to switch between groups of pages.

• author_check (bool | None) -- Whether only the original user of the command can change pages.

• menu_placeholder (str | None) -- The placeholder text to show in the page group menu when no page group has been selected yet. Defaults to "Select Page Group" if not provided.

• disable_on_timeout (bool | None) -- Whether the buttons get disabled when the paginator view times out.

• use_default_buttons (bool | None) -- Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

• default_button_row (int | None) -- The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

• loop_pages (bool | None) -- Whether to loop the pages when clicking prev/next while at the first/last page in the list.

• custom_view (View | None) -- A custom view whose items are appended below the pagination components.

• timeout (float | None) -- Timeout in seconds from last interaction with the paginator before no longer accepting input.

• custom_buttons (list[PaginatorButton] | None) -- A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

• trigger_on_display (bool | None) -- Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.

• interaction (Interaction | None) -- The interaction to use when updating the paginator. If not provided, the paginator will be updated by using its stored message attribute instead.

• current_page (int) -- The initial page number to display when updating the paginator.

await on_timeout()

Disables all buttons when the view times out.

戻り値の型:

None

await disable(include_custom=False, page=None)

Stops the paginator, disabling all of its components.

パラメータ:

• include_custom (bool) -- Whether to disable components added via custom views.

• page (None | str | Page | list[Embed] | Embed) -- The page content to show after disabling the paginator.

戻り値の型:

None

await cancel(include_custom=False, page=None)

Cancels the paginator, removing all of its components from the message.

パラメータ:

• include_custom (bool) -- Whether to remove components added via custom views.

• page (None | str | Page | list[Embed] | Embed) -- The page content to show after canceling the paginator.

戻り値の型:

None

await goto_page(page_number=0, *, interaction=None)

Updates the paginator message to show the specified page number.

パラメータ:

• page_number (int) --

  The page to display.

  注釈

  Page numbers are zero-indexed when referenced internally, but appear as one-indexed when shown to the user.

• interaction (Interaction | None) -- The interaction to use when editing the message. If not provided, the message will be edited using the paginator's stored message attribute instead.

戻り値:

The message associated with the paginator.

戻り値の型:

None

await interaction_check(interaction)

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

If this returns False, on_check_failure() is called.

注釈

If an exception occurs within the body then the check is considered a failure and on_error() is called.

パラメータ:

interaction (Interaction) -- The interaction that occurred.

戻り値:

Whether the view children's callbacks should be called.

戻り値の型:

bool

add_menu()

Adds the default PaginatorMenu instance to the paginator.

add_default_buttons()

Adds the full list of default buttons that can be used with the paginator. Includes first, prev, page_indicator, next, and last.

add_button(button)

Adds a PaginatorButton to the paginator.

パラメータ:

button (PaginatorButton)

remove_button(button_type)

Removes a PaginatorButton from the paginator.

パラメータ:

button_type (str)

update_buttons()

Updates the display state of the buttons (disabled/hidden)

戻り値:

The dictionary of buttons that were updated.

戻り値の型:

dict

update_custom_view(custom_view)

Updates the custom view shown on the paginator.

パラメータ:

custom_view (View)

get_page_group_content(page_group)

Returns a converted list of Page objects for the given page group based on the content of its pages.

パラメータ:

page_group (PageGroup)

戻り値の型:

list[Page]

staticmethod get_page_content(page)

Converts a page into a Page object based on its content.

パラメータ:

page (Page | str | Embed | list[Embed])

戻り値の型:

Page

await page_action(interaction=None)

Triggers the callback associated with the current page, if any.

パラメータ:

interaction (Interaction | None) -- The interaction that was used to trigger the page action.

戻り値の型:

None

await send(ctx, target=None, target_message=None, reference=None, allowed_mentions=None, mention_author=None, delete_after=None)

Sends a message with the paginated items.

パラメータ:

• ctx (Context) -- A command's invocation context.

• target (Messageable | None) -- A target where the paginated message should be sent, if different from the original Context

• target_message (str | None) -- An optional message shown when the paginator message is sent elsewhere.

• reference (None | Message | MessageReference | PartialMessage) -- A reference to the Message to which you are replying with the paginator. This can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

• allowed_mentions (AllowedMentions | None) -- Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• mention_author (bool | None) -- If set, overrides the replied_user attribute of allowed_mentions.

• delete_after (float | None) -- If set, deletes the paginator after the specified time.

戻り値:

The message that was sent with the paginator.

戻り値の型:

Message

await edit(message, suppress=None, suppress_embeds=None, allowed_mentions=None, delete_after=None, user=None)

Edits an existing message to replace it with the paginator contents.

注釈

If invoked from an interaction, you will still need to respond to the interaction.

パラメータ:

• message (Message) -- The message to edit with the paginator.

• suppress (bool | None) --

  Whether to suppress embeds for the message. This removes all the embeds if set to True. If set to False this brings the embeds back if they were suppressed. Using this parameter requires manage_messages.

  バージョン 2.8 で非推奨.

• suppress_embeds (bool) --

  Whether to suppress embeds for the message. This removes all the embeds if set to True. If set to False this brings the embeds back if they were suppressed. Using this parameter requires manage_messages.

  Added in version 2.8.

• allowed_mentions (AllowedMentions | None) -- Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• delete_after (float | None) -- If set, deletes the paginator after the specified time.

• user (User | Member | None) -- If set, changes the user that this paginator belongs to.

戻り値:

The message that was edited. Returns None if the operation failed.

戻り値の型:

Message | None

add_item(item)

Adds an item to the view. Attempting to add a ActionRow will add its children instead.

パラメータ:

item (ViewItem[TypeVar(V, bound= BaseView, covariant=True)]) -- The item to add to the view.

例外:

• TypeError -- An ViewItem was not passed.

• ValueError -- Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

戻り値の型:

Self

clear_items()

Removes all items from the view.

戻り値の型:

Self

copy_text()

Returns the text of all TextDisplay items in this View. Equivalent to the Copy Text option on Discord clients.

戻り値の型:

str

disable_all_items(*, exclusions=None)

Disables all buttons and select menus in the view.

パラメータ:

exclusions (list[ViewItem[TypeVar(V, bound= BaseView, covariant=True)]] | None) -- A list of items in self.children to not disable from the view.

戻り値の型:

Self

enable_all_items(*, exclusions=None)

Enables all buttons and select menus in the view.

パラメータ:

exclusions (list[ViewItem[TypeVar(V, bound= BaseView, covariant=True)]] | None) -- A list of items in self.children to not enable from the view.

戻り値の型:

Self

classmethod from_dict(data, /, *, timeout=180.0)

Converts a list of component dicts into a View.

パラメータ:

• data (list[Component]) -- The list of components to convert into a view.

• timeout (float | None) -- The timeout of the converted view.

戻り値:

The converted view. This always returns a View and not one of its subclasses.

戻り値の型:

View

classmethod from_message(message, /, *, timeout=180.0)

Converts a message's components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

パラメータ:

• message (Message) -- The message with components to convert into a view.

• timeout (float | None) -- The timeout of the converted view.

戻り値:

The converted view. This always returns a View and not one of its subclasses.

戻り値の型:

View

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, ...). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

パラメータ:

custom_id (str | int) -- The id of the item to get

戻り値:

The item with the matching custom_id or id if it exists.

戻り値の型:

Item | None

is_components_v2()

Whether the view contains V2 components.

A view containing V2 components cannot be sent alongside message content or embeds.

This is always False for View.

戻り値の型:

bool

is_dispatching()

Whether the view has been added for dispatching purposes.

戻り値の型:

bool

is_finished()

Whether the view has finished interacting.

戻り値の型:

bool

is_persistent()

Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

戻り値の型:

bool

await on_check_failure(interaction)

This function is a coroutine. A callback that is called when a BaseView.interaction_check() returns False. This can be used to send a response when a check failure occurs.

パラメータ:

interaction (Interaction) -- The interaction that occurred.

戻り値の型:

None

await on_error(error, item, interaction)

This function is a coroutine.

A callback that is called when an item's callback or interaction_check() fails with an error.

The default implementation prints the traceback to stderr.

パラメータ:

• error (Exception) -- The exception that was raised.

• item (ViewItem[TypeVar(V, bound= BaseView, covariant=True)]) -- The item that failed the dispatch.

• interaction (Interaction) -- The interaction that led to the failure.

戻り値の型:

None

remove_item(item)

Removes an item from the view. If an int or str is passed, the item will be removed by Item id or custom_id respectively.

パラメータ:

item (ViewItem[TypeVar(V, bound= BaseView, covariant=True)] | int | str) -- The item, item id, or item custom_id to remove from the view.

戻り値の型:

Self

await respond(interaction, ephemeral=False, target=None, target_message='Paginator sent!')

Sends an interaction response or followup with the paginated items.

パラメータ:

• interaction (Interaction | BridgeContext) -- The interaction or BridgeContext which invoked the paginator. If passing a BridgeContext object, you cannot make this an ephemeral paginator.

• ephemeral (bool) --

  Whether the paginator message and its components are ephemeral. If target is specified, the ephemeral message content will be target_message instead.

  警告

  If your paginator is ephemeral, it cannot have a timeout longer than 15 minutes (and cannot be persistent).

• target (Messageable | None) -- A target where the paginated message should be sent, if different from the original discord.Interaction

• target_message (str) -- The content of the interaction response shown when the paginator message is sent elsewhere.

戻り値:

The Message or WebhookMessage that was sent with the paginator.

戻り値の型:

Message | WebhookMessage

stop()

Stops listening to interaction events from this view.

This operation cannot be undone.

戻り値の型:

None

await wait()

Waits until the view has finished interacting.

A view is considered finished when stop() is called, or it times out.

戻り値:

If True, then the view timed out. If False then the view finished normally.

戻り値の型:

bool

PaginatorButton

Attributes

• custom_id
• disabled
• emoji
• id
• label
• paginator
• row
• sku_id
• style
• type
• url
• view
• width

Methods

• asynccallback

class discord.ext.pages.PaginatorButton(button_type, label=None, emoji=None, style=('success', 3), disabled=False, custom_id=None, row=0, loop_label=None)

Creates a button used to navigate the paginator.

パラメータ:

• button_type (str) -- The type of button being created. Must be one of first, prev, next, last, or page_indicator.

• label (str) -- The label shown on the button. Defaults to a capitalized version of button_type (e.g. "Next", "Prev", etc.)

• emoji (str | GuildEmoji | AppEmoji | PartialEmoji) -- The emoji shown on the button in front of the label.

• disabled (bool) -- Whether to initially show the button as disabled.

• loop_label (str) -- The label shown on the button when loop_pages is set to True in the Paginator class.

paginator

The paginator class where this button is being used. Assigned to the button when Paginator.add_button is called.

Type:

Paginator

パラメータ:

• style (ButtonStyle)

• custom_id (str)

• row (int)

property label: str | None

The label of the button, if available.

property emoji: PartialEmoji | None

The emoji of the button, if available.

property style: ButtonStyle

The style of the button.

property disabled: bool

Whether the button is disabled or not.

await callback(interaction)

This function is a coroutine.

The coroutine that is called when the navigation button is clicked.

パラメータ:

interaction (Interaction) -- The interaction created by clicking the navigation button.

property custom_id: str | None

The ID of the button that gets received during an interaction.

If this button is for a URL, it does not have a custom ID.

property id: int | None

Gets this item's ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item's parent is sent.

戻り値:

The ID of this item, or None if the user didn't set one.

戻り値の型:

Optional[int]

property row: int | None

Gets or sets the row position of this item within its parent view.

The row position determines the vertical placement of the item in the UI. The value must be an integer between 0 and 4 (inclusive), or None to indicate that no specific row is set. This attribute is not compatible with discord.ui.DesignerView.

戻り値:

The row position of the item, or None if not explicitly set.

戻り値の型:

Optional[int]

例外:

ValueError -- If the row value is not None and is outside the range [0, 4].

property sku_id: int | None

The ID of the SKU this button refers to.

property type: ComponentType

The underlying component's type.

property url: str | None

The URL this button sends you to.

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

戻り値:

The parent view of this item, or None if the item is not attached to any view.

戻り値の型:

Optional[BaseView]

property width: int

Gets the width of the item in the UI layout.

The width determines how much horizontal space this item occupies within its row.

戻り値:

The width of the item. Buttons have a width of 1.

戻り値の型:

int

PaginatorMenu

Attributes

• channel_types
• custom_id
• default_values
• disabled
• id
• max_values
• min_values
• modal
• options
• paginator
• placeholder
• required
• row
• type
• values
• view
• width

Methods

• defadd_default_value
• defadd_option
• defappend_default_value
• defappend_option
• asynccallback

class discord.ext.pages.PaginatorMenu(page_groups, placeholder=None, custom_id=None)

Creates a select menu used to switch between page groups, which can each have their own set of buttons.

パラメータ:

placeholder (str | None) -- The placeholder text that is shown if nothing is selected.

paginator

The paginator class where this menu is being used. Assigned to the menu when Paginator.add_menu is called.

Type:

Paginator

パラメータ:

• page_groups (list[PageGroup])

• custom_id (str | None)

add_default_value(*, id, type=...)

Adds a default value to the select menu.

To append a pre-existing discord.SelectDefaultValue use the append_default_value() method instead.

Added in version 2.7.

パラメータ:

• id (int) -- The ID of the entity to add as a default.

• type (SelectDefaultValueType) -- The default value type of the ID. This is only required if the select type is discord.ComponentType.mentionable_select.

例外:

• TypeError -- The select type is a mentionable_select and type was not provided, or the select type is string_select.

• ValueError -- The number of default select values exceeds 25.

戻り値の型:

Self

add_option(*, label, value=..., description=None, emoji=None, default=False)

Adds an option to the select menu.

To append a pre-existing discord.SelectOption use the append_option() method instead.

パラメータ:

• label (str) -- The label of the option. This is displayed to users. Can only be up to 100 characters.

• value (str) -- The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters.

• description (str | None) -- An additional description of the option, if any. Can only be up to 100 characters.

• emoji (str | GuildEmoji | AppEmoji | PartialEmoji | None) -- The emoji of the option, if available. This can either be a string representing the custom or unicode emoji or an instance of PartialEmoji, GuildEmoji, or AppEmoji.

• default (bool) -- Whether this option is selected by default.

例外:

ValueError -- The number of options exceeds 25.

戻り値の型:

Self

append_default_value(value, /)

Appends a default value to this select menu.

Added in version 2.7.

パラメータ:

value (SelectDefaultValue | Snowflake) --

The default value to append to this select.

These can be either discord.SelectDefaultValue instances or models, which will be converted into discord.SelectDefaultvalue instances.

Below, is a table defining the model instance type and the default value type it will be mapped:

Model Type	Default Value Type
discord.User	discord.SelectDefaultValueType.user
discord.Member	discord.SelectDefaultValueType.user
discord.Role	discord.SelectDefaultValueType.role
discord.abc.GuildChannel	discord.SelectDefaultValueType.channel
discord.Object	depending on discord.Object.type, it will be mapped to any above

If you pass a model that is not defined in the table, TypeError will be raised.

注釈

The discord.abc.GuildChannel protocol includes discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.ForumChannel, discord.Thread, discord.MediaChannel. This list is not exhaustive, and is bound to change based of the new channel types Discord adds.

例外:

• TypeError -- The select type is string_select, which does not allow for default_values

• ValueError -- The number of default select values exceeds 25.

戻り値の型:

Self

append_option(option)

Appends an option to the select menu.

パラメータ:

option (SelectOption) -- The option to append to the select menu.

例外:

ValueError -- The number of options exceeds 25.

戻り値の型:

Self

property channel_types: list[ChannelType]

A list of channel types that can be selected in this menu.

property custom_id: str

The ID of the select menu that gets received during an interaction.

property default_values: list[SelectDefaultValue]

A list of the select's default values. This is only applicable if the select type is not discord.ComponentType.string_select.

Added in version 2.7.

property disabled: bool

Whether the select is disabled or not.

property id: int | None

Gets this item's ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item's parent is sent.

戻り値:

The ID of this item, or None if the user didn't set one.

戻り値の型:

Optional[int]

property max_values: int

The maximum number of items that must be chosen for this select menu.

property min_values: int

The minimum number of items that must be chosen for this select menu.

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

戻り値:

The parent modal of this item, or None if the item is not attached to any modal.

戻り値の型:

Optional[BaseModal]

property options: list[SelectOption]

A list of options that can be selected in this menu.

property placeholder: str | None

The placeholder text that is shown if nothing is selected, if any.

property required: bool

Whether the select is required or not. Only applicable in modal selects.

property row: int | None

Gets or sets the row position of this item within its parent view.

The row position determines the vertical placement of the item in the UI. The value must be an integer between 0 and 4 (inclusive), or None to indicate that no specific row is set. This attribute is not compatible with discord.ui.DesignerView.

戻り値:

The row position of the item, or None if not explicitly set.

戻り値の型:

Optional[int]

例外:

ValueError -- If the row value is not None and is outside the range [0, 4].

property type: ComponentType

The underlying component's type.

property values: list[ST] | None

List[str] | List[discord.Member | discord.User]] | List[discord.Role]] | List[discord.Member | discord.User | discord.Role]] | List[discord.abc.GuildChannel] | None: A list of values that have been selected by the user. This will be None if the select has not been interacted with yet.

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

戻り値:

The parent view of this item, or None if the item is not attached to any view.

戻り値の型:

Optional[BaseView]

property width: int

Gets the width of the item in the UI layout.

The width determines how much horizontal space this item occupies within its row.

戻り値:

The width of the item. Select menus have a width of 5.

戻り値の型:

int

await callback(interaction)

This function is a coroutine.

The coroutine that is called when a menu option is selected.

パラメータ:

interaction (Interaction) -- The interaction created by selecting the menu option.

PageGroup

class discord.ext.pages.PageGroup(pages, label, description=None, emoji=None, default=None, show_disabled=None, show_indicator=None, author_check=None, disable_on_timeout=None, use_default_buttons=None, default_button_row=0, loop_pages=None, custom_view=None, timeout=None, custom_buttons=None, trigger_on_display=None)

Creates a group of pages which the user can switch between.

Each group of pages can have its own options, custom buttons, custom views, etc.

注釈

If multiple PageGroup objects have different options, they should all be set explicitly when creating each instance.

パラメータ:

• pages (list[str] | list[Page] | list[list[Embed] | Embed]) -- The list of Page objects, strings, embeds, or list of embeds to include in the page group.

• label (str) -- The label shown on the corresponding PaginatorMenu dropdown option. Also used as the SelectOption value.

• description (str | None) -- The description shown on the corresponding PaginatorMenu dropdown option.

• emoji (str | GuildEmoji | AppEmoji | PartialEmoji) -- The emoji shown on the corresponding PaginatorMenu dropdown option.

• default (bool | None) -- Whether the page group should be the default page group initially shown when the paginator response is sent. Only one PageGroup can be the default page group.

• show_disabled (bool | None) -- Whether to show disabled buttons.

• show_indicator (bool | None) -- Whether to show the page indicator when using the default buttons.

• author_check (bool | None) -- Whether only the original user of the command can change pages.

• disable_on_timeout (bool | None) -- Whether the buttons get disabled when the paginator view times out.

• use_default_buttons (bool | None) -- Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

• default_button_row (int) -- The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

• loop_pages (bool | None) -- Whether to loop the pages when clicking prev/next while at the first/last page in the list.

• custom_view (View | None) -- A custom view whose items are appended below the pagination buttons.

• timeout (float | None) -- Timeout in seconds from last interaction with the paginator before no longer accepting input.

• custom_buttons (list[PaginatorButton] | None) -- A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

• trigger_on_display (bool | None) -- Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.