# @gnist/design-system 中文文档

规范地址：https://npmcn.com/package/%40gnist/design-system/

版本：7\.9\.0
npm 元数据更新时间：2026-11-16T14:53:29.810Z
中文译文更新时间：2026-11-16T17:15:05.183Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40gnist/design-system
原文对照：https://npmcn.com/package/%40gnist/design-system/?lang=original

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

- 包体积（解压后）：4.3 MB，2019 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@types/react ^18\.0\.0 \|\| ^19\.0\.0，@types/react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2024-11-08T12:48:50.367Z
- 最新版本发布：2026-11-16T14:53:29.595Z
- 近 30 天下载量：4028（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：170（近 12 个月 63 个）

## 中文简介

`@gnist/design-system` 是一个 react 组件库,包含用于默勒生态系统应用的可重复使用的多品牌图形界面组件.

## 安装

```sh
npm install @gnist/design-system
```

也可以使用：`pnpm add @gnist/design-system`、`yarn add @gnist/design-system`、`bun add @gnist/design-system`

## README

# Møller 多品牌反应组件库

`@gnist/design-system` 是一个 react 组件库,包含用于默勒生态系统应用的可重复使用的多品牌图形界面组件.

关于开发组件的指示,见 [发展文件](https://npmcn.com/package/%40gnist/design-system/#readme-development)。 。 。 .

# 关闭图书馆

图书馆作为 [`@gnist/design-system` 在公共npm登记册中](https://npmcn.com/package/%40gnist/design-system/npmjs.com/package/@gnist/design-system)。前缀 `@moller` 是一个 [npm 范围](https://docs.npmjs.com/cli/v7/using-npm/scope) 与 [我们的组织在npm](https://www.npmjs.com/org/moller)

## 安装库

运行命令

```
npm install @gnist/design-system @gnist/themes
```

## 使用图书馆

要使用库,需要使用香草-提取插件.

### 维特

对于Vite 8,你需要

```
npm install -D @vanilla-extract/vite-plugin @vanilla-extract/rollup-plugin
```

 `vite.config.ts` 也许是这样的:

```ts
// vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { vanillaExtractPlugin as vanillaExtractRollupPlugin } from "@vanilla-extract/rollup-plugin";
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [react(), vanillaExtractPlugin()],
    optimizeDeps: {
        // Gnist publishes JS that imports vanilla-extract .css.js files,
        // so force those packages through Vite 8 prebundling.
        include: ["@gnist/design-system", "@gnist/design-system/**/*"],
        rolldownOptions: {
            plugins: [
                // Handle vanilla-extract file scopes during dep optimization.
                vanillaExtractRollupPlugin({ unstable_injectFilescopes: true }),
            ],
        },
    },
});
```

在应用程序条目点中,导入所需的全局样式并选择主题

```tsx
// app.tsx

import { LocalizationProvider } from "@gnist/design-system";
// Import one or more of these themes
import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";
import { gumpen } from "@gnist/themes/themes/gumpen.css.js";
import { brandless } from "@gnist/themes/themes/brandless.css.js";
import { mollerBil } from "@gnist/themes/themes/mollerBil.css.js";
import { skoda } from "@gnist/themes/themes/skoda.css.js";
import { vw } from "@gnist/themes/themes/vw.css.js";
import { dahles } from "@gnist/themes/themes/dahles.css.js";
import { autoria } from "@gnist/themes/themes/autoria.css.js";
import { audi } from "@gnist/themes/themes/audi.css.js";
import { cupra } from "@gnist/themes/themes/cupra.css.js";
// Import global styles
import { globalTextStyles } from "@gnist/themes/typography.css";
// Import necessary fonts (one or more, dependent on which themes are in use)
import "@gnist/design-system/fonts/moller";
import "@gnist/design-system/fonts/bilhold";
import "@gnist/design-system/fonts/skoda";
import "@gnist/design-system/fonts/gumpen";
import "@gnist/design-system/fonts/VW";
import "@gnist/design-system/fonts/dahles";
import "@gnist/design-system/fonts/autoria";
import "@gnist/design-system/fonts/audi";
import "@gnist/design-system/fonts/cupra";
import "@gnist/design-system/fonts/tools";

// Apply the theme
document.body.classList.add(bilholdLight);

// Apply global styles
globalTextStyles.forEach((c) => {
    document.body.classList.add(c);
});

export const App: React.FC = () => {
    return (
        <LocalizationProvider language="en">
            {/* ...the rest of your app here...*/}
        </LocalizationProvider>
    );
};
```

> 说明: `brandless` 财务报告和审定财务报表 `gnist` 主题用于 **仅内部使用**。两者都使用“Geist”字体家族,所以如果您使用其中任一主题,请导入 `@gnist/design-system/fonts/tools` 作为您的字体.

### Next.js项目

如果你在Next.js项目中设置, 程序相当相同.

您需要安装和使用 `@vanilla-extract/next-plugin`数字 :

```bash
npm install -D @vanilla-extract/next-plugin
```

有了这个安排,你的 `next.config.mjs` 也许是这样的:

```js
// next.config.mjs

import { createVanillaExtractPlugin } from "@vanilla-extract/next-plugin";
const withVanillaExtract = createVanillaExtractPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withVanillaExtract(nextConfig);
```

如果您正在运行一个 React 版本 18 工程, 您还需要在您的 `tsconfig.json` 以便它与这个 React 17 图书馆合作.

```json
// tsconfig.json

"paths": {
     ...
      "react": [ "./node_modules/@types/react"]
    }
```

然后把造型加进你的 `layout.tsx` 文档。 可能是这样的:

```tsx
// layout.tsx

import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";
import { globalTextStyles } from "@gnist/themes/typography.css.js";
import "@gnist/design-system/fonts/bilhold";

const bodyClassList = [bilholdLight, ...globalTextStyles];

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body className={bodyClassList.join(" ")}>{children}</body>
        </html>
    );
}
```

#### 使用组件

最后,从 `@gnist/design-system`数字 :

```js
// index.tsx

import { PrimaryButton } from "@gnist/design-system";

export default function Home() {
    return <PrimaryButton>Hello</PrimaryButton>;
}
```

#### 页面路由器

如果您正在运行 Pages 路由器, 请添加 `transpilePackages` 改为 `next.config.mjs` 用于库代码的 Vanilla 提取 :

```js
// next.config.mjs
const nextConfig = {
    transpilePackages: ["@gnist/design-system", "@gnist/themes"],
};
```

由于页路由器没有 `layout.tsx`,需要将设置在 `pages/_document.tsx` 财务报告和审定财务报表 `pages/_app.tsx`。 。 。 .

`_document.tsx` 在服务器上运行一次。 使用一个 **名称导入** 在此获取主题类:

```js
// _document.tsx

import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";
import { globalTextStyles } from "@gnist/themes/typography.css.js";
import "@gnist/design-system/fonts/bilhold";

const bodyClassList = [bilholdLight, ...globalTextStyles];

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body className={bodyClassList.join(" ")}>{children}</body>
        </html>
    );
}
```

`_app.tsx` 运行在每一个路线变化。 这里,你必须使用 **副作用导入** 对于相同的主题和打字,所以CSS实际上最终会被客户端捆绑:

```js
// _app.tsx

import { LocalizationProvider } from "@gnist/design-system";

// Fonts matching your chosen theme
import "@gnist/design-system/fonts/bilhold";

// Side-effect imports to include CSS/tokens in client bundle
import "@gnist/themes/themes/bilholdLight.css.js";
import "@gnist/themes/typography.css.js";


export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    // Wrap app in LocalizationProvider
    <LocalizationProvider language="en">
      <Component {...pageProps} />
    </LocalizationProvider>
  );
}
```

这确保:

`_document.tsx` 设置正确的主题类开始和 .

`_app.tsx` 将主题的 CSS 变量和打字符装入客户端捆绑中.

## 从 [`@moller/design-system`](https://www.npmjs.com/package/@moller/design-system)

如果您正在从旧组件库迁移 `@moller/design.system`请看 [移徙指南](https://npmcn.com/package/%40gnist/design-system/packages/design-system/MIGRATION.md)。 。 。 .

## 常见问题

### @gnist/design-system 是什么？

@gnist/design-system 是一个 react 组件库,包含用于默勒生态系统应用的可重复使用的多品牌图形界面组件\.

### 如何安装 @gnist/design-system？

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

### @gnist/design-system 支持 TypeScript 吗？

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

### @gnist/design-system 支持 ESM 还是 CommonJS？

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

### @gnist/design-system 可以商用吗？

@gnist/design-system 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @gnist/design-system 的下载量有多少？

根据 npm 官方下载统计，@gnist/design-system 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,028 次，日均约 134 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gnist/design-system 还在维护吗？

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

