Deploying to gh-pages from @ harttle/liquidjs@e941378535 🚀

This commit is contained in:
harttle
2024-08-16 16:56:29 +00:00
parent 6c9d227f92
commit fbd1c14cb8
422 changed files with 6202 additions and 17559 deletions
+9 -54
View File
@@ -38,7 +38,7 @@
<link rel="stylesheet" href="../../css/navy.css">
<link rel="alternate" href="../../atom.xml" title="LiquidJS" type="application/atom+xml">
<meta name="generator" content="Hexo 5.4.0"></head>
<meta name="generator" content="Hexo 7.3.0"></head>
<body>
<div id="container">
@@ -48,7 +48,7 @@
<a href="/zh-cn/" id="logo">LiquidJS</a>
</h1>
<nav id="main-nav">
<a href="intro-to-liquid.html" class="main-nav-link">教程</a><a href="../tags/overview.html" class="main-nav-link">标签</a><a href="../filters/overview.html" class="main-nav-link">过滤器</a><a href="../playground.html" class="main-nav-link">演示</a><a href="../api/classes/Liquid.html" class="main-nav-link">API</a>
<a href="intro-to-liquid.html" class="main-nav-link">教程</a><a href="../tags/overview.html" class="main-nav-link">标签</a><a href="../filters/overview.html" class="main-nav-link">过滤器</a><a href="../playground.html" class="main-nav-link">演示</a><a href="../../api/classes/Liquid.html" class="main-nav-link">API</a>
<div id="search-input-wrap">
<i id="search-input-icon" class="icon-search"></i>
<input type="search" id="search-input" placeholder="搜索...">
@@ -93,76 +93,31 @@
</header>
<div class="article-content" itemprop="articleBody">
<h2 id="访问原始参数" class="article-heading"><a href="#访问原始参数" class="headerlink" title="访问原始参数"></a>访问原始参数<a class="article-anchor" href="#访问原始参数" aria-hidden="true"></a></h2><p><a href="/tutorials/register-filters-tags.html">注册过滤器和标签</a> 中提到,可以通过 <code>tagToken.args</code> 来得到标签的原始参数字符串。例如:</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: &#123;% random foo bar coo %&#125;</span>
<span class="token comment">// Output: "foo", "bar" or "coo"</span>
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">&#123;</span>
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// tagToken.args === "foo bar coo"</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>items <span class="token operator">=</span> tagToken<span class="token punctuation">.</span>args<span class="token punctuation">.</span><span class="token function">split</span><span class="token punctuation">(</span><span class="token string">' '</span><span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// get a random index</span>
<span class="token keyword">const</span> index <span class="token operator">=</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token comment">// output that item</span>
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">[</span>index<span class="token punctuation">]</span><span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: &#123;% random foo bar coo %&#125;</span></span><br><span class="line"><span class="comment">// Output: &quot;foo&quot;, &quot;bar&quot; or &quot;coo&quot;</span></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">&#x27;random&#x27;</span>, &#123;</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) &#123;</span><br><span class="line"> <span class="comment">// tagToken.args === &quot;foo bar coo&quot;</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span> = tagToken.<span class="property">args</span>.<span class="title function_">split</span>(<span class="string">&#x27; &#x27;</span>)</span><br><span class="line"> &#125;,</span><br><span class="line"> <span class="title function_">render</span>(<span class="params">context, emitter</span>) &#123;</span><br><span class="line"> <span class="comment">// get a random index</span></span><br><span class="line"> <span class="keyword">const</span> index = <span class="title class_">Math</span>.<span class="title function_">floor</span>(<span class="variable language_">this</span>.<span class="property">items</span>.<span class="property">length</span> * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> <span class="comment">// output that item</span></span><br><span class="line"> emitter.<span class="title function_">write</span>(<span class="variable language_">this</span>.<span class="property">items</span>[index])</span><br><span class="line"> &#125;</span><br><span class="line">&#125;)</span><br></pre></td></tr></table></figure>
<p>见这个 JSFiddle<a target="_blank" rel="noopener external nofollow noreferrer" href="http://jsfiddle.net/ctj364up/2/">http://jsfiddle.net/ctj364up/2/</a></p>
<h2 id="解析参数的值" class="article-heading"><a href="#解析参数的值" class="headerlink" title="解析参数的值"></a>解析参数的值<a class="article-anchor" href="#解析参数的值" aria-hidden="true"></a></h2><p>除了静态的参数字符串之外,我们更希望把动态的值传递给标签。LiquidJS 中的值可以是字面量(字符串、数字等,也可以是当前上下文的变量。</p>
<p>下面是修改过的模板,也包含三个值用来随机。但它们表示的是值而不是静态的字符串。第一个是字符串字面量,第二个是标识符(表示变量),第三个是属性访问表达式,包含两个标识符。</p>
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">&#123;%</span> random <span class="token string">"foo"</span> bar obj<span class="token punctuation">.</span>coo <span class="token delimiter punctuation">%&#125;</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">&#123;% random &quot;foo&quot; bar obj.coo %&#125;</span><br></pre></td></tr></table></figure>
<p>解析这么多种情况会很麻烦,但 LiquidJS 提供了 <a href="/api/classes/Tokenizer.html">Tokenizer</a> 类来处理这种情况。</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> <span class="token punctuation">&#123;</span> Liquid<span class="token punctuation">,</span> Tokenizer<span class="token punctuation">,</span> evalToken <span class="token punctuation">&#125;</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span>
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">&#123;</span>
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">const</span> tokenizer <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Tokenizer</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>items <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
<span class="token keyword">while</span> <span class="token punctuation">(</span><span class="token operator">!</span>tokenizer<span class="token punctuation">.</span><span class="token function">end</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// here readValue() returns a LiteralToken or PropertyAccessToken</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span>tokenizer<span class="token punctuation">.</span><span class="token function">readValue</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">const</span> index <span class="token operator">=</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token keyword">const</span> token <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">[</span>index<span class="token punctuation">]</span>
<span class="token comment">// in LiquidJS, we use yield to wait for async call</span>
<span class="token keyword">const</span> value <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token function">evalToken</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> context<span class="token punctuation">)</span>
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> &#123; <span class="title class_">Liquid</span>, <span class="title class_">Tokenizer</span>, evalToken &#125; = <span class="built_in">require</span>(<span class="string">&#x27;liquidjs&#x27;</span>)</span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">&#x27;random&#x27;</span>, &#123;</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) &#123;</span><br><span class="line"> <span class="keyword">const</span> tokenizer = <span class="keyword">new</span> <span class="title class_">Tokenizer</span>(tagToken.<span class="property">args</span>)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span> = []</span><br><span class="line"> <span class="keyword">while</span> (!tokenizer.<span class="title function_">end</span>()) &#123;</span><br><span class="line"> <span class="comment">// here readValue() returns a LiteralToken or PropertyAccessToken</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span>.<span class="title function_">push</span>(tokenizer.<span class="title function_">readValue</span>())</span><br><span class="line"> &#125;</span><br><span class="line"> &#125;,</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) &#123;</span><br><span class="line"> <span class="keyword">const</span> index = <span class="title class_">Math</span>.<span class="title function_">floor</span>(<span class="variable language_">this</span>.<span class="property">items</span>.<span class="property">length</span> * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> <span class="keyword">const</span> token = <span class="variable language_">this</span>.<span class="property">items</span>[index]</span><br><span class="line"> <span class="comment">// in LiquidJS, we use yield to wait for async call</span></span><br><span class="line"> <span class="keyword">const</span> value = <span class="keyword">yield</span> <span class="title function_">evalToken</span>(token, context)</span><br><span class="line"> emitter.<span class="title function_">write</span>(value)</span><br><span class="line"> &#125;</span><br><span class="line">&#125;)</span><br></pre></td></tr></table></figure>
<p>用上下文 <code>&#123; bar: &quot;bar&quot;, obj: &#123; coo: &quot;coo&quot; &#125; &#125;</code> 来调用这个标签可以得到上第一个例子一样的效果。见这个 JSFiddle:<a target="_blank" rel="noopener external nofollow noreferrer" href="http://jsfiddle.net/ctj364up/3/">http://jsfiddle.net/ctj364up/3/</a>.</p>
<blockquote class="note info"><strong class="note-title">异步和 Promise</strong><p>在 LiquidJS 里异步用生成器实现,这样同样一份标签的实现也可以用于同步的 API 比如 <code>renderSync()</code><code>parseAndRenderSync()</code><code>renderFileSync()</code>。如果要在标签实现里等待 Promise,只需要把 <code>await somePromise</code> 换成 <code>yield somePromise</code>,并保留 <code>* render()</code> 不要改成 <code>async render()</code>。更多细节请参考 <a href="/tutorials/sync-and-async.html">Sync and Async</a></p>
</blockquote>
<h2 id="把键值对解析为命名参数" class="article-heading"><a href="#把键值对解析为命名参数" class="headerlink" title="把键值对解析为命名参数"></a>把键值对解析为命名参数<a class="article-anchor" href="#把键值对解析为命名参数" aria-hidden="true"></a></h2><p>当参数很多时或者有可选参数时,使用命名参数语法会很方便。这时参数由无序的键值对构成,LiquidJS 中的 <a href="/api/classes/Hash.html">Hash</a> 类就是来处理这种情况的。</p>
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">&#123;%</span> random from<span class="token operator">:</span><span class="token number">2</span><span class="token punctuation">,</span> to<span class="token operator">:</span>max <span class="token delimiter punctuation">%&#125;</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">&#123;% random from:2, to:max %&#125;</span><br></pre></td></tr></table></figure>
<p>上面的例子用来产生 [2, max] 范围内的随机数。我们要用 <code>Hash</code> 来解析 <code>from</code><code>to</code> 参数。</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> <span class="token punctuation">&#123;</span> Liquid<span class="token punctuation">,</span> Hash <span class="token punctuation">&#125;</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span>
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">&#123;</span>
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// 解析参数结果,存到 `this.args` 里</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>args <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Hash</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// 在当前 `context` 下计算参数的值</span>
<span class="token keyword">const</span> <span class="token punctuation">&#123;</span>from<span class="token punctuation">,</span> to<span class="token punctuation">&#125;</span> <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>args<span class="token punctuation">.</span><span class="token function">render</span><span class="token punctuation">(</span>context<span class="token punctuation">)</span>
<span class="token keyword">const</span> length <span class="token operator">=</span> to <span class="token operator">-</span> from <span class="token operator">+</span> <span class="token number">1</span>
<span class="token keyword">const</span> value <span class="token operator">=</span> from <span class="token operator">+</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span>
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> &#123; <span class="title class_">Liquid</span>, <span class="title class_">Hash</span> &#125; = <span class="built_in">require</span>(<span class="string">&#x27;liquidjs&#x27;</span>)</span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">&#x27;random&#x27;</span>, &#123;</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) &#123;</span><br><span class="line"> <span class="comment">// 解析参数结果,存到 `this.args` 里</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">args</span> = <span class="keyword">new</span> <span class="title class_">Hash</span>(tagToken.<span class="property">args</span>)</span><br><span class="line"> &#125;,</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) &#123;</span><br><span class="line"> <span class="comment">// 在当前 `context` 下计算参数的值</span></span><br><span class="line"> <span class="keyword">const</span> &#123;<span class="keyword">from</span>, to&#125; = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">args</span>.<span class="title function_">render</span>(context)</span><br><span class="line"> <span class="keyword">const</span> length = to - <span class="keyword">from</span> + <span class="number">1</span></span><br><span class="line"> <span class="keyword">const</span> value = <span class="keyword">from</span> + <span class="title class_">Math</span>.<span class="title function_">floor</span>(length * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> emitter.<span class="title function_">write</span>(value)</span><br><span class="line"> &#125;</span><br><span class="line">&#125;)</span><br></pre></td></tr></table></figure>
<p><code>&#123; max: 10 &#125;</code> 上下文上渲染 <code>&#123;% random from:2, to:max %&#125;</code> 将会得到 [2, 10] 范围内的随机数。见这个 JSFiddle:<a target="_blank" rel="noopener external nofollow noreferrer" href="http://jsfiddle.net/ctj364up/4/">http://jsfiddle.net/ctj364up/4/</a></p>
</div>
<footer class="article-footer">
<time class="article-footer-updated" datetime="2024-08-16T15:41:05.842Z" itemprop="dateModified">上次更新:2024-08-16</time>
<time class="article-footer-updated" datetime="2024-08-16T16:55:41.725Z" itemprop="dateModified">上次更新:2024-08-16</time>
<a href="access-scope-in-filters.html" class="article-footer-prev" title="过滤器里访问上下文"><i class="icon-chevron-left"></i><span>上一页</span></a><a href="render-tag-content.html" class="article-footer-next" title="渲染标签内容"><span>下一页</span><i class="icon-chevron-right"></i></a>
</footer>
</div>
@@ -201,7 +156,7 @@ engine<span class="token punctuation">.</span><span class="token function">regis
<nav id="mobile-nav">
<div id="mobile-nav-inner">
<ul id="mobile-nav-list">
<a href="intro-to-liquid.html" class="mobile-nav-link">教程</a><a href="../tags/overview.html" class="mobile-nav-link">标签</a><a href="../filters/overview.html" class="mobile-nav-link">过滤器</a><a href="../playground.html" class="mobile-nav-link">演示</a><a href="../api/classes/Liquid.html" class="mobile-nav-link">API</a>
<a href="intro-to-liquid.html" class="mobile-nav-link">教程</a><a href="../tags/overview.html" class="mobile-nav-link">标签</a><a href="../filters/overview.html" class="mobile-nav-link">过滤器</a><a href="../playground.html" class="mobile-nav-link">演示</a><a href="../../api/classes/Liquid.html" class="mobile-nav-link">API</a>
</ul>
<div class="mobile-sidebar-list">