跳转到正文

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 { useI18n } from '@/hooks'
import { iconNames, iconPackages } from '@/icons'
import { RIcon } from '@ray-template/ui/icon'
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>
    )
  },
})

添加和生成 ​

  1. 选择现有分包(如 action、navigation、system),或按业务新建分包。路径段使用小写字母、数字、下划线或连字符,且以字母开头。
  2. 单色图标用 currentColor,留白用 none。品牌保留原色。
  3. 开发服务或 pnpm icons:generate 更新 packages/icons/src/manifest.ts;检查 pnpm icons:check,与 SVG 一起提交。不要手改联合类型。

生产时每个顶层分包生成独立、带 hash 的雪碧图,资源随部署 base 加载。迁移时直接改旧代码的裸名称;旧缓存仅当文件名唯一时自动转换。

图标流程与分包表

RIcon API ​

RIcon、IconProps、iconProps、IconName 和 IconPackage 从 @/components 导出。也可从 @/icons 导入图标类型。

属性默认说明
name必填完整的分包路径,首段用于选择雪碧图。
size20基础宽高,数字按像素,也可传 CSS 尺寸。
width / height0 / 0分别覆盖基础尺寸,0 回退到 size。
color'currentColor'SVG 填充色;带原色的品牌不会全部被覆盖。
prefix'icon'symbol 前缀,须与生成配置一致。
customClassName无根元素的额外类名。
depth1图标透明层级。
cursor'inherit'默认继承所在控件的指针样式。
onClick(event)无支持函数或回调数组。

图标内部 SVG 对读屏隐藏。如果用图标触发操作,把它放进具有可访问名称的按钮内,保留键盘操作和焦点。

RIcon Props · 雪碧图引用实现

图标来源 ​

通用图标选自 Iconfont 的 IconPark 线性合辑。来源清单按用途列出包内名称和对应的 Iconfont ID。单色图标跟随文本颜色;Ray 和其他品牌标识保留各自原色。

已有图标名优先保留。三个退役资源的旧路由配置会在读取时迁移:action/export_excel → action/download、logo/office → navigation/table、illustration/login_bg → navigation/other。新代码直接使用新的完整名称。