convex-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<overview> Use Convex Components to add isolated backend features and compose component APIs. </overview> <reference> - **Components overview**: https://docs.convex.dev/components - **Understanding**: https://docs.convex.dev/components/understanding - **Using**: https://docs.convex.dev/components/using - **Authoring**: https://docs.convex.dev/components/authoring - **Directory**: https://convex.dev/components </reference> <context name="Component References"> You SHOULD consult these reference files for specific component knowledge: - `references/agent.md` — Agent component: threads/messages, streaming, tools, context, debugging, usage tracking, and install/setup. - `references/rag.md` — RAG component: namespaces, add/search/generateText, filters, chunking, prompt vs tool RAG. - `references/workpool.md` — Workpool component: enqueue, retries, onComplete, parallelism, batching, monitoring. - `references/workflow.md` — Workflow component: durable steps, events, retries, status, cancel/cleanup, limits. </context> <rules>

<overview> 使用Convex Components添加独立的后端功能并组合组件API。 </overview> <reference> - **组件概览**：https://docs.convex.dev/components - **组件详解**：https://docs.convex.dev/components/understanding - **组件使用**：https://docs.convex.dev/components/using - **组件编写**：https://docs.convex.dev/components/authoring - **组件目录**：https://convex.dev/components </reference> <context name="组件参考文件"> 你应查阅这些参考文件以获取特定组件的相关知识： - `references/agent.md` — Agent组件：线程/消息、流式传输、工具、上下文、调试、使用跟踪以及安装/设置。 - `references/rag.md` — RAG组件：命名空间、添加/搜索/生成文本、过滤器、分块、提示词与工具RAG。 - `references/workpool.md` — Workpool组件：入队、重试、onComplete、并行处理、批处理、监控。 - `references/workflow.md` — Workflow组件：持久化步骤、事件、重试、状态、取消/清理、限制。 </context> <rules>

Mental Model

心智模型

Components are isolated mini backends with their own schema, tables, file storage, and functions.
Components MUST NOT access app tables/functions/env unless passed explicitly.
Calls into components are transactional with the caller, but component mutations are sub-transactions.

组件是独立的迷你后端，拥有自己的schema、表、文件存储和函数。
组件不得访问应用的表/函数/环境变量，除非被显式传入。
对组件的调用与调用者保持事务性，但组件的变更属于子事务。

Installing Components

安装组件

Install package:
```
npm i @convex-dev/<component>
```
.

Add

convex/convex.config.ts

import { defineApp } from "convex/server";

app.use(component)

; use

app.use(component, { name: "custom" })

for multiple instances.

You MUST run
```
npx convex dev
```
to generate component code.
Access via
```
components.<name>
```
in
```
convex/_generated/api
```
.

安装包：
```
npm i @convex-dev/<component>
```
。

添加

convex/convex.config.ts

：

import { defineApp } from "convex/server";

app.use(component)

；若要创建多个实例，使用

app.use(component, { name: "custom" })

。

你必须运行
```
npx convex dev
```
以生成组件代码。
通过
```
convex/_generated/api
```
中的
```
components.<name>
```
访问组件。

Calling Component APIs

调用组件API

Use

ctx.runQuery/Mutation/Action

with

components.<name>.<fn>

Public component functions MUST NOT be called directly from clients (they are internal references).
Queries remain reactive; mutations are transactional.

使用

ctx.runQuery/Mutation/Action

配合

components.<name>.<fn>

。

不得直接从客户端调用公共组件函数（它们是内部引用）。
查询保持响应式；变更具备事务性。

Transaction Semantics

事务语义

Top-level mutation commits all writes across components together.
If a component mutation throws, only its writes are rolled back; the caller MAY catch and continue.

顶层变更会提交所有跨组件的写入操作。
如果组件变更抛出异常，仅回滚该组件的写入；调用者可捕获异常并继续执行。

Component API Differences

组件API差异

