واجهة سطر الأوامر ومكتبة Node
حزمة fontstay هي محرك المطابقة في هذا الموقع بدون المتصفح: أداة سطر أوامر ومكتبة Node تقرآن ملفات الخطوط وتطبعان قواعد @font-face وصيغ التصدير نفسها التي يقدمها التطبيق. لا تحتاجان إلى DOM ولا إلى الشبكة، لذا تناسبان مسارات البناء وCI.
التثبيت
الحزمة غير منشورة على npm بعد. تتطلب Node 24 أو أحدث؛ ابنِها من نسخة من المستودع. في الأمثلة أدناه تعني fontstay الأمر node packages/fontstay/dist/bin.js.
git clone https://github.com/fogrew/fontstay.dev.git
cd fontstay.dev
pnpm install
pnpm cli:build
node packages/fontstay/dist/bin.js --versionالأوامر
يقرأ fit ملف خط واحدًا أو أكثر (WOFF2 وWOFF وTTF وOTF) ويطبع CSS الخطوط الاحتياطية. تُدمج عدة ملفات في ورقة أنماط واحدة كما في التطبيق. يشغّل mcp خادم MCP عبر stdio لوكلاء البرمجة ولا يقبل خيارات.
مطابقة خط لنظامي Windows وmacOS بدون الوجوه السيريلية واليونانية. المخرجات هي نفس نص تصدير CSS في التطبيق.
$ fontstay fit font.woff2 --systems windows,macos --no-scripts
@font-face {
font-family: "Source Sans Pro Fallback";
src: local("Arial"), local("ArialMT");
size-adjust: 93.697%;
ascent-override: 105.0194%;
descent-override: 29.1365%;
line-gap-override: 0%;
}
body {
font-family: "Source Sans Pro", "Source Sans Pro Fallback", sans-serif;
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.48;
line-height: 1.4;
}
.fonts-loading {
letter-spacing: -0.0003em;
word-spacing: -0.0025em;
}fontstay fit Inter.woff2 -o fallbacks.css
fontstay fit regular.woff2 bold.woff2 --format tailwind
fontstay fit font.woff2 -a 'last 2 chrome versions, os windows' --jsonالخيارات
| الخيار | المعنى |
|---|---|
-s, --systems <list> | الأنظمة المطلوب مطابقتها: windows وmacos وios وandroid وlinux وchromeos. الافتراضي: كل نظام له حصة 1% على الأقل في الجمهور. |
-a, --audience <query> | استعلام Browserslist، مع أجزاء اختيارية «os <system>» و«not os <system>». الافتراضي: baseline widely available. |
-f, --format <format> | صيغة المخرجات، انظر أدناه. الافتراضي: css. |
-k, --kind <kind> | العائلة العامة للخطوط الاحتياطية: sans-serif أو serif أو monospace أو cursive. الافتراضي: يُكتشف من الخط. |
--locale <en|ru> | ملف التكرار المستخدم في المطابقة: en أو ru. الافتراضي: en. |
--unicode-range | إضافة unicode-range بالرموز التي يغطيها كل خط. |
--no-scripts | عدم إنشاء وجوه منفصلة للسيريلية واليونانية. |
-o, --out <file> | كتابة المخرجات في ملف بدل stdout. |
--json | طباعة تقرير JSON بدل نص الملف. |
-h, --help / -v, --version | عرض المساعدة أو الإصدار. |
صيغ المخرجات
يقبل --format إحدى هذه القيم. وهي تطابق صيغ التصدير في التطبيق وتنطلق من المطابقة نفسها.
شغّل هذا الأمر لكل تنسيق باستخدام خط Fira Sans النموذجي. المخرجات المعروضة من أداة سطر الأوامر المبنية.
الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format cssمخرجات أداة سطر الأوامر
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
body {
font-family: "Fira Sans", "Fira Sans Fallback", sans-serif;
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}
.fonts-loading {
letter-spacing: -0.0019em;
}الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format variablesمخرجات أداة سطر الأوامر
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
:root {
--font-body: "Fira Sans", "Fira Sans Fallback", sans-serif;
}
body {
font-family: var(--font-body);
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format tailwindمخرجات أداة سطر الأوامر
@import "tailwindcss";
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
@theme {
--font-sans: "Fira Sans", "Fira Sans Fallback", sans-serif;
}الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nextمخرجات أداة سطر الأوامر
// Put FiraSans-Regular.ttf into ./fonts/ and the @font-face rules from the CSS export into your global CSS.
import localFont from 'next/font/local';
export const font = localFont({
src: './fonts/FiraSans-Regular.ttf',
display: 'swap',
adjustFontFallback: false,
fallback: ['Fira Sans Fallback', 'sans-serif'],
variable: '--font-body',
});الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nuxtمخرجات أداة سطر الأوامر
// Add the @font-face rules from the CSS export to a stylesheet listed in `css`.
export default defineNuxtConfig({
modules: ['@nuxt/fonts'],
fonts: {
families: [
{
name: 'Fira Sans',
src: '/fonts/FiraSans-Regular.ttf',
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
},
});الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format astroمخرجات أداة سطر الأوامر
// Add the @font-face rules from the CSS export to your global styles.
import { defineConfig } from 'astro/config';
export default defineConfig({
fonts: [
{
name: 'Fira Sans',
cssVariable: '--font-body',
provider: 'local',
options: {
variants: [{ weight: 400, style: 'normal', src: ['./src/assets/fonts/FiraSans-Regular.ttf'] }],
},
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
});الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format wordpressمخرجات أداة سطر الأوامر
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"typography": {
"fontFamilies": [
{
"name": "Fira Sans",
"slug": "fira-sans",
"fontFamily": "\"Fira Sans\", \"Fira Sans Fallback\", sans-serif",
"fontFace": [
{
"fontFamily": "Fira Sans",
"fontWeight": "400",
"fontStyle": "normal",
"src": [
"file:./assets/fonts/FiraSans-Regular.ttf"
]
}
]
}
]
}
}
}الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format fontaineمخرجات أداة سطر الأوامر
// Put FiraSans-Regular.ttf into ./public/fonts/ and declare their @font-face rules in your CSS. In Nuxt, put the plugin under vite.plugins.
import { FontaineTransform } from 'fontaine';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
FontaineTransform.vite({
fallbacks: {
'Fira Sans': ['Trebuchet MS'],
},
resolvePath: (id) => new URL(`./public${id}`, import.meta.url),
}),
],
});الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format preloadمخرجات أداة سطر الأوامر
<link rel="preload" href="/fonts/FiraSans-Regular.ttf" as="font" type="font/ttf" crossorigin>الأمر
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format loadingمخرجات أداة سطر الأوامر
const root = document.documentElement;
const done = () => root.classList.remove('fonts-loading');
root.classList.add('fonts-loading');
document.fonts.load('1em "Fira Sans"').then(done, done);المخرجات والتقارير
يذهب نص الملف إلى stdout. مع --json تطبع الأداة تقريرًا بالمفاتيح file (المخرجات بالصيغة المختارة) وfonts (العائلة والنوع المكتشف وتغطية الرموز والخط الاحتياطي المختار لكل نظام لكل خط) وshares (حصة كل نظام في الجمهور بالنسبة المئوية) وsystems وuncovered (أنظمة الجمهور التي لا خط احتياطي لها) وaudience (الاستعلام بعد التحليل وعدد المتصفحات المطابقة). تعتمد الحصص على بيانات المتصفحات وقت التشغيل.
تذهب التحذيرات إلى stderr فلا تظهر في المخرجات أبدًا: خط تشترك احتياطياته في أقل من 90% من رموزه، وأنظمة بلا أي خط احتياطي. ومع --out تُبلغ الأداة أيضًا عن الملف المكتوب في stderr.
مكتبة Node
تأخذ fit بايتات الخط وتقرأ fitFiles الملفات. تعيد كلتاهما CSS والمخرجات بالصيغة المطلوبة وتقريرًا لكل خط وحصص الجمهور. تُطلق الإخفاقات FitRunError (invalid-audience وno-systems وno-fit) أو FontParseError (مثل invalid-font). الأنواع في index.d.ts.
import { fit, fitFiles } from 'fontstay';
import { readFile } from 'node:fs/promises';
const { css, fonts, shares } = await fit({
fonts: [{ fileName: 'font.woff2', data: await readFile('font.woff2') }],
audience: 'defaults',
systems: ['windows', 'macos'],
});
const tailwind = (await fitFiles(['font.woff2'], { format: 'tailwind' })).file.text;رموز الخروج
| الرمز | المعنى |
|---|---|
0 | نجاح. |
1 | إخفاق: ملف لا يمكن قراءته أو خط غير صالح أو جمهور غير صالح. |
2 | خطأ في الاستخدام: أمر غير معروف أو غياب ملف الخط أو قيمة خيار غير صالحة. |