API 参考 - PythonIDE Docs

这页是公开 Widget() API 的签名索引。先用 API 地图按任务选择能力，再回到这里核对函数名、参数名和返回句柄。

#怎么查

选能力：先看「常用组合」。
查签名：看「完整公开 API 索引」。
学写法：先看 widget 或从脚本到桌面，再进入布局、参数、交互、时间线或外观指南。
排故障：先看排错，再回到这里核对签名。

#常用组合

目标	推荐 API
普通信息卡	`text`、`value`、`progress`、`row`、`column`
精确表格	`table`、`canvas`、`path`、`shape`、`.place()`
可点击状态	`widget.state`、`button`、`toggle`
可调参数	`widget.param.color/slider/text/bool/choice/file`
动态数据	`widget.entry`、`timeline`、`content_transition`、`flip`
外观适配	`container_background`、`content_margins`、`transparent_background`、`accentable`

#行为契约

API	保证	注意
`Widget()`	创建一个小组件根容器，控制背景、边距和整体样式。	一个脚本只保留一个最终渲染的小组件。
`w.render()`	输出当前小组件并结束构建流程。	放在脚本末尾；没有调用时预览和发布都不会得到内容。
`widget.param.*`	在预览面板提供可配置输入，构建时读取当前值。	参数不是桌面点击状态；改名后需要重新运行并发布。
`widget.state.*`	保存桌面交互状态，并为按钮或开关生成安全动作。	不要把普通 Python 回调传给桌面按钮。
`w.button()` / `w.toggle()`	创建系统允许的点击或开关交互。	交互区域要清晰，避免同一区域同时承担链接和按钮。
`w.timeline()` / `widget.entry`	声明一组未来显示结果，用于系统刷新和数据更新动画。	刷新时机由系统调度，不适合连续动画。
`widget.family_value()`	为不同 family 选择不同值。	small、medium、large 内容密度差异大，不要只缩小同一套布局。
`.line_limit()` / `.min_scale()`	限制可变文本的行数，并允许文字在小尺寸内缩放。	用户可改文本、按钮标题和主值默认都应该加。
`w.container_background()`	声明系统小组件背景。	透明、染色和背景移除是否生效取决于系统宿主环境。

#公开 API 速查

场景	常用 API	用途
创建和运行	`Widget()`、`w.render`、`w.validate`、`w.timeline`	创建、检查、发布小组件，并声明更新时间线。
尺寸和数据	`widget.context`、`widget.entry`、`widget.param`、`widget.state`、`widget.family_value`	读取当前尺寸、时间线数据、参数和桌面交互状态。
文字和内容	`w.text`、`w.rich_text`、`w.value`、`w.symbol`、`w.svg`、`w.image`、`w.badge`	标题、数值、图标、图片和组合文字。
图表和进度	`w.progress`、`w.ring_chart`、`w.line_chart`、`w.bar_chart`	进度条、圆环、折线和柱状图。
布局	`w.row`、`w.column`、`w.layer`、`w.grid`、`w.table`、`w.canvas`、`w.spacer`、`w.divider`	从自动布局到精确表格、画布定位。
形状和线条	`w.shape`、`w.rect`、`w.circle`、`w.path`；`.stroke`、`.clip_shape`、`.mask`、`.reverse_mask`	线宽、虚线、裁切、遮罩和自定义图形。
交互	`w.button`、`w.toggle`、`w.link`；`widget.action`	AppIntent 按钮、开关、链接和状态动作。
外观	`w.container_background`、`w.content_margins`、`w.transparent_background`、`w.background_image`；`.accentable`、`.privacy_sensitive`、`.redacted`	深色、透明、染色、隐私和占位。
动画	`w.flip`；`.content_transition`、`.animation`、`.transition`、`.id`	WidgetKit 数据更新动画和稳定身份。
资源和缓存	`widget.save_image`、`widget.cache_json`、`widget.history`	保存图片、缓存网络数据和保留历史值。

