` (与 `as`(中文(简体) ) |
| `` | `ImageValue` | `![]()
` |
三个都拿A `field` 道具并读 `name` 从它。 传递任何额外的道具( E)`className`, (中文(简体) ), `loading`(等等),然后他们去完成 的元素.
```tsx
` 仅限scalar。 通过列表是一个类型错误 :
```tsx
// ✗ Field is not assignable to Field
` 使内线 ``,从没有标题或段落,所以你提供周围的语义标记:
```tsx
// ✓
` 是例外:它拥有块元素,而且 `as` 选哪一个.
```tsx
// ✓ — default is
`页:1 `<meta>` 标记,一个属性,或者它位于相互作用后方(一个闭合手风琴,一个自动演奏的旋转木马). 在作曲器中,您仍然需要作者可以点击的东西 .
`useInComposer()` 告诉你你在哪个模式:
```tsx
import { Field, Image, useInComposer } from '@amplifyup/sdk/react';
export function HeroBackground({ fields }: { fields: Fields<{ heading: string; image: ImageValue }> }) {
const inComposer = useInComposer();
return (
<section
className="hero"
style={{ backgroundImage: `url(${fields.image.value?.url ?? ''})` }}
>
{/* Live: image is a CSS background. Composer: also render it so it's clickable. */}
{inComposer ? <Image field={fields.image} className="hidden" /> : null}
<h1><Field field={fields.heading} /></h1>
</section>
);
}
```
其他常见案件:
```tsx
// Attribute on the live site, editable in Composer
const inComposer = useInComposer();
return (
<>
<button aria-label={fields.label.value ?? undefined}>
<Icon />
{inComposer ? <Field field={fields.label} /> : null}
</button>
</>
);
```
```tsx
// Component that hides itself when empty on live, but stays visible for authors
export function Announcement({ fields }: { fields: Fields<{ message: string }> }) {
const inComposer = useInComposer();
if (!fields.message.value && !inComposer) return null;
return <div className="announcement"><Field field={fields.message} /></div>;
}
```
```tsx
// Interaction that fights the canvas — turn it off in Composer
export function Carousel({ fields }) {
const inComposer = useInComposer();
return (
<>
{(fields.slides.value ?? []).map((slide) => (
<Slide key={slide.id} slide={slide} autoplay={!inComposer} />
))}
</>
);
}
```
拇指规则 :
- 这个 **字段组件在作曲器中是真理的来源.** 如果一个字段可以被作者看到,则必须通过 `<Field>` 编号 : `<RichText>` 编号 : `<Image>` 即使现场读取 `.value`。 。 。 .
- **别把整个部件都叉了.** 区分一个不同的要素,而不是整个返回。 两棵不同的树漂流,预览会停止匹配出产.
- **空格法用途 `inComposer`。 。 。 .** `if (!x.value) return null` 他们不能点击没有显示的东西。 添加 `&& !inComposer`。 。 。 .
- **不要用它来隐藏可编辑的文本在直播上.** 如果文本在现场站点上可见,则在两种模式中将其与字段部分并列. `useInComposer` 是为了满足 现场标记 真正不能暴露为田地.
```tsx
// ✗ — heading is visible on live; no reason to fork
{inComposer ? <Field field={fields.heading} /> : fields.heading.value}
// ✓
<Field field={fields.heading} />
```
* * *
## 名单
每个对象阵列都是记录列表. 每行都是字段对象加平原 `id`编辑 `post.title` 在网格中,您正在编辑文章。 哪些记录在列表中,以及它们的顺序,在道具面板中被编辑——不在画布上.
Scalar 列表( 标签, 多选择) 保持平原 : `fields.tags` 实值 `Field<string[]>`。 。 。 .
```tsx
import { Field, Image, RichText } from '@amplifyup/sdk/react';
export function LatestPosts({ fields }: { fields: Fields<{ heading: string; posts: Post[] }> }) {
const posts = fields.posts.value ?? [];
return (
<section>
<h2><Field field={fields.heading} /></h2>
<ul>
{posts.map((post) => (
<li key={post.id}>
<Image field={post.mainImage} />
<a href={`/blog/${post.slug}`}>
<Field field={post.title} />
</a>
</li>
))}
</ul>
</section>
);
}
```
```tsx
// ✗ — Field expects a scalar, not the list or the row
<Field field={fields.posts} />
<Field field={post} />
// ✓ — edit the record through its fields
<Field field={post.title} />
<Image field={post.mainImage} />
```
搜索或加载多行 `queryContent` 形状相同。 使其具有相同的组件——两种部件的一个渲染器:
```tsx
const posts = hits ?? fields.posts.value ?? [];
return posts.map((post) => (
<article key={post.id}>
<h2><Field field={post.title} /></h2>
</article>
));
```
### 可编辑行时
当SDK知道它来自哪个唱片时,一行是可以编辑的. 这在两种情况下是自动发生的:
| 单行来自 | 可用作曲器编辑吗 ? |
| --- | --- |
| 您组件上的列表道具( 已校验或查询连接) | 对 |
| `queryContent` 使用已公布的光谱 `{field}Pagination.spec` | 对 |
| `queryContent` 用手组装的光谱 丢失 `providerId` 或者说 `entity` | 否- 以纯文本形式制作 |
| 你从CMS中取出并传递到的道具 | 否- 以纯文本形式制作 |
只读行仍然在现场和作曲器上渲染出自己的文字. 他们只是不能点击, 在开发 SDK 日志一次每个字段:
```
[AmplifyUp SDK] title has no write target; rendered read-only.
```
如果您看到这个并期望一个可编辑的字段, 固定是上游的—— 使用已公布的光谱而不是手建的光谱, 或者将列表绑定在作曲器中的连接上 。 不尝试添加 `ref` 你自己来.
```tsx
// ✓ — spec comes from the list prop Composer published; rows stay editable
const hits = await queryContent({
trackingId,
route: '/insights',
spec: searchSpec(postsPagination, 'title', term),
});
// ✗ — hand-built spec with no connection behind it; rows render read-only
const hits = await queryContent({
trackingId,
route: '/insights',
spec: { providerId: '', entity: '', filter: [], sort: [], limit: 10, offset: 0 },
});
```
* * *
## 槽数
一个槽是作者放弃其他组件的区域. 把它给 `<Slot>`数字 :
```tsx
import { Slot } from '@amplifyup/sdk/react';
export function TwoColumn() {
return (
<div className="grid grid-cols-2">
<div><Slot name="left" /></div>
<div><Slot name="right" /></div>
</div>
);
}
```
`<Slot>` 仅使用 `name` 财务报告和审定财务报表 `className`。SDK在制作时将每个组件的槽内容交给它,所以你从不线程 `slots` 通过您的组件 .
```tsx
// ✗ — Slot has no `slots` prop
<Slot name="left" slots={slots} />
// ✓
<Slot name="left" />
```
槽名必须匹配在 AmplifyUp 中组件上声明的槽. 槽中含有组件, 而不是字段—— 槽中的任何内容都无法读取 `fields`。 。 。 .
* * *
## 这样做/不要
| 执行 | 别 |
| --- | --- |
| `<Field field={fields.heading} />` | `<Field field={fields.heading} name="heading" />` |
| `{fields.heading.value}` 非可见用途 | `{fields.heading}` 作为JSX儿童(这是一个物体) |
| `{fields.x.value ?? 'default'}` 在代码中 | 期望 SDK 提供默认副本 |
| `if (!fields.x.value) return null` 隐藏组件 | 关闭 `Field` 在编译器中隐藏字段的有条件逻辑中 |
| `<h1><Field … /></h1>` | 寻找一个 `as` 编号 : `wrapper` 道具 |
| `<Field field={post.title} />` 列表中 | `<Field field={fields.posts} />` 或者说 `<Field field={post} />` |
| `value` + 键 `name` 一起计算产出 | `value` 独自一人,或 `name` 一个人 |
| `<Image field={fields.cover} />` | `<img src={fields.cover.value.url} />` 何时可以编辑 |
| `queryContent` 横行 `<Field field={post.title} />` | 将查询行作为原始 CMS 对象 |
| `spec: searchSpec(postsPagination, …)` 从已公布的列表道克 | 手建一个 `spec` 并期望行保持可编辑 |
| `<Slot name="left" />` | `<Slot name="left" slots={slots} />` |
| 让制片人设定 `ref` | 设定、复制或补丁 `ref` 你自己来 |
| `useInComposer()` 以显示一个无法显示的字段( CSS 背景、 属性、 隐藏面板) | 整个部件的回放 `inComposer` |
| `if (!x.value && !inComposer) return null` | `if (!x.value) return null` ——作者不能点击未渲染的内容 |
* * *
## 主机消息
在开发中,SDK会告诉你什么是错的。 生产无声.
| 消息 | 这是什么意思 | 修补 |
| --- | --- | --- |
| `Field expects a scalar field. Did you mean <Field field={post.title} />?` | 你通过了一个名单或一整行 `Field` 编号 : `RichText` 编号 : `Image` | 从一行取出一个平板球 |
| `title has no write target; rendered read-only.` | SDK 无法追踪记录的行字段 | 将列表绑入连接, 或与已公布的光谱查询 |
| `Field value={…} requires name="…" for computed values` | 你通过了 `value` 无 `name` | 添加 `name={fields.x.name}` |
| `Field needs field={fields.yourProp} (or value + name for computed values)` | 没有约束力 | 过 `field=` |
| `Slot "left" only works inside a component rendered from your component registry` | `Slot` 用于SDK未渲染的组件中 | 使用 `Slot` 只有组件文件夹中的组件 |
| `No component in your component registry matches "Hero"` | 页面使用您网站没有的组件 | 添加 `Hero.tsx` (或匹配名称)到您的组件文件夹 |
| `renderComponent was removed in @amplifyup/sdk 0.2.0` | 0.1的代码仍在传递渲染函数 | 跟随 [从0.1升级](https://npmcn.com/package/%40amplifyup/sdk/#readme-upgrading-from-01) |
* * *
## 类型
```ts
import type { Field, Fields, ImageValue } from '@amplifyup/sdk/react';
type Field<T> = {
value: T;
name: string;
/** Write target — the record this field saves to. Page fields omit it. */
ref?: { providerId: string; entity: string; id: string };
/** Row field with no write target — display only in Composer. */
readOnly?: true;
};
type Fields<T> = { [K in keyof T]: /* Field<T[K]>, recursing into objects and lists */ };
```
在组件上宣布一次图案形状
```ts
type HeroFields = Fields<{
eyebrow: string;
heading: string;
body: string; // markdown → use <RichText>
image: ImageValue; // → use <Image>
posts: Post[]; // list — each row is Fields<Post> & { id: string }
tags: string[]; // scalar list — Field<string[]>
}>;
export function Hero({ fields }: { fields: HeroFields }) { … }
```
`fields.heading.value` 实值 `string`。 。 。 . `fields.image.value` 实值 `ImageValue | null`。 。 。 . `fields.posts.value[0]` 实值 `Fields<Post> & { id: string }`。 。 。 . `fields.posts.value[0].title` 实值 `Field<string>` 与 `ref` 指着那个位置.
* * *
## 内容来源
| 模式 | 来源 | 何时 |
| --- | --- | --- |
| 制作访问者 | 边缘 `/v1/resolve` | 默认 |
| Next.js SSG / 简要记录 | 边缘 `/v1/routes` 接下来 `/v1/resolve` | `generateAmplifyStaticParams` + 键 `fetchPageConfigServer` |
| 作曲家预览 | 控制平面布局提供者 | `?preview=true` / 作曲家 Iframe |
| 运行时间查询 | 边缘 `/v1/query` | `queryContent` - 搜索,加载,拾取者 |
当SDK读取"边缘"的响应时,现场信封会被附上一次. 边缘的JSON是生的,你永远不会看到它 如果你走过 `AmplifyPageContent` 或者说 `fetchPageConfigServer`。如果你拨打 `fetchEdgeResolve` 直接获得原始道具,必须亲自绘制地图——更喜欢有文件记载的路径.
## 图案页面(从页面)
使用作曲器的组件 **从页面** 需求 `pageContext` 关于提供者(或 `init`),所以第一个颜料和第一个页面视图包括了字段. 迟到 `setPageContext` 对于以后的事件,而不是制造这些组件,是罚款的.
`resource.key` 是 URL 参数值。 如果映射的实体字段( 例如 ) `post.slug`)不匹配该参数,SDK警告并使用URL参数.
```tsx
<AmplifyUpProvider
config={{ trackingId: 'your-tracking-id' }}
pageContext={{
resourceType: 'post',
key: slug,
fields: { title: post.title, slug: post.slug, category: post.category },
}}
>
{children}
</AmplifyUpProvider>
```
过 `pageContext` 在From页面组件的提供者/init。 别等到第一次油漆之后 当 `pageContext` 省略.
SDK将边缘的溶解树映射到 `layoutTree` 并让它。 Edge已经应用了个性化和CMS投影——网站不调用CMS或Decision API来进行布局. 画完后,就打给大家 `POST /v1/select` (或 `selectVariants()`) 那么,(笑声) `/v1/resolve?variants=` 因此,决定处于边缘(`clientPersonalization`) (中文(简体) ).
将您的整个网站包入 `AmplifyUpProvider` 所以每一页都有追踪 覆盖只运行在渲染的页面上 `AmplifyPageContent` (或 `AmplifyRenderer` 无 `pageConfig`) (中文(简体) ). 自己创建的页面会被跟踪,但从不要求布局.
## 运行时间查询
页面解析涵盖部署时已知的数据。 对于访问者要求的数据——搜索,加载更多,取取取器——使用 `queryContent`。浏览器询问 AmplifyUp, AmplifyUp 询问您的内容源, 因此您的网站中没有 CMS 证书或查询语法 .
标记查询连接 **标注** 在编译器和列表中的 prop 增益 pagination meta 中,包括已公布的查询光谱 :
```tsx
'use client';
import { queryContent, nextPageSpec, searchSpec } from '@amplifyup/sdk/react';
// next page
const more = await queryContent({
trackingId,
route: '/insights',
spec: nextPageSpec(postsPagination),
});
// search — keep `?q=` as input only; do not read searchParams on the server page
const hits = await queryContent({
trackingId,
route: '/insights',
spec: searchSpec(postsPagination, 'title', term),
});
```
只有发布该路径的实体才能被询问,访问者只看到发布的内容. 也可查阅: `@amplifyup/sdk/server`见 [运行时间查询指南](https://npmcn.com/package/docs/sdk-site-setup.md#8-runtime-content-queries)。 。 。 .
**总是从 `postsPagination.spec`。 。 。 .** `nextPageSpec` 财务报告和审定财务报表 `searchSpec` 这样做你。 该 spec 识别连接, 所以返回的行可以在 Composer 中编辑 —— 见 [可编辑行时](https://npmcn.com/package/%40amplifyup/sdk/#readme-when-a-row-is-editable)。用手组装的光谱后面没有连接,所以它的行只读即可返回.
## 跟踪活动
```typescript
import { init, page, track, identify } from '@amplifyup/sdk';
await init({ trackingId: 'your-tracking-id' });
page('/home');
track('Product Viewed', { productId: '123' });
identify('user-123', { email: 'user@example.com' });
```
## 访客同意
所以形式答案只留给同意的访客:
```typescript
import { setConsent } from '@amplifyup/sdk';
// When the visitor accepts or rejects in your banner:
setConsent('granted'); // or 'denied'
// To forget the choice:
setConsent(null);
```
选择在浏览器中被记住,并随每个表单提交而发送. 然后打开 **我同意的旗子上写着"放大"** 在表格中, 直到你这样做, 放大UP对待一个访客 谁同意与谁没有.
## 调试
```js
AmplifyUp.getStatus()
```
反应上下文 : `useAmplifyUp()` → `{ pageConfig, loading, error, source, meta }`。 。 。 .
## 许可证
麻省理工学院
## 常见问题
### @amplifyup/sdk 是什么？
放大跟踪 SDK - CDP - 不可知事件跟踪库
### 如何安装 @amplifyup/sdk？
在项目目录运行 npm install @amplifyup/sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @amplifyup/sdk 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @amplifyup/sdk 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @amplifyup/sdk 可以商用吗？
@amplifyup/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @amplifyup/sdk 的下载量有多少？
根据 npm 官方下载统计，@amplifyup/sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,478 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @amplifyup/sdk 还在维护吗？
最新版本 0\.3\.3 发布于 2026/11/01（6 天前）；至今共发布 95 个版本，其中过去 12 个月发布了 95 个；首次发布于 2026/02/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。
{fields.subheading.value ?? 'Built for teams that ship.'}
// ✓ hide the whole component when the key field is empty export function Banner({ fields }: { fields: Fields<{ message: string }> }) { if (!fields.message.value) return null; return