弹窗内做"搜索 + 分类 + 网格"

经验 1：弹窗内做"搜索 + 分类 + 网格"，用局部刷新保住输入焦点

lua
-- 模块级状态：跨弹窗持久，满足"记住上次分类"
local objectSearchQuery_ = ""
local objectCategory_ = "全部"
local objectGridContainer_ = nil      -- 网格容器引用，供局部刷新
local objectOverlayPanel_ = nil       -- 外壳引用，供动态改高度
local objectCatTabRefs_ = {}          -- 分类标签引用，供改高亮
local OBJECT_CATEGORY_ORDER = { "全部", "家具", "教学", "生活设施", "清洁", "随身物品", "电子设备" }

-- 局部刷新：只动网格 + 改标签色 + 改外壳高度，绝不 RebuildUI
RefreshObjectGrid = function(context)
    if not objectGridContainer_ then return end
    local filtered = FilterObjectItems(PALETTE_ITEMS.object or {})
    objectGridContainer_:ClearChildren()
    for i = 1, #filtered do
        local card = CreatePaletteCard(filtered[i], i, context, 0)  -- 0 = 相对 grid 定位
        card.props.zIndex = 3
        objectGridContainer_:AddChild(card)
    end
    local gridH = math.max(1, math.ceil(#filtered / 4)) * 82
    objectGridContainer_.props.height = gridH
    if objectOverlayPanel_ then
        objectOverlayPanel_.props.height = OBJECT_HEADER_H + gridH + 12
    end
    for _, tab in ipairs(objectCatTabRefs_) do
        local activeTab = tab._cat == objectCategory_
        tab:SetStyle({   -- 原地改色，不重建
            backgroundColor = activeTab and { 74, 126, 164, 246 } or { 52, 50, 44, 236 },
            borderColor     = activeTab and { 255, 232, 110, 255 } or { 120, 104, 74, 255 },
        })
    end
end

lua
overlay:AddChild(UI.TextField {
    position = "absolute", left = 12, top = 10,
    width = contentWidth - 24, height = 30, fontSize = 13,
    value = objectSearchQuery_ or "", placeholder = "搜索物品...",
    onChange = function(self, value)
        objectSearchQuery_ = value or ""
        RefreshObjectGrid(context)   -- 只刷网格，焦点不丢
    end,
})
-- 分类标签：onPointerDown 切分类后只刷网格
local tab = UI.Panel {
    onPointerDown = function(event)
        if event then event:StopPropagation() end   -- 见经验 6 的 onClick 守卫区别
        objectCategory_ = catName
        RefreshObjectGrid(context)
    end,
    children = { UI.Label { text = catName, pointerEvents = "none", ... } },
}

经验 2：flex 列里的 Label 想水平居中，必须 width="100%" + textAlign="center"

lua
UI.Label {
    text = item.text,
    width = "100%",          -- 禁用 autoWidth，撑满父宽
    textAlign = "center",    -- 此时居中才有可视效果
    fontSize = 14,
    fontColor = { 246, 236, 200, 255 },
    maxLines = 1,
},

经验 3：运行时拾取"零代码自动接通"——靠 text == name 逐字匹配

lua
-- scripts/数据/地图/校园主地图.lua
function M.NormalizeObjects()
    for i = 1, #map.objects do
        local object = map.objects[i]
        local itemId = ItemRegistry.ResolveItemId(object.type)  -- object.type = 编辑器目录的 text
        if itemId then
            object.interactable     = true     -- 强制补齐，不看编辑器目录
            object.carryable        = true
            object.interactionType  = "pickup"
            object.itemId = itemId
        end
    end
end

-- 匹配桥梁：中文名或 itemId 都能命中
function ItemRegistry.ResolveItemId(objectType)
    for id, def in pairs(ITEMS) do
        if def.name == objectType or id == objectType then return id end
    end
    return nil
end

经验 4：手持/地面双尺寸，用一个"尺寸漏斗"收敛

lua
-- 单一漏斗：held 优先 → 地面回退 → 兜底 3
function PlayerInteractionService.GetHeldItemVisual()
    local player = GetPlayer()
    if not player or not player.heldObjectId then return nil end
    local object = FindObject(player.heldObjectId)
    if not object or not object.image then return nil end
    local def = ResolveItemDef(object)
    local w = (def and def.heldVisualWidth)  or object.visualWidth  or 3
    local h = (def and def.heldVisualHeight) or object.visualHeight or 3
    return { image = object.image, visualWidth = w, visualHeight = h }
end

lua
screwdriver = { ..., heldVisualWidth = 2, heldVisualHeight = 4, ... },  -- 放大 2 倍
broom       = { ..., /* 不写 heldVisual，回退地面 4×4 */ },

经验 5：手持垂直定位用"躯干锚点"，别用几何中心

lua
local CHAR_W, CHAR_H = 36, 36
local HELD_ITEM_Y_ANCHOR = 0.65   -- 0.5=几何中心，0.65=躯干，0.7=腰，0.8=腿侧

local itemLeft, itemTop = 0, 0
if heldVisual then
    itemLeft = math.floor((contW - itemW) / 2)                      -- 水平仍居中
    local anchorY = charTop + CHAR_H * HELD_ITEM_Y_ANCHOR           -- 锚到躯干
    itemTop  = math.floor(anchorY - itemH / 2)                      -- 物品中心对齐锚点
end

经验 6：Lua 前向声明必须 name = function，绝不能 local function name

lua
local RecordObjectUse          -- line 94：前向声明，值 nil
...
RecordObjectUse = function(itemText)   -- 定义处：赋值，复用上面的 upvalue
    if not itemText then return end
    for i = 1, #objectRecentUse_ do
        if objectRecentUse_[i] == itemText then table.remove(objectRecentUse_, i); break end
    end
    table.insert(objectRecentUse_, 1, itemText)
    if #objectRecentUse_ > 20 then objectRecentUse_[#objectRecentUse_] = nil end
end

lua
if cat == "全部" and query == "" and #objectRecentUse_ > 0 then
    local rankMap = {}
    for i = 1, #objectRecentUse_ do rankMap[objectRecentUse_[i]] = i end
    table.sort(out, function(a, b)
        return (rankMap[a.text] or 9999) < (rankMap[b.text] or 9999)
    end)
end

复用清单：新增一件"可拾取物品"的标准 4 步

1. 物品注册表加条目：id / name / image / category / 效果积木块，需要手持缩小时加 heldVisualWidth/Height，想手持=地面就不写。
2. 编辑器目录 object 表加条目：text 必须逐字等于注册表 name，加 category（控制分类标签），image 指 image/交互/*.png。不要写 interactable。
3. 若分类是新的，在 OBJECT_CATEGORY_ORDER 追加名称。
4. LSP 0 Error → 官方 Build。运行时拾取/金圈/效果全部自动生效，无需改交互服务或渲染层。