【SpreadJS v16.1 新特性介绍】单元格输入支持掩码 / Input Mask

SpreadJS 提供了一个掩码属性和一个模式选项来设置输入掩码。您可以使用占位符选项来指定占位符。占位符是显示在输入字段中的一串字符，代表预期的输入格式，引导用户按照格式进行输入。如果用户没有指定占位符，SpreadJS 默认使用“_”。您可以使用excludePlaceholder选项选择是否在输入字符串中显示占位符。
例如，如果屏蔽模式为“000000”，“_”为占位符，则空白输入字段显示“______”以指示所需的 6 位格式。如果 excludePlaceholder 选项设置为 false（默认值）并且用户输入“1234”，则在退出编辑模式后输入将保存为“1234____”。当该选项为真时，输入存储为“1234”，即排除占位符。

同样，您也可以通过将excludeLiteral设置为 true 来排除文字字符。文字是在特定位置显示的字符，不能被任何其他字符替换。电话号码中使用的括号和连字符或日期格式中的正斜杠就是几个例子。

以下代码显示了如何设置输入掩码：


如果用户在光标位于占位符处时输入字符，则新字符将替换占位符字符。在其他情况下，插入新字符。如果用户输入与模式不匹配，SpreadJS 会从左到右保留与模式匹配的部分，并丢弃剩余的无效部分。但是，当用户删除某些文本时，它只会删除当前的限制内容。例如，在模式 'a{3}0{3}' 的情况下，如果用户从输入的最左边的字符开始删除，SpreadJS 允许删除当前限制的前三个字符。要删除剩余的输入，用户必须将光标放在下一个限制的开头。
为了确认模式是否有效，SpreadJS 提供了一个静态方法validatePattern。以下代码显示了如何使用 validatePattern 方法来验证模式：

字符串模式字符串模式是定义输入格式的最简单方法，它是使用最小模式单元构造的。最小模式单元由字符限制和可选的字符长度限制组成。当没有指定字符长度限制时，它被认为是一个字符。下表定义了使用这两种类型的限制创建模式的各种规则。

限制类型	类别	图案字符	解释	样本模式	显示（'_'作为占位符）	输入	输出
字符长度	字符	A	字符	aaa	___	abc	abc
		>	字母自动转换为大写	>	_	A	A
				><<<<	_____	chris	Chris
		<	字母自动转换为小写	<	_	A	A
	数字	0	数字 (0-9)	0	___	123	123
					___	12	12_
	可选的	()	大括号 () 中的任何字符串都应该匹配。	0{1,3}（千克|磅）	_ 公斤	12k	12公斤
		|	字符串之间的分隔符。在大括号 () 中使用。braces() 中的字符是静态字符串；大括号内不需要转义字符。	Aut\\horChris|Icey|Victor|Ian) or (Author)Chris|Icey|Victor|Ian)	Author:Chris	V	Author:Victor
		[]	将关键字和文字组合为一个整体。	[>0]{5}	_____	a7osn	A7OSN
		-	表示字符范围。在方括号 [] 内使用。	[\\a-f]	_	b	b
	特殊字符	\（构造模式字符串时应使用“\\”）	转义字符	0\>0	_>_	32	3>2
		#	任何角色	###	___	a1&	a1&
字符长度限制	动态的	{n}	"n" 次重复	0{4}/0{2}/0{2}	____/__/__	20230101	2023/1/1
		{n,m}	最小“n”次和最大“m”次重复	0{1,3}.0{1,3}.0{1,3}.0{1,3}	_._._._	1270.0.1	127.0.0.1
				[\\01]{0,}		1010	1010
		{,m}	最多重复“m”次	0{,3}		123	123
		{n,}	最少“n”次重复	0{1,}.0{2}	_.__	1234.56	1234.56

在动态模式中：

• 占位符仅代表所需的最小长度。例如：0{2,10} 显示“__”，0{0,1} 什么都不显示。
• 如果未指定“m”，则动态模式的最大长度为 2147483648。
  

日期模式日期模式是一种指定日期和时间值格式的方法。它是固定格式模式，不接受字符长度限制。对于日期模式，SpreadJS 会根据日期规则自动修复用户输入。但是，您不得在单个模式中重复日期时间项，例如 yyyy、MM 等。例如，“ yyyy/MM/dd yyyy ”是无效模式，因为“yyyy”被使用了两次。
下表描述了日期模式的各种掩码字符及其在示例模式帮助下的用法。

Pattern Character	Description	Sample Pattern	Display '_' as placeholder	User Input	Output
y	Years	yy/MM/dd	__/__/__	23317	2023/3/17
		yyyy/MM/dd	____/__/__	2023317	2023/3/17
M	Months	yyyy/M/dd	____/_/__	2023317	2023/3/17
		yyyy/MM/dd	____/__/__	2023317	2023/3/17
d	Days	yyyy/MM/d	____/__/_	202337	2023/3/7
		yyyy/MM/dd	____/__/__	202337	2023/3/7
H	24 Hours	HH:mm:ss	__:__:__	2277	22:07:07
		H:mm:ss	_:__:__	577	5:07:07
h	12 Hours	hh:mm:ss (am|pm)	__:__:__ am	277 p	2:07:07 下午
		h:mm:ss (pm|am)	_:__:__ pm	277 a	2:07:07 上午
m	Minutes	HH:mm:ss	__:__:__	2277	22:07:07
		HH:m:ss	__:_:__	2277	22:07:07
s	Seconds	HH:mm:ss	__:__:__	2277	22:07:07
		HH:mm:s	__:__:_	2277	22:07:07
t	Hour Format	hh:mm:ss t	__:__:__ A	2277p	22:07:07 P
		hh:mm:ss tt	__:__:__ AM	2277p	22:07:07 PM

命名模式您还可以定义命名模式并在其他模式中重用它们。但是，如果模式中有一个字符串与 namedPatterns 中的任何名称匹配，则掩码会将其替换为命名模式。因此，建议使用具有最小重复机会的名称来定义模式。为了获取所有名称模式的列表，SpreadJS 提供了一个静态方法getNamedPatterns。

公式模式SpreadJS 还支持公式模式，即以公式形式出现的以“=”开头的模式。例如，如果工作表的单元格 A1-A3 的作者姓名为“Chris”、“Icey”和“Ian”，则以下两种模式会给出相同的结果。

Formula Pattern	Equivalent Pattern
'="Aut\\hor"&TEXTJOIN("|",TRUE,A1:A3)&")"'	'Aut\\horChris|Icey|Ian)'

确认模式是否有效的静态方法 validatePattern 不支持公式模式。
要评估公式模式，请在调用 validatePattern 方法之前使用GC.Spread.Sheets.CalcEngine.evaluateFormula
示例模式下表列出了常用的模式以供快速参考：

案件	模式或选项	展示	输入	输出
电子邮件	[a0]{1,}@[a0]{1,}.(com|cn|gov|edu)	_@_.com	chris@grapecity.e	chris@grapecity.edu
姓名	><{1,} ><{1,}	__ __	chris diao	Chris Diao
长日期	dd-MM-yyyy HH:mm	__-__-____ __:__	16720231620	16-07-2023 16:20
短期约会	日-月-年	__-__-____	1672023	16-07-2023
验证码	[>0]{5}	_____	a7osn	A7OSN
十进制数	[\-]{,1}0{0,}[.]{,1}0{0,}		-12.34	-12.34
			12.34	12.34
二进制数	[\\01]{0,}		10101	10101
美国电话号码	[\\(]0{3}[\\)][-]0{3}[-]0{4}	(___)-___-____	1234567890	(123)-456-7890