glass-easel 0.1.0

package/guide/zh_CN/data_management/data_deep_copy.md

@@ -0,0 +1,157 @@
+# 数据字段拷贝控制
+
+## 数据深拷贝
+
+默认情况下，数据字段应用到模板前，会经过一次深拷贝。这样，无意中对组件实例的 `this.data` 进行的修改，将不会应用到模板上。例如：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }}</div>
+  `),
+  data: {
+    a: 1,
+  },
+  lifetimes: {
+    attached() {
+      // 这样进行的更新不会应用到模板上
+      this.data.a = 2
+    },
+  },
+})
+```
+
+这样虽然可以提供一些对错误逻辑的保护，但需要进行一次深拷贝。默认情况下，这次深拷贝不支持含有递归字段的数据，例如：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  data: {
+    a: {},
+  },
+  lifetimes: {
+    attached() {
+      const a = {}
+      a.b = a
+      // a 是一个有递归字段的对象
+      // 不能用于 setData ，否则会出错！
+      this.setData({ a })
+    },
+  },
+})
+```
+
+此时可以更改组件的 `dataDeepCopy` 选项，使其支持递归字段：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    dataDeepCopy: glassEasel.DeepCopyKind.SimpleWithRecursion,
+  },
+  data: {
+    a: {},
+  },
+  lifetimes: {
+    attached() {
+      const a = {}
+      a.b = a
+      this.setData({ a })
+    },
+  },
+})
+```
+
+或者也可以完全禁用拷贝（这需要保证不能直接修改 `this.data` ），这样可以完全避免额外开销、对象的原型链能够保留、性能最优：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    dataDeepCopy: glassEasel.DeepCopyKind.None,
+  },
+  data: {
+    a: {},
+  },
+  lifetimes: {
+    attached() {
+      const a = {}
+      a.b = a
+      this.setData({ a })
+    },
+  },
+})
+```
+
+如果需要改变所有组件的这个选项，考虑更改 [组件空间](../advanced/component_space.md) 中的默认组件选项。
+
+## 属性传递深拷贝
+
+默认情况下，传递组件属性时，也会经过一次深拷贝。这样可以使得两个组件之间不共享对象、对一个组件的数据变更不会影响另一个组件。
+
+但这个行为也会使得含有递归字段的对象在传递时出错。可以通过更改子组件的 `propertyPassingDeepCopy` 选项，使其属性支持递归字段：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    propertyPassingDeepCopy: glassEasel.DeepCopyKind.SimpleWithRecursion,
+  },
+  properties: {
+    a: Object,
+  },
+})
+
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    dataDeepCopy: glassEasel.DeepCopyKind.SimpleWithRecursion,
+  },
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <child a="{{ a }}" />
+  `),
+  data: {
+    a: {},
+  },
+  lifetimes: {
+    attached() {
+      const a = {}
+      a.b = a
+      this.setData({ a })
+    },
+  },
+})
+```
+
+或者也可以完全禁用拷贝（这需要子组件保证不修改传入的对象），这样可以完全避免额外开销、对象的原型链能够保留、性能最优：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    propertyPassingDeepCopy: glassEasel.DeepCopyKind.None,
+  },
+  properties: {
+    a: Object,
+  },
+})
+
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    dataDeepCopy: glassEasel.DeepCopyKind.None,
+  },
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <child a="{{ a }}" />
+  `),
+  data: {
+    a: {},
+  },
+  lifetimes: {
+    attached() {
+      const a = {}
+      a.b = a
+      this.setData({ a })
+    },
+  },
+})
+```

package/guide/zh_CN/data_management/data_observer.md

@@ -0,0 +1,154 @@
+# 数据监听器
+
+## 监听数据字段变化
+
+通过数据监听器，可以在某些属性或数据字段被设置时触发一个函数。
+
+例如，可以在 `a` 和 `b` 两个字段中任何一个被设置时，触发一个函数：
+
+```js
+// 使用 Definition API 添加数据监听器
+export const addComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>{{ a }} + {{ b }} = {{ sum }}</div>
+  `),
+  data: {
+    a: 1,
+    b: 2,
+    sum: 3,
+  },
+  // 添加一个数据监听器
+  observers: {
+    'a, b': function () {
+      // 数据监听器中，最好使用 updateData 而非 setData
+      // （事实上，使用 setData 将与 updateData 等效）
+      // 数据监听器执行完后，会自动将更新应用到模板上
+      this.updateData({
+        sum: this.data.a + this.data.b,
+      })
+    },
+  },
+  lifetimes: {
+    attached() {
+      // 执行这个 setData 时，数据监听器会被执行
+      this.setData({
+        a: 3,
+      })
+    },
+  },
+})
+// 或使用 Chaining API 添加数据监听器
+export const addComponent = componentSpace.define()
+  .data(() => ({
+    a: 1,
+    b: 2,
+    sum: 3,
+  }))
+  // 在 Chaining API 中，应传入数组来监听多个数据字段
+  .observer(['a', 'b'], function () {
+    this.updateData({
+      sum: this.data.a + this.data.b,
+    })
+  })
+  .lifetime('attached', function () {
+    this.setData({
+      a: 3,
+    })
+  })
+  .registerComponent()
+// 或在 init 函数中添加数据监听器
+export const addComponent = componentSpace.define()
+  .data(() => ({
+    a: 1,
+    b: 2,
+    sum: 3,
+  }))
+  .init(function ({ lifetime, observer }) {
+    // 应传入数组来监听多个数据字段
+    observer(['a', 'b'], () => {
+      this.updateData({
+        sum: this.data.a + this.data.b,
+      })
+    })
+    lifetime('attached', function () {
+      this.setData({
+        a: 3,
+      })
+    })
+  })
+  .registerComponent()
+```
+
+注意：数据监听器会在其所监听字段值被设置时触发，即使其值没有发生变化，监听器也会触发。
+
+不要在数据监听器内设置被监听的数据字段本身，否则会无限循环：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    a: 1,
+  },
+  observers: {
+    'a': function () {
+      // 会导致无限循环！
+      this.updateData({
+        a: 1,
+      })
+    },
+  },
+})
+```
+
+## 用数据监听器监听子字段
+
+数据监听器也可以监听子字段，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: { a: 1 },
+    arr: [1, 2, 3],
+  },
+  // 添加一个数据监听器
+  observers: {
+    'obj.a, arr[2]': function () {
+      // 当 obj.a 或 arr[2] 被设置时会执行
+    },
+  },
+  lifetimes: {
+    attached() {
+      // 执行这组更新时，数据监听器会被执行
+      this.groupUpdate(() => {
+        this.replaceDataOnPath(['obj', 'a'], 3)
+      })
+    },
+  },
+})
+```
+
+若想监听所有子字段，可以使用通配符 `**` ，例如：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  data: {
+    obj: { a: 1 },
+  },
+  observers: {
+    'obj.**': function () {
+      // 当 obj 的任何子字段被设置时都会执行
+    },
+  },
+})
+```
+
+特别地，这样可以监听所有数据字段：
+
+```js
+export const addComponent = componentSpace.defineComponent({
+  observers: {
+    '**': function () {
+      // 当任何字段被设置时都会执行
+    },
+  },
+})
+```

package/guide/zh_CN/data_management/property_early_init.md

@@ -0,0 +1,31 @@
+# 组件初始化策略
+
+组件实例初始化流程有两种：
+
+1. 总是以自己定义的数据来初始化模板、触发 created 生命周期，然后如有必要，应用外部设置的组件属性、触发数据监听器、再更新一次模板；
+2. 先在自己定义的数据的基础上，应用外部设置的组件属性、触发数据监听器，然后初始化模板、触发 created 生命周期。
+
+前者的好处是数据监听器永远在 created 生命周期之后触发，逻辑时序比较稳定；坏处是常常需要一次额外的模板更新，性能相对较差。
+
+glass-easel 目前以前者为默认的初始化方式，通过设置 `propertyEarlyInit` 选项可以改为后者：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    propertyEarlyInit: true,
+  },
+  data: {
+    a: 1,
+  },
+  observers: {
+    a() {
+      // 可能早于 created 生命周期触发
+    }
+  },
+  lifetimes: {
+    created() {
+      // 可能晚于 observers 触发
+    },
+  },
+})
+```

