# @opengovsg/confetti 中文文档

规范地址：https://npmcn.com/package/%40opengovsg/confetti/

版本：0\.9\.7
npm 元数据更新时间：2026-11-02T02:27:16.768Z
中文译文更新时间：2026-11-02T02:54:52.515Z
软件包许可：SEE LICENSE IN LICENSE\.md

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40opengovsg/confetti
原文对照：https://npmcn.com/package/%40opengovsg/confetti/?lang=original
项目主页：https://github.com/opengovsg/confetti
源码仓库：https://github.com/opengovsg/confetti

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：761 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2026-01-22T10:18:42.223Z
- 最新版本发布：2026-11-02T02:27:16.573Z
- 已发布版本数：84（近 12 个月 84 个）

## 中文简介

五彩纸屑的小部件

## 安装

```sh
npm install @opengovsg/confetti
```

也可以使用：`pnpm add @opengovsg/confetti`、`yarn add @opengovsg/confetti`、`bun add @opengovsg/confetti`

## README

# @opengovsg /糖果

可嵌入的React调查小部件，用于收集用户反馈。

[![npm version](https://img.shields.io/npm/v/@opengovsg/confetti.svg)](https://www.npmjs.com/package/@opengovsg/confetti)

## 安装

```bash
# npm
npm install @opengovsg/confetti

# yarn
yarn add @opengovsg/confetti

# pnpm
pnpm add @opengovsg/confetti
```

### 同行依赖性

此包需要React 18.2.0+或React 19：

```bash
npm install react@^18.2.0
```

## 快速入门

1.  将小部件添加到您的页面：

```tsx
import { PopoverConfetti } from '@opengovsg/confetti'

function App() {
  return (
    <div style={{ position: 'fixed', bottom: '1rem', right: '1rem' }}>
      <PopoverConfetti
        surveyId="your-survey-id"
        publishableKey="your-publishable-key"
        metadata={{}}
      />
    </div>
  )
}
```

模板组件加载脚本包和样式表 运行时的CDN，这是 **没有CSS要导入** -包括 主机渲染触发器按钮，其中 `TriggerPopoverConfetti` 风格本身。( 较低级别的 [`@opengovsg/confetti/components`](https://npmcn.com/package/%40opengovsg/confetti/#readme-building-blocks) 原语和 这个 `@opengovsg/confetti/static` 选择退出表面渲染在你自己的bundle和 仍然需要 `import '@opengovsg/confetti/confetti.css'`.）

> **注意：** 您将需要调查ID和可发布密钥从您的五彩纸屑仪表板。确保在团队设置中将您的域列入白名单。

### 分析元数据

默认情况下，禁用Analytics元数据收集。集 `autoInjectAnalyticsMetadata` 来 `true` 公开的标识符 在主机页面上发布每个响应的thog和Datadog RUM：

```tsx
<PopoverConfetti
  surveyId="your-survey-id"
  publishableKey="your-publishable-key"
  autoInjectAnalyticsMetadata
/>
```

小部件从中读取这些sdk `window.posthog` 和 `window.DD_RUM`，而它 从不捆绑任何一个SDK。 `@datadog/browser-rum` 分配 `window.DD_RUM` 用于 一旦导入，您就可以使用它，所以Datadog不需要额外的设置。

**postthog是不同的——你必须自己曝光。** 它 [文档](https://posthog.com/docs/libraries/js/usage#exposing-the-posthog-global-object-to-the-browser-console) 这是大多数现代应用程序所不具备的 `window.posthog`，所以把它分配到你的任何地方 预置PostHog:

```ts
import posthog from 'posthog-js'

posthog.init('<your-project-token>', { api_host: '<your-api-host>' })

window.posthog = posthog
```

缺少SDK的任何标识符都将被跳过，因此仍然是部分设置 提交其余部分。这些键在可用时收集：

| 关键 | 来源 |
| --- | --- |
| `posthog_distinct_id` | `posthog.get_distinct_id()` |
| `posthog_session_id` | `posthog.get_session_id()` |
| `datadog_rum_session_id` | `DD_RUM.getInternalContext()` |
| `datadog_rum_user` | `DD_RUM.getUser()`， JSON字符串化 |
| `datadog_rum_user_id`， `datadog_rum_user_email`， `datadog_rum_user_name` | `DD_RUM.getUser()` 标准字段 |

传递的显式值 `metadata` 总是优先于 自动收集值。

使用Datadog会话ID在Datadog会话浏览器中查找会话 与 `@session.id:<datadog_rum_session_id>`.

2.  在CSP标题中添加五彩纸屑。小部件从CDN加载它的脚本和样式表并调用API，所以allowlist全部三个：

```
script-src https://confetti.gov.sg;
style-src https://confetti.gov.sg;
connect-src https://confetti.gov.sg;
```

### 代理请求

每个模板组件都接受一个可选的 `proxyUrl`。设置后，小部件 将其API请求发送到 `{proxyUrl}/api/v1/cfti/...` 而不是 `https://confetti.gov.sg`，而cdn支持的shell也会加载它们的脚本 和样式表 `{proxyUrl}/widget/v1/...`。使用这个来路由小部件 通过您自己的来源的流量，例如当您的CSP拒绝第三方 方主机。

contfetti Cloud团队可以从 **团队设置**. 创建此处显示的仅限dns的CNAME，并等待它变为活动状态，然后通过 生成的URL。如果主机名在Cloudflare DNS中，禁用橙色 云所以 **代理地位** 是 **DNS只** -参见 [托管代理指南](https://docs.confetti.gov.sg/docs/developers/managed-proxies).

```tsx
<PopoverConfetti
  proxyUrl="https://c.example.gov.sg"
  surveyId="..."
  publishableKey="cfti_pk_..."
/>
```

当使用托管代理时，请为所示的所有三个CSP指令使用该源 上面而不是 `https://confetti.gov.sg`.

## 模板组件

选择最适合您用例的组件：

| 组件 | 用例 | 行为 |
| --- | --- | --- |
| `EmbeddedConfetti` | 内联调查，反馈部分 | 通过提交按钮以内联方式显示问题 |
| `ModalConfetti` | 中断的、集中的调查 | 中心模式叠加，一步一步的问题，自动提交 |
| `PopoverConfetti` | 浮动反馈部件 | 不允许弹出窗口，一步一步的问题，自动提交 |
| `TriggerPopoverConfetti` | 反馈启动按钮 | 呈现一个触发按钮，在单击时打开一个可忽略的弹出窗口调查；reopenable |
| `StepperConfetti` | 引导调查 | 一次一个问题，最后一个问题后自动提交 |

## 语言环境

需要 `@opengovsg/confetti` `0.8.2` 或更高版本。旧版本保留 英语调查-他们不会失败加载。

通过 `locale` 显示翻译后的调查。作者翻译在纸屑 英语永远是来源，汉语、马来语和泰米尔语也是 可选)。未翻译的字段返回到英语。

小部件本身并不读取浏览器语言。使用 `useResolveLocale` 来映射BCP-47标记（或浏览器的语言） 偏好) `'en' | 'zh' | 'ms' | 'ta'`：

```tsx
import { PopoverConfetti, useResolveLocale } from '@opengovsg/confetti'

function Feedback() {
  const locale = useResolveLocale()

  return (
    <PopoverConfetti
      surveyId="your-survey-id"
      publishableKey="your-publishable-key"
      locale={locale}
    />
  )
}
```

通过 `preferred` 当宿主应用程序已经知道区域设置时(例如 next-intl)。通过 `explicit` 即使失败了，也能赢得胜利 匹配一个conffetti区域设置—包括一个空字符串，它返回到 用英语代替 `preferred`：

```tsx
const locale = useResolveLocale({
  preferred: i18n.locale,
  explicit: searchParams.get('locale'),
})
```

要始终显示一种语言，通过 `locale` 直接跳过钩子：

```tsx
<PopoverConfetti
  surveyId="your-survey-id"
  publishableKey="your-publishable-key"
  locale="zh"
/>
```

| 价值 | 语言 |
| --- | --- |
| `en` | 英语(默认) |
| `zh` | 中文 |
| `ms` | 马来语 |
| `ta` | தமிழ் |

插件chrome你没有自定义-跳过，下一步，提交，返回，关闭，其他， 占位符和验证错误-仍然针对给定的语言环境进行本地化。 省略 `locale`，或通过 `'en'`，以保持英语调查。

同样的道具在 [静态](https://npmcn.com/package/%40opengovsg/confetti/#readme-static-components) 组件和 在 [积木](https://npmcn.com/package/%40opengovsg/confetti/#readme-building-blocks) 原语。进口 `useResolveLocale` 从 `@opengovsg/confetti` 在这些设置中也是如此。看到 [翻译指南](https://docs.confetti.gov.sg/docs/surveys/translations).

## 静态组件

这个 `@opengovsg/confetti/static` 子路径船的独立构建 相同的模板组件(`EmbeddedConfetti`， `ModalConfetti`， `PopoverConfetti`， `StepperConfetti`)加上 `ConfettiTrigger` 作文 帮手。它们完全从你自己的包中呈现，没有运行时CDN 依赖，因此调查呈现更新仅在升级时到达您的站点 包。

```tsx
import '@opengovsg/confetti/confetti.css'

import { PopoverConfetti } from '@opengovsg/confetti/static'
```

与支持cdn的shell不同，静态组件需要样式表 如上所示的导入。

## 能见度钩子

控制你的调查何时出现与这些挂钩：

### useVisibleAfterDelay

延迟后显示调查结果：

```tsx
import { useVisibleAfterDelay } from '@opengovsg/confetti'

const { isVisible } = useVisibleAfterDelay({ delay: 5000 }) // 5 seconds
```

### useVisibleAfterScroll

滚动一定距离后显示调查结果：

```tsx
import { useVisibleAfterScroll } from '@opengovsg/confetti'

const { isVisible } = useVisibleAfterScroll({ threshold: 500 }) // 500px
```

### useVisibleAfterPageVisits

一旦访问者加载了给定次数的当前页面（跨会话持续），就显示调查 `localStorage`):

```tsx
import { useVisibleAfterPageVisits } from '@opengovsg/confetti'

const { isVisible, reset } = useVisibleAfterPageVisits({
  visits: 3,
  respondent: 'optional-respondent-identifier',
})
```

### useVisibleAfterSessionPageVisits

如上所述，但访问计数的范围是通过当前浏览器会话 `sessionStorage`：

```tsx
import { useVisibleAfterSessionPageVisits } from '@opengovsg/confetti'

const { isVisible, reset } = useVisibleAfterSessionPageVisits({ visits: 3 })
```

### useRespondentState

在没有模板的情况下，阅读应答者的回复和解雇时间。 `respondent` （此钩子不会生成匿名id）。

```tsx
import { useRespondentState } from '@opengovsg/confetti'

const respondentState = useRespondentState({
  surveyId: '<your-survey-id>',
  publishableKey: '<your-publishable-key>',
  respondent: '<user-id>',
})
```

## 构建块

的底层原语 [模板组件](https://npmcn.com/package/%40opengovsg/confetti/#readme-template-components) 都是从 `@opengovsg/confetti/components` 子路径。利用这些来组成你自己的调查UI。

```tsx
import {
  ConfettiController,
  ConfettiProvider,
  SurveyContext,
  useSurvey,
} from '@opengovsg/confetti/components'
```

与模板组件不同，这些原语在您自己的包中呈现 在你的应用入口点导入一次样式表：

```tsx
import '@opengovsg/confetti/confetti.css'
```

## 常见问题

### @opengovsg/confetti 是什么？

五彩纸屑的小部件

### 如何安装 @opengovsg/confetti？

在项目目录运行 npm install @opengovsg/confetti，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @opengovsg/confetti 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @opengovsg/confetti 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @opengovsg/confetti 可以商用吗？

@opengovsg/confetti 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @opengovsg/confetti 还在维护吗？

最新版本 0\.9\.7 发布于 2026/11/02（1 天前）；至今共发布 84 个版本，其中过去 12 个月发布了 84 个；首次发布于 2026/01/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。