postcss

建立新的 處理器 執行個體，將 外掛程式 套用為 CSS 處理器。

let postcss = require('postcss')

postcss(plugins).process(css, { from, to }).then(result => {
  console.log(result.css)
})

傳回 處理器。

postcss.AcceptedPlugin

類型：物件 | OldPlugin<any> | 外掛程式 | PluginCreator<any> | 處理器 | TransformCallback。

postcss.Builder

postcss.Helpers

類型：物件 & Postcss。

postcss.JSONHydrator

傳回 節點。

postcss.OldPlugin

傳回 轉換器。

postcss.Parser

傳回 RootNode。

postcss.PluginCreator

傳回 處理器 | 外掛程式。

postcss.Postcss

類型：postcss 的 typeof。

postcss.SourceMap

類型：SourceMapGenerator 和物件。

postcss.Stringifier

postcss.TransformCallback

傳回 void | Promise<void>。

postcss.Transformer

傳回 void | Promise<void>。

postcss.atRule

建立新的 AtRule 節點。

傳回 AtRule_。

postcss.comment

建立新的 Comment 節點。

傳回 Comment_。

postcss.decl

建立新的 Declaration 節點。

傳回 Declaration_。

postcss.document

建立新的 Document 節點。

傳回 Document_。

postcss.fromJSON

將 JSON AST（來自 Node#toJSON）重新轉換為 AST 類別。

const json = root.toJSON()
// save to file, send by network, etc
const root2  = postcss.fromJSON(json)

傳回 節點。

postcss.list

類型：List。

postcss.parse

剖析原始碼 css 並傳回新的 Root 或 Document 節點，其中包含原始碼 CSS 節點。

// Simple CSS concatenation with source map support
const root1 = postcss.parse(css1, { from: file1 })
const root2 = postcss.parse(css2, { from: file2 })
root1.append(root2).toResult().css

傳回 Root。

postcss.root

建立新的 Root 節點。

傳回 Root。

postcss.rule

建立新的 Rule 節點。

傳回 Rule。

postcss.stringify

預設函式用於將節點樹轉換為 CSS 字串。

AtRule

表示 at-rule。

Once (root, { AtRule }) {
  let media = new AtRule({ name: 'media', params: 'print' })
  media.append(…)
  root.append(media)
}

如果在 CSS 中後面接著 {} 區塊，此節點將具有代表其子項目的 nodes 屬性。

const root = postcss.parse('@charset "UTF-8"; @media print {}')

const charset = root.first
charset.type  //=> 'atrule'
charset.nodes //=> undefined

const media = root.last
media.nodes   //=> []

AtRule#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 AtRule。

AtRule#append()

將新節點插入至容器的結尾。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.append(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 AtRule。

AtRule#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 AtRule。

AtRule#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 AtRule。

AtRule#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

AtRule#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 AtRule。

AtRule#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 AtRule。

AtRule#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 AtRule。

AtRule#each()

遍歷容器的直接子節點，並為每個子節點呼叫 callback。

在 callback 中傳回 false 將中斷反覆運算。

此方法只會迭代容器的直接子節點。如果您需要遞迴迭代所有容器的子節點，請使用 Container#walk。

與 for {} 循環或 Array#forEach 不同，如果您在迭代期間對子節點陣列進行變異，此迭代器是安全的。PostCSS 會調整目前索引以符合變異。

const root = postcss.parse('a { color: black; z-index: 1 }')
const rule = root.first

for (const decl of rule.nodes) {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Cycle will be infinite, because cloneBefore moves the current node
  // to the next index
}

rule.each(decl => {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Will be executed only for color and z-index
})

傳回 void | false。

AtRule#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

AtRule#every()

如果 callback 對容器的所有子節點傳回 true，則傳回 true。

const noPrefixes = rule.every(i => i.prop[0] !== '-')

傳回 boolean。

AtRule#index()

傳回 child 在 Container#nodes 陣列中的索引。

rule.index( rule.nodes[2] ) //=> 2

傳回 數字。

AtRule#insertAfter()

在容器中將新節點插入舊節點之後。

傳回 AtRule。

AtRule#insertBefore()

在容器中插入新的節點，位於舊節點之前。

rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))

傳回 AtRule。

AtRule#name

at 規則的名稱緊接在 @ 之後。

const root  = postcss.parse('@media print {}')
media.name //=> 'media'
const media = root.first

類型：字串。

AtRule#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

AtRule#nodes

包含容器子節點的陣列。

const root = postcss.parse('a { color: black }')
root.nodes.length           //=> 1
root.nodes[0].selector      //=> 'a'
root.nodes[0].nodes[0].prop //=> 'color'

類型：子節點[].

AtRule#params

at 規則的參數，即 at 規則名稱之後但位於任何 {} 區塊之前的那些值。

const root  = postcss.parse('@media print, screen {}')
const media = root.first
media.params //=> 'print, screen'

類型：字串。

AtRule#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Container_<子節點>。

AtRule#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

AtRule#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

AtRule#prepend()