package/guide/zh_CN/data_management/pure_data_pattern.md

@@ -0,0 +1,21 @@
+# 纯数据字段
+
+通过组件选项 `pureDataPattern` 可以使得一些数据字段不能用于模板上。这个选项接受一个正则表达式，符合这个正则表达式的字段名不能用于模板。
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    // 所有以 _ 开头的字段都不能用于模板
+    pureDataPattern: /^_/,
+  },
+  // 模板上的纯数据字段将视为 undefined
+  template: compileTemplate(`
+    <div>{{ _a }}</div>
+  `),
+  data: {
+    _a: 1,
+  },
+})
+```
+
+使用 `pureDataPattern` 通常不会带来性能方面的影响。但如果通过 `dataDeepCopy` 禁用数据拷贝， `pureDataPattern` 可能仍然会带来部分数据拷贝开销。

package/guide/zh_CN/index.md

@@ -0,0 +1,93 @@
+# glass-easel
+
+多后端组件化界面框架
+
+## 目录
+
+### 基础特性
+
+[入门](basic/beginning.md)
+
+[模板](basic/template.md)
+
+[组件](basic/component.md)
+
+[生命周期](basic/lifetime.md)
+
+[方法](basic/method.md)
+
+[事件](basic/event.md)
+
+### 组件间交互
+
+[slot 及 slot 类型](interaction/slot.md)
+
+[普通 Behaviors](interaction/behavior.md)
+
+[Trait Behaviors](interaction/trait_behavior.md)
+
+[组件路径](interaction/component_path.md)
+
+[组件间关系](interaction/relation.md)
+
+[占位组件](interaction/placeholder.md)
+
+[抽象节点](interaction/generic.md)
+
+[多文件模板](interaction/template_import.md)
+
+### 数据控制
+
+[高级数据更新方法](data_management/advanced_update.md)
+
+[数据监听器](data_management/data_observer.md)
+
+[数据字段拷贝控制](data_management/data_deep_copy.md)
+
+[组件初始化策略](data_management/property_early_init.md)
+
+[纯数据字段](data_management/pure_data_pattern.md)
+
+### 样式控制
+
+[样式隔离](styling/style_isolation.md)
+
+[外部样式类](styling/external_class.md)
+
+[虚拟组件节点](styling/virtual_host.md)
+
+### 节点树访问
+
+[节点树与节点类型](tree/node_tree.md)
+
+[节点树遍历](tree/element_iterator.md)
+
+[选择器查询](tree/selector.md)
+
+[节点树变化监听](tree/mutation_observer.md)
+
+[节点树变更](tree/node_tree_modification.md)
+
+### 高级特性
+
+[组件空间](advanced/component_space.md)
+
+[组件构造器中间件](advanced/component_filter.md)
+
+[绑定映射表更新](advanced/binding_map_update.md)
+
+[自定义后端](advanced/custom_backend.md)
+
+[自定义模板引擎](advanced/template_engine.md) 
+
+[外部组件](advanced/external_component.md)
+
+[警告与错误](advanced/error_listener.md)
+
+[构建参数](advanced/build_args.md)
+
+### 附录
+
+[自定义后端协议](appendix/backend_protocol.md)
+
+[list-diff 算法介绍](appendix/list_diff_algorithm.md)

package/guide/zh_CN/interaction/behavior.md

@@ -0,0 +1,52 @@
+# 普通 Behaviors
+
+behaviors 是一种简单的组件间代码共享机制。通过 behaviors ，可以将几个组件间共享的部分逻辑抽离出来。
+
+对于 Definition API ，可以用 behaviors 定义一部分属性、方法等，然后在组件中可以引用 behaviors ，例如：
+
+```js
+export const sharedBehavior = componentSpace.defineComponent({
+  // 属性列表会被合并到引用它的组件中
+  properties: {
+    a: Number,
+  },
+})
+
+export const myComponent = componentSpace.defineComponent({
+  // 引入 behavior
+  behaviors: [sharedBehavior],
+  properties: {
+    b: String,
+  },
+  // 属性会与 behavior 中的属性列表合并，因而模板中可以引用模板中的字段
+  template: compileTemplate(`
+    <div>{{a}}</div>
+    <div>{{b}}</div>
+  `),
+})
+```
+
+注意，有些字段不能写在 behaviors 中（会被忽略）。
+
+* `template` 模板因为无法很好合并，所以不能写在 behaviors 中。
+* `using` `generics` `placeholder` 由于涉及了模板中节点信息，也不能写在 behaviors 中。
+* `options` 是针对组件的配置，不能写在 hehaviors 中。
+
+对于 Chaining API ， behaviors 相当于链式调用中的一部分。 Chaining API 的 behaviors 也有上述字段限制。
+
+上面的例子可以用 Chaining API 表达为：
+
+```js
+export const sharedBehavior = componentSpace.define()
+  .property('a', Number)
+  .registerBehavior()
+
+export const myComponent = componentSpace.define()
+  .behavior(sharedBehavior)
+  .property('b', String)
+  .template(compileTemplate(`
+    <div>{{a}}</div>
+    <div>{{b}}</div>
+  `))
+  .registerComponent()
+```

package/guide/zh_CN/interaction/component_path.md

@@ -0,0 +1,37 @@
+# 组件路径
+
+可以给组件起一个路径名称，用于给组件归类。
+
+使用 Definition API 给组件命名的示例：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  is: 'path/to/my/component',
+})
+```
+
+使用 Chaining API 给组件命名的示例：
+
+```js
+export const myComponent = componentSpace.define('path/to/my/component')
+  .registerComponent()
+```
+
+在引用其他组件时，可以使用组件路径来指定，这对于含有递归引用的组件很实用：
+
+```js
+componentSpace.defineComponent({
+  is: 'path/to/one/component',
+  using: {
+    // 使用相对路径来指定另一个组件
+    another: '../another/component',
+  },
+})
+componentSpace.defineComponent({
+  is: 'path/to/another/component',
+  using: {
+    // 使用绝对路径来指定另一个组件
+    one: '/path/to/one/component',
+  },
+})
+```

