XSLT 任務 - Ant 繁體中文

XSLT

名稱 style 是同一個任務的已棄用名稱。

說明

透過 XSLT 處理一組文件。

這對於建立基於 XML 文件的檢視，或產生程式碼很有用。

可以精選要處理的文件組。這可以使用 includes、includesfile、excludes、excludesfile 和 defaultexcludes 屬性來完成。使用 includes 或 includesfile 屬性，您可以使用樣式指定要包含的文件。exclude 或 excludesfile 屬性用於指定要排除的文件。這也是使用樣式來完成。最後，使用 defaultexcludes 屬性，您可以指定是否要使用預設排除。請參閱基於目錄的任務部分，了解如何包含/排除檔案，以及如何撰寫樣式。

此任務形成一個隱含的 FileSet，並支援 <fileset>（dir 變成 basedir）的所有屬性，以及巢狀的 <include>、<exclude> 和 <patternset> 元素。

注意：與其他類似的任務不同，此任務以特殊方式處理已由隱含檔案集的包含/排除樣式配對的目錄。它也會將樣式表套用至其中包含的所有檔案。由於預設的 includes 樣式是 **，這表示它會將樣式表套用至所有檔案。如果您指定 excludes 樣式，它仍可能處理與那些樣式配對的檔案，因為其父目錄已配對。如果這不是您想要的行為，請將 scanincludedirectories 屬性設定為 false。

自 Ant 1.7 起，此任務除了（或取決於 useImplicitFileset 屬性，而取代）此任務形成的隱含檔案集之外，還支援巢狀的資源集合。

此任務支援使用巢狀的 <param> 元素，用於將值傳遞至 <xsl:param> 宣告。

此任務支援使用巢狀的 xmlcatalog 元素，用於執行實體和 URI 解析。

有關 XSLT 延伸函數的注意事項：當使用 Java 類別庫的預設 TrAX 實作，且有 SecurityManager 處於作用中時（例如從 IDE 內部執行），XSLT 延伸函數無法使用，因為在 Java 7 及以上版本中，會作用中「安全處理」。Ant 包含一個特殊「hack」，允許在 Java 7 和 8 中使用 XSLT 延伸函數，但此 hack 無法在 Java 9 中使用。如果您想要使用 Java 類別庫本身提供的延伸函數（例如重新導向延伸函數），您可以在 Java 9 及以上版本中啟用功能 http://www.oracle.com/xml/jaxp/properties/enableExtensionFunctions 來允許使用。如果您需要使用 Java 本身未提供的延伸函數，您可以將屬性 jdk.xml.transform.extensionClassLoader 設定為類別載入器（參照類似 Ant 路徑的結構）。

參數

