forked from aralejs/widget
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
293 lines (240 loc) · 18.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=0">
<title>Widget</title>
<link rel="stylesheet" href="http://aralejs.org/assets/base.css">
<link rel="stylesheet" href="http://aralejs.org/assets/style.css">
<link rel="stylesheet" href="http://aralejs.org/assets/pygments.css">
<script src="http://seajs.org/dist/sea.js"></script>
<script src="http://aralejs.org/tools/seajs-helper.js"></script>
<!--[if lt IE 9]>
<script src="http://aralejs.org/assets/html5shiv.js"></script>
<![endif]-->
</head>
<body>
<header id="header">
<div class="container fn-clear">
<a href="./" class="current">Widget</a>
<a href="./examples/" >演示</a>
<a id="nav-test" href="./tests/runner.html">用例</a>
<nav role="navigation" id="nav">
<a title="Home" class="icon-home" href="/" id="logo">首页</a>
<a id="code-link" class="icon-github" href="https://github.com/aralejs/widget">源码</a>
</nav>
</div>
</header>
<div id="main">
<div class="container">
<div class="document-body">
<div class="markdown-body">
<h1>Widget</h1>
<p>Widget 是 UI 组件的基础类，约定了组件的基本生命周期，实现了一些通用功能。基于 Widget
可以构建出任何你想要的 Web 界面组件。</p>
<hr/>
<h2>模块依赖</h2>
<ul>
<li>seajs</li>
<li>$</li>
<li>handlebars</li>
<li><a href="http://aralejs.org/base/">base</a></li>
</ul>
<p><strong>注</strong>：Handlebars 依赖仅在混入 <code>Templatable</code> 后才产生。</p>
<h2>使用说明</h2>
<h3>extend <code>Widget.extend(properties)</code></h3>
<p>使用 <code>extend</code> 方法，可以基于 <code>Widget</code> 来创建子类。</p>
<div class="highlight"><pre><span class="nx">define</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">require</span><span class="p">,</span> <span class="nx">exports</span><span class="p">,</span> <span class="nx">module</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">Widget</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'widget'</span><span class="p">);</span>
<span class="c1">// 定义 SimpleTabView 类</span>
<span class="kd">var</span> <span class="nx">SimpleTabView</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">events</span><span class="o">:</span> <span class="p">{</span>
<span class="s1">'click .nav li'</span><span class="o">:</span> <span class="s1">'switchTo'</span>
<span class="p">},</span>
<span class="nx">switchTo</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">index</span><span class="p">)</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">},</span>
<span class="p">...</span>
<span class="p">});</span>
<span class="c1">// 实例化</span>
<span class="kd">var</span> <span class="nx">demo</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">SimpleTabView</span><span class="p">({</span> <span class="nx">element</span><span class="o">:</span> <span class="s1">'#demo'</span> <span class="p">}).</span><span class="nx">render</span><span class="p">();</span>
<span class="p">});</span>
</pre></div>
<p>详细示例请访问：<a href="http://aralejs.org/widget/examples/simple-tabview.html">simple-tabview.html</a></p>
<h3>initialize <code>new Widget([config])</code></h3>
<p>Widget 实例化时，会调用此方法。</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">widget</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Widget</span><span class="p">({</span>
<span class="nx">element</span><span class="o">:</span> <span class="s1">'#demo'</span><span class="p">,</span>
<span class="nx">className</span><span class="o">:</span> <span class="s1">'widget'</span><span class="p">,</span>
<span class="nx">model</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">title</span><span class="o">:</span> <span class="s1">'设计原则'</span><span class="p">,</span>
<span class="nx">content</span><span class="o">:</span> <span class="s1">'开放、简单、易用'</span>
<span class="p">}</span>
<span class="p">});</span>
</pre></div>
<p><code>config</code> 参数用来传入选项，实例化后可以通过 <code>get/set</code> 访问。<code>config</code>
参数如果包含 <code>element</code> 和 <code>model</code> 属性，实例化后会直接放到 <code>this</code> 上，即可通过
<code>this.element</code>、<code>this.model</code> 来获取。</p>
<p>在 <code>initialize</code> 方法中，确定了组件构建的基本流程：</p>
<div class="highlight"><pre><span class="c1">// 初始化 attrs</span>
<span class="k">this</span><span class="p">.</span><span class="nx">initAttrs</span><span class="p">(</span><span class="nx">config</span><span class="p">,</span> <span class="nx">dataAttrsConfig</span><span class="p">);</span>
<span class="c1">// 初始化 props</span>
<span class="k">this</span><span class="p">.</span><span class="nx">parseElement</span><span class="p">();</span>
<span class="k">this</span><span class="p">.</span><span class="nx">initProps</span><span class="p">();</span>
<span class="c1">// 初始化 events</span>
<span class="k">this</span><span class="p">.</span><span class="nx">delegateEvents</span><span class="p">();</span>
<span class="c1">// 子类自定义的初始化</span>
<span class="k">this</span><span class="p">.</span><span class="nx">setup</span><span class="p">();</span>
</pre></div>
<p>下面逐一讲述。</p>
<h3>initAttrs <code>widget.initAttrs(config, [dataAttrsConfig])</code></h3>
<p>属性的初始化方法。通过该方法，会将用户传入的配置与所继承的默认属性进行合并，并进行初始化操作。</p>
<p>子类如果想在 <code>initAttrs</code> 执行之前或之后进行一些额外处理，可以覆盖该方法：</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyWidget</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">initAttrs</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">config</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// 提前做点处理</span>
<span class="c1">// 调用父类的</span>
<span class="nx">MyWidget</span><span class="p">.</span><span class="nx">superclass</span><span class="p">.</span><span class="nx">initAttrs</span><span class="p">.</span><span class="nx">call</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="nx">config</span><span class="p">);</span>
<span class="c1">// 之后做点处理</span>
<span class="p">}</span>
<span class="p">});</span>
</pre></div>
<p><strong>注意</strong>：一般情况下不需要覆盖 <code>initAttrs</code>。</p>
<h3>parseElement <code>widget.parseElement()</code></h3>
<p>该方法只干一件事：根据配置信息，构建好 <code>this.element</code>。</p>
<p>默认情况下，如果 <code>config</code> 参数中传入了 <code>element</code> 属性（取值可为 DOM element / selector），
会直接根据该属性来获取 <code>this.element</code> 对象。</p>
<p><code>this.element</code> 是一个 jQuery / Zepto 对象。</p>
<h3>parseElementFromTemplate <code>widget.parseElementFromTemplate()</code></h3>
<p>如果 <code>config</code> 参数中未传入 <code>element</code> 属性，则会根据 <code>template</code> 属性来构建
<code>this.element</code>。 默认的 <code>template</code> 是 <code><div></div></code>。</p>
<p>子类可覆盖该方法，以支持 Handlebars、Mustache 等模板引擎。</p>
<h3>element <code>widget.element</code></h3>
<p>widget 实例对应的 DOM 根节点，是一个 jQuery / Zepto 对象。</p>
<h3>initProps <code>widget.initProps()</code></h3>
<p>properties 的初始化方法，提供给子类覆盖，比如：</p>
<div class="highlight"><pre><span class="nx">initProps</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">targetElement</span> <span class="o">=</span> <span class="nx">$</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">'target'</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
<h3>delegateEvents <code>widget.delegateEvents([events])</code></h3>
<h3>delegateEvents <code>widget.delegateEvents(eventType, handler)</code></h3>
<p>注册事件代理。在 Widget 组件的设计里，推荐使用代理的方式来注册事件。这样可以使得对应的
DOM 内容有修改时，无需重新绑定。</p>
<p><code>widget.delegateEvents()</code> 会在实例初始化时自动调用，这时会从 <code>this.events</code> 中取得声明的代理事件，比如</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyWidget</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">events</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">"dblclick"</span><span class="o">:</span> <span class="s2">"open"</span><span class="p">,</span>
<span class="s2">"click .icon.doc"</span><span class="o">:</span> <span class="s2">"select"</span><span class="p">,</span>
<span class="s2">"mouseover .date"</span><span class="o">:</span> <span class="s2">"showTooltip"</span>
<span class="p">},</span>
<span class="nx">open</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">},</span>
<span class="nx">select</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">},</span>
<span class="p">...</span>
<span class="p">});</span>
</pre></div>
<p><code>events</code> 中每一项的格式是：<code>"event selector": "callback"</code>，当省略 <code>selector</code>
时，默认会将事件绑定到 <code>this.element</code> 上。<code>callback</code> 可以是字符串，表示当前实例上的方法名；
也可以直接传入函数。</p>
<p><code>events</code> 还可以是方法，返回一个 events hash 对象即可。比如</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyWidget</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">events</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">hash</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">"click"</span><span class="o">:</span> <span class="s2">"open"</span><span class="p">,</span>
<span class="s2">"click .close"</span><span class="o">:</span> <span class="s2">"close"</span>
<span class="p">};</span>
<span class="k">return</span> <span class="nx">hash</span><span class="p">;</span>
<span class="p">},</span>
<span class="p">...</span>
<span class="p">});</span>
</pre></div>
<p><code>events</code> 中，还支持 <code>{{name}}</code> 表达式，比如上面的代码，可以简化为：</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyWidget</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">events</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">"click"</span><span class="o">:</span> <span class="s2">"open"</span><span class="p">,</span>
<span class="s2">"click .close"</span><span class="o">:</span> <span class="s2">"close"</span><span class="p">,</span>
<span class="s2">"mouseover {{attrs.trigger}}"</span><span class="o">:</span> <span class="s2">"open"</span><span class="p">,</span>
<span class="s2">"mouseover {{attrs.panels}}"</span><span class="o">:</span> <span class="s2">"hover"</span>
<span class="p">},</span>
<span class="p">...</span>
<span class="p">});</span>
</pre></div>
<p>实例化后，还可以通过 <code>delegateEvents</code> 方法动态添加事件代理：</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">myWidget</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Widget</span><span class="p">();</span>
<span class="nx">myWidget</span><span class="p">.</span><span class="nx">delegateEvents</span><span class="p">(</span><span class="s1">'click .move'</span><span class="p">,</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">});</span>
</pre></div>
<h3>undelegateEvents <code>widget.undelegateEvents([eventType])</code></h3>
<p>卸载事件代理。不带参数时，表示卸载所有事件。</p>
<h3>setup <code>widget.setup()</code></h3>
<p>提供给子类覆盖的初始化方法。可以在此处理更多初始化信息，比如</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">TabView</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="p">...</span>
<span class="nx">setup</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">this</span><span class="p">.</span><span class="nx">activeIndex</span> <span class="o">=</span> <span class="nx">getActiveIndex</span><span class="p">();</span>
<span class="p">},</span>
<span class="p">...</span>
<span class="p">});</span>
</pre></div>
<h3>render <code>widget.render()</code></h3>
<p>提供给子类覆盖的初始化方法。render 方法只干一件事件：将 <code>this.element</code> 渲染到页面上。</p>
<p>默认无需覆盖。需要覆盖时，请使用 <code>return this</code> 来保持该方法的链式约定。</p>
<h3>$ <code>widget.$(selector)</code></h3>
<p>在 <code>this.element</code> 内查找匹配节点。</p>
<h3>destroy <code>widget.destroy()</code></h3>
<p>销毁实例。</p>
<h3>on <code>widget.on(event, callback, [context])</code></h3>
<p>这是从 Events 中自动混入进来的方法。还包括 <code>off</code> 和 <code>trigger</code>。</p>
<p>具体使用请参考 <a href="http://aralejs.org/events/">events 使用文档</a>。</p>
<h3>autoRenderAll <code>Widget.autoRenderAll([root], [callback])</code></h3>
<p>根据 data-widget 属性，自动渲染找到的所有 Widget 类组件。</p>
<h3>query <code>Widget.query(selector)</code></h3>
<p>查询与 selector 匹配的第一个 DOM 节点，得到与该 DOM 节点相关联的 Widget 实例。</p>
<h2>Templatable</h2>
<p>可混入的功能类，提供 Handlebars 模板支持。</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">Templatable</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'widget-templatable'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">MyWidget</span> <span class="o">=</span> <span class="nx">Widget</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">Implements</span><span class="o">:</span> <span class="nx">Templatable</span>
<span class="p">});</span>
<span class="kd">var</span> <span class="nx">myWidget</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyWidget</span><span class="p">({</span>
<span class="nx">template</span><span class="o">:</span> <span class="s1">'<h3>{{title}}</h3><ol>{{#each list}}<li>{{item}}</li>{{/each}}'</span><span class="p">,</span>
<span class="nx">model</span><span class="o">:</span> <span class="p">{</span>
<span class="s1">'title'</span><span class="o">:</span> <span class="s1">'标题'</span><span class="p">,</span>
<span class="s1">'list'</span><span class="o">:</span> <span class="p">[</span>
<span class="p">{</span> <span class="s1">'item'</span><span class="o">:</span> <span class="s1">'文章一'</span> <span class="p">},</span>
<span class="p">{</span> <span class="s1">'item'</span><span class="o">:</span> <span class="s1">'文章二'</span> <span class="p">}</span>
<span class="p">]</span>
<span class="p">},</span>
<span class="nx">parentNode</span><span class="o">:</span> <span class="s1">'#demo'</span>
<span class="p">});</span>
<span class="nx">myWidget</span><span class="p">.</span><span class="nx">render</span><span class="p">();</span>
</pre></div>
<h3>renderPartial <code>widget.renderPartial(selector)</code></h3>
<p>局部渲染。根据传入的 <code>selector</code> 参数，刷新匹配的区域。</p>
<p>默认无需覆盖。需要覆盖时，请使用 <code>return this</code> 来保持该方法的链式约定。</p>
<h2>演示页面</h2>
<ul>
<li><a href="http://aralejs.org/widget/examples/index.html">http://aralejs.org/widget/examples/index.html</a></li>
<li><a href="http://aralejs.org/widget/examples/simple-tabview.html">http://aralejs.org/widget/examples/simple-tabview.html</a></li>
</ul>
<h2>测试用例</h2>
<ul>
<li><a href="http://aralejs.org/widget/tests/runner.html">http://aralejs.org/widget/tests/runner.html</a></li>
</ul>
<h2>交流讨论</h2>
<p>欢迎创建
<a href="https://github.com/aralejs/widget/issues/new">GitHub Issue</a>
来提交反馈。</p>
</div>
</div>
</div>
</div>
<hr class="end">
<script src="http://aralejs.org/tools/nico-helper.js"></script>
</body>
</html>