> For the complete documentation index, see [llms.txt](https://primer2.dynamobim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://primer2.dynamobim.org/zh-tw/8_coding_in_dynamo/8-1_code-blocks-and-design-script/2-design-script-syntax.md).

# DesignScript 語法

您可能發現 Dynamo 中節點名稱有一個常見現象：每個節點都使用 *.* 語法而不含空格。這是因為每個節點頂部的文字都表示指令碼撰寫的實際語法，而 *.* (或 *點標記法* ) 將元素與我們可能呼叫的方法分開。這樣可以從視覺指令碼輕鬆轉換為文字型指令碼。

![NodeNames](/files/Wr8u36E28NgG6YWo2xg6)

如果將點標記法做一般的類比，在 Dynamo 中如何處理一個參數式蘋果呢？以下是我們在決定吃蘋果之前先對蘋果執行的一些方法。(注意：這些方法不是實際的 Dynamo 方法)。

| 人類用語         | 點標記法                      | 輸出     |
| ------------ | ------------------------- | ------ |
| 蘋果的顏色是什麼？    | Apple.color               | 紅色     |
| 蘋果成熟了嗎？      | Apple.isRipe              | true   |
| 蘋果有多重？       | Apple.weight              | 6 盎司。  |
| 蘋果來自何處？      | Apple.parent              | 樹      |
| 蘋果建立哪些項目？    | Apple.children            | 種子     |
| 這個蘋果是本地生長的嗎？ | Apple.distanceFromOrchard | 60 英里。 |

我不知道您覺得如何，但根據以上表格的輸出來判斷，這似乎是一個美味的蘋果。我認為我會執行 *Apple.eat()*。

### 程式碼區塊中的點標記法

記住蘋果的類比，我們來看看 *Point.ByCoordinates*，並示範如何使用程式碼區塊建立一個點。

在 Dynamo 中，*程式碼區塊* 語法 `Point.ByCoordinates(0,10);` 產生的結果與 *Point.ByCoordinates* 節點相同，只是我們可以使用一個節點來建立點。比起將不同節點連接至 *X* 與 *Y*，此方法更有效率。

> 1. 在 Code Block 中使用 *Point.ByCoordinates*，我們就是以內建節點 *(X,Y)* 的順序指定輸入。

### 呼叫節點 - 建立、動作、查詢

您可以透過 Code Block 呼叫資源庫中的任何一般節點，只要該節點不是特殊的 *「使用者介面」節點* (具有特殊的使用者介面功能) 即可。例如，您可以呼叫 *Circle.ByCenterPointRadius*，但是呼叫 *Watch 3D* 節點意義不大。

一般節點 (資源庫中的大多數節點) 通常分為三種類型。您會發現資源庫在組織時也考慮到了這些品類。在 Code Block 中呼叫時，對這三種類型方法 (或節點) 的處理方式不同。

> 1. **建立** - 建立 (或建構) 項目
> 2. **動作** - 對某項目執行動作
> 3. **查詢** - 取得既有項目的性質

#### 建立

「建立」品類將從零開始建構幾何圖形。我們在程式碼區塊中以從左至右的順序輸入值。這些輸入的順序與節點中從上到下的輸入順序相同。

將 *Line.ByStartPointEndPoint* 節點與程式碼區塊中對應的語法做比較，可以獲得相同結果。

![](/files/ouZAjKXIIGAullbLVl4s)

#### 動作

動作是您對該類型的物件執行的行為。Dynamo 使用許多程式語言中通用的 *點標記法* 對物件套用動作。確定物件後，輸入點，後接動作名稱。動作類型方法的輸入將放置在括號中，類似於建立類型的方法，只是您不必指定對應節點上看到的第一個輸入。我們改為指定執行動作時所依據的元素：

> 1. **Point.Add** 節點是動作類型節點，因此語法稍有不同。
> 2. 輸入是 (1) *point* 以及要加上去的 (2) *vector*。在 **Code Block** 中，我們已將點 (物件) 命名為 *pt*。為了將命名為 *vec* 的向量加入 *pt*，我們會編寫 *pt.Add(vec)* 或採用「物件, 點, 動作」的格式。加入動作僅有一個輸入，也就是 **Point.Add** 節點的所有輸入減去第一個輸入。**Point.Add** 節點的第一個輸入是點本身。

#### 查詢

查詢類型的方法會取得物件的性質。由於物件本身就是輸入，因此您不必指定任何輸入。不需要使用括號。

![](/files/ucMQ5KDkfKTO5bBjT7Ku)

### 交織的狀況如何？

節點的交織與程式碼區塊的交織稍有不同。如果是節點，使用者會在節點上按一下右鍵，然後選取要執行的交織選項。如果是程式碼區塊，使用者對於資料的建構方式會有更多的控制。程式碼區塊速寫方法使用 *複製指南* 設定幾個一維清單應採用的配對方式。角括號 <> 中的數字定義所產生巢狀清單的階層：<1>、<2>、<3> 等。

> 1. 在此範例中，我們使用速寫來定義兩個範圍 (本章的下一節將講述速寫的更多內容)。簡單來說，`0..1;` 相當於 `{0,1}`，`-3..-7` 相當於 `{-3,-4,-5,-6,-7}`。結果將產生包含 2 個 x 值與 5 個 y 值的清單。如果我們不對這些不相符的清單使用複製指南，則會得到包含兩個點的清單，這是長度最短的清單。使用複製指南，我們可以找出 2 個座標與 5 個座標所有可能的組合 (即笛卡兒積)。
> 2. 使用語法 **Point.ByCoordinates**`(x_vals<1>,y_vals<2>);`，可以得到 *兩個* 清單，每個清單有 *五個* 項目。
> 3. 使用語法 **Point.ByCoordinates**`(x_vals<2>,y_vals<1>);`，可以得到 *五個* 清單，每個清單有 *兩個* 項目。

使用此標記法，我們也可以指定哪個清單佔優勢：2 個清單 (各包含 5 個項目) 還是 5 個清單 (各包含 2 個項目)。在此範例中，若變更複製指南的順序，結果將在格線中產生一列點清單或一欄點清單。

### 要編碼的節點

以上程式碼區塊方法可能花一點時間才能習慣，而 Dynamo 中提供稱為「要編碼的節點」功能，可以讓程序更輕鬆。若要使用此功能，請在 Dynamo 圖表中選取一系列節點，在圖元區上按一下右鍵，然後選取「要編碼的節點」。Dynamo 會將這些節點及所有輸入與輸出濃縮到一個程式碼區塊中！這不僅是一個強大的工具可學習程式碼區塊，也能讓您處理更高效的參數式 Dynamo 圖表。我們將使用「要編碼的節點」結束以下練習，因此請勿錯過。

## 練習：曲面牽引

> 按一下下方的連結下載範例檔案。
>
> 附錄中提供完整的範例檔案清單。

為了展示 Code Block 的強大功能，我們要將既有的牽引欄位定義轉換為 Code Block 形式。使用既有定義可示範程式碼區塊與視覺指令碼如何具有相關性，有助於學習 DesignScript 語法。

先重新建立以上影像中的定義 (或開啟範例檔案)。

> 1. 請注意，**Point.ByCoordinates** 的交織已設定為 *「笛卡兒積」*。
> 2. 格線中的每個點都會根據其與參考點的距離而沿著 Z 方向上移。
> 3. 重新建立並增厚曲面，同時在幾何圖形上建立相對於距參考點距離的凸度。

> 1. 從頭開始，我們先定義參考點：**Point.ByCoordinates**`(x,y,0);` 我們使用的 **Point.ByCoordinates** 語法與參考點節點上方指定的語法相同。
> 2. 將變數 *x* 與 *y* 插入 **Code Block**，以便我們可以使用滑棒動態更新這些內容。
> 3. 在 **Code Block** 的輸入加入一些 *滑棒*，範圍從 -50 到 50。這樣我們可以跨越整個預設 Dynamo 格線。

> 1. 在 **Code Block** 的第二行，我們定義速寫以取代數字序列節點：`coordsXY = (-50..50..#11);`我們將在下一節詳細討論此內容。現在，請注意此速寫相當於視覺指令碼中的 **Number Sequence** 節點。

> 1. 現在，我們將從 *coordsXY* 序列建立點的格線。為了執行此作業，我們要使用 **Point.ByCoordinates** 語法，但還需要使用我們在視覺指令碼中採用的方式，創造一個清單的 *笛卡兒積*。為了執行此作業，我們鍵入行：`gridPts = Point.ByCoordinates(coordsXY<1>,coordsXY<2>,0);` 角括號表示笛卡兒積參考。
> 2. 請注意，在 **Watch3D** 節點中，我們有一個橫越 Dynamo 格線的點格線。

> 1. 現在講解困難的部分：我們希望根據點距參考點的距離，將這些點的格線上移。首先，我們呼叫這一組新點 *transPts*。由於平移是針對既有元素的動作，因此我們不用 `Geometry.Translate...`，而是使用 `gridPts.Translate`
> 2. 從圖元區上的實際節點，我們可以看到有三個輸入。要平移的 geometry 已經宣告，因為我們正對該元素執行動作 (使用 *gridPts.Translate*)。其餘兩個輸入將插入函數 direction 與 *distance* 的括號內。
> 3. direction 很簡單，我們使用 `Vector.ZAxis()` 垂直移動。
> 4. 參考點與每個格線點之間的距離仍需要計算，因此我們使用相同方式對參考點執行此動作：`refPt.DistanceTo(gridPts)`
> 5. 程式碼的最後一行得出平移後的點：`transPts=gridPts.Translate(Vector.ZAxis(),refPt.DistanceTo(gridPts));`

> 1. 我們現在已經有資料結構適當的點格線，可以建立 Nurbs 曲面。我們使用 `srf = NurbsSurface.ByControlPoints(transPts);` 建構曲面

> 1. 最後，為了對取面增加一些深度，我們使用 `solid = srf.Thicken(5);` 建構實體。在此案例中，我們在程式碼中將曲面變厚了 5 個單位，不過也可以將其宣告為變數 (例如將其稱為 thickness)，然後使用滑棒控制該值。

#### 使用「要編碼的節點」簡化圖表

只需按一下按鈕，「要編碼的節點」功能即可自動執行我們剛剛完成的整個練習。這不僅在建立自訂定義及可重複使用的 Code Block 時很有威力，也是瞭解如何在 Dynamo 中撰寫指令碼非常有用的工具。

> 1. 先使用練習的步驟 1 中使用的既有視覺指令碼。選取所有節點，在圖元區上按一下右鍵，然後選取 *「要編碼的節點」*。非常簡單。

Dynamo 已自動建立文字版本的視覺圖表、交織與全部項目。在您的視覺指令碼上試試看，體驗 Code Block 的強大功能！