+
这页是公开 Widget() API 的签名索引。先用 API 地图 按任务选择能力，再回到这里核对函数名、参数名和返回句柄。
+
# 怎么查
+
选能力：先看「常用组合」。 查签名：看「完整公开 API 索引」。 学写法：先看 widget 或 从脚本到桌面 ，再进入布局、参数、交互、时间线或外观指南。 排故障：先看 排错 ，再回到这里核对签名。
+
# 常用组合
+
+
# 行为契约
+
+
# 公开 API 速查
+
+
# 完整公开 API 索引
+
+
widget.CIRCULAR：Family: circularwidget.INLINE：Family: inlinewidget.LARGE：Family: largewidget.MEDIUM：Family: mediumwidget.RECTANGULAR：Family: rectangularwidget.SMALL：Family: small
+
# 运行值
+
widget.action：动作助手，用于创建受控刷新、状态和打开链接动作。widget.color：颜色助手，用于固定色、浅深色和系统角色色。widget.context：当前 family、尺寸和内容区域信息。widget.entry：当前 timeline entry 的字段读取入口。widget.family：当前小组件 family 名称。widget.param：预览面板参数声明入口。widget.state：桌面交互状态声明入口。widget.storage：小组件脚本可用的轻量存储入口。
+
+
+
+
+ text
+ 已复制
+
+ widget.cache_json(
+ url: str,
+ *,
+ ttl: Optional[float] = 3600,
+ default: Any = None,
+ params: Optional[Dict[str, Any]] = None,
+ headers: Optional[Dict[str, str]] = None,
+ key: Optional[str] = None,
+ timeout: float = 8,
+) -> Any
+
+
+
+ text
+ 已复制
+
+ widget.family_value(default: Any = None, **values: Any) -> Any
+
# widget.history
+
+
+ text
+ 已复制
+
+ widget.history(
+ key: str,
+ value: Any = None,
+ limit: int = 7,
+ *,
+ bucket: Optional[str] = "day",
+ default: Any = None,
+) -> Any
+
+
+
+ text
+ 已复制
+
+ widget.save_image(source: Union[str, bytes], name: str, *, variant: Optional[str] = None) -> str
+
+
# w.background
+
+
+ text
+ 已复制
+
+ w.background(value: WidgetBackground) -> "Widget"
+
# w.background_image
+
+
+ text
+ 已复制
+
+ w.background_image(
+ asset: Optional[ImageLike] = None,
+ content_mode: str = "fill",
+ dim: Optional[Union[bool, float]] = None,
+ scrim: Optional[Union[bool, str]] = None,
+ scrim_opacity: Optional[float] = None,
+ focal: str = "center",
+ overlay_color: ColorLike = "#000000",
+ *,
+ light: Optional[str] = None,
+ dark: Optional[str] = None,
+) -> "Widget"
+
# w.badge
+
+
+ text
+ 已复制
+
+ w.badge(
+ text: Union[str, int, float],
+ icon: Optional[str] = None,
+ tone: str = "accent",
+ style: str = "plain",
+) -> WidgetNode
+
# w.bar_chart
+
+
+ text
+ 已复制
+
+ w.bar_chart(
+ values: List[Union[int, float]],
+ color: Optional[ColorLike] = None,
+ height: Optional[float] = None,
+ min_value: Optional[float] = None,
+ max_value: Optional[float] = None,
+ spacing: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ track_color: Optional[ColorLike] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ segment_colors: Optional[List[ColorLike]] = None,
+ baseline: Optional[float] = None,
+ threshold: Optional[float] = None,
+ labels: Optional[Union[List[Any], Dict[str, Any]]] = None,
+ label_color: Optional[ColorLike] = None,
+) -> WidgetNode
+
# w.body
+
+
+ text
+ 已复制
+
+ w.body(content: Union[str, int, float]) -> WidgetNode
+
+
+
+ text
+ 已复制
+
+ w.button(
+ title: Optional[str] = None,
+ action: Optional[Union[str, WidgetAction]] = None,
+ url: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+ background: Optional[WidgetBackground] = None,
+ size: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ *,
+ style: Optional[str] = None,
+ layout: Optional[str] = None,
+ press: Optional[Dict[str, Any]] = None,
+ normal: Optional[Dict[str, Any]] = None,
+) -> WidgetNode
+
# w.canvas
+
+
+ text
+ 已复制
+
+ w.canvas(
+ height: Optional[float] = None,
+ coordinate_space: str = "relative",
+ align: str = "center",
+ background: Optional[WidgetBackground] = None,
+ padding: Optional[Union[int, float]] = None,
+ corner_radius: Optional[float] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+ opacity: Optional[float] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ fill: bool = False,
+) -> Canvas
+
# w.caption
+
+
+ text
+ 已复制
+
+ w.caption(content: Union[str, int, float]) -> WidgetNode
+
# w.change
+
+
+ text
+ 已复制
+
+ w.change(
+ primary: Union[str, int, float],
+ secondary: Optional[Union[str, int, float]] = None,
+ direction: Optional[str] = None,
+) -> WidgetNode
+
# w.circle
+
+
+ text
+ 已复制
+
+ w.circle(
+ color: Optional[ColorLike] = None,
+ size: Optional[float] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+) -> WidgetNode
+
# w.column
+
+
+ text
+ 已复制
+
+ w.column(
+ spacing: Optional[Union[int, float]] = None,
+ align: Optional[str] = None,
+) -> WidgetContainer
+
# w.container_background
+
+
+ text
+ 已复制
+
+ w.container_background(
+ value: Optional[WidgetBackground] = None,
+ *,
+ removable: Optional[bool] = None,
+) -> "Widget"
+
# w.content_margins
+
+
+ text
+ 已复制
+
+ w.content_margins(
+ enabled: bool = True,
+ padding: Optional[Union[int, float, Sequence[float], Dict[str, float]]] = None,
+) -> "Widget"
+
# w.context
+
+
+ text
+ 已复制
+
+ w.context -> WidgetContext
+
# w.countdown
+
+
+ text
+ 已复制
+
+ w.countdown(
+ title: Optional[Union[str, int, float]] = "Countdown",
+ target: Optional[Union[datetime, str]] = None,
+ subtitle: Optional[Union[str, int, float]] = None,
+ icon: Optional[str] = None,
+ tone: Optional[str] = None,
+ accent: Optional[ColorLike] = None,
+) -> WidgetBlock
+
# w.date
+
+
+ text
+ 已复制
+
+ w.date(target: Optional[Union[datetime, str]] = None, style: str = "date") -> WidgetNode
+
# w.divider
+
+
+ text
+ 已复制
+
+ w.divider(color: Optional[ColorLike] = None, opacity: Optional[float] = None, ) -> WidgetNode
+
# w.dynamic_date
+
+
+ text
+ 已复制
+
+ w.dynamic_date(target: Optional[Union[datetime, str]] = None, style: str = "date") -> WidgetNode
+
# w.flip
+
+
+ text
+ 已复制
+
+ w.flip(
+ value: Any,
+ previous: Optional[Any] = None,
+ *,
+ direction: str = "up",
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ size: Optional[float] = None,
+ weight: str = "bold",
+ color: Optional[ColorLike] = None,
+ background: Optional[WidgetBackground] = None,
+ corner_radius: Optional[float] = None,
+ duration: float = 0.55,
+ delta: Optional[float] = None,
+ perspective: float = 0.62,
+ shadow_opacity: float = 0.18,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ design: Optional[str] = "monospaced",
+) -> WidgetNode
+
# w.grid
+
+
+ text
+ 已复制
+
+ w.grid(
+ columns: int = 2,
+ spacing: Optional[Union[int, float]] = None,
+ row_spacing: Optional[Union[int, float]] = None,
+ column_spacing: Optional[Union[int, float]] = None,
+ align: Optional[str] = None,
+ padding: Optional[Union[int, float]] = None,
+ background: Optional[WidgetBackground] = None,
+ opacity: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+ url: Optional[str] = None,
+ shadow_color: Optional[ColorLike] = None,
+ shadow_radius: Optional[float] = None,
+ shadow_x: float = 0,
+ shadow_y: float = 2,
+ rows: Optional[int] = None,
+ equal: bool = False,
+ fill: bool = False,
+) -> WidgetContainer
+
# w.image
+
+
+ text
+ 已复制
+
+ w.image(
+ name: Optional[ImageLike] = None,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ content_mode: Optional[str] = None,
+ *,
+ light: Optional[str] = None,
+ dark: Optional[str] = None,
+ rendering_mode: Optional[str] = None,
+) -> WidgetNode
+
# w.layer
+
+
+ text
+ 已复制
+
+ w.layer(
+ align: str = "center",
+ padding: Optional[Union[int, float]] = None,
+ background: Optional[WidgetBackground] = None,
+ corner_radius: Optional[float] = None,
+) -> WidgetContainer
+
# w.line_chart
+
+
+ text
+ 已复制
+
+ w.line_chart(
+ values: List[Union[int, float]],
+ color: Optional[ColorLike] = None,
+ height: Optional[float] = None,
+ min_value: Optional[float] = None,
+ max_value: Optional[float] = None,
+ fill: bool = True,
+ show_points: bool = True,
+ line_width: Optional[float] = None,
+ track_color: Optional[ColorLike] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ segment_colors: Optional[List[ColorLike]] = None,
+ baseline: Optional[float] = None,
+ threshold: Optional[float] = None,
+ labels: Optional[Union[List[Any], Dict[str, Any]]] = None,
+ label_color: Optional[ColorLike] = None,
+) -> WidgetNode
+
# w.link
+
+
+ text
+ 已复制
+
+ w.link(
+ title: str,
+ url: str,
+ icon: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+) -> Union[WidgetNode, WidgetContainer]
+
# w.list
+
+
+ text
+ 已复制
+
+ w.list(
+ items: List[Any],
+ title: Optional[Union[str, int, float]] = None,
+ limit: Optional[int] = None,
+ empty_text: Optional[Union[str, int, float]] = None,
+ dividers: bool = False,
+) -> WidgetContainer
+
# w.path
+
+
+ text
+ 已复制
+
+ w.path(
+ points: List[PathPoint],
+ stroke: Optional[ColorLike] = None,
+ fill: Optional[ColorLike] = None,
+ line_width: Optional[Union[float, str]] = None,
+ closed: bool = False,
+ height: Optional[float] = None,
+ coordinate_space: str = "relative",
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ line_cap: Optional[str] = None,
+ line_join: Optional[str] = None,
+ dash: Optional[Sequence[float]] = None,
+ miter_limit: Optional[float] = None,
+) -> WidgetNode
+
# w.progress
+
+
+ text
+ 已复制
+
+ w.progress(
+ value: Union[int, float],
+ total: float = 1.0,
+ color: Optional[ColorLike] = None,
+ height: Optional[float] = None,
+ track_color: Optional[ColorLike] = None,
+ *,
+ title: Optional[str] = None,
+ subtitle: Optional[str] = None,
+ unit: Optional[str] = None,
+ icon: Optional[str] = None,
+ tone: Optional[str] = None,
+ accent: Optional[str] = None,
+ style: Optional[str] = None,
+) -> WidgetNode
+
# w.rect
+
+
+ text
+ 已复制
+
+ w.rect(
+ color: Optional[ColorLike] = None,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+) -> WidgetNode
+
# w.region
+
+
+ text
+ 已复制
+
+ w.region(
+ slot: str = "center",
+ spacing: Optional[Union[int, float]] = None,
+ align: Optional[str] = None,
+) -> WidgetContainer
+
# w.relative_time
+
+
+ text
+ 已复制
+
+ w.relative_time(target: Optional[Union[datetime, str]] = None) -> WidgetNode
+
# w.render
+
+
+ text
+ 已复制
+
+ w.render(url: Optional[str] = None) -> None
+
# w.rich_text
+
+
+ text
+ 已复制
+
+ w.rich_text(
+ parts: List[RichTextPart],
+ size: Optional[float] = None,
+ weight: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+ align: Optional[str] = None,
+ max_lines: Optional[int] = None,
+ design: Optional[str] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ minimum_scale_factor: Optional[float] = None,
+ font_width: Optional[str] = None,
+) -> WidgetNode
+
# w.ring_chart
+
+
+ text
+ 已复制
+
+ w.ring_chart(
+ value: Union[int, float],
+ total: float = 1.0,
+ label: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+ track_color: Optional[ColorLike] = None,
+ size: Optional[float] = None,
+ line_width: Optional[float] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+) -> WidgetNode
+
# w.row
+
+
+ text
+ 已复制
+
+ w.row(
+ spacing: Optional[Union[int, float]] = None,
+ align: Optional[str] = None,
+) -> WidgetContainer
+
# w.section
+
+
+ text
+ 已复制
+
+ w.section(
+ title: Optional[Union[str, int, float]] = None,
+ spacing: Optional[Union[int, float]] = None,
+ subtitle: Optional[Union[str, int, float]] = None,
+ style: Optional[str] = None,
+) -> WidgetContainer
+
# w.shape
+
+
+ text
+ 已复制
+
+ w.shape(
+ kind: str = "rectangle",
+ color: Optional[ColorLike] = None,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ size: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+ shadow_color: Optional[ColorLike] = None,
+ shadow_radius: Optional[float] = None,
+ shadow_x: float = 0,
+ shadow_y: float = 2,
+ stroke_color: Optional[ColorLike] = None,
+ stroke_width: Optional[Union[float, str]] = None,
+ dash: Optional[Sequence[float]] = None,
+ line_cap: Optional[str] = None,
+ line_join: Optional[str] = None,
+ miter_limit: Optional[float] = None,
+ top_leading_radius: Optional[float] = None,
+ top_trailing_radius: Optional[float] = None,
+ bottom_leading_radius: Optional[float] = None,
+ bottom_trailing_radius: Optional[float] = None,
+) -> WidgetNode
+
# w.spacer
+
+
+ text
+ 已复制
+
+ w.spacer(length: Optional[Union[int, float]] = None) -> WidgetNode
+
# w.surface
+
+
+ text
+ 已复制
+
+ w.surface(
+ role: str = "panel",
+ spacing: Optional[Union[int, float]] = None,
+ align: Optional[str] = None,
+ padding: Optional[Union[int, float]] = None,
+ background: Optional[WidgetBackground] = None,
+ corner_radius: Optional[float] = None,
+ border_color: Optional[ColorLike] = None,
+ border_width: Optional[float] = None,
+ shadow_color: Optional[ColorLike] = None,
+ shadow_radius: Optional[float] = None,
+) -> WidgetContainer
+
# w.svg
+
+
+ text
+ 已复制
+
+ w.svg(
+ name: Optional[ImageLike] = None,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ color: Optional[ColorLike] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ content_mode: str = "fit",
+ *,
+ light: Optional[str] = None,
+ dark: Optional[str] = None,
+) -> WidgetNode
+
# w.symbol
+
+
+ text
+ 已复制
+
+ w.symbol(
+ name: str,
+ rendering: Optional[str] = None,
+ palette: Optional[Sequence[ColorLike]] = None,
+ variant: Optional[str] = None,
+ scale: Optional[str] = None,
+) -> WidgetNode
+
# w.table
+
+
+ text
+ 已复制
+
+ w.table(
+ rows: int,
+ columns: int,
+ *,
+ line_color: Optional[ColorLike] = None,
+ line_width: Union[float, str] = "hairline",
+ line_cap: str = "butt",
+ line_join: str = "miter",
+ dash: Optional[Sequence[float]] = None,
+ miter_limit: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ background: Optional[WidgetBackground] = None,
+ opacity: Optional[float] = None,
+ corner_radius: Optional[float] = None,
+ border: bool = True,
+ fill: bool = True,
+ align: str = "center",
+) -> Table
+
# w.text
+
+
+ text
+ 已复制
+
+ w.text(
+ content: Union[str, int, float],
+ size: Optional[float] = None,
+ weight: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+ align: Optional[str] = None,
+ max_lines: Optional[int] = None,
+ design: Optional[str] = None,
+ opacity: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ frame: Optional[Dict[str, Any]] = None,
+ minimum_scale_factor: Optional[float] = None,
+ font_width: Optional[str] = None,
+) -> WidgetNode
+
# w.time
+
+
+ text
+ 已复制
+
+ w.time(target: Optional[Union[datetime, str]] = None) -> WidgetNode
+
# w.timeline
+
+
+ text
+ 已复制
+
+ w.timeline(
+ entries: Optional[List[Dict[str, Any]]] = None,
+ *,
+ update: str = "after",
+ after: Any = None,
+ interval: Optional[float] = None,
+) -> "Widget"
+
# w.timer_text
+
+
+ text
+ 已复制
+
+ w.timer_text(target: Optional[Union[datetime, str]] = None) -> WidgetNode
+
# w.title
+
+
+ text
+ 已复制
+
+ w.title(content: Union[str, int, float]) -> WidgetNode
+
# w.toggle
+
+
+ text
+ 已复制
+
+ w.toggle(
+ title: Optional[str] = None,
+ is_on: Union[bool, str] = False,
+ action: Optional[Union[str, WidgetAction]] = None,
+ url: Optional[str] = None,
+ color: Optional[ColorLike] = None,
+ background: Optional[WidgetBackground] = None,
+ size: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+ *,
+ value: Optional[Union[bool, str]] = None,
+ state: Optional[State[bool]] = None,
+ style: Optional[str] = None,
+ layout: Optional[str] = None,
+ press: Optional[Dict[str, Any]] = None,
+ normal: Optional[Dict[str, Any]] = None,
+) -> WidgetNode
+
# w.transparent_background
+
+
+ text
+ 已复制
+
+ w.transparent_background(enabled: bool = True) -> "Widget"
+
# w.unless
+
+
+ text
+ 已复制
+
+ w.unless(*families: str, layout: str = "layer") -> WidgetContainer
+
# w.validate
+
+
+ text
+ 已复制
+
+ w.validate(family: Optional[str] = None) -> Dict[str, Any]
+
# w.value
+
+
+ text
+ 已复制
+
+ w.value(
+ value: Union[str, int, float, State[int], State[float], State[str], State[str]],
+ unit: Optional[str] = None,
+ subtitle: Optional[str] = None,
+ format: Optional[str] = None,
+) -> WidgetNode
+
# w.when
+
+
+ text
+ 已复制
+
+ w.when(*families: str, layout: str = "layer") -> WidgetContainer
+
# 修饰符
+
# .accentable
+
+
+ text
+ 已复制
+
+ .accentable(enabled: bool = True) -> Self
+
# .accessibility
+
+
+ text
+ 已复制
+
+ .accessibility(
+ label: Optional[str] = None,
+ value: Optional[str] = None,
+ hint: Optional[str] = None,
+ hidden: Optional[bool] = None,
+) -> Self
+
# .align
+
+
+ text
+ 已复制
+
+ .align(value: str) -> Self
+
# .animation
+
+
+ text
+ 已复制
+
+ .animation(
+ value: str = "default",
+ *,
+ duration: Optional[float] = None,
+ value_by: Optional[Any] = None,
+) -> Self
+
# .background
+
+
+ text
+ 已复制
+
+ .background(value: WidgetBackground) -> Self
+
# .bar_spacing
+
+
+ text
+ 已复制
+
+ .bar_spacing(value: float) -> Self
+
# .baseline
+
+
+ text
+ 已复制
+
+ .baseline(value: float = 0, color: Optional[ColorLike] = None) -> Self
+
+
+
+ text
+ 已复制
+
+ .button_style(value: str = "plain") -> Self
+
# .capsule
+
+
+ text
+ 已复制
+
+ .capsule(tone: Optional[str] = None, padding: Optional[Union[int, float]] = None, ) -> Self
+
# .clip
+
+
+ text
+ 已复制
+
+ .clip(kind: str = "roundedRectangle", corner_radius: Optional[float] = None) -> Self
+
# .clip_shape
+
+
+ text
+ 已复制
+
+ .clip_shape(kind: str = "roundedRectangle", corner_radius: Optional[float] = None) -> Self
+
# .color
+
+
+ text
+ 已复制
+
+ .color(value: ColorLike) -> Self
+
# .compressed
+
+
+ text
+ 已复制
+
+ .compressed(enabled: bool = True) -> Self
+
# .content_transition
+
+
+ text
+ 已复制
+
+ .content_transition(value: str = "opacity") -> Self
+
# .control_layout
+
+
+ text
+ 已复制
+
+ .control_layout(value: str = "overlay") -> Self
+
# .control_style
+
+
+ text
+ 已复制
+
+ .control_style(value: str = "plain") -> Self
+
# .corner_radius
+
+
+ text
+ 已复制
+
+ .corner_radius(value: float) -> Self
+
# .fill
+
+
+ text
+ 已复制
+
+ .fill(enabled: bool = True) -> Self
+
# .fixed_size
+
+
+ text
+ 已复制
+
+ .fixed_size(horizontal: bool = True, vertical: bool = True) -> Self
+
# .font
+
+
+ text
+ 已复制
+
+ .font(
+ value: Optional[Union[str, int, float, Dict[str, Any]]] = None,
+ *,
+ size: Optional[Union[float, Dict[str, Any]]] = None,
+ weight: Optional[str] = None,
+ **size_values: Any,
+) -> Self
+
# .font_size
+
+
+ text
+ 已复制
+
+ .font_size(size: float) -> Self
+
# .font_style
+
+
+ text
+ 已复制
+
+ .font_style(style: str) -> Self
+
# .font_weight
+
+
+ text
+ 已复制
+
+ .font_weight(weight: str) -> Self
+
# .font_width
+
+
+ text
+ 已复制
+
+ .font_width(width: str) -> Self
+
# .frame
+
+
+ text
+ 已复制
+
+ .frame(
+ x: float = 0,
+ y: float = 0,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+ *,
+ inset: Union[int, float] = 0,
+) -> _CanvasFrame
+
# .grid
+
+
+ text
+ 已复制
+
+ .grid(
+ rows: int,
+ columns: int,
+ *,
+ padding: Union[int, float] = 0,
+ gap: Union[int, float] = 0,
+ row_gap: Optional[float] = None,
+ column_gap: Optional[float] = None,
+ line_width: Optional[float] = None,
+ border: bool = False,
+ x: float = 0,
+ y: float = 0,
+ width: Optional[float] = None,
+ height: Optional[float] = None,
+) -> CanvasGrid
+
# .guide_lines
+
+
+ text
+ 已复制
+
+ .guide_lines(count: Union[bool, int] = True, color: Optional[ColorLike] = None) -> Self
+
# .height
+
+
+ text
+ 已复制
+
+ .height(value: Optional[Union[float, Dict[str, Any]]] = None, **values: Any) -> Self
+
# .hide
+
+
+ text
+ 已复制
+
+ .hide(*families: str) -> Self
+
# .id
+
+
+ text
+ 已复制
+
+ .id(value: Any) -> Self
+
# .importance
+
+
+ text
+ 已复制
+
+ .importance(value: str = "primary") -> Self
+
# .intent
+
+
+ text
+ 已复制
+
+ .intent(action: Union[str, WidgetAction]) -> Self
+
# .labels
+
+
+ text
+ 已复制
+
+ .labels(
+ start: Optional[Union[str, int, float]] = None,
+ end: Optional[Union[str, int, float]] = None,
+ color: Optional[ColorLike] = None,
+) -> Self
+
# .layout_priority
+
+
+ text
+ 已复制
+
+ .layout_priority(value: float = 1) -> Self
+
# .line_limit
+
+
+ text
+ 已复制
+
+ .line_limit(value: int) -> Self
+
# .line_width
+
+
+ text
+ 已复制
+
+ .line_width(value: Union[float, str]) -> Self
+
# .link
+
+
+ text
+ 已复制
+
+ .link(url: str) -> Self
+
# .mask
+
+
+ text
+ 已复制
+
+ .mask(kind: str = "roundedRectangle", corner_radius: Optional[float] = None) -> Self
+
# .mask_view
+
+
+ text
+ 已复制
+
+ .mask_view(align: str = "center") -> WidgetContainer
+
# .min_scale
+
+
+ text
+ 已复制
+
+ .min_scale(value: float) -> Self
+
# .monospaced
+
+
+ text
+ 已复制
+
+ .monospaced(enabled: bool = True) -> Self
+
# .monospaced_digit
+
+
+ text
+ 已复制
+
+ .monospaced_digit(enabled: bool = True) -> Self
+
# .normal
+
+
+ text
+ 已复制
+
+ .normal(**style: Any) -> Self
+
# .offset
+
+
+ text
+ 已复制
+
+ .offset(x: float = 0, y: float = 0) -> Self
+
# .opacity
+
+
+ text
+ 已复制
+
+ .opacity(value: float) -> Self
+
# .overflow
+
+
+ text
+ 已复制
+
+ .overflow(
+ action: Optional[str] = None,
+ *,
+ importance: Optional[str] = None,
+ preserve: Optional[bool] = None,
+) -> Self
+
# .overlay
+
+
+ text
+ 已复制
+
+ .overlay(color: ColorLike = "#000000", opacity: float = 0.18) -> Self
+
# .overlay_view
+
+
+ text
+ 已复制
+
+ .overlay_view(align: str = "center") -> WidgetContainer
+
# .padding
+
+
+ text
+ 已复制
+
+ .padding(
+ value: Optional[Union[int, float]] = None,
+ *,
+ horizontal: Optional[float] = None,
+ vertical: Optional[float] = None,
+ top: Optional[float] = None,
+ leading: Optional[float] = None,
+ bottom: Optional[float] = None,
+ trailing: Optional[float] = None,
+) -> Self
+
# .palette
+
+
+ text
+ 已复制
+
+ .palette(colors: Sequence[ColorLike]) -> Self
+
# .pixel_perfect_center
+
+
+ text
+ 已复制
+
+ .pixel_perfect_center(enabled: bool = True) -> Self
+
# .place
+
+
+ text
+ 已复制
+
+ .place(x: Optional[float] = None, y: Optional[float] = None, unit: str = "relative") -> Self
+
# .plain
+
+
+ text
+ 已复制
+
+ .plain(enabled: bool = True) -> Self
+
# .points
+
+
+ text
+ 已复制
+
+ .points(enabled: bool = True) -> Self
+
# .position
+
+
+ text
+ 已复制
+
+ .position(x: Optional[float] = None, y: Optional[float] = None, unit: str = "points") -> Self
+
# .preserve
+
+
+ text
+ 已复制
+
+ .preserve(enabled: bool = True) -> Self
+
# .pressed
+
+
+ text
+ 已复制
+
+ .pressed(**style: Any) -> Self
+
# .privacy_sensitive
+
+
+ text
+ 已复制
+
+ .privacy_sensitive(enabled: bool = True) -> Self
+
# .redacted
+
+
+ text
+ 已复制
+
+ .redacted(reason: str = "placeholder") -> Self
+
# .rendering
+
+
+ text
+ 已复制
+
+ .rendering(mode: str, colors: Optional[Sequence[ColorLike]] = None) -> Self
+
# .reverse_mask
+
+
+ text
+ 已复制
+
+ .reverse_mask(kind: str = "roundedRectangle", corner_radius: Optional[float] = None) -> Self
+
# .rotate
+
+
+ text
+ 已复制
+
+ .rotate(degrees: float) -> Self
+
# .rotation
+
+
+ text
+ 已复制
+
+ .rotation(degrees: float) -> Self
+
# .scale
+
+
+ text
+ 已复制
+
+ .scale(value: Union[float, str]) -> Self
+
# .segment_colors
+
+
+ text
+ 已复制
+
+ .segment_colors(colors: List[ColorLike]) -> Self
+
# .shadow
+
+
+ text
+ 已复制
+
+ .shadow(color: ColorLike = "#000000", radius: float = 4, x: float = 0, y: float = 2, ) -> Self
+
# .slot
+
+
+ text
+ 已复制
+
+ .slot(value: str) -> Self
+
# .soft_background
+
+
+ text
+ 已复制
+
+ .soft_background(
+ tone: Optional[str] = None,
+ corner_radius: Optional[float] = None,
+ padding: Optional[Union[int, float]] = None,
+) -> Self
+
# .stroke
+
+
+ text
+ 已复制
+
+ .stroke(
+ color: Optional[ColorLike] = None,
+ *,
+ width: Optional[Union[float, str]] = None,
+ dash: Optional[Sequence[float]] = None,
+ cap: Optional[str] = None,
+ join: Optional[str] = None,
+ miter_limit: Optional[float] = None,
+) -> Self
+
# .threshold
+
+
+ text
+ 已复制
+
+ .threshold(value: float, color: Optional[ColorLike] = None) -> Self
+
# .toggle_style
+
+
+ text
+ 已复制
+
+ .toggle_style(value: str = "checkbox") -> Self
+
# .tone
+
+
+ text
+ 已复制
+
+ .tone(value: str) -> Self
+
# .track_color
+
+
+ text
+ 已复制
+
+ .track_color(value: ColorLike) -> Self
+
# .transition
+
+
+ text
+ 已复制
+
+ .transition(value: str = "opacity", edge: Optional[str] = None) -> Self
+
# .variant
+
+
+ text
+ 已复制
+
+ .variant(value: str) -> Self
+
# .width
+
+
+ text
+ 已复制
+
+ .width(value: Optional[Union[float, Dict[str, Any]]] = None, **values: Any) -> Self
+
# 内容和文字
+
文字节点返回的是可继续修改的句柄：
+
+
+ python
+ 已复制
+
+ w.text("ADHD Bingo", size=28, weight="bold", color="#242326") \
+ .line_limit(1) \
+ .min_scale(0.7)
+
数值用 value()，需要数字变化动画时加 content_transition("numericText") 和稳定身份：
+
+
+ python
+ 已复制
+
+ w.value(count, format="{} 次") \
+ .id("count") \
+ .monospaced_digit() \
+ .content_transition("numericText") \
+ .line_limit(1) \
+ .min_scale(0.7)
+
# 修饰顺序
+
推荐顺序是：内容 -> 字体和颜色 -> 尺寸 -> 位置 -> 动画或交互。
+
+
+ python
+ 已复制
+
+ w.text("喝水") \
+ .font_size(16) \
+ .color("#242326") \
+ .line_limit(1) \
+ .min_scale(0.7) \
+ .frame(width=72, height=44) \
+ .place(120, 80, unit="points")
+
# 什么时候用精确布局
+
信息卡、进度卡、列表优先用 row()、column()、grid()。需要做表格、键盘、翻页钟、海报式排版时，用 table()、canvas()、.frame() 和 .place() 读取 w.context 后按点位布局。
+
+ 
- 
- 
- 
- 
- 
- 
- 
+ 
+ 
+ 
+ 
| 
|
-| 文件管理、颜色标记、置顶、搜索、批量操作、回收站 | 语法高亮、智能补全、快捷输入栏、查找替换、分屏 |
-
-| 控制台 | AI 助手 |
-|:---:|:---:|
-| 
| 
|
-| Rich 彩色输出、进度条、多控制台切换、交互式 input() | Diff 差异对比、逐条采纳/拒绝、一键修复报错、SSH 远程运维 |
-
-| 库管理 | 工具箱 |
-|:---:|:---:|
-| 
| 
|
-| PyPI 搜索安装、热门库分类、进度条、版本管理、一键卸载 | 编解码、JSON、API 调试、二维码、时间戳、正则、直链下载 |
-
-| HTML 预览 | Markdown 渲染 |
-|:---:|:---:|
-| 
| 
|
-| 全屏网页渲染、双指缩放、alert/console 桥接 | 实时渲染，支持标题、列表、代码块、表格、任务列表 |
-
-| 新建文件 | 设置 |
-|:---:|:---:|
-| 
| 
|
-| 支持 py/js/html/css/md/json 等多种格式，可设置颜色标记 | 外观、编辑器字体、AI 配置、应用锁定、快捷指令帮助 |
-
----
-
-## 📥 安装 / Install
-
-
-
