Skip to content

4. 用户样式开发

Jump to bottom
PRO edited this page Jul 27, 2024 · 23 revisions

样式文件命名

  • 可以在文件名中使用诸如句点 ., 空格 , 加 + 等特殊字符，但是推荐仅使用字母、数字、下划线 _ 与连字符 -，最好仅使用字母、数字与连字符 -。
  • 使用英文名，简明扼要地表现样式的功能

用户样式规范

样式开头应为 UserStyle 块，声明样式的相关信息，之后则为标准 CSS 代码。参考如下例子：

/* ==UserStyle==
@name           Hello World
@description    这是一个用户样式
@preprocessor   transitio
@version        0.1.0
@homepageURL    https://github.com/PRO-2684/Transitio-user-css/#hello-world
@author         PRO-2684
@license     	gpl-3.0
@var text test-text "This is a text variable" "Default value"
@var color test-color "This is a color variable" "#3fb950"
@var number height "Height (em)" [10, 1]
==/UserStyle== */
#target::before {
    content: var(--test-text);
    color: var(--test-color);
    height: var(--height)em;
}
标头 说明
@name 样式名，显示在设置界面，未填写则显示文件名
@description 简短说明，显示在设置界面，未填写则显示 此文件没有描述
@preprocessor 固定为 transitio，可以不填写，但不能填写其它值
@version 样式版本号，显示在设置界面，未填写则不显示
@homepageURL 样式主页，可在设置界面打开
@author 作者的 GitHub 用户名，暂无实际作用
@license 代码的许可证，暂无实际作用
@var 变量，可在设置界面实时更改，参考下一节

样式结构与规范 (旧): 第一行为注释，简要介绍样式的功能（这段文字会显示在设置页面，供用户查看）

@var 变量

语法结构

@var <type> <name> "<label>" <args[]>/<default-value>
  • <type>: 变量类型
  • <name>: 变量名，之后可以在样式中通过 var(--name) 引用
    • 注意，与通常的 var 不同，Transitio 是通过正则表达式寻找相关变量引用后进行文本替换
    • 因此，你不能指定 Fallback 值，必须 严格按照 var(--name) 格式引用
  • <label>: 展示在设置界面中的名称，需使用 双引号 " 包裹，暂不支持转义。
  • <args[]>/<default-value>: 参数数组或默认值，均要求可被 JSON.parse 识别
    • 在所有情况下，使用长度为 $1$ 的 <args[]> 数组等效于一个单独的 <default-value>，例如 [0.8] 等效于 0.8，["text"] 等效于 "text"
    • 部分变量类型支持通过 <args[]> 数组传入额外参数，例如 number 类型支持传入最小/最大值以及步长

类型 <type>

  • text: 字符串值 (文本替换引用前会先通过 CSS.escape 转义，然后加上双引号)
  • color/colour: 颜色值
  • number: 数字值，可在 <args[]> 中控制默认值、最小值、最大值与步长，例如：
    • [1]: 默认值 $1$，范围 $[-\infty, +\infty]$, 步长 $1$
    • [2, 0]: 默认值 $2$，范围 $[0, +\infty]$, 步长 $1$
    • [3, 0, 10]: 默认值 $3$，范围 $[0, 10]$，步长 $1$
    • [10, 0, null, 10]: 默认值 $10$，范围 $[0, +\infty]$，步长 $10$
    • [0.8, 0, 1, 0.01]: 默认值 $0.8$，范围 $[0, 1]$，步长 $0.01$
  • percent/percentage: 百分比值，类似于 number，可在 <args[]> 中控制默认值、范围与步长，但是有以下区别：
    • 正则替换变量时最后会加上一个 %
    • 默认的最小值为 $0$，而非 $-\infty$
    • 默认的最大值为 $100$，而非 $+\infty$
  • checkbox: 二选一值，需在 <args[]> 中控制默认值以及不勾选与勾选时使用的值，例如：
    • [0, "inline", "none"]: 未勾选时此变量将被 inline 替代，勾选时将被 none 替代；默认不勾选
    • [1, "\\"String 1\\"", "\\"String 2\\""]: 未勾选时此变量将被 "String 1" 替代，勾选时将被 "String 2" 替代；默认勾选
    • [false, 0, 1]: 未勾选时此变量将被 0 替代，勾选时将被 1 替代；默认不勾选
    • [true, "#000000", "#ffffff"]: 未勾选时此变量将被 #000000 替代，勾选时将被 #ffffff 替代；默认勾选
  • select: 多选一值，需在 <args[]> 中控制默认值以及可选的值，例如：
    • [1, "\\"String 1\\"", "\\"String 2\\"", "\\"String 3\\""]: 此变量将被 "String 1", "String 2" 或 "String 3" 替代；默认选择 "String 2"
    • [0, ["inline", "显示"], ["none", "隐藏"]]: 此变量将被 inline (展示为 显示) 或 none (展示为 隐藏) 替代，默认选择 inline
    • 注：默认值即为默认选中选项的 index (从 0 开始计数)
  • raw: 字符串值 (不经处理直接文本替换引用)

RGBA 颜色

浏览器中 input[type="color"] 只能指定 RGB 颜色，无法指定透明度。那么，为了实现 RGBA 颜色变量，我们可以通过 相对颜色 组合 color 与 percent/number，随后通过 rgb(from var(--color) r g b / var(--percent)) 构造出 RGBA 颜色。以下是一个简单的例子 (q-tag-enhancement.css)：

/* ==UserStyle==
...
@var percent box-shadow-opacity "高光透明度 (%)" 80
@var color bot-color "bot 颜色" "#0A64FF"
...
==/UserStyle== */
...
.qq-bot-label {
    box-shadow: rgb(from var(--bot-color) r g b / var(--box-shadow-opacity)) 0px 0px 6px 1px;
    &.group-user__bot {
        box-shadow: rgb(from var(--bot-color) r g b / var(--box-shadow-opacity)) 0px 0px 6px 2px;
    }
}
Clone this wiki locally