在容器開頭插入新的節點。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.prepend(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 AtRule。

AtRule#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

AtRule#push()

將子節點新增至節點尾端。

rule.push(new Declaration({ prop: 'color', value: 'black' }))

傳回 AtRule。

AtRule#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

AtRule#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

AtRule#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：AtRuleRaws。

AtRule#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 AtRule。

AtRule#removeAll()

從容器中移除所有子節點並清除其父屬性。

rule.removeAll()
rule.nodes.length //=> 0

傳回 AtRule。

AtRule#removeChild()

從容器中移除節點並清除節點及其子節點的父屬性。

rule.nodes.length  //=> 5
rule.removeChild(decl)
rule.nodes.length  //=> 4
decl.parent        //=> undefined

傳回 AtRule。

AtRule#replaceValues()

傳回 AtRule。

AtRule#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 AtRule。

AtRule#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

AtRule#some()

如果回呼函式對容器的其中一個（至少一個）子節點傳回 true，則傳回 true。

const hasPrefix = rule.some(i => i.prop[0] === '-')

傳回 boolean。

AtRule#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

AtRule#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

AtRule#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

AtRule#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型：「atrule」。

AtRule#walk()

遍歷容器的後代節點，並針對每個節點呼叫回呼函式。

與 container.each() 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

如果您只需要反覆運算容器的直接子節點，請使用 Container#each。

root.walk(node => {
  // Traverses all descendant nodes.
})

傳回 void | false。

AtRule#walkAtRules()

遍歷容器的後代節點，並針對每個 at-rule 節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符名稱的 at-rule 發生。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

root.walkAtRules(rule => {
  if (isOld(rule.name)) rule.remove()
})

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

傳回 void | false。

AtRule#walkComments()

傳回 void | false。

AtRule#walkDecls()

遍歷容器的後代節點，並針對每個宣告節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符屬性的宣告發生。

root.walkDecls(decl => {
  checkPropertySupport(decl.prop)
})

root.walkDecls('border-radius', decl => {
  decl.remove()
})

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

傳回 void | false。

AtRule#walkRules()

遍歷容器的後代節點，針對每個規則節點呼叫回呼。

如果您傳遞篩選器，則迭代只會發生在具有匹配選擇器的規則上。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

傳回 void | false。

AtRule#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

Comment

它表示處理 CSS 註解 的類別

Once (root, { Comment }) {
  const note = new Comment({ text: 'Note: …' })
  root.append(note)
}

請記住，選擇器、at 規則參數或宣告值中的 CSS 註解會儲存在上面說明的 raws 屬性中。

Comment#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回Comment。

Comment#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回Comment。

Comment#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回Comment。

Comment#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

Comment#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回Comment。

Comment#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回Comment。

Comment#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回Comment。

Comment#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

Comment#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

Comment#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Container_<子節點>。

Comment#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

Comment#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

Comment#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

Comment#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

Comment#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

Comment#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：CommentRaws。

Comment#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回Comment。

Comment#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回Comment。

Comment#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

Comment#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

Comment#text

註解的文字。

類型：字串。

Comment#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

Comment#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

Comment#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型：「comment」。

Comment#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

容器

Root、AtRule 和 Rule 容器節點繼承了一些常見方法，以協助處理其子節點。

請注意，所有容器都可以儲存任何內容。如果您在規則內撰寫規則，PostCSS 將會解析它。

Container#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 Container<Child>。

Container#append()

將新節點插入至容器的結尾。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.append(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 Container<Child>。

Container#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 Container<Child>。

Container#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 Container<Child>。

Container#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

Container#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 Container<Child>。

Container#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 Container<Child>。

Container#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 Container<Child>。

Container#each()

遍歷容器的直接子節點，並為每個子節點呼叫 callback。

在 callback 中傳回 false 將中斷反覆運算。

此方法只會迭代容器的直接子節點。如果您需要遞迴迭代所有容器的子節點，請使用 Container#walk。

與 for {} 循環或 Array#forEach 不同，如果您在迭代期間對子節點陣列進行變異，此迭代器是安全的。PostCSS 會調整目前索引以符合變異。

const root = postcss.parse('a { color: black; z-index: 1 }')
const rule = root.first

for (const decl of rule.nodes) {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Cycle will be infinite, because cloneBefore moves the current node
  // to the next index
}

rule.each(decl => {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Will be executed only for color and z-index
})

傳回 void | false。

Container#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

Container#every()

如果 callback 對容器的所有子節點傳回 true，則傳回 true。

const noPrefixes = rule.every(i => i.prop[0] !== '-')

傳回 boolean。

Container#index()

傳回 child 在 Container#nodes 陣列中的索引。

rule.index( rule.nodes[2] ) //=> 2

傳回 數字。

Container#insertAfter()

在容器中將新節點插入舊節點之後。

傳回 Container<Child>。

Container#insertBefore()

在容器中插入新的節點，位於舊節點之前。

rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))

傳回 Container<Child>。

Container#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

Container#nodes

包含容器子節點的陣列。

const root = postcss.parse('a { color: black }')
root.nodes.length           //=> 1
root.nodes[0].selector      //=> 'a'
root.nodes[0].nodes[0].prop //=> 'color'

類型：Child[]。

Container#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Container_<ChildNode> | Document_。

Container#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

Container#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

Container#prepend()

