# @basenative/share 中文文档

规范地址：https://npmcn.com/package/%40basenative/share/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:00.773Z
中文译文更新时间：2026-10-31T16:34:27.321Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basenative/share
原文对照：https://npmcn.com/package/%40basenative/share/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/share#readme
源码仓库：https://github.com/DuganLabs/BaseNative

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：29.3 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@basenative/og-image 3\.0\.0
- 首次发布：2026-10-18T05:29:37.398Z
- 最新版本发布：2026-10-31T13:47:00.451Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

本机Web共享+剪贴板回退，共享卡薄荷客户端+服务器，和og重定向登陆页面生成器的BaseNative应用程序

## 安装

```sh
npm install @basenative/share
```

也可以使用：`pnpm add @basenative/share`、`yarn add @basenative/share`、`bun add @basenative/share`

## README

# @basenative /分享

每个可共享的BaseNative应用都需要三个要素：

1.  **本地共享+剪贴板回退** 对于浏览器。
2.  **Share-card薄荷** -服务器端存储+ POST处理程序 game/post/result变成一个稳定的短URL。
3.  **og重定向登陆页** -面向爬虫的HTML at `/s/{id}` 所以 iMessage / Discord / Twitter / LinkedIn渲染正确的卡片图像； 而真正的游客则会被js重新引导。

组合在一起 `@basenative/og-image` 为每股PNG。

## 安装

```sh
pnpm add @basenative/share
# Optional — server-side PNG rendering
pnpm add @basenative/og-image
```

## 从浏览器共享客户端

```js
import { nativeShare, mintShareCard, composeShareText } from '@basenative/share/client';

const { id, url } = await mintShareCard({
  sessionId, category, score, won, grid,
});

const text = composeShareText(
  'T4BS · ${category} · ${score}pts · ${verdict}\n\n${grid}',
  { category, score, verdict: won ? 'Solved' : 'Busted', grid }
);

const result = await nativeShare({ text, url });
// result.status: 'shared' | 'copied' | 'failed'
```

`nativeShare` 在可用的情况下使用Web共享API，回落到 `navigator.clipboard.writeText` 附加URL，并尊重用户 取消(`AbortError`)，所以我们不会通过默默地复制来伏击他们。

## 服务器铸造+着陆

在 `functions/api/share-cards.js`：

```js
import { defineShareCards, mintHandler } from '@basenative/share/server';

export const onRequestPost = async (ctx) => {
  const store = defineShareCards({ db: ctx.env.DB });
  return mintHandler({
    store,
    validate: (b) => {
      if (typeof b.category !== 'string' || !b.category) return 'bad-category';
      if (typeof b.score !== 'number') return 'bad-score';
      return true;
    },
  })(ctx);
};
```

在 `functions/s/[id].js`：

```js
import { defineShareCards, landingHandler } from '@basenative/share/server';

export const onRequestGet = async (ctx) => {
  const store = defineShareCards({ db: ctx.env.DB });
  return landingHandler({
    store,
    ogImage: (_card, { origin, id }) => `${origin}/og/score/${id}.png`,
    buildMeta: (card, { origin, id, ogImage }) => ({
      title: `T4BS — ${card.won ? 'Solved' : 'Busted'} ${card.category} for ${card.score}pts`,
      description: `Five-letter battle of bullshit — ${card.category}.`,
      imageUrl: ogImage,
      imageAlt: `T4BS score card`,
      canonicalUrl: `${origin}/s/${id}`,
      siteName: 'T4BS',
      themeColor: '#0C0B09',
    }),
    redirectTo: '/',
  })(ctx);
};
```

应用 `migrations/0001_share_cards.sql` 要设置 `share_cards` 表格。

## 勾搭 `@basenative/og-image`

在 `functions/og/score/[id].png.js`：

```js
import { defineShareCards } from '@basenative/share/server';
import { renderPng, defaultTheme } from '@basenative/og-image';
import { scoreCard } from '@basenative/og-image/presets';

export const onRequestGet = async ({ env, params }) => {
  const store = defineShareCards({ db: env.DB });
  const card = await store.get(params.id);
  if (!card) return new Response('not found', { status: 404 });

  const png = await renderPng(scoreCard({
    category: card.category,
    score: card.score,
    won: !!card.won,
    grid: card.grid,
    theme: defaultTheme,
  }));
  return new Response(png, {
    headers: {
      'Content-Type': 'image/png',
      'Cache-Control': 'public, max-age=31536000, immutable',
    },
  });
};
```

这个 `landingHandler` 引用这个URL，爬虫获取它，然后 预览渲染。

## 自定义域，自定义根

-   `origin` 接受字符串或 `(env) => string`.
-   `path` 默认为 `/s/`.
-   `idPattern` 默认为 `/^[a-z0-9]{4,16}$/i`.
-   `validate` 允许您内联拒绝格式错误的薄荷请求。

## 链接

-   碱性单氧- [https://github.com/DuganLabs/basenative](https://github.com/DuganLabs/basenative)
-   问题- - - - - - [https://github.com/DuganLabs/basenative/issues](https://github.com/DuganLabs/basenative/issues)
-   文档- [https://github.com/DuganLabs/basenative#readme](https://github.com/DuganLabs/basenative#readme)

## 许可证

apache - 2.0。

## 常见问题

### @basenative/share 是什么？

本机Web共享\+剪贴板回退，共享卡薄荷客户端\+服务器，和og重定向登陆页面生成器的BaseNative应用程序

### 如何安装 @basenative/share？

在项目目录运行 npm install @basenative/share，或使用 pnpm add / yarn add / bun add。

### @basenative/share 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basenative/share 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/share 可以商用吗？

@basenative/share 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/share 还在维护吗？

最新版本 3\.0\.0 发布于 2026/10/31（2 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。