webflow-designer-extension

用途

本技能用于构建在 Webflow Designer 内部运行的扩展（Designer Extensions）。这些扩展以 iframe 形式加载，通过 Webflow Designer API 与设计器交互，可以操作元素、样式、页面等。适用于创建、调试或修改此类扩展的场景。

主要能力

提供 Designer API 的完整参考，包括 Elements API（元素选择、插入、预设和元素构建器）、Styles API（创建样式、设置 CSS 属性、断点和伪状态）、Components API（组件定义、实例和编辑上下文）、Variables API（设计令牌变量，如颜色、尺寸、字体、数字、百分比）、Pages API（页面和文件夹管理）、Assets API（资产上传和管理）、Extension Utilities（站点信息、事件、通知、应用发现、认证）、Error Handling（错误结构、原因标签和恢复模式）以及 Code Examples（跨 API 工作流示例）。
提供 create-webflow-extension 脚手架 CLI 和 Webflow CLI 参考。
提供项目结构和构建配置说明（React 19 + TypeScript + Rspack）。
提供设计指南、应用注册、Marketplace 审核标准、应用提交与上架、FAQ 等文档。
提供脚本：validate-extension.py 用于打包前验证扩展结构；search_references.py 用于按标签、关键词搜索参考文件或列出全部元数据。
提供资产：webflow-variables.css，包含 Webflow 设计系统颜色、排版和阴影的 CSS 变量。

使用方式

快速上手流程：

前置条件：先在 Webflow 注册应用（参见 references/register-app.md），需要一个具有 Admin 权限的工作区。
脚手架：运行 npx create-webflow-extension@latest，通过交互式提示选择项目名称、包管理器、linter。
开发：cd <name> && pnpm dev，服务运行在 localhost:1337，也支持 npm/yarn/bun。
测试：通过 Workspace Settings > Apps & Integrations > Develop，将应用安装到测试站点。
打开：在 Designer 中按 "E" 打开应用面板，启动扩展。
构建：pnpm build 用于部署。

搜索脚本用法：

# 列出所有参考文件及其元数据
python scripts/search_references.py --list

# 按标签（精确匹配）搜索
python scripts/search_references.py --tag <tag>

# 按关键词搜索（覆盖名称、描述、标签和内容）
python scripts/search_references.py --search <query>

项目结构

由 create-webflow-extension 生成（React 19 + TypeScript + Rspack）：

my-extension/
├── public/
│   └── index.html        # 入口点
├── src/
│   ├── App.tsx           # 主 React 组件
│   ├── main.tsx          # React 入口点
│   └── index.css         # 样式
├── webflow.json          # 扩展设置
├── rspack.config.ts      # Rspack 打包配置
├── package.json
└── tsconfig.json

适用场景

适合需要在 Webflow Designer 中集成自定义功能、操作设计器内容、使用设计令牌变量、管理页面与资产，以及准备将扩展提交至 Marketplace 的开发者。

最佳实践

检查元素能力：在 append/prepend 前始终验证 element.children，在文本操作前验证 element.textContent。
优雅处理错误：使用 try/catch 配合 webflow.notify() 提供用户反馈。
响应式设计：设置样式时在多个断点上测试。
使用变量：利用设计令牌变量保持主题一致。
订阅事件：使用 Designer 事件保持扩展状态同步。
合适尺寸：使用 webflow.setExtensionSize() 设置合适的面板尺寸。

限制

资料未提供具体的功能限制、收费、价格或平台限制信息。