使用 CBP 设计系统Web组件
在您的应用程序中包含 Web 组件
将CBP设计系统网络组件纳入您的网站或应用程序有几种策略,详情如下:.
节点模块
在现代JavaScript框架中,你可以使用原生的网络组件,这些组件是框架-不可知的. 要将 CBP 设计系统网络组件添加到您的项目中,请做以下操作:
- 以依赖方式安装网络组件包 :
npm install @cbpds/web-components - 导入您框架中的 Web 组件加载器, 例如
App.js|jsx|tsx或者说main.js|jsx|tsx。 。 。 . - 打电话
defineCustomElements()初始化加载器并注册网络组件(在使用时会懒惰地加载).
import { defineCustomElements } from '@cbpds/web-components/dist/loader';
defineCustomElements();
如果您正在使用代码库中的 Typescript, 您可能需要在成功编译您的代码之前让您的项目意识到网络组件 。 在很多情况下,只需在您之前添加网络组件定义就可以做到这一点 tsconfig.json包括(在 npm install 已运行)。 例如,
"include": [
"src",
"node_modules/@cbpds/web-components/dist/types/components.d.ts"
]
如果使用带有React的TypeScript,这本身是不够的. 你还需要延长JSX。 内向元素来识别你的组件. 可以通过创建 src/types/ 文件夹和其中的文件,例如, custom-element-types.d.ts数字 :
import type { CustomElements, CustomCssProperties } from "@cbpds/web-components/dist/types/custom-element-jsx"
declare module "react" {
namespace JSX {
interface IntrinsicElements extends CustomElements {}
}
export interface CSSProperties extends CustomCssProperties {}
}
脚本标签
对于不在一个节点.js环境中运行或需要构建步骤的网站,可以通过脚本标记包含网页组件:
- 在您索引.html或模板文件头加载器模块的脚本标记 .
- 这个文件是一个加载器,它根据需要登记所有的设计系统组件和懒惰的单个组件.
- 注:无害环境管理模块必须在SSL/https上提供.
- 然后可以在模板,JSX,html等任何地方使用网络组件(海关元素).
您可以使用 UNPKG (一个反映 npm 的开源全球内容提供网络) 进行测试, 但是它不应该用于生产应用 .
参考最新版本:
<script type="module" src="https://unpkg.com/@cbpds/web-components/dist/cbp-web-components/cbp-web-components.esm.js"></script>
参考特定版本:
<script type="module" src="https://unpkg.com/@cbpds/[email protected]/dist/cbp-web-components/cbp-web-components.esm.js"></script>
理想的情况是,您的申请应参考文件的中央、组织托管副本或提取软件包 dist/cbp-web-components 在您的应用程序的“ 资产” 目录中引用 :
<script type="module" src="./assets/cbp-web-components/cbp-web-components.esm.js"></script>
使用 Web 组件
一旦CBP设计系统的网站组件被包含在您的网站或应用程序中,它们可能被用于HTML,JSX等. 这些web组件是像其他HTML元素一样被使用的自定义元素,其属性,方法和事件在其API文档中被定义.
建议: cbp-app 网络组件 用于包装您应用程序或站点模板的全部内容,以包括整个设计系统中用于设计组件的全局CSS变量(设计符号).
为了尽快开始,你可以抄取我们一个 "当代"的故事 来包装您的应用程序或网站内容.
字体和资产
无论您如何包含网络组件( 以上两种方法都不同), 您仍然需要一些属于 CBP 设计系统软件包但并未封装在 cbp-app 网络组件或任何其他组件 :
复制文件到 node_modules/@cbpds/web-components/dist/assets/ 您的应用程序 /assets 目录。 (这可自动与 vite-plugin-static-copy(例如,第1行) 这个目录包括了Roboto字体文件,他们的CSS字体面部定义,以及CBP封印,这些字被多处使用,可以作为favicon来引用.
Roboto字体家族是CBP设计系统标准的一部分,但必须在应用程序中手动链接 <head> 还有.
复制并粘贴到您的索引.html或模板文件中 :
<link rel="icon" type="image/svg+xml" href="assets/images/cbp-seal.svg">
<link rel="stylesheet" type="text/css" href="./assets/css/roboto.css">
<link rel="stylesheet" type="text/css" href="./assets/css/roboto_mono.css">
这些 CSS 文件假设一个目录结构:
- 网络根
- 资产
- 密码
- 字体
- 机器人
- 机器人摩诺
- 图像
- 资产
任何偏离此结构的情况都可能需要编辑链接到的CSS文件和通向字体的路径.
如果您的应用程序资产文件夹的路径不同于 ./assets,您可能需要提供路径作为属性 cbp-universal-header 作为您网站/应用程序模板的一部分.