Link

安装

批量导入

import { Link } from "@cloudflare/kumo";

细粒度导入

import { Link } from "@cloudflare/kumo/components/link";

用法

基础链接

默认的 Link 组件渲染一个带下划线、使用主题色的锚点。

import { Link } from "@cloudflare/kumo";

export default function Example() {
  return (
    <p>
      Read our <Link href="/docs">documentation</Link> for more details.
    </p>
  );
}

外部链接

用 Link.ExternalIcon 子组件标识会在新标签页中打开的链接。

import { Link } from "@cloudflare/kumo";

export default function Example() {
  return (
    <Link
      href="https://cloudflare.com"
      target="_blank"
      rel="noopener noreferrer"
    >
      Visit Cloudflare <Link.ExternalIcon />
    </Link>
  );
}

框架集成（LinkProvider）

如果要在整个应用中接入路由，请在应用根部配置 LinkProvider。 你的包装组件会接收 href，并负责对接你所用路由的 API。 这样工程师可以在任何地方使用 <Link href="...">， 而不必关心路由的内部细节。

import { forwardRef } from "react";
import { LinkProvider } from "@cloudflare/kumo";
import { Link as RouterLink } from "react-router-dom";

// 你的应用包装组件把 href 映射到路由的导航属性，
// 外部 URL 则用普通 <a> 处理
const AppLink = forwardRef(({ href, to, ...rest }, ref) => {
  const destination = href ?? to;
  const isExternal =
    destination?.startsWith("http") &&
    new URL(destination).origin !== window.location.origin;

  if (isExternal) {
    return <a ref={ref} href={destination} {...rest} />;
  }
  return <RouterLink ref={ref} to={destination} {...rest} />;
});

// 在应用根部包裹一次
export function App() {
  return (
    <LinkProvider component={AppLink}>
      {/* 所有 <Link href="..."> 调用都会经过 AppLink */}
      <YourApp />
    </LinkProvider>
  );
}

用 render 属性组合

对于需要直接控制渲染元素的特殊情况，可以使用 render 属性。 它会完全绕过 LinkProvider——其他所有属性（href、target、 className 等）都会自动合并到所提供的元素上。

import { Link } from "@cloudflare/kumo";
import { Link as RouterLink } from "react-router-dom";

export default function Example() {
  return (
    <>
      {/* 强制使用特定的路由链接（绕过 LinkProvider） */}
      <Link render={<RouterLink to="/dashboard" />} variant="inline">
        Dashboard
      </Link>

      {/* 强制使用普通锚点（绕过 LinkProvider） */}
      <Link render={<a />} href="https://example.com" target="_blank" rel="noopener noreferrer">
        External Site <Link.ExternalIcon />
      </Link>
    </>
  );
}

示例

段落内行内链接

链接在段落文本中自然排布，带有合适的下划线偏移。

import { Link } from "@cloudflare/kumo";

export function LinkInParagraphDemo() {
  return (
    <p className="mx-auto max-w-md text-base leading-relaxed text-kumo-default">
      This is a paragraph with an <Link href="#">inline link</Link> that flows
      naturally with the surrounding text. Links maintain proper underline
      offset for readability.
    </p>
  );
}

带图标的外部链接

用 Link.ExternalIcon 在视觉上标识会离开当前站点的链接。

import { Link } from "@cloudflare/kumo";

export function LinkExternalDemo() {
  return (
    <Link
      href="https://cloudflare.com"
      target="_blank"
      rel="noopener noreferrer"
      className="text-base"
    >
      Visit Cloudflare <Link.ExternalIcon />
    </Link>
  );
}

current 变体（颜色继承）

current 变体从父元素继承颜色，适用于警报等带颜色场景中的链接。

import { Link } from "@cloudflare/kumo";

export function LinkCurrentVariantDemo() {
  return (
    <p className="text-base text-kumo-danger">
      This error message contains a{" "}
      <Link href="#" variant="current">
        link
      </Link>{" "}
      that inherits the red color from its parent.
    </p>
  );
}

用 render 属性组合

render 属性让你可以把 Link 的样式组合到任意元素上， 从而与框架的路由组件集成。

import { Link } from "@cloudflare/kumo";

export function LinkRenderDemo() {
  return (
    <div className="flex flex-col gap-x-6 gap-y-4 text-base md:flex-row">
      <Link render={<CustomRouterLink href="/dashboard" />} variant="inline">
        Dashboard (via render)
      </Link>
      <Link
        render={
          <CustomRouterLink
            href="https://developers.cloudflare.com"
            target="_blank"
            rel="noopener noreferrer"
          />
        }
        variant="inline"
      >
        Cloudflare Docs <Link.ExternalIcon />
      </Link>
    </div>
  );
}

API 参考

Link 属性

继承原生锚点元素的全部属性。

变体

Link.ExternalIcon

用于标识外部链接的 SVG 图标组件。接受所有 SVG 元素属性。

<Link href="https://example.com" target="_blank" rel="noopener noreferrer">
  External Site <Link.ExternalIcon />
</Link>

设计指南