編輯「logical-functions」的標記來源

if

根據條件傳回兩個值之一。

參數

• condition：布林表達式
• value1：如果 condition 為真，傳回的值。
• value2：如果 condition 為假，傳回的值。

發布：v3.0.0 更新：v3.6.0

範例:

@some: foo;

div {
    margin: if((2 > 1), 0, 3px);
    color:  if((iscolor(@some)), @some, black);
}

結果

div {
    margin: 0;
    color:  black;
}

註解：支援作為 conditional 參數的布林表達式與 防護陳述式 相同。

if(not (true), foo, bar);
if((true) and (2 > 1), foo, bar);
if((false) or (isstring("boo!")), foo, bar);

註解：在 Less 3.6 之前，條件需要一組括弧。

if(2 > 1, blue, green);   // Causes an error in 3.0-3.5.3
if((2 > 1), blue, green); // Ok 3.6+

boolean

評估為真或假

您可以「儲存」布林測試，以便稍後在防護或 if() 中評估。

參數

• condition：布林表達式

發布：v3.0.0 更新：v3.6.0

範例:

@bg: black;
@bg-light: boolean(luma(@bg) > 50%);

div {
  background: @bg; 
  color: if(@bg-light, black, white);
}

結果

div {
  background: black;
  color: white;
}

編輯「string-functions」的 markdown 原始檔

escape

將 URL 編碼套用至輸入字串中找到的特殊字元。

• 下列字元不會編碼：,、/、?、@、&、+、'、~、! 和 $。
• 最常見的編碼字元為：\<space\>、#、^、(、)、{、}、|、:、>、<、;、]、[ 及 =。

參數：字串：要跳脫的字串。

傳回：跳脫後的 字串 內容，不含引號。

範例

escape('a=1')

輸出

a%3D1

注意：如果參數不是字串，則未定義輸出。目前的實作會在顏色上傳回 未定義，在任何其他類型的引數上傳回未變更的輸入。不應依賴此行為，而且此行為可能會在未來變更。

e

字串跳脫。

它預期字串為參數，並回傳其內容，但沒有引號。它可用於輸出 CSS 值，該值不是有效的 CSS 語法，或使用 Less 無法辨識的專有語法。

參數：字串 - 要跳脫的字串。

傳回：字串 - 跳脫後的字串，不含引號。

範例

@mscode: "ms:alwaysHasItsOwnSyntax.For.Stuff()" 
filter: e(@mscode);

輸出

filter: ms:alwaysHasItsOwnSyntax.For.Stuff();

% 格式

函數 %(字串, 引數 ...) 會格式化字串。

第一個引數為包含佔位符的字串。所有佔位符都以百分比符號 % 開頭，後接字母 s、S、d、D、a 或 A。其餘引數包含用於取代佔位符的運算式。如果您需要列印百分比符號，請用另一個百分比 %% 來跳脫它。

如果您需要將特殊字元跳脫成其 utf-8 跳脫碼，請使用大寫佔位符。此函數會跳脫所有特殊字元，但 ()'~! 除外。空白會編碼為 %20。小寫佔位符會讓特殊字元保持原樣。

佔位符

• d、D、a、A - 可替換為任何類型的引數（顏色、數字、跳脫值、表達式等）。如果您將它們與字串結合使用，則會使用整個字串，包括其引號。但是，引號會按原樣放入字串中，不會使用「/」或任何類似方式跳脫。
• s、S - 可替換為任何表達式。如果您將它與字串一起使用，則只會使用字串值，而省略引號。

參數

• string：包含佔位符的格式字串，
• anything*：替換佔位符的值。

傳回：格式化的 string。

範例

format-a-d: %("repetitions: %a file: %d", 1 + 2, "directory/file.less");
format-a-d-upper: %('repetitions: %A file: %D', 1 + 2, "directory/file.less");
format-s: %("repetitions: %s file: %s", 1 + 2, "directory/file.less");
format-s-upper: %('repetitions: %S file: %S', 1 + 2, "directory/file.less");

輸出

format-a-d: "repetitions: 3 file: "directory/file.less"";
format-a-d-upper: "repetitions: 3 file: %22directory%2Ffile.less%22";
format-s: "repetitions: 3 file: directory/file.less";
format-s-upper: "repetitions: 3 file: directory%2Ffile.less";

replace

取代字串中的文字。

發布 v1.7.0

參數

• string：要在其中搜尋並取代的字串。
• pattern：要搜尋的字串或正規表示式模式。
• replacement：用來取代配對模式的字串。
• flags：正規表示式旗標（選用）。

傳回：包含已取代值的字串。

範例

replace("Hello, Mars?", "Mars\?", "Earth!");
replace("One + one = 4", "one", "2", "gi");
replace('This is a string.', "(string)\.$", "new $1.");
replace(~"bar-1", '1', '2');

結果

"Hello, Earth!";
"2 + 2 = 4";
'This is a new string.';
bar-2;

編輯「list-functions」的標記語言來源

長度

傳回值清單中元素的數量。

參數

• 清單 - 以逗號或空白分隔的值清單。

