ks-app-employment-service/docs/阿里图标库引入指南.md

# 阿里图标库（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'
```

### 第六步：使用图标

#### 使用方式 1：Unicode 方式

```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>
```

#### 使用方式 2：Font 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
- [ ] 已测试图标显示正常
- [ ] 已封装图标组件（可选）
- [ ] 已统一管理图标名称（可选）