# @appdirect/sfb-theme-components 中文文档

规范地址：https://npmcn.com/package/%40appdirect/sfb-theme-components/

版本：2\.1\.52
npm 元数据更新时间：2026-11-02T20:10:06.068Z
中文译文更新时间：2026-11-06T23:59:31.695Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40appdirect/sfb-theme-components
原文对照：https://npmcn.com/package/%40appdirect/sfb-theme-components/?lang=original
项目主页：https://github.com/appdirect/sfb-theme-components#readme
源码仓库：https://github.com/appdirect/sfb-theme-components

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

- 包体积（解压后）：28 MB，1222 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：26 个
- peer 依赖：react \>= 16\.x\.x \|\| \>= 18\.x\.x
- 首次发布：2019-05-16T01:49:16.005Z
- 最新版本发布：2026-11-02T20:10:05.864Z
- 近 30 天下载量：2143（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 7 个）

## 中文简介

存储前置构建器用于构建主题的组件.

## 安装

```sh
npm install @appdirect/sfb-theme-components
```

也可以使用：`pnpm add @appdirect/sfb-theme-components`、`yarn add @appdirect/sfb-theme-components`、`bun add @appdirect/sfb-theme-components`

## README

# sfb -- -- 主题组成部分

存储前置构建器用于构建主题的组件.

### 安装

-   安装依赖关系 `npm install`
    -   升级到16号节点后,您必须完成 `npm install --legacy-peer-deps` 换成

### 利用市场进行地方发展

