版式预设

¥Typography preset

提供一组散文类，可用于将排版默认值添加到普通 HTML。

¥Provides a set of prose classes you can use to add typographic defaults to vanilla HTML.

源代码

¥Source Code

安装

¥Installation

pnpm

pnpm add -D @unocss/preset-typography

yarn

yarn add -D @unocss/preset-typography

npm

npm install -D @unocss/preset-typography

bun

bun add -D @unocss/preset-typography

提示

该预设包含在 unocss 包中，你也可以从那里导入它：

¥This preset is included in the unocss package, you can also import it from there:

import presetTypography from '@unocss/preset-typography'
// or
import { presetTypography } from 'unocss'

用法

¥Usage

uno.config.ts

import {
  defineConfig,
  presetAttributify,
  presetTypography,
  presetWind3 // or presetWind4
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(), // required!
    presetAttributify(), // required when using attributify mode
    presetTypography(),
  ],
})

Classes

<article class="text-base prose dark:prose-invert xl:text-xl">
  {{ markdown }}
  <p class="not-prose">Some text</p>
</article>

Attributes

<article text-base prose="~ dark:invert" xl="text-xl">
  {{ markdown }}
  <p class="not-prose">Some text</p>
</article>

警告

注意：not-prose 只能用作类，不能用作属性。

¥Notice: not-prose can only be used as a class, not as an attribute.

强调

¥Highlights

任意尺寸

¥Any size

使用内置尺寸变体应用不同的排版尺寸：prose-sm、prose-base、prose-lg、prose-xl 和 prose-2xl。默认的 prose 类使用基准大小，你可以使用特定的大小工具覆盖它。

¥Apply different typography sizes with built-in size variants: prose-sm, prose-base, prose-lg, prose-xl, and prose-2xl. The default prose class uses the base size, and you can override it with specific size utilities.

<!-- Different sizes -->
<article class="prose prose-sm">Small typography</article>
<article class="prose prose-base">Base typography (default)</article>
<article class="prose prose-lg">Large typography</article>
<article class="prose prose-xl">Extra large typography</article>
<article class="prose prose-2xl">2X large typography</article>

你还可以将尺寸工具与响应式变体结合使用：

¥You can also combine size utilities with responsive variants:

<!-- Responsive typography sizes -->
<article class="prose prose-sm md:prose-base lg:prose-lg xl:prose-xl">
  Responsive typography that scales with screen size
</article>

<!-- Use with other utilities -->
<article class="prose prose-lg prose-gray dark:prose-invert">Large typography with color and dark mode</article>

任何颜色

¥Any color

使用 presetWind3/4 提供的 prose-${colorName} 工具应用任何颜色。它们的颜色来自主题的 colors 键，建议这些颜色的范围从 50 到 950，以实现正确的渐变。因此，presetWind3/4 是必需的

¥Apply any color with prose-${colorName} utilities provided by presetWind3/4. Their colors come from the theme's colors key, and it's recommended that these colors have a range from 50 to 950 for proper gradation. Therefore, presetWind3/4 is required

prose 的默认颜色是 prose-gray。散文颜色工具将应用于各种排版元素，例如标题、链接、块引用和代码块。

¥And the default color for prose is prose-gray. The prose color utilities will apply to various typographic elements such as headings, links, blockquotes, and code blocks.

<!-- Different color themes -->
<article class="prose prose-gray">Gray themed typography</article>
<article class="prose prose-blue">Blue themed typography</article>
<article class="prose prose-green">Green themed typography</article>
<article class="prose prose-purple">Purple themed typography</article>

自然色	强调色
它们具有不同的颜色调度范围，会影响全局排版使用。	这些只会更改链接颜色，不会影响其他颜色。
prose-slate	prose-rose
prose-slate	prose-red
prose-gray	prose-orange
prose-zinc	prose-amber
prose-neutral	prose-yellow
prose-stone	prose-lime
	prose-green
	prose-emerald
	prose-teal
	prose-cyan
	prose-sky
	prose-blue
	prose-indigo
	prose-violet
	prose-purple
	prose-fuchsia
	prose-pink
	prose-rose

