Prism

Prism

原始檔
作者
  • Lea Verou <https://lea.verou.me>
授權條款
  • MIT

Prism：輕巧、穩健、優雅的語法高亮顯示

命名空間

勾子函數
語言

成員

(static) disableWorkerMessageHandler :boolean

原始檔
預設值
  • false

預設情況下，如果 Prism 位於網頁工作執行緒中，會假設它位於它自己建立的執行緒中，因此會使用 addEventListener 與其母執行個體進行通訊。但是，如果在您自己的執行緒中自行處理 Prism，您不希望 Prism 執行此動作。

將此值設定為 true，Prism 就會在執行緒中新增自己的監聽器。

顯而易見的，您必須在 Prism 執行前變更此值。為執行此動作，您可以在載入 Prism 腳本前，在全域作用域中新增一個空的 Prism 物件，如下所示

window.Prism = window.Prism || {};
Prism.disableWorkerMessageHandler = true;
// Load Prism's script
類型
  • boolean

(static) manual :boolean

原始檔
預設值
  • false

預設情況下，Prism 會嘗試在頁面載入完成後，對目前的頁面上所有程式碼元素（透過呼叫 Prism.highlightAll）進行高亮顯示。如果例如您想要非同步載入其他語言或外掛程式，這可能會有問題。

將此值設定為 true，Prism 就會不再自動對頁面上的所有程式碼元素進行高亮顯示。

顯而易見的，您必須在自動高亮顯示開始前變更此值。為執行此動作，您可以在載入 Prism 腳本前，在全域作用域中新增一個空的 Prism 物件，如下所示

window.Prism = window.Prism || {};
Prism.manual = true;
// add a new <script> to load Prism's script
類型
  • boolean

方法

(static) highlight(text, grammar, language) → {string}

原始檔

低階函數，只有在您完全了解其功能時，才能使用。它接收輸入字串以及使用的語言定義，並傳回自產製的 HTML 字串。

下列勾子函數會執行

  1. before-tokenize
  2. after-tokenize
  3. wrap：在每個 Token 中。
範例
Prism.highlight('var foo = true;', Prism.languages.javascript, 'javascript');
參數
名稱 類型 描述
text string

要高亮顯示的程式碼字串。
grammar 語法

包含要使用符號的物件。

通常是語言定義，例如 Prism.languages.markup。
language string

傳遞給 grammar 的語言定義名稱。
傳回

高亮顯示的 HTML。

類型
string

(static) highlightAll(asyncopt, callbackopt)

原始檔

這是 Prism API 中最顯著的功能。它會擷取所有具有 .language-xxxx 類別的元素，然後對它們每個執行 Prism.highlightElement。

這等於 Prism.highlightAllUnder(document, async, callback)。

參數
名稱 類型 屬性 預設值 描述
async boolean <optional>
 false

與 Prism.highlightAllUnder 中相同。
callback HighlightCallback <optional>

與 Prism.highlightAllUnder 中相同。

(static) highlightAllUnder(container, asyncopt, callbackopt)

原始檔

擷取含有 .language-xxxx 類別的 container 的所有子代，然後在每一個子代上呼叫 Prism.highlightElement。

下列勾子函數會執行

  1. before-highlightall
  2. before-all-elements-highlight
  3. 每個元素的 Prism.highlightElement 所有鉤子。
參數
名稱 類型 屬性 預設值 描述
container ParentNode

根元素，其含有 .language-xxxx 類別的子代將被突出顯示。
async boolean <optional>
 false

是否使用 Web Workers 異步突出顯示每個元素。
callback HighlightCallback <optional>

一個在每個元素的突出顯示完成後被呼叫的選用回呼。

(static) highlightElement(element, asyncopt, callbackopt)

原始檔

突出顯示單個元素內的程式碼。

下列勾子函數會執行

  1. before-sanity-check
  2. before-highlight
  3. Prism.highlight 的所有鉤子。若 async 為 true，這些鉤子將由非同步工作執行緒執行。
  4. before-insert
  5. after-highlight
  6. complete

若元素不包含任何文字或沒有載入元素語言的文法，將會略過一些上述的鉤子。

參數
名稱 類型 屬性 預設值 描述
element Element

包含程式碼的元素。它必須有一個 language-xxxx 類別才能被處理，其中 xxxx 是有效的語言識別碼。
async boolean <optional>
 false

是否要使用 Web Workers 異步突出顯示元素，以提升效能並在突出顯示大量的程式碼塊時避免阻擋使用者介面。此選項 預設為停用。

注意：必須在主 prism.js 檔案中包含所有用於突出顯示程式碼的語言定義，才能讓非同步突出顯示正常運作。您可以在 下載頁面 組建自己的套件。
callback HighlightCallback <optional>

一個在突出顯示完成後被呼叫的選用回呼。主要在 async 為 true 時有用，因為在這種情況下，突出顯示是異步完成的。

(static) tokenize(text, grammar) → {TokenStream}

原始檔

這是 Prism 的核心，也是您可以使用的最底層函式。它接受一個字串作為輸入和要使用的語言定義，並傳回一個包含已標記代碼的陣列。

當語言定義包含巢狀標記時，這個函式會針對每個標記遞迴呼叫。

這個方法還可在其他情況下作為一個非常粗糙的剖析程式被使用。

範例
let code = `var foo = 0;`;
let tokens = Prism.tokenize(code, Prism.languages.javascript);
tokens.forEach(token => {
    if (token instanceof Prism.Token && token.type === 'number') {
        console.log(`Found numeric literal: ${token.content}`);
    }
});
參數
名稱 類型 描述
text string

要高亮顯示的程式碼字串。
grammar 語法

包含要使用符號的物件。

通常是語言定義，例如 Prism.languages.markup。
傳回

一個字串和標記的陣列，一個標記串流。

類型
TokenStream