静态资源管理规范

一、规范目的

静态资源是软件系统页面渲染、交互展示、业务赋能的基础载体，其规范性直接影响系统加载性能、兼容性、安全性和迭代可维护性。为保障各类产品在资源命名、存储结构、格式压缩、引用调用上的一致性，千桐科技特制定本《静态资源管理规范》。

本规范凝聚了公司在长期项目实践中的运维与开发经验，已成为千桐科技各产品（包括 qKnow 知识平台、qData 数据中台、qThing 物联网平台、qModel 模型管理平台等）统一遵循的资源管理标准。通过规范化的静态资源管控，团队能够在多项目并行开发、版本迭代、环境部署中保持统一的资源标准与使用规范，优化页面访问速度、降低服务器带宽损耗，提升开发交付与运维管理效率，确保产品具备优质体验、合规性与长期迭代能力。

二、目录结构规范

规则

1、目录采用全英文命名

2、采用驼峰命名法（例：camelCase）

3、目录名统一使用模块名词（如 da、dp、dpp、ds）

4、通用目录名使用 common 命名

5、禁止跨模块直接引用

6、被 ≥2 个模块引用，必须移至每种资源类型下对应的 common/ 子目录通用模块下

7、模块资源按文件数量决定目录深度：15~20 个文件平铺在 assets/[类型]/[module]/，超过则按页面或二级模块拆分子目录 assets/[类型]/[module]/[page]/

示例结构

assets/
├── images/
│   ├── common/
│   ├── dp/
│   ├── ds/
│   └── qm/
├── icons/
│   ├── svg/
│   │   ├── common/
│   │   ├── dp/
│   │   └── ds/
│   └── iconfont/
│       └── font/
├── fonts/
│   ├── common/
│   └── dp/
├── styles/
│   ├── common/
│   ├── dp/
│   └── ds/

三、图片资源规范

规则

文件名称采用全小写英文 + 短横线连接，单个单词无需短横线命名

采用短横线命名法（例：kebab-case）

文件命名格式：[用途前缀]-[描述内容].[扩展名]

支持的扩展名：.png、.jpg、.svg、.webp、.gif

常见的前缀

分类	含义	示例
bg-	背景图	bg-login.jpg
logo-	Logo	logo-qdata.png
avatar-	头像	avatar-default.png
toolbar-	工具栏	toolbar-export.png
status-	状态指示	status-success.png
empty-	空状态	empty-no-data.png
error-	错误页	error-404.png
qr-	二维码	qr-wechat.png
ds-	数据源图标	ds-mysql.png
brand-	品牌/AI模型	brand-deepseek.svg
file-	文件类型	file-pdf.png
action-	操作按钮	action-edit.png
arrow-	箭头方向	arrow-left.png
deco-	装饰素材	deco-cockpit-box-1.png
ui-	UI组件素材	ui-tab.png
illust-	插画/功能图	illust-api.png
form-	表单控件	form-email.png
banner-	横幅	banner-login.png
theme-	主题切换	theme-dark.svg
img-	通用(兜底)	img-pay.png

命名示例

• bg-header.png
• logo-company.svg
• status-success.png
• empty-no-data.svg
• file-excel.png

四、图标规范

1、SVG

规则

文件名称采用全小写英文 + 短横线连接，单个单词无需短横线命名

采用短横线命名法（例：kebab-case）

文件命名格式：[用途前缀]-[描述内容/图标含义].svg

支持的文件扩展名：.svg

常见的前缀

分类	含义	示例
nav-	导航/菜单	nav-dashboard.svg
action-	操作/动作	action-edit.svg
status-	状态指示	status-success.svg
form-	表单控件	form-checkbox.svg
file-	文件类型	file-pdf.svg
user-	用户/角色	user-group.svg
media-	通讯/媒体	media-email.svg
biz-	业务功能	biz-dict.svg
chart-	图表/数据	chart-equalizer.svg
system-	系统/配置	system-settings.svg
device-	设备/硬件	device-server.svg
layout-	布局/视图	layout-fullscreen.svg
brand-	品牌/第三方	brand-github.svg
empty-	空状态插画	empty-data.svg
flag-	标记/旗帜	flag-cn.svg
loading-	加载/进度	loading-spin.svg

命名示例

• nav-home.svg
• action-delete.svg
• status-error.svg
• user-avatar.svg

iconfont

规则

文件命名必须以 icon-开头

全小写英文字母 + 短横线

文件命名格式：icon-[分类]-[图标名称]

常见分类

分类	含义	示例
nav	导航/菜单	icon-nav-home
action	操作/动作	icon-action-edit
status	状态结果	icon-status-success
form	表单控件	icon-form-calendar
file	文件类型	icon-file-pdf
user	用户/角色	icon-user-group
media	通讯/媒体	icon-media-email
biz	业务功能	icon-biz-caigou
chart	图表/数据	icon-chart-bar
brand	品牌/第三方	icon-brand-alipay
device	设备/硬件	icon-device-smartphone
layout	布局/视图	icon-layout-fullscreen

命名示例

• icon-action-save.css
• icon-status-warning.css

五、字体规范

规则

文件名称保持字体官方名称，用 kebab-case 连接，如 pingfang-sc-regular.woff2

文件命名格式：[字体风格]-[字体规格].[文件扩展名]

命名示例

• pingfang-sc-regular.woff2
• helvetica-neue-bold.woff
• roboto-medium.woff2
• microsoft-yahei-light.ttf

六、样式规范

规则

采用短横线命名法

单个单词无需短横线命名

文件命名格式：

• 全局样式：[职责/用途].[文件扩展名]
• 动态样式：[职责/用途].module.[文件扩展名]

文件扩展名：.css、.scss、.less

命名示例

• global.css
• variables.scss
• mixins.scss
• reset.css
• layout.module.scss
• form.module.css
• button.module.scss
• modal.module.less

七、常见词汇

常用词汇表

类型	词汇
状态	success, error, warning, info, active, disabled, loading
操作	add, edit, delete, save, search, filter, export, import, upload, download, copy, share, refresh, close, back, reset
方向	left, right, up, down
场景	login, home, dashboard, detail, list, setting
用户	default, admin, group, person
文件	pdf, excel, folder, image
表单	email, calendar, checkbox, select
图表	bar, line, pie, table
布局	fullscreen, grid, card, sidebar
系统	settings, key, server, mobile
通讯	chat, message, bell
空状态	no-data, no-result
主题	dark, light
加载	spin, dots

---

提示

遵守规范，方能行稳致远。