千字网 CDN

主题

使用教程 ​

教程目标
通过本教程，您将学会如何在项目中快速集成千字网 CDN 的中文字体服务

快速开始（三步上手） ​

只需三步，即可在您的项目中使用精美的中文字体：

第一步：选择字体 ​

浏览 字体列表，找到心仪的字体

字体列表说明

字体列表采用 TOML 格式，包含字体文件夹名、字体族名和描述信息，方便您快速定位所需字体

第二步：引入字体 ​

在 CSS 文件中添加引用：

css
@import url("https://hanzi.itedev.com/fonts/字体文件夹/result.css");

第三步：应用字体 ​

设置 font-family 属性：

css
body {
    font-family: '字体族名', sans-serif;
}

恭喜！字体已经可以使用了！

详细教程 ​

1. 查找字体 ​

访问 font_mapping.toml 文件，查看所有可用字体。

文件格式示例：

toml
[Source+Han+Sans+VF]
family = "Source Han Sans VF"
description = "思源黑体可变字体"

字段说明：

字段说明用途
[Source+Han+Sans+VF]字体文件夹名用于构建 URL
family = "Source Han Sans VF"字体族名用于 CSS 中的 font-family
description = "思源黑体可变字体"字体描述帮助理解字体特征

2. 引用字体文件 ​

在 CSS 文件中添加引用：

css
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

域名选择：

域名说明推荐场景
https://hanzi.itedev.com主域名，国内优化国内用户（推荐）
https://hanzi.qzz.ioCloudflare 代理海外用户
https://hanzi.bluu.pl备用域名Codeberg Pages 项目

注意事项

  • 建议在项目中配置备用域名，提高服务可用性
  • 不同域名的访问速度可能因地区而异，请根据实际情况选择

3. 应用字体 ​

在 CSS 中设置字体：

css
/* 全局应用 */
body {
    font-family: 'Source Han Sans VF', sans-serif;
}

/* 标题应用 */
h1, h2, h3 {
    font-family: 'Source Han Sans VF', sans-serif;
    font-weight: bold;
}

/* 特定元素应用 */
.custom-text {
    font-family: 'Source Han Sans VF', sans-serif;
}

4. 验证效果 ​

在浏览器中打开您的网页，检查字体是否正确加载。

验证步骤：

  1. 打开浏览器开发者工具（按 F12 键）
  2. 选择 "Network"（网络）标签
  3. 刷新页面
  4. 查看是否有字体文件加载成功

预期结果：

  • 在 Network 标签中可以看到 .woff2 或 .woff 格式的字体文件
  • 状态码为 200 表示加载成功
  • 字体文件大小通常在几 KB 到几 MB 之间

配置选项 ​

font-display 属性 ​

控制字体加载时的显示行为：

css
@font-face {
    font-family: '字体族名';
    font-display: swap; /* 推荐值 */
}

参数说明：

值说明适用场景
auto浏览器默认行为不确定时使用
block字体加载前不显示文本字体必须精确显示时
swap立即显示后备字体，字体加载后替换推荐使用，提升用户体验
fallback短时间显示后备字体，超时后使用默认字体平衡加载速度和显示效果
optional字体加载快则使用，否则使用默认字体性能优先场景

推荐

千字网 CDN 已默认设置为 swap，确保用户能立即看到内容，提升用户体验

font-weight 属性 ​

通过 CSS 控制字体粗细：

css
/* 常规（默认） */
.normal {
    font-weight: normal; /* 或 400 */
}

/* 粗体 */
.bold {
    font-weight: bold; /* 或 700 */
}

/* 数值控制（更精细） */
.thin {
    font-weight: 100;
}

.medium {
    font-weight: 500;
}

.extra-bold {
    font-weight: 900;
}

常用值对照表：

数值关键字说明
100-极细
200-特细
300-细
400normal常规
500-中等
600-半粗
700bold粗体
800-特粗
900-极粗

font-style 属性 ​

控制字体样式：

css
/* 常规（默认） */
.normal {
    font-style: normal;
}

/* 斜体 */
.italic {
    font-style: italic;
}

/* 倾斜（模拟斜体） */
.oblique {
    font-style: oblique;
}

示例项目 ​

HTML + CSS 项目 ​

index.html：

html
<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>千字网 CDN 字体示例</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>欢迎使用千字网 CDN</h1>
    <p>这是一个使用千字网 CDN 字体的示例页面。</p>
    <p class="bold">这是粗体文本。</p>
    <p class="italic">这是斜体文本。</p>