在容器開頭插入新的節點。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.prepend(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 Container<Child>。

Container#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

Container#push()

將子節點新增至節點尾端。

rule.push(new Declaration({ prop: 'color', value: 'black' }))

傳回 Container<Child>。

Container#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

Container#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

Container#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：任何。

Container#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 Container<Child>。

Container#removeAll()

從容器中移除所有子節點並清除其父屬性。

rule.removeAll()
rule.nodes.length //=> 0

傳回 Container<Child>。

Container#removeChild()

從容器中移除節點並清除節點及其子節點的父屬性。

rule.nodes.length  //=> 5
rule.removeChild(decl)
rule.nodes.length  //=> 4
decl.parent        //=> undefined

傳回 Container<Child>。

Container#replaceValues()

傳回 Container<Child>。

Container#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 Container<Child>。

Container#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

Container#some()

如果回呼函式對容器的其中一個（至少一個）子節點傳回 true，則傳回 true。

const hasPrefix = rule.some(i => i.prop[0] === '-')

傳回 boolean。

Container#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

Container#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

Container#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

Container#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型：字串。

Container#walk()

遍歷容器的後代節點，並針對每個節點呼叫回呼函式。

與 container.each() 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

如果您只需要反覆運算容器的直接子節點，請使用 Container#each。

root.walk(node => {
  // Traverses all descendant nodes.
})

傳回 void | false。

Container#walkAtRules()

遍歷容器的後代節點，並針對每個 at-rule 節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符名稱的 at-rule 發生。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

root.walkAtRules(rule => {
  if (isOld(rule.name)) rule.remove()
})

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

傳回 void | false。

Container#walkComments()

傳回 void | false。

Container#walkDecls()

遍歷容器的後代節點，並針對每個宣告節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符屬性的宣告發生。

root.walkDecls(decl => {
  checkPropertySupport(decl.prop)
})

root.walkDecls('border-radius', decl => {
  decl.remove()
})

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

傳回 void | false。

Container#walkRules()

遍歷容器的後代節點，針對每個規則節點呼叫回呼。

如果您傳遞篩選器，則迭代只會發生在具有匹配選擇器的規則上。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

傳回 void | false。

Container#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

CssSyntaxError

CSS 解析器會針對有問題的 CSS 拋出此錯誤。

自訂解析器可以使用 Node#error 方法針對有問題的自訂語法拋出此錯誤。

PostCSS 會使用輸入來源地圖來偵測原始錯誤位置。如果您撰寫 Sass 檔案，並將其編譯成 CSS，然後使用 PostCSS 解析，PostCSS 會顯示 Sass 檔案中的原始位置。

如果您需要 PostCSS 輸入中的位置（例如，除錯先前的編譯器），請使用 error.input.file。

// Raising error from plugin
throw node.error('Unknown variable', { plugin: 'postcss-vars' })

// Catching and checking syntax error
try {
  postcss.parse('a{')
} catch (error) {
  if (error.name === 'CssSyntaxError') {
    error //=> CssSyntaxError
  }
}

CssSyntaxError#column

錯誤的來源欄位。

error.column       //=> 1
error.input.column //=> 4

PostCSS 會使用輸入來源地圖來偵測原始位置。如果您需要 PostCSS 輸入中的位置，請使用 error.input.column。

類型：數字。

CssSyntaxError#endColumn

錯誤結束的來源欄位，不包含。如果錯誤與範圍有關，則提供。

error.endColumn       //=> 1
error.input.endColumn //=> 4

PostCSS 會使用輸入來源地圖來偵測原始位置。如果您需要 PostCSS 輸入中的位置，請使用 error.input.endColumn。

類型：數字。

CssSyntaxError#endLine

錯誤結束的來源行，不包含。如果錯誤與範圍有關，則提供。

error.endLine       //=> 3
error.input.endLine //=> 4

PostCSS 會使用輸入來源地圖來偵測原始位置。如果您需要 PostCSS 輸入中的位置，請使用 error.input.endLine。

類型：數字。

CssSyntaxError#file

損壞檔案的絕對路徑。

error.file       //=> 'a.sass'
error.input.file //=> 'a.css'

PostCSS 會使用輸入來源地圖來偵測原始位置。如果您需要 PostCSS 輸入中的位置，請使用 error.input.file。

類型：字串。

CssSyntaxError#input

輸入物件，包含 PostCSS 關於輸入檔案的內部資訊。如果輸入有來自先前工具的來源地圖，PostCSS 會使用原始 (例如 Sass) 來源。您可以使用這個物件來取得 PostCSS 輸入來源。

error.input.file //=> 'a.css'
error.file       //=> 'a.sass'

類型：FilePosition。

CssSyntaxError#line

錯誤的來源行。

error.line       //=> 2
error.input.line //=> 4

PostCSS 會使用輸入來源地圖來偵測原始位置。如果您需要 PostCSS 輸入中的位置，請使用 error.input.line。

類型：數字。

CssSyntaxError#message

使用外掛程式、檔案、行和欄的 GNU 錯誤格式的完整錯誤文字。

error.message //=> 'a.css:1:1: Unclosed block'

類型：字串。

CssSyntaxError#name

總是等於 'CssSyntaxError'。您應該總是透過 error.name === 'CssSyntaxError' 而不是 error instanceof CssSyntaxError 來檢查錯誤類型，因為 npm 可能有多個 PostCSS 版本。

if (error.name === 'CssSyntaxError') {
  error //=> CssSyntaxError
}

類型："CssSyntaxError"。

CssSyntaxError#plugin

如果錯誤來自於外掛，則為外掛名稱。

error.plugin //=> 'postcss-vars'

類型：字串。

CssSyntaxError#reason

錯誤訊息。

error.message //=> 'Unclosed block'

類型：字串。

CssSyntaxError#showSourceCode()

傳回導致錯誤的幾行 CSS 原始碼。

如果 CSS 有一個輸入來源地圖，但沒有 sourceContent，此方法將傳回一個空字串。

error.showSourceCode() //=> "  4 | }
                       //      5 | a {
                       //    > 6 |   bad
                       //        |   ^
                       //      7 | }
                       //      8 | b {"

傳回 字串。

CssSyntaxError#source

有問題檔案的原始碼。

error.source       //=> 'a { b {} }'
error.input.source //=> 'a b { }'

類型：字串。

CssSyntaxError#stack

類型：字串。

CssSyntaxError#toString()

傳回錯誤位置、訊息和有問題部分的原始碼。

error.toString() //=> "CssSyntaxError: app.css:1:1: Unclosed block
                 //    > 1 | a {
                 //        | ^"

傳回 字串。

Declaration

它代表一個處理 CSS 宣告 的類別

Once (root, { Declaration }) {
  const color = new Declaration({ prop: 'color', value: 'black' })
  root.append(color)
}

const root = postcss.parse('a { color: black }')
const decl = root.first?.first

decl.type       //=> 'decl'
decl.toString() //=> ' color: black'

Declaration#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 Declaration。

Declaration#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 Declaration。

Declaration#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 Declaration。

Declaration#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

Declaration#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 Declaration。

Declaration#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 Declaration。

Declaration#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 Declaration。

Declaration#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

Declaration#important

它代表宣告的特殊性。

如果為 true，CSS 宣告將會有 important 規範。

const root = postcss.parse('a { color: black !important; color: red }')

root.first.first.important //=> true
root.first.last.important  //=> undefined

類型：布林值。

Declaration#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

Declaration#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Container_<子節點>。

宣告#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

宣告#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

宣告#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

宣告#prop

CSS 宣告的屬性名稱。

const root = postcss.parse('a { color: black }')
const decl = root.first.first

decl.prop //=> 'color'

類型：字串。

宣告#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

宣告#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

宣告#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：DeclarationRaws。

宣告#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 Declaration。

宣告#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 Declaration。

宣告#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

宣告#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

宣告#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

宣告#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

宣告#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型：「decl」。

宣告#value

CSS 宣告的屬性值。

值字串中的任何 CSS 註解都會被濾除。原始值中存在的 CSS 註解會在 raws 屬性中提供。

指定新的 value 會在將節點編譯成字串時忽略 raws 屬性中的註解。

const root = postcss.parse('a { color: black }')
const decl = root.first.first

decl.value //=> 'black'

類型：字串。

宣告#variable

它表示一個 getter，如果宣告以 -- 或 $ 開頭，則會傳回 true，這些符號用於在 CSS 和 SASS/SCSS 中宣告變數。

const root = postcss.parse(':root { --one: 1 }')
const one = root.first.first

one.variable //=> true

const root = postcss.parse('$one: 1')
const one = root.first

one.variable //=> true

類型：布林值。

宣告#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

Document

表示一個檔案，並包含其所有已剖析的節點。

實驗性：此節點的某些面向可能會在次要或修補版本中變更。

const document = htmlParser(
  '<html><style>a{color:black}</style><style>b{z-index:2}</style>'
)
document.type         //=> 'document'
document.nodes.length //=> 2

文件#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 文件。

文件#append()

將新節點插入至容器的結尾。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.append(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 文件。

文件#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 文件。

文件#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 文件。

文件#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

文件#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 文件。

Document#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 文件。

Document#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 文件。

Document#each()

遍歷容器的直接子節點，並為每個子節點呼叫 callback。

在 callback 中傳回 false 將中斷反覆運算。

此方法只會迭代容器的直接子節點。如果您需要遞迴迭代所有容器的子節點，請使用 Container#walk。

與 for {} 循環或 Array#forEach 不同，如果您在迭代期間對子節點陣列進行變異，此迭代器是安全的。PostCSS 會調整目前索引以符合變異。

const root = postcss.parse('a { color: black; z-index: 1 }')
const rule = root.first

for (const decl of rule.nodes) {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Cycle will be infinite, because cloneBefore moves the current node
  // to the next index
}

rule.each(decl => {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Will be executed only for color and z-index
})

傳回 void | false。

Document#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

Document#every()

如果 callback 對容器的所有子節點傳回 true，則傳回 true。

const noPrefixes = rule.every(i => i.prop[0] !== '-')

傳回 boolean。

Document#index()

傳回 child 在 Container#nodes 陣列中的索引。

rule.index( rule.nodes[2] ) //=> 2

傳回 數字。

Document#insertAfter()

在容器中將新節點插入舊節點之後。

傳回 文件。

Document#insertBefore()

在容器中插入新的節點，位於舊節點之前。

rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))

