README.en.md

unocss-preset-chinese

English | 简体中文

Introduction

This is a project aimed at optimizing the display of fonts on Chinese websites or applications. By using this project, you can get a default font arrangement scheme to ensure that the selected fonts on your page meet the requirements of Chinese reading when no font is specified. The font arrangement scheme of this project is based on considerations of the Chinese reading experience. It prioritizes the selection of fonts widely used and popular in the Chinese environment and determines the priority order of fonts based on the fonts' supported glyphs, symbols, and cross-platform support.

Features

• Provides multiple font arrangement schemes to accommodate different types of Chinese characters (simplified or traditional).
• Supports mixed Chinese and English text, effectively avoiding the impact of English fonts on Chinese punctuation marks.

How to Use

1. Install unocss and unocss-preset-chinese using npm or pnpm:

npm install unocss unocss-preset-chinese --save-dev

2. In your UnoCss configuration file, import unocss-preset-chinese and add it to the presets section:

// unocss.config.js
import presetChinese from "unocss-preset-chinese";
import { defineConfig, presetUno } from "unocss";

export default defineConfig({
  presets: [
    presetUno(),
    presetChinese({
      chineseType: "simplified", // Specify the text as Simplified Chinese
    }),
    // ...custom presets
  ],
});

Configuration Options

You can use the following configuration options to customize the font arrangement scheme:

• extendTheme (boolean, default: true): Whether to extend the theme object.

• themeKey (string, default: "fontFamily"): The key of the theme object.

• fonts (Record<string, string | string[]>): Extend fonts, where you can specify different fonts and font weights.

• chineseType (ChineseType, default: "simplified"): Type of Chinese, with options "simplified" or "traditional".

• fallbackFont (string[] | null): Alternative fonts for Chinese characters.

• declareEnglishFont (string[]): Declare fonts for English text.

Example

Here's an example configuration demonstrating how to use these options to customize the font arrangement scheme:

import presetChinese from "unocss-preset-chinese";
import { defineConfig, presetUno } from "unocss";

export default defineConfig({
  presets: [
    presetUno(),
    presetChinese({
      extendTheme: false, // Do not extend the theme object
      themeKey: 'customFontFamily', // Use a custom theme key
      chineseType: "traditional", // Specify the text as Traditional Chinese
    }),
    // ...custom presets
  ],
});

License

MIT License © 2022-PRESENT Kirk Lin