在 变量 之后放一个 | 管道符号即可应用过滤器。过滤器可以链式使用，按从左到右的顺序执行。例如：

Template

{{ title | h2 | upper }}

Output

## THE MACHINE STOPS

只有已注册的过滤器可用。未知的名称和无效的参数会作为 validate() 与 render() 返回的诊断信息出现。

格式化 Markdown

Markdown 过滤器能在不把分隔符写进模板的前提下添加常用语法。

{{ title | h1 }}
{{ summary | italic }}
{{ source | code:"typescript" }}
{{ expression | math }}
{{ footer | hr:before }}
{{ literal_text | escape_md }}
{{ attachment | embed }}

Markdown 格式化过滤器能识别有类型的和序列化后的数组与对象，并递归应用到其中的字符串取值。对象的键和非字符串取值保持不变，因此结果可以继续传给 join 这样的集合过滤器。

{{ tags | bold | join:", " }}
{{ json_text | italic | join:", " }}

内置过滤器

用 ⌘K 搜索过滤器，可按名称、别名、类别或行为查找。

格式化

创建链接、callout、列表、表格及其他 Markdown 结构。

• blockquote：为每一行加上 Markdown 引用块前缀。
• bold：用 Markdown 粗体标记包裹文本。
• callout：创建 callout。
• code：格式化行内代码或围栏代码块。
• code_block：创建围栏代码块。
• comment：用注释标记包裹文本。
• embed：创建嵌入的 wiki 引用。
• escape_md：转义 Markdown 标点，使文本按字面渲染。
• footnote：把数组或对象转换为 Markdown 脚注定义。
• fragment_link：为高亮添加带文本片段锚点的来源 URL。
• h1：创建一级标题。
• h2：创建二级标题。
• h3：创建三级标题。
• h4：创建四级标题。
• h5：创建五级标题。
• h6：创建六级标题。
• hard_break：把单个换行转换为 Markdown 硬换行。
• highlight：用高亮标记包裹文本。
• hr：在文本前后放置水平分隔线。
• image：从 URL、数组或对象创建 Markdown 图片语法。
• italic：用 Markdown 斜体标记包裹文本。
• link：从 URL、数组或对象创建 Markdown 链接。
• list：把取值或数组转换为 Markdown 列表。
• math：格式化行内公式或公式块。
• math_block：创建块级公式表达式。
• strike：用 Markdown 删除线标记包裹文本。
• table：把数组或对象转换为紧凑的 Markdown 表格。
• table_pretty：把数组或对象转换为带对齐空格的 Markdown 表格。
• wikilink：从字符串、数组或对象创建 wikilink。
• yaml：把取值序列化为 YAML。
• yaml_property：把完整的 YAML 属性序列化。

文本

规范化大小写、间距、文件名和编码文本。

• camel：把文本转换为 camelCase。
• capitalize：把首字符转为大写，其余转为小写。
• decode_uri：解码百分号编码的 URI 文本。
• encode_uri：把文本编码为可用作 URI 组件的形式。
• indent：用空格缩进每个非空行。
• kebab：把文本转换为 kebab-case。
• lower：把文本转换为小写。
• pascal：把文本转换为 PascalCase。
• replace：替换一个或多个字符串或正则表达式。
• safe_name：移除文件名中不安全的字符。
• snake：把文本转换为 snake_case。
• title：把文本转换为 Title Case。
• trim：移除取值两端的空白。
• truncate：把文本截断到字符数上限。
• truncatewords：把文本截断到词数上限。
• uncamel：把 camelCase 或 PascalCase 转换为带空格的小写文本。
• unescape：把转义的引号和换行转换为字面字符。
• upper：把文本转换为大写。

日期

解析、调整和格式化日期或时长。

• date：格式化日期。
• date_modify：加上或减去一个日期间隔。
• duration：格式化秒数或 ISO 8601 时长。

数字

计算、取整和格式化数字取值。

• calc：对数字应用简单的算术运算。
• number_format：添加千位分隔符和可选的小数位。
• round：把数字舍入到可选的小数位数。

集合

选取、重塑、合并和渲染数组与对象。

• compact：从集合中移除 null 和空字符串取值。
• first：返回数组中的第一个条目。
• join：用可选的分隔符连接数组条目。
• last：返回数组中的最后一个条目。
• length：统计字符串字符数、数组条目数或对象键数。
• map：从每个数组条目中选取一个属性，或用表达式映射条目。
• merge：把一个或多个取值追加到数组。
• nth：用 nth 模式语法从数组中选取位置。
• object：把对象转换为键、取值或键值对。
• parse_json：把 JSON 文本解析为有类型的模板取值。
• reverse：反转字符串、数组或对象条目的顺序。
• slice：提取字符串或数组的一部分。
• sort：按取值或对象属性对数组排序。
• split：把字符串拆分为 JSON 数组。
• sum：对数组中的数字取值或对象中的数字属性求和。
• template：用一个小型 ${property} 模板渲染对象或每个数组条目。
• unique：从数组或对象中移除重复取值。
• where：保留属性与某个取值精确匹配的数组条目。

HTML 清理

在清理标记的同时保留 Markdown 工作流所需的片段。

• remove_attr：从 HTML 标签中移除指定的属性。
• remove_tags：移除指定的 HTML 标签但保留其内容。
• replace_tags：重命名指定的 HTML 标签并保留内容。
• strip_attr：移除除可选允许清单之外的所有 HTML 属性。
• strip_md：移除 Markdown 格式但保留可读文本。
• strip_tags：移除除可选允许清单之外的所有 HTML 标签。

HTML 解析

依赖 DOM 的过滤器，从 knap/html 单独导出。

• html_to_json：把 HTML 片段转换为结构化的 JSON 树。
• remove_html：移除指定的 HTML 元素及其内容。

HTML 过滤器

html_to_json 和 remove_html 需要浏览器兼容的 DOM 全局对象，因此从 knap/html 单独导出。

engine.ts

import { createEngine, standardFilters } from 'knap';
import { htmlFilters } from 'knap/html';

const engine = createEngine({
  filters: { ...standardFilters, ...htmlFilters },
});

注册自定义过滤器

自定义过滤器可以是同步的，也可以是异步的。当编辑器需要在渲染前校验参数时，为过滤器附加元数据。

filters.ts

import { createEngine, standardFilters, type TemplateFilter } from 'knap';

const surround: TemplateFilter = (value, param = '') => {
  const marker = param.replace(/^(['"])(.*)\1$/s, '$2');
  return marker + value + marker;
};

surround.metadata = { example: 'surround:"**"' };

const engine = createEngine({
  filters: { ...standardFilters, surround },
});

当过滤器保留回退值、但希望宿主给出非致命诊断信息时，可以调用 context.reportWarning()。

为兼容起见，过滤器接收的第一个参数是序列化后的字符串。当自定义过滤器需要区分数组/对象与包含 JSON 的文本时，可以通过 context.rawValue 取得原始的有类型取值。求值后的参数可以通过 context.rawArguments 取得；既有的序列化参数字符串保持不变。