# East Asian Full-Width Formula Input

## Content

SpreadJS supports formula input with East Asian full-width characters. When users enter or paste formulas that contain supported full-width formula characters, SpreadJS normalizes them to the corresponding half-width formula characters where applicable.
This behavior helps users enter formulas with Japanese or Chinese input methods while preserving valid SpreadJS formula syntax.
For example:

| Input formula | Saved formula |
| ------------- | ------------- |
| `＝SUM（1，2）` | `=SUM(1,2)` |
| `=Ａ１` | `=A1` |
| `=Sheet2！A1` | `=Sheet2!A1` |

## Supported Input Scenarios

Formula character normalization applies to user input scenarios, including:

* Formula input in cells
* Formula input by copy and paste
* Formula input in the FormulaTextBox
* Formula input in Designer conditional formatting rules
* Formula input in Designer data validation rules
* Formula input in Designer range selectors

Formula input can also start with full-width `＝`, `＋`, or `－` where formula entry is supported.

>type=note
> **Note:** Formula character normalization applies to user input. Formula strings set through APIs are not normalized automatically.

## Normalized Formula Characters

SpreadJS normalizes common full-width formula characters to their half-width equivalents.
The following examples show typical conversions:

| Full-width input | Normalized character | Example |
| ---------------- | -------------------- | ------- |
| `＝` | `=` | `＝SUM(1,2)` becomes `=SUM(1,2)` |
| `（` `）` | `(` `)` | `=SUM（A1,A2）` becomes `=SUM(A1,A2)` |
| `，` | `,` | `=SUM(1，2，3)` becomes `=SUM(1,2,3)` |
| `：` | `:` | `=SUM(A1：A2)` becomes `=SUM(A1:A2)` |
| `＋` `－` `＊` `／` | `+` `-` `*` `/` | `=２＊３` becomes `=2*3` |
| `＾` | `^` | `=２＾３` becomes `=2^3` |
| `％` | `%` | `=50％` becomes `=50%` |
| `＆` | `&` | `=＂A＂＆＂B＂` becomes `="A"&"B"` |
| `＄` | `$` | `=＄Ａ＄１` becomes `=$A$1` |
| `！` | `!` | `=Sheet2！A1` becomes `=Sheet2!A1` |
| `＞` `＜` | `>` `<` | `=２＞１` becomes `=2>1` |
| `｛` `｝` | `{` `}` | `=SUM(｛1，2；3，4｝)` becomes `=SUM({1,2;3,4})` |
| `；` | `;` | `=SUM({1；2})` becomes `=SUM({1;2})` |
| `＃` | `#` | `=A1＃` becomes `=A1#` |
| `＠` | `@` | `=＠A1:A3` becomes `=@A1:A3` |
| `［` `］` | `[` `]` | `=R［1］C［1］` becomes `=R[1]C[1]` |

SpreadJS also normalizes full-width letters and numbers when they are used in supported formula syntax, such as cell references and built-in function names.
For example:

| Input formula | Saved formula |
| ------------- | ------------- |
| `=Ａ２` | `=A2` |
| `=Ｒ２Ｃ２` | `=R2C2` |
| `=ＳＵＭ（Ａ１：Ａ２）` | `=SUM(A1:A2)` |

Some East Asian punctuation characters that are commonly used as quotes, periods, brackets, or comparison symbols are also normalized where applicable. For example, smart quotes such as `“ ”` can be normalized to formula double quotes.

## Function Names

Built-in function names entered with full-width letters are normalized to half-width letters.
For example:

```text
=ＳＵＭ(A1)
```

is saved as:

```auto
=SUM(A1)
```

For custom functions, the behavior depends on how the custom function is defined:

* If a half-width custom function is registered globally, full-width input can be normalized to match it.
* Custom functions with full-width names retain their original names and are not converted.

## Cell References and Ranges

Cell references can be normalized when users enter formulas with full-width letters or numbers.
For example:

| Input formula | Saved formula |
| ------------- | ------------- |
| `=Ａ２` | `=A2` |
| `=Ｒ２Ｃ２` | `=R2C2` |

Range-related formula characters can also be normalized.
For example:

| Input formula | Saved formula |
| ------------- | ------------- |
| `=SUM(A1：A2)` | `=SUM(A1:A2)` |
| `=Ａ１：Ａ１０` | `=A1:A10` |

## Custom Names and Structured References

Custom names are not normalized automatically. If a workbook contains a custom name, users should enter the exact custom name or select it from the autocomplete list.
For example, if a custom name is defined with full-width characters, SpreadJS preserves the full-width name.
Structured references also require exact table and column names. SpreadJS does not normalize table names or column names inside structured references.
For example, if the table name is `SalesTable`, the following formula does not match the table name:

```auto
=SUM(ＳａｌｅｓＴａｂｌｅ[Amount])
```

Use the exact table name instead:

```auto
=SUM(SalesTable[Amount])
```

Similarly, if the column name is `Amount`, the following formula does not match the column name:

```auto
=SUM(SalesTable[Ａｍｏｕｎｔ])
```

Use the exact column name instead:

```auto
=SUM(SalesTable[Amount])
```

Full-width structured reference symbols, such as brackets and structured-reference operators, can be normalized where applicable.
For example:

```auto
=SUM(SalesTable［Amount］)
```

is treated as:

```auto
=SUM(SalesTable[Amount])
```

## Strings and Wildcards

Formula character normalization does not change full-width characters inside string values.
For example:

```auto
=＂（）＂
```

is saved as:

```auto
="（）"
```

The formula result is:

```auto
（）
```

Full-width wildcard characters are treated as normal characters, not as wildcard operators.
For example:

```auto
=COUNTIF(A1:A10,"a？c")
```

matches the literal text `a？c`. It does not match values such as `abc` or `axc`.
Use half-width wildcard characters when wildcard behavior is required.

| Full-width character | Behavior |
| -------------------- | -------- |
| `？` | Treated as a literal character. |
| `＊` | Treated as a literal character. |
| `～` | Treated as a literal character. |

## API and File Behavior

Formula character normalization applies to user input. It does not change formulas when they are read from a file, and it does not automatically normalize formulas set through APIs.
For example:

```javascript
sheet.setFormula(0, 0, "=Ａ１");
```

In this case, the full-width input is preserved. `Ａ１` is treated according to the normal formula parsing rules, such as a custom name if applicable.
If you need normalized formula text when setting formulas through APIs, normalize the formula string before calling the API.

## Limitations

* Formula character normalization applies to user input scenarios only.
* Formula character normalization does not apply to formulas set through APIs.
* Formula character normalization does not change formulas when reading from files.
* Full-width characters inside string values are preserved.
* Custom names, table names, and structured-reference column names require exact matching.
* Full-width wildcard characters are treated as literal characters.
* TableSheet column formulas are not supported by this normalization behavior.