你可以将颜色与尺寸和响应式变体结合使用：

¥You can combine colors with sizes and responsive variants:

<!-- Responsive color changes -->
<article class="prose prose-gray md:prose-blue lg:prose-green">
  Typography that changes color at different breakpoints
</article>

<!-- Color with size and dark mode -->
<article class="prose prose-lg prose-slate dark:prose-invert">
  Large typography with slate color and dark mode support
</article>

具有单一工具的夜间模式

¥Dark mode with a single utility

使用 prose-invert 应用印刷夜间模式（背景颜色需要用户处理）。例如，prose dark:prose-invert 将在夜间模式下使用反色。

¥Apply typographic dark mode with prose-invert (background color needs to be handled by users). For instance, prose dark:prose-invert will use the inverted colors in the dark mode.

你自己的样式

¥Your very own style

不在 prose 作用域内的元素样式将保持不变。没有像 UnoCSS 那样重置样式。

¥Styles of elements not within prose will stay the same. No style resetting just like UnoCSS.

使用 not 工具撤消

¥Undo with not utility

将 not-prose 应用于元素以撤消印刷样式。例如，<table class="not-prose"> 将跳过 table 元素的此预设样式（注意：not 工具仅在类中可用，因为它仅在 CSS 选择器中使用且不被 UnoCSS 扫描）。

¥Apply not-prose to the elements to undo the typographic styles. For instance, <table class="not-prose"> will skip the styles by this preset for the table element (NOTE: not utility is only usable in class since it is only used in CSS selector & not scanned by UnoCSS).

兼容性选项

¥Compatibility options

