Files
liquidjs/zh-cn/tutorials/render-file.html
T

249 lines
25 KiB
HTML

<!DOCTYPE html>
<html lang="zh-cn">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>渲染文件 | LiquidJS</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="LiquidJS is a simple, expressive and safe Shopify / Github Pages compatible template engine in pure JavaScript.">
<link rel="dns-prefetch" href="https://cdn.jsdelivr.net/">
<link rel="manifest" href="/zh-cn/manifest.json">
<!-- Canonical links -->
<link rel="canonical" href="https://liquidjs.com/zh-cn/tutorials/render-file.html">
<!-- Alternative links -->
<link rel="alternative" hreflang="en" href="https://liquidjs.com/zh-cn/tutorials/render-file">
<link rel="alternative" hreflang="zh-cn" href="https://liquidjs.com/zh-cn/zh-cn/tutorials/render-file">
<!-- Icon -->
<link rel="apple-touch-icon" sizes="57x57" href="../../icon/apple-touch-icon-57x57.png">
<link rel="apple-touch-icon" sizes="114x114" href="../../icon/apple-touch-icon-114x114.png">
<link rel="apple-touch-icon" sizes="72x72" href="../../icon/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon" sizes="144x144" href="../../icon/apple-touch-icon-144x144.png">
<link rel="apple-touch-icon" sizes="60x60" href="../../icon/apple-touch-icon-60x60.png">
<link rel="apple-touch-icon" sizes="120x120" href="../../icon/apple-touch-icon-120x120.png">
<link rel="apple-touch-icon" sizes="76x76" href="../../icon/apple-touch-icon-76x76.png">
<link rel="apple-touch-icon" sizes="152x152" href="../../icon/apple-touch-icon-152x152.png">
<link rel="icon" type="image/png" href="../../icon/favicon-196x196.png" sizes="196x196">
<link rel="icon" type="image/png" href="../../icon/favicon-160x160.png" sizes="160x160">
<link rel="icon" type="image/png" href="../../icon/favicon-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="../../icon/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="../../icon/favicon-32x32.png" sizes="32x32">
<meta name="msapplication-TileColor" content="#2f83cd">
<meta name="msapplication-TileImage" content="../../icon/mstile-144x144.png">
<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>
<body>
<div id="container">
<header id="header" class="wrapper">
<div id="header-inner" class="inner">
<h1 id="logo-wrap">
<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>
<div id="search-input-wrap">
<i id="search-input-icon" class="icon-search"></i>
<input type="search" id="search-input" placeholder="搜索...">
</div>
</nav>
<div class="main-nav-link icon-nav-link">
<label><i class="icon-network"></i> <span class="icon-nav-title">简体中文</span></label>
<select id="lang-select" data-canonical="tutorials/render-file.html">
<option value="en">English</option>
<option value="zh-cn" selected>简体中文</option>
</select>
</div>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs" class="main-nav-link icon-nav-link"><i class="icon-github"></i> <span class="icon-nav-title">Github</span></a>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://opencollective.com/liquidjs" class="main-nav-link icon-nav-link"><i class="icon-opencollective"></i> <span class="icon-nav-title">Support</span></a>
<a id="mobile-nav-toggle">
<span class="mobile-nav-toggle-bar"></span>
<span class="mobile-nav-toggle-bar"></span>
<span class="mobile-nav-toggle-bar"></span>
</a>
</div>
</header>
<div id="content-wrap">
<div id="content" class="wrapper">
<div id="content-inner">
<aside id="sidebar" role="navigation">
<div class="inner">
<strong class="sidebar-title">开始使用</strong><a href="intro-to-liquid.html" class="sidebar-link">Liquid 简介</a><a href="setup.html" class="sidebar-link">安装</a><a href="options.html" class="sidebar-link">选项</a><a href="render-file.html" class="sidebar-link current">文件渲染</a><a href="partials-and-layouts.html" class="sidebar-link">引用/继承</a><a href="use-in-expressjs.html" class="sidebar-link">Express.js 中使用</a><strong class="sidebar-title">高级主题</strong><a href="caching.html" class="sidebar-link">缓存</a><a href="register-filters-tags.html" class="sidebar-link">注册标签/过滤器</a><a href="access-scope-in-filters.html" class="sidebar-link">过滤器里访问上下文</a><a href="parse-parameters.html" class="sidebar-link">参数解析</a><a href="render-tag-content.html" class="sidebar-link">渲染标签内容</a><a href="sync-and-async.html" class="sidebar-link">同步和异步</a><a href="whitespace-control.html" class="sidebar-link">换行和缩进</a><a href="plugins.html" class="sidebar-link">插件</a><a href="operators.html" class="sidebar-link">运算符</a><a href="truthy-and-falsy.html" class="sidebar-link">真和假</a><strong class="sidebar-title">其他</strong><a href="migrate-to-9.html" class="sidebar-link">迁移到 LiquidJS 9</a><a href="changelog.html" class="sidebar-link">更新日志</a><a href="differences.html" class="sidebar-link">与 Shopify/liquid 的不同</a><a href="contribution-guidelines.html" class="sidebar-link">贡献指南</a>
</div>
</aside>
<article class="article-container" itemscope itemtype="http://schema.org/Article">
<div class="article-inner">
<div class="article">
<div class="inner">
<header class="article-header">
<h1 class="article-title" itemprop="name">渲染文件</h1>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/edit/master/docs/source/zh-cn/tutorials/render-file.md" class="article-edit-link" title="改进这篇文档"><i class="icon-pencil"></i></a>
</header>
<div class="article-content" itemprop="articleBody">
<p>一个典型的项目会有一个目录下都是模板,最方便的方式就是设置 LiquidJS 的 <a href="/api/interfaces/LiquidOptions.html#root">root</a> 然后调用 <a href="/api/classes/Liquid.html#renderFile">.renderFile()</a><a href="/api/classes/Liquid.html#renderFileSync">.renderFileSync()</a> 来渲染其中的一个模板文件。</p>
<h2 id="渲染一个文件" class="article-heading"><a href="#渲染一个文件" class="headerlink" title="渲染一个文件"></a>渲染一个文件<a class="article-anchor" href="#渲染一个文件" aria-hidden="true"></a></h2><p>例如你有如下的目录结构:</p>
<pre class="line-numbers language-none"><code class="language-none">.
├── index.js
└── views&#x2F;
├── hello.liquid
└── world.liquid<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
<p>其中 <code>hello.liquid</code> 内容为:</p>
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid">name: <span class="token liquid language-liquid"><span class="token delimiter punctuation">&#123;&#123;</span>name<span class="token delimiter punctuation">&#125;&#125;</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
<p><code>index.js</code> 中可以这样渲染 <code>hello.liquid</code>:</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">&#123;</span>
<span class="token literal-property property">root</span><span class="token operator">:</span> path<span class="token punctuation">.</span><span class="token function">resolve</span><span class="token punctuation">(</span>__dirname<span class="token punctuation">,</span> <span class="token string">'views/'</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token comment">// 设置模板查找目录</span>
<span class="token literal-property property">extname</span><span class="token operator">:</span> <span class="token string">'.liquid'</span> <span class="token comment">// 添加后缀,默认为 "" 表示不添加后缀</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// 将会读取并渲染 `views/hello.liquid`</span>
engine<span class="token punctuation">.</span><span class="token function">renderFile</span><span class="token punctuation">(</span><span class="token string">"hello"</span><span class="token punctuation">,</span> <span class="token punctuation">&#123;</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span>console<span class="token punctuation">.</span>log<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></code></pre>
<p>执行 <code>node index.js</code> 你将会得到类似这样的输出:</p>
<pre class="line-numbers language-none"><code class="language-none">name: alice<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
<h2 id="模板查找" class="article-heading"><a href="#模板查找" class="headerlink" title="模板查找"></a>模板查找<a class="article-anchor" href="#模板查找" aria-hidden="true"></a></h2><p>传递给 <a href="/api/classes/Liquid.html#renderFile">.renderFile()</a>, <a href="/api/classes/Liquid.html#parseFile">.parseFile()</a> <a href="/api/classes/Liquid.html#renderFileSync">.renderFileSync()</a>, <a href="/api/classes/Liquid.html#parseFileSync">.parseFileSync()</a> 这些 API 的模板名,<br>以及传递给 <a target="_blank" rel="noopener external nofollow noreferrer" href="https://help.shopify.com/themes/liquid/tags/theme-tags#include">include</a>, <a target="_blank" rel="noopener external nofollow noreferrer" href="https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout">layout</a> 这些标签的模板名,将会根据 <a href="/api/interfaces/LiquidOptions.html#root">root</a> 选项来查找。</p>
<p><code>root</code> 可以设置为 <code>string</code> 类型的路径(见上面的例子), 也可以设置为一个字符串数组表示路径列表,这时 LiquidJS 将会按顺序去查找。例如:</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">&#123;</span>
<span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">'views/'</span><span class="token punctuation">,</span> <span class="token string">'views/partials/'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token literal-property property">extname</span><span class="token operator">:</span> <span class="token string">'.liquid'</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
<blockquote class="note tip"><strong class="note-title">相对路径</strong><p><code>root</code> 中使用相对路径将会被解释为相对于 <code>cwd()</code>(当前工作目录)。</p>
</blockquote>
<p>当模板中引入子模板时(<code>{% render "foo" %}</code>),或者调用 <code>.renderFile(&#39;foo&#39;)</code> 时,LiquidJS 会依次查看如下几个文件,并渲染第一个存在的文件:</p>
<ul>
<li><code>cwd()</code>/views/foo.liquid</li>
<li><code>cwd()</code>/views/partials/foo.liquid</li>
</ul>
<p>如果上述文件都不存在,将会抛出一个 <code>ENOENT</code> 错误。</p>
<blockquote class="note info"><strong class="note-title">示例</strong><p>在 Node.js 示例中展示了怎么渲染一个文件 <a href="https://github.com/harttle/liquidjs/blob/master/demo/nodejs/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/nodejs/</a></p>
</blockquote>
<p>在浏览器中使用 LiquidJS 时,比如当前路径为 <a target="_blank" rel="noopener external nofollow noreferrer" href="https://example.com/bar/index.html">https://example.com/bar/index.html</a>,只会去 <code>root</code> 数组中的第一个路径下获取,也就是这个文件:</p>
<ul>
<li><a target="_blank" rel="noopener external nofollow noreferrer" href="https://example.com/bar/foo.liquid">https://example.com/bar/foo.liquid</a></li>
</ul>
<p>如果获取失败(比如得到一个 404/500 错误)或网络错误,将会抛出一个 <code>ENOENT</code> 错误。</p>
<blockquote class="note info"><strong class="note-title">示例</strong><p>在这个示例中展示了如何从网络获取并渲染一个模板文件 <a href="https://github.com/harttle/liquidjs/blob/master/demo/browser/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/browser/</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/interfaces/FS.html">src/fs/ifs.ts</a>),在 Node.js 下的默认实现是 <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/fs-impl.ts">src/fs/node.ts</a>,在浏览器打包文件中的默认实现是 <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/fs-impl-browser.ts">src/fs/browser.ts</a><br>你可以通过创建 <code>Liquid</code> 时的 <a href="/api/interfaces/LiquidOptions.html#fs">fs</a> 参数来指定一个自定义实现来指定如何读取模板文件。比如从数据库里读取:</p>
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">&#123;</span>
<span class="token literal-property property">fs</span><span class="token operator">:</span> <span class="token punctuation">&#123;</span>
<span class="token function">readFileSync</span> <span class="token punctuation">(</span><span class="token parameter">file</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">return</span> db<span class="token punctuation">.</span><span class="token function">model</span><span class="token punctuation">(</span><span class="token string">'Template'</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">findByIdSync</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span><span class="token punctuation">.</span>text
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token keyword">await</span> <span class="token function">readFile</span> <span class="token punctuation">(</span><span class="token parameter">file</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">const</span> template <span class="token operator">=</span> <span class="token keyword">await</span> db<span class="token punctuation">.</span><span class="token function">model</span><span class="token punctuation">(</span><span class="token string">'Template'</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">findById</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span>
<span class="token keyword">return</span> template<span class="token punctuation">.</span>text
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token function">existsSync</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">return</span> <span class="token boolean">true</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token keyword">await</span> <span class="token function">exists</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">return</span> <span class="token boolean">true</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token function">resolve</span><span class="token punctuation">(</span><span class="token parameter">root<span class="token punctuation">,</span> file<span class="token punctuation">,</span> ext</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">return</span> file
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">)</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></span></span></code></pre>
</div>
<footer class="article-footer">
<time class="article-footer-updated" datetime="2023-08-08T13:59:03.891Z" itemprop="dateModified">上次更新:2023-08-08</time>
<a href="options.html" class="article-footer-prev" title="选项"><i class="icon-chevron-left"></i><span>上一页</span></a><a href="partials-and-layouts.html" class="article-footer-next" title="引用/继承"><span>下一页</span><i class="icon-chevron-right"></i></a>
</footer>
</div>
</div>
<aside id="article-toc" role="navigation">
<div id="article-toc-inner">
<div id="article-toc-inner-list">
<strong class="sidebar-title">目录</strong>
<ol class="toc"><li class="toc-item toc-level-2"><a class="toc-link" href="#%E6%B8%B2%E6%9F%93%E4%B8%80%E4%B8%AA%E6%96%87%E4%BB%B6"><span class="toc-text">渲染一个文件</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#%E6%A8%A1%E6%9D%BF%E6%9F%A5%E6%89%BE"><span class="toc-text">模板查找</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#%E6%96%87%E4%BB%B6%E7%B3%BB%E7%BB%9F%E6%8E%A5%E5%8F%A3"><span class="toc-text">文件系统接口</span></a></li></ol>
</div>
<a href="#" id="article-toc-top">回到顶部</a>
</div>
</aside>
</div>
</article>
</div>
</div>
</div>
<footer id="footer" class="wrapper">
<div class="inner">
<div id="footer-copyright">
&copy; 2023 <a href="https://github.com/harttle/liquidjs/graphs/contributors" rel="external nofollow noreferrer" target="_blank">Harttle</a><br>
本文档通过 <a href="http://creativecommons.org/licenses/by/4.0/" rel="external nofollow noreferrer" target="_blank">CC BY 4.0</a> 授权。
</div>
<div id="footer-links">
<a href="https://twitter.com/harttleharttle" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-twitter"></i></a>
<a href="https://opencollective.com/liquidjs" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-opencollective"></i></a>
<a href="https://github.com/harttle/liquidjs" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-github"></i></a>
</div>
</div>
</footer>
</div>
<div id="mobile-nav-dimmer"></div>
<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>
</ul>
<div class="mobile-sidebar-list">
<strong class="mobile-nav-title">开始使用</strong><a href="intro-to-liquid.html" class="mobile-nav-link">Liquid 简介</a><a href="setup.html" class="mobile-nav-link">安装</a><a href="options.html" class="mobile-nav-link">选项</a><a href="render-file.html" class="mobile-nav-link current">文件渲染</a><a href="partials-and-layouts.html" class="mobile-nav-link">引用/继承</a><a href="use-in-expressjs.html" class="mobile-nav-link">Express.js 中使用</a><strong class="mobile-nav-title">高级主题</strong><a href="caching.html" class="mobile-nav-link">缓存</a><a href="register-filters-tags.html" class="mobile-nav-link">注册标签/过滤器</a><a href="access-scope-in-filters.html" class="mobile-nav-link">过滤器里访问上下文</a><a href="parse-parameters.html" class="mobile-nav-link">参数解析</a><a href="render-tag-content.html" class="mobile-nav-link">渲染标签内容</a><a href="sync-and-async.html" class="mobile-nav-link">同步和异步</a><a href="whitespace-control.html" class="mobile-nav-link">换行和缩进</a><a href="plugins.html" class="mobile-nav-link">插件</a><a href="operators.html" class="mobile-nav-link">运算符</a><a href="truthy-and-falsy.html" class="mobile-nav-link">真和假</a><strong class="mobile-nav-title">其他</strong><a href="migrate-to-9.html" class="mobile-nav-link">迁移到 LiquidJS 9</a><a href="changelog.html" class="mobile-nav-link">更新日志</a><a href="differences.html" class="mobile-nav-link">与 Shopify/liquid 的不同</a><a href="contribution-guidelines.html" class="mobile-nav-link">贡献指南</a>
</div>
</div>
<div id="mobile-button-list">
<a href="https://github.com/harttle/liquidjs" class="mobile-nav-link" rel="external" target="_blank"><i class="icon-github"></i></a>
<a href="https://opencollective.com/liquidjs" class="mobile-nav-link" rel="external" target="_blank"><i class="icon-opencollective"></i></a>
<div id="mobile-lang-select-wrap" class="mobile-nav-link">
<label for="mobile-lang-select"><i class="icon-network"></i></label>
<select id="mobile-lang-select" data-canonical="tutorials/render-file.html">
<option value="en">English</option>
<option value="zh-cn" selected>简体中文</option>
</select>
</div>
</div>
</nav>
<script src="../../js/main.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
document.getElementById('search-input-wrap').classList.add('on');
docsearch({
apiKey: '01f36cc168657a26a385308b9e721bc6',
indexName: 'liquidjs',
inputSelector: '#search-input',
debug: false
});
</script>
</body>
</html>