本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# CloudWatch 自訂小工具的詳細資訊
<a name="add_custom_widget_dashboard_about"></a>

自訂小工運作方式如下：

1. CloudWatch 儀表板會呼叫包含小工具程式碼的 Lambda 函數。它會傳遞在小工具中定義的任何自訂參數。

1. Lambda 函數會傳回 HTML、JSON 或 Markdown 的字串。Markdown 會以下列各式傳回為 JSON：

   ```
   {"markdown":"{{markdown content}}"}
   ```

1. 儀表板會顯示傳回的 HTML 或 JSON。

如果函數傳回 HTML，則會支援大多數 HTML 標籤。您可以使用 Cascading 樣式表 (CSS) 樣式和可擴展向量圖形 (SVG) 來建置複雜的檢視。

HTML 元素 (例如連結和表格) 的預設樣式會遵循 CloudWatch 儀表板的樣式。您可以透過使用內嵌樣式和 `<style>` 標籤來自訂此樣式。您也可以透過包括具有 `cwdb-no-default-styles` 類別的單一 HTML 元素來停用預設樣式。下列範例會停用預設樣式：`<div class="cwdb-no-default-styles"></div>`。

每次透過自訂小工具對 Lambda 的呼叫都包含 `widgetContext` 元素，可提供 Lambda 函數開發人員有用的內容資訊。

```
{
  "widgetContext": {
    "dashboardName": "Name-of-current-dashboard",
    "widgetId": "widget-16",
    "accountId": "012345678901",
    "locale": "en",
    "timezone": {
      "label": "UTC",
      "offsetISO": "+00:00",
      "offsetInMinutes": 0
    },
    "period": 300,
    "isAutoPeriod": true,
    "timeRange": {
      "mode": "relative",
      "start": 1627236199729,
      "end": 1627322599729,
      "relativeStart": 86400012,
      "zoom": {
        "start": 1627276030434,
        "end": 1627282956521
      }
    },
    "theme": "light",
    "linkCharts": true,
    "title": "Tweets for Amazon website problem",
    "forms": {
      "all": {}
    },
    "params": {
      "original": "param-to-widget"
    },
    "width": 588,
    "height": 369
  }
}
```

## 預設 CSS 樣式
<a name="add_custom_widget_styling"></a>

自訂小工具提供以下預設 CSS 樣式元素：
+ 您可以使用 CSS 類別 **btn** 以新增按鈕。它將錨點 (`<a>`) 轉變為按鈕，如下列範例所示：

  ```
  <a class="btn" href=https://amazon.com”>Open Amazon</a>
  ```
+ 您可以使用 CSS 類別 **btn btn-primary** 以新增主要按鈕。
+ 依預設，下列為樣式元素：**table**、**select**、**headers (h1, h2, and h3)**、**preformatted text (pre)**、**input** 和 **text area**。

## 使用描述參數
<a name="add_custom_widget_describe"></a>

強烈建議您支援 **describe** (描述) 參數，即使它只會傳回一個空字串。如果您不支援它，並且它在自訂小工具中被呼叫，它會像顯示文件那樣顯示小工具內容。

如果您包含 **describe** (描述) 參數時，Lambda 函數會傳回 Markdown 格式的文件，而且不會執行任何其他動作。

當您在主控台中建立自訂小工具時，在您選取 Lambda 函數之後，隨即便會出現 **Get documentation** (取得文件) 按鈕。如果您選擇此按鈕，則會使用 **describe** (描述) 參數，並傳回函數的文件。如果文件在 Markdown 中格式良好，CloudWatch 會剖析 YAML 中由三個反引號字符 (```) 包圍的文件中的第一個條目。然後，它會自動填充參數中的文件。以下是格式良好的文件的範例。

```
``` yaml
echo: <h1>Hello world</h1>
```
```