@sj-distributor/react-iconfont-cli 2.4.2 → 2.6.0

package/README.md

@@ -155,6 +155,68 @@ export const App = () => {
 </div>
 ```
 
+### 点击交互
+
+不要直接把 SVG 图标作为交互控件。SVG 本身不是原生按钮，直接使用时还需要自行实现焦点、键盘操作、控件角色和可访问名称。
+
+汇总 `IconFont` 组件检测到 `onClick` 后，会自动渲染一个原生 `button`，并将内部 SVG 标记为装饰元素；没有 `onClick` 时仍然只渲染 SVG：
+
+```tsx
+const handleIconClick = () => {
+  console.log("icon clicked");
+};
+
+<IconFont
+  name="alipay"
+  aria-label="打开支付宝"
+  onClick={handleIconClick}
+  buttonProps={{
+    className: "icon-button",
+    disabled: false,
+  }}
+/>;
+```
+
+`buttonProps` 用于设置外层按钮的属性；`className`、`style` 等普通图标属性仍应用到内部 SVG。按钮仅默认设置 `type="button"`，不附带布局、尺寸、颜色或重置样式，调用方可以使用普通 CSS、CSS Modules 或 Tailwind CSS 自行控制。原生按钮已经支持 Enter/Space 键盘操作，因此不需要额外添加 `onKeyDown`。
+
+交互模式下，顶层的 `aria-*`、`role` 和 `tabIndex` 会自动应用到外层按钮，不会留在已隐藏的 SVG 上。除 `aria-label` 和 `onClick` 外，也可以通过 `buttonProps` 设置按钮属性；同名属性以 `buttonProps` 为准。
+
+调用方自定义按钮样式时，应保留清晰的键盘焦点状态，并根据适用的 WCAG 等级确保足够的点击区域和间距。
+
+按需引入的单图标组件始终只渲染 SVG。如需交互，请由调用方显式包裹按钮：
+
+```tsx
+<button type="button" onClick={handleIconClick} aria-label="打开支付宝">
+  <IconAlipay aria-hidden="true" />
+</button>
+```
+
+## 无障碍支持（WCAG）
+
+无障碍属性添加在最终生成的单图标 SVG 上。重新运行生成命令后，现有调用无需修改即可获得默认的可访问名称。
+
+将生成类似下面的 SVG：
+
+```html
+<svg role="img" aria-label="alipay" focusable="false">...</svg>
+```
+
+默认的 `aria-label` 是本包提供的兜底值：它根据去除前缀后的图标名生成，并将连字符、下划线和驼峰命名转换为空格。例如 `arrow-left` 会生成 `aria-label="arrow left"`。
+
+本包无法判断图标在具体页面中的含义和语言。调用方应根据实际语境覆盖默认标签：
+
+```tsx
+<IconFont name="alipay" aria-label="支付宝" />
+```
+
+如果图标只是装饰，或者所在按钮、链接已经有可访问名称，可以显式隐藏图标，避免读屏软件重复朗读：
+
+```tsx
+<button type="button" aria-label="关闭">
+  <IconFont name="close" aria-hidden="true" />
+</button>
+```
+
 ## 更新图标
 
 当 iconfont 项目图标有变更时，更新 `iconfont.json` 中的 `symbol_url` 后重新生成：

package/libs/generateComponent.js

@@ -36,9 +36,11 @@ var generateComponent = function (data, config) {
         names.push(iconIdAfterTrim);
         cases += "".concat((0, whitespace_1.whitespace)(4), "case '").concat(iconIdAfterTrim, "':\n");
         imports.push(componentName);
-        cases += "".concat((0, whitespace_1.whitespace)(6), "return <").concat(componentName, " {...rest} />;\n");
+        cases += "".concat((0, whitespace_1.whitespace)(6), "icon = <").concat(componentName, " {...iconProps} />;\n");
+        cases += "".concat((0, whitespace_1.whitespace)(6), "break;\n");
         singleFile = (0, getTemplate_1.getTemplate)("SingleIcon" + jsxExtension);
         singleFile = (0, replace_1.replaceSize)(singleFile, config.default_icon_size);
+        singleFile = (0, replace_1.replaceAriaLabel)(singleFile, getAccessibleLabel(iconIdAfterTrim));
         if (jsxExtension === ".tsx") {
             singleFile = (0, replace_1.replaceReactName)(singleFile, config.can_import_react);
         }
@@ -74,7 +76,7 @@ var generateComponent = function (data, config) {
 exports.generateComponent = generateComponent;
 var generateCase = function (data, baseIdent) {
     var e_1, _a;
-    var template = "\n".concat((0, whitespace_1.whitespace)(baseIdent), "<svg viewBox=\"").concat(data.$.viewBox, "\" width={size} height={size} style={style} {...rest}>\n");
+    var template = "\n".concat((0, whitespace_1.whitespace)(baseIdent), "<svg viewBox=\"").concat(data.$.viewBox, "\" width={size} height={size} style={style} role={role} aria-label={accessibilityLabel} focusable=\"false\" {...rest}>\n");
     // Determine the primary fill color (first path's fill)
     // to distinguish primary paths from detail paths at runtime.
     var primaryFill = getPrimaryFill(data);
@@ -115,6 +117,14 @@ var generateCase = function (data, baseIdent) {
     template += "".concat((0, whitespace_1.whitespace)(baseIdent), "</svg>\n");
     return template;
 };
+var getAccessibleLabel = function (iconName) {
+    var label = iconName
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/[-_.=+#@!~*]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return label || iconName;
+};
 var getPrimaryFill = function (data) {
     var e_2, _a;
     var _b;

package/libs/replace.d.ts

@@ -1,4 +1,5 @@
 export declare const replaceSize: (content: string, size: number) => string;
+export declare const replaceAriaLabel: (content: string, label: string) => string;
 export declare const replaceCases: (content: string, cases: string) => string;
 export declare const replaceNames: (content: string, names: string[]) => string;
 export declare const replaceNamesArray: (content: string, names: string[]) => string;

package/libs/replace.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.replaceExports = exports.replaceSizeUnit = exports.replaceImports = exports.replaceSingleIconContent = exports.replaceReactName = exports.replaceComponentName = exports.replaceNamesArray = exports.replaceNames = exports.replaceCases = exports.replaceSize = void 0;
+exports.replaceExports = exports.replaceSizeUnit = exports.replaceImports = exports.replaceSingleIconContent = exports.replaceReactName = exports.replaceComponentName = exports.replaceNamesArray = exports.replaceNames = exports.replaceCases = exports.replaceAriaLabel = exports.replaceSize = void 0;
 var replaceSize = function (content, size) {
     return content.replace(/#size#/g, String(size));
 };
 exports.replaceSize = replaceSize;
+var replaceAriaLabel = function (content, label) {
+    return content.replace(/#ariaLabel#/g, JSON.stringify(label));
+};
+exports.replaceAriaLabel = replaceAriaLabel;
 var replaceCases = function (content, cases) {
     return content.replace(/#cases#/g, cases);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sj-distributor/react-iconfont-cli",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "main": "index.js",
   "keywords": [
     "iconfont",

package/templates/Icon.d.ts.template

@@ -1,12 +1,16 @@
 /* eslint-disable */
 
-import { SVGAttributes, FunctionComponent } from 'react';
+import { ButtonHTMLAttributes, FunctionComponent, MouseEventHandler, SVGAttributes } from 'react';
 #exports#
 
-interface Props extends Omit<SVGAttributes<SVGElement>, 'color'> {
+type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label' | 'children' | 'dangerouslySetInnerHTML' | 'onClick'>;
+
+interface Props extends Omit<SVGAttributes<SVGElement>, 'color' | 'onClick'> {
   name: '#names#';
   size?: number;
   color?: string | string[];
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  buttonProps?: ButtonProps;
 }
 
 declare const IconFont: FunctionComponent<Props>;

package/templates/Icon.js.template

@@ -4,12 +4,74 @@ import React from 'react';
 #imports#
 #exports#
 
-const IconFont = ({ name, ...rest }) => {
+const splitInteractiveProps = (props) => {
+  const buttonA11yProps = {};
+  const iconProps = {};
+
+  Object.keys(props).forEach((propName) => {
+    if (
+      propName.indexOf('aria-') === 0 ||
+      propName === 'role' ||
+      propName === 'tabIndex'
+    ) {
+      buttonA11yProps[propName] = props[propName];
+    } else {
+      iconProps[propName] = props[propName];
+    }
+  });
+
+  return { buttonA11yProps, iconProps };
+};
+
+const getAccessibleLabel = (iconName) => {
+  const label = iconName
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/[-_.=+#@!~*]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return label || iconName;
+};
+
+const IconFont = ({
+  name,
+  onClick,
+  buttonProps = {},
+  'aria-label': ariaLabel,
+  ...rest
+}) => {
+  const interactiveProps = splitInteractiveProps(rest);
+  const iconProps = onClick
+    ? { ...interactiveProps.iconProps, 'aria-hidden': true }
+    : { ...rest, 'aria-label': ariaLabel };
+  let icon = null;
+
   switch (name) {
 #cases#
   }
 
-  return null;
+  if (!icon || !onClick) {
+    return icon;
+  }
+
+  const { type = 'button', ...restButtonProps } = buttonProps;
+  delete restButtonProps.dangerouslySetInnerHTML;
+  const accessibilityLabel =
+    typeof ariaLabel === 'string' && ariaLabel.trim()
+      ? ariaLabel.trim()
+      : getAccessibleLabel(name);
+
+  return (
+    <button
+      {...interactiveProps.buttonA11yProps}
+      {...restButtonProps}
+      type={type}
+      aria-label={accessibilityLabel}
+      onClick={onClick}
+    >
+      {icon}
+    </button>
+  );
 };
 
 export default IconFont;

package/templates/Icon.tsx.template

@@ -1,24 +1,98 @@
 /* tslint:disable */
 /* eslint-disable */
 
-import #reactName#{ SVGAttributes, FunctionComponent } from 'react';
+import #reactName#{ ButtonHTMLAttributes, FunctionComponent, MouseEventHandler, ReactElement, SVGAttributes } from 'react';
 #imports#
 #exports#
 
 export type IconNames = '#names#';
 
-interface Props extends Omit<SVGAttributes<SVGElement>, 'color'> {
-  name: IconNames;
+type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label' | 'children' | 'dangerouslySetInnerHTML' | 'onClick'>;
+
+type IconProps = Omit<SVGAttributes<SVGElement>, 'color' | 'onClick'> & {
   size?: number;
   color?: string | string[];
+};
+
+interface Props extends IconProps {
+  name: IconNames;
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  buttonProps?: ButtonProps;
 }
 
-const IconFont: FunctionComponent<Props> = ({ name, ...rest }) => {
+const splitInteractiveProps = (props: IconProps) => {
+  const source = props as Record<string, unknown>;
+  const buttonA11yProps: Record<string, unknown> = {};
+  const iconProps: Record<string, unknown> = {};
+
+  Object.keys(source).forEach((propName) => {
+    if (
+      propName.indexOf('aria-') === 0 ||
+      propName === 'role' ||
+      propName === 'tabIndex'
+    ) {
+      buttonA11yProps[propName] = source[propName];
+    } else {
+      iconProps[propName] = source[propName];
+    }
+  });
+
+  return {
+    buttonA11yProps: buttonA11yProps as ButtonHTMLAttributes<HTMLButtonElement>,
+    iconProps: iconProps as IconProps,
+  };
+};
+
+const getAccessibleLabel = (iconName: string): string => {
+  const label = iconName
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+    .replace(/[-_.=+#@!~*]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return label || iconName;
+};
+
+const IconFont: FunctionComponent<Props> = ({
+  name,
+  onClick,
+  buttonProps = {},
+  'aria-label': ariaLabel,
+  ...rest
+}) => {
+  const interactiveProps = splitInteractiveProps(rest);
+  const iconProps = onClick
+    ? { ...interactiveProps.iconProps, 'aria-hidden': true }
+    : { ...rest, 'aria-label': ariaLabel };
+  let icon: ReactElement | null = null;
+
   switch (name) {
 #cases#
   }
 
-  return null;
+  if (!icon || !onClick) {
+    return icon;
+  }
+
+  const { type = 'button', ...restButtonProps } = buttonProps;
+  const safeButtonProps = restButtonProps as ButtonHTMLAttributes<HTMLButtonElement>;
+  delete safeButtonProps.dangerouslySetInnerHTML;
+  const accessibilityLabel =
+    typeof ariaLabel === 'string' && ariaLabel.trim()
+      ? ariaLabel.trim()
+      : getAccessibleLabel(name);
+
+  return (
+    <button
+      {...interactiveProps.buttonA11yProps}
+      {...safeButtonProps}
+      type={type}
+      aria-label={accessibilityLabel}
+      onClick={onClick}
+    >
+      {icon}
+    </button>
+  );
 };
 
 export default IconFont;

package/templates/SingleIcon.js.template

@@ -7,8 +7,16 @@ const DEFAULT_STYLE = {
   display: 'block',
 };
 
-const #componentName# = ({ size = #size#, color, style: _style, ...rest }) => {
+const #componentName# = ({
+  size = #size#,
+  color,
+  style: _style,
+  role = 'img',
+  'aria-label': ariaLabel,
+  ...rest
+}) => {
   const style = _style ? { ...DEFAULT_STYLE, ..._style } : DEFAULT_STYLE;
+  const accessibilityLabel = typeof ariaLabel === 'string' && ariaLabel.trim() ? ariaLabel.trim() : #ariaLabel#;
 
   return (#iconContent#  );
 };

package/templates/SingleIcon.tsx.template

@@ -13,8 +13,16 @@ const DEFAULT_STYLE: CSSProperties = {
   display: 'block',
 };
 
-const #componentName#: FunctionComponent<Props> = ({ size = #size#, color, style: _style, ...rest }) => {
+const #componentName#: FunctionComponent<Props> = ({
+  size = #size#,
+  color,
+  style: _style,
+  role = 'img',
+  'aria-label': ariaLabel,
+  ...rest
+}) => {
   const style = _style ? { ...DEFAULT_STYLE, ..._style } : DEFAULT_STYLE;
+  const accessibilityLabel = ariaLabel && ariaLabel.trim() ? ariaLabel.trim() : #ariaLabel#;
 
   return (#iconContent#  );
 };