widget 参数面板 - PythonIDE Docs

用 widget.param 声明用户可在预览面板调节的配置项；返回值直接用于 Widget()、text()、progress()、button() 等。

边界：widget.param 是小组件配置（预览/发布时的参数），不是桌面点击改写的数据。计数、开关持久化用 widget.state，见状态和交互。

#本篇目标

项	说明
何时用	颜色、标题文案、字号、阈值、是否紧凑、主题选项、背景图文件
何时不用	用户点按钮 +1、桌面开关记忆 → 用 `widget.state`
声明时机	构建 UI 之前；在 `w.render()` 之前
改名/改类型后	重新运行并发布；桌面小组件可能需重新添加

#快速开始

预览侧栏会出现多类参数；choice 切换主题时，背景、图标与强调色一并变化（无 widget.state）。

预期效果：小组件预览面板显示与脚本一致的布局与交互。

python

import widget

theme = widget.param.choice("主题", ["海洋", "日落", "森林"], default="海洋")
themes = {
    "海洋": (("#E0F2FE", "#082F49"), "#0EA5E9", "drop.fill"),
    "日落": (("#FFF7ED", "#431407"), "#F97316", "sun.max.fill"),
    "森林": (("#ECFDF5", "#052E16"), "#10B981", "leaf.fill"),
}
bg, accent, icon = themes[str(theme)]
title = widget.param.text("标题", "今日天气")
city = widget.param.text("城市", "上海")
temp = widget.param.number("温度", 24, min=-20, max=45)

w = widget.Widget(background=bg, padding=14)
with w.row(spacing=10):
    w.symbol(icon).color(accent).font_size(24)
    w.text(title, size=16, weight="semibold", color=accent).line_limit(1).min_scale(0.72)
(
    w.value(temp, unit="°")
    .content_transition("numericText")
    .monospaced_digit()
    .line_limit(1)
    .min_scale(0.72)
)
w.text(city, size=12, color="secondary").line_limit(1).min_scale(0.72)
w.render()

#参数 vs 状态

	`widget.param`	`widget.state`
谁改	用户在预览面板 / Studio 调	用户在桌面小组件点按
持久化	写入 Widget 项目配置	写入小组件状态存储
典型用途	主题色、默认标题、目标值	计数器、完成开关、列表勾选
传给 UI	直接作 `color=`、`size=`、`background=`	作 `value` / `state=` + `action`

python

# ✅ 配置：强调色可调
accent = widget.param.color("强调色", "#2563EB")

# ✅ 交互：桌面点击累加
count = widget.state.int("count", 0)
w.button("加 1", action=count.increment(), background=accent)

#API 参考

#速查

API	返回值	预览控件
`param.text(name, default)`	`str`（可绑定）	文本框
`param.color(name, default)`	颜色字符串	取色器
`param.slider(name, default, min=, max=, step=)`	`float`/`int`	滑块
`param.number(name, default, min=, max=)`	数字	数字步进
`param.bool(name, default)`	`bool`	开关
`param.choice(name, options, default=)`	`str`（选项之一）	下拉/分段
`param.file(name, default, extensions=)`	文件路径 `str`	文件选择

name 是参数 ID，同时作为预览面板默认标题；建议用用户能看懂的中文，如 "背景色"、"标题字号"。

#`text`

python

title = widget.param.text("标题", "每日记录")
subtitle = widget.param.text("副标题", "", placeholder="可选")
hint = widget.param.text(
    "备注",
    "",
    title="页脚说明",
    description="显示在卡片底部，可为空",
    group="高级",
    hidden=False,
)

用于标题、备注、显示用文案默认值。绑定后的字符串传给 w.text(title, ...) 时，用户改参数会反映到预览。

可选关键字（均在 name、default 之后）：

参数	作用
`placeholder`	预览侧栏输入框占位提示
`title`	覆盖侧栏显示标题（默认用 `name`）
`description`	侧栏帮助说明
`group`	参数分组标题
`order`	组内排序（数字越小越靠前）
`hidden`	`True` 时侧栏隐藏（脚本仍可读取）
`role` / `live`	高级用途；一般示例可省略

#`color`

python

