# @clubmed/trident-ui 中文文档

规范地址：https://npmcn.com/package/%40clubmed/trident-ui/

版本：2\.1\.0
npm 元数据更新时间：2026-11-03T15:54:36.471Z
中文译文更新时间：2026-11-10T03:38:30.305Z
软件包许可：BSD-3-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40clubmed/trident-ui
原文对照：https://npmcn.com/package/%40clubmed/trident-ui/?lang=original
源码仓库：https://scm.clubmed.com/clubmed/ui/trident-ui

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

- 包体积（解压后）：1.9 MB，957 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：16 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，tailwindcss \>=3\.4\.17 \|\| \>=4\.0\.0，@clubmed/trident-icons \>=1\.16\.0，@tailwindcss/typography \>=0\.5\.19，@tailwindcss/container-queries \>=0\.1\.1
- 首次发布：2024-02-28T17:40:03.155Z
- 最新版本发布：2026-11-03T15:54:36.318Z
- 近 30 天下载量：4634（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：259（近 12 个月 141 个）

## 中文简介

共享 ClubMed React UI 组件

## 安装

```sh
npm install @clubmed/trident-ui
```

也可以使用：`pnpm add @clubmed/trident-ui`、`yarn add @clubmed/trident-ui`、`bun add @clubmed/trident-ui`

## README

