docs: MEOW_APP_SDK §5.8 控件层架构升级 — 统一控件+扩展接口+通用化(agent-137)
- §5.8.1 统一控件架构: meow_widget_custom_create(render/hit回调), 标准=内置实现/自定义=回调同构, App魔改三处 - §5.8.2 Modifier式Options: meow_widget_opts + set_opts (不改既有create签名, 向后兼容) - §5.8.3 统一状态机: enabled/selected/focused/pressed + 物理键整页焦点导航 - §5.8.4 MD3语义色板: meow_theme 尾部追加(旧字段映射兼容), 日/夜 - §5.8.5 可组合布局: Row/Column/Box+Spacer(算成绝对坐标, 与绝对定位兼容) - §5.8.6 Material子集15项(后续批次); §5.8.7 取舍(不照搬Compose); §5.8.8 分批(第一批通用基座→第二批Material) - 与 §6.1(owner命中)/§8(旧字段兼容)/§5现有控件(create零改动) 一致
This commit is contained in:
MeowOS committed
1 parent
a31a004afe
commit
a6877bbd75
1 file changed
+241
+241
@@ -466,6 +466,247 @@ void meow_ui_panel_set_collapsed(meow_panel *p, int collapsed);
|
||||
|
||||
---
|
||||
|
||||
### 5.8 控件层架构升级：统一控件 + 扩展接口 + 通用化 [源:2026-08-30]
|
||||
|
||||
> **性质**：控件层的**演进蓝图**（后续实现权威）。把现有最小控件集（§5）与设计模板（§5.2-§5.7）收敛到**统一控件架构**——一个 `meow_widget` 基座承载「标准控件（SDK 内置）」与「自定义画布（App 提供 render/hit 回调）」，二者**同构**；并给出**三大通用化设计**：① 可组合布局（Row/Column/Box + Spacer）；② Modifier 式通用 Options（`meow_widget_opts`，通吃所有控件）；③ 统一状态机（enabled/selected/focused/pressed，触摸 + 物理键焦点）+ MD3 完整语义色板（日/夜自动切换）。
|
||||
>
|
||||
> **本小节只定架构与 API 草案**，均为「草案/待定案」，不随 B1 落地；实现以 `meow_ui.h` 为准。**不破坏**既有 btn/slider/switch/list（§5）与设计模板（§5.2-§5.7）——既有 create 签名一字不改，Options/状态机走**新增挂载器**（§5.8.2/§5.8.3）。**移植 Compose/Flutter 的思想而非照搬**（见 §5.8.7 取舍）。
|
||||
|
||||
#### 5.8.0 一句话定位
|
||||
|
||||
- **标准控件** = SDK 内置实现（`meow_btn/slider/switch/list`，及后续 Material 子集 §5.8.6），一个 `meow_widget`。
|
||||
- **自定义画布** = App 提供 render/hit 回调（`meow_widget_custom_create`），**同一个 `meow_widget`**。
|
||||
- 两者**同构**：共用同一套生命周期 / 命中分流 / 局部刷新 / 主题 / 状态机 / Activity 归属（§6.1 ①）。差异只在「绘制内容从哪来」（内置 switch vs App 回调）与「命中怎么判」（矩形内含 vs App 回调）。
|
||||
|
||||
#### 5.8.1 统一控件架构（基座 + 扩展接口）
|
||||
|
||||
**现状**（§5 / `meow_ui_widget.c`）：`struct meow_widget` 用 `type` + `switch(type)` 分发绘制；命中统一矩形内含（`meow_widget_hit`）；控件状态由 SDK 维护；owner 绑定创建时 Activity（§6.1 ①）。
|
||||
|
||||
**演进**（同构、最小侵入）：
|
||||
- `meow_widget` 基座**保留**现有字段（type/x/y/w/h/owner/label/…），内部**追加**一块承载：统一 Options（§5.8.2）+ 状态机位（§5.8.3）+ 自定义回调。
|
||||
- **类型枚举扩展**：新增 `W_CUSTOM`。标准控件照旧走 `switch(type)` 内置绘制；`W_CUSTOM` 走 App 回调。**其余类型（btn/slider/switch/list）行为不变**（向后兼容）。
|
||||
- **扩展点（App 魔改三处）**：① **自绘内容**（`render_cb` 决定画什么）；② **自定义命中**（`hit_cb` 决定怎么响应，不只矩形）；③ **复用通用层**（Options + 状态机 + MD3 色板由 SDK 收口——App **只写「画什么/怎么响应」**，生命周期 / 命中分流 / 局部刷新 / 主题 / 状态 / Activity 归属全由 SDK 处理）。
|
||||
|
||||
**API 草案（「草案/待定案」，实现以 `meow_ui.h` 为准）**：
|
||||
|
||||
```c
|
||||
/* —— 自定义画布回调（App 提供；SDK 调用时上下文已就绪）——
|
||||
* render：SDK 在 meow_widget_draw 时调用，th=当前生效主题（MD3 语义色板，§5.8.4）；
|
||||
* w 的 x/y/w/h 已就位；App 用 §3/§4 绘制 API 自绘（往 back_buf 画）。
|
||||
* hit ：命中判定，App 自定义（如圆形/区域外镂空）；返回 1=命中。 */
|
||||
typedef void (*meow_widget_render_fn)(meow_widget *w, const meow_theme *th, void *ctx);
|
||||
typedef int (*meow_widget_hit_fn)(meow_widget *w, int x, int y, void *ctx);
|
||||
|
||||
/* —— 创建：自定义画布（x,y,w,h = 绝对坐标，同既有控件）——
|
||||
* 生命周期/Activity 归属：创建时绑定当前 active Activity（同 meow_btn_create，§6.1 ①）。 */
|
||||
meow_widget *meow_widget_custom_create(int x, int y, int w, int h,
|
||||
meow_widget_render_fn render_cb,
|
||||
meow_widget_hit_fn hit_cb,
|
||||
void *ctx);
|
||||
|
||||
/* 标准控件：既有 create 一字不改（向后兼容）；
|
||||
* 统一用 Options（§5.8.2）修饰、状态机（§5.8.3）统一视觉/交互。 */
|
||||
```
|
||||
|
||||
> **同构理由**：若自定义画布由 App 直接往 back_buf 自绘 + 自行分发命中，会重复造轮子、且与既有控件/模板（§5.2-§5.7 复用 btn/slider/switch/list）行为不一致。收敛到 `meow_widget` 基座后，自定义与内置一样享受：owner 绑定、命中双闸门（`meow_widget_hit` 仅限 `owner==active`，§6.1 ①）、局部刷新（`meow_ui_flush_region`，§3）、主题注入、状态层与 disabled/focused/selected 通用能力。**App 魔改 = 提供 render/hit 两回调，其余 SDK 收口。**
|
||||
|
||||
#### 5.8.2 Modifier 式通用 Options（`meow_widget_opts`）
|
||||
|
||||
**目的**：把「padding / 背景 / 圆角 / 描边 / disabled / selected」等**通用修饰**从每个控件里抽出来，**所有控件（含自定义）通吃**。不做链式 DSL（软渲、极简 → **轻量结构体**），经 `meow_widget_set_opts` 一次性挂载。
|
||||
|
||||
```c
|
||||
/* —— 通用 Options（轻量结构体，非链式 DSL）——
|
||||
* 0 / -1 表示「本项用控件或主题默认」，App 只设想改的项。 */
|
||||
typedef struct meow_widget_opts {
|
||||
uint32_t bg; /* 背景色（0=控件/主题默认，如按钮=th->primary） */
|
||||
uint32_t fg; /* 前景/文字（0=主题 onSurface） */
|
||||
uint32_t stroke; /* 描边色（0=无描边） */
|
||||
int stroke_w; /* 描边宽（px） */
|
||||
int radius; /* 圆角（px；-1=控件默认，如按钮 10） */
|
||||
int pad_x; /* 内边距（水平，px） */
|
||||
int pad_y; /* 内边距（垂直，px） */
|
||||
int margin_x; /* 外边距（水平，px；布局用） */
|
||||
int margin_y; /* 外边距（垂直，px；布局用） */
|
||||
int disabled; /* 1=禁用（视觉变暗 + 不响应命中，见状态机 §5.8.3） */
|
||||
int selected; /* 1=选中（列表高亮/勾选，见状态机 §5.8.3） */
|
||||
} meow_widget_opts;
|
||||
|
||||
/* 挂载：作用于任意控件（标准/自定义）。w 内部浅拷这份 opts。
|
||||
* 返回 0=成功；NULL/无效=负值（不销毁 w）。 */
|
||||
int meow_widget_set_opts(meow_widget *w, const meow_widget_opts *opts);
|
||||
|
||||
/* 取回当前 opts（浅拷到 out；0=成功）。自定义画布用它读通用修饰。 */
|
||||
int meow_widget_opts_get(const meow_widget *w, meow_widget_opts *out);
|
||||
```
|
||||
|
||||
**应用规则**：
|
||||
- **标准控件**：绘制时**先读 opts 覆盖默认**（如按钮默认 bg=`th->primary`、radius=10；pad 按控件内建）。`meow_widget_draw` 内部统一套用 bg/radius/stroke/pad 后再画内容 → 一个按钮可变成卡片/圆角块。既有控件零改动即获得通用修饰能力。
|
||||
- **自定义画布**：App 在 `render_cb` 里**主动读 `meow_widget_opts_get`** 决定自绘底色/圆角/描边；SDK **不替**自定义画布画背景（App 全权自绘），但 **disabled/selected/focused/pressed** 状态层由 SDK 统一暴露（App 读状态位自行叠，见 §5.8.3）。
|
||||
- **命名区分**：`meow_widget_opts`（控件修饰）与 `meow_ui_opts`（§3 init 宽高覆写）同名后缀不同、用途不同，互不相关。
|
||||
|
||||
> **为何不改 create 签名**：既有 `meow_btn_create(x,y,w,h,label)` 等被 App/hello 与设计模板（§5.4-§5.7）广泛使用，改签名即破坏兼容。故 Options 走**独立 set_opts 挂载器**，标准控件零改动获得通用修饰——「扩展/兼容」而非「替换」。
|
||||
|
||||
#### 5.8.3 统一状态机（enabled / selected / focused / pressed）
|
||||
|
||||
**目的**：把「控件处于什么状态、怎么表现」统一为**一套状态机**，标准/自定义控件共用，不再各写各的。
|
||||
|
||||
| 态 | 含义 | 视觉/交互 | 触达来源 |
|
||||
|---|---|---|---|
|
||||
| `enabled` | 可交互（默认 1） | 置 0=变暗 + 不响应 hit + 不进 `pressed` | `meow_widget_set_state(w, MEOW_WS_ENABLED, 0)` |
|
||||
| `selected` | 被选中（列表高亮/单选/多选/开关 on） | 底色用 `primaryContainer`、前景 `onPrimaryContainer`（或描边 `primary`） | App 设 / 控件自身逻辑（如 list 选中、switch on） |
|
||||
| `focused` | 物理键焦点（方向键导航当前命中者） | 外圈描边（1-2px `primary`）+ 可选底 `primary` α8 | **SDK 整页焦点导航**（物理键，见下） |
|
||||
| `pressed` | 按下（触屏按压/物理键触发） | MD3 状态层叠色（基色向 `onSurface` 叠 α，见 §5.8.4） | SDK 触摸层（`meow_widget_touch_refresh`）/ App `meow_btn_pressed` |
|
||||
|
||||
**API 草案**：
|
||||
|
||||
```c
|
||||
/* 状态位（可组合） */
|
||||
#define MEOW_WS_ENABLED (1u<<0)
|
||||
#define MEOW_WS_SELECTED (1u<<1)
|
||||
#define MEOW_WS_FOCUSED (1u<<2)
|
||||
#define MEOW_WS_PRESSED (1u<<3)
|
||||
|
||||
/* 设/查状态（置位/清位，其它位不动）。 */
|
||||
void meow_widget_set_state(meow_widget *w, unsigned bits, int on); /* on=1 置位 / 0 清位 */
|
||||
unsigned meow_widget_state(const meow_widget *w); /* 位掩码 */
|
||||
|
||||
/* 便捷：禁用/启用、选中/取消（单态等效于 set_state）。 */
|
||||
int meow_widget_enabled(const meow_widget *w);
|
||||
void meow_widget_set_enabled(meow_widget *w, int on);
|
||||
int meow_widget_selected(const meow_widget *w);
|
||||
```
|
||||
|
||||
**一致化规则（标准 + 自定义共用）**：
|
||||
- **绘制**：`enabled=0` → 整体变暗（状态层向 `onSurface` 叠 α，或按 `surfaceVariant` 淡化）；`selected` → 语义色板高亮；`pressed` → 在底色叠状态层（alpha 递增）；`focused` → 外圈描边 + 低 α 底。**标准控件由 SDK 自动叠加**；**自定义画布**由 App 在 render 里读 `meow_widget_state()` 自行叠加（SDK 暴露状态位；可选辅助 `meow_widget_draw_state_layer(w,th)` 一键叠状态层——**草案/待定案**）。
|
||||
- **命中/交互**：`enabled=0` 不响应 hit（`meow_widget_hit` 返回 0）、不进 `pressed`；`pressed` 不跨 owner（沿用 §6.1 ① stale 保护）。
|
||||
- **触摸 + 物理键焦点**：
|
||||
- **触摸**：`pressed`/`selected` 由 SDK 触摸层驱动（把 `g_live_btns[]` 从「仅 W_BTN」扩展为**按活动 Activity 分区**的控件注册集 + 实时按压刷新，§6.1 ①，见 §5.8.8 分批）。
|
||||
- **物理键焦点**：无鼠标，物理键（VOL± / 中心确认键，见 §5.1 物理键辅助与 §6 `on_key`）驱动**整页焦点导航**——SDK 维护「当前 active Activity 内可聚焦控件集（`focused` 态）」，VOL± 上下移动、确认键触发。**该导航属 SDK 收口**（不入 App `on_key` 语义），App 只需控件存在；`focused` 由 SDK 置位。**草案/待定案**（见 §5.8.7 硬件约束）。
|
||||
- **默认态**：控件默认 `ENABLED`；`slider`/`switch`/`list` 的选中态映射到 `selected`（开关 on、列表 sel）。
|
||||
|
||||
#### 5.8.4 MD3 完整语义色板（日/夜自动切换）
|
||||
|
||||
**现状**（§8 / `meow_ui_theme`）：`{bg, fg, accent, dim, font_title, font_body}` 四色 + 日/夜两套 + AUTO 跟随系统，控件用 `th->accent/dim/fg`。
|
||||
|
||||
**演进**：把 `meow_ui_theme` **在结构体尾部追加 MD3 语义色板字段**（**扩展兼容**——既有 `bg/fg/accent/dim` 保留为兼容别名/映射，见下表）；标准/自定义控件统一从 `meow_theme`（`th` 传入 render）取色，不再硬编码（如现有按钮文字 `0xFFFFFF`）。
|
||||
|
||||
**MD3 语义色板（日/夜各自取值）草案**：
|
||||
|
||||
```c
|
||||
typedef struct meow_theme {
|
||||
/* —— 既有字段（兼容保留，映射见下表）—— */
|
||||
uint32_t bg, fg, accent, dim;
|
||||
int font_title, font_body; /* 28 / 20 */
|
||||
/* —— MD3 语义色板（新增；日/夜各一组，AUTO 按 meow_theme_mode 切换）——
|
||||
* 取值对齐 Material 3 语义色（本地化到主题 primary 等），非固定品牌色。 */
|
||||
uint32_t onPrimary, primaryContainer, onPrimaryContainer;
|
||||
uint32_t secondary, onSecondary, secondaryContainer, onSecondaryContainer;
|
||||
uint32_t tertiary, onTertiary, tertiaryContainer, onTertiaryContainer;
|
||||
uint32_t surface, onSurface, surfaceVariant, onSurfaceVariant;
|
||||
uint32_t surfaceContainerLowest, surfaceContainerLow, surfaceContainer,
|
||||
surfaceContainerHigh, surfaceContainerHighest;
|
||||
uint32_t surfaceDim, surfaceBright, surfaceTint;
|
||||
uint32_t outline, outlineVariant, scrim;
|
||||
uint32_t error, onError, errorContainer, onErrorContainer;
|
||||
uint32_t inverseSurface, inverseOnSurface, inversePrimary;
|
||||
uint32_t shadow; /* 仅状态层/描边近似用；无 GPU 不做投影（§5.8.7） */
|
||||
} meow_theme;
|
||||
```
|
||||
|
||||
**与既有字段映射（等价保留，代码可继续用旧字段）**：
|
||||
|
||||
| 旧字段 | 等价 MD3 语义色 | 说明 |
|
||||
|---|---|---|
|
||||
| `bg` | `surface`（/`background`） | 页面底 |
|
||||
| `fg` | `onSurface` | 正文/前景 |
|
||||
| `accent` | `primary` | 强调色（按钮/选中） |
|
||||
| `dim` | `onSurfaceVariant` | 次要文字/弱前景 |
|
||||
|
||||
**取色规则**：
|
||||
- **标准控件**：绘制读 `meow_theme_get()`，全用语义色（primary/surface/surfaceVariant/outline/error/…），不再硬编码。
|
||||
- **自定义画布**：`render_cb` 的 `th` 参数即当前生效主题（MD3 板），App 取 `th->primary/onPrimary/surface/...` 自绘 → **自动日/夜切色**，无需 App 额外查色板。
|
||||
- **日/夜切换**：沿用 `meow_theme_mode`（LIGHT/DARK/AUTO，§8）+ `meow_theme_get` 返回当前板；AUTO 按 `display.theme_mode` 解析（日/夜），切换时经 `meow_theme_listener` 广播（§8），App 在 `on_tick` 重绘（`meow_ui_flush_region`）。
|
||||
- **状态层（MD3 overlay）**：`pressed/focused/disabled/selected` 视觉用「状态层叠色」——基色（如 `primary`/`surface`）向 `onSurface` 叠 alpha（对应 MD3 state-layer 思想），取代现有 `blend_color`（`meow_ui_widget.c` 已内置）；演进时把状态层颜色来源改为语义色板，不外露给 App。
|
||||
|
||||
> **注意**：`meow_ui_theme` 追加字段 = **`meow_ui.a` ABI 变化** → 需按 §9/§10「**同步重编 hello**（App 也链 `meow_ui.a`）」一并处理（§5.8.8 分批）。
|
||||
|
||||
#### 5.8.5 可组合布局（Row / Column / Box + Spacer）
|
||||
|
||||
**目的**：让 App 少手算坐标。既有控件是**绝对定位**（x,y,w,h）；布局是**相对布局容器**，内部在 arrange 时把子控件**算成绝对坐标**（结果仍写进每个控件的 x,y,w,h）→ 与现有绝对定位**完全兼容**——布局只是「帮你算坐标」的容器，不改变控件绘制 / 命中 / 状态机。
|
||||
|
||||
```c
|
||||
/* 布局容器：Row（横排）/ Column（纵排）/ Box（叠放）。坐标 = 容器矩形（绝对）。 */
|
||||
enum { MEOW_LAYOUT_ROW, MEOW_LAYOUT_COLUMN, MEOW_LAYOUT_BOX } meow_layout_kind;
|
||||
|
||||
meow_widget *meow_row_create(int x, int y, int w, int h, int spacing);
|
||||
meow_widget *meow_column_create(int x, int y, int w, int h, int spacing);
|
||||
meow_widget *meow_box_create(int x, int y, int w, int h);
|
||||
|
||||
/* 添加子控件（子可为普通控件/自定义/另一布局/Spacer）。返回 0=成功。 */
|
||||
int meow_layout_add(meow_widget *layout, meow_widget *child);
|
||||
/* 计算子控件绝对坐标（写入各 child 的 x,y,w,h）；此后照常 draw/hit。 */
|
||||
void meow_layout_arrange(meow_widget *layout);
|
||||
|
||||
/* 固定尺寸空白（也作 flex 撑余量）。 */
|
||||
meow_widget *meow_layout_spacer(int w, int h);
|
||||
```
|
||||
|
||||
- **坐标语义**：child 的 x,y 在加入布局后由 arrange 覆写为布局内绝对位置；child 的 w/h 若为 0 表示「按内容/弹性」由布局分配（**草案/待定案**——B1 控件皆有确定 w/h，先支持固定尺寸子项，弹性为后续增强）。
|
||||
- **与绝对定位兼容**：控件最终 x,y,w,h 即绝对坐标，故 `meow_widget_draw/hit`（§5）、`meow_ui_flush_region`（§3）、owner 闸门（§6.1 ①）照常不变。
|
||||
- **局部刷新**：交互仍只刷变化区（`meow_ui_flush_region`），布局不导致整页重排；仅 arrange 时算一次坐标。
|
||||
- **嵌套**：布局可作另一布局的子控件（Row 内嵌 Column），arrange 递归。
|
||||
|
||||
#### 5.8.6 Material 组件子集（后续追加批次）
|
||||
|
||||
> **性质**：Material 3 组件子集，**后续追加批次**（不随第一批基座落地）。基于「统一控件架构 + Options + 状态机 + MD3 色板」实现，观感对齐 MD3、本地化到主题语义色。每项一句用途：
|
||||
|
||||
| 组件 | 一句用途 | 批次 |
|
||||
|---|---|---|
|
||||
| TextField | 单/多行文本输入（复用 IME §5.1） | 后续 |
|
||||
| Card | 圆角容器卡片（`surfaceContainer` 底 + 可选描边/状态层） | 后续 |
|
||||
| Divider | 横向/纵向分隔线 | 后续 |
|
||||
| Badge | 角标（红点/计数） | 后续 |
|
||||
| Checkbox | 复选（`selected` 态 + `primary` 勾） | 后续 |
|
||||
| Radio | 单选（单选组；`selected` 态） | 后续 |
|
||||
| ProgressBar | 线性/圆形进度（确定性 + 不定性） | 后续 |
|
||||
| Button（五型） | filled / tonal / outlined / text / elevated（`meow_btn` 扩展五型，Options 区分） | 后续 |
|
||||
| TopAppBar | 顶部标题栏（标题 + 返回 + 操作） | 后续 |
|
||||
| NavigationBar | 底部导航栏（图标 + 文字） | 后续 |
|
||||
| TabBar | 顶部分页 Tab（swipe 联动 §5.2） | 后续 |
|
||||
| BottomSheet | 底部面板（复用 §5.7 B④ 面板） | 后续 |
|
||||
| Dialog | 弹窗（复用 §5.6 B③ 弹窗） | 后续 |
|
||||
| FloatingActionButton | 悬浮操作钮（圆角增强；无投影，仅描边/状态层近似） | 后续 |
|
||||
| 列表容器 | 可滚动列表（复用 §5.5 A② listview） | 后续 |
|
||||
|
||||
> **说明**：多数 Material 组件是**既有设计模板（§5.2-§5.7）的「MD3 观感化」**——如 Card=圆角容器、BottomSheet 复用 §5.7 面板、Dialog 复用 §5.6 弹窗、TabBar 联动 §5.2 分页、列表容器复用 §5.5 listview。故 Material 子集**不重复造结构**，只把这些模板的绘制观感对齐 MD3 语义色 + 统一基座。**首批不实现**（见 §5.8.8）。
|
||||
|
||||
#### 5.8.7 取舍 / 不做（移植思想而非照搬）
|
||||
|
||||
> **关键（防照搬桌面 UI 框架踩坑）**：本层是**软渲 + 无 GPU + 无鼠标 + 14MB 内存/极简 rootfs** 的嵌入式环境（§11）。移植 Compose/Flutter 的**思想**（组合/状态驱动/语义色），**不照搬其运行时**：
|
||||
|
||||
- **不做声明式运行时（状态→UI 全量重算）**：Compose/Flutter 把 UI 声明为状态函数、每帧全量 recompose/rebuild；软渲（CPU 逐像素、back_buf 全帧 blit）扛不住高频全量重算。MeowOS 控件为**命令式 + 局部重绘**（状态变化只刷变化区，§5.4/§5.5/§7）。状态机（§5.8.3）只驱动**控件自身**局部重绘，不触发整页重建。
|
||||
- **不做重度动画/模糊/阴影**：无 GPU（≤60fps 软渲，§11）。动画=状态式短插值（§5.2/§5.7「松手补 2-4 帧吸附」）；模糊=「降采样」廉价版（§11，封面缩 1/8 铺底，仅切歌算一次）；阴影**不做投影**（无 GPU 合成，仅用 `shadow` 语义色做描边/状态层近似，避免每帧多 pass 铺底）。
|
||||
- **不做 hover**：无鼠标（仅触摸 goodix + 物理键）。按压反馈=触摸 `pressed` 状态层（§5.8.3）；鼠标 hover 一律不做；**物理键焦点**（`focused`）作为「无鼠标导航」替代——只做方向键移动 + 确认，不做悬停。
|
||||
- **组件轻量**：单个控件=1 个 `meow_widget`（小结构体）；无对象树/无布局引擎运行时；options 是轻量结构体（非链式 DSL）；布局只在 arrange 算一次坐标、不维护昂贵约束求解。**无虚拟 DOM / 无增量 reconcile**。
|
||||
- **语义色而非品牌色**：所有组件取 `meow_theme` 语义色（primary/surface/…，§5.8.4），App 不自配色 → 日/夜/系统观感统一点（§8）。
|
||||
- **移思想不照搬**：借 Composition / Modifier / 语义色 / 状态层的**命名与心智模型**，实现为**轻量 C 结构体 + 命令式重绘**；不引入 GC/协程/运行时反射，不用虚拟机。
|
||||
|
||||
#### 5.8.8 分批实现建议
|
||||
|
||||
**第一批 = 通用基座**（先行；落地后 all 控件升级地基）：
|
||||
1. **MD3 语义色板扩展**（§5.8.4）：`meow_theme` 尾部追加语义色字段 + 日/夜取值 + 映射旧字段（bg/fg/accent/dim）；`meow_theme_get` 返回新板。
|
||||
2. **统一 Options**（§5.8.2）：`meow_widget_opts` + `meow_widget_set_opts/get_opts`；标准控件绘制读 opts。
|
||||
3. **统一状态机**（§5.8.3）：`enabled/selected/focused/pressed` 状态位 + `meow_widget_state/set_state/enabled/selected`；标准控件绘制叠状态层；`disabled` 阻断 hit/pressed。
|
||||
4. **自定义画布融合**（§5.8.1）：`meow_widget_custom_create` + `W_CUSTOM`；基座统一 render（th 注入）/hit；与标准控件同构（owner/命中双闸门/局部刷新/主题/状态机）。
|
||||
5. **可组合布局**（§5.8.5）：`meow_row/column/box + meow_layout_add/arrange + spacer`；固定尺寸子项先做，算绝对坐标（与绝对定位兼容）。
|
||||
6. **实时按压刷新扩展**：把 `g_live_btns[]`（仅 W_BTN）扩展为「按活动 Activity 分区」控件注册集（§6.1 ①），供标准 + 自定义画布共用按压态即时刷新。
|
||||
|
||||
**第二批 = Material 组件子集**（§5.8.6）：TextField/Card/Divider/Badge/Checkbox/Radio/ProgressBar/Button 五型/TopAppBar/NavigationBar/TabBar/BottomSheet/Dialog/FloatingActionButton/列表容器——基于第一批基座实现，多数复用既有设计模板（§5.2-§5.7）的「MD3 观感化」。
|
||||
|
||||
**同步重编注意（关键）**：`meow_ui_theme` 追加字段 / `meow_widget` 结构变化 → **`meow_ui.a` ABI 变化** → 需按 §9/§10「**同步重编 hello**（App 也链 `meow_ui.a meow_font.a libz.a -lpthread`）」一并处理；`build_sdk.sh` 一键重编 + `hello_app/build_hello.sh` 重链。**B1 既有控件与模板零改动**（§5.8.1/§5.8.2 均向后兼容）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 输入层 / 生命周期（B1 部分 + B2 衔接）
|
||||
|
||||
**B1（本阶段）**：应用不再自读 `/dev/input/event*`，meow_ui 建立输入线程，把按键/触摸翻译成语义事件回调：
|
||||
|
||||
Reference in new issue
Block a user