glass-easel 0.1.0

package/guide/zh_CN/basic/event.md

@@ -0,0 +1,169 @@
+# 事件
+
+## 触发事件
+
+子组件可以向父组件发送事件，事件中可以携带数据。这是子组件向父组件传递消息和数据的主要方式。
+
+子组件触发事件时应使用组件实例的 `this.triggerEvent` 方法。例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      // 事件携带的数据
+      const detail = { someData: 'data' }
+      // 触发事件
+      this.triggerEvent('customEvent', detail)
+    },
+  },
+})
+```
+
+事件的可以指定为不冒泡事件（默认）、冒泡事件或跨组件冒泡事件，由 `triggerEvent` 的第三个参数控制，例如：
+
+```js
+// 触发冒泡事件（冒泡范围仅限于父组件内部）
+this.triggerEvent('customEvent', detail, { bubbles: true })
+// 触发跨组件冒泡事件
+this.triggerEvent('customEvent', detail, { bubbles: true, composed: true })
+```
+
+在 DOM 环境下， glass-easel 也会自动触发 DOM 事件。
+
+## 用普通组件方法响应事件
+
+`methods` 内定义的方法可以用于响应事件。例如：
+
+```js
+// 使用 Definition API 响应事件
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <child catch:customEvent="childEvent" />
+  `),
+  methods: {
+    childEvent({ detail }) {
+      detail.someData === 'data' // true
+    },
+  },
+})
+// 或使用 Chaining API 响应事件
+export const myComponent = componentSpace.define()
+  .usingComponents({
+    child: childComponent,
+  })
+  .template(compileTemplate(`
+    <child catch:customEvent="childEvent" />
+  `))
+  .methods({
+    childEvent({ detail }) {
+      detail.someData === 'data' // true
+    },
+  })
+  .registerComponent()
+// 或在 init 中响应事件
+export const myComponent = componentSpace.define()
+  .template(compileTemplate(`
+    <child catch:customEvent="childEvent" />
+  `))
+  .init(function ({ method }) {
+    const childEvent = method(({ detail }) => {
+      detail.someData === 'data' // true
+    })
+    return { childEvent }
+  })
+  .registerComponent()
+```
+
+## 用 init 响应事件
+
+如果使用 init ，也可以用 `listener` 包裹函数后将响应函数返回来响应事件。
+
+```js
+export const myComponent = componentSpace.define()
+  .template(compileTemplate(`
+    <child catch:customEvent="childEvent" />
+  `))
+  .init(function ({ method }) {
+    const childEvent = listener(({ detail }) => {
+      detail.someData === 'data' // true
+    })
+    return { childEvent }
+  })
+  .registerComponent()
+```
+
+这样做的好处是，如果使用 TypeScript ，可以方便地指定 `detail` 数据类型：
+
+```ts
+.init(function ({ method }) {
+  const childEvent = listener<{ someData: string }>(({ detail }) => {
+    detail.someData === 'data' // true
+  })
+  return { childEvent }
+})
+```
+
+## 绑定前缀
+
+在模板中绑定事件时，除了 `catch:` 前缀，还可以使用 `bind:` 前缀，例如：
+
+```xml
+<div bind:customEvent="childEvent2">
+  <child bind:customEvent="childEvent1" />
+</div>
+```
+
+`bind:` 的区别是它不会停止事件冒泡，使得节点的祖先也能够响应这个事件。（对于非冒泡事件，两者效果相同。）
+
+为了保持与微信小程序 WXML 的兼容性， `catch:` 和 `bind:` 中的冒号 `:` 可以省略，但并不建议。
+
+另一个绑定前缀是 `mut-bind:` ，它不会停止事件冒泡，但一个 `mut-bind:` 绑定的函数执行后，其他 `mut-bind:` 绑定的函数不会被执行。换而言之，所有 `mut-bind:` 绑定之间是互斥的。
+
+## 事件捕获阶段
+
+冒泡事件支持类似于 DOM 事件的捕获阶段。捕获阶段位于普通的冒泡阶段之前，且与冒泡经过的节点顺序正好相反。
+
+事件需要具有捕获阶段时，需要指定 `capture` 选项，例如：
+
+```js
+this.triggerEvent('customEvent', detail, { bubbles: true, capture: true })
+```
+
+在捕获阶段绑定响应函数时，可以使用 `capture-catch:` 或 `capture-bind:` ，例如：
+
+```xml
+<div capture-bind:customEvent="childEvent2">
+  <child capture-catch:customEvent="childEvent1" />
+</div>
+```
+
+## 事件节点标记
+
+在 `wx:for` 列表中绑定的事件，常常想要知道它具体是列表中的哪个节点，此时可以使用 `mark:` 为节点加上标记：
+
+```xml
+<block wx:for="{{ list }}">
+  <child mark:listIndex="{{ index }}" bind:customEvent="childEvent" />
+</block>
+```
+
+在响应函数中可以访问到：
+
+```js
+childEvent({ mark }) {
+  mark.listIndex // 列表中的 index
+}
+```
+
+`mark:` 也可以打在祖先节点上：
+
+```xml
+<block wx:for="{{ list }}">
+  <div mark:listIndex="{{ index }}">
+    <child bind:customEvent="childEvent" />
+  </div>
+</block>
+```

