.ipynb .pdf

repository open issue

Binder

Contents

小部件清单

参考 examples/Widget List.ipynb

import ipywidgets as widgets

数字小部件

有许多与 ipywidgets 一起分发的小部件被设计用来显示数值。存在用于显示有界和无界整数和浮点数的小部件。整数小部件与其对应的浮点部件共享类似的命名模式。通过将小部件名称中的 Float 替换为 Int，您可以找到等效的Integer。

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 指的是 base 的最小和最大指数，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'
)

当用户按下 enter 键时，数字文本框对数据施加了一些限制（范围、整数）。

BoundedIntText

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

Checkbox

• value 指定复选框的值

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

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

Valid

valid 的小部件提供一个只读指示器。

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

选择小部件

有几个小部件可用于显示单个选择列表，还有两个小部件可用于选择多个值。它们都继承自同一个基类。您可以通过传递一个列表（选项是 (label, value) 对，或者通过调用 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', 'OSX'],
    value='OSX',
    # rows=10,
    description='OS:',
    disabled=False
)

SelectionSlider

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

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（或命令）按下鼠标单击或方向键。

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

字符串小部件

有几个小部件可以用来显示字符串值。Text、Textarea 和 Combobox 小部件接受输入。HTML 和 HTMLMath 小部件将字符串显示为 HTML（HTMLMath 也渲染为 math）。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',
)

HTMLMath

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

from urllib.request import urlopen

file = urlopen("https://media.githubusercontent.com/media/xinetzone/ipywidgets-media/main/images/WidgetArch.png")
image = file.read()
widgets.Image(
    value=image,
    format='png',
    width=300,
    height=400,
)

---------------------------------------------------------------------------
HTTPError                                 Traceback (most recent call last)
/tmp/ipykernel_2487/710070080.py in <module>
      1 from urllib.request import urlopen
      2 
----> 3 file = urlopen("https://media.githubusercontent.com/media/xinetzone/ipywidgets-media/main/images/WidgetArch.png")
      4 image = file.read()
      5 widgets.Image(

/usr/lib/python3.8/urllib/request.py in urlopen(url, data, timeout, cafile, capath, cadefault, context)
    220     else:
    221         opener = _opener
--> 222     return opener.open(url, data, timeout)
    223 
    224 def install_opener(opener):

/usr/lib/python3.8/urllib/request.py in open(self, fullurl, data, timeout)
    529         for processor in self.process_response.get(protocol, []):
    530             meth = getattr(processor, meth_name)
--> 531             response = meth(req, response)
    532 
    533         return response

/usr/lib/python3.8/urllib/request.py in http_response(self, request, response)
    638         # request was successfully received, understood, and accepted.
    639         if not (200 <= code < 300):
--> 640             response = self.parent.error(
    641                 'http', request, response, code, msg, hdrs)
    642 

/usr/lib/python3.8/urllib/request.py in error(self, proto, *args)
    567         if http_err:
    568             args = (dict, 'default', 'http_error_default') + orig_args
--> 569             return self._call_chain(*args)
    570 
    571 # XXX probably also want an abstract factory that knows when it makes

/usr/lib/python3.8/urllib/request.py in _call_chain(self, chain, kind, meth_name, *args)
    500         for handler in handlers:
    501             func = getattr(handler, meth_name)
--> 502             result = func(*args)
    503             if result is not None:
    504                 return result

/usr/lib/python3.8/urllib/request.py in http_error_default(self, req, fp, code, msg, hdrs)
    647 class HTTPDefaultErrorHandler(BaseHandler):
    648     def http_error_default(self, req, fp, code, msg, hdrs):
--> 649         raise HTTPError(req.full_url, code, msg, hdrs, fp)
    650 
    651 class HTTPRedirectHandler(BaseHandler):

HTTPError: HTTP Error 404: Not Found

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

Output 小部件可以捕获和显示 stdout、stderr 和 IPython 生成的丰富输出。详细的文档请参见 小部件示例输出。

Play（动画）小部件

Play 小部件通过以一定的速度迭代一个整数序列来执行动画是很有用的。下面的滑块的值链接到 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])

DatePicker

日期选择器小部件可以在 Chrome、Firefox 和 IE Edge 中工作，但目前不能在 Safari 中工作，因为它不支持 HTML 日期输入字段。

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

ColorPicker

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

FileUpload

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

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

upload 小部件公开一个包含所上传文件的 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))

如果上传的文件是一个图像，你可以用一个图像小部件来可视化它：

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

警告

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

Controller

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

widgets.Controller(
    index=0,
)

容器/布局小部件

这些小部件用于容纳其他小部件（称为子部件 children）。每个都有一个 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 Grid 规范在二维网格中布局其子框。下面的示例在 3 列中列出了 8 个项目，以及容纳项目所需的行数。

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

Accordion

name = ['Slider', 'Text']
accordion = widgets.Accordion(children=[widgets.IntSlider(),
                                        widgets.Text()])
[accordion.set_title(k, name) for k, name in enumerate(name)]

accordion

Tabs

在本例中，子选项卡是在创建后设置的。选项卡的标题的设置方式与 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.set_title(i, f"tab_{i}") for i in range(len(children))]
tab

Stacked

Stacked 小部件可以像 Tab 和 Accordion 一样有多个子部件，但每次只显示一个，这取决于 selected_index 的值:

button = widgets.Button(description='Click here')
slider = widgets.IntSlider()
stacked = widgets.Stacked([button, slider])
stacked  # will show only the button

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

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

Accordion, Tab 和 Stacked 使用 selected_index，而不是 value

与前面讨论的其他小部件不同，容器小部件 Accordion 和 Tab 在用户更改选中哪个 accordion 或选项卡时更新它们的 selected_index 属性。

设置 selected_index = None 关闭所有 accordion 或取消选择所有选项卡。

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

tab.selected_index = 3
accordion.selected_index = None

嵌套选项卡和 accordions

选项卡和 accordions 可以嵌套到您想要的深度。如果您有几分钟的时间，可以尝试嵌套一些 accordion，或将 accordion 放在一个标签或一个标签中 accordion。

下面的示例创建了两个选项卡，其中一个选项卡中有一个 cordion 子选项卡：

names = ('An accordion', 'Copy of the accordion')

tab_nest = widgets.Tab()
tab_nest.children = [accordion, accordion]
[tab_nest.set_title(k, name) for k, name in enumerate(names)]
tab_nest

上一页

简单的小部件

下一页

Output 小部件