Perfect Corner Dash

English Version

Perfect Corner Dash 是一个基于几何计算的 SVG 虚线生成器，专门用于在圆角矩形等 UI 场景下绘制“完美对齐”的虚线边框。它既可以在浏览器里直接使用，也可以作为 npm 依赖集成到 React、Vue 或任意前端工程中。

功能特点

• 按弧长精确分配虚线，圆角处自然衔接，不出现断裂或堆叠。
• 纯函数 API，默认无副作用，适合 SSR 与客户端渲染。
• 附带 render / attach 辅助方法，可直接插入或覆盖现有 DOM。
• 支持自动尺寸、段落拆分（按边统一 dash 数量）以及首尾半段等高级配置。
• 无额外依赖，可直接通过 CDN 或 npm 获取。

安装

npm / pnpm / yarn

npm install perfect-corner-dash
# 或者
pnpm add perfect-corner-dash
# 或者
yarn add perfect-corner-dash

安装后即可在任何打包工具（Vite、webpack、Next.js 等）里按需引用：

import PerfectDash from "perfect-corner-dash";

const svgMarkup = PerfectDash({
  width: 320,
  height: 200,
  borderRadius: 24,
  dashCount: 6,
});

document.querySelector("#preview").innerHTML = svgMarkup;

React / Vue 等框架同理，只需在组件中调用 PerfectDash 并渲染返回的字符串或节点。

如果希望直接覆盖现有元素，可以使用 attach：

const card = document.querySelector(".card");

const handle = PerfectDash.attach(card, {
  borderRadius: 20,
  strokeWidth: 3,
  dashCount: 8,
  strokeColor: "#ff6b6b",
});

// 后续可更新或销毁
handle.update({ strokeColor: "#2563eb" });
handle.destroy();

封装为组件的示例

import { useEffect, useRef } from "react";
import PerfectDash from "perfect-corner-dash";

export function DashedCard({ children }) {
  const ref = useRef(null);

  useEffect(() => {
    if (!ref.current) return;
    const handle = PerfectDash.attach(ref.current, {
      borderRadius: 24,
      strokeWidth: 4,
      dashCount: 6,
      strokeColor: "#0ea5e9",
    });
    return () => handle.destroy();
  }, []);

  return (
    <div ref={ref} style={{ position: "relative", padding: "24px" }}>
      {children}
    </div>
  );
}

CDN 直接引入

<script src="https://unpkg.com/perfect-corner-dash@latest/dist/index.umd.js"></script>

<div id="preview"></div>
<script>
  const svg = PerfectDash({
    width: 280,
    height: 160,
    borderRadius: 18,
    strokeColor: "#2f3538",
  });
  document.getElementById("preview").innerHTML = svg;
</script>

UMD 版本会在全局对象上暴露 window.PerfectDash，dist/index.min.js 提供压缩版本，适合通过 CDN 发布。

API 概览

type PerfectDashOptions = {
  width?: number | null;
  height?: number | null;
  borderRadius?: number;
  strokeWidth?: number;
  dashCount?: number;
  holeFactor?: number;
  offset?: number;
  splitSegments?: boolean;
  halfExtreme?: boolean;
  unifySegment?: boolean;
  strokeColor?: string;
  strokeLinecap?: "round" | "butt" | "square";
  strokeLinejoin?: "round" | "miter" | "bevel";
};

declare function PerfectDash(options?: PerfectDashOptions): string;

更多详细类型可在 types/index.d.ts 中查看。

辅助方法

• PerfectDash.createSVGString(options)：生成 SVG 字符串。
• PerfectDash.createElement(options)：返回 SVGSVGElement 元素。
• PerfectDash.render(target, options)：在目标容器中渲染 SVG。
• PerfectDash.attach(target, options)：将虚线覆盖层附着到目标元素，同时监听页面尺寸变化。

示例与构建

• 运行 npm install 安装依赖。
• npm run build 生成 dist/ 与 types/ 输出。
• 示例位于 examples/ 目录，可直接使用静态服务器预览。

构建流程会输出 ESM（dist/index.js）、CJS（dist/index.cjs.js）、UMD（dist/index.umd.js、dist/index.min.js）以及类型声明 types/index.d.ts。

许可证

MIT License。