package/guide/zh_CN/basic/lifetime.md

@@ -0,0 +1,66 @@
+# 生命周期
+
+## 普通生命周期
+
+组件可以定义一些生命周期回调函数。最常见的是 `attached` 生命周期，它在组件被添加到页面内后立刻触发，例如：
+
+```js
+// 使用 Definition API 添加生命周期回调函数
+export const myComponent = componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      // 组件被添加到页面后触发
+    },
+  },
+})
+// 或使用 Chaining API 添加生命周期回调函数
+export const myComponent = componentSpace.define()
+  .lifetime('attached', function () {
+    // 组件被添加到页面后触发
+  })
+  .registerComponent()
+// 或在 init 中添加生命周期回调函数
+export const myComponent = componentSpace.define()
+  .init(function ({ lifetime }) {
+    lifetime('attached', function () {
+      // 组件被添加到页面后触发
+    })
+  })
+  .registerComponent()
+```
+
+glass-easel 会自动触发的生命周期列表如下。
+
+| 生命周期 | 触发时机 | 触发次数 |
+| -------- | -------- | ------ |
+| `created` | 组件实例刚刚被创建完时触发 | 每个实例触发一次 |
+| `attached` | 组件实例被添加到页面后触发 | 每个实例最多触发一次 |
+| `moved` | 组件实例在节点树中位置被移动后触发 | 只有 `wx:for` 内项目可能触发，次数不定 |
+| `detached` | 组件实例被从页面内移除后触发 | 每个实例最多触发一次 |
+
+也可以使用组件实例的 `this.triggerLifetime` 方法来触发生命周期。
+
+## 页面生命周期
+
+页面生命周期是一类特殊的生命周期。 glass-easel 不会主动触发页面生命周期，只能通过调用组件实例的 `this.triggerPageLifetime` 来触发。
+
+触发时，页面生命周期会自动递归到所有子孙组件上。因而它主要用于广播一些全局事件。
+
+```js
+// 使用 Definition API 添加页面生命周期回调函数
+export const myComponent = componentSpace.defineComponent({
+  pageLifetimes: {
+    someLifetime() { /* ... */ },
+  },
+})
+// 或使用 Chaining API 添加页面生命周期回调函数
+export const myComponent = componentSpace.define()
+  .pageLifetime('someLifetime', function () { /* ... */ })
+  .registerComponent()
+// 或在 init 中添加页面生命周期回调函数
+export const myComponent = componentSpace.define()
+  .init(function ({ pageLifetime }) {
+    pageLifetime('someLifetime', function () { /* ... */ })
+  })
+  .registerComponent()
+```

package/guide/zh_CN/basic/method.md

@@ -0,0 +1,62 @@
+# 方法
+
+## 普通组件方法
+
+可以通过 `methods` 来定义一些能在组件实例 `this` 对象上访问的函数：
+
+```js
+// 使用 Definition API 添加方法
+export const myComponent = componentSpace.defineComponent({
+  methods: {
+    aPlusB(a, b) {
+      return a + b
+    },
+  },
+  lifetimes: {
+    attached() {
+      this.aPlusB(1, 2) === 3 // true
+    },
+  },
+})
+// 或使用 Chaining API 添加方法
+export const myComponent = componentSpace.define()
+  .methods({
+    aPlusB(a, b) {
+      return a + b
+    },
+  })
+  .lifetime('attached', function () {
+    this.aPlusB(1, 2) === 3 // true
+  })
+  .registerComponent()
+// 或在 init 中添加方法
+export const myComponent = componentSpace.define()
+  .init(function ({ lifetime, method }) {
+    const aPlusB = method((a, b) => {
+      return a + b
+    })
+    lifetime('attached', function () {
+      this.aPlusB(1, 2) === 3 // true
+    })
+    // 注意 method 需要返回
+    return { aPlusB }
+  })
+  .registerComponent()
+```
+
+## 使用 init 内函数代替
+
+实际上，如果使用 init ，则通常不需要用普通组件方法，直接在 init 中定义函数即可。
+
+```js
+export const myComponent = componentSpace.define()
+  .init(function ({ lifetime }) {
+    const aPlusB = (a, b) => a + b
+    lifetime('attached', function () {
+      aPlusB(1, 2) === 3 // true
+    })
+  })
+  .registerComponent()
+```
+
+这种做法可以让一些私有函数不能通过组件实例 `this` 来访问。

