本章描述如何使用回调函数来制作你的Dash应用程序:当输入组件的属性发生变化时，Dash会自动调用这些Python函数。

1.简单栗子

  1. import dash
  2. import dash_core_components as dcc
  3. import dash_html_components as html
  4. from dash.dependencies import Input, Output
  6. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  8. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  10. app.layout = html.Div([
  11.     html.H6("Change the value in the text box to see callbacks in action!"),
  12.     html.Div(["Input: ",
  13.               dcc.Input(id='my-input', value='initial value', type='text')]),
  14.     html.Br(),
  15.     html.Div(id='my-output'),
  17. ])
  20. @app.callback(
  21.     Output(component_id='my-output', component_property='children'),
  22.     Input(component_id='my-input', component_property='value')
  23. )
  24. def update_output_div(input_value):
  25.     return 'Output: {}'.format(input_value)
  28. if __name__ == '__main__':
  29.     app.run_server(debug=True)

image.png

让我们来分析一下这个例子:

  1. app.callback装饰器通过声明，描述应用程序界面的“输入”与“输出”项；
  2. 我们的应用程序的**Input**和**output**只是特定组件的属性。在本例中，我们**Input**的**value**值是**ID**为 “**my-input**“。我们的**Output**是**ID**为“**my-output**”的组件的“**children**”属性。
  3. 每当输入属性发生变化时，回调装饰器包装的函数将被自动调用。Dash将输入属性的新值作为输入参数提供给函数，Dash使用函数返回的内容更新输出组件的属性。
  4. 不要混淆dash.dependencies.Input和dash_core_components对象。前者只是在这些回调中使用，而后者是一个实际的组件。
  5. The component_id and component_property可以被省略
  6. Dash应用程序启动时，会自动使用输入组件的初始值，调用所有的回调函数，以填充输出组件的初始值。所以，不要在layout中设置 my-div组件的children特性，本例中，如果指定了 html.Div(id='my-div', children='Hello world') 的内容，应用启动时会被覆盖。这种方式类似于Microsoft Excel编程：当单元格的内容发生变化时，依赖于该单元格的所有单元格的内容，都将自动更新。这称为 “反应式编程” (Reactive Programming) 。

@callback的详细用法：

  1. 通过编写这个装饰器，我们告诉Dash在“input”组件(文本框)的值发生变化时为我们调用这个函数，以便更新页面上“output”组件的子组件(HTML div)
  2. 可以使用任何的函数名称跟在@callback之后，但必须在回调函数中使用与定义中相同的名称（就和python语法一样）。约定是用名称来描述回调输出。
  3. 参数是有位置的。第一个（最底下那个）是Input，后面跟任何state，顺序与装饰器中相同。
  4. 当把Dash组件作为@appback的输入或输出时，你必须使用与app.layout中Dash组件相同的id。回调装饰。
  5. callback后面紧跟着函数，不能有空行。
  6. If you’re curious about what the decorator syntax means under the hood, you can read this StackOverflow answer and learn more about decorators by reading PEP 318 — Decorators for Functions and Methods.

2.滑块

  1. import dash
  2. import dash_core_components as dcc
  3. import dash_html_components as html
  4. from dash.dependencies import Input, Output
  5. import plotly.express as px
  7. import pandas as pd
  9. df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminderDataFiveYear.csv')
  11. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  13. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  15. app.layout = html.Div([
  16.     dcc.Graph(id='graph-with-slider'),
  17.     dcc.Slider(
  18.         id='year-slider',
  19.         min=df['year'].min(),
  20.         max=df['year'].max(),
  21.         value=df['year'].min(),
  22.         marks={str(year): str(year) for year in df['year'].unique()},
  23.         step=None
  24.     )
  25. ])
  28. @app.callback(
  29.     Output('graph-with-slider', 'figure'),
  30.     Input('year-slider', 'value'))
  31. def update_figure(selected_year):
  32.     filtered_df = df[df.year == selected_year]
  34.     fig = px.scatter(filtered_df, x="gdpPercap", y="lifeExp",
  35.                      size="pop", color="continent", hover_name="country",
  36.                      log_x=True, size_max=55)
  38.     fig.update_layout(transition_duration=500)
  40.     return fig
  43. if __name__ == '__main__':
  44.     app.run_server(debug=True)

