search.xml

<?xml version="1.0" encoding="utf-8"?>
<search> 
  
  
    
    <entry>
      <title>Day 30：使用 Parchment 實現類似 Medium 的編輯器 - Videos &amp; Tweets</title>
      <link href="/2023/10/15/quill-day-30/"/>
      <url>/2023/10/15/quill-day-30/</url>
      
        <content type="html"><![CDATA[<p>今天來到了挑戰的最後一天，接著把剩下的 Videos 和 Tweets 等自訂 Blot 體驗一遍。</p><h2 id="Videos"><a href="#Videos" class="headerlink" title="Videos"></a>Videos</h2><p>我們將以和 images 的實現方式來實現 Videos。從第一個直覺或許可以使用 HTML 的 <code>&lt;video&gt;</code> 標籤，但我們無法用這種方式來播放 Youtube 的影片，考慮到 Youtube 影片是目前主流看影片的其中一種方式，我們就用 <code>&lt;iframe&gt;</code> 標籤來實現。如果希望多個 Blot 使用相同的標籤，除了 <code>tagName</code> 之外，我們還可以使用 <code>className</code>，下一個 Tweets 練習會示範這個部分。</p><p>另外，我們將支援對寬度與高度，作為未註冊的 Formats。特定於 Embeds 的 Formats 不需要單獨註冊，只要它們與已註冊的 Formats 沒有命名空間的衝突即可。這樣可以運作是因為 Blots 只是將未知的 Foramts 傳遞給其子元素，最終達到葉節點。這也允許不同的 Embeds 以不同的方式處理未註冊的 Formats。例如，我們之前的插入圖片可能會跟我們在這裡的 Videos 以不同的方式來識別和處理寬度格式。</p><pre><code class="typescript">export class VideoBlot extends BlockEmbed &#123;  static blotName = &#39;myVideo&#39;;  static tagName = &#39;iframe&#39;;  static create(value: &#123; url: string &#125;) &#123;    const node = super.create();    node.setAttribute(&#39;src&#39;, value.url);    // Set non-format related attributes with static values    node.setAttribute(&#39;frameborder&#39;, &#39;0&#39;);    node.setAttribute(&#39;allowfullscreen&#39;, &#39;true&#39;);    return node;  &#125;  static formats(node: HTMLIFrameElement): Format &#123;    let format: Format = &#123;&#125;;    if (node.hasAttribute(&#39;height&#39;)) &#123;      format[&#39;height&#39;] = node.getAttribute(&#39;height&#39;)!;    &#125;    if (node.hasAttribute(&#39;width&#39;)) &#123;      format[&#39;width&#39;] = node.getAttribute(&#39;width&#39;)!;    &#125;    return format;  &#125;  static value(node: HTMLImageElement) &#123;    return node.getAttribute(&#39;src&#39;);  &#125;  format(name: string, value: number | string) &#123;    // Handle unregistered embed formats    if (name === &#39;height&#39; || name === &#39;width&#39;) &#123;      if (value) &#123;        this[&#39;domNode&#39;].setAttribute(name, value);      &#125; else &#123;        this[&#39;domNode&#39;] .removeAttribute(name, value);      &#125;    &#125; else &#123;      super.format(name, value);    &#125;  &#125;&#125;</code></pre><p>新增 VideoBlot 之後，和前面幾次練習一樣，註冊到 Quill，並且加上對應的 Click Event 到 Component：</p><pre><code class="html">  &lt;button type=&quot;button&quot; title=&quot;video&quot; id=&quot;video-button&quot; (click)=&quot;addVideo()&quot;&gt;    &lt;i class=&quot;fa fa-play&quot;&gt;&lt;/i&gt;  &lt;/button&gt;</code></pre><pre><code class="typescript">  registerBasicFormatting() &#123;    // ...    Quill.register(VideoBlot);  &#125;  addVideo() &#123;    const range = this.quillInstance.getSelection(true);    this.quillInstance.insertText(range.index, &#39;\n&#39;, Quill.sources.USER);    this.quillInstance.insertEmbed(range.index + 1, &#39;myVideo&#39;, &#123;      url: &#39;https://www.youtube.com/embed/QHH3iSeDBLo&#39;,    &#125;);    this.quillInstance.formatText(range.index + 1, 1, &#123;      height: &#39;170&#39;,      width: &#39;400&#39;,    &#125;);    this.quillInstance.setSelection(      &#123; index: range.index + 2, length: 0 &#125;,      Quill.sources.SILENT    );  &#125;</code></pre><p>點擊按鈕嵌入 Youtube 影片之後，可以看到編輯器的內容加了一個 <code>iframe</code> 標籤：</p><p><img src="/2023/10/15/quill-day-30/20090749bmGrHQyGj4.png" alt="編輯器的內容加了一個 `iframe` 標籤"></p><p>如果打開 dev tool 使用 <code>getContents</code> 方法來查看編輯器內容，Quill 會回傳 Video 的 Delta 內容像這樣：</p><pre><code class="json">&#123;  ops: [&#123;    insert: &#123;      video: &#39;https://www.youtube.com/embed/QHH3iSeDBLo?showinfo=0&#39;    &#125;,    attributes: &#123;      height: &#39;170&#39;,      width: &#39;400&#39;    &#125;  &#125;]&#125;</code></pre><h2 id="Tweets"><a href="#Tweets" class="headerlink" title="Tweets"></a>Tweets</h2><p>Medium 支援多種嵌入類型，但我們練習就只專注於 Tweets。Tweet Blot 的實現方式與 images 幾乎完全相同。我們利用 Embed Blots 不一定要對應到一個空（void）節點的行為。它可以是任何自定義的節點，Quill 會將其視為一個空節點，而不遍歷其子節點或後代節點。這使我們可以使用一個 <code>&lt;div&gt;</code>，並讓原生的 Twitter Javascript 函式庫在我們指定的 <code>&lt;div&gt;</code> 容器內運作。</p><p>由於我們的根 Scroll Blot 也使用了一個 <code>&lt;div&gt;</code>，所以我們還指定了一個 className 來消除歧義。需要注意的是，Inline Blots 預設使用 <code>&lt;span&gt;</code>，而 Block Blots 預設使用 <code>&lt;p&gt;</code>。因此，如果想讓自定義的 Blots 使用這些標籤，除了指定 <code>tagName</code> 之外，還要帶上一個 <code>className</code>。</p><p>我們使用 Tweet id 作為定義我們 Blot 的值。同樣的，在 Click Event handler 一樣帶入固定值來方便練習。</p><pre><code class="typescript">export class TweetBlot extends BlockEmbed &#123;  static blotName = &#39;myTweet&#39;;  static tagName = &#39;div&#39;;  static className = &#39;tweet&#39;;  static create(id: string) &#123;    const node = super.create();    node.dataset.id = id;    // Allow twitter library to modify our content    twttr.widgets.createTweet(id, node);    return node;  &#125;  static value(domNode: HTMLElement) &#123;    return domNode.dataset[&#39;id&#39;];  &#125;&#125;</code></pre><p>上面這個範例程式中，如果直接加上 <code>twttr</code> 應該會出現 TypeScript 不認得的錯誤訊息，<code>twttr</code> 是 Twitter platform widgets.js 函式庫提供的，因此我們這邊就先使用 <code>declare</code> any 來定義它的型別：</p><pre><code class="typescript">declare var twttr: any;</code></pre><p>此外，我們還需要加上 Twitter widgets 的 JS script，這邊我們可以利用 Angular 提供的 <code>Renderer2</code> 來插入外部的 <code>script</code>，當然也可以直接在 <code>index.html</code> 的檔案上加入：</p><pre><code class="typescript">import &#123; CommonModule, DOCUMENT &#125; from &#39;@angular/common&#39;;import &#123;  AfterViewInit,  Component,  ElementRef,  Inject,  OnInit,  Renderer2,  SecurityContext,  ViewChild,&#125; from &#39;@angular/core&#39;;// ...Component  constructor(    // ...    private renderer: Renderer2,    @Inject(DOCUMENT) private document: Document  ) &#123;&#125;  ngOnInit(): void &#123;    const script = this.renderer.createElement(&#39;script&#39;);    script.type = &#39;text/javascript&#39;;    script.src = &#39;https://platform.twitter.com/widgets.js&#39;;    script.async = true;    script.charset = &#39;utf-8&#39;;    this.renderer.appendChild(this.document.body, script);  &#125;</code></pre><p>建立好 TweetBlot 之後，我們一樣進行 Quill 註冊以及綁定 click event 對應的按鈕：</p><pre><code class="html">  &lt;button type=&quot;button&quot; title=&quot;tweet&quot; id=&quot;tweet-button&quot; (click)=&quot;addTweet()&quot;&gt;    &lt;i class=&quot;fa-brands fa-twitter&quot;&gt;&lt;/i&gt;  &lt;/button&gt;</code></pre><p>使用 Quill Instance 提供的方法取得游標位置，並插入 TweetBlot 的區塊：</p><pre><code class="typescript">  registerBasicFormatting() &#123;    // ...    Quill.register(TweetBlot);  &#125;  addTweet() &#123;    const range = this.quillInstance.getSelection(true);    const id = &#39;464454167226904576&#39;;    this.quillInstance.insertText(range.index, &#39;\n&#39;, Quill.sources.USER);    this.quillInstance.insertEmbed(      range.index + 1,      &#39;myTweet&#39;,      id,      Quill.sources.USER    );    this.quillInstance.setSelection(      &#123; index: range.index + 2, length: 0 &#125;,      Quill.sources.SILENT    );  &#125;</code></pre><p>點擊後的效果：</p><p><img src="/2023/10/15/quill-day-30/20090749OJWSQiyGaN.png" alt="點擊後的效果"></p><h2 id="最後的潤色"><a href="#最後的潤色" class="headerlink" title="最後的潤色"></a>最後的潤色</h2><p>我們從一堆按鈕和只能理解純文本的 Quill 核心開始。通過 Parchment，我們能夠添加粗體、斜體、連結、引用區塊、標題、分隔線、圖片、影片，甚至是 Tweets。所有這些都能在維持一個可預測且一致性的文件實現，這使我們能夠使用 Quill 的 API 來處理這些新的格式和內容。</p><p>讓我們為這個範例加上一些最後的潤色。雖然它不能與 Medium 的 UI 相比，但還是盡可能的去貼近它。</p><p>最後的效果，當選擇文本時會顯示工具列：</p><p><img src="/2023/10/15/quill-day-30/20090749aoYxsaa9cE.png" alt="顯示工具列"></p><p>游標換行之後停在最前面的時候顯示插入內容按鈕，點擊之後可以展開內容：</p><p><img src="/2023/10/15/quill-day-30/200907499NssOAmiEm.png" alt="點擊之後可以展開內容"></p><p>具體的程式碼變更可以參考對應的 commit 紀錄。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>終於來到了第 30 天，最後用了這個練習把 Quill 的東西初步都摸過了一遍。今天把剩下的練習像是 Video, Tweets 這些自訂的 Blot 插入，並把整個 UI 改成像是 Medium 的編輯器風格。從中學到不少東西，也因為很久沒碰 Angular，有一些對我來說可能是新的東西也派上用場，目前的實現並不是最好的實現方式，因為官方提供的範例是直接用 jQuery，那我想在 Angular 專案的話，應該要透過 Angular 的生態系統下來實現正確的 UI 操作方式，這個未來可以在持續的探討。同時有機會的話也可以改成 Signal 的版本 XD</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天下午繼續參加週末的 MNH 社群日，遇到很多低等的會想挑戰高階的魔物，想挑戰的心態值得嘉許，但更多的可能是想蹭並獲取材料，對於等級可能剛剛好可以應付魔物的玩家，如果遇到這樣的情況就會很尷尬，因為不一定能夠扛著住，所以現在加入一個組隊之後，都要先觀望一下隊友的等級，才知道這場會不會又整個翻車，畢竟藥水真的不便宜 QQ</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/87471dd20edfb511016b37facb434a65c25499f6">今日份的練習：加入 Videos, Tweets</a></li><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/4bc1769ecf17e035cd0a56d4555fb1f03e81ea6d">今日份的練習：改成 Medium like UI</a></li><li><a href="https://quilljs.com/guides/cloning-medium-with-parchment/#videos">Cloning Medium with Parchment - Quill (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10340029">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 29：使用 Parchment 實現類似 Medium 的編輯器 - Dividers &amp; Images</title>
      <link href="/2023/10/14/quill-day-29/"/>
      <url>/2023/10/14/quill-day-29/</url>
      
        <content type="html"><![CDATA[<p>昨天體驗了基本的行內格式 Blot 以及區塊格式 Blot，今天繼續實現類似 Medium 編輯器的最後四個部分，分別為分隔線、圖片、影片、以及推文的自訂功能實現。</p><h2 id="分隔線-Dividers"><a href="#分隔線-Dividers" class="headerlink" title="分隔線 (Dividers)"></a>分隔線 (Dividers)</h2><p>接下來的步驟中，我們將實作第一個所謂的「葉子 Blot (Leaf Blot) 」。不同於先前我們練習過的 Blot，這些主要是負責文本格式化—例如定義文字的外觀或調整排列，並實作<code>format()</code>方法。Leaf Blot 的主要職責則是提供特定的內容，並透過實作 <code>value()</code> 方法來達成。</p><p>Leaf Blot 可以是文本 (Text) 型態或嵌入 (Embed) 型態的 Blot。在本例中，我們會實作一個屬於嵌入型態的 Blot，即分隔線 (Divider)。值得注意的是，一旦 Embed Blot 建立，其內含的值將會是不可變的 (Immutable) 。因此，如果你需要變更這個 Blot 的內容，則必須先將其從文本中刪除，再重新插入新的內容。</p><p>首先我們新增一個 TS 檔當作 Leaf Blot 的練習，並加入 Divider 的 Blot：</p><pre><code class="typescript">import Quill from &#39;quill&#39;;const BlockEmbed = Quill.import(&#39;blots/block/embed&#39;);export class DividerBlot extends BlockEmbed &#123;  static blotName = &#39;myDivider&#39;;  static tagName = &#39;hr&#39;;&#125;</code></pre><p>我們的 click handler 呼叫了 <code>insertEmbed()</code> 方法，這個方法不像 <code>format()</code> 那麼方便可以確定、保存和恢復使用者的選擇區域。因此我們需要自行做一些額外的工作來維護這個選擇區域。此外，當我們嘗試在一個 Block 的中間插入一個 Block Embed 時，Quill 會自動為我們將該 Block 分割開來。為了讓這個行為更為明確，我們會在插入分隔線之前明確地插入一個換行符，以自行分割該 Block。</p><p>建立 DividerBlot 之後，回到 Component 註冊 DividerBlot 並新增 <code>addDivider</code> 方法：</p><pre><code class="typescript">registerBasicFormatting() &#123;  // ...  // Leaf blot  Quill.register(DividerBlot);&#125;addDivider() &#123;  const range = this.quillInstance.getSelection(true);  this.quillInstance.insertText(range.index, &#39;\n&#39;, Quill.sources.USER)  this.quillInstance.insertEmbed(    range.index + 1,    &#39;myDivider&#39;,    true,    Quill.sources.USER  );    this.quillInstance.setSelection(    &#123; index: range.index + 2, length: 0 &#125;,    Quill.sources.SILENT  );&#125;</code></pre><p>接著將對應的 button 加上事件綁定：</p><pre><code class="html">  &lt;button    type=&quot;button&quot;    title=&quot;divider&quot;    id=&quot;divider-button&quot;    (click)=&quot;addDivider()&quot;  &gt;    &lt;i class=&quot;fa fa-minus&quot;&gt;&lt;/i&gt;  &lt;/button&gt;</code></pre><p>輸入兩行 Hello World 之後，游標停留在第一行的 Hello 後面，並點擊加入分隔線，可以看到 HTML 被強制換行後加入分隔線：</p><p><img src="/2023/10/14/quill-day-29/20090749xs4eCKsO7y.png" alt="強制換行後加入分隔線"></p><h2 id="圖片"><a href="#圖片" class="headerlink" title="圖片"></a>圖片</h2><p>圖片的處理可以使用我們在建立 Link 和 Divider blots 時所學到的概念來新增。我們會使用一個物件作為圖片的值來展示如何被支援的。我們用於插入圖像的 click handler 直接帶入 hardcode 的內容來專注在插入圖片 Blot 的實現。</p><p>建立 ImageBlot，分別有 <code>create</code> 以及 <code>value</code> 兩個靜態方法：</p><pre><code class="typescript">export class ImageBlot extends BlockEmbed &#123;  static blotName = &#39;myImage&#39;;  static tagName = &#39;img&#39;;    static create(value: &#123; alt: string; url: string &#125;) &#123;    const node = super.create();    node.setAttribute(&#39;alt&#39;, value.alt);    node.setAttribute(&#39;src&#39;, value.url);    return node;  &#125;  static value(node: HTMLImageElement) &#123;    return &#123;      alt: node.getAttribute(&#39;alt&#39;),      url: node.getAttribute(&#39;src&#39;),    &#125;;  &#125;&#125;</code></pre><p>接著在 Component 加上插入圖片的 handler，並綁定到對應的 button：</p><pre><code class="html">&lt;button type=&quot;button&quot; title=&quot;image&quot; id=&quot;image-button&quot; (click)=&quot;addImage()&quot;&gt;  &lt;i class=&quot;fa fa-camera&quot;&gt;&lt;/i&gt;&lt;/button&gt;</code></pre><pre><code class="typescript">addImage() &#123;    const range = this.quillInstance.getSelection(true);    this.quillInstance.insertText(range.index, &#39;\n&#39;, Quill.sources.USER);    this.quillInstance.insertEmbed(      range.index + 1,      &#39;image&#39;,      &#123;        alt: &#39;Quill Cloud&#39;,        url: &#39;https://quilljs.com/0.20/assets/images/cloud.png&#39;,      &#125;,      Quill.sources.USER    );    this.quillInstance.setSelection(      &#123; index: range.index + 2, length: range.length &#125;,      Quill.sources.SILENT    );  &#125;</code></pre><p>看一下加入圖片後的效果：</p><p><img src="/2023/10/14/quill-day-29/20090749KoNw5w1Re2.png" alt="加入圖片後的效果"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天主要就兩個 Embed Blot 的實現，我們透過繼承 Quill 底下的 Parchment Embed Blot 來建立自定義的 Blot，對於 Quill 的方法及應用有比較深入的理解。 整體的實現上都是與 DOM 去做對應在編輯器中加入內容，因此都會經過 <code>Create()</code> 方法來新增 DOM，如果是簡單的 HTML，沒有太多的加工處理，則直接帶上 <code>blotNmae</code> 和 <code>tagName</code> 即可，按照官網文件的說明，Quill 的確也讓編輯器的內容與結構盡可能的單純易懂。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>這個週末是魔物獵人 Now 的社群日，有期間限定的櫻火龍，貌似對拿弓箭的玩家來說是不錯的裝備材料收集，準備好今天的文章之後，等等就要出去晃晃，希望不會太快就把藥水喝完 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/02143d0c84a93c8c4a6e254fb52e083bc6a100e4">今日份的練習</a></li><li><a href="https://quilljs.com/guides/cloning-medium-with-parchment/#dividers">Cloning Medium with Parchment - Quill (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10339493">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 28：使用 Parchment 實現類似 Medium 的編輯器 - Basic Formatting &amp; myBlot</title>
      <link href="/2023/10/13/quill-day-28/"/>
      <url>/2023/10/13/quill-day-28/</url>
      
        <content type="html"><![CDATA[<p>昨天我們新增了一個元件並初始化 Quill 的核心，今天繼續實現 Medium 編輯器的練習。</p><h2 id="實作基礎格式"><a href="#實作基礎格式" class="headerlink" title="實作基礎格式"></a>實作基礎格式</h2><p>我們之前提到過，Inline 不貢獻任何格式。這是為 Inline 基礎類別所制定的例外，而不是規則。基本的 block Blot 和區塊級的元素 (Block level element) 的運作方式相同。<br>要實作粗體和斜體，我們只需要繼承 Inline，設定 blotName 和 tagName，並註冊到 Quill 中即可。有關繼承和靜態方法和變數的內容介紹可以參考 Parchment 的介紹。</p><pre><code class="typescript">import Quill from &#39;quill&#39;;const Inline = Quill.import(&#39;blots/inline&#39;);export class BoldBlot extends Inline &#123;  static blotName = &#39;myBold&#39;;  static tagName = &#39;strong&#39;;&#125;export class ItalicBlot extends Inline &#123;  static blotName = &#39;myItalic&#39;;  static tagName = &#39;em&#39;;&#125;</code></pre><p>這裡跟著 Medium 的範例使用 <code>Strong</code> 以及 <code>em</code> 標籤，但我們也可以使用 <code>b</code> 和 <code>i</code> 標籤。Quill 將使用 blot 的名稱當作格式名稱，透過註冊我們的 Blot，我們現在可以在新格式上使用 Quill 的完整 API：</p><pre><code class="typescript">ngAfterViewInit(): void &#123;  this.registerBasicFormatting();  this.quillInstance = new Quill(this.editorContainer.nativeElement);&#125;registerBasicFormatting() &#123;  Quill.register(BoldBlot);  Quill.register(ItalicBlot);&#125;insertText() &#123;  this.quillInstance.insertText(0, &#39;Test&#39;, &#123; myBold: true &#125;);&#125;formatText() &#123;  this.quillInstance.formatText(0, 4, &#39;myItalic&#39;, true);&#125;</code></pre><p>接著將按鈕的 <code>click</code> 事件加上，這邊為了示範方便，我們直接寫死一個 <code>true</code> 在程式裡面，這樣就會一直是加上格式的操作。在 App 中，我們可以使用 <code>getFormat()</code> 來尋找指定範圍內的文本格式，來決定是否新增或刪除格式。Toolbar 模組因為 Quill 已經實現了，就不在這重新實作。</p><p>兩個按鈕都點擊之後的效果如下：<br><img src="/2023/10/13/quill-day-28/20090749XSOo5OU7wF.png" alt="都點擊之後的效果"></p><h2 id="實作連結-Link"><a href="#實作連結-Link" class="headerlink" title="實作連結 (Link)"></a>實作連結 (Link)</h2><p>與其他格式（如粗體或斜體）不同，Link 需要存入更多資訊，特別是 URL。這主要影響到「Link blot」的兩個方面：建立和格式檢索。</p><ol><li><strong>建立（Creation）</strong>: 當建立一個 Link 時，除了表示它是一個 Link 外，還需要加上 URL。這通常會以字串的形式來表示。</li><li><strong>格式檢索（Format Retrieval）</strong>: 當需要找出或修改一個已存在的 Link 格式時，除了知道它是一個Link 外，我們還需要取得或修改 Link 的 URL。</li></ol><p>雖然 URL 通常以字串的型別存入，但也可以用其他方式來表示，例如以一個包含 URL Key value 的物件。這樣做可以允許我們加入其他的 Key&#x2F;Value 來定義一個連結，提供更多自定義的選項。</p><p>新增一個 Link Blot：</p><pre><code class="typescript">export class LinkBlot extends Inline &#123;  static blotName = &#39;myLink&#39;;  static tagName = &#39;a&#39;;  static create(value: string) &#123;    let node = super.create();    // Sanitize url value if desired    node.setAttribute(&#39;href&#39;, value);    // Okay to set other non-format related attributes    // These are invisible to Parchment so must be static    node.setAttribute(&#39;target&#39;, &#39;_blank&#39;);    return node;  &#125;  static formats(node: HTMLElement) &#123;    // We will only be called with a node already    // determined to be a Link blot, so we do    // not need to check ourselves    return node.getAttribute(&#39;href&#39;);  &#125;&#125;</code></pre><p>Component 加入新的註冊和方法：</p><pre><code class="typescript">registerBasicFormatting() &#123;  Quill.register(BoldBlot);  Quill.register(ItalicBlot);  Quill.register(LinkBlot);&#125;</code></pre><p>考慮到安全性，這裡我們可以在 <code>constructor</code> 注入 Angular 提供的 <code>DomSanitizer</code> “消毒” (sanitize)輸入的 URL 避免 XSS 問題發生：</p><pre><code class="typescript">constructor(private sanitizer: DomSanitizer) &#123;&#125;addLink() &#123;  const url = prompt(&#39;請輸入 URL&#39;);  const safeUrl = this.sanitizer.sanitize(SecurityContext.URL, url);  this.quillInstance.format(&#39;myLink&#39;, safeUrl);&#125;</code></pre><p>接著嘗試選取文本內容，並點擊加入連結的按鈕，輸入網址後可以看到效果：</p><p><img src="/2023/10/13/quill-day-28/20090749DdXqJnTjSl.png" alt="加入連結效果"></p><h2 id="區塊引用-Blockquote-與標題-Headers"><a href="#區塊引用-Blockquote-與標題-Headers" class="headerlink" title="區塊引用 (Blockquote) 與標題 (Headers)"></a>區塊引用 (Blockquote) 與標題 (Headers)</h2><p>Blockquotes 繼承自 Block，這是基本的 Block Blot（一種自定義的文本塊）。與 Inline blots 不同的是，Block Blots 不能被嵌套。如果對同一範圍的文字套用多個 Block blots，它們不會互相包裹，而是會相互替換。也就是說，新套用的 Block Blot 會取代原有的 Block Blot。</p><p>建立 BlockquoteBlot：</p><pre><code class="typescript">const Block = Quill.import(&#39;blots/block&#39;);export class BlockquoteBlot extends Block &#123;  static blotName = &#39;myBlockquote&#39;;  static tagName = &#39;blockquote&#39;;&#125;</code></pre><p>註冊 Blot：</p><pre><code class="typescript">Quill.register(BlockquoteBlot);</code></pre><p>Header 的實作方式完全相同，只有一處不同：它可以由多個 DOM 元素表示。預設情況下，格式的值將成為 tagName，而不僅僅是 true。我們可以透過擴充 formats() 來自訂，類似於我們對連結所做的那樣：</p><pre><code class="typescript">export class HeaderBlot extends Block &#123;  static blotName = &#39;myHeader&#39;;  static tagName = [&#39;H1&#39;, &#39;H2&#39;];  static formats(node: HTMLElement) &#123;    return HeaderBlot.tagName.indexOf(node.tagName) + 1;  &#125;&#125;</code></pre><p>為了方便測試，加入 CSS 的部分：</p><pre><code class="scss">::ng-deep h1, ::ng-deep h2 &#123;  margin-top: 0.5em;  color: purple;&#125;::ng-deep blockquote &#123;  border-left: 4px solid #111;  padding-left: 1em;&#125;</code></pre><p>最後在 Component 加入 event function，再和 template 的 <code>click</code> 事件綁定：</p><pre><code class="typescript">addBlockquote() &#123;  this.quillInstance.format(&#39;myBlockquote&#39;, true);&#125;addHeader1() &#123;  this.quillInstance.format(&#39;myHeader&#39;, 1);&#125;addHeader2() &#123;  this.quillInstance.format(&#39;myHeader&#39;, 2);&#125;</code></pre><p>輸入不同段落的內容後，點擊按鈕試試看套用格式效果，可以看到對應的 HTML 元素也被成功加入了，並且套用了設定好的 CSS Style：</p><p><img src="/2023/10/13/quill-day-28/200907499JOpQmtui3.png" alt="套用了設定好的 CSS Style"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天嘗試跟著實現自訂的 Inline Blot 和 Block Blot，實際操作過一遍會比較有感覺，官方文件提供的範例是 JavaScript，那我們就直接以 Angular 的專案當作練習，以 Angular 的方式來實現對應的功能。對於自訂的 Blot 內容有進一步的理解，明天再接著練習後面的其他功能。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>轉眼間就來到第 28 天了，時間真的過的很快，也平安度過試用期(?)。但對於很多細節和產業的觀念還是持續學習中，白天工作內容的轟炸與考古，晚上則持續學習及寫文章做紀錄，上週的連假則是邊出去旅遊，回到住宿的地方後，繼續準備文章內容，腦袋裝了滿滿的東西。生活的節奏也比以往要快了許多，從進辦公室開始工作，回過神來就快下班了，除了充實，還是充實 XD…</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/0a2256e1d4601c4e5c8a388572cc03ce5c77e7ec">今日份的練習</a></li><li><a href="https://quilljs.com/guides/cloning-medium-with-parchment/">Cloning Medium with Parchment - Quill (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10338783">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 27：使用 Parchment 實現類似 Medium 的編輯器 - 準備工作</title>
      <link href="/2023/10/12/quill-day-27/"/>
      <url>/2023/10/12/quill-day-27/</url>
      
        <content type="html"><![CDATA[<p>昨天透過 Parchement 新增了三種不同的 Attributor，今天來看要如何在編輯器上運用。官方文件介紹嘗試實現一個類似 Medium 的功能編輯器，今天就來逐步練習看看。</p><h2 id="實現-Medium-編輯器"><a href="#實現-Medium-編輯器" class="headerlink" title="實現 Medium 編輯器"></a>實現 Medium 編輯器</h2><p>為了提供一致的編輯體驗，我們需要同時具有一致的資料及可預測的行為，然而這兩項是 DOM 都沒有的。現代編輯器的解決方案是維護自己的文件模型來表示其內容。對於 Quill 來說，Parchment 就是這樣的一個解決方案。它在自己的 library 中有組織的架構，並有屬於自己的 API。透過 Parchment，我們就可以自定義 Quill 能夠識別的內容與格式，或者加入全新的格式。</p><p>在官網這份指南中，我們將使用 Parchment 和 Quill 提供的基礎模組來複製 Medium 上的編輯器。我們將從 Quill 的最基本架構開始，不涉及任何 Theme，額外的模組或格式。在這個基礎上，Quill 只能理解純文本。但跟著這份指南做到最後，連結，影片甚至推文都能被 Quill 所辨別。</p><h2 id="準備工作"><a href="#準備工作" class="headerlink" title="準備工作"></a>準備工作</h2><p>剛開始我們不使用 Quill，而只需要 <code>textarea</code> 及按鈕。並且將按鈕加上 event listener。文件的介紹是使用 jQuery 來實現，但我們就直接在 Angular 專案下來做這個練習囉。另外還需要  <a href="https://fonts.google.com/">Google Fonts</a> 和 <a href="https://fontawesome.io/">Font Awesome</a> 為練習的專案加上一些基本樣式。這些都和 Quill 或 Parchment 沒有直接關係，這部分就快速帶過。首先新增一個練習用的 Component，之後分別將 HTML 以及 CSS 加到 Component。</p><p>HTML ：</p><pre><code class="html">&lt;p&gt;medium-editor works!&lt;/p&gt;&lt;div #tooltipControls class=&quot;tooltip-controls&quot;&gt;  &lt;button id=&quot;bold-button&quot; (click)=&quot;formatBold()&quot;&gt;    &lt;i class=&quot;fa fa-bold&quot;&gt;&lt;/i&gt;  &lt;/button&gt;  &lt;button id=&quot;italic-button&quot;&gt;&lt;i class=&quot;fa fa-italic&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;link-button&quot;&gt;&lt;i class=&quot;fa fa-link&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;blockquote-button&quot;&gt;&lt;i class=&quot;fa fa-quote-right&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;header-1-button&quot;&gt;&lt;i class=&quot;fa fa-header&quot;&gt;&lt;/i&gt;&lt;sub&gt;1&lt;/sub&gt;&lt;/button&gt;  &lt;button id=&quot;header-2-button&quot;&gt;&lt;i class=&quot;fa fa-header&quot;&gt;&lt;/i&gt;&lt;sub&gt;2&lt;/sub&gt;&lt;/button&gt;&lt;/div&gt;&lt;div class=&quot;sidebar-controls&quot;&gt;  &lt;button id=&quot;image-button&quot;&gt;&lt;i class=&quot;fa fa-camera&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;video-button&quot;&gt;&lt;i class=&quot;fa fa-play&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;tweet-button&quot;&gt;&lt;i class=&quot;fa-brands fa-twitter&quot;&gt;&lt;/i&gt;&lt;/button&gt;  &lt;button id=&quot;divider-button&quot;&gt;&lt;i class=&quot;fa fa-minus&quot;&gt;&lt;/i&gt;&lt;/button&gt;&lt;/div&gt;&lt;textarea  class=&quot;editor-container&quot;  placeholder=&quot;Tell your story...&quot;  #editorContainer&gt;&lt;/textarea&gt;</code></pre><p>CSS：</p><pre><code class="scss">* &#123;  box-sizing: border-box;&#125;.editor-container &#123;  display: block;  font-family: &#39;Open Sans&#39;, Helvetica, sans-serif;  font-size: 1.2em;  height: 200px;  margin: 0 auto;  width: 450px;&#125;.tooltip-controls, .sidebar-controls &#123;  text-align: center;&#125; button &#123;  background: transparent;  border: none;  cursor: pointer;  display: inline-block;  font-size: 18px;  padding: 0;  height: 32px;  width: 32px;  text-align: center;&#125;button:active, button:focus &#123;  outline: none;&#125;</code></pre><p>Component 我們只加了一個 <code>formatBold</code> 方法來和 template 做事件綁定：</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; CommonModule &#125; from &#39;@angular/common&#39;;@Component(&#123;  selector: &#39;app-medium-editor&#39;,  standalone: true,  imports: [CommonModule],  templateUrl: &#39;./medium-editor.component.html&#39;,  styleUrls: [&#39;./medium-editor.component.scss&#39;],&#125;)export class MediumEditorComponent &#123;  formatBold() &#123;    alert(&#39;click!&#39;);  &#125;&#125;</code></pre><p>執行 <code>serve</code> 指令之後確認渲染的結果：</p><p><img src="/2023/10/12/quill-day-27/20090749CWYQwIo4Xl.png" alt="執行 `serve` 指令之後確認渲染的結果"></p><h2 id="加入-Quill-核心"><a href="#加入-Quill-核心" class="headerlink" title="加入 Quill 核心"></a>加入 Quill 核心</h2><p>接下來，我們將用 Quill 核心取代文字區域，去除主題、格式和無關模組。打開 Dev tool，在編輯器中輸入內容時檢查示範。可以看到 Parchment 文件的 base building block 正在執行中。</p><p>HTML 的部分，將剛才加入的 <code>textarea</code> 改成 <code>div</code> 並帶入範本參考變數 (Template Reference Variable) <code>editorContainer</code>， 例如：</p><pre><code class="html">&lt;div class=&quot;editor-container&quot; #editorContainer&gt;Tell your story...&lt;/div&gt;</code></pre><p>由於換成 <code>div</code>，所以 <code>editor-container</code> class 也有做了小更動：</p><pre><code class="scss">.editor-container &#123;  border: 1px solid #ccc;  font-family: &#39;Open Sans&#39;, Helvetica, sans-serif;  font-size: 1.2em;  height: 200px;  margin: 0 auto;  width: 450px;&#125;</code></pre><p>存檔重新整理之後，嘗試在編輯區域打字，可以看到 Quill 核心正在執行中：</p><p><img src="/2023/10/12/quill-day-27/20090749800mBZwczC.png" alt="在編輯區域打字"></p><p>就像 DOM 一樣，Parchment 文件是一個樹 (tree)。它的節點稱為 Blot，是 DOM 節點的抽象化。已經有一些 blot 已經為我們定義了，例如：Scroll, Block, Inline, Text 以及 Break。當我們輸入文字的時候，Text Blot 會與對應的 DOM 文字節點同步。而 Enter 則會建立一個新的 Block Blot 來處理。在 Parchment 中，可以有子項的 Blot 必須至少有一個子項，因此 Empty Block 會被 Break Blot 填滿。這使得處理樹葉 (leaves) 變得簡單且可預測。所有這一切都組織在 Root Scroll Blot 下。</p><p>這時我們無法僅透過輸入文本來觀察 Inline Blot，因為它​​不會為文件提供有意義的結構或格式。有效的 Quill 文件必須規範 (canonical) 且緊湊 (compact)。只有一棵有效的 DOM 樹可以表示給定的文件，並且該 DOM 樹包含最少數量的節點。</p><p>由於 <code>&lt;p&gt;&lt;span&gt;Text&lt;/span&gt;&lt;/p&gt;</code> 和 <code>&lt;p&gt;Text&lt;/p&gt;</code> 代表著相同的內容, 前者是無效的，Quill 的優化過程之一就是拆開 <code>&lt;span&gt;</code>. 同樣地，一旦我們加入格式，<code>&lt;p&gt;&lt;em&gt;Te&lt;/em&gt;&lt;em&gt;st&lt;/em&gt;&lt;/p&gt;</code> 和 <code>&lt;p&gt;&lt;em&gt;&lt;em&gt;Test&lt;/em&gt;&lt;/em&gt;&lt;/p&gt;</code> 也是無效的，因為它們不是最緊湊的表示方式。</p><p>因為這些限制，<strong>Quill 無法支援任意 DOM 樹和 HTML 變更</strong>。但正如我們將看到的，這種結構提供的一致性和可預測性使我們能夠輕鬆建立豐富的編輯體驗。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天開始嘗試從無到有實現 Quill 的基本功能，官網文件介紹是使用 jQuery 當作範例，但因為我們主要是在 Angular 的專案上開發，所以範例的部分都融入了 Angular 元件的生命週期，使用起來更貼近實際的開發情況。明天繼續練習 Basic Formatting 以及自訂 blot 的部分。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天中午吃飯經過南港展覽館，看到人比平常還多就知道這週末有展期了，分別是世界貓咪博覽會，還有攝影器材暨影音創作設備展，台灣戶外用品展，共有三個展覽同步在今天開始，如果是貓奴、有在玩影音創作相關設備或是時常在露營的人，感覺進去錢包就會被榨乾 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/5994068535154158c7fb31418ff6058ffeaf661e">今日份練習</a></li><li><a href="https://quilljs.com/guides/cloning-medium-with-parchment/">Cloning Medium with Parchment - Quill (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10338673">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 26：關於 Pachment 的 Attributors</title>
      <link href="/2023/10/11/quill-day-26/"/>
      <url>/2023/10/11/quill-day-26/</url>
      
        <content type="html"><![CDATA[<p>之前有探討過 Parchment 與 Blot，而 Parchment 還有一個屬性器 (Atrributors)，今天就來看一下關於 Attributor 的介紹以及使用方式。</p><p>Attributor 是另一種更輕量的表示格式的方式。與其對應的就是 DOM attribute。就像 DOM 屬性與節點的關係一樣，屬性也屬於 Blot。在 Inline 或 Block blot 上呼叫 <code>formats()</code> 如果有對應的 DOM 節點以及 DOM 節點 <code>attribute</code> 則將回傳其表示的格式。</p><h2 id="Attributor-Class"><a href="#Attributor-Class" class="headerlink" title="Attributor Class"></a>Attributor Class</h2><p>首先我們來看一下 Attributor 的介面：</p><pre><code class="typescript">class Attributor &#123;  attrName: string;  keyName: string;  scope: Scope;  whitelist: string[];  constructor(attrName: string, keyName: string, options: AttributorOptions = &#123;&#125;);  add(node: HTMLElement, value: string): boolean;  canAdd(node: HTMLElement, value: string): boolean;  remove(node: HTMLElement);  value(node: HTMLElement);&#125;</code></pre><p>需要留意的地方是，自訂的 attributor 是 instance，而不是像 blot 一樣的 class 定義。與 Blot 相似，我們不會想要從頭開始建立，而是希望使用既有的 attributors 實現，例如基礎屬性器 (base Attributor)，類別屬性器 (Class Attributor) 或樣式屬性器 (Style Attributor)。另外我們也可以透過<a href="https://github.com/quilljs/parchment/tree/main/src/attributor">原始碼</a>來看 attributor 的實現，其實沒有很複雜。</p><h2 id="Attributor"><a href="#Attributor" class="headerlink" title="Attributor"></a>Attributor</h2><p>使用 Attributor 來表示格式：</p><pre><code class="typescript">const width = new Attributor(&#39;width&#39;, &#39;width&#39;);Quill.register(width);const imageNode = document.createElement(&#39;img&#39;);width.add(imageNode, &#39;200px&#39;);console.log(imageNode.outerHTML); // Will print &lt;img width=&quot;200px&quot;&gt;const value = width.value(imageNode); // Will return 200pxconsole.log(&#39;value&#39;, value); width.remove(imageNode);console.log(imageNode.outerHTML) // Will print &lt;img&gt;</code></pre><p>可以看到我們直接以 <code>new Attributor()</code> 的方法來新增一個實體化 <code>width</code> 屬性後，以 <code>Quill.register()</code> 註冊 attribute，並且呼叫 <code>add</code> 方法將屬性加到 <code>img</code> DOM 上。然後可以透過 <code>value()</code> 取得目標 DOM 的 <code>width</code>，最後使用 <code>remove()</code> 將 <code>width</code> 從 <code>imageNode</code> 刪除。</p><h2 id="Class-Attributor"><a href="#Class-Attributor" class="headerlink" title="Class Attributor"></a>Class Attributor</h2><p>使用 Class Attributor 的方式來表示格式：</p><pre><code class="typescript">const align = new ClassAttributor(&#39;align&#39;, &#39;blot-align&#39;);Quill.register(align);const node = document.createElement(&#39;div&#39;);align.add(node, &#39;right&#39;);console.log(node.outerHTML); // Will print &lt;div class=&quot;blot-align-right&quot;&gt;&lt;/div&gt;</code></pre><p>有別於上一個 <code>new Attributor()</code>，一樣是 <code>new</code> 但後面換成是 <code>ClassAttributor</code>，帶入指定的 DOM <code>attribute</code> 並自訂一個名稱 <code>blot-align</code>，一樣註冊後使用。也能呼叫 <code>add()</code> 將自訂的 class attributor 加到目標 DOM。</p><h2 id="Style-Attributor"><a href="#Style-Attributor" class="headerlink" title="Style Attributor"></a>Style Attributor</h2><p>使用 Style Attributor 的方式來表示格式：</p><pre><code class="typescript">const align = new StyleAttributor(&#39;align&#39;, &#39;text-align&#39;, &#123;  whitelist: [&#39;right&#39;, &#39;center&#39;, &#39;justify&#39;], // Having no value implies left align&#125;);Quill.register(align);const node = document.createElement(&#39;div&#39;);align.add(node, &#39;right&#39;);console.log(node.outerHTML); // Will print &lt;div style=&quot;text-align: right;&quot;&gt;&lt;/div&gt;</code></pre><p>這次則是在實體化的時候以 <code>new StyleAttributor</code> 來新增 attributor，一樣是操作 <code>text-align</code>，但這次加上了 <code>whitelist</code> 來表示合法的參數選項。沒有帶入值則代表 <code>left</code> 置左。在註冊之後呼叫 <code>add()</code> 方法並帶入 DOM 以及 <code>align</code> 的參數選項來套用。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天探討了 Parchment 的另一塊拼圖，Attributor，提供一個文本格式套用的簡易方式。一開始嘗試練習發現奇怪怎麼會出現找不到的錯誤，看了一下 sourcecode 才發現原來實現的方式已經換了，但 Github 的 repositroy README 還是古早的實現方式。這時只能看原始碼才能知道要怎麼使用了。</p><p>我們可以透過 Base Atrributor，Class Atrributor，以及 Style Attributor 來實現不同方式的文本樣式套用，並且 Attributor 也提供了幾個方法例如 <code>add()</code>，<code>value()</code>，<code>remove()</code> 等方法取得與操作對應的 blot 來編輯文本樣式。之後再研究看看如何將 attributor 應用到編輯器中來套用文本樣式。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>連假後上班的第一天，果然精神不是很好，儘管前一晚已經盡量提早躺平，但起床後還是有沒充滿電的感覺，由於台北住處附近不好停車，所以果斷的把車開回宜蘭停放，所以今天早上是從宜蘭搭車到台北，想說國光客運到南港展覽館離上班地點最近，沒想到七點半到轉運站，要能上車得要等到八點整的班次，到辦公室就都九點了，看來如果是從宜蘭到台北的話還要再更早一點到才行了QQ</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/a719545a2167edbda7099c5ff37222bf4c25bc30">今日份的練習</a></li><li><a href="https://github.com/quilljs/parchment/">quilljs&#x2F;parchment (github.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10338302">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 25：ngx-quill 介紹</title>
      <link href="/2023/10/10/quill-day-25/"/>
      <url>/2023/10/10/quill-day-25/</url>
      
        <content type="html"><![CDATA[<p>前面 14 天都在看 Quill Editor 的官方文件，突然想起我的主題還是要跟 Angular 有一點關係，除了直接在 Angular 引入 Quill 之外，其實也有方便的第三方套件可以使用，也就是 ngx-quill。</p><p>在 Angular 專案中，有時候會需要用到第三方套件，為了要能順利的融入 Angular 的世界，我們會需要額外的處理與封裝，讓套件使用體驗可以更 Angular。而使用 ngx-quill 的好處如下：</p><h2 id="資料與事件綁定"><a href="#資料與事件綁定" class="headerlink" title="資料與事件綁定"></a>資料與事件綁定</h2><p>我們都知道 Angular 使用 data binding 以及 event binding 作為核心特性之一，使用 ngx-quill 可以方便的透過綁定的方式來維護資料的狀態以及編輯器的互動等功能。</p><h2 id="模組化及相依性注入"><a href="#模組化及相依性注入" class="headerlink" title="模組化及相依性注入"></a>模組化及相依性注入</h2><p>Angular 專案中，我們透過 module (目前更推薦使用 standalone component)，以及相依性注入 ( Dependency Injection ) 作為管理各種服務和元件的方式。ngx-quill 也是按照 Angular 的模組化及相依性注入的設計模式來建立。使其更容易整合到既有的 Angular App 中。</p><h2 id="表單控制"><a href="#表單控制" class="headerlink" title="表單控制"></a>表單控制</h2><p>Angular 有很強大的表單 module，包括了：<code>template-driven forms</code> 以及 <code>reactive Forms</code>。ngx-quill 可以輕鬆的整合到 Angular 的表單系統中，讓我們能使用 Angular 的驗證、狀態追蹤等功能。</p><h2 id="安裝與使用"><a href="#安裝與使用" class="headerlink" title="安裝與使用"></a>安裝與使用</h2><p>首先我們一樣透過 <code>npm install</code> 來安裝 <code>ngx-quill</code>：</p><pre><code class="bash">npm install ngx-quill --savenpm install @types/quill@1.3.10</code></pre><p>另外需要注意的是，如果之前的練習有安裝到 <code>@types/quill</code> 的話，版本會是 <code>2.0.11</code>，這邊我們需要降版到 <code>1.3.10</code> 才不會導致編譯時的類型錯誤。</p><p>如果是全新的 Angular 專案，需要將 quill editor 的佈景主題 (theme) CSS Style 加到專案，例如：<br>要選用 <code>snow</code> 的主題，可以 import CSS 到 <code>styles.scss</code>：</p><pre><code class="scss">@import &#39;~quill/dist/quill.snow.css&#39;;</code></pre><p>也可以把 <code>node_modules/quill/dist/quill.snow.css</code> 加到 <code>angular.json</code> 或 Nx 的 <code>project.json</code> 的 <code>styles</code> 陣列中。</p><pre><code class="json">&quot;styles&quot;: [    &quot;node_modules/quill/dist/quill.snow.css&quot;,    &quot;src/styles.scss&quot;],</code></pre><p>安裝完畢之後，接著我們要將 <code>ngx-quill</code> 的 module 導入：</p><pre><code class="typescript">import &#123; QuillModule &#125; from &#39;ngx-quill&#39;;@NgModule(&#123;  imports: [    QuillModule.forRoot()  ],&#125;)export class AppModule &#123; &#125;</code></pre><p>Import 之後就可以直接在 template 使用這個元件：</p><pre><code class="html">&lt;quill-editor&gt;&lt;/quill-editor&gt;</code></pre><p>這時直接 <code>ng serve</code> 就可以看到有基本款的 Quill Editor 了。</p><h2 id="配置選項"><a href="#配置選項" class="headerlink" title="配置選項"></a>配置選項</h2><p>配置選項目前我們可以放在兩個地方，一個是在 template 的 component 屬性中，另一個則是在 import <code>QuillConfigModule.forRoot()</code> 的括號中帶入配置選項。</p><p>在 template 的 component 屬性加上 quill eidtor 的配置：</p><pre><code class="html">&lt;quill-editor  [modules]=&quot;&#123;    toolbar: [      [&#39;bold&#39;, &#39;italic&#39;],      [&#39;link&#39;, &#39;blockquote&#39;]    ]  &#125;&quot;  [theme]=&quot;&#39;snow&#39;&quot;&gt;&lt;/quill-editor&gt;</code></pre><p>透過 import <code>QuillConfigModule</code> 帶入配置：</p><pre><code class="typescript">import &#123; QuillConfigModule, QuillModule &#125; from &#39;ngx-quill&#39;;@NgModule(&#123;  imports: [    QuillModule.forRoot(),    QuillConfigModule.forRoot(&#123;      modules: &#123;        toolbar: [          [&#39;bold&#39;, &#39;italic&#39;],          [&#39;link&#39;, &#39;blockquote&#39;],        ],      &#125;,    &#125;),  ],&#125;)export class AppModule &#123; &#125;</code></pre><h3 id="Standalone-元件"><a href="#Standalone-元件" class="headerlink" title="Standalone 元件"></a>Standalone 元件</h3><p><code>ngx-quill</code> 也支援 standalone 的功能，可以直接使用 <code>provideQuillConfig</code> 方法進行配置，例如在 <code>main.ts</code> 的 <code>bootstrapApplication</code> 呼叫時，將配置加入到 <code>providers</code>：</p><pre><code class="typescript">import &#123; provideQuillConfig &#125; from &#39;ngx-quill/config&#39;;bootstrapApplication(AppComponent, &#123;  providers: [    provideQuillConfig(&#123;      modules: &#123;        syntax: true,        toolbar: [          [&#39;bold&#39;, &#39;italic&#39;],          [&#39;link&#39;, &#39;blockquote&#39;],        ],      &#125;    &#125;)  ]&#125;);</code></pre><p>此時的 <code>AppComponent</code> 對應的 standalone 設定如下：</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; QuillModule &#125; from &#39;ngx-quill&#39;;@Component(&#123;  selector: &#39;app-root&#39;,  templateUrl: &#39;./app.component.html&#39;,  styleUrls: [&#39;./app.component.scss&#39;],  standalone: true,  imports: [QuillModule],&#125;)export class AppComponent &#123;// ...&#125;</code></pre><h2 id="與-Angular-Form-整合"><a href="#與-Angular-Form-整合" class="headerlink" title="與 Angular Form 整合"></a>與 Angular Form 整合</h2><p>有時候我們要確認編輯器的狀態，以根據需求進行像是表單驗證，或是否修改過等相關的操作，這時候可以搭配 Angular Form module 加到 <code>ngx-quill</code> 就能快速的實現表單操作與驗證的需求。例如以下的範例，搭配 <code>import</code> 對應的 <code>FormsModule</code> 或 <code>ReactiveFormsModule</code> 就能使用了：</p><pre><code class="html">&lt;!-- Reactive Forms --&gt;&lt;form [formGroup]=&quot;myForm&quot;&gt;  &lt;quill-editor formControlName=&quot;editorContent&quot;&gt;&lt;/quill-editor&gt;&lt;/form&gt;&lt;!-- Template-driven Forms --&gt;&lt;quill-editor [(ngModel)]=&quot;editorContent&quot; name=&quot;editorContent&quot;&gt;&lt;/quill-editor&gt;</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p><code>ngx-quill</code> 作為 Quill 的 Angular wrapper，為 Angular 開發者提供了一個更方便、更“Angular化”的方式來使用編輯器。從簡單的安裝配置到與 Angular Forms 的整合，可以省略掉前期的設定流程，直接無痛加入並使用。之後再繼續看 ngx-quill 的其他介紹內容。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>連假的最後一天，運氣還不錯，儘管前一天晚上豪大雨，但今天的天氣就陰陰的沒有下雨，是涼爽舒服的，去了傳統藝術中心，這次也待了比較多的時間在裡面度過，跟著導覽員去看各種不同的傳統文化，也看了很帥的霹靂布袋戲人偶，不論什麼時候看，精細的程度都不輸專業的模型，但真的很大尊，家裡空間不夠的收一尊就很極限了 XD 期待下次再來逛逛，會有不同的展覽內容。</p><h3 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h3><p><a href="https://github.com/KillerCodeMonkey/ngx-quill">KillerCodeMonkey&#x2F;ngx-quill: Angular (&gt;&#x3D;2) components for the Quill Rich Text Editor (github.com)</a><br><a href="https://snyk.io/advisor/npm-package/@types/quill">@types&#x2F;quill - npm Package Health Analysis | Snyk</a></p><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10337742">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 24：讀 Quill Editor API 技術文件 - Clipboard 與 Syntax Highlighter Module</title>
      <link href="/2023/10/09/quill-day-24/"/>
      <url>/2023/10/09/quill-day-24/</url>
      
        <content type="html"><![CDATA[<p>連假第三天，終於來到最後的兩個章節，Clipboard &amp; Syntax Highlighter Module。因為篇幅比較沒有那麼多，所以就放在一起看了。</p><p>剪貼簿 ( Clipboard Module )，負責處理 Quill Editor 與外部 App 之間的複製、剪下與貼上的操作。Clipboard module 提供了一組預設的判斷邏輯處理貼上的內容，並且我們能進一步通過加入自定義的匹配器（matcher）來調整或擴充這些預設行為。例如：我們可以讓特定的 HTML 標籤或文字段落在貼上時有特殊的格式或行為。</p><p>剪貼簿會通過後序遍歷（post-order）相應的 DOM 樹來處理貼上的 HTML，從而建構所有子樹的 Delta 表示形式。在每個子節點，matcher 函數會被呼叫，並傳入 DOM 節點和到目前為止的 Delta 處理，這樣可以讓 matcher 回傳一個修改過的 Delta。要能操作好 matcher，就需要熟悉和理解 Delta。</p><h2 id="可用的-API"><a href="#可用的-API" class="headerlink" title="可用的 API"></a>可用的 API</h2><h4 id="addMatcher"><a href="#addMatcher" class="headerlink" title="addMatcher"></a>addMatcher</h4><p>將自定義 matcher 新增到 clipboard module。使用 <code>nodeType</code> 的 matcher 會先被呼叫，按照它們被加入的順序，另一個是使用 CSS selector 的 matcher，也是按照被加入的順序。<code>nodeType</code> 可能是 <code>Node.ELEMENT_NODE</code> 或 <code>Node.TEXT_NODE</code>。</p><p>方法：</p><pre><code class="typescript">addMatcher(selector: String, (node: Node, delta: Delta) =&gt; Delta)addMatcher(nodeType: Number, (node: Node, delta: Delta) =&gt; Delta)</code></pre><p>範例：</p><pre><code class="typescript">quill.clipboard.addMatcher(Node.TEXT_NODE, function(node, delta) &#123;  return new Delta().insert(node.data);&#125;);// Interpret a &lt;b&gt; tag as boldquill.clipboard.addMatcher(&#39;B&#39;, function(node, delta) &#123;  return delta.compose(new Delta().retain(delta.length(), &#123; bold: true &#125;));&#125;);</code></pre><h4 id="dangerouslyPasteHTML"><a href="#dangerouslyPasteHTML" class="headerlink" title="dangerouslyPasteHTML"></a>dangerouslyPasteHTML</h4><p>在指定的索引位置將由 HTML 片段表示的內容插入到編輯器中。該片段會被剪貼簿的匹配器解釋，這可能不會產生完全相同的輸入 HTML。如果沒有提供插入索引，則會覆蓋整個編輯器的內容。來源可能是 “user”、”api” 或 “silent”。</p><p>不正確的處理 HTML 可能會導致跨站腳本攻擊（XSS），而未能正確清理 (sanitize) 則是引發網站漏洞的主要原因之一。明確的命名這個方法，以確保我們能注意到使用這個方法可能涉及的風險。這個命名方式也遵循了 React 框架的例子，React 也有類似的概念，如 <code>dangerouslySetInnerHTML</code> 用來提醒開發者必須謹慎操作。</p><p>方法：</p><pre><code class="typescript">dangerouslyPasteHTML(html: String, source: String = &#39;api&#39;)dangerouslyPasteHTML(index: Number, html: String, source: String = &#39;api&#39;)</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello!&#39;);quill.clipboard.dangerouslyPasteHTML(5, &#39; &lt;b&gt;World&lt;/b&gt;&#39;);// 編輯器的 HTML 文本內容會是 &#39;&lt;p&gt;Hello &lt;strong&gt;World&lt;/strong&gt;!&lt;/p&gt;&#39;;</code></pre><h2 id="Clipboard-配置設定"><a href="#Clipboard-配置設定" class="headerlink" title="Clipboard 配置設定"></a>Clipboard 配置設定</h2><h4 id="matchers"><a href="#matchers" class="headerlink" title="matchers"></a>matchers</h4><p>可以將 <code>matcher</code> 陣列傳遞到剪貼簿的配置選項中。這些將附加在 Quill 內建的 <code>matcher</code> 之後。</p><pre><code class="typescript">var quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123;    clipboard: &#123;      matchers: [        [&#39;B&#39;, customMatcherA],        [Node.TEXT_NODE, customMatcherB]      ]    &#125;  &#125;&#125;);</code></pre><h3 id="Syntax-Highlighter-Module"><a href="#Syntax-Highlighter-Module" class="headerlink" title="Syntax Highlighter Module"></a>Syntax Highlighter Module</h3><p>語法高亮模組（Syntax Highlighter Module）在 Quill Editor 中用於增強程式碼區塊內容（Code Block）格式。它會自動檢測並套用語法高亮效果，且依賴於 highlight.js 函式庫來解析和標記程式碼區塊。</p><p>我們可以根據需求來配置 highlight.js。不過，Quill 要求 <code>useBR</code> 的選項必須設為 false。</p><p>範例：</p><pre><code class="typescript">&lt;!-- 引入 highlight.js 樣式表 --&gt;&lt;link href=&quot;highlight.js/monokai-sublime.min.css&quot; rel=&quot;stylesheet&quot;&gt;&lt;!-- 引入 highlight.js 函式庫 --&gt;&lt;script href=&quot;highlight.js&quot;&gt;&lt;/script&gt;  &lt;script&gt;hljs.configure(&#123;   // optionally configure hljs  languages: [&#39;javascript&#39;, &#39;ruby&#39;, &#39;python&#39;]&#125;);var quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123;    syntax: true,              // Include syntax module    toolbar: [[&#39;code-block&#39;]]  // Include button in toolbar  &#125;,  theme: &#39;snow&#39;&#125;);&lt;/script&gt;</code></pre><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>剪貼簿（Clipboard）模組在 Quill Editor 中負責處理與外部應用間的複製、剪下和貼上操作。它提供了一套預設行為來解析貼上的內容，並允許開發者透過自定義 <code>matcher</code> 來進一步調整這些行為。這些 <code>matcher</code> 可以按照它們被加入的順序來進行呼叫，而在貼上 HTML 時，剪貼簿會後序遍歷對應的 DOM 樹來創建一個 Delta 表示形式。</p><p>基於安全性考慮，提供了一個 <code>dangerouslyPasteHTML</code> 的API，用在確認安全的操作情境下插入  HTML。剪貼簿模組不僅提供了彈性的自訂方式，也考慮到貼上內容的安全處理，使 Quill 更靈活實用。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>儘管昨日發現前一晚停車時刮到了輪拱板金，心情受到一些影響之外，整體的行程還不錯，在金車威士忌酒廠待了一整天，雖然之前也去過幾次，但都沒有導覽員，這次趁著人多時，有導覽員的服務，也學到不少威士忌的一些觀念，今天出發前就發了這篇文章，預計會去傳統藝術中心，今天天氣看起來很不錯，要多喝水避免被太陽曬昏頭了 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/715fbbeecb81d6092729b55db7edce578ed9fa18">今日份的練習</a></li><li><a href="https://quilljs.com/docs/modules/clipboard/">Clipboard Module - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10337353">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 23：讀 Quill Editor API 技術文件 - History Module</title>
      <link href="/2023/10/08/quill-day-23/"/>
      <url>/2023/10/08/quill-day-23/</url>
      
        <content type="html"><![CDATA[<p>昨天泡了溫泉，休息一下，繼續看 History module。<br>History module 主要保存文本操作紀錄與處理與 Quill 的 undo 和 redo。<br>有以下的選項可以使用：</p><h2 id="配置設定參數"><a href="#配置設定參數" class="headerlink" title="配置設定參數"></a>配置設定參數</h2><h3 id="delay"><a href="#delay" class="headerlink" title="delay"></a>delay</h3><p>預設值：<code>1000</code> </p><p>設定在指定秒數內更改合併成一個更改紀錄。例如當 <code>delay</code> 設為 <code>0</code> 時，幾乎每個字元都會記錄成一次更改，因此使用 <code>undo</code> 就只會取消一個字元。當 <code>delay</code> 設置為 1000 時，<code>undo</code> 將會撤銷最後 1000 毫秒內發生的所有變更。</p><h3 id="maxStack"><a href="#maxStack" class="headerlink" title="maxStack"></a>maxStack</h3><p>預設值：<code>100</code></p><p>設定歷史操作紀錄堆疊的最大值。與 <code>delay</code> 選項合併的變更算是一次變更操作。</p><h3 id="userOnly"><a href="#userOnly" class="headerlink" title="userOnly"></a>userOnly</h3><p>預設值：<code>false</code></p><p>預設的情況下，無論 <code>source</code> 是 <code>user</code> 或是透過 <code>api</code> 的方式進行的所有變更。都視為同等的操作，並且變更可以從 <code>history</code> <code>redo</code>&#x2F;<code>undo</code>。如果 <code>userOnly</code> 設為 <code>true</code>，則只會處理使用者的變更。</p><pre><code class="typescript">const quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123;    history: &#123;      delay: 2000,      maxStack: 500,      userOnly: true    &#125;  &#125;,  theme: &#39;snow&#39;&#125;);</code></pre><h2 id="API"><a href="#API" class="headerlink" title="API"></a>API</h2><h3 id="clear"><a href="#clear" class="headerlink" title="clear"></a>clear</h3><p>清除 <code>history</code> 的所有堆疊紀錄</p><p>方法：</p><pre><code class="typescript">clear()</code></pre><p>範例：</p><pre><code class="typescript">quill.history.clear();</code></pre><h3 id="cutoff-實驗性"><a href="#cutoff-實驗性" class="headerlink" title="cutoff (實驗性)"></a>cutoff (實驗性)</h3><p>通常短時間內連續進行的變更，我們可以透過 <code>delay</code> 設置來合併成為一次歷史紀錄，以便觸發更多的 <code>undo</code> 的變更。使用 <code>cutoff</code> 將重置合併窗口，以便呼叫 <code>cutoff</code> 之前和之後的更改不會被合併。</p><p>方法：</p><pre><code class="typescript">cutoff()</code></pre><p>範例：</p><pre><code class="typescript">quill.history.cutoff();</code></pre><h3 id="undo"><a href="#undo" class="headerlink" title="undo"></a>undo</h3><p>取消最後一次的變更操作。</p><p>方法：</p><pre><code class="typescript">undo()</code></pre><p>範例：</p><pre><code class="typescript">quill.history.undo();</code></pre><h3 id="redo"><a href="#redo" class="headerlink" title="redo"></a>redo</h3><p>如果上次的操作是 <code>undo</code>，則還原 <code>undo</code>。</p><p>方法：</p><pre><code class="typescript">redo()</code></pre><p>範例：</p><pre><code class="typescript">quill.history.redo();</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天嘗試了初始化的時候加入 History module 的配置設定參數，另外也透過按鈕的方式來呼叫 history module 的 API，也能觀察到其 history stack 的變化，不過目前 <code>@types/quill</code> 的 history 版本似乎沒看到有 history module 的其他屬性，只有加上 API 的定義而已，感覺可以再提一個新 PR 了 XD</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>昨天運氣不錯，搭客運回宜蘭牽車沒遇到塞車，順利的開車到新竹接朋友出發到宜蘭，這聽起來有點瘋狂，我只是喜歡開車而已XD 不過到了住宿的停車場，因為是機械式的，沒注意到後面兩側還有塗上黃色的支撐桿，今天早上出發前才看到右後輪拱有擦到 Orz 前一晚停車時原本以為是機械車位的地板阻尼之類的作動聲，沒想到是磨擦聲，儘管是老車了，也多少有一些擦傷，但還是免不了會心痛 QQ，找時間再去買幾支板金補漆筆塗一下了，畢竟輪拱最邊緣的地方有一小部分都看到銀色的部分，應該是底漆也有刮掉了 (哭</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/b399895e47cf5221bdaed7ef89fe4401b31b477c">今日份的練習</a></li><li><a href="https://quilljs.com/docs/modules/history/">History Module - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10336767">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 22：讀 Quill Editor API 技術文件 - Keyboard Module (下)</title>
      <link href="/2023/10/07/quill-day-22/"/>
      <url>/2023/10/07/quill-day-22/</url>
      
        <content type="html"><![CDATA[<p>連假的第一天，今天繼續看 Keyboard module 的 <code>context</code> 剩下的參數以及設定相關的介紹。</p><h3 id="offset"><a href="#offset" class="headerlink" title="offset"></a>offset</h3><p>當使用者的游標從開始移動到 <code>offset</code> 指定的特定的位置則觸發 handler，例如：當 <code>offset</code> 為 <code>3</code> 時，只有使用者選擇的文字或是游標是在同一行的第三個字元位置開始，才會執行對應的 handler。另外執行的時機點是在使用者輸入內容的時候就已經判定的，因此使用者如果在第 3 個字元時按下按鍵輸入文字，則 handler 會在文字輸入之前就被執行。</p><pre><code class="typescript">quill.keyboard.addBinding(  &#123; key: &#39;o&#39; &#125;,  &#123; offset: 2 &#125;, // 當游標在第3個字元前面時觸發  (range, context) =&gt; &#123;    // 插入特殊符號的代碼    quill.insertText(range.index, &#39;★★★&#39;);  &#125;);</code></pre><h3 id="prefix"><a href="#prefix" class="headerlink" title="prefix"></a>prefix</h3><p>一個正則表達式（Regex）屬性，用於指定必須與使用者選擇的區域或游標開始位置之前的文字比對的模式。換句話說，當該正則表達式匹配到使用者選擇開始位置前方的文字時，相關的處理函數（handler）才會被觸發。例如，當使用者輸入一個 <code>@</code> 符號，然後按下 <code>k</code> 時，這個 handler 會被觸發。<code>prefix: /@$/</code> 確保了只有當游標（或選取範圍）前方是 <code>@</code> 符號時，這個 handler 才會執行：</p><pre><code class="typescript">quill.keyboard.addBinding(&#123; key: &#39;k&#39; &#125;, &#123;  prefix: /@$/, // 前置文本必須是 @&#125;, (range, context) =&gt; &#123;  // 這裡實現你的自定義邏輯，例如彈出一個用戶列表以供選擇  console.log(&quot;觸發了 @ 符號的自定義行為&quot;);&#125;);</code></pre><p><code>context.prefix</code> 在這個例子中會是 <code>@</code>，因為它包含了選擇開始位置之前的整個文字區塊。如此一來，我們就可以在使用者輸入 <code>@</code> 符號後進行特定操作，像是顯示一個下拉清單讓使用者選擇名稱。</p><h3 id="suffix"><a href="#suffix" class="headerlink" title="suffix"></a>suffix</h3><p>和 <code>prefix</code> 的概念相同，只是比對的位置是使用者選擇的內容或游標的位置的後面開始。</p><h2 id="配置"><a href="#配置" class="headerlink" title="配置"></a>配置</h2><p>預設的情況下，Quill 內建幾個實用的按鍵綁定，例如使用 Tab 鍵進行縮排。我們可以在初始化時加入自訂的按鍵綁定。</p><p>有些綁定對於防止瀏覽器的危險預設行為（如 Enter 鍵和 Backspace 鍵）是必要的。不能移除這些綁定以恢復到瀏覽器的原生行為。然而，由於在配置中指定的綁定會在 Quill 的預設綁定之前運行，您可以處理特殊情況並將其傳播給 Quill。</p><p>使用 <code>quill.keyboard.addBinding</code> 加入綁定不會在 Quill 的預設綁定之前運行，因為到那時預設綁定已經被加入。</p><p>每個綁定配置必須包含鍵（key）和處理器（handler）選項，並且可以選擇性地包括任何 <code>context</code> 選項。</p><pre><code class="typescript">const bindings = &#123;  // 這將覆蓋名為 &#39;tab&#39; 的預設綁定  tab: &#123;    key: 9,    handler: function() &#123;      // 處理 Tab 鍵    &#125;  &#125;,  // 沒有名為 &#39;custom&#39; 的預設綁定，  // 因此這將會被新增，而不會覆蓋任何內容  custom: &#123;    key: &#39;B&#39;,    shiftKey: true,    handler: (range, context) =&gt; &#123;      // 處理 Shift + B    &#125;  &#125;,  // 當按 Backspace 鍵並且格式為 list 時  list: &#123;    key: &#39;backspace&#39;,    format: [&#39;list&#39;],    handler: (range, context) =&gt; &#123;      if (context.offset === 0) &#123;        // 若在 list 的第一個字元上按 Backspace，        // 則移除該列表        this.quill.format(&#39;list&#39;, false, Quill.sources.USER);      &#125; else &#123;        // 否則，傳給 Quill 做預設處理        return true;      &#125;    &#125;  &#125;&#125;;// 初始化 Quill，並指定 keyboard module 的綁定var quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123;    keyboard: &#123;      bindings: bindings    &#125;  &#125;&#125;);</code></pre><h2 id="性能考量"><a href="#性能考量" class="headerlink" title="性能考量"></a>性能考量</h2><p>和 DOM event 相同，Quill key binding 在每次比對時都會阻擋呼叫，因此為一個非常普通的按鍵綁定一個複雜的 handler 不是一個好的實現方式。在套用像是滑鼠移動或卷軸滾動的 DOM 事件時，盡可能的套用性能較好的實現以確保一定品質的使用者體驗。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>這兩天探討了 Quill 的 Keyboard module，讓我們可以自定義鍵盤事件的處理。Quill 的 keyboard module 主要有兩種用途：</p><ol><li>綁定格式化快捷鍵：比如 “Ctrl + B” 可以讓選中的文字變粗。</li><li>防止瀏覽器的一些預設行為：這樣可以確保應用程式的穩定性與使用者體驗。</li></ol><p>我們也了解如何使用不同的 <code>context</code> 參數來更精細的控制 handler 的觸發時機，包含游標的位置、目前使用中的格式、以及前後緊鄰的文本內容等。</p><p>此外，keyboard module 也提供了豐富的設定選項，讓我們可以在初始化時加入自訂的綁定，或是覆蓋Quill 的預設綁定。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天午餐後整理一下文章，晚一點就要出發去載朋友來宜蘭玩了，希望不要塞車塞得太嚴中 XD。昨天看了同事的分享會 Feedback，看到很多有趣的回應。其中還有提到下班後學習這件事，我認為學習是屬於個人的事情，至於有沒有要求下班後學習這件事，最終決定權還是在自己手上。若真的有興趣的而且學到之後能讓自己在上班的過程更順暢也能克服一些挑戰，我想這個學習過程應該是相當精彩的，儘管最後發現也許是個坑，但這都是成長的一部分。</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/be03de30380a0ae188fee3c97890ec9b6d5b0cbd">今日份的練習</a></li><li><a href="https://quilljs.com/docs/modules/keyboard/#offset">Keyboard Module - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10335867">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 21：讀 Quill Editor API 技術文件 - Keyboard Module (上)</title>
      <link href="/2023/10/06/quill-day-21/"/>
      <url>/2023/10/06/quill-day-21/</url>
      
        <content type="html"><![CDATA[<p>今天來看 Keyboard module 的章節。</p><p>Keyboard module 支援特定 context 中鍵盤事件的自訂行為。Quill 使用 Keyboard module 來綁定格式化快捷鍵並防止一些瀏覽器副作用。</p><h2 id="Key-Bindings"><a href="#Key-Bindings" class="headerlink" title="Key Bindings"></a>Key Bindings</h2><p>Keyboard handler 綁訂到特定的按鍵與修飾鍵。<code>key</code> 是 JavaScript event 的 key code，但也允許英文字母與數字鍵，以及常用的按鍵的字串縮寫設定。常見的修飾鍵例如：<code>metaKey</code>，<code>ctrl</code>，<code>shift</code>，以及 <code>alt</code> 等。另外 <code>shortKey</code> 是指特定平台的修飾鍵，像是 MacOS 上的 <code>metaKey</code>，以及 Linux 和 Windows 上的 <code>ctrlKey</code>。</p><p>我們可以將指定的按鍵和修飾鍵綁定到一個 handler。當這個鍵被按下時，handler 就會被執行，並將使用者選擇的範圍傳入以及綁定到 keyboard module 當下的 instance：</p><pre><code class="typescript">quill.keyboard.addBinding(&#123;  key: &#39;B&#39;,  shortKey: true&#125;, function(range, context) &#123;  quill.formatText(range, &#39;bold&#39;, true);&#125;);// addBinding 也能只帶入一個參數，並加上 handlerquill.keyboard.addBinding(&#123;  key: &#39;B&#39;,  shortKey: true,  handler: function(range, context) &#123;    quill.formatText(range, &#39;bold&#39;, true);  &#125;&#125;);</code></pre><p>這個範例是當使用者按下 <code>B</code> 鍵加上修飾鍵（Mac 上的 <code>metaKey</code> 或 Windows 和 Linux 上的 <code>ctrlKey</code>）時，選取的文字會變粗體。</p><h2 id="Context"><a href="#Context" class="headerlink" title="Context"></a>Context</h2><p>我們還可以設定更多的條件，讓 handler 只在特定的情境下被呼叫。例如，當使用者選擇的是一個空行或者是列表項目時，才會觸發相對應的 handler：</p><pre><code class="typescript">// 如果使用者在 list 或 blockquote 的開頭按了 ctrl + d,// 則刪除 list 或 blockquote 的格式quill.keyboard.addBinding(  &#123; key: &#39;d&#39;, shortKey: true &#125;,  &#123;    collapsed: false,    format: [&#39;blockquote&#39;, &#39;list&#39;],    offset: 0,  &#125;,  function (range, context) &#123;    console.log(&#39;backspace pressed&#39;);    if (context.format.list) &#123;      quill.format(&#39;list&#39;, false);    &#125; else &#123;      quill.format(&#39;blockquote&#39;, false);    &#125;  &#125;);</code></pre><p>不過需要注意的地方是，當編輯器初始化之後才加入的 keyboard binding，需要確認內建的部分是否也有監聽，否則會因為按鍵事件發生時逐條比對條件的關係，就被前面的規則代為執行了。例如 <code>backspace</code> 的 <code>keycode</code> 是 <code>8</code>：<br><img src="/2023/10/06/quill-day-21/20090749Cy3B9odY5Z.png" alt="被前面的規則代為執行"></p><h2 id="Context-的參數"><a href="#Context-的參數" class="headerlink" title="Context 的參數"></a>Context 的參數</h2><h3 id="collapsed"><a href="#collapsed" class="headerlink" title="collapsed"></a>collapsed</h3><p>如果為 <code>true</code> 則當使用者的游標停在編輯器上，在沒有選擇任何文字的情況下觸發 handler。<code>collapsed</code> 翻成中文是收折的意思，但實際上就是指游標停在編輯器上並沒有選取任何文字的狀態。</p><h3 id="empty"><a href="#empty" class="headerlink" title="empty"></a>empty</h3><p>如果為 <code>true</code>，當使用者的游標在一行空白的時候會觸發。設為 <code>false</code> 則代表非空行，另外當 <code>empty</code> 為 <code>true</code> 時，意思就是 <code>collapsed</code> 也要是 <code>true</code>，且 <code>offset</code> 必須是 <code>0</code>，這樣才是真正完全的一行空白。<br>例如當使用者換行的時候加上一個星星符號：</p><pre><code class="typescript">quill.keyboard.addBinding(&#123; key: &#39;enter&#39; &#125;, &#123;  empty: true  // 只在空行觸發&#125;, function(range, context) &#123;  // 插入特殊符號的代碼  this.editor.insertText(range.index, &#39;★&#39;);&#125;);</code></pre><h3 id="format"><a href="#format" class="headerlink" title="format"></a>format</h3><p><code>format</code> 這個參數用來控制 handler 在哪些特定的格式條件下會被觸發。</p><ul><li>當 <code>format</code> 是一個陣列時，如果當前活動（active）的格式中包含陣列裡面指定的任何一種格式，則會觸發 handler：</li></ul><pre><code class="typescript">quill.keyboard.addBinding(&#123; key: Keyboard.keys.ENTER &#125;, &#123;  format: [&#39;bold&#39;, &#39;italic&#39;] // 只要文字是粗體或斜體，處理函數就會觸發&#125;, function(range, context) &#123;  // 插入特殊符號的代碼  this.editor.insertText(range.index, &#39;★&#39;);&#125;);</code></pre><ul><li>當 <code>format</code> 是一個物件：所有指定的格式條件必須全部滿足，handler 才會觸發。</li></ul><pre><code class="typescript">quill.keyboard.addBinding(&#123; key: Keyboard.keys.ENTER &#125;, &#123;  format: &#123;    bold: true,    italic: true  &#125; // 當文字是粗體且斜體，處理函數才會觸發&#125;, function(range, context) &#123;  // 插入特殊符號的代碼  this.editor.insertText(range.index, &#39;★&#39;);&#125;);</code></pre><p>在任何情況下，<code>context</code> 參數的 <code>format</code> 屬性都會是一個物件，其中包含了所有當前活動的格式。這個物件的結構和 <code>quill.getFormat()</code> 回傳的結構是相同的。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天研究了 Quill 的 keyboard module，並了解如何加入自訂的 keyboard binding，也看到 <code>context</code> 的內容有哪些可以讓我們運用，明天接著看 <code>context</code> 其他的參數介紹。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天下班前，不小心把弄了一陣子的 Git stash 給 drop 掉了，然後又因為是在 Git Graph 上執行，所以也沒有留意到 hash 的部分，當下真的有 BBQ 的感覺，不死心的我花了一點時間研究，總算找到解法，第一次使用 <code>git fsck</code>，搭配 sh 腳本執行，把碎片找回來從裡面去翻之前改過的程式片段，找到後來改的內容，趕快把 hash 記下來，接著 apply，逝去的青春終於又回來了(誤。這故事給了我一個教訓，以後還是乖乖建 commit 吧…Orz</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/37337ce44f6a8659a39be3107e739b032d3e9373">今日份的練習</a></li><li><a href="https://quilljs.com/docs/modules/keyboard/">Keyboard Module - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10335585">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 20：讀 Quill Editor API 技術文件 - Toolbar Module</title>
      <link href="/2023/10/05/quill-day-20/"/>
      <url>/2023/10/05/quill-day-20/</url>
      
        <content type="html"><![CDATA[<p>今天開始第一個內建 module 的介紹，在第六天的時候我們就已經介紹如何自訂工具列，這篇就當作複習，跟著技術文件介紹來練習體驗。</p><p>工具列模組 (Toolbar module) 可以讓使用者輕鬆的將文本內容套用格式。Toolbar 除了初始化設置要開啟的功能後直接渲染，我們也可以自行定義 container 內容以及工具列功能的處理器 (handler)。</p><h2 id="Toolbar-module-設定"><a href="#Toolbar-module-設定" class="headerlink" title="Toolbar module 設定"></a>Toolbar module 設定</h2><p>Toolbar 的設定方式可分為兩種，一種是指定 toolbar 的容器 (container)，並視需求加上 HTML 控制項以及對應的處理器 (handler)，另一種則是直接使用陣列來設置。</p><p>透過指定 container 的設置方式：</p><pre><code class="html">&lt;p&gt;toolbar-practice works!&lt;/p&gt;&lt;div #myToolbar&gt;&lt;/div&gt;&lt;div #quillContainer&gt;&lt;/div&gt;</code></pre><pre><code class="typescript">@ViewChild(&#39;quillContainer&#39;) quillContainer!: ElementRef;@ViewChild(&#39;myToolbar&#39;) myToolbar!: ElementRef;quill!: Quill;ngAfterViewInit(): void &#123;    this.quill = new Quill(this.quillContainer.nativeElement, &#123;       modules: &#123;         toolbar: &#123;           container: this.myToolbar.nativeElement,           handlers: &#123;             bold: (value: boolean) =&gt; &#123;              console.log(&#39;value&#39;, value);              this.quill.format(&#39;bold&#39;, value);            &#125;,           &#125;        &#125;       &#125;     &#125;);&#125;</code></pre><p><code>toolbar</code> 也可直接給 <code>container</code> 的 id <code>selector</code>，這裡我們直接用 <code>template reference</code>：</p><pre><code class="typescript">const quill = new Quill(this.quillContainer.nativeElement, &#123;     modules: &#123; // Equivalent to &#123; toolbar: &#123; container: &#39;#toolbar&#39; &#125;&#125;         toolbar: this.myToolbar.nativeElement     &#125; &#125;);</code></pre><p>可以看到直接指定 <code>container</code> 之後，就可以直接渲染，但因為沒有設定要放哪些功能按鈕在工具列上，所以現在看到是還沒有任何按鈕的：</p><p><img src="/2023/10/05/quill-day-20/200907490cqE545H5z.png" alt="現在看到是還沒有任何按鈕"></p><h2 id="Container"><a href="#Container" class="headerlink" title="Container"></a>Container</h2><p>工具列的控制項可以帶入控制項名稱的陣列或自定義 HTML 容器來指定。<br>從基本的陣列來設定 <code>toolbar</code> 開始：</p><pre><code class="typescript">const toolbarOptions = [&#39;bold&#39;, &#39;italic&#39;, &#39;underline&#39;, &#39;strike&#39;]; this.quill = new Quill(this.quillContainer.nativeElement, &#123;     modules: &#123;         toolbar: toolbarOptions     &#125; &#125;);</code></pre><h3 id="控制項分組與自定義"><a href="#控制項分組與自定義" class="headerlink" title="控制項分組與自定義"></a>控制項分組與自定義</h3><p>控制項也能放在巢狀陣列來表示設定分組，這樣可以將同一組的控制項放在 <code>className</code> 為 <code>ql-formats</code> 的 <code>&lt;span&gt;</code> 標籤下以提供佈景主題利用，例如在佈景主題 <a href="https://quilljs.com/docs/themes/#snow/"><code>snow</code></a>) 時，就會在這些分組間加上間距，方便使用者進行操作：</p><pre><code class="typescript">const toolbarOptions = [[&#39;bold&#39;, &#39;italic&#39;], [&#39;link&#39;, &#39;image&#39;]];</code></pre><p>另外可以使用一個物件來指定自定義值的按鈕，並將格式名稱作為 key：</p><pre><code class="typescript">const toolbarOptions = [&#123; &#39;header&#39;: &#39;3&#39; &#125;];</code></pre><p>上面這個範例會在工具列上加入一個按鈕，這個按鈕代表的是 <code>header</code> 格式，並且按鈕會套用 <code>3</code> 這個自定義的值。換句話說，當點擊這個按鈕時，選定的文字會變成第三級標題 <code>&lt;h3&gt;</code>。</p><h2 id="下拉選單"><a href="#下拉選單" class="headerlink" title="下拉選單"></a>下拉選單</h2><p>下拉選單也是透過物件來定義，但與其他元素不同的地方在於，這裡會用一個陣列來存入所有可能的選項值。下拉選單選項的視覺表現（例如文字標籤或顏色）是由 CSS 來控制的。</p><p>例如，設定字體大小 <code>size</code> 的選項：</p><pre><code class="typescript">// Note false, not &#39;normal&#39;, is the correct value // quill.format(&#39;size&#39;, false) removes the format, // allowing default styling to work const toolbarOptions = [ &#123; size: [ &#39;small&#39;, false, &#39;large&#39;, &#39;huge&#39; ]&#125; ];</code></pre><p><code>size</code> 陣列中的 <code>false</code> 是用於移除格式，也就是把文字的大小回到預設的狀態。</p><h2 id="佈景主題和預設值"><a href="#佈景主題和預設值" class="headerlink" title="佈景主題和預設值"></a>佈景主題和預設值</h2><p>某些佈景主題，例如 Snow，會為下拉選單（如顏色和背景格式）提供預設值。當設定空的陣列在 <code>color</code> 或 <code>background</code> 時， <a href="https://quilljs.com/docs/themes/#snow/">Snow</a> 將預設提供 35 種顏色選項：</p><pre><code class="typescript">const toolbarOptions = [     [&#39;bold&#39;, &#39;italic&#39;, &#39;underline&#39;, &#39;strike&#39;], // toggled buttons     [&#39;blockquote&#39;, &#39;code-block&#39;],         [&#123; &#39;header&#39;: 1 &#125;, &#123; &#39;header&#39;: 2 &#125;], // custom button values     [&#123; &#39;list&#39;: &#39;ordered&#39;&#125;, &#123; &#39;list&#39;: &#39;bullet&#39; &#125;],     [&#123; &#39;script&#39;: &#39;sub&#39;&#125;, &#123; &#39;script&#39;: &#39;super&#39; &#125;], // 升冪與降冪    [&#123; &#39;indent&#39;: &#39;-1&#39;&#125;, &#123; &#39;indent&#39;: &#39;+1&#39; &#125;], // 縮排與減少縮排    [&#123; &#39;direction&#39;: &#39;rtl&#39; &#125;], // text direction         [&#123; &#39;size&#39;: [&#39;small&#39;, false, &#39;large&#39;, &#39;huge&#39;] &#125;], // custom dropdown     [&#123; &#39;header&#39;: [1, 2, 3, 4, 5, 6, false] &#125;],         [&#123; &#39;color&#39;: [] &#125;, &#123; &#39;background&#39;: [] &#125;], // dropdown 從 theme 獲取預設值     [&#123; &#39;font&#39;: [] &#125;],     [&#123; &#39;align&#39;: [] &#125;],         [&#39;clean&#39;] // 移除格式 ]; this.quill = new Quill(this.quillContainer.nativeElement, &#123;     modules: &#123;         toolbar: toolbarOptions     &#125;,     theme: &#39;snow&#39; &#125;);</code></pre><h2 id="進階客製化（Advanced-Customization）"><a href="#進階客製化（Advanced-Customization）" class="headerlink" title="進階客製化（Advanced Customization）"></a>進階客製化（Advanced Customization）</h2><p>如果需要對工具列更多的客製化，也能直接用 HTML 來手動創建工具列。只需要將 DOM 元素或選擇器傳遞給 Quill 即可。<code>ql-toolbar</code> 類會被添加到工具列容器中，而 Quill 會自動為具有 <code>ql-$&#123;format&#125;</code> 格式名稱的 <code>&lt;button&gt;</code> 和 <code>&lt;select&gt;</code> 元素附加對應的內建 handler。</p><pre><code class="html">&lt;!-- Create toolbar container --&gt; &lt;div #myToolbar&gt;&lt;!-- Add font size dropdown --&gt;     &lt;select class=&quot;ql-size&quot;&gt;        &lt;option value=&quot;small&quot;&gt;&lt;/option&gt;        &lt;!-- Note a missing, thus falsy value, is used to reset to default --&gt;        &lt;option selected&gt;&lt;/option&gt;        &lt;option value=&quot;large&quot;&gt;&lt;/option&gt;        &lt;option value=&quot;huge&quot;&gt;&lt;/option&gt;    &lt;/select&gt;    &lt;!-- Add a bold button --&gt;    &lt;button class=&quot;ql-bold&quot;&gt;&lt;/button&gt;    &lt;!-- Add subscript and superscript buttons --&gt;     &lt;button class=&quot;ql-script&quot; value=&quot;sub&quot;&gt;&lt;/button&gt;    &lt;button class=&quot;ql-script&quot; value=&quot;super&quot;&gt;&lt;/button&gt;&lt;/div&gt;&lt;div #quillContainer&gt;&lt;/div&gt; &lt;!-- Initialize editor with toolbar --&gt; </code></pre><pre><code class="typescript">this.quill = new Quill(this.quillContainer.nativeElement, &#123;     modules: &#123;         toolbar: this.myToolbar.nativeElement     &#125; &#125;); </code></pre><h2 id="自訂按鈕（Custom-Buttons）"><a href="#自訂按鈕（Custom-Buttons）" class="headerlink" title="自訂按鈕（Custom Buttons）"></a>自訂按鈕（Custom Buttons）</h2><p>當我們提供自己的 HTML 元素作為 Quill 的工具列時，Quill 會尋找特定的輸入元素來綁定功能。然而，除了 Quill 會自動識別和處理的元素外，你仍然可以加入和設計與 Quill 無關的自定義輸入元素。這些自定義的輸入元素可以和 Quill 的元素共存，且不會產生衝突。</p><pre><code class="html">&lt;div #myToolbar&gt;&lt;!-- Add buttons as you would before --&gt;    &lt;button class=&quot;ql-bold&quot;&gt;&lt;/button&gt;    &lt;button class=&quot;ql-italic&quot;&gt;&lt;/button&gt;    &lt;!-- But you can also add your own --&gt;    &lt;button class=&quot;custom-button&quot; (click)=&quot;doSomething()&quot;&gt;do something&lt;/button&gt;&lt;/div&gt;&lt;div id=&quot;editor&quot;&gt;&lt;/div&gt;</code></pre><pre><code class="typescript">this.quill = new Quill(this.quillContainer.nativeElement, &#123;    modules: &#123;        toolbar: this.myToolbar.nativeElement    &#125;&#125;); </code></pre><h2 id="處理器-Handler"><a href="#處理器-Handler" class="headerlink" title="處理器 (Handler)"></a>處理器 (Handler)</h2><p>工具列的控制項預設會套用或移除格式，但我們也可以用自定義的 handler 來取代行為，例如顯示外部的使用者介面。<br>Handler function 會綁定到工具列，並且傳入輸入元素的 <code>value</code> 屬性。如果相對應的格式是非啟動狀態，則會傳入 <code>false</code>。加入自定義的 handler 會覆寫預設的工具列和主題行為。</p><pre><code class="typescript">const toolbarOptions = &#123;  handlers: &#123;    // handlers 物件會與預設的 handler 物件合併    link: (value: string) =&gt; &#123;      if (value) &#123;        const href = prompt(&#39;Enter the URL&#39;);        this.quill.format(&#39;link&#39;, href);      &#125; else &#123;        this.quill.format(&#39;link&#39;, false);      &#125;    &#125;,  &#125;&#125;this.quill = new Quill(this.quillContainer.nativeElement, &#123;  modules: &#123;    toolbar: toolbarOptions  &#125;&#125;);// Handler 也可以在初始化之後加入const toolbar = this.quill.getModule(&#39;toolbar&#39;);toolbar.addHandler(&#39;image&#39;, showImageUI);</code></pre><p>在上面的範例，為 <code>link</code> 格式定義了一個 custom handler。當使用者點擊工具列的連結按鈕時，會彈出一個提示框可以輸入URL。當使用者輸入URL 則會把選取的文字變成一個連結。反之當使用者取消操作會移除文字的連結格式。另外，可以在 Quill 初始化之後，動態地加入更多的 handler，如 <code>showImageUI</code> 這個函數用來處理圖像插入的 UI。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>Quill 在初始化的時候，就算沒有給任何的 toolbar 設定，也會提供預設的功能選項直接使用，設定 toolbar 主要有兩種方式：</p><ol><li>使用 HTML 設置功能按鈕並指定 toolbar 的 <code>container</code><ul><li>Quill 會依照 <code>ql-*</code> class 名稱的 HTML 帶入對應的內建功能</li></ul></li><li>使用 toolbar options 陣列設置需要的功能<ul><li>不需要額外給定 HTML 或 container 即可初始化後渲染到 Quill 容器上</li></ul></li></ol><p>透過這些方式，我們可以靈活設計和調整 Quill 編輯器的工具列來滿足各種需求。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天對於北北基桃來說是個再正常不過的上班日了，但不知道為啥就沒有上班的氛圍，我想應該是新竹以南的夥伴們都在家防颱吧。沒有會議的一天可以完全專注的在開發工作上，雖然過程也遇到一些意外的挑戰，但還好都有初步解決了。明天還有一天班，之後就要好好充電休息一下，但還是要持續發文到 15 號了，希望扛的住…XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/cc354e601455a78eb7e63d82e711b31c67733d03">今日份的練習</a></li><li><a href="https://quilljs.com/docs/modules/toolbar/">Toolbar Module - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10334843">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 19：讀 Quill Editor API 技術文件 - Modules</title>
      <link href="/2023/10/04/quill-day-19/"/>
      <url>/2023/10/04/quill-day-19/</url>
      
        <content type="html"><![CDATA[<p>明天北北基桃沒有放颱風假，大家上班注意安全。<br>今天開始進到 Module 的章節。</p><p>Module 允許 Quill 的操作行為與功能實現客製化。有幾個官方支援的模組可供選擇，其中一些還有額外的配置選項和API。目前官網列出支援的模組有：<code>Toolbar</code>，<code>Keyboard</code>，<code>History</code>，<code>Clipboard</code>，以及<code>Syntax Highlighter</code>。各章節也都會提到如何使用以及有哪些 API 可供操作。</p><p>要啟用模組只需要把要使用的模組加到 Quill 的配置中即可：</p><pre><code class="typescript">const quill = new Quill(&#39;#editor&#39;, &#123;     modules: &#123;         &#39;history&#39;: &#123; // Enable with custom configurations             &#39;delay&#39;: 2500,             &#39;userOnly&#39;: true         &#125;,         &#39;syntax&#39;: true // Enable with default configuration     &#125; &#125;);</code></pre><p>Clipboard，Keyboard 和 History 模組是 Quill 所必需的，不需要明確設定就預設在裡面了，但也可以像其他模組一樣進行設定。</p><h2 id="繼承-Extending"><a href="#繼承-Extending" class="headerlink" title="繼承 (Extending)"></a>繼承 (Extending)</h2><p>模組也可以繼承和重新註冊，替換掉原本的模組。甚至原本預設內建的必要模組也能重新註冊來做替換。例如繼承 clipboard 模組並自訂一些功能：</p><pre><code class="typescript">const Clipboard = Quill.import(&#39;modules/clipboard&#39;); const Delta = Quill.import(&#39;delta&#39;); class PlainClipboard extends Clipboard &#123;     convert(html = null) &#123;         if (typeof html === &#39;string&#39;) &#123;             this.container.innerHTML = html;         &#125;         let text = this.container.innerText;         this.container.innerHTML = &#39;&#39;;         return new Delta().insert(text);     &#125; &#125; Quill.register(&#39;modules/clipboard&#39;, PlainClipboard, true); // Will be created with instance of PlainClipboard const quill = new Quill(&#39;#editor&#39;);</code></pre><p>上面這個範例只是為了解釋 module 提供的可能性。單純用既有模組提供的 API 或 config 通常會更容易些。在這個 <code>clipboard</code> 模組擴充的操作範例中，用現有的 <code>addMatcher</code> 其實就能夠滿足大部分的情境需求了。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天介紹了 Quill 的 module，強調其客製化，以及可繼承並擴展。Quill 內建了許多豐富的 module，讓我們可以按照需求選擇和配置。繼承的部分則允許開發者擴充新功能並替換原有的模組，同時也提到單純使用既有的 API 或設定也許就能滿足大部分的需求。在這個章節，我們了解如何利用 module 來啟用 Quill 的功能，並依照實際需求進行繼承及擴充自訂功能，之後來介紹並研究一下第三方的開源套件要如何使用，以及他們是如何實現自訂功能的。應該能有不少收穫。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>最近上下班的運氣都還不錯，儘管有下雨，但出門跟下班回家的這段時間都是無雨的，今天又去了整復保養一下，然後再去看中醫，弄得時間有點晚。這次的颱風感覺也是來者不善，放颱風假就乖乖待在家，看點書追個劇也好。我明天要繼續去上班了 QQ</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://quilljs.com/docs/modules/">Modules - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10334295">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 18：讀 Quill Editor API 技術文件 - Extension</title>
      <link href="/2023/10/03/quill-day-18/"/>
      <url>/2023/10/03/quill-day-18/</url>
      
        <content type="html"><![CDATA[<p>今天接著看 Extension 的部分，顧名思義就是和擴充功能相關的 API 使用。</p><h2 id="debug"><a href="#debug" class="headerlink" title="debug"></a>debug</h2><p>提供除錯用的靜態方法，可以開啟指定層級的 log 訊息，例如：<code>error</code>，<code>warn</code>，<code>log</code>，或 <code>info</code>。<br>傳入 <code>true</code> 等同於傳入 <code>log</code>，傳入 <code>false</code> 則是關閉所有 log 訊息。</p><p>方法：</p><pre><code class="typescript">Quill.debug(level: String | Boolean)</code></pre><p>範例：</p><pre><code class="typescript">Quill.debug(&#39;info&#39;);</code></pre><h2 id="import"><a href="#import" class="headerlink" title="import"></a>import</h2><p>將指定的擴充功能或模組引入 Quill。</p><p>方法：</p><pre><code class="typescript">Quill.import(path): any</code></pre><p>範例：</p><pre><code class="typescript">const Parchment = Quill.import(&#39;parchment&#39;);const Delta = Quill.import(&#39;delta&#39;);const Toolbar = Quill.import(&#39;modules/toolbar&#39;);const Link = Quill.import(&#39;formats/link&#39;);// 類似 ES6 的 import 語法: `import Link from &#39;quill/formats/link&#39;;`</code></pre><h2 id="register"><a href="#register" class="headerlink" title="register"></a>register</h2><p>用於註冊 module、theme 或 format。可以讓我們擴充和自定義 Quill 的功能。註冊執行之後可以使用 <code>Quill.import</code> 獲取。使用路徑前綴 ‘formats&#x2F;‘、’modules&#x2F;‘ 或 ‘themes&#x2F;‘ 分別註冊 <code>formats</code>、<code>modules</code> 或 <code>themes</code>。對於 <code>format</code>，可以直接帶入且路徑將自動生成。也會覆蓋掉具有相同路徑的定義。</p><p>方法：</p><pre><code class="typescript">Quill.register(format: Attributor | BlotDefinintion, supressWarning: Boolean = false)Quill.register(path: String, def: any, supressWarning: Boolean = false)Quill.register(defs: &#123; [String]: any &#125;, supressWarning: Boolean = false)</code></pre><p>範例：</p><pre><code class="typescript">// 自訂一個空 moduleconst Module = Quill.import(&#39;core/module&#39;);class CustomModule extends Module &#123;&#125;Quill.register(&#39;modules/custom-module&#39;, CustomModule);</code></pre><p><code>register</code> 方法使 Quill 的功能更加彈性和可擴展，允許開發人員自定義格式、模組和主題，進而更滿足特定的應用需求。</p><blockquote><p>註冊之後要留意一下初始化的 <code>options</code> 裡面是否也有加入 custom-module!</p></blockquote><h2 id="addContainer"><a href="#addContainer" class="headerlink" title="addContainer"></a>addContainer</h2><p>在 Quill container 內加入一個容器元素 (container element) 並回傳，作為編輯器本身的同層元素。通常 Quill 模組都會有以 ql- 當作前綴的 class name。選擇性的參數 <code>refNode</code>，表示容器的插入位置應該在這個 <code>refNode</code> 之前。</p><p>方法：</p><pre><code class="typescript">addContainer(className: String, refNode?: Node): ElementaddContainer(domNode: Node, refNode?: Node): Element</code></pre><p>範例：</p><pre><code class="typescript">// 使用 className 加入 container elementconst container = quill.addContainer(&#39;ql-custom&#39;);// 使用 element reference 取得的 DOMaddContainerWithNativeElement(quill: Quill, nativeElement: HTMLElement) &#123;  const toolEditor = document.querySelector(&#39;.ql-editor&#39;);  console.log(&#39;addContainerWithNativeElement&#39;);  quill.addContainer(nativeElement, toolEditor);&#125;</code></pre><p>因為是在 Angular 專案上，所以建議還是使用 <code>@ViewChild</code> 取得 element reference，如此一來在套用 CSS 樣式的時候，就不需要再加上像 <code>::ng-deep</code> 的方式套用， 避免影響子元件樣式。 </p><p>使用 element reference 加上指定位置後的效果：<br><img src="/2023/10/03/quill-day-18/20090749iPB48sCf4t.png" alt="加上指定位置後的效果"></p><h2 id="getModule"><a href="#getModule" class="headerlink" title="getModule"></a>getModule</h2><p>取得已加入 Quill instance 的模組。</p><p>方法：</p><pre><code class="typescript">getModule(name: String): any</code></pre><p>範例：</p><pre><code class="typescript">const toolbar = quill.getModule(&#39;custom-module&#39;);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>Quill 在擴充功能的部分提供了幾個 API，包含了模組引入、除錯、註冊，也能加入自訂的 container element，並直接獲取 Quill instance 裡面指定的模組，稍微整理一下：</p><ul><li><code>debug</code>：靜態方法用於開啟不同層級的 log 訊息，有助於開發和除錯。</li><li><code>import</code>：用於回傳 Quill library、格式、模組或主題的靜態方法。使自定義和擴充變得非常靈活。</li><li><code>register</code>：這個方法允許註冊和定義自己的模組、主題或格式，提高 Quill 的可擴展性。</li><li><code>addContainer</code>：允許在 Quill 容器內新增容器元素，使得界面結構更加靈活。</li><li><code>getModule</code>：取得已經加入到編輯器的模組，有助於模組的管理和操控。</li></ul><p>大多數情況下，靜態方法如 <code>register</code> 和 <code>import</code> 最好是在 <code>new Quill()</code> 之前使用，以確保在初始化 Quill 時能夠使用這些自定義 module 或定義。而 <code>debug</code> 則可以根據實際需要來決定使用的時機。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天整理文章的時候，看到新聞上寫有颱風名字叫做小犬，於是心血來潮查了一下，別問我為什麼要查 XD<br>根據教育部的辭典網站釋義：<br>1)幼小的狗。清．孔尚任《桃花扇》第四○齣：「行到那舊院，何用輕敲，也不怕小犬哰哰。」<br>2)謙稱自己的兒子。《紅樓夢》第一三回：「待服滿後，親帶小犬到府叩謝。」也作「豚犬」、「豚兒」。</p><p>貌似第一次聽到這樣的命名，以前的名字都滿酷的，但最近的颱風名稱似乎有點微妙。聽說小犬一點都不小，大家要做好防颱措施阿…QQ</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/1c036fa131e6c06204b206da7b891c07ddf8fe27">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#extension">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10333603">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 17：讀 Quill Editor API 技術文件 - Model</title>
      <link href="/2023/10/02/quill-day-17/"/>
      <url>/2023/10/02/quill-day-17/</url>
      
        <content type="html"><![CDATA[<p>今天看 Quill Editor 的 Model 技術文件介紹，根據文件的描述，語意版本控制（Semantic Versioning）不適用於實驗性 API，意思是 Model 的 API 目前仍然處於實驗性階段，代表未來可能會出現一些重大的改動而影響到 API 的穩定性，但可以先看過一遍並嘗試玩看看，未來有機會正式發布後，再考慮應用到正式的專案上。</p><p>透過 Model API 找到的 Blot 物件是 <code>LinkedList</code> 的資料結構：<br><img src="/2023/10/02/quill-day-17/20090749KPxBk00GWC.png" alt="LinkedList 的資料結構"></p><h2 id="find"><a href="#find" class="headerlink" title="find"></a>find</h2><p>這是一個靜態方法，可以代入 DOM 節點並回傳 Quill 或 Blot Instance。在後者的情況下，對 <code>bubble</code> 參數傳入 true 會向上尋找目標 DOM 的祖先，直到找到相應的 Blot。</p><p>方法：</p><pre><code class="typescript">Quill.find(domNode: Node, bubble: boolean = false): Blot | Quill</code></pre><p>範例：</p><pre><code class="typescript">find(quill: Quill, container: HTMLElement) &#123;  // 帶入 container 尋找並取得 quill instance  const target = Quill.find(container);  console.log(&#39;target is quill instance&#39;, target === quill);  // 編輯器輸入連結文字並嘗試取得 link node  quill.insertText(0, &#39;Hello, World!&#39;, &#39;link&#39;, &#39;https://google.com&#39;);  const linkNode = container.querySelector(&#39;a&#39;);  const findLinkNode = Quill.find(linkNode!);  console.log(&#39;linkNode&#39;, findLinkNode);&#125;</code></pre><h2 id="getIndex"><a href="#getIndex" class="headerlink" title="getIndex"></a>getIndex</h2><p>回傳從文件開頭到帶入的 blot 之間的距離長度。</p><p>方法：</p><pre><code class="typescript">getIndex(blot: Blot): Number</code></pre><p>範例：</p><pre><code class="typescript">// 預先輸入文字並取得第 10 個字元的 blotquill.insertText(0, &#39;Hello, World!&#39;);const [line, offset] = quill.getLine(10);console.log(&#39;line&#39;, line);// 帶入 blot 取得 indexconst index = quill.getIndex(line); // index + offset should == 10console.log(&#39;index&#39;, index);console.log(&#39;offset&#39;, offset);</code></pre><h2 id="getLeaf"><a href="#getLeaf" class="headerlink" title="getLeaf"></a>getLeaf</h2><p>回傳文件中指定索引處的葉節點。<code>leaf</code> 通常指的是資料結構中的末端節點。</p><p>方法：</p><pre><code class="typescript">getLeaf(index: Number): Blot</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello Good World!&#39;);quill.formatText(6, 4, &#39;bold&#39;, true);const [leaf, offset] = quill.getLeaf(7);// leaf 會是帶有值為 &quot;Good&quot; 的葉節點// offset 應為 1，因為回傳的葉節點在索引 6 開始console.log(&#39;leaf&#39;, leaf);console.log(&#39;offset&#39;, offset);</code></pre><h2 id="getLine"><a href="#getLine" class="headerlink" title="getLine"></a>getLine</h2><p>回傳帶入的索引值指定位置的行 blot 。</p><p>方法：</p><pre><code class="typescript">getLine(index: Number): [Blot, Number]</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello\nWorld!&#39;);const [line, offset] = quill.getLine(7);// line 應為代表第二個 &quot;World!&quot; 行的 Block Blotconsole.log(&#39;line&#39;, line);// offset 為 1，因為 index 7 是在第二行 &quot;World!&quot; 的第二個字元console.log(&#39;offset&#39;, offset);</code></pre><h2 id="getLines"><a href="#getLines" class="headerlink" title="getLines"></a>getLines</h2><p>回傳指定位置的行中所包含的 blot。</p><p>方法：</p><pre><code class="typescript">getLines(index: Number = 0, length: Number = remaining): Blot[]getLines(range: Range): Blot[]</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello\nGood\nWorld!&#39;);quill.formatLine(1, 1, &#39;list&#39;, &#39;bullet&#39;);const lines = quill.getLines(2, 5);// 帶有 ListItem 與 Block Blot 的陣列// 代表是前面的兩行console.log(&#39;lines&#39;, lines);// 帶入 range 物件const linesByRange = quill.getLines(&#123; index: 8, length: 5 &#125;);console.log(&#39;linesByRange&#39;, linesByRange);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天看了 Model 提供的 API，這些 API 主要是用於尋找 Blot 的相關應用，對於未來要自訂編輯器模組的功能實現時，可以利用這些 API 來找到正確的 Blot 並進一步處理文本內容，並且 Blot 提供的是 <code>linkedList</code> 的資料結構，因此對於節點的尋找來說，未來編輯內容量大的時候，可以研究看看<code>linkedList</code> 訪問節點的技巧來實現較有效率的搜尋處理。</p><p>Quill 的觀念基本上不難，較有挑戰的地方在於未來要滿足各種特殊需求時，要建立自訂的 Blot 必須要很清楚底層的生命週期與處理過程，這樣才能打造出高效且實用的自訂功能。找時間再繼續研究使用一些第三方套件，並嘗試了解這些套件是如何實現的，對於自訂功能的實現與優化應該會有所幫助。</p><p>再整理一下今天嘗試的 API：</p><ul><li><code>find</code>：透過 DOM 節點找到 Quill 或 Blot 實例。</li><li><code>getIndex</code>：回傳文件開頭到指定 blot 之間的距離。</li><li><code>getLeaf</code>：回傳指定索引處的葉節點。</li><li><code>getLine</code>：回傳指定索引位置的行 blot。</li><li><code>getLines</code>：回傳指定位置內的所有行 blot。</li></ul><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天突然意識到，這星期上完班之後，又是一個連續假期，這次的假期是要回宜蘭帶朋友四處走走，雖然住在宜蘭很久了，但還是有不少地方沒去過，趁這個機會去走走看。不過 11 月就完全沒有連假了，週末期望能好好的學習，並嘗試一些新玩意兒，還有買了一些書，要好好的閱讀一番。</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/f888866bcc3263bcdec796f564cb2ba38521c13e">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#model">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10332980">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 16：讀 Quill Editor API 技術文件 - Events</title>
      <link href="/2023/10/01/quill-day-16/"/>
      <url>/2023/10/01/quill-day-16/</url>
      
        <content type="html"><![CDATA[<p>今天來看 Events 的部分，Event 的使用方式就和 JavaScript 的事件監聽一樣，透過指定的事件名稱來監聽，並執行指定的方法。</p><h3 id="text-change"><a href="#text-change" class="headerlink" title="text-change"></a>text-change</h3><p><code>text-change</code> 事件在編輯器的內容發生變化時觸發。變更的細節、變更前的內容，以及變更的來源都會提供出來。來源如果是使用者觸發的，則 <code>source</code> 就會是 <code>user</code>。例如：</p><ul><li>使用者在編輯器中打字</li><li>使用者使用工具列格式化文字</li><li>使用者使用快捷鍵回上一步</li><li>使用者使用作業系統拼寫校正</li></ul><p>特例：<br>觸發內容變更的事件雖然也可能透過 API 呼叫，但如果觸發的原因是使用者操作導致的話，<code>source</code> 仍然要設為 <code>user</code>。舉個例子：當使用者點擊工具欄的模組功能，該模組會呼叫變更的 API，但由於是使用者點擊所造成的變化，因此我們在模組呼叫 API 的時候，帶入的 <code>source</code> 仍必須是 <code>user</code>。 </p><p>Silent Source：<br>呼叫 API 處理的內容變更也可能以 <code>source</code> 為 <code>silent</code> 的方式觸發，在這樣的情況下 <code>text-change</code> 將不會被觸發。不建議這樣的操作，因為這樣可能會導致撤銷的堆疊紀錄異常，或是間接影響到需要完整內容變化紀錄的功能。</p><p>選取 (Selection) 發生變化<br>文字內容的變化可能導致 selection 變化（例如，打字使游標前進），但是在 <code>text-change</code> handler 執行期間，selection 尚未更新，加上原生瀏覽器的行為可能導致 selection 狀態不一致的情況。因此要使用 <code>selection-change</code> 或 <code>editor-change</code> 來處理 selection 更新比較穩定。</p><p>Callback Signature：</p><pre><code class="typescript">handler(delta: Delta, oldContents: Delta, source: String)</code></pre><p>範例：</p><pre><code class="typescript">quill.on(&#39;text-change&#39;, function(delta, oldDelta, source) &#123;  if (source == &#39;api&#39;) &#123;     console.log(&quot;An API call triggered this change.&quot;);  &#125; else if (source == &#39;user&#39;) &#123;     console.log(&quot;A user action triggered this change.&quot;);   &#125; &#125;);</code></pre><h3 id="selection-change"><a href="#selection-change" class="headerlink" title="selection-change"></a>selection-change</h3><p>當使用者或 API 造成 selection 變更時觸發，<code>range</code> 代表 selection 的邊界。當 <code>range</code> 為 <code>null</code> 時，表示 selection 的丟失（通常是由於編輯器失去焦點）。我們也可以在收到 <code>range</code> 是 <code>null</code> 的時候，用這個事件當作焦點變更的 event 確認。</p><p>API 造成的選取範圍變更也可能會以 <code>source</code> 為 <code>silent</code> 觸發，在這樣的情況下就不會觸發 <code>selection-change</code>。如果 <code>selection-change</code> 是 side effect 的話就很有用。例如：輸入文字造成 selection 變更，但每個字元都觸發 <code>selection-change</code> 的話就可能會造成干擾。</p><p>Callback Signature：</p><pre><code class="typescript">handler(range: &#123; index: Number, length: Number &#125;,        oldRange: &#123; index: Number, length: Number &#125;,        source: String)</code></pre><p>範例：</p><pre><code class="typescript">quill.on(&#39;selection-change&#39;, function(range, oldRange, source) &#123;  if (range) &#123;     if (range.length == 0) &#123;      console.log(&#39;User cursor is on&#39;, range.index);    &#125; else &#123;       const text = quill.getText(range.index, range.length);      console.log(&#39;User has highlighted&#39;, text);    &#125;   &#125; else &#123;     console.log(&#39;Cursor not in the editor&#39;);   &#125;&#125;);</code></pre><h3 id="editor-change"><a href="#editor-change" class="headerlink" title="editor-change"></a>editor-change</h3><p>當觸發 <code>text-change</code> 或 <code>selection-change</code> 事件時，也會跟著觸發 <code>editor-change</code>，即使 <code>source</code> 是 <code>silent</code> 也是一樣。第一個參數是事件名稱，不是 <code>text-change</code> 就是 <code>selection-change</code>，之後的通常是傳遞給這些相應的 handler 參數。</p><p>Callback Signature：</p><pre><code class="typescript">handler(name: String, ...args)</code></pre><p>範例：</p><pre><code class="typescript">quill.on(&#39;editor-change&#39;, function(eventName, ...args) &#123;  if (eventName === &#39;text-change&#39;) &#123;     // args[0] will be delta   &#125; else if (eventName === &#39;selection-change&#39;) &#123;    // args[0] will be old range   &#125;&#125;);</code></pre><h2 id="on"><a href="#on" class="headerlink" title="on"></a>on</h2><p>監聽特定的事件並加入 event handler。</p><p>方法：</p><pre><code class="typescript">on(name: String, handler: Function): Quill</code></pre><p>範例：</p><pre><code class="typescript">quill.on(&#39;text-change&#39;, function() &#123;  console.log(&#39;Text change!&#39;); &#125;);</code></pre><h2 id="once"><a href="#once" class="headerlink" title="once"></a>once</h2><p>為事件的一次觸發加入 event handler。</p><p>方法：</p><pre><code class="typescript">once(name: String, handler: Function): Quill</code></pre><p>範例：</p><pre><code class="typescript">quill.once(&#39;text-change&#39;, function() &#123;  console.log(&#39;First text change!&#39;);&#125;);</code></pre><h2 id="off"><a href="#off" class="headerlink" title="off"></a>off</h2><p>移除 event handler</p><p>方法：</p><pre><code class="typescript">off(name: String, handler: Function): Quill</code></pre><p>範例：</p><pre><code class="typescript">function handler() &#123;   console.log(&#39;Hello!&#39;);&#125;quill.on(&#39;text-change&#39;, handler);quill.off(&#39;text-change&#39;, handler);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>Quill 提供了三種事件監聽類型分別是 <code>text-change</code>，<code>selection-change</code>，以及 <code>editor-change</code>，整理一下今天練習的 event 方法：</p><ul><li><strong>text-change</strong>：內容變化時觸發，包括使用者操作或API呼叫等。</li><li><strong>selection-change</strong>：選取範圍變更時觸發，提供選取的邊界，也能作為焦點變更的事件。</li><li><strong>editor-change</strong>：結合觸發 <code>text-change</code> 與 <code>selection-change</code> 的變更。</li><li><strong>on</strong>：根據監聽類型加入對應的事件處理器。</li><li><strong>once</strong>：根據監聽類型加入只執行一次的事件處理器。</li><li><strong>off</strong>：移除事件處理器。</li></ul><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>前幾天在 DefinitelyTyped 提的 Quill PR 終於合併了，目前只要重新 npm install 就能夠把 OP 類型錯誤的問題解決了，要確認一下 types 的版本是 <code>2.0.12</code>。久違的 OpenSource contribution XD 希望對大家有所幫助 :D</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/789afdecfc34b102d486f85722dca578eecf4bfc">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#events">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10332125">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 15：讀 Quill Editor API 技術文件 - Editor</title>
      <link href="/2023/09/30/quill-day-15/"/>
      <url>/2023/09/30/quill-day-15/</url>
      
        <content type="html"><![CDATA[<p>今天繼續配著烤肉和月餅來看 Editor 的部分。Editor API 比前面的操作簡單一些，主要用在判斷使用者的游標或焦點狀態，並提供啟用與禁用編輯功能。</p><h2 id="blur"><a href="#blur" class="headerlink" title="blur"></a>blur</h2><p>移除編輯器的 <code>focus</code> 狀態，從使用這的角度來看就是輸入文字的游標離開編輯器。</p><p>方法：</p><pre><code class="typescript">blur()</code></pre><p>範例：</p><pre><code class="typescript">quill.blur();</code></pre><h2 id="enable"><a href="#enable" class="headerlink" title="enable"></a>enable</h2><p>控制編輯器是否能讓使用者進行輸入。當編輯器在 <code>disabled</code> 狀態時，不影響 <code>source</code> 為 <code>api</code> 與 <code>slient</code> 的 API 呼叫。</p><p>方法：</p><pre><code class="typescript">enable(enabled: boolean = true)</code></pre><p>範例：</p><pre><code class="typescript">quill.enable();quill.enable(false); // 禁用使用者輸入</code></pre><h2 id="disable"><a href="#disable" class="headerlink" title="disable"></a>disable</h2><p>將編輯器設為禁用編輯狀態，如同上面的範例所提到的，相當於 <code>enable(false)</code> 的意思。</p><h2 id="focus"><a href="#focus" class="headerlink" title="focus"></a>focus</h2><p>將焦點回到編輯器上，游標會停留在上一次離開 (<code>blur</code>) 的地方。</p><p>方法：</p><pre><code class="typescript">focus()</code></pre><p>範例：</p><pre><code class="typescript">quill.focus();</code></pre><h2 id="hasFocus"><a href="#hasFocus" class="headerlink" title="hasFocus"></a>hasFocus</h2><p>確認焦點是否在編輯器的輸入範圍，這邊需要留意的是焦點在 <code>toolbar</code> 或是 <code>tooltip</code> 時，都不算在編輯器。</p><p>方法：</p><pre><code class="typescript">hasFocus(): Boolean</code></pre><p>範例：</p><pre><code class="typescript">quill.hasFocus();</code></pre><h2 id="update"><a href="#update" class="headerlink" title="update"></a>update</h2><p>同步檢查編輯器的使用者更新，並在發生修改時觸發事件。對於有協作需求要解決衝突時，需要最新的狀態下相當實用。<code>Source</code> 的來源可以是 <code>user</code>，<code>api</code>， 以及 <code>silent</code>。</p><p>由於這主要是用於線上共筆時可能造成編輯衝突時，可以透過 <code>update</code> 方法來同步編輯器的狀態，因此這之後如果有機會再來嘗試看看。</p><p>方法：</p><pre><code class="typescript">update(source: String = &#39;user&#39;)</code></pre><p>範例：</p><pre><code class="typescript">quill.update();</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>稍微回顧一下今天研究 Editor 相關的 API：</p><ul><li><strong>blur</strong>：移除編輯器的焦點狀態。</li><li><strong>enable</strong>：控制編輯器是否能讓使用者進行輸入，包括禁用使用者輸入。</li><li><strong>disable</strong>：相當於 <code>enable(false)</code>，禁止使用者輸入。</li><li><strong>focus</strong>：將焦點回到編輯器上，游標停留在上次離開的地方。</li><li><strong>hasFocus</strong>：確認焦點是否在編輯器上。</li><li><strong>update</strong>：同步檢查編輯器的使用者更新並在修改時觸發事件。<br>除了 <code>update</code> 的操作沒辦法立即呈現之外，大部分的 API 都還滿淺顯易懂的。</li></ul><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天邊塞車邊寫文章，還好有弟弟幫忙開車，早上七點多有驚無險的避免了一場危險，前面的車子似乎快睡著了又沒有打開車道維持輔助，導致車子直接嚕到中央護欄，還好沒翻車，雖然沒看到左側的鈑金狀況，但應該是滿慘的。再次證明了保持車距的重要性。</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/6f5bc5d83ebb73e78952a4567ea22f006343dd64">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#editor">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10331555">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 14：讀 Quill Editor API 技術文件 - Selection</title>
      <link href="/2023/09/29/quill-day-14/"/>
      <url>/2023/09/29/quill-day-14/</url>
      
        <content type="html"><![CDATA[<p>昨天研究並練習關於套用文本的行內與區塊樣式，初步把每個 API 的使用方式都看過一遍，今天輪到編輯器選取功能相關的 API，繼續給他看下去 XD</p><h2 id="getBounds"><a href="#getBounds" class="headerlink" title="getBounds"></a>getBounds</h2><p>這個方法非常實用，用於獲取指定索引或選取範圍的界限（bounds）。並返回一個包含界限的物件，裡面會有 <code>left</code>，<code>top</code>，<code>width</code> 以及 <code>height</code> 屬性，分別代表指定索引的左上角位置和尺寸。通常用來定位游標或選取的範圍在編輯器容器內的位置。例如可以利用這個方法決定在編輯器內容旁邊或是游標的位置顯示自訂的選單或者工具提示。</p><p>方法：</p><pre><code class="typescript">getBounds(index: Number, length: Number = 0):     &#123; left: Number, top: Number, height: Number, width: Number &#125;</code></pre><p>範例：<br>先在編輯器的元素下面新增一個 <code>tooltip</code> 標籤：</p><pre><code class="html">&lt;div id=&quot;tooltip&quot; style=&quot;display: none; position: absolute; background-color: lightgray;&quot;&gt; 我是一個小提示 &lt;/div&gt;</code></pre><p>實現監聽事件，在文本選取的時候判斷選取的位置來顯示 tooltip：</p><pre><code class="typescript">// 監聽文本選擇事件quill.on(&#39;selection-change&#39;, function(range) &#123;  if (range) &#123;    if (range.length &gt; 0) &#123;      // 獲取選擇範圍的界限      const bounds = quill.getBounds(range.index, range.length);      // 定位和顯示小提示      const tooltip = document.getElementById(&#39;tooltip&#39;);      tooltip.style.left = bounds.left + &#39;px&#39;;      tooltip.style.top = (bounds.top + bounds.height) + &#39;px&#39;;      tooltip.style.display = &#39;block&#39;;    &#125; else &#123;      // 隱藏小提示      const tooltip = document.getElementById(&#39;tooltip&#39;);      tooltip.style.display = &#39;none&#39;;    &#125;  &#125;&#125;);</code></pre><p>效果如下：<br><img src="/2023/09/29/quill-day-14/20090749cNFuDeHiXF.png" alt="Tooltip 效果如下"></p><h2 id="getSelection"><a href="#getSelection" class="headerlink" title="getSelection"></a>getSelection</h2><p>獲取編輯器中當前的選取範圍。可帶入 optional 參數 <code>focus</code>，如果為 <code>true</code>，則獲取焦點之後返回選取的範圍 <code>index</code> 與 <code>length</code>，如果為 <code>false</code>，則返回 <code>null</code>。</p><p>方法：</p><pre><code class="typescript">getSelection(focus = false): &#123; index: Number, length: Number &#125;</code></pre><p>範例：</p><pre><code class="typescript">var range = quill.getSelection();if (range) &#123;  if (range.length == 0) &#123;    console.log(&#39;User cursor is at index&#39;, range.index);  &#125; else &#123;    var text = quill.getText(range.index, range.length);    console.log(&#39;User has highlighted: &#39;, text);  &#125;&#125; else &#123;  console.log(&#39;User cursor is not in editor&#39;);&#125;  </code></pre><h2 id="setSelection"><a href="#setSelection" class="headerlink" title="setSelection"></a>setSelection</h2><p>設置編輯器中的選取範圍，這也會使編輯器是在 <code>focus</code> 的狀態。如果傳入的參數為 <code>null</code>，則會離開焦點並觸發 <code>blur</code> 事件。</p><p>方法：</p><pre><code class="typescript">setSelection(index: Number, length: Number = 0, source: String = &#39;api&#39;)setSelection(range: &#123; index: Number, length: Number &#125;, source: String = &#39;api&#39;)</code></pre><p>範例：</p><pre><code class="typescript">quill.setSelection(0, 5);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>稍微整理一下：</p><ul><li><code>getBounds</code>: 獲取指定索引的座標或界限資訊，常用於定位游標或選取範圍在編輯器內的位置。</li><li><code>getSelection</code>: 獲取編輯器中當前的選取範圍，可用於判斷用戶選取的內容或游標位置。</li><li><code>setSelection</code>: 設置編輯器中的選取範圍，使編輯器處於 Focus 狀態。</li></ul><p>今天詳細探討了編輯器的 Selection 功能，Quill 提供了選取範圍相關的控制方法，到目前為止，無論是文本樣式或是內容選取，可以看到大部分的操作都離不開 <code>index</code> 與 <code>length</code>，而 <code>range</code> 是一個滿方便使用的參數，可以知道選取的起點以及選取的長度，以便我們在自訂功能的時候可以做為位置索引的參考。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>已經好幾年沒有玩過手機遊戲了，最近上下班通勤時間都會玩一款新的手機遊戲叫 Monster Hunter Now，整體還滿有趣的，是 Niantic 也就是開發 Ingress 以及 Pokemon Go 的開發商，這遊戲也是要走出去戶外實際去看地圖上有哪些資源以及魔物，也能夠與其他玩家來進行遊戲。不過有個小缺點，就是當 HP 不夠的時候需要使用藥水，那個藥水除了每天提供五罐免費的之外，其他時間若喝完的話，就需要等時間回復或者直接打開線上商城買藥水道具，就是要課金的意思，但畢竟是休閒，沒血的話就乖乖的等待回滿再繼續被魔物虐了 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/5a1302ac5145a19ebd6df9db2f9d6f22c4a66141">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#selection">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10330722">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 13：讀 Quill Editor API 技術文件 - Formatting</title>
      <link href="/2023/09/28/quill-day-13/"/>
      <url>/2023/09/28/quill-day-13/</url>
      
        <content type="html"><![CDATA[<p>繼昨天的 Contents 相關的 API，今天來看看 Formatting 的部分。</p><h2 id="format"><a href="#format" class="headerlink" title="format"></a>format</h2><p>根據使用者當前選擇的字串套用文字格式，回傳的 Delta 代表變更的內容。當使用者選擇字串長度為 <code>0</code> 時，代表是游標的狀態，對應的文字樣式則會變成啟動狀態，使用者接下來輸入的內容則會套用啟動的文字樣式。<code>Source</code> 一樣可以設定 <code>user</code>，<code>api</code> 或 <code>silent</code>。當呼叫的時候如果編輯器為禁用(disabled) 狀態，則會直接略過 <code>source</code> 為 <code>user</code> 的呼叫。</p><ul><li><code>source</code> 預設是 <code>api</code></li></ul><p>方法：</p><pre><code class="typescript">format(name: String, value: any, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.format(&#39;color&#39;, &#39;red&#39;);quill.format(&#39;align&#39;, &#39;right&#39;);</code></pre><h2 id="formatLine"><a href="#formatLine" class="headerlink" title="formatLine"></a>formatLine</h2><p>將選到的行數套用樣式，回傳的 Delta 代表變更的內容。關於可使用的樣式有哪些，可以參考官網文件 <a href="https://quilljs.com/docs/formats/">formats</a>描述。這個方法主要是處理區塊 (block) 樣式，當呼叫的時候如果帶入的樣式是屬於行內 (inline) 樣式，則會沒有效果。要移除格式的話直接在 <code>value</code> 的參數傳入 <code>false</code> 即可。另外套用區塊樣式的時候，可能會在套用後導致使用者當前的選擇被取消，並且游標移動到新的位置。</p><ul><li><code>source</code> 預設是 <code>api</code></li></ul><p>方法：</p><pre><code class="typescript">formatLine(index: Number, length: Number, source: String = &#39;api&#39;): DeltaformatLine(index: Number, length: Number, format: String, value: any, source: String = &#39;api&#39;): Delta formatLine(index: Number, length: Number, formats: &#123; [String]: any &#125;, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello\nWorld!\n&#39;);quill.formatLine(1, 2); // 沒有給樣式的話，預設套用的樣式是 boldquill.formatLine(1, 2, &#39;align&#39;, &#39;right&#39;); // 第一行置右quill.formatLine(4, 4, &#39;align&#39;, &#39;center&#39;); // 兩行都置中// 套用多個區塊樣式quill.formatLine(0, 5, &#123;  list: &#39;bullet&#39;,  align: &#39;right&#39;,&#125;);</code></pre><h2 id="format-VS-formatLine"><a href="#format-VS-formatLine" class="headerlink" title="format VS formatLine"></a>format VS formatLine</h2><p>最主要的差別就是 <code>format</code> 用在更改選取範圍內的特定格式，例如字體大小、顏色、粗體等。而 <code>formatLine</code> 處理的是整行的樣式，例如列表、對齊方式等。</p><h2 id="formatText"><a href="#formatText" class="headerlink" title="formatText"></a>formatText</h2><p>一樣是在編輯器針對選定的範圍套用文字的樣式，回傳的是內容變更的 Delta，如果要移除文字樣式，則直接在對應樣式的值帶入 <code>false</code> 即可移除。如果是操作 block 相關的樣式，使用者的選擇範圍可能不會保留。<code>Source</code> 的來源有 <code>user</code>，<code>api</code>，以及 <code>silent</code>，當編輯器為 <code>disabled</code> 狀態則會直接無視 <code>source</code> 為 <code>user</code> 的呼叫。</p><ul><li><code>source</code> 預設是 <code>api</code></li></ul><p>方法：</p><pre><code class="typescript">formatText(index: Number, length: Number, source: String = &#39;api&#39;): Delta formatText(index: Number, length: Number, format: String, value: any, source: String = &#39;api&#39;): DeltaformatText(index: Number, length: Number, formats: &#123; [String]: any &#125;, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello\nWorld!\n&#39;);quill.formatText(0, 5, &#39;bold&#39;, true); // 將 Hello 設為粗體quill.formatText(0, 5, &#123; // 將 Hello 解除粗體，並設為藍色   &#39;bold&#39;: false,   &#39;color&#39;: &#39;rgb(0, 0, 255)&#39;  &#125;);quill.formatText(5, 1, &#39;align&#39;, &#39;right&#39;); // 將 Hello 的那一行置右</code></pre><h2 id="getFormat"><a href="#getFormat" class="headerlink" title="getFormat"></a>getFormat</h2><p>這個方法可以讓我們查詢特定範圍內文字的格式。如果範圍內的所有文字共用相同的格式，則會回傳該格式。如果有不同的真值 (truthy value)，則會回傳所有的真值在陣列中。當不帶參數呼叫此方法，將針對當前使用者選取的範圍進行操作。</p><ul><li><code>source</code> 預設是 <code>api</code></li></ul><p>方法：</p><pre><code class="typescript">getFormat(range: Range = current): &#123; [String]: any &#125;getFormat(index: Number, length: Number = 0): &#123; [String]: any &#125;</code></pre><p>範例：</p><pre><code class="typescript">// 假設設定一段文字 Hello World!，並設定樣式quill.setText(&#39;Hello World!&#39;);quill.formatText(0, 2, &#39;bold&#39;, true);quill.formatText(1, 2, &#39;italic&#39;, true);quill.getFormat(0, 2); // &#123; bold: true &#125;quill.getFormat(1, 1); // &#123; bold: true, italic: true &#125;quill.formatText(0, 2, &#39;color&#39;, &#39;red&#39;);quill.formatText(2, 1, &#39;color&#39;, &#39;blue&#39;);quill.getFormat(0, 3); // &#123; color: [&#39;red&#39;, &#39;blue&#39;] &#125;quill.setSelection(3);quill.getFormat(); // &#123; italic: true, color: &#39;blue&#39; &#125;quill.format(&#39;strike&#39;, true);quill.getFormat(); // &#123; italic: true, color: &#39;blue&#39;, strike: true &#125;quill.formatLine(0, 1, &#39;align&#39;, &#39;right&#39;);quill.getFormat(); // &#123; italic: true, color: &#39;blue&#39;, strike: true, // align: &#39;right&#39; &#125;</code></pre><h2 id="removeFormat"><a href="#removeFormat" class="headerlink" title="removeFormat"></a>removeFormat</h2><p>將選定的範圍內刪除所有的格式及嵌入內容，並回復到沒有格式的狀態。回傳的 Delta 代表變更的操作，如果範圍內包含到 block format，也會一併移除。因此使用者的選取狀態可能不會被保留。<code>Source</code> 可以是 <code>user</code>，<code>api</code> 或 <code>silent</code>。當編輯器為 <code>disabled</code> 狀態時，<code>source</code> 為 <code>user</code> 的呼叫將會被忽略。</p><ul><li><code>source</code> 預設是 <code>api</code></li></ul><p>方法：</p><pre><code class="typescript">removeFormat(index: Number, length: Number, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.setContents([  &#123; insert: &#39;Hello&#39;, &#123; bold: true &#125; &#125;,  &#123; insert: &#39;\n&#39;, &#123; align: &#39;center&#39; &#125; &#125;,  &#123; insert: &#123; formula: &#39;x^2&#39; &#125; &#125;,  &#123; insert: &#39;\n&#39;, &#123; align: &#39;center&#39; &#125; &#125;,  &#123; insert: &#39;World&#39;, &#123; italic: true &#125;&#125;,  &#123; insert: &#39;\n&#39;, &#123; align: &#39;center&#39; &#125; &#125;]);quill.removeFormat(3, 7);// 編輯器在執行之後內容會變成// [// &#123; insert: &#39;Hel&#39;, &#123; bold: true &#125; &#125;,// &#123; insert: &#39;lo\n\nWo&#39; &#125;,// &#123; insert: &#39;rld&#39;, &#123; italic: true &#125;&#125;,// &#123; insert: &#39;\n&#39;, &#123; align: &#39;center&#39; &#125; &#125;// ]</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天嘗試使用格式化相關的 API，基本上使用的方式都差不多，但我們還沒討論到 Format 還有哪些可以使用，剛才的介紹中也有提到<a href="https://quilljs.com/docs/formats/">這篇文件</a>有列出所有支援的格式，要找時間來實驗看看並感受一下。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>明天就開始一小段假期，不過按照往年的慣例，都會先回去宜蘭開車回台南拜拜，希望這次塞車不要塞的太久QQ，儘管早上四點半就起床，五點就出門了，到了七八點還是會開始塞。印象中過台中之前都滿大的機會遇到塞車的情況，還好可以跟弟弟輪流開，不至於累到不行 XD </p><p>祝中秋佳節愉快 :)</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/275e5d30a3206460dfbca1cc292dda0f6d5f15f5">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#format">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10330316">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 12：讀 Quill Editor API 技術文件 - Content (下)</title>
      <link href="/2023/09/27/quill-day-12/"/>
      <url>/2023/09/27/quill-day-12/</url>
      
        <content type="html"><![CDATA[<p>今天就繼續來看 Content 相關的 API 後半段。</p><h2 id="insertEmbed"><a href="#insertEmbed" class="headerlink" title="insertEmbed"></a>insertEmbed</h2><p>將嵌入式內容插入編輯器，return 為更改後的 Delta 物件。<code>source</code> 可以是 <code>user</code>、<code>api</code> 或 <code>silent</code>。當編輯器是 <code>disabled</code> 狀態時，當 <code>source</code> 設為 <code>user</code> 的呼叫則會被忽略。</p><ul><li><code>index</code> 可以選擇要插入的位置索引值</li></ul><p>方法：</p><pre><code class="typescript">insertEmbed(index: Number, type: String, value: any, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.insertEmbed(10, &#39;image&#39;, &#39;https://quilljs.com/images/cloud.png&#39;);</code></pre><h2 id="insertText"><a href="#insertText" class="headerlink" title="insertText"></a>insertText</h2><p>顧名思義將文字插入編輯器，可以選擇使用指定格式或多種格式。return 收到的是更新後的 Delta 物件。<code>source</code> 可以是 <code>user</code>、<code>api</code> 或 <code>silent</code>。當編輯器 <code>disabled</code> 時，<code>source</code> 為 <code>user</code> 的呼叫將直接略過。</p><p>方法共有三種，後兩者的差別在於 format 可以設一個或多個文字格式。</p><pre><code class="typescript">insertText(index: Number, text: String, source: String = &#39;api&#39;): Delta insertText(index: Number, text: String, format: String, value: any, source: String = &#39;api&#39;): Delta insertText(index: Number, text: String, formats: &#123; [String]: any &#125;, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.insertText(0, &#39;Hello&#39;); quill.insertText(3, &#39;Hello&#39;, &#39;bold&#39;, true); quill.insertText(8, &#39;Quill&#39;, &#123; &#39;color&#39;: &#39;#ffff00&#39;, &#39;italic&#39;: true &#125;);</code></pre><h2 id="setContents"><a href="#setContents" class="headerlink" title="setContents"></a>setContents</h2><p>將參數的內容覆蓋編輯器。內容必須以換行符號 <code>\n</code> 結尾。return 收到的是更新後的 Delta。如果給定 Delta 沒有無效操作，這將與傳入的 Delta 相同。<code>source</code> 可以為 <code>user</code>、<code>api</code> 或 <code>silent</code>。當編輯器是 <code>disabled</code> 狀態時，當<code>source</code> 為 <code>user</code> 的呼叫則會被忽略。</p><p>方法：</p><pre><code class="typescript">setContents(delta: Delta, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">// 使用 new Delta() 新增 Delta 物件const delta = new Delta()    .insert(&#39;This is a title&#39;)    .insert(&#39;\n&#39;, &#123; header: 1 &#125;)    .insert(&#39;This is a subtitle \n&#39;, &#123;header: 2, color: &#39;red&#39; &#125;)    .insert(&#39;The description is Hello World&#39;, &#123;    bold: true,    color: &#39;purple&#39;,    &#125;);quill.setContents(delta);</code></pre><p>上面這個範例可以觀察到套用 <code>header</code> 的變化，除了從 <code>text-change</code> 觀察到的套用方式，如果想要在一個 <code>insert</code> 就實現樣式與 <code>header</code> 格式套用，可以在文字內容的最後加上換行符號，這樣加上 <code>header</code> 在 <code>attribute</code> 上才會有效果。</p><h2 id="setText"><a href="#setText" class="headerlink" title="setText"></a>setText</h2><p>將純文字內容覆蓋到編輯器，return 收到的是更新後的 Delta，文字內容必須以換行符號做結尾，沒有加上的話，編輯器會另外加上。與 <code>setContents</code> 不同的是，<code>setText</code> 只能將純文字覆蓋到編輯器，而 <code>setContents</code> 的文字內容可以包含不同的格式。<code>source</code> 可以為 <code>user</code>、<code>api</code> 或 <code>silent</code>，預設是 <code>api</code>。當編輯器是 <code>disabled</code> 狀態時，當<code>source</code> 為 <code>user</code> 的呼叫則會被忽略。</p><p>方法：</p><pre><code class="typescript">setText(text: String, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.setText(&#39;Hello\n&#39;);</code></pre><h2 id="updateContents"><a href="#updateContents" class="headerlink" title="updateContents"></a>updateContents</h2><p>將 Delta 資料更新到編輯器，return 收到的是更新操作的 Delta。如果傳入的 Delta 沒有不合法的操作，return 收到的 Delta 則會是相同的內容。舉例來說，當編輯器沒有內容，但仍然執行 <code>retain(6)</code> 的話，實際上回傳的 Delta 中的 <code>retain</code> 會只有 1，因為空白的編輯器會預設一個換行符號，因此長度只有 <code>1</code> 可以 <code>retain</code>。<br>另外，即使執行 <code>delete(5)</code>，收到的 Delta 變化也不會有看到 ops 中有 <code>delete</code> 的操作，畢竟編輯器沒有內容可以讓我們刪除。</p><p>方法：</p><pre><code class="typescript">updateContents(delta: Delta, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">// 假設編輯器當前的內容 [&#123; insert: &#39;Hello World!&#39; &#125;]quill.updateContents(new Delta()  .retain(6) // Keep &#39;Hello &#39;  .delete(5) // &#39;World&#39; is deleted  .insert(&#39;Quill&#39;)  .retain(1, &#123; bold: true &#125;) // Apply bold to exclamation mark);// 編輯器現在會變成 [//   &#123; insert: &#39;Hello Quill&#39; &#125;,//   &#123; insert: &#39;!&#39;, attributes: &#123; bold: true&#125; &#125;// ]</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>在實際看過每個方法及體驗過使用方式後，對於 Contents API 的運用有初步的認識，並在不同的情境下選擇適合的 API ，透過帶入不同參數的呼叫方式實現功能，我們也可以在特殊情況自訂 <code>source</code> 來決定保留或跳過編輯器的觸發機制，明天接著進入到 Formatting 的章節，也就是套用文字格式。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>最近午餐跟著其他同事點外賣，不過也許是上班日的關係，在尖峰時段單點東西似乎特別容易漏掉，漏餐的話，幫忙開團的同事還要確認是否有其他同事也沒拿到，然後還要處理退款的申請，再次感謝願意開團的同事 XD。看來以後在尖峰時段還是盡量點套餐比較保險…也許吧XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/ee5d69d6180cba551f71523af00152bf827b6f01">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#content">Quill API - Conetent</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10329481">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 11：讀 Quill Editor API 技術文件 - Content (上)</title>
      <link href="/2023/09/26/quill-day-11/"/>
      <url>/2023/09/26/quill-day-11/</url>
      
        <content type="html"><![CDATA[<p>今天開始來細看 Quill Editor 的技術文件，看看 Quill 有哪些方法可以使用。同時也準備了範例練習，實際呼叫並觀察也許會比較有感覺。這會是一段細節探索的旅程。</p><h2 id="關於-Source"><a href="#關於-Source" class="headerlink" title="關於 Source"></a>關於 <code>Source</code></h2><p>在閱讀技術文件的時候，有部分的 <code>function</code> 會提供 <code>Source</code> 的參數名稱，稍微研究了一下。</p><ul><li>API：當更改的事件來自 API 的呼叫，例如直接用 JavaScript 呼叫 Instance 的 function</li><li>User：當變更來自使用者的操作時，例如：使用者在編輯器打字輸入內容、貼上圖片或是修改文字樣式。</li><li>Silent：此選項允許我們在不觸發任何 Quill 事件的情況下進行更改。這在某些情況下很實用，例如，我們想要在不通知其他程式的情況下更新編輯器的內容。</li></ul><p>大部分的情況是不需要自訂設定這些值，只有在較特殊的情況下，需要額外設置以更精確的控制編輯的行為。例如：</p><pre><code class="typescript">// 使用 &#39;api&#39; 作為 source，代表這個更改是由 API 控制的quill.format(&#39;bold&#39;, true, &#39;api&#39;); // 使用 &#39;user&#39; 作為 source，代表這個更改是模擬使用者操作quill.format(&#39;italic&#39;, true, &#39;user&#39;); </code></pre><p>透過這樣的分別使用，我們可以在事件監聽或其他處理邏輯中區分更改的來源，進而執行不同的操作或處理。例如我們只對使用者所做的更改進行特定的處理，並忽略由 API 控制的更改。透過 <code>source</code> 的設置就讓我們滿足這樣的需求。</p><h2 id="deleteText：在指定位置刪除文字"><a href="#deleteText：在指定位置刪除文字" class="headerlink" title="deleteText：在指定位置刪除文字"></a>deleteText：在指定位置刪除文字</h2><p>刪除的來源可以是從 <code>user</code>, <code>api</code> 或 <code>silent</code>。當編輯器狀態為 disabled 時，會直接忽略掉從 <code>user</code> 來的呼叫</p><p>方法：</p><pre><code class="typescript">deleteText(index: Number, length: Number, source: String = &#39;api&#39;): Delta</code></pre><p>範例：</p><pre><code class="typescript">quill.deleteText(4, 6) // 從第 4 個位置，刪除長度 6 的內容</code></pre><h2 id="getContents：獲取編輯器指定位置與長度的內容"><a href="#getContents：獲取編輯器指定位置與長度的內容" class="headerlink" title="getContents：獲取編輯器指定位置與長度的內容"></a>getContents：獲取編輯器指定位置與長度的內容</h2><p>獲取編輯器的內容以及格式資料，收到的是 Delta 物件。可選參數有兩個：</p><ul><li><code>index</code>：指定獲取內容的起始索引，預設是從 <code>0</code></li><li><code>length</code>：指定要獲取內容的長度，預設 <code>remaining</code> 是指從起始索引後的剩餘內容</li></ul><p>方法：</p><pre><code class="typescript">getContents(index: Number = 0, length: Number = remaining): Delta</code></pre><p>範例：</p><pre><code class="typescript">// 獲取完整內容的 Deltaconst delta = quill.getContents();// 獲取部分內容的 Deltaconst delta = quill.getContents(27, 5);</code></pre><h2 id="getLength：獲取編輯器內容的長度"><a href="#getLength：獲取編輯器內容的長度" class="headerlink" title="getLength：獲取編輯器內容的長度"></a>getLength：獲取編輯器內容的長度</h2><p>獲取編輯器內容的長度。<strong>需要注意的是，即使 Quill 為空，仍然有一個由 ‘\n’ 表示的空行，因此 getLength 將返回 1</strong>。</p><p>方法：</p><pre><code class="typescript">getLength(): Number</code></pre><p>範例：</p><pre><code class="typescript">const length = quill.getLength();</code></pre><h2 id="getText：獲取指定位置與長度的文本內容"><a href="#getText：獲取指定位置與長度的文本內容" class="headerlink" title="getText：獲取指定位置與長度的文本內容"></a>getText：獲取指定位置與長度的文本內容</h2><p>獲取編輯器的字串內容，非字串的內容會直接省略，因此返回的字串長度可能會比呼叫 <code>getLength</code> 回傳的編輯器長度短些。這邊一樣要留意的是，即使編輯器是空的沒有內容，仍然會留一個空行，所以在這樣的情況將會返回 <code>\n</code>。</p><ul><li><code>index</code>：指定獲取內容的起始索引，預設是從 <code>0</code></li><li><code>length</code>：指定要獲取內容的長度，預設 <code>remaining</code> 是指從起始索引後的剩餘內容</li></ul><p>方法：</p><pre><code class="typescript">getText(index: Number = 0, length: Number = remaining): String</code></pre><p>範例：</p><pre><code class="typescript">// 獲取從 0 開始，長度為 10 的文本內容const text = quill.getText(0, 10);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天開始仔細閱讀技術文件，會相對的比較乏味，但是能徹底的去看每個方法及參數要如何使用，知道自己有哪些武器可以用，對於特殊的需求也比較能找到合適的方法來實現。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>由於中秋節快到了，開始收到各種月餅禮盒，周遭也開始出現柚子，雖然還沒開始烤肉，但希望中秋之後別長太多肥肉出來，剛轉換跑道一陣子，還在適應節奏的階段，需要找到合適的運動時間，目前看來只剩下早上了，下班後加上通勤時間到健身房，運動完回家洗完澡也差不多到睡覺的時間了，最近嘗試調整起床的時間，先從六點半開始觀察看看囉…XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/1f147960445f8f26c42cc653221d10e7443cabdc">今日份的練習</a></li><li><a href="https://quilljs.com/docs/api/#content">API - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10328811">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 10：編輯內容的呈現 - Parchment 與 Blot</title>
      <link href="/2023/09/25/quill-day-10/"/>
      <url>/2023/09/25/quill-day-10/</url>
      
        <content type="html"><![CDATA[<p>今天我們將一同探討 Quill 背後的兩個關鍵概念：Blot 和 Parchment。雖然這些名詞可能聽起來有些陌生，但它們在 Quill 的運作中扮演了重要的角色。讓我們來了解一下，究竟 Blot 和 Parchment 是什麼，以及它們如何影響著 Quill 的編輯內容。</p><h3 id="什麼是-Parchment？"><a href="#什麼是-Parchment？" class="headerlink" title="什麼是 Parchment？"></a>什麼是 Parchment？</h3><p>Parchment 是 Quill 的文件模型，它是與 DOM (Document Object Model) 並行的樹狀結構，並提供了對內容編輯（例如 Quill）的功能。一個 Parchment 樹是由多個 Blot 組成的，這些 Blot 會反射對應的 DOM 節點。Blot 如同剛才提到的，它可以提供結構、格式與內容。換句話說，它們扮演著為文件元素提供實質性、樣式和功能的角色。除了 Blot 之外，Attributors 也可以提供輕量的格式化資訊，可定義如何將某些簡單的格式套用到文本或其他元素。</p><h3 id="什麼是-Blot？"><a href="#什麼是-Blot？" class="headerlink" title="什麼是 Blot？"></a>什麼是 Blot？</h3><p>Blot 是構成 Parchment 文件的基本區塊，有幾個基本的實現例如：<code>Block</code>, <code>Inline</code>, 以及 <code>Embed</code>。大部分的情況下，我們不會從頭開始實現 Blot，而是從其中一個基本實現來建立自訂功能。一個最基本的 Blot 必須使用一個靜態的 <code>blotName</code> 來命名，並且有一個相關聯的 <code>tagName</code> 或 <code>className</code>。如果 Blot 是透過標籤和 Class 定義的，Class 會是第一個優先，標籤則會作為備用。Blot 也需要有一個範圍，作為確認是行內 (inline) 還是區塊 (block)。</p><pre><code class="typescript">class Blot &#123;    static blotName: string;    static className: string;    static tagName: string | string[];    static scope: Scope;        domNode: Node;    prev: Blot | null;    next: Blot | null;    parent: Blot;        // 建立對應的 DOM 節點    static create(value?: any): Node;        constructor(domNode: Node, value?: any);        // 對於子集來說，是 Blot 的長度    // 對於父節點來說，是所有子節點的總和    length(): Number;        // 如果適用，則按照給定的 index 和 length 進行處理    // 經常會把響應轉移到合適的子節點上    deleteAt(index: number, length: number);    formatAt(index: number, length: number, format: string, value: any);    insertAt(index: number, text: string);    insertAt(index: number, embed: string, value: any);        // 回傳當下 Blot 與父節點之間的偏移量    offset(ancestor: Blot = this.parent): number;        // 在更新的生命週期結束後被呼叫    // 不能修改文件的值和長度，並且任何 DOM 的操作必須降低 DOM 樹的複雜度    // 共用的 context 物件會被傳到所有的 Blot    optimize(context: &#123;[key: string]: any&#125;): void;        // 當 blot 發生變化時呼叫，並帶著其變化的紀錄。    // blot 值得內部紀錄可以被更新，並允許修改 Blot 本身。    // 可以透過使用者操作或 API 呼叫觸發    // 共用 context 物件並傳給所有的 Blot    update(mutations: MutationRecord[], context: &#123;[key: string]: any&#125;);        /** Leaf Blots only **/        // 如果是 Blot 的類型，則回傳由 domNode 表示的值    // 本身沒有對 domNode 的類型校驗，需要應用程式在呼叫前進行外部校驗    static value(domNode): any;        // 給定一個 node 和 DOM 選擇範圍內的偏移量，回傳一個該位置的 index    index(node: Node, offset: number): number;        // 給定一個 Blot 的座標位置，回傳目前節點在 DOM 可以選範圍的偏移量    position(index: number, inclusive: boolean): [Node, number];        // 回傳目前 Blot 代表的值    // 除了來自 API 或透過 update 可檢測的使用者變更，否則不應該被改變    value(): any;    /** Parent blots only **/        // Blots 的白名單陣列，可以是直接的子節點    static allowedChildren: Blot[];        // 預設節點，當節點為空時會被插入    static defaultChild: string;        children: LinkedList&lt;Blot&gt;;        // 在建構時呼叫，應該填入其子節點的 LinkedList    build();        // 對後代有用的搜尋功能，不應修改    descendant(type: BlotClass, index: number, inclusive): Blot    descendents(type: BlotClass, index: number, length: number): Blot[];        /** Formattable blots only **/        // 如果是 Blot 的類型，則回傳 domNode 格式化後的值    // 不需要檢查 domNode 是否為 blot 類型    static formats(domNode: Node);        // 套用格式到 blot，不應該傳到子節點或其他的 Blot    format(format: name, value: any);        // 回傳代表 Blot 的格式，包括來自 Attributors    formats(): Object;    &#125;</code></pre><h3 id="自訂-Blot"><a href="#自訂-Blot" class="headerlink" title="自訂 Blot"></a>自訂 Blot</h3><p>我們可以透過自訂 Blot 的屬性和行為，來實現各種自訂的功能和外觀。這讓我們能夠按照專案的需求來建立符合特定用途的編輯器元素。例如我們可以建立一個紅色的 <code>span</code> 元素：</p><pre><code class="typescript">import Quill from &#39;quill&#39;;// 自訂一個紅色的 span 元素export class RedTextBlot extends Quill.import(&#39;blots/inline&#39;) &#123;  static blotName = &#39;red-text&#39;;  static tagName = &#39;span&#39;;    static create(value: string) &#123;    const node: HTMLElement = super.create() as HTMLElement;    if (value) &#123;    node.style.color = &#39;red&#39;;    &#125;    return node;  &#125;&#125;// 初始化 Quillconst quillEditor = new Quill(&#39;#editor&#39;, &#123;  theme: &#39;snow&#39;,  modules: &#123;    toolbar: true,  &#125;,&#125;);// 插入自訂的紅色文字quillEditor.insertText(0, &#39;這是自訂的&#39;, &#39;red-text&#39;, true);</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>剛開始研究的時候一頭霧水，需要多看幾次搭配練習才逐漸有感覺。Blot、Parchment 和 Delta 在 Quill Editor 中是密切相關的三個核心概念，它們共同形成了 Quill Editor 的基礎架構和功能。</p><ol><li><p><strong>Delta：</strong> Delta 是 Quill 使用的資料結構，專門用來描述編輯器內容或其變更。Delta 包含一個稱為 <code>ops</code> 的物件陣列，其中每個物件都是一個操作，這些操作可以是插入文字、刪除內容或套用格式等。</p></li><li><p><strong>Blot：</strong> Blot 是 Quill 文件模型 Parchment 中的基本建構單位，代表編輯器中的各種元素，例如文字、圖片和樣式。每個 Blot 都具有特定的屬性和行為，能夠包含或被其他 Blots 包含，形成一個層次化的樹狀結構。</p></li><li><p><strong>Parchment：</strong> Parchment 是 Quill 的文件模型，它存在於 DOM 樹結構的平行層面。Parchment 提供了一系列對內容編輯有用的功能和接口。一個 Parchment 主要由多個 Blot 組成，這些 Blot 對應到 DOM 樹中的特定節點。</p></li></ol><p>今天初步了解了 Quill 其中的核心概念：Blot 和 Parchment。透過理解這些概念，讓我們能對於 Quill 的功能與機制有所掌握，並在在實際專案開發中較能得心應手。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>昨天參加了教師節聚餐，意外發現有兩個學妹在同公司，但我現在要叫學姊 XD 難得有這樣的機會可以跟學弟妹們交流。吃完飯之後還到了咖啡廳邊喝咖啡邊聊天，聊了很多，無論是技術或是職涯規劃，都有很棒的收穫。老師還加碼續攤請我們吃晚餐，體驗到某家美墨餐廳美味餐點的強大。我覺得每年盡可能的來參加這樣的活動，除了敘舊之外，更多的是互相同步一下近況，也能看到很多厲害的學弟妹們卓越的成就。期待下一次的聚餐！</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference:"></a>Reference:</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/875db66a72dcdb6e5ef27a98609ef9854f982dea">今日份的練習</a></li><li><a href="https://github.com/quilljs/parchment">quilljs&#x2F;parchment (github.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10327573">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 9：Quill Editor 的資料物件 - Delta (下)</title>
      <link href="/2023/09/24/quill-day-9/"/>
      <url>/2023/09/24/quill-day-9/</url>
      
        <content type="html"><![CDATA[<p>昨天探討了 Delta，初步有了一些概念，今天就來嘗試練習看看，為了方便查看，先新增一個 <code>quill-editor.service</code>，並將 Delta 相關的練習內容都放到這裡面。</p><h2 id="使用-new-Delta-操作"><a href="#使用-new-Delta-操作" class="headerlink" title="使用 new Delta() 操作"></a>使用 new Delta() 操作</h2><p>在上一篇文章中，官方不建議手動建立 Delta 物件，應該要透過可連結 Deltas 物件的方法像是：<code>insert()</code>、<code>delete()</code>，和 <code>keep()</code> 等方法來建立新的 Delta。</p><p>因此使用的操作方式會是每次都直接 new 一個 <code>Delta</code>，並把要進行的文本操作透過鏈式呼叫(Method Chaining) 的方式處理，最後再呼叫 <code>quill.updateContents</code> 方法並帶入新增的 <code>helloWorldDelta</code>：</p><pre><code class="typescript">const helloWorldDelta = new Delta().insert(&#39;Hello World!&#39;);quill.updateContents(helloWorldDelta as any); // types 問題，暫時 as any</code></pre><p>從上面看到我在 <code>helloWorldDelta</code> 後面加了 as any，如果沒加的話會導致型別的錯誤，因為 <code>@types/quill</code> 並不是官方的類型定義庫，因此在後來的版本有修改了 <code>Op</code> 這個 interface，導致在編譯的時候會發生型別錯誤，目前暫解就是 <code>as any</code>，我也提個一個 PR，主要是變更 <code>quill-delta</code> 的版本號，還不確定能不能過 XD 先等看看 reviewer 有沒有什麼回應了。</p><h3 id="鏈式呼叫-Method-Chaining"><a href="#鏈式呼叫-Method-Chaining" class="headerlink" title="鏈式呼叫 (Method Chaining)"></a>鏈式呼叫 (Method Chaining)</h3><p>如果直接執行上方的範例，應該會看到編輯器出現了 Hello World!，但當你先輸入一些內容之後再執行這個方法，就會看到 Hello World! 並不是從游標後面接著進去的，原因是 delta 加入內容的操作都是從頭開始塞進去的，所以這裡我們需要使用鏈式呼叫的方式，在插入新內容之前計算一下目前的游標位置，並在這個位置後面加上內容：</p><pre><code class="typescript">// 使用 `getSelection()` 取得選取狀態const currentIndex = quill.getSelection()?.index;if (typeof currentIndex === &#39;number&#39;) &#123;// 將內容插入    const insertContent = &#39;Hello World!&#39;;    const helloWorldDelta = new Delta()        .retain(currentIndex)        .insert(insertContent);      quill.updateContents(helloWorldDelta);&#125;</code></pre><p>這時我們就能跟著游標位置插入內容，但又注意到另一個問題，插入內容之後游標卻還是在原地，印象中好的操作體驗應該是插入內容後，游標也應該跟著移動到新增的內容後面才對。這時我們還需要呼叫一個方法來更新游標的位置。</p><h3 id="更新游標位置"><a href="#更新游標位置" class="headerlink" title="更新游標位置"></a>更新游標位置</h3><p>使用 <code>setSelection</code> 更新編輯器游標位置，新的 <code>index</code> 可以用 <code>currentIndex</code> + <code>insertContent.length</code> 來獲得：</p><pre><code class="typescript">// 使用 `getSelection()` 取得選取狀態const currentIndex = quill.getSelection()?.index;if (typeof currentIndex === &#39;number&#39;) &#123;// 將內容插入    const insertContent = &#39;Hello World!&#39;;    const helloWorldDelta = new Delta()        .retain(currentIndex) // 保留到游標前的內容        .insert(insertContent); // 插入內容    quill.updateContents(helloWorldDelta); // 帶入 Delta 更新內容    quill.setSelection(currentIndex + insertContent.length, 0); // 更新游標位置&#125;</code></pre><h3 id="Line-Formatting"><a href="#Line-Formatting" class="headerlink" title="Line Formatting"></a>Line Formatting</h3><p>除了內容的輸入，有時候需要加入整行的內容並加上文字格式，例如我們可以插入一個 H1 級別的 Header 內容，為了能夠套用到整行，必須再加上一個換行的 <code>Delta</code> 並加上 Header 的 attribute：</p><pre><code class="typescript">const currentLength = quill.getLength();const currentIndex = quill.getSelection()?.index;if (typeof currentIndex === &#39;number&#39;) &#123;    const headerContent = &#39;This is Header&#39;;    const headerDelta = new Delta()        .retain(currentLength)        .insert(headerContent)        .insert(&#39;\n&#39;, &#123; header: 1 &#125;);    quill.updateContents(headerDelta);    quill.setSelection(currentIndex + headerContent.length + 1, 0);&#125;</code></pre><p>上面這個範例可以看到除了 <code>insert(headerContent)</code> 將 header 的內容加上之外，後面還 <code>insert(&#39;\n&#39;, &#123; header:1 &#125;)</code> 表示 header 的樣式是加在換行符號上的。即使最後一行沒有套用格式，所有 Quill 文件都必須以換行符號結尾，這樣我們就始終能有一個字元位置來套用行格式。</p><h2 id="從內容變化時看-Delta-內容"><a href="#從內容變化時看-Delta-內容" class="headerlink" title="從內容變化時看 Delta 內容"></a>從內容變化時看 Delta 內容</h2><p>我們可以註冊 Quill 的 <code>text-change</code> 事件，這個事件會提供 Delta 作為文本內容發生變化時的描述。先在 <code>quill-editor.service.ts</code> 新增一個 <code>updateQuillChanges</code> 方法來處理 Quill 事件註冊：</p><pre><code class="typescript">@Injectable(&#123;    providedIn: &#39;root&#39;,&#125;)export class QuillEditorService &#123;    quillUpdateSubject$ = new Subject&lt;Delta&gt;();    // ...        updateQuillChanges(quill: Quill) &#123;        quill.on(&#39;text-change&#39;, (delta) =&gt; this.quillUpdateSubject$.next(delta));    &#125;&#125;</code></pre><p>在 <code>updateQuillChanges</code> 底下註冊 <code>text-change</code> 事件，並把獲得帶有內容變更的 delta 使用 <code>subejct</code> 方式打出去。這個方法可以在 Quill 初始化後，接著加入事件監聽並訂閱。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>Delta 的操作其實還滿單純的，我們可以透過監聽事件觀察 Delta 如何描述內容變更，同時我們也可以使用 <code>quill.getContent()</code> 取得完整描述文本的 Delta 狀態，透過這樣的觀察可以回推當有特定需求的時候，我們可以如何實現較正確的方式來變更編輯器的內容。搭配 Angular 實現 Quill 相關的機制在專案管理及維護上都能有所幫助。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天室友發了一個很酷的 30 天鐵人賽，是關於桃園青埔的建案描述，雖然跟 IT 沒有太大的關聯，但也是滿有趣的挑…戰? XD 這讓我想到有一個說法是要培養一個習慣需要花 30 天來練習。希望寫文章的習慣可以在這次挑戰之後，對於寫文章就比較不會太卡，往往都是面對一頁空白的時候不知道從何下筆，但都用電腦設備打文章了，先寫一點東西就對了 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://quilljs.com/docs/delta/">Delta - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10326421">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 8：Quill Editor 的資料物件 - Delta (上)</title>
      <link href="/2023/09/23/quill-day-8/"/>
      <url>/2023/09/23/quill-day-8/</url>
      
        <content type="html"><![CDATA[<p>今天初步探討 Quill Editor 資料物件之一，Delta，就一起來了解一下吧。</p><h3 id="什麼是-Delta-物件？"><a href="#什麼是-Delta-物件？" class="headerlink" title="什麼是 Delta 物件？"></a>什麼是 Delta 物件？</h3><p>不要被 Delta 這酷酷的名字給嚇到，它其實是很單純的東西。</p><p>首先我們將官網文件的描述翻譯來看：</p><blockquote><p>Delta 是一種簡單但富有表現力的格式，可用於<strong>描述 Quill 的內容和變化</strong>。這個格式是 JSON 的嚴格子集，可讀性高，並且機器也能容易解析。Delta 可以描述任何 Quill 文件，包含所有文字和格式資訊，並去除 HTML 的歧義與複雜性。</p></blockquote><p>Delta 是 Quill Editor 使用的資料物件，它同時也作為<a href="https://github.com/quilljs/delta/">獨立的儲存庫</a>，使 Delta 可以在 Quill 外的情境中被使用。主要用途在處理<a href="https://en.wikipedia.org/wiki/Operational_transformation">操作轉換（Operational Transform）</a>，並且可以套用到即時協同編輯的應用，像 Google Docs，之後我們再來深入了解 Delta 的格式設計概念。</p><p>因此，Delta 主要用來儲存編輯器的內容，它由一系列的操作物件組成，每個操作物件代表一個對內容的變更，例如插入文字、刪除內容、新增樣式等。Delta 的結構主要是以操作物件（OPS Object）的陣列方式呈現。</p><p>另外需要注意的一點是：不建議手動建立 Delta 物件，應該要透過可連結 Deltas 物件的方法像是：<code>insert()</code>、<code>delete()</code>，和 <code>keep()</code> 等方法來建立新的 Delta。</p><h2 id="當-Delta-為文件內容的描述"><a href="#當-Delta-為文件內容的描述" class="headerlink" title="當 Delta 為文件內容的描述"></a>當 Delta 為文件內容的描述</h2><p>每個 Delta 物件都包含一個 <code>ops</code> 屬性，這個屬性是一個操作陣列。每個操作都是一個物件，包含 <code>insert</code>、<code>delete</code>、<code>retain</code> 等屬性，分別代表插入文字、刪除文字、保留文字等操作。</p><p>以下是一個 Delta 物件的範例：</p><pre><code class="typescript">&#123;  ops: [    &#123; insert: &#39;Hello, &#39; &#125;,    &#123; insert: &#39;world&#39;, attributes: &#123; bold: true &#125; &#125;,    &#123; insert: &#39;!&#39; &#125;,  ]&#125;</code></pre><p>在這個範例中，Delta 物件表示一個包含「Hello, 」和「world」（加粗樣式）兩個片段的內容， 是不是非常容易閱讀及理解呢？上面有提到，Delta 是用來<strong>描述文件內容及變更的內容</strong>，而當 Deltas 用於描述內容時，當套用到空白的文件時，可以將其視為要建立的內容。</p><h3 id="Delta-ops-的屬性："><a href="#Delta-ops-的屬性：" class="headerlink" title="Delta ops 的屬性："></a>Delta ops 的屬性：</h3><ul><li><code>insert</code>：插入文字，可以指定要插入的文字內容。</li><li><code>delete</code>：刪除文字，可以指定要刪除的文字數量。</li><li><code>retain</code>：保留文字，可以指定要保留的文字數量。</li><li><code>attributes</code>：操作的屬性，例如文字樣式、顏色等。</li></ul><h3 id="操作的順序和組合："><a href="#操作的順序和組合：" class="headerlink" title="操作的順序和組合："></a>操作的順序和組合：</h3><p>Delta 的操作按照順序應用於文本，從左到右。它們可以組合在一起，以建立完整的編輯器內容。例如 Delta 物件表示在游標的位置插入「Hello, world!」這段文字：</p><pre><code class="typescript">&#123;  ops: [    &#123; insert: &#39;Hello, world!&#39; &#125;,  ]&#125;</code></pre><h3 id="操作的應用："><a href="#操作的應用：" class="headerlink" title="操作的應用："></a>操作的應用：</h3><p>我們可以使用 Quill Editor 提供的 <code>setContents</code> 方法，將 Delta 物件設置到編輯器中。這樣就能夠在編輯器中動態修改內容。</p><pre><code class="typescript">  setEditorContent() &#123;    const delta = &#123;      ops: [&#123; insert: &#39;Hello, world!&#39; &#125;],    &#125;;        this.quillEditor.setContents(delta as any);  &#125;</code></pre><h2 id="Embeds-嵌入式內容："><a href="#Embeds-嵌入式內容：" class="headerlink" title="Embeds 嵌入式內容："></a>Embeds 嵌入式內容：</h2><p>除了文字內容與樣式的資料，Delta 也可以描述嵌入式 (Embed) 的內容，例如：圖片、超連結或數學公式。這類型的內容在 Delta 物件中必須要有一個描述該類型的 key，而這個 key 同時也是 <code>bolt</code> 的名稱，如果有用 <code>parchment</code> 來建立自訂內容，嵌入式內容也可以像文字一樣擁有 <code>attributes</code> 的 key ，讓嵌入的內容也能有格式的設定。另外所有嵌入式內容的在編輯器中的內容長度 <code>length</code> 均為 <strong>1</strong>。</p><pre><code class="typescript">&#123;  ops: [&#123;     // 圖片連結     insert: &#123;       image: &#39;https://quilljs.com/assets/images/icon.png&#39;     &#125;,     attributes: &#123;       link: &#39;https://quilljs.com&#39;     &#125;   &#125;] &#125;</code></pre><p>關於 <code>BoltName</code> 與 <code>Parchment</code> 的介紹，我們之後再來仔細探討。(<del>又挖坑…</del>) XD</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天初步了解 Quill Editor 使用的 Delta 物件，在編輯器的處理情境中，我們有時候會需要利用 Delta 處理編輯器的內容，透過 Delta 可以解析文本內容，並依照專案需求進一步的處理資料，最後利用內建的方法將處理後的內容更新回編輯器，因此要能對 Quill 得心應手，對於 Delta 物件的理解也是很重要的一環。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>本來還煩惱著要怎麼安排週末的行程，因為週日要到台中參加教師節聚餐，同時還要記著上來日更文章，但週六是要補班的，然後昨天才知道原來今天不需要補班，還好是昨天就知道，如果今天匆匆到公司之後才發現，大概會很錯愕吧，雖然接著回老家非常方便，站點就在展覽館旁邊而已 XD </p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://quilljs.com/docs/delta/">Delta - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10325791">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 7：Quill Editor 擴充自訂功能</title>
      <link href="/2023/09/22/quill-day-7/"/>
      <url>/2023/09/22/quill-day-7/</url>
      
        <content type="html"><![CDATA[<p>Quill 作為編輯器的核心優勢在於它提供了豐富的 API 與容易實現客製化的功能。當我們基於 Quill 的 API 實作功能時，可以包成一個 module 較方便使用。今天一起探討如何擴充 Quill 編輯器的功能，讓我們可以依照特定的需求實現並加入，使編輯器的功能更豐富以貼近專案的特殊需求。</p><h2 id="註冊-Quill-自訂模組"><a href="#註冊-Quill-自訂模組" class="headerlink" title="註冊 Quill 自訂模組"></a>註冊 Quill 自訂模組</h2><p>假設我們需要新增一個能顯示編輯器當前字數的計數器，首先需要建立一個名為 <code>counter</code> 的 module： </p><pre><code class="typescript">// 建立自訂 ModulecreateCustomModule() &#123;    Quill.register(      &#39;modules/counter&#39;, // 自訂 module 名稱      function (quill: Quill, options: QuillOptions) &#123;        const container: HTMLDivElement = document.querySelector(&#39;#counter&#39;)!;        // 透過 text-change 事件監聽處理        quill.on(&#39;text-change&#39;, function () &#123;          // 獲取 quill 文本內容          const text = quill.getText();          // 根據 module options 來決定計算單位          if (options.unit === &#39;word&#39;) &#123;            container.innerText = text.split(/\s+/).length + &#39; words&#39;;          &#125; else &#123;            container.innerText = text.length + &#39; characters&#39;;          &#125;        &#125;);      &#125;    );&#125;// 初始化的操作const quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123;    counter: &#123;      container: &#39;#counter&#39;, // 設定 counter HTML id      unit: &#39;word&#39; // 設定文本計算單位    &#125;  &#125;&#125;);</code></pre><p>上面的範例中，我們宣告了一個 <code>createCustomModule</code> function，並透過 <code>Quill.register</code> 註冊一個名為 <code>counter</code> 的 module，第一個參數是 module name, 第二個參數則是帶入一個 function，這個 function 可以取得 <code>Quill</code> 及 <code>options</code> 參數。</p><p>function 的實現是利用監聽 Quill 的 <code>text-change</code> 事件，當文本內容改變的時候觸發，並執行對應的操作。這裡根據 <code>unit</code> 參數來決定計算單位。Quill 初始化的時候，我們可以在 <code>modules</code> 底下設定 <code>counter</code> 也就是 custom module 名稱，並帶入像是 <code>container</code>, <code>unit</code> 的參數設定計數器的 HTML 以及計算單位。</p><h2 id="Keyboard-module-監聽事件"><a href="#Keyboard-module-監聽事件" class="headerlink" title="Keyboard module 監聽事件"></a>Keyboard module 監聽事件</h2><p>我們可以透過監聽事件來執行額外的操作，並根據事件觸發類型相應的功能。Quill 提供了幾種不同的監聽事件，除了像上面的範例用到了 <code>text-change</code> 之外，在 <code>keyboard</code> module 也提供了按鍵事件綁定，讓我們可以設定，當某個按鍵觸發的時候，執行自訂的功能。</p><p>處理 Quill Editor 的按鍵事件，可以透過 <code>keyboard</code> module 設定監聽按鍵的事件，例如按下某個按鍵或是組合鍵就進行對應的處理：</p><pre><code class="typescript">const quillConfig = &#123;  modules: &#123;    // 其他模組...    keyboard: &#123;      bindings: &#123;        enter: &#123;          key: &#39;Enter&#39;,          handler: function(range, context) &#123;            // 在這裡處理按下 Enter 鍵後的邏輯            console.log(&#39;Enter 鍵被按下&#39;);          &#125;        &#125;      &#125;    &#125;  &#125;,  theme: &#39;snow&#39;,&#125;;   </code></pre><p>上面的範例是當 <code>Enter</code> 鍵按下的時候，就執行 <code>handler</code> 帶入的 function，這裡我們簡單用個 <code>console.log</code> 實驗一下就好，至於參數 <code>range</code> 及 <code>context</code> 是什麼，我們之後再來細看。</p><h2 id="實用的擴充套件"><a href="#實用的擴充套件" class="headerlink" title="實用的擴充套件"></a>實用的擴充套件</h2><p>當需要更特殊或複雜的功能時，我們可以透過自訂的擴充套件來實現。只要依照 Quill 的擴充自訂功能的方式，就能夠為編輯器新增各種功能。官方文件也整理了<a href="https://github.com/quilljs/awesome-quill">一份清單</a>，收錄了好用的擴充套件供大家參考並能安裝使用。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天我們初步體驗了如何自訂並註冊自訂的 module，並且利用 Quill 提供的監聽事件來處理額外的事情，也嘗試加入按鍵綁定事件，並在指定的按鍵觸發的時候呼叫自訂的方法。只是簡單的利用 Quill 提供的 API 就能讓我們實現額外的功能，由此可知 Quill 的可擴充性是非常高的。在 Github 上我們也能看到多樣的自訂功能模組可以直接安裝使用。但當遇到非常特殊的需求時，我們也可以按照需求來實現。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天參加了 Study4 的活動小聚，然後不知道怎麼聊的，聊到同事A需要在上班時間偶爾回訊息給老婆，同事B就問說上班時間為什麼要回訊息，同事A說，因為有時候要安撫一下老婆，回應老婆大人的抱怨什麼之類的，於是我就比喻，上班時間偶爾還是會被 ping 一下，我們還是要回個 <code>200</code>，這時另一個社群朋友就問，那如果 <code>404</code> 或 <code>500</code> 怎麼辦？我想，回去就完蛋吧 ˊ_&gt;ˋ 室友說：也許可以用 <code>301</code>，我：？？？</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://quilljs.com/guides/building-a-custom-module/">Building a Custom Module - Quill Rich Text Editor (quilljs.com)</a></li><li><a href="https://github.com/jeffwu85182/quill-editor-todo/commit/1184ea0cf270d4172b8be18b3a346e612b1e8502">今日份的練習</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10325338">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 6：Quill Editor 自訂工具列</title>
      <link href="/2023/09/21/quill-day-6/"/>
      <url>/2023/09/21/quill-day-6/</url>
      
        <content type="html"><![CDATA[<p>昨天我們知道如何設定編輯器的 CSS 樣式，並且修改既有的功能按鈕。今天接著研究要如何自訂工具列的內容以及加入自訂功能的按鈕。</p><h2 id="自訂工具列：Toolbar-Options"><a href="#自訂工具列：Toolbar-Options" class="headerlink" title="自訂工具列：Toolbar Options"></a>自訂工具列：Toolbar Options</h2><p>Quill Editor 的工具列有兩種設置方式，一種是定義 <code>toolbarOption</code> 物件，由於 Quill 內建相當豐富實用的功能，因此我們可以直接以陣列的方式設定想要加入的控制按鈕，陣列底下的每個元素也是陣列，用來表示一個群組，除了可以調整工具列的功能按鈕順序之外，我們也能以分組的方式將同類型的功能擺在一起。</p><pre><code class="typescript">const toolbarOptions = &#123;    container: [        [&#39;bold&#39;, &#39;italic&#39;, &#39;underline&#39;, &#39;strike&#39;], // 預設的工具按鈕        [&#123; header: 1 &#125;, &#123; header: 2 &#125;], // 預設的工具按鈕        [&#123; list: &#39;ordered&#39; &#125;, &#123; list: &#39;bullet&#39; &#125;], // 預設的工具按鈕        [&#123; script: &#39;sub&#39; &#125;, &#123; script: &#39;super&#39; &#125;], // 預設的工具按鈕        [&#123; indent: &#39;-1&#39; &#125;, &#123; indent: &#39;+1&#39; &#125;], // 預設的工具按鈕        [&#123; direction: &#39;rtl&#39; &#125;], // 預設的工具按鈕        [&#123; size: [&#39;small&#39;, false, &#39;large&#39;, &#39;huge&#39;] &#125;], // false 是 normal        [&#123; header: [1, 2, 3, 4, 5, 6, false] &#125;], // 預設的工具按鈕        [&#123; color: [] &#125;, &#123; background: [] &#125;], // 預設的工具按鈕        [&#123; font: [] &#125;], // 預設的工具按鈕        [&#39;image&#39;, &#39;customButton&#39;], // 自定義與內建工具按鈕        [&#39;clean&#39;], // 預設的工具按鈕    ],&#125;</code></pre><p>另外需要留意的部分像是 <code>size</code> 以及 <code>header</code>，分別是文字的大小以及標題層級，兩者都與字體大小有關，陣列中有設定值是 <code>false</code> ，在畫面渲染之後，可以看到下拉清單會表示 <code>Normal</code>，意思是移除該樣式，僅顯示原本的大小。</p><p><img src="/2023/09/21/quill-day-6/200907493oFpjVVyUC.png" alt="toolbar options"></p><p>例如原本選擇了一段文字並設定 <code>header</code> 為 <code>1</code>，意思就是把選取的範圍文字套上 <code>&lt;h1&gt;</code> 標籤，這時的字體是呈現大標題的樣式，接著我們再把一樣的選取範圍切換到 <code>Normal</code>，原本的 <code>H1</code> 標題樣式就會被移除，回到原始的文字狀態。</p><h2 id="加入自定義按鈕"><a href="#加入自定義按鈕" class="headerlink" title="加入自定義按鈕"></a>加入自定義按鈕</h2><p>接著我們嘗試新增一個 <code>customButton</code> 的自訂按鈕，並透過 <code>toolbar</code> 物件下的 <code>handlers</code> 屬性註冊按鈕的自訂函式，這個函式主要處理按下按鈕後的操作。我們可以在 <code>handlers</code> 中實作我們需要的功能，例如插入特定的內容、修改編輯器文本內容…等等。另外 <code>toolbar</code> 也提供了群組按鈕的設定，例如要將相同類型的按鈕放一起，直接放在同一個陣列即可。</p><h2 id="使用自訂按鈕功能"><a href="#使用自訂按鈕功能" class="headerlink" title="使用自訂按鈕功能"></a>使用自訂按鈕功能</h2><p>在 <code>quillConfig</code> 的 <code>toolbar</code> 中加入自訂功能按鈕的名稱及對應的 <code>handler</code>，並且設定按鈕的 icon：</p><pre><code class="typescript">const quillConfig = &#123;  modules: &#123;    toolbar: &#123;      container: [        // ...其他按鈕        [&#39;image&#39;, &#39;customButton&#39;], // 自定義的工具按鈕群組      ],      handlers: &#123;        &quot;customButton&quot;: () =&gt; console.log(&#39;handle custom button&#39;)      &#125;    &#125;,    theme: &#39;snow&#39;,  &#125;&#125;;// 使用 font awesome 自訂按鈕 iconconst icons = Quill.import(&#39;ui/icons&#39;);icons[&#39;customButton&#39;] = &#39;&lt;i class=&quot;fa-regular fa-star&quot;&gt;&lt;/i&gt;&#39;;</code></pre><h2 id="自訂工具列：HTML"><a href="#自訂工具列：HTML" class="headerlink" title="自訂工具列：HTML"></a>自訂工具列：HTML</h2><p>我們也可以自訂工具列的 HTML，在初始化的時候，Quill 會根據 <code>toolbar</code> 屬性給的工具列容器選擇器進行內建功能的事件綁定，我們也可以自訂額外的按鈕或元件在上面。例如：</p><pre><code class="html">&lt;div #toolbar&gt;  &lt;span class=&quot;ql-formats&quot;&gt;    &lt;button class=&quot;ql-bold&quot;&gt;Bold&lt;/button&gt;    &lt;button class=&quot;ql-italic&quot;&gt;Italic&lt;/button&gt;    &lt;button class=&quot;ql-link&quot;&gt;Link&lt;/button&gt;    &lt;button class=&quot;ql-list&quot; value=&quot;bullet&quot;&gt;Ul&lt;/button&gt;  &lt;/span&gt;  &lt;!-- customButton --&gt;  &lt;span class=&quot;ql-formats&quot;&gt;    &lt;button class=&quot;ql-customButton&quot; [title]=&quot;&#39;Custom Button&#39;&quot;&gt;      Custom Button    &lt;/button&gt;  &lt;/span&gt;&lt;/div&gt;</code></pre><p>在 Component 初始化的時候帶入指定的容器，這邊我們一樣透過 <code>@ViewChild</code> 來獲取 HTML，同時也將對應的 <code>handlers</code> 加上來模擬觸發按鈕的時候進行的操作：</p><pre><code class="typescript">@ViewChild(&#39;editor&#39;) editor!: ElementRef;@ViewChild(&#39;toolbar&#39;) toolbar!: ElementRef;// ...const quill = new Quill(this.editor.nativeElement, &#123;   modules: &#123;     // toolbar: toolbarOptions,    toolbar: &#123;      container: this.toolbar.nativeElement,      handlers: &#123;        customButton: () =&gt; console.log(&#39;handle custom button&#39;),      &#125;,    &#125;,  &#125; &#125;);</code></pre><p>重新整理之後可以看到工具列變成自訂的 HTML 內容：<br><img src="/2023/09/21/quill-day-6/20090749mykJprNm2j.png" alt="自訂的 HTML 內容"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天我們了解到工具列的設定，Quill 提供了這兩種設定方式，在大部分的情況下，我們可以選擇定義 <code>toolbarOption</code> 物件的方式，將想要使用的內建功能分門別類組成不同的群組後編排順序，當遇到較特殊的情況，只設定顯示以及順序無法滿足需求的時候，我們可以直接以 HTML 的方式完全自訂一個工具列，並按照需求加入額外的介面或其他功能。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>昨天下班的時候路過南港展覽館，發現今天突然好多人，而且感覺就不是剛下班的樣子，也看到許多代客寄物的小攤，看到告示牌才知道，原來今天展覽館有舉辦演唱會，外頭都是排隊的人潮。可以看到很多元的打扮風格，不過人真的是多到差點進不去捷運站。到了隔天上班的時候發現展覽館外圍地上一堆垃圾，有沒喝完的飲料，更多的是抽完菸的菸蒂，對於厭惡抽菸的我來說，很久沒看到這麼精彩的景象了，還是希望民眾參加演唱會之後，也別忘了把垃圾帶走，抽完菸的菸蒂熄滅之後也順手丟到垃圾桶吧。真心覺得素質還有待提升QQ</p><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10324342">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 5：自訂 Quill Editor 外觀樣式</title>
      <link href="/2023/09/20/quill-day-5/"/>
      <url>/2023/09/20/quill-day-5/</url>
      
        <content type="html"><![CDATA[<p>今天我們將著重於自訂 Quill Editor 的外觀與樣式，讓編輯器更符合專案的設計風格需求。Quill Editor 提供了幾種方法來調整外觀樣式，讓我們一探究竟！</p><h2 id="修改工具列樣式"><a href="#修改工具列樣式" class="headerlink" title="修改工具列樣式"></a>修改工具列樣式</h2><p>在初始化的時候我們透過 <code>new Quill()</code> 並帶入編輯器容器的 HTML 元素以及編輯器配置的物件共兩個參數進行初始化。初始化後可以看到編輯器上方有一排工具列，工具列提供了編輯器預設的功能按鈕，我們可以用 CSS 對工具列及按鈕調整 UI 樣式，例如在 <code>styles.scss</code> 或對應的專案目錄下的 CSS 檔案加入新的 Style：</p><pre><code class="scss">.ql-toolbar &#123;  background-color: aqua; /* 修改編輯器工具列的背景顏色 */&#125;.ql-editor &#123;   background-color: #f0f0f0; /* 使用你想要的背景顏色 */   border: 1px solid #ccc; /* 使用你想要的邊框樣式 */ &#125;</code></pre><p>但這時候如果直接儲存重整頁面你會發現工具列的樣式完全沒有變化，這是為什麼呢？我們利用 <code>ngAfterViewInit</code> 觀察 <code>QuillEditorComponent</code> 在 Quill 初始化渲染後的 <code>nativeElement</code>：</p><pre><code class="typescript">@Component(&#123;  selector: &#39;app-quill-editor&#39;,  standalone: true,  imports: [CommonModule],  templateUrl: &#39;./quill-editor.component.html&#39;,  styleUrls: [&#39;./quill-editor.component.scss&#39;],&#125;)export class QuillEditorComponent implements AfterViewInit &#123;  @ViewChild(&#39;editor&#39;) editorElementRef!: ElementRef;     ngAfterViewInit() &#123;    this.initQuillEditor();        // 監聽編輯器內容變化事件，並將變化同步到 Angular 的資料模型    this.quillEditor.on(&#39;text-change&#39;, () =&gt; &#123;      this.content = this.quillEditor.root.innerHTML;    &#125;);    console.log(this.editorElementRef.nativeElement);  &#125;</code></pre><p>可以看到 <code>console.log</code> 出來的 <code>nativeElement</code> 並沒有包含 <code>ql-toolbar</code>，而是在 <code>#editor-container</code> 的上面：<br><img src="/2023/09/20/quill-day-5/20090749LZoCDHBBgj.png" alt="console.log(&#39;nativeElement&#39;)"></p><p>這時候我們就需要新增一個 Component 的屬性 <code>encapsulation</code> 並且值設為 <code>ViewEncapsulation.None</code> ，透過這個設定可以取消 Angular 的樣式封裝機制，將元件樣式直接套用到全局樣式中，不過要小心可能會導致樣式污染和衝突。另一種方式是直接自訂 Toolbar 的 HTML 內容，這個我們明天接著研究。</p><p>加上之後就可以看到編輯器的工具列顏色有了變化：<br><img src="/2023/09/20/quill-day-5/200907493mmVEK5DQj.png" alt="顏色有了變化"></p><h2 id="自訂工具列圖示"><a href="#自訂工具列圖示" class="headerlink" title="自訂工具列圖示"></a>自訂工具列圖示</h2><p>如果想要自訂工具列按鈕的圖示，可以使用 <code>Quill.import(&#39;ui/icons&#39;)</code> 並選擇要更換 icon 的功能按鈕指定自訂的 icon 元素，例如把粗體的 icon 換成 Font-Awesome 的 icon：</p><ol><li>先安裝 Font Awesome node module</li></ol><pre><code class="bash">npm install @fortawesome/fontawesome-free --save</code></pre><ol start="2"><li>將 <code>fontawesome-free</code> CSS &amp; JS 加入 angular.json：</li></ol><pre><code class="json">&#123;  // ...  &quot;architect&quot;: &#123;    &quot;build&quot;: &#123;      &quot;options&quot;: &#123;        &quot;styles&quot;: [          &quot;node_modules/@fortawesome/fontawesome-free/css/all.min.css&quot;,          &quot;node_modules/quill/dist/quill.snow.css&quot;,          &quot;src/styles.css&quot;        ],        &quot;scripts&quot;: [          &quot;node_modules/@fortawesome/fontawesome-free/js/all.min.js&quot;        ]        // ...      &#125;,      // ...    &#125;,    // ...  &#125;&#125;</code></pre><p>完成 FontAwesome 設置之後，我們可以直接在初始化 Quill Editor 之前先調整我們要的 icon：</p><pre><code class="typescript"> const icons = Quill.import(&#39;ui/icons&#39;); icons[&#39;bold&#39;] = &#39;&lt;i class=&quot;fa-solid fa-hippo&quot;&gt;&lt;/i&gt;&#39;; this.quillEditor = new Quill(this.editorElementRef.nativeElement, &#123;   // ... &#125;);</code></pre><p>重整頁面看看粗體的按鈕是不是變成河馬的樣式了 XD<br><img src="/2023/09/20/quill-day-5/200907499yUTtqmFJ4.png" alt="變成河馬的樣式了"></p><h2 id="自訂-Quill-Editor-佈景主題："><a href="#自訂-Quill-Editor-佈景主題：" class="headerlink" title="自訂 Quill Editor 佈景主題："></a>自訂 Quill Editor 佈景主題：</h2><p>如果想要更進一步自訂佈景主題，可以在 CSS 檔案中像上述的修改方式一樣來撰寫 CSS 樣式。Quill Editor 使用一些特定的 CSS class 來控制不同的元素，我們可以透過這些 class 來實現想要的效果。當然在全球最大交友平台 Github 上也有其他精美的佈景主題可以選擇，就看專案需求囉。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>透過自訂 Quill Editor 外觀和樣式，我們可以依專案需求進行調整。自訂外觀可以讓編輯器與專案整體的設計風格是一致的，從 UI&#x2F;UX 的角度提供更好的使用者體驗。下一篇文章，我們將介紹 Quill Editor 的擴充套件和自定義功能。</p><h4 id="雜記"><a href="#雜記" class="headerlink" title="雜記"></a>雜記</h4><p>今天寫文章之前，先去整復保養一下，不知不覺已經到了需要為身體繳保養費的人生階段，現在要熬夜都是一件要命的事情。想當初第一次去整復的時候，既緊張又怕受傷害。先是對肩頸做紅外線熱敷十五分鐘，之後就先從正面開始，然後是背部壓到都能聽到筋骨啪啪啪鬆開的聲音，最後壓軸則是用毛巾繞住脖子連同腰椎一起拉開，那一下直接腦袋空白了好幾秒，接著出去之後看到的光景似乎變明亮了，視覺的色彩飽和度也變的很清晰。真的是很神奇的體驗。後來只要每次做完，姿勢都會端正一陣子，深怕拉開的筋骨又太快被打回原形 XD</p><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10323588">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 4：Quill Editor 的基本操作與編輯功能</title>
      <link href="/2023/09/19/quill-day-4/"/>
      <url>/2023/09/19/quill-day-4/</url>
      
        <content type="html"><![CDATA[<p>在前一篇文章中，我們新增了 Angular 專案並安裝與配置了 Quill Editor，並建立了一個 “quill-editor” 元件。今天就讓我們繼續探索 Quill Editor 的基本功能，試著編輯操作和使用工具列選項體驗一下。</p><p><img src="/2023/09/19/quill-day-4/20090749uuZobTAYi2.png" alt="toolbar"></p><h2 id="編輯器工具列"><a href="#編輯器工具列" class="headerlink" title="編輯器工具列"></a>編輯器工具列</h2><p>Quill 預設提供了幾個實用的功能在工具列上，讓使用者可以輕鬆的進行文字編輯。包含了常用的文字格式化功能，例如粗體、斜體、底線，還有文字大小及顏色的調整。此外，還可以插入清單（有序清單、無序清單）的功能。透過這些功能，我們可以輕鬆編輯文本內容及文字格式。</p><h2 id="加入連結"><a href="#加入連結" class="headerlink" title="加入連結"></a>加入連結</h2><p>在 Quill 編輯器中加入超連結的方式和大部分常見的編輯器一樣，使用者只需要選擇想要加上連結的文字，然後點擊工具列中的連結按鈕並輸入連結的 URL，按下確認鈕，即可在你的內容中插入超連結。</p><h2 id="插入圖片"><a href="#插入圖片" class="headerlink" title="插入圖片"></a>插入圖片</h2><p>除了文字超連結的功能，Quill 也有插入圖片的功能。在理想的情況下，我們只需點擊工具列上的圖片按鈕，選擇要插入的圖片檔案，Quill Editor 就會自動將圖片嵌入到內容。</p><p>不過在第一次嘗試初始化 Quill Editor 的時候，可以看到上方的工具列示沒有插入圖片的按鈕可以點擊的，卻可以將螢幕截圖或是從網頁複製的圖片貼到編輯器中。</p><p>看了官方文件之後才知道，Quill 內建的功能在初始化的時候預設都是全開的。主要是 Toolbar 的預設值沒有把對應的功能按鈕打開，因此我們還要加上插入圖片的按鈕，這可以在初始化的設定裡修改 toolbar 的選項：</p><pre><code class="typescript">const toolbarOptions = [      [&#39;bold&#39;, &#39;italic&#39;, &#39;underline&#39;, &#39;strike&#39;], // toggled buttons      [&#39;blockquote&#39;, &#39;code-block&#39;],      [&#123; header: 1 &#125;, &#123; header: 2 &#125;], // custom button values      [&#123; list: &#39;ordered&#39; &#125;, &#123; list: &#39;bullet&#39; &#125;],      [&#123; script: &#39;sub&#39; &#125;, &#123; script: &#39;super&#39; &#125;], // superscript/subscript      [&#123; indent: &#39;-1&#39; &#125;, &#123; indent: &#39;+1&#39; &#125;], // outdent/indent      [&#123; direction: &#39;rtl&#39; &#125;], // text direction      [&#123; size: [&#39;small&#39;, false, &#39;large&#39;, &#39;huge&#39;] &#125;], // custom dropdown      [&#123; header: [1, 2, 3, 4, 5, 6, false] &#125;],      [&#39;link&#39;, &#39;image&#39;, &#39;video&#39;, &#39;formula&#39;], // add&#39;s image support      [&#123; color: [] &#125;, &#123; background: [] &#125;], // dropdown with defaults from theme      [&#123; font: [] &#125;],      [&#123; align: [] &#125;],      [&#39;clean&#39;], // remove formatting button    ];</code></pre><p>透過上面的設定，就可以看到有更多內建功能按鈕加到工具列了。至於還有哪些內建的功能可以加在 Toolbar 上，可以參考<a href="https://quilljs.com/docs/formats/">技術文件</a> 。之後我們還可以加入自訂 module 來擴充編輯器，使編輯器支援更豐富的文本編輯功能，例如拖曳的方式插入圖片、或插入圖片後可縮放等。</p><p>加入 <code>toolbarOptions</code> 之後的效果：<br><img src="/2023/09/19/quill-day-4/20090749dPKiTby69O.png" alt="toolbar options"></p><h2 id="編輯的內容就是實際呈現"><a href="#編輯的內容就是實際呈現" class="headerlink" title="編輯的內容就是實際呈現"></a>編輯的內容就是實際呈現</h2><p>由於 Quill 提供了「所見即所得」的編輯介面，我們可以在編輯過程中即時預覽最終的呈現效果，使文字格式和插入的圖片等內容能立即展示出來，比起有些較早期的編輯器，Quill 消除了需要頻繁切換頁面以檢查預覽效果的麻煩。讓我們在編輯時所看到的畫面就能確保最終輸出與預期一致。</p><h2 id="鍵盤快速鍵"><a href="#鍵盤快速鍵" class="headerlink" title="鍵盤快速鍵"></a>鍵盤快速鍵</h2><p>我們不僅可以用滑鼠點擊工具列的功能圖示格式化文本，Quill Editor 也提供了一些常見且方便的快速鍵，讓我們能直覺又快速的編輯文本。例如，我們使用 Ctrl+B 把文字設為粗體，使用 <code>Ctrl + I</code> 設為斜體，還有 <code>Ctrl + U</code> 是斜體等常見的快速鍵。除了格式化的快捷鍵之外，我們也能透過 <code>Ctrl + Z</code> 以及 <code>Ctrl + Shift + Z</code> 回上一步或進到下一步的操作紀錄。這些快捷鍵可以提高編輯的效率，讓使用者更能專注於輸入與編輯內容。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天我們探討了 Quill Editor 的基本使用和編輯功能，學會如何使用工具列進行文字格式化、插入連結和圖片，還有預覽內容的最終效果。我們也瞭解了如何使用鍵盤快捷鍵來提高編輯效率。下一篇文章將探討如何自訂 Quill Editor 的外觀與樣式，讓我們能夠根據專案需求進行編輯器的樣式設定。</p><h4 id="雜記："><a href="#雜記：" class="headerlink" title="雜記："></a>雜記：</h4><p>雖然已經知道在網頁上編輯內容沒有定時存檔或 <code>beforeunload</code> 是一件很抖的事情，當實際體會到在編輯一半時沒有存檔的情況下，誤觸鍵盤快速鍵或書籤連結導致頁面跳掉，真的會讓人滿臉糾結 Orz。以後還是乖乖的在本地的編輯器把稿子打好之後再貼上來吧…QQ</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><p><a href="https://quilljs.com/docs/formats/">Formats - Quill Rich Text Editor (quilljs.com)</a></p><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10322628">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 3：Quill 與 Angular 起手式</title>
      <link href="/2023/09/18/quill-day-3/"/>
      <url>/2023/09/18/quill-day-3/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/quill-day-3/20090749dwlMNWNaj5.png" alt="Quill"><br>上一篇我們看了 Why Quill，今天就來複習環境設置，並嘗試新增一個 Angular 專案，不過如果你是被標題吸引進來的同學，多少都有接觸過 Angular，或者主要就是用 Angular 開發的。這篇的目標是給沒接觸過 Angular 的朋友按照步驟體驗看看用 Angular 開發專案的感受。以前當過一陣子的 Angular 傳教士，雖然後來因為工作的關係換寫 React，但個人私心還是比較喜歡 Angular 的開發體驗 XD</p><h2 id="什麼是-Quill？"><a href="#什麼是-Quill？" class="headerlink" title="什麼是 Quill？"></a>什麼是 Quill？</h2><p>Quill 是一個簡單易用且可擴展的 WYSIWYG 開源文本編輯器，它提供了豐富的文本編輯功能，包括格式化文字、插入圖片、表格和連結等。Quill 的設計簡單、易於使用，它是以 JavaScript 為基礎，並且提供了豐富的插件和擴充功能，讓使用者可以輕鬆地滿足各種文本編輯的需求。</p><blockquote><p>WYSIWYG (What You See Is What You Get) 縮寫。<br>初次看到的時候也一頭霧水，就是所見即所得。</p></blockquote><h2 id="什麼是-Angular？"><a href="#什麼是-Angular？" class="headerlink" title="什麼是 Angular？"></a>什麼是 Angular？</h2><p>Angular 是一個基於 <a href="https://www.typescriptlang.org/">TypeScript</a> 的開發平台。而身為一個平台，Angular 包含：</p><ul><li>一個元件化的框架，用來建構可延展的 Web 應用程式。</li><li>一整套經深思熟慮而整合出來的函式庫，包含各種不同的功能，包含路由機制、表單管理、Client&#x2F;Server 通訊，以及更多。</li><li>一組完善的開發工具，幫助你開發、建置、測試、更新你的程式碼。</li></ul><h2 id="安裝和配置-Quill-Editor-在-Angular-專案中"><a href="#安裝和配置-Quill-Editor-在-Angular-專案中" class="headerlink" title="安裝和配置 Quill Editor 在 Angular 專案中"></a>安裝和配置 Quill Editor 在 Angular 專案中</h2><p>首先我們需要準備 Node.js 環境，然後安裝 Angular CLI 並使用指令建立新專案，最後到專案目錄下用 NPM 安裝 Quill，步驟如下：</p><ol><li>在 Angular 專案中安裝 Quill 函式庫：使用 npm 或者 yarn 安裝 Quill，確保在專案中引入所需的 dependency：</li></ol><pre><code class="bash"># 安裝 Angular CLInpm install @angular/cli# 建立一個新專案ng new quill-editor-todo# 建立的過程會有一些提問，按照需求選擇即可，例如:# 要不要分享資料給官方作為改善用途: Yes# 選擇 Style 的語言: SCSS# 是否建立 Routing: No# Install Quill Editorcd quill-editor-todonpm install quill@1.3.6 --save# Install Quill Editor Typesnpm install @types/quill@1 --save-dev</code></pre><ol start="2"><li>引入 Quill Style</li></ol><pre><code>&#123;  // ...  &quot;architect&quot;: &#123;    &quot;build&quot;: &#123;      &quot;options&quot;: &#123;        &quot;styles&quot;: [          &quot;node_modules/quill/dist/quill.snow.css&quot;,          &quot;src/styles.css&quot;        ],        // ...      &#125;,      // ...    &#125;,    // ...  &#125;&#125;</code></pre><ol start="3"><li>建立 Quill Editor 元件，來試試看 standalone：</li></ol><pre><code class="bash"># 建立一個 standalone componentng generate component quill-editor --standalone</code></pre><p>在 Component 的 template 簡單的加上一個帶有 Id 的 <code>div</code> 標籤</p><pre><code class="html">&lt;!-- quill-editor.component.html --&gt; &lt;div id=&quot;quill&quot; #quillContainer&gt;&lt;/div&gt;</code></pre><ol start="4"><li>在 quill-editor component 初始化 Quill Editor：</li></ol><pre><code class="typescript">// quill-editor.component.tsimport Quill from &#39;quill&#39;;import &#123; AfterViewInit, Component, ElementRef, ViewChild &#125; from &#39;@angular/core&#39;;import &#123; CommonModule &#125; from &#39;@angular/common&#39;;@Component(&#123;  selector: &#39;app-quill-editor&#39;,  standalone: true,  imports: [CommonModule],  templateUrl: &#39;./quill-editor.component.html&#39;,  styleUrls: [&#39;./quill-editor.component.css&#39;],&#125;)export class QuillEditorComponent implements AfterViewInit &#123;  @ViewChild(&#39;quillContainer&#39;) quillContainer!: ElementRef;  private quillEditor: any;  content: string = &#39;&#39;; // 初始化編輯器內容為空字串  ngAfterViewInit() &#123;    this.quillEditor = new Quill(this.quillContainer.nativeElement, &#123;      // this.quillEditor = new Quill(&quot;#quill&quot;, &#123; // also works      theme: &#39;snow&#39;, // 可以選擇不同的主題，例如 &#39;bubble&#39; 或 &#39;core&#39;    &#125;);      // 監聽編輯器內容變化事件，並將變化同步到 Angular 的資料模型    this.quillEditor.on(&#39;text-change&#39;, () =&gt; &#123;      this.content = this.quillEditor.root.innerHTML;    &#125;);  &#125;&#125;</code></pre><p>雖然透過 <code>AfterViewInit</code> 可以拿到對應的 <code>id</code> selector，但用 <code>@ViewChild</code> 可以更符合 Angular 的操作方式來獲取 DOM，因此我們還是使用 <code>this.quillContainer.nativeElement</code> 來初始化 Quill。</p><p>當執行 <code>ng serve</code> 時，會看到這樣的 warning：</p><pre><code>Warning: D:\Projects\quill-editor-todo\src\app\quill-editor\quill-editor.component.ts depends on &#39;quill&#39;. CommonJS or AMD dependencies can cause optimization bailouts.</code></pre><p>這是由於 Quill 是屬於 CommonJS module，進而影響到未來在建置的時候打包優化的問題。目前如果不想看到這個訊息，可以直接在 <code>project.json</code> 或 <code>angular.json</code> 裡面的 <code>build</code> 底下新增：</p><pre><code class="json">&quot;allowedCommonJsDependencies&quot;: [&quot;quill&quot;]</code></pre><p>再 <code>ng serve</code> 一次就不會看到 warning 了。</p><p>最後在 app component import <code>QuillEditorComponent</code>，並且在 <code>app.component.html</code> 加上 tag：</p><pre><code class="html">&lt;app-quill-editor&gt;&lt;/app-quill-editor&gt;</code></pre><p><code>ng serve</code> 並重新整理，試著在編輯器中輸入文字、調整文字樣式，以及插入連結等功能，來體驗 Quill Editor 的基本編輯功能。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>今天我們體驗了如何安裝 Angular CLI ，並透過指令建立新專案後加入 Quill，讓我們能夠在這個專案輕鬆擁有一個功能豐富的文字編輯器。明天我們將會依照內建的功能介紹關於 Quill Editor 的應用，之後會提供一些實例和程式碼來幫助讀者更好理解如何操作。</p><blockquote><p>備註：如果你的 VSCode 有安裝 Nx console，這時候 Extension 會跳出來詢問是否直接套用 Nx，這個步驟可用可不用，筆者提供的範例是有透過 Nx 自動初始化，所以會和原本的 Angular 初始專案不太一樣。</p></blockquote><h4 id="雜記："><a href="#雜記：" class="headerlink" title="雜記："></a>雜記：</h4><p>很久沒玩手機遊戲了，最近跟室友開始玩魔物獵人 Now，跟 Pokemon Go 一樣，需要走到戶外才能玩這遊戲，邊散步邊打魔物感覺還滿新鮮的。給自己另一個出去走走的理由 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://github.com/jeffwu85182/quill-editor-todo">練習範例 Repo</a></li><li><a href="https://developer.mozilla.org/zh-TW/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/Angular_getting_started">Angular 新手入門 - 學習該如何開發 Web | MDN (mozilla.org)</a></li><li><a href="https://quilljs.com/docs/quickstart/">Quickstart - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10321755">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 2：Why Quill？</title>
      <link href="/2023/09/17/quill-day-2/"/>
      <url>/2023/09/17/quill-day-2/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/quill-day-2/20230917153540.png"></p><h2 id="建立內容"><a href="#建立內容" class="headerlink" title="建立內容"></a>建立內容</h2><p>從網路誕生以來，建立內容一直是網路的核心。<code>&lt;textarea&gt;</code> 為大部分的網頁應用提供了原生且重要的解決方案，但有時候我們會需要為輸入的文本加上文字格式。這時 Rich Ediotr 的出現就派上用場了。目前有很多解決方案可以選擇，但 Quill 提供了一些現代的想法可供參考。</p><h2 id="API-驅動設計-API-Driven-Design"><a href="#API-驅動設計-API-Driven-Design" class="headerlink" title="API 驅動設計 (API Driven Design)"></a>API 驅動設計 (API Driven Design)</h2><p>Rich editor 的目的是協助使用者撰寫文本。但大多數的 rich editor 都不知道使用者寫了什麼文本。什麼意思呢? 就是說編輯器與 Web 開發者一樣是透過 DOM (Document Object Model) 的視角來查看內容。這樣的方式會出現一些阻礙，因為 DOM 是以非平衡樹 (Unbalanced Tree) 的節點組合而成，而文本則是由行、單詞與字符所構成。</p><p>沒有任何一個 DON API 是以字元為測量單位。也因為這樣的限制，大部分的 rich editor 無法回答出類似這樣的簡單問題：「這個範圍的文本是什麼?」 或「目前游標是否停在粗體的文字上?」DOM 與文本兩者的基礎結構不一致，造成開發者在嘗試提供更豐富且直覺的文本編輯體驗時面臨到的困難和挑戰。</p><p>Quill 專為編輯和字符而設計，並在這些基於自然文本為中心單位上開發了 API。要確定某些內容是否為粗體，Quill 不需要遍歷 DOM 來查找 <code>&lt;b&gt;</code> 或 <code>&lt;strong&gt;</code> 節點或字體粗細樣式屬性 - 只需呼叫 getFormat(5, 1)。其中所有核心 API 呼叫都允許使用任意索引 (index) 和長度 (length) 進行訪問或修改。其事件 API(Event API) 也以直觀的 JSON 格式回報變更的內容。不需要解析 HTML 或比對 DOM Tree。</p><h2 id="自定義內容與格式化"><a href="#自定義內容與格式化" class="headerlink" title="自定義內容與格式化"></a>自定義內容與格式化</h2><p>在不久前，評估 rich editor 很簡單，只需比較它支援了多少種格式。雖然這是一個重要的評估指標，但隨著需求的增加，這個下限正在趨近於無限大。簡單來說就是坑越來越深了。</p><p>文本的撰寫不再只是為了列印出來，如今也能渲染在網頁上。這是一個比紙更豐富的平台。內容可以是即時的、有互動的，可協作的。甚至有些 rich editor 支援如圖片和影片等媒體來豐富文本內容，但幾乎沒有可以像嵌入推文 (tweet )或互動圖表的。然而，這正是網路正在發展的方向：更豐富且可互動的內容。因此，這些建立內容的工具就需要考慮到這些使用案例。</p><p>Quill 提供了自己的文件模型 (document model)，這是比 DOM 還要強大的抽象方式，允許進行擴充和自訂。Quill 可以支援的格式和內容幾乎是沒有限制的。使用者已經使用它來加入嵌入式幻燈片、互動式待辦事項清單甚至是 3D 模型。</p><h2 id="跨平台"><a href="#跨平台" class="headerlink" title="跨平台"></a>跨平台</h2><p>對很多 JavaScript 函式庫來說，跨平台支援是很重要的。但這個具體的概念也常因為函式庫的不同而有所差異。對 Quill 來說，它的標準不僅僅是能正常運作這麼簡單，無論是功能實現上要考慮跨平台的支援，或是使用者與開發者的體驗也必須是一致的。</p><p>舉例來說：</p><ul><li>如果在 OSX 上的 Chrome 瀏覽器中某些內容會產生特定的標記，那麼在 IE 上也應該產生相同的標記。(OS：還好目前的工作只需要專注在 chrome…)</li><li>如果在 Windows 上的 Firefox 瀏覽器中按下 Enter 鍵能保留文字加粗的格式，那麼在 Mobile 的 Safari 上也應該能保留。</li></ul><h2 id="易於使用"><a href="#易於使用" class="headerlink" title="易於使用"></a>易於使用</h2><p>上述的所有好處就集中在這個容易使用的 package 中。Quill 附帶了合理的預設配置，只需要幾行 JavaScript 程式碼，你就可以立即享用：</p><pre><code class="typescript">const quill = new Quill(&#39;#editor&#39;, &#123;  modules: &#123; toolbar: true &#125;,  theme: &#39;snow&#39;&#125;);</code></pre><p>Quill 已經為你提供了一個豐富且一致的使用體驗，這個體驗是“開箱即用”的。如果你的需求完全符合 Quill 預設提供的功能，且不需要額外自訂功能，那麼你只需安裝和使用它，不必進行任何額外的設定或開發。</p><blockquote><p>當然我是因為有很多大量的客製需求，所以才開始跳入這個坑的，明天就來練習一下，如何建立一個 Angular 專案，並把 Quill 加進去。</p></blockquote><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>Quill 是一個現代化的富文本編輯器，提供了基於自然文本的 API，讓開發者更容易操作和獲取文本資訊。它支援高度自定義和擴展，以適應多變和複雜的需求。同時，Quill 也重視跨平台的一致性和使用者體驗。Quill 的初始設置非常簡單，可謂是”開箱即用”的解決方案。</p><h4 id="雜記："><a href="#雜記：" class="headerlink" title="雜記："></a>雜記：</h4><p>前天跟隊友一起去吃飯，正在等候叫位的時候，來了一對老夫婦，老太太說這兩個人中間有個小孩，應該是吧? 朝著他們看的方向看了一下，原來是廁所的 icon，內心想：這對老夫婦大概是剛才錯把電梯的 icon 當成廁所了。這麼說，以前好像也滿常在三創把廁所跟電梯的 icon 給搞混的。平常還好，但 O 在滾的時候可是很要命的，再次體會到 UI&#x2F;UX 的重要性 XD</p><h4 id="Reference"><a href="#Reference" class="headerlink" title="Reference"></a>Reference</h4><ul><li><a href="https://quilljs.com/guides/why-quill/">Why Quill - Quill Rich Text Editor (quilljs.com)</a></li></ul><p>文章同步發表於<a href="https://ithelp.ithome.com.tw/articles/10320449">2023 iThome 鐵人賽</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Day 1：就從前言開始吧</title>
      <link href="/2023/09/16/quill-day-1/"/>
      <url>/2023/09/16/quill-day-1/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/quill-day-1/20090749y1RK7VNloK.png" alt="Quill"></p><h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>最近開始新的職業生涯，重回 Angular 專案的懷抱，但也看到許多未曾接觸過的東西，例如 Quill Editor 這個編輯器，這裡面的東西非常的豐富，而且也有相當多的運用。剛好碰到鐵人賽準備開始，以前都沒參加過，但也看過不少完賽的鐵人大神，我想我也來試試看吧！至於參加這個鐵人賽的心情，我需要給自己設一下 mindset，除了給自己有機會可以好好了解一下這個編輯器在 Angular 專案上的使用，同時也可以透過寫文章的方式將學到的知識內化，並在未來當作複習參考的筆記、參考的筆記，的筆記，筆記。</p><blockquote><p>這是筆記，至少要自己能看懂，但也歡迎有任何問題都可以留言討論 :)</p></blockquote><h2 id="關於我"><a href="#關於我" class="headerlink" title="關於我"></a>關於我</h2><p>我是 Jeff Wu，曾經是推廣 Angular 的傳教士，喜歡參與社群與不同的開發者交流。以前參加過 Coscup 開源人年會擔任一小節的講者、Angular Taiwan 小聚的講者，不定期參加線上讀書會，前面幾年跳到 React.js 的開發團隊，所以將近四年沒有接觸實務上的 Angular 專案開發。在換工作之前，由於疫情的關係已經整整遠距工作長達兩年，平常習慣下班後去運動，但換了工作之後還在適應恢復通勤人生的節奏，以及新工作上的各種燒腦的龐大資訊量。休閒興趣是健身、模型以及看動畫。偶爾喜歡跟朋友喝威士忌、梅酒、紅酒，因此家裡也堆了不少酒…XD，但還不至於發生酒精驅動開發這種神奇的狀況就是了。</p><h2 id="關於主題"><a href="#關於主題" class="headerlink" title="關於主題"></a>關於主題</h2><p>雖然說是 Angular + Quill.js，但更多的會去了解 Quill Editor 的世界觀，例如底下有哪些模組(module)、內建的方法(method)或屬性(property)有哪些、 以及有什麼 API 可以使用，如果有自訂需求的時候要如何去實現，等相關議題，所以絕大部分都會是去看官方的技術文件，之後做一些簡單的練習來驗證。</p><p>而 Angular 的部分則會碰到的時候稍微提一下，例如要引用的時候需要留意的地方，或者使用 <code>ngx-qull</code> 套件將 Quill Editor 的引入更容易些。</p><p>與 Quill 有關的詞彙例如：Parchment、Blot、Delta…etc. 會是接下來主要想研究的內容。但如果有 Angular 相關的疑問，也歡迎留言，或者直接到 <a href="https://www.facebook.com/groups/augularjs.tw">Angular Taiwan</a> 社團發文討論。</p><p>文章同步發表於：(2023 iThome 鐵人賽)[<a href="https://ithelp.ithome.com.tw/articles/10319333]">https://ithelp.ithome.com.tw/articles/10319333]</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Quill </category>
          
      </categories>
      
      
        <tags>
            
            <tag> 15th 30 Days Challenge </tag>
            
            <tag> Quill </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>把 Angular SSR 應用部屬到 Firebase</title>
      <link href="/2023/05/13/angular-ssr-firebase/"/>
      <url>/2023/05/13/angular-ssr-firebase/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>繼上次玩了一下 SSR Hydration 之後，這次直接體驗用 Firebase 來發布 Angular SSR 的應用，並把過程記錄下來。這次的實驗是使用 Firebase 的 Functions 來部屬 SSR 應用，以及使用 Firebase Hosting 來部屬靜態檔案。概念上就是 Hosting 的首頁直接導向 Server 的 API 來取得 SSR 的 HTML 字串，然後 Client 端再進行 Hydration 以此初始化 Angular 應用。<br>先看 Lighthouse 測一下跑分的結果:<br><img src="/images/angular-ssr-firebase/lighthouse.webp" alt="Firebase SSR Lighthouse"></p><h2 id="Ng-build-之前的準備"><a href="#Ng-build-之前的準備" class="headerlink" title="Ng build 之前的準備"></a>Ng build 之前的準備</h2><p>我直接基於之前的 TodoMVC2023 專案來實驗，在執行指令之前，我們需要做一下檔案的調整。</p><h3 id="修改-angular-json-的-build-outputPath"><a href="#修改-angular-json-的-build-outputPath" class="headerlink" title="修改 angular.json 的 build outputPath"></a>修改 angular.json 的 build outputPath</h3><p>把 <code>angular.json</code> 中的 build 與 server 的 outputPath 調整一下，將打包出來的檔案放在 <code>dist/functions</code> 目錄下。</p><pre><code class="json"> &quot;architect&quot;: &#123;        &quot;build&quot;: &#123;          &quot;builder&quot;: &quot;@angular-devkit/build-angular:browser&quot;,          &quot;options&quot;: &#123;            &quot;outputPath&quot;: &quot;dist/functions/browser&quot;,          ...          ...          &quot;server&quot;: &#123;          &quot;builder&quot;: &quot;@angular-devkit/build-angular:server&quot;,          &quot;options&quot;: &#123;            &quot;outputPath&quot;: &quot;dist/functions/server&quot;,          ...        &#125;,</code></pre><h3 id="修改-server-ts"><a href="#修改-server-ts" class="headerlink" title="修改 server.ts"></a>修改 server.ts</h3><p>由於 Angular CLI 自動產生的 server.ts 裡面也有 <code>distFolder</code> 的配置，所以也要跟著調整:</p><pre><code class="typescript">const isDev = isDevMode(); // Don&#39;t forget to import isDevMode from @angular/coreconst website = isDev ? &#39;dist/functions/browser&#39; : &#39;browser&#39;;const distFolder = join(process.cwd(), website);</code></pre><p>執行 <code>build:ssr</code> 指令:</p><pre><code class="bash">npm run build:ssr</code></pre><p>Build 完之後可以看到 dist 目錄下有 <code>function/server</code> 以及 <code>function/browser</code> 的資料夾，稍微確認一下有沒有正常出現。</p><h2 id="安裝-Firebase-Tools-CLI"><a href="#安裝-Firebase-Tools-CLI" class="headerlink" title="安裝 Firebase Tools CLI"></a>安裝 Firebase Tools CLI</h2><p>首先要先安裝 Firebase Tools CLI，這個工具可以讓我們在本機端進行 Firebase 操作指令，安裝方式如下:</p><pre><code class="bash">npm install -g firebase-tools</code></pre><p>安裝完成後可以透過 <code>firebase --version</code> 來確認是否安裝成功。</p><h2 id="登入-Firebase-CLI"><a href="#登入-Firebase-CLI" class="headerlink" title="登入 Firebase CLI"></a>登入 Firebase CLI</h2><p>接著要進行登入，輸入 <code>firebase login</code> 指令，會跳出瀏覽器視窗，請登入 Google 帳號，登入完成後，就可以在 CLI 看到登入成功的訊息。另外它會問你是否要讓它收集資料以改善服務，這邊就看個人意願了。</p><h2 id="初始化-Firebase"><a href="#初始化-Firebase" class="headerlink" title="初始化 Firebase"></a>初始化 Firebase</h2><h3 id="Project-Setup"><a href="#Project-Setup" class="headerlink" title="Project Setup"></a>Project Setup</h3><p>登入之後，就可以進行初始化，輸入 <code>firebase init</code> 指令，會跳出選單，我是選擇 <code>Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys</code> 以及 <code>Functions: Configure a Cloud Functions directory and its files</code>，接著會問你要使用哪個專案，可以選擇建立新的專案或是選擇既有的專案。</p><pre><code class="bash">? Please select an option: Create a new projecti  If you want to create a project in a Google Cloud organization or folder, please use &quot;firebase projects:create&quot; instead, and return to this command when you\&#39;ve created the project.? Please specify a unique project id (warning: cannot be modified afterward) [6-30 characters]: todomvc-ssr-demo? What would you like to call your project? (defaults to your project ID)✔ Creating Google Cloud Platform project✔ Adding Firebase resources to Google Cloud Platform project=== Your Firebase project is ready! ===Project information:   - Project ID: todomvc-ssr-demo   - Project Name: todomvc-ssr-demo</code></pre><h3 id="Hosting-Setup"><a href="#Hosting-Setup" class="headerlink" title="Hosting Setup"></a>Hosting Setup</h3><p>接著是 Hosting 相關的設定，主要會詢問你要部屬到哪個資料夾，以及是否要使用 SPA 模式:</p><pre><code class="bash">? What do you want to use as your public directory? functions? Configure as a single-page app (rewrite all urls to /index.html)? Yes? Set up automatic builds and deploys with GitHub? No+  Wrote public/index.html</code></pre><h3 id="Function-Setup"><a href="#Function-Setup" class="headerlink" title="Function Setup"></a>Function Setup</h3><p>設置 Functions 的部分，會有幾個提問，我們選擇 <code>JavaScript</code>，然後會問你要不要使用 ESLint，這邊我選擇 <code>No</code>，最後會問你要不要安裝相依套件，這邊我選擇 <code>Yes</code>。</p><pre><code class="bash">? What language would you like to use to write Cloud Functions? JavaScript? Do you want to use ESLint to catch probable bugs and enforce style? No+  Wrote functions/package.json+  Wrote functions/.gitignore+  Wrote functions/index.js? Do you want to install dependencies with npm now? Yes</code></pre><h3 id="functions-x2F-index-js-加入-ngssr-API"><a href="#functions-x2F-index-js-加入-ngssr-API" class="headerlink" title="functions&#x2F;index.js 加入 ngssr API"></a>functions&#x2F;index.js 加入 ngssr API</h3><p>初始化完成之後，刪除 <code>functions/index.html</code>，並且在 <code>functions/index.js</code> 這個檔案新增 API: ngssr:</p><pre><code class="JavaScript">const functions = require(&quot;firebase-functions&quot;);const mainjsfile = require(__dirname + &#39;/server/main&#39; );exports.ngssr = functions.https.onRequest(mainjsfile.app());</code></pre><h3 id="調整-firebase-json"><a href="#調整-firebase-json" class="headerlink" title="調整 firebase.json"></a>調整 firebase.json</h3><p>新增 <code>ngssr</code> API 之後，要修改 <code>firebase.json</code> 裡面的 <code>rewrites</code>，讓它可以正確的導向到 <code>ngssr</code> API:</p><blockquote><p>注意: 預設的 <code>rewrites</code> 是 <code>destination</code>，這邊要改成 <code>function</code>。</p></blockquote><pre><code class="json">&quot;rewrites&quot;: [      &#123;        &quot;source&quot;: &quot;**&quot;,        &quot;function&quot;: &quot;ngssr&quot;      &#125;    ]</code></pre><h2 id="執行本地端測試"><a href="#執行本地端測試" class="headerlink" title="執行本地端測試"></a>執行本地端測試</h2><p>使用 firebase emulators:start 來啟動本地端的測試環境，這邊會需要一些時間，因為它會幫你安裝相依套件，並且啟動本地端的測試環境。</p><pre><code class="bash">firebase emulators:start</code></pre><p>都沒有報錯的話，就可以在瀏覽器輸入 <code>http://localhost:5000</code> 來看到 SSR 的畫面了。</p><h2 id="發布到-Firebase"><a href="#發布到-Firebase" class="headerlink" title="發布到 Firebase"></a>發布到 Firebase</h2><p>都確認沒問題之後，就發佈到 Firebase 吧，輸入 <code>firebase deploy</code> 指令，就可以看到部屬的結果了。</p><pre><code class="bash">firebase deploy</code></pre><blockquote><p>注意: 如果是新的 Firebase Project，預設是免費的 Plan: Spark，可能需要轉成付費的 Blaze Plan 才能部屬成功。</p></blockquote><p>部屬的網址應該是 <code>YOUR_PROJECT_NAME.web.app</code>，deploy 成功後也會出現提示:</p><pre><code class="bash">+  Deploy complete!Project Console: https://console.firebase.google.com/project/YOUR_PROJECT_NAME/overviewHosting URL: https://YOUR_PROJECT_NAME.web.app</code></pre><h2 id="驗證結果"><a href="#驗證結果" class="headerlink" title="驗證結果"></a>驗證結果</h2><p>首先看一下 Network 第一時間拿到的 HTML:<br><img src="/images/angular-ssr-firebase/network.webp" alt="Firebase SSR Network"></p><p>使用 Dev Tool 的 Performance 錄製:<br><img src="/images/angular-ssr-firebase/performance.webp" alt="Firebase SSR Performance"></p><h2 id="結論"><a href="#結論" class="headerlink" title="結論"></a>結論</h2><p>儘管 Angular 配置 SSR 已經相對簡單了許多，不過要搭配什麼樣的 Server 具體還是要根據每個專案的需求去個別調整。這次的實驗是使用 Firebase Functions 來部屬 SSR 應用。另外，雖然升級 Blaze 付費方案後 Firebase Functions 還是有提供免費額度，但超過的話就要付費了，所以如果是大量使用 SSR 的話，還是要考慮一下成本的問題。另外還要注意 .gitignore 的設定，因為這個實驗是直接把 Firebase 專案放到 <code>dist</code> 目錄下，是沒有進版控的。如果要進版控的話，要把 <code>dist</code> 目錄下的 <code>functions</code> 資料夾加入到 <code>.gitignore</code> 中，避免把 <code>node_modules</code> 也一起上版控。</p><blockquote><p><strong><span style="color:red">!!!注意: 如果你只是嘗試玩一下的話，保險起見還是要到 GCP 帳戶設定一下預算，避免超支。!!!</span></strong></p></blockquote><p><img src="/images/angular-ssr-firebase/budget.webp" alt="Firebase SSR Budget"></p><h2 id="參考資料與範例"><a href="#參考資料與範例" class="headerlink" title="參考資料與範例"></a>參考資料與範例</h2><p><a href="https://github.com/jeffwu85182/TodoMVC2023">TodoMVC2023</a><br><a href="https://medium.com/@d.gerbede/angular-ssr-with-universal-and-firebase-e68e3989b8ff">Angular SSR with Universal and firebase</a><br><a href="https://fireship.io/lessons/angular-universal-firebase/">Angular Universal SSR with Firebase</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
          <category> Firebase </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> Angular 16 </tag>
            
            <tag> SSR </tag>
            
            <tag> Hydration </tag>
            
            <tag> Firebase Functions </tag>
            
            <tag> Firebase Hosting </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>使用原生 HTML Dialog</title>
      <link href="/2023/05/09/html-dialog/"/>
      <url>/2023/05/09/html-dialog/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/html-dialog/cover.webp" alt="HTML Dialog"></p><h2 id="關於-Modal-與-Dialog"><a href="#關於-Modal-與-Dialog" class="headerlink" title="關於 Modal 與 Dialog"></a>關於 Modal 與 Dialog</h2><p>在今日的網站開發上，使用彈窗式的介面來呈現資訊只要是接觸過網站開發的人應該都不陌生，而在過去我們對於彈窗式介面的實現方式，通常是透過 JavaScript 控制 class 來達成，但這樣的方式在維護上會有一些問題，例如：對於 Modal 或 Dialog 的顯示位置我們都需要另外寫一份 CSS 去設計，需要使用 <code>.open</code> 之類的 CSS class 來控制開關，或者需要額外的元素實現 Modal 的背景，而這樣的實現成本比較高，而且也不易維護。而在 HTML5 中，我們可以透過 <code>dialog</code> 標籤來實現彈窗式介面，這樣的實現方式不僅簡單，而且也不需要透過 JS 來控制 CSS Class，接下來就讓我們來看看如何使用 dialog element。</p><span id="more"></span><h2 id="Modal-與-Dialog-的差異"><a href="#Modal-與-Dialog-的差異" class="headerlink" title="Modal 與 Dialog 的差異"></a>Modal 與 Dialog 的差異</h2><p>Modal 是一種介面的設計模式，而 Dialog 則是一種介面的元素，Modal 通常會使用 Dialog 來實現，但 Dialog 並不一定是 Modal，例如：我們可以透過 Dialog 來實現一個提示訊息的介面，而這個介面並不是 Modal，因為它並不會阻止使用者對其他元素進行操作，而 Modal 則是會阻止使用者對其他元素進行操作，直到 Modal 關閉為止。<br></p><blockquote><p>兩者最大的差異在於：Modal 會阻止使用者對其他元素進行操作，而 Dialog 則不會。對我來說，Modal 是一個完全阻隔的彈窗內容並且顯示在畫面上的中央，而 Dialog 比較像是一個提示訊息的介面。</p></blockquote><h2 id="使用-Dialog"><a href="#使用-Dialog" class="headerlink" title="使用 Dialog"></a>使用 Dialog</h2><p>要使用 Dialog 很簡單，只需要在 HTML 中加入 <code>&lt;dialog&gt;</code> 元素即可，例如：</p><pre><code class="html">&lt;dialog open&gt;  &lt;p&gt;Greetings, one and all!&lt;/p&gt;  &lt;form method=&quot;dialog&quot;&gt;    &lt;button&gt;OK&lt;/button&gt;    &lt;button (click)=&quot;closeDialog()&quot;&gt;Cancel&lt;/button&gt;  &lt;/form&gt;&lt;/dialog&gt;</code></pre><p><code>open</code> attribute 會讓 Dialog 在載入時就顯示出來，而 form 中的 method 屬性則是用來指定 Dialog 的行為，預設值為 <code>dialog</code>，也就是當使用者點擊 form 中的 button 時，Dialog 會關閉，如果我們將 method 屬性設定為 <code>get</code>，則會將 form 中的資料以 GET 的方式送出，而如果設定為 <code>post</code>，則會以 POST 的方式送出，這樣的設定方式和一般的 form 是一樣的。</p><h2 id="Dialog-的-JS-操作方法"><a href="#Dialog-的-JS-操作方法" class="headerlink" title="Dialog 的 JS 操作方法"></a>Dialog 的 JS 操作方法</h2><p>要在 JavaScript 操作 Dialog 或 Modal，我們可以透過 <code>show()</code> 來顯示 Dialog，而 <code>showModal()</code> 則是以 Modal 方式呈現，兩者皆可使用 <code>close()</code> 方法來關閉 Modal 與 Dialog：</p><pre><code class="js">const dialog = document.querySelector(&#39;dialog&#39;);function openDialog() &#123;  dialog.showModal(); // for modal  // dialog.show(); // for dialog&#125;function closeDialog() &#123;  dialog.close();&#125;</code></pre><h2 id="Dialog-的-CSS-操作方法"><a href="#Dialog-的-CSS-操作方法" class="headerlink" title="Dialog 的 CSS 操作方法"></a>Dialog 的 CSS 操作方法</h2><p>關於 Style 的部分，Dialog 有一些預設的樣式，例如：<code>showModal()</code> 會自動置中，並且有陰影效果，這些預設的樣式讓我們只需要專注在介面呈現的風格，我們也可以透過 CSS 來進行修改，假設要調整 Modal 的陰影效果我們可以使用 <code>::backdrop</code> 調整：</p><pre><code class="css">dialog::backdrop &#123;  background-color: rgba(0, 0, 0, 0.5);&#125;</code></pre><h2 id="Dialog-的事件"><a href="#Dialog-的事件" class="headerlink" title="Dialog 的事件"></a>Dialog 的事件</h2><p>Dialog 也有一些事件可以使用，例如：<code>close</code> 事件，當 Dialog 關閉時觸發，而 <code>cancel</code> 事件則是當使用者點擊 Dialog 中的取消按鈕時觸發，而 <code>submit</code> 事件則是當使用者點擊 Dialog 中的確認按鈕時觸發：</p><pre><code class="js">const dialog = document.querySelector(&#39;dialog&#39;);dialog.addEventListener(&#39;close&#39;, () =&gt; &#123;  console.log(&#39;Dialog closed&#39;);&#125;);dialog.addEventListener(&#39;cancel&#39;, () =&gt; &#123;  console.log(&#39;Dialog cancelled&#39;);&#125;);dialog.addEventListener(&#39;submit&#39;, () =&gt; &#123;  console.log(&#39;Dialog submitted&#39;);&#125;);</code></pre><h2 id="兼容性"><a href="#兼容性" class="headerlink" title="兼容性"></a>兼容性</h2><p>如果舊版的瀏覽器不支援 Dialog，可以透過 <a href="https://github.com/GoogleChrome/dialog-polyfill">dialog-polyfill</a> 來實現，根據 README 裡面的描述可以支援到 IE9 以上的瀏覽器。使用之前也可以上 <a href="https://caniuse.com/dialog">Can I use</a> 來查看瀏覽器的支援度。</p><h2 id="結論"><a href="#結論" class="headerlink" title="結論"></a>結論</h2><p>使用 HTML 原生的 Dialog 可以讓我們更能專注於畫面的設計，同時也帶來有語意化的架構確保可用性及可訪問性。避免產生不必要的 CSS 樣式來管理 Dialog 的開關或位置，使用起來更直覺且易於維護。</p><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><p><a href="https://web-platform-yvpddf.stackblitz.io/">實作範例</a><br><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog">MDN - The Dialog element</a><br><a href="https://blog.webdevsimplified.com/2023-04/html-dialog/">Modals Will Never Be The Same - HTML dialog Element</a></p>]]></content>
      
      
      <categories>
          
          <category> HTML </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> Dialog </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>關於 Angular SSR 與 Hydration</title>
      <link href="/2023/05/08/angular-hydration-intro/"/>
      <url>/2023/05/08/angular-hydration-intro/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/angular-hydration-intro/cover.webp" alt="Angular Hydration"></p><h2 id="什麼是-SSR"><a href="#什麼是-SSR" class="headerlink" title="什麼是 SSR ?"></a>什麼是 SSR ?</h2><p>SSR 的全名是 Server-Side Rendering，是一種網頁開發技術。它指的是在 server 端將網頁應用程式的原始碼轉換成 HTML 字串，然後將這些 HTML 發送到 client 端。當 client 端收到預先渲染的 HTML 時，它可以立即在瀏覽器上顯示，而無需等待 JavaScript 加載和執行。這樣可以提高網站的首次加載速度，改善搜尋引擎的索引效果，以及提供更好的使用者體驗。</p><h2 id="什麼是-Hydration"><a href="#什麼是-Hydration" class="headerlink" title="什麼是 Hydration ?"></a>什麼是 Hydration ?</h2><p>Hydration 是指 client 端將 server 端回傳的 HTML 字串轉換成具有 Angular 功能的實時應用。在這個過程中，Angular 會將預先渲染的 HTML 中的靜態內容與 Angular 的動態功能結合起來，並綁定事件，讓使用者可以直接操作 app，就像與 client 端渲染的應用進行交互一樣。</p><h2 id="v16-的-Hydration-亮點是什麼"><a href="#v16-的-Hydration-亮點是什麼" class="headerlink" title="v16 的 Hydration 亮點是什麼?"></a>v16 的 Hydration 亮點是什麼?</h2><p>舊版的 Hydration 過程是透過 server 端渲染畫面之後送到 client 端，client 端雖然可以快速的看到應用程式的第一個畫面，但實際上還是要<strong>整個 App 在 Client 端重新渲染一次</strong>，因為 client 端無法訪問 Angular app 的狀態，這樣的過程會影響到使用體驗而且不夠有效率。<br><br>新的 Angular hydration 通過允許 client 端訪問 Angular app 狀態來解決這個問題。這意味著 client 端不必在 server 端呈現 HTML 後重新渲染整個應用。相反，client 端可以直接混合應用程式狀態，這是一個更快的過程。</p><h2 id="如何使用-SSR"><a href="#如何使用-SSR" class="headerlink" title="如何使用 SSR ?"></a>如何使用 SSR ?</h2><p>啟用 SSR 有幾個步驟:</p><ol><li>確認是否有升級到 Angular v16:</li></ol><pre><code class="bash">npx ng updatenpx ng update @angular/core @angular/cli</code></pre><ol start="2"><li>加入 <code>@nguniversal/express-engine</code>，會出現詢問是否執行自動執行，選擇 <code>Yes</code>:</li></ol><pre><code class="bash">ng add @nguniversal/express-engine</code></pre><p>完成之後會產生四個檔案，並更新 <code>package.json</code>:</p><pre><code class="bash">CREATE src/main.server.tsCREATE src/app/app.config.server.tsCREATE tsconfig.server.jsonCREATE server.ts</code></pre><ol start="3"><li>建立一個 <code>app.config.ts</code>，並將 <code>main.ts</code> 中的 <code>bootstrapApplication</code> 第二個參數(<code>options</code>) 搬過來:<br>由於 <code>app.config.server.ts</code> 會引用 <code>app.config.ts</code>，但目前沒有建立，所以我們要手動新增，例如:</li></ol><pre><code class="TypeScript">import &#123; ApplicationConfig, importProvidersFrom, isDevMode &#125; from &#39;@angular/core&#39;;import &#123; BrowserModule &#125; from &#39;@angular/platform-browser&#39;;import &#123; ServiceWorkerModule &#125; from &#39;@angular/service-worker&#39;;export const appConfig: ApplicationConfig = &#123;  providers: [    importProvidersFrom(      BrowserModule,      ServiceWorkerModule.register(&#39;ngsw-worker.js&#39;, &#123;        enabled: !isDevMode(),        // Register the ServiceWorker as soon as the application is stable        // or after 30 seconds (whichever comes first).        registrationStrategy: &#39;registerWhenStable:30000&#39;,      &#125;)    ),  ],&#125;;</code></pre><ol start="4"><li>並把 <code>main.ts</code> 的 <code>options</code> 改成 import 的方式:</li></ol><pre><code class="TypeScript">import &#123; bootstrapApplication &#125; from &#39;@angular/platform-browser&#39;;import &#123; AppComponent &#125; from &#39;./app/app.component&#39;;import &#123; appConfig &#125; from &#39;./app/app.config&#39;;bootstrapApplication(AppComponent, appConfig).catch((err) =&gt; console.error(err));</code></pre><ol start="5"><li>執行 <code>npm run dev:ssr</code>，以自己做的 TODOMVC 的跑分結果。<br>沒有 SSR 的分數:<br><img src="/images/angular-hydration-intro/withoutSSR.webp" alt="Result"><br>使用 SSR 的分數:<br><img src="/images/angular-hydration-intro/result.webp" alt="Result"></li></ol><h2 id="SSR-的優點"><a href="#SSR-的優點" class="headerlink" title="SSR 的優點"></a>SSR 的優點</h2><ul><li>更快的首頁渲染時間：由於伺服器已經渲染了初始 HTML，客戶端可以立即顯示內容，而無需等待 JavaScript 加載和執行。</li><li>搜索引擎優化 (SEO)： SSR 使搜索引擎更容易抓取和索引 app 的內容，因為它們可以直接讀取伺服器發送的 HTML。</li><li>提高可訪問性：部分瀏覽器可能對於 JavaScript 支持有限， SSR 可以確保這些瀏覽器至少能看到基本的內容和功能。</li></ul><h2 id="SSR-可能的挑戰及問題"><a href="#SSR-可能的挑戰及問題" class="headerlink" title="SSR 可能的挑戰及問題"></a>SSR 可能的挑戰及問題</h2><p>在實現 Angular SSR 時，可能會遇到一些需要探討的問題：</p><ul><li>性能問題：在 server 上渲染 app 會增加 server 的負擔，對於高流量的網站，這可能會導致性能問題。</li><li>client 端和 server 之間的狀態同步：由於 SSR 需要在 client 端和 server 之間共享狀態，開發人員需要確保兩者之間的狀態同步，以防止出現錯誤或不一致的行為。</li><li>環境差異：由於 client 端和 server 環境的差異，開發人員需要確保應用的程式碼可以在這兩個環境中正常運行。這可能涉及到檢查和處理某些特定於環境的 API 和功能。</li><li>增加複雜性：引入 SSR 可能會增加應用的複雜性，因為開發人員需要依照情況維護和管理兩個不同環境的程式碼。這可能需要更多的開發和測試時間。</li></ul><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><p><a href="https://angular.io/guide/universal">Server-side rendering with Angular Universal</a><br><a href="https://angular.io/guide/hydration">Angular Hydration</a><br><a href="https://blog.angular.io/angular-v16-is-here-4d7a28ec680d">Angular v16 is here!</a><br><a href="https://www.youtube.com/watch?v=b6MfRwiPhpo">Server Side Rendering (SSR) in Angular v16</a><br><a href="https://www.youtube.com/watch?v=25FgSUH4DCk">All About Server-side Rendering w&#x2F;Angular v16</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> Angular 16 </tag>
            
            <tag> SSR </tag>
            
            <tag> Hydration </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>使用 Angular Standalone Component 簡化開發</title>
      <link href="/2023/04/21/angular-standalone-component/"/>
      <url>/2023/04/21/angular-standalone-component/</url>
      
        <content type="html"><![CDATA[<p>在 Angular 14 新增了 <code>Standalone Component</code> 的功能，以往我們新增的 Component、Directive 以及 Pipe 可以不需要透過 <code>NgModule</code> 來管理元件，同時也能簡化使用 Angular 開發應用的體驗。現有應用可以選擇性逐步採用新的獨立樣式，而無需進行任何重大更改。<br><img src="/images/angular-standalone-component/standalone.webp" alt="Stand Alone"></p><h2 id="如何使用-Standalone-Component"><a href="#如何使用-Standalone-Component" class="headerlink" title="如何使用 Standalone Component"></a>如何使用 Standalone Component</h2><h3 id="建立-Standalone-Component"><a href="#建立-Standalone-Component" class="headerlink" title="建立 Standalone Component"></a>建立 Standalone Component</h3><p>語法相當簡單，只需要在 <code>ng generate</code> 指令後面加上 <code>--standalone</code> 即可：</p><pre><code class="bash">ng generate component &lt;component-name&gt; --standalone</code></pre><h3 id="Component-轉換成-Standalone-Component"><a href="#Component-轉換成-Standalone-Component" class="headerlink" title="Component 轉換成 Standalone Component"></a>Component 轉換成 Standalone Component</h3><p>如果要在既有的 Component 轉換成 Standalone Component，只需要在 <code>@Component</code> 裡面加上 <code>standalone: true</code>：</p><pre><code class="typescript">@Component(&#123;  standalone: true,  selector: &#39;photo-gallery&#39;,  imports: [ImageGridComponent],  template: ` ... &lt;image-grid [images]=&quot;imageList&quot;&gt;&lt;/image-grid&gt; `,&#125;)export class PhotoGalleryComponent &#123;  // component logic&#125;</code></pre><p>加上 <code>standalone: true</code> 之後，我們就可以在 Component 使用 imports 來引入其他的 Dependency，像是 Directive、Pipe、Component 等等。此外 <code>imports</code> 也可以引入其他的 NgModule。</p><h3 id="既有的-NgModule-加入-Standalone-Component"><a href="#既有的-NgModule-加入-Standalone-Component" class="headerlink" title="既有的 NgModule 加入 Standalone Component"></a>既有的 NgModule 加入 Standalone Component</h3><p>Standalone Component 透過 <code>NgModule.imports</code> 就可以加到既有的 NgModule 中：</p><pre><code class="typescript">@NgModule(&#123;  declarations: [AlbumComponent],  exports: [AlbumComponent],  imports: [PhotoGalleryComponent],&#125;)export class AlbumModule &#123;&#125;</code></pre><h2 id="直接從-Standalone-Component-執行應用"><a href="#直接從-Standalone-Component-執行應用" class="headerlink" title="直接從 Standalone Component 執行應用"></a>直接從 Standalone Component 執行應用</h2><p>我們可以不用透過任何 <code>NgModule</code> 來啟動應用，Angular 提供了 <code>bootstrapApplication</code> API，可以直接從 Standalone Component 啟動：</p><pre><code class="typescript">// in the main.ts fileimport &#123; bootstrapApplication &#125; from &#39;@angular/platform-browser&#39;;import &#123; PhotoAppComponent &#125; from &#39;./app/photo.app.component&#39;;bootstrapApplication(PhotoAppComponent);</code></pre><h2 id="新的-Routing-API-簡化-lazy-loading"><a href="#新的-Routing-API-簡化-lazy-loading" class="headerlink" title="新的 Routing API 簡化 lazy-loading"></a>新的 Routing API 簡化 lazy-loading</h2><p>Angular router API 也更新並簡化，以便利用 Standalone Component，在許多常見 lazy-loading 的情境不再需要 <code>NgModule</code>。例如要 lazy-loading 一個 Component，只需要在 <code>Route.loadComponent</code> 裡面使用 <code>import()</code> 來引入 Component 即可：</p><pre><code class="typescript">export const ROUTES: Route[] = [  &#123;    path: &#39;admin&#39;,    loadComponent: () =&gt;      import(&#39;./admin/panel.component&#39;).then((mod) =&gt; mod.AdminPanelComponent),  &#125;,  // ...];</code></pre><h3 id="一次-lazy-loading-多個路由"><a href="#一次-lazy-loading-多個路由" class="headerlink" title="一次 lazy-loading 多個路由"></a>一次 lazy-loading 多個路由</h3><p><code>LoadChildren</code> 現在支援加載一組新的子路由，不需要寫一個 lazy-load 的 <code>NgModule</code>，利用 <code>RouterModule.forChild</code> 宣告路由：</p><pre><code class="typescript">// In the main application:export const ROUTES: Route[] = [  &#123;    path: &#39;admin&#39;,    loadChildren: () =&gt;      import(&#39;./admin/routes&#39;).then((mod) =&gt; mod.ADMIN_ROUTES),  &#125;,  // ...];// In admin/routes.ts:export const ADMIN_ROUTES: Route[] = [  &#123; path: &#39;home&#39;, component: AdminHomeComponent &#125;,  &#123; path: &#39;users&#39;, component: AdminUsersComponent &#125;,  // ...];</code></pre><h3 id="Lazyloading-與-default-exports"><a href="#Lazyloading-與-default-exports" class="headerlink" title="Lazyloading 與 default exports"></a>Lazyloading 與 default exports</h3><p>上面的範例中 <code>ADMIN_ROUTES</code> 也可以改成 <code>export default</code>，如此一來在 <code>loadChildren</code> 或 <code>loadComponent</code> 都只需要 <code>import(&#39;./admin/routes&#39;)</code> ：</p><pre><code class="typescript">// In the main application:export const ROUTES: Route[] = [  &#123; path: &#39;admin&#39;, loadChildren: () =&gt; import(&#39;./admin/routes&#39;) &#125;,  // ...];// In admin/routes.ts:export default [  &#123; path: &#39;home&#39;, component: AdminHomeComponent &#125;,  &#123; path: &#39;users&#39;, component: AdminUsersComponent &#125;,  // ...] as Route[];</code></pre><h3 id="為部分路由提供服務的方法"><a href="#為部分路由提供服務的方法" class="headerlink" title="為部分路由提供服務的方法"></a>為部分路由提供服務的方法</h3><p>對於 NgModules 的 lazy-load API（即 <code>loadChildren</code>），在讀取路由的延遲載入子路由時，會創建一個新的模組注入器(Injector)。這個功能經常被用來為特定的路由提供 service。舉個例子，如果把所有 <code>/admin</code> 下的路由都用 <code>loadChildren</code> 來設定範圍，那麼只有這些路由才能獲得針對 Admin 的特定 service。要做到這一點，即使不需要延遲載入相關路由，也需要使用 <code>loadChildren</code> API。</p><p>如今，Router 允許在路由上明確指定額外的 <code>Providers</code>，這樣可以在不需要延遲載入或 <code>NgModule</code> 的情況下實現相同的範圍設定。舉例來說，<code>/admin</code> 路由結構內範圍限定的 service 將如下：</p><pre><code class="typescript">export const ROUTES: Route[] = [  &#123;    path: &#39;admin&#39;,    providers: [AdminService, &#123; provide: ADMIN_API_KEY, useValue: &#39;12345&#39; &#125;],    children: [      &#123; path: &#39;users&#39;, component: AdminUsersComponent &#125;,      &#123; path: &#39;teams&#39;, component: AdminTeamsComponent &#125;,    ],  &#125;,  // ... other application routes that don&#39;t  //     have access to ADMIN_API_KEY or AdminService.];</code></pre><p>我們可以將 provider 與額外路由配置的 <code>loadChildren</code> 相結合，以實現延遲載入帶有額外路由和路由級 provider 的 NgModule 的相同效果。這個例子配置了與上述相同的 provider&#x2F;子路由，但是在延遲載入的邊界之後：</p><pre><code class="typescript">// Main application:export const ROUTES: Route[] = &#123;  // Lazy-load the admin routes.  &#123;path: &#39;admin&#39;, loadChildren: () =&gt; import(&#39;./admin/routes&#39;).then(mod =&gt; mod.ADMIN_ROUTES)&#125;,  // ... rest of the routes&#125;// In admin/routes.ts:export const ADMIN_ROUTES: Route[] = [&#123;  path: &#39;&#39;,  pathMatch: &#39;prefix&#39;,  providers: [    AdminService,    &#123;provide: ADMIN_API_KEY, useValue: 12345&#125;,  ],  children: [    &#123;path: &#39;users&#39;, component: AdminUsersCmp&#125;,    &#123;path: &#39;teams&#39;, component: AdminTeamsCmp&#125;,  ],&#125;];</code></pre><p>要留意一下空路徑的路由下的 providers 是在所有的子路由共享的。 另外，<code>importProvidersFrom</code> 這個方法可以 import 基於 <code>NgModule</code> 的 DI 注入到 Route 的 providers 中：</p><pre><code class="typescript">export const ROUTES: Route[] = [  &#123;    path: &#39;foo&#39;,    providers: [importProvidersFrom(NgModuleOne, NgModuleTwo)],    component: YourStandaloneComponent,  &#125;,];</code></pre><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>當專案規模越來越大的時候 NgModule 的管理可能會面臨挑戰，時常要思考是否要建立新的 NgModule，或是這個元件是否會被重覆使用，一不小心就進入了重構地獄。Standalone Coponent 算是把 NgModule 一部分的功能下放到元件的層級，這樣可以避免建立元件時可能的摩擦，並且簡化了學習歷程，同時也可以讓延遲載入變得更容易。未來需要什麼東西就直接 import 到元件中，不需要再去管 NgModule 的事情。</p><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><p><a href="https://angular.io/guide/standalone-components">Angular Standalone Component</a><br><a href="https://www.youtube.com/watch?v=x5PZwb4XurU&ab_channel=Angular">Getting started with Angular Standalone Component</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> Angular Standalone Component </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>原子化 CSS 學習筆記</title>
      <link href="/2023/04/19/atomic-css-intro/"/>
      <url>/2023/04/19/atomic-css-intro/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/atomic-css-intro/cover.jpg" alt="原子化概念"></p><h2 id="原子化"><a href="#原子化" class="headerlink" title="原子化"></a>原子化</h2><p>原子化是指將事物拆分成最小、最基本的單位，就像原子一樣。這種方法強調把各個元件或功能分解為更細緻、可重複使用的部分，以便在不同的場景下靈活應用。原子化設計理念的出現，為設計師和開發者帶來了新的思考方式，讓他們能更有效率的設計與開發。</p><h2 id="關於原子化-CSS"><a href="#關於原子化-CSS" class="headerlink" title="關於原子化 CSS"></a>關於原子化 CSS</h2><p>單論原子化設計本身是一個概念，這個概念適用於很多事物上，而原子化 CSS 是基於原子化設計概念而提出的一種 CSS 編寫方法，它傾向於小巧且用途單一的 class，並且會以視覺效果進行命名。</p><h2 id="撰寫風格與命名規範可能衍生的問題"><a href="#撰寫風格與命名規範可能衍生的問題" class="headerlink" title="撰寫風格與命名規範可能衍生的問題"></a>撰寫風格與命名規範可能衍生的問題</h2><p>OOCSS、SMACSS、BEM、ITCSS 等這些撰寫風格和命名規範在網頁開發領域相當常見。其主要目的是通過組件名稱或狀態描述 class，並給予多個 CSS 屬性配置，以提高可維護性和重用性。然而，在實際應用中，這些方法可能會遇到一些挑戰。<br><br>隨著專案需求不斷變化，原有的配置可能會與新需求產生衝突。在這種情況下，開發者往往需要新增具有更高權重的 class 來進行擴充或調整。當需求不斷迭代，衝突愈來愈多時，維護 class 變得越來越困難。<br><br>另一方面，我們總是要為一個新的 class 命名，也許是表達元件狀態，抑或是元件中的某個小裝飾，都需要賦予有意義的名稱，但這其中也不乏命名過長的問題發生。團隊就需要不斷地維護命名規範，當規範逐漸失控，不同的團隊成員命名差異也可能越來越大。最終導致不可避免的災難發生。<br><br>為了避免重複的樣式，我們通常會將 CSS 檔案拆分，提供所謂的“通用樣式”給團隊成員方便引入和調整。然而在多個產品同時開發的情況下，很容易出現重複的配置但命名卻不同的情況。這將導致維護規範變得更加困難，並增加防止樣式重複的工作量。在這種情況下，CSS 維護可能變得相當棘手。<br><br>因此原子化 CSS 應運而生，它提供了一種全新的思路來解決這些問題。原子化 CSS 的核心概念是將樣式拆分成小巧且用途單一的 class，以便更容易管理和維護。</p><blockquote><p>原則是：class 按照單一功能命名。</p></blockquote><p>相較於 OOCSS、SMACSS、BEM、ITCSS 等方法，原子化 CSS 的優勢在於它將樣式抽象成獨立的、可重用的原子，這有助於減少樣式衝突和命名問題。此外，原子化 CSS 有助於團隊成員遵循一致的命名規範，避免因不同命名而造成的混亂。<br></p><p>以下是一些原子化 CSS 的範例：</p><pre><code class="css">/* 文字對齊相關 */.text-left &#123;  text-align: left;&#125;.text-center &#123;  text-align: center;&#125;/* 文字大小相關 */.text-sm &#123;  font-size: 0.875rem;&#125;.text-base &#123;  font-size: 1rem;&#125;.text-lg &#123;  font-size: 1.125rem;&#125;/* 顏色相關 */.text-black &#123;  color: #000;&#125;.border-green &#123;  border-color: #9ca3af;&#125;.bg-gray &#123;  background-color: #9ca3af;&#125;/* 位置與邊距相關 */.top-0 &#123;  top: 0;&#125;.left-0 &#123;  left: 0;&#125;.mt-0 &#123;  margin-top: 0;&#125;.mb-2 &#123;  margin-bottom: 2rem;&#125;</code></pre><p>透過上面的範例可以看到原子化 CSS 的簡單且易於理解的特點。開發者很輕鬆的將這些原子 class 組合在一起以實現各種需求。而且原子化 CSS 的組件化設計，未來的擴展和維護工作也將變得更加容易。<br><br>原子化 CSS 通過將樣式拆分成小巧且用途單一的 class，為前端開發帶來了一種新的思路。雖然它可能無法完全取代傳統的 OOCSS、SMACSS、BEM、ITCSS 等方法，但它確實為解決這些方法中存在的問題提供了一種有效的替代方案。<br></p><h2 id="原子化-CSS-框架"><a href="#原子化-CSS-框架" class="headerlink" title="原子化 CSS 框架"></a>原子化 CSS 框架</h2><ul><li><a href="https://tailwindcss.com/">Tailwind CSS</a> - Tailwind 是一個功能強大且高度可定制的原子化 CSS 框架。它提供了大量的實用工具類，可以快速的建立 RWD 的網頁。與其他 CSS 框架不同，Tailwind 不強制任何特定的 UI 設計，從而使開發者能夠更靈活創建自己的風格。</li><li><a href="https://tachyons.io/">Tachyons</a> - Tachyons 是一個輕量級的、功能驅動的 CSS 框架，它遵循原子化設計方法。這個框架提供了一組可組合的 CSS 類，讓開發者可以快速地創建獨特且一致的 UI。Tachyons 的目標是提高開發速度、降低 CSS 複雜性並減少維護負擔。</li><li><a href="https://acss.io/">Atomic CSS</a> - Atomic CSS 是另一個基於原子化設計的框架，其核心思想是將樣式分解為最小的可重用部分。它提供了一組規則，可將 HTML 中的元素與 CSS 中的單一功能類相關聯。這種方法有助於減少 CSS 的規模，提高樣式重用性並降低維護成本。</li><li><a href="https://css.master.co/">Master CSS</a> - 比起前面提到的原子化 CSS 框架，MasterCSS 是一種具增強語法的虛擬 CSS 語言。提供虛擬 CSS 引擎自動的生成與智慧的排序規則，著重於體驗導向的設計，提供非常豐富的功能，同時也提供持續完善的開發工具帶來舒適的開發體驗。開發者完全可以不用寫任何 CSS 檔案，只需要在元件 HTML 的 class 中加入 MasterCSS 的語法即可。</li></ul><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><ul><li><a href="https://tailwindcss.com/">Tailwind CSS</a></li><li><a href="https://tachyons.io/">Tachyons</a></li><li><a href="https://acss.io/">Atomic CSS</a></li><li><a href="https://css.master.co/">Master CSS</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> CSS </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> css </tag>
            
            <tag> atomic-css </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>從 TravisCI 轉移到 GitHub Action</title>
      <link href="/2023/04/18/travis-ci-to-github-action/"/>
      <url>/2023/04/18/travis-ci-to-github-action/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/travis-ci-to-github-action/travis-ci-to-github-actions.png" alt="TravisCI to Github Actions"></p><h2 id="TravisCI-沒有免費的方案了"><a href="#TravisCI-沒有免費的方案了" class="headerlink" title="TravisCI 沒有免費的方案了"></a>TravisCI 沒有免費的方案了</h2><p><a href="/2023/04/17/hexo-asset-convert-markdown/">上一篇</a>提到整理完 Hexo 的部落格後，就開始整理自動化佈署。原本是使用 TravisCI 來做自動化的部署，跳過去看才發現 TravisCI 有要收費了，而 Github 有 Action 可以直接使用，所以就改用 Github Action 來做自動化的部署。只是需要再新增一個設定檔即可。</p><!-- 展示 TravisCI yml 配置 --><p>佈署的操作主要有幾個步驟：</p><ol><li>安裝 Hexo CLI</li><li>執行 <code>npm insall</code> 安裝相依套件</li><li>使用 <code>hexo generate</code> 產生靜態檔案</li><li>設定 git 使用者資訊與 token</li><li>使用 <code>hexo deploy</code> 佈署到 Github Pages</li></ol><h2 id="TravisCI-yml-配置"><a href="#TravisCI-yml-配置" class="headerlink" title="TravisCI yml 配置"></a>TravisCI yml 配置</h2><p>原本的 TravisCI 的配置檔案是這樣的：</p><pre><code class="yml">os: linuxlanguage: node_jsnode_js:  - &#39;19.6.0&#39;dist: trustybranches:  only:    - sourcebefore_install:  - export TZ=Asia/Taipei  - yarn global add hexo-cli  - yarn global add hexo-deployer-gitinstall:  - yarn installscript:  - hexo clean  - hexo generateafter_success:  - git config --global user.name &#39;John Doe&#39;  - git config --global user.email &#39;foo@bar.com&#39;  - sed -i&#39;&#39; &quot;/^ *repo/s~github\.com~$&#123;GITHUB_TOKEN&#125;@github.com~&quot; _config.yml  - hexo deploycache:  directories:    - node_modules</code></pre><h2 id="Github-Action-yml-配置"><a href="#Github-Action-yml-配置" class="headerlink" title="Github Action yml 配置"></a>Github Action yml 配置</h2><p>參考了 Github 的說明文件，新增一個 <code>.github/workflows</code> 資料夾，加入 <code>deploy.yml</code> 的檔案，內容如下：</p><pre><code class="yml">name: Hexo Deployon:  push:    branches:      - sourcejobs:  build-and-deploy:    runs-on: ubuntu-latest    steps:      - name: Checkout repository        uses: actions/checkout@v2      - name: Set up Node.js        uses: actions/setup-node@v2        with:          node-version: &#39;19.6.0&#39;      - name: Set timezone        run: sudo timedatectl set-timezone Asia/Taipei      - name: Install dependencies        run: |          yarn global add hexo-cli          yarn global add hexo-deployer-git          yarn install      - name: Build and deploy        run: |          hexo clean          hexo generate          git config --global user.name &#39;John Doe&#39;          git config --global user.email &#39;foo@bar.com&#39;          sed -i &quot;/^ *repo/s~github\.com~$&#123;&#123; secrets.HEXO_DEPLOY &#125;&#125;@github.com~&quot; _config.yml          hexo deploy</code></pre><h2 id="設定-DEPLOY-TOKEN"><a href="#設定-DEPLOY-TOKEN" class="headerlink" title="設定 DEPLOY_TOKEN"></a>設定 DEPLOY_TOKEN</h2><p>感謝 <a href="https://jiaming0708.github.io/">Jimmy Ho 大大</a> 的補充:<br>如果你的 build 和 source 是在同一個 repo 的話，可以直接略過這個步驟，直接在上方的範例中，將 <code>$&#123;&#123; secrets.HEXO_DEPLOY &#125;&#125;</code> 改成 <code>$&#123;&#123; secrets.GITHUB_TOKEN &#125;&#125;</code> 即可。<br>配置完成之後，我們還需要在 Github 的專案設定中，新增一個 <code>HEXO_DEPLOY</code> 的 secret，內容是我們的 Github token。這樣就可以在 Github Action 中使用了。<br>新增 Github Token 的方式:</p><ol><li>點選右上角的個人頭像</li><li>點選 <code>Settings</code></li><li>點選 <code>Developer settings</code></li><li>左側欄點擊 <code>Personal access tokens</code> 展開選項</li><li>選擇 Tokens(classic)，右邊的內容會看到 <code>Generate new token</code> 按鈕，點擊後選擇 <code>Generate new token (classic)</code></li><li>輸入 token 名稱，選擇 <code>repo</code> 與 <code>workflow</code> 的權限，按照需求選擇有效日期，最後點擊 <code>Generate token</code></li><li>回到 repo，進入 <code>Settings</code>，左側欄點擊 <code>Secrets and variables</code> 展開選項，再選擇 <code>Actions</code></li><li>點擊 <code>New repository secret</code>，輸入 <code>HEXO_DEPLOY</code>，複製剛剛產生的 token，貼到 <code>Value</code> 欄位，最後點擊 <code>Add secret</code></li><li>觸發一下 <code>source</code> 分支的 push，稍微等一下就可以看到 Github Action 的執行結果了</li></ol><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><ul><li><a href="https://docs.github.com/en/actions">GitHub Actions</a></li><li><a href="https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow">GitHub Automatic token authentication</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> CI/CD </category>
          
          <category> GitHub </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> github </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>寫個 script 把 hexo asset 語法轉換成 markdown</title>
      <link href="/2023/04/17/hexo-asset-convert-markdown/"/>
      <url>/2023/04/17/hexo-asset-convert-markdown/</url>
      
        <content type="html"><![CDATA[<h2 id="部落格改版"><a href="#部落格改版" class="headerlink" title="部落格改版"></a>部落格改版</h2><p>好一陣子沒有更新部落格了，之前的工作都主要是內部分享，大部分的筆記也都寫在內部的 wiki 上。最近看了一下 Lighthouse 的分數，發現分數頗低，一開始想直接分析列出的問題逐一解決掉，但感覺沒有什麼效率，雖然可以練習，但懶惰的我還是直接換一個 Theme 吧。</p><p>這次選了一個 <a href="https://github.com/Haojen/hexo-theme-Claudia">hexo-theme-Claudia</a> 的佈景主題，如同目前正在看的畫面，風格還滿簡潔的，有興趣的話可以去看看。</p><h2 id="關於圖片標記問題"><a href="#關於圖片標記問題" class="headerlink" title="關於圖片標記問題"></a>關於圖片標記問題</h2><p>Hexo 支援了 asset_img 語法來插入圖片，但我個人還是偏好使用 Markdown 的語法。因此，我考慮將 Hexo 內建的圖片插入語法轉換成 Markdown 語法。畢竟在未來若要更換主題時，大多數主題都使用 Markdown 語法來插入圖片。雖然繼續使用 Hexo 內建的語法也能正常運作，但隨著文章越來越多的，在管理上可能會變得越來越不方便。</p><p>Hexo 內部支援的標記功能是長這個樣子:</p><pre><code>&#123;% asset_img [title] [path] [width] [height] [link] %&#125;</code></pre><p>但大部分的 Theme 都以 Markdown 的方式呈現:</p><pre><code>![title](path)</code></pre><p>另外圖片存放的位置預設是在 <code>_posts</code> 底下，會產生跟文章檔案名稱相同的資料夾，我覺得隨著文章越來越多，會越來越難管理，所以我把圖片移動到 <code>source/images</code> 底下，並且把圖片的路徑改成 <code>images/文章檔名/圖片檔名</code>。</p><p>手動逐一改的話就要花很多時間在這上面，所以直接寫個腳本來快速轉換吧。</p><h2 id="轉換-script"><a href="#轉換-script" class="headerlink" title="轉換 script"></a>轉換 script</h2><p>轉換的邏輯主要是透過正規表達式來做，主要的步驟有:</p><ol><li>指定要轉換的資料夾</li><li>找出所有的 Markdown 檔案</li><li>逐一讀取檔案內容</li><li>透過正規表達式來找出 Hexo 內建的標記語法</li><li>如果已經有存在的 Markdown 語法，就只改圖片的路徑</li><li>將找到的內容轉換成 Markdown 的語法</li><li>將轉換後的內容寫回檔案</li></ol><p>基於上面的流程就寫了一個 script 做轉換:</p><pre><code class="js">const fs = require(&#39;fs-extra&#39;);const path = require(&#39;path&#39;);const fg = require(&#39;fast-glob&#39;);const postsPath = &#39;source/_posts&#39;; // 要轉換的 md 文件所在的目錄(async () =&gt; &#123;  try &#123;    const files = await fg(`$&#123;postsPath&#125;/**/*.md`);    files.forEach(async (file) =&gt; &#123;      try &#123;        const fileContent = await fs.readFile(file, &#39;utf8&#39;);        const dirname = path.dirname(file);        const basename = path.basename(file, &#39;.md&#39;);        const assetImgRegex = /&#123;%\s*asset_img\s+(.*?)\s+(.*?)\s*%&#125;/g;        const mdImgRegex = /!\[(.*?)\]\((.+?)\)/g;        const convertAssetImg = (match, filename, description) =&gt; &#123;          return `![$&#123;description&#125;](images/$&#123;basename&#125;/$&#123;filename&#125;)`;        &#125;;        const convertMdImg = (match, description, filename) =&gt; &#123;          if (!filename.startsWith(&#39;images/&#39;)) &#123;            return `![$&#123;description&#125;](images/$&#123;basename&#125;/$&#123;filename&#125;)`;          &#125; else &#123;            return match;          &#125;        &#125;;        const newFileContent = fileContent          .replace(assetImgRegex, convertAssetImg)          .replace(mdImgRegex, convertMdImg);        await fs.writeFile(file, newFileContent, &#39;utf8&#39;);        console.log(`成功轉換：$&#123;file&#125;`);      &#125; catch (error) &#123;        console.error(`處理文件 $&#123;file&#125; 時出錯：`, error);      &#125;    &#125;);  &#125; catch (error) &#123;    console.error(&#39;讀取文件列表失敗：&#39;, error);  &#125;&#125;)();</code></pre><h2 id="將轉換後的檔案確認及整理"><a href="#將轉換後的檔案確認及整理" class="headerlink" title="將轉換後的檔案確認及整理"></a>將轉換後的檔案確認及整理</h2><p>轉換完成之後，我是直接用 Git 來確認被修改的部分，發現了幾個問題:</p><ol><li>圖片如果是外部網址<br>早期文章是直接找圖床然後帶入圖片網址，所以初步轉換之後會變成像這樣:</li></ol><pre><code>![title](images/文章檔名/https://example.com/image.png)</code></pre><p>還好這些問題是早期用 logdown 寫的文章，所以沒有太多的圖片需要處理，隨手改一下即可。</p><ol start="2"><li>Hexo 的標記語法有多餘的參數<br>內建的標記語法可以指定圖片的寬高，或是圖片的文字描述，但 MD 語法只有單純的 title，所以轉換之後就會變成像這樣:</li></ol><pre><code>![900 &quot;&#39;title&#39;&quot; &quot;&#39;description&#39;&quot;](images/文章檔名/image.png)</code></pre><p>不過受影響的圖片也沒有太多，所以也是隨手改一下即可。真的很多的時候就要根據上面的 script 進一步修改了。</p><h2 id="換主題後的效果"><a href="#換主題後的效果" class="headerlink" title="換主題後的效果"></a>換主題後的效果</h2><p>最後改完重新跑一次 LightHouse:<br><img src="/images/hexo-asset-convert-markdown/lighthouse-score.png" alt="更新之後的分數"><br>分數相當的不錯，不過要到滿分的話還有一些細節問題需要調整，這後面有時間再處理了。</p><p>另外太久沒看 CI，發現 TravisCI 沒有免費的服務了，所以又花了一點時間把 CI 轉移到 Github Action 上面，這部分之後再寫<a href="/2023/04/18/travis-ci-to-github-action">另外一篇轉換的過程</a>。</p><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><ul><li><a href="https://github.com/Haojen/hexo-theme-Claudia">Hexo Theme Claudia</a></li><li><a href="https://hexo.io/zh-tw/docs/asset-folders.html">Hexo Asset Folders</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Hexo </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Note </tag>
            
            <tag> convert </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>TypeScript intro and migrating</title>
      <link href="/2019/05/29/TypeScript%20intro%20and%20migrating/"/>
      <url>/2019/05/29/TypeScript%20intro%20and%20migrating/</url>
      
        <content type="html"><![CDATA[<h2 id="TypeScript-intro-and-migrating"><a href="#TypeScript-intro-and-migrating" class="headerlink" title="TypeScript intro and migrating"></a>TypeScript intro and migrating</h2><h3 id="Background"><a href="#Background" class="headerlink" title="Background"></a>Background</h3><p>It’s not easy to build a great project that is easy to maintain. Especially when you are in a large company, you have to work with other members. There are many different opinions and ideas even for the simplest of things. Fortunately we have a lot of talent members in RingCentral. We maintain a high quality in our libraries, widgets and products which we build. But, as the project or requirements increase, more and more issue appear. It’s time to prepare our project for facing huge projects in the future with innovations.</p><h3 id="Current-problems"><a href="#Current-problems" class="headerlink" title="Current problems"></a>Current problems</h3><ol><li>Project scaling<br>As described above, more and more source code have been pushed into the projects. There will be a day when our projects grow to enormous sizes. How to make our source code easy to maintain and read, that is the challenge we would have to overcome.</li></ol><span id="more"></span><ol start="2"><li><p>Refactoring<br>What are the common procedures of refactoring?</p><ol><li>Bulk rename functions or property with meaningful names.</li><li>Check the reference counts of functions and properties, and remove if they are unused.</li><li>Extract common logic from functions.</li></ol></li><li><p>Build a great library that is flexible and maintainable.<br>Since we also provide our library as open source project for 3rd-party use, the importance of maintaining and scaling the project is much higher than before. TypeScript can make this easier.</p></li><li><p>How to reduce the work of moving from Javascript to TypeScript?<br>Apart from the efforts in learning TypeScirpt, we also have to consider how we can maintain our product development velocity.</p></li></ol><h3 id="TypeScript"><a href="#TypeScript" class="headerlink" title="TypeScript"></a>TypeScript</h3><p>“Static types can make it easier to maintain your code by catching bugs early on, making it easier to navigate your projects, giving accurate code completion, and providing handy fixes for when you do make mistakes”, said Microsoft’s Daniel Rosenwasser in an introductory <a href="https://blogs.msdn.microsoft.com/typescript/2017/08/31/announcing-typescript-2-5/">blog post</a>.</p><p>Microsoft designed TypeScript with specific architectural parameters in mind allow TypeScript to integrate fully and easily with existing JavaScript code while providing robust feature external to JavaScript. Any valid JavaScript code is valid TypeScript code with only a few exceptions: handing option function parameters and assigning a value to an object literal.</p><p>Let’s take a look at how to install TypeScript:</p><pre><code class="bash">npm install typescriptyarn add typescript</code></pre><p>If you want to install at global instead of local repository, just add <code>global</code> and <code>-g</code> argument.</p><p>After Installed, we can refer the <a href="https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html">tutorial</a> from TypeScript document and practice.</p><p>By the tutorial, we can know that advantage of using TypeScript. Static typing is a feature that detects bugs as developers write the scripts. This allows us to write more robust code and maintain it, resulting in better and clean code. Static language helps you implementing SOLID design patterns into a language that doesn’t really support it. Innovation and change, also, with safety measures to ensure that it doesn’t go completely in the wrong direction. Types make the code more readable. It helps us remember faster what each piece of code is supposed to do. We can add and change the current code faster. With these benefits which using TypeScript, it will more confident for large scaling projects and have a better experience of co-working, then increase the ability of powerful production efficiently.</p><h3 id="Migrating"><a href="#Migrating" class="headerlink" title="Migrating"></a>Migrating</h3><p>To migrating with current repositories, we need a smooth progress of migration from ES6 babel. Here are 2 ways I found for smooth migration:</p><ol><li><p>Using <a href="https://github.com/wmonk/create-react-app">react-app-script-ts</a></p><p>If you want to start without configurating the build setup, this CLI tool is a good choice for you. Just install the CLI tool with NPM, then you can use the command provided by the CLI tool easily. The tool will setup webpack, babel-loader, and ts-loader behind the scenes, and the actual configuration can be found in the node_modules folders. In our scenario, we need to set the configuration by ourselves. We can refer the configuration to know how to config the loaders for our webpack projects. </p></li><li><p>Using <a href="https://babeljs.io/docs/en/babel-preset-typescript">babel-preset-typescript</a></p><p>As our current projects use webpack and gulp for automatic processes, using babel-preset-typescript make it possible for JS files and TS files to co-exists and compile in one step.</p></li></ol><p>Although these solutions can fully meet our requirements, we still have an issue to resolve - the monorepo that we transferred to recently. Before we can use this setup, we need to upgrade babel to babel v7. However, babel v7 is incompatible with our monorepo setup, in particular, referencing modules from subrepos will fail to use the proper babel configuration from the monorepo. We are still trying to figure out the solution to this problem, and we believe that solving this problem will enable us to use typescript, which is beneficial for our future development with large projects.</p><h3 id="Conclusion"><a href="#Conclusion" class="headerlink" title="Conclusion"></a>Conclusion</h3><ol><li>TS and JS can work together.</li><li>TS is widely used for large projects in the industry.</li><li>TS is solid community and developer support.</li><li>Updating to Babel v7 is the first issue we need to solve.</li></ol><h3 id="References"><a href="#References" class="headerlink" title="References"></a>References</h3><ol><li><a href="https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html">TypeScript in 5 minutes</a></li><li><a href="https://apiumhub.com/tech-blog-barcelona/top-typescript-advantages/">Top TypeScript Advantages</a></li><li><a href="https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4">Migrating a Babel project to TypeScript</a></li><li><a href="https://toddmotto.com/typescript-introduction">Introduction to TypeScript</a></li><li><a href="https://juejin.im/entry/5a52ed336fb9a01cbd586f9f">TypeScript vs JavaScript deep comparison</a></li></ol>]]></content>
      
      
      <categories>
          
          <category> TypeScript </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>Capacitor - The Native Bridge for Cross-Platform Web Apps</title>
      <link href="/2018/12/03/capacitor-intro/"/>
      <url>/2018/12/03/capacitor-intro/</url>
      
        <content type="html"><![CDATA[<p><img src="/images/capacitor-intro/capacitor-logo.jpg"></p><h2 id="Hybrid-App"><a href="#Hybrid-App" class="headerlink" title="Hybrid App"></a>Hybrid App</h2><p>談到 <code>Hybrid App</code> 你會想到什麼呢？大部分的人都一定會想到 Phonegap 或是 Cordova 吧，這些框架讓我們可以將 Web 封裝成 App 的形式，並且能夠在行動裝置的作業系統上運作，例如 Android, iOS 等主流的行動平台。並且讓我們透過各種原生的 plugin 的方式，以一份原始碼能夠在不同平台上執行的目的，提供開發者更有效率且容易維護的一套解決方案。而 Capacitor 呢？</p><h2 id="Native-Progressive-Web-Apps"><a href="#Native-Progressive-Web-Apps" class="headerlink" title="Native Progressive Web Apps"></a>Native Progressive Web Apps</h2><p>Capacitor 的靈感來自其他熱門的跨平台工具例如： <a href="http://facebook.github.io/react-native/">React Native</a> 以及 <a href="https://github.com/turbolinks/turbolinks">Turbolinks</a> ， 並繼承 <a href="https://cordova.apache.org/">Apache Cordova</a> 和 <a href="https://phonegap.com/">Adobe PhoneGap</a> 的精神，完全專注於使現代的網站應用能很簡單的在目前主流的平台上執行。同時也向後兼容許多現有的 <a href="https://cordova.apache.org/plugins/">Cordova plugins</a>。要入門 Capacitor 其實是相當簡單，馬上就來試試看吧。</p><span id="more"></span><h2 id="Installing-Capacitor"><a href="#Installing-Capacitor" class="headerlink" title="Installing Capacitor"></a>Installing Capacitor</h2><p>開始的方式有兩種，直接在現有的前端專案下加入 Capacitor，或是直接建立一個全新的專案。Capacitor 主要是設計成在現有的專案下生成，如果想要以全新的專案開始，也會提供簡單的初始專案架構。Capacitor 提供了一個原生行動平台的 runtime 以及可在網頁應用呼叫的 API。但沒有提供像是遊戲開發所需的特定 UI 控制元件。官方強烈建議使用行動平台的前端框架 ( 例如 <a href="https://beta.ionicframework.com/docs/">ionic</a> ) 來作為初始化專案，儘管全新初始化的專案有提供完全空白且沒有前端 UI 框架的應用，但以 ionic 建立的起始專案就可以建置生產就緒的 Native App 以及漸進式網站應用 ( PWA ) 。</p><h3 id="確認所需的相依套件是否有安裝"><a href="#確認所需的相依套件是否有安裝" class="headerlink" title="確認所需的相依套件是否有安裝"></a>確認所需的相依套件是否有安裝</h3><p>由於跨平台的原因，所需要的相依套件或環境主要視我們鎖定要支援的平台情況而定，基本所需的就是 <a href="https://nodejs.org/">Node v8.6.0</a> 以上，NPM 5.6.0 以上 ( 一般安裝 node 之後就會一起安裝了 )。至於 yarn 的部分，目前官方並沒有正式支援使用 yarn 進行安裝，也尚未針對 yarn 提供修復或開放提交相關問題的支援，因此建議還是先使用 node &amp; npm 來進行安裝。至於要執行在哪些平台，以及其相依的準備，整理在下方：</p><h4 id="iOS-開發"><a href="#iOS-開發" class="headerlink" title="iOS 開發"></a>iOS 開發</h4><p>需要 MacOS 以及 Xcode 9 以上。如果你只有 Windows，可以利用 <a href="http://ionicframework.com/pro">Ionic Pro</a> 建置 iOS 應用。此外還需要安裝 <a href="https://cocoapods.org/">CocoaPods</a> 以及 <strong>Xcode Command Line tools</strong></p><p>安裝 CocoaPods：</p><pre><code class="bash">sudo gem install cocoapods</code></pre><p>安裝 <strong>Xcode Command Line tools</strong> 除了直接安裝 Xcode 就有內建之外，也可以利用指令安裝：</p><pre><code class="bash">xcode-select --install</code></pre><p>CocoaPods 安裝完成之後，為了確保相依的版本是最新版的，我們需要定期的執行更新的指令：</p><pre><code class="bash">pod repo update</code></pre><p>通常 Capacitor 支援的 iOS 版本為最後的兩個版本，例如 iOS 10 &amp; iOS 11，未來如果要支援舊的版本，就需要安裝舊版的 Capacitor ( 如果可用的話 )。</p><h4 id="Android-開發"><a href="#Android-開發" class="headerlink" title="Android 開發"></a>Android 開發</h4><p>首先要安裝 <strong>Java 8 JDK</strong> 並設定為預設，如果已經有安裝其他版本的話，須留意。至於 Java 9 目前還不能正常運作。此外還需要安裝 <a href="https://developer.android.com/studio/index.html">Android Studio</a> 的 Android SDK，技術面來說，Android Studio 不是必須的安裝項目，因為也能透過 Android CLI 的方式進行，但為了使建置與執行應用更簡單，官方強烈建議使用 Android Studio。</p><p>Capacitor 在 Android 的版本支援上比 iOS 稍微複雜了些，目前鎖定的 API level 為 21 以上，相當於支援 Android 5.0 ( Lollipop ) 以上。在 2018 年一月時，統計的 Android 版本中，5.0 以上的使用者超過 75%，而且這個成長幅度相當快，因此官方認為當 Capacitor 可以準備推出正式版的時候，這個百分比會變得更高。同時，Capacitor 需要的 Android Webview 版本至少為 Chrome 50 以上。</p><h4 id="Electron-開發"><a href="#Electron-開發" class="headerlink" title="Electron 開發"></a>Electron 開發</h4><p>使用 Electron 開發並沒有特定相依需要安裝。</p><h3 id="在現有的-Web-專案下加入-Capacitor"><a href="#在現有的-Web-專案下加入-Capacitor" class="headerlink" title="在現有的 Web 專案下加入 Capacitor"></a>在現有的 Web 專案下加入 Capacitor</h3><p>由於 Capacitor 是設計成能夠直接在現有的 JS Web 專案中加入，因此要加入 Capacitor，我們必須先進入現有的 Web 應用專案，並安裝所需的套件。</p><pre><code class="bash">cd my-appnpm install --save @capacitor/core @capacitor/cli</code></pre><p>進入現有的 Web 應用專案目錄並安裝完成後，執行初始化指令：</p><pre><code class="bash">npx cap init</code></pre><p>這個指令會提示輸入 App 的資訊例如，App 名稱、要使用在 Android 平台的 App ID 以及要產生的目錄名稱。輸入完之後即完成初始化。</p><h3 id="使用-Capacitor-Starter-搭配-Ionic-Framework"><a href="#使用-Capacitor-Starter-搭配-Ionic-Framework" class="headerlink" title="使用 Capacitor Starter 搭配 Ionic Framework"></a>使用 Capacitor Starter 搭配 Ionic Framework</h3><p>未來即將整合至 ionic CLI，目前先以 <code>ionic start</code> 產生新的專案，初始化之後依照上方的初始化流程加入 Capacitor 專案。新增後可以接著在 ionic 專案目錄下執行建置 <code>ionic build</code>，建置完成後進入新增的 capacitor 專案目錄中。</p><h4 id="Android"><a href="#Android" class="headerlink" title="Android"></a>Android</h4><p>首先要加入 Android 平台到 capacitor 目錄：</p><pre><code class="bash">npx cap add android</code></pre><p>接著進行同步，同步的內容主要為將外部的 dist 檔案內容複製到 <code>www</code> 目錄下，並檢查有無新的原生套件。</p><pre><code class="bash">npx cap sync</code></pre><p>我們也可以只更新建置好的 web 內容：</p><pre><code class="bash">npx cap copy</code></pre><p>若沒有新的原生相依套件需要更新，使用 <code>copy</code> 可以加快更新的速度。接著打開 Android Studio 並進行建置：</p><pre><code class="bash">npx cap open android</code></pre><h4 id="iOS"><a href="#iOS" class="headerlink" title="iOS"></a>iOS</h4><p>和上方的順序一樣，只需要將 <code>android</code> 的部分改成 <code>ios</code> 即可。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>透過以上的介紹，來初步了解 Capacitor 的初始化以及建置的流程，之後再找時間整理各平台可能較容易遇到的錯誤問題。</p><p>Reference</p><p><a href="https://capacitor.ionicframework.com/">Capacitor</a><br><a href="https://capacitor.ionicframework.com/docs/">Capacitor document</a></p>]]></content>
      
      
      
        <tags>
            
            <tag> capacitor </tag>
            
            <tag> hybrid app </tag>
            
            <tag> ionic 4 </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>[Cordova Week-5] Cordova Plugin Geolocation</title>
      <link href="/2018/06/03/cordova-week-5/"/>
      <url>/2018/06/03/cordova-week-5/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>來到了第五週，這次要介紹的功能也是時常會用到的，衛星定位功能，無論是在生活還是實務中，一定會用到的功能，因此 Cordova 官方也將 <code>cordova-plugin-geolocation</code> 列為核心套件並持續提供維護。套件支援的平台有 Windows, Android 以及 iOS，這次一樣針對 Android &amp; iOS 的部分來做介紹。</p><h2 id="安裝方式"><a href="#安裝方式" class="headerlink" title="安裝方式"></a>安裝方式</h2><p>安裝方式與前面幾篇介紹的一樣，透過 cordova cli 安裝套件：</p><pre><code class="bash">$ cordova plugin add cordova-plugin-geolocation</code></pre><h2 id="初始化"><a href="#初始化" class="headerlink" title="初始化"></a>初始化</h2><p>在安裝並建置完成之後，套件會建立全域的物件 <code>navigator</code> 下的一個 <code>geolocation</code> 屬性，雖然是全域屬性，但與其它套件一樣，要在 <code>deviceready</code> 觸發之後才能開始使用，因此可以透過事件監聽的方式 console.log 物件：</p><pre><code class="javascript">document.addEventListener(&quot;deviceready&quot;, onDeviceReady, false);function onDeviceReady() &#123;    console.log(&quot;navigator.geolocation works well&quot;);&#125;</code></pre><span id="more"></span><h2 id="方法-Method"><a href="#方法-Method" class="headerlink" title="方法 ( Method )"></a>方法 ( Method )</h2><p><code>cordova-plugin-geolocation</code> 提供的方法有以下三個：</p><ul><li>navigator.geolocation.getCurrentPosition</li><li>navigator.geolocation.watchPosition</li><li>navigator.geolocation.clearWatch</li></ul><h3 id="navigator-geolocation-getCurrentPosition"><a href="#navigator-geolocation-getCurrentPosition" class="headerlink" title="navigator.geolocation.getCurrentPosition"></a>navigator.geolocation.getCurrentPosition</h3><p>當成功取得裝置目前的位置資訊時會觸發 <code>geolocationSuccess</code> callback，並帶 <code>Position</code> 物件作為參數，若發生錯誤則會觸發 <code>geolocationError</code> callback 並帶有 <code>PositionError</code> 物件作為參數：</p><pre><code class="javascript">navigator.geolocation.getCurrentPosition(geolocationSuccess,                                         [geolocationError],                                         [geolocationOptions]);</code></pre><ul><li><strong>geolocationSuccess</strong>: 會帶入目前位置的 callback function</li><li><strong>geolocationError</strong>: <em>(Optional)</em> 當錯誤發生時會執行的 callback</li><li><strong>geolocationOptions</strong>: <em>(Optional)</em> 地理位置相關的選項設定</li></ul><p>範例：</p><pre><code class="javascript">// onSuccess Callback    // This method accepts a Position object, which contains the    // current GPS coordinates    //    var onSuccess = function(position) &#123;        alert(&#39;Latitude: &#39;          + position.coords.latitude          + &#39;\n&#39; +              &#39;Longitude: &#39;         + position.coords.longitude         + &#39;\n&#39; +              &#39;Altitude: &#39;          + position.coords.altitude          + &#39;\n&#39; +              &#39;Accuracy: &#39;          + position.coords.accuracy          + &#39;\n&#39; +              &#39;Altitude Accuracy: &#39; + position.coords.altitudeAccuracy  + &#39;\n&#39; +              &#39;Heading: &#39;           + position.coords.heading           + &#39;\n&#39; +              &#39;Speed: &#39;             + position.coords.speed             + &#39;\n&#39; +              &#39;Timestamp: &#39;         + position.timestamp                + &#39;\n&#39;);    &#125;;    // onError Callback receives a PositionError object    //    function onError(error) &#123;        alert(&#39;code: &#39;    + error.code    + &#39;\n&#39; +              &#39;message: &#39; + error.message + &#39;\n&#39;);    &#125;    navigator.geolocation.getCurrentPosition(onSuccess, onError);</code></pre><h4 id="iOS-注意事項"><a href="#iOS-注意事項" class="headerlink" title="iOS 注意事項"></a>iOS 注意事項</h4><p>從 iOS 10 開始，若嘗試存取隱私敏感資料，則必須在 <code>info.plist</code> 提供使用說明，當系統提示使用者是否允許存取時，使用說明就會顯示在權限允許確認的視窗中描述。但如果沒有加入使用說明，App 會在顯示是否允許的視窗之前直接閃退，而且 Apple 也會拒絕沒有提供敏感資料使用說明的 App 上架。</p><p>這個套件加入資料存取使用說明的方式如下：</p><ul><li><code>NSLocationWhenInUseUsageDescription</code> 是描述存取使用者位置的原因。</li></ul><p>要將使用說明加入 <code>info.plist</code> 中，可以在 <code>config.xml</code> 中加入 <code>edit-config</code> 標籤：</p><pre><code class="xml">&lt;edit-config target=&quot;NSLocationWhenInUseUsageDescription&quot; file=&quot;*-Info.plist&quot; mode=&quot;merge&quot;&gt;    &lt;string&gt;需要存取位的說明放在這裡&lt;/string&gt;&lt;/edit-config&gt;</code></pre><h4 id="Android-注意事項"><a href="#Android-注意事項" class="headerlink" title="Android 注意事項"></a>Android 注意事項</h4><p>若 Geolocation service 被關閉，且有設定 <code>timeout</code> 的話，則會觸發 <code>onError</code> callback，若沒有設定 <code>timeout</code> 則不會觸發 callback，因此若要在定位服務被關閉時執行相關動作，則需要留意是否有設定 <code>timeout</code>。</p><h3 id="navigator-geolocation-watchPosition"><a href="#navigator-geolocation-watchPosition" class="headerlink" title="navigator.geolocation.watchPosition"></a>navigator.geolocation.watchPosition</h3><p>當檢測到位置發生變化時，回傳裝置目前的位置。當裝置檢測到新的位置時，則觸發 <code>geolocationSuccess</code> callback 並帶著 <code>Position</code> 物件作為參數執行；若發生錯誤，則觸發 <code>geolocationError</code> callback 並帶著 <code>PositionError</code> 物件作為參數執行。</p><pre><code class="javascript">var watchId = navigator.geolocation.watchPosition(geolocationSuccess,                                                  [geolocationError],                                                  [geolocationOptions]);</code></pre><p>和 <code>getCurrentPosition</code> 相同，可帶入三個參數，個別為：成功取得位置時 (<code>geolocationSuccess</code>)、發生錯誤時 ( <code>geolocationError</code>) 與套件設定物件 (<code>geolocationOptions</code>)。</p><h4 id="回傳值"><a href="#回傳值" class="headerlink" title="回傳值"></a>回傳值</h4><p>這個方法呼叫執行後會回傳一個字串，主要是持續監視位置改變的 <code>watch id</code>，此 <code>id</code> 可用在當我們要停止持續追蹤時呼叫用的，也就是第三個方法 <code>clearWatch</code> 呼叫時作為參數帶入執行。</p><pre><code class="javascript">// onSuccess Callback//   This method accepts a `Position` object, which contains//   the current GPS coordinates//function onSuccess(position) &#123;    var element = document.getElementById(&#39;geolocation&#39;);    element.innerHTML = &#39;Latitude: &#39;  + position.coords.latitude      + &#39;&lt;br /&gt;&#39; +        &#39;Longitude: &#39; + position.coords.longitude     + &#39;&lt;br /&gt;&#39; +        &#39;&lt;hr /&gt;&#39;      + element.innerHTML;&#125;// onError Callback receives a PositionError object//function onError(error) &#123;    alert(&#39;code: &#39;    + error.code    + &#39;\n&#39; +          &#39;message: &#39; + error.message + &#39;\n&#39;);&#125;// Options: throw an error if no update is received every 30 seconds.//var watchID = navigator.geolocation.watchPosition(onSuccess, onError, &#123; timeout: 30000 &#125;);</code></pre><h3 id="navigator-geolocation-clearWatch"><a href="#navigator-geolocation-clearWatch" class="headerlink" title="navigator.geolocation.clearWatch"></a>navigator.geolocation.clearWatch</h3><p>藉由 <code>watchID</code> 參數傳入並呼叫，以停止追蹤裝置的位置變化。其參數是由 <code>watchPosition</code> 呼叫後回傳的值。</p><pre><code class="javascript">navigator.geolocation.clearWatch(watchID);</code></pre><p>範例：</p><pre><code class="javascript">// Options: watch for changes in position, and use the most// accurate position acquisition method available.//var watchID = navigator.geolocation.watchPosition(onSuccess, onError, &#123; enableHighAccuracy: true &#125;);// ...later on...navigator.geolocation.clearWatch(watchID);</code></pre><h2 id="相關物件介紹"><a href="#相關物件介紹" class="headerlink" title="相關物件介紹"></a>相關物件介紹</h2><h3 id="geolocationOptions"><a href="#geolocationOptions" class="headerlink" title="geolocationOptions"></a>geolocationOptions</h3><p>在呼叫 <code>getCurrentPosition</code> 與 <code>watchPosition</code> 兩個方法時，帶入的第三個參數 <code>geolocationOptions</code> 主要有以下幾個屬性可設定：</p><pre><code class="javascript">&#123; maximumAge: 3000, timeout: 5000, enableHighAccuracy: true &#125;;</code></pre><ul><li><strong>enableHighAccuracy</strong>：提供使 App 取得準確度更高的提示，預設的情況，裝置是藉由網路為基礎的方法取得 <code>Position</code>，設定此屬性為 <code>true</code> 以提醒可選用精度更高的方式，例如衛星定位。（Boolean）</li><li><strong>timeout</strong>：允許等待傳入參數並執行 <code>navigator.geolocation.getCurrentPosition</code> 或 <code>navigator.geolocation.watchPosition</code> 中的 <code>geolocationSuccess</code> callback 的最長時間（毫秒），若在設定的時間內未觸發 <code>geolocationSuccess</code> 則會帶入 <code>PositionError.TIMEOUT</code> 的錯誤碼，觸發 <code>geolocationError</code> callback，要注意到若是呼叫 <code>geolocation.watchPosition</code>，只要每次超過設定的時間就會觸發 <code>geolocationError</code>。(Number)</li><li><strong>maximumAge</strong>: 設定位置暫存時間，以毫秒為單位，預設為0，該值為0時，定位時會重新獲取一個新的 <code>Position</code> 物件；若有設定值則會在設定的時間內回傳上一次的暫存 <code>Position</code> 物件，如果超過設定的時間，則重新取得。 (Number)</li></ul><h3 id="Position"><a href="#Position" class="headerlink" title="Position"></a>Position</h3><p>由 <code>geolocation</code> API 所建立的物件，包含了位置 ( Position ) 的座標與時間戳。</p><h4 id="屬性"><a href="#屬性" class="headerlink" title="屬性"></a>屬性</h4><ul><li><strong>coords</strong>: 一組位置的座標資訊。</li><li><strong>timestamp</strong>: 建立座標資訊的時間戳。</li></ul><h3 id="Coordinates"><a href="#Coordinates" class="headerlink" title="Coordinates"></a>Coordinates</h3><p><code>Coordinates</code> 物件包含一組描述位置的地理坐標屬性並存在 <code>Position</code> 物件下，當請求位置的 callback 發生時，會作為參數帶入。</p><h4 id="屬性-1"><a href="#屬性-1" class="headerlink" title="屬性"></a>屬性</h4><ul><li><strong>latitude</strong>: 緯度 <em>(Number)</em></li><li><strong>longitude</strong>: 經度 <em>(Number)</em></li><li><strong>altitude</strong>: 高度 <em>(Number)</em></li><li><strong>accuracy</strong>: 座標經緯度的準確程度，單位為公尺 <em>(Number)</em></li><li><strong>altitudeAccuracy</strong>: 座標高度的準確程度，單位為公尺 <em>(Number)</em></li><li><strong>heading</strong>: 面對行徑的方向，以北為起始點順時針計算的度數 <em>(Number)</em></li><li><strong>speed</strong>: 裝置目前的移動速度，單位為每秒公尺 <em>(Number)</em></li></ul><h4 id="Android-注意事項-1"><a href="#Android-注意事項-1" class="headerlink" title="Android 注意事項"></a>Android 注意事項</h4><p><strong>altitudeAccuracy</strong>: 不支援 Android，會回傳 <code>null</code>.</p><h3 id="PositionError"><a href="#PositionError" class="headerlink" title="PositionError"></a>PositionError</h3><p><code>PositionError</code> 物件會在 navigator.geolocation 發生錯誤時作為參數傳入 <code>geolocationError</code> callback 並觸發。</p><h4 id="屬性-2"><a href="#屬性-2" class="headerlink" title="屬性"></a>屬性</h4><ul><li><strong>code</strong>: 如下列，預先定義好的錯誤代碼</li><li><strong>message</strong>: 描述關於錯誤發生的訊息內容</li></ul><h4 id="常數"><a href="#常數" class="headerlink" title="常數"></a>常數</h4><ul><li><pre><code>PositionError.PERMISSION_DENIED</code></pre><ul><li>當使用者不允許 App 存取座標資訊時會回傳，視平台而定。</li></ul></li><li><pre><code>PositionError.POSITION_UNAVAILABLE</code></pre><ul><li>當裝置無法取得座標時會回傳，一般來說都是未連接網路或沒有啟用定位功能。</li></ul></li><li><pre><code>PositionError.TIMEOUT</code></pre><ul><li>當裝置無法在指定的時間 ( <code>geolocationOptions</code> 中的 <code>timeout</code> ) 內取得座標資訊時回傳，若是透過 <code>navigator.geolocation.watchPosition</code> 方式取得，則在每次設定的 <code>timeout</code> 發生時，都會藉由 <code>geolocationError</code> callback 帶入並觸發。</li></ul></li></ul><h2 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h2><p><a href="https://github.com/apache/cordova-plugin-geolocation">apache&#x2F;cordova-plugin-geolocation</a></p>]]></content>
      
      
      <categories>
          
          <category> Cordova </category>
          
      </categories>
      
      
        <tags>
            
            <tag> cordova plugin </tag>
            
            <tag> geolocation </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>[Cordova Week-4] Cordova File System</title>
      <link href="/2018/05/07/cordova-week-4/"/>
      <url>/2018/05/07/cordova-week-4/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>開發 App 的時候，時常會遇到要處理裝置中的圖片或檔案，一陣子沒有碰了，因此這次就來聊聊 Cordova App 中的 File System！Cordova 針對 File System 提供了核心套件 ( Core Plugin ) - <code>cordova-plugin-file</code>，主要實作了檔案操作相關的 API 使我們能讀寫裝置中的檔案，不同的平台，提供的屬性或方法都不盡相同，我們先從 Android 的部分開始介紹。</p><h2 id="安裝套件"><a href="#安裝套件" class="headerlink" title="安裝套件"></a>安裝套件</h2><p>透過 Cordova CLI 進行安裝：</p><pre><code class="bash">$ cordova plugin add cordova-plugin-file</code></pre><p>在執行時期，若有正確引入 cordova.js，加入 <code>cordova-plugin-file</code> 後，會在全域屬性中找到 cordova.file 物件。所以我們可以在 javascript 的部分加入事件監聽 ( Event Listener )，並 console.log 物件確認是否有成功加入：</p><pre><code class="javascript">document.addEventListener(&quot;deviceready&quot;, onDeviceReady, false);function onDeviceReady() &#123;    console.log(cordova.file);&#125;</code></pre><h2 id="支援的平台"><a href="#支援的平台" class="headerlink" title="支援的平台"></a>支援的平台</h2><p>根據套件 Repo 提供的 <code>README</code>，目前支援的平台如下：</p><ul><li>Android</li><li>iOS</li><li>OS X</li><li>Windows</li><li>Browser</li></ul><p>其中 Ｗindows 平台目前不支援 <code>FileReader.readAsArrayBuffer</code> 以及 <code>FileWriter.write(blob)</code> 的方法。 但這次的介紹主軸在於 Android &amp; iOS，因此這部分有個基本的了解即可。</p><span id="more"></span><h2 id="Entry：DirectoryEntry-amp-FileEntry"><a href="#Entry：DirectoryEntry-amp-FileEntry" class="headerlink" title="Entry：DirectoryEntry &amp; FileEntry"></a>Entry：DirectoryEntry &amp; FileEntry</h2><p>在開始之前，需要先了解一下兩個名詞，主要在進行存取的時候一定會需要使用的入口 ( Entry ) 物件。</p><ul><li>DirectoryEntry：目錄的入口，透過 <code>window.requestFileSystem</code> 或 <code>resolveLocalFileSystemURL</code> 取得。</li><li>FileEntry：檔案入口，透過 <code>directoryEntry.getFile()</code> 取得，若可取得即代表檔案有存在。<ul><li>若檔案存在則能順利取得物件實體，否則會收到錯誤 <code>FileError &#123;code: 1&#125;</code>，即 <code>NOT_FOUND_ERR</code></li></ul></li></ul><h2 id="引用-Types"><a href="#引用-Types" class="headerlink" title="引用 Types"></a>引用 Types</h2><p>由於我們使用 Angular + Cordova 進行 Hybrid App 開發，寫 Angular 習慣使用 <code>TypeScript</code>，負責維護 Cordova 核心套件的團隊也針對套件提供了好用的定義檔，我們只需要引入到 tsconfig.json (tsconfig.app.json) 即可：</p><pre><code class="json">&#123;  &quot;extends&quot;: &quot;../tsconfig.json&quot;,  &quot;compilerOptions&quot;: &#123;    &quot;outDir&quot;: &quot;../out-tsc/app&quot;,    &quot;baseUrl&quot;: &quot;./&quot;,    &quot;module&quot;: &quot;es2015&quot;,    &quot;types&quot;: [      &quot;../hello/plugins/phonegap-plugin-push/types&quot;,      &quot;../hello/plugins/cordova-plugin-device/types&quot;,      &quot;../hello/plugins/cordova-plugin-file/types&quot;    ]  &#125;,  &quot;exclude&quot;: [&quot;test.ts&quot;, &quot;**/*.spec.ts&quot;]&#125;</code></pre><p>範例的 Cordova 專案建立在 angular 專案根目錄下，利用相對路徑，進入 Cordova 專案目錄下的 <code>node_modules</code>，在套件加入的時候， <code>node_module</code> 會同時產生加入的套件，因此可以在這個目錄下看到加入過的套件，底下都會有 <code>types</code> 目錄，而裡面的檔案就是帶給我們更多方便的 types。</p><h2 id="設定套件-可選擇"><a href="#設定套件-可選擇" class="headerlink" title="設定套件 (可選擇)"></a>設定套件 (可選擇)</h2><p>可透過 config.xml 新增標籤設定，限定特定位置開放存取操作，標籤中的 value 可參考上方 file-system layout 的項目列出來並以逗號隔開，代表只有列出的項目有安裝並開放存取。而在預設的情況下所有的 file-system root 都是啟用的。</p><pre><code>&lt;preference name=&quot;iosExtraFilesystems&quot; value=&quot;library,library-nosync,documents,documents-nosync,cache,bundle,root&quot; /&gt;&lt;preference name=&quot;AndroidExtraFilesystems&quot; value=&quot;files,files-external,documents,sdcard,cache,cache-</code></pre><h3 id="Android"><a href="#Android" class="headerlink" title="Android"></a>Android</h3><ul><li><code>files</code>: App 內部的檔案存取目錄</li><li><code>files-external</code>: App 外部檔案存取目錄</li><li><code>sdcard</code>: 全域的外部存取目錄（若有裝的話則是 SD 卡的根目錄），必須先取得 <code>android.permission.WRITE_EXTERNAL_STORAGE</code> 權限才能使用。</li><li><code>cache</code>: App 內部的快取目錄</li><li><code>cache-external</code>: App 外部的快取目錄</li><li><code>assets</code>: App 打包的檔案資料 (唯讀)</li><li><code>root</code>: 整個裝置的 file-system</li></ul><p>Android 也支援一個特殊的 file-system，名叫 <code>documents</code>，這代表是在 <code>files</code> 的 file-system 根目錄下的 <code>Documents</code> 的子目錄名稱。</p><h3 id="iOS"><a href="#iOS" class="headerlink" title="iOS"></a>iOS</h3><ul><li><code>library</code>: App 的 <code>Library</code> 目錄</li><li><code>documents</code>: App 的 <code>Documents</code> 目錄</li><li><code>cache</code>: App 的 <code>Cache</code> 目錄</li><li><code>bundle</code>: App 的 <code>bundle</code> 目錄，是 App 在磁碟中本身的位置 (唯讀)</li><li><code>root</code>: 整個裝置的 file-system</li></ul><p>在預設的情況 <code>library</code> 與 <code>documents</code> 目錄可以同步到 iCloud ，我們也可以要求兩個 file-system，<code>library-nosync</code> 與 <code>documents-nosync</code>，代表這兩個 file-system 中不會同步到 iCloud 的目錄。</p><h2 id="初始化目錄實體-DirectoryEntry-Instance"><a href="#初始化目錄實體-DirectoryEntry-Instance" class="headerlink" title="初始化目錄實體 ( DirectoryEntry Instance )"></a>初始化目錄實體 ( DirectoryEntry Instance )</h2><p>每次操作檔案或目錄時，我們需要透過物件實體進行操作，因此需要先進行初始化以取得物件實體，由於一開始是從 <code>cordova.file.externalDataDirectory</code> 取得，可以確認是 <code>DirectoryEntry</code> 而不是 <code>FileEntry</code>，如下的範例，並嘗試使用 Observable 實作：</p><pre><code class="typescript">initRootDirectoryEntry() &#123;    this.resolveLocalFileSystemURL()      .pipe(map(fs =&gt; (this.rootDirectoryEntry = fs)))      .subscribe();&#125;  private resolveLocalFileSystemURL(): Observable&lt;DirectoryEntry&gt; &#123;    return Observable.create((observer: Observer&lt;DirectoryEntry&gt;) =&gt; &#123;      window.resolveLocalFileSystemURL(        cordova.file.externalDataDirectory,        fs =&gt; &#123;          console.log(`resolved fs`, fs);          this.title = &#39;file system is resolved&#39;;          // this.rootDirectoryEntry = &lt;DirectoryEntry&gt;fs;          observer.next(&lt;DirectoryEntry&gt;fs);        &#125;,        err =&gt; &#123;          console.log(`resolve error`, err);          observer.error(err);        &#125;      );    &#125;);  &#125;</code></pre><p>由於 TypeScript 提供了強型別的概念，這段程式碼直接引用的話，在開發時期，會遇到 <code>cannot find name cordova</code> 的問題，這時候只需要在檔案的最上方新增一行宣告即可使用：</p><pre><code class="typescript">declare const cordova: Cordova;</code></pre><p>至於 cordova.file 有哪些空間可以使用，可參考文件 <a href="https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/#file-system-layouts">File-System-Layouts</a> 的部分，有整理名稱與對應的裝置路徑。</p><h2 id="存取檔案"><a href="#存取檔案" class="headerlink" title="存取檔案"></a>存取檔案</h2><p>存取檔案的方式是利用 <code>Entry</code> 提供的方法 <code>getFile()</code> 取得，若有檔案確實存在則會取得 FileEntry，反之則會收到錯誤訊息，若在 <code>getFile()</code> 加入設定參數 <code>&#123;create: true&#125;</code>，即使沒有檔案存在則一樣會建立檔案。</p><pre><code class="typescript">createFile() &#123;    this.rootDirectoryEntry.getFile(        &#39;test.txt&#39;,        &#123; create: true &#125;, // 若 create 為 flase，當檔案不存在時會發出錯誤。        fileEntry =&gt; &#123;            console.log(&#39;fileEntry is file?&#39; + fileEntry.isFile.toString());            this.writeFile(fileEntry, null);            this.myFileEntry = fileEntry;        &#125;,        error =&gt; console.log(`createFile Error`, error)    );&#125;</code></pre><h2 id="建立檔案"><a href="#建立檔案" class="headerlink" title="建立檔案"></a>建立檔案</h2><p>建立檔案的方式與存取檔案一樣都是透過 <code>getFile</code> 方法進行，取得 <code>FileEntry</code> 後寫入檔案內容，寫入的方式是透過 <code>FileEntry</code> 提供的 <code>createWriter</code> 帶入 Callback Function，並在各個事件例如 <code>onwritteend</code>, <code>onerror</code> 實作對應的處理，最後則呼叫 <code>write()</code> 並帶入 <code>dataObj</code>：</p><pre><code class="typescript"> createFile() &#123;    this.rootDirectoryEntry.getFile(      &#39;test.txt&#39;,      &#123; create: true &#125;,      fileEntry =&gt; &#123;        console.log(&#39;fileEntry is file?&#39; + fileEntry.isFile.toString());        this.writeFile(fileEntry, null);        this.myFileEntry = fileEntry;      &#125;,      error =&gt; console.log(`createFile Error`, error)    );  &#125;  private writeFile(fileEntry: FileEntry, dataObj) &#123;    // Create a FileWriter object for our FileEntry (log.txt).    fileEntry.createWriter(fileWriter =&gt; &#123;      fileWriter.onwriteend = () =&gt; &#123;        console.log(&#39;Successful file write...&#39;);        this.readFile(fileEntry);      &#125;;      fileWriter.onerror = e =&gt; &#123;        console.log(&#39;Failed file write: &#39; + e.toString());      &#125;;      // If data object is not passed in,      // create a new Blob instead.      if (!dataObj) &#123;        dataObj = new Blob([&#39;some file data&#39;], &#123; type: &#39;text/plain&#39; &#125;);      &#125;      fileWriter.write(dataObj);    &#125;);  &#125;</code></pre><h2 id="讀取檔案"><a href="#讀取檔案" class="headerlink" title="讀取檔案"></a>讀取檔案</h2><p>在寫入檔案的範例中，或許有注意到 <code>this.readFile</code> 方法的呼叫，這個是我們要自己實作一個讀取檔案的方法，一樣透過 <code>FileEntry</code> 進行，並取得 <code>file</code> 後 new 一個 <code>FileReader</code>，並註冊事件方法在 <code>onloadend</code>，最後再選用讀取的方法例如 <code>readAsText()</code> 並帶入取得的 <code>file</code> 物件：</p><pre><code class="typescript">private readFile(fileEntry: FileEntry) &#123;    fileEntry.file(        file =&gt; &#123;            const reader = new FileReader();            reader.onloadend = result =&gt; &#123;                console.log(&#39;Successful file read: &#39;, result);                // displayFileData(fileEntry.fullPath + &quot;: &quot; + this.result);            &#125;;            reader.readAsText(file);        &#125;,        readFileError =&gt; console.log(`readFileError`, readFileError)    );&#125;</code></pre><h2 id="刪除檔案"><a href="#刪除檔案" class="headerlink" title="刪除檔案"></a>刪除檔案</h2><p>透過 <code>FileEntry</code> 提供的 <code>remove()</code> 方法即可刪除檔案：</p><pre><code class="typescript">deleteFile() &#123;    this.myFileEntry.remove(        () =&gt; console.log(`remove sucess`),        error =&gt; console.log(`remove error`, error)    );&#125;</code></pre><p>從上述的例子中，有些有用 <code>private</code> 有些則沒有，主要區別提供 UI 呼叫的公開方法及 <code>component</code> 使用的私有方法。</p><h2 id="Android-相關注意事項"><a href="#Android-相關注意事項" class="headerlink" title="Android 相關注意事項"></a>Android 相關注意事項</h2><p>套件的說明文件中其中有一個段落在描述各平台的 <code>Quirks</code>，翻成中文是指『怪癖』，這邊我們就當作有些小奇葩的地方要留意囉。</p><h3 id="Android-持續存取的位置決定"><a href="#Android-持續存取的位置決定" class="headerlink" title="Android 持續存取的位置決定"></a>Android 持續存取的位置決定</h3><p>在 Android 裝置上有許多可以持續儲存的空間，可以參考 <a href="http://developer.android.com/guide/topics/data/data-storage.html">Android 官網文件</a> 延伸討論其可行性。先前的版本套件會在啟動的時候選擇暫存與永久檔案個別的位置，根據裝置是否有宣告安裝了SD卡（或等效的儲存分區），若有安裝 SD 卡，或有較大的內部儲存空間時，則會將檔案存取設定在該空間的根目錄上。換句話說，所有的 Cordova 應用都能看到所有在這張卡上的檔案，若有這樣的疑慮則要多留意了。</p><p>若 SD 卡無法使用時，之前的版本套件會將資料在 <code>/ data / data / &lt;packageId&gt;</code>下存取，這雖然能將各應用隔離，但還是有可能導致在不同的使用者間分享資料。</p><p>現在可以決定是否針對舊版的判斷邏輯來選擇要存取的空間，只需要透過以下兩行的其中一行加入到 Cordova 專案根目錄中的 <code>config.xml</code> 即可：</p><pre><code class="xml">&lt;preference name=&quot;AndroidPersistentFileLocation&quot; value=&quot;Internal&quot; /&gt;&lt;preference name=&quot;AndroidPersistentFileLocation&quot; value=&quot;Compatibility&quot; /&gt;</code></pre><p>若沒有加入上述的其中一行時，預設的行為是 <code>Internal</code>，若有加入標籤但 <code>value</code> 卻不是這兩個的其中一個，則會導致 App 無法啟動，若是專案是早期的版本，並使用 <code>3.0.0</code> 之前版本的套件，而且已經發佈給使用者的話，就要將標籤加入至設定檔，並設定值為 <code>Compatibility</code>。若沒有這樣設定，直接切換到 <code>Internal</code> 的話，使用者更新之後可能會無法存取到先前操作所留下的檔案，這要視使用者的裝置而定。反之若是新的專案，則建議直接使用 <code>Internal</code> 囉。</p><h3 id="遞迴處理-Android-assets-緩慢問題"><a href="#遞迴處理-Android-assets-緩慢問題" class="headerlink" title="遞迴處理 Android_assets 緩慢問題"></a>遞迴處理 Android_assets 緩慢問題</h3><p>若碰到需要處理列出 <code>android_assets</code> 資料夾相關遞迴操作時，會發現執行速度非常緩慢的情況，因此套件的 <code>src/android</code> 目錄下有提供 <code>build-extras.gradle</code> 的檔案，將檔案加至 Cordova platform android 根目錄即可提升速度，但 cordova-android 版本至少要 <code>4.0.0</code> 以上。筆者是還沒遇過這樣的操作需求，有遇過的大大可以分享一下。</p><h3 id="Android-Marshmallow-android-6-0-版本權限問題"><a href="#Android-Marshmallow-android-6-0-版本權限問題" class="headerlink" title="Android Marshmallow (android 6.0) 版本權限問題"></a>Android Marshmallow (android 6.0) 版本權限問題</h3><p>當 Android 6.0，也就是棉花糖的版本中，預設的情況下是擁有 <code>cordova.file.applicationStorageDirectory</code> 以及 <code>cordova.file.externalApplicationStorageDirectory</code> 的讀寫權限的，套件並不需要針對這兩個存取空間去請求存取操作的權限，除非外部儲存空間並沒有安裝，由於系統限制的關係，當沒有安裝外部儲存時，就會跳出 <code>cordova.file.externalApplicationStorageDirectory</code> 空間的存取權限請求。筆者想嘗試還原情境，但試不出來，參考<a href="https://github.com/Microsoft/cordova-plugin-code-push/issues/57">這篇討論文</a>，應該是要實體的裝置執行時才會遇到了。</p><h2 id="錯誤代碼與意義"><a href="#錯誤代碼與意義" class="headerlink" title="錯誤代碼與意義"></a>錯誤代碼與意義</h2><p>當有執行過程產生錯誤時，會丟出下方列表中的錯誤：</p><table><thead><tr><th>Code</th><th>Constant</th></tr></thead><tbody><tr><td>1</td><td><code>NOT_FOUND_ERR</code></td></tr><tr><td>2</td><td><code>SECURITY_ERR</code></td></tr><tr><td>3</td><td><code>ABORT_ERR</code></td></tr><tr><td>4</td><td><code>NOT_READABLE_ERR</code></td></tr><tr><td>5</td><td><code>ENCODING_ERR</code></td></tr><tr><td>6</td><td><code>NO_MODIFICATION_ALLOWED_ERR</code></td></tr><tr><td>7</td><td><code>INVALID_STATE_ERR</code></td></tr><tr><td>8</td><td><code>SYNTAX_ERR</code></td></tr><tr><td>9</td><td><code>INVALID_MODIFICATION_ERR</code></td></tr><tr><td>10</td><td><code>QUOTA_EXCEEDED_ERR</code></td></tr><tr><td>11</td><td><code>TYPE_MISMATCH_ERR</code></td></tr><tr><td>12</td><td><code>PATH_EXISTS_ERR</code></td></tr></tbody></table>]]></content>
      
      
      <categories>
          
          <category> Cordova </category>
          
      </categories>
      
      
        <tags>
            
            <tag> cordova plugin file </tag>
            
            <tag> file </tag>
            
            <tag> Cordova Android </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>升級! 全新進化 Angular 6！</title>
      <link href="/2018/05/05/ng-update/"/>
      <url>/2018/05/05/ng-update/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>Angular 終於發布 6.0 正式版了，當然馬上拿手邊的專案來升級啦！後面也順利升級完成了，<a href="https://forum.angular.tw/t/topic/891">在論壇蓋大樓回報區</a>回報的同時，也在這紀錄一下。</p><h2 id="使用-ng-update-進行更新"><a href="#使用-ng-update-進行更新" class="headerlink" title="使用 ng update 進行更新"></a>使用 ng update 進行更新</h2><p>首先更新了 <code>node_modules</code> 的 <code>@angular/cli</code>：</p><pre><code class="bash">全域：yarn global upgrade @angular/cli@latest專案目錄：yarn upgrade @angular/cli@latest</code></pre><span id="more"></span><p>接著輸入 <code>ng update</code> 進行檢查，ng update 會進行相關 package 分析，並提供建議與指令提示：<br><img src="/images/ng-update/step1.png" alt="ng update 會進行相關 module 的版本分析"></p><p>根據分析結果先來升級 <code>@angular/core</code>：</p><pre><code class="bash">ng update @angular/core</code></pre><p>然後就等了快五分鐘…<br>看來大部分升級第一個會遇到的問題應該都是 typescript，畢竟不是時常會去動這個。<br><img src="/images/ng-update/step2.png" alt="可能遇到的錯誤訊息之一"><br>or<br><img src="/images/ng-update/step3.png" alt="可能遇到的錯誤訊息之二"></p><p>檢查 typescript 版本：</p><pre><code class="bash">$ tsc -v</code></pre><p>升級 typescript：</p><pre><code class="bash">yarn upgrade typescript@2.7</code></pre><p>輸入 angular cli 的升級指令進行確認：</p><pre><code class="bash">ng update</code></pre><p><img src="/images/ng-update/step4.png" alt="升級完成後並檢查版本"></p><p>再輸入一次 <code>ng update</code>：<br><img src="/images/ng-update/step5.png"></p><p>Good work!</p><p>接著最重要的 <code>ng serve</code> 死掉了：<br><img src="/images/ng-update/step6.png"></p><p>原來 6.0 的設定檔名稱已經從原本的 <code>.angular-cli.json</code> 改成 <code>angular.json </code>了，要如何更新呢？一樣透過指令進行，在更新 <code>@angular/cli</code> 的時候會根據舊的設定檔重新建立 <code>angular.json</code>：</p><pre><code class="bash">ng update @angular/cli</code></pre><p><img src="/images/ng-update/step7.png" alt="ng update @angular/cli"></p><p>再來一次！！<br><img src="/images/ng-update/step8.png" alt="重新 ng serve"></p><p><code>localhost:4200</code> 也確認無誤正常執行，以上。</p><p>參考資料：</p><p><a href="https://blog.angular.io/version-6-of-angular-now-available-cc56b0efa7a4">Angular blog : version-6-of-angular-now-available</a></p><p><a href="https://update.angular.io/">Update Angular</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 6 </tag>
            
            <tag> angular/cli </tag>
            
            <tag> ng update </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>[Cordova Week-3] Cordova Push Notification - iOS</title>
      <link href="/2018/04/28/cordova-week-3/"/>
      <url>/2018/04/28/cordova-week-3/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>上一篇我們介紹了如何建立 FCM 並將 API 金鑰設定至 Azure，最後完成訊息推播測試，本篇將繼續說明 iOS 訊息推播要如何設定，主要的步驟有：</p><ol><li>建立 iOS 推播通知憑證</li><li>上傳 p12 與設定 Azure Notification Hub</li><li>進行推播測試</li></ol><h2 id="建立-App-Identity-App-ID"><a href="#建立-App-Identity-App-ID" class="headerlink" title="建立 App Identity (App ID)"></a>建立 App Identity (App ID)</h2><p>iOS 平台需要先進入 Apple Developer 的管理介面建立 <code>AppId</code>，並啟動 <code>Push Notifications</code> 的功能。另外，要準備一台 MacOS 裝置，透過鑰匙圈 ( Keychain ) 工具建立 CSR ( Certificate Signing Request )，將檔案上傳轉換成憑證並下載，點擊加入鑰匙圈後匯出 p12 檔，將 p12 檔上傳至 Azure Notification Hub 的 Apple 設定中。</p><span id="more"></span><p><img src="/images/cordova-week-3/ios-create-app-id-0.png" alt="&#39;點擊 `Certificate, Identifiers &amp; Profiles` 進入管理介面&#39;"></p><p><img src="/images/cordova-week-3/ios-create-app-id-1.png" alt="點選 `App IDs`，並點選右上角 `+` 符號新增 App ID"></p><p><img src="/images/cordova-week-3/ios-create-app-id-2.png" alt="輸入關於此 App 的描述"></p><p><img src="/images/cordova-week-3/ios-create-app-id-3.png" alt="輸入與 cordova 專案的 `config.xml` 相同的 id"></p><p><img src="/images/cordova-week-3/ios-create-app-id-4.png" alt="勾選 `Push Notifications`"></p><p>勾選完成後，點擊下方藍色的 <code>Continue</code> 按鈕繼續下一步：</p><p><img src="/images/cordova-week-3/ios-create-app-id-5.png" alt="確認資料無誤後，點擊 `Register` 建立 App ID"></p><p>完成 APP IDs 新增後，可以看到目前 App 的 <code>Push Notifications</code> 狀態為 <code>Configurable</code>，也就是待設定中，點擊下方的 <code>Edit</code> 進行設定。</p><p><img src="/images/cordova-week-3/ios-create-app-id-7.png" alt="確認 `Push Notifications` 狀態後，點擊 Edit "></p><p>點擊 <code>Edit</code> 按鈕後，可以看到關於此 App 的服務相關設定，將捲軸滾到 <code>Push Notifications</code> 的地方，並點擊 <code>Development SSL Certificate</code> 的 <code>Create Certificate</code> 按鈕建立憑證：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-1.png" alt="點擊開發用的 SSL 憑證建立按鈕"></p><p>由於建立憑證需要上傳 CSR，因此在這之前，需要先透過鑰匙圈工具建立 CSR。</p><h2 id="建立-CSR-Certificate-Signing-Request"><a href="#建立-CSR-Certificate-Signing-Request" class="headerlink" title="建立 CSR ( Certificate Signing Request )"></a>建立 CSR ( Certificate Signing Request )</h2><p>首先在 MacOS 的裝置上開啟鑰匙圈存取 ( Keychain )：</p><p><img src="/images/cordova-week-3/ios-create-csr-1.png" alt="開啟鑰匙圈存取"></p><p>功能選單點擊<code>鑰匙圈存取</code> &#x3D;&gt;<code>憑證輔助程式</code>&#x3D;&gt;<code>從憑證授權要求憑證</code>：</p><p><img src="/images/cordova-week-3/ios-create-csr-2.png" alt="從憑證授權要求憑證"></p><p>電子郵件地址建議輸入真實的位置，由於是自己本機產生的，不需要寄送電子郵件給 CA，因此選擇儲存到磁碟即可。</p><p><img src="/images/cordova-week-3/ios-create-csr-3.png" alt="輸入電子郵件並選擇儲存到磁碟"></p><p><img src="/images/cordova-week-3/ios-create-csr-4.png" alt="選擇要儲存的位置"></p><h2 id="建立-APNS-憑證"><a href="#建立-APNS-憑證" class="headerlink" title="建立 APNS 憑證"></a>建立 APNS 憑證</h2><p>回到 <code>Create Certificate</code> 之後的頁面，點擊最下方 <code>continue</code> 按鈕進入下一頁，並點擊 <code>Choose File</code> 上傳 CSR：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-2.png" alt="選取完成之後點擊 `Continue` 上傳"></p><p>上傳完成後即可建立憑證，點擊 <code>Download</code> 下載憑證：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-3.png" alt="點擊 `Download` 下載憑證"></p><p>憑證下載完成之後，點擊兩下即可將憑證加入至鑰匙圈存取工具中，即可看到加入的憑證：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-4.png" alt="將下載的憑證點擊兩下加入鑰匙圈存取工具"></p><p>加入之後點擊右鍵選取輸出憑證：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-5.png" alt="點擊右鍵輸出憑證"></p><p>輸入檔名後，點擊儲存：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-6.png" alt="輸入檔名後點擊儲存"></p><p>設定 p12 檔的存取密碼，設定完成後即可完成輸出：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-7.png" alt="設定存取密碼後即可完成輸出"></p><h2 id="設定-Azure-Notification-Hub"><a href="#設定-Azure-Notification-Hub" class="headerlink" title="設定 Azure Notification Hub"></a>設定 Azure Notification Hub</h2><p>最後一個步驟，在取得 p12 檔之後，需要上傳至 Azure Notification Hub，如此一來才能順利存取 APNS 的服務，並透過 Azure 通知中樞進行推播。</p><p>Apple 的 APNS 設定畫面，選擇上傳 <code>Certifiate</code> 的方式進行設定：</p><p><img src="/images/cordova-week-3/ios-create-push-certificate-8.png"></p><p>應用程式模式的部分，由於我們建立的是開發用的測試憑證，因此應用程式模式要選擇沙箱 ( Sandbox )，儲存之後即可完成通知中樞 Apple 平台的設定。</p><p>回到 Cordova 專案，輸入指令進行 iOS 建置：</p><pre><code class="bash">$ cordova build ios</code></pre><p>建置完成後到 Cordova 專案目錄下的 <code>platforms/ios</code> 路徑，開啟 <code>xcworkspace</code> 檔：</p><p><img src="/images/cordova-week-3/open-xcworkspace.png" alt="開啟 `xcworkspace` 檔"></p><p>由於推播訊息的測試無法透過模擬器進行，因此需要一台實體的 iOS 裝置，並將裝置註冊到開發的管理後台，Xcode 提供了快速註冊的功能，當接上 iOS 裝置後選擇部署目標為實體裝置時，Xcode 會進行裝置的確認，若尚未註冊裝置則會出現錯誤的提示訊息，此時在 Signing 的部分會出現一個 <code>Register Device</code> 按鈕，點擊即可自動註冊。</p><p><img src="/images/cordova-week-3/build-app.png" alt="有時候會遇到簽署失敗的情況，可以先將 `Automatically manage signing` 的選項打勾取消"></p><p>選擇部署裝置後，點選 <code>Capabilities</code> 分頁，確認推播的服務是否有啟用：</p><p><img src="/images/cordova-week-3/check-apns.png" alt="確認是否有啟用推播服務"></p><p>部署到裝置上，點擊 <code>Push Init</code> 按鈕：</p><p><img src="/images/cordova-week-3/demo-1.jpg" alt="進行推播功能初始化，點選允許傳送通知"></p><p>允許傳送通知後，即可完成推播功能初始化並取得註冊 token，然後點擊 <code>Registration</code> 將 token 傳到後端：</p><p><img src="/images/cordova-week-3/demo-2.jpg" alt="註冊裝置完成"></p><p>回到 Azure 通知中樞，進行測試傳送：</p><p><img src="/images/cordova-week-3/test-push.png" alt="選擇平台後，即可發送測試"></p><p>收到推播訊息囉！</p><p><img src="/images/cordova-week-3/final-demo.jpg"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>透過以上的介紹，我們可以知道如何建立 App ID，並且透過 MacOS 的鑰匙圈存取工具建立 CSR 檔案，將 CSR 上傳到 APNS 建立憑證，將憑證下載並加入鑰匙圈，然後匯出成 p12 檔，將 p12 檔上傳至 Azure 通知中樞設定，利用 Cordova build 指令部署到測試的實體裝置中，最後發送測試。</p>]]></content>
      
      
      <categories>
          
          <category> Cordova </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Cordova-iOS </tag>
            
            <tag> Phonegap plugin </tag>
            
            <tag> Push Notification </tag>
            
            <tag> Azure Notification Hub </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>[Cordova Week-2] Cordova Push Notification - Android</title>
      <link href="/2018/04/16/cordova-week-2/"/>
      <url>/2018/04/16/cordova-week-2/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>在 Mobile App 的開發中，推播通知已經是不可或缺的 App 功能之一，大部分的商業 APP 都一定有推播通知的功能，因此，這次要介紹如何安裝與使用 Phonegap Plugin Push 並透過 Azure Notification Hub 實現 Android 與 iOS 的即時推播訊息功能。</p><h2 id="什麼是-Phonegap-plugin-push"><a href="#什麼是-Phonegap-plugin-push" class="headerlink" title="什麼是 Phonegap-plugin-push?"></a>什麼是 Phonegap-plugin-push?</h2><p>Phonegap-plugin-push 提供使用<strong>單一獨立的 API</strong> 來支援接收及處理原生 push notification。但這不是指我們可以發送單一個訊息並在不同作業系統上都能收到。基本上 Android 使用的是 FCM，iOS 則使用 APNS，而且他們的 payload 都很不一樣。即使在 Android 及 iOS 都使用 FCM，也是需要提供不同的 payload 才能使套件正常運作。對 Android 來說，每一次的推播內容都會在 payload 存放 <code>data</code> 的物件，可以參考 <a href="https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/PAYLOAD.md#notification-vs-data-payloads">Notification vs Data Payload</a> 這篇文章。iOS 的話可以依照 <a href="https://firebase.google.com/docs/cloud-messaging/http-server-ref">FCM documentation</a>。</p><p>筆者主要是透過 <a href="https://docs.microsoft.com/zh-tw/azure/app-service-mobile/app-service-mobile-cordova-get-started-push">Azure Notification Hub</a> 發送推播訊息， Azure Notification Hub 同時提供了方便管理的介面，讓我們只需要透過一個通知中樞，並根據不同的平台提供不同的 payload 即可輕鬆的實現推播訊息通知的功能！</p><h3 id="安裝需求"><a href="#安裝需求" class="headerlink" title="安裝需求"></a>安裝需求</h3><p>在安裝之前需要檢查一下對應的 Cordova 所支援的版本，若選擇的版本是較舊的 Cordova-Android 6.0.0 與  Cordova-iOS 4.3，則需要留意套件的版本要裝 1.9.0 的。</p><table><thead><tr><th>Plugin version</th><th>Cordova CLI</th><th>Cordova Android</th><th>Cordova iOS</th><th>CocoaPods</th></tr></thead><tbody><tr><td>2.0.0</td><td>7.0.0</td><td>6.2.1</td><td>4.4.0</td><td>1.1.1</td></tr><tr><td>1.9.0</td><td>6.4.0</td><td>6.0.0</td><td>4.3.0</td><td>1.1.1</td></tr><tr><td>1.8.0</td><td>3.6.3</td><td>4.0.0</td><td>4.1.0</td><td>N&#x2F;A</td></tr></tbody></table><span id="more"></span><h3 id="指令安裝"><a href="#指令安裝" class="headerlink" title="指令安裝"></a>指令安裝</h3><p>透過指令工具進行安裝：</p><pre><code class="bash">$ cordova plugin add phonegap-plugin-push</code></pre><p>安裝完成後可以看到 <code>config.xml</code> 出現如下的內容：</p><pre><code class="xml">&lt;plugin name=&quot;phonegap-plugin-push&quot; spec=&quot;^2.1.2&quot; /&gt;</code></pre><h2 id="建立-Azure-通知中樞"><a href="#建立-Azure-通知中樞" class="headerlink" title="建立 Azure 通知中樞"></a>建立 Azure 通知中樞</h2><p>首先點選左上角建立資源，選擇 <code>Web + 行動</code> 的類別，可以看到 <code>Notification Hub</code>：</p><p><img src="/images/cordova-week-2/create-azure-hub-step-1.png"></p><p>輸入 Notification Hub 相關資料，完成後點擊建立按鈕：</p><p><img src="/images/cordova-week-2/create-azure-hub-step-2.png"></p><p>回到儀表板，可以看到剛建立好的通知中樞：</p><p><img src="/images/cordova-week-2/azure-dash-board.png"></p><p>點擊通知中樞可以看到詳細資訊：</p><p><img src="/images/cordova-week-2/create-azure-hub-step-3.png" alt="NOTIFICATION SETTINGS 則是通知中樞所支援的平台"></p><h2 id="實作-Cordova-App-接收推播通知功能"><a href="#實作-Cordova-App-接收推播通知功能" class="headerlink" title="實作 Cordova App 接收推播通知功能"></a>實作 Cordova App 接收推播通知功能</h2><ul><li>Sample Code<ul><li>Initialize PushNotification</li><li>WebAPI Post platform info and device token</li></ul></li></ul><h4 id="初始化設定"><a href="#初始化設定" class="headerlink" title="初始化設定"></a>初始化設定</h4><pre><code class="typescript">  initNotification() &#123;    const senderID = environment.senderId;    const pushConfig: PhonegapPluginPush.InitOptions = &#123;      android: &#123;        senderID: senderID      &#125;,      ios: &#123; alert: true, badge: true, sound: true &#125;    &#125;;    this.pushNotification = PushNotification.init(pushConfig);        // 進行註冊    this.pushNotification.on(&#39;registration&#39;, data =&gt; &#123;      // Get the native platform of the device.      const platform = device.platform;      // Get the handle returned during registration.      const registId = data.registrationId;      // Set the device-specific message template.      if (platform === &#39;android&#39; || platform === &#39;Android&#39;) &#123;        // Register for GCM notifications.        this.handleData = &#123; Platform: &#39;gcm&#39;, DeviceToken: registId &#125;;      &#125; else if (device.platform === &#39;iOS&#39;) &#123;        // Register for notifications.        this.handleData = &#123; Platform: &#39;apns&#39;, DeviceToken: registId &#125;;      &#125;      console.log(`取得 token`, data.registrationId);    &#125;);        // 收到訊息時    this.pushNotification.on(&#39;notification&#39;, data =&gt; &#123;      console.log(`got notification!`, data);      // data.message,      // data.title,      // data.count,      // data.sound,      // data.image,      // data.additionalData    &#125;);        // 發生錯誤時    this.pushNotification.on(&#39;error&#39;, e =&gt; &#123;      console.log(`Notification Error: $&#123;e.message&#125;`, e);    &#125;);  &#125;</code></pre><h4 id="註冊裝置"><a href="#註冊裝置" class="headerlink" title="註冊裝置"></a>註冊裝置</h4><pre><code class="typescript">registDevice(): Observable&lt;any&gt; &#123;    // console.log(`進行推播註冊`, environment.serverUrl);    // console.log(`device token`, this.handleData.DeviceToken);    // console.log(`platform`, this.handleData.Platform);    return this.http      .post&lt;any&gt;(        environment.apiUrl,        this.handleData,      )      .pipe(        catchError(err =&gt; &#123;          console.log(`notificationService registDevice error`, err);          return Observable.throw(err);        &#125;)      );  &#125;</code></pre><h2 id="Android-平台設定"><a href="#Android-平台設定" class="headerlink" title="Android 平台設定"></a>Android 平台設定</h2><h3 id="建立-FCM-Project"><a href="#建立-FCM-Project" class="headerlink" title="建立 FCM Project"></a>建立 FCM Project</h3><p>要推播訊息到 Android 系統，需要先建立 <a href="https://console.firebase.google.com/">FCM</a> ( Firebase Cloud Message ) 專案，登入 Google 帳號後可以看到以下的畫面，點選新增專案：</p><p><img src="/images/cordova-week-2/create-fcm-project-step-1.png"></p><p>然後輸入專案相關資訊：專案名稱、ID 及國家或地區，並點擊建立專案。</p><p><img src="/images/cordova-week-2/create-fcm-project-step-2.png"></p><p>專案建立完成後，會進到專案的 dash board，點選左上角的齒輪展開選單，點擊<code>專案設定</code>：</p><p><img src="/images/cordova-week-2/create-fcm-project-step-3.png"></p><p>點選後會看到專案的相關資訊，捲軸滾到下方可以看到目前專案中沒有任何應用程式，點擊中間將 Firebase 加入您的 Android 應用程式的選項：</p><p><img src="/images/cordova-week-2/fcm-create-android-app.png"></p><p>點擊後進入新增 Android 應用程式的畫面，輸入 App 相關資訊，輸入完成後點擊註冊應用程式：</p><p><img src="/images/cordova-week-2/fcm-create-android-app-2.png"></p><p>註冊完成之後，點選 下載 google-services.json&#96; 按鈕進行下載，並將檔案存放在 Cordova 專案的根目錄。</p><p><img src="/images/cordova-week-2/fcm-create-android-app-3.png"></p><p>下載完成之後再回到 Cordova 專案的 <code>config.xml</code> 設定檔，在 Android 的 <code>platform</code> 區塊中加上以下的內容：</p><pre><code class="xml"> &lt;platform name=&quot;android&quot;&gt;        &lt;allow-intent href=&quot;market:*&quot; /&gt;        &lt;resource-file src=&quot;google-services.json&quot; target=&quot;app/google-services.json&quot; /&gt;&lt;/platform&gt;</code></pre><p>FCM 的部分設定完成後，我們還需要將 API Key 存放至 Azure Notification Hub 的設定中，因此回到專案的主控台，雖然在一般的分頁下可以看到 <code>網路 API 金鑰</code>，但這似乎還是舊版的，筆者在 Azure 輸入設定時會遇到錯誤的情況，因此新版的部分要點選 <code> CLOUD MESSAGING</code> 標籤進入：</p><p><img src="/images/cordova-week-2/create-fcm-project-step-4.png"></p><p>會看到專案憑證的資訊及寄件者 ID，而伺服器金鑰則是建立 Azure Notification Hub 之後要設定的 API Key：</p><p><img src="/images/cordova-week-2/create-fcm-project-step-5.png"></p><p>進入 Googel ( GCM ) 的設定，並將複製的 API Key 貼上：</p><p><img src="/images/cordova-week-2/android-add-api-key.png"></p><h3 id="Azure-Notification-Hub-測試推播"><a href="#Azure-Notification-Hub-測試推播" class="headerlink" title="Azure Notification Hub 測試推播"></a>Azure Notification Hub 測試推播</h3><p>完成設定之後，可以到側欄下方有個<code>支援與疑難排解</code>的類別，底下有個 <code>Test Send</code> 連結，點選後會看到測試發送的畫面，確認 Cordova App 的 Device Token 有順利註冊成功後，選擇 Android 平台即可立即發送測試。</p><p><img src="/images/cordova-week-2/android-send-test.png"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>經過以上的介紹我們可以知道要如何安裝 <code>phonegap-plugin-push</code> 並建立 FCM Project 後，將 <code>google-service.json</code> 加入 Cordova 專案中，同時將伺服器金鑰設定至 Azure Notification Hub 中，最後來一發測試訊息，大功告成！</p><p>Apple 的部分，由於需要另外建立推播服務的憑證，下篇文章會再針對 APNS 的部分去做說明，若沒接觸過 Apple Develope 後台，想實作推播功能的話，需要花點時間了解 Apple 的 App Identity 與憑證的建立方式，才能順利實作囉。</p>]]></content>
      
      
      <categories>
          
          <category> Cordova </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Cordova-Android </tag>
            
            <tag> Cordova-iOS </tag>
            
            <tag> Phonegap plugin </tag>
            
            <tag> Push Notification </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>[Cordova Week-1] Hello Cordova!</title>
      <link href="/2018/04/08/cordova-week-1/"/>
      <url>/2018/04/08/cordova-week-1/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>潛水了很久，是時候出來<del>還債</del>分享一下了，在工作上跟 Cordova 真的很有緣，雖然主要是 Angular 的專案開發，但幾乎都是要打包成 APP 的方式呈現，在開發的過程中也踩了不少地雷，經歷過多少次的絕望深淵中爬出，為此，將自身的經驗紀錄下來分享給大家，若有錯誤或需補充的地方還請大家不吝指教。</p><h2 id="什麼是-Cordova？"><a href="#什麼是-Cordova？" class="headerlink" title="什麼是 Cordova？"></a>什麼是 Cordova？</h2><p>Apache Cordova 是一個開源的行動開發框架，它可以讓我們透過標準的 Web 技術例如：<code>HTML</code>, <code>CSS3</code> 與 <code>JavaScript</code> 進行跨平台的行動應用開發，應用程式可以在每個不同的平台包裝並執行，並依靠符合標準的 API 綁定來存取裝置的功能，例如傳感器，資料或網路狀態等。</p><p>有以下的情況可以使用 Cordova：</p><ul><li>你的行動應用開發想要沿用現有的專案，跨到其他平台，不想再使用該平台的程式語言與工具重新開發。</li><li>你是網站開發者，想要將你的網站應用封裝並部署到各個應用商店平台。</li><li>你是原生的行動應用開發者，對混合式的原生應用存取原生裝置層級 API 的 <code>WebView</code> 元件感興趣，或是你想開發一個可以在原生與 WebView 間運作的套件。</li></ul><span id="more"></span><h2 id="Cordova-架構"><a href="#Cordova-架構" class="headerlink" title="Cordova 架構"></a>Cordova 架構</h2><p>透過下方的架構圖可以了解 Cordova 的世界觀：</p><ul><li><h3 id="HTML-Rendering-Engine-Web-View"><a href="#HTML-Rendering-Engine-Web-View" class="headerlink" title="HTML Rendering Engine ( Web View )"></a>HTML Rendering Engine ( Web View )</h3><ul><li>是整個 Web 應用表演的舞台，除了提供一般瀏覽器都有的 HTML API 之外，同時也提供了 Cordova API，我們可以使用 JavaScript 來呼叫這些 API，實作我們想要的功能。</li></ul></li><li><h3 id="Web-App"><a href="#Web-App" class="headerlink" title="Web App"></a>Web App</h3><ul><li>顧名思義就是主要開發 Web 的區塊，整個 App 的畫面與非原生的功能都在這開發，可以比喻成是表演者與工作人員的後台，負責撰寫腳本、準備道具的地方。預設的網頁名稱為 <code>index.html</code>，並引用 CSS、JavaScript、圖片或其他在執行時所需要的資源檔案。應用程式會在一個原生應用包裝的 <code>WebView</code> 中執行，這個區塊有一個很重要的檔案 <code>config.xml</code>，他主要提供關於應用程式的資訊與特定的設定參數影響他的執行方式，例如是否針對裝置轉向做出反應。</li></ul></li><li><h3 id="Plugins"><a href="#Plugins" class="headerlink" title="Plugins"></a>Plugins</h3><ul><li>Cordova 套件是整個舞台最重要的部分，他們是幕後辛苦的工作人員窗口，提供原生裝置相關的功能存取介面，這些介面背後綁定了 Cordova 原生 API，我們可以使用 JavaScript 呼叫這些套件提供的 API，實現例如相機功能、電池、網路狀態、檔案存取…等原生的功能。</li><li>Apache Cordova 專案持續維護的套件稱為核心套件( <a href="https://cordova.apache.org/docs/en/latest/guide/support/index.html#core-plugin-apis">Core Plugins</a> )，這些核心套件提供存取了上述基本且重要的功能，此外，也有不少針對特定平台才有的功能進行開發的第三方套件可以使用，我們可以在 <a href="https://cordova.apache.org/plugins/">plugin search</a> 或 <a href="https://www.npmjs.com/search?q=ecosystem:cordova">npm</a> 搜尋需要的 Cordova 套件。或是直接參考 <a href="https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html">Plugin Development Guide</a> 自行開發套件。</li><li>在專案初始化的時候預設是沒有安裝任何套件的，即使是核心套件，這部分需要我們自行設定與安裝。</li></ul></li></ul><p><img src="/images/cordova-week-1/cordovaapparchitecture.png" alt="Cordova 架構圖"></p><h2 id="開發路線"><a href="#開發路線" class="headerlink" title="開發路線"></a>開發路線</h2><p>Cordova 提供了兩種基本的工作流程 ( workflow ) 來建立行動應用，雖然都可以完成相同的工作，但不同的工作流成有著不同的優勢：</p><ul><li>跨平台工作流程 ( <strong>Cross-platform (CLI) workflow</strong> ) <ul><li>若你的應用要盡可能在許多不同的 mobile OS 中執行，就使用這個工作流程吧！只需要專注在特定平台的開發，這個工作流程主要以 <code>cordova</code> CLI 為中心，CLI 是一個高層的工具，它可以讓我們一次建立多個平台專案，並將底層常見的 <code>shell script</code> 功能抽象化。CLI 會將一包 Web Assets 複製到每個行動平台的子目錄中，在每次執行建置的時候為每個平台進行必要的配置調整，並產生應用程式的二進位檔案，CLI 也提供了方便的套件安裝功能，除非你需要切換成以平台為中心的工作流程，建議還是以跨平台工作流程為主。</li></ul></li><li>平台為中心工作流程 ( <strong>Platform-centered workflow</strong> )<ul><li>若想專注於為單一平台構建應用程式並需要<strong>針對底層</strong>進行調整，請使用此工作流程。舉例來說，如同 <a href="https://cordova.apache.org/docs/en/latest/guide/hybrid/webviews/index.html">Embedding WebViews</a> 的說明，你需要將一個原生元件混合到以 Web 為基礎的 Cordova 元件中，根據經驗，如果需要修改SDK 中的專案，那個使用此工作流程較為適合。</li></ul></li></ul><p>筆者在開發的時候，都是以跨平台工作流程為主，因此接下來的介紹都會以跨平台工作流程的開發經驗分享為主。</p><hr><h2 id="環境準備"><a href="#環境準備" class="headerlink" title="環境準備"></a>環境準備</h2><h3 id="安裝-Node-js"><a href="#安裝-Node-js" class="headerlink" title="安裝 Node.js"></a>安裝 Node.js</h3><p>可以到 <a href="https://nodejs.org/en/">node.js 官網</a>下載安裝檔進行安裝。</p><h3 id="安裝-Cordova-CLI"><a href="#安裝-Cordova-CLI" class="headerlink" title="安裝 Cordova-CLI"></a>安裝 Cordova-CLI</h3><p>在開發過程中，cordova-cli 扮演著很重要的角色，它提供了平台管理、套件管理、建置與執行的功能，安裝方式如下：</p><p>使用 npm 安裝：</p><pre><code class="bash">npm install -g cordova</code></pre><p>使用 yarn 安裝：</p><pre><code class="bash">yarn global add cordova</code></pre><p>目前常見的 App 開發主要支援的平台有 Android、iOS 與 Windows Phone，其中前兩者為主要的市場平台，筆者目前遇到需要支援的平台也以 iOS 與 Android 為主，因此就針對這兩個平台來分享經驗囉。</p><h3 id="Android-環境準備"><a href="#Android-環境準備" class="headerlink" title="Android 環境準備"></a>Android 環境準備</h3><h4 id="JDK-Java-Development-Kit"><a href="#JDK-Java-Development-Kit" class="headerlink" title="JDK ( Java Development Kit )"></a>JDK ( Java Development Kit )</h4><p>Java JDK 可直接到<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">官網下載</a>。</p><p><img src="/images/cordova-week-1/download-jdk.png" alt="到官網即可下載 JDK 進行安裝"></p><p>Android SDK Manager 根據<a href="https://developer.android.com/studio/intro/update.html">官方建議</a>使用 <a href="https://developer.android.com/studio/index.html">Android Studio</a> 提供的 GUI 管理介面進行管理較方便。</p><p><img src="/images/cordova-week-1/download-android-studio.png" alt="到官網即可下載 Android Studio 進行安裝"></p><h4 id="Android-SDK-Management"><a href="#Android-SDK-Management" class="headerlink" title="Android SDK Management"></a>Android SDK Management</h4><p>Cordova Android 的版本支援需要留意對應的 Android API-Level，而 Android API-Level 關係到行動裝置的版本是否支援。因此這部分在一開始需要確認專案支援的 Android 版本最低需求為何。Android SDK 的版本除非需要特定支援舊版的情況，一般來說只要裝最新版本即可，未來若有更新也可以將舊版的移除。</p><table><thead><tr><th>cordova-android 版本</th><th>支援的 Android API-Levels</th><th>相當於 Android 版本範圍</th></tr></thead><tbody><tr><td>7.X.X</td><td>19 - 27</td><td>4.4 - 8.0</td></tr><tr><td>6.X.X</td><td>16 - 25</td><td>4.1 - 7.1.1</td></tr><tr><td>5.X.X</td><td>14 - 23</td><td>4.0 - 6.0.1</td></tr><tr><td>4.1.X</td><td>14 - 22</td><td>4.0 - 5.1</td></tr><tr><td>4.0.X</td><td>10 - 22</td><td>2.3.3 - 5.1</td></tr><tr><td>3.7.X</td><td>10 - 21</td><td>2.3.3 - 5.0.2</td></tr></tbody></table><p>開啟 <strong>Android SDK Management</strong> 的方式：開啟 Android Studio 之後進入 <strong>Preferences</strong> 的視窗，<strong>System Settings</strong> 下有 Android SDK，點擊即可檢視 Android SDK Management 的介面。</p><p><img src="/images/cordova-week-1/open-android-sdk-management.png" alt="Android SDK Management 開啟方式"></p><p><img src="/images/cordova-week-1/android-sdk-management.png" alt="Android SDK Management 位置"></p><h3 id="iOS-環境準備"><a href="#iOS-環境準備" class="headerlink" title="iOS 環境準備"></a>iOS 環境準備</h3><ul><li><p>Xcode</p><ul><li><p>Xcode 有兩種安裝方式：</p><ul><li><a href="https://itunes.apple.com/us/app/xcode/id497799835?mt=12">App Store</a> 搜尋 Xcode 進行安裝</li><li><a href="https://developer.apple.com/downloads/index.action">Apple Developer Downloads</a> 下載安裝檔</li></ul></li><li><p>Xcode 安裝完成之後，有一些指令列工具需要啟動提供給 Cordova 執行。在指令列工具下輸入：</p></li><li><pre><code class="bash">$ xcode-select --install</code></pre></li></ul></li><li><p>Deployment Tools</p><ul><li><p><a href="https://www.npmjs.org/package/ios-deploy">ios-deploy</a> 可以讓我們透過 command-line 將 iOS 應用程式更新到 iOS 裝置上。</p></li><li><p>安裝方式：</p><ul><li><p>透過 npm 安裝</p></li><li><pre><code class="bash">$ npm install ios-deploy -g</code></pre></li><li><p>透過 yarn 安裝</p></li><li><pre><code class="bash">$ yarn global add ios-deploy</code></pre></li></ul></li></ul></li></ul><hr><h2 id="建立-Cordova-專案"><a href="#建立-Cordova-專案" class="headerlink" title="建立 Cordova 專案"></a>建立 Cordova 專案</h2><p>環境都準備好之後，就正式來建立 Cordova 專案吧！透過 cordova cli 在指令列工具上輸入：</p><pre><code class="bash">$ cordova create hello com.example.hello HelloWorld</code></pre><p><code>create</code> 是主要的指令，屬於<a href="https://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#global-command-list">全域型指令</a>，hello 是資料夾的命名，也可以是路徑，若是路徑的話則要先手動建立資料夾。<code>com.example.hello</code> 是 App 的 ID，通常是以反向域名的方式命名，<code>HelloWorld</code> 則是 APP 的顯示名稱，在建立之後這些資訊都可以在 <code>config.xml</code> 中進行調整。建立後的資料夾架構如下圖：</p><p><img src="/images/cordova-week-1/create-cordova-folder.png" alt="Cordova 建立新專案後的內容"></p><h3 id="專案目錄架構"><a href="#專案目錄架構" class="headerlink" title="專案目錄架構"></a>專案目錄架構</h3><ul><li><code>config.xml</code>：整個專案最重要的檔案，主要記錄著 APP 相關的參數，例如：圖示、初始化圖片、名稱、開發團隊資訊、平台與套件相關資訊…等，這個檔案一定要加入版控！</li><li><code>hooks</code>：預設是空的，可針對專案需求製作掛鉤腳本以節省不必要的時間浪費。</li><li><code>package.json</code>：就是 npm 的 package.json，紀錄著套件或平台之間的版本相依性檔案。</li><li><code>platforms</code>：依照不同的平台會產生不同的資料夾，例如：android, ios…等。由於在編譯的過程中，會時常修改這裡面的檔案，因此不建議直接在這檔案中進行編輯，極有可能會被覆寫掉喔！</li><li><code>plugins</code>：存放加入的 cordova 套件，也不需要加入版控，config.xml 已經有紀錄囉。</li><li><code>res</code>：存放 APP Icon 與初始畫面圖片的地方，有很多不同的大小，這部分可<a href="http://cordova.apache.org/docs/en/7.x/config_ref/images.html">參考文件</a>與 <a href="http://cordova.apache.org/docs/en/7.x/reference/cordova-plugin-splashscreen/index.html">SplashScreen 套件說明</a>。</li><li><code>www</code>：Web 應用存放的地方，用 Angular 開發的話就是將 <code>ng build</code> 後的結果複製到這個資料夾中。</li></ul><h3 id="gitignore-設定"><a href="#gitignore-設定" class="headerlink" title=".gitignore 設定"></a>.gitignore 設定</h3><p>Git 這麼好用的版控工具，沒用怎麼行呢？由於新增的時候沒有版控的設定，網路上有熱心的開發者提供現成的 gitignore 設定檔下載，基本上就是 <code>platforms</code>、<code>plugins</code> 這兩個資料夾中的檔案不需要加入版控即可。由於筆者的開發是搭配 Angular 進行，因此 <code>www</code> 資料夾也沒有加入版控，最後會再說明如何透過 Hooks 與 Angular CLI 的 <code>ng build</code> 搭配。</p><hr><h2 id="新增-Cordova-平台-Platform"><a href="#新增-Cordova-平台-Platform" class="headerlink" title="新增 Cordova 平台 ( Platform )"></a>新增 Cordova 平台 ( Platform )</h2><p>新增平台的方式很簡單，一樣透過 Cordova CLI 輸入以下的指令：</p><pre><code class="bash">$ cordova platform add android ios</code></pre><p><code>platform</code> <a href="https://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#project-command-list">專案型指令</a>，主要與平台相關的操作，<code>add</code> 是加入指定的平台，Android 和 iOS 可以一起建立。</p><h2 id="安裝-Cordova-Plugins"><a href="#安裝-Cordova-Plugins" class="headerlink" title="安裝 Cordova Plugins"></a>安裝 Cordova Plugins</h2><p>專案開發的過程中多少都會需要存取原生的功能，這時候就要去尋找是否有符合需求的套件能使用，在架構介紹的時候有提到 Cordova 官方有持續在維護核心套件 ( Core Plugin )，大部分的需求都可透過這些套件實現，但有少部分的情況，我們可能需要尋找第三方套件來安裝，Cordova 發展時間已 6 年，因此不太需要擔心找不到適合的套件情況，僅留意套件之間是否有相依性的問題。</p><p>安裝 cordova plugin 指令：</p><pre><code class="bash">$ cordova plugin add cordova-plugin-xxx</code></pre><p>安裝完成之後，可以觀察一下 <code>config.xml</code> 檔案的變化，就可以了解主要的平台與套件的資訊皆紀錄在這個檔案中。</p><pre><code class="xml">&lt;?xml version=&#39;1.0&#39; encoding=&#39;utf-8&#39;?&gt;&lt;widget id=&quot;com.cordova.hello&quot; version=&quot;1.0.0&quot; xmlns=&quot;http://www.w3.org/ns/widgets&quot; xmlns:cdv=&quot;http://cordova.apache.org/ns/1.0&quot;&gt;    &lt;name&gt;HelloCordova&lt;/name&gt;    &lt;description&gt;        A sample Apache Cordova application that responds to the deviceready event.    &lt;/description&gt;    &lt;author email=&quot;dev@cordova.apache.org&quot; href=&quot;http://cordova.io&quot;&gt;        Apache Cordova Team    &lt;/author&gt;    &lt;content src=&quot;index.html&quot; /&gt;    &lt;plugin name=&quot;cordova-plugin-whitelist&quot; spec=&quot;1&quot; /&gt;    &lt;access origin=&quot;*&quot; /&gt;    &lt;allow-intent href=&quot;http://*/*&quot; /&gt;    &lt;allow-intent href=&quot;https://*/*&quot; /&gt;    &lt;allow-intent href=&quot;tel:*&quot; /&gt;    &lt;allow-intent href=&quot;sms:*&quot; /&gt;    &lt;allow-intent href=&quot;mailto:*&quot; /&gt;    &lt;allow-intent href=&quot;geo:*&quot; /&gt;    &lt;platform name=&quot;android&quot;&gt;        &lt;allow-intent href=&quot;market:*&quot; /&gt;    &lt;/platform&gt;    &lt;platform name=&quot;ios&quot;&gt;        &lt;allow-intent href=&quot;itms:*&quot; /&gt;        &lt;allow-intent href=&quot;itms-apps:*&quot; /&gt;    &lt;/platform&gt;    &lt;engine name=&quot;android&quot; spec=&quot;~7.0.0&quot; /&gt;    &lt;engine name=&quot;ios&quot; spec=&quot;~4.5.4&quot; /&gt;    &lt;plugin name=&quot;cordova-plugin-device&quot; spec=&quot;^2.0.1&quot; /&gt;    &lt;plugin name=&quot;cordova-plugin-dialogs&quot; spec=&quot;^2.0.1&quot; /&gt;    &lt;plugin name=&quot;cordova-plugin-geolocation&quot; spec=&quot;^4.0.1&quot; /&gt;&lt;/widget&gt;</code></pre><hr><h2 id="建置-Cordova-專案"><a href="#建置-Cordova-專案" class="headerlink" title="建置 Cordova 專案"></a>建置 Cordova 專案</h2><p>建置專案的方式很簡單，首先將做好的 Web 專案整包複製到 <code>www</code> 資料夾下，然後輸入指令：</p><pre><code class="bash">$ cordova run android$ cordova build android</code></pre><p><code>cordova run</code> 的用途是直接建置完成後部署到模擬器或實體裝置上。 <code>cordova build</code> 則只有進行編譯，不會另外部署。兩者皆會產生 apk 檔案，除了對 android 進行建置之外，也可以一次建置多個平台，只需要將平台加在指令後即可：</p><pre><code class="bash">$ cordova run android ios$ cordova build android ios</code></pre><p>建置完成之後 Android 平台會產生 APK 檔，路徑在：<code>&lt;your project name&gt;/platforms/android/app/build/outputs/apk/debug</code>，會看到名稱為 <code>app-debug.apk </code>檔案，複製之後存到行動裝置中也以手動的方式進行安裝。從檔案名稱就可以知道這是在開發時期進行測試用的 apk 檔案。至於要如何建置正式發佈的版本，之後再紀錄分享。</p><h4 id="iOS-建置"><a href="#iOS-建置" class="headerlink" title="iOS 建置"></a>iOS 建置</h4><p>由於第一次開啟 Xcode 會有同意書需要先確認同意，若之前沒有開啟過 Xcode，請先開啟一次，才能確保專案建置與模擬器開啟順利。一樣透過 <code>cordova run</code> 建置與部署至實體裝置或模擬器，或是以 <code>cordova build</code> 建置產生 Xcode 的專案檔，檔案路徑如下：<code>&lt;your project name&gt;/platforms/ios/</code> 資料夾中有名為 <code>&lt;AppName&gt;.xcworkspace</code> 的檔案，若要手動建置則直接開啟此檔，第一次建置完成開啟後會看到一些錯誤訊息，主要是簽證的部分，由於尚未設定，因此會出現錯誤的情況。</p><p><img src="/images/cordova-week-1/xcode-without-sign.png" alt="第一次開啟時必定會出現的錯誤訊息-沒有簽證"></p><p><img src="/images/cordova-week-1/xcode-with-sign.png" alt="選擇團隊之後會進行 APP Provision 的註冊，即可解決錯誤"></p><h2 id="設定掛鉤-Hooks-搭配-Angular-Build"><a href="#設定掛鉤-Hooks-搭配-Angular-Build" class="headerlink" title="設定掛鉤 ( Hooks ) 搭配 Angular Build"></a>設定掛鉤 ( Hooks ) 搭配 Angular Build</h2><p>由於我們使用 Angular 進行開發，因此在建置之前還需要經過 <code>ng build</code> 這段，並將 <code>dist</code> 資料架內容複製到 Cordova 專案目錄下的 <code>www</code>，當有新的變更要進行 <code>cordova build</code> 或 <code>cordova run</code> 時，都必須要『人肉 CI』一下，手動複製編譯後的內容，很沒效率，對於撰寫批次檔熟悉的開發者，就會自己寫個腳本來做這些事情，任何能透過指令解決的都可以寫成腳本，而 Cordova 也提供了方便好用的 Hooks 機制，可以設定在 <code>config.xml</code> 中：</p><pre><code class="xml">&lt;hook src=&quot;hooks/buildApp.js&quot; type=&quot;before_build&quot; /&gt;&lt;hook src=&quot;hooks/buildApp.js&quot; type=&quot;before_run&quot; /&gt;</code></pre><p>上面的意思就是，當 Cordova 要 <code>build</code> 或 <code>run</code> 之前，可以執行 <a href="https://gist.github.com/jeffwu85182/1c39649696eed4c51dffdeb9585a175d">buildApp.js</a> 檔案，而這個檔案是使用 node.js 撰寫的腳本，主要做的事情就是回到 Angular 專案目錄下進行 <code>ng build</code>，完成後將 <code>dist</code> 的內容複製到 cordova 專案的 <code>www</code> 目錄下，如此一來就可以省下很多不必要的時間浪費囉！Working hard 之外，Working smart 也很重要呢！更多 Hooks 可<a href="https://cordova.apache.org/docs/en/latest/guide/appdev/hooks/index.html">參考官網文件</a></p><h2 id="Debug"><a href="#Debug" class="headerlink" title="Debug"></a>Debug</h2><p>網站開發時我們都會透過 Chrome 的 <code>F12</code> 開發者工具進行除錯，到 App 上後，我們該如何除錯呢？很簡單，Chrome 針對 Android 平台提供了方便除錯的功能，一樣透過開發者工具，開啟 Remote Device：</p><p><img src="/images/cordova-week-1/open-chrome-remote-dev-tools.png" alt="在 chrome devtools 右上角點選 More tools 中的 Remote devices"></p><p><img src="/images/cordova-week-1/open-chrome-dev-tools.png" alt="若有開啟模擬器或連接中的裝置則會出現在左邊的 Devices 清單，點擊 Inspect 即可開啟 APP 除錯工具"></p><p>iOS APP 若要進行除錯的話，則需要透過 safari，首先進入 safari 的偏好設定：</p><p><img src="/images/cordova-week-1/open-safari-preference.png"></p><p>接著到<code>進階</code>的分頁下，有個<code>在選單列中顯示『開發』選單</code>的選項，勾選起來：</p><p><img src="/images/cordova-week-1/enable-safari-dev-tools.png"></p><p>回到 Safari，就會看到開發的選單項目，裡面會看到如下圖的內容，其中『Jeff-Macbook』是筆者的電腦，若有接上其他 iOS 裝置或模擬器則會顯示在這個選單中，展開會就可查看『可檢閱的應用程式』，也就能進行除錯囉！</p><p><img src="/images/cordova-week-1/open-safari-dev-tools.png" alt="Safari 開發選單項目的內容"></p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>透過以上的介紹，可以了解如何準備環境與安裝 Cordova CLI，透過指令 <code>cordova create</code> 新增專案並使用 <code>cordova platform add</code> 加入支援的平台與套件，最後利用 Cordova hooks 搭配 Angular CLI 將建置後的內容與複製到 <code>www</code> 資料夾進行 Cordova 建置。利用 <code>cordova run android</code> 或 <code>cordova build android</code> 進行 APP 建置，iOS 第一次建置完成後透過 Xcode 開啟 <code>xcworkspace</code> 檔案需要選擇團隊以建立 APP Provision，在開發的過程中可利用 Chrome 瀏覽器的 F12 開發者工具進行 Android APP 的偵錯，透過 Safari 瀏覽器提供的開發者工具針對 iOS APP 除錯。</p><p>參考資料：</p><ul><li><a href="http://cordova.apache.org/docs/en/7.x/guide/cli/index.html">Cordova doc - Create your first app</a></li><li><a href="http://cordova.apache.org/docs/en/7.x/reference/cordova-cli/index.html">Cordova doc - CLI Reference</a></li><li><a href="https://cordova.apache.org/docs/en/latest/guide/appdev/hooks/index.html">Cordova doc - Hooks</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Cordova </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular with cordova </tag>
            
            <tag> Cordova environment prepare </tag>
            
            <tag> Cordova-CLI </tag>
            
            <tag> Cordova-Android </tag>
            
            <tag> Cordova-iOS </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular Directive 初探 - Part.4</title>
      <link href="/2017/04/11/angular-directive-research-part-4/"/>
      <url>/2017/04/11/angular-directive-research-part-4/</url>
      
        <content type="html"><![CDATA[<p>在初探 part.1 的時候，提到了 Angular directive 有分三種，Component, Attribute Directive and Structural Directive，而之前介紹了 Attribute Directive，知道如何建立與使用，這次就來研究一下 Structural Directive 吧！</p><h3 id="什麼是-structural-directive"><a href="#什麼是-structural-directive" class="headerlink" title="什麼是 structural directive ?"></a>什麼是 structural directive ?</h3><p>Structural directives 負責 HTML 的 layout。通常是藉由加入、移除或操作 element ，將 DOM 架構進行繪製或重繪的動作，就和其他的 directives 使用方式一樣，套用到 HTML host element 上，並且依照這個 directive 有什麼功能去進行處理，而被套用的 host element 本身以及其底下的其他後代都是在 directive 執行的範圍內。</p><p>structural directive 很好分辨，directive 的名稱前面有星號 ( * ) 的 directive 就是 structural directive。</p><pre><code class="html">&lt;div *ngIf=&quot;isChecked&quot;&gt;is checked&lt;/div&gt;</code></pre><p>像上方的範例，我們很常在使用的 directive 之一 <code>*ngIf </code> ，只要帶著設定的屬性名稱，不需要加上任何括號就能執行。稍後會提到使用星號帶來的方便性，以及後面的字串其實是 microsyntax 而不是一般的 template expression 喔，Angular 會對星號的標記語法進行<em>解語法糖</em> 的動作，並且將結果放進 <code>&lt;template&gt;</code> 標記中，而這個 template 的影響範圍在 host element 以及其底下的後代。每個 strucural directive 都和對應的 template 內容不太一樣。</p><p>三個內建且常用的 structural directive —<a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngIf">NgIf</a>、 <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngFor">NgFor</a>、 <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngSwitch">NgSwitch…</a>等，在官網的 <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html"><em>Template Syntax</em></a> 文件中都有提到，也有提供參考的範例，以下為其中一個 template 的範例：</p><span id="more"></span><pre><code class="html">&lt;div *ngIf=&quot;hero&quot;&gt;&#123;&#123;hero.name&#125;&#125;&lt;/div&gt;&lt;ul&gt;  &lt;li *ngFor=&quot;let hero of heroes&quot;&gt;&#123;&#123;hero.name&#125;&#125;&lt;/li&gt;&lt;/ul&gt;&lt;div [ngSwitch]=&quot;hero?.emotion&quot;&gt;  &lt;happy-hero *ngSwitchCase=&quot;&#39;happy&#39;&quot; [hero]=&quot;hero&quot;&gt;&lt;/happy-hero&gt;  &lt;sad-hero *ngSwitchCase=&quot;&#39;sad&#39;&quot; [hero]=&quot;hero&quot;&gt;&lt;/sad-hero&gt;  &lt;confused-hero *ngSwitchCase=&quot;&#39;confused&#39;&quot; [hero]=&quot;hero&quot;&gt;&lt;/confused-hero&gt;  &lt;unknown-hero *ngSwitchDefault [hero]=&quot;hero&quot;&gt;&lt;/unknown-hero&gt;&lt;/div&gt;</code></pre><p>基本上大家都應該知道要怎麼去使用了，所以這篇<strong>不會提到如何使用</strong>，但是會去說明 structural directive 是<strong>如何運作</strong>的，以及要怎麼<strong>寫一個自訂的</strong> structural directive。</p><p>關於 directive 大小寫的拼法，在官網文章中有提到這部分，雖然都是駝峰式命名 ( Camel Case )，但有分首字大小寫，首字大寫的例如：<code>NgIf</code> 是指 directive class 的名稱；而 <code>ngIf</code> 指的是 directive 套用時的 attribute 名稱。</p><p>Directive 的 class 是以首字大駝峰式命名 ( <code>NgIf</code> )， 套用 Directive 的 attribute 名稱則是首字小駝峰式命名 ( <code>ngIf</code> )，如果文章中提到它的屬性或這個 directive 在做什麼的，指的都是 directive class 的部分，如果是在說明如何套用到 template 中的 html，那就是指 directive attribute，這部分多多留意喔！</p><p>雖然前面的文章有提到過，但還是先來複習一下：除了本篇的 structural directive，另外還有兩種 Angular directives，<code>components</code> 以及 <code>attribute</code>。<code>components</code> 主要是管理一個區域原生的 HTML element ，簡單來說，就是帶有 template 的 directive。而 <code>attribute</code> directive 可以用來改變 element、component 或其他 directive 的外觀或行為，舉例來說，內建的 <code>NgStyle</code> directive 可以同時改變多個 element style。</p><p>一個 host element 可以套用多個 <code>attribute</code> directive ，但<code>structural</code> directive 就只能套用一個。</p><h3 id="NgIf-case-study"><a href="#NgIf-case-study" class="headerlink" title="NgIf case study"></a>NgIf case study</h3><p><code>NgIf</code> 是最簡單的 structural directive 也最容易理解，它取得 boolean expression 後，把標記的 DOM 整個顯示或消失。</p><pre><code class="html">&lt;p *ngIf=&quot;true&quot;&gt;  Expression is true and ngIf is true. This paragraph is in the DOM.&lt;/p&gt;&lt;p *ngIf=&quot;false&quot;&gt;  Expression is false and ngIf is false. This paragraph is not in the DOM.&lt;/p&gt;</code></pre><p>Angular 的 <code>ngIf</code> 並非透過 CSS 來隱藏 element，而是直接從 DOM 本身加入或移除。這可以從瀏覽器的開發者工具檢查元素確定。</p><p><img src="/images/angular-directive-research-part-4/element-not-in-dom.png" alt="透過 ngIf 可以將要隱藏的 element 不存在於 dom"></p><p>上圖有兩段內容，第一段就是一般正常的 DOM，而下方的第二段是沒有使用的部分，可以看到這個區塊不存在於 DOM 中，取而代之的是關於 “template binding” 的一段註解，詳細的說明後面會提到。</p><p>當條件是 false 時，<code>NgIf</code> 會將 DOM 上的 host element 移除，同時移除 DOM 相關的附件 ( 指 ngIf 建立在 host element 底下的相關屬性或事件 )，也會透過 Angular 變更偵測的機制將 component 抽離與毀滅，而 component 和 DOM 節點就可以被回收與釋放記憶體空間。</p><h4 id="為何移除比隱藏要來得好？"><a href="#為何移除比隱藏要來得好？" class="headerlink" title="為何移除比隱藏要來得好？"></a>為何移除比隱藏要來得好？</h4><p>Directive 可以隱藏不需要的段落，但不是將 <code>display</code> style 設置為 <code>none</code>，例如以下的範例：</p><pre><code class="html">&lt;p [style.display]=&quot;&#39;block&#39;&quot;&gt;  Expression sets display to &quot;block&quot;. This paragraph is visible.&lt;/p&gt;&lt;p [style.display]=&quot;&#39;none&#39;&quot;&gt;  Expression sets display to &quot;none&quot;. This paragraph is hidden but still in the  DOM.&lt;/p&gt;</code></pre><p>雖然設定 CSS <code>display: none</code> 在畫面上確實是看不見的，但元素仍會存在 DOM 中。</p><p><img src="/images/angular-directive-research-part-4/element-display-in-dom.png" alt="只用 display none，雖然畫面上是隱藏的，但實際還存在於 DOM 中"></p><p>對於內容簡單的段落來說，要隱藏或移除都是無關緊要的，但若是 host element 附加到資料密集的 component 中，這樣的 component 即使隱藏起來仍會持續執行並附加自己的 element 在 DOM 上，因此也會持續進行事件的監聽，而 Angular 持續確認改變的特性可以去影響資料的綁定，無論 component 在幹嘛，Angular 都會持續進行這件事。</p><p>雖然在畫面上看不到，但 component 以及它底下所有子 components 都會佔用資源。效能和記憶體負擔都會變大，甚至反應變慢，導致使用者啥都看不到。</p><p>從正向的角度來看，要再次顯示 element 確實很快，component 先前的資料狀態也會留著且隨時可以準備顯示，就不用再重新初始化一次，畢竟這樣操作的代價可能會不小。所以單純用隱藏與顯示的話，有時候是對的。</p><p>但我們不應該總是這樣處理不顯示的內容，而是應該透過像 <code>NgIf</code> 這樣的 structural directive 把使用者看不到的 DOM elements 移除且將資源回收。<strong>這是在套用每一個內建或自訂的 structural directive 時都應該去思考的。</strong>在套用 structural directive 之前，你應該停下腳步，去思考加入與刪除 elements 或創造與銷毀 component 的後果。</p><h3 id="關於星號-前綴"><a href="#關於星號-前綴" class="headerlink" title="關於星號 ( * ) 前綴"></a>關於星號 ( * ) 前綴</h3><p>在使用 structural directive 時，你一定會注意到的星號前綴，無論是 <code>ngIf</code> 或 <code>ngFor</code>…等內建的 structural directives 名稱前面都要加上星號前綴，但為什麼要一定加上星號呢？它是做什麼的呢？</p><p>這是個 <code>ngIf</code> 範例，如果 hero 存在的話，就要顯示：</p><pre><code class="html">&lt;div *ngIf=&quot;hero&quot;&gt;&#123;&#123;hero.name&#125;&#125;&lt;/div&gt;</code></pre><p>這個星號是所謂的“語法糖”，簡化了一些複雜的語法，在 Angular 內部在解語法糖時，分成兩個階段，首先會將 <code>*ngIf=&quot;...&quot;</code> 轉譯到 template attribute，<code>template=&quot;ngIf&quot;</code>，如下：</p><pre><code class="html">&lt;div template=&quot;ngIf hero&quot;&gt;&#123;&#123;hero.name&#125;&#125;&lt;/div&gt;</code></pre><p>然後它會將 template attribute 轉換成 <code>&lt;ng-template&gt;</code> element，並且包著 host element：</p><pre><code class="html">&lt;ng-template [ngIf]=&quot;hero&quot;&gt;  &lt;div&gt;&#123;&#123;hero.name&#125;&#125;&lt;/div&gt;&lt;/ng-template&gt;</code></pre><ul><li><code>*ngIf</code> directive 移動到 <code>ng-template</code> element，這個 element 會變成 property binding <code>[ngIf]</code>。</li><li><code>&lt;div&gt;</code> 的部分，包含 class attribute 會移動到 <code>&lt;ng-template&gt;</code> element 底下。</li></ul><p>而上述這些內容都不會實際運作時呈現出來，只會顯示最後的結果到 DOM 中。</p><p><img src="/images/angular-directive-research-part-4/hero-div-in-dom.png"></p><p>Angular 在實際渲染時會消耗 <code>&lt;ng-template&gt;</code> 的內容，取而代之的是可用來除錯時參考的註解。</p><p>而 <code>NgFor</code> 和 <code>NgSwitch</code> …等 directive 也是遵循一樣的 pattern 執行的。</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>透過 <code>NgIf</code> directive 讓我們可以初步了解 structural directive 的運作機制，接著會再介紹 <code>NgFor</code> 的運作機制，看看 <code>NgFor</code> 和 <code>NgIf</code> 有何不同之處。</p><h3 id="參考來源"><a href="#參考來源" class="headerlink" title="參考來源"></a>參考來源</h3><ul><li><a href="https://angular.io/guide/structural-directives#structural-directives">Angular.io - Structural Directive</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Directive </tag>
            
            <tag> Structural Directives </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular Directive 初探 - Part.3</title>
      <link href="/2017/04/09/angular-directive-research-part-3/"/>
      <url>/2017/04/09/angular-directive-research-part-3/</url>
      
        <content type="html"><![CDATA[<p>前兩篇文章，Part.1 和 Part.2 的介紹，可以認識到如何寫一個簡單且富有彈性的 directive 並套用，這次來嘗試將 jQuery datepicker 的執行改成 directive ，並認識一下 Angular Directive 的 <code>Decorator</code> 吧！</p><h3 id="製作-jQuery-datepicker-的-directive"><a href="#製作-jQuery-datepicker-的-directive" class="headerlink" title="製作 jQuery datepicker 的 directive"></a>製作 jQuery datepicker 的 directive</h3><p>首先，npm 要先準備好 jquery 以及 bootstrap-datepicker，包含定義檔的部分：</p><pre><code>npm install jquery bootstrap @types/jquery @types/bootstrap-datepicker --save</code></pre><p>相依套件安裝完成後，到 tsconfig.app.ts 中，將 types 的陣列加上 “jquery” 字串，代表加入定義。或許你會有疑問，為什麼 <code>tsconfig.json</code> 中已經有設定 <code>typeRoots</code> 了，為何 <code>tsconfig.app.json</code> 還要再加上 “jquery”？</p><p>雖然 <code>tsconfig.app.json</code> 繼承了 <code>tsconfig.json</code> 但這裡的 types 是空陣列，因此造成 tsconfig 的 <code>typeRoots</code> 不會讀進來，在編譯的過程中就會報錯，這還滿雷的…Orz 除了在 <code>tsconfig.app.json</code>補上 <code>types</code> 之外，你也可以直接刪除 <code>types</code>，如此一來就只會抓 <code>tsconfig.ts</code> 的 <code>typeRoots</code> 囉…</p><p>npm, tsconfig 都準備好之後，把剛才安裝好的套件加入 Angular-CLI 的設定檔，主要是 jquery 的 js 以及 datepicker 的 css &amp; js 檔案要進行引入的動作：</p><span id="more"></span><pre><code class="json">&quot;styles&quot;: [        &quot;../node_modules/bootstrap/dist/css/bootstrap.css&quot;,        &quot;../node_modules/bootstrap-datepicker/dist/css/bootstrap-datepicker3.css&quot;,        &quot;styles.css&quot;],&quot;scripts&quot;: [  &quot;../node_modules/jquery/dist/jquery.js&quot;,  &quot;../node_modules/bootstrap-datepicker/dist/js/bootstrap-datepicker.js&quot;],</code></pre><p>接著透過 Angular CLI 新增一個 directive：</p><pre><code>ng g directive directives/datepicker</code></pre><p>實作 datepikcer directive：</p><pre><code class="typescript">import &#123; Directive, ElementRef, NgZone &#125; from &#39;@angular/core&#39;;@Directive(&#123;  selector: &#39;[appDatepicker]&#39;,&#125;)export class DatepickerDirective &#123;  constructor(private _elementRef: ElementRef, private _ngZone: NgZone) &#123;    const date = new Date();    this._ngZone.run(() =&gt; &#123;      jQuery(this._elementRef.nativeElement)        .datepicker(&#123;          startDate: date,          todayBtn: &#39;linked&#39;,          keyboardNavigation: false,          forceParse: false,          autoclose: true,          format: &#39;yyyy/mm/dd&#39;,        &#125;)        .on(&#39;changeDate&#39;, function (e) &#123;          console.log(e.date);        &#125;);    &#125;);  &#125;&#125;</code></pre><p>完成之後，在 template 中加入 directive 就會有效果出來囉！！！</p><pre><code class="html">&lt;div&gt;  &lt;label for=&quot;myDate&quot;&gt;選擇時間&lt;/label&gt;  &lt;input    type=&quot;text&quot;    class=&quot;form-control&quot;    id=&quot;myDate&quot;    name=&quot;myDate&quot;    appDatepicker  /&gt;&lt;/div&gt;</code></pre><p>我們也能夠透過之前提到的 <code>@HostListener</code>, <code>@Input</code> 讓 directive 可以存取參數或進行事件的處理，變得更有彈性，以上就是簡單的將第三方套件執行的程式把包裝成 directive，這麼做的好處就是可以和 Angular 較無直接關係的程式碼隔開，我們的 component 或 service 就不會變的太雜亂，套件的管理也能更容易去進行維護了。</p><h3 id="關於-Directive-decorator"><a href="#關於-Directive-decorator" class="headerlink" title="關於 Directive decorator"></a>關於 Directive decorator</h3><p>Directive decorator 可以讓你將 class 標記為 directive 並提供 metadata，以確定如何在運行時處理，實例化和使用。Directives 可以讓我們把行為附加到 DOM 中的元素中。為了可以被其他的 directive、component 或 application 所使用，Directive 必須屬於在某一個 NgModule 下。若要明確指定 directive 是 NgModule 中的成員，你必須將 directive 加在 NgModule 的 <code>declaralations</code> 屬性中。</p><p>除了透過 Directive decorator 指定的 metadata 配置之外，directive 可以藉由實作各種生命週期鉤子 ( Life-Cycle hooks ) 來控制執行時的行為。</p><p>Directive Decorator 的 metadata 屬性包含了：</p><ul><li><strong>exportAs</strong> - Component 實體在 template 中匯出的名稱</li><li><strong>host</strong> - 將 host element 綁定的事件, DOM 或 HTML 的屬性比對到 class 中的屬性</li><li><strong>inputs</strong> - 列出提供給 directive 輸入時作為資料綁定用的 class 屬性</li><li><strong>outputs</strong> - 列出其他可以訂閱輸出事件的 class 屬性</li><li><strong>providers</strong> - 列出這個 directive 及底下的 directive 可用的 providers</li><li><strong>queries</strong> - 設定可以被注入到這個 directive 的 queries</li><li><strong>selector</strong> - 用來提供在 template 中能辨識 directive 的 css selector</li></ul><h3 id="exportAs"><a href="#exportAs" class="headerlink" title="exportAs"></a>exportAs</h3><p>在 directive decorator 中加上 <code>exportAs</code> 屬性，並自訂名稱，我們就拿之前的<a href="https://github.com/jeffwu85182/angularDirectiveResearch">範例</a>的 highlight directive 當作練習，加上 <code>exportAs:&#39;appHighlight&#39;</code> 我們一樣取名為 appHighlight。</p><pre><code class="typescript">@Directive(&#123;  selector: &#39;[appHighlight]&#39;,  exportAs: &#39;appHighlight&#39;&#125;)</code></pre><p>接著直接在這個 directive 新增一個方法叫 <code>sayHello()</code>：</p><pre><code class="typescript">sayHello() &#123;  alert(&#39;Hello!!!&#39;);&#125;</code></pre><p>我們先不做太複雜的處理，單純的 alert 就好，完成後到 template 的部分，將有套 appHighlight directive 的元素後面加上範本參考變數並給予剛剛設定好的 exportAs 名稱：</p><pre><code class="html">&lt;span appHighlight bgColor=&quot;tomato&quot; #jeff=&quot;appHighlight&quot;&gt; this is span 1 &lt;/span&gt;</code></pre><p>這邊的變數名稱我就先取自己的名字 <code>#jeff</code>，為了驗證是否確實有資料，可以到 appComponent 來做確認，app component 的部分，從 <code>@angular/core</code> import <code>ViewChild</code>, <code>AfterViewInit</code>，並且將 HighlightDirective 也 import 進來，等等要派上用場：</p><pre><code class="typescript">import &#123; Component, ViewChild, AfterViewInit &#125; from &#39;@angular/core&#39;;import &#123; HighlightDirective &#125; from &#39;./directives/highlight.directive&#39;;</code></pre><p>import 之後，先在 class 中加上 <code>@ViewChild</code> 來取得我們的範本變數 <code>jeff</code>：</p><pre><code class="typescript">@ViewChild(&#39;jeff&#39;) myJeff: HighlightDirective;</code></pre><p>為了有提示可方便參考，我們指定透過 ViewChild 取得的範本變數 <code>jeff</code> 的屬性， <code>myJeff</code> 型別為 <code>HighlightDirective</code> ，這個型別需要 import HighlightDirective 作為參考，所以上一個步驟就先 import 了。</p><p>要取得 directive 的實體， AppComponent Class 需要實作 AfterViewInit，為什麼呢？之前的文章有稍微提到 directive 的生命週期，它跟 Component 一樣擁有生命週期，但 <strong>directive 會隨著套用的元素誕生而初始化，也會隨著套用的元素消失而毀滅</strong>，如果直接在 component 的 <code>constructor()</code> 或 <code>ngOnInit()</code> 是取不到的，因此要在 AppComponent 取得 directive 的實體，一定要在 View 初始化之後，所以就要實作這個生命週期掛鉤，在這個階段才取得到：</p><pre><code class="typescript">import &#123; Component, ViewChild, AfterViewInit &#125; from &#39;@angular/core&#39;;import &#123; HighlightDirective &#125; from &#39;./directives/highlight.directive&#39;;@Component(&#123;  selector: &#39;app-root&#39;,  templateUrl: &#39;./app.component.html&#39;,  styleUrls: [&#39;./app.component.css&#39;],&#125;)export class AppComponent implements AfterViewInit &#123;  @ViewChild(&#39;jeff&#39;) myJeff: HighlightDirective;  title = &#39;app works!&#39;;  ngAfterViewInit() &#123;    console.log(&#39;this is jeff&#39;, this.myJeff);  &#125;  callHelloByHighlight() &#123;    this.myJeff.sayHello();  &#125;&#125;</code></pre><p>最後建立一個 <code>callHelloByHighlight()</code> 的方法，裡面先 alert 就好。接著再回到 template 的部分，我們加一個按鈕上去，並在 <code>click</code> 的時候呼叫 <code>callHelloByHighligh()</code>：</p><pre><code class="html">&lt;div&gt;  &lt;button (click)=&quot;callHelloByHighlight()&quot;&gt;    click this button to call directive method.  &lt;/button&gt;&lt;/div&gt;</code></pre><p>重整之後，點擊按鈕，就可以呼叫 directive 實體中的方法囉！</p><h3 id="Host"><a href="#Host" class="headerlink" title="Host"></a>Host</h3><p>Directives 的 metadata Host 屬性可綁定目標元素的事件 ( Event )、DOM 或 HTML 的屬性 ( Property or Attributes ) ，其實就是 <code>@HostListener()</code> &amp; <code>@HostBinding()</code> ，寫在 metadata 是較早期的寫法，如果屬性很多的話，建議直接使用 @HostListener() &amp; @HostBinding()，避免 metadata 太大包，要進行追蹤比較不容易，雖然也有 F12 能用就是了…但用 decorator 比較清楚，這點是確定的。</p><pre><code class="typescript">@Directive(&#123;  selector: &#39;[tohValidator2]&#39;,  host: &#123;    &#39;attr.role&#39;: &#39;button&#39;,    &#39;(mouseenter)&#39;: &#39;onMouseEnter()&#39;,  &#125;,&#125;)export class Validator2Directive &#123;  role = &#39;button&#39;;  onMouseEnter() &#123;    // do work  &#125;&#125;</code></pre><p><a href="https://angular.io/docs/ts/latest/guide/style-guide.html#!#06-03">參考資料 - Angular StyleGuide</a></p><h3 id="Input-amp-Output"><a href="#Input-amp-Output" class="headerlink" title="Input &amp; Output"></a>Input &amp; Output</h3><p>其實就是 <code>@Input</code> 和 <code>@Output</code>，這也是早期的寫法了，為了方便屬性的管理，建議還是使用 decorator 將屬性寫在 Class 中比較適合。</p><h3 id="Selector"><a href="#Selector" class="headerlink" title="Selector"></a>Selector</h3><p>提供在 template 中進行辨識的 CSS selector，確定有這個 selector 才會進行套用的動作，Selector 可以是多個或是有條件性的，例如：</p><pre><code class="typescript">selector: &#39;[appHighlight], span.needHighlight&#39;;</code></pre><p>這代表說只要有套用 appHighlight attribute 或是 html class 名稱為 <code>needHighlight</code> 的元素，都會有效果。</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>透過這次的練習，我們學會要如何存取 directive 的實體，只要拿到實體物件之後，想要做什麼基本上都不會有太大的問題，就看自己的想像力囉 XD</p><p>參考資料</p><ul><li><a href="https://angular.io/docs/ts/latest/guide/style-guide.html#!#06-03">Angular.io Style Guide</a></li><li><a href="https://angular.io/docs/ts/latest/api/core/index/ViewChild-decorator.html">Angular ViewChild decorator</a></li><li><a href="https://angular.io/docs/ts/latest/api/core/index/Directive-decorator.html">Angular Directive decorator</a></li><li><a href="https://github.com/jeffwu85182/angularDirectiveResearch">練習範例</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Directive </tag>
            
            <tag> Attribute Directives </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular Directive 初探 - Part.2</title>
      <link href="/2017/04/08/angular-directive-reaserch-part-2/"/>
      <url>/2017/04/08/angular-directive-reaserch-part-2/</url>
      
        <content type="html"><![CDATA[<p><a href="/2017/03/25/angular-directive-reaserch/">上一篇文章</a>，我們初步了解 directive 基本的使用方式，這次來嘗試加入一些事件或值的傳遞，進一步體驗這強大又方便的 Angular Directive。</p><h3 id="反應由使用者發起的事件"><a href="#反應由使用者發起的事件" class="headerlink" title="反應由使用者發起的事件"></a>反應由使用者發起的事件</h3><p>目前 <code>appHighlight</code> 很單純的去改變一個元素的樣式而已，但 directive 可以做得更動態，例如我們可以指定當使用者將滑鼠移入或移出元素的時候，進行背景色的改變。在最上方從 <code>@angular/core</code> import 的部分加入 <code>HostListener</code>：</p><pre><code class="typescript">import &#123;  Directive,  ElementRef,  OnInit,  HostListener,  Input,&#125; from &#39;@angular/core&#39;;</code></pre><p>然後加入兩個 eventhandlers 負責處理 mouse enters 或 leaves 的事件，由於滑鼠的進入及離開共有兩個事件，要加上各自的 <code>@HostListener</code> decorator 共兩個：</p><pre><code class="typescript">  @HostListener(&#39;mouseenter&#39;) onMouseEnter() &#123;    this._el.nativeElement.style.backgroundColor = &#39;green&#39;;  &#125;  @HostListener(&#39;mouseleave&#39;) onMouseLeave() &#123;    this._el.nativeElement.style.backgroundColor = &#39;orange&#39;;  &#125;</code></pre><p>透過 <code>HostListener</code> 來監聽事件並進行處理，就可以讓 directive 實現更多動態的功能囉，那如果要從外部傳值進來讓 directive 進行處理的話呢？我們接著往下看。</p><span id="more"></span><h3 id="藉由-Input-進行資料綁定的方式將值傳進-Directive"><a href="#藉由-Input-進行資料綁定的方式將值傳進-Directive" class="headerlink" title="藉由 @Input 進行資料綁定的方式將值傳進 Directive"></a>藉由 @Input 進行資料綁定的方式將值傳進 Directive</h3><p>到目前為止，highlight 指定的顏色都是直接寫死 ( hard-coded ) 在 directive，但這樣還不夠，若要自訂顏色的話還要進來 directive 中進行修改，缺乏了可調整的彈性，因此我們可以透過一些方法讓 directive 去接收外面的值，如此一來 direcitve 就變得更有彈性，提供給其他開發者使用時也能快速的進行套用的動作，以加快開發速度。Time is money XD</p><h4 id="從-directive-class-開始"><a href="#從-directive-class-開始" class="headerlink" title="從 directive class 開始"></a>從 directive class 開始</h4><p>在開始之前，先在 class 中加入 <code>@Input</code> decorator 如下：</p><pre><code class="typescript">@Input() bgColor: string;</code></pre><p>記得要最上方的部分要 import <code>Input</code> 才能使用 decorator 喔 :D 接著建立一個 get 屬性方法：</p><pre><code class="typescript">// 設定一個 get，如果 bgColor 沒有值，預設給 orange  get backgroundColor() &#123;    console.log(&#39;this.bgColor&#39;, this.bgColor);    return this.bgColor || &#39;orange&#39;;  &#125;</code></pre><p>考慮到使用者在套用 directive 的時候，可能會沒給值，這時會有兩條路：<del>勝利或死亡</del> (誤) 直接出現錯誤訊息壞掉或提供預設值，站在貼心的角度，善良的開發者都應該要設個預設值才對（謎之音：廢話）因此這邊我們就先設個 get 屬性方法，直接在取值的時候決定是否給與預設值囉。接著就是將原本 hard-code 的部分改成讀取屬性的值：</p><pre><code class="typescript">this._el.nativeElement.style.backgroundColor = this.backgroundColor;</code></pre><h4 id="Template-的使用方式"><a href="#Template-的使用方式" class="headerlink" title="Template 的使用方式"></a>Template 的使用方式</h4><p>使用方式就是直接在上面加上 html attribute 並把值加上去，套用的方式有兩種表達型態：</p><pre><code class="html">&lt;span appHighlight bgColor=&quot;tomato&quot;&gt; this is span 1 &lt;/span&gt;</code></pre><p>或</p><pre><code class="html">&lt;span appHighlight [bgColor]=&quot;&#39;royalblue&#39;&quot;&gt; this is span 2 &lt;/span&gt;</code></pre><p>若沒有用中括號包起來的話，傳入的直接就是字串的值，若你的 component 有屬性是負責提供值的話，可改用第二種方法，上面第二種方法可以看到多了單引號，若沒加單引號的話，傳入的值會是屬性名稱，因此要再多補個單引號來告訴他是傳字串。</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>來個小結吧，這次我們了解要如何讓 directive 變得更有彈性，體會到 directive 帶來封裝的便利性，而且我們從頭到尾都沒有在 AppComponent 中撰寫任何程式碼，只有在 AppModule 的部分加入 <code>declarations</code> 並在 template 中的 HTML Tag 加上 attributes 就搞定一切了！做到這邊不知道你的嘴角是否不自覺的上揚，還是只有我而已？<del>對，只有你！</del></p><p>沒關係，下一篇我們試著來做一個使用第三方套件的 directive，相信一定會有更強烈的感受 XD</p><p>參考資料：</p><ul><li><a href="https://angular.io/docs/ts/latest/guide/attribute-directives.html#!#pass-values-into-the-directive-with-an-_-input_-data-binding">Angular.io Guide - Attribute Directive</a></li><li><a href="https://github.com/jeffwu85182/angularDirectiveReaserch">練習範例</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Directive </tag>
            
            <tag> Attribute Directives </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular Directive 初探 - Part.1</title>
      <link href="/2017/03/25/angular-directive-reaserch/"/>
      <url>/2017/03/25/angular-directive-reaserch/</url>
      
        <content type="html"><![CDATA[<p>最近買了一本中國的 Angular 2 簡體書，想看看有別於自己的角度，如何介紹 Angular ，再加上想深入研究 directive 的部分，因此除了 Angular 官網，也參考了這本書的部分內容，希望對大家有所幫助。</p><p><em>Directive 又翻做 “指令”，但我還是習慣直接叫 directive</em></p><p>在 Angular 的世界中，directive 扮演相當重要的角色之一，它可以在特定的 DOM 元素上執行，進而擴充這個元素的功能，為元素增加新的方法。而我們最常用的元件 ( Component )，基本上就是一個帶有 template 的 directive，它繼承了 directive，是 directive 的一個子類別，通常用來打造 UI 的部分。</p><p>在開始介紹 directive 之前，稍微複習一下 HTML 的相關內容。</p><span id="more"></span><p>HTML 檔是一個純文字檔，包含了 HTML 元素、CSS 樣式以及 JavaScript 程式碼。而 HTML 元素指的是從開始標籤到結束標籤的所有程式碼，元素的內容是開始標籤與結束標間之間的內容，例如：</p><table><thead><tr><th align="left">開始標籤</th><th align="left">元素內容</th><th align="left">結束標籤</th></tr></thead><tbody><tr><td align="left"><code>&lt;a href=&quot;www.google.com&quot;&gt;</code></td><td align="left">Hello World</td><td align="left"><code>&lt;/a&gt;</code></td></tr></tbody></table><p>HTML 標籤可以設定屬性，屬性為 HTML 元素提供了更多附加資訊。屬性一般以 <code>Property=&quot;Value&quot;</code> 的形式出現，例如 <code>href=&quot;www.google.com&quot;</code> 有時候也會只有 <code>Property</code> 而沒有 <code>Value</code> ，例如我們常用的 Input 若要設為必填項目，就會加上一個 <code>required</code> 屬性。</p><p>超連結標籤建立了一個前往其他頁面的連接，<code>href</code> 作為超連結標籤的屬性，定義了連接的目標位置。以上述為例，當使用者點擊這個超連結時，瀏覽器的 URL 會變成 <code>www.google.com</code> 並且連到 Google 的首頁。這樣的一個操作過程，主要是瀏覽器依照 HTML 的標準來進行解析，知道 <code>&lt;a&gt;</code> 標籤宣告了一個超連結，href 屬性則指定了連結的目標。Angular 中 directive 的使用方式和 HTML 元素中屬性的使用方式類似，我們可透過自定義的 <code>CustomHighlightDirective</code>來為元素加上背景色，範例如下：</p><pre><code class="html">&lt;a href=&quot;http://google.com&quot; custom-highlight&gt; Google &lt;/a&gt;</code></pre><p>先不管 custom-hightlight directive 的實作內容，從上方的範例我們可得知，只要在標籤加上屬性，就可以實現你想要的功能，這就是 directive 基本的使用方式，是不是超威的阿！ XDD</p><h3 id="Directives-概述"><a href="#Directives-概述" class="headerlink" title="Directives 概述"></a>Directives 概述</h3><p>在 Angular 的世界中，Directives 有分三種類型：</p><ol><li>元件 ( Components ) — 擁有 template 的 directives</li><li>結構類 directive ( Structural directives ) — 改變 view 的結構</li><li>屬性類 directive ( Attribute directives ) — 改變元素 ( Element )、元件 ( Component) 或另一個 directive 的外觀或行為</li></ol><p><code>Components</code> 是最常見的 directive， Angular 開發的應用程式基本上就是一群 Component 所組起來的。而結構類 directive 則是藉由加入及移除 DOM 元素 ( Element ) 來改變 DOM layout，最常見的  <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngFor">NgFor</a>  及  <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngIf">NgIf</a> 就是結構型 directive。屬性類 directive 顧名思義，使用方式就像 element 的 attribute 一樣，舉例來說，在官網  <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html">Template Syntax</a>  這篇文章中提到內建的  <a href="https://angular.io/docs/ts/latest/guide/template-syntax.html#ngStyle">NgStyle</a> directive 就是屬性類 directive，可實現同時改變多個元素的樣式。</p><h3 id="建立一個簡單的-Attribute-Directive"><a href="#建立一個簡單的-Attribute-Directive" class="headerlink" title="建立一個簡單的 Attribute Directive"></a>建立一個簡單的 Attribute Directive</h3><p>首先我們透過 angular-cli 進行練習，輸入指令 <code>ng g d directives/highlight</code> 就可快速建立 directive 囉！<br>建立好 directive 之後，可以看到 directive 的內容如下：</p><pre><code class="typescript">import &#123; Directive &#125; from &#39;@angular/core&#39;;@Directive(&#123;  selector: &#39;[appHighlight]&#39;,&#125;)export class HighlightDirective &#123;  constructor() &#123;&#125;&#125;</code></pre><p>從 <code>@angular/core</code> 將 <code>Directive</code> import 進來，這樣才能使用 Directive 的 <code>decorator</code>，目前的 decorator metadata 只有 selector 的部分設為 <code>[appHighlight]</code> 。<code>@Directive</code> 需要透過 CSS selector 來協助辨識在 template 中與 directive 有關聯的 HTML，這裡 Attribute 當作 CSS selector 使用的方式為名稱的前後加上中括號例如： <code>[AttributeName]</code> 。意思是在 Angular 的專案底下，無論是哪個 component 的 template，若要使用 highlightDirective，必須在 element 中加上 appHighlight 的 attribute 才會有作用。</p><pre><code class="html">&lt;span appHighlight&gt;這樣才會有作用喔！&lt;/span&gt;</code></pre><h4 id="為何不直接取作-“highlight”"><a href="#為何不直接取作-“highlight”" class="headerlink" title="為何不直接取作 “highlight” ?"></a>為何不直接取作 “highlight” ?</h4><p>的確， <code>highlight</code> 的命名比 <code>appHighlight</code> 更簡潔且能正常執行，在實務上最好還是加上前綴，確保不會和標準的 HTML attribute 發生衝突，這也能降低在使用第三方套件時發生命名衝突的風險。此外，我們自訂的前綴不能用 <strong>ng</strong> 作為開頭，因為這是 Angular 自己要用的，如果跟著用 ng 作為前綴的話，也可能會造成 bug 導致除錯的困難，因此 Angular-CLI 很貼心的（真的太貼心惹~），一開始任何的 component 或 directive 在建立時 selector 都會自動加上前綴，為了就是避免我們自己埋了地雷卻不知道的窘境發生。</p><p>如果你沒修改過 <code>.angular-cli.json</code> 中 prefix 設定，預設的 prefix 是 app，因此在透過 CLI 產生的 directive selector 預設都是 app 開頭的，接著在 <code>constructor </code> 將 <code>ElementRef</code> 進行注入的動作（ 參考下方範例 ），藉此存取目標的 DOM Element。</p><p><em>關於 decorator 想深入了解，可參考 Kevin Yang 的文章 <a href="http://blog.kevinyang.net/2017/01/30/angular2-decorators/">自訂 Decorators</a></em></p><h4 id="實作-highlightDirective-的功能"><a href="#實作-highlightDirective-的功能" class="headerlink" title="實作 highlightDirective 的功能"></a>實作 highlightDirective 的功能</h4><p>直接看 code 吧：</p><pre><code class="typescript">import &#123; Directive, ElementRef, OnInit &#125; from &#39;@angular/core&#39;;@Directive(&#123;  selector: &#39;[appHighlight]&#39;,&#125;)export class HighlightDirective implements OnInit &#123;  constructor(private _el: ElementRef) &#123;    // 注入 elementRef 就可以取得 DOM    console.log(&#39;directive init,&#39;, this._el);  &#125;  ngOnInit() &#123;    // 設定 CSS 樣式    this._el.nativeElement.style.backgroundColor = &#39;orange&#39;;    this._el.nativeElement.style.color = &#39;white&#39;;    this._el.nativeElement.style.display = &#39;inline-block&#39;;    this._el.nativeElement.style.width = &#39;120px&#39;;    this._el.nativeElement.style.height = &#39;40px&#39;;    this._el.nativeElement.style.textAlign = &#39;center&#39;;    this._el.nativeElement.style.lineHeight = &#39;2.5&#39;;  &#125;&#125;</code></pre><p>上面這段程式碼基本上就是注入 <code>ElementRef</code> 後即可存取目標的 DOM，藉此進行操作，既然我們是要做一個 highlight 的功能，我們只需要針對目標設定 CSS 樣式即可，樣式的設定方式透過上方的範例可以知道，在注入的 elementRef 中，帶有 nativeElement 的屬性，這個屬性可以讓我們進行 DOM 的存取及操作。</p><p>這時你或許會有一些疑問，style 的屬性名稱怎麼跟 CSS 的不太一樣，這邊帶一個觀念，英文的 Property 及 Attribute 我們中文翻譯都叫做<strong>屬性</strong>。但事實上這兩個指的完全是不同的東西，來看這擷取自 stackoverflow 的一段回文：</p><blockquote><p><strong>Attributes</strong> are defined by <strong>HTML</strong>.<br><strong>Properties</strong> are defined by <strong>DOM</strong>.</p></blockquote><p><em>Some HTML attributes have 1:1 mapping onto properties. <strong>id</strong> is one example of such. Some do not (e.g. the <code>value attribute</code> specifies the initial value of an input, but the <code>value property</code> specifies the <strong>current</strong> value).</em></p><p>Attributes 是從 HTML 定義來的，而 Properties 則是從 DOM 定義，有些 HTML attributes 的屬性是 1:1 的比對到 DOM 的 properties 中，例如 <code>id</code> 就是，兩者的屬性都叫做 <code>id</code>，但有些則不是，例如 value attribute 指定的是 input 中初始的預設值，而 value property 指的卻是目前的值。這觀念一定要釐清！才不會一直鬼打牆喔 XD</p><h3 id="套用-Attribute-Directive"><a href="#套用-Attribute-Directive" class="headerlink" title="套用 Attribute Directive"></a>套用 Attribute Directive</h3><p>在套用之前，先來觀察一下 angular-cli 在幫我們建立 directive 時，做了哪些事情。Angular CLI 很貼心的幫我們在 <code>app.module.ts</code> 的 declarations 加入了剛剛新建的 directive，所以 directive 產生之後，實作的部份搞定，就可以直接在 template 中使用了，揪甘心欸。套用的方式就跟一開始提到的一樣簡單，在 HTML Tag 加上 <code>appHighlight</code> Attribute 就會有作用囉！</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>Angular 的 directive 真的很強大 BJ4 ( 不解釋 )，透過 directive 我們可以將很多東西進行封裝的動作，例如第三方套件的使用，透過 directive 封裝後，只要在 template 加上 Attribute 就會有作用，而且擁有自己的生命週期，它會隨著 DOM 產生而誕生，隨著 DOM 消失而毀滅。一切是那麼的輕鬆愉快 ;-)</p><p>參考資料：</p><ul><li><a href="https://angular.io/docs/ts/latest/guide/attribute-directives.html">Angular.io Guide - Attribute Directive</a></li><li><a href="http://stackoverflow.com/questions/19246714/html-attributes-vs-properties">StackOverflow - HTML Attributes VS Properties</a></li><li><a href="https://github.com/jeffwu85182/angularDirectiveReaserch">練習範例</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Directive </tag>
            
            <tag> Attribute Directives </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular FormGroup 取得所有 formControl 的值</title>
      <link href="/2017/02/23/formGroup-getRawValue/"/>
      <url>/2017/02/23/formGroup-getRawValue/</url>
      
        <content type="html"><![CDATA[<h2 id="消失的欄位資料"><a href="#消失的欄位資料" class="headerlink" title="消失的欄位資料"></a>消失的欄位資料</h2><p>最近在專案上遇到表單處理的問題，主要是 UI 上的需求是有條件的 disabled 控制項，換句話說，在某些情況下，指定的表單控制項在畫面上要是鎖定的狀態，但是在呼叫 API 的時候還是得要取得欄位鎖定的內容。強者我同事，在準備回傳給 API 的物件資料時，偶然發現到控制項在 disabled 的狀態下，FormGroup 是取不到 disabled 欄位 Value 的，究竟那消失的欄位到底是去哪了？明明在畫面上，DOM 也有值在裡面，為何就是取不到？</p><p>原來…欄位一直都在，從沒離開過。</p><span id="more"></span><p><img src="/images/formGroup-getRawValue/missing.jpg" alt="消失的欄位到哪去了？"></p><p>雖然表單的控制項在畫面上是鎖住的狀態，但在 Call API 送資料的時候還是會用到，要如何取得因 disabled 而“被消失”的控制項的值呢？遇到這種感覺被雷雷的問題該怎麼辦？當然是先去查文件啦！</p><h3 id="找回失蹤的欄位資料"><a href="#找回失蹤的欄位資料" class="headerlink" title="找回失蹤的欄位資料"></a>找回失蹤的欄位資料</h3><p>原來，在預設的情況，Angular 的 <code>FormGroup</code> 為我們提供了貼心的過濾功能，它會默默地協（ㄌ ㄟ ˊ）助（ㄉㄠ ˋ）你，Angular 認為 Disabled 狀態下的 FormControl 是不需要在 FormGroup 的 Value 屬性中顯示的。</p><p>其實直接透過 FormControl 的 Value 是找得到資料的，若真的非要不可的話，只要有心你也可以直接去取得 disabled 的 FormControl Value。以 template-driven 開發模式舉例，在表單的 <code>fullname</code> 子群組下找到 firstName 的控制項並取值：</p><pre><code class="typescript">f.form.controls.fullName.controls.first;</code></pre><p>但這樣會變得很長，我只是要取個值，而且還只有兩層的情況下就這麼長了…</p><p>好在，官方技術文件的 FormGroup 頁面介紹中，在底下的屬性及方法介紹的最後找到了一個方法：</p><h4 id="getRawValue-any"><a href="#getRawValue-any" class="headerlink" title="getRawValue() : any"></a>getRawValue() : any</h4><p>The aggregate value of the <a href="https://angular.io/docs/ts/latest/api/forms/index/FormGroup-class.html"><code>FormGroup</code></a>, including any disabled controls.<br>取得整個 FormGroup 的值，包含任何被 disabled 的控制項。</p><blockquote><p>If you’d like to include all values regardless of disabled status, use this method. Otherwise, the <code>value </code> property is the best way to get the value of the group.</p></blockquote><p>相信看到這裡，真相也就水落石出了。如果想要取得表單子群組的所有值，包含 disabled 狀態的控制項，可以透過這個方法，但基本上使用 formGroup 的 <code>value</code> 屬性才是最好的取值方式。</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><p>本日小品文感想，遇到問題時不要忙著靠直覺去亂寫，先去查查文件，或許答案就在裡面，甚至會有意想不到的收穫。</p><p><a href="https://plnkr.co/edit/ASkNmDyvxaKx3V6rbNIM?p=preview">參考範例</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Forms </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular-CLI 設定 Global</title>
      <link href="/2017/02/21/angular-cli-global/"/>
      <url>/2017/02/21/angular-cli-global/</url>
      
        <content type="html"><![CDATA[<h2 id="介紹-Global-設定"><a href="#介紹-Global-設定" class="headerlink" title="介紹 Global 設定"></a>介紹 Global 設定</h2><p>上次介紹了 Angular-CLI JSON 設定檔中 assets 的設定，讓我們不需再逐一的手動<del>人肉</del>複製需要的 assets，這次來介紹在透過 Angular-CLI 進行專案開發時，與全域有關的設定，主要有三種：<code>Global Library Installation</code>, <code>Global Scripts</code>, <code>Global Styles</code>。接下來我一樣參考了 Github 上的文件來做整理與介紹。藉此讓大家可以更了解 Angular CLI 的設定，以節省時間及方便專案內容的管理。</p><p><img src="/images/angular-cli-global/cover.jpg"></p><span id="more"></span><h3 id="Global-Library-Installation"><a href="#Global-Library-Installation" class="headerlink" title="Global Library Installation"></a>Global Library Installation</h3><p>顧名思義就是全域的 JS 程式庫 ( Library ) 安裝，例如：相信大家一定很常用的 <code>jQuery</code>, <code>Bootstrap</code> 等 Framework，像這類 Framework 或 Library 通常需要在 html 中加入 <code>script</code> 標籤來進行載入到全域的 scope 下，而我們可以透過 Angular-CLI 的 JSON 設定檔做設定，我們知道 JSON 的格式本身就和 JS 的物件格式是一樣的，都有屬性 ( Property ) 與值 ( Value )，因此這邊我們可以使用 <code>.angular-cli.json</code> 中的 <code>apps[0].scripts</code> 以及 <code>apps[0].styles</code> 的屬性來進行設定。</p><p>就以 Bootstrap 4 來當範例吧，要使用 Bootstrap 4 之前，我們需要先做一些前置準備：</p><p>首先，透過 <code>npm</code> 來安裝 Bootstrap 4：</p><pre><code>npm install bootstrap@next --save</code></pre><p>安裝完成後，將需要的 script 檔案加到 <code>apps[0].scripts</code> 屬性的陣列中：</p><pre><code class="json">&quot;scripts&quot;: [  &quot;../node_modules/jquery/dist/jquery.js&quot;,  &quot;../node_modules/tether/dist/js/tether.js&quot;,  &quot;../node_modules/bootstrap/dist/js/bootstrap.js&quot;],</code></pre><p>最後再加上 Bootstrap 的 CSS 檔案到 <code>apps[0].styles</code> 屬性的陣列中：</p><pre><code class="json">&quot;styles&quot;: [  &quot;../node_modules/bootstrap/dist/css/bootstrap.css&quot;,  &quot;styles.css&quot;],</code></pre><p>如果這時候 ng serve 正在執行的話，請重新執行 <code>ng serve</code> ，然後試著在 Template 中加入我們熟悉的 Bootstrap 元件預覽看看囉，未來若有其他的程式庫要加入，也是一樣的方式加入即可，就是這麼的輕鬆方便 :)</p><h3 id="Global-Scripts"><a href="#Global-Scripts" class="headerlink" title="Global Scripts"></a>Global Scripts</h3><p>除了全域的框架或程式庫外，如果自訂的 JS 檔也要在 <code>index.html</code> 中新增 <code>script</code> 標籤在全域執行的話，加入的方式和上方介紹如何加入 Bootstrap 的方式是相同的。</p><p>例如 Google 分析 ( Google Analytics ) 或 FB SDK 等等相關的程式碼片段，要加入的話一樣在 <code>apps[0].scripts</code> 的屬性陣列中加入檔案的路徑即可：</p><pre><code class="json">&quot;scripts&quot;: [  &quot;global-script.js&quot;,],</code></pre><p>我們也可以在建置輸出的時候進行檔名的變更，或者需要延遲載入的時候，可以使用以下的物件格式加到 <code>apps[0].scripts</code> 的陣列中：</p><pre><code class="json">&quot;scripts&quot;: [  &quot;global-script.js&quot;,  &#123; &quot;input&quot;: &quot;lazy-script.js&quot;, &quot;lazy&quot;: true &#125;,  &#123; &quot;input&quot;: &quot;pre-rename-script.js&quot;, &quot;output&quot;: &quot;renamed-script&quot; &#125;,],</code></pre><p><code>input</code> 指的是目標文件的路徑及檔名，<code>output</code> 則是要輸出的路徑及檔名，<code>lazy</code> 則是帶布林值，設定是否延遲載入。</p><h3 id="Global-Styles"><a href="#Global-Styles" class="headerlink" title="Global Styles"></a>Global Styles</h3><p>透過 Angular-CLI 建立的空專案中，預設提供一個 <code>styles.css</code> 檔案，這個檔案主要是提供使用者加入全域的 CSS 樣式並且支援 CSS imports 的功能，當然，在前端開發，CSS 預處理器 ( CSS Preprocessor ) 相信是大家的好朋友，少了它，要進行切版真的會很不方便<del>藍瘦香菇</del>，因此在建立空專案的時候，記得要加上 <code>--style=scss</code> 的參數，一樣的方式，你也能選擇 <code>sass/less/styl</code> 等熟悉的預處理器，讓你能愉快的進行切版。</p><p>我們一樣可以透過<code>.angular-cli.json</code> 中的 <code>app[0].styles</code> 屬性加入其他的全域樣式，這些樣式檔會在執行的時候，以新增 <code>link</code> 標籤進行讀取，載入到 <code>index.html</code> 中：</p><pre><code class="json">&quot;styles&quot;: [  &quot;styles.css&quot;,  &quot;more-styles.css&quot;,],</code></pre><p>我們也可以和 <code>scripts</code> 的設定一樣，以物件格式來設定變更檔名及延遲載入的需求：</p><pre><code class="json">&quot;styles&quot;: [  &quot;styles.css&quot;,  &quot;more-styles.css&quot;,  &#123; &quot;input&quot;: &quot;lazy-style.scss&quot;, &quot;lazy&quot;: true &#125;,  &#123; &quot;input&quot;: &quot;pre-rename-style.scss&quot;, &quot;output&quot;: &quot;renamed-style&quot; &#125;,],</code></pre><p>透過 Angular-CLI 的自動化設定，協助我們節省很多瑣碎的時間，這些時間久了湊起來也是可以做很多事情的，除了努力工作之外，更要學會如何聰明工作，這也是很重要的一門課題喔！</p><p>以上這些介紹，希望可以為大家節省更多時間，寫出可讀性高，漂亮又好維護的程式碼 XD</p><h3 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h3><ul><li><a href="https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/global-lib.md">Angular-CLI - global-lib.md</a></li><li><a href="https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/global-scripts.md">Angular-CLI - global-scrips.md</a></li><li><a href="https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/global-styles.md">Angular-CLI - global-styles.md</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Angular-CLI </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular-CLI 設定 - Assets</title>
      <link href="/2017/02/20/angular-cli-config-assets/"/>
      <url>/2017/02/20/angular-cli-config-assets/</url>
      
        <content type="html"><![CDATA[<h2 id="介紹-assets-設定"><a href="#介紹-assets-設定" class="headerlink" title="介紹 assets 設定"></a>介紹 assets 設定</h2><p>我們在使用 Angular-CLI 進行開發的時候，一定要會設定 <code>.angular-cli.json</code>，為了協助大家了解，究竟 angular-cli 的設定檔中的屬性是要設定什麼？我直接參考 Github 的文件來為大家做介紹，就先從 <code>assets</code> 開始吧！</p><p>angular-cli.json 中的 assets 屬性存放的是一個陣列，這個陣列會列出有哪些檔案或資料夾是 angular-cli 在建置 ( <code>ng build</code> ) 時需要一起複製到專案輸出作為準備佈署的資料夾（ 預設是 <code>dist</code> ）中。</p><p>在新增專案時，預設的 assets 內容如下，意思是在建置時，路徑 <code>src/assets</code> 的目錄和檔案，以及 <code>src/favicon.ico</code> 的檔案會進行複製。</p><pre><code class="json">&quot;assets&quot;: [  &quot;assets&quot;,  &quot;favicon.ico&quot;]</code></pre><p>除了以字串的型態表示之外，我們也能以物件的方式來做進一步的設定，底下的物件陣列和上方預設的內容是相同的：</p><pre><code class="json">&quot;assets&quot;: [  &#123; &quot;glob&quot;: &quot;**/*&quot;, &quot;input&quot;: &quot;./assets/&quot;, &quot;output&quot;: &quot;./assets/&quot; &#125;,  &#123; &quot;glob&quot;: &quot;favicon.ico&quot;, &quot;input&quot;: &quot;./&quot;, &quot;output&quot;: &quot;./&quot; &#125;,]</code></pre><p><code>glob</code> 是一個叫  <a href="https://github.com/isaacs/node-glob">node-glob</a>  的套件使用 <code>input</code> 來當作基礎目錄，以相對路徑的方式表示，<code>input</code> 相對於專案存放原始碼根目錄的位置，也就是相同檔案 <code>angular-cli.json</code>中的 <code>root</code> 屬性指定的路徑 ( 預設為 <code>src/</code> )，而 <code>output</code> 設定的是相對於建置後，輸出的檔案要存放的位置，也就是 <code>outDir</code> 屬性指定的路徑 ( 預設為 <code>dist</code> )。</p><p>相對路徑讓我們可以使用這些進階的設定方式，從專案外部的位置複製需要的資料夾或檔案，例如：從 node_modules 來複製需要的項目：</p><pre><code class="json">&quot;assets&quot;: [  &#123; &quot;glob&quot;: &quot;**/*&quot;, &quot;input&quot;: &quot;../node_modules/some-package/images&quot;, &quot;output&quot;: &quot;./some-package/&quot; &#125;,]</code></pre><p>上方的範例指的是，當建置時，要從<code>node_modules/some-package/</code>  複製 <code>images</code> 資料夾及其內容到輸出的資料夾  <code>dist/some-package/</code> 中。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>透過 angular-cli.json 的 assets 設定，可以讓我們在建置時更有彈性，就不需要自己去尋找檔案做人肉複製貼上了！</p><h3 id="參考來源"><a href="#參考來源" class="headerlink" title="參考來源"></a>參考來源</h3><p><a href="https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/asset-configuration.md">Angular-CLI - asset-configuration</a></p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Angular-CLI </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>讓萬惡的舊 IE 支援 Angular 2</title>
      <link href="/2017/02/19/old-ie-support/"/>
      <url>/2017/02/19/old-ie-support/</url>
      
        <content type="html"><![CDATA[<h2 id="萬惡的根源"><a href="#萬惡的根源" class="headerlink" title="萬惡的根源"></a>萬惡的根源</h2><p>西元 2017 年，在網站技術蓬勃發展的情況下，各種技術不斷的推陳出新，目的讓網站的效能變得更好，開發模式的優化，對使用者的使用經驗變得更友善，但，世界不可能是完美的，有個萬惡的根源到現在都還無法根除，它讓許多開發者曾經頭痛不已，每次認為告一段落的時候，它，總是會讓許多網站開發者面臨絕望，它就是 <strong>Internet Explorer</strong> 瀏覽器。</p><p>Angular 2 也是一樣，對於舊版的 IE 預設的情況下是沒有支援的，但生命總是會找到屬於自己的出口，在許多熱情的開發者不斷的努力情況下，出現了針對讓舊版瀏覽器支援新程式碼的函式庫，我們稱這些套件為 <strong>Polyfill</strong>。</p><span id="more"></span><p><img src="/images/old-ie-support/cover.jpg" alt="當你以為你做完了的時候，你發現還有 IE 要處理"></p><h2 id="Angular-2-Polyfill"><a href="#Angular-2-Polyfill" class="headerlink" title="Angular 2 Polyfill"></a>Angular 2 Polyfill</h2><p>根據 Angular 官網的技術文件中瀏覽器支援說明的部分，目前最多能支援到 IE 9：</p><p><img src="/images/old-ie-support/angular-browser-support.png" alt="Angular 2 目前對於各版本瀏覽器的支援度一覽"></p><p>Angular 2 是基於最新的 web paltform 標準進行開發的，要能支援多樣的瀏覽器版本著實是一大挑戰，因為這些瀏覽器不一定能支援現代瀏覽器的所有新功能，而我們在專案開發時，若遇到支援 IE 的需求也不得不勇敢的面對，而我們可以藉由在 <code>index.html</code> 載入 <strong>Polyfill</strong> 來補足一些舊版瀏覽器不支援的功能，如下：</p><pre><code class="html">&lt;script src=&quot;node_modules/core-js/client/shim.min.js&quot;&gt;&lt;/script&gt;</code></pre><p>除了對特定瀏覽器缺少的功能加入 polyfill 之外，若有使用到其他功能但舊版瀏覽器不支援的情況，也需要再額外加入 polyfill，以下的表格可以協助你了解對於缺少的功能來加入特定的 polyfill 進行讀取，而這些特定的 polyfill 則依據我們設定的瀏覽器相容範圍以及有使用到的功能來進行追加的動作。</p><p>這些建議的 polyfill 是官網建議已知能讓 Angular 應用完整執行的項目，也有可能有用到其他功能是不在這清單上的，要知道，這些 <strong>polyfill 是沒有神奇魔力可以讓一個又老又慢的瀏覽器變的跟新的一樣快</strong>。</p><h3 id="必裝的-polyfill"><a href="#必裝的-polyfill" class="headerlink" title="必裝的 polyfill"></a>必裝的 polyfill</h3><p>要能正常執行 Angular 應用，這些 polyfill 是一定要加入在每個支援的瀏覽器上的：</p><table><thead><tr><th>Polyfills required</th><th>Browsers (desktop &amp; mobile)</th></tr></thead><tbody><tr><td>None</td><td>Chrome, Firefox, Edge, Safari 9+</td></tr><tr><td><a href="https://github.com/zloirock/core-js">ES6</a></td><td>Safari 7 &amp; 8, IE10 &amp; 11, Android 4.1+</td></tr><tr><td><a href="https://github.com/eligrey/classList.js">ES6classList</a></td><td>IE9</td></tr></tbody></table><h3 id="選擇性功能以及搭配的-polyfill"><a href="#選擇性功能以及搭配的-polyfill" class="headerlink" title="選擇性功能以及搭配的 polyfill"></a>選擇性功能以及搭配的 polyfill</h3><p>Angular 中的一些功能可能會需要額外的 polyfill，例如，<code>animation library</code> 依靠標準的 web animation API，目前只有 Chrome 以及 Firefox 存在，因此若需要在其他瀏覽器使用 animations，我們就需要加入 polyfill 來支援。以下這些功能可能需要額外加入 polyfill：</p><table><thead><tr><th>Feature</th><th>Polyfill</th><th>Browsers (desktop &amp; mobile)</th></tr></thead><tbody><tr><td><a href="https://angular.io/docs/ts/latest/guide/animations.html">Animations</a></td><td><a href="https://angular.io/docs/ts/latest/guide/browser-support.html#web-animations">Web Animations</a></td><td>All but Chrome and FirefoxNot supported in IE9</td></tr><tr><td><a href="https://angular.io/docs/ts/latest/api/common/index/DatePipe-pipe.html">Date</a>, <a href="https://angular.io/docs/ts/latest/api/common/index/CurrencyPipe-pipe.html">currency</a>, <a href="https://angular.io/docs/ts/latest/api/common/index/DecimalPipe-pipe.html">decimal</a> and <a href="https://angular.io/docs/ts/latest/api/common/index/PercentPipe-pipe.html">percent</a> pipes</td><td><a href="https://github.com/andyearnshaw/Intl.js">Intl API</a></td><td>All but Chrome, Firefox, Edge, IE11 and Safari 10</td></tr><tr><td><a href="https://angular.io/docs/ts/latest/api/common/index/NgClass-directive.html">NgClass</a> on SVG elements</td><td><a href="https://github.com/eligrey/classList.js">classList</a></td><td>IE10, IE11</td></tr><tr><td><a href="https://angular.io/docs/ts/latest/guide/server-communication.html">Http</a> when sending and receiving binary data</td><td><a href="https://github.com/inexorabletash/polyfill/blob/master/typedarray.js">Typed Array</a> <a href="https://github.com/eligrey/Blob.js">Blob</a><a href="https://github.com/francois2metz/html5-formdata">FormData</a></td><td>IE 9</td></tr></tbody></table><h3 id="建議的-polyfill"><a href="#建議的-polyfill" class="headerlink" title="建議的 polyfill"></a>建議的 polyfill</h3><p>這些是用在測試框架本身的 polyfill，可以參考上表的 Angular 功能以及要支援的瀏覽器來選擇：</p><table><thead><tr><th>Polyfill</th><th>Licence</th><th>Size*</th></tr></thead><tbody><tr><td><a href="https://github.com/zloirock/core-js">ES6</a></td><td>MIT</td><td>27.4KB</td></tr><tr><td><a href="https://github.com/eligrey/classList.js">classList</a></td><td>Public domain</td><td>1KB</td></tr><tr><td><a href="https://github.com/andyearnshaw/Intl.js">Intl</a></td><td>MIT &#x2F; Unicode licence</td><td>13.5KB</td></tr><tr><td><a href="https://github.com/web-animations/web-animations-js">Web Animations</a></td><td>Apache</td><td>14.8KB</td></tr><tr><td><a href="https://github.com/inexorabletash/polyfill/blob/master/typedarray.js">Typed Array</a></td><td>MIT</td><td>4KB</td></tr><tr><td><a href="https://github.com/eligrey/Blob.js">Blob</a></td><td>MIT</td><td>1.3KB</td></tr><tr><td><a href="https://github.com/francois2metz/html5-formdata">FormData</a></td><td>MIT</td><td>0.4KB</td></tr></tbody></table><h2 id="透過-Angular-CLI-設定-Polyfill"><a href="#透過-Angular-CLI-設定-Polyfill" class="headerlink" title="透過 Angular-CLI 設定 Polyfill"></a>透過 Angular-CLI 設定 Polyfill</h2><p>若專案是透過 Angular-CLI 進行開發，你或許會覺得奇怪，為什麼我們新增完專案後直接 <code>ng serve</code> 後就能馬上在瀏覽器上看到了？原來，在我們使用 <code>ng new</code> 建立專案的時候，Angular-CLI 已經在專案目錄下新增了一個名為 <a href="https://github.com/angular/angular-cli/blob/137a0dea183d48b28bdec2d1e65b3a9addcd812c/packages/%40angular/cli/blueprints/ng2/files/__path__/polyfills.ts"><code>polyfills.ts</code></a> 的檔案，其實這個檔案的內容已經準備好相關的 polyfill 了，而且上面還有很親切的註解，我們只要針對需要用到的 import 項目解除註解即可 。</p><h2 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h2><p>最近筆者在專案開發上遇到要支援 IE 9 的需求，一開始我們針對瀏覽器顯示的錯誤訊息來尋找對應的 polyfill，殊不知 <a href="https://angular.io/docs/ts/latest/guide/browser-support.html">Angular 官網文件</a>已經有提到舊版瀏覽器支援的問題，按照官網技術文件的提示，將有使用到的 Angular 功能逐一補上 polyfill，總算能正常執行了 Orz，後來在 Angular CLI 建立的專案中發現預設已經有提供 polyfills.ts，忽然有一種繞了一圈的感覺，但，事情能順利解決最重要啦 XD 畢竟這些都是一趟努力的旅程，LOL</p><h3 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h3><ul><li><a href="https://hacks.mozilla.org/2014/11/an-easier-way-of-using-polyfills/">An easier way of using polyfills</a></li><li><a href="https://github.com/angular/angular-cli/blob/137a0dea183d48b28bdec2d1e65b3a9addcd812c/packages/%40angular/cli/blueprints/ng2/files/__path__/polyfills.ts">Angular-CLI polyfills.ts</a></li><li><a href="https://angular.io/docs/ts/latest/guide/browser-support.html">Angular.io - Browser Support</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Polyfill </tag>
            
            <tag> FuxkIE </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular Forms 介紹：Model-Driven Forms</title>
      <link href="/2016/10/26/angular-model-driven/"/>
      <url>/2016/10/26/angular-model-driven/</url>
      
        <content type="html"><![CDATA[<h2 id="面對各種神奇需求的表單，要能克服重重挑戰，就用-Model-Driven-實作吧！"><a href="#面對各種神奇需求的表單，要能克服重重挑戰，就用-Model-Driven-實作吧！" class="headerlink" title="面對各種神奇需求的表單，要能克服重重挑戰，就用 Model-Driven 實作吧！"></a>面對各種神奇需求的表單，要能克服重重挑戰，就用 Model-Driven 實作吧！</h2><p>上一篇我們已經介紹了如何使用 Template-Driven 進行表單的開發，對於大部分簡易的表單，搭配預設提供的 Validator Directive，就能輕鬆的實作出可驗證、有提示互動的表單。但人生總不會是都那麼的簡單，在實戰開發上，我們往往會遇到各種神奇的表單需求，可能是多個欄位之間會有複雜的驗證，抑或是動態的驗證，甚至連表單的欄位是動態的！</p><p>對於這些奇葩的需求，相信有遇過的朋友都知道，光靠是 Template-Driven 是不夠的，雖然 Template-Driven 也可以實作出複雜的表單，但會造成 Template 會非常的髒亂，而且開發過程中會在 Template 與 Component 之間來回進行，這樣的開發會很沒有效率，而且做到後面可能頭都昏了。</p><p>生命是有限的，我們不該把生命浪費在這奇葩的表單上，因此 Angular 2 提供了另一種表單的實作方式： <strong>Model-Driven Forms</strong> ！話不多說，直接開始吧！首先，我們直接透過 Angular CLI 新增一個專案：</p><p><a href="https://github.com/jeffwu85182/model-driven-demo">範例</a></p><blockquote><p>範例的部分已經更新到 V16，同時也調整了控制項取得的方式。<br>主要為 <code>form.get(&#39;firstName&#39;)</code> 取代 <code>form.controls.firstName</code> 的用法。<br>驗證條件檢查則是 <code>form.get(&#39;firstName&#39;).errors?.required</code> 取代 <code>form.controls.firstName.errors?.[&#39;required&#39;]</code> 的用法。</p></blockquote><span id="more"></span><pre><code class="shell">ng new model-driven-demo -sncd model-driven-demo</code></pre><p>接著為了有效節省時間，在新增指令的後面加上 <code>-sn</code> 略過 npm install ，直接用 yarn 來安裝 npm !!</p><pre><code class="shell">yarn</code></pre><p>安裝完成之後，執行專案</p><pre><code class="shell">ng serve</code></pre><p>有看到 <strong>app works!</strong> 字樣就代表初步執行成功囉！</p><h3 id="Import-ReactiveFormsModule"><a href="#Import-ReactiveFormsModule" class="headerlink" title="Import ReactiveFormsModule"></a>Import ReactiveFormsModule</h3><p>我們在實作 template-driven forms 的時候，會在 app.module import <strong>FormsModule</strong>，現在我們要用 mode-driven 的方式來開發，因此我們要在 app.module 中 import <strong>ReactiveFormsModule</strong> ，才能進行 model-driven 的實作。</p><pre><code class="typescript">import &#123; BrowserModule &#125; from &#39;@angular/platform-browser&#39;;import &#123; NgModule &#125; from &#39;@angular/core&#39;;import &#123; ReactiveFormsModule &#125; from &#39;@angular/forms&#39;;import &#123; HttpModule &#125; from &#39;@angular/http&#39;;import &#123; AppComponent &#125; from &#39;./app.component&#39;;@NgModule(&#123;  declarations: [AppComponent],  imports: [BrowserModule, ReactiveFormsModule, HttpModule],  providers: [],  bootstrap: [AppComponent],&#125;)export class AppModule &#123;&#125;</code></pre><p>在開始之前，先準備一份純 HTML 的表單 template：</p><pre><code class="html">&lt;!-- Model-Driven --&gt;&lt;div class=&quot;container&quot;&gt;  &lt;form [formGroup]=&quot;form&quot;&gt;    &lt;div class=&quot;profile&quot;&gt;      &lt;h2&gt;基本資料&lt;/h2&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入名字&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;firstName&quot;          name=&quot;firstName&quot;          placeholder=&quot;請輸入名字&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入英文名&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;nickName&quot;          name=&quot;nickName&quot;          placeholder=&quot;請輸入英文名&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入Email&lt;/label&gt;        &lt;input          type=&quot;email&quot;          class=&quot;form-control&quot;          id=&quot;email&quot;          name=&quot;email&quot;          placeholder=&quot;請輸入Email&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入電話&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;keyNum&quot;          name=&quot;keyNum&quot;          placeholder=&quot;請輸入電話&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入生日&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;birthday&quot;          name=&quot;birthday&quot;          placeholder=&quot;yyyy/mm/dd&quot;        /&gt;      &lt;/div&gt;      &lt;h3&gt;請選擇興趣&lt;/h3&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;          &lt;input type=&quot;checkbox&quot; id=&quot;movie&quot; name=&quot;checkArea&quot; value=&quot;movie&quot; /&gt;          電影        &lt;/label&gt;        &lt;label&gt;          &lt;input type=&quot;checkbox&quot; id=&quot;music&quot; name=&quot;checkArea&quot; value=&quot;music&quot; /&gt;          音樂        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;technology&quot;            name=&quot;checkArea&quot;            value=&quot;technology&quot;          /&gt;          技術        &lt;/label&gt;        &lt;label&gt;          &lt;input type=&quot;checkbox&quot; id=&quot;sports&quot; name=&quot;checkArea&quot; value=&quot;sports&quot; /&gt;          運動        &lt;/label&gt;        &lt;label&gt;          &lt;input type=&quot;checkbox&quot; id=&quot;games&quot; name=&quot;checkArea&quot; value=&quot;games&quot; /&gt;          遊戲        &lt;/label&gt;      &lt;/div&gt;      &lt;h3&gt;性別&lt;/h3&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;          &lt;input type=&quot;radio&quot; id=&quot;male&quot; name=&quot;sex&quot; value=&quot;male&quot; /&gt; 漢子        &lt;/label&gt;        &lt;label&gt;          &lt;input type=&quot;radio&quot; id=&quot;female&quot; name=&quot;sex&quot; value=&quot;female&quot; /&gt; 妹子        &lt;/label&gt;      &lt;/div&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;下一位&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>重整後，你會在 Devtool 看到以下的畫面：</p><p>因為在只有 Import <strong>ReactiveFormsModule</strong> 的情況下，<code>&lt;form&gt;</code> 必須綁定一個 <code>formGroup</code> 的實體，否則會產生像上方的錯誤訊息。</p><h3 id="建立-FromModel"><a href="#建立-FromModel" class="headerlink" title="建立 FromModel"></a>建立 FromModel</h3><p>或許你有注意到，我在 template 的 <code>&lt;form&gt;</code> 標籤上已經先加了 <code>[formGroup]=&quot;form&quot;</code> ，這是綁定 FormGroup 實體的方式，接著我們到 <strong>app.component.ts</strong> 建立名為 <code>form</code> 的 Form Model：</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; FormGroup, FormControl &#125; from &#39;@angular/forms&#39;;@Component(&#123;  selector: &#39;app-root&#39;,  templateUrl: &#39;./app.component.html&#39;,  styleUrls: [&#39;./app.component.css&#39;],&#125;)export class AppComponent &#123;  form;  constructor() &#123;    this.form = new FormGroup(&#123;      firstName: new FormControl(),      nickName: new FormControl(),      email: new FormControl(),      phone: new FormControl(),      birthday: new FormControl(),      interest: new FormGroup(&#123;        movie: new FormControl(),        music: new FormControl(),        technology: new FormControl(),        sports: new FormControl(),        games: new FormControl(),      &#125;),      sex: new FormControl(),    &#125;);  &#125;&#125;</code></pre><p>首先，我們先從 @angular&#x2F;forms Import 了 <code>FormGroup</code> <code>FormControl</code> 這兩個 class，我們就可以直接在建構式 ( Constructor ) 中建立 form model 實體。為了看得到 form 實體的值，可以在 template 最下方加上這行：</p><pre><code class="html">&lt;pre&gt;  &#123;&#123;form.value | json&#125;&#125;&lt;/pre&gt;</code></pre><p>重整之後就可以看到表單的下方會印出 form 的 value，並使用 <code>json pipe</code> 來做 render，這就是 model-driven 基本的建立方式。但你或許會覺得，每個欄位都要實體化一個 FormControl 或 FromGroup 實在很麻煩，別擔心，Angular 提供了一個 <code>FormBuilder</code> 讓我們更容易的方式建立 Form Model。</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; FormBuilder &#125; from &#39;@angular/forms&#39;;@Component(&#123;  selector: &#39;app-root&#39;,  templateUrl: &#39;./app.component.html&#39;,  styleUrls: [&#39;./app.component.css&#39;],&#125;)export class AppComponent &#123;  form;  constructor(private _fb: FormBuilder) &#123;    this.form = this._fb.group(&#123;      firstName: &#39;&#39;,      nickName: &#39;&#39;,      email: &#39;&#39;,      phone: &#39;&#39;,      birthday: &#39;&#39;,      interest: this._fb.group(&#123;        movie: &#39;&#39;,        music: &#39;&#39;,        technology: &#39;&#39;,        sports: &#39;&#39;,        games: &#39;&#39;,      &#125;),      sex: &#39;&#39;,    &#125;);  &#125;&#125;</code></pre><p>這樣看起來是不是清爽多了呢？若欄位需要預設值的話，直接加上就可以囉！等同於 new 一個 FormControl。關於 FormControl 與 FormGroup 之間的關係，單一的表單控制項綁定的實體就叫做 FormControl，FormGroup 則是一群 FormControl 的集合，通常用於表單中的部分區塊，使用 FormGroup 最大的好處就是針對驗證的部分，當 FormGoup 底下的某一個 FormControl 有問題，那 FormGroup 的 Valid 也會跟著變成 false，在偵測表單子區塊的狀態會較方便。</p><h3 id="綁定表單實體"><a href="#綁定表單實體" class="headerlink" title="綁定表單實體"></a>綁定表單實體</h3><p>到目前為止，你會發現到，雖然實體都有印出來，但我們還沒進行表單的綁定，表單綁定的方法也很容易，在表單的最外層，通常是 <code>&lt;form&gt;</code> 標籤，加上<code>formGroup</code> Directive 像這樣： <code>[formGroup]=&quot;form&quot;</code>，來表示綁定的表單實體與範圍，接著將現有的控制項的 <code>name</code> 改成 <code>formControlName</code> 即可，如下：</p><pre><code class="html">&lt;!-- Model-Driven --&gt;&lt;div class=&quot;container&quot;&gt;  &lt;form [formGroup]=&quot;form&quot;&gt;    &lt;div class=&quot;profile&quot;&gt;      &lt;h2&gt;基本資料&lt;/h2&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入名字&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;firstName&quot;          formControlName=&quot;firstName&quot;          placeholder=&quot;請輸入名字&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入英文名&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;nickName&quot;          formControlName=&quot;nickName&quot;          placeholder=&quot;請輸入英文名&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入Email&lt;/label&gt;        &lt;input          type=&quot;email&quot;          class=&quot;form-control&quot;          id=&quot;email&quot;          formControlName=&quot;email&quot;          placeholder=&quot;請輸入Email&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入電話&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;phone&quot;          formControlName=&quot;phone&quot;          placeholder=&quot;請輸入電話&quot;        /&gt;      &lt;/div&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;請輸入生日&lt;/label&gt;        &lt;input          type=&quot;text&quot;          class=&quot;form-control&quot;          id=&quot;birthday&quot;          formControlName=&quot;birthday&quot;          placeholder=&quot;yyyy/mm/dd&quot;        /&gt;      &lt;/div&gt;      &lt;h3&gt;請選擇興趣&lt;/h3&gt;      &lt;div class=&quot;form-group&quot; formGroupName=&quot;interest&quot;&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;movie&quot;            formControlName=&quot;movie&quot;            value=&quot;movie&quot;          /&gt;          電影        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;music&quot;            formControlName=&quot;music&quot;            value=&quot;music&quot;          /&gt;          音樂        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;technology&quot;            formControlName=&quot;technology&quot;            value=&quot;technology&quot;          /&gt;          技術        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;sports&quot;            formControlName=&quot;sports&quot;            value=&quot;sports&quot;          /&gt;          運動        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;checkbox&quot;            id=&quot;games&quot;            formControlName=&quot;games&quot;            value=&quot;games&quot;          /&gt;          遊戲        &lt;/label&gt;      &lt;/div&gt;      &lt;h3&gt;性別&lt;/h3&gt;      &lt;div class=&quot;form-group&quot;&gt;        &lt;label&gt;          &lt;input type=&quot;radio&quot; id=&quot;male&quot; formControlName=&quot;sex&quot; value=&quot;male&quot; /&gt;          漢子        &lt;/label&gt;        &lt;label&gt;          &lt;input            type=&quot;radio&quot;            id=&quot;female&quot;            formControlName=&quot;sex&quot;            value=&quot;female&quot;          /&gt;          妹子        &lt;/label&gt;      &lt;/div&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;下一位&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>別忘了，我們也把 <code>checkbox</code> 的部分建立了一個 <code>formGroup</code> 子區塊，對於子項目綁定的 Directive 我們常用的有： <code>formControlName</code>, <code>formGroupName</code>, <code>formArrayName</code>，所以也要在這區塊加上 <code>formGroupName</code> 進行子表單區塊的綁定喔！</p><h3 id="初始化資料"><a href="#初始化資料" class="headerlink" title="初始化資料"></a>初始化資料</h3><p>我們一定都會遇到欄位要有預設值的情況，要如何設定初始化資料呢？很簡單，透過 <code>formBuilder</code> 建立 <code>formControl</code> 的過程中，欄位後面直接加上字串就可以囉，我們做個簡單的範例：</p><pre><code class="typescript">this.form = this._fb.group(&#123;  firstName: &#39;Jeff&#39;,  nickName: &#39;crazy&#39;,  email: &#39;abc@def.com&#39;,  phone: &#39;0912345678&#39;,&#125;);</code></pre><p>像這樣，就可以很輕鬆的將初始預設值設定到 FormControl 上了。</p><h3 id="表單驗證與錯誤訊息提示"><a href="#表單驗證與錯誤訊息提示" class="headerlink" title="表單驗證與錯誤訊息提示"></a>表單驗證與錯誤訊息提示</h3><p>既然是表單，那一定會有表單驗證，這是一件很正常的事情。Angular 也提供了很好用的 Validator 讓我們可以快速建立基本的表單控制項的驗證，只要在 Component 最上方 Import 一個 <code>Validators</code> 就能馬上使用了，例如我們要 firstName 為必填項目，且長度至少要 5 個字元；email 也是必填項目，而且要是正確的 email 格式：</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; FormBuilder, Validators &#125; from &#39;@angular/forms&#39;;@Component(&#123;  selector: &#39;app-root&#39;,  templateUrl: &#39;./app.component.html&#39;,  styleUrls: [&#39;./app.component.css&#39;]&#125;)export class AppComponent &#123;  form;  emailPattern = &#39;^[a-zA-Z0-9.!#$%&amp;』*+/=?^_`&#123;|&#125;~-]+@[a-zA-Z0-9-]+(?:.[a-zA-Z0-9-]+)*$&#39;;  constructor(private _fb: FormBuilder) &#123;    this.form = this._fb.group(&#123;      firstName: [&#39;&#39;, [Validators.required, Validators.minLength(5)]],      nickName: &#39;crazy&#39;,      email: [&#39;&#39;, [Validators.required, Validators.pattern(this.emailPattern)]],,      phone: &#39;0912345678&#39;      ...    &#125;);  &#125;&#125;</code></pre><p>在上面的範例中，首先 Import @angular&#x2F;form 提供的 Validators，接著建立待會要用到的 emailPattern，並直接在 FormBuilder 中的欄位 formControl 以陣列的方式加入，陣列第一個項目為**狀態 ( State )**，也就是資料的值，第二個再加上一組陣列，主要放的是 <strong>Validators</strong>，除了可以使用 Angular 預設提供的 Validator，我們也可以自己建立所謂的 <strong>CustomValidator</strong>，關於自訂驗證，之後再另外寫一篇文章來做介紹。</p><h3 id="建立動態表單以表單陣列為例"><a href="#建立動態表單以表單陣列為例" class="headerlink" title="建立動態表單以表單陣列為例"></a>建立動態表單以表單陣列為例</h3><p>最後一個部分，動態表單，目前我們用了 formControl 、 formGroup，還有一個 <code>formArray</code> 可以使用，常見的使用情境例如有些表單的子區塊項目是會重複出現多筆的時候，就很適合用 <strong>formArray</strong>，馬上來看如何使用吧！我們直接將目前的練習改寫成動態的表單。</p><p>我們先把 <code>constructor</code> 建構式中，用 <code>formBuilder</code> 建立表單 Model 的動作寫成 function，然後一樣透過 <code>formBuilder</code> 建立 FormGroup，並加入一個 formAr 的欄位，建立 FormArray：</p><pre><code class="typescript">  constructor(private _fb: FormBuilder) &#123;    this.form = this._fb.group(&#123;      formAr: this._fb.array([        this.buildGroup()      ])    &#125;);  &#125;  buildGroup(): FormGroup &#123;    return this._fb.group(&#123;      firstName: [&#39;&#39;, [Validators.required, Validators.minLength(5)]],      nickName: &#39;crazy&#39;,      email: [&#39;&#39;, [Validators.required, Validators.pattern(this.emailPattern)]],      phone: &#39;0912345678&#39;,      birthday: &#39;&#39;,      interest: this._fb.group(&#123;        movie: &#39;&#39;,        music: &#39;&#39;,        technology: &#39;&#39;,        sports: &#39;&#39;,        games: &#39;&#39;      &#125;),      sex: &#39;&#39;    &#125;);  &#125;</code></pre><p>然後再回到 Template 的部分，我們在 form 標籤的下一層建立一個 div 並加上 <code>formArrayName</code>，接著 <code>profile</code> Class 的 <code>div</code> 標籤加上 <code>*ngFor</code> 並且綁定 FormGroup 為 <code>i</code>，<code>i</code> 是前面用 *ngFor 時宣告的 index，因為現在我們的 formAr 是 FormArray，它是個陣列，所以在陣列中要綁定每個 FormGroup 就透過 index 來進行，所以後面還有一個 <code>formGroupName</code> 來做綁定。此外，錯誤訊息提示也要改由 form.controls 改為 profile.control ，因為綁定的是 ngFor 的 item，這裡的 item 我命名為 profile。</p><pre><code class="html">&lt;div class=&quot;container&quot;&gt;  &lt;form [formGroup]=&quot;form&quot;&gt;    &lt;div formArrayName=&quot;formAr&quot;&gt;      &lt;div        class=&quot;profile&quot;        *ngFor=&quot;let profile of form.controls.formAr.controls; let i=index&quot;        [formGroupName]=&quot;i&quot;      &gt;        &lt;h2&gt;基本資料&lt;/h2&gt;        &lt;div class=&quot;form-group&quot;&gt;          &lt;label&gt;請輸入名字&lt;/label&gt;          &lt;input            type=&quot;text&quot;            class=&quot;form-control&quot;            id=&quot;firstName&quot;            formControlName=&quot;firstName&quot;            placeholder=&quot;請輸入名字&quot;          /&gt;          &lt;div *ngIf=&quot;profile.controls.firstName.errors&quot;&gt;            &lt;span *ngIf=&quot;profile.controls.firstName.valid&quot;&gt;合格&lt;/span&gt;            &lt;span *ngIf=&quot;profile.controls.firstName.errors.required&quot;              &gt;必填項目&lt;/span            &gt;            &lt;span *ngIf=&quot;profile.controls.firstName.errors.minlength&quot;              &gt;欄位長度不足&lt;/span            &gt;          &lt;/div&gt;        &lt;/div&gt;        &lt;div class=&quot;form-group&quot;&gt;          &lt;label&gt;請輸入英文名&lt;/label&gt;          &lt;input            type=&quot;text&quot;            class=&quot;form-control&quot;            id=&quot;nickName&quot;            formControlName=&quot;nickName&quot;            placeholder=&quot;請輸入英文名&quot;          /&gt;        &lt;/div&gt;        &lt;div class=&quot;form-group&quot;&gt;          &lt;label&gt;請輸入Email&lt;/label&gt;          &lt;input            type=&quot;email&quot;            class=&quot;form-control&quot;            id=&quot;email&quot;            formControlName=&quot;email&quot;            placeholder=&quot;請輸入Email&quot;          /&gt;          &lt;div *ngIf=&quot;profile.controls.email.errors&quot;&gt;            &lt;span *ngIf=&quot;profile.controls.email.valid&quot;&gt;合格&lt;/span&gt;            &lt;span *ngIf=&quot;profile.controls.email.errors.required&quot;&gt;必填項目&lt;/span&gt;            &lt;span *ngIf=&quot;profile.controls.email.errors.pattern&quot;              &gt;請輸入正確的 email&lt;/span            &gt;          &lt;/div&gt;        &lt;/div&gt;        ...      &lt;/div&gt;    &lt;/div&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>既然是 FormArray，那我們當然也要加一個新增項目的方法：</p><pre><code class="typescript">  add() &#123;    this.form.push(this.buildGroup());  &#125;</code></pre><p>並且 template 的部分，底下有一個等候多時的按鈕，為它加上 <code>click</code> 事件：</p><pre><code class="html">&lt;button type=&quot;button&quot; class=&quot;btn btn-default&quot; (click)=&quot;add()&quot;&gt;下一位&lt;/button&gt;</code></pre><p>重新整理之後，可以試著按一下按鈕觀察看看表單的變化囉！</p><h3 id="小結"><a href="#小結" class="headerlink" title="小結"></a>小結</h3><ul><li>Model-Driven Form 是透過 Component 來建立 Form Model，並且在 Template 進行綁定。</li><li>Template 綁定的方式：<ul><li>最外層的表單實體一律用 <code>formGroup</code> Directive 進行綁定。</li><li>子項目或區塊則使用 formControlName, formGroupName, formArrayName 進行綁定。</li></ul></li><li>在 Template 搭配 ngIf 進行錯誤訊息顯示操作時，要存取名為 form 的實體中的錯誤項目<ul><li>一般表單控制項：form.control.firstName.errors，firstName 是表單的控制項名稱</li><li>陣列表單控制項：透過 ngFor 輸出的項目，假設為 item，則存取方式為 item.control.firstName.errors</li></ul></li></ul><h3 id="參考資源-amp-延伸閱讀"><a href="#參考資源-amp-延伸閱讀" class="headerlink" title="參考資源 &amp; 延伸閱讀"></a>參考資源 &amp; 延伸閱讀</h3><ul><li><a href="https://angular.io/docs/ts/latest/api/">Angular API Reference</a></li><li><a href="https://angular.io/docs/ts/latest/api/">Angular Dynamic Forms</a></li><li><a href="http://blog.thoughtram.io/angular/2016/06/22/model-driven-forms-in-angular-2.html">REACTIVE FORMS IN ANGULAR 2</a></li><li><a href="https://scotch.io/tutorials/using-angular-2s-model-driven-forms-with-formgroup-and-formcontrol">Using Angular 2’s Model-Driven Forms with FormGroup and FormControl</a></li><li><a href="http://blog.angular-university.io/introduction-to-angular-2-forms-template-driven-vs-model-driven/">Introduction to Angular 2 Forms - Template Driven vs Model Driven or Reactive Forms</a></li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Angular 16 </tag>
            
            <tag> Forms </tag>
            
            <tag> Model-Driven </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular 2 Forms 介紹：Template-Driven Forms</title>
      <link href="/2016/09/27/angular2-form-template-driven/"/>
      <url>/2016/09/27/angular2-form-template-driven/</url>
      
        <content type="html"><![CDATA[<h2 id="介紹如何使用-template-driven-快速建立簡易的互動表單"><a href="#介紹如何使用-template-driven-快速建立簡易的互動表單" class="headerlink" title="介紹如何使用 template driven 快速建立簡易的互動表單"></a>介紹如何使用 template driven 快速建立簡易的互動表單</h2><p>Angular 2 正式版在日前已經正式發佈了，因此較不會再遇到 alpha 或 beta 甚至 rc 的時候還出現的重大變更（BREAK CHANGE）了，真的出現的話，我想也應該是 Angular 3 要出來的時候了 XD。</p><p>先前參考官方文件介紹過 Angular 2 Forms 的用法，這次來自己實作，以 Template-Driven 的方式建立簡單的登入表單，並且介紹完整的運作流程，主要的內容如下：</p><ul><li>Import FormsModule &amp; 準備 HTML template</li><li>在 Template 中的表單控制項加上 <code>ngModel</code> Directive</li><li>初始化表單控制項預設值</li><li>使用 <code>ngModel</code> 提供的狀態進行 CSS class 裝飾</li><li>追蹤表單驗證狀態並顯示錯誤訊息提示</li></ul><p>登入畫面，是我們在任何的 web application 中最常看到的頁面，因此，就以登入畫面來當範例練習吧！</p><span id="more"></span><h2 id="首先，import-所需要的-FormsModule"><a href="#首先，import-所需要的-FormsModule" class="headerlink" title="首先，import 所需要的 FormsModule"></a>首先，import 所需要的 FormsModule</h2><p>使用 Angular 2 Forms 之前，要先把需要的 Module import 進來，AppModule 的內容如下：</p><pre><code class="typescript">import &#123; BrowserModule &#125; from &#39;@angular/platform-browser&#39;;import &#123; NgModule &#125; from &#39;@angular/core&#39;;import &#123; FormsModule &#125; from &#39;@angular/forms&#39;;import &#123; AppComponent &#125; from &#39;./app.component&#39;;@NgModule(&#123;  declarations: [AppComponent],  imports: [BrowserModule, FormsModule],  providers: [],  bootstrap: [AppComponent],&#125;)export class AppModule &#123;&#125;</code></pre><p>接著，準備我們的 HTML Template：</p><pre><code class="html">&lt;div class=&quot;container&quot;&gt;  &lt;h1&gt;Angular 2 Form Demo&lt;/h1&gt;  &lt;form&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;email&quot;&gt;Email&lt;/label&gt;      &lt;input        type=&quot;email&quot;        class=&quot;form-control&quot;        id=&quot;email&quot;        name=&quot;email&quot;        placeholder=&quot;Email&quot;      /&gt;    &lt;/div&gt;    &lt;div class=&quot;errors&quot;&gt;      &lt;p&gt;請輸入帳號&lt;/p&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;password&quot;&gt;Password&lt;/label&gt;      &lt;input        type=&quot;password&quot;        class=&quot;form-control&quot;        id=&quot;password&quot;        name=&quot;password&quot;        placeholder=&quot;Password&quot;      /&gt;    &lt;/div&gt;    &lt;div class=&quot;errors&quot;&gt;      &lt;p&gt;請輸入密碼&lt;/p&gt;    &lt;/div&gt;    &lt;div class=&quot;checkbox&quot;&gt;      &lt;label&gt;        &lt;input id=&quot;remember&quot; name=&quot;remember&quot; type=&quot;checkbox&quot; /&gt; Remember me      &lt;/label&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;Login&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>這是一個單純的 HTML Template，到目前為止都尚未有任何和 Angular 相關的操作，HTML <code>class</code> 的部分則是套用了 <a href="http://getbootstrap.com/">Bootstrap</a> 的樣式，你也可以先在 index.html 上加上 Bootstrap 的樣式來源。讓畫面看起來比較順眼些。準備好以上的前置步驟後，準備開始套用 <code>ngModel</code> 實作 Template-Driven Forms 囉！</p><h2 id="在-Template-中的表單控制項加上-ngModel-Directive"><a href="#在-Template-中的表單控制項加上-ngModel-Directive" class="headerlink" title="在 Template 中的表單控制項加上 ngModel Directive"></a>在 Template 中的表單控制項加上 <code>ngModel</code> Directive</h2><p>打開 <code>app.component.html</code> template 檔，在表單中的所有 <code>input</code> 加上 <code>ngModel</code>，如下：</p><pre><code class="html">&lt;!--Template-Driven--&gt;&lt;div class=&quot;container&quot;&gt;  &lt;h1&gt;Angular 2 Form Demo&lt;/h1&gt;  &lt;form #myForm=&quot;ngForm&quot;&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;email&quot;&gt;Email&lt;/label&gt;      &lt;input        type=&quot;email&quot;        class=&quot;form-control&quot;        id=&quot;email&quot;        name=&quot;email&quot;        placeholder=&quot;Email&quot;        ngModel      /&gt;    &lt;/div&gt;    &lt;div class=&quot;errors&quot;&gt;      &lt;p&gt;請輸入帳號&lt;/p&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;password&quot;&gt;Password&lt;/label&gt;      &lt;input        type=&quot;password&quot;        class=&quot;form-control&quot;        id=&quot;password&quot;        name=&quot;password&quot;        placeholder=&quot;Password&quot;        ngModel      /&gt;    &lt;/div&gt;    &lt;div class=&quot;errors&quot;&gt;      &lt;p&gt;請輸入密碼&lt;/p&gt;    &lt;/div&gt;    &lt;div class=&quot;checkbox&quot;&gt;      &lt;label&gt;        &lt;input id=&quot;remember&quot; name=&quot;remember&quot; type=&quot;checkbox&quot; ngModel /&gt;        Remember me      &lt;/label&gt;    &lt;/div&gt;    &lt;button type=&quot;button&quot; class=&quot;btn btn-default&quot; (click)=&quot;doSome(myForm)&quot;&gt;      Login    &lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;&lt;!-- Show Test Data--&gt;&lt;hr /&gt;&lt;div class=&quot;container&quot;&gt;  &lt;pre&gt;    &#123;&#123; myForm.value | json &#125;&#125;  &lt;/pre&gt;&lt;/div&gt;</code></pre><p>上面這邊我們主要是在表單中的所有控制項加上 <code>ngModel</code> 屬性，加上後，首先 Angular 就會在這個 template 產生一個 ngForm 的實體，每個有 <code>ngModel</code> directive 的 input 也會產生實體物件，並且存在於 ngForm 實體中，為了可以看到 model 的值，我們在 <code>form</code> 標籤新增一個 template 變數 <code>myForm</code> ，然後在下方新增一個 <code>pre</code> 標籤區塊並加上 Angular 的 expression 來顯示 <code>myForm</code> 的值，執行後的結果如下：</p><p><img src="/images/angular2-form-template-driven/template-driven-1.gif" alt="初步建立的 template-driven form"></p><h2 id="初始化表單預設值"><a href="#初始化表單預設值" class="headerlink" title="初始化表單預設值"></a>初始化表單預設值</h2><p>很多時候我們的表單都會需要有預設值的情況，那在 template-driven form 要如何初始化 model 的預設值呢？</p><p>我們需要先在 component class 新增一個屬性來存放 model 資料，然後在 template 把原本的 <code>ngModel</code> 改成 <code>[ngModel]=&quot;modelName&quot;</code> 就可以囉！</p><pre><code class="html">&lt;div class=&quot;form-group&quot;&gt;  &lt;label for=&quot;email&quot;&gt;Email&lt;/label&gt;  &lt;input    type=&quot;email&quot;    class=&quot;form-control&quot;    id=&quot;email&quot;    name=&quot;email&quot;    placeholder=&quot;Email&quot;    [ngModel]=&quot;email&quot;  /&gt;&lt;/div&gt;</code></pre><h2 id="使用-ngModel-提供的狀態進行-CSS-class-裝飾"><a href="#使用-ngModel-提供的狀態進行-CSS-class-裝飾" class="headerlink" title="使用 ngModel 提供的狀態進行 CSS class 裝飾"></a>使用 <code>ngModel</code> 提供的狀態進行 CSS class 裝飾</h2><p>還有一種需求佷也很常見，就是依照表單的狀態來顯示不同的 CSS 樣式，一般的做法通常都是自己針對不同狀態來命名 CSS Class，Angular 預設為表單提供了三種類型的狀態 class，我們就可以直接對預設提供的 class 名稱來設計樣式。表單控制項的狀態預設提供的有：</p><table><thead><tr><th>狀態（State ）</th><th>Class if true</th><th>Class if false</th></tr></thead><tbody><tr><td>Control 被點擊接觸過</td><td>ng-touched</td><td>ng-untouched</td></tr><tr><td>Control 的值被改變</td><td>ng-dirty</td><td>ng-pristine</td></tr><tr><td>Control 的值不符合驗證</td><td>ng-valid</td><td>ng-invalid</td></tr></tbody></table><h2 id="追蹤表單驗證狀態並顯示錯誤訊息提示"><a href="#追蹤表單驗證狀態並顯示錯誤訊息提示" class="headerlink" title="追蹤表單驗證狀態並顯示錯誤訊息提示"></a>追蹤表單驗證狀態並顯示錯誤訊息提示</h2><p>表單控制項除了依照狀態來顯示 CSS 樣式之外，我們還需要有提示訊息的顯示來讓使用者可以更容易的了解，透過適當的訊息提示可有效幫助 UI 操作，帶來良好的使用者體驗。<code>ngModel</code> 除了依照控制項的狀態來提供 CSS Class 之外，在 formControl 的實體中，也存在著控制項狀態的 model，我們可以依照這些 model 作為訊息顯示的判斷。</p><p>一開始準備好的 template 可以看到有 <code>class=&quot;errors&quot;</code> 的 <code>div</code> 元素，但一開始進入頁面的時候，其實不需要馬上顯示錯誤，而是要使用者接觸或輸入之後，若有錯誤再出現提示訊息即可。</p><p>我們可以在表單控制項加上 template 變數 <code>#userMail</code> 變數名稱可自訂，要以 <code>#</code> 字號為開頭，並指定成 <code>ngModel</code>，然後每個再加上需要的驗證屬性例如：<code>required</code>, <code>minlength</code>, <code>maxlength</code>, <code>pattern</code> 等，這些是 Angular 預設提供的 Validator，套用的方式如下：</p><pre><code class="html">&lt;div class=&quot;form-group&quot;&gt;  &lt;label for=&quot;email&quot;&gt;Email&lt;/label&gt;  &lt;input    type=&quot;email&quot;    class=&quot;form-control&quot;    id=&quot;email&quot;    name=&quot;email&quot;    placeholder=&quot;Email&quot;    [ngModel]=&quot;email&quot;    required    minlength=&quot;5&quot;    pattern=&quot;^[a-zA-Z0-9.!#$%&amp;』*+/=?^_`&#123;|&#125;~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$&quot;    #iemail=&quot;ngModel&quot;  /&gt;&lt;/div&gt;&lt;div class=&quot;errors&quot; *ngIf=&quot;iemail.errors&quot;&gt;  &lt;p *ngIf=&quot;iemail.errors.minlength&quot;&gt;最少要 5 個字&lt;/p&gt;  &lt;p *ngIf=&quot;iemail.errors.required&quot;&gt;必填項目&lt;/p&gt;  &lt;p *ngIf=&quot;iemail.errors.pattern&quot;&gt;請輸入正確的 Email 格式&lt;/p&gt;&lt;/div&gt;</code></pre><p>Class errors 的 div 的用途用來顯示錯誤訊息的部分，以上面的 input 為例，Angular 建立實體之後，會有一個 errors 的屬性，當有 Validator 驗證錯誤的時候，會存一個物件到 errors 屬性中。這時候我們做了一個 ngIf 來判斷是哪一個錯誤，然後顯示對應的錯誤訊息。另外我們也可以在按鈕設定，當整張表單的驗證狀態為 invalid 的時候，就可以把按鈕 <code>disabled</code> 禁止點擊。</p><p>到目前為止的練習，我們的 component 完全沒有任何的邏輯驗證或處理，只設定了一個初始值，所有的驗證都在 template 做完了！Angular 2 Template-Driven Forms 是不是很簡單呢？ :)</p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Forms </tag>
            
            <tag> Template-Driven-Forms </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular 2 ngModel 的內幕(?)</title>
      <link href="/2016/08/03/inside-ng-model/"/>
      <url>/2016/08/03/inside-ng-model/</url>
      
        <content type="html"><![CDATA[<h2 id="關於-NgModel"><a href="#關於-NgModel" class="headerlink" title="關於 NgModel"></a>關於 NgModel</h2><p>這篇文章主要來深入討論 <code>[(ngModel)]</code>，若你已經有在開發 Angular 2 的專案，或是自己嘗試練習 Angular 的過程中， <code>[(ngModel)]</code> 一定會接觸到的語法，透過<code>[(ngModel)]</code> 實現雙向繫結的功能，但，為什麼要使用中括號和小括號呢？</p><p>其實，繫結語法中的  <strong>[( )]</strong>  符號是一個很好的提示。</p><span id="more"></span><p>在屬性繫結中，一個值從 Model 中傳到螢幕上的目標屬性。我們把名稱放在中括號 <strong>[ ]</strong> 裡面來標記出目標屬性 。這是一個 <strong>從 Model 到 View</strong> 的單向資料繫結。</p><p>在事件繫結中，從螢幕上的目標屬性把值傳到 Model 裡。我們透過小括號 <strong>( )</strong> 把名稱包起來標記出目標屬性。這是一個 <strong>從 View 到 Model</strong> 的反向單向資料繫結 。</p><p>由此可知，Angular 選擇了組合符號 <strong>[( )]</strong> 來標記出雙向資料繫結和雙向資料流。</p><p>事實上，我們可以把  <code>NgModel</code>  繫結拆成兩個獨立的繫結，就像上一篇我們重寫的 「Name」 <code>&lt;input&gt;</code>   繫結一樣：</p><pre><code class="html">&lt;input  type=&quot;text&quot;  class=&quot;form-control&quot;  required  [ngModel]=&quot;model.name&quot;  (ngModelChange)=&quot;model.name = $event&quot;/&gt;TODO: remove this: &#123;&#123;model.name&#125;&#125;</code></pre><p>這個屬性繫結看起來很眼熟，但事件繫結看起來有點怪。</p><p><code>ngModelChange</code>  並不是  <code>&lt;input&gt;</code>  元素的事件。 它實際上是一個來自  <code>ngModel</code> directive 的事件屬性。 當 Angular 在表單中看到一個  [(x)]  的繫結目標時， 它會預計這個  <code>x</code> directive 有一個名為  <code>x</code>  的輸入屬性，和一個名為  <code>xChange</code>  的輸出屬性。</p><p>樣板表達式 ( template expression ) 中的另一個奇怪的地方是  <code>model.name = $event</code> 。 我們以前看到的  <code>$event</code>  變數是來自 DOM 事件的。 但  <code>ngModelChange</code>  屬性不會產生 DOM 事件，它是一個 Angular 的  <code>EventEmitter</code>  類型的屬性，當它觸發時， return 的是輸入框的值 - 這個值剛好和我們必須設給 Model 的  <code>name</code>  屬性一樣。</p><p>很高興知道這些，但這樣實際嗎？實務上我們幾乎總是較習慣使用  <code>[(ngModel)]</code>  形式的雙向繫結。 只有當我們不得不在事件處理函式中做一些特別的事情 (例如合併或限制按鍵頻率) 時，才需要另外拆出獨立的事件處理函式。</p><p>想了解更多關於  <code>ngModel</code>  和其它樣板語法的內容，請參考  <a href="https://angular.cn/docs/ts/latest/guide/template-syntax.html">Template Syntax </a> 章節。</p>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> ngModel </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Angular 2 Forms 介紹</title>
      <link href="/2016/07/30/angular2-forms-study/"/>
      <url>/2016/07/30/angular2-forms-study/</url>
      
        <content type="html"><![CDATA[<h2 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h2><p>Angular 2 目前已經來到 RC 4 了，相信再過不久就會即將正式的 Release，這次就先針對官網上表單（Forms）文件的部分來做研究與紀錄。之後再寫其他關於 Angular 2 的介紹。現今的 Web 應用 ，不論是登入頁面、會員申請、購物車等各式各樣的應用一定都會使用到表單，透過表單來建立一個有凝聚力且有效、引人注目的資料輸入體驗。Angular 表單整合了使用者資料繫結控制，追蹤變更、驗證輸入的正確性並提供錯誤訊息顯示。</p><p>我們將會從頭開始建立一個範例表單，分成幾個項目並按照逐一實作。實作的項目有：</p><ul><li>使用 Component 與 Template 建立一個 Angular 表單</li><li>使用 <code>[(ngModel)]</code> 語法實現雙向資料繫結，提供讀取與寫入控制項的值</li><li>結合一個表單來使用  <code>ngModel</code> ，能讓我們跟蹤狀態的變化並對表單控制項做驗證</li><li>特殊的 CSS 類別 ( Class )會用來反應控制項的狀態，並能提供強烈的視覺反饋</li><li>向使用者顯示有效性驗證的錯誤提示和啟用&#x2F;關閉表單控制項</li><li>透過 Template 參考變數，在控制項之間共享資訊</li></ul><span id="more"></span><h2 id="啟動-Bootstarp"><a href="#啟動-Bootstarp" class="headerlink" title="啟動 ( Bootstarp )"></a>啟動 ( Bootstarp )</h2><p>先來了解一下如何啟動 應用 並加入表單所需要的相依模組。在啟動的期間，呼叫 <code> provideForms()</code>，並將它的結果傳給 <code>providers</code> 陣列，以註冊這些新的表單模組。</p><pre><code class="typescript">import &#123; bootstrap &#125; from &#39;@angular/platform-browser-dynamic&#39;;import &#123; disableDeprecatedForms, provideForms &#125; from &#39;@angular/forms&#39;;import &#123; AppComponent &#125; from &#39;./app.component&#39;;bootstrap(AppComponent, [disableDeprecatedForms(), provideForms()]).catch(  (err: any) =&gt; console.error(err));</code></pre><p>舊版的表單 API 已經進入了棄用階段。在這個過渡期， Angular 會同時支援兩個表單模組。為了提醒我們 「舊版 API 已被棄用」， Angular 會在 console 顯示一些警告訊息。</p><p><img src="/images/angular2-forms-study/angualr-warn-console.png" alt="在 Devtool console 中會顯示舊版表單 API 即將被棄用提示訊息"></p><p>當我們完全轉換成新的 API 而不再用舊版的時候，可以呼叫  <code>disableDeprecatedForms()</code>  來徹底禁用舊版的表單功能，並消除警告訊息。</p><h2 id="表單驅動模式"><a href="#表單驅動模式" class="headerlink" title="表單驅動模式"></a>表單驅動模式</h2><p>建立表單的方法有兩種，樣板驅動表單 ( Template-Driven Forms ) 與模型驅動表單 ( Model-Driven Forms ) ，這兩種有什麼地方不同，之後再寫篇文章做介紹。或是直接參考 <a href="http://blog.angular-university.io/introduction-to-angular-2-forms-template-driven-vs-model-driven/">Introduction to Angular 2 Forms - Template Driven, Model Driven or In-Between</a></p><h3 id="Template-驅動表單-Template-Driven-Forms"><a href="#Template-驅動表單-Template-Driven-Forms" class="headerlink" title="Template 驅動表單 ( Template-Driven Forms )"></a>Template 驅動表單 ( Template-Driven Forms )</h3><p>利用 Angular template ，幾乎所有的表單都可以建構，例如：登錄表單、聯絡表單…… 等大量的各種商務表單。 我們可以自由的擺放各種控制項並把它們繫結到資料、指定驗證規則、顯示驗證錯誤、有條件的禁用 &#x2F; 啟用特定的控制項、觸發內建的視覺反饋等等，不勝枚舉。它的確很簡單，因為 Angular 幫我們處理了大多數重複、單調的任務，讓我們可以不必親自操刀、身陷其中。</p><p>我們將討論與學習建構如下的 「 Template 驅動」 表單：</p><p><img src="/images/angular2-forms-study/hero-form-1.png" alt="建立template 驅動表單"></p><p>這個表單中的三個欄位都是必填的。這些欄位左側會有一個綠色的小標籤色塊，讓它們更容易辨識。如果我們刪除了 Name，表單就會用一種引人注目的樣式把驗證錯誤顯示出來。</p><p><img src="/images/angular2-forms-study/hero-form-2.png" alt="表單欄位驗證錯誤提示"></p><p>我們將按照一系列的步驟來建構此表單：</p><ol><li>建立  <strong>Hero</strong>  模型類別 ( Model Class )</li><li>建立控制此表單的元件</li><li>建立具有初始表單佈局的 template</li><li>使用  <strong>ngModel</strong> 雙向資料繫結語法把資料屬性繫結到每個表單輸入控制項</li><li>在每個表單輸入控制項中加入 <strong>ngControl</strong> directive</li><li>新增自定義 CSS 來提供視覺反饋</li><li>顯示和隱藏有效性驗證的錯誤訊息</li><li>使用  <strong>ngSubmit</strong>  處理表單送出</li><li>禁用此表單的送出按鈕，直到表單變為有效</li></ol><h2 id="開始建置"><a href="#開始建置" class="headerlink" title="開始建置"></a>開始建置</h2><p>我們直接透過 Angular Cli 來建立一個練習專案</p><p><img src="/images/angular2-forms-study/ng-cli-new-project.png" alt="使用 Angular-Cli 新增練習專案"></p><h3 id="Step-1-建立一個-Hero-模型類-Model-Class"><a href="#Step-1-建立一個-Hero-模型類-Model-Class" class="headerlink" title="Step 1. 建立一個 Hero 模型類 ( Model Class )"></a>Step 1. 建立一個 Hero 模型類 ( Model Class )</h3><p>當使用者輸入表單資料時，我們要截取到其中的變化，並更新到模型的實體中。 除非我們知道模型裡有什麼，否則無法設計表單。最簡單的模型就是一個「屬性包」( Property bag )，用來存放應用中一件事物的事實。這裡使用三個必填欄位 (<code>id</code> 、 <code>name</code> 、 <code>power</code>) ，和一個選填欄位 (<code>alterEgo</code>)。</p><p>在應用文件夾中建立一個  <code>hero.ts</code>  文件，並且寫入下列 Class 定義內容：</p><pre><code class="typescript">export class Hero &#123;  constructor(    public id: number,    public name: string,    public power: string,    public alterEgo?: string  ) &#123;&#125;&#125;</code></pre><p>TypeScript 編譯器為建構式 ( constructor ) 中每個標為  <code>public</code>  的參數建立一個公共欄位，並在建立新的 Hero 實體時，把參數值自動賦給這些公共欄位。注意  <code>alterEgo</code>  後面的問號 (?) 代表<code>alterEgo</code>  是非必要的，允許省略 。</p><p>建立一個新 Hero 資料：</p><pre><code class="typescript">let myHero = new Hero(  42,  &#39;SkyDog&#39;,  &#39;Fetch any object at any distance&#39;,  &#39;Leslie Rollover&#39;);console.log(&#39;My hero is called &#39; + myHero.name); // &quot;My hero is called SkyDog&quot;</code></pre><h3 id="Step-2-建立表單元件"><a href="#Step-2-建立表單元件" class="headerlink" title="Step 2. 建立表單元件"></a>Step 2. 建立表單元件</h3><p>每個 Angular 表單分成兩部分：一個基於 HTML 的 template ，和一個基於程式碼的元件，它用來處理資料和使用者互動。我們從元件開始，是因為它能夠簡要說明英雄編輯器能做什麼。</p><p>使用 Angular Cli 輸入指令 <code>ng g component hero-form</code> 建立 hero-form 元件，並在  <code>hero-form.component.ts</code>  修改內容如下：</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; NgForm &#125; from &#39;@angular/forms&#39;;import &#123; Hero &#125; from &#39;../shared/hero&#39;;@Component(&#123;  moduleId: module.id,  selector: &#39;app-hero-form&#39;,  templateUrl: &#39;hero-form.component.html&#39;,  styleUrls: [&#39;hero-form.component.css&#39;],&#125;)export class HeroFormComponent &#123;  public powers = [    &#39;Really Smart&#39;,    &#39;Super Flexible&#39;,    &#39;Super Hot&#39;,    &#39;Weather Changer&#39;,  ];  public model = new Hero(18, &#39;Dr IQ&#39;, this.powers[0], &#39;Chuck Overstreet&#39;);  public submitted = false;  onSubmit() &#123;    this.submitted = true;  &#125;  // TODO: Remove this when we&#39;re done  get diagnostic() &#123;    return JSON.stringify(this.model);  &#125;&#125;</code></pre><p>在 hero-form 元件中新增 powers 與 model 建立 Demo 用假資料，並新增一個 submitted 為 false 並在最後增加一個  <code>diagnostic</code>  屬性，它回傳這個模型的 JSON 格式。 協助查看開發過程中發生的事，最後做清理時再移除它即可。</p><h3 id="Step-3-建立一個初始-HTML-表單-template"><a href="#Step-3-建立一個初始-HTML-表單-template" class="headerlink" title="Step 3. 建立一個初始 HTML 表單 template"></a>Step 3. 建立一個初始 HTML 表單 template</h3><p>建立一個新的 template 文件，命名為  <code>hero-form.component.html</code>並加入內容：</p><pre><code class="html">&lt;div class=&quot;container&quot;&gt;  &lt;h1&gt;Hero Form&lt;/h1&gt;  &lt;form&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;name&quot;&gt;Name&lt;/label&gt;      &lt;input type=&quot;text&quot; class=&quot;form-control&quot; required /&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;alterEgo&quot;&gt;Alter Ego&lt;/label&gt;      &lt;input type=&quot;text&quot; class=&quot;form-control&quot; /&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;Submit&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>這只是一段普通的 HTML，出現了兩個  <code>Hero</code>  的欄位， <code>name</code>  和  <code>alterEgo</code> ，讓使用者可以輸入與編輯。<strong>Name</strong> <code>&lt;input&gt;</code> 控制項加上  <code>required</code>  屬性；但  <strong>Alter Ego</strong> <code>&lt;input&gt;</code>  控制項就沒有加了，因為<code>alterEgo</code>  是選填的欄位。最後底部有一個  <strong>Submit</strong>  按鈕，它有一些 CSS 的 Class。目前這個 template 還沒有任何的 Angular 語法，只是個 Layout。Class 的部分， <code>container</code> 、 <code>form-group</code> 、 <code>form-control</code>  和  <code>btn</code>  來自  <a href="http://getbootstrap.com/css/">Twitter Bootstrap</a> 。純粹是裝飾。</p><p>使用 Bootstrap 來裝飾表單，在 <code>index.html</code> 的 head 中加上 css 來源。</p><pre><code class="html">&lt;link  href=&quot;https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css&quot;  rel=&quot;stylesheet&quot;/&gt;</code></pre><h4 id="修改-app-component-ts-檔案"><a href="#修改-app-component-ts-檔案" class="headerlink" title="修改  app.component.ts  檔案"></a>修改  <em>app.component.ts</em>  檔案</h4><p>接著修改由 Angular Cli 新增專案而產生的 app.component.ts 檔案，將 <code>hero-form</code> 元件 import 進來。</p><pre><code class="typescript">import &#123; Component &#125; from &#39;@angular/core&#39;;import &#123; HeroFormComponent &#125; from &#39;./hero-form/hero-form.component&#39;;@Component(&#123;  moduleId: module.id,  selector: &#39;app-root&#39;,  templateUrl: &#39;app.component.html&#39;,  styleUrls: [&#39;app.component.css&#39;],  directives: [HeroFormComponent],&#125;)export class AppComponent &#123;  title = &#39;app works!&#39;;&#125;</code></pre><h4 id="修改-app-component-html-檔案"><a href="#修改-app-component-html-檔案" class="headerlink" title="修改 app.component.html 檔案"></a>修改 <em>app.component.html</em> 檔案</h4><p>加入剛新增的 hero-form 元件的標籤到 app.component.html</p><pre><code class="html">&lt;h1&gt;&#123;&#123;title&#125;&#125;&lt;/h1&gt;&lt;app-hero-form&gt;&lt;/app-hero-form&gt;</code></pre><h4 id="用-ngFor-新增-Select-Option"><a href="#用-ngFor-新增-Select-Option" class="headerlink" title="用  ngFor  新增 Select Option"></a>用  <strong>ngFor</strong>  新增 Select Option</h4><p>我們將新增一個  <code>select</code>  到表單中，並且用  <code>ngFor</code>  把  <code>powers</code>  列表繫結到  <code>option</code>  中。</p><pre><code class="html">&lt;div class=&quot;container&quot;&gt;  &lt;h1&gt;Hero Form&lt;/h1&gt;  &lt;form&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;name&quot;&gt;Name&lt;/label&gt;      &lt;input type=&quot;text&quot; class=&quot;form-control&quot; required /&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;alterEgo&quot;&gt;Alter Ego&lt;/label&gt;      &lt;input type=&quot;text&quot; class=&quot;form-control&quot; /&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;power&quot;&gt;Hero Power&lt;/label&gt;      &lt;select class=&quot;form-control&quot; required&gt;        &lt;option *ngFor=&quot;let p of powers&quot; [value]=&quot;p&quot;&gt;&#123;&#123;p&#125;&#125;&lt;/option&gt;      &lt;/select&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;Submit&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>在列表中的每一個選項渲染出一個 <code>option</code> 標籤。 template 輸入變數 <code>p</code>  在每個迭代中都代表一個不同的項目，使用雙大括號 的表達式語法來顯示它的值。</p><h3 id="Step-4-使用-ngModel-雙向資料繫結"><a href="#Step-4-使用-ngModel-雙向資料繫結" class="headerlink" title="Step 4. 使用  ngModel 雙向資料繫結"></a>Step 4. 使用  ngModel 雙向資料繫結</h3><p>目前還沒有看到其他欄位的資料，這是因為還沒有繫結到  <code>Hero</code> 。 從以前的章節中，我們知道該怎麼解決。 <a href="https://angular.cn/docs/ts/latest/guide/displaying-data.html">顯示資料</a>教會我們屬性繫結。 <a href="https://angular.cn/docs/ts/latest/guide/user-input.html">使用者輸入</a>告訴我們如何透過事件繫結來監聽 DOM 事件，以及如何用所顯示的值更新元件的屬性。現在，我們需要同時進行顯示、監聽和提取。雖然可以在表單中再次使用這些技術。 但是，這裡將引入一個新東西， <code>[(ngModel)]</code>  語法，它使用一種非常簡單的方式把表單繫結到模型。找到 「Name」 對應的 <code>&lt;input&gt;</code> 標籤，並像這樣進行修改。</p><pre><code class="html">&lt;div class=&quot;form-group&quot;&gt;  &lt;label for=&quot;name&quot;&gt;Name&lt;/label&gt;  &lt;input    type=&quot;text&quot;    class=&quot;form-control&quot;    required    [(ngModel)]=&quot;model.name&quot;    name=&quot;name&quot;  /&gt;  TODO: remove this: &#123;&#123;model.name&#125;&#125;&lt;/div&gt;</code></pre><p>在 input 標籤後新增一個偵錯用的表達式，以便查看正在發生什麼事。 並留下註解提醒：在完成後移除。</p><p>現在看一下繫結語法  <code>[(ngModel)]=&quot;...&quot;</code> ，如果現在執行這個應用，並在<strong>姓名</strong>輸入框中鍵入，新增和刪除字符，我們將看到下方的訊息中顯示和消失。它看起來像這樣：</p><p><img src="/images/angular2-forms-study/binding-test.gif" alt="雙向資料繫結"></p><p>偵錯訊息證明了資料從輸入框流動到模型，再反向流動回來的整個過程。 <strong>這就是雙向資料繫結！</strong></p><p>注意，我們還在 <code>&lt;input&gt;</code> 標籤上新增了一個  <strong>ngModel</strong>  屬性 ( Attribute ) 。當在表單中使用  <code>[(ngModel)]</code>時，這是必須的，這樣才能輕鬆的引用它來收集表單的值以及校驗狀態。接著用相同的方式把  <code>[(ngModel)]</code>  繫結新增到  <strong>Alter Ego</strong> 和   <strong>Hero Power</strong> 屬性。 我們將拋棄輸入框的繫結訊息，並在元件頂部新增一個到  <code>diagnostic</code>  的新繫結。 這樣就能確認雙向資料繫結<strong>在整個 Hero 模型上</strong>都能正常工作了。修改後的表單，其核心是三個  <code>[(ngModel)]</code>  繫結，如下：</p><pre><code class="html">&lt;div class=&quot;container&quot;&gt;  &lt;h1&gt;Hero Form&lt;/h1&gt;  &#123;&#123;diagnostic&#125;&#125;  &lt;form&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;name&quot;&gt;Name&lt;/label&gt;      &lt;input        type=&quot;text&quot;        class=&quot;form-control&quot;        required        [(ngModel)]=&quot;model.name&quot;        name=&quot;name&quot;      /&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;alterEgo&quot;&gt;Alter Ego&lt;/label&gt;      &lt;input        type=&quot;text&quot;        class=&quot;form-control&quot;        [(ngModel)]=&quot;model.alterEgo&quot;        name=&quot;alterEgo&quot;      /&gt;    &lt;/div&gt;    &lt;div class=&quot;form-group&quot;&gt;      &lt;label for=&quot;power&quot;&gt;Hero Power&lt;/label&gt;      &lt;select        class=&quot;form-control&quot;        required        [(ngModel)]=&quot;model.power&quot;        name=&quot;power&quot;      &gt;        &lt;option *ngFor=&quot;let p of powers&quot; [value]=&quot;p&quot;&gt;&#123;&#123;p&#125;&#125;&lt;/option&gt;      &lt;/select&gt;    &lt;/div&gt;    &lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot;&gt;Submit&lt;/button&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>如果現在執行應用，並且修改 Hero 模型的每一個屬性，表單看起來會像這樣：</p><p><img src="/images/angular2-forms-study/ng-model-in-action-2.png" alt="表單頂部的偵錯訊息反映出了我們所做的一切更改"></p><p>表單頂部的  <code>diagnostic</code>  繫結表達式已經完成了它的使命，可以刪除它了。</p><h3 id="Step-5-透過-ngModel-跟蹤修改狀態與有效性驗證"><a href="#Step-5-透過-ngModel-跟蹤修改狀態與有效性驗證" class="headerlink" title="Step 5. 透過  ngModel  跟蹤修改狀態與有效性驗證"></a>Step 5. 透過  <strong>ngModel</strong>  跟蹤修改狀態與有效性驗證</h3><p>表單不僅是關於資料繫結的。我們還希望知道表單中各個控制項的狀態。</p><p>在表單中使用  <code>ngModel</code>  能讓我們比只使用雙向資料繫結獲得更多的控制權。它還會告訴我們很多訊息：User 接觸過此控制項？值是否變更過？資料是否有效？</p><p>這個 directive 不只是追蹤狀態，它還會使用下面列出的這些特殊 CSS 的 Class 更新此控制項。 我們可以透過自訂這些 CSS 的 Class 來更改控制項的外觀，以及讓訊息顯示或隱藏。</p><p>很快就會看到那些效果。在這之前要確保在所有這三個表單控制項中都有  <code>ngModel</code>  以及相應的<code>name</code>  屬性。那就從  <em>Name</em>  輸入框開始吧：</p><pre><code class="html">&lt;input  type=&quot;text&quot;  class=&quot;form-control&quot;  required  [(ngModel)]=&quot;model.name&quot;  ngControl=&quot;name&quot;/&gt;</code></pre><p>對本範例來說，把這個  <code>name</code>  屬性設定為 “name” 會更容易理解。但也可以設定成任何唯一的值。</p><p>Angular 內部會建立 <code>FormControls</code> 並註冊在 <code>NgForm</code> directive 中，讓 Angular 附加在 <code>tag</code> 上。每個 <code>FormControl</code> 會被註冊在我們所設定的 name 屬性下面，關於 <code>NgForm</code> 的介紹，我們後面會再提到。</p><h3 id="Step-6-新增自定義-CSS-來提供視覺反饋"><a href="#Step-6-新增自定義-CSS-來提供視覺反饋" class="headerlink" title="Step 6. 新增自定義 CSS 來提供視覺反饋"></a>Step 6. 新增自定義 CSS 來提供視覺反饋</h3><p><strong>NgModel</strong> directive 不僅僅跟蹤狀態。它還使用三個 CSS 的 Class 來更新控制項，以反應目前的狀態。</p><table><thead><tr><th>狀態</th><th>為真時的 CSS Class</th><th>為假時的 CSS Class</th></tr></thead><tbody><tr><td>控制項已經被訪問過</td><td><code>ng-touched</code></td><td><code>ng-untouched</code></td></tr><tr><td>控制項的值已經變化</td><td><code>ng-dirty</code></td><td><code>ng-pristine</code></td></tr><tr><td>控制項的值是有效的</td><td><code>ng-valid</code></td><td><code>ng-invalid</code></td></tr></tbody></table><p>我們往姓名  <code>&lt;input&gt;</code>  標籤上新增一個名叫  <strong>spy</strong>  的臨時  <a href="https://angular.cn/docs/ts/latest/guide/template-syntax.html#local-vars">template 參考變數</a>，然後用 spy 來顯示它上面的所有 CSS 的 Class。</p><p>現在，執行應用，並讓<strong>姓名</strong>輸入框在 Focus 的狀態。 然後按照下面四個步驟來做：</p><ol><li>查看輸入框，但別碰它</li><li>點擊輸入框，然後點擊輸入框外的空白處</li><li>在名字的末尾新增一個斜線</li><li>刪除名字</li></ol><p>動作和對應的效果如下：</p><p><img src="/images/angular2-forms-study/control-state-transitions-anim.gif" alt="class test"></p><p>可以看到下列四組 CSS Class 以及它們的變化：</p><p><img src="/images/angular2-forms-study/ng-control-class-changes.png" alt="class test"></p><p>當資料驗證失敗時，我們希望發出一個強力的視覺提醒並標記出必填欄位。因此在輸入框的左側新增一個帶顏色的色塊，透過 (<code>ng-valid</code> | <code>ng-invalid</code>) 這兩個 CSS Class 來進行裝飾。</p><p><img src="/images/angular2-forms-study/validity-required-indicator.png" alt="indicator"></p><p>在 hero-form 的資料夾下有  <code>hero-form.component.css</code>  檔案，針對這個元件新增兩個樣式如下：</p><pre><code class="scss">.ng-valid[required] &#123;  border-left: 5px solid #42a948; /* green */&#125;.ng-invalid &#123;  border-left: 5px solid #a94442; /* red */&#125;</code></pre><p>這些樣式的選擇器分別為 Angular 驗證 Class 與 HTML 5 的 <code>required</code> 屬性。</p><h3 id="Step-7-顯示和隱藏有效性驗證的錯誤訊息"><a href="#Step-7-顯示和隱藏有效性驗證的錯誤訊息" class="headerlink" title="Step 7. 顯示和隱藏有效性驗證的錯誤訊息"></a>Step 7. 顯示和隱藏有效性驗證的錯誤訊息</h3><p>「Name」 輸入框是必填的，清空它會讓左側的條變紅。這表示  <strong>某些東西</strong>是錯的，但不知道錯在哪裡，或者如何糾正。 我們可以透過  <code>ng-invalid</code> Class 來提供一個更明確的訊息。例如當姓名是空白的時後，可以在下方出現提示訊息：</p><p><img src="/images/angular2-forms-study/name-required-error.png" alt="錯誤訊息提示"></p><p>要實作這樣的效果，需要在 template 做些調整，在控制項新增一個 template 參考變數，並在下方加入一個提示訊息區塊，當驗證失敗的時候才會顯示。</p><pre><code class="html">&lt;label for=&quot;name&quot;&gt;Name&lt;/label&gt;&lt;input  type=&quot;text&quot;  class=&quot;form-control&quot;  required  [(ngModel)]=&quot;model.name&quot;  ngControl=&quot;name&quot;  #name=&quot;ngForm&quot;/&gt;&lt;div [hidden]=&quot;name.valid || name.pristine&quot; class=&quot;alert alert-danger&quot;&gt;  Name is required&lt;/div&gt;</code></pre><p>我們需要一個 template 參考變數來存取 template 中輸入框的 Angular 控制項。 這裡建立了一個名叫<code>name</code>  的變數 ( #name ) ，並且把它設為 “ngModel” 。</p><p>為什麼是 “ngModel”？</p><p>Directive 的  <a href="https://angular.cn/docs/ts/latest/api/core/index/DirectiveMetadata-class.html#!#exportAs">exportAs</a>  屬性會告訴 Angular 如何連接參考變數到 directive 中。 這裡我們把  <code>name</code>  設定為  <code>ngModel</code>  就是因為  <code>ngModel</code> 這個 directive 的  <code>exportAs</code>  屬性恰好是 「ngModel」。</p><p>現在，把  <code>div</code>  元素的  <code>hidden</code>  屬性繫結到  <code>name</code>  控制項的屬性，就可以控制 「姓名」 欄位錯誤訊息的顯示了。</p><pre><code class="html">&lt;div [hidden]=&quot;name.valid || name.pristine&quot; class=&quot;alert alert-danger&quot;&gt;&lt;/div&gt;</code></pre><p>這個範例中，當控制項是有效或全新 ( pristine ) 時，我們要隱藏訊息。「全新」 意味著從它被顯示在表單中開始使用者從未修改過它的值。這種使用者體驗取決於開發或設計人員的選擇。有些人會希望任何時候都顯示這條訊息。 如果忽略了<code>pristine</code>  狀態，就會只在欄位值有效時隱藏此訊息。</p><h4 id="加入一個-Hero-並重置表單"><a href="#加入一個-Hero-並重置表單" class="headerlink" title="加入一個 Hero 並重置表單"></a>加入一個 Hero 並重置表單</h4><p>我們希望在這個表單中加入一個新的 Hero。 先在表單的底部放一個 「 New Hero 」 按鈕，並且把它的點擊事件繫結到一個元件的方法上。</p><pre><code class="html">&lt;button type=&quot;button&quot; class=&quot;btn btn-default&quot; (click)=&quot;newHero()&quot;&gt;  New Hero&lt;/button&gt;</code></pre><pre><code class="typescript">newHero() &#123;  this.model = new Hero(42, &#39;&#39;, &#39;&#39;);&#125;</code></pre><p>再次執行應用，點擊 <strong>New Hero</strong> 按鈕，表單被清空了。 輸入框左側的<strong>必填欄位</strong>豎條是紅色的，表示 <code>name</code>  和 <code>power</code>  屬性是無效的。 對必填欄位來說，這樣的方式簡單易懂。 錯誤訊息目前是隱藏的，這是因為表單還是全新的，我們還沒有修改任何東西。輸入一個名字，並再次點擊 <strong>New Hero</strong> 按鈕。 這次，我們看到了錯誤訊息！為什麼？當我們顯示一個新 ( 空白 ) 的 Hero 時，我們不希望如此。使用瀏覽器工具檢查元素就會發現，這個 <strong>name</strong> 輸入框並不是全新的。 更換了 Hero **並不會重置控制項的「全新」狀態  **。</p><p>由此可知，在這種實現方式下， Angular 沒辦法區分是替換了整個英雄資料還是用程式單獨清除了  <code>name</code> 屬性。 Angular 不能作出假設，因此只好讓控制項保留當前狀態—髒狀態 ( dirty state )。</p><p>這時候在元件新增一個  <code>active</code>  變數預設為<code>true</code> 。當我們新增一個新紀錄時，它把變數  <code>active</code>  設為  <code>false</code> ， 然後透過一個快速的<code>setTimeout</code>  函式迅速把它設定回  <code>true</code> 。</p><pre><code class="typescript">  active = true;  newHero() &#123;    this.model = new Hero(42, &#39;&#39;, &#39;&#39;);    this.active = false;    setTimeout(() =&gt; this.active = true, 0);  &#125;</code></pre><p>然後，我們把 form 元素繫結到這個  <code>active</code>  變數上。</p><pre><code class="html">&lt;form *ngIf=&quot;active&quot;&gt;&lt;/form&gt;</code></pre><p>在透過  <code>NgIf</code>  繫結到  <code>active</code>  變數之後，點擊 「 New Hero 」 將從 DOM 中移除這個表單，並在一眨眼的功夫重建它。 重新建立的表單處於 「全新」 狀態。錯誤訊息被隱藏了。這只是一個臨時的變通方案，將來我們還會有一個更合適的方案來重置表單。</p><h3 id="Step-8-透過-ngSubmit-來送出表單"><a href="#Step-8-透過-ngSubmit-來送出表單" class="headerlink" title="Step 8. 透過  ngSubmit  來送出表單"></a>Step 8. 透過  <strong>ngSubmit</strong>  來送出表單</h3><p>在填表完成之後，使用者要能送出這個表單。 「送出」 按鈕位於表單的底部，它自己不會做任何事，但因為 type 屬性是 <strong>submit</strong>，所以它會觸發表單送出。僅僅觸發 「表單提交」 在目前是沒用的。 還要用另一個 Angular directive 更新<code>&lt;form&gt;</code>  標籤，那就是  <code>NgSubmit</code> ， 並且透過事件繫結機制把它繫結到  <code>HeroFormComponent.submit()</code>方法上。</p><pre><code class="html">&lt;form *ngIf=&quot;active&quot; (ngSubmit)=&quot;onSubmit()&quot; #heroForm=&quot;ngForm&quot;&gt;&lt;/form&gt;</code></pre><p>最後，我們定義了一個 template 參考變數  <strong>#heroForm</strong> ，並且把它初始化為 “ngForm” 。這個  <code>heroForm</code>  變數現在引用的是  <code>NgForm</code> directive，它代表的是表單的整體。</p><h4 id="NgForm-directive"><a href="#NgForm-directive" class="headerlink" title="NgForm directive"></a>NgForm directive</h4><p>什麼  <code>NgForm</code> directive？ 我們沒有新增過  <a href="https://angular.cn/docs/ts/latest/api/common/index/NgForm-directive.html">NgForm</a> directive 啊！</p><p>其實是 Angular 幫我們做了，它自動建立了  <code>NgForm</code> directive，並且把它附加到  <code>&lt;form&gt;</code>  標籤上。</p><p><code>NgForm</code> directive 為普通的  <code>form</code>  元素擴充了額外的特性。 它持有我們透過  <code>ngModel</code> directive 和  <code>name</code>  屬性為各個元素建立的那些控制項 Class，並且監視它們的屬性變化，包括有效性。 它還有自己的  <code>valid</code>  屬性，只有當<strong>每一個被包含的控制項</strong>都有效時，它才有效。</p><h3 id="Step-9-禁用此表單的送出按鈕，直到表單變為有效"><a href="#Step-9-禁用此表單的送出按鈕，直到表單變為有效" class="headerlink" title="Step 9. 禁用此表單的送出按鈕，直到表單變為有效"></a>Step 9. 禁用此表單的送出按鈕，直到表單變為有效</h3><p>template 中後的部分，透過  <code>heroForm</code>  變量，把按鈕的  <code>disabled</code>  屬性繫結到了表單的全員有效性。</p><pre><code class="html">&lt;button type=&quot;submit&quot; class=&quot;btn btn-default&quot; [disabled]=&quot;!heroForm.form.valid&quot;&gt;  Submit&lt;/button&gt;</code></pre><p>重新執行應用。表單打開時，狀態是有效的，按鈕是可用的。</p><p>現在，刪除<strong>姓名</strong>。我們違反了 「必填姓名」 規則，它還是像以前那樣顯示了錯誤訊息來提醒我們。同時，「送出」 按鈕也被禁用了。</p><p>沒想明白？再想一會兒。如果沒有 Angular <code>NgForm</code>  的幫助，我們又該怎麼讓按鈕的禁用 &#x2F; 啟用狀態和表單的有效性關聯起來呢？</p><p>有了 Angular ，它就是這麼簡單：</p><ol><li>定義一個 template 參考變數，放在 ( 強化過的 ) form 元素上</li><li>從 50 行之外的按鈕上引用這個變數。</li></ol><h3 id="切換兩個表單區域-延伸學習"><a href="#切換兩個表單區域-延伸學習" class="headerlink" title="切換兩個表單區域 ( 延伸學習 )"></a>切換兩個表單區域 ( 延伸學習 )</h3><p>來實現一些更明顯的視覺效果。 隱藏掉資料輸入框，並且顯示一些別的東西。</p><p>先把表單包裹進  <code>&lt;div&gt;</code>  中，並且把它的  <code>hidden</code>  屬性繫結到  <code>HeroFormComponent.submitted</code>  屬性上。</p><pre><code class="html">&lt;div [hidden]=&quot;submitted&quot;&gt;  &lt;h1&gt;Hero Form&lt;/h1&gt;  &lt;form *ngIf=&quot;active&quot; (ngSubmit)=&quot;onSubmit()&quot; #heroForm=&quot;ngForm&quot;&gt;    &lt;!-- ... all of the form ... --&gt;  &lt;/form&gt;&lt;/div&gt;</code></pre><p>主表單從一開始就是可見的，因為  <code>submitted</code>  屬性是 false ，直到我們送出這個表單。來自<code>HeroFormComponent</code>  的程式碼片段告訴了我們這一點：</p><pre><code class="typescript">submitted = false;onSubmit() &#123; this.submitted = true; &#125;</code></pre><p>當我們點擊提交按鈕時， <code>submitted</code>  標誌會變成 true ，並且表單像預想中一樣消失了。</p><p>現在，當表單處於已送出狀態時，我們需要顯示一些別的東西。 在我們剛剛寫的  <code>&lt;div&gt;</code>  下方，新增下列 HTML ：</p><pre><code class="html">&lt;div [hidden]=&quot;!submitted&quot;&gt;  &lt;h2&gt;You submitted the following:&lt;/h2&gt;  &lt;div class=&quot;row&quot;&gt;    &lt;div class=&quot;col-xs-3&quot;&gt;Name&lt;/div&gt;    &lt;div class=&quot;col-xs-9  pull-left&quot;&gt;&#123;&#123; model.name &#125;&#125;&lt;/div&gt;  &lt;/div&gt;  &lt;div class=&quot;row&quot;&gt;    &lt;div class=&quot;col-xs-3&quot;&gt;Alter Ego&lt;/div&gt;    &lt;div class=&quot;col-xs-9 pull-left&quot;&gt;&#123;&#123; model.alterEgo &#125;&#125;&lt;/div&gt;  &lt;/div&gt;  &lt;div class=&quot;row&quot;&gt;    &lt;div class=&quot;col-xs-3&quot;&gt;Power&lt;/div&gt;    &lt;div class=&quot;col-xs-9 pull-left&quot;&gt;&#123;&#123; model.power &#125;&#125;&lt;/div&gt;  &lt;/div&gt;  &lt;br /&gt;  &lt;button class=&quot;btn btn-default&quot; (click)=&quot;submitted=false&quot;&gt;Edit&lt;/button&gt;&lt;/div&gt;</code></pre><p>它透過插值表達式繫結顯示為唯讀內容。 這一小段 HTML 只在元件處於已提交狀態時才會顯示。然後新增了一個 「編輯」 按鈕，它的 click 事件被繫結到了一個表達式來重設  <code>submitted</code>  為 false。當我們點它時，這個唯讀區塊消失了，可編輯的表單重新出現了。</p><h2 id="結論"><a href="#結論" class="headerlink" title="結論"></a>結論</h2><p>本章討論的 Angular 2 表單利用了下列框架特性來支援資料修改、驗證和更多操作：</p><ul><li>Angular HTML 表單 template 。</li><li>帶有  <code>Component</code>  裝飾器的元件類別。</li><li>用來處理表單提交的  <code>ngSubmit</code> directive。</li><li>template 參考變數，如  <code>#heroForm</code> 、 <code>#name</code> 、 <code>#alter-ego</code>  和  <code>#power</code> 。</li><li>用於雙向資料繫結、資料驗證和追蹤變更的  <code>[(ngModel)]</code>  語法</li><li>指向 input 控制項中參考變數上的  <code>valid</code>  屬性，可用於檢查控制項是否有效、是否顯示 &#x2F; 隱藏錯誤訊息。</li><li>透過繫結到  <code>NgForm</code>  的有效性狀態，控制送出按鈕的禁用狀態。</li><li>對無效控制項，自訂 CSS Class 來為使用者提供視覺反饋。</li></ul>]]></content>
      
      
      <categories>
          
          <category> Angular </category>
          
      </categories>
      
      
        <tags>
            
            <tag> Angular 2 </tag>
            
            <tag> Forms </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Hexo 預設 template 頁面切換按鈕問題</title>
      <link href="/2016/07/23/hexo-template-page-button/"/>
      <url>/2016/07/23/hexo-template-page-button/</url>
      
        <content type="html"><![CDATA[<p>最近開始在使用 Hexo 來寫部落格文章，這是一個 blog framework，使用起來很方便。只要透過 Markdown 語法就可以做出常用的基本排版了，之後再寫篇介紹的文章囉！</p><p>今天遇到了一個問題，Hexo 的預設佈景主題 landscape 文章列表的頁面切換按鈕顯示異常。看到覺得奇怪，難道這是什麼神奇的格式嗎？</p><p><img src="/images/hexo-template-page-button/1-the-next-issue.png" alt="按鈕文字應該是要顯示下一頁才對"></p><p>經過抽絲剝繭的調查，原來是預設的佈景主題在頁面切換的按鈕語法似乎寫錯了。<br>下面是 template 中 archive.ejs 的檔案其中一部分的內容，主要就是 page-nav 的部分有誤。</p><pre><code class="ejs">&lt;% if (page.total &gt; 1)&#123; %&gt;  &lt;nav id=&quot;page-nav&quot;&gt;    &lt;%- paginator(&#123;      prev_text: &quot;&amp;laquo; +__(&#39;prev&#39;)&quot;,      next_text: &quot;__(&#39;next&#39;)+ &amp;raquo;&quot;    &#125;) %&gt;  &lt;/nav&gt;&lt;% &#125; %&gt;</code></pre><p>將上方的 <code>prev_text</code> 與 <code>next_text</code> 後面的內容修改一下，引號的位置錯囉…</p><pre><code class="ejs">prev_text: &quot;&amp;laquo; &quot;+__(&#39;prev&#39;),next_text: __(&#39;next&#39;)+&quot; &amp;raquo;&quot;</code></pre><p>這樣就可以正常顯示囉 XD</p><p><img src="/images/hexo-template-page-button/2-slove-way.png" alt="這才是正確的按鈕文字的顯示"></p>]]></content>
      
      
      <categories>
          
          <category> Hexo </category>
          
      </categories>
      
      
        <tags>
            
            <tag> template issue </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>VS Code 檔案顯示設定</title>
      <link href="/2016/07/21/vscode-file-display/"/>
      <url>/2016/07/21/vscode-file-display/</url>
      
        <content type="html"><![CDATA[<h2 id="開始寫-Typescript-之後…"><a href="#開始寫-Typescript-之後…" class="headerlink" title="開始寫 Typescript 之後…"></a>開始寫 Typescript 之後…</h2><p>編譯後的檔案都會出現在同一個地方，導致每次點選檔案的時候都要留一下自己點到的到底是 <strong>ts</strong> 還是 <strong>js</strong> 很不方面。因此開始尋找是否有辦法可以隱藏 Typescript 編譯後的檔案，畢竟我們很少會去看編譯後的檔案，除了一開始學習 typescript 時，會觀察一下編譯前後的變化…但，到後面還是覺得隱藏起來比較方便！</p><p><img src="/images/vscode-file-display/1-no-file-hidden.png" alt="重複顯示的檔名使人眼花"></p><span id="more"></span><h3 id="步驟一：開啟-Workspace-Settings"><a href="#步驟一：開啟-Workspace-Settings" class="headerlink" title="步驟一：開啟 Workspace Settings"></a>步驟一：開啟 Workspace Settings</h3><p>在 VS Code 按 <code>cmd</code> + <code>shift</code> + <code>p</code> 打開指令視窗</p><p><img src="/images/vscode-file-display/2-open-cmd-window.png" alt="打開指令視窗輸入 Workspace Settings"></p><h3 id="步驟二：輸入-Workspace-Settings-編輯工作區組態設定"><a href="#步驟二：輸入-Workspace-Settings-編輯工作區組態設定" class="headerlink" title="步驟二：輸入 Workspace Settings 編輯工作區組態設定"></a>步驟二：輸入 Workspace Settings 編輯工作區組態設定</h3><p>接著輸入 <code>work</code>，不需要完整輸入即可看到 <code>Preference: Open Workspace Settings</code> 然後按 Enter 打開。</p><p><img src="/images/vscode-file-display/3-show-setting-content.png" alt="左邊為設定參考範本，右邊為設定內容"></p><h3 id="步驟三：開始設定，輸入-files-exclude"><a href="#步驟三：開始設定，輸入-files-exclude" class="headerlink" title="步驟三：開始設定，輸入 files.exclude"></a>步驟三：開始設定，輸入 files.exclude</h3><p>在設定編輯區輸入 <code>files.exclude</code>，因為有提示字的關係，只要輸入 file 開頭就可以看到選項囉！Enter 選擇之後會有預設的範本。</p><p><img src="/images/vscode-file-display/4-input-settings.png" alt="輸入 files.exclude"></p><h3 id="步驟四：加上新條件，隱藏所有-js-檔案"><a href="#步驟四：加上新條件，隱藏所有-js-檔案" class="headerlink" title="步驟四：加上新條件，隱藏所有 js 檔案"></a>步驟四：加上新條件，隱藏所有 js 檔案</h3><p>這時候在下方加個新項目，將我們要隱藏的檔案類型加上去。條件為 “隱藏專案目錄底下所有的 js 檔案”<br>輸入 <code>&quot;**/*.js&quot;:true</code></p><p><img src="/images/vscode-file-display/5-input-filesetting.png" alt="新增隱藏所有專案目錄下的 js 檔案"></p><h3 id="這時候你或許會注意到…"><a href="#這時候你或許會注意到…" class="headerlink" title="這時候你或許會注意到…"></a>這時候你或許會注意到…</h3><p>不對阿，有時候我們會抓 js 套件來使用，這些套件不一定都是 typescript 寫的，怎麼辦？別緊張，我們的條件設定是可以有很彈性的。<br>將剛才輸入的 <code>&quot;**/*.js&quot;</code> 後面的 <code>true</code> 這段改成 <code>&#123; &quot;when&quot;: &quot;$(basename).ts&quot; &#125;</code> 如下圖。<br>這是什麼意思呢？意思是當 ts 檔案類型的名稱和 js 的檔案類型名稱一樣時，條件就會成立並進行過濾的動作。</p><p><img src="/images/vscode-file-display/6-setting-advance.png" alt="修改過濾條件"></p><h3 id="順便隱藏-map-js-檔案吧"><a href="#順便隱藏-map-js-檔案吧" class="headerlink" title="順便隱藏 map.js 檔案吧"></a>順便隱藏 map.js 檔案吧</h3><p>我們也可以再加上一個條件來隱藏 map.js 的檔案。避免太多名稱相同且不一定會用到的檔案出現。</p><p><img src="/images/vscode-file-display/7-comment.png" alt="加入新的設定來隱藏 map.js 檔案"></p><h3 id="完成，看起來清爽多了"><a href="#完成，看起來清爽多了" class="headerlink" title="完成，看起來清爽多了!"></a>完成，看起來清爽多了!</h3><p>修改完成，這樣看起來是不是比較輕鬆了呢？ XD</p><p><img src="/images/vscode-file-display/8-done.png" alt="修改完成，看起來輕鬆多了"></p><p>參考: <a href="http://stackoverflow.com/questions/31587949/hide-js-map-files-in-visual-studio-code">Hide JS files in visual studio code</a></p>]]></content>
      
      
      
        <tags>
            
            <tag> Visual Studio Code </tag>
            
            <tag> VScode 設定 </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Http status 狀態筆記</title>
      <link href="/2014/10/09/http-status-the-status-notes/"/>
      <url>/2014/10/09/http-status-the-status-notes/</url>
      
        <content type="html"><![CDATA[<h1 id="HTTP-Status-狀態代表的意思"><a href="#HTTP-Status-狀態代表的意思" class="headerlink" title="HTTP Status 狀態代表的意思"></a>HTTP Status 狀態代表的意思</h1><p><strong>網頁接收到伺服器的回應後，都會自動去判讀網頁的狀態，其中的 Http Status 代碼的意思如下：</strong></p><pre><code>- 200 伺服器回應Data成功。- 206 取得片段資料，Http Request 中有的 Range 屬性，可以指定要取得那一段Bytes數。- 301 目標網頁移到新網址(永久轉址)。- 302 暫時轉址- 304 已讀取過的圖片或網頁，由瀏覽器緩存 (cache) 中讀取。- 401 需身分驗證，如 SSL key or htaccess pasword。- 403 沒有權限讀取，可能是 IP 被阻檔或是伺服器限制。- 404 伺服器未找到目標網址，檔案不存在。- 408 Client Request timeout- 411 沒有指定 content-length，使用 POST 傳送參數時，必須指定參數的總長度- 414 URL 太長導致伺服器拒絕處理。- 500 伺服器發生錯誤 : 可能是 htaccess 有錯- 503 伺服器當掉 : maybe is code dump- 505 不支此 HTTP 版本</code></pre><p>資料來源： <a href="http://www.puritys.me/docs-blog/article-45-Http-status-%E7%8B%80%E6%85%8B-404-304.html">Http status 狀態 404 304</a></p>]]></content>
      
      
      <categories>
          
          <category> HTTP </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>使用 CSS 的 ::before 自訂 HTML 列表樣式</title>
      <link href="/2014/09/18/use-css-before-customizing-html-list-style/"/>
      <url>/2014/09/18/use-css-before-customizing-html-list-style/</url>
      
        <content type="html"><![CDATA[<p>今天看到一篇關於 CSS 的自訂列表計數器的相關運用，來分享一下。</p><p>以下介紹如何使用 CSS 的 ::before selector 自訂 HTML ordered lists（ol）的編號樣式。</p><p>一般 HTML 的 ordered lists（ol）呈現的效果是這樣：</p><ol>    <li>aaaa</li>  <li>bbbb</li>  <li>cccc</li>  <li>dddd</li>  <li>eeee</li></ol><p>我們這裡介紹如何使用 CSS 自訂每一個項目的編號：<br><img src="/images/use-css-before-customizing-html-list-style/stylesample.png"></p><p>步驟練習：</p><span id="more"></span><p>Step1.首先，將既有的編號拿掉，並加上一些邊界空白的設定。</p><pre><code class="css">.custom-counter  padding-left: 10px  margin-left: 0  padding-right: 0  list-style-type: none</code></pre><p>Step2.使用 <strong>counter-increment</strong> 自訂計數器的名稱。</p><pre><code class="css">.custom-counter li  counter-increment: step-counter  margin: 10px 0</code></pre><p>這裡的 <strong>step-counter</strong> 是一個自訂的名稱，您可以隨便取，只要跟隨後 ::before 中的名稱有對應好即可。</p><p>Step3.使用 <strong>::before</strong> 在每個項目前面插入自訂的編號，並設定編號的樣式。</p><pre><code class="css">.custom-counter li::before  content: counter(step-counter)  margin-right: 5px  font-size: 80%  background-color: #2ecc71  color: white  font-weight: blod  padding: 3px 8px  border-radius: 4px</code></pre><p>這裡的 counter 要對應 Step2. 的自訂計數器名稱（這裡是 step-counter），<br>這樣瀏覽器就會自動計算 li 的個數並依序編號，這樣就可以完成自訂列表編號的樣式囉^^</p><p>參考來源：<a href="http://www.gtwang.org/2014/09/customize-ordered-lists-pseudo-element.html">http://www.gtwang.org/2014/09/customize-ordered-lists-pseudo-element.html</a></p>]]></content>
      
      
      <categories>
          
          <category> CSS </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>document.body.scrollTop IE 和 Firefox 沒作用</title>
      <link href="/2014/09/17/documentbodyscrolltop-ie-and-firefox-not-responding/"/>
      <url>/2014/09/17/documentbodyscrolltop-ie-and-firefox-not-responding/</url>
      
        <content type="html"><![CDATA[<p>今天寫 js 的效果時候，發現 document.body.scrollTop 在 Chrome、Opera 上都可以順利取得瀏覽器的 top 位置，</p><p>但是 IE、Firefox 卻完全沒有反應，console.log 出來，捲軸怎麼滾就只是個 0 ，後來問了 Google 大神，</p><p>發現有其他的解決辦法。</p><p>只要換成 jQuery 的 <strong>scrollTop()</strong> 就都能正常運作了^^</p><p>記錄下來：</p><span id="more"></span><p>工作上用到的一小段 code</p><pre><code class="js">// called when the window is scrolled.window.onscroll = function () &#123;  var scrollTop = $(document).scrollTop();  if (scrollTop &gt; 50) &#123;    $(&#39;#nav&#39;).addClass(&#39;nav-shadow&#39;);  &#125; else if (document.body.scrollTop &lt; 51) &#123;    $(&#39;#nav&#39;).removeClass(&#39;nav-shadow&#39;);  &#125;  if (scrollTop &gt;= 3600) &#123;    TweenMax.to(&#39;.img_m_zip&#39;, 0.7, &#123;      opacity: 1,      delay: 0.4,      left: &#39;10%&#39;,      ease: &#39;easeOut&#39;,    &#125;);  &#125;  if (scrollTop &gt;= 4200) &#123;    TweenMax.to(&#39;.img_g_zip&#39;, 0.7, &#123;      opacity: 1,      delay: 0.4,      left: &#39;13%&#39;,      ease: &#39;easeOut&#39;,    &#125;);  &#125;&#125;;</code></pre><p>參考資料： <a href="http://api.jquery.com/scrollTop/">jQuery scrollTop() api</a></p>]]></content>
      
      
      <categories>
          
          <category> JavaScript </category>
          
          <category> jQuery </category>
          
      </categories>
      
      
        <tags>
            
            <tag> scrollTop </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Bootstap nav-scroller 用法紀錄</title>
      <link href="/2014/09/11/bootstap-nav-scroller-usage-records/"/>
      <url>/2014/09/11/bootstap-nav-scroller-usage-records/</url>
      
        <content type="html"><![CDATA[<p>現在 Bootstrap 非常的流行，只要打好 html 架構後套上 class 就可以呈現出很有質感的效果。</p><p>今天用 Bootstrap 製作 nav 導覽列點擊連結移動到同頁面的目標區塊，使它有動態滾動捲軸的效果，</p><p>於是找到了 <strong>scrolling-nav.js</strong> !!</p><p>我們來看下方的原始碼</p><span id="more"></span><pre><code class="html">&lt;script src=&quot;./js/scrolling-nav.js&quot;&gt;&lt;/script&gt;&lt;div id=&quot;nav&quot; class=&quot;navbar navbar-inverse navbar-fixed-top&quot; role=&quot;navigation&quot;&gt;      &lt;div class=&quot;container&quot;&gt;        &lt;div class=&quot;navbar-header&quot;&gt;          &lt;button type=&quot;button&quot; class=&quot;navbar-toggle collapsed&quot; data-toggle=&quot;collapse&quot; data-target=&quot;.navbar-collapse&quot;&gt;            &lt;span class=&quot;sr-only&quot;&gt;Toggle navigation&lt;/span&gt;            &lt;span class=&quot;icon-bar&quot;&gt;&lt;/span&gt;            &lt;span class=&quot;icon-bar&quot;&gt;&lt;/span&gt;            &lt;span class=&quot;icon-bar&quot;&gt;&lt;/span&gt;          &lt;/button&gt;          &lt;a class=&quot;navbar-brand&quot; href=&quot;#home&quot;&gt;Project name&lt;/a&gt;        &lt;/div&gt;        &lt;div class=&quot;collapse navbar-collapse&quot;&gt;            &lt;!-- 這邊是nav連結的區塊 start --&gt;          &lt;ul class=&quot;nav navbar-nav&quot;&gt;            &lt;li class=&quot;active&quot;&gt;&lt;a class=&quot;page-scroll&quot; href=&quot;#home&quot;&gt;Home&lt;/a&gt;&lt;/li&gt;            &lt;li&gt;&lt;a class=&quot;page-scroll&quot; href=&quot;#about&quot;&gt;About&lt;/a&gt;&lt;/li&gt;            &lt;li&gt;&lt;a class=&quot;page-scroll&quot; href=&quot;#contact&quot;&gt;Contact&lt;/a&gt;&lt;/li&gt;          &lt;/ul&gt;          &lt;!-- 這邊是nav連結的區塊 end --&gt;        &lt;/div&gt;      &lt;/div&gt;&lt;/div&gt;&lt;section id=&quot;home&quot;&gt;....&lt;/section&gt;&lt;section id=&quot;about&quot;&gt;....&lt;/section&gt;&lt;section id=&quot;contact&quot;&gt;....&lt;/section&gt;</code></pre><p>先將 <strong>scrolling-nav.js</strong> 放上去後，在各個連結加上 <strong>page-scroll</strong> 的 class。</p><p>一般靜態的用法就只是將 href 補上區塊的 id，我們透過這個方法就可以很輕鬆的呈現動態滾動的效果。</p><p>另外在練習的過程中，可能會遇到滾動的位置被上方的 nav 蓋到，原因滾動的目標<strong>區塊其定位是在瀏覽器視窗最上方</strong>。</p><p>那我們最上方有固定到 nav 所以才會有這樣的情況，所以各個區塊可以再加上padding-top 即可解決。</p><p><strong><a href="http://jsbin.com/valawu/4">參考JSbin範例</a></strong></p>]]></content>
      
      
      <categories>
          
          <category> Bootstap </category>
          
          <category> Nav-Scrolling </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>Sass筆記「@mixin」介紹：節省重複撰寫CSS樣式的時間</title>
      <link href="/2014/08/13/using-sass-mixin-saves-repeating-the-time-writing-the-same-css-style/"/>
      <url>/2014/08/13/using-sass-mixin-saves-repeating-the-time-writing-the-same-css-style/</url>
      
        <content type="html"><![CDATA[<p>撰寫 CSS 的時候，時常會遇到一種情況：</p><p>在開發多種 CSS 樣式時，會將第一次寫的程式碼複製貼上後，再進行修改，</p><p>日後樣式需要整個大修時(例：圓形改方形)，又必須將所有 CSS 重新逐一修正，非常不方便。</p><p>使用 Sass @mixin 的話，上述的問題可輕鬆解決，同時還可傳入多個變數進去。</p><p>我們先來看下面的 code：</p><span id="more"></span><pre><code class="sass">$font-size:13px /*設變數font-size*/@mixin bg    background: #000    font-size: $font-size.header    +bg</code></pre><p>編譯之後如下：</p><pre><code class="css">.header &#123;  background: black;  font-size: 13px;&#125;</code></pre><p>前面以@mixin 開頭，後面的 bg 則是命名要 mixin 的名稱。</p><p>所以如果.header 要載入的話，寫「+」後面接 mixin 名稱即可載入。</p><p>同時你也可以載入在外面的變數，當然也可以在裡面進行運算(加減乘除)。</p><p>再來假設背景顏色隨時會更動，你也可以在 mixin 建立變數：</p><pre><code class="sass">$font-size:13px@mixin bg($bgcolor) /*mixin 建立 bg 加入 bgcolor 變數*/    background: $bgcolor    font-size: $font-size.header    +bg(#000) /*變數設定#000*/.content    +bg(#fff) /*變數設定#fff*/</code></pre><p>編譯後的結果如下：</p><pre><code class="css">.header &#123;  background: black;  font-size: 13px;&#125;.content &#123;  background: white;  font-size: 13px;&#125;</code></pre><p>@mixin 變數也可具有預設值，並載入多種變數：</p><pre><code class="sass">@mixin bg($bgcolor:#000,$width:200px)    background: $bgcolor    width: $width.header    +bg.footer    +bg(#ff0000,300px)</code></pre><p>編譯後</p><pre><code class="css">.header &#123;  background: black;  width: 200px;&#125;.footer &#123;  background: red;  width: 300px;&#125;</code></pre><p>透過變數載入的方式，就可以將樣式獨立出來，透過 @mixin 來進行集中管理與設計。</p><p>參考來源：<a href="http://ithelp.ithome.com.tw/question/10128138">30 天掌握 Sass 語法 - (6)利用 Sass「@mixin」，讓你省去重複撰寫相同 CSS 樣式的時間</a></p>]]></content>
      
      
      <categories>
          
          <category> SASS </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>Sass筆記「@extend」介紹：無痛合併CSS樣式</title>
      <link href="/2014/08/12/using-sass-extend-painless-merging-css-styles/"/>
      <url>/2014/08/12/using-sass-extend-painless-merging-css-styles/</url>
      
        <content type="html"><![CDATA[<p>在撰寫 CSS 過程中，為了避免 CSS 太龐大，當我們有用到相同的樣式時，</p><p>都會將它合併起來如下：</p><pre><code class="css">/* 第200行位置 */.header h1,.content h1,.footer h1 &#123;  font-size: 20px;  line-height: 1.8;  letter-spacing: 1px;&#125;/* 第400行位置 */.header h1 &#123;  color: black;&#125;/* 第1000行位置 */.content h1 &#123;  color: green;&#125;/* 第N000行位置 */.footer &#123;  color: pink;&#125;</code></pre><p>但這樣子會有個麻煩的地方是，假設合併樣式程式碼的位置在第 200 行，而我目前位置是在 N 千多行。</p><p>當需要合併樣式時，又必須回到第 200 行來合併 class 樣式，所以當程式碼越變越多時，</p><p>要集中相同樣式的工作流程相對也會變得更加繁瑣。</p><p>因此 Sass ＠extend 繼承的方式可以解決這樣的問題。</p><span id="more"></span><p>使用 Sass 的 ＠extend：</p><pre><code class="sass">.all-h1 /*建立繼承用的樣式*/    font-size: 20px    line-height: 1.8    letter-spacing: 1px.header h1    @extend .all-h1    color: #000.content h1    @extend .all-h1    color: green.footer    @extend .all-h1    color: pink</code></pre><p>這樣產生的結果會是</p><pre><code class="scss">/* 第200行位置 */.all-h1,.header h1,.content h1,.footer h1 &#123;  font-size: 20px;  line-height: 1.8;  letter-spacing: 1px;&#125;/* 第400行位置 */.header h1 &#123;  color: black;&#125;/* 第1000行位置 */.content h1 &#123;  color: green;&#125;/* 第N000行位置 */.footer &#123;  color: pink;&#125;</code></pre><p>但這樣還不是夠好，因為多出來的 <code>.all-h1</code> 不一定會用到，是多出來的。</p><p>因此，我們可以在繼承的類別名稱前面，加上「 <code>%</code> 」來將它合併起來。</p><pre><code class="scss">%all-h1 /*建立繼承用的樣式*/    font-size: 20px    line-height: 1.8    letter-spacing: 1px.header h1    @extend %all-h1    color: #000.content h1    @extend %all-h1    color: green.footer    @extend %all-h1    color: pink</code></pre><p>編譯後的結果也會和最上面的 CSS 一樣，首先於上方撰寫合併用的程式碼，也就是「%all-h1」。</p><p>「<code>%</code>」後面加上自己命名要合併樣式的名稱例如：</p><pre><code class="sass">%all-class_name</code></pre><p>再來在繼承用的 class 加上@extend 後面接%all-h2，編譯出來的程式碼便會將其合併。</p><p>所以往後寫 css 有樣式需要合併時，直接用@extend 的用法就可以輕鬆達成囉！</p><h3 id="問題來了"><a href="#問題來了" class="headerlink" title="問題來了"></a>問題來了</h3><p>究竟<strong>Mixin</strong>與<strong>extend</strong>的使用時機該如何抉擇？</p><p>基本上呢，</p><p><strong>@mixin</strong>是將程式碼帶入到對應的 class 去，同時可帶入變數。</p><p><strong>@extend</strong>則是藉由合併 class，並吃到共通樣式，但沒辦法帶入變數。</p><p>所以如果你的樣式都固定不變的，不會需要帶參數去改變樣式的話，</p><p>使用@extend，程式碼會比較少些。</p><p>但如果你的程式碼需要帶入多個變數進行運算時，那用@mixin 則較適合。</p><p>參考來源：<a href="https://www.facebook.com/sfismy">sfisonly</a>，<a href="http://ithelp.ithome.com.tw/question/10128359">30 天掌握 Sass 語法 - (7)利用 Sass「@extend」，讓你無痛合併 CSS 樣式</a></p>]]></content>
      
      
      <categories>
          
          <category> SASS </category>
          
      </categories>
      
      
        <tags>
            
            <tag> sass </tag>
            
            <tag> extend </tag>
            
        </tags>
      
    </entry>
    
    
    
    <entry>
      <title>Sass版本與Compass版本的相依問題</title>
      <link href="/2014/08/08/sass-and-compass-versions-questions/"/>
      <url>/2014/08/08/sass-and-compass-versions-questions/</url>
      
        <content type="html"><![CDATA[<p>今天想嘗試 Sass framework ，Bourbon !!</p><p>但是在編譯的過程中遇到了一些問題，就是 <strong>sass 已經更新到 3.3 版了，compass 仍然使用 3.2 版</strong>，於是上網四處找資料。</p><p>在經過苦痛的 google 搜尋之後，才發現原來 compass 有對應的 sass 版本相依，由於沒有裝 compass 相關 app，</p><p>所以不清楚是不是可以直接在哪邊做 sass 版本的修改。</p><span id="more"></span><p>因此最後發現的解決辦法是，把現有的 compass 移除，並安裝最新版(或 beta 版)的 compass。</p><p><strong>目前安裝完的 compass 版本是(1.0.0.rc.1)</strong><br>輸入</p><pre><code>gem install compass --pre</code></pre><p><img src="/images/sass-and-compass-versions-questions/compass-version.jpg" alt="compass版本安裝與確認"></p><p>如此一來就可以讓使用 Bourbon 的 sass 檔案順利進行編譯囉！</p><p>參考來源：<a href="http://stackoverflow.com/questions/22427567/is-sass-3-3-3-compatible-with-compass">stackoverflow：Is sass 3.3.3 compatible with compass</a></p>]]></content>
      
      
      <categories>
          
          <category> SASS </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>Sass環境建置紀錄</title>
      <link href="/2014/08/05/sass-record-of-built-environment/"/>
      <url>/2014/08/05/sass-record-of-built-environment/</url>
      
        <content type="html"><![CDATA[<p>最近開始練習 Compass + Sass 的練習，記錄一下如何在 Windows 系統下建置 Sass 開發環境。</p><p><strong>首先，安裝 Ruby</strong></p><p>Sass 與 Compass 是用 ruby 開發的，在 windows 的環境下，</p><p>就必須先到他的官網安裝最新的 ruby，<a href="http://rubyinstaller.org/downloads/">http://rubyinstaller.org/downloads/</a></p><p><strong>接著安裝 Sass、compass</strong></p><p>在開始工作列程式搜尋欄位輸入「CMD」後開啟「命令提示字元」，輸入以下指令後按 ENTER。</p><pre><code>gem install compass</code></pre><p>compass 安裝完成之後接著安裝 sass</p><span id="more"></span><pre><code>gem install sass</code></pre><p><strong>建立新專案</strong></p><p>先進入要建立專案的資料夾</p><p>接著輸入指令 (以 project001 名稱為例)</p><pre><code>compass create project001</code></pre><p>完成之後可以在資料夾看到新增好的專案及檔案。</p><p><strong>Subelime Text package control 安裝 sass snippets &amp; compass</strong></p><p>接著開啟 Sublime Text 編輯器，按 <code>Ctrl + Shift +P</code> 鍵，再輸入<code>install</code>。</p><p>當安裝完成後，下方就會出現成功的訊息，再重覆以上步驟，分別再安裝 SASS snippets、Compass 二個套件。</p><p><strong>在 Sublime Text 使用 Sass：</strong></p><p>都完成上述步驟之後，就可以開始寫 sass 囉！</p><p>首先，進到 Sublime Text 後，再選擇 Project &#x2F; Add Folder to Project (項目 &gt; 增加資料夾到項目)選項。<br><img src="/images/sass-record-of-built-environment/add-item-to-folder.jpg"></p><p>然後選擇剛所建立好的專案目錄。</p><p>選擇完畢後，再選擇 View &#x2F; Show Side Bar (檢視 &gt; 顯示&#x2F;隱藏側邊攔)選項。<br><img src="/images/sass-record-of-built-environment/hide-side-bar.jpg"></p><p>接著左側就會出現專案的目錄，sass 是儲放原始檔的目錄，而 stylesheets 是轉存好的 css 檔。</p><p>按<code>Alt+Shift+2</code>，將畫面一分為二，再個別載入檔案，一個是原檔，另一個是編譯後的 CSS 檔。</p><p>開啟命令視窗，進入該專案的目錄下，再輸入 compass watch 指令，並請勿關閉此視窗，由於它會自動監控，</p><p>每當 Sublime Text 一儲存時，就會立即編譯成 css 檔。這時可看到，右邊立即就會呈現出，左邊所寫的結果。</p><p><strong>千萬要記得，別關掉命令視窗，否則會無法即時的進行編譯!</strong></p><p>而要停止監控(watch)的話，在命令提示視窗打<code>ctrl+c</code>就可以停止。</p><p><strong>config.rb 設定</strong></p><p>如果希望 sass 編譯出來的 css 不要有註解，那就打開根目錄的 config.rb，</p><p>將# line_comments &#x3D; false 前面的#號拿掉就不會產生出註解。<br><img src="/images/sass-record-of-built-environment/remove-comment.jpg"></p><p>裡面會有四行以下的預設設定碼，如果你放 CSS 的資料夾名稱為 CSS，便把 stylesheets 名稱改為 CSS，</p><p>這樣 Sass 編譯出來的 CSS 就會在 CSS 資料夾，而不會 style 裡面。</p><p><strong>注意</strong>：當修改 config 設定後，要重新在命令提示字元 watch 資料夾一次，設定才會生效。</p><p>資料來源：<a href="http://www.minwt.com/html/10003.html">梅問題教學網</a>、<a href="http://ithelp.ithome.com.tw/question/10128634">30 天掌握 Sass 語法</a></p>]]></content>
      
      
      <categories>
          
          <category> SASS </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title> Javascript：this用法整理</title>
      <link href="/2014/07/14/javascriptthis-use-finishing/"/>
      <url>/2014/07/14/javascriptthis-use-finishing/</url>
      
        <content type="html"><![CDATA[<p>看到不錯的文章，轉貼過來紀錄做個分享。<br>轉貼來源：<a href="https://software.intel.com/zh-cn/blogs/2013/10/09/javascript-this">https://software.intel.com/zh-cn/blogs/2013/10/09/javascript-this</a></p><p>常用 Javascript 的人都知道，［this 這個關鍵字在一個函式內究竟指向誰］的這個問題很令人頭大，這裡整理了一下 Javascript 中 this 的指向的五種不同情況，其中前三種屬於基本的情況，而後兩種情況可基於前三種情況的方式來進行思考。</p><p>#1.this 指向於調用該函式之物件</p><p>如果你有學過 C&#x2F;C++，你可能會記得一個物件內的成員函式裡的 this 指的即是該成員函式所在之物件，但在 Javascript 裡則有那麼些許不同，Javascript 裡的 this 看的是究竟是誰調用該函式，而不是看該函式被定義在哪個物件內，這個大原則抓到了，基本上就已經可以探知 this 的奧秘了。底下寫一下這種情況的公式與範例：</p><span id="more"></span><p>公式</p><pre><code>物件.函式(); //函式內的this指向該物件</code></pre><p>範例</p><pre><code class="js">var obj = &#123;  x: 20,  f: function () &#123;    console.log(this.x);  &#125;,&#125;;obj.f(); //由於調用f函式時，點前面物件為obj，故f內的this指向obj，則輸出為20。obj.innerobj = &#123;  x: 30,  f: function () &#123;    console.log(this.x);  &#125;,&#125;;obj.innerobj.f(); //由於調用f函式時，點前面物件為obj.innerobj，故f內的this指向obj.innerobj，則輸出為30。</code></pre><p>#2.this 指向全域物件(瀏覽器：window 物件、node.js：GLOBAL 物件)</p><p>如果調用函式的前方並未有物件，則函式內 this 就指向全域物件。在瀏覽器內全域物件為 window 物件，而在 node.js 中全域物件則為 GLOBAL 物件。底下一樣寫一下這種情況的公式與範例：</p><p>公式</p><pre><code>函式(); //函式內的this指向全域物件</code></pre><p>範例</p><pre><code class="js">var x = 10;var f = function () &#123;  console.log(this.x);&#125;;f(); /*由於調用f函式時，前方並未有[物件.]的形式，故f內的this指向全域物件，則輸出全域變數的x(10)。*/</code></pre><p>##<i>例外：在使用 node.js 時，若使用 node file.js 這樣的方式執行 js 檔，並不會讓宣告的全域變數掛在全域物件上(意指會利用 function 將 code 整個包起來執行)，故輸出應為 undefined。</i></p><p>#前兩種情況常見誤導範例 ##範例一、物件之成員函式內有函式</p><pre><code class="js">var x = 10;var obj = &#123;  x: 20,  f: function () &#123;    console.log(this.x);    var foo = function () &#123;      console.log(this.x);    &#125;;    foo(); // (2)  &#125;,&#125;;obj.f(); // (1)</code></pre><p>這個範例會輸出多少呢？別忘記大原則，在 Javascript 裡的 this 看的是究竟是誰調用該函式，故並不會輸出 20 20，而是輸出 20 10，為什麼呢？因為(1)obj.f()調用時，f 前面物件為 obj，故 f 內的 this 指向 obj。但因為調用 f 內的(2)foo 函式時是用 foo()，調用的前方並未有物件，故 foo 內的 this 指向全域物件，所以輸出會是全域變數的 x 的值。</p><p>若要讓 foo 內使用 obj.x 的值，解法如下：</p><pre><code class="js">var x = 10;var obj = &#123;  x: 20,  f: function () &#123;    console.log(this.x);    var that = this; //使用that保留在這個函式內的this    var foo = function () &#123;      console.log(that.x);    &#125;; //使用that取得obj    foo();  &#125;,&#125;;obj.f();</code></pre><p>##範例二、借用函式</p><pre><code class="js">var x = 10;var obj = &#123;  x: 20,  f: function () &#123;    console.log(this.x);  &#125;,&#125;;obj.f(); // (1)var fOut = obj.f;fOut(); //(2)var obj2 = &#123;  x: 30,  f: obj.f,&#125;;obj2.f(); // (3)</code></pre><p>範例中三次調用之函式的 this 所指向的物件為何，不知道各位能不能看得出來。雖然用的是同一個函式，但是因為調用的不同，故 this 所指向的物件就不同。(1)obj.f()的 f 所指向的是 obj，這比較沒有問題，輸出的會是 20；而(2)fOut()裡的 this，則是因為調用時前方無物件，則 this 所指的是全域物件，輸出的會是 10；最後(3)obj2.f()則是 obj2 去呼叫 f，故 f 內的 this 指向的是 obj2，輸出的會是 30。</p><p>#3.this 指向利用 call 或 apply 所指派給 this 的物件<br>有個方法可以更動前兩種敘述所讓 this 指派的值，就是利用 call 與 apply。call 與 apply 都是呼叫該函式並讓該函式的 this 指向給予 call 或 apply 的第一個參數。至於 call 和 apply 的差別則是在於其後面給予被調用之函式的參數放入的方法不同，一個是直接攤平放在第二個以後的參數；一個是直接放入一個裡面放要給予之參數的陣列。底下一樣看一下公式和範例：</p><p>公式</p><pre><code>(A物件.)函式.call(B物件,參數1,參數2,參數3, ......); //函式的this指向B物件(若B物件為null，則指向全域物件)(A物件.)函式.apply(B物件,[參數1,參數2,參數3, ......]); //函式的this指向B物件(若B物件為null，則指向全域物件)</code></pre><p>範例</p><pre><code>var obj = &#123;    x: 20;    f: function()&#123; console.log(this.x); &#125;&#125;;var obj2 = &#123;    x: 30;&#125;;obj1.f.call(obj2); //利用call指派f的this為指向obj2，故輸出為30</code></pre><p>#4.this 指向 new 所產生之新物件<br>若將函式當作建構式(constructor)來用，則內部的 this 則指向於 new 所產生之新物件。<br>公式</p><pre><code>new 建構式(); //建構式內之this指向new所產生之新物件</code></pre><p>範例</p><pre><code class="js">function Monster() &#123;  this.hp = 100;&#125;var monster = new Monster(); //Monster的this指向new出來之新物件並回傳回來，new的寫法就類似於下面的寫法。var monster = (function () &#123;  var _new = &#123; constructor: Monster, __proto__: Monster.prototype &#125;; //在IE內可能不相似  _new.constructor(); //這也是為何說可以利用前三種情況來變化的原因，constructor呼叫時，this指向的即是_new這個物件。  return _new;&#125;)();</code></pre><p>#5.callback 函式內的 this 會指向於調用放入該 callback 的函式之 this 所指向之物件<br>先想想在 jQuery 中，我們若要讓#button 這個元素被 click 的時候，內容改為“Clicked”這樣的字串，該如何寫呢？</p><pre><code class="js">$(&#39;#button&#39;).click(function () &#123;  this.html(&#39;Clicked&#39;);&#125;);</code></pre><p>此時這個 this 居然會指向$(‘#button’)這個物件，感覺很自然，但實際想想會覺得很神奇。假設你寫一個 function，它可以吃一個 function，並在裡面呼叫傳入的 function，你該怎麼寫呢？</p><pre><code class="js">var f = function(innerf)&#123;    //前面的處理    innerf(arg1, arg2, arg3, ......);    //後面的處理&#125;</code></pre><p>但如果這樣寫的話，innerf 裡的 this 根據前述規則就應該是全域物件了！那為什麼常常別人實作的 callback 函式可讓 this 指向於調用放入該 callback 的函式之 this 所指向之物件呢？這表示大家實作上會遵守一個規則，會將自己的 this 傳給 callback 當作它的 this 來用！這也是為什麼我說這個情況其實也是前三種情況的變化而已了！所以上面的 code 應該改成如下的形式會比較好：</p><pre><code class="js">var f = function(innerf)&#123;    //前面的處理    innerf.call(this, arg1, arg2, arg3, ......);    //或是innerf.apply(this, [arg1, arg2, arg3, ......])    //後面的處理&#125;</code></pre><p>來源：<a href="https://software.intel.com/zh-cn/blogs/2013/10/09/javascript-this">https://software.intel.com/zh-cn/blogs/2013/10/09/javascript-this</a></p>]]></content>
      
      
      <categories>
          
          <category> JavaScript </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>如何優化一個網站的靜態檔案 (assets) 和資源 (resources)？</title>
      <link href="/2014/06/24/how-to-optimize-a-site-for-assets-and-resources/"/>
      <url>/2014/06/24/how-to-optimize-a-site-for-assets-and-resources/</url>
      
        <content type="html"><![CDATA[<p><a href="https://developer.yahoo.com/performance/rules.html">https://developer.yahoo.com/performance/rules.html</a><br><a href="http://www.sitepoint.com/web-site-optimization-steps/">http://www.sitepoint.com/web-site-optimization-steps/</a><br>準備兩篇文章要翻譯~~ #加速你的網站的最好的方式</p><p><em>在 Yahoo 的開發團隊整理出<strong> 35 </strong>項使網頁速度加快的優化方式，其中包含了<strong> 7 大類 </strong>：</em></p><ul><li>內容(Content)</li><li>伺服器(Server)</li><li>Cookie</li><li>CSS</li><li>JavaScript</li><li>圖片(Images)</li><li>行動裝置(Mobile)</li></ul><p>#盡量減少 HTTP 請求<br>tag:content<br>80%的終端使用者(end-user)回應時間都花在前端上。大部分時間都被綁在下載頁面上的所有組件像是：images, stylesheet, script, Flash…等。減少呈現頁面所需要的組件和 HTTP 請求的數量是加快頁面的關鍵所在。</p><p>簡化頁面設計來減少頁面中的組件數量是一個方法，但有沒有方法是可以使網站內容變得更豐富，同時也能加快回應的時間呢?<br>這裡有一些技巧來減少 HTTP 請求的數量，在需要豐富的頁面設計時仍然可支援。</p>]]></content>
      
      
      <categories>
          
          <category> Optimization </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>介紹 Semantic HTML</title>
      <link href="/2014/06/19/about-semantic-html/"/>
      <url>/2014/06/19/about-semantic-html/</url>
      
        <content type="html"><![CDATA[<p>在網路上看到一篇 <a href="http://webdesignfromscratch.com/html-css/semantic-html/">Semantic HTML</a> 的介紹，嘗試翻譯了一下，有任何錯誤或需要修改的地方請多多指教，謝謝。<br>#Semantic：語意<br>現在任何人想建立他們自己的 HTML 頁面應該要以**”使自己的標記語義是正確”**為目標。<br>這篇文章將會解釋什麼是 Semantic HTML 與 semantically-correct HTML，以及它是如何有利於 Web 的發展。</p><span id="more"></span><p>Semantic 一詞在中文直譯為「語意」，不過這裡的「語意」非語言中的「語意」，而是讓你所撰寫的電子資訊，可以讓人類能夠清楚理解，同時也適合被機器或程式處理之。其實這一點就跟網站優化的目的相同：</p><ul><li>可以讓人類能夠清楚理解 - SMO</li><li>適合被機器或程式處理 - SEO</li></ul><p>#什麼是 Semantic HTML?<br>Semantic 的主要研究意義在於：如何有意義的去建立並應用這些標記。<br>“為什麼 X 要叫做 X?” 這就是 semantics 的問題。<br>HTML 是我們用來撰寫網頁的標記語言，它是能夠被標準的網頁瀏覽器所了解，以及多項其他類型的”使用者代理”，包含了行動裝置、搜尋引擎蜘蛛及聽覺瀏覽器等。</p><p>HTML 包含了兩種類型的東西：</p><ul><li>標記(Tags)</li><li>文字內容(Text content)</li></ul><p>有一些標記可以擁有他們自己的內容（像是圖片、Flash 動畫或是 metadata），但大部分的 HTML 標記都是應用在內容架構上。<br>語意化 HTML(Semantic HTML) 或 語意正確的 HTML(semantically-correct HTML)<br>指的是我們選用建立架構的標記是要有意義的，並適當的應用在其中。</p><p>因為搜索引擎不是人，她並不懂你網站中文字的意思是什麼，她會的只是整理跟歸納而已。所以你的 HTML 結構中，就必須先幫搜索引擎劃重點。<br>所以，舉個例子好了，如果你想要你的 HTML 是語意正確(semantically-correct)的話…</p><ul><li>Headings：也就是 h1 ~ h6，標籤數字越小層級越高，這就有如書本中或是報紙的大中小標題一般。被標示為 h1（大標題）通常是很醒目的目標，一定是具代表性的意義的文字，於是搜索引擎就會特別注意 h1 標籤內的字。</li><li>一個段落標記<code>&lt;p&gt;&lt;/p&gt;</code>的使用應該要用於標示一個段落(這是一個架構的概念)，而不能用在建立一個在網頁上的空間。<br> <strong>絕對不要用一堆<code>&lt;p&gt;</code>來建立網頁上的空白位置</strong></li><li>標記<code>&lt;b&gt;&lt;/b&gt;</code>(粗體)與<code>&lt;i&gt;&lt;/i&gt;</code>(斜體)永遠不要用它，因為這些標記是用在格式上的應用，在內容的架構上是沒有意義的。取而代之，使用<code>&lt;strong&gt;&lt;/strong&gt;</code>與<code>&lt;em&gt;&lt;/em&gt;</code>(強調意味)，兩者在瀏覽器預設的情況下，文字格式會變成粗體與斜體，但使用<code>&lt;strong&gt;&lt;/strong&gt;</code>和<code>&lt;em&gt;&lt;/em&gt;</code>同時也增加有意義的架構內容。</li><li>Alt：這是附屬在 img 標籤裡面的屬性，因為搜索引擎看到的都是程式碼，alt 的功用就是幫圖附上註解，讓搜索引擎知道，這張圖是在說什麼。</li></ul><p>就 W3C 的準則而言：</p><ul><li>I: Renders as italic text style.</li><li>B: Renders as bold text style. [<a href="http://www.w3.org/TR/html4/present/graphics.html#h-15.2.1">w3c.org</a>]</li><li>EM:Indicates emphasis.</li><li>STRONG:Indicates stronger emphasis. [<a href="http://www.w3.org/TR/html4/struct/text.html#h-9.2.1">w3c.org</a>]</li></ul><p><strong>所以在操作 SEO 的時候，網站或是每篇文章的重要關鍵字，一定是要被包在 h1 標籤中的。</strong></p><p>#總是將樣式表從內容獨立出來<br>HTML 標記不應該被套上圖樣 - 這是 CSS 的工作(層疊樣式表 Cascading Style Sheet)<br>請參考 [<a href="http://webdesignfromscratch.com/web-design-tutorials/]">http://webdesignfromscratch.com/web-design-tutorials/]</a>(Free Web Design Tutorials)來了解更多關於 HTML、CSS 及 JavaScript 如何結合在一個網頁上。<br>(實際演練的時候也會將所有的 JavaScript 功能(Functions)及事件處理(Event Handlers)從 HTML 標記中移除)</p><p>以上是基礎中的基礎，要做好 SEO 事實上並沒那麼困難，出發點就是讓人及搜尋引擎能夠輕鬆的看懂你的網站，就是好的網站優化。</p><p>#為什麼有正確語意的 HTML 會比較好?<br>撰寫語意化 HTML 帶來的相當大的好處：</p><ul><li>易於使用 (Ease of use)</li><li>易接近、無障礙 (Accessibility)</li><li>搜尋引擎優化 (Search Engine Optimisation)</li><li>可再利用 (Repurposing)</li></ul><p>#易於使用<br>首先，語意化 HTML 是乾淨的 HTML。它更容易閱讀和編輯標記，而且沒有額外的標記和內嵌樣式。<br>當要和其他人協力進行的時候，乾淨的標記也節省了時間和金錢。<br>例如：開發人員要在一個內容管理系統或任何其他 web 應用來實現你的頁面樣板，乾淨的 HTML 就可以很快的完成樣式的套用。<br>而且還有一個好處就是你的 HTML 檔案會比較小，可以加速讀取的速度。</p><p>#易接近、無障礙<br>搜尋引擎蜘蛛與爬蟲，像是 Google 機器人，代表著另一種使用者代理，他們也會讀取網頁內容，嘗試去辨別其中的涵義。<br>當爬蟲發現一個網頁，它會在索引資料庫存取對於這個網頁是關於什麼的評估，以提供與使用者相匹配的搜尋查詢時使用。</p><p><strong>最大的問題是：搜尋引擎要如何匹配搜尋的條件，對已知頁面來建立一個優先級列表?</strong><br>當然，每家的作法都不太一樣，不過對於搜尋引擎優化其中一個關鍵點，就是使用普通的方式。如果你是一個搜尋引擎，你會怎麼做呢?如果你透過搜尋引擎的工作遇到一些問題，那麼有幾項很快就會明白，往往容易表達的前綴就是”所有的事物都是平等的”。</p><p>比方說，你有兩個網頁，這兩個網頁都是完全相同的文字內容(10KB)，其中一頁有多餘 5KB 的 HTML 標記，整齊地註釋在內容的語意意涵。第二頁有多餘 30KB 的標記，包含了行內樣式、大量的巢狀<code>&lt;div&gt;</code>標記及裝飾圖像。<br>現在，更多的圖樣密集的頁面或許對人類訪客來說看起來比較好，但如果每頁都包含了搜尋條件 “bluebottle” 五次，你會(把自己當成是搜尋引擎)如何判別哪一個才是最接近某人要的”bluebottle”搜尋條件呢?</p><p>顯然的，是第一個，除了頁面比較輕巧，還有以下幾點可能的原因：</p><ul><li><p>1.輕盈頁面的關鍵字密度是最好的。它在 15KB 的標記中帶有搜尋條件 5 次，而第二個頁面 40KB 的標記中也帶有 5 次條件。無論加入的標記是要給搜尋引擎看的(搜尋引擎也許無法告知)，它看起來似乎沒有關於”bluebottle”的條件。</p></li><li><p>2.每個出現的搜尋條件很可能在文件的一開始中，輕量化的頁面比 40KB 大的頁面提升更多。所有的事物都是平等的，越早發現文件的搜尋條件，越有可能是關於這個搜尋條件的文件，或這個條件是在這個文件內容中最突出的。</p></li><li><p>3.假設第一個文件是明確的含有語意化的標記，比起在一個更多圖樣的頁面(這頁面可能使用圖片當連結，或許也沒有適當的加入<code>alt</code>屬性)，那麼第一個頁面很可能會是搜尋條件中被放在更高價值的標記(例如標頭(heading)或連結(link))。</p></li></ul><p>#再利用<br>當你的標記(有意義的內容)從你的樣式(為不同的媒體提供的樣式表)中分離，明顯地內容可以更容易被使用者代理了解。這意味著不只是使用者代理已經知道你，但是有些你不完全知道(像是自動抓取建立自定義的 RSS 新聞 feeds 在某個主題上、或圖片或具體的影片搜尋引擎)以及其他尚未被發明的！</p><p>最近幾年我們可以看到很多混和內容為主要特點的網站與應用。這會在網站原創者沒有知識(knowledge)下發生，但大多數的情況下，這樣的自由內容在網站間移動，適應各種媒體，這對原創者來說是有益的。</p><p>通常在這樣的情況下，在新的混合頁面上被不同格式的方式獲取網頁的內容，更重要的是它從標記本身移除所有的任何樣式內容。<br>(注意 行內樣式、直接套用在 HTML 標記上、透過分離出來的樣式表來覆蓋任何其他樣式，如此一來他們就可以把程式碼剝離)</p><p>顯然地，這使內容從任何來源更容易獲取與再使用，而且能容易套用到任何介質(medium)，當它不包含任何寫死的(hard-coded)樣式，而且當它包含語意標記可幫助電腦程序了解其內容的架構和意涵。</p><p>來源：<br>[<a href="http://webdesignfromscratch.com/html-css/semantic-html/]">http://webdesignfromscratch.com/html-css/semantic-html/]</a>(Introduction to Semantic HTML)<br><a href="%E5%8F%B0%E7%81%A3SEO%E5%84%AA%E5%8C%96%E5%AD%B8%E9%99%A2">http://blog.seo-tw.org/2010/04/seo-semantic-html.html</a><br>[<a href="http://www.slideshare.net/josephj/semantic-html-basic-presentation]">http://www.slideshare.net/josephj/semantic-html-basic-presentation]</a>(Semantic HTML Basic)</p>]]></content>
      
      
      <categories>
          
          <category> HTML </category>
          
      </categories>
      
      
    </entry>
    
    
    
    <entry>
      <title>漸進增強 (progressive enhancement)與優美退化 (graceful degradation) </title>
      <link href="/2014/06/18/progressive-enhancement-progressive-enhancement-with-graceful-degradation-graceful-degradation/"/>
      <url>/2014/06/18/progressive-enhancement-progressive-enhancement-with-graceful-degradation-graceful-degradation/</url>
      
        <content type="html"><![CDATA[<p>#1.觀念部分<br>在動手開發軟體時，通常我們會先考慮的問題就是使用者將在何種設備、系統、平台以及這些係同平台的版本使用它，最後決定一個方向，開始開發。<br>以開發網站為例，目標使用者可能會使用IE, Chrome, Firefox 甚至是行動裝置上瀏覽器來使用這個網站<br>可能問題如下：</p><ul><li>是否支援所有瀏覽器？</li><li>是否針對先進瀏覽器增強使用經驗？</li><li>主要功能支援就好？</li><li>完全支援開發成本比較高？</li><li>需要顧慮到這麼多瀏覽器好麻煩？</li></ul><p>這些問題通常有兩種作法，分別為「優雅降級」、「漸進增強」。<br>以下分別會介紹兩者的概念，以及它們之間的不同到最後實際應用時我們該如何決策。</p><span id="more"></span><p>#何謂優雅降級 (Graceful Degradation)</p><blockquote><p><em>Progressive enhancement is a strategy for web design that emphasizes accessibility, semantic HTML markup, and external stylesheet and scripting technologies. - wiki</em></p></blockquote><p><strong>優雅降級（Graceful Degradation）</strong>就是在一開始建構一個系統或網站時，就針對最新、最完善的環境來設計，然後針對其它環境進行測時與修復。使用這個方案時，我們首先會挑選一個較完善的平台完成所有的功能和經驗，然後再針對無法支援所有功能的平台或環境撰寫候選方案，讓那些較舊的平台不致於無法使用主要的功能。</p><p>這種作法是在主要的環境上<br><strong>提供「最好的使用者經驗」，「簡陋卻無妨 (poor, but passable)」</strong><br>是看待那些<strong>被認為過時或功能有缺失的平台</strong> 的方式。</p><p>Craig Buckler在Sitepoint上也提出類似的看法</p><blockquote><p><em>Graceful degradation is one solution. It is the practice of building a web site or application so it provides a good level of user experience in modern browsers. However, it will degrade gracefully for those using older browsers. The system may not be as pleasant or as pretty, but the basic functionality will work on older systems. - Craig Buckler</em></p></blockquote><p>#何謂漸進增強 (Progressive Enhancement)</p><blockquote><p><em>Progressive enhancement is similar concept to graceful degradation but in reverse. The web site or application would establish a base-level of user experience for most browsers. More advanced functionality would then be added when a browser supports it. - Craig Buckler</em></p></blockquote><p><strong>漸進增強(Progressive Enhancement)</strong><br>就是從最基本的功能出發，在保證系統在任何環境中的可用性的基礎上，逐步增加功能及提高使用者經驗。<br><strong>漸進增強</strong>首先考慮到的是一般性，必須提供所有的平台完整的功能，然後再去針對較新的平台進行改良與優化。<br>簡單來說，<strong>先求有、再求好</strong></p><p>上述兩種做法的選擇，主要在於視當時的需求情況來進行選擇，有好有壞。</p><p>例如建立一個完美支援所有平台的應用程式是一個理想的情況，然而那是不太可能的。<br>開發過程中有技術、預算、工作時程等問題，那麼要做的就是去「需求評估」，從需求開始。<br>如果要開發一個電子商務平台，使用「漸進增強」可能會是個好的方法；<br>如果要開發線上互動會議系統，完美的平台支援相對就沒那麼重要了。</p><p>#成本的花費<br>使用<strong>漸進增強</strong>的方法需要更多的時間、人力、資源開發，初期開發成本較高，但是能提供更好的穩定性以及平台支援，以長期來說反而減少維護、開發成本。</p><p>使用<strong>優雅降級</strong>的方法，開發初期僅需要把所有火力集中在一個平台上，迅速的開發出產品的雛形，進行市場試水溫的測試，對於功能尚未確定的產品來說，使用優雅降級的方式也許能夠節省資源不必要的浪費。</p><p>#參考資料</p><ul><li><a href="http://en.wikipedia.org/wiki/Progressive_enhancement">Progressive_enhancement Wiki</a></li><li><a href="http://www.sitepoint.com/progressive-enhancement-graceful-degradation-basics/">Progressive Enhancement and Graceful Degradation: an Overview</a></li><li><a href="http://www.sitepoint.com/progressive-enhancement-graceful-degradation-choice/">Progressive Enhancement and Graceful Degradation: Making a Choice</a></li><li><a href="http://fatesinger.com/archives/764.html">fatesinger</a></li><li><a href="http://www.candoudou.com/archives/481">web前端開發</a></li><li><a href="http://yrzhll.com/blog/2013/01/06/web/">yrzhll.com</a></li><li><a href="http://hanazawakana.iteye.com/blog/1711556">優雅降級和漸進增強 - 血鐵藍獅</a></li><li><a href="http://augus-blog.logdown.com/posts/143403-graceful_degradation_and_progressive_enhancement">Augus’s Blog</a></li></ul>]]></content>
      
      
      
    </entry>
    
    
    
    <entry>
      <title>Sublime Text 2 常用插件</title>
      <link href="/2014/06/17/sublime-text-2-plugins/"/>
      <url>/2014/06/17/sublime-text-2-plugins/</url>
      
        <content type="html"><![CDATA[<p>在使用SublimeText2之後，覺得真的很棒，尤其是插件的部分更是可以提升撰寫的效率！<br>以下則是插件安裝方式以及我常用的插件整理。</p><h1 id="SublimeText2-插件安裝方式："><a href="#SublimeText2-插件安裝方式：" class="headerlink" title="SublimeText2 插件安裝方式："></a>SublimeText2 插件安裝方式：</h1><span id="more"></span><p>第一次使用必須裝 <a href="https://sublime.wbond.net/installation">Package Contorl</a>，安裝方式：<br><code>ctrl</code>+<code>、</code> 開啟 Python 控制台<br>將這段碼貼上，<code>Enter</code></p><pre><code>import urllib2,os,hashlib; h = &#39;7183a2d3e96f11eeadd761d777e62404&#39; + &#39;e330c659d4bb41d3bdf022e94cab3cd0&#39;; pf = &#39;Package Control.sublime-package&#39;; ipp = sublime.installed_packages_path(); os.makedirs( ipp ) if not os.path.exists(ipp) else None; urllib2.install_opener( urllib2.build_opener( urllib2.ProxyHandler()) ); by = urllib2.urlopen( &#39;http://sublime.wbond.net/&#39; + pf.replace(&#39; &#39;, &#39;%20&#39;)).read(); dh = hashlib.sha256(by).hexdigest(); open( os.path.join( ipp, pf), &#39;wb&#39; ).write(by) if dh == h else None; print(&#39;Error validating download (got %s instead of %s), please try manual install&#39; % (dh, h) if dh != h else &#39;Please restart Sublime Text to finish installation&#39;)</code></pre><p><img src="/images/sublime-text-2-plugins/open-package-control.jpg" alt="可以看到Package Control就是成功囉!!"><br>完成之後重開SublimeText，在 Preferences 有看到 Package Control 即安裝成功。</p><p><code>Ctrl</code> + <code>shift</code> + <code>p</code><br>輸入 <code>package install</code><br>接著輸入要安裝的插件名稱即可。</p><p>#1.Emmet<br>即 Zen coding 的改名，可以快速的進行code的撰寫，加快開發速度。<br>文件的頁面內容的<a href="http://docs.emmet.io/cheat-sheet/">Cheat Sheet</a>連結有使用方式可參考。<br>參考文件<a href="http://docs.emmet.io/">Emmet docs</a><br>#2.SublimeTmpl<br><img src="/images/sublime-text-2-plugins/add-new-html.jpg" alt="這樣可以少打很多基本的Code~"><br>可以快速產生新的檔案樣板<br>#3.ConvertToUTF8<br>SublimeText並非完美，它在開啟 ansi 的檔案時，因為中文的編碼為 big 5，會有亂碼的問題，因此只要安裝這個插件，就可以讓它支援繁體中文與簡體中文啦！<br>#4.HTML Beautify<br>在進行公司的網站維護工作時，可能會遇到一些檔案的排版非常獵奇，難以閱讀，安裝之後可在Edit &gt; HTML Beautify 執行。<br>#5.Color Highlighter<br><img src="/images/sublime-text-2-plugins/styles.jpg" alt="CSS的色碼直接顯示在選擇的色碼底下很方便查看!"><br>對於 CSS 的顏色設定，Color Highlighter 直接顯示目前選擇的色碼底色。<br>#6.Snippets系列<br>顧名思義就是有 Snippets 功能，提升速度用。</p>]]></content>
      
      
      
    </entry>
    
    
  
  
</search>