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

[translation] tutorial/event.md #81

Closed
wants to merge 3 commits into from
Closed

[translation] tutorial/event.md #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
869b212
[transition] tutorial/event.md
Nov 1, 2018
d6da7f3
[translate] for.md + form.md
Nov 11, 2018
eca06d2
translation: fix grammar
Nov 23, 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
41 changes: 21 additions & 20 deletions source/_posts/en/tutorial/event.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
---
title: 事件处理
title: Event Handling
categories:
- tutorial
---

事件是开发中最常用的行为管理方式。通过 **on-** 前缀，可以将事件的处理绑定到组件的方法上。
Events are the most commonly used behavior management methods in development.
Bind the processing of events to the component's methods with the **on-** prefix。

`提示`：在 San 中，无论是 DOM 事件还是组件的自定义事件，都通过 **on-** 前缀绑定，没有语法区分。
`Hint`: In San, both DOM event and component's custom event are bound by the **on-** prefix, with no syntax distinction.


DOM 事件
DOM Event
-------

**on- + 事件名** 将 DOM 元素的事件绑定到组件方法上。当 DOM 事件触发时，组件方法将被调用，this 指向组件实例。下面的例子中，当按钮被点击时，组件的 submit 方法被调用。
**on- + event name** binds the event of the DOM element to the component method. When a DOM event fires, the component method is called and this points to the component instance.
In the following example, when the button is clicked, the component's submit method is called.


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


