Apache FreeMarker™ 技术文档

2024-12-23 05:16:03作者：苗圣禹Peter

Apache Freemarker: 是一个开源的模板引擎，用于生成HTML、XML和其他文本格式的文档。适合Web应用开发者、Java开发者和其他后端开发者。特点包括提供简单易用的模板语法和API、支持多种数据源和格式、支持多种模板引擎扩展、易于集成到现有的应用程序和系统中以及提供丰富的文档和社区支持。

项目地址：https://gitcode.com/gh_mirrors/fr/freemarker

1. 安装指南

使用 Maven 安装

如果你使用 Maven 进行项目管理，只需在 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker-gae</artifactId>
    <version>{version}</version>
</dependency>

注意：确保没有其他依赖项引入旧版本的 freemarker（groupId 为 freemarker 而不是 org.freemarker），否则可能会导致运行时行为不可预测。

手动安装

如果不使用 Maven，可以直接将 freemarker.jar 文件复制到你的 Java 应用程序的 ClassLoader 可以找到的位置。例如，如果你在 Web 应用程序中使用 FreeMarker，可以将 freemarker.jar 放入 WEB-INF/lib 目录。

FreeMarker 没有强制依赖项，但有一些可选依赖项。通常情况下，你不需要处理这些依赖项，除非你使用了某些需要特定库的特性。

升级到 OpenJDK 9 或更高版本

如果你升级到 OpenJDK 9 或更高版本，并且你在模板中使用 XPath 查询，你需要添加 Apache Xalan 作为依赖项，因为 freemarker.ext.dom 无法再使用 OpenJDK 内置的 XPath 支持。

2. 项目的使用说明

什么是 Apache FreeMarker™？

Apache FreeMarker™ 是一个“模板引擎”，它是一个通用的工具，用于基于模板生成文本输出（从 HTML 到自动生成的源代码）。它是一个 Java 包，供 Java 程序员使用的类库。它本身并不是一个面向最终用户的应用程序，而是程序员可以嵌入到其产品中的工具。FreeMarker 的设计目的是为基于 MVC（模型视图控制器）模式的 servlet 应用程序生成 HTML Web 页面。

使用场景

FreeMarker 通常用于以下场景：

生成动态 HTML 页面。
生成电子邮件模板。
生成源代码、配置文件等。

3. 项目 API 使用文档

基本用法

FreeMarker 的核心 API 主要包括 Configuration 和 Template 类。以下是一个简单的示例，展示如何使用 FreeMarker 生成 HTML 输出：

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateExceptionHandler;

import java.io.File;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.util.HashMap;
import java.util.Map;

public class FreeMarkerExample {
    public static void main(String[] args) throws Exception {
        // 创建配置实例
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);

        // 指定模板文件的位置
        cfg.setDirectoryForTemplateLoading(new File("templates/"));

        // 设置异常处理方式
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);

        // 获取模板
        Template temp = cfg.getTemplate("example.ftl");

        // 创建数据模型
        Map<String, Object> root = new HashMap<>();
        root.put("message", "Hello, FreeMarker!");

        // 合并模板和数据模型
        Writer out = new OutputStreamWriter(System.out);
        temp.process(root, out);
    }
}

模板示例

以下是一个简单的 FreeMarker 模板文件 example.ftl：

<!DOCTYPE html>
<html>
<head>
    <title>FreeMarker Example</title>
</head>
<body>
    <h1>${message}</h1>
</body>
</html>

常用 API

Configuration：用于配置 FreeMarker 的全局设置。
Template：表示一个模板文件。
TemplateExceptionHandler：用于处理模板解析和执行过程中的异常。

4. 项目安装方式

通过 Maven 安装

如前所述，通过在 pom.xml 中添加依赖项来安装 FreeMarker。

手动安装

将 freemarker.jar 文件复制到你的项目中，并确保它位于 ClassLoader 可以找到的路径中。

构建 FreeMarker

如果你需要从源码构建 FreeMarker，可以按照以下步骤进行：

下载源码发布包或从源码仓库中检出 FreeMarker。
确保你安装了 JDK 8、JDK 16 和 JDK 17（仅用于某些测试）。
在项目根目录下运行 ./gradlew jar（Windows 上运行 gradlew.bat jar）来构建 freemarker.jar。

IDE 设置

IntelliJ IDEA

打开项目：选择 settings.gradle.kts 文件。
配置 Gradle：确保 Gradle JVM 设置为 JDK 17 或更高版本。
导入代码风格和检查配置。

Eclipse

将项目作为 Gradle 项目导入。
配置 Java 编译器和代码格式化器。

通过以上步骤，你可以顺利安装、使用和构建 Apache FreeMarker™ 项目。

freemarker

项目地址：https://gitcode.com/gh_mirrors/fr/freemarker

登录后查看全文

项目优选

收起

docs

OpenHarmony documentation | OpenHarmony开发者文档

Ascend Extension for PyTorch

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！

1.03 K

448

openGauss-server

openGauss kernel ~ openGauss is an open source relational database management system

一个用于服务器应用开发的综合工具库。 - 零配置文件 - 环境变量和命令行参数配置 - 约定优于配置 - 深刻利用仓颉语言特性 - 只需要开发动态链接库，fboot负责加载、初始化并运行。

Cangjie

280