#完整公开 API 索引

#常量

widget.CIRCULAR：Family: circular
widget.INLINE：Family: inline
widget.LARGE：Family: large
widget.MEDIUM：Family: medium
widget.RECTANGULAR：Family: rectangular
widget.SMALL：Family: small

#运行值

widget.action：动作助手，用于创建受控刷新、状态和打开链接动作。
widget.color：颜色助手，用于固定色、浅深色和系统角色色。
widget.context：当前 family、尺寸和内容区域信息。
widget.entry：当前 timeline entry 的字段读取入口。
widget.family：当前小组件 family 名称。
widget.param：预览面板参数声明入口。
widget.state：桌面交互状态声明入口。
widget.storage：小组件脚本可用的轻量存储入口。

#函数

#`widget.cache_json`

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

#`widget.family_value`

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

#`widget.save_image`

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

#`w.button`

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

#`.button_style`

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 后按点位布局。

#怎么查

#常用组合

#行为契约

#公开 API 速查

#完整公开 API 索引

#常量

#运行值

#函数

#widget.cache_json

#widget.family_value

#widget.history

#widget.save_image

#Widget 方法

#w.background

#w.background_image

#w.badge

#w.bar_chart

#w.body

#w.button

#w.canvas

#w.caption

#w.change

#w.circle

#w.column

#w.container_background

#w.content_margins

#w.context

#w.countdown

#w.date

#w.divider

#w.dynamic_date

#w.flip

#w.grid

#w.image

#w.layer

#w.line_chart

#w.link

#w.list

#w.path

#w.progress

#w.rect

#w.region

#w.relative_time

#w.render

#w.rich_text

#w.ring_chart

#w.row

#w.section

#w.shape

#w.spacer

#w.surface

#w.svg

#w.symbol

#w.table

#w.text

#w.time

#w.timeline

#w.timer_text

#w.title

#w.toggle

#w.transparent_background

#w.unless

#w.validate

#w.value

#w.when

#修饰符

#.accentable

#.accessibility

#.align

#.animation

#.background

#.bar_spacing

#.baseline

#.button_style

#.capsule

#.clip

#.clip_shape

#.color

#.compressed

#.content_transition

#`widget.cache_json`

#`widget.family_value`

#`widget.history`

#`widget.save_image`

#`w.background`

#`w.background_image`

#`w.badge`

#`w.bar_chart`

#`w.body`

#`w.button`

#`w.canvas`

#`w.caption`

#`w.change`

#`w.circle`

#`w.column`

#`w.container_background`

#`w.content_margins`

#`w.context`

#`w.countdown`

#`w.date`

#`w.divider`

#`w.dynamic_date`

#`w.flip`

#`w.grid`

#`w.image`

#`w.layer`

#`w.line_chart`

#`w.link`

#`w.list`

#`w.path`

#`w.progress`

#`w.rect`

#`w.region`

#`w.relative_time`

#`w.render`

#`w.rich_text`

#`w.ring_chart`

#`w.row`

#`w.section`

#`w.shape`

#`w.spacer`

#`w.surface`

#`w.svg`

#`w.symbol`

#`w.table`

#`w.text`

#`w.time`

#`w.timeline`

#`w.timer_text`

#`w.title`

#`w.toggle`

#`w.transparent_background`

#`w.unless`

#`w.validate`

#`w.value`

#`w.when`

#`.accentable`

#`.accessibility`

#`.align`

#`.animation`

#`.background`

#`.bar_spacing`

#`.baseline`

#`.button_style`

#`.capsule`

#`.clip`

#`.clip_shape`

#`.color`

#`.compressed`

#`.content_transition`

#`.control_layout`

#`.control_style`

#`.corner_radius`

#`.fill`

#`.fixed_size`

#`.font`

#`.font_size`

#`.font_style`

#`.font_weight`

#`.font_width`