image.png

  1. 本例中，app的输入是 **Slider** 的属性value，app的输出是 **Graph** 的属性figure。当 Slider 的 value 变化时，Dash用新值调用回调函数 update_figure，该函数使用此新值过滤数据框，构造 figure 对象，并将其返回到Dash应用程序中，作为输出；
  2. 使用关键字参数进行组件描述，很重要。通过Dash交互性，使用回调函数，可以动态地更新这些特性。如：更新组件的 **children** 属性从而更新文本内容、更新 **dcc.Graph** 组件的**figure** 属性从而更新数据、更新组件的 **style** 属性从而更新画布样式、更新 **dcc.Dropdown** 组件的 **options** 从而更新下拉菜单；
  3. 将数据加载至内存并进行计算的代价很高，所以尽量在应用的全局范围内下载或查询数据，避免在回调函数里进行这类操作，确保用户访问或与应用交互时，数据(df)已经载入至内存。本例中df获取的数据是全局的，可以被回调函数读取；
  4. 回调函数不会修改原始数据，只是通过**Pandas**的过滤器来筛选数据，并创建DataFrame的副本。这点非常重要：不要在回调函数范围之外更改变量。如果在全局状态下调整回调函数，某一用户的会话就可能影响下一用户的会话，特别是应用部署在多进程或多线程的环境时，这些修改可能会导致跨会话数据分享出现问题；

3.多端输入

在Dash中，任何“Input”都可以有多个“Output”组件。下面是一个简单的例子，它将五个输入(两个Dropdown组件的value属性、两个RadioItems组件和一个Slider组件)绑定到一个输出组件(Graph组件的figure属性)。回调函数的第二个参数，列表中列举了所有的五个输入项dash.dependencies.Input 。

  1. import dash
  2. import dash_core_components as dcc
  3. import dash_html_components as html
  4. from dash.dependencies import Input, Output
  5. import plotly.express as px
  7. import pandas as pd
  9. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  11. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  13. df = pd.read_csv('https://plotly.github.io/datasets/country_indicators.csv')
  15. available_indicators = df['Indicator Name'].unique()
  17. app.layout = html.Div([
  18.     html.Div([
  20.         html.Div([
  21.             dcc.Dropdown(
  22.                 id='xaxis-column',
  23.                 options=[{'label': i, 'value': i} for i in available_indicators],
  24.                 value='Fertility rate, total (births per woman)'
  25.             ),
  26.             dcc.RadioItems(
  27.                 id='xaxis-type',
  28.                 options=[{'label': i, 'value': i} for i in ['Linear', 'Log']],
  29.                 value='Linear',
  30.                 labelStyle={'display': 'inline-block'}
  31.             )
  32.         ],
  33.         style={'width': '48%', 'display': 'inline-block'}),
  35.         html.Div([
  36.             dcc.Dropdown(
  37.                 id='yaxis-column',
  38.                 options=[{'label': i, 'value': i} for i in available_indicators],
  39.                 value='Life expectancy at birth, total (years)'
  40.             ),
  41.             dcc.RadioItems(
  42.                 id='yaxis-type',
  43.                 options=[{'label': i, 'value': i} for i in ['Linear', 'Log']],
  44.                 value='Linear',
  45.                 labelStyle={'display': 'inline-block'}
  46.             )
  47.         ],style={'width': '48%', 'float': 'right', 'display': 'inline-block'})
  48.     ]),
  50.     dcc.Graph(id='indicator-graphic'),
  52.     dcc.Slider(
  53.         id='year--slider',
  54.         min=df['Year'].min(),
  55.         max=df['Year'].max(),
  56.         value=df['Year'].max(),
  57.         marks={str(year): str(year) for year in df['Year'].unique()},
  58.         step=None
  59.     )
  60. ])
  62. @app.callback(
  63.     Output('indicator-graphic', 'figure'),
  64.     Input('xaxis-column', 'value'),
  65.     Input('yaxis-column', 'value'),
  66.     Input('xaxis-type', 'value'),
  67.     Input('yaxis-type', 'value'),
  68.     Input('year--slider', 'value'))
  69. def update_graph(xaxis_column_name, yaxis_column_name,
  70.                  xaxis_type, yaxis_type,
  71.                  year_value):
  72.     dff = df[df['Year'] == year_value]
  74.     fig = px.scatter(x=dff[dff['Indicator Name'] == xaxis_column_name]['Value'],
  75.                      y=dff[dff['Indicator Name'] == yaxis_column_name]['Value'],
  76.                      hover_name=dff[dff['Indicator Name'] == yaxis_column_name]['Country Name'])
  78.     fig.update_layout(margin={'l': 40, 'b': 40, 't': 10, 'r': 0}, hovermode='closest')
  80.     fig.update_xaxes(title=xaxis_column_name,
  81.                      type='linear' if xaxis_type == 'Linear' else 'log')
  83.     fig.update_yaxes(title=yaxis_column_name,
  84.                      type='linear' if yaxis_type == 'Linear' else 'log')
  86.     return fig
  89. if __name__ == '__main__':
  90.     app.run_server(debug=True)

