ks-app-employment-service/docs/阿里图标库快速开始.md

阿里图标库快速开始 🚀

一、5分钟快速上手

Step 1: 下载图标文件（2分钟）

1. 访问 https://www.iconfont.cn/
2. 登录后搜索图标，点击"添加入库"
3. 购物车 → 添加至项目（没有项目先创建）
4. 我的项目 → 下载至本地

Step 2: 放置文件（1分钟）

解压下载的文件，将以下4个文件复制到 static/iconfont/ 目录：

✅ iconfont.css
✅ iconfont.ttf
✅ iconfont.woff
✅ iconfont.woff2

Step 3: 修改CSS路径（1分钟）

打开 static/iconfont/iconfont.css，将字体路径修改为相对路径：

@font-face {
  font-family: "iconfont";
  src: url('./iconfont.woff2?t=xxx') format('woff2'),
       url('./iconfont.woff?t=xxx') format('woff'),
       url('./iconfont.ttf?t=xxx') format('truetype');
}

Step 4: 全局引入（1分钟）

在 App.vue 的 <style> 标签中添加：

<style>
/* 引入阿里图标库 */
@import url("/static/iconfont/iconfont.css");
</style>

Step 5: 开始使用 ✨

<template>
  <!-- 直接使用 -->
  <text class="iconfont icon-home"></text>
  
  <!-- 或使用组件 -->
  <IconfontIcon name="home" :size="48" color="#13C57C" />
</template>

---

二、推荐使用方式

方式 A：使用封装的组件（最推荐）👍

<template>
  <IconfontIcon name="phone" :size="40" color="#13C57C" />
</template>

<script setup>
import IconfontIcon from '@/components/IconfontIcon/IconfontIcon.vue'
</script>

优点：

• ✅ 统一管理，易于维护
• ✅ 支持动态修改大小和颜色
• ✅ 语义清晰
• ✅ 支持点击事件

方式 B：使用配置常量（推荐）

<template>
  <IconfontIcon 
    :name="ICONS.HOME" 
    :size="ICON_SIZES.LARGE" 
    :color="ICON_COLORS.PRIMARY" 
  />
</template>

<script setup>
import IconfontIcon from '@/components/IconfontIcon/IconfontIcon.vue'
import { ICONS, ICON_SIZES, ICON_COLORS } from '@/config/icons'
</script>

优点：

• ✅ 统一图标名称
• ✅ 避免拼写错误
• ✅ IDE 自动补全
• ✅ 便于重构

方式 C：直接使用类名

<template>
  <text class="iconfont icon-home" style="font-size: 32rpx; color: #333;"></text>
</template>

---

三、常用场景示例

场景1：导航栏图标

<template>
  <view class="navbar">
    <IconfontIcon name="arrow-left" :size="40" @click="goBack" />
    <text class="title">页面标题</text>
    <IconfontIcon name="share" :size="36" @click="share" />
  </view>
</template>

<script setup>
const goBack = () => {
  uni.navigateBack()
}

const share = () => {
  // 分享逻辑
}
</script>

场景2：按钮图标

<template>
  <button class="primary-btn">
    <IconfontIcon name="phone" :size="32" color="#FFFFFF" />
    <text>手机号登录</text>
  </button>
</template>

<style>
.primary-btn {
  display: flex;
  align-items: center;
  gap: 12rpx;
}
</style>

场景3：列表项图标

<template>
  <view class="list-item">
    <IconfontIcon name="location" :size="36" color="#13C57C" />
    <text class="text">工作地点</text>
    <IconfontIcon name="arrow-right" :size="28" color="#999" />
  </view>
</template>

场景4：状态图标

<template>
  <view class="status-box">
    <IconfontIcon 
      :name="status.icon" 
      :size="64" 
      :color="status.color" 
    />
    <text>{{ status.text }}</text>
  </view>
</template>

<script setup>
import { computed } from 'vue'

const orderStatus = ref('success')

const status = computed(() => {
  const map = {
    success: { icon: 'success', color: '#13C57C', text: '提交成功' },
    error: { icon: 'error', color: '#F44336', text: '提交失败' },
    loading: { icon: 'loading', color: '#256BFA', text: '处理中...' }
  }
  return map[orderStatus.value]
})
</script>

---

四、组件API说明

IconfontIcon 组件

Props:

参数	类型	默认值	说明
name	String	-	图标名称（必填），如：'home' 或 'icon-home'
size	String/Number	32	图标大小，单位rpx
color	String	-	图标颜色，支持十六进制、rgb等
bold	Boolean	false	是否加粗

Events:

事件名	说明	回调参数
click	点击图标时触发	event

使用示例:

<IconfontIcon 
  name="home" 
  :size="48" 
  color="#13C57C"
  :bold="true"
  @click="handleClick"
/>

---

五、配置说明

图标名称配置（config/icons.js）

export const ICONS = {
  HOME: 'home',
  USER: 'user',
  SEARCH: 'search',
  // ... 更多图标
}

尺寸预设

export const ICON_SIZES = {
  MINI: 24,      // 24rpx
  SMALL: 28,     // 28rpx
  NORMAL: 32,    // 32rpx（默认）
  LARGE: 40,     // 40rpx
  XLARGE: 48,    // 48rpx
}

颜色预设

export const ICON_COLORS = {
  PRIMARY: '#13C57C',      // 主色调
  SECONDARY: '#256BFA',    // 次要色
  SUCCESS: '#13C57C',      // 成功
  WARNING: '#FF9800',      // 警告
  DANGER: '#F44336',       // 危险
  TEXT: '#333333',         // 文本色
}

---

六、常见问题

Q1: 图标不显示？

检查清单：

• 文件是否已复制到 static/iconfont/ 目录
• CSS路径是否正确修改
• 是否已在 App.vue 中引入
• 图标类名是否正确（如：icon-home）
• 清除缓存并重新编译

Q2: 如何查看可用的图标？

1. 打开下载包中的 demo_index.html
2. 或查看 iconfont.css 中的类名
3. 类名格式通常为 .icon-xxx:before

Q3: 如何更新图标？

1. 在阿里图标库添加新图标到项目
2. 重新下载至本地
3. 替换 static/iconfont/ 下的所有文件
4. 清除缓存，重新编译

Q4: 小程序能用在线链接吗？

❌ 不能！微信小程序必须使用本地字体文件。

---

七、最佳实践

✅ 推荐做法

1. 统一管理图标名称

   // 使用配置文件
   import { ICONS } from '@/config/icons'
   

2. 使用封装的组件

   <IconfontIcon name="home" />
   

3. 预设常用尺寸和颜色

   import { ICON_SIZES, ICON_COLORS } from '@/config/icons'
   

4. 语义化命名

   const ICONS = {
     HOME: 'home',           // ✅ 语义清晰
     USER_CENTER: 'user',    // ✅ 明确用途
   }
   

❌ 不推荐做法

1. 硬编码图标名称

   <text class="iconfont icon-home"></text>  <!-- ❌ 不推荐 -->
   

2. 使用在线链接（小程序）

   @import url("//at.alicdn.com/xxx.css");  /* ❌ 小程序不支持 */
   

3. 直接使用 Unicode

   <text class="iconfont">&#xe600;</text>  <!-- ❌ 不直观 -->
   

---

八、测试页面

已为你创建了测试页面，可以查看各种使用方式：

路径: pages/demo/iconfont-demo.vue

在 pages.json 中添加页面配置即可访问：

{
  "path": "pages/demo/iconfont-demo",
  "style": {
    "navigationBarTitleText": "图标示例"
  }
}

---

九、相关文件

项目结构：
├── components/
│   └── IconfontIcon/
│       └── IconfontIcon.vue          # 图标组件
├── config/
│   └── icons.js                      # 图标配置
├── static/
│   └── iconfont/
│       ├── iconfont.css              # 样式文件
│       ├── iconfont.ttf              # 字体文件
│       ├── iconfont.woff             # 字体文件
│       ├── iconfont.woff2            # 字体文件
│       └── README.md                 # 说明文档
├── pages/
│   └── demo/
│       └── iconfont-demo.vue         # 测试页面
└── docs/
    ├── 阿里图标库引入指南.md         # 详细文档
    └── 阿里图标库快速开始.md         # 本文档

---

十、总结

✅ 记住这三步：

1. 下载 - 从阿里图标库下载文件
2. 放置 - 复制到 static/iconfont/ 目录
3. 引入 - 在 App.vue 中引入 CSS

🎉 就是这么简单！

如有问题，请参考详细文档：docs/阿里图标库引入指南.md