Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

translate: tutorial/data-method.md, working on #65 #79

Merged
merged 2 commits into from
Nov 19, 2018
Merged

translate: tutorial/data-method.md, working on #65 #79

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16c57c9
translate: tutorial/data-method.md, working on #65
harttle Nov 1, 2018
0d36380
Update data-method.md
harttle Nov 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 52 additions & 50 deletions source/_posts/en/tutorial/data-method.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
title: 数据操作
title: Data Manipulation
categories:
- tutorial
---


San 在组件的 data 上提供了一些数据操作的方法。通过 get 方法可以获取数据；通过 set、splice 等方法修改数据，相应的视图会被自动刷新。
San provides a number of methods on components' data. You can retrieve data via `.get()` method and modify data via `.set()`, `.splice()` methods, views will be updated automatically.

`说明`：为什么是通过 San 提供的方法操作数据，而不是直接操作数据？因为defineProperty并未被国内常用的浏览器广泛支持，并且我们也并不喜欢这种侵入式的风格，所以我们选择了折中的方式。因此，只有通过 San 提供的方法修改数据，视图才会自动刷新。
`Note`: You may ask why do we have to use these methods instead of manipulating data directly? That's because the [defineProperty](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) API is still not fully supported by major browsers in China and we prefer non-invasive ways to implement data binding. As a result, you have to use the methods provided by San in order to get the views updated automatically.

初始化
Initialization
-----

通过定义 initData 方法，可以在定义组件时指定组件初始化时的数据。initData 方法返回组件实例的初始化数据。
By defining an `initData` method, you can specify the data used to initialize the component. The return value of `initData` method will be used as the initialization data.

```javascript
san.defineComponent({
Expand All @@ -34,9 +34,9 @@ get
```


`解释`：
`Explanation`:

get 方法能够让我们从 data 中获取数据。
Use `.get()` method to retrieve data.

```javascript
san.defineComponent({
Expand All @@ -54,7 +54,7 @@ san.defineComponent({
});
```

当 expr 参数为空时，将返回整个数据项的对象。提供无参的 **get** 方法，主要是为了 ESNext 的解构，能够在一个表达式中获取多个数据项。
The entire data object will be returned if the `expr` argument is not provided. The no argument function overload is provided for ESNext destructuring to retrieve multiple data items with a single expression.

```javascript
san.defineComponent({
Expand All @@ -76,7 +76,7 @@ san.defineComponent({
});
```

`注意`： **get** 方法获取的数据不能直接修改，否则可能导致不一致的问题。数据修改请使用本文下面的 **set** 、 **splice** 等方法
`Note`: The data retrieved via **get** method is not expected to be modified, which will lead to inconsistent state. Use the following **set**, **splice** methods to modify any data.


set
Expand All @@ -87,12 +87,12 @@ set({string|Object}expr, {*}value, {Object?}option)
```


`解释`：
`Explanation`:

set 方法是最常用的数据修改方法，作用相当于 JavaScript 中的赋值 (=)。
The `.set()` method should be used in most cases, which is equivalent to the JavaScript assignment operator (=).


`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -118,13 +118,13 @@ merge
merge({string|Object}expr, {*}value, {Object?}option)
```

`版本`：>= 3.4.0
`Version`: >= 3.4.0

`解释`：
`Explanation`:

merge 方法用于将目标数据对象（target）和传入数据对象（source）的键进行合并，作用类似于 JavaScript 中的 `Object.assign(target, source)`。
The `.merge()` method is used to assign properties of the source object to the target object, just like the `Object.assign()` method in JavaScript.

`用法`：
`Usage`:


```javascript
Expand All @@ -146,14 +146,14 @@ apply
apply({string|Object}expr, {function({*}):{*}}value, {Object?}option)
```

`版本`：>= 3.4.0
`Version`: >= 3.4.0

`解释`：
`Explanation`:

apply 方法接受一个函数作为参数，传入当前的值到函数，然后用新返回的值更新它。其行为类似 `Array.prototype.map` 方法。
`.apply()` method accepts a function argument, which takes the data's current value as its input, and returns the updated value. The behavior of `.apply()` is like the JavaScript `Array.prototype.map` method.


`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -174,12 +174,12 @@ san.defineComponent({
});
```

数组方法
Array Methods
------

我们提供了一些数组操作的方法，这些方法与 JavaScript 的数组操作方法基本同名，以减少使用者的学习与记忆成本。除了 **删除** 操作。
We provide a number of methods for array manipulation. All of them take the same name as the `Array.prototype` except **remove**. Hope it helps to memorize!

`提示`：修改数组项还是直接使用 set 方法。我们可以认为，基本上所有写 JavaScript 时使用 = 赋值的场景，都用 set 方法。
`Note`: Use `.set()` method to modify an Array element. Actually whenever you want a JavaScript `=` assignment, you'll need the `.set()` method.

```javascript
san.defineComponent({
Expand All @@ -197,11 +197,11 @@ san.defineComponent({
{number} push({string|Object}expr, {*}value, {Object?}option)
```

`解释`：
`Explanation`:

在数组末尾插入一条数据。
Append an element into an array.

`用法`：
`Usage`:


```javascript
Expand All @@ -218,11 +218,11 @@ san.defineComponent({
{*} pop({string|Object}expr, {Object?}option)
```

`解释`：
`Explanation`:

在数组末尾弹出一条数据。
Pop one element out of an array.

`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -239,11 +239,11 @@ san.defineComponent({
{number} unshift({string|Object}expr, {*}value, {Object?}option)
```

`解释`：
`Explanation`:

在数组开始插入一条数据。
Insert one element to the beginning of an array.

`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -259,11 +259,11 @@ san.defineComponent({
{*} shift({string|Object}expr, {Object?}option)
```

`解释`：
`Explanation`:

在数组开始弹出一条数据。
Remove one element from the beginning of an array.

`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -279,11 +279,13 @@ san.defineComponent({
remove({string|Object}expr, {*}item, {Object?}option)
```

`解释`：
`Explanation`:

移除一条数据。只有当数组项与传入项完全相等(===)时，数组项才会被移除。
Remove the given item.

`用法`：
`.remove()` compares `item` to elements of the Array using [strict equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators#Using_the_Equality_Operators) (the same method used by the `===` operator).

`Usage`:

```javascript
san.defineComponent({
Expand All @@ -299,11 +301,11 @@ san.defineComponent({
removeAt({string|Object}expr, {number}index, {Object?}option)
```

`解释`：
`Explanation`:

通过数据项的索引移除一条数据。
Remove the element at the given index.

`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -319,11 +321,11 @@ san.defineComponent({
{Array} splice({string|Object}expr, {Array}spliceArgs, {Object?}option)
```

`解释`：
`Explanation`:

向数组中添加或删除项目。
The `.splice()` method changes the contents of an array by removing existing elements and/or adding new elements.

`用法`：
`Usage`:

```javascript
san.defineComponent({
Expand All @@ -336,22 +338,22 @@ san.defineComponent({
option
------

每个数据操作方法，最后都可以包含一个类型为 Object 的数据操作选项参数对象，该对象中的参数可控制视图更新行为。
Each of the above methods accepts an extra `option` argument, which is a plain object of key-value pairs to control how the views will be updated.


### silent

`解释`：
`Explanation`:

静默更新数据，不触发视图变更。
Update the data silently without updating the view.


### force

`版本`：>= 3.5.5
`Version`: >= 3.5.5

`解释`：
`Explanation`:

设置相同的数据时，强制触发视图变更。该参数仅对 set 方法有效
Force update the view even if the data to be set is identical to the existing value. Available for `.set()` method only.