mesop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mesop

Use this skill to build, debug, and deploy Mesop applications. Mesop is a Python-native UI framework that enables developers to build web apps without writing frontend code (HTML/CSS/JS).

使用此技能来构建、调试和部署Mesop应用。Mesop是一个原生Python UI框架，开发者无需编写前端代码（HTML/CSS/JS）即可构建Web应用。

Quick Triage

快速判断

Use this skill for pure Python web UIs, especially for AI/ML demos and internal tools.
Do NOT use this skill if the user specifically requests a different Python framework (Streamlit, Gradio, Solara) unless they are asking for a comparison or migration.
Do NOT use this skill for general Flask/FastAPI backend development unless it's specifically about mounting a Mesop app.

此技能适用于纯Python Web UI场景，尤其适合AI/ML演示和内部工具。
若用户明确要求使用其他Python框架（Streamlit、Gradio、Solara），除非是询问对比或迁移方案，否则请勿使用此技能。
除非是关于挂载Mesop应用的特定需求，否则请勿将此技能用于通用Flask/FastAPI后端开发。

Workflow

工作流程

Setup: Install
```
mesop
```
and create
```
main.py
```
.
Define Page: Use
```
@me.page(path="/")
```
to define the entry point.
Define State: Create a
```
@me.stateclass
```
to hold session state (must be serializable).
Create Components: Build the UI tree using
```
me.box
```
,
```
me.text
```
,
```
me.input
```
, etc.
Handle Events: Write event handler functions (regular or generator) to update state.
Style: Apply styles using
```
me.Style
```
(flexbox/grid) for layout and appearance.
Deploy: Deploy to Cloud Run, Docker, or Hugging Face Spaces.

环境搭建：安装
```
mesop
```
并创建
```
main.py
```
文件。
定义页面：使用
```
@me.page(path="/")
```
定义应用入口点。
定义状态：创建
```
@me.stateclass
```
来存储会话状态（必须可序列化）。
创建组件：使用
```
me.box
```
、
```
me.text
```
、
```
me.input
```
等组件构建UI树。
处理事件：编写事件处理函数（常规函数或生成器）来更新状态。
样式设置：使用
```
me.Style
```
（flexbox/grid）来设置布局和外观样式。
部署应用：部署至Cloud Run、Docker或Hugging Face Spaces。

Essential Patterns

核心模式

Standard Import

标准导入

Always use the standard alias:

python

import mesop as me
import mesop.labs as mel # For labs components like chat

始终使用标准别名：

python

import mesop as me
import mesop.labs as mel # For labs components like chat

State Management

状态管理

State is session-scoped and must be serializable.

python

@me.stateclass
class State:
  count: int = 0
  input_value: str = "" # Immutable default
  # items: list[str] = field(default_factory=list) # Mutable default pattern

Accessing State:

state = me.state(State)

inside components or event handlers.

状态是会话级别的，且必须可序列化。

python

@me.stateclass
class State:
  count: int = 0
  input_value: str = "" # Immutable default
  # items: list[str] = field(default_factory=list) # Mutable default pattern

访问状态： 在组件或事件处理函数内使用

state = me.state(State)

。

Event Handlers

事件处理函数

Regular: Run to completion, then update UI.
Generator:
```
yield
```
to stream UI updates (e.g., loading states, LLM streaming). MUST yield at the end.
Async: Use
```
async def
```
and
```
await
```
for concurrent operations.

常规函数：运行至完成后更新UI。
生成器函数：使用
```
yield
```
来流式更新UI（例如加载状态、LLM流式输出）。必须在末尾使用yield。
异步函数：使用
```
async def
```
和
```
await
```
处理并发操作。

Component Composition

组件组合

Use

with

blocks for content components (parents):

python

with me.box(style=me.Style(display="flex")):
  me.text("Child 1")
  me.button("Child 2")

使用

with

块来组织内容组件（父组件）：

python

with me.box(style=me.Style(display="flex")):
  me.text("Child 1")
  me.button("Child 2")

Key Usage

Key的使用

Use

key

to identify components for:

Resetting state (change key to re-render)
Focus management (
```
me.focus_component
```
)
Scroll targeting (
```
me.scroll_into_view
```
)
Reusing event handlers (access
```
e.key
```
)

使用

key

来标识组件，用于：

重置状态（修改key以重新渲染）
焦点管理（
```
me.focus_component
```
）
滚动定位（
```
me.scroll_into_view
```
）
复用事件处理函数（访问
```
e.key
```
）

Common Pitfalls

常见陷阱

Closure Variables: Do NOT rely on closure variables in event handlers; they may be stale. Use
```
key
```
or state instead.
Input Race Conditions: Avoid setting
```
value
```
on inputs unless necessary. Use
```
on_blur
```
instead of
```
on_input
```
for performance, or track "initial" vs "current" value if bidirectional binding is needed.
Mutable Defaults: Never use mutable types (list, dict) as default values in
```
@me.stateclass
```
. Use
```
dataclasses.field(default_factory=...)
```
.
Global State: Global variables are shared across ALL users. Use
```
@me.stateclass
```
for per-session state.

闭包变量：请勿在事件处理函数中依赖闭包变量，它们可能已过期。请改用
```
key
```
或状态。
输入竞态条件：除非必要，否则避免为输入组件设置
```
value
```
。为提升性能，使用
```
on_blur
```
替代
```
on_input
```
；若需要双向绑定，请跟踪“初始值”与“当前值”。
可变默认值：切勿在
```
@me.stateclass
```
中使用可变类型（列表、字典）作为默认值。请使用
```
dataclasses.field(default_factory=...)
```
。
全局状态：全局变量会在所有用户之间共享。请使用
```
@me.stateclass
```
来存储会话级状态。

Reference Map

参考指南

Core Patterns:
```
references/core-patterns.md
```
(State, Events, Streaming, Navigation)
Components:
```
references/components-reference.md
```
(API reference for all components)
Styling & Layouts:
```
references/styling-and-layouts.md
```
(CSS-in-Python, Flexbox, Grid, Theming)
Deployment:
```
references/deployment-and-config.md
```
(Cloud Run, Docker, Config, Security)
Web Components:
```
references/web-components.md
```
(Custom JS integration, Lit)

核心模式：
```
references/core-patterns.md
```
（状态、事件、流式输出、导航）
组件：
```
references/components-reference.md
```
（所有组件的API参考）
样式与布局：
```
references/styling-and-layouts.md
```
（Python中的CSS、Flexbox、Grid、主题）
部署：
```
references/deployment-and-config.md
```
（Cloud Run、Docker、配置、安全）
Web组件：
```
references/web-components.md
```
（自定义JS集成、Lit）