<!-- review: finished -->

<a id="http-xslt"></a>

# XSLT

该模块是一个过滤器，使用一个或多个 XSLT 样式表转换 XML 响应。

当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时，默认不构建此模块；应使用 `‑‑with‑http_xslt_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 启用它。

在我们的代码库中，该模块是 [动态构建](https://cn.angie.software//angie/docs/installation/index.md#install-dynamicmodules) 的，并作为一个名为 `angie-module-xslt` 或 `angie-pro-module-xslt` 的独立包提供。

#### NOTE
该模块需要 [libxml2](http://xmlsoft.org/) 和 [libxslt](http://xmlsoft.org/XSLT/) 库。

<a id="configuration-example-51"></a>

## 配置示例

```nginx
location / {
    xml_entities    /site/dtd/entities.dtd;
    xslt_stylesheet /site/xslt/one.xslt param=value;
    xslt_stylesheet /site/xslt/two.xslt;
}
```

<a id="directives-54"></a>

## 指令

<a id="index-0"></a>

<a id="xml-entities"></a>

### xml_entities

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xml_entities` path;   |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值                                                                                  | —                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

指定声明字符实体的 DTD 文件。该文件在配置阶段编译。出于技术原因，该模块无法使用在处理的 XML 中声明的外部子集，因此被忽略，并使用专门定义的文件。该文件不应描述 XML 结构。只需声明所需的字符实体，例如：

```xml
<!ENTITY nbsp "&#xa0;">
```

<a id="index-1"></a>

<a id="xslt-last-modified"></a>

### xslt_last_modified

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_last_modified` `on` | `off`;   |
|--------------------------------------------------------------------------------------|--------------------------------------|
| 默认值                                                                                  | `xslt_last_modified off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location               |

在 XSLT 转换期间允许保留原始响应中的 `Last-Modified` 头字段，以便于响应缓存。

默认情况下，头字段被移除，因为响应的内容在转换期间被修改，可能包含动态生成的元素或与原始响应独立更改的部分。

<a id="index-2"></a>

<a id="xslt-param"></a>

### xslt_param

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_param` parameter value;   |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值                                                                                  | —                               |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

定义 XSLT 样式表的参数。值被视为 XPath 表达式。值可以包含变量。要将字符串值传递给样式表，可以使用 [xslt_string_param](#xslt-string-param) 指令。

可以有多个 `xslt_param` 指令。如果当前级别没有定义 `xslt_param` 和 [xslt_string_param](#xslt-string-param) 指令，则这些指令将从上一个配置级别继承。

<a id="index-3"></a>

<a id="xslt-string-param"></a>

### xslt_string_param

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_string_param` parameter value;   |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值                                                                                  | —                                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                 |

定义 XSLT 样式表的字符串参数。值中的 XPath 表达式不被解释。值可以包含变量。

可以有多个 `xslt_string_param` 指令。如果当前级别没有定义 [xslt_param](#xslt-param) 和 `xslt_string_param` 指令，则这些指令将从上一个配置级别继承。

<a id="index-4"></a>

<a id="xslt-stylesheet"></a>

### xslt_stylesheet

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_stylesheet` stylesheet [parameter=value ...];   |
|--------------------------------------------------------------------------------------|-------------------------------------------------------|
| 默认值                                                                                  | —                                                     |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                                              |

定义 XSLT 样式表及其可选参数。样式表在配置阶段编译。

参数可以单独指定，也可以使用 ":" 分隔符在一行中分组。如果参数包含 ":" 字符，应转义为 "%3A"。此外，libxslt 要求将包含非字母数字字符的参数用单引号或双引号括起来，例如：

```console
param1='http%3A//www.example.com':param2=value2
```

参数描述可以包含变量，例如，整个参数行可以从一个变量中取得：

```nginx
location / {
    xslt_stylesheet /site/xslt/one.xslt
                    $arg_xslt_params
                    param1='$value1':param2=value2
                    param3=value3;
}
```

可以指定多个样式表。它们将按指定的顺序依次应用。

<a id="index-5"></a>

<a id="xslt-types"></a>

### xslt_types

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `xslt_types` mime-type ...;   |
|--------------------------------------------------------------------------------------|-------------------------------|
| 默认值                                                                                  | `xslt_types text/xml;`        |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location        |

启用对指定 MIME 类型的响应进行转换，除了 `text/xml` 之外。特殊值 "\*" 匹配任何 MIME 类型。如果转换结果是 HTML 响应，则其 MIME 类型更改为 `text/html`。