IPython 组件清单

import ipywidgets as widgets

数值小部件(IPython)

ipywidgets 中有许多设计用于显示数值的小部件。有用于显示整数和浮点数的小部件，包括有界和无界的。整数小部件与其浮点数对应物共享类似的命名方案。通过在小部件名称中将 Float 替换为 Int，你可以找到整数对应的小部件。

IntSlider

• 滑块以指定的初始 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'
)

FloatSlider

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

FloatLogSlider 具有刻度，使得使用滑块处理大范围的正数变得容易。min 和 max 指的是底数的最小和最大指数，而 value 指的是滑块的实际值。

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

IntRangeSlider

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',
)

FloatRangeSlider

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',
)

IntProgress

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

FloatProgress

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

对数据（范围、仅限整数）施加某些限制的数字文本框在用户按下回车键时会施加该限制。

BoundedIntText

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

BoundedFloatText

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

IntText

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

FloatText

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

布尔小部件

有三种小部件专门设计用于显示布尔值。

ToggleButton

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
)

Valid

Valid 部件提供了只读指示器。

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

选择部件

有多种部件可用于显示单选列表，还有两种可用于选择多个值。所有这些都继承自相同的基类。你可以通过传递一个列表来指定可选择选项的枚举（选项要么是（标签，值）对，要么只是值，其标签通过调用 str 得到）。

Dropdown

widgets.Dropdown(
    options=['1', '2', '3'],
    value='2',
    description='Number:',
    disabled=False,
)

以下也是有效的，它将单词 'One', 'Two', 'Three' 显示为下拉选项，但返回值 1, 2, 3。

widgets.Dropdown(
    options=[('One', 1), ('Two', 2), ('Three', 3)],
    value=2,
    description='Number:',
)

RadioButtons

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'}
        )
    ]
)

Select

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

SelectionSlider

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

value、index 和 label 键是所选最小值和最大值的2元组。options 必须非空。

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
)

ToggleButtons

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
)

SelectMultiple

可以通过按住 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 部件可用于构建自定义控件标签。

Text

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

Textarea

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

Combobox

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

Password

Password 部件在屏幕上隐藏用户输入。这个部件不是收集敏感信息的安全方式，因为：

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

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

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

Label

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

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

HTML

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

HTML Math

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

Image

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

Button

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 部件可以捕获和显示 stdout、stderr 以及由 IPython 生成的 富输出。有关详细文档，请参阅 output widget examples。

播放（动画）部件

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])

Tag 部件

TagsInput

TagsInput 部件对于选择/创建标签列表非常有用。你可以拖放标签以重新排序它们，将它们限制在一组允许的值中，甚至防止创建重复的标签。

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

ColorsInput

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 date 输入字段的文章。

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

时间选择器

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

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）对象易于理解和操作，但代价是忽略了现实的某些方面。

如果你需要将所选的日期时间与无时区的日期时间对象进行比较，这将非常有用，否则 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
)

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

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

uploader = widgets.FileUpload()
display(uploader)

# 上传一些文件...

# 一旦文件被上传，使用 `.value` 属性来检索内容：
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 dataframe，你可以使用一个 BytesIO 对象：

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

如果上传的文件是图像，你可以使用 图像 部件进行可视化：

widgets.Image(value=uploaded_file.content.tobytes())

*ipywidgets 8* 中的更改：

FileUpload 在 ipywidgets 8 中发生了重大变化：

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

• .data traitlet 已被删除。要检索它，请使用 [f.content.tobytes() for f in uploader.value]。

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

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

控制器

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

widgets.Controller(
    index=0,
)

容器/布局部件

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

Box

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

HBox

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

VBox

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])

GridBox

此框使用 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，而不是 value

与之前讨论的其他部件不同，容器部件 Accordion 和 Tab 在用户更改所选的折叠面板或标签页时更新它们的 selected_index 属性。这意味着你既可以观察用户的操作 也可以 通过设置 selected_index 的值来编程控制用户看到的内容。

将 selected_index 设置为 None 会关闭所有折叠面板或者取消选择所有标签页。

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

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