# @flamingo-stack/openframe-frontend-core 中文文档

规范地址：https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/

版本：0\.0\.831
npm 元数据更新时间：2026-11-01T03:20:33.521Z
中文译文更新时间：2026-11-01T04:07:36.656Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40flamingo-stack/openframe-frontend-core
原文对照：https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/?lang=original
项目主页：https://github.com/flamingo-stack/openframe-oss-lib#readme
源码仓库：https://github.com/flamingo-stack/openframe-oss-lib

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

- 包体积（解压后）：42.5 MB，16067 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：102 个
- peer 依赖：zod ^3\.0\.0 \|\| ^4\.0\.0，next ^15\.0\.0 \|\| ^16\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，eslint ^9\.39\.0，prettier ^3\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@hookform/resolvers ^3\.0\.0 \|\| ^4\.0\.0 \|\| ^5\.0\.0，@tanstack/react-query ^5\.0\.0
- 首次发布：2026-02-12T14:58:53.213Z
- 最新版本发布：2026-11-01T03:20:33.298Z
- 已发布版本数：2167（近 12 个月 2167 个）

## 中文简介

所有Flamingo平台的共享设计系统和组件

## 安装

```sh
npm install @flamingo-stack/openframe-frontend-core
```

也可以使用：`pnpm add @flamingo-stack/openframe-frontend-core`、`yarn add @flamingo-stack/openframe-frontend-core`、`bun add @flamingo-stack/openframe-frontend-core`

## README

# @flamingo-stack / openframe-frontend-core

火烈鸟平台（OpenMSP, OpenFrame, Admin Hub, Flamingo Website， TMCG）的共享设计系统和组件库。

## 安装

```bash
npm install https://pkg.pr.new/flamingo-stack/openframe-oss-lib/@flamingo-stack/openframe-frontend-core@<x.y.z>
```

## 使用

### 组件

```tsx
import { Button, Card, Input, Modal, Tag } from '@flamingo-stack/openframe-frontend-core/components/ui'
import { YouTubeEmbed, FigmaPrototypeViewer } from '@flamingo-stack/openframe-frontend-core/components/features'
import { GithubIcon, OpenframeLogoIcon } from '@flamingo-stack/openframe-frontend-core/components/icons-v2'
```

### 钩子

```tsx
import { useDebounce, useMediaQuery, useToast } from '@flamingo-stack/openframe-frontend-core/hooks'
```

### 公用事业公司

```tsx
import { cn, formatDate, formatPrice, getPlatformUrl } from '@flamingo-stack/openframe-frontend-core/utils'
```

### 风格

```tsx
// Import in your layout or _app.tsx
import '@flamingo-stack/openframe-frontend-core/styles'
```

### 顺风配置

在项目中扩展共享的Tailwind配置：

```ts
import designSystemConfig from '@flamingo-stack/openframe-frontend-core/tailwind.config.ts'
import { appStyleSources } from '@flamingo-stack/openframe-frontend-core/style-sources'

export default {
  presets: [designSystemConfig],
  // The files your App Router routes import, yours and this library's: never this library's whole
  // `dist` or `src`, which puts every component's classes in the stylesheet every page blocks on.
  content: appStyleSources({ root: __dirname, appDir: 'src/app' }),
}
```

`appStyleSources` （`scripts/style-sources.cjs`)从路由文件中遍历导入图，摇树 就像你的捆绑者一样。主机可以将惰性加载的聊天从页面的样式表中删除 `firstPaint: true`，并给予 `EmbeddableChat` 一个 `loadStyles` 这将加载构建的完整样式表 没有它（参见文件的头文件）。

然后将样式表发送到每个页面的HTML中，这样页面就不会等待第二次绘制请求， 把它的规模控制在你支票的预算之内。`scripts/next-styles.cjs` 说明原因和成本)：

```js
// next.config.mjs
import { withInlineStyles } from '@flamingo-stack/openframe-frontend-core/next-styles'
export default withInlineStyles(nextConfig)
```

```bash
node node_modules/@flamingo-stack/openframe-frontend-core/dist/build/next-styles.cjs budget \
  --input src/app/globals.css --config tailwind.config.ts --budget 31500
```

## 包出口