屬性	說明	必要
basedir	尋找來源 XML 檔案的位置。	否；預設為專案的 `basedir`
destdir	儲存結果的目錄。	是，除非已指定 `in` 和 `out`。
extension	要使用於目標的所需檔案延伸詞。	否；預設為 .html，如果已指定巢狀 `<mapper>` 或 `in` 和 `out`，則會忽略
style	要使用的樣式表的檔名，相對於專案的 `basedir` 或絕對路徑。或者，可以使用 Ant 可詮釋為資源的巢狀元素，以指出尋找樣式表的位置。已棄用的變異: 如果找不到樣式表，且您已為任務指定 `basedir` 屬性，Ant 會假設 `style` 屬性相對於任務的 `basedir`。	否，如果使用巢狀 `<style>` 元素指定樣式表的位置
classpath	尋找 XSLT 處理器時要使用的類別路徑。	否
classpathref	要使用的類別路徑，以參照形式提供，指向其他地方定義的路徑。	否
force	重新建立目標檔案，即使它們比對應的來源檔案或樣式表新。	否；預設為 false
processor	要使用的 XSLT 處理器的名稱。允許的值為 trax，表示符合 TraX 的處理器（例如 Xalan 2 或 Saxon 等 JAXP 介面實作）自 Ant 1.7 起，已移除對 Xalan 1 的支援。	否；預設為 trax
includes	必須包含的檔案範本的逗號或空格分隔清單。	否；預設為全部 (**)
includesfile	檔案名稱。此檔案的每一行都視為包含範本	否
excludes	必須排除的檔案範本的逗號或空格分隔清單。	否；如果 `defaultexcludes` 為 no，則預設為預設排除或無
excludesfile	檔案名稱。此檔案的每一行都視為排除範本	否
defaultexcludes	指出是否應使用預設排除 (yes\|no)。	否；預設為 yes
in	指定要套用樣式的單一 XML 文件。應與 `out` 屬性一起使用。	否
out	指定 `in` 屬性中套用樣式後的結果輸出名稱。	否
scanincludeddirectories	如果任何目錄符合 `includes`/`excludes` 範本，請嘗試轉換這些目錄中的所有檔案。	否；預設為 true
reloadstylesheet	控制是否為每個轉換作業重新建立樣式表轉換器。如果您將此設定為 true，效能可能會下降，但您可能會解決某些 Xalan 版本中的錯誤。自 Ant 1.5.2 起。	否；預設為 false
useImplicitFileset	是否使用此任務形成的隱式檔案集。如果您將此設定為 false，您必須使用巢狀資源集合或 `in` 屬性，在此情況下，此屬性反正沒有影響。自 Ant 1.7 起。	否；預設為 true
filenameparameter	指定用於存取目前處理檔案名稱的 XSL 參數。如果未設定，檔案名稱不會傳遞至轉換。自 Ant 1.7 起。	否
filedirparameter	指定用於存取目前處理檔案目錄的 XSL 參數。對於目前目錄中的檔案，會將 . 值傳遞至轉換。如果未設定，目錄不會傳遞至轉換。自 Ant 1.7 起。	否
suppressWarnings	是否抑制處理器警告。此選項需要處理器支援，它受 Ant 隨附的 TrAX 處理器支援。自 Ant 1.8.0 起。	否；預設為 false
failOnError	如果發生任何錯誤，建置是否應該失敗。請注意，即使此屬性為 true，仍可透過將 `failOnTransformationError` 設為 false 來抑制轉換錯誤。自 Ant 1.8.0 起。	否；預設為 true
failOnTransformationError	如果在轉換文件時發生錯誤，建置是否應該失敗。請注意，如果 `failOnError` 為 false，此屬性不會產生任何效果。自 Ant 1.8.0 起。	否；預設為 true
failOnNoResources	如果巢狀資源集合為空，建置是否應該失敗。請注意，如果 `failOnError` 為 false，此屬性不會產生任何效果。自 Ant 1.8.0 起。	否；預設為 true

指定為巢狀元素的參數

任何資源集合

自 Ant 1.7 起

使用資源集合來指定樣式表應該套用的資源。使用巢狀對應器和任務的 destdir 屬性來指定輸出檔案。

classpath

也可以透過巢狀 <classpath> 來指定用於載入處理器的類別路徑，也就是類似的路徑結構。

xmlcatalog

xmlcatalog 元素用於執行實體和 URI 解析。

param

Param 用於將參數傳遞至 XSL 樣式表。

參數

屬性	說明	必要
name	XSL 參數名稱	是
expression	要放入 param 的值或 XPath 表達式（取決於 `type`）。	是
type	參數的資料類型。可能的數值為 STRING BOOLEAN INT LONG DOUBLE XPATH_STRING XPATH_BOOLEAN XPATH_NUMBER XPATH_NODE XPATH_NODESET 自 Ant 1.9.3 起	否；預設為 STRING
if	如果設定此屬性，才會傳遞 param if this property is set。	否
unless	如果設定此屬性，不會傳遞 param if this property is set。	否

XPATH_* 類型表示 expression 不僅是原始類型值，還是 XPath 表達式。此表達式會在空的 XML 文件上評估，而結果會以指定類型的參數傳遞至 XSLT 轉換器。在這些表達式中，已宣告的 Ant 屬性可以用作 XPath 變數，例如 $someProperty。因此，您可以使用標準 XPath 函數和運算子來運算某些內容。

如果您寫 ${someProperty} 而不是 $someProperty，在評估 XPath 表達式之前，Ant 會簡單地替換值（此替換也適用於基本類型）。

outputproperty（僅限 `trax` 處理器）

用於指定您希望如何輸出結果樹，如 XSLT 規格中所述。

參數

屬性	說明	必要
name	屬性的名稱	是
值	屬性的值	是

factory（僅限 `trax` 處理器）

自 Ant 1.9.8 起

用於指定工廠設定。

參數

