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 的处理器（即 JAXP 接口实现，如 Xalan 2 或 Saxon）从 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	要放入参数的值或 XPath 表达式（取决于 `type`）。	是
type	参数的数据类型。可能的值是 STRING BOOLEAN INT LONG DOUBLE XPATH_STRING XPATH_BOOLEAN XPATH_NUMBER XPATH_NODE XPATH_NODESET 从 Ant 1.9.3 开始	否；默认为 STRING
if	仅当设置此属性时，才会传递参数。	否
unless	仅当设置此属性时，不会传递参数。	否

XPATH_* 类型表示 expression 不仅仅是原始类型值，而是一个 XPath 表达式。此表达式将在空 XML 文档上进行评估，结果将作为给定类型的参数传递给 XSLT 转换器。在这些表达式中，声明的 Ant 属性可以用作 XPath 变量，例如 $someProperty。因此，您可以使用标准 XPath 函数和运算符来计算某些内容。

如果您编写 ${someProperty} 而不是 $someProperty，则该值将在评估 XPath 表达式之前由 Ant 简单地替换（此替换也适用于原始类型）。

outputproperty (`trax` 处理器专用)

用于指定您希望结果树如何输出，如 XSLT 规范中所述。

参数

属性	描述	必需
name	属性的名称	是
value	属性的值	是

factory (`trax` 处理器专用)

从 Ant 1.9.8 开始

用于指定工厂设置。

参数

属性	描述	必需
name	要使用的转换器工厂的完全限定类名。例如 `org.apache.xalan.processor.TransformerFactoryImpl` 或 `org.apache.xalan.xsltc.trax.TransformerFactoryImpl` 或 `net.sf.saxon.TransformerFactoryImpl`...	否；默认为 JAXP 查找机制

作为嵌套元素指定的参数

attribute

用于指定处理器工厂的设置。属性名称和值完全是处理器特定的，因此您必须了解实现才能弄清楚它们。阅读处理器的文档。例如，在 Xalan 2.x 中

http://xml.apache.org/xalan/features/optimize (boolean)
http://xml.apache.org/xalan/features/incremental (boolean)
...

在 Saxon 7.x 中

http://saxon.sf.net/feature/allow-external-functions (boolean)
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 属性名称是

value 属性值。以下选项中必须选择一个

valueref 属性值为具有给定 ID 的项目引用的值。自 Ant 1.9.8 起

classloaderforpath 属性值为一个类加载器，该类加载器使用由具有给定 id 的项目引用的路径指定的类路径。自 Ant 1.9.8 起

属性	描述	必需
name	属性名称	是
value	属性值。	以下选项中必须选择一个
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 功能名称是

value 功能值。布尔值（即允许的值为 true、false、yes、no、on、off）。否；默认值为 false

属性	描述	必需
name	功能名称	是
value	功能值。布尔值（即允许的值为 true、false、yes、no、on、off）。	否；默认值为 false

mapper

自 Ant 1.6.2 起

您可以通过使用嵌套的 mapper 元素来定义文件名转换。<xslt> 使用的默认映射器会从源文件中删除文件扩展名，并添加通过 extension 属性指定的扩展名。

style

从 Ant 1.7 开始

嵌套的 style 元素可用于根据 Ant 的 resource 类型来指定您的样式表。使用此元素，样式表应指定为嵌套资源或单元素集合。或者，使用 refid 将资源或集合指定为引用。

sysproperty

自 Ant 1.8.0 起.

使用嵌套的 <sysproperty> 元素来指定工厂或转换所需的系统属性。这些属性将在类执行期间提供给 JVM。此元素的属性与环境变量的属性相同。

syspropertyset

自 Ant 1.8.0 起.

您可以使用 syspropertyset 来指定一组用作系统属性的属性。

示例

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

使用 xmlcatalog

<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>

XSLT

描述

参数

作为嵌套元素指定的参数

任何 资源集合

classpath

xmlcatalog

param

参数

outputproperty (trax 处理器专用)

参数

factory (trax 处理器专用)

参数

作为嵌套元素指定的参数

attribute

参数

示例

feature

参数

mapper

style

sysproperty

syspropertyset

示例

使用 xmlcatalog

使用 XSL 参数

使用输出属性

使用工厂设置

使用映射器

使用嵌套资源来定义样式表

打印当前处理的文件名

在转换时使用支持 XInclude 的 Xerces 版本

任何资源集合

outputproperty (`trax` 处理器专用)

factory (`trax` 处理器专用)