表达式参考 · 文档

表达式是 JavaScript 的一个安全子集。本页列出了表达式可以使用的全部内容。编辑器的自动补全也基于同一套定义构建，因此这份列表始终完整。

语法

// Arithmetic       + - * / % **
// Comparison       == != === !== < > <= >=
// Logic            && || ! ?? and  cond ? a : b
// Access           a.b  a[b]  a?.b
// Literals         'text'  `Hi ${user.name}`  [1, ...list]  { a: 1, ...obj }
// Lambdas          items.filter(x => x.price > 10)   (as call arguments only)

作用域

名称	内容	可用范围
`vars`	页面和站点变量	任何地方
`queries`	每个查询的 `{ data, loading, error, updatedAt }`	页面
`item`、`index`、`parent`	当前行、它的位置、外层的行	集合列表、模板页面
`page`	`path`、`params`、`query`	页面
`site`	`name`、`locale`	任何地方
`user`	访客，未登录时为 `{ isLoggedIn: false }`	任何地方
`steps`、`input`、`event`、`error`	步骤结果、工作流输入、触发事件、捕获的错误	工作流
`row`	正在读取或写入的行	行规则
`fn`	下面的内置函数和你的公式	任何地方

函数

以 fn.name(…) 的形式调用内置函数。标有 ? 的参数是可选的。键参数接受字段路径（'author.name'）或 lambda。

格式化

函数	返回值	说明
`fn.formatNumber(value, decimals?, locale?)`	`string`	Locale-formatted number with grouping. decimals is a fixed number of decimals or Intl.NumberFormat options ({ notation: "compact" }, { style: "percent" }). Empty string for null/undefined. `fn.formatNumber(1234.5, 2, 'en-US') // '1,234.50'`
`fn.formatCurrency(value, currency?, locale?, decimals?)`	`string`	Locale-formatted money amount (currency: ISO 4217 code, default USD). `fn.formatCurrency(item.price, 'EUR', 'de-DE') // '12,50 €'`
`fn.formatDate(date, format?, locale?, timeZone?)`	`string`	Locale-formatted date. Formats: short, medium (default), long, full, datetime, time, iso, isoDateTime, or Intl.DateTimeFormat options. Time zone defaults to UTC. `fn.formatDate(item.publishedAt, 'long', 'en-GB') // '1 March 2026'`

日期

函数	返回值	说明
`fn.now()`	`date`	Current time as an ISO string. `fn.now()`
`fn.dateAdd(date, amount, unit)`	`date`	Adds an amount of a unit (year, quarter, month, week, day, hour, minute, second). UTC; month math clamps to the last day. `fn.dateAdd(fn.now(), 7, 'day')`
`fn.dateDiff(from, to, unit?)`	`number`	Whole units from from to to (default day; negative when to is earlier). `fn.dateDiff(item.publishedAt, fn.now(), 'day')`
`fn.startOf(date, unit)`	`date`	Start of the unit containing the date (UTC; weeks start on Monday). `fn.startOf(fn.now(), 'month')`

文本

函数	返回值	说明
`fn.truncate(text, length, suffix?)`	`string`	Cuts to length characters (suffix included, default …) when longer. `fn.truncate(item.excerpt, 120)`
`fn.slugify(text)`	`string`	Kebab-case ASCII slug (Café Ñandú → cafe-nandu).

数组

函数	返回值	说明
`fn.length(value)`	`number`	Items in an array, characters in a string, keys in an object; 0 otherwise.
`fn.sum(items, key?)`	`number`	Sum of the numeric values (non-numbers skipped). `fn.sum(queries.cart.data, 'price')`
`fn.avg(items, key?)`	`number`	Average of the numeric values; null when there are none.
`fn.uniq(items, key?)`	`array`	Items with duplicates removed (by deep value, or by key).
`fn.groupBy(items, key)`	`object`	Object of arrays keyed by the key value. `fn.groupBy(queries.products.data, 'category')`
`fn.sortBy(items, key?, direction?)`	`array`	Sorted copy (asc default or desc): numbers numerically, strings by code point, null last. `fn.sortBy(items, 'price', 'desc')`
`fn.range(start, end?, step?)`	`array`	Numbers from start (inclusive) to end (exclusive); fn.range(3) → [0, 1, 2].

数学

函数	返回值	说明
`fn.min(...values)`	`any`	Smallest value: fn.min(1, 2), fn.min(items, "price").
`fn.max(...values)`	`any`	Largest value: fn.max(1, 2), fn.max(items, "price").
`fn.round(value, decimals?)`	`number`	Rounds half away from zero to decimals places (default 0).

