控件列表#

import ipywidgets as widgets

数值组件#

ipywidgets 中分发了许多用于显示数值的小部件。存在用于显示有界和无界整数和浮点数的小部件。整数小部件的命名方案与其浮点对应物类似。通过在小部件名称中将 Float 替换为 Int，您可以找到对应的整数版本。

整数滑块#

  • 滑块显示时带有指定的初始value。上下边界由min和max定义，并且数值可以根据step参数进行递增。

  • 滑动条的标签由description参数定义

  • 滑块的 orientation 可以是 'horizontal'（默认）或 'vertical'

  • readout 在滑块旁边显示其当前值。选项为 True（默认）或 False

    • readout_format 指定用于表示滑块值的格式函数。默认为 '.2f'

widgets.IntSlider(
    value=7,
    min=0,
    max=10,
    step=1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True,
    readout_format='d'
)

浮点滑块#

widgets.FloatSlider(
    value=7.5,
    min=0,
    max=10.0,
    step=0.1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True,
    readout_format='.1f',
)

一个滑块垂直显示的示例。

widgets.FloatSlider(
    value=7.5,
    min=0,
    max=10.0,
    step=0.1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='vertical',
    readout=True,
    readout_format='.1f',
)

浮点对数滑块#

FloatLogSlider 具有对数刻度，这使得创建覆盖广泛正数范围的滑块变得容易。min 和 max 指的是 base 的最小和最大指数，而 value 指的是滑块的实际值。

widgets.FloatLogSlider(
    value=10,
    base=10,
    min=-10, # min exponent of base
    max=10, # max exponent of base
    step=0.2, # exponent step
    description='Log Slider'
)

整数范围滑块#

widgets.IntRangeSlider(
    value=[5, 7],
    min=0,
    max=10,
    step=1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True,
    readout_format='d',
)

浮动范围滑块#

widgets.FloatRangeSlider(
    value=[5, 7.5],
    min=0,
    max=10.0,
    step=0.1,
    description='Test:',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True,
    readout_format='.1f',
)

进度指示器#

widgets.IntProgress(
    value=7,
    min=0,
    max=10,
    description='Loading:',
    bar_style='', # 'success', 'info', 'warning', 'danger' or ''
    style={'bar_color': 'maroon'},
    orientation='horizontal'
)

浮动进度条#

widgets.FloatProgress(
    value=7.5,
    min=0,
    max=10.0,
    description='Loading:',
    bar_style='info',
    style={'bar_color': '#ffff00'},
    orientation='horizontal'
)

数值文本框对数据施加某些限制（如范围、仅限整数），当用户按下回车键时强制执行该限制。

有界整数文本#

widgets.BoundedIntText(
    value=7,
    min=0,
    max=10,
    step=1,
    description='Text:',
    disabled=False
)

有界浮点文本#

widgets.BoundedFloatText(
    value=7.5,
    min=0,
    max=10.0,
    step=0.1,
    description='Text:',
    disabled=False
)

整数文本#

widgets.IntText(
    value=7,
    description='Any:',
    disabled=False
)

浮动文本#

widgets.FloatText(
    value=7.5,
    description='Any:',
    disabled=False
)

布尔组件#

有三种小部件用于显示布尔值。

切换按钮#

widgets.ToggleButton(
    value=False,
    description='Click me',
    disabled=False,
    button_style='', # 'success', 'info', 'warning', 'danger' or ''
    tooltip='Description',
    icon='check' # (FontAwesome names without the `fa-` prefix)
)

复选框#

  • value 指定了复选框的值

  • indent 参数会放置一个缩进的复选框，与其他控件对齐。选项为 True（默认）或 False

widgets.Checkbox(
    value=False,
    description='Check me',
    disabled=False,
    indent=False
)

有效的#

有效的小部件提供了一个只读指示器。

widgets.Valid(
    value=False,
    description='Valid!',
)

选择小部件#

有多个小部件可用于显示单选列表，以及两个可用于选择多个值的小部件。它们都继承自同一个基类。您可以通过传递一个列表来指定可选择的选项枚举（选项可以是（标签，值）对，或者只是其标签通过调用str函数派生的值）。

单选框#

widgets.RadioButtons(
    options=['pepperoni', 'pineapple', 'anchovies'],
#    value='pineapple', # Defaults to 'pineapple'
#    layout={'width': 'max-content'}, # If the items' names are long
    description='Pizza topping:',
    disabled=False
)

使用动态布局和超长标签#

