# @dpgradio/creative 中文文档

规范地址：https://npmcn.com/package/%40dpgradio/creative/

版本：9\.0\.5
npm 元数据更新时间：2026-10-01T13:31:10.365Z
中文译文更新时间：2026-11-14T12:38:40.964Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dpgradio/creative
原文对照：https://npmcn.com/package/%40dpgradio/creative/?lang=original
项目主页：https://github.com/dpgradio/creative#readme
源码仓库：https://github.com/dpgradio/creative

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

- 包体积（解压后）：90.5 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2023-02-16T13:52:15.852Z
- 最新版本发布：2026-10-01T13:31:09.225Z
- 近 30 天下载量：2042（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 3 个）

## 中文简介

独立 Javascript 应用程序的支持软件包

## 安装

```sh
npm install @dpgradio/creative
```

也可以使用：`pnpm add @dpgradio/creative`、`yarn add @dpgradio/creative`、`bun add @dpgradio/creative`

## README

# @dpgradio/创造性

目录 :

-   [安装](https://npmcn.com/package/%40dpgradio/creative/#readme-installation)
-   [CSS: 字体和颜色](https://npmcn.com/package/%40dpgradio/creative/#readme-css-fonts-and-colors)
-   [配置](https://npmcn.com/package/%40dpgradio/creative/#readme-config)
-   [隐私和跟踪](https://npmcn.com/package/%40dpgradio/creative/#readme-privacy-and-tracking)
-   [API 密码](https://npmcn.com/package/%40dpgradio/creative/#readme-api)
-   [套接字](https://npmcn.com/package/%40dpgradio/creative/#readme-socket)
-   [混合](https://npmcn.com/package/%40dpgradio/creative/#readme-hybrid)
-   [认证](https://npmcn.com/package/%40dpgradio/creative/#readme-authentication)
-   [共享生成器](https://npmcn.com/package/%40dpgradio/creative/#readme-sharing-generator)
-   [公用事业](https://npmcn.com/package/%40dpgradio/creative/#readme-utilities)

## 安装

```bash
npm i @dpgradio/creative
```

## CSS: 字体和颜色

注意,本套件第5版提供字体和颜色作为纯cs. 变量和字体不再作为 scs 变量/ 导入而可用.

示例

```css
@import "@dpgradio/creative/styles/colors/qmusic";
@import "@dpgradio/creative/styles/fonts/qmusic";

body, html {
  background-color: rgb(var(--q-green));
  color: rgb(var(--q-grey) / 0.8);
  font-family: 'BlackBones';
}
```

使用以下内容来导入所有品牌的颜色和字体 :

```css
@import "@dpgradio/creative/styles/all";
```

## 配置

### 使用量

在应用程序的主脚本中添加以下内容以获取配置 . 此配置也将被本套件的其他组件所使用(如隐私,跟踪等).

```js
import { configuration } from '@dpgradio/creative'

// Global config only
await configuration.retrieveConfigForDetectedStation()

// Global and app-specific config
await configuration.retrieveConfigForDetectedStation(appId) // Default, by hostname or query parameter

// Or, if you want to retrieve the config by hostnames only.
await configuration.retrieveConfigByHostname(appId)
// Or, if you want to retrieve the config for a specific station:
await configuration.retrieveConfigForStation(stationId, appId)

// By default the first station ID (stationIdA) is used as the current station of the configuration.
// If you want to use a different station, you can do so by calling setStation:
await configuration.retrieveConfigForStations([stationIdA, stationIdB, stationIdC], appId)
configuration.setStation(stationIdC)
```

你可以在稍后的任何时候更改车站,而无需再次取回配置. API客户端将自动使用正确的站. 换站后需要恢复隐私和跟踪.

现在的配置可以使用如下:

```js
import { config } from '@dpgradio/creative'

config('api_base_url') // or: config().api_base_url
config('app.default_theme') // or: config().app.default_theme
```

### 更新Schema

应用程序可以通过创建包含以下内容的脚本来创建/修改配置计划:

```js
import { api, configuration } from '@dpgradio/creative'

api.setApiKey('<api-token-here>')

await configuration.replaceSchema('greety', [
  {
    name: 'display_language',
    type: 'options',
    default: 'dutch',
    options: ['dutch', 'english'],
  },
  {
    name: 'author_name',
    type: 'string',
  },
])
```

(假设高层等待和 `fetch`(中文(简体) )

## 隐私和跟踪

### 隐私

#### 初始化

无 [配置](https://npmcn.com/package/%40dpgradio/creative/#readme-config)数字 :

```js
import { privacy } from '@dpgradio/creative'

privacy.initialize(privacyManagerId, websiteUrl, cmpCname)
```

有配置( 之后) [初始化配置](https://npmcn.com/package/%40dpgradio/creative/#readme-config):

```js
import { privacy } from '@dpgradio/creative'

privacy.initialize()
```

#### 获取同意字符串

```js
import { privacy } from '@dpgradio/creative'

const consent = await privacy.waitForConsent()

// Available properties:
consent.consentString
consent.purposes
consent.allowsTargetedAdvertising()
```

### 跟踪

```js
import { dataLayer } from '@dpgradio/creative'

dataLayer.initialize() // Pushes gtmStart and currently authenticated user
dataLayer.pushVirtualPageView(brand) // brand is not required when the config is initialized

dataLayer.pushEvent(event, data)
```

与 Mixpanel 连接

```js
import { mixpanel } from '@dpgradio/creative'
import Mixpanel from 'mixpanel-browser'

mixpanel.initialize(Mixpanel, {
    mixpanelId: 'MIXPANEL ID',
})

mixpanel.trackEvent(event, data)
```

## API 密码

刚开始 [配置](https://npmcn.com/package/%40dpgradio/creative/#readme-config)数字 :

```js
import { api } from '@dpgradio/creative'

const channels = await api.channels.all()

const globalChannels = await api.global().channels.all()

api.setRadioToken(token)
const profile = await api.members.me() // or await api.setRadioToken(token).members.me()

api.setApiKey(key)
await api.global().config.update(appId, schema)

const oldChannels = await api.onVersion('1.4').channels.all()
```

没有初始化 [配置](https://npmcn.com/package/%40dpgradio/creative/#readme-config)数字 :

```js
import { Api } from '@dpgradio/creative'

const api = new Api('https://api.qmusic.be')

const channels = await api.channels.all()
```

## 套接字

```js
import { socket } from '@dpgradio/creative'

socket.connect(stationId).subscribe('plays').on('play', () => {
  console.log('play')
}, { backlog: 3 }})

// or

socket.join({ station: stationId, entity: 'plays', action: 'play', options: { backlog: 3 } }, (play) => {
  console.log(play)
})
```

## 混合

在应用程序中的网页视图中使用的应用程序交互层. 互动取道"贾瓦斯克力特桥". 在iOS上它会使用 [信件处理器](https://developer.apple.com/documentation/webkit/wkscriptmessagehandler) 它在Android上使用过 [Javascript 界面](https://developer.android.com/guide/webapps/webview#BindingJavaScript)。 。 。 .

```js
import { hyrid } from '@dpgradio/creative'
```

### 资料

#### `hybrid.appInfo()`

提供该应用的品牌,平台,版本等信息.

#### `hybrid.isNativeApp()`

回返 `true` 如果客户端是本地应用程序.

#### `hybrid.isVersion({ iOS, Android })`

回返 `true` 如果客户端是本地的应用程序,且该版本等于或低于给定平台的给定版本.

### 倾听事件

该应用程序将释放出能够被倾听的事件. 对于某些事件,例如: `appLoad` 必须尽快开始倾听. 因为这有时很难做到,因为.. `appLoaded` 方法可用于等待 `appLoad` 活动. 如果这个事件在方法被调用之前已经释放出来,它会立即返回.

现有活动如下:

-   `appLoad`:应用程序已装入. 如果用户登录,则提供他们的无线电信号.
-   `authenticated`: 用户已认证 。 它提供了用户的收音机代号.
-   `didAppear`:网页视图可见. 如果用户登录,则提供他们的无线电信号。 ⚠️ 测试此事件何时发射 .
-   `didHide`:网页视图被隐藏. ⚠️ 测试此事件何时发射 .

#### `hybrid.on(event, callback, once)`

听为一事. 若为 `once` 实值 `true`,召回只使用一次.

#### `hybrid.one(event, callback)`

听为一事. 召回将只召回一次.

#### `hybrid.appLoaded()`

这种方法返回一个承诺,当 `appLoad` 事件已释放. 如果该事件在调用方法之前已经发射, 则会立即返回 .

如果用户登录,则返回用户的收音机令牌.

示例用法:

```
const radioToken = await hybrid.appLoaded()
await api.members.me()
```

### 行动

为了启动应用方面的行动,我们提供以下方法.

在头罩下,这些动作被称为使用以下方法,在需要调用一个不能作为方法的动作时,也可以直接使用:

```
hybrid.call(method, options)
```

你可能会遇到这个方法 `"navigateTo"` 在旧代码. 这种方法现已贬值,取而代之的是 `hybrid.openUrl` 财务报告和审定财务报表 `hybrid.openPermalink`。 。 。 .

#### `hybrid.openUrl(url, { mode })`

在选择模式中打开外部 URL. 这并不意味着在我们自己的域上打开URL,例如. `https://qmusic.be/this-is-a-cool-article`。 。 。 . 使用这个 `hybrid.openPermalink`。 。 。 .

支持的模式 :

-   `segue`:在从右侧滑出并推入当前页面的窗口中打开 URL.
-   `overlay`: 以从下方向上滑动的全屏模式打开URL.
-   `in-app-browser`: 在带有导航控制的内应用浏览器中打开URL. 没有支持混合功能 .
-   `external-browser`:在默认浏览器中打开URL. 没有支持混合功能 .

#### `hybrid.openPermalink(permalink)`

打开文章等的通路. 文章将以正则显示 `segue` 样式.

QQ截至2023年10月,尚未获得应用程序支持.

#### `hybrid.showAuthentication()`

显示认证对话框 .

在Android上,无论登录状态如何,都会显示此功能,在iOS上,只有在用户没有登录时才会显示.

#### `hybrid.changeHeight(height, { animated })`

更改网页视图的高度.

## 认证

```js
import { authentication } from '@dpgradio/creative'

// Call once, at least before requiring authentication somewhere
authentication.initialize()

// Main usage: prompts for login if needed and sets the token in the API client
await authentication.require()


// Potentially helpful methods (but not required for typical usage)
authentication.isLoggedIn()
authentication.onRadioTokenChange(callback)
authentication.onLogin(callback)
authentication.askForLogin() // Does the same as require(), but does not await the result
authentication.radioToken
```

## 共享生成器

示例

```js
import { Shareable, ImageGeneratorProperties } from '@dpgradio/creative/share'

const shareable = new Shareable()
  .withTitle(`${this.name} is mijn seventies match!`)
  .withDescription('Ontdek wie jouw seventies match is in de Generation Quiz van Joe!')
  .withMessageText(`Mijn seventies match is ${this.name}, wat is die van jou?`)
  .redirectTo('https://article_url.com')
  .fromDomain('joe.be')

// Facebook
const image = new ImageGeneratorProperties('https://static.qmusic.be/acties/joe-70s-quiz-share-fb/index.html')
  .withDimensions(1200, 630)
  .withPayload({ results: this.matches });

(await shareable.generateUsingImage(image)).openFacebookUrl()

// Instagram
const image = new ImageGeneratorProperties('https://static.qmusic.be/acties/joe-70s-quiz-share-fb/index.html')
  .withDimensions(1080, 1920)
  .withPayload({ results: this.matches });

(await shareable.generateUsingImage(image)).openInstagramUrl()

// Whatsapp
const image = new ImageGeneratorProperties('https://static.qmusic.be/acties/joe-70s-quiz-share-fb/index.html')
  .withDimensions(1200, 630)
  .withPayload({ results: this.matches });

(await shareable.generateUsingImage(image)).openWhatsappUrl()
```

## 社区支助方案

有时需要设置严格的内容安全政策(CSP)头. 当情况是这样时,本套件中的一些方法的优美之处在于它们支持一个随机的非ce来传递到额外来源(GTM,隐私门),所以不需要明确列入白名单(因为它们在开发时可能是未知的). 我们的数据显示器和隐私门初始化器可选 `nonce` 参数可以传递到其中.

```js
import { privacy, dataLayer } from '@dpgradio/creative'

privacy.initialize(privacyManagerId, websiteUrl, cmpCname, { nonce: "abc1234" })
dataLayer.initialize({ nonce: "abc1234" })
```

这样你就可以在您的 CSP 信头中 将这个非编号白列了

```
Content-Security-Policy: script-src 'nonce-abc1234'
```

**来了! 注意这个非ce 需要随机的每个请求, 否则这个安全是没用的!**

## 公用事业

这个软件包提供了一些实用功能.

| 函数 | 说明 |
| --- | --- |
| `loadScript(url, { timeout })` | 动态地装入JS剧本. |
| `openExternalUrl(url)` | 在 Web/app 上尽可能从当前页面中单独打开外部URL. |
| `tap(value, callback)` | 调用 `callback` 与 `value` 然后返回 `value`。 。 。 . |
| `cdnImageUrl(endpoint[, size])` | 获取一个特定大小的结束点的完整图像 URL( T)`w480`, (中文(简体) ), `w800`, (中文(简体) ), `w1200`, (中文(简体) ), `w2400`) (中文(简体) ). |
| `cdnUrl(endpoint)` | 为给定的终点获取完整的 CDN URL . |
| `removePhoneNumberCountryPrefix(phoneNumber, [, prefix])` | 从基于车站配置的电话号码中删除国家前缀 `country_code`。 。 。 . |
| `onLocalStorageChange(key, callback)` | 电话 `callback` 当值为 `key` 内 `localStorage` 变化. |
| `decodeRadioToken(token)` | 解码一个JWT收音机符号. |

## 常见问题

### @dpgradio/creative 是什么？

独立 Javascript 应用程序的支持软件包

### 如何安装 @dpgradio/creative？

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

### @dpgradio/creative 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dpgradio\_\_creative 是否存在。

### @dpgradio/creative 支持 ESM 还是 CommonJS？

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

### @dpgradio/creative 可以商用吗？

@dpgradio/creative 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dpgradio/creative 的下载量有多少？

根据 npm 官方下载统计，@dpgradio/creative 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,042 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dpgradio/creative 还在维护吗？

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