Files
ks-app-employment-service/docs/阿里图标库引入指南.md
2025-10-20 16:15:29 +08:00

430 lines
8.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 阿里图标库iconfont引入指南
## 📦 方式一:使用字体文件(推荐)
### 第一步:下载图标资源
1. 访问 [阿里图标库](https://www.iconfont.cn/)
2. 注册/登录账号
3. 搜索需要的图标,点击"添加入库"
4. 点击右上角购物车图标
5. 点击"添加至项目"(如果没有项目,先创建一个)
6. 进入"我的项目"
7. 点击"下载至本地"按钮
### 第二步:解压并复制文件
下载的压缩包中包含以下文件:
```
iconfont.css
iconfont.ttf
iconfont.woff
iconfont.woff2
iconfont.json
demo_index.html
demo.css
```
**需要的文件:**
- `iconfont.css` - 样式文件
- `iconfont.ttf` - 字体文件
- `iconfont.woff` - 字体文件
- `iconfont.woff2` - 字体文件
### 第三步:创建项目目录
在项目中创建 `static/iconfont/` 目录(如果不存在):
```
ks-app-employment-service/
├── static/
│ ├── iconfont/ ← 新建此目录
│ │ ├── iconfont.css
│ │ ├── iconfont.ttf
│ │ ├── iconfont.woff
│ │ └── iconfont.woff2
│ └── ...
```
### 第四步:修改 CSS 文件
打开 `static/iconfont/iconfont.css`,修改字体文件路径:
**原始路径:**
```css
@font-face {
font-family: "iconfont";
src: url('iconfont.woff2?t=1234567890') format('woff2'),
url('iconfont.woff?t=1234567890') format('woff'),
url('iconfont.ttf?t=1234567890') format('truetype');
}
```
**修改为(相对路径):**
```css
@font-face {
font-family: "iconfont";
src: url('./iconfont.woff2?t=1234567890') format('woff2'),
url('./iconfont.woff?t=1234567890') format('woff'),
url('./iconfont.ttf?t=1234567890') format('truetype');
}
```
**或修改为(绝对路径,推荐):**
```css
@font-face {
font-family: "iconfont";
src: url('/static/iconfont/iconfont.woff2?t=1234567890') format('woff2'),
url('/static/iconfont/iconfont.woff?t=1234567890') format('woff'),
url('/static/iconfont/iconfont.ttf?t=1234567890') format('truetype');
}
```
### 第五步:在项目中引入
#### 方法 A全局引入App.vue
`App.vue` 中引入:
```vue
<style>
/* 引入阿里图标库 */
@import url("/static/iconfont/iconfont.css");
/* 其他全局样式 */
@import '@/common/animation.css';
@import '@/common/common.css';
</style>
```
#### 方法 B在 main.js 中引入
```javascript
// main.js
import './static/iconfont/iconfont.css'
```
### 第六步:使用图标
#### 使用方式 1Unicode 方式
```vue
<template>
<view class="icon">&#xe600;</view>
</template>
<style>
.icon {
font-family: "iconfont" !important;
font-size: 32rpx;
font-style: normal;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
</style>
```
#### 使用方式 2Font Class 方式(推荐)
```vue
<template>
<view class="iconfont icon-home"></view>
<view class="iconfont icon-user"></view>
<view class="iconfont icon-search"></view>
</template>
<style scoped>
.iconfont {
font-size: 32rpx;
color: #333;
}
</style>
```
#### 使用方式 3封装为组件
创建 `components/IconfontIcon/IconfontIcon.vue`
```vue
<template>
<text class="iconfont" :class="iconClass" :style="iconStyle"></text>
</template>
<script setup>
import { computed } from 'vue'
const props = defineProps({
name: {
type: String,
required: true
},
size: {
type: [String, Number],
default: 32
},
color: {
type: String,
default: '#333'
}
})
const iconClass = computed(() => `icon-${props.name}`)
const iconStyle = computed(() => ({
fontSize: `${props.size}rpx`,
color: props.color
}))
</script>
<style scoped>
.iconfont {
font-style: normal;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
</style>
```
**使用组件:**
```vue
<template>
<IconfontIcon name="home" :size="48" color="#13C57C" />
<IconfontIcon name="user" :size="36" color="#256BFA" />
</template>
<script setup>
import IconfontIcon from '@/components/IconfontIcon/IconfontIcon.vue'
</script>
```
---
## 📦 方式二:使用在线链接(不推荐小程序)
### 第一步:获取在线链接
1. 在阿里图标库"我的项目"中
2. 点击"Font class"
3. 点击"查看在线链接"
4. 复制 CSS 链接
### 第二步:引入在线 CSS
`App.vue` 中:
```vue
<style>
/* 注意:小程序不支持在线字体 */
@import url("//at.alicdn.com/t/c/font_xxxxx.css");
</style>
```
**⚠️ 注意:** 微信小程序不支持外部字体文件,必须使用方式一!
---
## 📦 方式三:使用 Symbol 方式SVG
### 第一步:获取 Symbol 代码
1. 在"我的项目"中
2. 点击"Symbol"
3. 点击"生成代码"
4. 复制生成的 JS 链接
### 第二步:下载 JS 文件
将 JS 文件下载到 `static/iconfont/iconfont.js`
### 第三步:引入并使用
`App.vue` 或需要的页面中:
```vue
<template>
<svg class="icon" aria-hidden="true">
<use xlink:href="#icon-home"></use>
</svg>
</template>
<script>
// 引入 Symbol 脚本
// 注意:需要在 main.js 中引入 iconfont.js
</script>
<style>
.icon {
width: 1em;
height: 1em;
vertical-align: -0.15em;
fill: currentColor;
overflow: hidden;
}
</style>
```
**⚠️ 注意:** 小程序对 SVG 支持有限,推荐使用方式一!
---
## 🎯 最佳实践建议
### 1. 使用 Font Class 方式(方式一)
**优点:**
- ✅ 兼容性好,支持所有平台
- ✅ 可以自定义颜色和大小
- ✅ 语义化强,易于维护
- ✅ 体积小,加载快
**缺点:**
- ❌ 只支持单色图标
### 2. 创建图标组件库
```
components/
├── IconfontIcon/
│ └── IconfontIcon.vue # 通用图标组件
```
### 3. 统一管理图标名称
创建 `config/icons.js`
```javascript
// 图标配置
export const ICONS = {
HOME: 'home',
USER: 'user',
SEARCH: 'search',
LOCATION: 'location',
PHONE: 'phone',
// ... 更多图标
}
```
使用:
```vue
<script setup>
import { ICONS } from '@/config/icons'
</script>
<template>
<IconfontIcon :name="ICONS.HOME" />
</template>
```
---
## 🔧 常见问题
### Q1: 小程序中图标不显示?
**解决方案:**
- 确保使用本地字体文件,不要使用在线链接
- 检查 CSS 中的字体路径是否正确
- 确保字体文件已正确复制到 `static/iconfont/` 目录
### Q2: 图标显示为方框?
**解决方案:**
- 检查字体文件是否完整
- 检查 `@font-face``font-family` 名称是否一致
- 清除缓存重新编译
### Q3: 如何更新图标库?
1. 在阿里图标库添加新图标到项目
2. 重新下载至本地
3. 替换 `static/iconfont/` 下的所有文件
4. 清除缓存,重新编译
### Q4: H5 和小程序路径不一致?
**解决方案:**
使用条件编译:
```css
@font-face {
font-family: "iconfont";
/* #ifdef H5 */
src: url('/static/iconfont/iconfont.woff2') format('woff2');
/* #endif */
/* #ifdef MP-WEIXIN */
src: url('./iconfont.ttf') format('truetype');
/* #endif */
}
```
---
## 📝 示例代码
### 完整示例:登录按钮
```vue
<template>
<button class="login-btn">
<text class="iconfont icon-phone"></text>
<text>手机号登录</text>
</button>
</template>
<style scoped>
.login-btn {
display: flex;
align-items: center;
justify-content: center;
padding: 20rpx 40rpx;
background: #13C57C;
border-radius: 12rpx;
color: #fff;
}
.iconfont {
font-size: 32rpx;
margin-right: 12rpx;
}
</style>
```
---
## 🎨 推荐使用的图标
### 常用图标
- `icon-home` - 首页
- `icon-user` - 用户
- `icon-search` - 搜索
- `icon-location` - 位置
- `icon-phone` - 电话
- `icon-message` - 消息
- `icon-setting` - 设置
- `icon-star` - 收藏
- `icon-share` - 分享
- `icon-close` - 关闭
---
## 📚 相关资源
- [阿里图标库官网](https://www.iconfont.cn/)
- [uni-app 字体图标文档](https://uniapp.dcloud.net.cn/tutorial/syntax-css.html#%E5%AD%97%E4%BD%93%E5%9B%BE%E6%A0%87)
- [CSS @font-face](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@font-face)
---
## ✅ 检查清单
- [ ] 已下载图标文件到 `static/iconfont/` 目录
- [ ] 已修改 CSS 中的字体文件路径
- [ ] 已在 App.vue 中引入 iconfont.css
- [ ] 已测试图标显示正常
- [ ] 已封装图标组件(可选)
- [ ] 已统一管理图标名称(可选)