A 类 Carbon for IBM.com 和本地 HTML 元素一样容易使用的变体,
没有框架税,没有框架仓.
@carbon/ibmdotcom-web-components
@carbon/ibmdotcom-web-components 已存在 Carbon for IBM.com 与
自定义元素 v1和Shadow DOM v1 specs.
目录
开始
要安装 @carbon/ibmdotcom-web-components 在你的项目中,你需要
使用 无数字 :
npm install -S @carbon/ibmdotcom-web-components
如果你喜欢 雅伦,使用以下命令 相反:
yarn add @carbon/ibmdotcom-web-components
注:从IBM.com开始,Lit依赖性将由Carbon管理
v1.13.0。对于较早的版本,必须安装 Lit 依赖性 单独:无 :
npm install -S lit-html lit-element亚伦:
yarn add lit-html lit-element
@carbon/ibmdotcom-web-components 用途
lit 上面的活性诱导
原始 Web 组件标准和
lit/decorators 用于反应
顶端的属性/属性 lit。 。 。 .
用法实例
Webpack 应用程序设置
基本设置
对于生产用途,我们的建议是 设置模块捆绑器 改为
解决 ECMAScript import编号.
你可以从大多数模块捆绑器的最小配置开始. 对于 示例,与 网络软件包,你不需要一个 配置 .
一旦你建立了一个模块捆绑器, 你可以开始导入我们的组件模块, 例如:
import '@carbon/ibmdotcom-web-components/es/components/masthead/masthead-container';
一旦你这样做,你可以像使用HTML标记那样容易地使用我们的组件,例如:
<c4d-masthead-container></c4d-masthead-container>
检查我们 代码框 实例执行.
\\\ 高于代码Sandbox 示例
html-webpack-plugin允许 WebPack 服务器 服务.html文件,但您可以使用其他方式服务.html文档, 例如,使用 快递 服务器.
使用萨斯
虽然样式作为网络组件的一部分,但设置 Sass 工具链通常对内容的造型有用.
要使用 Sass,可以在模块捆绑器中添加 Sass 工具链. 一对夫妇 sass 工具链所需的关键设置如下:
autoprefixer。这是 要求使用碳核心 Sass 代码.enable-css-custom-propertiesCarbon Sass 特征旗帜. 这是一个 iBM.com样式对Carbon的要求,特别是使用 表达式主题。 。 。 .grid-column-16Carbon Sass 特征旗帜. 这是碳的要求 iBM.com 样式,因为设计偏好碳16列网格carbon-components库默认的12列网格。 。 。 .
以下是WebPack的例子:
module: {
rules: [
{
test: /\.scss$/,
sideEffects: true,
use: [
'style-loader',
'css-loader',
{
loader: 'postcss-loader',
options: {
postcssOptions: {
// `autoprefixer` is a requirement for Carbon core Sass code
plugins: [autoprefixer],
},
},
},
{
loader: 'sass-loader',
options: {
implementation: require('sass'),
sassOptions: {
includePaths: ['../node_modules', '../../../node_modules'],
// `enable-css-custom-properties` and `grid-columns-16` feature flags
// are requirements for Carbon for IBM.com styles
data: `
$feature-flags: (
enable-css-custom-properties: true,
grid-columns-16: true,
);
`,
},
},
},
],
},
],
},
检查我们 代码框 实例执行.
为了防止在您的页面上出现一闪未命名内容(FOUC)
一定会 display: none 如果一个组件尚未定义。 举个例子
c4d-button-group:not(:defined) {
display: none;
}
Process.env 错误
有提及 process.env 全球变量
网络组件包和依赖性。 如果构建工具链( 例如 WebPack)
用于替换 process.env.* 您的应用程序中没有使用,
您可以在 polyfills.ts 申请文件.
(window as any).process = {
env: { DEBUG: undefined },
};
CDN 组件
为了让应用程序运行而不需要前端捆绑,有 为每个组件预建的CDN捆绑.
以下是执行《公约》的实例 dotcom-shell数字 :
<!DOCTYPE html>
<html>
<head>
<script type="module">
import 'https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/dotcom-shell.min.js';
// The minimum prerequisite to use our service for translation data, etc.
window.digitalData = {
page: {
pageInfo: {
language: 'en-US',
ibm: {
country: 'US',
siteID: 'IBMTESTWWW',
},
},
isDataLayerReady: true,
},
};
</script>
<style type="text/css">
body {
font-family: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif;
margin: 0;
}
</style>
<!-- The minimum prerequisite to use our locale selector -->
<link rel="alternate" hreflang="en-us" href="https://www.ibm.com/us-en/" />
<link rel="alternate" hreflang="x-default" href="https://www.ibm.com" />
...
</head>
<body>
<c4d-dotcom-shell-container></c4d-dotcom-shell-container>
</body>
</html>
Carbon CDN 样式助手( 可选)
有可选的CDN文物可以协助全球碳 样式代替包含在您的特定应用程序包中.
例如,下文在“碳重置”中添加了碳重置和必要的Plex字体 页面:
<!DOCTYPE html>
<html>
<head>
<link
rel="stylesheet"
href="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/plex.css" />
...
</head>
</html>
参见 "IBM.com的大楼" 页面
window.digitalData财务报告和审定财务报表<link rel="alternate" ...>。 。 。 .
检查我们 代码框 实例执行.
已版本套装
CDN软件包由国家预防机制标签提供 latest (全部释放), next
(最晚发布候选),和特定版本. 导入的 URL 模式
将:
<script
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/[VERSION]/dotcom-shell.min.js"></script>
或者说
<script type="module">
import 'https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/[VERSION]/dotcom-shell.min.js';
</script>
标签发布将称为:
<!-- LATEST -->
<script
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/latest/dotcom-shell.min.js"></script>
<!-- NEXT -->
<script
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v2/next/dotcom-shell.min.js"></script>
具体的释放将称为:
<!-- SPECIFIC VERSION (available starting v1.6.0) -->
<script
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/version/v2.x.y/dotcom-shell.min.js"></script>
注:最新/下个标签是移动版本。 虽然总是有好处 保留最新版本,建议选择一个特定的 版本,并在升级到更新版本时适当测试应用程序.
使用其他设计系统(例如Northstar v18)
阴影DOM,其中一个 carbon中用于IBM.com网络组件的标准,将网络组件隔离 样式来自应用程序样式。 也就是说这两种风格不会不利 互相影响.
对于目前运行在其他设计系统上的应用程序,例如 遗产 北星 v18,这种隔离 将协助从IBM.com Northstar v18风格逐渐迁移到 碳为IBM.com风格. 两种技术都能够安全共存 应用。 以下是IBM.com的"碳"的例子 IBM.com 北星页脚:
<!-- Loads legacy IBM.com Design System (Northstar) -->
<link rel="stylesheet" href="https://1.www.s81c.com/common/v18/css/www.css" />
<script src="https://1.www.s81c.com/common/v18/js/www.js"></script>
<!-- Loads Carbon for IBM.com Web Components masthead -->
<script
type="module"
src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/masthead.min.js"></script>
...
<body id="ibm-com" class="ibm-type">
<div id="ibm-top" class="ibm-landing-page">
<!-- Uses Carbon for IBM.com Web Components masthead -->
<c4d-masthead-container></c4d-masthead-container>
<div id="ibm-content-wrapper">...</div>
<!-- Uses legacy IBM.com Design System (Northstar) footer -->
<footer role="contentinfo" aria-label="IBM"></footer>
</div>
</body>
如前所述,上面的例子需要设置模块捆绑器 节.
检查我们 代码框 实例执行.
浏览器支持
依据 ibm.com 浏览器支持数字 :
- 最新Chrome/Safari/FF ESR
- IE和经典边缘 没有 支持
可用组件清单
查看可用的网络组件 : https://www.ibm.com/标准/碳/web-组件/。您可以看到用法 以几种方式提供信息:
- 前往 Docs 标签,其中显示用途和可用的属性, 属性和自定义事件.
- 点击 诺比 选项卡,在底部和正在更改的值。 多数
旋钮显示为类似
Button kind (kind)时kind这是 属性名称 - 点击 行动 选项卡在下方,并与
选定组件。 你可能会看到类似的东西
bx-modal-closed哪个 通常表示带有此类事件类型的事件被发射.
网络组件中的稳定选择器(用于分析和集成/E2E测试)
可见于 这里。 。 。 .
高级
在组件中使用自定义样式
作为 Shadow DOM( Web 组件规格之一)
@carbon/ibmdotcom-web-components 承诺、风格
@carbon/ibmdotcom-web-components 定义不影响您的样式
应用程序,或反之亦然.
然而,如果您的应用程序或出自碳的样式指南想要 要改变我们组件的样式,有几个选项.
创建不同样式的衍生组件
您可以创建我们组件的衍生类并覆盖
静态 styles 属性, (中文(简体) ),
例如:
import { css, customElement } from 'lit';
import C4DLinkWithIcon from '@carbon/ibmdotcom-web-components/es/components/link-with-icon/link-with-icon';
@customElement('my-link-with-icon')
class MyLinkWithIcon extends C4DLinkWithIcon {
// Custom CSS to enforce `g100` color of the link text
static styles = css`
${C4DLinkWithIcon.styles}
.bx--link-with-icon {
color: #3d70b2;
}
`;
}
使用 CSS 自定义属性
对 CSS 自定义主题属性的修改以颜色反映
计划 @carbon/ibmdotcom-web-components 组件 :
例如,如果将 CSS 添加如下:
c4d-link-with-icon {
--c4d-link-01: #3d70b2; /* `$link-01` token for `g100` theme */
}
下方代码中链接的颜色修改为 g100 主题:
<c4d-link-with-icon
href="https://www.ibm.com/standards/carbon"
cta-type="local">
Link text
</c4d-link-with-icon>
CSS 自定义属性的名称您可以使用 Carbon 主题符号
前缀为 --cds-。碳主题符号列表可见于
这里。 。 。 .
使用 CSS 自定义属性方法,您可以在 特定要素:
@use '@carbon/styles/scss/themes' as *;
c4d-link-with-icon {
// Emits all theme tokens in CSS Custom Properties
@include theme(g100, true);
}
CSS 阴影部件
一些构成部分支助
CSS 阴影部件 你也可以这样
使用您的应用程序的 CSS 来影响 @carbon/ibmdotcom-web-components 样式
以更灵活的方式.
例如,样式下方修改后按钮的文字颜色
<cds-locale-modal> 对其中之一 g100 主题:
cds-locale-modal::part(back-button) {
color: #152935;
}
ưμ㼯A
虽然阴影部件选择器是可供选择的,但用在自己 风险。 更改组件样式可能导致组件不作为 预期。 您负责确保您的组件保持功能 同时使用阴影部件选择器。 我们无法保证我们的更新 库组件样式不会与阴影部分修改相冲突.
IBM.com 站点所有者的先进用途
还有其他一些关键高级使用模式适合IBM.com 网站所有者。 IBM.com网站所有者可以在 这里。 。 。 .
为IBM.com网络组件贡献碳
可见于 这里。 。 。 .
IBM 遥测
本套件使用 IBM 遥测来收集去识别和匿名的度量衡 数据。 通过安装此包作为依赖, 您同意远程测量 藏书。 选择退出,看 选择退出IBM遥测数据收集。 。 。 . 有关所收集数据的更多信息,请参见: IBM 遥测文档。 。 。 .