对象

函数	返回值	说明
`fn.keys(object)`	`array`	Own keys.
`fn.values(object)`	`array`	Own values.
`fn.entries(object)`	`array`	[key, value] pairs.

逻辑

函数	返回值	说明
`fn.default(value, fallback)`	`any`	The fallback when the value is null, undefined or "". `fn.default(item.subtitle, 'Untitled')`
`fn.toNumber(value, fallback?)`	`number`	Number from a number or numeric string; the fallback (default null) otherwise.

JSON

函数	返回值	说明
`fn.jsonStringify(value, indent?)`	`string`	JSON text (forbidden keys dropped; oversized values are errors).
`fn.jsonParse(text, fallback?)`	`any`	Parses JSON; the fallback (default null) when invalid. __proto__/constructor keys are dropped.

方法

值还拥有常见的 JavaScript 方法。方法绝不会修改原值：sort 和 reverse 返回副本。

文本方法

方法	返回值	说明
`.length`	`number`	Number of UTF-16 code units.
`.toUpperCase()`	`string`	Upper-case copy.
`.toLowerCase()`	`string`	Lower-case copy.
`.trim()`	`string`	Removes leading and trailing whitespace.
`.trimStart()`	`string`	Removes leading whitespace.
`.trimEnd()`	`string`	Removes trailing whitespace.
`.startsWith(search, position?)`	`boolean`	True when the string starts with search.
`.endsWith(search, length?)`	`boolean`	True when the string ends with search.
`.includes(search)`	`boolean`	True when search occurs in the string.
`.indexOf(search, from?)`	`number`	First index of search, or -1.
`.lastIndexOf(search)`	`number`	Last index of search, or -1.
`.slice(start?, end?)`	`string`	Part of the string (negative indexes count from the end).
`.substring(start, end?)`	`string`	Part of the string between two indexes.
`.split(separator, limit?)`	`array`	Splits on a literal separator.
`.replace(search, replacement)`	`string`	Replaces the first literal occurrence.
`.replaceAll(search, replacement)`	`string`	Replaces every literal occurrence.
`.padStart(length, fill?)`	`string`	Pads the start to length.
`.padEnd(length, fill?)`	`string`	Pads the end to length.
`.repeat(count)`	`string`	The string repeated count times.
`.charAt(index)`	`string`	Character at an index.
`.at(index)`	`string`	Character at an index (negative counts from the end).
`.concat(...parts)`	`string`	Appends the parts.
`.localeCompare(other, locale?)`	`number`	Locale-aware comparison (-1, 0, 1).
`.toString()`	`string`	The string itself.

数组方法

方法	返回值	说明
`.length`	`number`	Number of items.
`.map(callback)`	`array`	New array with the callback result for each item: (item, index) => ….
`.filter(callback)`	`array`	Items for which the callback is truthy.
`.find(callback)`	`any`	First item for which the callback is truthy.
`.findIndex(callback)`	`number`	Index of the first match, or -1.
`.findLast(callback)`	`any`	Last item for which the callback is truthy.
`.findLastIndex(callback)`	`number`	Index of the last match, or -1.
`.some(callback)`	`boolean`	True when the callback is truthy for any item.
`.every(callback)`	`boolean`	True when the callback is truthy for every item.
`.reduce(callback, initial?)`	`any`	Folds the items into one value: (acc, item, index) => ….
`.flatMap(callback)`	`array`	Maps, then flattens one level.
`.includes(value)`	`boolean`	True when the array contains the value (===).
`.indexOf(value)`	`number`	First index of the value, or -1.
`.lastIndexOf(value)`	`number`	Last index of the value, or -1.
`.join(separator?)`	`string`	Joins the items into a string (default ,).
`.slice(start?, end?)`	`array`	Part of the array (negative indexes count from the end).
`.concat(...values)`	`array`	New array with the values appended (arrays flattened one level).
`.at(index)`	`any`	Item at an index (negative counts from the end).
`.flat(depth?)`	`array`	Flattens nested arrays (default depth 1, max 10).
`.reverse()`	`array`	Reversed copy (the original never changes).
`.sort(compare?)`	`array`	Sorted copy (the original never changes). Without a comparator, sorts as strings like JS.

数字方法

方法	返回值	说明
`.toFixed(digits?)`	`string`	Fixed-point notation (0–100 digits).
`.toPrecision(precision)`	`string`	Significant-digit notation (1–100).
`.toString(radix?)`	`string`	Text form, optionally in base 2–36.
`.toLocaleString(locale?)`	`string`	Locale-formatted number (default: site locale).
`.toString()`	`string`	"true" or "false".