当前位置：首页 > news >正文

如何为Stencil开发自定义扩展插件：完整指南

news 2026/4/16 9:27:50

如何为Stencil开发自定义扩展插件：完整指南

【免费下载链接】StencilStencil is a simple and powerful template language for Swift.项目地址: https://gitcode.com/gh_mirrors/ste/Stencil

Stencil是Swift语言中一款简单而强大的模板语言，通过开发自定义扩展插件，你可以轻松扩展其功能，满足特定项目需求。本教程将带你了解Stencil扩展开发的核心步骤，从创建扩展结构到注册自定义过滤器，让你快速掌握扩展开发技巧。

了解Stencil扩展基础

Stencil的扩展系统基于Extension类实现，位于项目的Sources/Stencil/Extension.swift文件中。这个类提供了注册过滤器、标签和函数的核心方法，是所有自定义扩展的基础。

扩展插件本质上是通过Extension类向Stencil环境添加新功能。你可以创建独立的扩展模块，也可以直接在现有代码中扩展Stencil功能。

搭建扩展开发环境

1. 准备开发环境

确保你的开发环境满足以下要求：

Swift 5.0+ 开发环境
Stencil源码（可通过git clone https://gitcode.com/gh_mirrors/ste/Stencil获取）
Xcode或其他Swift兼容的IDE

2. 创建扩展文件结构

在项目中创建扩展相关文件，建议的目录结构如下：

Stencil/ └── Sources/ └── Stencil/ ├── Extensions/ # 存放自定义扩展 │ ├── MyCustomFilter.swift │ └── MyCustomTag.swift └── Extension.swift # 核心扩展类

开发自定义过滤器

过滤器是Stencil扩展最常用的功能，允许你在模板中转换变量值。以下是创建自定义过滤器的完整步骤：

1. 创建过滤器函数

在新的Swift文件中定义过滤器逻辑。例如，创建一个将文本转换为大写的过滤器：

import Stencil public extension Extension { func addCustomFilters() { registerFilter("uppercase") { (value: Any?) throws -> Any? in guard let string = value as? String else { return value } return string.uppercased() } } }

2. 理解过滤器注册方法

Stencil提供了多种过滤器注册方法，位于Sources/Stencil/Extension.swift：

基本过滤器：registerFilter(_ name: String, filter: @escaping (Any?) throws -> Any?)
带参数过滤器：registerFilter(_ name: String, filter: @escaping (Any?, [Any?]) throws -> Any?)
带上下文过滤器：registerFilter(_ name: String, filter: @escaping (Any?, [Any?], Context) throws -> Any?)
布尔型过滤器：registerFilter(name: String, negativeFilterName: String, filter: @escaping (Any?) throws -> Bool?)

3. 在模板中使用自定义过滤器

注册过滤器后，即可在模板中使用：

{{ user.name | uppercase }}

开发自定义标签

除了过滤器，你还可以创建自定义标签来扩展模板语法。以下是开发{% current_time %}标签的示例：

1. 创建标签节点

首先创建标签对应的节点类，处理标签逻辑：

import Stencil class CurrentTimeNode: NodeType { func render(_ context: Context) throws -> String { let formatter = DateFormatter() formatter.dateStyle = .medium return formatter.string(from: Date()) } }

2. 创建标签解析器

然后创建标签解析器，用于在模板解析时识别和处理自定义标签：

public extension Extension { func addCurrentTimeTag() { registerTag("current_time") { parser, token in return CurrentTimeNode() } } }

注册扩展到Stencil环境

创建扩展后，需要将其注册到Stencil环境中才能生效：

import Stencil let environment = Environment(extensions: [ Extension() .addCustomFilters() .addCurrentTimeTag() ]) // 加载并渲染模板 let template = try environment.loadTemplate(name: "mytemplate.stencil") let result = try template.render(["name": "Stencil"])

测试自定义扩展

为确保扩展功能正常工作，建议编写单元测试。Stencil的测试文件位于Tests/StencilTests/目录，你可以参考现有测试用例结构添加自己的测试。

例如，为 uppercase 过滤器添加测试：

import XCTest @testable import Stencil class CustomFiltersTests: XCTestCase { func testUppercaseFilter() throws { let environment = Environment(extensions: [Extension().addCustomFilters()]) let template = try environment.loadTemplate(string: "{{ 'hello' | uppercase }}") let result = try template.render([]) XCTAssertEqual(result, "HELLO") } }