project-binding-adapter-from-source

# 从源码生成 DataBinding BindingAdapter ## 模块路径（本地优先，与 viewtheme 共用锚点） | 符号 | 当前值（DevUtils） | |------|-------------------| | `DEVSIMPLE_ROOT` | `lib/DevSimple` | | `BINDING_VIEW_DIR` | `{DEVSIMPLE_ROOT}/src/main/java/dev/simple/bindingadapters/view` | | `BINDING_ATTR_DIR` | `{DEVSIMPLE_ROOT}/src/main/java/dev/simple/bindingadapters/view/attribute` | 存在 `{DEVSIMPLE_ROOT}` 时 **Read 本地 `*.kt`**，勿用 WebFetch 代替。生成前在 `{BINDING_VIEW_DIR}` 下列出并对照现有实现；**优先范例文件名、前缀惯例、判定表** → [references/reference.md](references/reference.md)。 **上游 fallback**（仅工作区无模块时）：https://github.com/afkT/DevUtils/tree/master/lib/DevSimple ## 必读搭配 生成或改写 **方法体与文档** 时，**同时 Read 并遵守**： - [code-method-normalize/SKILL.md](../code-method-normalize/SKILL.md)（JavaDoc/KDoc、`<pre>`、首段规则、`@param`/`@return`、`boolean` 对举、异常内消化等） 本 Skill 负责 **「是否该做 BindingAdapter、属性如何设计、时间戳与合并参数」**；文档句式交给 **code-method-normalize**。 ## 风格对齐（执行要点） 1. **Read** `{BINDING_VIEW_DIR}` 下与目标控件相关的 `*.kt`（至少一份同族文件 + [references/reference.md §优先范例](references/reference.md#优先范例文件按主题选读) 中对应行）。 2. 合并参数实体放在 `{BINDING_ATTR_DIR}`；`XYI` 等写法对照同目录 `XYI.kt`。 3. 文件头「不适合 BindingAdapter」的说明以 **`View.kt`** 为准（路径见 reference）。 --- ## 1. 核心门槛：方法是否适合 BindingAdapter + XML BindingAdapter 绑定在 **布局里的单个 View 节点**；只封装 **对该接收者 View（及合理子类型）有意义、且能在 XML 表达参数** 的操作。 **应跳过或不要求用户封装**（与 `View.kt` 文件头说明一致）的典型类别： - 需要 **LayoutInflater / 非当前节点上下文** 的：`inflate` 等 - 返回 **Activity / Fragment / 任意非 View** 且无法在绑定中作为稳定入参的：`getActivity` 等 - 依赖 **任意子下标访问**、且语义不属于「当前节点自身配置」的：`getChildAt` 等（除非业务明确绑定的是容器且参数是 index，再按列表类控件单独设计） - **ViewGroup 结构转换** 等与当前节点单次属性语义不符的：`convertViewGroup` 等 **适合封装的正向例子**：`removeAllViews`、`requestLayout`、`setText`、滚动到某位置、设置可见性、设置图片资源等——参数为基本类型、`String`、Drawable、`XYI` 等可在 Binding / LiveData 中传递的类型。 若某方法 **仅 `View`/`TextView`/… 一个参数**，除「纯状态同步」（如设置某个由 XML 已绑定的 bool）外，**重复触发**（同值不刷新）往往成问题 → 见第 2 节 **时间戳**。 --- ## 2. 仅 View（接收者）型副作用：`Long?` 时间戳触发 当底层 API 形如 `FooUtils.action(view)` **仅有当前接收者、无业务参数**，又需要在 MVVM 里 **多次触发同一逻辑**（例如再次滑到底、再次清空）时： - **唯一绑定入参** 使用 `timestamp: Long?`（或与其它参数组合时，时间戳作为触发列之一） - 在适配器开头使用 **与项目一致的正时间戳判断**（见第 3 节） - 在 KDoc `<pre>` 中写明：建议绑定 `System.currentTimeMillis()` 或 ViewModel 内递增时间戳；**优于** `LiveData<Boolean>` 固定 `true` 不二次刷新 **成对语义（示例）**：已有 `EditTextUtils.setText(view, text)` 对应「设文本」；可另增 **「清空文本」** 适配器，入参仅为 `timestamp: Long?`，内部在通过校验后调用 `EditTextUtils.setText(view, "")`（或项目等价 API）。文档中说明与 `binding_et_text` 等的关系，避免重复绑定冲突。 --- ## 2.5 Boolean 三态开关（开启 / 关闭 / 不修改） 当底层工具类提供 **成对的 set / remove**（或语义等价的 enable / disable）API，且布局需要绑定 **可切换、可保持的 View 效果**（下划线、删除线、`paintFlags` 装饰、部分可见性样式等）时： - 绑定入参使用 **`Boolean?`**（不用非空 `Boolean`，以便区分「未绑定」与「显式关闭」）。 - 适配器内统一约定： - **`null`** → `return`，**不修改** View（未提供 LiveData、或尚未赋值时保留 XML / 主题默认）。 - **`true`** → 调用 **开启 / 设置** API（如 `TextViewUtils.setUnderlineText`）。 - **`false`** → 调用 **关闭 / 移除** API（如 `TextViewUtils.removeUnderlineText`）。 与 **§2 时间戳** 的分工： | 场景 | 选用 | |------|------| | 需要 **同步并保持** 开/关状态，随 DataBinding 刷新更新 UI | **`Boolean?` 三态**（本节） | | **无状态**，每次都要 **再触发一次** 副作用（再次滚到底、再次清空） | **`Long?` 时间戳**（§2） | | 工具类 **仅有 set、无 remove**，且 `false` 语义就是「不做事」 | 可 `Boolean?` 仅 `true` 时执行；若业务要在布局里 **关掉** 已有效果，应补 remove 工具方法后改本节三态 | **禁止**：底层已有 `removeXxx` 时仍写 `if (flag != true) return`，导致布局绑 `false` 无法撤销效果。 **仓库参考实现**：`TextView.bindingTVUnderline`、`TextView.bindingTVStrikeThru`（见 `{BINDING_VIEW_DIR}/TextView.kt`，reference §优先范例）。 ```kotlin fun TextView.bindingTVUnderline( underline: Boolean?, antiAlias: Boolean?, ) { if (underline == null) return if (underline) { TextViewUtils.setUnderlineText(this, antiAlias ?: true) } else { TextViewUtils.removeUnderlineText(this) } } ``` - 可选第二参数（如 `antiAlias`）仅在 **`true` 开启分支** 使用；`requireAll = false` 时缺省与工具类一致。 - KDoc `<pre>` 中写明三态与对应的 `set*` / `remove*` 工具方法名。 --- ## 3. 时间戳判定：可复用扩展 逻辑统一为：**非 null 且大于 0** 才执行。 本仓库已有： ```kotlin fun Long?.qualifiesScroll(): Boolean = this != null && this > 0L ``` **新代码**若语义不是滚动（避免命名误导），可在同一模块抽取例如： ```kotlin /** 数据绑定用：时间戳非空且大于 0 时执行一次副作用。 */ fun Long?.qualifiesBindingAction(): Boolean = this != null && this > 0L ``` 具体命名与存放文件随模块惯例；**禁止**用 `<=0` 或 `null` 仍执行（除非项目已有特例并在备注中写明）。 --- ## 4. 多参数合并为实体类（减少绑定次数与属性数量） **避免** 多个密切相关、应同事务触发的量拆成多个 `binding_*`，导致 **多次调用适配器**、LiveData 数量膨胀。 做法： 1. 在 `dev.simple.bindingadapters.view.attribute`（即 `{BINDING_ATTR_DIR}`，或用户指定包的 `attribute` 子包）新增 **Kotlin data class / open class**，字段覆盖原工具方法参数（含可选默认值）。 2. **单个** `@BindingAdapter("binding_…_single_snake_name")`，入参为该类型可空；`null` 时跳过。 3. 命名与 **XYI** 对齐习惯：简短后缀表意（如位移用 `XYI`）；补充 `equals`/`hashCode`（data class 自带）、`toString`、伴生工厂方法视需要。 4. 迁移示例：由 `binding_scroll_instant_rel_dx` + `binding_scroll_instant_rel_dy`（`requireAll = false`）改为 **`binding_scroll_instant_rel_xy`** + `XYI?`（见用户提供的旧/新对照）。 --- ## 5. 布局属性与 Kotlin 命名 - XML：`app:binding_snake_case`；`@BindingAdapter` 的 `value` 与之一致。 - Kotlin 扩展：`fun View.bindingCamelCase(...)`，与文件内现有风格一致。 - `requireAll = false` 仅当 **确有独立缺省语义** 时使用；能合并为实体类则优先合并。 - 有返回值时：优先 `Boolean` 表示是否执行/成功，并满足 **code-method-normalize** 中 `boolean`/`Boolean` 的 `@return` 写法。 --- ## 6. 生成工作流（Agent 执行顺序） 1. **Read** 用户给出的源文件，列出候选 `public`/`internal` 方法。 2. **过滤** 第 1 节不适配 XML 的 API。 3. 对每个保留方法：**映射接收者类型**（`View` / `TextView` / `ImageView` / `ViewGroup` / `RecyclerView` 等）、**参数拆分或合并**（第 4 节）、**是否需要时间戳**（第 2 节）或 **Boolean 三态开关**（第 2.5 节）。 4. 落文件：新适配器写入 `{BINDING_VIEW_DIR}/`（按控件分文件，与现有 `TextView.kt`、`ViewScroll.kt` 等并列）；attribute 类写入 `{BINDING_ATTR_DIR}/`。 5. **Read** `code-method-normalize` 并整理文档与返回类型。 6. 自检：`@BindingAdapter` 不与 `{BINDING_VIEW_DIR}` 内已有属性名冲突；`try/catch` 与日志风格参照 reference 中 **TextView** / **ImageViewLoadNative** 范例。 判定表、XML 示例、`binding_*` 前缀表见 [references/reference.md](references/reference.md)。 ## 执行清单 - [ ] 已 Read 本地 `{BINDING_VIEW_DIR}` 或 reference §优先范例，而非仅凭记忆写适配器。 - [ ] 已对照 reference §DevSimple 前缀惯例，避免 `binding_*` 冲突。 - [ ] 新 attribute 类落在 `{BINDING_ATTR_DIR}`；成稿前已 Read `code-method-normalize`。