# @bolttech/frontend-foundations 中文文档

规范地址：https://npmcn.com/package/%40bolttech/frontend-foundations/

版本：0\.12\.3
npm 元数据更新时间：2026-11-06T15:03:03.062Z
中文译文更新时间：2026-11-08T10:37:01.556Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：76.6 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2023-11-06T11:09:40.193Z
- 最新版本发布：2026-06-08T14:14:44.812Z
- 近 30 天下载量：3960（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 5 个）

## 中文简介

[![N|Solid](https://www.bolttech.co.th/blog/wp-content/uploads/2020/10/logo.png)](https://bolttech.io/)

## 安装

```sh
npm install @bolttech/frontend-foundations
```

也可以使用：`pnpm add @bolttech/frontend-foundations`、`yarn add @bolttech/frontend-foundations`、`bun add @bolttech/frontend-foundations`

## README

[![N|Solid](https://www.bolttech.co.th/blog/wp-content/uploads/2020/10/logo.png)](https://bolttech.io/)

# **前端基金会**

## **内容提要**

关于这些文件,您可找到以下专题:

-   [说明](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-description)
-   [所需资源](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-requirements)
-   [安装](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-installation)
-   [在你开始之前](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-before-you-start)
    -   [屏幕断点和媒体查询](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-screen-breakpoints-and-media-queries)
    -   [默认主题](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-default-theme)
-   [构成部分](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-components)
    -   [电瓶技术主题](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-bolttechthemeprovider)
    -   [行数](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-row)
    -   [栏](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-column)
    -   [中间](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-center)
    -   [类型](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-typography)
-   [助教课程](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-helper-classes)
    -   [颜色](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-colors)
    -   [边距](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-margin)
    -   [铺垫](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-padding)
    -   [定位](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-positioning)
-   [生成自己的主题](https://npmcn.com/package/%40bolttech/frontend-foundations/#readme-markdown-header-generating-your-own-theme)

## **说明**

这些地基是一组组件,供开发者方便地复制设计者使用的地基 **_位置、对齐、样式和结构._**

它包含一系列严格的组件,应当始终用于你的开发,因为它遵循的是 [**_Bolttech 设计页面指南._**](https://zeroheight.com/9a2ddf9f2/p/54487b-colors/b/24d401)

## **所需资源**

-   [节点.js](https://nodejs.org/) 16.0+ (韩语)
-   [反应](https://react.dev/) 18.2+ (单位:千美元)
-   [样式组件](https://styled-components.com/) 6个+

## **安装**

安装 `frontend-foundations` 软件包,包含以下命令:

```sh
npm i @bolttech/frontend-foundations
```

关于发展环境:

```sh
git clone git@bitbucket.org:gofrank/frontend-foundations.git
cd frontend-foundations
npm install
npm run storybook
```

## **在你开始之前**

在开始之前,你应该知道两点是这个项目的基础. 这些要点是与设计小组共同界定的,以便建立一个基本结构 **应跟踪每次设计和开发新的组件和网页**这些要点是:

### **屏幕断点和媒体查询**

地基内部的所有组件都遵循了我们的断点规则. 这些规则后来也用于您根据当前屏幕的断点提供某些组件的特定尺寸。 这些断点是:

| 断点 | 屏幕大小 |
| --- | --- |
| **页:1** | \* |
| **系统** | 414px - 767px (英语) |
| **货币** | 768px - 1439px (英语) |
| **语言** | \* |

这么说,你应该输入我们的 `media-queries` 基于这些断点,在开发页面时,可以更好地遵循网格指引.

#### 示例

```css
import styled from 'styled-components';
import { MediaQueries } from '@bolttech/frontend-foundations';

export const MyComponent = styled.div`
  display: flex;
  flex-direction: row;
  background-color: red;


  @media ${MediaQueries.LG} {
    background-color: green;
  }

  @media ${MediaQueries.SM} {
    flex-direction:column
  }
`
```

### **默认主题**

地基有颜色、花纹、相距、打字和道具的预设 `default theme` 或者说 `bolttech theme`。 。 。 .

以下是主题的结构:

```typescript
type bolttechTheme = {
  colors: ColorsType;
  spacing: SpacingType;
  typography: TypographyType;
  effects: EffectType;
  components: Record<string, unknown>;
  tokens?: Record<string, unknown>;
};
```

## **构成部分**

### **电瓶技术主题**

这个 `BolttechThemeProvider` 组件是 [`ThemeProvider`](https://styled-components.com/docs/api#themeprovider) 从样式组件。 它允许你注射 **主题** 在树上.

我们 `ThemeProvider` 和风格的组件不同 因为我们期望一个主题 具有一个定义的结构, 也有一个默认的主题 与布尔特克风格.

如果你想,你可以导入我们 **默认主题** 编辑 **主题类型** 并随想而用.

#### 示例

```jsx
import { BolttechThemeProvider, bolttechTheme } from '@bolttech/frontend-foundations';

const MyApp = () => (
  <BolttechThemeProvider theme={bolttechTheme}>
    <App />
  </BolttechThemeProvider>
);

export default MyApp;
```

**重要内容:** 如果你打算使用任何组件 Bellow,你 **需求** 用 `BolttechThemeProvider` 因为我们的组件使用带有预定义结构的设计符号,所以您需要提供带有该类型的主题 `BolttechThemeType`。 。 。 .

### **方框**

Box组件是用于React应用的多功能容器组件,旨在提供灵活的造型和布局选项. 它接受各种道具来定制它的外观和行为.

# 反应框组件

## 概览

这个 `Box` 组件是用于反应应用的多功能容器组件,旨在提供灵活的样式和布局选项。 它接受各种道具来定制它的外观和行为.

### 使用量

```jsx
import { Box } from '@bolttech/frontend-foundations';

// ...

const MyComponent = () => {
  return (
    <Box
      sizes={{ xs: 100, sm: 100, md: 100, lg: 100 }} /* Optional */
      className="flex pt-l"
      removeGridPadding
      removeGridGap
    >
      {/* Your content goes here */}
    </Box>
  );
};
```

### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `sizes`(备选) | `{ xs?: number; sm?: number; md?: number; lg?: number }` | `undefined` | 指定不同断点的组件大小. |
| `className` | 弦声 | 字符串\[\]\` | `undefined` |
| `removeGridPadding` | `boolean` | `false` | 如果设置为 `true`,删除网格类名称所应用的默认编目. |
| `removeGridGap` | `boolean` | `false` | 如果设置为 `true`,删除网格类名称应用的默认缺口. |

### 参考文件转发

这个 `Box` 组件支持 [转发](https://reactjs.org/docs/forwarding-refs.html)您可以使用 `ref` 以引用基础 `div` 键.

```jsx
const myRef = useRef();

<Box ref={myRef}>Content</Box>;
```

### **行数**

这个 `Row` 构成部分基本上是a `div` 将组件包装为一个弹性容器,应用我们的基本样式 [**设计网格系统**](https://zeroheight.com/9a2ddf9f2/p/872765-layout/b/786f73)。 。 。 .

它有一个 **最大宽度为 1440px**页:1 **列之间的间隔** 财务报告和审定财务报表 **列两侧的挂起**. 空隙和补丁的价值基于我们的网格系统的断点.

| 断点 | 差距 | 铺垫 |
| --- | --- | --- |
| **页:1** | 弹性框. XS | 弹性框.S |
| **系统** | 弹性框.S | 弹性框.L |
| **货币** | 弹性框.M | 弹性框\['2XL'\] |
| **语言** | 弹性框.M | 弹性框\['3XL'\] |

  

#### 道具

| Prop | 说明 | 类型 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| **全网风** | 删除行标签 | `boolean` | `false` | `false` |
| **满重** | 添加100%的高度 | `boolean` | `false` | `false` |
| **中间** | 添加比值 0 自动 | `boolean` | `false` | `false` |
| **类Name** | 额外 css 类 | `string` | `false` | `undefined` |
| **儿童** | 儿童部分 | **反应元素或反应元素 \[\]** | `false` | `undefined` |

#### 示例

```jsx
import { Row } from '@bolttech/frontend-foundations';

<Row fullWidth={true} fullHeight={true} center={false} className="mb-xs">
  <ChildComponent />
</Row>;
```

### **栏**

这个 `Column` 组件是使用 **宽度百分比** 以定义容器的大小。 设计师和devs需要意识到每个屏幕断点都有需要填充的大小. 每个断点的可能性如下:

| 断点 | 允许的大小 |
| --- | --- |
| **页:1** | 100%,75%,66.66%,50%,33.333%,25%,0% |
| **系统** | 100%,75%,66.66%,50%,33.333%,25%,20%,16.66%,0% |
| **MD 和 LG 数据** | 100%,75%,66.66%,50%,33.333%,25%,20%,16.66%,0% |

#### 道具

| Prop | 说明 | 类型 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| **儿童** | 儿童部分 | `ReactElement` 或者说 `ReactElement[]` | `false` | `undefined` |
| **类Name** | 包含需要应用到列中的类列表的字符串 | `string` | `false` | `undefined` |
| **大小** | 包含每个断点列大小的对象 | `Object` | `true` |  |

#### 示例

```jsx
import { Column, Row } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Row>
    <Column size={{ xs: '100%', sm: '33.333%', md: '50%', ld: '50%' }}>Hello</Column>
    <Column size={{ xs: '100%', sm: '66.666%', md: '50%', lg: '50%' }}>World</Column>
  </Row>
);
```

### **中间**

这个 `Center` 其组成部分是一个基本组成部分,它包罗着儿童组成部分和中心.

#### 示例

```jsx
import { Center, Column, Row } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Row>
    <Center>
      <Column size={{ xs: '50%', sm: '50%', md: '50%', lg: '50%' }}>World</Column>
    </Center>
  </Row>
);
```

### **类型**

这个 `Typography` 是一个文本组件,可以假设许多大小,由设计团队根据其中的符号来决定 **主题文件夹下的打字文件**请提供有效的组合 `variant` 财务报告和审定财务报表 `type` 基于此文件.

#### 道具

| Prop | 说明 | 类型 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| **类型** | 类型 | `string` | `true` | `body` |
| **变体** | 样式变体 | `string` | `true` | `primary` |
| **文本** | 如果您需要以道具的形式提供文本 | `boolean` | `false` | `undefined` |
| **类Name** | 额外 css 类 | `string` | `false` | `undefined` |
| **儿童** | 儿童部分 | `ReactElement` 或者说 `ReactElement[]` | `false` | `undefined` |

**说明:** 取决于什么 `type` 财务报告和审定财务报表 `variant` 你提供 `Typography` 构成部分将 **生成不同的 HTML 元素**。 。 。 .

| 类型 | 备选案文 | 元素 |
| --- | --- | --- |
| **标题** | `h1`, (中文(简体) ), `h1Light` | `h1` |
| **标题** | `h2` | `h2` |
| **标题** | `h3` | `h3` |
| **标题** | `h4` | `h4` |
| **机构** | `primary`, (中文(简体) ), `secondary`, (中文(简体) ), `tertiary` | `p` |
| **标签** | `primary`, (中文(简体) ), `secondary`, (中文(简体) ), `tertiary` | `label` |

#### 示例

```jsx
import { Typography } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Typography variant="primary" type="body">
    Welcome to bolttech!
  </Typography>
);
```

此外 `Typography` 组件可以使其文本中的链接。 要渲染链接,您应该像普通的Markdown文件中那样通过,例如:

```jsx
const MyComponent = () => (
  <Typography variant="primary" type="body">
    normal text [text to render as link](https://google.com)(blank|download)
  </Typography>
);
```

注意最后一个参数是可选的. 如果你不通过它,它会打开链接在同一标签上

## **助教课程**

为了帮助您的页面的开发与造型,我们决定增加帮助者课程,用于 **颜色、垫和边距** 正如我们所知道的那样,仅仅为添加这些属性而创建有风格的组件不是一个有趣的任务.

所有这些类都是根据您主题配置所提供的符号的颜色、间隔和弹性框属性创建的

说到这里,我们有一套基本的课程,我们提供:

### **颜色**

基于主题的结构,我们创建了带有前缀的班级 `text-`, (中文(简体) ), `bg-` 财务报告和审定财务报表 `fill-` 并附加主题提供的颜色。 例如,如果您有以下颜色的主题:

```ts
colors: {
  content: {
    accent: tokens.cyan['700'],
    base: tokens.navy['700'],
    subtle: tokens.navy['500'],
    weak: tokens.navy['400'],
    // ...
  }
}
```

我们将为您的全球风格设置以下课程:

```css
.text-content-accent {
  color: #00bac7;
}
.bg-content-accent {
  background-color: #00bac7;
}
.fill-content-accent {
  fill: #00bac7;
}

.text-content-base {
  color: #170f4f;
}
.bg-content-base {
  background-color: #170f4f;
}
.fill-content-base {
  fill: #170f4f;
}
/* ... */
```

### **边距**

基于主题的结构,我们创建了带有前缀的班级 `mt-`, (中文(简体) ), `mb-`, (中文(简体) ), `ml-`, (中文(简体) ), `mr-`, (中文(简体) ),`mh-`, (中文(简体) ),`mv-`,以及 `m-`,并附加您主题提供的边距。 因此,例如,如果一个主题有以下边距:

```ts
spacing: {
  flexbox: {
    XXS: '8px',
    XS: '16px',
    S: '24px',
    M: '32px',
    // ...
  },
}
```

我们将为您的全球风格设置以下课程:

```css
.mt-xxs: {
  margin-top: 8px;
}
.mb-xxs {
  margin-bottom: 8px;
}
.ml-xxs {
  margin-left: 8px;
}
.mr-xxs {
  margin-right: 8px;
}
.mh-xxs {
  margin-left: 8px;
  margin-right: 8px;
}
.mv-xxs {
  margin-top: 8px;
  margin-bottom: 8px;
}
.m-xxs {
  margin: 8px;
}
```

### **铺垫**

基于主题的结构,我们创建了带有前缀的班级 `pt-`, (中文(简体) ), `pb-`, (中文(简体) ), `pl-`, (中文(简体) ), `pr-`, (中文(简体) ),`ph-`, (中文(简体) ),`pv-`,以及 `p-`,并附上由您的主题提供的垫片。 例如,如果您有一个主题, 上面有以下标签:

```ts
spacing: {
  padding: {
    NONE: '0px',
    XXXS: '2px',
    XXS: '3px',
    XS: '4px',
    S: '8px',
    // ...
  },
}
```

我们将为您的全球风格设置以下课程:

```css
.pt-xxs: {
  padding-top: 8px;
}
.pb-xxs {
  padding-bottom: 8px;
}
.pl-xxs {
  padding-left: 8px;
}
.pr-xxs {
  padding-right: 8px;
}
.ph-xxs {
  padding-left: 8px;
  padding-right: 8px;
}
.pv-xxs {
  padding-top: 8px;
  padding-bottom: 8px;
}
.p-xxs {
  padding: 8px;
}

/* ... */
```

### **定位**

我们还希望为人们提供一个方便的方法,在页面上定位元素,而无需仅仅为定位而创建自定义的有风格的组件. 因此,我们也为您的全球风格注入这些课程:

```css
.flex {
  display: flex;
}
.flex-row {
  flex-direction: row;
}
.flex-row-reverse {
  flex-direction: row-reverse;
}
.flex-column {
  flex-direction: column;
}
.flex-column-reverse {
  flex-direction: column-reverse;
}
.flex-shrink-1 {
  flex-shrink: 1;
}
.flex-shrink-0 {
  flex-shrink: 0;
}
.flex-grow {
  flex: 1;
}
.flex-grow-1 {
  flex-grow: 1;
}
.flex-grow-0 {
  flex-grow: 0;
}
.flex-basis-0 {
  flex-basis: 0;
}
.flex-basis-1 {
  flex-basis: auto;
}
.align-start {
  align-items: flex-start;
}
.align-center {
  align-items: center;
}
.align-right {
  align-items: flex-end;
}
.align-self-stretch {
  align-self: stretch;
}
.align-self-center {
  align-self: center;
}
.align-self-start {
  align-self: start;
}
.align-self-end {
  align-self: end;
}
.justify-left {
  justify-content: flex-start;
}
.justify-center {
  justify-content: center;
}
.justify-right {
  justify-content: flex-end;
}
.justify-between {
  justify-content: space-between;
}
.justify-evenly {
  justify-content: space-evenly;
}
.justify-arround {
  justify-content: space-arround;
}
.min-content {
  width: min-content:
}
.max-content {
  width: max-content:
}

/* ... */
```

### 类型

生成 CSS 类,用于整个应用程序中可以应用的打字,确保按指定主题的打字风格的一致性。 它满足不同的文本元素,如标题,正文,以及移动和桌面断点的标签.

### 参数

-   **`theme: ThemeType`**: 包含打字设置的对象 `typography` 用于移动和桌面的属性,每个包含 `headings`, (中文(简体) ), `body`,以及 `label`。 。 。 .

### 回返

包含主题对象所指定的打字变体 CSS 类定义的字符串 .

### 使用量

确保您的主题对象结构包含 `typography` 移动和桌面的设置,详细样式用于 `headings`, (中文(简体) ), `body`,以及 `label`。 。 。 .

```typescript
const theme = {
  typography: {
    mobile: {
      headings: { /* styles */ },
      body: { /* styles */ },
      label: { /* styles */ },
    },
    desktop: {
      headings: { /* styles */ },
      body: { /* styles */ },
      label: { /* styles */ },
    },
  }
};
```

调用 `createTypographyClasses` 有主题对象 :

```typescript
const typographyClasses = createTypographyClasses(theme);
```

### 示例 CSS 输出

```css
.ty-headings-h1 {
  font-weight: 700;
  line-height: 1.2;
  font-size: 2rem;
  letter-spacing: 0.5px;
}
/* Additional classes for body, label, and other headings */
```

### 弹性框缺口

生成 CSS 类,用于控制弹性框布局中的空白,使用主题对象所定义的弹性框符号值. 它支持不同缺口大小的自定义前缀,允许更灵活的设计系统.

### 参数

-   **`theme: ThemeType`**: 在 `tokens.flexbox` 属性.
    
-   **`prefix = ''`**:一个可选的字符串参数,用于前缀生成的类名,允许定制并避免命名冲突. 示例前缀:"sm:","md:","lg:".
    

### 回返

一系列字符串,每个字符串都代表 CSS 类定义,根据主题的flexbox 符号值对空隙,行格和列格进行定义.

### 使用量

确保您的主题对象包含下方的灵活框符号值 `tokens.flexbox`。 。 。 .

```typescript
const theme = {
  tokens: {
    flexbox: {
      xss: '4px',
      xs: '6px',
      s: '8px',
    }
  }
};
```

调用 `createGapClasses` 有主题对象,如果需要,则有一个可选的前缀。 下面用"sm:","md:"和"lg:"前缀表示不同的缺口大小:

```typescript
const smallGapClasses = createGapClasses(theme, 'sm:');
const mediumGapClasses = createGapClasses(theme, 'md:');
const largeGapClasses = createGapClasses(theme, 'lg:');
```

### 示例 CSS 输出

```css
.sm:gap-s {
  gap: 8px;
}
.sm:rg-s {
  row-gap: 8px;
}
.sm:cg-s {
  column-gap: 8px;
}
/* Additional classes for medium "md:" and large "lg:" gaps */
```

### **响应**

在台基上,我们也为您提供了一种基于屏幕大小的组件样式,处理反应的方法. 对于用于样式组件的每个类,也可以针对特定的屏幕大小,简单地添加您想要针对的屏幕大小的前缀.

我们的方法是 **移动电话** 因此请注意,如果你提供一个没有前缀的类,它将适用于所有屏幕大小,但例如,如果你提供一个叫作 `md:pt-xs` 它会应用类 `pt-xs` 到屏幕大小 `md` **较大**说吧! 如果您想要只添加到特定屏幕大小中, 您需要添加另一个类目标屏幕大小比您所选择的更大 .

```typescript
<Row className="pb-m sm:pb-s md:pb-xs lg:pb-xxs md:flex-grow-0 md:justify-between">
  <Column size={{ xs: '100%', sm: '33.333%', md: '50%', ld: '50%' }}>Hello</Column>
  <Column size={{ xs: '100%', sm: '66.666%', md: '50%', lg: '50%' }}>World</Column>
</Row>
```

## **生成/更新您自己的主题**

如果你需要更新主题或创建新主题,请看看我们 [主题生成器 cli 工具.](https://bitbucket.org/gofrank/bolttech-ui/src/main/libs/theme-generator/)

## 常见问题

### 如何安装 @bolttech/frontend-foundations？

在项目目录运行 npm install @bolttech/frontend-foundations，或使用 pnpm add / yarn add / bun add。

### @bolttech/frontend-foundations 支持 TypeScript 吗？

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

### @bolttech/frontend-foundations 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bolttech/frontend-foundations 可以商用吗？

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

### @bolttech/frontend-foundations 的下载量有多少？

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

### @bolttech/frontend-foundations 还在维护吗？

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