frappe-frontend-development

用途

本技能用于使用 Frappe UI（Vue 3 + TailwindCSS）和门户页面构建现代前端应用。适用场景包括：为 Frappe 应用构建自定义 SPA 前端；使用 Frappe UI 组件（Button、Dialog、ListView 等）；通过 Resource、ListResource、DocumentResource 实现数据获取；创建门户/公开页面；在 Frappe 应用内搭建 Vue 3 前端工具链。

前置输入

需要明确：应用名称以及前端是否已存在；前端类型（通过 Frappe UI 的完整 SPA，或门户页面）；认证要求（登录用户、访客访问）；所需的关键组件和数据资源。

选择前端方案

Frappe UI SPA：用于自定义应用前端，技术栈为 Vue 3、TailwindCSS、Vite。
门户页面：用于简单公开页面，技术栈为 Jinja + HTML、少量 JS。
Desk 扩展：用于管理界面增强，使用 Form/List 脚本（参见 frappe-desk-customization）。

搭建 Frappe UI 前端

在 Frappe 应用目录内执行：

cd apps/my_app
npx degit frappe/frappe-ui-starter frontend
cd frontend
yarn
yarn dev

配置 main.js

import { createApp } from 'vue'
import {
    FrappeUI,
    setConfig,
    frappeRequest,
    resourcesPlugin,
    pageMetaPlugin
} from 'frappe-ui'
import App from './App.vue'
import './index.css'

let app = createApp(App)
app.use(FrappeUI)
setConfig('resourceFetcher', frappeRequest)
app.use(resourcesPlugin)
app.use(pageMetaPlugin)
app.mount('#app')

使用 Resource 获取数据

通用 Resource 用于自定义 API 调用，支持 url、params、auto、cache、transform、onSuccess、onError 等配置；提供 data、loading、error、fetched 属性，以及 fetch()、reload()、submit()、reset() 方法。

List Resource 用于带分页的 DocType 列表，支持 doctype、fields、filters、orderBy、pageLength、auto、cache；提供 data、hasNextPage、next()、reload()，以及 insert、setValue、delete、runDocMethod 等 CRUD 操作。

Document Resource 用于单个文档操作，支持 doctype、name、whitelistedMethods、onSuccess；提供 doc、reload()、setValue、setValueDebounced、白名单方法调用和 delete。

使用 Frappe UI 组件

组件类别包括：输入类（TextInput、Textarea、Select、Combobox、MultiSelect、Checkbox、Switch、DatePicker、TimePicker、Slider、Password、Rating）；展示类（Alert、Avatar、Badge、Breadcrumbs、Progress、Tooltip、ErrorMessage、LoadingText）；导航类（Button、Dropdown、Tabs、Sidebar、Popover）；布局类（Dialog、ListView、Calendar、Tree）；富内容类（TextEditor（TipTap）、Charts、FileUploader）。

指令与工具

可使用 onOutsideClickDirective、visibilityDirective 以及 debounce 工具。

配置 TailwindCSS

在 tailwind.config.js 中引入 frappe-ui 的预设，并将 frappe-ui 组件路径加入 content。

生产构建

执行 cd frontend && yarn build，构建产物由 Frappe 在 /frontend 路径下提供。

门户页面（替代方案）

对于无需完整 SPA 的简单公开页面，可在应用的 website/ 或 www/ 目录下创建 HTML 与 Python 文件，使用 Jinja 模板继承 templates/web.html，并在 get_context 中设置上下文数据。

验证

yarn dev 无错误启动；组件正确渲染；数据资源能获取并展示数据；CRUD 操作正常；认证正常（登录重定向、会话处理）；yarn build 成功完成；生产资源能从 Frappe 正确提供。

故障排查

CORS 错误：本地开发设置 ignore_csrf，生产环境确保正确的 CSRF 令牌。API 调用 404：检查方法路径，确认 @frappe.whitelist() 装饰器。组件未找到：确保导入路径正确，检查 frappe-ui 版本。样式损坏：确认 TailwindCSS 配置包含 frappe-ui 组件路径。认证问题：检查会话 cookie，确保开发代理配置中的站点 URL 匹配。

升级路径

Desk UI 脚本参见 frappe-desk-customization；API 端点实现参见 frappe-api-development；应用架构参见 frappe-app-development；官方应用的 UI/UX 模式参见 frappe-ui-patterns。

参考

references/frappe-ui.md（Frappe UI 框架参考）；references/portal-development.md（门户页面概览）。

注意事项

自定义前端始终使用 Frappe UI，不要使用原生 JS、jQuery 或自定义框架；优先使用 FrappeUI 组件；CRUD 应用遵循 CRM/Helpdesk 应用外壳模式；处理加载状态；验证 API 响应；正确配置代理；处理认证。

常见错误

缺少 CORS/代理设置导致开发中 API 调用失败，需配置 Vite 代理转发 /api；未处理认证状态导致登出用户崩溃，需在挂载时检查登录用户；资源 URL 错误导致 404；硬编码站点 URL 破坏跨环境；未包含 CSRF 令牌导致 POST 失败；缺少 TailwindCSS 配置导致样式损坏；使用原生 JS/jQuery 导致体验不一致；自定义应用外壳设计与生态不一致。