image.png

  1. 在本例中，每当Dropdown、Slider或RadioItems组件的value属性更改时，就会调用update_graph函数。
  2. update_graph函数的输入参数是每个输入属性的新值或当前值，按指定的顺序排列。
  3. 即使一次只更改一个输入(用户在给定时刻只能更改单个下拉列表的值)，Dash也会收集所有指定输入属性的当前状态，并将它们传递到函数中。你的回调函数总是保证会被传递给应用程序的代表状态。


4.多端输出

  1. import dash
  2. import dash_core_components as dcc
  3. import dash_html_components as html
  4. from dash.dependencies import Input, Output
  6. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  8. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  10. app.layout = html.Div([
  11.     dcc.Input(
  12.         id='num-multi',
  13.         type='number',
  14.         value=5
  15.     ),
  16.     html.Table([
  17.         html.Tr([html.Td(['x', html.Sup(2)]), html.Td(id='square')]),
  18.         html.Tr([html.Td(['x', html.Sup(3)]), html.Td(id='cube')]),
  19.         html.Tr([html.Td([2, html.Sup('x')]), html.Td(id='twos')]),
  20.         html.Tr([html.Td([3, html.Sup('x')]), html.Td(id='threes')]),
  21.         html.Tr([html.Td(['x', html.Sup('x')]), html.Td(id='x^x')]),
  22.     ]),
  23. ])
  26. @app.callback(
  27.     Output('square', 'children'),
  28.     Output('cube', 'children'),
  29.     Output('twos', 'children'),
  30.     Output('threes', 'children'),
  31.     Output('x^x', 'children'),
  32.     Input('num-multi', 'value'))
  33. def callback_a(x):
  34.     return x**2, x**3, 2**x, 3**x, x**x
  37. if __name__ == '__main__':
  38.     app.run_server(debug=True)

image.png

  • 一个Dash回调函数只能更新一个输出属性。要想实现多重输出，需要编写多个函数；
  • 具体方法：将需要更新的所有属性，作为列表添加到装饰器中，并从回调中返回多个输出项。如果两个输出依赖于相同的计算密集型中间结果，例如慢速数据库查询，推荐使用该方法；
  • 组合输出并不总是一个好主意：1）如果输出依赖于某些但不是所有相同的输入，则将它们分开可以避免不必要的更新；2）如果它们具有相同的输入，但使用这些输入进行独立计算，则将回调分开，可以实现并行运行它们；

5.Chained Callbacks