傳回 文件。

Document#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

Document#nodes

包含容器子節點的陣列。

const root = postcss.parse('a { color: black }')
root.nodes.length           //=> 1
root.nodes[0].selector      //=> 'a'
root.nodes[0].nodes[0].prop //=> 'color'

類型：Root[].

Document#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：未定義。

Document#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

Document#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

Document#prepend()

在容器開頭插入新的節點。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.prepend(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 文件。

Document#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

Document#push()

將子節點新增至節點尾端。

rule.push(new Declaration({ prop: 'color', value: 'black' }))

傳回 文件。

Document#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

Document#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

Document#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：任何。

Document#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 文件。

Document#removeAll()

從容器中移除所有子節點並清除其父屬性。

rule.removeAll()
rule.nodes.length //=> 0

傳回 文件。

Document#removeChild()

從容器中移除節點並清除節點及其子節點的父屬性。

rule.nodes.length  //=> 5
rule.removeChild(decl)
rule.nodes.length  //=> 4
decl.parent        //=> undefined

傳回 文件。

Document#replaceValues()

傳回 文件。

Document#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 文件。

Document#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

Document#some()

如果回呼函式對容器的其中一個（至少一個）子節點傳回 true，則傳回 true。

const hasPrefix = rule.some(i => i.prop[0] === '-')

傳回 boolean。

Document#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

Document#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

Document#toResult()

傳回一個表示文件 CSS 根的 Result 實例。

const root1 = postcss.parse(css1, { from: 'a.css' })
const root2 = postcss.parse(css2, { from: 'b.css' })
const document = postcss.document()
document.append(root1)
document.append(root2)
const result = document.toResult({ to: 'all.css', map: true })

傳回 Result<Document_ | Root>。

Document#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

Document#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型："document".

文件#walk()

遍歷容器的後代節點，並針對每個節點呼叫回呼函式。

與 container.each() 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

如果您只需要反覆運算容器的直接子節點，請使用 Container#each。

root.walk(node => {
  // Traverses all descendant nodes.
})

傳回 void | false。

文件#walkAtRules()

遍歷容器的後代節點，並針對每個 at-rule 節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符名稱的 at-rule 發生。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

root.walkAtRules(rule => {
  if (isOld(rule.name)) rule.remove()
})

let first = false
root.walkAtRules('charset', rule => {
  if (!first) {
    first = true
  } else {
    rule.remove()
  }
})

傳回 void | false。

文件#walkComments()

傳回 void | false。

文件#walkDecls()

遍歷容器的後代節點，並針對每個宣告節點呼叫回呼函式。

如果您傳遞篩選器，則反覆運算只會針對具有相符屬性的宣告發生。

root.walkDecls(decl => {
  checkPropertySupport(decl.prop)
})

root.walkDecls('border-radius', decl => {
  decl.remove()
})

root.walkDecls(/^background/, decl => {
  decl.value = takeFirstColorFromGradient(decl.value)
})

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

傳回 void | false。

文件#walkRules()

遍歷容器的後代節點，針對每個規則節點呼叫回呼。

如果您傳遞篩選器，則迭代只會發生在具有匹配選擇器的規則上。

與 Container#each 一樣，如果您在反覆運算期間變異陣列，則可以使用這個方法。

const selectors = []
root.walkRules(rule => {
  selectors.push(rule.selector)
})
console.log(`Your CSS uses ${ selectors.length } selectors`)

傳回 void | false。

文件#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

Input

表示來源 CSS。

const root  = postcss.parse(css, { from: file })
const input = root.source.input

輸入#css

輸入 CSS 來源。

const input = postcss.parse('a{}', { from: file }).input
input.css //=> "a{}"

類型：字串。

輸入#error()

傳回 CssSyntaxError_。

輸入#檔案

使用 from 選項定義的 CSS 來源檔案的絕對路徑。

const root = postcss.parse(css, { from: 'a.css' })
root.source.input.file //=> '/home/ai/a.css'

類型：字串。

輸入#fromOffset()

將來源偏移轉換為行和欄。

傳回 物件。

輸入#hasBOM

旗標用於指示來源程式碼是否有 Unicode BOM。

類型：布林值。

輸入#id

CSS 來源的唯一 ID。如果未提供 from 選項，將會建立此 ID（因為 PostCSS 不知道檔案路徑）。

const root = postcss.parse(css)
root.source.input.file //=> undefined
root.source.input.id   //=> "<input css 8LZeVF>"

類型：字串。

輸入#map

從 PostCSS 之前的編譯步驟傳遞的輸入來源地圖（例如，來自 Sass 編譯器）。

root.source.input.map.consumer().sources //=> ['a.sass']

類型：PreviousMap_。

輸入#origin()

讀取輸入來源地圖，並傳回輸入來源中的符號位置（例如，在傳遞給 PostCSS 之前編譯成 CSS 的 Sass 檔案中）。選擇性地採用結束位置（不包含）。

root.source.input.origin(1, 1) //=> { file: 'a.css', line: 3, column: 1 }
root.source.input.origin(1, 1, 1, 4)
//=> { file: 'a.css', line: 3, column: 1, endLine: 3, endColumn: 4 }

傳回 false | 檔案位置。

LazyResult

PostCSS 轉換結果的 Promise 代理。

LazyResult 執行個體由 Processor#process 傳回。

const lazy = postcss([autoprefixer]).process(css)

LazyResult#async()

以非同步方式執行外掛程式，並傳回 Result。

傳回 Promise<Result<RootNode>>。

LazyResult#catch

類型：函式。

LazyResult#finally

類型：函式。

LazyResult#sync()

以同步方式執行外掛程式，並傳回 Result。

傳回 Result<RootNode>。

LazyResult#then

類型：函式。

LazyResult#toString()

LazyResult#css 屬性的別名。

lazy + '' === lazy.css

傳回 字串。

LazyResult#warnings()

透過同步外掛程式處理輸入的 CSS，並呼叫 Result#warnings。

傳回 Warning[]。

NoWorkResult

PostCSS 轉換結果的 Promise 代理。此 LazyResult 執行個體不會剖析 CSS，除非存取 NoWorkResult#root 或 Result#root。請參閱以下範例，以取得詳細資料。Processor#process 僅在未定義任何外掛程式時傳回 NoWork 執行個體。

const noWorkResult = postcss().process(css) // No plugins are defined.
                                            // CSS is not parsed
let root = noWorkResult.root // now css is parsed because we accessed the root

NoWorkResult#async()

以非同步方式執行外掛程式，並傳回 Result。

傳回 Promise<Result<Root>>。

NoWorkResult#catch

類型：函式。

NoWorkResult#finally

類型：函式。

NoWorkResult#sync()

以同步方式執行外掛程式，並傳回 Result。

傳回 Result<Root>。

NoWorkResult#then

類型：函式。

NoWorkResult#toString()

LazyResult#css 屬性的別名。

lazy + '' === lazy.css

傳回 字串。

NoWorkResult#warnings()

透過同步外掛程式處理輸入的 CSS，並呼叫 Result#warnings。

傳回 Warning[]。

節點

Node#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 節點。

Node#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 節點。

節點#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 節點。

節點#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

節點#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 節點。

節點#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 節點。

節點#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 節點。

節點#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

節點#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

節點#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Container_<ChildNode> | Document_。

節點#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

節點#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

節點#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

節點#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

節點#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

節點#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：任何。

節點#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 節點。

節點#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 節點。

節點#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

節點#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

節點#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

節點#toString()

它會根據類型將節點編譯成瀏覽器可讀的層疊樣式表字串。

new Rule({ selector: 'a' }).toString() //=> "a {}"

傳回 字串。

節點#type

它表示抽象語法樹中節點的類型。

節點類型有助於識別節點，並根據其類型執行操作。

const declaration = new Declaration({
  prop: 'color',
  value: 'black'
})

declaration.type //=> 'decl'

類型：字串。

節點#warn()

它是 Result#warn 的包裝器，提供產生警告的便利方式。

  Declaration: {
    bad: (decl, { result }) => {
      decl.warn(result, 'Deprecated property: bad')
    }
  }

傳回Warning。

PreviousMap

來自輸入 CSS 的原始碼資訊。例如，Sass 編譯器後的原始碼資訊。

此類別會自動在輸入 CSS 或輸入檔案附近的檔案系統中尋找原始碼資訊（根據 from 選項）。

const root = parse(css, { from: 'a.sass.css' })
root.input.map //=> PreviousMap

PreviousMap#annotation

sourceMappingURL 內容。

類型：字串。

PreviousMap#consumer()

從 source-map 函式庫建立 SourceMapGenerator 類別的執行個體，以處理原始碼資訊。

這是延遲方法，因此它只會在第一次呼叫時建立物件，然後會使用快取。

傳回 SourceMapConsumer。

PreviousMap#file

CSS 原始碼識別碼。如果使用者設定 from 選項，則包含 輸入#檔案；如果使用者未設定，則包含 輸入#id。

類型：字串。

PreviousMap#inline

原始碼資訊是否透過 data-uri 內嵌到輸入 CSS。

類型：布林值。

PreviousMap#mapFile

來源地圖檔案路徑。

類型：字串。

PreviousMap#root

如果來源地圖在獨立檔案中，則為來源地圖檔案的目錄。

類型：字串。

PreviousMap#text

來源地圖檔案內容。

類型：字串。

PreviousMap#withContent()

來源地圖是否包含具有輸入來源文字的 sourcesContent。

傳回 boolean。

處理器

包含用於處理 CSS 的外掛程式。建立一個 Processor 實例，初始化其外掛程式，然後在多個 CSS 檔案上使用該實例。

const processor = postcss([autoprefixer, postcssNested])
processor.process(css1).then(result => console.log(result.css))
processor.process(css2).then(result => console.log(result.css))

Processor#plugins

新增至這個處理器的外掛程式。

const processor = postcss([autoprefixer, postcssNested])
processor.plugins.length //=> 2

類型：(Plugin | TransformCallback | Transformer)[].

Processor#process()

剖析來源 CSS 並傳回 LazyResult Promise 代理。由於某些外掛程式可能是非同步的，因此它不會執行任何轉換。轉換會套用於 LazyResult 方法中。

processor.process(css, { from: 'a.css', to: 'a.out.css' })
  .then(result => {
     console.log(result.css)
  })

傳回 NoWorkResult_ | LazyResult_<Document_ | Root>。

Processor#use()

新增外掛程式以用作 CSS 處理器。

PostCSS 外掛程式可以有 4 種格式

• Plugin 格式的外掛程式。
• 具有 pluginCreator.postcss = true 的外掛程式建立函式。PostCSS 會在沒有引數的情況下呼叫這個函式以取得外掛程式。
• 函式。PostCSS 會將函式傳遞 Root 作為第一個引數，並將目前的 Result 實例作為第二個引數。
• 另一個 Processor 實例。PostCSS 將從該實例複製外掛程式到這個實例。

建立 postcss 實例時，也可以透過傳遞外掛程式作為參數來新增外掛程式（請參閱 [postcss(plugins)]）。

非同步外掛程式應傳回 Promise 實例。

const processor = postcss()
  .use(autoprefixer)
  .use(postcssNested)

傳回 處理器。

Processor#version

目前的 PostCSS 版本。

if (result.processor.version.split('.')[0] !== '6') {
  throw new Error('This plugin works only with PostCSS 6')
}

類型：字串。

Result

提供 PostCSS 轉換的結果。

LazyResult#then 或 Root#toResult 方法會傳回 Result 實例。

postcss([autoprefixer]).process(css).then(result => {
 console.log(result.css)
})

const result2 = postcss.parse(css).toResult()

Result#css

代表 Result#root 的 CSS 字串。

postcss.parse('a{}').toResult().css //=> "a{}"

類型：字串。

Result#lastPlugin

最後執行的 PostCSS 外掛程式。

類型：Plugin | TransformCallback。

Result#map

source-map 函式庫中 SourceMapGenerator 類別的實例，代表對 Result#root 實例的變更。

result.map.toJSON() //=> { version: 3, file: 'a.css', … }

if (result.map) {
  fs.writeFileSync(result.opts.to + '.map', result.map.toString())
}

類型：SourceMap。

Result#messages

包含來自外掛程式的訊息（例如警告或自訂訊息）。每個訊息都應有類型和外掛程式屬性。

AtRule: {
  import: (atRule, { result }) {
    const importedFile = parseImport(atRule)
    result.messages.push({
      type: 'dependency',
      plugin: 'postcss-import',
      file: importedFile,
      parent: result.opts.from
    })
  }
}

類型：Message[].

Result#opts

產生這個 Result 實例的 Processor#process 或 Root#toResult 呼叫中的選項。]

root.toResult(opts).opts === opts

類型：ResultOptions。

Result#processor

用於這個轉換的 Processor 實例。

for (const plugin of result.processor.plugins) {
  if (plugin.postcssPlugin === 'postcss-bad') {
    throw 'postcss-good is incompatible with postcss-bad'
  }
})