widgets.Box(
    [
        widgets.Label(value='Pizza topping with a very long label:'), 
        widgets.RadioButtons(
            options=[
                'pepperoni', 
                'pineapple', 
                'anchovies', 
                'and the long name that will fit fine and the long name that will fit fine and the long name that will fit fine '
            ],
            layout={'width': 'max-content'}
        )
    ]
)

选择#

widgets.Select(
    options=['Linux', 'Windows', 'macOS'],
    value='macOS',
    # rows=10,
    description='OS:',
    disabled=False
)

选择滑条#

widgets.SelectionSlider(
    options=['scrambled', 'sunny side up', 'poached', 'over easy'],
    value='sunny side up',
    description='I like my eggs ...',
    disabled=False,
    continuous_update=False,
    orientation='horizontal',
    readout=True
)

SelectionRangeSlider#

值、索引和标签键是所选最小值和最大值的二元组。选项必须非空。

import datetime
dates = [datetime.date(2015, i, 1) for i in range(1, 13)]
options = [(i.strftime('%b'), i) for i in dates]
widgets.SelectionRangeSlider(
    options=options,
    index=(0, 11),
    description='Months (2015)',
    disabled=False
)

切换按钮#

widgets.ToggleButtons(
    options=['Slow', 'Regular', 'Fast'],
    description='Speed:',
    disabled=False,
    button_style='', # 'success', 'info', 'warning', 'danger' or ''
    tooltips=['Description of slow', 'Description of regular', 'Description of fast'],
#     icons=['check'] * 3
)

选择多个#

可以使用shift和/或ctrl（或command）键加鼠标点击或方向键来选择多个值。

widgets.SelectMultiple(
    options=['Apples', 'Oranges', 'Pears'],
    value=['Oranges'],
    #rows=10,
    description='Fruits',
    disabled=False
)

字符串小部件#

有多个小部件可用于显示字符串值。Text、Textarea 和 Combobox 小部件接受输入。HTML 和 HTMLMath 小部件将字符串显示为 HTML（HTMLMath 还渲染数学公式）。Label 小部件可用于构建自定义控件标签。

文本#

widgets.Text(
    value='Hello World',
    placeholder='Type something',
    description='String:',
    disabled=False   
)

文本区域#

widgets.Textarea(
    value='Hello World',
    placeholder='Type something',
    description='String:',
    disabled=False
)

组合框#

widgets.Combobox(
    # value='John',
    placeholder='Choose Someone',
    options=['Paul', 'John', 'George', 'Ringo'],
    description='Combobox:',
    ensure_option=True,
    disabled=False
)

密码#

Password 部件会在屏幕上隐藏用户输入。此部件并非收集敏感信息的安全方式，因为：

  • 密码 小部件的内容以未加密的方式传输。

  • 如果小部件的状态保存在笔记本中，Password 小部件的内容将以纯文本形式存储。

widgets.Password(
    value='password',
    placeholder='Enter password',
    description='Password:',
    disabled=False
)

标签#

如果你需要在控件旁边使用与内置控件描述相似的样式构建自定义描述，那么 Label 小部件会非常有用。

widgets.HBox([widgets.Label(value="The $m$ in $E=mc^2$:"), widgets.FloatSlider()])

超文本标记语言#

widgets.HTML(
    value="Hello <b>World</b>",
    placeholder='Some HTML',
    description='Some HTML',
)

HTML 数学#

widgets.HTMLMath(
    value=r"Some math and <i>HTML</i>: \(x^2\) and $$\frac{x+1}{x-1}$$",
    placeholder='Some HTML',
    description='Some HTML',
)

图像#

file = open("images/WidgetArch.png", "rb")
image = file.read()
widgets.Image(
    value=image,
    format='png',
    width=300,
    height=400,
)

按钮#

button = widgets.Button(
    description='Click me',
    disabled=False,
    button_style='', # 'success', 'info', 'warning', 'danger' or ''
    tooltip='Click me',
    icon='check' # (FontAwesome names without the `fa-` prefix)
)
button

icon 属性可用于定义图标；请参阅 fontawesome 页面了解可用图标。 可以使用 button.on_click(foo) 注册回调函数 foo。当按钮被点击时，函数 foo 将被调用，并将按钮实例作为其唯一参数。

输出#

Output 部件可以捕获并显示标准输出、标准错误以及IPython生成的富输出。有关详细文档，请参见输出部件示例。

播放 (动画) 控件#

Play 小部件通过以特定速度迭代整数序列来执行动画非常有用。下方滑块的数值与播放器相关联。