package/guide/zh_CN/basic/template.md

@@ -0,0 +1,135 @@
+# 模板
+
+glass-easel 模板遵循 WXML 语法。
+
+一些语法细节与 HTML 有一定差异。最明显的区别是标签都需要正确闭合，如 `<div></div>` 和 `<div />` 。
+
+## 数据绑定
+
+在模板中，可以用 `{{ ... }}` 的形式嵌入表达式，表达式中的数据来源于组件的 `data` ，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ a + b }}</div>
+  `),
+  data: {
+    a: 1,
+    b: 2,
+  },
+})
+```
+
+使用组件实例的 `setData` 方法可以更新数据绑定，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ a + b }}</div>
+  `),
+  data: {
+    a: 1,
+    b: 2,
+  },
+  lifetimes: {
+    attached() {
+      this.setData({
+        a: 3,
+      })
+    },
+  },
+})
+```
+
+## 条件分支
+
+借助 `wx:if` `wx:elif` `wx:else` 可以控制节点的存在与否，例如：
+
+```xml
+<div wx:if="{{ a > b }}"> a 大于 b </div>
+<div wx:elif="{{ a < b }}"> a 小于 b </div>
+<div wx:elif="{{ a === b }}"> a 等于 b </div>
+```
+
+如果想要同时控制多个节点，可以借助 `<block>` 块，例如：
+
+```xml
+<block wx:if="{{ a > b }}">
+  <span>a</span>
+  <span>大于</span>
+  <span>b</span>
+</block>
+```
+
+注意， `<block>` 块不是一个真正的节点，其中不能包含其他属性。
+
+## 列表
+
+借助 `wx:for` 可以将一个数组展开成一组节点，例如：
+
+```xml
+<div wx:for="{{ arr }}">数组的第 {{ index }} 项是 {{ item }}</div>
+```
+
+这个例子中，如果 `arr` 数组有 3 项，则会最终生成 3 个 `<div>` 。
+
+这里也可以借助 `<block>` ：
+
+```xml
+<block wx:for="{{ arr }}">
+  <div>数组的第 {{ index }} 项是 {{ item }}</div>
+</block>
+```
+
+其中， `index` 和 `item` 是自动生成的临时变量，变量名可以使用 `wx:for-index` 和 `wx:for-item` 来调整：
+
+```xml
+<block wx:for="{{ arr }}" wx:for-index="i" wx:for-item="t">
+  <div>数组的第 {{ i }} 项是 {{ t }}</div>
+</block>
+```
+
+## 带 key 列表
+
+在列表数据更新时， glass-easel 会尝试对比新旧列表数据来推断哪些节点应该被增删或移动。
+
+如果列表开头或者中间部分需要发生插入或删除， glass-easel 的推断可能不够准确或高效。此时可以提供一个 key 字段来辅助推断。
+
+例如对于这样的数据：
+
+```js
+data: {
+  students: [
+    { id: 'A0001', name: '张三' },
+    { id: 'A0002', name: '李四' },
+    { id: 'A0003', name: '王五' },
+  ]
+}
+```
+
+列表中每一项的 `id` 是唯一的、有代表性的，就可以将它作为 key 使用：
+
+```xml
+<block wx:for="{{ arr }}" wx:key="id">
+  <div>姓名：{{ item.name }}</div>
+</block>
+```
+
+在复杂的列表中，使用 key 通常可以提升整体性能。但要注意：
+
+* 如果每一项的 key 值不是唯一的，会降低使用 key 进行推断效果，不要将唯一性很差的字段作为 key ；
+* 作为 key 的字段会被转换为字符串使用，所以只应使用数值或字符串类型的数据字段；
+* 如果列表项目是固定的，或者只会在末尾增加、删除项目， key 不会有任何帮助（反而会增加少量开销），可以不用。
+
+## 转义符
+
+在数据绑定以外，应使用 XML Entities 来进行特殊字符的转义。
+
+通常情况下只需要转义尖括号，例如 `<` 转义为 `&lt;` ：
+
+```xml
+<div wx:if="{{ a > b }}"> a &gt; b </div>
+<div wx:elif="{{ a < b }}"> a &lt; b </div>
+```
+
+数据绑定内部的转义方式与 JavaScript 一致。