類型：Processor。

Result#root

所有轉換後的根節點。

root.toResult().root === root

類型：RootNode。

Result#toString()

傳回 Result#css 內容。

result + '' === result.css

傳回 字串。

Result#warn()

建立 Warning 的執行個體，並將其新增至 Result#messages。

if (decl.important) {
  result.warn('Avoid !important', { node: decl, word: '!important' })
}

傳回Warning。

Result#warnings()

傳回外掛程式中的警告。從 Result#messages 中篩選出 Warning 執行個體。

result.warnings().forEach(warn => {
  console.warn(warn.toString())
})

傳回 Warning[]。

Root

表示 CSS 檔案，並包含其所有已剖析的節點。

const root = postcss.parse('a{color:black} b{z-index:2}')
root.type         //=> 'root'
root.nodes.length //=> 2

Root#after()

將新節點插入至目前的節點之後，並加入至目前的節點父節點中。

僅為 node.parent.insertAfter(node, add) 的別名。

decl.after('color: black')

傳回 Root。

Root#append()

將新節點插入至容器的結尾。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.append(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 Root。

Root#assign()

將屬性指定給現有的節點實例。

decl.assign({ prop: 'word-wrap', value: 'break-word' })

傳回 Root。

Root#before()

將新節點插入至目前的節點之前，並加入至目前的節點父節點中。

僅為 node.parent.insertBefore(node, add) 的別名。

decl.before('content: ""')

傳回 Root。

Root#cleanRaws()

清除節點及其子節點的程式碼樣式屬性。

node.raws.before  //=> ' '
node.cleanRaws()
node.raws.before  //=> undefined

Root#clone()

建立現有節點的複製，其中包含所有屬性及其值，包括 raws 但不包括 type。

decl.raws.before    //=> "\n  "
const cloned = decl.clone({ prop: '-moz-' + decl.prop })
cloned.raws.before  //=> "\n  "
cloned.toString()   //=> -moz-transform: scale(0)

傳回 Root。

Root#cloneAfter()

複製節點的捷徑，並將複製後的節點插入至目前的節點之後。

傳回 Root。

Root#cloneBefore()

複製節點的捷徑，並將複製後的節點插入至目前的節點之前。

decl.cloneBefore({ prop: '-moz-' + decl.prop })

傳回 Root。

Root#each()

遍歷容器的直接子節點，並為每個子節點呼叫 callback。

在 callback 中傳回 false 將中斷反覆運算。

此方法只會迭代容器的直接子節點。如果您需要遞迴迭代所有容器的子節點，請使用 Container#walk。

與 for {} 循環或 Array#forEach 不同，如果您在迭代期間對子節點陣列進行變異，此迭代器是安全的。PostCSS 會調整目前索引以符合變異。

const root = postcss.parse('a { color: black; z-index: 1 }')
const rule = root.first

for (const decl of rule.nodes) {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Cycle will be infinite, because cloneBefore moves the current node
  // to the next index
}

rule.each(decl => {
  decl.cloneBefore({ prop: '-webkit-' + decl.prop })
  // Will be executed only for color and z-index
})

傳回 void | false。

Root#error()

它建立 CssSyntaxError 類別的執行個體，傳遞給此方法的參數會指定給錯誤執行個體。

錯誤執行個體會包含錯誤的描述、節點在來源中的原始位置，顯示行號和欄號。

如果存在任何先前的對應，將會使用它來取得來源的原始位置。

此處的先前對應是指由先前編譯產生的來源對應，例如：Less、Stylus 和 Sass。

此方法傳回錯誤執行個體，而不是擲回它。

if (!variables[name]) {
  throw decl.error(`Unknown variable ${name}`, { word: name })
  // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
  //   color: $black
  // a
  //          ^
  //   background: white
}

傳回 CssSyntaxError_。

Root#every()

如果 callback 對容器的所有子節點傳回 true，則傳回 true。

const noPrefixes = rule.every(i => i.prop[0] !== '-')

傳回 boolean。

Root#index()

傳回 child 在 Container#nodes 陣列中的索引。

rule.index( rule.nodes[2] ) //=> 2

傳回 數字。

Root#insertAfter()

在容器中將新節點插入舊節點之後。

傳回 Root。

Root#insertBefore()

在容器中插入新的節點，位於舊節點之前。

rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))

