Icon 图标
显示 @ns/icons 里的内置 SVG 图标,也可以通过插槽放自己的 SVG。图标颜色默认跟随文字颜色。
引入
import { NsIcon } from '@ns/ui'
基础用法
name 写图标名。可用的名字见 图标指南 的图标清单,共 67 个。
<script setup lang="ts">
import { NsIcon, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsIcon name="search" />
<NsIcon name="home" />
<NsIcon name="setting" />
<NsIcon name="user" />
<NsIcon name="bell" />
<NsIcon name="mail" />
</NsSpace>
</template>
写了清单以外的名字不会报错,但图标位置是一块 1em×1em(默认 16px)的空白。
全部图标
下面是 @ns/icons 里的全部 67 个图标,按用途分成 5 组。点一个图标复制它的名字。
<script setup lang="ts">
import { NsIcon, NsMessage } from '@ns/ui'
const groups = [
{
title: '方向和导航',
names: [
'home',
'menu',
'apps',
'top',
'arrow-up',
'arrow-down',
'arrow-left',
'arrow-right',
'chevron-up',
'chevron-down',
'chevron-left',
'chevron-right',
'double-left',
'double-right',
'caret-up',
'caret-down',
'caret-left',
'caret-right',
'more-horizontal',
'more-vertical'
]
},
{
title: '操作',
names: [
'close',
'check',
'plus',
'minus',
'edit',
'trash',
'refresh',
'copy',
'save',
'share',
'link',
'upload',
'download',
'filter',
'sort',
'drag',
'lock',
'eye',
'eye-off',
'zoom-in',
'zoom-out',
'rotate-left',
'rotate-right',
'fullscreen'
]
},
{
title: '状态',
names: [
'success',
'warning',
'error',
'info',
'help',
'loading',
'star',
'star-half',
'heart',
'clock',
'calendar'
]
},
{
title: '用户和通用',
names: ['user', 'users', 'setting', 'search', 'bell', 'phone', 'location', 'mail']
},
{ title: '文件', names: ['file', 'folder', 'image', 'table'] }
]
const copy = async (name: string) => {
try {
await navigator.clipboard.writeText(name)
NsMessage.success(`已复制 ${name}`)
} catch {
// 不是 HTTPS 或 localhost 时剪贴板不可用
NsMessage.warning(`复制失败,图标名是 ${name}`)
}
}
</script>
<template>
<div v-for="group in groups" :key="group.title" class="icon-group">
<div class="icon-group__title">{{ group.title }}({{ group.names.length }})</div>
<div class="icon-grid">
<button
v-for="name in group.names"
:key="name"
type="button"
class="icon-cell"
:title="`复制 ${name}`"
@click="copy(name)"
>
<NsIcon :name="name" size="xl" />
<span class="icon-cell__name">{{ name }}</span>
</button>
</div>
</div>
</template>
<style scoped>
.icon-group + .icon-group {
margin-top: var(--ns-spacing-4);
}
.icon-group__title {
margin-bottom: var(--ns-spacing-2);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.icon-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(104px, 1fr));
gap: var(--ns-spacing-2);
}
.icon-cell {
display: flex;
flex-direction: column;
align-items: center;
gap: var(--ns-spacing-2);
padding: var(--ns-spacing-3) var(--ns-spacing-1);
border: var(--ns-border-width) solid var(--ns-border-color-lighter);
border-radius: var(--ns-border-radius);
background: none;
color: var(--ns-text-color);
font: inherit;
cursor: pointer;
}
.icon-cell:hover {
color: var(--ns-color-primary);
border-color: var(--ns-color-primary);
}
.icon-cell__name {
font-size: var(--ns-font-size-xs);
color: var(--ns-text-color-secondary);
}
</style>
尺寸
size 可选 xs 12px、sm 14px、md 16px、lg 18px、xl 24px,默认 md。尺寸是固定的像素值,不随父元素的字号变化。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace size="large" align="end">
<NsSpace direction="vertical">
<NsIcon name="home" size="xs" />
<span class="size-label">xs 12px</span>
</NsSpace>
<NsSpace direction="vertical">
<NsIcon name="home" size="sm" />
<span class="size-label">sm 14px</span>
</NsSpace>
<NsSpace direction="vertical">
<NsIcon name="home" />
<span class="size-label">md 16px(默认)</span>
</NsSpace>
<NsSpace direction="vertical">
<NsIcon name="home" size="lg" />
<span class="size-label">lg 18px</span>
</NsSpace>
<NsSpace direction="vertical">
<NsIcon name="home" size="xl" />
<span class="size-label">xl 24px</span>
</NsSpace>
</NsSpace>
<!-- 父元素字号是 24px,图标仍是各自的尺寸 -->
<div style="font-size: 24px">
<NsSpace>
<span>24px 的文字</span>
<NsIcon name="star" size="xs" />
<NsIcon name="star" />
<NsIcon name="star" size="xl" />
</NsSpace>
</div>
</NsSpace>
</template>
<style scoped>
.size-label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-xs);
}
</style>
颜色
color 设置图标颜色,可以是任意 CSS 颜色值,包括主题变量;不传时跟随文字颜色(currentColor),放在彩色文字里就是文字的颜色。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsIcon name="success" size="xl" color="var(--ns-color-success)" />
<NsIcon name="warning" size="xl" color="var(--ns-color-warning)" />
<NsIcon name="error" size="xl" color="var(--ns-color-danger)" />
<NsIcon name="info" size="xl" color="var(--ns-color-info)" />
<NsIcon name="help" size="xl" color="var(--ns-color-help)" />
<NsIcon name="heart" size="xl" color="#eb2f96" />
<NsIcon name="star" size="xl" color="rgb(250, 173, 20)" />
</NsSpace>
<NsSpace wrap>
<span style="color: var(--ns-color-primary)"><NsIcon name="link" /> 跟随蓝色文字</span>
<span style="color: var(--ns-color-danger)"><NsIcon name="trash" /> 跟随红色文字</span>
<span style="color: var(--ns-text-color-secondary)">
<NsIcon name="clock" /> 跟随次要文字
</span>
</NsSpace>
</NsSpace>
</template>
动画
spin 让图标持续旋转,常用于加载中;pulse 让图标闪烁(透明度在 1 和 0.5 之间变化,不旋转)。两者都能和 size、color 一起用。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">spin</span>
<NsIcon name="loading" spin />
<NsIcon name="refresh" spin size="lg" />
<NsIcon name="setting" spin size="xl" color="var(--ns-color-primary)" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">pulse</span>
<NsIcon name="bell" pulse />
<NsIcon name="heart" pulse size="lg" color="var(--ns-color-danger)" />
<NsIcon name="warning" pulse size="xl" color="var(--ns-color-warning)" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 48px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
和文字一起用
图标是 inline-flex 的 1em×1em 方块,vertical-align: -0.15em,和文字放在一行时大致居中。
<template>
<NsSpace direction="vertical" align="start">
<span><NsIcon name="location" /> 北京市朝阳区</span>
<span><NsIcon name="phone" /> 010-12345678</span>
<span><NsIcon name="calendar" /> 2026-11-18 <NsIcon name="clock" /> 14:30</span>
<span style="font-size: 18px"><NsIcon name="folder" size="lg" /> 18px 的文字配 lg 图标</span>
</NsSpace>
</template>
组件没有事件。需要点击时给 NsIcon 绑 @click,会透传到根元素。下面点星星打分:
<script setup lang="ts">
import { ref } from 'vue'
import { NsIcon, NsSpace } from '@ns/ui'
const score = ref(3)
</script>
<template>
<NsSpace>
<NsIcon
v-for="i in 5"
:key="i"
name="star"
size="xl"
:color="i <= score ? 'var(--ns-color-warning)' : 'var(--ns-border-color)'"
style="cursor: pointer"
@click="score = i"
/>
<span>{{ score }} 分</span>
</NsSpace>
</template>
自定义类名
class 加在根元素上,可以用来写自己的样式,例如给图标加一个圆形底色。
<template>
<NsSpace wrap>
<NsIcon name="user" size="lg" class="icon-badge" />
<NsIcon name="mail" size="lg" class="icon-badge" />
<NsIcon name="bell" size="lg" class="icon-badge icon-badge--danger" />
</NsSpace>
</template>
<style scoped>
.icon-badge {
box-sizing: content-box;
padding: var(--ns-spacing-2);
border-radius: var(--ns-border-radius-circle);
color: var(--ns-color-primary);
background-color: var(--ns-color-primary-bg);
}
.icon-badge--danger {
color: var(--ns-color-danger);
background-color: var(--ns-color-danger-bg);
}
</style>
自定义图标
默认插槽可以放任意 SVG,size、color、spin、pulse 照样生效。SVG 要带 viewBox,填充色写 currentColor。没写 fill 的 <svg> 默认用文字颜色填充;只用描边的图形在 <svg> 或 <path> 上写 fill="none" 就不会被填满。
<template>
<NsSpace wrap>
<NsIcon name="layers" size="lg" color="#1890ff">
<svg viewBox="0 0 24 24" fill="currentColor">
<path d="M12 2 2 7l10 5 10-5-10-5z" />
</svg>
</NsIcon>
<NsIcon name="layers" size="xl" color="var(--ns-color-success)">
<svg viewBox="0 0 24 24">
<path
d="M12 2 2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linejoin="round"
/>
</svg>
</NsIcon>
<NsIcon name="spinner" size="xl" spin color="var(--ns-color-primary)">
<svg viewBox="0 0 24 24">
<path
d="M12 3a9 9 0 1 1-9 9"
fill="none"
stroke="currentColor"
stroke-width="3"
stroke-linecap="round"
/>
</svg>
</NsIcon>
<NsIcon name="dot" size="xl" pulse color="var(--ns-color-danger)">
<svg viewBox="0 0 24 24" fill="currentColor">
<circle cx="12" cy="12" r="6" />
</svg>
</NsIcon>
</NsSpace>
</template>
传了插槽时插槽内容优先,不再渲染 name 对应的内置图标。name 仍然必填,并会作为 aria-label 被读屏软件读出来,最好写一个有意义的名字。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | NsIconName | - | 图标名,必填。内置图标名在编辑器里有补全;传了默认插槽时只作为 aria-label |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | 图标尺寸:12px / 14px / 16px / 18px / 24px |
| color | string | undefined | 图标颜色,不传时跟随文字颜色 |
| spin | boolean | false | 是否持续旋转 |
| pulse | boolean | false | 是否闪烁(透明度在 1 和 0.5 之间变化) |
| class | string | '' | 追加到根元素上的类名 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 自定义图标内容,传了之后不再渲染 name 对应的内置图标 |
类型
import type { IconSize, IconProps, NsIconName } from '@ns/ui'
import type { IconName } from '@ns/icons'
type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
// IconName 是全部内置图标名的联合类型;string & {} 允许配合插槽写别的名字
type NsIconName = IconName | (string & {})
interface IconProps {
name: NsIconName
size?: IconSize
color?: string
spin?: boolean
pulse?: boolean
class?: string
}
注意事项
- 根元素是
<span class="ns-icon" role="img" aria-label="图标名">,读屏软件会把name当作图片名读出来。按钮、链接里只起装饰作用的图标会被读成英文名,例如 “search 搜索”。 - 图标是
inline-flex的 1em×1em 方块,vertical-align: -0.15em,和文字放在一行时大致居中。 - 组件没有事件,也没有暴露方法。需要点击时给外层元素或
NsIcon本身绑@click(会透传到根元素)。
优化点
- [ ] 支持更多图标库导入方式
- [ ] 支持图标悬停效果配置
- [ ] 增加图标搜索和预览工具