範例：length(1px solid #0080ff);

輸出：3

範例

@list: "banana", "tomato", "potato", "peach";
n: length(@list);

輸出

n: 4;

萃取

傳回清單中指定位置的值。

參數

• 清單 - 以逗號或空白分隔的值清單。
• 索引 - 指定要傳回的清單元素位置的整數。

範例：extract(8px dotted red, 2);

輸出：dotted

範例

@list: apple, pear, coconut, orange;
value: extract(@list, 3);

輸出

value: coconut;

範圍

已發布 v3.9.0

產生橫跨值範圍的清單

參數

• 開始 - (選用) 開始值，例如 1 或 1px
• 結束 - 結束值，例如 5px
• 步驟 - (選用) 要遞增的量

範例

value: range(4);

輸出

value: 1 2 3 4;

範圍中每個值的輸出將與 結束 值使用相同的單位。例如

value: range(10px, 30px, 10);

輸出

value: 10px 20px 30px;

每個

已發布 v3.7.0

將規則集的評估繫結至清單的每個成員。

參數

• 清單 - 以逗號或空白分隔的值清單。
• rules - 匿名規則集/mixin

範例

@selectors: blue, green, red;

each(@selectors, {
  .sel-@{value} {
    a: b;
  }
});

輸出

.sel-blue {
  a: b;
}
.sel-green {
  a: b;
}
.sel-red {
  a: b;
}

預設情況下，每個規則集會繫結至清單成員的 @value、@key 和 @index 變數。對於大多數清單，@key 和 @index 會指定為相同的值（數字位置，以 1 為基礎）。不過，您也可以將規則集本身用作結構化清單。例如

@set: {
  one: blue;
  two: green;
  three: red;
}
.set {
  each(@set, {
    @{key}-@{index}: @value;
  });
}

這會輸出

.set {
  one-1: blue;
  two-2: green;
  three-3: red;
}

當然，您可以呼叫每個規則集呼叫的守衛混入，這會讓 each() 變成非常強大的函式。

在 each() 中設定變數名稱

您不必在 each() 函式中使用 @value、@key 和 @index。在 Less 3.7 中，Less 會在 each() 函式中引入匿名混入的概念，這可能會在稍後擴充至語法的其他部分。

匿名混入會使用 #() 或 .() 的形式，就像一般的混入會以 . 或 # 開頭一樣。在 each() 中，您可以像這樣使用它

.set-2() {
  one: blue;
  two: green;
  three: red;
}
.set-2 {
  // Call mixin and iterate each rule
  each(.set-2(), .(@v, @k, @i) {
    @{k}-@{i}: @v;
  });
}

這會輸出預期的結果

.set-2 {
  one-1: blue;
  two-2: green;
  three-3: red;
}

each() 函式會採用匿名混入中定義的變數名稱，並依序將它們繫結至 @value、@key 和 @index 值。如果您只撰寫 each(@list, #(@value) {})，則不會定義 @key 或 @index。

使用 range 和 each 建立 for 迴圈

需要 Less v3.9.0

你可以透過產生數值清單並使用 each 將其擴充為規則集，來模擬 for 迴圈。

範例

each(range(4), {
  .col-@{value} {
    height: (@value * 50px);
  }
});

輸出

.col-1 {
  height: 50px;
}
.col-2 {
  height: 100px;
}
.col-3 {
  height: 150px;
}
.col-4 {
  height: 200px;
}

編輯「數學函數」的 markdown 原始碼

ceil

向上取整至下一個最高整數。

參數：number - 浮點數。

傳回：integer

範例：ceil(2.4)

輸出：3

floor

向下取整至下一個最低整數。

參數：number - 浮點數。

傳回：integer

範例：floor(2.6)

輸出：2

percentage

將浮點數轉換為百分比字串。

參數：number - 浮點數。

傳回：number

範例：percentage(0.5)

輸出：50%

round

套用捨入。

參數

• number：浮點數。
• decimalPlaces：選用：要捨入的小數位數。預設為 0。

傳回：number

範例：round(1.67)

輸出：2

範例：round(1.67, 1)

輸出：1.7

sqrt

計算數字的平方根。維持原有的單位。

參數：number - 浮點數。

傳回：number

範例

sqrt(25cm)

輸出

5cm

範例

sqrt(18.6%)

輸出

4.312771730569565%;

abs

計算數字的絕對值。維持原有的單位。

參數：number - 浮點數。

傳回：number

範例 #1：abs(25cm)

輸出：25cm

範例 #2：abs(-18.6%)

輸出：18.6%;

sin

計算正弦函數。

假設沒有單位的數字為弧度。

參數：number - 浮點數。

傳回：number

範例

sin(1); // sine of 1 radian
sin(1deg); // sine of 1 degree
sin(1grad); // sine of 1 gradian

輸出

0.8414709848078965; // sine of 1 radian
0.01745240643728351; // sine of 1 degree
0.015707317311820675; // sine of 1 gradian

asin

計算反正弦（正弦的反函數）函數。

傳回弧度數，例如介於 -π/2 和 π/2 之間的數字。

參數：數字 - 來自 [-1, 1] 區間的浮點數。

傳回：number

範例

asin(-0.8414709848078965)
asin(0)
asin(2)

輸出

-1rad
0rad
NaNrad

cos

計算餘弦函數。

假設沒有單位的數字為弧度。

參數：number - 浮點數。

傳回：number

範例

cos(1) // cosine of 1 radian
cos(1deg) // cosine of 1 degree
cos(1grad) // cosine of 1 gradian

輸出

0.5403023058681398 // cosine of 1 radian
0.9998476951563913 // cosine of 1 degree
0.9998766324816606 // cosine of 1 gradian

acos

計算反餘弦（餘弦的反函數）函數。

傳回弧度數，例如介於 0 和 π 之間的數字。

參數：數字 - 來自 [-1, 1] 區間的浮點數。

傳回：number

範例

acos(0.5403023058681398)
acos(1)
acos(2)

輸出

1rad
0rad
NaNrad

tan

計算正切函數。

假設沒有單位的數字為弧度。

參數：number - 浮點數。

傳回：number

範例

tan(1) // tangent of 1 radian
tan(1deg) // tangent of 1 degree
tan(1grad) // tangent of 1 gradian

輸出

1.5574077246549023   // tangent of 1 radian
0.017455064928217585 // tangent of 1 degree
0.015709255323664916 // tangent of 1 gradian

atan

計算反正切（正切的反函數）函數。

傳回弧度數，例如介於 -π/2 和 π/2 之間的數字。

參數：number - 浮點數。

傳回：number

範例

atan(-1.5574077246549023)
atan(0)
round(atan(22), 6) // arctangent of 22 rounded to 6 decimal places

輸出

-1rad
0rad
1.525373rad;

pi

傳回 π（圓周率）；

參數：無

傳回：number

範例

pi()

輸出

3.141592653589793

pow

傳回第一個引數乘方第二個引數的值。

傳回值與第一個參數具有相同的維度，而第二個參數的維度則會被忽略。

參數

• 數字：base - 浮點數。
• 數字：exponent - 浮點數。

傳回：number

範例

pow(0cm, 0px)
pow(25, -2)
pow(25, 0.5)
pow(-25, 0.5)
pow(-25%, -0.5)

輸出

1cm
0.0016
5
NaN
NaN%

mod

傳回第一個參數模數第二個參數的值。

傳回值與第一個參數具有相同的維度，而第二個參數的維度則會被忽略。此函式也可以處理負數和浮點數。

參數

• 數字：浮點數。
• 數字：浮點數。

傳回：number

範例

mod(0cm, 0px)
mod(11cm, 6px);
mod(-26%, -5);

輸出

NaNcm;
5cm
-1%;

min

傳回一個或多個值中的最小值。

參數：value1, ..., valueN - 一個或多個要比較的數值。

傳回值：最小值。

範例：min(5, 10);

輸出：5

範例：min(3px, 42px, 1px, 16px);

輸出：1px

max

傳回一個或多個值中的最大值。

參數：value1, ..., valueN - 一個或多個要比較的數值。

傳回值：最大值。

範例：max(5, 10);

輸出：10

範例：max(3%, 42%, 1%, 16%);

輸出：42%

編輯「類型函數」的標記原始碼

isnumber

如果值為數字，則傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值為數字，則傳回 true，否則傳回 false。

範例

isnumber(#ff0);     // false
isnumber(blue);     // false
isnumber("string"); // false
isnumber(1234);     // true
isnumber(56px);     // true
isnumber(7.8%);     // true
isnumber(keyword);  // false
isnumber(url(...)); // false

isstring

如果值為字串，則傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值為字串，則傳回 true，否則傳回 false。

範例

isstring(#ff0);     // false
isstring(blue);     // false
isstring("string"); // true
isstring(1234);     // false
isstring(56px);     // false
isstring(7.8%);     // false
isstring(keyword);  // false
isstring(url(...)); // false

iscolor

如果值為顏色，則傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值為顏色，則傳回 true，否則傳回 false。

範例

iscolor(#ff0);     // true
iscolor(blue);     // true
iscolor("string"); // false
iscolor(1234);     // false
iscolor(56px);     // false
iscolor(7.8%);     // false
iscolor(keyword);  // false
iscolor(url(...)); // false

iskeyword

如果值為關鍵字，則傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值為關鍵字，則傳回 true，否則傳回 false。

範例

iskeyword(#ff0);     // false
iskeyword(blue);     // false
iskeyword("string"); // false
iskeyword(1234);     // false
iskeyword(56px);     // false
iskeyword(7.8%);     // false
iskeyword(keyword);  // true
iskeyword(url(...)); // false

isurl

如果一個值是 URL，傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值是 URL，傳回 true，否則傳回 false。

範例

isurl(#ff0);     // false
isurl(blue);     // false
isurl("string"); // false
isurl(1234);     // false
isurl(56px);     // false
isurl(7.8%);     // false
isurl(keyword);  // false
isurl(url(...)); // true

ispixel

如果一個值是像素數，傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值是像素，傳回 true，否則傳回 false。

範例

ispixel(#ff0);     // false
ispixel(blue);     // false
ispixel("string"); // false
ispixel(1234);     // false
ispixel(56px);     // true
ispixel(7.8%);     // false
ispixel(keyword);  // false
ispixel(url(...)); // false

isem

如果一個值是 em 值，傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值是 em 值，傳回 true，否則傳回 false。

範例

isem(#ff0);     // false
isem(blue);     // false
isem("string"); // false
isem(1234);     // false
isem(56px);     // false
isem(7.8em);    // true
isem(keyword);  // false
isem(url(...)); // false

ispercentage

如果一個值是百分比值，傳回 true，否則傳回 false。

參數：value - 要評估的值或變數。

傳回：如果值是百分比值，傳回 true，否則傳回 false。

範例

ispercentage(#ff0);     // false
ispercentage(blue);     // false
ispercentage("string"); // false
ispercentage(1234);     // false
ispercentage(56px);     // false
ispercentage(7.8%);     // true
ispercentage(keyword);  // false
ispercentage(url(...)); // false

isunit

如果一個值是指定單位數，傳回 true，否則傳回 false。

參數

• value - 正在評估的值或變數。
• unit - 要測試的單位識別碼（可選擇加上引號）。

傳回：如果值是指定單位中的數字，傳回 true，否則傳回 false。

範例

isunit(11px, px);  // true
isunit(2.2%, px);  // false
isunit(33px, rem); // false
isunit(4rem, rem); // true
isunit(56px, "%"); // false
isunit(7.8%, '%'); // true
isunit(1234, em);  // false
isunit(#ff0, pt);  // false
isunit("mm", mm);  // false

isruleset

如果值是規則組，傳回 true，否則傳回 false。

參數

• value - 正在評估的變數。

傳回：如果值是規則組，傳回 true，否則傳回 false。

範例

@rules: {
    color: red;
}

isruleset(@rules);   // true
isruleset(#ff0);     // false
isruleset(blue);     // false
isruleset("string"); // false
isruleset(1234);     // false
isruleset(56px);     // false
isruleset(7.8%);     // false
isruleset(keyword);  // false
isruleset(url(...)); // false

isdefined

已發布 v4.0.0

如果變數已定義，傳回 true，否則傳回 false。

參數：variable - 正在評估的變數。

範例

@foo: 1;
isdefined(@foo);     // true
isdefined(@bar);     // false

編輯「雜項函式」的標記原始碼

color

分析顏色，因此代表顏色的字串會變成顏色。

參數：string：指定顏色的字串。

傳回：color

範例：color("#aaa");

輸出：#aaa

image-size

從檔案取得影像尺寸。

參數：字串：要取得尺寸的檔案。

傳回：尺寸

範例：image-size("file.png");

輸出：10px 10px

注意：此函式需要由每個環境實作。目前僅在 node 環境中可用。

新增於：v2.2.0

image-width

從檔案取得影像寬度。

參數：字串：要取得尺寸的檔案。

傳回：尺寸

範例：image-width("file.png");

輸出：10px

注意：此函式需要由每個環境實作。目前僅在 node 環境中可用。

新增於：v2.2.0

image-height

從檔案取得影像高度。

參數：字串：要取得尺寸的檔案。

傳回：尺寸

範例：image-height("file.png");

輸出：10px

注意：此函式需要由每個環境實作。目前僅在 node 環境中可用。

新增於：v2.2.0

convert

將數字從一個單位轉換到另一個單位。

第一個參數包含帶有單位的數字，第二個參數包含單位。如果單位相容，則會轉換數字。如果它們不相容，則第一個參數會不修改地傳回。

請參閱 unit 以變更單位而不進行轉換。

相容的單位群組:

• 長度：m、cm、mm、in、pt 和 pc，
• 時間：s 和 ms，
• 角度：rad、deg、grad 和 turn。

參數

• number：帶有單位的浮點數。
• 識別碼、字串或轉義值：單位

傳回：number

範例

convert(9s, "ms")
convert(14cm, mm)
convert(8, mm) // incompatible unit types

輸出

9000ms
140mm
8

data-uri

內嵌資源，如果 ieCompat 選項開啟且資源太大，或您在瀏覽器中使用該函數，則會使用 url() 作為備用。如果未提供 MIME 類型，則節點使用 mime 套件來確定正確的 MIME 類型。

參數

• mimetype： (選用) MIME 類型字串。
• url：要內嵌的檔案 URL。

如果沒有 mimetype，data-uri 函數會從檔名後綴猜測。文字和 svg 檔案編碼為 utf-8，其他任何內容都編碼為 base64。

如果使用者提供了 mimetype，則函數在 mimetype 參數以 ;base64 結尾時使用 base64。例如，image/jpeg;base64 編碼為 base64，而 text/html 編碼為 utf-8。

範例：data-uri('../data/image.jpg');

輸出：url('data:image/jpeg;base64,bm90IGFjdHVhbGx5IGEganBlZyBmaWxlCg==');

瀏覽器輸出：url('../data/image.jpg');

範例：data-uri('image/jpeg;base64', '../data/image.jpg');

輸出：url('data:image/jpeg;base64,bm90IGFjdHVhbGx5IGEganBlZyBmaWxlCg==');

範例：data-uri('image/svg+xml;charset=UTF-8', 'image.svg');

輸出：url("data:image/svg+xml;charset=UTF-8,%3Csvg%3E%3Ccircle%20r%3D%229%22%2F%3E%3C%2Fsvg%3E");

預設

僅在防護條件內可用，且僅在沒有其他混合相符時傳回 true，否則傳回 false。

範例

.mixin(1)                   {x: 11}
.mixin(2)                   {y: 22}
.mixin(@x) when (default()) {z: @x}

div {
  .mixin(3);
}

div.special {
  .mixin(1);
}

輸出

div {
  z: 3;
}
div.special {
  x: 11;
}

可以使用 default 傳回的值搭配防護運算子。例如，.mixin() when not(default()) {} 僅在至少有一個其他混合定義相符 .mixin() 呼叫時相符

.mixin(@value) when (ispixel(@value)) {width: @value}
.mixin(@value) when not(default())    {padding: (@value / 5)}

div-1 {
  .mixin(100px);
}

div-2 {
  /* ... */
  .mixin(100%);
}

結果

div-1 {
  width: 100px;
  padding: 20px;
}
div-2 {
  /* ... */
}

允許多次在同一個防護條件或同一個名稱的混合的不同條件中呼叫 default()

div {
  .m(@x) when (default()), not(default())    {always: @x}
  .m(@x) when (default()) and not(default()) {never:  @x}

  .m(1); // OK
}

然而，如果 Less 偵測到使用 default() 的多個混合定義之間有潛在衝突，就會傳回錯誤

div {
  .m(@x) when (default())    {}
  .m(@x) when not(default()) {}

  .m(1); // Error
}

在上方的範例中，無法判斷每個 default() 呼叫應該傳回什麼值，因為它們會遞迴依賴彼此。

進階的多重 default() 用法

.x {
  .m(red)                                    {case-1: darkred}
  .m(blue)                                   {case-2: darkblue}
  .m(@x) when (iscolor(@x)) and (default())  {default-color: @x}
  .m('foo')                                  {case-1: I am 'foo'}
  .m('bar')                                  {case-2: I am 'bar'}
  .m(@x) when (isstring(@x)) and (default()) {default-string: and I am the default}

  &-blue  {.m(blue)}
  &-green {.m(green)}
  &-foo   {.m('foo')}
  &-baz   {.m('baz')}
}

結果

.x-blue {
  case-2: #00008b;
}
.x-green {
  default-color: #008000;
}
.x-foo {
  case-1: I am 'foo';
}
.x-baz {
  default-string: and I am the default;
}

default 函數僅在 Less 內建函數中可用，僅限於防護表達式內。如果在混合防護條件外使用，則會被解釋為常規 CSS 值

範例

div {
  foo: default();
  bar: default(42);
}

結果

div {
  foo: default();
  bar: default(42);
}

unit

移除或變更維度的單位

參數

• dimension：一個數字，可以有單位或沒有單位。
• unit：要變更成的單位（可選），如果省略則會移除單位。

請參閱 convert 以了解如何透過轉換變更單位。

範例：unit(5, px)

輸出：5px

範例：unit(5em)

輸出：5

get-unit

傳回數字的單位。

如果參數包含有單位的數字，函數會傳回其單位。沒有單位的參數會傳回空值。

參數

• number：一個有單位或沒有單位的數字。

範例：get-unit(5px)

輸出：px

範例：get-unit(5)

輸出：//nothing

svg-gradient

產生多點 SVG 漸層。

Svg-gradient 函數會產生多點 svg 漸層。它必須至少有三個參數。第一個參數指定漸層類型和方向，其餘參數則列出顏色及其位置。第一個和最後一個指定顏色的位置是選用的，其餘顏色必須指定位置。

方向必須為下列之一：to bottom、to right、to bottom right、to top right、ellipse 或 ellipse at center。方向可以指定為跳脫值 ~'to bottom' 和以空白分隔的字詞清單 to bottom。

方向後面必須接續兩個以上的顏色停止點。它們可以提供在清單內，或者您可以指定每個顏色停止點在個別引數中。

參數 - 清單中的顏色停止點

• 跳脫值或識別碼清單：方向
• 清單 - 清單中的所有顏色及其位置

參數 - 引數中的顏色停止點

• 跳脫值或識別碼清單：方向
• 顏色 [百分比] 對：第一個顏色及其相對位置（位置是選用的）
• 顏色 百分比 對：第二個顏色及其相對位置（選用的）
• ...
• 顏色 百分比 對：第 n 個顏色及其相對位置（選用的）
• 顏色 [百分比] 對：最後一個顏色及其相對位置（位置是選用的）

傳回：包含「URI 編碼」svg 漸層的 url。

範例 - 清單中的顏色停止點

div {
  @list: red, green 30%, blue;
  background-image: svg-gradient(to right, @list);
}

等效 - 參數中的顏色停止

div {
  background-image: svg-gradient(to right, red, green 30%, blue);
}

兩者結果為

div {
  background-image: url('data:image/svg+xml,%3C%3Fxml%20version%3D%221.0%22%20%3F%3E%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20version%3D%221.1%22%20width%3D%22100%25%22%20height%3D%22100%25%22%20viewBox%3D%220%200%201%201%22%20preserveAspectRatio%3D%22none%22%3E%3ClinearGradient%20id%3D%22gradient%22%20gradientUnits%3D%22userSpaceOnUse%22%20x1%3D%220%25%22%20y1%3D%220%25%22%20x2%3D%22100%25%22%20y2%3D%220%25%22%3E%3Cstop%20offset%3D%220%25%22%20stop-color%3D%22%23ff0000%22%2F%3E%3Cstop%20offset%3D%2230%25%22%20stop-color%3D%22%23008000%22%2F%3E%3Cstop%20offset%3D%22100%25%22%20stop-color%3D%22%230000ff%22%2F%3E%3C%2FlinearGradient%3E%3Crect%20x%3D%220%22%20y%3D%220%22%20width%3D%221%22%20height%3D%221%22%20fill%3D%22url(%23gradient)%22%20%2F%3E%3C%2Fsvg%3E');
}

注意：在 2.2.0 之前的版本中，結果是 base64 編碼。

產生的背景圖片左側為紅色，寬度的 30% 處為綠色，並以藍色結束。Base64 編碼部分包含以下 svg 漸層

<?xml version="1.0" ?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="100%" height="100%" viewBox="0 0 1 1" preserveAspectRatio="none">
    <linearGradient id="gradient" gradientUnits="userSpaceOnUse" x1="0%" y1="0%" x2="100%" y2="0%">
        <stop offset="0%" stop-color="#ff0000"/>
        <stop offset="30%" stop-color="#008000"/>
        <stop offset="100%" stop-color="#0000ff"/>
    </linearGradient>
    <rect x="0" y="0" width="1" height="1" fill="url(#gradient)" />
</svg>

編輯「color-definition」的標記源碼

rgb

從十進位紅色、綠色和藍色 (RGB) 值建立不透明色彩物件。

標準 HTML/CSS 格式中的文字顏色值也可以用來定義顏色，例如 #ff0000。

參數

• red：整數 0-255 或百分比 0-100%。
• green：整數 0-255 或百分比 0-100%。
• blue：整數 0-255 或百分比 0-100%。

傳回：color

範例：rgb(90, 129, 32)

輸出：#5a8120

rgba

從十進位的紅色、綠色、藍色和 alpha (RGBA) 值建立一個透明的色彩物件。

參數

• red：整數 0-255 或百分比 0-100%。
• green：整數 0-255 或百分比 0-100%。
• blue：整數 0-255 或百分比 0-100%。
• alpha：一個介於 0-1 的數字或介於 0-100% 的百分比。

傳回：color

範例：rgba(90, 129, 32, 0.5)

輸出：rgba(90, 129, 32, 0.5)

argb

以 #AARRGGBB 格式建立一個顏色的十六進位表示（不是 #RRGGBBAA！）。

此格式用於 Internet Explorer、.NET 和 Android 開發。

參數：color，色彩物件。

傳回值：字串

範例：argb(rgba(90, 23, 148, 0.5));

輸出：#805a1794

hsl

從色相、飽和度和明度 (HSL) 值建立一個不透明的色彩物件。

參數

• hue：一個表示角度的整數 0-360。
• saturation：一個介於 0-100% 的百分比或介於 0-1 的數字。
• lightness：一個介於 0-100% 的百分比或介於 0-1 的數字。

傳回：color

範例：hsl(90, 100%, 50%)

輸出：#80ff00

如果你想要根據另一個顏色的通道建立一個新的顏色，這會很有用，例如：@new: hsl(hue(@old), 45%, 90%);

@new 會有 @old 的色相，以及它自己的飽和度和明度。

hsla

建立一個透明的顏色物件，從色相、飽和度、明度和 alpha (HSLA) 值。

參數

• hue：一個表示角度的整數 0-360。
• saturation：一個介於 0-100% 的百分比或介於 0-1 的數字。
• lightness：一個介於 0-100% 的百分比或介於 0-1 的數字。
• alpha：一個百分比 0-100% 或數字 0-1。

傳回：color

範例：hsla(90, 100%, 50%, 0.5)

輸出：rgba(128, 255, 0, 0.5)

hsv

建立一個不透明的顏色物件，從色相、飽和度和值 (HSV) 值。

請注意，這是一個在 Photoshop 中可用的色彩空間，與 hsl 不同。

參數

• hue：一個表示角度的整數 0-360。
• saturation：一個介於 0-100% 的百分比或介於 0-1 的數字。
• value：一個百分比 0-100% 或數字 0-1。

傳回：color

範例：hsv(90, 100%, 50%)

輸出：#408000

hsva

建立一個透明的顏色物件，從色相、飽和度、值和 alpha (HSVA) 值。

請注意，這與 hsla 不同，而且是 Photoshop 中可用的色彩空間。

參數

• hue：一個表示角度的整數 0-360。
• saturation：一個介於 0-100% 的百分比或介於 0-1 的數字。
• value：一個百分比 0-100% 或數字 0-1。
• alpha：一個百分比 0-100% 或數字 0-1。

傳回：color

範例：hsva(90, 100%, 50%, 0.5)

輸出：rgba(64, 128, 0, 0.5)

編輯「color-channel」的 markdown 原始碼

色相

擷取 HSL 色彩空間中色彩物件的色相通道。

參數：color - 一個色彩物件。

傳回：整數 0-360

範例：hue(hsl(90, 100%, 50%))

輸出：90

飽和度

擷取 HSL 色彩空間中色彩物件的飽和度通道。

參數：color - 一個色彩物件。

傳回：百分比 0-100

範例：saturation(hsl(90, 100%, 50%))

輸出：100%

明度

擷取 HSL 色彩空間中色彩物件的明度通道。

參數：color - 一個色彩物件。

傳回：百分比 0-100

範例：lightness(hsl(90, 100%, 50%))

輸出：50%

hsv 色相

擷取 HSV 色彩空間中色彩物件的色相通道。

參數：color - 一個色彩物件。

傳回：整數 0-360

範例：hsvhue(hsv(90, 100%, 50%))

輸出：90

hsv 飽和度

擷取 HSV 色彩空間中色彩物件的飽和度通道。

參數：color - 一個色彩物件。

傳回：百分比 0-100

範例：hsvsaturation(hsv(90, 100%, 50%))

輸出：100%

hsvvalue

擷取 HSV 色彩空間中色彩物件的值通道。

參數：color - 一個色彩物件。

傳回：百分比 0-100

範例：hsvvalue(hsv(90, 100%, 50%))

輸出：50%

red

擷取色彩物件的紅色通道。

參數：color - 一個色彩物件。

傳回：float 0-255

範例：red(rgb(10, 20, 30))

輸出：10

green

擷取色彩物件的綠色通道。

參數：color - 一個色彩物件。

傳回：float 0-255

範例：green(rgb(10, 20, 30))

輸出：20

blue

擷取色彩物件的藍色通道。

參數：color - 一個色彩物件。

傳回：float 0-255

範例：blue(rgb(10, 20, 30))

輸出：30

alpha

擷取色彩物件的 alpha 通道。

參數：color - 一個色彩物件。

傳回：float 0-1

範例：alpha(rgba(10, 20, 30, 0.5))

輸出：0.5

luma

計算色彩物件的 亮度（感知亮度）。

使用 SMPTE C / Rec. 709 係數，如 WCAG 2.0 中所建議。此計算也用於對比度函數。

在 v1.7.0 之前，亮度是在沒有伽瑪校正的情況下計算的，使用亮度函數來計算這些「舊」值。

參數：color - 一個色彩物件。

傳回：百分比 0-100%

範例：luma(rgb(100, 200, 30))

輸出：44%

亮度

計算沒有伽瑪校正的亮度值（此函數在 v1.7.0 之前稱為 luma）

參數：color - 一個色彩物件。

傳回：百分比 0-100%

範例：luminance(rgb(100, 200, 30))

輸出：65%

編輯「color-operations」的標記原始碼

色彩運算通常使用與其所變更值相同的單位作為參數，而百分比則視為絕對值處理，因此將 10% 的值增加 10% 會得到 20%。將選項 method 參數設為 relative 以使用相對百分比。使用相對百分比時，將 10% 的值增加 10% 會得到 11%。值會受限於其允許的範圍；它們不會換行。在顯示傳回值時，我們使用清楚顯示各個函數所執行動作的格式，除了您通常會使用的十六進位版本之外。

飽和

在 HSL 色彩空間中，以絕對值增加色彩的飽和度。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：saturate(hsl(90, 80%, 50%), 20%)

輸出：#80ff00 // hsl(90, 100%, 50%)

➜

去飽和

在 HSL 色彩空間中，以絕對值減少色彩的飽和度。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：desaturate(hsl(90, 80%, 50%), 20%)

輸出：#80cc33 // hsl(90, 60%, 50%)

➜

變亮

在 HSL 色彩空間中，以絕對值增加色彩的亮度。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：lighten(hsl(90, 80%, 50%), 20%)

輸出：#b3f075 // hsl(90, 80%, 70%)

➜

變暗

在 HSL 色彩空間中，以絕對值減少色彩的亮度。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：darken(hsl(90, 80%, 50%), 20%)

輸出：#4d8a0f // hsl(90, 80%, 30%)

➜

淡入

降低顏色的透明度（或增加不透明度），使其更不透明。

對不透明顏色沒有影響。要反方向淡入，請使用 fadeout。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：fadein(hsla(90, 90%, 50%, 0.5), 10%)

輸出：rgba(128, 242, 13, 0.6) // hsla(90, 90%, 50%, 0.6)

淡出

增加顏色的透明度（或降低不透明度），使其更透明。要反方向淡入，請使用 fadein。

參數

• color：色彩物件。
• amount：百分比 0-100%。
• method：選擇性，設定為 relative，調整為相對於目前值。

傳回：color

範例：fadeout(hsla(90, 90%, 50%, 0.5), 10%)

輸出：rgba(128, 242, 13, 0.4) // hsla(90, 90%, 50%, 0.4)

淡化

設定顏色的絕對不透明度。無論顏色是否已有不透明度值，都可以套用。

參數

• color：色彩物件。
• amount：百分比 0-100%。

傳回：color

範例：fade(hsl(90, 90%, 50%), 10%)

輸出：rgba(128, 242, 13, 0.1) //hsla(90, 90%, 50%, 0.1)

旋轉

以任一方向旋轉顏色的色相角度。

角度範圍為 0-360 時，會套用模數 360 運算，因此你可以輸入更大的值 (或負值)，它們會換行，例如角度 360 和 720 會產生相同的結果。請注意，顏色會透過 RGB 轉換傳遞，這不會保留灰色的色相值 (因為當沒有飽和度時，色相沒有意義)，因此請務必以保留色相的方式套用函數，例如不要這樣做

@c: saturate(spin(#aaaaaa, 10), 10%);

改用這種方式

@c: spin(saturate(#aaaaaa, 10%), 10);

顏色總是傳回 RGB 值，因此對灰色值套用 spin 不會產生任何作用。

參數

• color：色彩物件。
• angle：要旋轉的度數 (+ 或 -)。

傳回：color

範例

spin(hsl(10, 90%, 50%), 30)
spin(hsl(10, 90%, 50%), -30)

輸出

#f2a60d // hsl(40, 90%, 50%)
#f20d59 // hsl(340, 90%, 50%)

➜

➜

mix

以可變比例將兩種顏色混合在一起。計算中包含不透明度。

參數

• color1：顏色物件。
• color2：顏色物件。
• weight：兩種顏色之間的百分比平衡點，預設為 50%。

傳回：color

範例

mix(#ff0000, #0000ff, 50%)
mix(rgba(100,0,0,1.0), rgba(0,100,0,0.5), 50%)

輸出

#800080
rgba(75, 25, 0, 0.75)

+ ➜

tint

以可變比例將顏色與白色混合。這與呼叫 mix(#ffffff, @color, @weight) 相同

參數

• color：色彩物件。
• weight：顏色與白色之間的百分比平衡點，預設為 50%。

傳回：color

範例

no-alpha: tint(#007fff, 50%); 
with-alpha: tint(rgba(00,0,255,0.5), 50%); 

輸出

no-alpha: #80bfff;
with-alpha: rgba(191, 191, 255, 0.75);

➜

shade

以可變比例將顏色與黑色混合。這與呼叫 mix(#000000, @color, @weight) 相同

參數

• color：色彩物件。
• weight：可選，顏色和黑色之間的百分比平衡點，預設為 50%。

傳回：color

範例

no-alpha: shade(#007fff, 50%); 
with-alpha: shade(rgba(00,0,255,0.5), 50%); 

輸出

no-alpha: #004080;
with-alpha: rgba(0, 0, 64, 0.75);

➜

灰階

從 HSL 色彩空間中的顏色移除所有飽和度；這與呼叫 desaturate(@color, 100%) 相同。

因為飽和度不受色相影響，因此產生的顏色對應可能有點暗或混濁；luma 可能提供更好的結果，因為它提取的是感知亮度，而不是線性亮度，例如 greyscale('#0000ff') 會傳回與 greyscale('#00ff00') 相同的值，儘管它們在人眼看來亮度非常不同。

參數：color：顏色物件。

傳回：color

範例：greyscale(hsl(90, 90%, 50%))

輸出：#808080 // hsl(90, 0%, 50%)

➜

請注意，產生的灰色看起來比原始綠色更暗，即使它們的明度值相同。

與使用 luma 比較（用法不同，因為 luma 傳回單一值，而不是顏色）

@c: luma(hsl(90, 90%, 50%));
color: rgb(@c, @c, @c);

輸出：#cacaca

➜

這次灰色的明度看起來與綠色差不多，儘管它的值實際上更高。

對比

選擇兩個顏色中哪一個與另一個顏色形成最大的對比。

這對於確保顏色在背景下可讀很有用，這對於符合無障礙性也很有用。此函數的工作方式與 SASS 的 Compass 中的對比函數 相同。根據 WCAG 2.0，顏色是使用其伽瑪校正的 明度 值進行比較，而不是其亮度。

亮色和暗色參數可以按任何順序提供 - 函數將計算其明度值並自動分配亮色和暗色，這表示您不能透過反轉順序來使用此函數選擇對比最少的顏色。

參數

• color：要進行比較的顏色物件。
• dark：選用 - 指定的暗色（預設為黑色）。
• light：選用 - 指定的亮色（預設為白色）。
• threshold：選用 - 百分比 0-100%，用來指定從「暗」到「亮」的轉換點（預設為 43%，與 SASS 相符）。這用於偏向對比，例如讓你可以決定 50% 灰色的背景應產生黑色或白色文字。通常會將較「淺」的色盤設定得較低，而較「深」的色盤則設定得較高。

傳回：color

範例

p {
    a: contrast(#bbbbbb);
    b: contrast(#222222, #101010);
    c: contrast(#222222, #101010, #dddddd);
    d: contrast(hsl(90, 100%, 50%), #000000, #ffffff, 30%);
    e: contrast(hsl(90, 100%, 50%), #000000, #ffffff, 80%);
}

輸出

p {
    a: #000000 // black
    b: #ffffff // white
    c: #dddddd
    d: #000000 // black
    e: #ffffff // white
}

這些範例使用上述計算的顏色作為背景和前景；你可以看到你永遠不會得到白色在白色上，或黑色在黑色上，儘管可以使用閾值來允許較低對比的結果，如同最後一個範例

編輯「color-blending」的 markdown 原始檔

這些運算與 Photoshop、Fireworks 或 GIMP 等影像編輯器中的混合模式類似（但未必完全相同），因此你可以使用它們讓你的 CSS 顏色與你的影像相符。

multiply

將兩種顏色相乘。兩個顏色的對應 RGB 通道會相乘，然後除以 255。結果會是較深的顏色。

參數

• color1：顏色物件。
• color2：顏色物件。

傳回：color

範例:

multiply(#ff6600, #000000);

multiply(#ff6600, #333333);

multiply(#ff6600, #666666);

multiply(#ff6600, #999999);

multiply(#ff6600, #cccccc);

multiply(#ff6600, #ffffff);

multiply(#ff6600, #ff0000);

multiply(#ff6600, #00ff00);

multiply(#ff6600, #0000ff);

螢幕

與 multiply 相反。結果為較亮的顏色。

參數

• color1：顏色物件。
• color2：顏色物件。

傳回：color

範例

screen(#ff6600, #000000);

screen(#ff6600, #333333);

screen(#ff6600, #666666);

screen(#ff6600, #999999);

screen(#ff6600, #cccccc);

screen(#ff6600, #ffffff);

screen(#ff6600, #ff0000);

screen(#ff6600, #00ff00);

screen(#ff6600, #0000ff);

疊加

結合 multiply 和 screen 的效果。有條件地使亮色通道變亮，使暗色通道變暗。注意：條件的結果由第一個顏色參數決定。

參數

• color1：一個基礎顏色物件。也是決定結果變亮或變暗的決定性顏色。
• color2：一個要疊加的顏色物件。

傳回：color

範例

overlay(#ff6600, #000000);

overlay(#ff6600, #333333);

overlay(#ff6600, #666666);

overlay(#ff6600, #999999);

overlay(#ff6600, #cccccc);

overlay(#ff6600, #ffffff);

overlay(#ff6600, #ff0000);

overlay(#ff6600, #00ff00);

overlay(#ff6600, #0000ff);

柔光

類似於 overlay，但避免純黑色導致純黑色，純白色導致純白色。

參數

• color1：一個要柔光另一個的顏色物件。
• color2：一個要柔光變亮的顏色物件。

傳回：color

範例

softlight(#ff6600, #000000);

softlight(#ff6600, #333333);

softlight(#ff6600, #666666);

softlight(#ff6600, #999999);

softlight(#ff6600, #cccccc);

softlight(#ff6600, #ffffff);

softlight(#ff6600, #ff0000);

softlight(#ff6600, #00ff00);

softlight(#ff6600, #0000ff);

強光

與 overlay 相同，但顏色角色相反。

參數

• color1：一個要疊加的顏色物件。
• color2：一個基礎顏色物件。也是決定結果變亮或變暗的決定性顏色。

傳回：color

範例

hardlight(#ff6600, #000000);

hardlight(#ff6600, #333333);

hardlight(#ff6600, #666666);

hardlight(#ff6600, #999999);

hardlight(#ff6600, #cccccc);

hardlight(#ff6600, #ffffff);

hardlight(#ff6600, #ff0000);

hardlight(#ff6600, #00ff00);

hardlight(#ff6600, #0000ff);

差異

逐通道從第一個顏色中減去第二個顏色。負值會反轉。減去黑色不會產生變化；減去白色會導致顏色反轉。

參數

• color1：作為被減數的色彩物件。
• color2：作為減數的色彩物件。

傳回：color

範例

difference(#ff6600, #000000);

difference(#ff6600, #333333);

difference(#ff6600, #666666);

difference(#ff6600, #999999);

difference(#ff6600, #cccccc);

difference(#ff6600, #ffffff);

difference(#ff6600, #ff0000);

difference(#ff6600, #00ff00);

difference(#ff6600, #0000ff);

排除

類似於 difference，但對比度較低。

參數

• color1：作為被減數的色彩物件。
• color2：作為減數的色彩物件。

傳回：color

範例

exclusion(#ff6600, #000000);

exclusion(#ff6600, #333333);

exclusion(#ff6600, #666666);

exclusion(#ff6600, #999999);

exclusion(#ff6600, #cccccc);

exclusion(#ff6600, #ffffff);

exclusion(#ff6600, #ff0000);

exclusion(#ff6600, #00ff00);

exclusion(#ff6600, #0000ff);

平均

計算兩個色彩在每個通道 (RGB) 上的平均值。

參數

• color1：顏色物件。
• color2：顏色物件。

傳回：color

範例

average(#ff6600, #000000);

average(#ff6600, #333333);

average(#ff6600, #666666);

average(#ff6600, #999999);

average(#ff6600, #cccccc);

average(#ff6600, #ffffff);

average(#ff6600, #ff0000);

average(#ff6600, #00ff00);

average(#ff6600, #0000ff);

否定

執行與 difference 相反的效果。

結果是更亮的色彩。注意：相反 效果並不表示反向 效果，後者是由加法 運算產生的。

參數

• color1：作為被減數的色彩物件。
• color2：作為減數的色彩物件。

傳回：color

範例

negation(#ff6600, #000000);

negation(#ff6600, #333333);

negation(#ff6600, #666666);

negation(#ff6600, #999999);

negation(#ff6600, #cccccc);

negation(#ff6600, #ffffff);

negation(#ff6600, #ff0000);

negation(#ff6600, #00ff00);

negation(#ff6600, #0000ff);