IconProvider 使用手册

v1.0.0 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

为应用或局部区域统一替换 SnowUI 内置功能图标，未配置的图标继续使用组件默认样式。

使用选择

用于为后代图标提供共享配置。它不是可见图标；实际图形仍由 Icon 或资源组件渲染。

icons 提供名称映射，resolver 提供按名称解析入口。
只影响后代图标解析，原样渲染 children；它不生成可见图形或布局外壳。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { ColorSchemeButton, CopyButton, IconProvider } from '@snowui-design-system/components';	import { createSnowUIComponentIconResolver } from '@snowui-design-system/resource-svelte';	const resolver = createSnowUIComponentIconResolver({ collection: 'phosphor', fallbackCollections: ['snowui'] });</script> <IconProvider resolver={resolver}><div style="display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: var(--gap-4) var(--gap-3); max-width: 100%;">    <CopyButton text="pnpm add @snowui-design-system/components">Copy install command</CopyButton>    <ColorSchemeButton applyToDocument={false} ariaLabel="Preview theme" /></div></IconProvider>

API

关键字	类型	默认值	描述
icons	`ComponentIconMap`	`{}`	稳定语义名到外部 Svelte 图标组件的映射
resolver	`ComponentIconResolver`	—	按 `{ name, weight }` 解析图标；优先于同层 `icons`
children	`Snippet`	—	原样渲染的子树

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

概览与选择边界

IconProvider 是无视觉 Context Provider。没有 Provider 时，组件使用 Components 包内置的默认功能图标；提供 icons 或 resolver 后，未被组件实例 Snippet / 具名角色明确替换的内置图标会在当前子树统一改用外部图标库。

它不接管调用方显式书写的 <Icon>、资源图标或普通 children。需要替换单个组件实例时，继续使用该组件公开的 Icon Snippet 或具名角色；需要整棵应用切换图标库时使用本组件。

Import

<script lang="ts">    import { IconProvider } from "@snowui-design-system/components";</script>

API

同层解析顺序为 resolver → icons；未命中时继续查询外层 Provider，最后由组件内置默认图标回退。切换 resolver 或 icons Prop 会更新当前子树。外部图标组件接收 size、color、weight、class、data-as 和 ARIA 等标准化渲染参数。

示例

<script lang="ts">    import { IconProvider, CopyButton } from "@snowui-design-system/components";    import { Copy, Check } from "my-icon-library";     const appIcons = { copy: Copy, check: Check };</script> <IconProvider icons={appIcons}>    <CopyButton text="SnowUI" /></IconProvider>

无障碍与组合边界

Provider 不生成 DOM。功能名称、Button 的 aria-label、交互命中区和状态仍由拥有该功能的组件负责；外部图标只替换图形，不接管事件或可访问名称。

IconProvider 样式覆盖

先阅读完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按样式选择与改写顺序使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

本组件源文件没有直接消费已登记的专属 override。组合子组件的样式通过公开 parts 或显式 child 配置；不要凭名称猜测变量。

设计指南 · Token · 组合边界

IconProvider 类型与状态

必填属性：无具名必填属性。

可双向绑定：本组件未声明具名双向绑定属性；状态更新通过公开回调或所属宿主处理。

继承声明：无接口继承。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。