# @canonical/svelte-icons 中文文档

规范地址：https://npmcn.com/package/%40canonical/svelte-icons/

版本：0\.1\.0
npm 元数据更新时间：2026-10-23T10:19:33.917Z
中文译文更新时间：2026-11-09T15:11:17.930Z
软件包许可：LGPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canonical/svelte-icons
原文对照：https://npmcn.com/package/%40canonical/svelte-icons/?lang=original
项目主页：https://github.com/canonical/svelte-icons#readme
源码仓库：https://github.com/canonical/svelte-icons

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：285 kB，383 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：svelte ^5\.0\.0
- 首次发布：2025-11-26T14:24:39.436Z
- 最新版本发布：2026-10-23T10:19:33.572Z
- 近 30 天下载量：2397（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

作为斯维尔特组件的 Canonical 图标

## 安装

```sh
npm install @canonical/svelte-icons
```

也可以使用：`pnpm add @canonical/svelte-icons`、`yarn add @canonical/svelte-icons`、`bun add @canonical/svelte-icons`

## README

# @ canonical/ svelte- icons (英语)

Canonical的设计系统图标被包装为Svelte 5组件. 此库提供来自 [Canonical的Pragma设计系统](https://github.com/canonical/pragma/tree/main/packages/ds-assets) 作为易于使用的斯维尔特组件.

> \[尖叫声\] 这个包裹是实验阶段 在稳定释放之前,可能会发生重大变化。 目前不建议生产使用.

## 安装

```bash
bun add @canonical/svelte-icons
```

## 使用量

### 基本用途

单独导入图标并将其用作组件 :

```html
<script>
  import { HomeIcon, SettingsIcon, UserIcon } from "@canonical/svelte-icons";
</script>

<HomeIcon />
<SettingsIcon class="custom-class" />
<UserIcon />
```

### 样式图标

图标默认继承当前文本的颜色和大小.

```html
<script>
  import { SearchIcon } from "@canonical/svelte-icons";
</script>

<SearchIcon style="color: red; width: 2em; height: 2em;" />
```

### 性能优化

当多次使用同一图标时,可以使用 `IconsOptimizationProvider` 在生成标记中复制 SVG 定义:

```html
<script>
  import { IconsOptimizationProvider, HomeIcon } from "@canonical/svelte-icons";
</script>

<IconsOptimizationProvider>
  <nav>
    <HomeIcon />
    <!-- All instances share the same SVG definition -->
    <HomeIcon />
    <HomeIcon />
  </nav>
</IconsOptimizationProvider>
```

这在多次渲染同一图标时特别有用.

> 看看这个 [节点树大小比较](https://main--693121d8204f530975a41c27.chromatic.com/?path=/story/advanced-iconsoptimizationprovider--node-tree-size-comparison) 故事可以看到DOM的大小差异 优化与非优化渲染.

### 自定义图标

您也可以使用 `IconBase` 组件 :

```html
<script>
  import { IconBase } from "@canonical/svelte-icons";
</script>

<IconBase iconName="my-custom-icon">
  <svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
    <circle cx="8" cy="8" r="6" stroke="black" stroke-width="1" fill="red" />
  </svg>
</IconBase>
```

> \[大 当使用自定义图标时 `IconsOptimizationProvider`数字 :
> 
> -   确保 `iconName` 道具是每个自定义图标独有的以避免相撞,
> -   修改内部的 SVG 内容 `IconBase` 运行时间可能导致出乎意料的行为.
> 
> 看看这个 [反应操场](https://main--693121d8204f530975a41c27.chromatic.com/?path=/story/advanced-iconsoptimizationprovider--reactivity-playground) 故事来学习更多.

## 图标来源

所有 SVG 图标来自 [@ canonical/ ds- 资产](https://github.com/canonical/pragma/tree/main/packages/ds-assets) 包,是Canonical的Pragma设计系统的一部分.

## 发展

```bash
# Install dependencies
bun install

# Build icon components from source
bun run build

# Run Storybook for development
bun run storybook

# Lint, type check and verify metadata.json is up to date
bun run check
```

### 生成图标元数据

`metadata.json` 持有由视觉模型生成的每个图标的搜索标记 从图标及其名称。 每个条目还存储一个散列 图标的 SVG,所以生成器只调用新图标的模型 已更改, 或还没有标记; 所有其他标记都重新使用 。 图标条目 不再存在.

`bun run check` (和CI) 失败时 `metadata.json` 没有同步到 `@canonical/ds-assets`,所以在撞出软件包后运行生成器:

```bash
# Set OPENROUTER_API_KEY in your environment or ignored .env file.
bun run build:metadata
```

生成器接受支持 OpenAI 兼容聊天的任何端点 结业. 模型 **必须支持图像输入**。默认情况下,它使用 打开路透器 `google/gemma-4-26b-a4b-it`数字 :

```bash
# Override the OpenRouter model.
bun run build:metadata --model google/gemini-3.1-flash-lite
```

对于自定义终点,请通过 **API 基础 URL** 和一个明确的模式:

```bash
# Ollama: start the server and download the chosen model beforehand.
bun run build:metadata --base-url http://localhost:11434/v1 --model gemma4:26b

# llama.cpp: start llama-server with your model; use its served model ID.
bun run build:metadata --base-url http://localhost:8080/v1 --model your-served-model-id
```

自定义端点只使用 `METADATA_API_KEY` 供应时,否则无 认证头已发送 .

图标默认一次处理 6; 用 `--concurrency` (或 `-j`),例如. `-j 1` 用于慢本地服务器。 120后请求暂停 秒和重试最多2次,有备份,超时,网络 错误、 速率限制和服务器错误 。 增加慢本地模型的超时 `--timeout <seconds>`的图标 剩余结果被写入,命令退出状态为非零.

每个生成的图标被记录在一条有其标记的单行上. 添加 `--verbose` (或 `-v`)还登录模型对绘图的描述及其含义.

被再用标记实现常态化(小写,去字,填字被去掉). 添加 `--clean` (或 `-c`)重新生成所有图标的标记.

## 常见问题

### @canonical/svelte-icons 是什么？

作为斯维尔特组件的 Canonical 图标

### 如何安装 @canonical/svelte-icons？

在项目目录运行 npm install @canonical/svelte-icons，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @canonical/svelte-icons 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canonical/svelte-icons 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @canonical/svelte-icons 可以商用吗？

@canonical/svelte-icons 使用 LGPL-3\.0 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @canonical/svelte-icons 的下载量有多少？

根据 npm 官方下载统计，@canonical/svelte-icons 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,397 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canonical/svelte-icons 还在维护吗？

最新版本 0\.1\.0 发布于 2026/10/23（17 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2025/11/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。