play = widgets.Play(
    value=50,
    min=0,
    max=100,
    step=1,
    interval=500,
    description="Press play",
    disabled=False
)
slider = widgets.IntSlider()
widgets.jslink((play, 'value'), (slider, 'value'))
widgets.HBox([play, slider])

标签小部件#

标签输入#

TagsInput 小部件适用于选择/创建标签列表。您可以拖放标签以重新排序，将它们限制为一组允许的值，甚至防止创建重复标签。

tags = widgets.TagsInput(
    value=['pizza', 'fries'],
    allowed_tags=['pizza', 'fries', 'tomatoes', 'steak'],
    allow_duplicates=False
)
tags

颜色输入#

ColorsInput 小部件对于选择/创建颜色列表非常有用。您可以拖放颜色以重新排序它们，将它们限制为一组允许的值，甚至防止创建重复的颜色。

color_tags = widgets.ColorsInput(
    value=['red', '#2f6d30'],
    # allowed_tags=['red', 'blue', 'green'],
    # allow_duplicates=False
)
color_tags

浮点与整数输入部件#

FloatInputs 和 IntsInput 小部件支持创建浮点数或整数列表。

floatsinput = widgets.FloatsInput(
    value=[1.3, 4.56, 78.90],
    tag_style='info',
    format = '.2f'
)
floatsinput

intsinput = widgets.IntsInput(
    value=[1, 4, 3243],
    min=0,
    max=1000000,
    format='$,d'
)
intsinput

日期选择器#

有关支持日期选择器小部件的浏览器列表，请参见MDN HTML 日期输入字段文章。

widgets.DatePicker(
    description='Pick a Date',
    disabled=False
)

时间选择器#

有关支持时间选择器小部件的浏览器列表，请参阅HTML 时间输入字段的 MDN 文章。

widgets.TimePicker(
    description='Pick a Time',
    disabled=False
)

日期时间选择器#

有关支持日期时间选择器小组件的浏览器列表，请参见MDN文章中的HTML datetime-local输入字段。对于不支持datetime-local输入的浏览器，我们会尝试回退显示独立的日期和时间输入。

时区#

关于日期时间时区，有两点值得注意：

  • 浏览器始终使用其时区选择日期时间。

  • 内核始终在系统默认时区获取日期时间（参见 https://docs.python.org/3/library/datetime.html#datetime.datetime.astimezone 使用 None 作为参数）。

这意味着如果内核和浏览器处于不同的时区，时区的默认字符串序列化可能不同，但它们仍将代表同一时间点。

widgets.DatetimePicker(
    description='Pick a Time',
    disabled=False
)

朴素选择器#

在某些情况下，您可能希望选择原生日期时间对象，即无时区意识的日期时间。引用 Python 3 文档的话：

简单对象易于理解和使用，但代价是忽略了现实的某些方面。

当你需要将选择的日期时间与 naive datetime 对象进行比较时，这很有用，否则 Python 会报错！

widgets.NaiveDatetimePicker(description='Pick a Time')

颜色选择器#

widgets.ColorPicker(
    concise=False,
    description='Pick a color',
    value='blue',
    disabled=False
)

文件上传#

FileUpload 允许将任意类型的文件上传到内核的内存中。

widgets.FileUpload(
    accept='',  # Accepted file extension e.g. '.txt', '.pdf', 'image/*', 'image/*,.pdf'
    multiple=False  # True to accept multiple files upload else False
)

上传部件暴露了一个value属性，该属性包含已上传的文件。value属性是一个元组，其中包含每个已上传文件的字典。例如：

uploader = widgets.FileUpload()
display(uploader)

# upload something...

# once a file is uploaded, use the `.value` attribute to retrieve the content:
uploader.value
#=> (
#=>   {
#=>     'name': 'example.txt',
#=>     'type': 'text/plain',
#=>     'size': 36,
#=>     'last_modified': datetime.datetime(2020, 1, 9, 15, 58, 43, 321000, tzinfo=datetime.timezone.utc), 
#=>     'content': <memory at 0x10c1b37c8>
#=>   },
#=> )

字典中的条目可以像访问字典一样作为项目访问，或者作为属性访问：

uploaded_file = uploader.value[0]
uploaded_file["size"]
#=> 36
uploaded_file.size
#=> 36

上传文件的内容位于content键的值中。它们是一个内存视图：

uploaded_file.content
#=> <memory at 0x10c1b37c8>

您可以将内容提取为字节：

uploaded_file.content.tobytes()
#=> b'This is the content of example.txt.\n'

