skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
developer.tuya.com100 installs

smart-ui-skill

面向 Ray 小程序 smart-ui,基于 meta-first 工作流协助生成与修改页面与组件。在用户提出 UI 搭建、组件改造、表单与反馈交互、导航展示、图片转代码或 smart-ui 排障升级时使用;也覆盖在纯浏览器 / H5 / 非小程序宿主中使用 smart-ui 的 Web Components(assets/wc/ 目录)场景。仅覆盖 smart-ui,实现前须查阅 _meta.json 与组件文档,禁止虚构 props、事件与能力。

How do I install this agent skill?

npx skills add https://developer.tuya.com --skill smart-ui-skill
view source ↗

Is this agent skill safe to install?

No partner audit is available yet. Read the source before installing.

What does this agent skill do?

概述 {#description}

本 skill 是 Ray 小程序 smart-ui 的专项开发入口,采用 meta-first 流程(先索引、再文档、最后输出),不使用任务分区。目标是在有据可查的前提下完成页面与组件的设计、改造与排障,避免对文档未载明的能力进行猜测。

适用场景 {#scene}

  • 搭建或调整 smart-ui 页面、布局与组件组合。
  • 表单、反馈类交互、导航与展示类 UI 的实现或改造。
  • 图片转代码、参考稿落地为 smart-ui 结构。
  • smart-ui 相关报错、样式或行为不符合预期时的定位与升级。
  • 在纯浏览器 / H5 / 预览页等非小程序宿主中使用 smart-ui:改用 assets/wc/ 下的 Web Components,见 Web Components 用法。

当前仅处理 smart-ui,不作为通用 Ray API 或设备能力开发总入口。若用户目标超出 smart-ui,应先说明超出当前范围,再给出最小必要的外部建议。

搭配使用 {#usage}

  • ** requirement-creating-guide-skill **:需求生成指南 skill,配合使用可产出符合小程序面板规范的需求文档。
  • ** ray-common-develop-skill **:Ray 小程序开发 skill,配合使用可在更广泛的 Ray 开发场景中提供文档导航与实现约束,提升开发效率和代码质量。

工作流程 {#workflow}

  1. 先读索引:读取 references/smart-ui/_meta.json,按 englishName、chineseName、category 初筛候选组件。
  2. 再读文档:读取 1~2 个候选组件对应的 references/smart-ui/*.md;信息不足时再增量补读 1~2 个相关文档。不允许一次性扫完整个 references/smart-ui/ 目录,须按需增量读取。
  3. 核对默认样式:只要涉及样式还原、间距 / 对齐、深色背景配色、覆盖组件默认外观,先查 references/default-styles.md(内置默认 token 速查 + 高风险清单)确认组件自带的默认 padding / margin / inset / max-width / 字号 / 行高 / min-height / icon-size / 颜色,再动手;穷尽查具体 token 值回权威源 references/smart-ui-default-tokens.less。不要在不知道默认值的情况下靠外层容器反向补偿或手写重画组件外观。
  4. 最后输出:先给结论,再给依据与实现建议;文档未覆盖时须显式说明「未在文档中找到」,禁止静默猜测。

输出时需区分两类信息:文档确认(明确来自当前已读文档)与经验推断(文档未覆盖、基于上下文的保守假设)。涉及能力说明时,优先引用组件文档中的 props、events、示例与注意事项。

默认约定:UI 优先 smart-ui;无法满足时再考虑 Ray 原生组件。页面生成默认放在 /pages,组件默认放在 /components。若涉及文案,提醒接入 i18n,避免在业务代码中硬编码中文。

生成硬约束(第一版代码就必须遵守){#must}

下面几条是高频反复出现的坑,历史上都是"生成→发现点不动/对不齐→再修"。它们不是排障项,是生成规范:写第一版代码时就必须内置,输出前逐条自检。 每条的原理与更多细节见后文链接。

  • 受控组件必须带 change 写回:smart-switch / smart-checkbox / smart-radio / smart-slider / smart-stepper / smart-field 只上报事件、不自更新。手写静态 HTML(无 data-bind-* 运行时)时,生成的同时就要给它们加 change 监听把新值写回(switch 写 checked attribute)。少了它 = 「点了没反应」。详见后文「使用约定 → 受控组件必须写回值」。
  • 用 inset 的 CellGroup,容器已有左右 padding 时必须归零 inset margin:inset 默认带 margin: 0 16px(变量名 --cell-group-inset-padding 实为 margin)。当页面内容容器已有 padding:0 16px 时,生成时就在容器上写 --cell-group-inset-padding: 0,否则 CellGroup 会比同页其它卡窄 32px、左右对不齐。详见 内置组件默认样式覆盖 坑 1。
  • NavBar 一级/二级选对,且标题不并存、深色背景改色:首页用 leftText+leftTextType="home"(无箭头无 title);子页用 leftArrow+居中 title(sideWidth 按内容选 min/mid/max,选窄了右侧文字会截断)。居中 title 与 home 左标题二选一。深色 Hero 上文字/图标色必须用 --nav-bar-*-color 变量覆盖(color 不穿透)。详见 内置组件默认样式覆盖 坑 2、3。
  • 图标用对机制 + 显式设颜色:组件 *-icon 属性只认 SmartUI 字形名;要放 RemixIcon 用 slot + <smart-icon data-remix="settings-3-line">(key 去 ri- 前缀)并加载 remix-icons.js,且写进静态 HTML。smart-icon 颜色只认组件的 color= 属性或 --icon-color CSS 变量——CSS 里写 color: …(含 color: var(--app-M1)、内联 style="color"、继承)对 mask 图标统统无效、保持默认黑。想让图标跟主题色:给图标或其容器加 --icon-color(可与文字 color 同值)。徽标/深色背景/主题色图标发黑,基本都是把 color: 当成了上色手段。详见 图标 段。
  • 组件自带 padding 的(Cell / Collapse / NavBar / CellGroup / Search),外层不要再补同方向 padding,避免双重内边距。

输出前自检(必跑):每输出 / 修改完一版 HTML,最后一步跑静态自检脚本,把 [E] 项清零再交付:

node <skill>/scripts/check-artifact.mjs <生成的.html> [更多.html ...]

它静态拦截高频坑:data-remix 带 ri- 前缀 / 无效 key(icon 不渲染)、用了 <smart-*> 却没加载 demo-runtime.js(switch 点不动)、组件 *-icon 传了 remix 名、smart-icon 用 style="color" 上色(应 --icon-color)、NavBar home+title 并存、smart-search background 染错层。[E] 必修、[W] 建议。CSS/语义类坑(彩底黑图标、CellGroup inset 双缩进、间距)静态查不到,仍需对照下面各条人工核。

Web Components 用法 {#webcomponents}

除 Ray 小程序外,smart-ui 还提供一套浏览器可直接运行的 Web Components,位于本 skill 的 assets/wc/ 目录。它由 packages/* 经 @tuya-miniapp/mp-compiler 编译而来,不是另写一套实现,组件行为与小程序版一致。当需求是纯浏览器 / H5 / 预览页 / 非小程序宿主中使用 smart-ui 时,走本节;小程序内开发仍走 references/smart-ui/ 的 meta-first 流程。

目录内容

  • assets/wc/wc-dist/:编译产物合包(运行时 + 组件),示例页依赖它。
  • assets/wc/smart-<name>-example.html(67 份):每个组件的可运行示例,是最权威的用法参考。
  • assets/wc/smart-<name>.md(67 份):每个组件的属性 / 属性名映射 / 事件 API 表。
  • assets/wc/home.html:组件总入口导航,按「基础 / 表单 / 反馈 / 展示 / 导航 / 业务」分类列出全部组件。
  • assets/wc/demo-runtime.js、assets/wc/remix-icons.js(RemixIcon 名 → SVG path 字典 + <smart-icon data-remix> 桥接,全量 3227 图标,覆盖等同旧 remixicon 字体)、assets/wc/smart-common.css、assets/wc/icon-demo-data.js:示例页的事件桥、公共主题样式与 Icon 演示数据。
  • assets/wc/WC_HANDOFF.md:改造与构建交接文档(背景、构建链、已知边界)。

资源加载顺序(不可调整)

每个页面按以下顺序加载后,<smart-*> 标签即可用:

<script src="./wc-dist/builtin-components/next.js"></script>
<script src="./wc-dist/runtime/index.js"></script>
<script src="./wc-dist/smart-ui-wc.js"></script>
<script src="./demo-runtime.js"></script>
<script src="./remix-icons.js"></script>
<link rel="stylesheet" href="./smart-common.css">

注意:smart-<name>.md 开头「Load smart-icon.js …」的措辞是早期独立组件写法,已过时。当前默认加载方式是上面的合包;.md 的价值在于其属性 / 事件 API 表,据此使用即可,不要引用已废弃的独立 smart-*.js。

唯一例外是 Slider:smart-slider 用独立文件 assets/wc/slider.js(不走合包),详见下方 特例:Slider 滑块。

图标:SmartUI 字体图标 vs RemixIcon 桥接

页面里要放图标有两条路,别混用:

  • SmartUI 自带字体图标:用 <smart-icon name="more">、或组件的 *-icon 属性(如 NavBar right-icon="more"、left-icon)。name 只认 SmartUI 图标集里的字形名(如 more、house),也可传图片 URL。
    • 坑:传了不存在的字形名会静默渲染成 0×0 空图标(页面上啥也没有,不报错)。例如 right-icon="add"——add 不是 SmartUI 字形名,图标框 0×0。别凭猜写字形名;拿不准就用下面的 RemixIcon(slot + data-remix),或先在 smart-icon-example.html 确认该名存在。
  • RemixIcon(推荐,覆盖全、离线):用 <smart-icon data-remix="settings-3-line"> + 加载 assets/wc/remix-icons.js,桥接会把 RemixIcon 的 SVG path 写进该 smart-icon 的 name。高频坑:
    • data-remix 的值是 RemixIcon 名去掉 ri- 前缀——用 settings-3-line,不是 ri-settings-3-line(带前缀查不到、渲染空)。字典 3227 个图标,key 形如 settings-3-line / settings-3-fill。
    • 组件的 *-icon 属性只认 SmartUI 字形名,不认 RemixIcon:right-icon="ri-settings-3-line" / right-icon="settings-3-line" 都渲染不出来。要在组件的图标位放 RemixIcon,必须走具名 slot + <smart-icon data-remix>,例如 NavBar:
      <smart-nav-bar title="标题" background="transparent">
        <smart-icon slot="right" data-remix="settings-3-line" size="24px" color="#fff" style="margin-right:16px;--icon-color:#fff"></smart-icon>
      </smart-nav-bar>
      
    • slot 内容必须写进静态 HTML:具名 slot 投影只在组件首次渲染时发生,渲染后再用 JS appendChild 一个 slot="right" 的节点不会被投影进去(会掉到普通文档流、位置错乱)。
    • smart-icon 颜色必须显式设置,否则默认发黑(高频坑):smart-icon(含 data-remix 图标)是 CSS mask 上色——内部 .__smart-icon__svg 的规则是 background: var(--icon-color, var(--app-B4-N2, rgba(0,0,0,.7))),即颜色由 --icon-color 变量决定,默认 @B4-N2(≈黑)。
      • 不设就发黑,且不跟随文字色:给容器/父级设了文字 color(如白底徽标 color:var(--app-M1)、深色 Hero 白字),图标不会跟着变色。CSS color / 继承 / inline style="color:#fff" 对 mask 图标统统无效(color 不在上色链里)。徽标里图标发黑、深色背景图标看不见,基本都是这个原因。
      • 两种正确设法:① 给 smart-icon 设 color 属性(prop):<smart-icon color="#fff" …>;② 设 --icon-color CSS 变量——放在图标本身或任一祖先容器上(批量最省事):
        .album-card__ai-badge { color: var(--app-M1); --icon-color: var(--app-M1); } /* 文字 + 图标同色 */
        .panel-hero__eyebrow  { color: #fff;          --icon-color: #fff;          } /* 深色 Hero 上白图标 */
        
      • 记忆点:凡是给文字设了 color 又带 smart-icon 的容器,同时设一份 --icon-color(两者不联动);组件的 *-icon-color 变量(如 --nav-bar-icon-color)只管组件内建图标,管不到 slot 里的 smart-icon。
    • data-remix 的 key 必须是有效 RemixIcon 名,写错会静默不渲染(表现为"只剩容器底色的方块 / 图标缺失",不报错)。例如 ai-generate-fill 不存在、正确是 ai-generate。拿不准去 smart-icon-example.html 或字典核对,别凭感觉拼 -fill/-line。
    • smart-button 放 RemixIcon:button 没有 icon slot,icon 属性只认 SmartUI 字形名(传 remix 名会渲染不出)→ 把 <smart-icon data-remix="…"> 放进按钮默认 slot(和文字并列),并设 --icon-color。
  • 图标紧跟文字要留间距(≈4px),别贴死:smart-icon / <i> 默认没有右间距,图标右边紧跟文字时会挨在一起。按承载方式补:
    • 内联组合(徽标、眉标、按钮内「图标+文字」)→ 容器设 gap:4px(或图标 margin-right:4px)。
    • Cell 的 slot="icon" → 默认贴死标题(0px),用 smart-cell [slot="icon"] { margin-right: 4px; }(间距值按设计调,列表常用 8~12px,紧凑徽标 4px)。
    • 只对"图标右侧有文字"的补;箭头类(文字在左、图标在右,如「全部 ›」)不需要。

使用约定

  • 标签名:kebab-case,如 <smart-button>、<smart-nav-bar>。
  • 属性:kebab-case attribute(如 left-text、is-link)。布尔与字符串可直接写 attribute。
  • 复杂值(对象 / 数组 / 函数):attribute 无法承载,必须用 JS property 赋值,如 el.options = [...];property 名为 camelCase。
  • 事件:组件通过 CustomEvent 派发,event.detail 携带数据。既可用标准 el.addEventListener('finish', e => e.detail),示例页也用 bind:finish="handler" 由 demo-runtime.js 桥接。
  • 受控组件必须写回值(高频坑:「点了没反应」):smart-switch / smart-checkbox / smart-radio / smart-slider / smart-stepper / smart-field 等表单类组件是受控的——点击 / 输入只派发 change(或 input) 事件上报新值,组件不会自更新,渲染态始终跟着传入的值走。示例页能动,是因为 data-bind-checked / data-bind-value + bind:change 由 demo-runtime.js 的 __set 把新值写回。脱离该数据绑定运行时(如手写静态 HTML)时,必须自己监听 change 把新值写回,否则「点不动」。写回要改能被组件 observe 的载体:smart-switch 观察的是 checked attribute(setAttribute('checked','true') / removeAttribute('checked') 生效;直接赋 .checked property 不可靠)。示例:
    document.querySelectorAll('smart-switch').forEach(sw => {
      sw.addEventListener('change', e => {
        const d = e.detail; const v = (d && typeof d === 'object' && 'value' in d) ? d.value : d;
        v ? sw.setAttribute('checked','true') : sw.removeAttribute('checked');
      });
    });
    
    Ray 小程序里同理:用 state 承接 onChange 的新值并回传给组件的受控 prop(checked / value),不要指望组件自己保持状态。
    • 「点了没反应」的另一大常见原因:脚本报错中断,写回处理器根本没绑上。排查时先看 console:若初始化脚本里有一处 document.getElementById(x) 取到 null 又直接 .addEventListener(例如按钮只标了 data-od-id="x" 而没有真实 id="x"),整个 IIFE 会抛错中断,它之后的 switch / slider 等所有绑定都不会执行——症状看着是"开关点不动",真因却在上游。所以:① 事件绑定前判空或确保元素带真实 id(data-od-id 是标注属性,getElementById 取不到);② 修 switch 前先确认 console 无 Cannot read properties of null (reading 'addEventListener') 这类中断错误。
  • 样式:组件默认 display: block;公共主题变量与工具类在 smart-common.css,编译后工具类带作用域前缀,故公共样式已在该 CSS 中以属性选择器兜底,引入即可。

弹层宽度:把 fixed 层锁进 375px 手机外框 {#viewport-width}

症状:桌面浏览器里做 375px 宽的手机原型,ActionSheet / Popup / BottomSheet / Picker 弹出来后横跨整个浏览器窗口,遮罩也黑掉整屏。原因是这些组件是 position: fixed,包含块是浏览器视口,跟 375px 的外框 div 没关系(外框没有 transform / filter,不会形成新的包含块)。

已默认修好:smart-common.css 里写死了 --wc-viewport-width: min(375px, 100%),引入这份公共 CSS 就生效,页面不用写任何东西,也不用改组件、重新构建 wc。桌面浏览器上封顶 375px 并水平居中;窄屏 / 真机(< 375px)自动退回 100% 满宽,不会出现左右留白。

覆盖范围:ActionSheet(保留官方左右各 16px 内缩 → 桌面上 343px)、遮罩 Overlay、上/下方向的 Popup / BottomSheet / Picker / DatetimePicker / Cascader,以及 TabBar / GoodsAction / fixed NavBar / Sticky / DropdownItem 等常驻 fixed 层。

要调整就覆盖变量(在弹层元素上求值,写 :root / body / 任一祖先容器都行,推荐 :root——弹层常被挂在手机外框 div 之外,写在外框上会漏掉):

:root { --wc-viewport-width: 414px; }  /* 换机型宽度 */
:root { --wc-viewport-width: 100%; }   /* 退回满宽(真机 H5、全屏页) */
:root { --wc-viewport-left: 0; }       /* 手机外框不水平居中时改锚点 */
  • ActionSheet 的 left / width 在组件 CSS 里带 !important,页面写 smart-action-sheet { width: 343px } 无效,只能走官方变量 --action-sheet-left / --action-sheet-width(公共 CSS 已经在做这件事)。要单独调 ActionSheet 宽度也用这两个变量,别去改 --wc-viewport-width。
  • 居中类弹层(Dialog、Toast)本来就是 left:50% + translate(-50%)、宽度固定,不受影响,无需处理。
  • 改这段 CSS 时别在那个说明注释块里再嵌 /* … */:CSS 注释不能嵌套,内层结束符会提前闭合外层注释,把注释里的示例代码变成真规则(:root { --wc-viewport-width: 100% } 就这么被误当成生效规则,导致 375 完全不起作用)。

内置组件默认样式覆盖(高频坑){#builtin-style}

内置组件都带一套默认 token / inset / padding / 颜色变量。做样式还原或深色背景适配时,先排查并显式覆盖官方 CSS 变量,不要靠外层容器做反向补偿,也不要手写 width / background / border-radius 去「重画」组件本已提供的外观。判断偏差前,先查 references/default-styles.md(内置默认 token 速查 + 高风险清单,权威源 references/smart-ui-default-tokens.less)核对默认值(字号、行高、min-height、默认 padding / inset、图标尺寸、文本截断策略等),别把默认值带来的偏差误判成业务样式问题。下面三类最常踩,是速查表里高风险清单的展开:

1. CellGroup 的 inset 卡片外观 —— 用官方 inset 属性 + 变量,别手写卡片样式

  • 想要「圆角卡片式」的 CellGroup,给 <smart-cell-group> 加 inset 属性即可:官方会补上 border-radius:16px + overflow:hidden + 卡片背景(--cell-background-color / --app-B6)。不必再手写 width / background / border-radius / overflow 反向补偿。
  • 默认 margin 坑:.smart-cell-group--inset 的实际 CSS 是 margin: var(--cell-group-inset-padding, 0 16px) —— 变量名叫 padding,控制的却是 margin,默认 0 16px 会让卡片比外层容器再窄 32px。当页面内容容器已自带 padding:16px 时会产生双重缩进,卡片比同页其它卡窄一圈、左右起始线对不齐。
  • 修复:在 CellGroup 的祖先容器(如 .content / .page)上设 --cell-group-inset-padding: 0;,CSS 变量向下级联覆盖,inset 只保留圆角 / overflow,宽度自动与其它卡对齐。相关默认变量:--cell-group-inset-padding(inset margin,默认 0 16px)、--cell-group-inset-border-radius(默认 16px)、--cell-background-color / --cell-group-background-color(卡片底色)。
  • Ray 小程序侧同理,但 CSS Modules 的 .module.less 不能用 :global {} 块(Ray 构建报 "Ambiguous CSS module class not supported"),把变量声明放在业务类名(如 .page)上即可。

2. NavBar 内部文字 / 图标颜色 —— 只能靠官方 CSS 变量覆盖,color 不穿透

  • NavBar 内部文字、图标颜色各由独立 CSS 变量控制,直接在 customStyle / 元素上写 color:#fff 无法穿透到内部元素。深色 Hero / 渐变背景上放 NavBar 时,默认深色文字会不可见,必须逐个用官方变量改白。
  • 常用变量:--nav-bar-background-color(背景,注意不是 --nav-bar-bg)、--nav-bar-title-text-color(标题)、--nav-bar-home-text-color(leftTextType="home" 文字)、--nav-bar-text-color(通用文字)、--nav-bar-right-text-color(右侧文字)、--nav-bar-icon-color(图标)、--nav-bar-arrow-color(返回箭头)。
  • WC 里在 NavBar 的容器上声明这些变量即可级联生效;Ray 小程序侧用 customClass(不是 className)挂载覆盖类。

3. NavBar 标题 —— 「居中 title」与「home 左对齐标题」二选一,别并存

  • NavBar 有两种放标题的方式,同一个 NavBar 只用一种:
    • 居中 title:title="AI 智能相框"(默认 17px/600,水平居中)。适合左右两侧都放操作/图标的常规导航。
    • home 左对齐标题:leftText="AI 智能相框" leftTextType="home"(默认 --nav-bar-home-font-size:22px / weight 600 大字号,左对齐)。这是涂鸦面板首页常见写法——leftText 直接就是页面标题,官方参考 <NavBar leftText="Home" leftTextType="home" onClickLeftText={...} />。此时不要再设中间 title,也常不需要右侧图标。
  • 坑:两者并存会互相挤。leftTextType="home" 的左区会撑到 --nav-bar-home-max-width(默认 calc(100% - 98px - 16px) ≈ 261px),若同时设了中间 title,title 会被挤到只剩几十 px,而 title 是 overflow:hidden; white-space:nowrap,于是截断成「AI ...」并偏右。
    • 源码级原因(packages/nav-bar/index.less):.smart-nav-bar__left--home { width:100%; max-width: var(--nav-bar-home-max-width) }——home 左区是 width:100%(吃满)+ max-width 261px,而这条规则在 less 里排在 --min(width:40px) 之后、同优先级 → 覆盖它。所以 sideWidth="min" 对 home 类型左区完全无效,左区照样占 261px。
  • 处理,按"要几个元素"选:
    • 只要一个标题 → 二选一:居中 title(不设 home),或 home 左标题(leftText+leftTextType="home",不设 title)。短标题在 261px home 区内完整不截断。
    • 要 小左文字 + 居中 title + 右图标 三段式(如 我的 + AI 相册 + +)→ 不要用 leftTextType="home"(它会吃满左区)。用普通 leftText(17px,走 sideWidth),并把 sideWidth 给到 mid(80px)——min(40px) 减去 16px padding 只剩 24px,2 个汉字的 我的 会被截断;mid 让左右都 80px、对称,我的 放得下、title 精确居中、右图标不受影响。
    • 确需 home 大标题 + 居中 title 并存 → 才收窄 --nav-bar-home-max-width(如 72~80px)折中,但 title 会略偏右。
  • 深色 Hero 上:home 标题色用 --nav-bar-home-text-color,居中 title 色用 --nav-bar-title-text-color(见坑 2,color 不穿透)。
  • 排查手法:截图看着"标题被截断/偏移"时,别当作字号问题,先量 __title 元素的 getBoundingClientRect().width 与 scrollWidth——scrollWidth > clientWidth 即被压缩截断,再回头看是不是被 __left(尤其 home 类型)占了宽度。
  • 一级 / 二级导航约定(对应上面两种标题方式,见 assets/wc/smart-nav-bar-example.html「首页」与「二级页面」示例):
    • 一级导航(首页 / 顶层页):leftText="页面名" leftTextType="home"(左对齐大标题)+ 通常 background 融入 Hero,不要返回箭头、不要中间 title。这是"我在首页"的语义。
    • 二级导航(子页 / 详情页):leftArrow(返回箭头)+ 居中 title,右侧按需 rightText / rightIcon / slot smart-icon。这是"可返回上一级"的语义。
    • 二级页的 sideWidth 选择(决定两侧留给箭头/文字/图标的宽度,坑:选窄了右侧会截断):min(40px) 适合长标题+右侧仅单图标;mid(80px,默认) 适合标题 + 右侧文字/图标的常见情况;max(105px) 适合短标题+两侧内容较多。例:title="相册管理" + rightText="管理" 用 min 会把「管理」截成「管.」,改 mid 才放得下。

4. Cell 的 slot="icon" 自定义图标 —— 与标题无默认间距(紧贴),且组件无相关属性/变量

  • smart-cell 只在用 icon 属性(SmartUI 字形名 / 图片 URL)时,才把图标包进带右间距的 __left-icon-wrap。用 slot="icon" 传自定义图标(灰底方块、封面图、<i class="ri-..."> 等)时是裸 slot、直接 flex 子元素、margin-right:0,于是图标紧贴标题(实测间隙 0px)。
  • 组件没有暴露控制 slot 图标间距的 prop 或 CSS 变量(--cell-left-icon-margin-right 之类在当前版本不存在),改组件源码需重编译 wc,一般不划算。
  • 页面侧修复(推荐,不碰组件):给 slot 图标自身加右间距即可,一条选择器覆盖全页:
    smart-cell [slot="icon"] { margin-right: 12px; }
    
    (WC 是 light DOM,slot 元素渲染后仍带 slot="icon" 属性,故 [slot="icon"] 选择器命中。)
  • 对照:用 icon 属性的图标本就有 4px 间距;用 slot 才需要手动补。

5. Search —— background 属性染的是外层根(易变灰盒子),且自带左右 padding

  • 两层背景别搞混:smart-search 有外层根 .smart-search(background 属性 → 根的 inline background,默认 --search-background-color=B3 白)和内层输入胶囊 .smart-search__content(--search-body-background-color,默认 B4-N9)。想染的"搜索框"其实是内层胶囊。
    • 坑:给 background="var(--app-B6-N9)" 会把整个外层根染成灰色大圆角块,里面再套一个输入胶囊 → 双层灰、又重又怪。
    • 正确:要染输入胶囊用 --search-body-background-color;外层根想融入页面就 background="transparent"。例:<smart-search background="transparent" style="--search-body-background-color: var(--app-B6-N9)">。
  • 自带左右 16px 内边距(源码 @search-padding: 12px 16px):外层容器别再补左右 padding,否则输入胶囊缩进 32px、比同页卡片(16px)更靠里对不齐。容器只留竖向间距(如 .search-wrap { padding: 8px 0 })。

通用心法:先查官方变量 → 覆盖归零 / 改色 → 再判断是否还需外层留白。Collapse / Cell / NavBar / Search 等已自带 header / cell / inset / 左右 padding 的组件,外层包裹容器默认不要再补一层同方向 padding,避免双重内边距。

特例:Slider 滑块(slider.js 独立实现)

smart-slider 有两套互不相同的实现,按标签属性风格区分,不要混用:

  • ty-slider(推荐、功能全):来自 @ray-js/components-ty-slider 的独立 WC,文件是 assets/wc/slider.js,使用 Shadow DOM,属性为 kebab-case(instance-id、track-style、bar-style、is-show-ticks、step-style、parcel、is-vertical 等)。它不走 wc-dist 合包,页面只需:

    <script src="./slider.js"></script>
    <link rel="stylesheet" href="./smart-common.css">
    

    参考 assets/wc/smart-slider-example.html(自带内联 demo runtime)与 assets/wc/smart-slider.md。因内容在 shadow root,取内部结构须走 el.shadowRoot。

  • normal-slider(合包版):assets/wc/smart-normal-slider-example.html,来自 packages/normal-slider,走 wc-dist 合包,属性为 camelCase property(trackStyle、showSteps、hideThumbButton)。

  • range-slider(双滑块):assets/wc/smart-range-slider-example.html,来自 packages/slider,标签 smart-range-slider,走合包。

在纯浏览器场景做「滑块」需求时,默认用 ty-slider(slider.js);仅在需要与小程序 packages/normal-slider / packages/slider 行为完全一致时才用合包版。

查阅流程(WC 场景)

  1. 从 assets/wc/home.html 或组件中文名定位英文名 smart-<name>。
  2. 读 assets/wc/smart-<name>.md 获取属性 / 事件 API(按需增量,勿全量扫)。
  3. 读 assets/wc/smart-<name>-example.html 获取可运行的组合与事件绑定写法。
  4. 输出时同样区分「文档确认」与「经验推断」,禁止虚构 props / 事件。

注意事项 {#tip}

  • 禁止使用小写 HTML 标签(如 div、span)。
  • 禁止混入 wx.*、my.* 等非 Ray 业务 API。
  • 禁止虚构 smart-ui 的 props、事件或版本能力。
  • 禁止在未通过 _meta.json 定位前一次性加载大量文档。
  • 禁止在业务代码中硬编码中文文案。

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/developer.tuya.com/smart-ui-skill">View smart-ui-skill on skillZs</a>