屬性	說明	必要
name	要使用的轉換器工廠的完全限定類別名稱。例如 `org.apache.xalan.processor.TransformerFactoryImpl` 或 `org.apache.xalan.xsltc.trax.TransformerFactoryImpl` 或 `net.sf.saxon.TransformerFactoryImpl`...	否；預設為 JAXP 查詢機制

指定為巢狀元素的參數

屬性

用於指定處理器工廠的設定。屬性名稱和值完全取決於處理器，因此您必須了解實作才能找出它們。請閱讀處理器的文件。例如，在 Xalan 2.x 中

http://xml.apache.org/xalan/features/optimize（布林值）
http://xml.apache.org/xalan/features/incremental（布林值）
...

在 Saxon 7.x 中

http://saxon.sf.net/feature/allow-external-functions（布林值）
http://saxon.sf.net/feature/timing（布林值）
http://saxon.sf.net/feature/traceListener（字串）
http://saxon.sf.net/feature/treeModel（整數）
http://saxon.sf.net/feature/linenumbering（整數）
...

參數

屬性說明必要

name 屬性的名稱是

值屬性的值。這些屬性中只有一個

valueref 屬性的值是具有給定 id 的專案參考值。自 Ant 1.9.8 起

classloaderforpath 屬性的值是類別載入器，它使用具有給定 id 的專案參考的路徑所指定的類別路徑。自 Ant 1.9.8 起

範例

<path id="extension-path">
  ...
</path>

<xslt ...>
  <factory>
    <attribute name="jdk.xml.transform.extensionClassLoader"
               classloaderforpath="extension-path"/>
  </factory>
</xslt ...>

將類別載入器設定為使用 id 為 extension-path 的 path 載入延伸函數時使用。

feature

用於指定處理器工廠的設定。功能名稱大多取決於處理器，因此您必須了解實作才能找出它們。請閱讀處理器的文件。所有實作都必須支援的功能只有 http://javax.xml.XMLConstants/feature/secure-processing。

參數

屬性說明必要

name 功能的名稱是

值功能的值。布林值（即允許的值為 true、false、yes、no、on、off）。否；預設為 false

屬性	說明	必要
name	功能的名稱	是
值	功能的值。布林值（即允許的值為 true、false、yes、no、on、off）。	否；預設為 false

對應器

自 Ant 1.6.2 起

您可以使用巢狀對應器元素定義檔案名稱轉換。<xslt> 使用的預設對應器會從來源檔案中移除檔案副檔名，並新增透過副檔名屬性指定的副檔名。

style

自 Ant 1.7 起

巢狀 style 元素可用於根據 Ant 的資源類型指定您的樣式表。使用此元素時，樣式表應指定為巢狀資源或單一元素集合。或者，使用 refid 將資源或集合指定為參考。

系統屬性

自 Ant 1.8.0 起.

使用巢狀 <sysproperty> 元素指定工廠或轉換所需的系統屬性。這些屬性會在執行類別期間提供給 JVM。此元素的屬性與環境變數相同。

系統屬性集

自 Ant 1.8.0 起.

您可以使用系統屬性集指定一組屬性，以用作系統屬性。

範例

<xslt basedir="doc" destdir="build/doc"
       extension=".html" style="style/apache.xsl"/>

使用 xml 目錄

<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <xmlcatalog refid="mycatalog"/>
</xslt>

<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
   <xmlcatalog>
       <dtd
         publicId="-//ArielPartners//DTD XML Article V1.0//EN"
         location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
   </xmlcatalog>
</xslt>

使用 XSL 參數

簡單的字串參數

<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <param name="date" expression="07-01-2000"/>
</xslt>

然後，如果您使用頂層元素 <xsl:param name="date"/> 宣告全域參數 date，變數 $date 之後將具有值 07-01-2000。

各種資料類型和 XPath 表達式

<property name="antProperty1" value="ANT_PROPERTY_1"/>
<property name="antProperty2" value="ANT_PROPERTY_2"/>
<property name="antProperty3" value="3"/>
<property name="antProperty4" value="substring-before"/>

<!--
  ${this} is substituted by Ant itself
  and $this is evaluated by XPath as a variable
-->