-   启动服务器 `npm start`。 。 。 .
-   你用得着 [资源覆盖](https://chrome.google.com/webstore/detail/resource-override/pkoacgokdfckfpndoffpifphamojphii?hl=en) 用于js和cs:
    -   发讯人: `https://engage19billing.test.devappdirect.me/sfb-theme-components@0/*` 改为 `http://localhost:3444/*`
    -   替换您选择的 MP URL

### 使用工具包进行地方发展

-   安装 [sfb-toolkit (英语)](https://help.appdirect.com/platform/Default.htm#StorefrontBuilder/sfb-install-dev-tool.htm%3FTocPath%3DCustomize%2520the%2520storefront%7CWork%2520with%2520the%2520Storefront%2520Toolkit%7C_____1)。 。 。 .
-   设置以 Plaza 为主题的主题项目: `sfb-toolkit setup`。 。 。 .
-   开始 `sfb-toolkit` 本地服务器 : `sfb-toolkit start`。 。 。 .
-   开始 `sfb-theme-components` 服务捆绑的本地服务器 : `npm run start`
-   你可以做到这一点 [资源覆盖](https://chrome.google.com/webstore/detail/resource-override/pkoacgokdfckfpndoffpifphamojphii?hl=en) 用于js和cs:
    -   发讯人: `https://engage19billing.test.devappdirect.me/sfb-theme-components@0/*` 改为 `http://localhost:3444/*`

### 故事书

要查看组件,我们可以启动"故事本"服务器:

-   运行 `npm run storybook`。 。 。 .
-   导航到 `http://localhost:8087/`。 。 。 .
-   在左手导航栏上,选择一个组件/Atom将使组件成为主部分.
-   我们正在使用 [童话小说](https://storybook.js.org/addons/storybook-addon-knobs-color-options) 以更新故事本中组件设置道具.

### 为您的主题创建自定义组件

-   启动故事簿服务器 : `npm run storybook`
-   转到 [自定义组件文档](http://localhost:8087/?path=/story/docs-customization-custom-components--page) 需要更多信息.

### CSS - 命名公约

我们将遵循修改后的版本: [https://css-tricks.com/abem-useful-adaptation-bem/ (中文(中国大陆) )](https://css-tricks.com/abem-useful-adaptation-bem/)

-   **无** a/o/m 前缀
-   名称应多用一个词 _骆驼 Case_ 公约代替 `-`
-   修改器正在使用 `--` (双破折号)并与名称相接

实例:

```jsx
// just an element, nothing to see
<div class="blockName_elementName"></div>
```

```jsx
// with a modifier
<div class="blockName_elementName blockName_elementName--modifier"></div>
```

关于更详细的例子,请参见一节 `CSS - Naming Tool`

### 构成部分的结构

组件有两个文件夹:

-   `atoms/` 其中应包括非常基本、易于重复使用的不同主题和样式组件,例如: _图像_, (中文(简体) ), _按钮_, (中文(简体) ), _页眉_等 (中文(简体) ).
-   `components/` 包含一个主题更具体的组件,大多数时间包括一个或多个 _原子_ 组件

### 进行响应

-   弹性 [https://markus.oberlehner.net/blog/创建-a-应变-二相栏-放出-用flexbox/](https://markus.oberlehner.net/blog/creating-a-responsive-alternating-two-column-layout-with-flexbox/)
    
-   隐藏元素 [https://markus.oberlehner.net/blog/poor-mans-container-queries-hide-content-on-the-width-of-its-container/ 互联网档案馆的存檔,存档日期2014-12-21](https://markus.oberlehner.net/blog/poor-mans-container-queries-hide-content-based-on-the-width-of-its-container/)
    
-   **不要使用媒体查询**
    

### 推进型和功能组件不强制

-   功能组件示例 [https://reactjs.org/docs/hooks-state.html 页面存档备份,存于互联网档案馆](https://reactjs.org/docs/hooks-state.html)
-   跟随清除 守则最佳做法 [https://github.com/ryancdermott/ clean-code-javascript 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/ryanmcdermott/clean-code-javascript)

### CSS - 命名工具

已实施命名工具,以帮助跟踪CSS命名结构:

每一组成部分应包含:

```js
import { createNamespace } from './tools/namingTools';

const n = createNamespace('MyComponentName');
```

#### 简单用途 :

```jsx
<div {...n(element[, [modifiers]]).props}></div>
```

-   `modifier` 是可选的,也可以是其中之一 `string` 或者说 `array of strings`

#### 实例

##### 带有修改符的元素 :

```jsx
<div {...n('elementName', 'myModifier').props}></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--myModifier">
</div> 
```

##### 带有修改词列表的元素 :

```jsx
<div {...n('elementName', ['myModifier1', 'myModifier2']).props}></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--myModifier1 
           myComponentName_elementName--myModifier2">
</div> 
```

##### 有 testId 的元素 : `.withTestId()`

```jsx
<div {...n('elementName').withTestId().props}></div> 
// translates to
<div class="myComponentName_elementName" data-testid="myComponentName:elementName"></div> 
```

##### 有自定义 testId 的元素 : `.withTestId(*)`

```jsx
<div {...n('elementName').withTestId('myTestId').props}></div> 
// translates to
<div class="myComponentName_elementName" data-testid="myComponentName:myTestId"></div> 
```

##### 有 testId 的元素 _仅限_数字 : `.withTestId()`

```jsx
<div {...n().withTestId('myTestId').props}></div> 
// translates to
<div data-testid="myComponentName:myTestId"></div> 
```

##### 有额外类的元素 `.withClass(*)`

```jsx
<div {...n('elementName').withClass('myExtraClass').props}></div> 
// translates to
<div class="myComponentName_elementName myExtraClass"></div> 
```

##### 有额外类的元素 `.withClass(*)`

```jsx
<div {...n('elementName').withClass(['myExtraClass1', 'myExtraClass2']).props}></div> 
// or
<div {...n('elementName').withClass('myExtraClass1').withClass('myExtraClass2').props}></div> 
// translates to
<div class="myComponentName_elementName myExtraClass1 myExtraClass2"></div> 
```

`namingTool` 和它的职能 `.withClass()`, (中文(简体) ), `.withTestId()` 为: **可连锁** 这意味着您可以研究每个函数的结果,直到 `.props` 将召入.

##### 复杂实例

```jsx
<div 
     {...n('elementName', ['modifier1', modifier2'])
         .withClass(['myExtraClass1', 'myExtraClass2'])
         .withClass('testClass')
         .withTestId()
         .props
     }></div> 
// translates to
<div 
    class="myComponentName_elementName 
           myComponentName_elementName--modifier1
           myComponentName_elementName--modifier2
           myExtraClass1 
           myExtraClass2
           testClass"
    data-testid="myComponentName:elementName "
></div> 
```

### Jest - 测试和调试

已有5个定义的发射配置可用于测试和调试:

-   `Jest run all test suites` - 这个配置将贯穿所有测试套件和项目中定义的所有测试案例.
-   `Jest run selected test suite` - 此配置将运行目前在您工作空间中选择的文件( 测试套件) 中找到的所有测试大小写 .
-   `Jest run all tests matching selected text` - 此配置将运行所有匹配您工作空间中选中/ 突出显示的文本的测试大小写( 多个测试可根据所选文本匹配)
-   `Jest run all test suites matching prompted input` - 此配置将运行所有包含/匹配输入框中提供的文本的测试套件, 当配置运行时将会显示( 多个测试套件可以匹配)
-   `Jest run all tests matching prompted input` - 此配置将运行所有包含/匹配输入框中提供的文本的测试大小写, 当配置运行时会显示( 多个测试大小写可以匹配)

`NOTE:` 在使用上述配置时,断点应在VS代码中正确工作.

## 常见问题

### @appdirect/sfb-theme-components 是什么？

存储前置构建器用于构建主题的组件\.

### 如何安装 @appdirect/sfb-theme-components？

在项目目录运行 npm install @appdirect/sfb-theme-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>= 16\.x\.x \|\| \>= 18\.x\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @appdirect/sfb-theme-components 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/appdirect\_\_sfb-theme-components 是否存在。

### @appdirect/sfb-theme-components 支持 ESM 还是 CommonJS？

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

### @appdirect/sfb-theme-components 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @appdirect/sfb-theme-components 可以商用吗？

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

### @appdirect/sfb-theme-components 的下载量有多少？

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

### @appdirect/sfb-theme-components 还在维护吗？

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