更新记录

2.0.0（2025-07-13） 下载此版本

修复若干已知问题

平台兼容性

uni-app(4.35)

uni-app x(4.35)

其他

🎨 Neurix Font Loader - 全平台字体加载器

v2.0.0 支持本地+远程字体，Vue 2/3、UniApp X、鸿蒙Next全平台兼容，智能域名切换，完美中英文支持！

✨ 核心特性

🎯 零配置使用 - 安装即用，无需复杂配置
🌐 全平台兼容 - Vue 2/3、UniApp X、鸿蒙Next、小程序、H5、App全支持
📁 本地+远程字体 - 支持本地字体文件和远程字体URL加载
🔤 Google Fonts 优化 - 内置9种精选Google字体，中英文完美支持
🌍 智能域名切换 - 自动检测地域，国内外用户体验一致
⚡ 性能优化 - 智能缓存，多格式支持，加载速度快
🎨 主题预设 - 内置10种主题，支持自定义主题
💾 持久化存储 - 用户选择自动保存，刷新页面不丢失
🔧 TypeScript 支持 - 完整类型定义，开发体验极佳

🚀 快速开始

1. 安装插件

通过 uni_modules 导入插件到你的项目中。

2. 选择适合的版本

根据你的项目框架选择对应的插件版本：

3. 基础用法

Vue 3 项目

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import FontPlugin from './uni_modules/neurix-font-loader/js_sdk/font-plugin-vue3.js'

const app = createApp(App)

app.use(FontPlugin, {
  cache: true,              // 启用智能缓存
  persistTheme: true,       // 持久化主题选择
  autoLoad: false,          // 按需加载
  globalFont: 'Inter'       // 默认字体
})

app.mount('#app')

Vue 2 项目

// main.js
import Vue from 'vue'
import App from './App.vue'
import FontPlugin from './uni_modules/neurix-font-loader/js_sdk/font-plugin-vue2.js'

Vue.use(FontPlugin, {
  cache: true,
  persistTheme: true,
  globalFont: 'Inter'
})

new Vue({
  render: h => h(App)
}).$mount('#app')

UniApp X 项目

// main.uts
import App from './App.uvue'
import FontPlugin from './uni_modules/neurix-font-loader/js_sdk/font-plugin-vue3.js'
import { createSSRApp } from 'vue'

export function createApp() {
  const app = createSSRApp(App)

  app.use(FontPlugin, {
    cache: true,
    persistTheme: true,
    globalFont: 'Inter'
  })

  return { app }
}

📋 字体支持

🌐 远程字体

Google Fonts (内置)

中文字体

自定义远程字体

// 加载自定义远程字体
await this.$loadWebFont('CustomFont', 'https://example.com/fonts/custom.woff2')
this.$setGlobalFont('CustomFont')

📁 本地字体

支持格式

• TTF - TrueType Font (推荐)
• WOFF2 - Web Open Font Format 2.0 (现代浏览器)
• WOFF - Web Open Font Format (兼容性好)
• OTF - OpenType Font

本地字体使用

// 加载本地字体文件
await this.$loadLocalFont('MyLocalFont', '/static/fonts/my-font.ttf')
this.$setGlobalFont('MyLocalFont')

// 或者使用详细配置
await this.$loadFont({
  fontFamily: 'MyLocalFont',
  src: '/static/fonts/my-font.woff2',
  format: 'woff2',
  type: 'local',
  cache: true
})

🎯 主题预设

内置 10 种精心设计的主题，一键切换：

// 英文主题
this.$switchTheme('modern')        // 现代简约 (Inter)
this.$switchTheme('elegant')       // 优雅衬线 (Playfair Display)
this.$switchTheme('code')          // 程序员专用 (Source Code Pro)
this.$switchTheme('handwriting')   // 手写风格 (Dancing Script)
this.$switchTheme('robust')        // 谷歌经典 (Roboto)
this.$switchTheme('elegant_modern') // 优雅现代 (Lato)

// 中文主题
this.$switchTheme('chinese_modern')     // 中文现代 (Noto Sans SC)
this.$switchTheme('chinese_traditional') // 龙藏古韵 (Long Cang)
this.$switchTheme('chinese_handwriting') // 马善手写 (Ma Shan Zheng)
this.$switchTheme('system')             // 系统默认

🔧 核心 API

基础字体操作

