Closed nighca closed 2 years ago
@nighca Nice to see this awesome library developed farther and farther! Is there any chance of translating whole release notes to english?
@mattleonowicz I will (in couple of days).
P.S. If currently you are not using any older versions of formstate-x, the release note here is not actually important. You can head to the documents directly :) That's much more detailed.
@mattleonowicz The en version is here. Feel free if any further questions.
Thank you! I'm still on v2. Will move to v3 soon
Changes of v3
See #47 for details.
Migrating from v2
Breaking Changes
1. Naming Adjustment
interface
Validatable
&ComposibleValidatable
-> interfaceIState
state.validators()
->state.withValidator()
(for details: #20)state.diableValidationWhen()
->state.disableWhen()
(for details: #17)state.dirty
->state.touched
Note that behaviors of the two fields differ (for details: #74 #63):
dirty
tells if current value (value
) equals initial value (initialValue
)touched
tells if any change ever happenedWhich means, for code like:
in v2, the result
state.dirty
will befalse
; in v3, the resultstate.touched
will betrue
P.S.
state.reset()
will resetstate.touched
tofalse
2. Changes of
FieldState
In v3, we now no longer debounce value change of
FieldState
. Correspondingly, it is not supported to specifydelay
(of debouncing) when constructingFieldState
instances now (for details: #61).If you need the debouncing of value change, you can use
DebouncedFieldState
instead. It's almost the same asFieldState
in v2:As a result, field
_value
ofFieldState
instances is removed and UI binding is simplified:bindInput
is no longer provided in v3, just usestate.value
&state.onChange
to bind states to UI inputs:Note that if
state
is an instance ofDebouncedFieldState
, you should usestate.$
instead ofstate
to do binding (for details: Debounced State).3.
FormState[mode=array]
->ArrayFormState
In v2, there are two modes for
FormState
:object
/array
, corresponding for two cases:[mode=object]
[mode=array]
In v3, the mode
object
remains the same. Modearray
is not supported any more, and we provided classArrayFormState
for the array cases:Its APIs differs slightly, for details: Input List & #54
4. Others
$
ofFormState
instances is now read-only, which means, behaviors likestate.$.foo = ...
is no longer allowed$
ofFieldState
instances is removedisFormState
is removedOther important (while not breaking) changes
1.
TransformedState
For situations where UI value differs with business value, we provide
TransformedState
. It works perfect within composition, for details: Transformed State & #562.
set
&onChange
In v2, only
FieldState
instances provided methodsset
&onChange
to change theirvalue
. If you want to change the value of aFormState
instance, you need to access its child states (state.$.*
) first. In v3, you can callset
oronChange
directly on any state, as long as it implemented interfaceIState
. The semantics for these methods remains the same.Compare
with
The way in v3 (
state.set({ foo: 1, bar: 2 })
) is much simpler, and it introduces lower coupling between parent states and child states.3.
ownError
&hasOwnError
In v2, only instances of
FormState
provided fieldsownError
&hasOwnError
. In v3, you can accessownError
&hasOwnError
on any states which implemented interfaceIState
. And they are recommended (instead oferror
&hasError
) for UI binding purpose. for details: #714. The brand-new docs
We built brand-new documents site for v3. It will be helpful to read them first, especially for key concepts in formstate-x.
v3 变更
详见 #47
升级文档
不兼容变更
1. 命名调整
interface
Validatable
&ComposibleValidatable
-> interfaceIState
state.validators()
->state.withValidator()
(详见 #20)state.diableValidationWhen()
->state.disableWhen()
(详见 #17)state.dirty
->state.touched
注意该字段的行为也有所调整(详见 #74 #63):
dirty
代表的是当前值(value
)跟初始值(initialValue
)是否不相等touched
代表的是值是否 发生过 变更(仅reset
会将该状态重置)即,以下的行为
对于 v2,结果
state.dirty
为false
;对于 v3,结果state.touched
为true
P.S.
state.reset()
会将state.touched
重置为false
2.
FieldState
变更及输入控件的绑定v3 中
FieldState
不再对 value 变更添加 debounce,对应地也不再支持在构造FieldState
时指定 debounce 的delay
(详见 #61)如果业务上确实需要对 value 变更 debounce 后再去响应,可以使用
DebouncedFieldState
代替;DebouncedFieldState
的构造方式与 v2 中的FieldState
一致:对应地,
FieldState
上的字段_value
也被移除,因此绑定 UI 的方式会有调整:formstate-x v3 不再提供bindInput
;要将 state 与输入控件进行绑定,直接使用state.value
&state.onChange
即可。如:注意,若
state
是DebouncedFieldState
实例 ,应当使用state.$
而不是state
进行绑定(详见 Debounced State)。3.
FormState[mode=array]
->ArrayFormState
v2 的
FormState
支持object
/array
两种模式(mode
),分别对应两种不同的使用姿势:[mode=object]
[mode=array]
在 v3 中,第一种使用姿势与 v2 一致;对于第二种使用姿势(对应于输入是一个长度不定的列表的情况),我们单独提供了
ArrayFormState
来满足这样的场景:ArrayFromState
的使用与原FormState
也会有所区别,详见 Input List & #544. 其他
FormState
实例的$
调整为readonly
,即不再允许类似state.$.foo = ...
的操作FieldState
实例的$
被移除isFormState
被移除其他值得了解的变更
1.
TranformedState
对于 UI value 与 business value 不一致的情况,我们过去通过由 Input 组件导出
getValue
来实现。在 v3 中,我们提供了TranformedState
来处理这种诉求,它的好处是不会要求 Input 组件提供额外的导出(getValue
),对 Input 组件的使用者也更友好(直接使用state.value
即可),对应地,其可组合性也会更好。详见 Transformed State & #562.
set
&onChange
在 v2 中,仅
FieldState
实例提供了set
/onChange
来直接操作其value
;对于FormState
实例,往往需要去通过其子 state(state.$.xxx
)来实现对值的设置。在 v3 中,所有(实现了IState
接口的)state 都会提供onChange
/set
,其语义与 v2 中FieldState
实例提供的set
/onChange
语义一致。因此你可以方便地在上层(父级 state)直接进行值的设置:相比
state.set({ foo: 1, bar: 2 })
的做法更简单,也使得上层与下层逻辑的耦合更低(父级 state 无须知道子 state 的信息)3.
ownError
&hasOwnError
在 v3 中,仅
FormState
实例会提供ownError
&hasOwnError
。现在所有(实现了IState
接口的)state 实例都会提供ownError
&hasOwnError
。建议使用ownError
&hasOwnError
代替error
&hasError
去实现校验结果与界面的绑定(如bindFormItem
),详见 #714. 阅读最新的文档
v3 提供了全新的文档( https://qiniu.github.io/formstate-x/ ),内容不长,建议阅读以便了解 formstate-x 中的关键概念