傳回 Root。

Root#next()

傳回節點父層的下一層子節點。如果目前節點為最後一個子節點，則傳回 undefined。

if (comment.text === 'delete next') {
  const next = comment.next()
  if (next) {
    next.remove()
  }
}

傳回 子節點。

Root#nodes

包含容器子節點的陣列。

const root = postcss.parse('a { color: black }')
root.nodes.length           //=> 1
root.nodes[0].selector      //=> 'a'
root.nodes[0].nodes[0].prop //=> 'color'

類型：子節點[].

Root#parent

代表目前節點的父層。

root.nodes[0].parent === root //=> true

類型：Document_。

Root#positionBy()

取得節點內部字詞或索引的位置。

傳回 位置。

Root#positionInside()

將字串索引轉換為行/欄。

傳回 位置。

Root#prepend()

在容器開頭插入新的節點。

const decl1 = new Declaration({ prop: 'color', value: 'black' })
const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
rule.prepend(decl1, decl2)

root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
root.append({ selector: 'a' })                       // rule
rule.append({ prop: 'color', value: 'black' })       // declaration
rule.append({ text: 'Comment' })                     // comment

root.append('a {}')
root.first.append('color: black; z-index: 1')

傳回 Root。

Root#prev()

傳回節點父層的前一個子節點。如果目前節點為第一個子節點，則傳回 undefined。

