内容管理

一个支持集合、条目、语言区域和发布版本的 headless CMS。通过 Content 面板或 SDK 管理内容。

Proyecta 内置完整的 headless CMS，采用 schema 优先的设计：你先定义集合（结构化内容类型），再创建符合各集合字段规范的条目。条目可进行本地化处理，并归组到发布版本中统一管理。

Content 面板

内容可通过 SDK 管理，也可以直接向 AI 提问来操作。Content API 共有六种资源类型：

标签页 / 资源	用途
Collections	定义和管理内容 schema（例如”博客文章”、“常见问题”、“产品规格”）
Fields	集合中的类型化字段槽（作为 Collections 的子资源管理）
Entries	在集合中浏览、创建、编辑、发布和删除条目
Locales	添加和管理用于翻译内容的语言/地区区域设置
Releases	将条目归组，统一上线（或下线）；通过 `releases.publish()` 手动发布
Assets	上传和管理可在条目中引用的媒体文件（图片、视频、PDF）

在 Collections 标签页中点击某个集合，即可跳转到其条目列表。Entries 标签页支持创建、编辑、发布和删除单个内容项。

你也可以通过 SDK（proyecta.content）以编程方式管理所有内容。

核心概念

概念	说明
Collection	一种 schema，定义某类内容的数据结构（例如”博客文章”、“常见问题”、“产品规格”）
Field	集合中的类型化字段槽（例如 `title: string`、`body: rich_text`、`coverImage: asset`）
Entry	集合的单个实例（一篇博客文章、一条 FAQ 记录）
Asset	可在条目中引用的已上传媒体文件
Locale	内容被翻译成的语言/地区
Release	一组计划在同一时间上线（或下线）的条目

快速上手

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

// 1. 定义一个集合
const blog = await proyecta.content.collections.create({
    api_id: 'blogPost',
    name: 'Blog Post',
    // 字段通过 collections.fields.create() 添加
});

// 2. 创建一个条目
const post = await proyecta.content.entries.create({
    collection_id: blog.id,
    data: {
        title: 'Hello, world',
        body: 'My very first post.',
    },
});

// 3. 发布条目
await proyecta.content.entries.publish({ entryId: post.id });

集合

// 浏览集合列表
for await (const collection of proyecta.content.collections.list()) {
    console.log(collection.name);
}

// 为集合添加或删除字段
await proyecta.content.collections.fields.create(blog.id, {
    /* 字段定义 */
});
await proyecta.content.collections.fields.delete(blog.id, fieldId);

条目

条目是实际的内容数据行。每个条目归属于某个集合，并携带与该集合字段匹配的数据。

// 浏览条目（传入集合的 api_id，而非其数字 id）
for await (const entry of proyecta.content.entries.list({ collection: 'blogPost' })) {
    console.log(entry);
}

// 更新条目
await proyecta.content.entries.update(post.id, { data: { title: 'Updated title' } });

// 发布条目
await proyecta.content.entries.publish({ entryId: post.id });

// 删除条目
await proyecta.content.entries.delete(post.id);

资产文件

资产文件上传是一等公民——使用它们可以将图片、视频或 PDF 附加到你的条目中：

// 浏览资产文件列表
for await (const asset of proyecta.content.assets.list()) {
    console.log(asset);
}

// 通过 assets.create / assets.update / assets.delete 上传、更新或删除

如需通过对话界面上传文件（拖拽至 Builder），请参阅文件与媒体。

本地化

内容可以被翻译为多种语言区域。每个语言区域都是一条通过 proyecta.content.locales 管理的记录：

await proyecta.content.locales.create({
    /* code、name 等 */
});

for await (const locale of proyecta.content.locales.list()) {
    console.log(locale);
}

获取条目时，你可以请求特定语言区域的翻译版本。有关完整的 i18n 方案，请参阅国际化。

发布版本

**发布版本（Release）**是一批同时上线（或下线）的条目集合。这让你可以为一次协调一致的内容发布——营销上线、新产品页面、FAQ 更新——做好预发布准备，并实现原子性切换。

注意： 定时自动发布功能尚未实现。设置了 scheduled_at 日期的发布版本会进入 scheduled 状态，但仍须通过 releases.publish() 手动发布。指定时间自动发布的功能即将推出。

// 创建发布版本（可选择指定目标日期）
const release = await proyecta.content.releases.create({
    name: 'Monday launch',
    scheduled_at: '2024-01-08T09:00:00Z',
});

// 就绪后手动发布
await proyecta.content.releases.publish({ releaseId: release.id });

// 浏览发布版本列表
for await (const r of proyecta.content.releases.list()) {
    console.log(r);
}

如需修改发布版本的计划时间，请删除后重新创建——目前不提供更新 endpoint。

常见使用模式（让 AI 帮你搭建）

"使用 Proyecta Content API 搭建一个博客。集合'Blog Post'包含以下字段：title、slug、excerpt、body（富文本）、coverImage（资产文件）、author。公开路由为 /blog 和 /blog/[slug]。"
"在 Proyecta Content 中创建一个 FAQ 集合。搭建一个可添加/编辑 FAQ 的管理页面，以及一个公开的 /faq 页面。"
"使用 Proyecta Content 搭建一个支持英语和西班牙语的多语言落地页。"
"创建一个包含三篇博客文章的发布版本，并在就绪后手动发布。"

Content API 与 Database 的选择

使用场景	推荐方案
编辑类内容（文章、FAQ、营销文案）——需要发布/草稿状态、定时发布、本地化	Content API
应用数据（用户、订单、明细项）——需要查询性能、事务支持、实时更新	Database
代码中的静态资源	项目中的 `public/` 目录
用户上传的文件	文件与媒体

即将推出

富文本条目编辑器 —— 在 Content 面板中为 rich_text 字段提供完整的所见即所得编辑体验
内容变更实时预览 —— 直接在你的应用中预览内容修改效果
内容角色权限 —— 将编辑权限与开发者权限分离管理