x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/link.md

@@ -0,0 +1,197 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Link AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Link`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./link-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/link`（包含 base.css、link.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/link.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./link-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于页面跳转或轻量动作，适合在正文、列表和操作区中承载低重量入口。
+
+
+### 何时使用
+
+- 在正文、详情页或表格操作区放置低强调的跳转入口。
+- 用状态色表达成功、警告、危险等轻量动作。
+- 需要在链接前展示默认图标、业务图标或加载反馈。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+
+</script>
+<template>
+<Link href="https://example.com">文本链接</Link>
+  <Link href="https://example.com/docs" strong>强调链接</Link>
+  <Link disabled>禁用链接</Link>
+</template>
+```
+
+### 链接状态
+
+`status` 与品牌状态族一一对应：`normal` 即主色，另有 `success`、`warning`、`strong`、`danger`。
+
+> 注意区分两个 `strong`：`status="strong"` 是**颜色**（品牌强调色），无值的 `strong` 属性是**字重加粗**（见上方示例）。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+
+</script>
+<template>
+<Link href="https://example.com">普通链接</Link>
+  <Link status="success" href="https://example.com">成功链接</Link>
+  <Link status="warning" href="https://example.com">警告链接</Link>
+  <Link status="strong" href="https://example.com">强调链接</Link>
+  <Link status="danger" href="https://example.com">危险链接</Link>
+</template>
+```
+
+### 悬浮底色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+
+</script>
+<template>
+<Link href="https://example.com">默认悬浮底色</Link>
+  <Link href="https://example.com" :hoverable="false">无悬浮底色</Link>
+  <Link status="danger" href="https://example.com" :hoverable="false">危险无底色</Link>
+</template>
+```
+
+### 图标与插槽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+
+</script>
+<template>
+<Link icon href="https://example.com">默认图标</Link>
+  <Link href="https://example.com">
+    <template #icon>
+      <span aria-hidden="true">#</span>
+    </template>
+    自定义图标
+  </Link>
+  <Link icon disabled>禁用图标</Link>
+</template>
+```
+
+### 加载与事件
+
+没有传入 `href` 时，Link 会作为轻量动作入口处理，可通过键盘聚焦并使用 Enter 或 Space 触发点击事件。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(false);
+const logs = ref<string[]>([]);
+
+const runLoading = () => {
+  loading.value = true;
+  logs.value = ['loading link clicked', ...logs.value];
+  window.setTimeout(() => {
+    loading.value = false;
+  }, 1600);
+};
+
+const pushLog = (label: string) => {
+  logs.value = [`${label} clicked`, ...logs.value];
+};
+</script>
+<template>
+<Link :loading="loading" @click="runLoading">异步加载</Link>
+  <Link @click="pushLog('normal')">点击计数</Link>
+  <Link disabled @click="pushLog('disabled')">禁用不触发</Link>
+</template>
+```
+
+### 原生链接属性
+
+`target`、`rel`、`download`、`aria-*`、`id`、`class`、`style` 等原生 `<a>` 属性会透传到根节点。使用 `target="_blank"` 时建议同时设置 `rel="noopener noreferrer"`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Link } from 'x-next';
+
+import type { AnchorHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "target": "_blank", "rel": "noopener noreferrer", "aria-label": "在新窗口打开示例站点" } satisfies AnchorHTMLAttributes;
+const nativeAttrs2 = { "download": true } satisfies AnchorHTMLAttributes;
+</script>
+<template>
+<Link v-bind="nativeAttrs1"
+    href="https://example.com"
+
+
+
+  >
+    新窗口外链
+  </Link>
+  <Link v-bind="nativeAttrs2" href="/files/report.pdf" >下载链接</Link>
+</template>
+```
+
+### 亮暗颜色与交互状态
+
+文字使用独立的状态文字色；悬浮与按下只改变可用链接的背景。`hoverable=false`、禁用和加载态保持透明背景。用 Tab 聚焦动作链接，再用 Enter 或 Space 观察计数和焦点轮廓。
+
+页面本身为暗色时，请先切回亮色观察局部对照；`dark=false` 不会重置暗色祖先。任意品牌色仍需重新检查对比度。可通过 `--x-link-color-text`、`--x-link-color-text-success/warning/danger` 分别覆盖文字，通过既有 `--x-link-*-background-color` 覆盖悬浮背景。
+
+```vue
+<script setup lang="ts">
+const loading = ref(false);
+
+import { ref } from 'vue';
+import { Button as XButton, ConfigProvider as XConfigProvider, Link as XLink, Switch as XSwitch } from 'x-next';
+import 'x-next/style.css';
+
+const dark = ref(false);
+const brand = ref('#1c61ff');
+const statuses = ['normal', 'success', 'warning', 'danger'] as const;
+const clicks = ref(0);
+</script>
+<template>
+<label><XSwitch v-model="dark" />切换链接暗色</label>
+  <XButton @click="brand = brand === '#1c61ff' ? '#0f766e' : '#1c61ff'">切换品牌色</XButton>
+  <XConfigProvider :dark="dark" :theme-color="brand" class="color-scope">
+    <div v-for="status in statuses" :key="status">
+      <XLink :status="status" @click="clicks++">{{ status }}</XLink>
+      <XLink :status="status" :hoverable="false" @click="clicks++">无底色</XLink>
+      <XLink :status="status" loading @click="clicks++">加载中</XLink>
+      <XLink :status="status" disabled @click="clicks++">禁用</XLink>
+    </div>
+    <p aria-live="polite">点击：{{ clicks }}</p>
+  </XConfigProvider>
+</template>
+<style scoped>
+.color-scope {
+  padding: 16px;
+  color: var(--x-color-text-primary);
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./link-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。