| 导出路径 | 描述 |
| --- | --- |
| `.` | 主入口（所有组件、钩子、utils） |
| `./components/ui` | 基本UI组件（按钮、卡片、输入、模态、标签等） |
| `./components/features` | 复杂组件（YouTubeEmbed, FigmaPrototypeViewer, AuthProvidersList） |
| `./components/icons-v2` | 生成的图标集 |
| `./components/navigation` | 导航组件（Header, StickySectionNav） |
| `./components/toast` | 祝酒通知系统 |
| `./hooks` | React钩子（useDebounce, useMediaQuery， useToast等） |
| `./utils` | 实用程序（cn, formatDate, formatPrice, getPlatformUrl, platform-config） |
| `./types` | TypeScript类型定义 |
| `./styles` | CSS样式和ODS设计标记 |
| `./style-sources` | 顺风 `content` 对于一个应用程序：它的路由导入文件(`appStyleSources`） |
| `./next-styles` | 每个页面的HTML (`withInlineStyles`)及其大小门(`measureStylesheet`， `budget` 命令) |
| `./nats` | NATS WebSocket实用程序 |
| `./fonts` | 字体配置 |

## 设计系统（ODS）

该软件包包括开放框架设计系统（ODS），具有：

-   **CSS变量** -将令牌设计为自定义属性
-   **响应排版** - - - - - - `text-h1` 通过 `text-h6` 公用事业通过顺风插件
-   **平台主题** —基于自动色彩适应 `NEXT_PUBLIC_APP_TYPE`
-   **断点** - - - - - - `md: 800px`， `lg: 1280px`， `xl: 1440px` (尝试)

### 顺风归并配置

这个 `cn()` 实用程序扩展 `tailwind-merge` 识别ODS排版类(`text-h1`–`text-h6`)作为一个独立的群体，所以他们不冲突 `text-color` 类:

```tsx
import { cn } from '@flamingo-stack/openframe-frontend-core/utils'

// text-h5 and text-red-500 coexist correctly
cn('text-h5', 'text-red-500') // => "text-h5 text-red-500"
```

## 平台支持

| 平台 | 应用程序类型 | 口音的颜色 |
| --- | --- | --- |
| OpenMSP | `openmsp` | 黄色(# FFC008) |
| OpenFrame | `openframe` | 青色(# 5 efaf0) |
| 火烈鸟 | `flamingo` | 粉色(# FF6B6B) |
| 管理中心 | `admin-hub` | 粉色(# F357BB) |
| 火烈鸟急转弯 | `flamingo-teaser` | 粉红色的 |
| TMCG | `tmcg` | 紫色(# 8 b5cf6) |

平台检测是自动通过 `NEXT_PUBLIC_APP_TYPE` 环境变量。

## 开发

```bash
# Build the package
npm run build

# Build without type declarations (faster)
npm run build:fast

# Watch mode
npm run dev

# Type checking
npm run type-check

# Run tests
npm run test

# Storybook
npm run storybook

# Publish via yalc (local development)
npm run yalc:push
npm run yalc:watch
```

## 体系结构

```
src/
  components/
    ui/           # Base components (Button, Card, Input, Modal, Tag, etc.)
    features/     # Complex components (YouTubeEmbed, FigmaPrototypeViewer)
    icons/        # Centralized icon components
    icons-v2-generated/  # Auto-generated icon set
    navigation/   # Header, StickySectionNav
    toast/        # Toast notification system
  hooks/
    ui/           # UI hooks (useDebounce, useMediaQuery)
    api/          # Data fetching hooks
    platform/     # Platform configuration hooks
  styles/
    index.css     # Main stylesheet
    ods-*.css     # Design token modules
  utils/
    cn.ts         # clsx + tailwind-merge
    platform-config.tsx  # Unified platform configuration
  types/          # TypeScript type definitions
  nats/           # NATS WebSocket integration
```

## 教程

端到端导览 [`docs/`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs)：

-   [`MIGRATING_COMPONENTS.md`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs/MIGRATING_COMPONENTS.md) -如何将组件从hub移动到这个lib（3层模型，桶规则，运行时上下文注入）。
-   [`EMBEDDING.md`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs/EMBEDDING.md) -运行时提供程序(`EndpointsRuntimeContext`， `ChatRuntimeContext`)用于非hub React应用。
-   [`EMBEDDING_DOCS_HUB.md`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs/EMBEDDING_DOCS_HUB.md) ——嵌入 `<DocsHubPage>` （侧边栏树+内容+ RAG搜索栏）在第三方应用程序。hub使用相同的组件在 `/knowledge-base` 和 `/data-room`.
-   [`CHAT_EMBEDDING_TUTORIAL.md`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs/CHAT_EMBEDDING_TUTORIAL.md) -嵌入完整 `<EmbeddableChat>` 面板（向导+明戈模式）。
-   [`EMBEDDING_HUBSPOT_MEETINGS.md`](https://npmcn.com/package/%40flamingo-stack/openframe-frontend-core/docs/EMBEDDING_HUBSPOT_MEETINGS.md) ——嵌入 `<HubSpotMeetingScheduler>` （本土品牌HubSpot预订流）背后的主机代理；包括链接命名约定和代理端点契约。

## 关键依赖关系

-   **18 + / 19反应** -同伴依赖
-   **基数UI** -可访问的组件原语
-   **顺风CSS 3** -样式与自定义设计令牌
-   **类别变更授权** -组件变体管理
-   **筹划者运动** ——动画
-   **Lucide反应** ——图标

## 许可证

用于Flamingo CX项目的私有包。

## 常见问题

### @flamingo-stack/openframe-frontend-core 是什么？

所有Flamingo平台的共享设计系统和组件

### 如何安装 @flamingo-stack/openframe-frontend-core？

在项目目录运行 npm install @flamingo-stack/openframe-frontend-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（^15\.0\.0 \|\| ^16\.0\.0）、react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@tanstack/react-query（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 next-styles，可以用 npx next-styles 直接运行。

### @flamingo-stack/openframe-frontend-core 支持 TypeScript 吗？

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

### @flamingo-stack/openframe-frontend-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flamingo-stack/openframe-frontend-core 可以商用吗？

@flamingo-stack/openframe-frontend-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @flamingo-stack/openframe-frontend-core 还在维护吗？

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