在 carbon 仓库中运行图标预览示例（icon preview example）完整指南

在 carbon 仓库中运行图标预览示例icon preview example完整指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文围绕carbon/icons包中自带的「图标预览示例」icon preview example展开讲解如何从零启动一个基于 Next.js 的图标浏览、检索与调试环境。读完本文你将掌握在 carbon monorepo 中构建全部包、启动examples/preview预览页面的完整流程并能结合示例源码理解该页面如何通过metadata.json渲染全部图标、如何拼接图标导入路径es/lib/umd以及如何为单个图标快速创建视觉缺陷 issue。示例目录与它的定位该示例位于仓库的 packages/icons/examples/preview 目录属于carbon/icons包的配套示例应用。它的用途不是演示某个业务组件而是为图标资产本身提供一套「全量预览 检索 导入路径提示 快速报 issue」的开发工具页面通常用于图标设计评审、接入前挑选图标以及视觉回归检查。目录结构相对仓库根目录如下packages/icons/examples/preview/ ├── src/ │ ├── pages/ │ │ ├── _app.js # 引入全局样式 │ │ └── index.js # 图标表格页面的核心实现 │ ├── scss/ │ │ └── _reset.scss # 基础 reset │ └── styles.scss # 页面与代码高亮样式 ├── README.md # 官方启动说明本文主体来源 ├── next.config.js # Next.js 配置 ├── package.json # 依赖与脚本 └── yarn.lock第一步在仓库根目录构建全部包示例应用直接依赖 monorepo 内正在开发的包例如通过link:链接的carbon/styles、需要由图标构建任务生成的metadata.json因此官方 README 要求先在 carbon 仓库根目录完成一次整体构建yarn install yarn build其中yarn install负责安装整个 monorepo 的依赖yarn build会依次构建各个包。对于本示例而言关键产物有两个carbon/styles等样式包供 styles.scss 中的use carbon/styles/scss/grid、use carbon/type、use carbon/colors、use carbon/layout引用packages/icons/metadata.json图标元数据文件由carbon/icons的构建任务生成预览页面直接读取它来渲染图标表格。从 packages/icons/package.json 可以看到files字段中包含了metadata.json说明它会随包一起发布预览页面在本地开发时则直接引用构建产物。构建完成后carbon/icon-helpers预览页通过import { toString } from carbon/icon-helpers使用等依赖也已就绪。第二步进入示例目录安装依赖并启动开发服务器在仓库根目录构建成功后切换到示例目录并安装它自身的依赖cd packages/icons/examples/preview然后使用你偏好的包管理器安装依赖yarn install # 或 npm install安装完成后启动开发服务器yarn develop # 或 npm run developdevelop脚本在 package.json 中定义为develop: next即直接调用 Next.js 开发服务器。启动成功后用浏览器打开 http://localhost:3000 即可看到图标预览页面。默认端口为 3000若端口被占用Next.js 会自动尝试下一个可用端口请注意终端输出的实际地址。开发服务器的技术栈从 package.json 可以确认该示例的依赖组合next^16.2.6与react/react-dom^19.2.5Next.js 驱动的 React 应用sass编译styles.scssprismjs在页面内做 JS 代码高亮用于展示图标导入语句url-polyfill为部分环境补齐 URL 相关 API页面代码中第一行import url-polyfillcarbon/styles以link:../../../styles方式链接到 monorepo 内的样式包保证示例始终使用仓库当前代码change-case-all字符串命名转换工具供图标构建流程使用。next.config.js 中还有两处值得注意的配置开发模式下启用了 Turbopack并把root指向仓库根目录path.resolve(__dirname, ../../../..)以支持跨包的本地链接解析生产构建阶段PHASE_PRODUCTION_BUILD会输出为静态导出basePath: /icons/examples/preview、output: export、distDir: build这意味着该页面也可以被构建为静态站点部署到子路径下仓库的部署任务会利用这一能力。预览页面能做什么源码视角进入 src/pages/index.js可以看到页面核心逻辑从../../../../metadata.json导入图标元数据该相对路径最终指向packages/icons/metadata.json对metadata.icons做flatMap把每个图标的output展开为表格行表格列依次为Name名称、Size尺寸、Preview预览、GitHub源文件、Issues创建 issue、Path导入路径。图标尺寸与降级逻辑每个图标在元数据中带有assets原始 SVG 资产和output各尺寸产出。源码先以assets.find(asset asset.size 32)确定默认资产遍历output时若当前产出尺寸如 16、20、24、32找不到对应资产则标记为Downsized降级缩放显示名称会显示为name (Downsized to size)。尺寸为glyph的产出则显示为glyph普通尺寸显示为16x16这类格式。预览渲染预览单元格通过carbon/icon-helpers的toString(info.descriptor)把图标描述符转换为内联 SVG 字符串再通过dangerouslySetInnerHTML注入页面配合 styles.scss 中.icon-preview svg { outline: 1px solid #8a3ffc; }的紫色描边便于在灰底容器中观察每个图标的实际边界。图标导入路径的生成规则页面头部「Usage」区解释了如何把表格中的Path列转换成真实导入语句其通用模板为import IconName from carbon/icon-package/es/path-to-icon/size;例如在 React 中导入add图标16 尺寸import IconName from carbon/icon-react/es/add/16;注意两点若要使用 CommonJS 或 UMD 模块只需把路径中的es分别替换为lib或umd每个图标的名称列是一个锚点链接点击即可生成带#moduleName的 URL可直接分享给协作者定位到具体图标。一键创建视觉缺陷 issue表格的Issues列通过getBugTemplate(name, source)生成一个预填的 issue 链接标题为 Visual bug for theicon正文包含图标来源、复现步骤模板、浏览器与版本等字段。这为「发现某个图标视觉有误 → 直接提交反馈」提供了低摩擦路径无需手动整理上下文。页面样式与代码高亮styles.scss 展示了如何把 Carbon 的设计令牌引入一个独立页面通过use引入grid、type、colors、layout模块再调用include default-type()与include grid.flex-grid()启用 Carbon 的默认排版与弹性栅格。页面中cds--grid、cds--row、cds--col等栅格类名正是由这套 flex grid 生成的。文件末尾还内置了一套 Prismjs 的深色主题用于渲染language-js代码块。常见问题与排查思路打开 3000 端口页面为空白或样式缺失多半是根目录构建未完成导致carbon/styles、metadata.json等产物缺失回到仓库根目录重新执行yarn install yarn build。图标数量与预期不符metadata.json是构建产物修改packages/icons/src/svg下的 SVG 后需重新构建carbon/icons见 packages/icons/package.json 中build: yarn clean node tasks/build.js再刷新预览页。端口被占用Next.js 会自动改用其他端口以终端输出的实际地址为准。生产环境部署该示例支持next build静态导出产物位于build目录basePath为/icons/examples/preview可直接托管到任意静态服务器或仓库配套的部署平台仓库根目录的netlify.toml配置了相关示例页面的部署。小结packages/icons/examples/preview是一套麻雀虽小、五脏俱全的图标预览工具它演示了在 monorepo 中链接本地包link: Turbopack root 指向仓库根、以构建产物metadata.json为数据源渲染全量图标、通过carbon/icon-helpers动态生成 SVG 预览以及「一键生成 issue」的反馈闭环。无论你是想在接入图标前挑选合适的资产、核对图标在不同尺寸下的渲染效果还是想为图标包贡献新的视觉修复按本文的yarn install yarn build→cd packages/icons/examples/preview yarn install yarn develop流程都能快速进入可用的预览环境。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考