npm package: @sohu-bpd/share
Description: Web page share metadata management library
Latest version: 0.1.3

# @sohu-bpd/share

网页分享元数据管理库。支持在浏览器页面中轻松集成分享功能配置，包括开放图谱（Open Graph）标签、Twitter Card 标签和微信分享配置。

## 安装

```bash
npm install @sohu-bpd/share
# 或
pnpm add @sohu-bpd/share
# 或
yarn add @sohu-bpd/share
```

## 使用方式

### ESM / CommonJS

```typescript
import { setOGTags, setTwitterTags, configWechatShare } from '@sohu-bpd/share'

// 或
const { setOGTags, setTwitterTags, configWechatShare } = require('@sohu-bpd/share')
```

### Browser (IIFE)

```html
<script src="https://unpkg.com/@sohu-bpd/share/dist/index.global.js"></script>
<script>
  const { setOGTags, setTwitterTags, configWechatShare } = SohuShare
</script>
```

## API 文档

### Open Graph 标签 (OG)

#### setOGTags

在 HTML head 中创建或更新 Open Graph 元标签，用于控制页面在社交媒体和搜索引擎上的分享预览。

```typescript
function setOGTags(metadata: ShareMetadata): void
```

**参数：**

- `metadata` - 分享元数据配置对象

**类型：**

```typescript
interface ShareMetadata {
  title?: string              // 页面标题
  description?: string        // 页面描述
  url?: string               // 页面 URL
  image?: string             // 分享图片 URL
  siteName?: string          // 网站名称
  publishedTime?: string     // 文章发布时间 (ISO 8601 格式)
  modifiedTime?: string      // 文章更新时间 (ISO 8601 格式)
  twitterCardType?: string   // Twitter 卡片类型
  twitterSite?: string       // Twitter 账号
  twitterCreator?: string    // Twitter 创建者账号
}
```

**示例：**

```typescript
import { setOGTags } from '@sohu-bpd/share'

setOGTags({
  title: '我的精彩文章',
  description: '这是一篇很棒的技术文章，分享给大家',
  url: 'https://example.com/article/123',
  image: 'https://example.com/images/article-cover.jpg',
  siteName: '我的博客',
  publishedTime: '2024-01-15T10:30:00Z',
})
```

#### getOGTag

获取当前页面的 Open Graph 标签值。

```typescript
function getOGTag(property: string): string | null
```

**参数：**

- `property` - OG 属性名称，如 `'og:title'`、`'og:image'` 等

**返回值：** 对应标签的 content 值，不存在则返回 `null`

**示例：**

```typescript
import { getOGTag } from '@sohu-bpd/share'

const title = getOGTag('og:title')
const image = getOGTag('og:image')
```

### Twitter Card 标签

#### setTwitterTags

在 HTML head 中创建或更新 Twitter Card 元标签，用于控制页面在 Twitter/X 上的分享预览。

```typescript
function setTwitterTags(metadata: ShareMetadata): void
```

**参数：**

- `metadata` - 分享元数据配置对象（同 OG 标签）

**卡片类型：**

支持四种 Twitter 卡片类型：

- `'summary'` - 标准卡片（默认）
- `'summary_large_image'` - 大图片卡片
- `'app'` - 应用卡片
- `'player'` - 播放器卡片

**示例：**

```typescript
import { setTwitterTags } from '@sohu-bpd/share'

setTwitterTags({
  title: '我的精彩文章',
  description: '这是一篇很棒的技术文章',
  image: 'https://example.com/images/article-cover.jpg',
  twitterCardType: 'summary_large_image',
  twitterSite: '@myhandle',
  twitterCreator: '@author',
})
```

#### getTwitterTag

获取当前页面的 Twitter 标签值。

```typescript
function getTwitterTag(name: string): string | null
```

**参数：**

- `name` - Twitter 属性名称，如 `'twitter:card'`、`'twitter:title'` 等

**返回值：** 对应标签的 content 值，不存在则返回 `null`

**示例：**

```typescript
import { getTwitterTag } from '@sohu-bpd/share'

const cardType = getTwitterTag('twitter:card')
const creator = getTwitterTag('twitter:creator')
```

### 微信分享

#### configWechatShare

使用微信 JS-SDK 配置页面的分享信息。该函数会同时配置分享到朋友和分享到朋友圈的菜单项。

```typescript
function configWechatShare(config: WechatShareConfig): void
```

**参数：**

- `config` - 微信分享配置对象

**配置类型：**