如果文件是文本文件，您可以通过解码将其内容作为字符串获取：

import codecs
codecs.decode(uploaded_file.content, encoding="utf-8")
#=> 'This is the content of example.txt.\n'

您可以将上传的文件从内核保存到文件系统中：

with open("./saved-output.txt", "wb") as fp:
    fp.write(uploaded_file.content)

要将上传的文件转换为Pandas数据框，您可以使用BytesIO对象：

import io
import pandas as pd
pd.read_csv(io.BytesIO(uploaded_file.content))

如果上传的文件是图像，您可以使用一个image小部件进行可视化：

widgets.Image(value=uploaded_file.content.tobytes())
Changes in *ipywidgets 8*:

FileUpload 在 ipywidgets 8 中发生了显著变化：

  • .value 属性现在是一个字典列表，而不是将上传名称映射到内容的字典。要检索原始形式，请使用 {f["name"]: f.content.tobytes() for f in uploader.value}。

  • .data 特征属性已被移除。要获取它，请使用 [f.content.tobytes() for f in uploader.value]。

  • .metadata 特性已被移除。要检索它，请使用 [{k: v for k, v in f.items() if k != "content"} for f in w.value]。

警告：当使用 `FileUpload` 部件时，如果部件状态被保存，上传的文件内容可能会保存在笔记本中。

控制器#

Controller 允许将游戏控制器作为输入设备使用。

widgets.Controller(
    index=0,
)

容器/布局小组件#

这些部件用于容纳其他部件，称为子部件。每个部件都有一个children属性，可以在部件创建时或之后设置。

盒子#

items = [widgets.Label(str(i)) for i in range(4)]
widgets.Box(items)

横向框布局#

items = [widgets.Label(str(i)) for i in range(4)]
widgets.HBox(items)

垂直盒#

items = [widgets.Label(str(i)) for i in range(4)]
left_box = widgets.VBox([items[0], items[1]])
right_box = widgets.VBox([items[2], items[3]])
widgets.HBox([left_box, right_box])

网格盒子#

此框利用HTML网格规范将其子元素布局在二维网格中。以下示例将内部的8个项目布局为3列，并根据需要自动调整行数以容纳所有项目。

items = [widgets.Label(str(i)) for i in range(8)]
widgets.GridBox(items, layout=widgets.Layout(grid_template_columns="repeat(3, 100px)"))

折叠面板#

accordion = widgets.Accordion(children=[widgets.IntSlider(), widgets.Text()], titles=('Slider', 'Text'))
accordion

标签页#

在这个例子中，子项是在标签页创建之后设置的。标签页的标题设置方式与Accordion相同。

tab_contents = ['P0', 'P1', 'P2', 'P3', 'P4']
children = [widgets.Text(description=name) for name in tab_contents]
tab = widgets.Tab()
tab.children = children
tab.titles = [str(i) for i in range(len(children))]
tab

堆栈#

Stack 小部件可以像 Tab 和 Accordion 一样拥有多个子小部件，但一次仅显示一个，具体取决于 selected_index 的值：

button = widgets.Button(description='Click here')
slider = widgets.IntSlider()
stack = widgets.Stack([button, slider], selected_index=0)
stack  # will show only the button

这可以与另一个基于选择的控件结合使用，根据选择显示不同的控件：

dropdown = widgets.Dropdown(options=['button', 'slider'])
widgets.jslink((dropdown, 'index'), (stack, 'selected_index'))
widgets.VBox([dropdown, stack])

手风琴、标签页和堆叠使用 selected_index，而非值#

与之前讨论的其他小部件不同，容器小部件 Accordion 和 Tab 在用户更改选中的折叠面板或选项卡时更新其 selected_index 属性。这意味着您既可以查看用户的操作，也可以通过设置 selected_index 的值来以编程方式控制用户看到的内容。

设置 selected_index = None 会关闭所有手风琴或取消选择所有标签页。

在下面的单元格中，尝试显示或设置 selected_index 的 tab 和/或 accordion。

tab.selected_index = 3

accordion.selected_index = None

嵌套标签页和手风琴#

选项卡和手风琴可以任意深度嵌套。如果你有几分钟时间，可以尝试嵌套几个手风琴，或者将手风琴放入选项卡内，或者将选项卡放入手风琴内。

下面的例子在一个标签页中创建了几个带有手风琴子元素的标签页

tab_nest = widgets.Tab()
tab_nest.children = [accordion, accordion]
tab_nest.titles = ('An accordion', 'Copy of the accordion')
tab_nest
On this page
Edit on GitHub
Show Source