package/guide/zh_CN/data_management/advanced_update.md

@@ -0,0 +1,170 @@
+# 高级数据更新方法
+
+## 使用 setData 更新模板数据绑定
+
+一般情况下，可以使用组件实例的 `this.setData` 来更新数据绑定。
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ a + b }}</div>
+  `),
+  data: {
+    a: 1,
+    b: 2,
+  },
+  lifetimes: {
+    attached() {
+      this.setData({
+        a: 3,
+      })
+    },
+  },
+})
+```
+
+在使用 Chaning API 时，也可以利用 init 函数这样做：
+
+```js
+export const addComponent = componentSpace.define()
+  .template(compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ a + b }}</div>
+  `))
+  .data(() => ({
+    a: 1,
+    b: 2,
+  }))
+  .init(function ({ setData, lifetime }) {
+    lifetime('attached', () => {
+      // 这种做法可以省略掉 this
+      setData({
+        a: 3,
+      })
+    })
+  })
+  .registerComponent()
+```
+
+setData 支持一些复杂的数据路径，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: {
+      a: [1, 2],
+    },
+  },
+  lifetimes: {
+    attached() {
+      this.setData({
+        'obj.a[0]': 3,
+      })
+    },
+  },
+})
+```
+
+## 高级路径更新
+
+如果想仅更新对象内的一个字段，可以使用高级路径更新的方式。这样虽然接口复杂一些，但可以拥有更好的性能。
+
+例如，可以使用 `replaceDataOnPath` 来更新对象内的数据字段：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: {
+      a: [1, 2],
+    },
+  },
+  lifetimes: {
+    attached() {
+      // 更新 obj.a 字段
+      this.replaceDataOnPath(['obj', 'a', 0], 3)
+      // 将更新应用到模板上
+      this.applyDataUpdates()
+    },
+  },
+})
+```
+
+如果字段是数组类型的，还可以使用 `spliceArrayDataOnPath` 来对数组项进行插入和删除：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: {
+      arr: [1, 2, 3, 4],
+    },
+  },
+  lifetimes: {
+    attached() {
+      // 更新 obj.arr 数组：
+      // 类似于数组的 splice 方法
+      // 可以在一个位置上移除若干项，再插入若干项
+      this.spliceArrayDataOnPath(['obj', 'arr'], 1, 2, [5, 6, 7])
+      // 得到的 obj.arr 是 [1, 5, 6, 7, 4]
+      // 将更新应用到模板上
+      this.applyDataUpdates()
+    },
+  },
+})
+```
+
+调用 `replaceDataOnPath` 和 `spliceArrayDataOnPath` 后，并不会立即将更新内容应用到模板上，还需要调用 `applyDataUpdates` 。如果需要连续调用多个 `replaceDataOnPath` 或 `spliceArrayDataOnPath` ，在末尾调用一次 `applyDataUpdates` 即可。
+
+## 组合更新
+
+连续调用多个 `replaceDataOnPath` 或 `spliceArrayDataOnPath` 后，可能会遗忘调用 `applyDataUpdates` 。
+
+可以考虑改用 `groupUpdates` 将它们组合起来，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: {
+      a: 1,
+      b: 2,
+    },
+  },
+  lifetimes: {
+    attached() {
+      // 进行组合更新
+      this.groupUpdates(() => {
+        this.replaceDataOnPath(['obj', 'a'], 3)
+        this.replaceDataOnPath(['obj', 'b'], 5)
+      })
+    },
+  },
+})
+```
+
+在 `groupUpdates` 调用后，会自动将更新应用到模板上，不再需要调用 `applyDataUpdates` 。
+
+另外，如果需要将多个 `setData` 调用组合起来，可以使用 `updateData` ，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ a + b }}</div>
+  `),
+  data: {
+    a: 1,
+    b: 2,
+  },
+  lifetimes: {
+    attached() {
+      this.groupUpdates(() => {
+        this.updateData({
+          a: 3,
+        })
+        this.updateData({
+          b: 5,
+        })
+      })
+    },
+  },
+})
+```
+
+这种做法性能上优于连续多次 `setData` 。