```typescript
interface WechatShareConfig {
  title?: string           // 分享标题（默认使用 document.title）
  description?: string     // 分享描述（默认使用 meta[name="description"]）
  link?: string           // 分享链接（默认使用当前页面 URL）
  imgUrl?: string         // 分享图标 URL（默认使用 og:image）
  type?: string           // 分享类型，可选值：'link'、'photo'、'music'、'video'（默认 'link'）
  onSuccess?: () => void  // 分享成功回调
  onCancel?: () => void   // 分享取消回调
  onComplete?: () => void // 分享完成回调（无论成功还是取消都会触发）
}
```

**示例：**

```typescript
import { configWechatShare } from '@sohu-bpd/share'

configWechatShare({
  title: '分享标题',
  description: '分享描述',
  link: 'https://example.com/page',
  imgUrl: 'https://example.com/images/share.jpg',
  type: 'link',
  onSuccess: () => {
    console.log('分享成功！')
  },
  onCancel: () => {
    console.log('分享已取消')
  },
  onComplete: () => {
    console.log('分享完成')
  },
})
```

**注意：** 使用此功能前，需要先初始化微信 JS-SDK。推荐使用 `@sohu-bpd/wechat` 包来初始化。

#### setWechatTimelineShare

设置微信分享到朋友圈的菜单项。

```typescript
function setWechatTimelineShare(config: WechatShareConfig): void
```

**已弃用：** 推荐使用 `configWechatShare` 替代，该函数同时配置朋友圈和朋友分享。

#### setWechatAppMessageShare

设置微信分享到朋友的菜单项。

```typescript
function setWechatAppMessageShare(config: WechatShareConfig): void
```

**已弃用：** 推荐使用 `configWechatShare` 替代，该函数同时配置朋友圈和朋友分享。

## 完整示例

以下示例展示如何在 React 应用中集成分享功能：

```typescript
import { setOGTags, setTwitterTags, configWechatShare } from '@sohu-bpd/share'
import { useEffect } from 'react'

interface ArticleProps {
  title: string
  description: string
  url: string
  imageUrl: string
}

export function ArticleDetail({ title, description, url, imageUrl }: ArticleProps) {
  useEffect(() => {
    // 设置 Open Graph 标签
    setOGTags({
      title,
      description,
      url,
      image: imageUrl,
      siteName: '我的博客',
    })

    // 设置 Twitter Card 标签
    setTwitterTags({
      title,
      description,
      image: imageUrl,
      twitterCardType: 'summary_large_image',
      twitterSite: '@myblog',
    })

    // 配置微信分享
    configWechatShare({
      title,
      description,
      link: url,
      imgUrl: imageUrl,
      onSuccess: () => console.log('微信分享成功'),
    })
  }, [title, description, url, imageUrl])

  return (
    <article>
      <h1>{title}</h1>
      <img src={imageUrl} alt={title} />
      <p>{description}</p>
    </article>
  )
}
```

## TypeScript 支持

该库使用 TypeScript 开发，提供完整的类型定义：

```typescript
import type { ShareMetadata, WechatShareConfig } from '@sohu-bpd/share'

// 所有函数都有完整的类型提示
const metadata: ShareMetadata = {
  title: '文章标题',
  description: '文章描述',
  url: 'https://example.com',
}

const wechatConfig: WechatShareConfig = {
  title: '分享标题',
  onSuccess: () => console.log('成功'),
}
```

## 构建格式

- **ESM** (`.mjs`) - 现代 JavaScript 模块
- **CommonJS** (`.js`) - Node.js 和打包工具
- **IIFE** (`.global.js`) - 浏览器 `<script>` 标签，全局对象名为 `SohuShare`

## 兼容性

- **浏览器支持：** 所有现代浏览器（需要支持 ES2015）
- **Node.js：** 不在 Node.js 中使用（这是浏览器专用库）

## 常见问题

### 微信分享配置不生效怎么办？

确保：
1. 已正确初始化微信 JS-SDK
2. 页面已加载完全（通常在 React 组件 mount 后调用）
3. 检查浏览器控制台是否有错误信息

### 如何同时支持 OG 和 Twitter 标签？

使用 `setOGTags` 和 `setTwitterTags` 分别设置：

```typescript
// 同时设置 OG 和 Twitter 标签
setOGTags({ title: 'My Article', ... })
setTwitterTags({ title: 'My Article', ... })
```

或创建一个辅助函数：

```typescript
function setAllShareTags(metadata: ShareMetadata) {
  setOGTags(metadata)
  setTwitterTags(metadata)
  configWechatShare(metadata)
}
```

## 许可证

MIT