属性化预设

¥Attributify preset

这使得 属性化模式 能够用于其他预设。

¥This enables the attributify mode for other presets.

源代码

¥Source Code

安装

¥Installation

pnpm

pnpm add -D @unocss/preset-attributify

yarn

yarn add -D @unocss/preset-attributify

npm

npm install -D @unocss/preset-attributify

// uno.config.ts
import presetAttributify from '@unocss/preset-attributify'

export default defineConfig({
  presets: [
    presetAttributify({ /* preset options */ }),
    // ...
  ],
})

提示

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

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

import { presetAttributify } from 'unocss'

属性化模式

¥Attributify Mode

想象一下，你有一个使用 Tailwind CSS 工具的按钮。当列表变得更长时，阅读和维护就变得非常困难。

¥Imagine you have this button using Tailwind CSS's utilities. When the list gets longer, it becomes really hard to read and maintain.

<button class="bg-blue-400 hover:bg-blue-500 text-sm text-white font-mono font-light py-2 px-4 rounded border-2 border-blue-200 dark:bg-blue-500 dark:hover:bg-blue-600">
  Button
</button>

使用属性模式，你可以将工具分成属性：

¥With attributify mode, you can separate utilities into attributes:

<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>

例如，text-sm text-white 可以分组为 text="sm white"，而无需重复相同的前缀。

¥For example, text-sm text-white could be grouped into text="sm white" without duplicating the same prefix.

前缀自引用

¥Prefix self-referencing

对于 flex、grid、border 等具有与前缀相同的工具的工具，提供了特殊的 ~ 值。

¥For utilities like flex, grid, border, that have the utilities same as the prefix, a special ~ value is provided.

例如：

¥For example:

<button class="border border-red">
  Button
</button>

可以写成：

¥Can be written as:

<button border="~ red">
  Button
</button>

无值的属性化

¥Valueless attributify

除了 Windi CSS 的属性模式外，此预设还支持无值属性。

¥In addition to Windi CSS's attributify mode, this preset also supports valueless attributes.

例如，

¥For example,

<div class="m-2 rounded text-teal-400" />

现在可以

¥now can be

<div m-2 rounded text-teal-400 />

信息

注意：如果你使用 JSX，<div foo> 可能会转换为 <div foo={true}>，这将使 UnoCSS 生成的 CSS 无法匹配属性。要解决此问题，你可能需要尝试使用 transformer-attributify-jsx 和此预设。

¥Note: If you are using JSX, <div foo> might be transformed to <div foo={true}> which will make the generated CSS from UnoCSS fail to match the attributes. To solve this, you might want to try transformer-attributify-jsx along with this preset.

属性冲突

¥Properties conflicts

如果属性模式的名称与 elements'或组件' 属性发生冲突，你可以添加 un- 前缀以特定于 UnoCSS 的属性模式。

¥If the name of the attributes mode ever conflicts with the elements' or components' properties, you can add un- prefix to be specific to UnoCSS's attributify mode.

例如：

¥For example:

<a text="red">This conflicts with links' `text` prop</a>
<!-- to -->
<a un-text="red">Text color to red</a>

默认情况下，前缀是可选的，如果要强制使用前缀，请设置

¥Prefix is optional by default, if you want to enforce the usage of prefix, set

presetAttributify({
  prefix: 'un-',
  prefixedOnly: true, // <--
})

你还可以通过以下方式禁用某些属性的扫描：

¥You can also disable the scanning for certain attributes by:

presetAttributify({
  ignoreAttributes: [
    'text'
    // ...
  ]
})

TypeScript 支持 (JSX/TSX)

¥TypeScript support (JSX/TSX)

使用以下内容创建 shims.d.ts：

¥Create shims.d.ts with the following content:

默认情况下，该类型包括 @unocss/preset-uno 中的公共属性。如果你需要自定义属性，请参考 类型来源 来实现你自己的类型。

¥By default, the type includes common attributes from @unocss/preset-uno. If you need custom attributes, refer to the type source to implement your own type.

Vue

自 Volar 0.36 起，现在对未知属性非常严格。要选择退出，你可以将以下文件添加到你的项目中：

¥Since Volar 0.36, it's now strict to unknown attributes. To opt-out, you can add the following file to your project:

// html.d.ts
declare module '@vue/runtime-dom' {
  interface HTMLAttributes {
    [key: string]: any
  }
}
declare module '@vue/runtime-core' {
  interface AllowedComponentProps {
    [key: string]: any
  }
}
export {}

React

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'react' {
  interface HTMLAttributes<T> extends AttributifyAttributes {}
}

Vue 3

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module '@vue/runtime-dom' {
  interface HTMLAttributes extends AttributifyAttributes {}
}

SolidJS

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'solid-js' {
  namespace JSX {
    interface HTMLAttributes<T> extends AttributifyAttributes {}
  }
}

Svelte 和 SvelteKit

¥Svelte & SvelteKit

declare namespace svelteHTML {
  import type { AttributifyAttributes } from '@unocss/preset-attributify'

  type HTMLAttributes = AttributifyAttributes
}

Astro

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare global {
  namespace astroHTML.JSX {
    interface HTMLAttributes extends AttributifyAttributes { }
  }
}

Preact

import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'preact' {
  namespace JSX {
    interface HTMLAttributes extends AttributifyAttributes {}
  }
}

使用前缀进行属性化

¥Attributify with Prefix

import type { AttributifyNames } from '@unocss/preset-attributify'

type Prefix = 'uno:' // change it to your prefix

interface HTMLAttributes extends Partial<Record<AttributifyNames<Prefix>, string>> {}

选项

¥Options

strict

• 类型：boolean

  ¥type: boolean

• 默认：false

  ¥default: false

仅生成属性或类的 CSS。

¥Only generate CSS for attributify or class.

prefix

• 类型：string

  ¥type: string

• 默认：'un-'

  ¥default: 'un-'

属性模式的前缀。

¥The prefix for attributify mode.

prefixedOnly

• 类型：boolean

  ¥type: boolean

• 默认：false

  ¥default: false

仅匹配前缀属性。

¥Only match for prefixed attributes.

nonValuedAttribute

• 类型：boolean

  ¥type: boolean

• 默认：true

  ¥default: true

支持匹配非值属性。

¥Support matching non-valued attributes.

ignoreAttributes

• 类型：string[]

  ¥type: string[]

提取时要忽略的属性列表。

¥A list of attributes to be ignored from extracting.

trueToNonValued

• 类型：boolean

  ¥type: boolean

• 默认：false

  ¥default: false

如果 DOM 中表示的实际值是 true，则非值属性也将匹配。该选项的存在是为了支持将非值属性编码为 true 的框架。启用此选项将破坏以 true 结尾的规则。

¥Non-valued attributes will also match if the actual value represented in DOM is true. This option exists for supporting frameworks that encodes non-valued attributes as true. Enabling this option will break rules that ends with true.

致谢

¥Credits

最初的想法是由 @Tahul 和 @antfu 提出的。先于 Windi CSS 中的实现 至 @voorjaar。

¥Initial idea by @Tahul and @antfu. Prior implementation in Windi CSS by @voorjaar.