绑定事件时，可以指定参数，引用当前渲染环境中的数据。参数可以是任何类型的[表达式](../template/#表达式)。
When binding events, you can specify parameters that reference the data in the current rendering environment. The argument can be any type of [expression] (../template/#expression).

```html
<!-- Template -->
Expand All @@ -54,8 +55,8 @@ san.defineComponent({
});
```


指定参数时，**$event** 是 San 保留的一个特殊变量，指定 $event 将引用到 DOM Event 对象。从而你可以拿到事件触发的 DOM 对象、鼠标事件的鼠标位置等事件信息。
When specifying a parameter, **$event** is a special variable reserved by San, specifying that $event will be referenced to the DOM Event object.
So you can get event information such as the event-triggered DOM object, mouse position of the mouse event.

```javascript
san.defineComponent({
Expand All @@ -73,10 +74,9 @@ san.defineComponent({
customized event
--------

在组件上通过 **on-** 前缀，可以绑定组件的自定义事件。

Custom events for components can be bound by the **on-** prefix on the component.

下面的例子中，MyComponent 为 Label 组件绑定了 done 事件的处理方法。
In the following example, MyComponent binds the handling of the done event to the Label component.

```javascript
var MyComponent = san.defineComponent({
Expand All @@ -92,7 +92,7 @@ var MyComponent = san.defineComponent({
});
```

San 的组件体系提供了事件功能，Label 直接通过调用 fire 方法就能方便地派发一个事件。
San's component architecture provides event functionality, and Label can easily dispatch an event directly by calling the fire method.

```javascript
var Label = san.defineComponent({
Expand All @@ -105,14 +105,14 @@ var Label = san.defineComponent({
```


修饰符
Modifier
--------

### capture

`版本`：>= 3.3.0
`Version`：>= 3.3.0

在元素的事件声明中使用 capture 修饰符，事件将被绑定到捕获阶段。
The capture modifier is used in the element's event declaration and the event is bound to the capture phase.

```javascript
var MyComponent = san.defineComponent({
Expand All @@ -131,14 +131,14 @@ var MyComponent = san.defineComponent({
});
```

`注意`：只有在支持 **addEventListener** 的浏览器环境支持此功能，老旧 IE 上使用 capture 修饰符将没有效果。
`Note`: This feature is only supported in browser environments that support **addEventListener**. Using the capture modifier on older IEs will have no effect.

### native

`版本`：>= 3.3.0
`Version`：>= 3.3.0


在组件的事件声明中使用 native 修饰符，事件将被绑定到组件根元素的 DOM 事件。
Using the native modifier in the component's event declaration, the event is bound to the DOM event of the component's root element.

```javascript
var Button = san.defineComponent({
Expand All @@ -158,6 +158,7 @@ var MyComponent = san.defineComponent({
});
```

有时候组件封装了一些基础结构和样式，同时希望点击、触摸等 DOM 事件由外部使用方处理。如果组件需要 fire 每个根元素 DOM 事件是很麻烦并且难以维护的。native 修饰符解决了这个问题。
Sometimes components encapsulate some infrastructure and styles, and expect that DOM events such as clicks and touches are handled by external consumers.
If the component needs fire each root element DOM event is cumbersome and difficult to maintain. The native modifier solves this problem.
andycall marked this conversation as resolved.
Show resolved Hide resolved
andycall marked this conversation as resolved.
Show resolved Hide resolved


34 changes: 17 additions & 17 deletions source/_posts/en/tutorial/for.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
---
title: 循环
title: loop
categories:
- tutorial
---

通过循环渲染列表是常见的场景。通过在元素上作用 **s-for** 指令，我们可以渲染一个列表。
Rendering a list by looping is a common scenario. We can render a list by applying the **s-for** directive on the element.


语法
Syntax
----

**s-for** 指令的语法形式如下：
The syntax of the **s-for** directive is as follows:

```
item-identifier[, index-identifier] in expression[ trackBy accessor-expression]
```

列表渲染
List Rendering
----

下面的代码描述了在元素上作用 **s-for** 指令，渲染一个列表。在列表渲染的元素内部，可以正常访问到 owner 组件上的其他数据（下面例子中的dept）。
The following code describes the use of the **s-for** directive on an element to render a list. Inside the elements rendered by the list, you can access other data on the owner component (dept in the example below).

```html
<!-- Template -->
Expand All @@ -46,10 +46,10 @@ san.defineComponent({
});
```

索引
Index
----

**s-for** 指令中可以指定索引变量名（下面例子中的index），从而在列表渲染过程获得列表元素的索引。
The index variable name (index in the example below) can be specified in the **s-for** directive to get the index of the list element in the list rendering process.

```html
<!-- Template -->
Expand All @@ -76,16 +76,16 @@ san.defineComponent({
});
```

列表数据操作
List data operation
-------

列表数据的增加、删除等操作请使用组件 data 提供的数组方法。详细请参考[数组方法](../data-method/#数组方法)文档。
For the addition, deletion, etc. of list data, use the array method provided by the component data. For details, please refer to the [Array Method] (../data-method/#Array-Method) document.


虚拟元素
Virtual element
------

和 if 指令一样，对 template 元素应用 for 指令，能够让多个元素同时根据遍历渲染，可以省掉一层不必要的父元素。
As with the if directive, applying the for directive to the template element allows multiple elements to be rendered at the same time based on traversal, eliminating the need for an unnecessary parent element.


```html
Expand All @@ -104,7 +104,7 @@ trackBy
`>= 3.6.1`


在 **s-for** 指令声明中指定 **trackBy**，San 在数组更新时，将自动跟踪项的变更，进行相应的 insert/remove 等操作。 **trackBy** 只能声明 item-identifier 的属性访问。
Specify **trackBy** in the **s-for** directive declaration. When the array is updated, San will automatically track the changes of the items and perform the corresponding insert/remove operations. **trackBy** can only declare attribute access to item-identifier.


```html
Expand Down Expand Up @@ -133,12 +133,12 @@ san.defineComponent({
```


trackBy 通常用在对后端返回的 JSON 数据渲染时。因为前后两次 JSON parse 无法对列表元素进行 === 比对，通过 trackBy， 框架将在内部跟踪变更。结合 transition 时，变更过程的动画效果将更符合常理。
TrackBy is typically used when rendering JSON data returned by the backend. Because the two JSON parse cannot make a === comparison on the list elements, the track will track the changes internally through trackBy. When combined with transitions, the animation of the change process will be more reasonable.

在下面的场景下，使用 trackBy 的性能上反而会变差：
In the following scenario, the performance of using trackBy will be worse:

- 所有数据项都发生变化
- 数据项变化前后的顺序不同
- All data items have changed
- The order of data items before and after changes is different



Expand Down
24 changes: 12 additions & 12 deletions source/_posts/en/tutorial/form.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: 表单
title: Form
categories:
- tutorial
---


表单是常见的用户输入承载元素，本篇介绍一些常用表单元素的用法。在 MVVM 中，我们一般在用户输入的表单元素或组件上应用 **双向绑定**。
Forms are common user input hosting elements, and this section describes the usage of some common form elements. In MVVM, we typically apply **two-way binding** on form elements or components entered by the user.


输入框
Input
-----

输入框的绑定方法比较简单，直接对输入框的 value 属性应用双向绑定就行了。
The binding method of the input box is relatively simple, and it is sufficient to apply the two-way binding directly to the value attribute of the input box.


```html
Expand All @@ -22,9 +22,9 @@ categories:
checkbox
-------

checkbox 常见的使用场景是分组，在组件模板中，我们把需要分组的 checkbox 将 checked 属性双向绑定到同名的组件数据中。
The common usage scenarios for checkboxes are grouping. In the component template, we bind the checked property to the component data of the same name in both directions.

`提示`：除非你需要进行传统的表单提交，否则无需指定 checkbox 的 name 属性。San 仅以 checked 作为分组的依据。
`Hint`: Unless you need to make a traditional form submission, you don't need to specify the checkbox's name attribute. San only uses checked as the basis for grouping.

```html
<!-- Template -->
Expand All @@ -35,7 +35,7 @@ checkbox 常见的使用场景是分组，在组件模板中，我们把需要
</div>
```

我们期望 checkbox 绑定到的数据项是一个 **Array&lt;string&gt;** 。当 checkbox 被选中时，其 value 会被添加到绑定的数据项中；当 checkbox 被取消选中时，其 value 会从绑定数据项中移除。
The data item we expect the checkbox to bind to is a **Array&lt;string&gt;** . When the checkbox is selected, its value is added to the bound data item; when the checkbox is unchecked, its value is removed from the bound data item.

```js
// Component
Expand All @@ -60,9 +60,9 @@ san.defineComponent({
radio
-----

与 checkbox 类似，我们在组件模板中，把需要分组的 radio 将 checked 属性绑定到同名的组件数据中。
Similar to the checkbox, in the component template, we bind the checked attribute to the component data of the same name in the radio that needs to be grouped.

`提示`：你需要手工指定分组 radio 的 name 属性，使浏览器能处理 radio 选择的互斥。可以把它设置成与绑定数据的名称相同。
`Hint`: You need to manually specify the name attribute of the group radio so that the browser can handle the mutual exclusion of the radio selection. It can be set to the same name as the bound data.

```html
<!-- Template -->
Expand All @@ -73,7 +73,7 @@ radio
</div>
```

我们期望 radio 绑定到的数据项是一个 **string** 。当 radio 被选中时，绑定的数据项值被设置成选中的 radio 的 value 属性值。
The data item we expect radio to bind to is a **string** . When radio is selected, the bound data item value is set to the value of the selected radio's value property.

```js
// Component
Expand All @@ -92,7 +92,7 @@ san.defineComponent({
select
------

select 的使用方式和输入框类似，直接对 value 属性应用双向绑定。
The select is used in a similar way to the input box, applying a two-way binding directly to the value property.

```html
<!-- Template -->
Expand All @@ -103,7 +103,7 @@ select 的使用方式和输入框类似，直接对 value 属性应用双向绑
</select>
```

`提示`：在浏览器中，select 的 value 属性并不控制其选中项，select 的选中项是由 option 的 selected 属性控制的。考虑到开发的方便，开发者不需要编写 option 的 selected 属性，San 会在下一个视图更新时间片中刷新 select 的选中状态。
`Hint`: In the browser, the value attribute of select does not control its selected item, and the selected item of select is controlled by the selected attribute of option. Considering the ease of development, the developer does not need to write the selected property of option, and San will refresh the selected state of select in the next view update time slice.

```js
// Component
Expand Down