SVG 图标
tsx
import type { IconName } from '@ray-template/icons'
import { RIcon } from '@ray-template/ui/icon'
const name: IconName = 'directional/resize_h'
const renderIcon = () => <RIcon name={name} />RIcon.name 和路由 meta.icon 使用同一套完整分包名。将 SVG 加入 packages/icons/src/<分包>,例如 packages/icons/src/business/orders/approved.svg 对应 business/orders/approved。可在演示的 SVG 图标页面查找并复制用法。
交互示例
图标库默认复制 TSX 用法(<RIcon name="action/search" />)。选择「Vue 模板」后,点击图标即可复制 <r-icon name="action/search" />,粘贴到已导入 RIcon 的 Vue 模板。
查看示例源码
tsx
import './index.scss'
import { RIcon } from '@/components'
import { useI18n } from '@/hooks'
import { iconNames, iconPackages } from '@/icons'
import {
NCard,
NEmpty,
NInput,
NRadioButton,
NRadioGroup,
NSelect,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
export default defineComponent({
name: 'PreviewSVGIcons',
setup() {
const { t } = useI18n('icons')
const { t: showcaseT } = useI18n('showcase')
const query = ref('')
const selectedPackage = ref<string | null>(null)
const copyFormat = ref<'tsx' | 'vue'>('tsx')
const copyTag = computed(() =>
copyFormat.value === 'tsx' ? 'RIcon' : 'r-icon',
)
const filtered = computed(() =>
iconNames.filter(
(name) =>
(!selectedPackage.value ||
name.startsWith(`${selectedPackage.value}/`)) &&
name.includes(query.value.trim().toLowerCase()),
),
)
const groups = computed(() =>
iconPackages
.map((name) => ({
name,
icons: filtered.value.filter((icon) => icon.startsWith(`${name}/`)),
}))
.filter((group) => group.icons.length),
)
return () => (
<DemoPage
title={t<string>('title')}
description={t<string>('description')}
eyebrow={showcaseT<string>('iconsEyebrow')}
meta={`${iconNames.length} SVG / ${iconPackages.length} ${t<string>('packagesLabel')}`}
>
<NCard class="r-icon-library">
<div class="r-icon-library__toolbar">
<NInput
class="r-icon-library__search"
value={query.value}
onUpdateValue={(value) => {
query.value = value
}}
placeholder={t<string>('search')}
inputProps={{ 'aria-label': t<string>('search') }}
clearable
>
{{ prefix: () => <RIcon name="action/search" size={16} /> }}
</NInput>
<NSelect
class="r-icon-library__filter"
value={selectedPackage.value}
onUpdateValue={(value: string | null) => {
selectedPackage.value = value
}}
options={iconPackages.map((value) => ({ label: value, value }))}
clearable
placeholder={t<string>('allPackages')}
/>
<NRadioGroup
v-model:value={copyFormat.value}
aria-label={t<string>('copyFormat')}
>
<NRadioButton value="tsx">TSX</NRadioButton>
<NRadioButton value="vue">{t('vueTemplate')}</NRadioButton>
</NRadioGroup>
</div>
<div class="r-icon-library__hint">
<span>
{t('copy', {
format: copyFormat.value === 'tsx' ? 'TSX' : t('vueTemplate'),
})}
</span>
<span>
{filtered.value.length} / {iconNames.length}
</span>
</div>
{groups.value.map((group) => (
<section class="r-icon-library__group" key={group.name}>
<header>
<h2>{group.name}</h2>
<span>{group.icons.length}</span>
</header>
<div class="pre-view-icons__grid">
{group.icons.map((name) => (
<button
type="button"
class="pre-view-icons__card"
key={name}
title={name}
aria-label={name}
v-copy={`<${copyTag.value} name="${name}" />`}
>
<RIcon name={name} size={28} cursor="pointer" />
<span>{name.split('/').slice(1).join('/')}</span>
</button>
))}
</div>
</section>
))}
{!filtered.value.length ? (
<NEmpty description={t<string>('empty')} />
) : null}
</NCard>
</DemoPage>
)
},
})添加和生成
- 选择现有分包(如
action、navigation、system),或按业务新建分包。路径段使用小写字母、数字、下划线或连字符,且以字母开头。 - 单色图标用
currentColor,留白用none。品牌保留原色。 - 开发服务或
pnpm icons:generate更新packages/icons/src/manifest.ts;检查pnpm icons:check,与 SVG 一起提交。不要手改联合类型。
生产时每个顶层分包生成独立、带 hash 的雪碧图,资源随部署 base 加载。迁移时直接改旧代码的裸名称;旧缓存仅当文件名唯一时自动转换。
RIcon API
RIcon、IconProps、iconProps、IconName 和 IconPackage 从 @/components 导出。也可从 @/icons 导入图标类型。
| 属性 | 默认 | 说明 |
|---|---|---|
name | 必填 | 完整的分包路径,首段用于选择雪碧图。 |
size | 20 | 基础宽高,数字按像素,也可传 CSS 尺寸。 |
width / height | 0 / 0 | 分别覆盖基础尺寸,0 回退到 size。 |
color | 'currentColor' | SVG 填充色;带原色的品牌不会全部被覆盖。 |
prefix | 'icon' | symbol 前缀,须与生成配置一致。 |
customClassName | 无 | 根元素的额外类名。 |
depth | 1 | 图标透明层级。 |
cursor | 'inherit' | 默认继承所在控件的指针样式。 |
onClick(event) | 无 | 支持函数或回调数组。 |
图标内部 SVG 对读屏隐藏。如果用图标触发操作,把它放进具有可访问名称的按钮内,保留键盘操作和焦点。
图标来源
通用图标选自 Iconfont 的 IconPark 线性合辑。来源清单按用途列出包内名称和对应的 Iconfont ID。单色图标跟随文本颜色;Ray 和其他品牌标识保留各自原色。
已有图标名优先保留。三个退役资源的旧路由配置会在读取时迁移:action/export_excel → action/download、logo/office → navigation/table、illustration/login_bg → navigation/other。新代码直接使用新的完整名称。