此预设使用一些未得到广泛支持的伪类，但你可以禁用它们。(#2064)

¥This preset uses some pseudo-classes which are not widely supported, but you can disable them. (#2064)

• 如果启用 noColonNot 或 noColonWhere，not-prose 将不可用。

  ¥If you enable noColonNot or noColonWhere, not-prose will be unavailable.

• 如果启用 noColonIs，属性化模式将出现错误行为。

  ¥If you enable noColonIs, attributify mode will have a wrong behavior.

选项

¥Options

此预设提供了全面的配置选项，用于自定义排版样式、颜色、大小和行为。

¥This preset provides comprehensive configuration options for customizing typography styles, colors, sizes, and behavior.

提示

传递给 cssExtend 的 CSS 声明将

¥The CSS declarations passed to cssExtend will

• 如果值冲突，则覆盖内置样式，否则

  ¥override the built-in styles if the values are conflicting, else

• 与内置样式深度融合。:::

  ¥be merged deeply with built-in styles.

selectorName

• 类型：string

  ¥Type: string

• 默认：prose

  ¥Default: prose

使用排版工具的类名。要撤消元素的样式，请像 not-${selectorName} 一样使用它，默认情况下是 not-prose。

¥The class name to use the typographic utilities. To undo the styles to the elements, use it like not-${selectorName} which is by default not-prose.

提示

not 工具仅在课堂上可用。

¥not utility is only available in class.

cssExtend

• 类型：Record<string, CSSObject> | ((theme: T) => Record<string, CSSObject>)

  ¥Type: Record<string, CSSObject> | ((theme: T) => Record<string, CSSObject>)

• 默认：undefined

  ¥Default: undefined

使用 CSS 声明块扩展或覆盖 CSS 选择器。可以是静态对象，也可以是接收主题并返回 CSS 选择器的函数。

¥Extend or override CSS selectors with CSS declaration block. Can be either a static object or a function that receives the theme and returns CSS selectors.

important

• 类型：boolean | string

  ¥Type: boolean | string

• 默认：false

  ¥Default: false

控制散文工具是否应标记为 !important。设置为 true 时，所有散文样式都会添加 !important。设置为字符串时，它将用作 CSS 选择器范围。

¥Control whether prose utilities should be marked with !important. When set to true, all prose styles will have !important added. When set to a string, it will be used as a CSS selector scope.

colorScheme

• 类型：TypographyColorScheme

  ¥Type: TypographyColorScheme

• 默认：见下文

  ¥Default: See below

排版元素的配色方案。每个键代表一个排版元素，其值采用 [light, dark] => [color, invert-color] 的格式。

¥Color scheme for typography elements. Each key represents a typographic element with values in the format [light, dark] => [color, invert-color].

默认配色方案：

¥Default color scheme:

{
  "body": [700, 300],
  "headings": [900, "white"],
  "lead": [600, 400],
  "links": [900, "white"],
  "bold": [900, "white"],
  "counters": [500, 400],
  "bullets": [300, 600],
  "hr": [200, 700],
  "quotes": [900, 100],
  "quote-borders": [200, 700],
  "captions": [500, 400],
  "kbd": [900, "white"],
  "kbd-shadows": [900, "white"],
  "code": [900, "white"],
  "pre-code": [200, 300],
  "pre-bg": [800, "rgb(0 0 0 / 50%)"],
  "th-borders": [300, 600],
  "td-borders": [200, 700]
}

sizeScheme

• 类型：TypographySizeScheme

  ¥Type: TypographySizeScheme

• 默认：undefined

  ¥Default: undefined

排版元素的大小方案。允许你为不同尺寸的各种排版元素自定义 CSS 样式。与 cssExtend 类似，但会将精细的叠加应用于不同的文本大小。

¥Size scheme for typography elements. Allows you to customize the CSS styles of various typographic elements for different sizes. Similar to cssExtend, but applies granular overlays to different text sizes.

示例：

¥Example:

{
  "sm": {
    "h1": { "font-size": "1.5rem" },
    "p": { "font-size": "0.875rem" }
  },
  "base": {
    "h1": { "font-size": "2rem" },
    "p": { "font-size": "1rem" }
  },
  "lg": {
    "h1": { "font-size": "2.5rem" },
    "p": { "font-size": "1.125rem" }
  }
}

cssVarPrefix

• 类型：string

  ¥Type: string

• 默认：--un-prose

  ¥Default: --un-prose

生成的 CSS 自定义属性（CSS 变量）的前缀。这允许你自定义预设内部使用的 CSS 变量的命名。

¥Prefix for generated CSS custom properties (CSS variables). This allows you to customize the naming of CSS variables used internally by the preset.

compatibility

• 类型：TypographyCompatibilityOptions

  ¥Type: TypographyCompatibilityOptions

• 默认：undefined

  ¥Default: undefined

参见 兼容性选项。

¥See Compatibility options.

警告

请注意，它会影响某些功能。

¥Notice that it will affect some features.

interface TypographyCompatibilityOptions {
  noColonWhere?: boolean
  noColonIs?: boolean
  noColonNot?: boolean
}

示例

¥Example

uno.config.ts

import { presetTypography } from '@unocss/preset-typography'
import { defineConfig, presetAttributify, presetWind3 } from 'unocss'

export default defineConfig({
  presets: [
    presetAttributify(), // required if using attributify mode
    presetWind3(), // required
    presetTypography({
      selectorName: 'markdown', // now use like `markdown markdown-gray`, `not-markdown`
      // cssExtend is an object with CSS selector as key and
      // CSS declaration block as value like writing normal CSS.
      cssExtend: {
        'code': {
          color: '#8b5cf6',
        },
        'a:hover': {
          color: '#f43f5e',
        },
        'a:visited': {
          color: '#14b8a6',
        },
      },
    }),
  ],
})

致谢

¥Acknowledgement

• Tailwind CSS 版式

  ¥Tailwind CSS Typography

• Windi CSS 版式

  ¥Windi CSS Typography