paper = widget.param.color("背景色", "#FBFAF5")
ink = widget.param.color("文字色", "#242326")
accent = widget.param.color("强调色", "#2563EB")

默认值为 #RRGGBB 或语义色名字符串。
可传给 Widget(background=paper)、w.text(..., color=ink)、w.progress(..., color=accent)、w.button(..., background=accent)。
toggle 用 color=，没有 tint= 参数。

#`slider` / `number`

python

title_size = widget.param.slider("标题字号", 18, min=12, max=28, step=1)
target = widget.param.number("目标次数", 8, min=1, max=20)

slider：连续调节（字号、透明度、圆角等）。
number：离散数值（目标、阈值、上限）。
传给 size=、height= 等时建议 int(...)，尤其在 family_value 分支里。

#`bool`

python

compact = widget.param.bool("紧凑模式", False)
show_footer = widget.param.bool("显示页脚", True)

返回普通 bool，用于 Python 分支，例如：

python

padding = 10 if compact else 16
if show_footer:
    w.text("页脚", size=11, color="secondary")

不要与 widget.state.bool（桌面交互）混淆。

#`choice`

python

mode = widget.param.choice("风格", ["健康", "专注", "代码"], default="专注")

options 至少一项。
default 必须是 options 中的某一项（或省略则用第一项）。
返回值是选项字符串，可拼进 w.text("风格：" + mode)。

#`file`

python

logo = widget.param.file("角标图", "", extensions=["png", "jpg", "svg"])
bg = widget.param.file("背景图", "assets/bg.png", extensions=["png", "jpg"])

默认路径相对于 widget 脚本目录或项目 assets/。
选中文件后路径注入参数；配合 w.image(logo, ...) 或背景资源 API（见资源与外观）。
文档预览里文件选择仅演示，不能当生产路径依赖。

#与布局、尺寸配合

参数常和 widget.context、widget.family_value 一起用，避免 small 字号过大：

python

size = widget.param.slider("标题字号", 20, min=14, max=28, step=1)
display_size = widget.family_value(int(size), small=14, medium=int(size), large=min(28, int(size) + 2))
w.text(title, size=display_size).line_limit(1).min_scale(0.65)

详见布局与尺寸。

#预览与发布行为

阶段	行为
文档 / Studio 预览	侧栏改参数 → 重新构建当前 family 预览
发布到桌面	使用发布时刻的项目参数快照
改参数名	旧桌面实例可能仍绑定旧 key → 重新发布，必要时删组件重装
改默认值	新发布生效；已添加的桌面组件不自动改配置

Studio 中 color / slider / number / bool 等常带 live 预览：拖动滑块即可看效果，无需改代码。

#常见错误

错误写法	后果	修正
用 `widget.state` 当配色	桌面乱改主题色	配色用 `widget.param.color`
`param` 写在 `render()` 之后	面板无参数	全部提前到 UI 构建前
`choice` 的 default 不在 options	构建报错	default 必须是 options 之一
`slider` 传入字符串默认值	类型异常	用数字 `18`，不是 `"18"`
参数名随代码重构乱改	桌面配置丢失	对用户可见名保持稳定，或接受重装
`toggle(..., tint=)`	`TypeError`	用 `color=`

#失败路径

现象	处理
预览侧栏没有参数	确认 `widget.param.*` 且在 `w.render()` 前
改参数预览不变	看控制台构建日志；color/slider 类应自动 live
桌面仍是旧配色	重新运行发布；不是 param 没生效而是未重发
文件参数路径无效	文件放进脚本同目录或 `assets/`；检查 `extensions`
参数与状态搞混	对照上文表格；交互见状态和交互

#相关文档

文档	用途
widget 概览	总览与示例
从脚本到桌面	发布流程
状态和交互	`widget.state`、按钮、开关
资源与外观	图片、渐变、文件资源
布局与尺寸	`family_value`、防裁切
API 参考	`widget.param` 完整签名

#本篇目标

#快速开始

#参数 vs 状态

#API 参考

#速查

#text

#color

#slider / number

#bool

#choice

#file

#与布局、尺寸配合

#预览与发布行为

#常见错误

#失败路径

#相关文档

相关文档

#`text`

#`color`

#`slider` / `number`

#`bool`

#`choice`

#`file`