<xslt in="in.xml" out="out.xml" style="template.xsl">

  <!-- Simple String parameter: -->
  <param name="p0" expression="some nice string" type="STRING"/>

  <!-- A value substituted by Ant -->
  <param name="p1" expression="some string with ${antProperty1} constructed by Ant" type="STRING"/>

  <!-- XPath resulting in: and this is done in XPath: ANT_PROPERTY_2 -->
  <param name="p2" expression="concat('and this is done in XPath: ', $antProperty2)" type="XPATH_STRING"/>

  <!-- Some XPath math, result: 42 -->
  <param name="p3" expression="64 * 64 div 128 + 10" type="XPATH_NUMBER"/>

  <!-- Some numeric parameter: -->
  <param name="p4" expression="123.45" type="DOUBLE"/>

  <!-- XPath expression, result: true boolean -->
  <param name="p5" expression="$antProperty1 = 'ANT_PROPERTY_1'" type="XPATH_BOOLEAN"/>

  <!-- First one is an XPath variable, second one is a text substituted by Ant, result: true boolean -->
  <param name="p6" expression="$antProperty2 = '${antProperty2}'" type="XPATH_BOOLEAN"/>

  <!-- Some XPath math with a variable, result: 64 -->
  <param name="p7" expression="$antProperty3 * 4 * 5 + 4" type="XPATH_NUMBER"/>

  <!--
    XPath expression with substituted function name and a variable:
    substring-before($antProperty2, '_')
    result: ANT
  -->
  <param name="p8" expression="${antProperty4}($antProperty2, '_')" type="XPATH_STRING"/>

  <!-- Without type attribute: -->
  <param name="p9" expression="default type is String"/>
</xslt>

使用輸出屬性

<xslt in="doc.xml" out="build/doc/output.xml"
      style="style/apache.xsl">
  <outputproperty name="method" value="xml"/>
  <outputproperty name="standalone" value="yes"/>
  <outputproperty name="encoding" value="iso8859_1"/>
  <outputproperty name="indent" value="yes"/>
</xslt>

使用工廠設定

<xslt in="doc.xml" out="build/doc/output.xml"
      style="style/apache.xsl">
  <factory name="org.apache.xalan.processor.TransformerFactoryImpl">
    <attribute name="http://xml.apache.org/xalan/features/optimize" value="true"/>
  </factory>
</xslt>

使用對應器

<xslt basedir="in" destdir="out"
      style="style/apache.xsl">
  <mapper type="glob" from="*.xml.en" to="*.html.en"/>
</xslt>

使用巢狀資源定義樣式表

<xslt in="data.xml" out="${out.dir}/out.xml">
    <style>
        <url url="${printParams.xsl.url}"/>
    </style>
    <param name="set" expression="value"/>
</xslt>

列印目前處理的檔案名稱

<project>
  <xslt style="printFilename.xsl" destdir="out" basedir="in" extension=".txt"
        filenameparameter="filename"
        filedirparameter="filedir"/>
</project>

<xsl:stylesheet
     version="1.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:param name="filename"></xsl:param>
  <xsl:param name="filedir">.</xsl:param>

  <xsl:template match="/">
    Current file is <xsl:value-of select="$filename"/> in directory <xsl:value-of select="$filedir"/>.
  </xsl:template>

</xsl:stylesheet>

在轉換時使用支援 XInclude 的 Xerces 版本

<xslt ...>
    <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration"
                 value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
<xslt>

屬性	說明	必要
name	屬性的名稱	是
值	屬性的值。	這些屬性中只有一個
valueref	屬性的值是具有給定 id 的專案參考值。自 Ant 1.9.8 起
classloaderforpath	屬性的值是類別載入器，它使用具有給定 `id` 的專案參考的路徑所指定的類別路徑。自 Ant 1.9.8 起

XSLT

說明

參數

指定為巢狀元素的參數

任何 資源集合

classpath

xmlcatalog

param

參數

outputproperty（僅限 trax 處理器）

參數

factory（僅限 trax 處理器）

參數

指定為巢狀元素的參數

屬性

參數

範例

feature

參數

對應器

style

系統屬性

系統屬性集

範例

使用 xml 目錄

使用 XSL 參數

使用輸出屬性

使用工廠設定

使用對應器

使用巢狀資源定義樣式表

列印目前處理的檔案名稱

在轉換時使用支援 XInclude 的 Xerces 版本

任何資源集合

outputproperty（僅限 `trax` 處理器）

factory（僅限 `trax` 處理器）