const annotation = decl.prev()
if (annotation.type === 'comment') {
  readAnnotation(annotation.text)
}

傳回 子節點。

Root#push()

將子節點新增至節點尾端。

rule.push(new Declaration({ prop: 'color', value: 'black' }))

傳回 Root。

Root#rangeBy()

取得節點內單字或開始和結束索引的範圍。開始索引包含在內；結束索引則不包含在內。

傳回 Range。

Root#raw()

傳回 raws 值。如果節點遺失程式碼樣式屬性（因為節點是手動建立或複製），PostCSS 會嘗試透過檢視樹狀結構中的其他節點來自動偵測程式碼樣式屬性。

const root = postcss.parse('a { background: white }')
root.nodes[0].append({ prop: 'color', value: 'black' })
root.nodes[0].nodes[1].raws.before   //=> undefined
root.nodes[0].nodes[1].raw('before') //=> ' '

傳回 字串。

Root#raws

它代表 css 原始程式碼中不必要的空白和字元。

產生與原始輸入中位元組對位元組相等的節點字串資訊。

raws 物件的屬性由剖析器決定，預設剖析器使用下列屬性

• before：節點前的空白符號。它也儲存宣告前的 * 和 _ 符號（IE hack）。
• after：節點最後一個子節點到節點結尾的空白符號。
• between：宣告中屬性和值、規則中選擇器和 { 或 at 規則中最後一個參數和 { 之間的符號。
• semicolon：如果最後一個子節點有（可選的）分號，則包含 true。
• afterName：at 規則名稱和其參數之間的空白。
• left：/* 和註解文字之間的空白符號。
• right：註解文字和 */ 之間的空白符號。

• important：重要聲明的內容，如果它不只是 !important。

PostCSS 會過濾掉選擇器、宣告值和 at 規則參數中的註解，但會將原始內容儲存在 raws 中。

const root = postcss.parse('a {\n  color:black\n}')
root.first.first.raws //=> { before: '\n  ', between: ':' }

類型：RootRaws。

Root#remove()

它會從父節點移除節點並刪除其父屬性。

if (decl.prop.match(/^-webkit-/)) {
  decl.remove()
}

傳回 Root。

Root#removeAll()

從容器中移除所有子節點並清除其父屬性。

rule.removeAll()
rule.nodes.length //=> 0

傳回 Root。

Root#removeChild()

從容器中移除節點並清除節點及其子節點的父屬性。

rule.nodes.length  //=> 5
rule.removeChild(decl)
rule.nodes.length  //=> 4
decl.parent        //=> undefined

傳回 Root。

Root#replaceValues()

傳回 Root。

Root#replaceWith()

在目前節點之前插入節點並移除目前節點。

AtRule: {
  mixin: atrule => {
    atrule.replaceWith(mixinRules[atrule.params])
  }
}

傳回 Root。

Root#root()

尋找節點樹的 Root 實例。

root.nodes[0].nodes[0].root() === root

傳回 Root。

Root#some()

如果回呼函式對容器的其中一個（至少一個）子節點傳回 true，則傳回 true。

const hasPrefix = rule.some(i => i.prop[0] === '-')

傳回 boolean。

Root#source

它表示與節點來源相關的資訊，且對於產生原始碼對應表是必要的。

使用 PostCSS 提供的公開 API 手動建立的節點將會有未定義的 source，且會在原始碼對應表中缺失。

因此，外掛程式開發人員應考慮複製節點，因為複製的節點預設會與原始節點具有相同的來源，或將來源指定給手動建立的節點。

decl.source.input.from //=> '/home/ai/source.css'
decl.source.start      //=> { line: 10, column: 2 }
decl.source.end        //=> { line: 10, column: 12 }

// Incorrect method, source not specified!
const prefixed = postcss.decl({
  prop: '-moz-' + decl.prop,
  value: decl.value
})

// Correct method, source is inherited when duplicating.
const prefixed = decl.clone({
  prop: '-moz-' + decl.prop
})

if (atrule.name === 'add-link') {
  const rule = postcss.rule({
    selector: 'a',
    source: atrule.source
  })

 atrule.parent.insertBefore(atrule, rule)
}

類型：來源。

Root#toJSON()

修正 JSON.stringify() 上的循環連結。

傳回 物件。

Root#toResult()

傳回一個表示根部 CSS 的 Result 實例。

const root1 = postcss.parse(css1, { from: 'a.css' })
const root2 = postcss.parse(css2, { from: 'b.css' })
root1.append(root2)
const result = root1.toResult({ to: 'all.css', map: true })