ala-icon (React Native IconPark)

React Native 版 IconPark 组件库。支持按需导入、主题配置、语义化色板及通用 <Icon name> 入口。

安装

npm install ala-icon react-native-svg
# 或
yarn add ala-icon react-native-svg

react-native-svg 是运行时依赖，请确保已正确安装并在工程中配置。

基本使用

直接按需导入组件：

import { Abdominal } from "ala-icon";

export function Example() {
  return <Abdominal theme="outline" size={24} fill="#333" />;
}

• theme 可选：outline（默认）| filled | two-tone | multi-color
• size：数字或字符串
• fill：字符串或字符串数组（多色时使用）
• 其余可选：strokeWidth | strokeLinecap | strokeLinejoin

IconProvider（主题 / 语义色）

通过 IconProvider 提供全局配置（色板、尺寸、默认主题），所有图标会优先读取 Provider 中的配置：

import { IconProvider, Abdominal } from "ala-icon";

const iconConfig = {
  size: 24,
  theme: "outline",
  colors: {
    outline: { fill: "#1F2937" },
    twoTone: { twoTone: "#0EA5E9" },
  },
};

export function App() {
  return (
    <IconProvider config={iconConfig}>
      <Abdominal />
    </IconProvider>
  );
}

你可以在 config 中覆盖：

• size（默认 24，RN 不支持 em，请使用数字或百分比字符串）、strokeWidth（默认 3）, strokeLinecap, strokeLinejoin, theme
• colors.outline | colors.filled | colors.twoTone | colors.multiColor
• spin：为所有图标开启旋转动画（默认 false，可在 Provider 中全局开启）
• rtl：开启后仅对官方标记为可镜像的图标生效

通用 <Icon name> 入口

如果希望按字符串名称渲染图标，可在 Provider 中注册映射：

import { IconProvider, Icon, Abdominal, Add, AddTextTwo } from "ala-icon";

const registry = { Abdominal, Add, AddTextTwo };

export function Example() {
  return (
    <IconProvider registry={registry}>
      <Icon name="Abdominal" size={28} theme="two-tone" fill={["#111", "#0EA5E9"]} />
    </IconProvider>
  );
}

也可直接传入组件：

<Icon component={Abdominal} size={24} />

查找不到名称时会输出警告并返回 null。

全量入口（对标官方 all）

• 自动生成 IconType / ALL_ICON_KEYS / IconMap，用于类型安全的字符串调用或选择器：

import { Icon, IconType, ALL_ICON_KEYS, IconMap } from "ala-icon";

const name: IconType = "Abdominal";

export function Picker({ type }: { type: IconType | string }) {
  return <Icon name={type} theme="filled" />;
}

• name 字符串会自动转为 PascalCase（支持 add-text 形式），并优先读取 registry，找不到时再回退到内置 IconMap。

RTL / 方向

• 在 IconProvider 中设置 rtl: true 后，只有官方标记为支持镜像的图标会自动左右翻转；未标记的图标保持原样。
• 如需强制某个实例翻转，可在单个图标上传 rtl 覆盖。

语义化主题建议

• 在 Provider 的 config.colors 中填充你项目的主题色（如 primary/surface/error 等），让图标跟随主题切换。
• 可将 config 构造成与应用主题联动的对象，例如基于 Appearance / useColorScheme 或 UI 库（react-native-paper / nativewind）的 tokens。

与 react-native-paper 主题联动示例

import { Provider as PaperProvider, useTheme } from "react-native-paper";
import { IconProvider, Abdominal } from "ala-icon";

const IconWithTheme = () => {
  const { colors } = useTheme();
  return (
    <IconProvider
      config={{
        colors: {
          outline: { fill: colors.onSurface },
          twoTone: { fill: colors.onSurface, twoTone: colors.primary },
        },
        size: 22,
      }}
    >
      <Abdominal theme="two-tone" />
    </IconProvider>
  );
};

export default function App() {
  return (
    <PaperProvider>
      <IconWithTheme />
    </PaperProvider>
  );
}

与 nativewind / tailwind 联动示例

import { IconProvider, Icon, Add } from "ala-icon";
import { useColorScheme } from "react-native";

const registry = { Add };

export function Screen() {
  const scheme = useColorScheme();
  const primary = scheme === "dark" ? "#22d3ee" : "#0ea5e9";
  const text = scheme === "dark" ? "#e5e7eb" : "#111827";

  return (
    <IconProvider
      registry={registry}
      config={{
        colors: { outline: { fill: text }, twoTone: { fill: text, twoTone: primary } },
      }}
    >
      <Icon name="Add" className="text-sky-500" theme="two-tone" size={24} />
    </IconProvider>
  );
}

Tree Shaking / 体积

• 包含 sideEffects:false 且为 ESM 导出，未引用的图标会被生产构建剪裁。
• 使用 <Icon name> 时按需注册 registry 以避免全量打包。
• 如果需要全量列表/元数据，可使用包内 IconMap、ALL_ICON_KEYS 或读取根目录 icons.json。

构建与生成

• 批量生成图标：npm run gen（读取 src/source 下 SVG，生成 src/icons 和 src/index.ts）
• 构建发布产物：npm run build（输出到 dist）
• 同步官方 SVG 源文件：npm run sync:source（默认读取 ../IconPark/source，可用 ICONPARK_SOURCE_DIR 覆盖）

常见问题

• 看不到图标？ 确认 react-native-svg 安装并链接；检查是否传入了覆盖 xml 的空值。
• 颜色不对？ 主题为 two-tone/multi-color 时传入数组或调整 Provider colors；默认 currentColor 会继承文本色。