一个回调函数的输出是另一个回调函数的输入。

  1. # -*- coding: utf-8 -*-
  2. import dash
  3. import dash_core_components as dcc
  4. import dash_html_components as html
  5. from dash.dependencies import Input, Output
  7. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  9. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  11. all_options = {
  12.     'America': ['New York City', 'San Francisco', 'Cincinnati'],
  13.     'Canada': [u'Montréal', 'Toronto', 'Ottawa']
  14. }
  15. app.layout = html.Div([
  16.     dcc.RadioItems(
  17.         id='countries-radio',
  18.         options=[{'label': k, 'value': k} for k in all_options.keys()],
  19.         value='America'
  20.     ),
  22.     html.Hr(),
  24.     dcc.RadioItems(id='cities-radio'),
  26.     html.Hr(),
  28.     html.Div(id='display-selected-values')
  29. ])
  32. @app.callback(
  33.     Output('cities-radio', 'options'),
  34.     Input('countries-radio', 'value'))
  35. def set_cities_options(selected_country):
  36.     return [{'label': i, 'value': i} for i in all_options[selected_country]]
  39. @app.callback(
  40.     Output('cities-radio', 'value'),
  41.     Input('cities-radio', 'options'))
  42. def set_cities_value(available_options):
  43.     return available_options[0]['value']
  46. @app.callback(
  47.     Output('display-selected-values', 'children'),
  48.     Input('countries-radio', 'value'),
  49.     Input('cities-radio', 'value'))
  50. def set_display_children(selected_country, selected_city):
  51.     return u'{} is a city in {}'.format(
  52.         selected_city, selected_country,
  53.     )
  56. if __name__ == '__main__':
  57.     app.run_server(debug=True)

image.png

  • 链式回调：将输出和输入链接在一起，即一个回调函数的输出是另一个回调函数的输入；
  • 此模式用于创建动态UI，其中一个输入组件更新下一个输入组件的可用选项；
  • 第二个单选按钮RadioItems的选项，基于第一个回调函数传递的单选按钮RadioItems中选择的值；
  • 第二个回调函数设置了options特性改变时的初始值：将自身设置为options数组中的第一个值；
  • 最后的回调函数，显示了每个组件中的可选内容。如果更改了城市单选按钮RadioItems组件的value属性，则Dash将等待，直到value更新状态组件后，再调用最后的回调函数。

6.状态回调

  1. # -*- coding: utf-8 -*-
  2. import dash
  3. import dash_core_components as dcc
  4. import dash_html_components as html
  5. from dash.dependencies import Input, Output, State
  7. external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
  9. app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
  11. app.layout = html.Div([
  12.     dcc.Input(id='input-1-state', type='text', value='Montréal'),
  13.     dcc.Input(id='input-2-state', type='text', value='Canada'),
  14.     html.Button(id='submit-button-state', n_clicks=0, children='Submit'),
  15.     html.Div(id='output-state')
  16. ])
  19. @app.callback(Output('output-state', 'children'),
  20.               Input('submit-button-state', 'n_clicks'),
  21.               State('input-1-state', 'value'),
  22.               State('input-2-state', 'value'))
  23. def update_output(n_clicks, input1, input2):
  24.     return u'''
  25.         The Button has been pressed {} times,
  26.         Input 1 is "{}",
  27.         and Input 2 is "{}"
  28.     '''.format(n_clicks, input1, input2)
  31. if __name__ == '__main__':
  32.     app.run_server(debug=True)

image.png

在这个例子中，更改输入框不会有返回值的改变，只有点击SUBMIT才会更新返回值。
dcc.Input的值依然会传入到回调参数中，但是仅仅是作为State传入，当SUBMIT的控件触发后，才会把State的value传入到函数中。

7.小结

  1. Dash应用是基于下述简单但强大的原则进行构建的：通过响应式与函数式的Python回调函数，自定义声明式的UI；
  2. 声明式组件中的每个元素属性，都可以通过回调函数和属性子集进行更新，比如dcc.Dropdown的value特性，这样用户就可以在交互界面中进行编辑。

注释参考：https://www.jianshu.com/p/cb0dc98e00bc
官方文档：https://dash.plotly.com/basic-callbacks