Semi Design 语义插画包 @douyinfe/semi-illustrations 使用指南：安装、React 组件集成与 Empty 空状态插画详解

前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载本篇技术指南以 Semi Design 开源仓库中packages/semi-illustrations/README.md为核心骨架系统讲解douyinfe/semi-illustrations语义化插画包的安装方式、作为独立 React 组件渲染、以及与douyinfe/semi-ui的Empty空状态组件组合使用的完整方案。读完本文你将掌握 8 组语义插画含暗色模式版本的导入方式、组件 API 约定、底层 SVG 实现原理CSS 变量取色、无障碍属性并能在实际项目中一键替换默认空状态占位图。插画包是什么douyinfe/semi-illustrations是由 Semi Team 设计并开源发布的**语义化插画Semantic Illustrations**组件包位于本仓库的 packages/semi-illustrations 目录。它与核心组件库douyinfe/semi-ui解耦发布专门为空状态、异常态、结果态等典型业务场景提供统一的视觉语言。插画包的设计动机非常明确让业务方无需自行绘制占位图就能获得与 Semi Design 设计体系完全一致的插画风格。每个插画组件本质是一个封装为 React 组件的 SVG 图形内部直接引用 Semi 设计令牌Design Token对应的 CSS 变量取色如var(--semi-color-primary)因此会随主题如暗色模式、品牌色定制自动变化天然融入整套设计系统。快速开始安装依赖插画包通过 npm 独立发布包名为douyinfe/semi-illustrations安装命令npm install douyinfe/semi-illustrations从 package.json 可以看到该包的工程约定main指向lib/cjs/index.jsmodule指向lib/es/index.jstypings指向lib/es/index.d.ts即同时提供 CommonJS 与 ES Module 两套产物并携带完整的 TypeScript 类型声明peerDependencies声明react 16.0.0插画组件是纯 React 组件不依赖douyinfe/semi-ui可独立使用当前仓库中该包版本为2.103.0以仓库实际为准。如果你的项目使用 yarn也可使用yarn add douyinfe/semi-illustrations安装。作为独立 React 组件使用安装完成后插画可以直接作为普通的 React 组件渲染。README 给出的最小示例如下import { IllustrationIdle } from douyinfe/semi-illustrations; ReactDOM.render(IllustrationIdle /, root);IllustrationIdle /默认渲染一个 200 x 200 的 SVG 图形源码中width、height、viewBox均为 200见 IllustrationIdle.tsx。组件接受React.SVGPropsSVGSVGElement类型的 props因此你可以像使用普通 SVG 一样覆盖尺寸、样式等属性import { IllustrationSuccess } from douyinfe/semi-illustrations; // 按业务场景自定义插画尺寸 IllustrationSuccess style{{ width: 150, height: 150 }} /作为 Empty 空状态内容使用这是插画包最核心、最常见的用法——作为Empty组件的image属性传入替换默认占位图import { Empty } from douyinfe/semi-ui; import { IllustrationIdle } from douyinfe/semi-illustrations; ReactDOM.render(Empty image{IllustrationIdle /}/Empty, root);Empty是douyinfe/semi-ui提供的空状态组件组件文档位于 content/show/empty/index.md它通过image属性接收占位图节点。将语义插画传给image后即可快速得到标题 描述 语义插画的标准空状态 UI。更完整的实战组合示例如下来自仓库 Empty 组件文档的代码演示import React from react; import { Empty } from douyinfe/semi-ui; import { IllustrationConstruction, IllustrationConstructionDark } from douyinfe/semi-illustrations; () ( Empty image{IllustrationConstruction style{{ width: 150, height: 150 }} /} darkModeImage{IllustrationConstructionDark style{{ width: 150, height: 150 }} /} title{功能建设中} description当前功能暂未开放敬请期待。 / );插画清单8 组语义场景与暗色模式版本从 src/illustrations/index.ts 的导出列表可以确认插画包共内置8 个语义主题每个主题对应普通版与 Dark暗色版两个组件合计 16 个导出组件。仓库根入口 src/index.ts 对全部组件做了二次导出因此可以从包顶层直接按需导入。语义场景普通版组件暗色版组件典型用途建设中IllustrationConstructionIllustrationConstructionDark功能开发中提示失败IllustrationFailureIllustrationFailureDark加载失败、操作失败空闲IllustrationIdleIllustrationIdleDark空闲等待、默认占位无权限IllustrationNoAccessIllustrationNoAccessDark没有访问权限无内容IllustrationNoContentIllustrationNoContentDark列表/面板暂无数据无结果IllustrationNoResultIllustrationNoResultDark搜索无结果未找到IllustrationNotFoundIllustrationNotFoundDark页面 404成功IllustrationSuccessIllustrationSuccessDark创建/提交成功在 content/show/empty/index.md 的占位图插画演示中8 个主题与其暗色版本被逐一展示在Empty组件中并给出了对应文案建议成功创建成功、失败加载失败、无权限没有权限、无内容暂无内容请添加、未找到页面 404、无结果搜索无结果、建设中建设中、空闲神游四方。这为业务接入时的插画选择提供了直接参考。暗色模式适配原理README 本身只演示了普通插画但暗色模式是这套插画包的关键能力。Empty组件文档指出darkModeImage用于暗色模式开启后的占位图响应 document.body 的 theme-mode 属性变化。从 packages/semi-ui/empty/index.tsx 的源码可以看到其实现逻辑if (this.props.darkModeImage) { // ... 监听 theme-mode 变化更新 state.mode } // ... const imgSrc ((this.state.mode dark) darkModeImage) ? darkModeImage : image;即当document.body的theme-mode变为dark时Empty会自动切换渲染darkModeImage指定的暗色插画未开启暗色模式或未传darkModeImage时则始终渲染image。因此推荐做法是成对传入普通版与暗色版插画让空状态在不同主题下都保持合适的视觉层次。插画自身的取色机制进一步保障了主题一致性在 IllustrationIdle.tsx 的 SVG 中主色填充使用的是fillvar(--semi-color-primary-light-default)与fillvar(--semi-color-primary)见第 19、92 行等辅助色使用#E6E8EA、描边使用#41464C。也就是说插画的主色调直接引用 Semi 设计令牌随全局主题定制而变化这也是它与普通静态图片占位相比的核心优势。源码级解析插画组件如何实现组件结构每个插画组件以 IllustrationIdle.tsx 为例都是一个接收React.SVGPropsSVGSVGElement的默认导出函数组件其 SVG 根节点关键属性包括svg width{200} height{200} viewBox0 0 200 200 fillnone xmlnshttp://www.w3.org/2000/svg focusable{false} aria-hidden{true} {...props} 其中两个属性值得关注aria-hidden{true}插画作为装饰性图形不参与无障碍语义。Empty组件文档的 Accessibility 一节也明确说明Empty 插图的 aria-hidden 为 true见 content/show/empty/index.mdfocusable{false}避免插画进入 Tab 焦点序列防止干扰键盘导航。同时组件通过{...props}透传所有外部传入的 SVG 属性这也是style{{ width: 150 }}这类尺寸定制能生效的原因。底层 SVG 资产除了 TSX 组件插画包还维护了对应的原始 SVG 资产目录 packages/semi-illustrations/src/svgs其中包含construction.svg、failure.svg、idle.svg、noAccess.svg、noContent.svg、noResult.svg、notFound.svg、success.svg及各自-dark.svg版本与 16 个 TSX 组件一一对应。这体现了原始 SVG 资产 编译为 React 组件的维护模式设计资产与组件产物分离便于设计侧更新插画。构建产物插画包的构建流程定义在 gulpfile.js 与 package.json 中cleanLib任务清理旧的lib目录compileTSXForESM/compileTSXForCJS分别将src/**/*.tsx、src/**/*.ts编译为lib/esESM与lib/cjsCJS两套产物其中 JS 编译使用 esbuildloader 配置.tsx: tsx类型声明.d.ts通过 gulp-typescript 生成build:js脚本串联执行build:lib与compileDist.js生成 dist 产物prepublishOnly在发布前先执行clean与build:js。这就是main/module/typings三个字段能分别指向 CJS、ESM 与类型声明文件的构建来源。实战技巧与最佳实践1. 成对使用普通版与暗色版凡涉及可能切换暗色模式的场景都应同时传入image与darkModeImage。仓库的 Empty 单元测试也验证了这一组合见 packages/semi-ui/empty/test/empty.test.jsEmpty {...props} image{IllustrationConstruction /} darkModeImage{IllustrationConstructionDark /}/Empty2. 按场景尺寸定制插画默认 200 x 200通过style属性可任意缩放。Empty 组件文档中的演示普遍使用style{{ width: 150, height: 150 }}。若使用Empty的layouthorizontal横向布局插画与文本并排时配合style{{ width: 800 }}之类的容器约束即可获得稳定排版参见 content/show/empty/index.md。3. 按需引入控制包体积插画包根入口对 16 个组件做了具名导出配合 Tree-Shaking 按需引入单个插画即可。在构建时注意保持对douyinfe/semi-illustrations的 ESM 产物module字段解析以便最大程度摇树优化。4. 结合 Empty 的完整 APIEmpty组件API 详见 content/show/empty/index.md支持title标题、description描述、image占位图、darkModeImage暗色占位图、layoutvertical/horizontal默认vertical、imageStyle、children自定义内容可放操作按钮等属性。将语义插画作为image配合title、description、children即可搭建插画 说明 行动按钮的完整空状态闭环import { Empty, Button } from douyinfe/semi-ui; import { IllustrationNoContent, IllustrationNoContentDark } from douyinfe/semi-illustrations; Empty image{IllustrationNoContent style{{ width: 150, height: 150 }} /} darkModeImage{IllustrationNoContentDark style{{ width: 150, height: 150 }} /} title空状态标题 description开始创建你的第一个仪表盘吧 Button typeprimary themesolid style{{ padding: 6px 24px }} 创建 /Button /Empty小结douyinfe/semi-illustrations为 Semi Design 生态提供了开箱即用的语义化插画资产8 个覆盖建设、失败、空闲、无权限、无内容、无结果、未找到、成功场景的主题每个主题均含暗色模式版本。它既可独立渲染为 React 组件也可通过Empty的image/darkModeImage属性无缝接入空状态 UI底层 SVG 组件直接引用 Semi 设计令牌取色、声明aria-hidden与focusable兼顾主题一致性与无障碍规范。对业务项目而言这是以最低成本获得与设计体系一致视觉语言的推荐方案。延伸阅读插画包完整源码packages/semi-illustrations组件根入口导出packages/semi-illustrations/src/index.ts插画清单与导出packages/semi-illustrations/src/illustrations/index.ts单个插画组件实现示例packages/semi-illustrations/src/illustrations/IllustrationIdle.tsx原始 SVG 资产packages/semi-illustrations/src/svgsEmpty 空状态组件文档content/show/empty/index.mdEmpty 组件源码与测试packages/semi-ui/empty/index.tsx / packages/semi-ui/empty/test/empty.test.js赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐knowledge-work-pluginsZoom Video SDK for Linux 实战开发指南——环境配置、Raw Data 渲染与无头机器人接入knowledge work pluginsZoom Video SDK for Linux 实战开发指南——环境配置、Raw Data 渲染与无头机器人接入前端UI组件设计系统douyinfe/semi-animation-react 实战指南用 Spring 物理引擎为 Semi Design 组件实现进入/退出过渡动画douyinfe/semi animation react 实战指南用 Spring 物理引擎为 Semi Design 组件实现进入/退出过渡动画 本文以前端UI组件设计系统Semi Design 动画基础库 douyinfe/semi-animation 完全指南插值驱动的 JS 动画引擎与生命周期控制Semi Design 动画基础库 douyinfe/semi animation 完全指南插值驱动的 JS 动画引擎与生命周期控制 douyinfe/s前端UI组件设计系统上一篇如何实现虚拟环境中的多人数据编辑APITable实时协作空间终极指南 下一篇Swagger UI 扩展新 OAS 版本支持完整指南从规范分析到插件实现的 17 步实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考