```
components.<name>
```
exposes ONLY public component functions.
```
Id
```
types cross boundaries as
```
string
```
; You MUST NOT use
```
v.id("table")
```
for external tables.
Each component has its own
```
_generated
```
directory; You MUST use the app's
```
components
```
references.

```
components.<name>
```
仅暴露公共组件函数。
```
Id
```
类型跨边界时以
```
string
```
形式存在；不得对外部表使用
```
v.id("table")
```
。
每个组件都有自己的
```
_generated
```
目录；必须使用应用的
```
components
```
引用。

Environment Variables

环境变量

Components MUST NOT access
```
process.env
```
directly.
You MUST pass env values as arguments from the app, or store config in a component table.

组件不得直接访问
```
process.env
```
。
你必须从应用中传入环境变量值，或在组件表中存储配置。

HTTP Actions

HTTP动作

Components MUST NOT expose routes directly; app MUST mount handlers in
```
convex/http.ts
```
.

组件不得直接暴露路由；应用必须在
```
convex/http.ts
```
中挂载处理程序。

Auth in Components

组件中的认证

```
ctx.auth
```
is NOT available inside component functions.
You MUST authenticate in the app and pass identifiers (userId) to component functions.

组件函数内部无法使用
```
ctx.auth
```
。
你必须在应用中完成认证，然后将标识符（userId）传入组件函数。

Pagination

分页

Built-in
```
.paginate()
```
is NOT supported inside components.
You SHOULD use
```
convex-helpers
```
paginator and
```
usePaginatedQuery
```
from convex-helpers if needed.

组件内部不支持内置的
```
.paginate()
```
。
如有需要，应使用
```
convex-helpers
```
分页器和来自convex-helpers的
```
usePaginatedQuery
```
。

Authoring Components

编写组件

Component folder MUST include
```
convex.config.ts
```
,
```
schema.ts
```
, functions, and
```
_generated
```
.
```
defineComponent("name")
```
defines component; use
```
component.use(...)
```
for child components.
Local components MAY live in
```
convex/components/
```
or any folder.

NPM components SHOULD export:

```
@pkg/convex.config.js
```
```
@pkg/_generated/component.js
```
```
@pkg/test
```
helpers

组件文件夹必须包含
```
convex.config.ts
```
、
```
schema.ts
```
、函数以及
```
_generated
```
。
```
defineComponent("name")
```
用于定义组件；使用
```
component.use(...)
```
引入子组件。
本地组件可存放于
```
convex/components/
```
或任意文件夹。

NPM组件应导出：

```
@pkg/convex.config.js
```
```
@pkg/_generated/component.js
```
```
@pkg/test
```
辅助工具

Function Handles

函数句柄

You SHOULD use
```
createFunctionHandle(api.foo.bar)
```
to pass callbacks across boundaries.
Handles are strings; use
```
v.string()
```
validators and cast back to
```
FunctionHandle
```
.

你应使用
```
createFunctionHandle(api.foo.bar)
```
在边界之间传递回调。
句柄为字符串类型；使用
```
v.string()
```
验证器并转换回
```
FunctionHandle
```
。

Testing Components

测试组件

You SHOULD register component with
```
convex-test
```
using component schema/modules or provided test helpers.
For component packages, You SHOULD use
```
@pkg/test
```
register helper.

你应使用组件的schema/模块或提供的测试辅助工具，通过
```
convex-test
```
注册组件。
对于组件包，你应使用
```
@pkg/test
```
注册辅助工具。

Best Practices

最佳实践

You MUST always validate args/returns on public component functions.
You SHOULD prefer app-level wrappers to add auth/rate limiting when re-exporting component APIs.
You SHOULD use a single-row globals/config table for static configuration.

</rules>

必须始终验证公共组件函数的参数/返回值。
重新导出组件API时，应优先通过应用级包装器添加认证/速率限制。
应使用单行全局/配置表存储静态配置。

</rules>