# @aiot-toolkit/card-expression

> 快应用卡片表达式解析库

Latest version **1.0.17** (published 2025-12-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install @aiot-toolkit/card-expression
pnpm add @aiot-toolkit/card-expression
yarn add @aiot-toolkit/card-expression
bun add @aiot-toolkit/card-expression
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.17 |
| Published | 2025-12-25 |
| First published | 2024-09-24 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 60.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | yinhunfeixue, lewiscutey, yaotaiyang, xiaobin06, bluestoneq, susanpan, dongwa |

## Links

- npm: https://www.npmjs.com/package/@aiot-toolkit/card-expression
- npm.io page: https://npm.io/package/@aiot-toolkit/card-expression

## Dependencies (3)

- [@babel/types](https://npm.io/package/@babel/types.md) ^7.25.6
- [@babel/parser](https://npm.io/package/@babel/parser.md) ^7.25.6
- [@babel/generator](https://npm.io/package/@babel/generator.md) ^7.25.6

## Recent versions

- 1.0.17 (latest) — 2025-12-25
- 1.0.16 — 2025-12-23
- 1.0.15 — 2025-07-21
- 1.0.14 — 2025-07-11
- 1.0.13 — 2024-12-03
- 1.0.12 — 2024-12-02
- 1.0.11 — 2024-11-08
- 1.0.10 — 2024-11-07
- 1.0.9 — 2024-11-07
- 1.0.8 — 2024-11-01
- 1.0.7 — 2024-10-24
- 1.0.6 — 2024-09-29
- 1.0.5 — 2024-09-27
- 1.0.4 — 2024-09-27
- 1.0.3 — 2024-09-24
- … 3 more at https://npm.io/package/@aiot-toolkit/card-expression/versions

## README

# 快应用卡片表达式解析

用于

1. `JS表达式` 转换为 `快应用卡片表达式`
2. `模板表达式` 转换为 `快应用卡片表达式`

快应用卡片表达式是一种类似 `lisp的语法树表达式`

> 示例

| js 表达式        | 转换后                                              |
| ---------------- | --------------------------------------------------- |
| `a+123`          | `["+", ["$", "a"], 123]`                            |
| `!a`             | `["!", ["$", "a"]]`                                 |
| `a[1].x.y`       | `[".",[".", ["[]", ["$", "a"], 1], "x", "y"`        |
| `fun(a, b, 124)` | `["()", ["$", "fun"], ["$", "a"], ["$", "b"], 124]` |

| 模板表达式   | 转换后                                  |
| ------------ | --------------------------------------- |
| `a+b{{a+b}}` | `["+","a+b",["+",["$","a"],["$","b"]]]` |

## 快速上手

### 模板代码转换为 Card 代码

```js
import { templateValueToCardCode } from '@aiot-toolkit/card-expression';

const result = templateValueToCardCode('a+b{{a+b}}');
console.log(result); // ["+","a+b",["+",["$","a"],["$","b"]]]
```

### js 代码转为 Card 代码

```js
import jsToCardCode from '@aiot-toolkit/card-expression';

const result = jsToCardCode('a+b');
console.log(result); // '["+", ["$", "a"], ["$", "b"]]'
```

###

## 表达式

### 模板表达式

模板表达式是快应用使用的**字符串和 js 混合**的表达式，双大括号中的内容为 js，其
它为字符串

示例：`aaaa{{x+y}}bbbb` 等于 js 代码 `"aaaa" + (x + y) + "bbbb"`

### 支持的 js 表达式

快应用卡片支持的**js 表达式**如下。需要注意的是，各表达式之间**可递归使用**，例
如 `data[a+b]` `data.x + (a?1:2)`

| 表达式                                              | 源码                                         | 产物                                     | 示例                                                                              |
| --------------------------------------------------- | -------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------- |
| 字面量 <br/> literal                                | `value`                                      | `value`                                  | `123` --> `123`                                                                   |
| 标识符<br/> Identifier                              | `value`                                      | `["$", "value"]`                         | `a`-->`["$", "a"]`                                                                |
| 数组表达式<br/> ArrayExpression                     | `[value1, value2, value3]`                   | `["~", "value1", "value2", "value3"]`    | `[a, 1, 2]`-->`["~", ["$", "a"], 1, 2]`                                           |
| 一元表达式<br/> UnaryExpression                     | `operator value`                             | `["operator", value]`                    | `!a`-->`["!", ["$", "a"]]`                                                        |
| 二元表达式<br/> BinaryExpression                    | `value1 operator value1`                     | `["operator", value1, value2]`           | `a+1` --> `["+", ["$", "a"], 1]`                                                  |
| 属性表达式<br/> MemberExpression                    | 1. `value1[value2]` <br/> 2. `value1.value2` | `[".", value1, value2]`                  | `a[1]` --> `[".", ["$", "a"], 1]`                                                 |
| 逻辑表达式<br/> LogicalExpression                   | `value1 operator value1`                     | `["operator", value1, value2]`           | `a \|\| 1` --> `["\|\|", ["$", "a"], 1]`                                          |
| 条件表达式<br/> ConditionalExpression               | `condition? value1 : value2`                 | `["?:", "$condition" value1, value2]`    | `a?x:1` --> `["?:", ["$", "a"], ["$", "x"], 1]`                                   |
| 调用表达式<br/> CallExpression                      | `fun(arg1, args2, ...)`                      | `["()", ["$", "fun"], arg1, arg2, ...]`  | `fun(a, 123)` --> `["()", ["$", "fun"], ["$", "a"], 123]`                         |
| 无前缀调用表达式 <br/>(可自定义，默认["$t", "$tc"]) | `noPrefixFun(arg1)`                          | `["()", "noPrefixFun", arg1, arg2, ...]` | `$t("abc")` --> `["()", "$t", "abc"]`                                             |
| 模板字符串                                          | `str-${js}`                                  | 相当于**加法**二元表达式 `"str" + js`    |
| 对象表达式<br/> ObjectExpression                    | `{key1: value1, key2: value2}`               | `["{}", {key1: value1, key2: value2}`    | `{x:1, y:"2", z:a+b}`-->`['{}',{x: 1, y: '2', z: ['+', ['$', 'a'], ['$', 'b']]}]` |

## 特殊情况

### 函数调用去掉前缀

如果希望“函数调用的生成结果中，**函数名**去掉`'$'` 前缀”, 可使用
`noPrefixFunctionList` 参数.

```js
import { templateValueToCardCode } from '@aiot-toolkit/card-expression';

// 默认有 '$' 前缀
const result = templateValueToCardCode(`{{myfun("hello", a)}}`);
console.log(result); // '['()', ['$', 'myfun'], 'hello', ['$', 'a']]'

// 去掉 'myfun' 的前缀
const result = templateValueToCardCode(`{{myfun("hello", a)}}`, {
  noPrefixFunctionList: ['myfun'],
});
console.log(result); // '['()', 'myfun', 'hello', ['$', 'a']]'
```

**默认值：['$t', '$tc']**

### 属性表达式合并到函数的第 1 个参数

如果期望“属性表达式的属性名合并到函数的第 1 个参数”，可使用
`functionsForMemberNameToParam`参数

```js
const code = `myfun("hello", a)[1]`;
// 普通函数 + 属性表达式
const result = jsToCardCode(code);
console.log(result); // "["[]",["()","myfun","hello",["$","a"]],1]"

// 属性名合并到函数的第 1 个参数
const result = jsToCardCode(item.source, {
  functionsForMemberNameToParam: ['myfun'],
});
console.log(result); // "["()","myfun","hello.1",["$","a"]]"
```

**默认值：['$t', '$tc']**

## 转换参数

```js
jsToCardCode(code, { noPrefixFunctionList: [] });
templateValueToCardCode(code, { noPrefixFunctionList: [] });
```

| 参数名                        | 类型       | 默认值          | 说明                                          |
| ----------------------------- | ---------- | --------------- | --------------------------------------------- |
| noPrefixFunctionList          | `string[]` | `['$t', '$tc']` | 不需要添加 `$` 前缀的函数名列表               |
| functionsForMemberNameToParam | `string[]` | `['$t', '$tc']` | 属性表达式合并到函数的第 1 个参数的函数名列表 |

---
_Source: https://npm.io/package/@aiot-toolkit/card-expression · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._