更新系统

目的与范围

更新系统是一套Python脚本和实用程序，可将 Material Design Icons 代码库与 Google Fonts 提供的最新图标版本保持同步。它会自动检索新图标和更新的图标，以下载各种格式（SVG、Android XML、iOS 文件等）的资源，处理字体文件，并生成字形映射文件。该系统确保代码库在最少人工干预的情况下保持最新。

本文档涵盖了更新脚本的技术实现。有关 Material Icons 和 Material Symbols 的区别，请参阅 Material Icons vs. Material Symbols。有关在项目中如何使用这些图标的详细信息，请参阅 Getting Started。

来源： update/update_repo.py15 update/update_symbols.py15

系统概览

更新系统包含两个主要脚本，用于处理不同的图标集。

Material Icons 更新（update_repo.py） - 更新经典的 Material Icons 图标集
Material Symbols 更新（update_symbols.py） - 更新较新的 Material Symbols 图标集（基于可变字体的图标）

这些脚本共享一个通用的工作流程，但针对每个图标集的特定特性进行了优化。两者都依赖于版本跟踪文件（current_versions.json）来确定需要更新的图标。

来源： update/update_repo.py update/update_symbols.py update/current_versions.json update/icons.py

更新工作流

这两个更新脚本都遵循相似的工作流程，以高效地检索和处理图标资源。

来源： update/update_repo.py103-275 update/update_symbols.py87-254

1. 元数据检索

更新过程首先从 Google Fonts API 获取最新的图标元数据。这些元数据包含有关所有可用图标的信息，包括：

图标名称
类别
当前版本
可用的样式和变体
支持的尺寸

来源： update/update_repo.py42-107 update/update_symbols.py39-91

2. 版本比较

检索到元数据后，系统会将其与本地存储在 current_versions.json 中的版本信息进行比较。此文件记录了每个图标已下载的版本。

只有版本号高于本地存储版本号的图标才会被处理更新。

来源： update/update_repo.py110-129 update/update_symbols.py94-114 update/current_versions.json

3. 资源下载

对于每个需要更新的图标，系统会创建一个获取操作列表。这些操作下载各种样式变体和尺寸的资源：

用于 Web 的 SVG 文件
用于 Android 的 XML 文件
用于 iOS 的平台特定资源
不同密度的 PNG 文件
字体文件

Material Symbols 更新程序会创建更多的获取操作，因为其可变字体具有轴（粗细、填充、等级、光学尺寸）。

来源： update/update_repo.py130-257 update/update_symbols.py115-240

4. 字体处理和字形生成

下载资源后，更新系统会处理字体文件。

对于 Material Symbols，WOFF2 字体会被转换为 TTF 格式。
icons.py 实用程序从字体中提取字形信息。
会生成字形文件（.codepoints），将图标名称映射到其对应的 Unicode 字形码。

字形文件对于开发人员在项目中使用的图标至关重要，因为它们将人类可读的图标名称映射到字体中相应的字符代码。

来源： update/update_repo.py175-186 update/update_symbols.py149-167 update/icons.py61-75

技术实现细节

资源结构和 URL 模式

该系统使用 URL 模式来构建不同资源的下载路径。对于 Material Icons：

对于 Material Symbols，其模式更复杂，以适应可变字体参数。

来源： update/update_repo.py63-100 update/update_symbols.py57-73

并行下载实现

Material Symbols 更新程序使用并行处理来高效地下载大量资源。这是使用 joblib 库实现的。

来源： update/update_symbols.py124-146 update/requirements.txt18

字形提取

icons.py 实用程序通过一个复杂的流程从字体文件中提取字形映射。

使用 FontTools 打开字体文件。
提取 Unicode 字符映射。
识别 GSUB 表中的连字替换。
将图标名称映射到私有使用区 (PUA) 中的相应字形码。

然后，这些信息将被写入 .codepoints 文件，该文件将可读的图标名称映射到十六进制 Unicode 值。

来源： update/icons.py21-75 update/update_repo.py177-185 update/update_symbols.py155-167

配置选项

两个更新脚本都支持命令行标志来控制其行为。

标志	描述	默认	脚本
`--fetch`	是否下载资源	True	两者
`--icon_limit`	要处理的图标数量上限（0 表示全部）	0	两者
`--skip_existing`	如果本地文件已存在，则跳过	否	update_repo.py
`--explode_zip_files`	提取 zip 资源	True	update_repo.py
`--overwrite`	更新并覆盖现有资源	否	update_symbols.py

例如，在不下载任何文件的情况下更新 Material Symbols（模拟运行）

来源： update/update_repo.py32-39 update/update_symbols.py34-36

Material Icons 与 Material Symbols 的更新差异

更新系统在处理这两个图标集的方式上存在重要差异

由于可变字体技术的存在，Material Symbols 的处理要复杂得多，需要

每个图标有更多资源（参数组合）
字体格式转换（WOFF2 → TTF）
并行下载以提高效率

来源： update/update_repo.py update/update_symbols.py

依赖项和要求

更新系统依赖几个 Python 库

absl-py：Google 的 Abseil Python 库，用于命令行参数
requests：用于 HTTP 请求下载资源
fonttools：用于字体处理和 WOFF2 转换
joblib：用于 Material Symbols 更新程序中的并行处理
pathlib：用于平台无关的文件路径处理

这些依赖项列在 requirements.txt 中，并且必须安装这些依赖项，更新脚本才能正常运行。

来源： update/requirements.txt