AndroidForgeHQ/sketchware-layout-designer

Sketchware 佈局設計師技能

概述

此技能專門用於建立和管理 Sketchware Pro 專案的 UI 層。它能產出 .swb 備份套件中 data/view 所需的精確 JSON 規格，並完整支援小部件階層、樣式設定、響應式佈局和浮動動作按鈕 (FAB)。

---

1. 備份存檔中的檔案結構

在 Sketchware 專案或 .swb 存檔中，所有螢幕佈局會合併成一個 單一 AES 加密檔案：data/view。

多螢幕與區段標頭

佈局透過區段標記進行劃分：

• @<activity_xml_name>.xml（例如 @main.xml、@home.xml）
• @<activity_xml_name>.xml_fab（用於包含浮動動作按鈕的 Activity）
• @<custom_view_name>.xml（用於 ListView/Spinner 中使用的自訂視圖）

@main.xml
<ViewBean JSON for view 1>
<ViewBean JSON for view 2>
<ViewBean JSON for view 3>

@main.xml_fab
<ViewBean JSON for FAB>

@item_row.xml
<ViewBean JSON for custom view items>

---

2. ViewBean JSON 結構與必要欄位

每個 UI 元素都是一個表示 ViewBean 的單行 JSON 字串：

{
  "id": "button_submit",
  "type": 3,
  "parent": "root",
  "parentType": 0,
  "index": 0,
  "convert": "Button",
  "customView": "",
  "enabled": 1,
  "clickable": 1,
  "alpha": 1.0,
  "translationX": 0.0,
  "translationY": 0.0,
  "scaleX": 1.0,
  "scaleY": 1.0,
  "firstDayOfWeek": 1,
  "dividerHeight": 1,
  "choiceMode": 0,
  "checked": 0,
  "indeterminate": "false",
  "progress": 0,
  "max": 100,
  "progressStyle": "?android:progressBarStyle",
  "spinnerMode": 1,
  "inject": "",
  "adSize": "",
  "adUnitId": "",
  "preIndex": 0,
  "preParentType": -1,
  "parentAttributes": {},
  "layout": {
    "width": -1,
    "height": -2,
    "orientation": -1,
    "gravity": 0,
    "layoutGravity": 0,
    "weight": 0,
    "weightSum": 0,
    "marginLeft": 16,
    "marginTop": 16,
    "marginRight": 16,
    "marginBottom": 16,
    "paddingLeft": 12,
    "paddingTop": 12,
    "paddingRight": 12,
    "paddingBottom": 12,
    "backgroundColor": 16777215,
    "borderColor": -16740915
  },
  "text": {
    "text": "Submit",
    "textSize": 16,
    "textColor": -16777216,
    "hint": "",
    "hintColor": 16777215,
    "singleLine": 0,
    "line": 0,
    "inputType": 1,
    "imeOption": 0,
    "textFont": "default_font",
    "textType": 1
  },
  "image": {
    "rotate": 0,
    "scaleType": "CENTER"
  }
}

---

3. 小部件與佈局類型常數

類型整數	小部件 / 佈局類別	convert 字串	說明
0	LinearLayout	LinearLayout	線性容器（水平或垂直）
1	RelativeLayout	RelativeLayout	相對容器
2	HorizontalScrollView	HorizontalScrollView	水平滾動容器
3	Button	Button	互動式按鈕
4	TextView	TextView	文字顯示標籤
5	EditText	EditText	文字輸入欄位
6	ImageView	ImageView	圖片容器
7	WebView	WebView	應用程式內瀏覽器 / 網頁框架
8	ProgressBar	ProgressBar	圓形或水平載入指示器
9	ListView	ListView	可滾動的垂直項目列表
10	Spinner	Spinner	下拉式選項列表
11	CheckBox	CheckBox	雙狀態可勾選框
12	ScrollView	ScrollView	垂直滾動容器
13	Switch	Switch	雙狀態切換開關
14	SeekBar	SeekBar	可拖曳的值滑桿
15	CalendarView	CalendarView	互動式月份日曆
16	FloatingActionButton	FloatingActionButton	標準 Material FAB（位於 _fab 區段）
17	AdView	AdView	Google AdMob 橫幅廣告
18	MapView	MapView	Google 地圖容器

---

4. 階層與父層規則（重要）

1. 根層級視圖：
   • 對於直接附加到螢幕基礎的元素，設定 "parent": "root"。
   • 設定 "parentType": 0（FAB 則設為 -1）。
