跳转到主要内容

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.

​
构建技巧

​
1. 先定义数据结构

Teable 应用构建器基于你现有的表格工作——你设计的表和字段，就是应用的数据底座，AI 直接读取它们来生成界面和逻辑。 所以在开始构建 App 之前，先把数据结构定义好。字段类型、关联关系、数据的读写方向越清晰，AI 的产出质量就越高。

​
2. 先规划，再动手

数据结构定义好之后，也不要急着让 AI 开始搭界面。先和它一起做一轮规划。 告诉 AI：“我们先不写代码，先做个计划。“描述你要解决的问题、面向的用户、大致的功能需求，让 AI 帮你梳理出一份结构化的方案。审核、调整、确认方案合理之后，再让它动手。
前期多花几分钟对齐方向，能帮你省掉后面大量的返工。

​
3. 从简单开始

不要试图一次把所有功能塞进一个提示词里。先描述核心功能，跑通一个最小可用版本，然后一次加一个东西：一个交互、一个样式、一个逻辑。 每次改动后确认效果，再进入下一步。出了问题只需要回退一个小改动，而不是推倒重来。

​
4. 具体描述，避免抽象

“做得好看一点""让交互更自然”这类描述对 AI 来说几乎没有信息量。 有效的提示词是具体的：哪个页面、哪个区域、期望什么行为、不想要什么效果。能附上截图或参考界面，效果会更好。
把提示词当成给一个聪明但完全不了解你项目的人交代任务。描述越精确，交付越接近预期。

​
5. 先诊断，再修复

App 表现不符合预期的时候，不要急着让 AI “修一下”。模糊的修复指令容易导致 AI 盲目打补丁，甚至引入新问题。 更好的做法是分两步：
1

让 AI 先分析原因

描述观察到的现象，让 AI 给出几个可能的原因和对应方案，先别动手改。
2

选定方向后再动手

你判断哪个解释最合理，告诉 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 可能会出错。请仔细检查。
Last modified on April 21, 2026