// 加载字体（自动识别本地/远程）
await this.$loadFont('Inter')                    // 内置字体
await this.$loadFont('/static/fonts/local.ttf') // 本地字体
await this.$loadFont('https://fonts.com/remote.woff2') // 远程字体

// 加载本地字体
await this.$loadLocalFont('LocalFont', '/static/fonts/font.ttf')

// 加载远程字体
await this.$loadWebFont('RemoteFont', 'https://example.com/font.woff2')

// 设置全局字体
this.$setGlobalFont('Inter')

// 获取当前字体
const currentFont = this.$getCurrentFont()

// 检查字体是否已加载
const isLoaded = this.$isFontLoaded('Inter')

主题管理

// 获取所有主题预设
const themes = this.$getThemePresets()

// 应用主题
await this.$applyTheme('modern')

// 获取当前主题
const currentTheme = this.$getCurrentTheme()

// 快速切换主题
await this.$switchTheme('elegant')

字体列表

// 获取内置字体
const builtinFonts = this.$getBuiltinFonts()

// 获取远程字体
const remoteFonts = this.$getRemoteFonts()

// 获取中文字体
const chineseFonts = this.$getChineseFonts()

// 获取所有可用字体
const allFonts = this.$getAvailableFonts()

// 获取已加载字体
const loadedFonts = this.$getLoadedFonts()

🌍 智能域名切换

插件内置智能地域检测，自动为不同地区用户选择最优域名：

• 🇨🇳 中国大陆用户: 自动使用 gstatic.aby.pub 镜像
• 🌍 海外用户: 使用 Google 官方域名 fonts.gstatic.com

检测机制：

1. 时区检测 - 检查用户系统时区
2. 语言检测 - 分析浏览器语言设置
3. 网络测试 - 通过延迟测试确定位置

📱 平台兼容

支持平台

浏览器支持

⚙️ 配置选项

app.use(FontPlugin, {
  // 基础配置
  cache: true,                    // 启用缓存 (默认: true)
  autoLoad: false,                // 自动加载 (默认: false)
  globalFont: 'Inter',            // 默认字体 (默认: '')

  // 高级配置
  persistTheme: true,             // 持久化主题 (默认: true)
  preloadBuiltinFonts: false,     // 预加载内置字体 (默认: false)
})

🎨 在组件中使用

模板使用

<template>
  <!-- 使用全局字体 -->
  <div class="content">
    这段文字会使用全局字体
  </div>

  <!-- 指定特定字体 -->
  <neurix-font font-family="Inter">
    <div class="special-text">
      这段文字使用 Inter 字体
    </div>
  </neurix-font>
</template>

动态切换

<template>
  <div>
    <button @click="changeFont('Inter')">现代UI</button>
    <button @click="changeFont('Roboto')">谷歌经典</button>
    <button @click="changeFont('NotoSansSC')">中文字体</button>
    <button @click="loadLocalFont()">加载本地字体</button>
  </div>
</template>

<script>
export default {
  methods: {
    async changeFont(fontName) {
      try {
        await this.$loadFont(fontName)
        this.$setGlobalFont(fontName)
        uni.showToast({
          title: `已切换到 ${fontName}`,
          icon: 'success'
        })
      } catch (error) {
        console.error('字体切换失败:', error)
      }
    },

    async loadLocalFont() {
      try {
        // 加载本地字体文件
        await this.$loadLocalFont('MyFont', '/static/fonts/my-font.ttf')
        this.$setGlobalFont('MyFont')
        uni.showToast({
          title: '本地字体加载成功',
          icon: 'success'
        })
      } catch (error) {
        console.error('本地字体加载失败:', error)
      }
    }
  }
}
</script>

📝 TypeScript 支持

插件提供完整的 TypeScript 类型定义，支持 Vue 2 和 Vue 3 项目。

🎯 类型定义文件

• Vue 3: /js_sdk/types.d.ts - 完整类型定义文件
• Vue 2: /js_sdk/types-vue2.d.ts - Vue 2专用类型定义

🚀 TypeScript 配置

Vue 3 + TypeScript

main.ts 配置

import { createSSRApp } from 'vue'
import App from './App.vue'
import FontPlugin from './uni_modules/neurix-font-loader/js_sdk/font-plugin-vue3.js'
import type { PluginOptions } from './uni_modules/neurix-font-loader/js_sdk/types'

export function createApp() {
  const app = createSSRApp(App)

  const fontOptions: PluginOptions = {
    cache: true,
    persistTheme: true,
    globalFont: 'Inter',
    autoLoad: false,
    preloadBuiltinFonts: false
  }

  app.use(FontPlugin, fontOptions)
  return { app }
}

