Streamlit 學習筆記 : 使用者輸入元件 (一) 按鈕

本篇旨在記錄 Streamlit 使用者輸入元件中的按鈕元件. 

本系列所有測試文章參考 :

# Streamlit 學習筆記索引

使用者輸入元件又稱為 Widgets, 這是 Streamlit 的核心部分, 也是 Streamlit 應用程式 UI 的構建方塊, 也是使用者與應用程式互動的介面. Streamlit 提供許多函式來建立這些 Widgets, 摘要說明如下表 :

輸入元件函式	說明
st.button(label)	建立一個按鈕，點擊後回傳 True
st.download_button(label, data)	建立可供下載的按鈕
st.checkbox(label)	建立核取方塊，回傳布林值
st.radio(label, options)	建立單選按鈕，選一個選項
st.selectbox(label, options)	建立下拉式選單
st.multiselect(label, options)	建立多選選單，回傳選擇的列表
st.slider(label, min_value, max_value)	建立滑桿，可拖曳選數值（整數或浮點數）
st.select_slider(label, options)	類似 slider，但使用自訂選項（可為字串）
st.text_input(label)	單行文字輸入框，回傳字串
st.text_area(label)	多行文字輸入框
st.number_input(label)	數值輸入框，可選範圍與步進
st.date_input(label)	日期選擇器，回傳 datetime.date
st.time_input(label)	時間選擇器，回傳 datetime.time
st.file_uploader(label)	上傳檔案（可設檔案類型、是否允許多個）
st.color_picker(label)	顏色選擇器，回傳 HEX 色碼
st.camera_input(label)	開啟攝影機拍照（需用戶授權）
st.toggle(label)	建立開關按鈕（布林值）
st.form(key)	建立表單容器以群組輸入元件
st.form_submit_button(label)	表單送出按鈕，與 st.form() 配合使用

呼叫這些函式會在網頁上輸出一個 Widgets 元件. 

呼叫 st.button() 會建立一個按鈕元件, 當按下按鈕時傳回 True, 否則傳回 False, 其參數結構如下 : 

st.button(label, key=None, help=None, on_click=None, args=None, kwargs=None, type="secondary", disabled=False, use_container_width=False)

參數說明如下表 :

st.button() 之參數	說明
label	按鈕顯示的文字內容（必填）。
key	按鈕的唯一識別字串，用於避免重複。
help	滑鼠懸停時顯示的說明文字。
on_click	按鈕被點擊時要執行的回呼函式。
args	傳給 on_click 函式的位置引數（tuple）。
kwargs	傳給 on_click 函式的關鍵字引數（dict）。
type	按鈕類型，可為 "primary" 或 "secondary"（預設）。
disabled	是否停用此按鈕，預設為 False。
use_container_width	是否讓按鈕寬度填滿整個容器，預設為 False。

注意, 位置引數 args 為 tuple, 因此若只有一個引數後面必須有一個逗點, 例如 (name,). 

參數 type 預設為 secondary 的白底黑字按鈕, 若傳入 type='primary' 則會變成紅底白字的按鈕, 用來強調其特殊性, 例如 : 

測試 1 : 參數 type=primary 與 secondary 效果 [看原始碼] 

# st-button-test-1.py

import streamlit as st

st.subheader('參數 type 測試')

btn1=st.button('type=primary 的按鈕', type='primary')

if btn1:  # 按下傳回 True

    st.write('你按了 type=primary 的按鈕')

btn2=st.button('type=secondary 的按鈕')

if btn2:  # 按下傳回 True

    st.write('你按了 type=secondary 的按鈕') 

此例建立了兩個按鈕元件, btn1 被設為 primary 按鈕; btn2 則為一般的 secondary 按鈕, 當任一按鈕被按時 st.button() 會傳回 True, 從而在其下方印出被按下的訊息, 結果如下 : 

左邊是初始化後尚未按任一按鈕時, 中間是按下 primary 按鈕; 右邊是按下 secondary 按鈕, 當按下按鈕時網頁內容會刷新, 這時只有被按下的那個按鈕傳回 True 顯示文字於其下方, 另一個音傳回 False 而不會顯示下方文字. 

下面範例測試 on_click 與 args 參數用法 :

測試 2 : 參數 on_click 與 args 用法 [看原始碼] 

# st-button-test-2.py

import streamlit as st

def say_hello(name):

    st.write(f'Hello! {name}')

name='Tony'

st.button('打招呼', on_click=say_hello, args=(name,))

此例參數 on_click=say_hello 表示按下按鈕時呼叫 say_hello() 函式, args=(name,) 表示要攜帶一個參數 name 給該函式. 注意, 不可以用 args=name 傳參數, 因 args 型態為 tuple, 單一元素的 tuple 必須以逗號結尾即 (name,), 結果如下 : 

按下按鈕會在上方顯示訊息. 

下面範例測試 on_click 與 kwargs 參數用法 :

測試 3 : 參數 on_click 與 kwargs 用法 [看原始碼] 

# st-button-test-3.py

import streamlit as st

def say_hello(name, greeting="Hello"):

    st.write(f'{greeting}, {name}!')

    

kwargs={'name': 'Tony', 'greeting': 'Hi'}

st.button("打招呼", on_click=say_hello, kwargs=kwargs)

此例在按下按鈕時會將關鍵字參數以字典傳給 on_click 指定之函式, 結果如下 :