如何创建自定义Stencil过滤器和标签：扩展模板功能
项目地址: https://gitcode.com/gh_mirrors/ste/Stencil Stencil是Swift中一款简单而强大的模板语言，它允许开发者通过自定义过滤器和标签来扩展模板功能，满足特定的业务需求。本文将详细介绍如何为Stencil创建自定义过滤器和标签，帮助你轻松扩展模板功能。
一、了解Stencil过滤器和标签
Stencil提供了丰富的内置过滤器和标签，如capitalize、uppercase、if、for等。这些功能可以通过Sources/Stencil/Extension.swift文件查看，其中定义了Stencil的核心扩展机制。
1.1 过滤器的作用
过滤器用于对模板中的变量进行处理和转换，例如将文本转换为大写、拼接字符串等。Stencil的内置过滤器包括：
default：提供默认值capitalize：首字母大写uppercase：全部大写lowercase：全部小写join：拼接数组元素
1.2 标签的作用
标签用于控制模板的逻辑流程，如条件判断、循环、包含其他模板等。Stencil的内置标签包括：
if/ifnot：条件判断for：循环include：包含其他模板block/extends：模板继承
二、创建自定义过滤器
2.1 过滤器的基本结构
自定义过滤器是一个接受输入值并返回处理结果的函数。通过registerFilter方法注册到Stencil中。过滤器可以接受不同数量的参数，主要有以下几种形式：
// 无参数过滤器
public func registerFilter(_ name: String, filter: @escaping (Any?) throws -> Any?)
// 带参数过滤器
public func registerFilter(_ name: String, filter: @escaping (Any?, [Any?]) throws -> Any?)
// 带上下文过滤器
public func registerFilter(_ name: String, filter: @escaping (Any?, [Any?], Context) throws -> Any?)
2.2 实现一个简单的过滤器
以下是一个将字符串反转的过滤器示例：
import Stencil
let ext = Extension()
// 注册一个名为"reverse"的过滤器
ext.registerFilter("reverse") { (value: Any?) throws -> Any? in
guard let input = value as? String else {
return value
}
return String(input.reversed())
}
// 创建环境并应用扩展
let environment = Environment(extensions: [ext])
在模板中使用这个过滤器：
{{ "Hello Stencil"|reverse }} // 输出：licnetS olleH
2.3 带参数的过滤器示例
创建一个可以指定重复次数的过滤器：
ext.registerFilter("repeat") { (value: Any?, arguments: [Any?]) throws -> Any? in
guard let input = value as? String,
let count = arguments.first as? Int,
count > 0 else {
return value
}
return String(repeating: input, count: count)
}
模板中使用：
{{ "Hi "|repeat:3 }} // 输出：Hi Hi Hi
三、创建自定义标签
3.1 标签的基本结构
自定义标签通过registerTag方法注册，需要实现一个解析器函数，该函数接收TokenParser和Token参数，并返回一个NodeType对象。
public func registerTag(_ name: String, parser: @escaping (TokenParser, Token) throws -> NodeType)
3.2 实现一个简单的标签
以下是一个显示当前时间的自定义标签示例：
import Stencil
class CurrentTimeNode: NodeType {
func render(_ context: Context) throws -> String {
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
return formatter.string(from: Date())
}
}
let ext = Extension()
ext.registerTag("current_time") { (parser, token) throws -> NodeType in
return CurrentTimeNode()
}
let environment = Environment(extensions: [ext])
在模板中使用：
{% current_time %} // 输出：2023-10-01 12:34:56
3.3 带参数的标签示例
创建一个可以指定日期格式的时间标签：
class FormattedTimeNode: NodeType {
let format: String
init(format: String) {
self.format = format
}
func render(_ context: Context) throws -> String {
let formatter = DateFormatter()
formatter.dateFormat = format
return formatter.string(from: Date())
}
}
ext.registerTag("time") { (parser, token) throws -> NodeType in
let components = token.components()
guard components.count == 2 else {
throw TemplateSyntaxError("Invalid syntax for time tag. Usage: {% time 'format' %}")
}
let format = components[1].trimmingCharacters(in: .quotes)
return FormattedTimeNode(format: format)
}
模板中使用：
{% time 'MM/dd/yyyy' %} // 输出：10/01/2023
四、在项目中集成自定义扩展
4.1 创建扩展文件
建议将自定义过滤器和标签组织在单独的文件中，例如创建CustomExtensions.swift：
import Stencil
public extension Extension {
static var custom: Extension {
let ext = Extension()
// 注册自定义过滤器
ext.registerFilter("reverse") { ... }
ext.registerFilter("repeat") { ... }
// 注册自定义标签
ext.registerTag("current_time") { ... }
ext.registerTag("time") { ... }
return ext
}
}
4.2 使用扩展
在创建Stencil环境时，将自定义扩展添加进去：
let environment = Environment(
loader: FileSystemLoader(paths: ["templates"]),
extensions: [.custom]
)
let template = try environment.loadTemplate(name: "index.stencil")
let result = try template.render(["name": "Stencil"])
print(result)
五、测试自定义扩展
为了确保自定义过滤器和标签的正确性，建议编写单元测试。可以参考Tests/StencilTests/FilterSpec.swift和Tests/StencilTests/NodeSpec.swift中的测试方法。
示例测试代码：
import XCTest
@testable import Stencil
class CustomExtensionsTests: XCTestCase {
func testReverseFilter() {
let ext = Extension.custom
let environment = Environment(extensions: [ext])
let template = try! environment.loadTemplate(string: "{{ 'hello'|reverse }}")
let result = try! template.render([:])
XCTAssertEqual(result, "olleh")
}
}
六、总结
通过自定义过滤器和标签，你可以极大地扩展Stencil的功能，使其更符合项目需求。无论是简单的数据转换还是复杂的逻辑控制，Stencil的扩展机制都能满足你的需求。开始动手创建自己的扩展，让模板处理变得更加高效和灵活吧！
更多关于Stencil的使用方法，可以参考项目中的docs/目录，其中包含了详细的官方文档。如果你想查看Stencil的核心实现，可以阅读Sources/Stencil/目录下的源代码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