2. 容器中的子視圖：
   • 設定 "parent": "<container_view_id>"（例如 "parent": "linear_main"）。
   • 設定 "parentType": <container_type_int>（例如 LinearLayout 使用 0）。
3. 索引順序：
   • "index" 在具有相同 "parent" 的同級元素中必須從 0, 1, 2, 3... 依序排列。
4. 佈局尺寸：
   • MATCH_PARENT：-1
   • WRAP_CONTENT：-2
   • 精確 DP：正整數（例如 48 代表 48dp）。
5. 線性佈局方向：
   • 水平："orientation": 0
   • 垂直："orientation": 1
   • 非容器小部件："orientation": -1

---

5. 樣式、顏色與排版

• ARGB 十六進位轉 32 位元有號整數： Sketchware 將顏色儲存為 32 位元有號整數：
  • 透明 / 預設：16777215（0x00FFFFFF）
  • 黑色（#FF000000）：-16777216
  • 白色（#FFFFFFFF）：-1
  • Sketchware 主要藍色（#FF008DCD）：-16740915
  • Material 強調紅色（#FFFF4081）：-49023
  • Material 灰色（#FF9E9E9E）：-6381922
• 文字樣式 (textType)：
  • 0：正常
  • 1：粗體
  • 2：斜體
  • 3：粗體斜體
• 輸入類型 (inputType for EditText)：
  • 1：一般文字
  • 2：文字（無建議）
  • 33：電子郵件地址 (TYPE_TEXT_VARIATION_EMAIL_ADDRESS)
  • 129：密碼 (TYPE_TEXT_VARIATION_PASSWORD)
  • 2：數字 (TYPE_CLASS_NUMBER)
  • 3：電話 (TYPE_CLASS_PHONE)
• 縮放類型 (scaleType for ImageView)：
  • "CENTER"、"CENTER_CROP"、"CENTER_INSIDE"、"FIT_CENTER"、"FIT_START"、"FIT_END"、"FIT_XY"

---

6. 浮動動作按鈕 (FAB) 設定

如果 Activity 啟用 FAB：

1. 在 data/file（@activity）中，設定 "options": 1（或包含 FAB 的位元遮罩）。
2. 在 data/view 中，於 @<activity>.xml_fab 下新增一個條目：

@main.xml_fab
{"adSize":"","adUnitId":"","alpha":1.0,"checked":0,"choiceMode":0,"clickable":1,"convert":"","customView":"","dividerHeight":1,"enabled":1,"firstDayOfWeek":1,"id":"_fab","image":{"rotate":0,"scaleType":"CENTER"},"indeterminate":"false","index":0,"inject":"","layout":{"backgroundColor":16777215,"borderColor":-16740915,"gravity":0,"height":-2,"layoutGravity":85,"marginBottom":16,"marginLeft":16,"marginRight":16,"marginTop":16,"orientation":-1,"paddingBottom":0,"paddingLeft":0,"paddingRight":0,"paddingTop":0,"weight":0,"weightSum":0,"width":-2},"max":100,"parentAttributes":{},"parentType":-1,"preIndex":0,"preParentType":0,"progress":0,"progressStyle":"?android:progressBarStyle","scaleX":1.0,"scaleY":1.0,"spinnerMode":1,"text":{"hint":"","hintColor":16777215,"imeOption":0,"inputType":1,"line":0,"singleLine":0,"text":"","textColor":16777215,"textFont":"default_font","textSize":12,"textType":0},"translationX":0.0,"translationY":0.0,"type":16}

3. 在 data/logic 中，點擊事件繫結到目標 _fab：
   • 事件標頭：@MainActivity.java_events -> {"eventName":"onClick","eventType":1,"targetId":"_fab","targetType":16}
   • 邏輯區塊標頭：@MainActivity.java__fab_onClick

---

7. 技能間整合協定

• 與 sketchware-events-manager 搭配： 此處建立的每個互動式視圖（Button、EditText、ImageView、ListView、_fab）都會在 data/logic 中透過其 id 和 targetType 被參考，用於點擊、變更和項目監聽器。
• 與 sketchware-blocks-engine 搭配： 視圖 ID 會傳遞到 UI 區塊參數中（例如 setText、getText、setVisible、setImageUrl）。
• 與 sketchware-project-generator 搭配： 產生的視圖 JSON 字串會在其各自的 @<screen>.xml 標頭下合併，並加密至 data/view。