Vue 2 + TypeScript

import Vue from 'vue'
import App from './App.vue'
import FontPlugin from './uni_modules/neurix-font-loader/js_sdk/font-plugin-vue2.js'
import type { PluginOptions } from './uni_modules/neurix-font-loader/js_sdk/types-vue2'

const fontOptions: PluginOptions = {
  cache: true,
  persistTheme: true,
  globalFont: '',          // Vue 2建议留空
  autoLoad: false,
  preloadBuiltinFonts: false
}

Vue.use(FontPlugin, fontOptions)

🔗 核心类型定义

// 字体配置
interface FontConfig {
  fontFamily: string
  src: string
  backupSrc?: string
  format?: 'woff2' | 'woff' | 'ttf' | 'otf'
  type?: 'local' | 'remote'
  cache?: boolean
}

// 字体信息
interface FontInfo {
  name: string
  displayName: string
  url?: string
  type: 'local' | 'remote'
  loaded: boolean
  builtin?: boolean
  description?: string
}

// 主题预设
interface ThemePreset {
  key: string
  name: string
  font: string
  description: string
  loaded: boolean
  icon?: string
}

// 插件配置
interface PluginOptions {
  cache?: boolean
  persistTheme?: boolean
  autoLoad?: boolean
  preloadBuiltinFonts?: boolean
  globalFont?: string
}

// 主题键值类型
type ThemeKey = 
  | 'modern' | 'elegant' | 'code' | 'handwriting'
  | 'robust' | 'elegant_modern'
  | 'chinese_modern' | 'chinese_traditional' | 'chinese_handwriting'
  | 'system'

💻 TypeScript 使用示例

// 类型安全的字体加载
const loadCustomFont = async (): Promise<void> => {
  const fontConfig: FontConfig = {
    fontFamily: 'MyCustomFont',
    src: '/static/fonts/custom-font.ttf',
    format: 'ttf',
    type: 'local',
    cache: true
  }

  await proxy!.$fontLoader.loadFont(fontConfig)
  const success = await proxy!.$setGlobalFont('MyCustomFont')

  if (success) {
    uni.showToast({ title: '字体加载成功', icon: 'success' })
  }
}

// 类型安全的主题切换
const switchTheme = async (themeKey: ThemeKey): Promise<boolean> => {
  try {
    await proxy!.$ensureFontLoaderInit()
    return await proxy!.$switchTheme(themeKey)
  } catch (error: unknown) {
    if (error instanceof Error) {
      console.error('主题切换失败:', error.message)
    }
    return false
  }
}

🔍 故障排除

常见问题

Q: 字体加载失败怎么办？ A: 检查网络连接和字体文件路径，插件会自动重试并使用备用域名。

Q: 本地字体不显示？ A: 确保字体文件路径正确，支持相对路径和绝对路径。推荐放在 /static/fonts/ 目录下。

Q: 中文字体显示不完整？ A: 推荐使用 Noto Sans SC，支持完整的中文字符集。

Q: 自定义字体格式选择？ A: 现代浏览器推荐 WOFF2，兼容性考虑使用 TTF。

Q: 主题切换后页面刷新丢失？ A: 确保配置中开启了 persistTheme: true。

Q: UniApp X 项目中字体不生效？ A: 使用专用的 font-plugin-uniappx.js 版本。

调试信息

开启调试模式查看详细日志：

// 在浏览器控制台中查看
console.log('当前CDN信息:', this.$getCDNInfo())
console.log('已加载字体:', this.$getLoadedFonts())
console.log('当前字体:', this.$getCurrentFont())
console.log('可用字体:', this.$getAvailableFonts())

📦 版本历史

完整更新日志请查看 CHANGELOG.md

v2.0.0 (2025-07-13) - Google Fonts 专版

• 🔥 全面支持 Google Fonts
• 🌍 智能域名切换 - 自动检测地域选择最优域名
• 📁 本地+远程字体 - 完善的本地和远程字体支持
• 🎨 精简字体库 - 精选 9 种高质量字体
• ⚡ 性能优化 - TTF 格式，加载速度提升 50%
• 🛠️ 重构核心 - 更稳定的字体管理机制
• 🐛 修复重置问题 - 解决系统默认字体重置错误
• 📱 全平台兼容 - Vue 2/3、UniApp X、鸿蒙Next全支持

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！