</body>
</html>

style.css：

css
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

body {
    font-family: 'Source Han Sans VF', sans-serif;
    line-height: 1.6;
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
}

h1 {
    font-size: 2em;
    margin-bottom: 0.5em;
    font-weight: bold;
}

.bold {
    font-weight: bold;
}

.italic {
    font-style: italic;
}

Vue.js 项目 ​

在 Vue 组件中引入：

vue
<template>
  <div class="container">
    <h1>Vue.js 字体示例</h1>
    <p>使用千字网 CDN 字体</p>
  </div>
</template>

<script>
export default {
  name: 'FontExample'
}
</script>

<style>
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

.container {
  font-family: 'Source Han Sans VF', sans-serif;
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
}

h1 {
  font-size: 2em;
  margin-bottom: 0.5em;
  font-weight: bold;
}
</style>

React 项目 ​

在 React 组件中引入：

App.jsx：

jsx
import React from 'react';
import './App.css';

function App() {
  return (
    <div className="container">
      <h1>React 字体示例</h1>
      <p>使用千字网 CDN 字体</p>
    </div>
  );
}

export default App;

App.css：

css
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

.container {
    font-family: 'Source Han Sans VF', sans-serif;
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
}

h1 {
    font-size: 2em;
    margin-bottom: 0.5em;
    font-weight: bold;
}

进阶用法 ​

预加载字体 ​

提升字体加载速度，减少布局偏移：

html
<head>
    <link rel="preload" href="https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css" as="style">
    <link rel="stylesheet" href="style.css">
</head>

性能优化

预加载可以让浏览器提前发现并加载字体文件，减少首屏渲染时间

多字体组合 ​

在项目中使用多个字体：

css
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");
@import url("https://hanzi.itedev.com/fonts/Source+Han+Serif+VF/result.css");

/* 无衬线字体用于正文 */
body {
    font-family: 'Source Han Sans VF', sans-serif;
}

/* 衬线字体用于标题或引用 */
.serif-text {
    font-family: 'Source Han Serif VF', serif;
}

字体回退方案 ​

设置字体回退，确保在字体加载失败时有替代方案：

css
body {
    font-family: 'Source Han Sans VF', 'PingFang SC', 'Microsoft YaHei', 'Hiragino Sans GB', sans-serif;
}

回退顺序：

  1. 首选：Source Han Sans VF（千字网 CDN）
  2. 备选1：PingFang SC（macOS 系统字体）
  3. 备选2：Microsoft YaHei（Windows 系统字体）
  4. 备选3：Hiragino Sans GB（部分系统字体）
  5. 最终：sans-serif（浏览器默认无衬线字体）

常见问题 ​

字体没有生效？ ​

排查步骤：

  1. 检查 CSS 是否正确引入

    • 确认 @import 语句是否在 CSS 文件顶部
    • 检查 URL 是否正确，无拼写错误

  2. 检查 font-family 名称

    • 确认字体族名与字体列表中的完全一致
    • 注意大小写和空格

  3. 查看浏览器控制台

    • 打开开发者工具（F12）
    • 查看 Console 标签是否有错误信息
    • 查看 Network 标签，确认字体文件是否加载成功

  4. 确认字体 URL 可访问

    • 在浏览器中直接访问字体 CSS 文件
    • 确认能正常返回内容

加载速度慢？ ​

优化建议：

  1. 使用推荐域名

    css
    /* 国内用户推荐 */
@import url("https://hanzi.itedev.com/fonts/字体文件夹/result.css");

  2. 检查网络连接

    • 确认网络连接正常
    • 尝试切换网络环境

  3. 使用预加载

    html
    <link rel="preload" href="字体URL" as="style">

  4. 配置字体回退

    • 设置系统字体作为回退，确保内容始终可见

字体显示异常？ ​

可能原因：

  1. 字体文件未完全加载

    • 等待字体加载完成
    • 使用 font-display: swap 改善体验

  2. 浏览器缓存问题

    • 清除浏览器缓存
    • 强制刷新页面（Ctrl+F5）

  3. CSS 优先级问题

    • 检查是否有其他样式覆盖了字体设置
    • 使用开发者工具查看计算后的样式

相关资源 ​

小贴士
如果您在使用过程中遇到任何问题，欢迎通过 邮箱 或 Codeberg 联系我们！

基于 MIT 许可发布 | 支持开源

版权所有 © 2024-present Exyone Dev