Google Fonts

自托管 Google 字体

配置参数

fonts string record: The Share URL of the fonts to download (like https://fonts.google.com/share?selection.family=...)
Default:
""
folder string: The folder to save the fonts
Default:
"/fonts"
cssFile string: The CSS file to output the font-face rules
Default:
"/fonts.css"
placeholder string: A placeholder to replace with the generated CSS
Default:
""
subsets string[]: The font subsets to download (latin, cyrillic, etc)

描述

此插件自动从 Google Fonts 下载优化的字体文件到 /fonts 目录中，并生成包含 @font-face 声明的 /fonts.css 文件。这允许自托管 webfonts，而不是直接使用 Google Fonts CDN，这并非一个好主意，不仅因为隐私和 GDPR 合规性问题，还因为性能原因。

安装

在你的 _config.ts 文件中导入此插件，并传入你的字体选择分享 URL。例如，假设我们要使用 Playfair Display：

import lume from "lume/mod.ts";
import googleFonts from "lume/plugins/google_fonts.ts";

const site = lume();

site.use(googleFonts({
  fonts:
    "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
}));

export default site;

重命名字体

可以通过传递一个包含 name: url 键值对的对象来重命名字体：

site.use(googleFonts({
  fonts: {
    display: "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
    text: "https://fonts.google.com/share?selection.family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900"
  }
}));

在上面的例子中，Playfair Display 字体被重命名为 "display"，而 Roboto 被重命名为 "text"，这允许在 CSS 代码中使用这些名称来使用字体：

h1 {
  font-family: display;
}
body {
  font-family: text;
}

这对于在不修改 CSS 代码的情况下更改网站的字体非常有用。

配置输出代码

默认情况下，此插件将包含 @font-face 声明的 CSS 代码输出到 /fonts.css 文件。你可以使用 cssFile 选项配置不同的文件名：

site.use(googleFonts({
  cssFile: "styles.css",
  fonts:
    "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
}));

在这个例子中，@font-face 声明被生成到 styles.css 文件中。如果文件已存在，代码将被追加到文件内容中。如果你想将代码插入到不同的位置，请使用 placeholder 选项。

site.use(googleFonts({
  cssFile: "styles.css",
  placeholder: "/* google-fonts */",
  fonts:
    "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
}));

然后，在你的 CSS 文件中，在你想要插入代码的位置添加占位符，例如：

/* google-fonts */

body {
  color: blue;
}

/* google-fonts */ 占位符将被 @font-face 声明替换。

指定子集

默认情况下，该插件会下载字体的所有可用子集。如果你知道你不需要某些子集，你可以在配置中指定你需要的子集。Google Fonts 在它提供的 CSS 中显示子集名称，例如这里和这里，你可以按如下方式指定你想要的子集数组（为了简洁而缩短）：

site.use(googleFonts({
  subsets: [
    "latin",
    "latin-ext",
    "[2]",
    "[3]",
    "[4]",
    ..."[117]",
    "[118]",
    "[119]",
  ],
  cssFile: "styles.css",
  placeholder: "/* lume-google-fonts-here */",
  fonts: {
    display:
      "https://fonts.google.com/share?selection.family=Alegreya+Sans+SC:wght@300",
    text:
      "https://fonts.google.com/share?selection.family=Alegreya:ital,wght@0,400..900;1,400..900",
    textjp:
      "https://fonts.google.com/share?selection.family=Zen+Maru+Gothic:wght@700&display=swap",
  },
}));

非 CJK 字体通常具有诸如 "latin"、"latin-ext"、"cyrillic" 或 "vietnamese" 之类的子集，而像上面提到的 "Zen Maru Gothic" 日语字体这样的 CJK 字体，则有许多子集，这些子集对应于包含的音节和汉字字符集中使用的广泛 Unicode 字符。