> ## Documentation Index
> Fetch the complete documentation index at: https://help.teable.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 应用构建器最佳实践
> 充分发挥 Teable 应用构建器能力的实用技巧与模式。
## 构建技巧
### 1. 先定义数据结构
Teable 应用构建器基于你现有的表格工作——**你设计的表和字段，就是应用的数据底座**，AI 直接读取它们来生成界面和逻辑。
所以在开始构建 App 之前，先把数据结构定义好。字段类型、关联关系、数据的读写方向越清晰，AI 的产出质量就越高。
### 2. 先规划，再动手
数据结构定义好之后，也不要急着让 AI 开始搭界面。先和它一起做一轮规划。
告诉 AI："我们先不写代码，先做个计划。"描述你要解决的问题、面向的用户、大致的功能需求，让 AI 帮你梳理出一份结构化的方案。审核、调整、确认方案合理之后，再让它动手。
前期多花几分钟对齐方向，能帮你省掉后面大量的返工。
### 3. 从简单开始
不要试图一次把所有功能塞进一个提示词里。先描述核心功能，跑通一个最小可用版本，然后一次加一个东西：一个交互、一个样式、一个逻辑。
每次改动后确认效果，再进入下一步。出了问题只需要回退一个小改动，而不是推倒重来。
### 4. 具体描述，避免抽象
"做得好看一点""让交互更自然"这类描述对 AI 来说几乎没有信息量。
有效的提示词是具体的：**哪个页面、哪个区域、期望什么行为、不想要什么效果**。能附上截图或参考界面，效果会更好。
把提示词当成给一个聪明但完全不了解你项目的人交代任务。描述越精确，交付越接近预期。
### 5. 先诊断，再修复
App 表现不符合预期的时候，不要急着让 AI "修一下"。模糊的修复指令容易导致 AI 盲目打补丁，甚至引入新问题。
更好的做法是分两步：
描述观察到的现象，让 AI 给出几个可能的原因和对应方案，先别动手改。
你判断哪个解释最合理，告诉 AI 按那个方向来修。
如果连续几次修复都没效果，回退到之前正常工作的版本重新来过。这通常比反复打补丁更快。
### 6. 善用版本回退
每一次和 AI 的对话都会产生变更。建议的节奏是：完成一个功能模块，确认它正常工作，再开始下一个。**不要同时推进多个未完成的功能**。
后续修改导致了问题？回退到上一个稳定版本，用更清晰的提示词重新尝试。
## 常见问题
### App Builder 只支持 Next.js
App Builder 的运行环境（沙箱、预览、构建）基于 **Next.js** 构建，目前**不支持**其他前端框架，包括 Astro、Vite、Create React App、Vue、Svelte 等。
如果你在对话中要求使用非 Next.js 框架，AI 可能不会始终拒绝，甚至可能尝试为你生成对应代码。但由于底层环境不兼容，**预览将无法正常启动**，你会持续看到 "Preview is starting..." 而无法进入应用——在这个过程中，对话仍然会消耗 credits。
如果你需要使用 Next.js 以外的框架，建议在 App Builder 之外的本地开发环境中进行，然后通过 Teable API 与你的数据对接。
### 处理 429 错误
Teable API 目前有 **10 QPS**（每秒 10 次请求）的限制。App Builder 生成的应用如果没有做好请求优化，在使用过程中可能会触发 429 错误。我们正在持续优化 API 性能，后续可能会调整这一限制。
核心策略有四个方向：
减少重复请求
减少单次数据量
降低请求频率
减少预览报错
以下按策略分类列出常见场景、解决思路和参考提示词。
**缓存：减少重复请求**
**场景**：仪表盘页面有多个图表、统计卡片、列表，每个组件独立请求不同的表；或者页面主要用于展示数据，但每次访问都直接请求 API。这样一来，页面打开瞬间并发就可能过高，访问量一上来时也更容易触发 429。
**解决方式**：优先使用缓存友好的渲染方式。数据加载后缓存到 App 内存中（建议 1–3 分钟有效期），再次访问时直接读缓存；非首屏组件延迟加载，错开请求时机。如果你发现页面仍然在每次访问时重复请求，可以明确要求它使用缓存策略。
**参考提示词**："这是一个展示型页面，请优先使用更适合缓存的渲染方式。页面加载数据后缓存到本地，缓存有效期 1 分钟，有效期内不重新请求 API；非首屏组件延迟 500ms 再加载数据。"
**场景**：页面上 3 个组件都需要同一张表的数据，各自独立发请求，实际上一次就够了。
**解决方式**：统一数据源管理，同一份数据只请求一次，多个组件共享使用。
**参考提示词**："如果多个组件需要同一张表的数据，只请求一次，然后共享给所有需要的组件。不要重复请求。"
**场景**：用户在页面之间来回切换，每次进入都重新拉取数据，即使数据没有变化。
**解决方式**：在缓存有效期内直接复用之前的数据，不重复请求。
**参考提示词**："用户切换页面后再回来时，如果距离上次加载不超过 1 分钟，直接使用缓存数据，不重新请求 API。"
**场景**：一个下拉框需要展示某张表的全部记录作为选项，记录多时一次性加载压力很大。
**解决方式**：改为搜索式选择器，用户输入关键词后再请求匹配结果；或者缓存选项列表。
**参考提示词**："下拉选择器不要一次加载所有选项。改为用户输入关键词后搜索匹配的记录，并加 debounce。"
**场景**：选择一个字段后触发加载下一级的选项，多级级联一次操作就产生多次请求。
**解决方式**：预加载相关数据后在本地筛选，或者缓存已加载的级联数据。
**参考提示词**："级联选择器的选项数据加载后缓存到本地。用户切换上级选项时，先从缓存中筛选，不要每次都重新请求。"
**场景**：组件状态管理不当，每次重新渲染都重新发起数据请求。
**解决方式**：数据请求应该由特定事件触发，而不是跟随每次渲染。加缓存作为兜底。
**参考提示词**："数据请求只在页面首次加载和用户主动操作时触发。组件重新渲染时不要重复请求，使用缓存中的数据。"
**分页与批量：减少单次数据量**
**场景**：一次性加载全量数据，记录多的时候产生大量 API 调用。
**解决方式**：加分页，每次只请求当前页的数据。
**参考提示词**："列表每页显示 20 条数据，用户翻页时才加载下一页。不要一次加载全部数据。"
**场景**：加载一个列表后，对每条记录逐一请求关联表的详情。比如加载 50 个项目，然后逐个请求每个项目的负责人信息，瞬间产生 50 次请求。
**解决方式**：一次性批量获取关联数据，而不是逐条请求。
**参考提示词**："加载列表时，一次性批量获取所有关联数据。不要用循环逐条请求每条记录的关联信息。"
**场景**：批量更新多条记录时，逐条发送更新请求而不是一次批量提交。
**解决方式**：使用批量方式一次提交多条记录的变更。
**参考提示词**："批量操作时，把多条记录的变更合并为一次请求提交。不要逐条发送更新请求。"
**场景**：代码里用 for 循环逐条处理数据，每次循环都调一次 API。
**解决方式**：先收集所有需要的数据，然后一次性批量请求。
**参考提示词**："不要在循环中调用 API。先收集所有需要的数据 ID，然后一次性批量请求。"
**防抖与节流：降低请求频率**
**场景**：用户在搜索框输入时，每输入一个字符就触发一次请求。输入"项目管理"四个字就产生 4 次请求。
**解决方式**：加 debounce（防抖），用户停止输入 300–500ms 后再发请求。
**参考提示词**："搜索框加 debounce，用户停止输入 300ms 后再发起搜索请求。输入过程中不要发请求。"
**场景**：快速连续点击提交按钮、快速切换筛选条件、快速翻页，每次操作都立即发请求。
**解决方式**：加 debounce 或 throttle（节流）。提交按钮在请求完成前禁用，防止重复提交。
**参考提示词**："提交按钮点击后禁用，请求完成后再恢复。筛选条件变化时加 debounce，300ms 内的连续变化只发一次请求。"
**场景**：用户每修改一个字段就立即保存，填一个表单可能触发十几次写入。
**解决方式**：改为用户主动点击保存，或加 debounce，停止编辑一段时间后再统一保存。
**参考提示词**："表单不要每改一个字段就保存。用户点击保存按钮时才提交，或者用户停止编辑 2 秒后自动保存一次。"
**场景**：设置了每几秒自动刷新数据，持续高频请求。
**解决方式**：延长轮询间隔到合理范围（30 秒或 1 分钟以上），或改为用户手动刷新。
**参考提示词**："数据自动刷新间隔设为 60 秒。加一个手动刷新按钮，让用户可以主动获取最新数据。"
**场景**：页面上多个组件各自设了定时刷新，叠加起来很容易超限。
**解决方式**：统一轮询机制，一次刷新后分发给所有需要更新的组件。
**参考提示词**："不要让每个组件各自设定时刷新。统一一个数据刷新机制，定时一次性获取所有需要更新的数据，然后分发给各组件。"
**渲染兼容：减少预览报错**
**场景**：页面里用了图表、地图，或者依赖 `window`、DOM 尺寸、浏览器环境的库，结果在预览中报错、白屏，或者出现 hydration mismatch。
**解决方式**：这类组件更适合在浏览器端加载，而不是直接参与服务端渲染。App Builder 通常会尽量避开这类问题；如果你仍然遇到预览异常，可以明确让它改成浏览器端加载方案。
**参考提示词**："这个组件依赖浏览器环境，请改成只在浏览器端加载，避免在预览阶段出现渲染报错或 hydration mismatch。"
AI 可能会出错。请仔细检查。