![Club Med](https://ns.clubmed.com/fbs/RWD/branding2023/Logo/MicrosoftTeams-image%20\(9\).png)

# @ clubmed/ 三叉戟- ii

* * *

[![npm version](https://badge.fury.io/js/%40clubmed%2Ftrident-ui.svg)](https://badge.fury.io/js/%40clubmed%2Ftrident-ui) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)

## 这是什么

React UI组件是可重复使用的组件库,用于使用Club Med品牌指南构建网络应用程序.

## 有用链接

-   [Figma 三叉戟 UI](https://www.figma.com/@clubmed)
-   [Jira董事会](https://clubmed.atlassian.net/jira/software/c/projects/SCL/boards/122)
-   [故事书稳定版本](https://latest.trident-ui.pro.clubmed/?path=/docs/introduction--docs)
-   [故事书版](https://develop.trident-ui.pro.clubmed/storybook/index.html?path=/docs/introduction--docs)
-   [文档](https://develop.trident-ui.pro.clubmed/?path=/docs/introduction--docs)

## 所需资源

-   反应 18
-   尾风 4

## 安装

```sh
npm install --save @clubmed/trident-icons @clubmed/trident-ui react react-dom
npm install --save-dev tailwindcss @tailwindcss/vite
```

```sh
yarn add @clubmed/trident-icons @clubmed/trident-ui react react-dom
yarn add -D tailwindcss @tailwindcss/vite
```

```sh
pnpm add @clubmed/trident-icons @clubmed/trident-ui react react-dom
pnpm add -D tailwindcss @tailwindcss/vite
```

> 使用 vite 可以安装 `@tailwindcss/vite` 而不是使用邮箱。 见 [尾风花纹文档](https://tailwindcss.com/docs/installation/using-vite)

## 配置

添加 `@tailwindcss/vite` 给您的 `vite.config.ts` 插件 :

```ts
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});
```

然后,在你的风格 `index.css` 文件 :

```css
@import '@clubmed/trident-ui/style.css';
@source '../node_modules/@clubmed/trident-ui/ui/**/*.js'; /* Important, this line is required to make Tailwind CSS work with Trident UI components */
@source '../node_modules/@clubmed/trident-ui/chunks/**/*.js'; /* Important, this line is required to make Tailwind CSS work with Trident UI components */
```

> `@source` 必须是相对于导入文件的文件,并且必须指向 `ui` 图书馆目录。 这需要让Tailwind CSS与三叉戟UI组件配合,因为它需要扫描源文件来生成正确的样式.

## 尾风合并配置

三叉戟 UI 使用自定义运出的设计符 `text-*` 水电费(`text-b5`, (中文(简体) ), `text-h2`等),其行为类似字体大小的帮助者. 当消费者依赖时 [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) 要组成分类,这些符号必须登记为印刷工具;否则 `tailwind-merge` 可能错误地把它们当作文本颜色类, 并丢弃有效的样式( 例如 ) `twMerge('text-b5', 'text-white')` 将删除 `text-white`) (中文(简体) ).

为了获得正确的行为,你可以重新使用我们暴露的帮助者:

```ts
import { twMerge } from '@clubmed/trident-ui/helpers/twMerge';

// twMerge('text-b5', 'text-white') -> 'text-b5 text-white'
```

如果您需要自定义 `tailwind-merge` 在您的应用中,请用我们的打字符扩展:

```ts
import { extendTailwindMerge } from 'tailwind-merge';

export const twMerge = extendTailwindMerge({
  extend: {
    theme: {
      text: ['b6', 'b5', 'b4', 'b3', 'b2', 'b1', 'b0', 'h5', 'h4', 'h3', 'h2', 'h1', 'h0'],
    },
  },
});
```

两种方法都确保三叉戟UI类安全地与您的覆盖合并.

## 使用量

您可以直接从是目录导入任何组件 。 例如,按钮组件可以导入,并且 使用情况如下:

```tsx
import { useState } from 'react';
import { Button } from '@clubmed/trident-ui/ui/buttons/Button';

export function App() {
  const [count, setCount] = useState(0);

  return (
    <>
      <Button onClick={() => setCount((count) => count + 1)}>count is {count}</Button>
    </>
  );
}
```

## 库配置

您可以使用 `TridentUIConfigProvider` 配置三叉戟 UI 库中的某些选项 :

```tsx
import './index.css';
import App from './App';
import React from 'react';
import { createRoot } from 'react-dom/client';
import { TridentUIConfigProvider } from '@clubmed/trident-ui';
import { IconsProvider } from '@clubmed/trident-ui/atoms/Icons/contexts/IconsContext.js';
import Actions from '@clubmed/trident-ui/atoms/Icons/svg/Actions';

const baseName = (window as any).basename || '/';

createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <TridentUIConfigProvider
      value={{
        locale: 'fr-FR',
      }}
    >
      <IconsProvider icons={[Actions]}>
        <App />
      </IconsProvider>
    </TridentUIConfigProvider>
  </React.StrictMode>,
);
```

### 选项

-   `locale` - 用于组件的地块。 默认为 `fr-FR`。 。 。 .

## 图标配置

三叉戟 UI 提供了加载图标的新方法. 你可以用这个 `IconProvider` 从特定组中装入图标的组件. 目前,有两个图标提供者:

-   SvgIcon Provider:使用懒惰加载的SVG来显示图标.
-   SvgUseicon Provider:使用本地Svg使用属性来加载并显示图标.

对于每个提供者,您都有按组名拆分的图标子集:

-   行动
-   活 动
-   品牌
-   科维德
-   粮食
-   快乐的照顾
-   地点
-   度假地 \* (仅供 SVG 使用)
-   会议室
-   服务
-   社会
-   运输
-   公用事业

默认情况下, 没有设置图标提供者 。 您必须在代码中导入子集图标如下 :

Svg 模式 :

```tsx
import Actions from '@clubmed/trident-ui/atoms/Icons/svg/Actions'; // load only the Actions subset using SVG mode
import { Icon } from '@clubmed/trident-ui/atoms/Icons/Icon';

function App() {
  return (
    <IconsProvider icons={[Actions]}>
      <Icon name="ArrowDefaultLeft" />
    </IconsProvider>
  );
}
```

您可以混合使用 SVG 和 SVG 使用模式 :

```tsx
import Actions from '@clubmed/trident-ui/atoms/Icons/svg-use/Actions'; // load the Actions subset
import Brand from '@clubmed/trident-ui/Icons/svg/Brand';

function App() {
  return (
    <IconsProvider icons={[Actions, Brand]}>
      <Icon name="ArrowDefaultLeft" />
      <Icon name="ClubMed" />
    </IconsProvider>
  );
}
```

> 在这种情况下,图标组件会自动使用相应的图标Resolver来加载并显示图标.

### 注册自定义图标

三叉戟 UI 提供功能来注册任何外部 Svg 图标而无需重新开发 a 自定义图标组件。 刚刚使用 `resolver` 从 `SvgIconResolver` 或者说 `SvgUseIconResolver` 添加您的新图标 :

```tsx
import { resolver } from '@/atoms/Icons/svg/SvgIconResolver';

const CustomIcons = resolver([
  {
    name: 'MyCustomIcon',
    group: 'custom',
    element: lazy(() => import('./MyCustomIcon.svg?react')),
    // viewBox: '0 0 30 30', // default '0 0 30 30'
    // aspectRatio: 1, // default '1'
    // orientation: 'left' // apply rotation to the icon
  },
]);

function App() {
  return (
    <IconsProvider icons={[CustomIcons]}>
      <Icon name="MyCustomIcon" />
    </IconsProvider>
  );
}
```

## 从 v1 迁移到 v2

1.  在开始迁移前更新三叉戟UI的最新v1发布.
2.  在Button v2和Card v2上移动您的代码基础.
3.  替换包含任何导入路径 `atoms` 或者说 `molecules` 与 `ui` 路径段.
4.  路径中的不行为现在进入了小范围。 (例如: `molecules/Buttons/Button` - > (中文) `ui/buttons/button`) (中文(简体) ).
5.  直接从 `@clubmed/trident-icons`。 。 。 .
6.  将格式调用更新到 v2 统一签名 : `onChange(event, value)`。 。 。 .
    -   v1 模式类 `onChange={(name, value) => ...}` 必须是 `onChange={(event, value) => ...}`。 。 。 .
    -   当你仍然需要字段名称时,请从 `event.currentTarget.name`。 。 。 .
    -   对于类似复选框的组件,将直接事件替换为 (单位:千美元)`event.target.checked`)与第二个论证(`value`) (中文(简体) ).

> 此时,请检查您是否没有在路径和组件上出现任何问题,然后移动到下一步.

您可以更新到 Tailwind 4 和 三叉戟 UI v2:

-   尾风4不再读 `tailwind.config.ts` 或由 三叉戟 UI 运出预设; 将配置重命名为 `tailwind.config.legacy.(js|ts)`。 。 。 .
-   采用 Tailwind 4 语法更新( 例如) `@layer`, (中文(简体) ), `@utility`) (中文(简体) ).

将样式添加到您的 `index.css` 文件 :

```css
@import '@clubmed/trident-ui/style.css';
```

狦 `custom.css` 文件使用三叉戟 UI 类或变量,并在最上方添加此内容 :

```css
@reference "@clubmed/trident-ui/style.css";

.button {
}
```

应足够:)

### 了解问题

目前,由于 SVG 源代码不正确,一些字体模式的图标无法正确渲染 清理干净了.

## 游戏配置

如果您正在使用 Jest, 您可以在您的配置中添加以下 `jest.config.js` 文件 :

```js
{
  moduleNameMapper: {
    "^@clubmed/trident-ui/(.*)$": dirname(require.resolve("@clubmed/trident-ui")) + "$1"
  },
  // add also this line can solve issue:
  transformIgnorePatterns: ["/node_modules/(?!@clubmed/trident-ui)/.*"]
}
```

## 无障碍测试

要测试访问权限错误( 目前在库中负债) , 您需要激活选项 `parameters.a11y.test` 改为 `error` 并进行测试:

```sh
npm run test
```

## 捐款

请阅读 [捐款额](https://npmcn.com/package/%40clubmed/trident-ui/CONTRIBUTING.md) 详细介绍我们的行为守则和向我们提交拉动请求的程序.

## 许可证

版权 2024 - 今天 QQ Club Med

允许以源和二进制形式进行再分配和使用,无论是否修改,但必须符合下列条件:

1.  源代码再分配必须保留上述版权通知,本条件清单和以下免责声明.
    
2.  以二进制形式的再分配必须转载上述版权通知,本条件清单以及随分发而提供的文件和(或)其他材料中的下列免责声明.
    
3.  未经具体事先书面许可,不得使用版权持有人的姓名或撰稿人的姓名认可或推广从该软件衍生出的产品.
    

这种软件是由治安维持者和贡献者提供的,“安全”和任何扩张或军事攻击,包括但不限制为某一特定目的制造的危机和损失。 任何直接、直接、意外、特别、紧急、紧急、或后果的转让(包括、但不限制、采购非物质货物或服务;使用、数据、或买卖的损耗;或商业干涉),无论以何种方式造成、使用、限制、限制或限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用或限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用、限制使用或限制使用、限制使用、限制使用、限制使用、限制使用、限制使用或限制使用、限制使用、限制使用、限制、限制使用或限制使用、限制使用、限制使用、限制、限制使用、限制使用或限制使用、限制使用、限制使用、限制使用、限制、限制使用、限制使用、限制或限制使用、限制使用、限制使用、限制、限制使用、限制、限制、限制使用、限制、限制、限制使用、限制或限制使用、限制使用、限制.

## 常见问题

### @clubmed/trident-ui 是什么？

共享 ClubMed React UI 组件

### 如何安装 @clubmed/trident-ui？

在项目目录运行 npm install @clubmed/trident-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、tailwindcss（\>=3\.4\.17 \|\| \>=4\.0\.0）、@clubmed/trident-icons（\>=1\.16\.0）、@tailwindcss/typography（\>=0\.5\.19）、@tailwindcss/container-queries（\>=0\.1\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clubmed/trident-ui 支持 TypeScript 吗？

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

### @clubmed/trident-ui 支持 ESM 还是 CommonJS？

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

### @clubmed/trident-ui 可以商用吗？

@clubmed/trident-ui 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @clubmed/trident-ui 的下载量有多少？

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

### @clubmed/trident-ui 还在维护吗？

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