package/guide/zh_CN/interaction/generic.md

@@ -0,0 +1,73 @@
+# 抽象节点
+
+有时，由于代码解耦等需要，一些节点对应的组件是不确定的。此时可以将它设置为一个 **抽象节点** ，它对应的组件可以由父组件来指定。例如：
+
+```js
+// 使用 Definition API 设置抽象节点
+export const childComponent = componentSpace.defineComponent({
+  generics: {
+    // 设置一个抽象节点
+    item: true,
+  },
+  // 在模板中可以使用抽象节点
+  template: compileTemplate(`
+    <item />
+  `),
+})
+// 或使用 Chaining API 设置抽象节点
+export const childComponent = componentSpace.define()
+  .generics({
+    item: true,
+  })
+  .template(compileTemplate(`
+    <item />
+  `))
+  .registerComponent()
+```
+
+在使用含有抽象节点的组件时，需要指定抽象节点对应的实际组件，例如：
+
+```js
+// 先定义一个抽象节点的实现组件
+export const implItemComponent = componentSpace.defineComponent({})
+
+// 使用组件时，传入 itemComponent
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+    impl: implItemComponent,
+  },
+  template: compileTemplate(`
+    <child generic:item="impl" />
+  `),
+})
+```
+
+注意：使用 `generic:` 传入实现组件时，不能使用数据绑定。
+
+定义抽象节点时，可以提供一个默认组件，如果父组件没有传入实现组件，则会转而使用这个默认组件，例如：
+
+```js
+const defaultComponent = componentSpace.defineComponent({})
+
+export const childComponent = componentSpace.defineComponent({
+  generics: {
+    item: {
+      default: defaultComponent,
+    },
+  },
+  template: compileTemplate(`
+    <item />
+  `),
+})
+
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  // 未指定 generic:item 时，默认组件将被使用
+  template: compileTemplate(`
+    <child />
+  `),
+})
+```

package/guide/zh_CN/interaction/placeholder.md

@@ -0,0 +1,40 @@
+# 占位组件
+
+有时，出于性能考虑，一些组件需要被延迟加载。此时，可以设置一个占位组件，当一个组件缺失时，可以用占位组件来暂时代替。等到组件被注册之后，占位组件会被自动替换成它。例如：
+
+```js
+export const placeholderComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>Loading...</div>
+  `),
+})
+
+// 使用 Definition API 设置占位组件
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: 'lazy-components/child',
+    placeholder: placeholderComponent,
+  },
+  placeholders: {
+    child: 'placeholder',
+  },
+})
+// 或使用 Chaining API 设置占位组件
+export const myComponent = componentSpace.define()
+  .usingComponents({
+    child: 'lazy-components/child',
+    placeholder: placeholderComponent,
+  })
+  .placeholders({
+    child: 'placeholder',
+  })
+  .registerComponent()
+```
+
+等到对应的被注册时，占位组件会被自动替换：
+
+```js
+componentSpace.defineComponent({
+  is: 'lazy-components/child',
+})
+```