# @basenative/flags 中文文档

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

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:48:08.732Z
中文译文更新时间：2026-10-31T15:59:57.987Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：23.1 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-20T05:27:47.332Z
- 最新版本发布：2026-10-31T13:48:08.402Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

带有percentage rollouts和@feature template指令的特性标志

## 安装

```sh
npm install @basenative/flags
```

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

## README

# @basenative /旗帜

> 带有百分比推出、基于规则的目标和可插拔提供者的特性标志

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/flags
```

## 快速入门

```js
import { createFlagManager, createMemoryProvider } from '@basenative/flags';

const provider = createMemoryProvider({
  newDashboard: { enabled: true },
  betaSearch: { percentage: 20 },
  premiumFeature: {
    enabled: false,
    rules: [{ attribute: 'plan', value: 'pro', value: true }],
  },
});

const flags = createFlagManager(provider);

// Simple boolean check
const showNew = await flags.isEnabled('newDashboard'); // true

// Percentage rollout (consistent per userId)
const inBeta = await flags.isEnabled('betaSearch', { userId: 'user-42' });

// Get all flags for client hydration
const allFlags = await flags.getAll({ userId: 'user-42' });
```

## 服务器中间件

```js
import { flagMiddleware } from '@basenative/flags';
import { createPipeline } from '@basenative/middleware';

const pipeline = createPipeline()
  .use(flagMiddleware(flags));
// ctx.state.flags is now an object of resolved flag values
```

## 模板的指令: `@feature`

`@basenative/flags` 注册一个 `@feature` 模板指令 `@basenative/runtime`作为导入这个包的副作用——它在任何地方都可以工作 `render()` (SSR)或 `hydrate()` （客户端）运行，没有额外的布线；

```html
<template @feature="newDashboard">
  <p>Try the new dashboard.</p>
</template>
<template @else>
  <p>Classic dashboard.</p>
</template>
```

`@feature` 读取 `ctx.$flags` 从渲染/水合物上下文- a _同步_ `{ isEnabled(name) }` 对象。 `flagManager.isEnabled()` 是异步的（它等待提供程序），而模板呈现端到端是同步的，所以在呈现之前解析每个标志一次，使用 `createFlagContext()`：

```js
import { createFlagManager, createMemoryProvider, createFlagContext } from '@basenative/flags';
import { render } from '@basenative/server';

const flags = createFlagManager(createMemoryProvider({ newDashboard: { enabled: true } }));
const $flags = await createFlagContext(flags, { userId: user.id });

const html = render(template, { ...data, $flags });
```

在客户端，水合物具有相同的形状-通常从服务器响应中嵌入(例如： `$flags.flags`)，并重组为 `{ isEnabled: (name) => Boolean(flags[name]) }`，或者一个活动对象，如果你想让标志对变化做出反应：

```js
import { hydrate } from '@basenative/runtime';

hydrate(root, { ...data, $flags: { isEnabled: (name) => window.__FLAGS__[name] } });
```

没有 `$flags` 在上下文中, `@feature` 将标志视为禁用-它呈现 `@else` 如果存在，则不存在-并发出 `BN_FEATURE_NO_PROVIDER` 诊断(通过 `options.onDiagnostic`)，而不是对无法求值的标志猜测“enabled”。 `flagName` 是一个字面的标志名，而不是一个表达式-没有引号，不像 `@if`/`@switch`.

在一个非——`<template>` 元素, `@feature="x"` 控制流不像其他流吗 `@name` 在那里，它变成了一个名为 `feature`, `@basenative/validate` 将其标记为 `BN_E_CONTROL_FLOW_ON_ELEMENT`.

### `createFlagContext(flagManager, context?)`

为每个标志解析一次 `context` 形状与…相同 `isEnabled`并返回一个普通的同步快照： `{ flags: Record<string, boolean>, isEnabled: (name) => boolean }`． 使用它的 `isEnabled` 在 `ctx.$flags` 用于 `@feature`.

## API

### `createFlagManager(provider, options?)`

创建标志求值管理器。选项: `defaultValue` -未找到标志时返回的值(默认值： `false`）。

返回:

-   `isEnabled(flagName, context?)` ——返回 `Promise<boolean>`． 上下文字段，如 `userId` 和 `sessionId` 用于百分比滚出散列。
-   `getAll(context?)` ——返回 `Promise<Record<string, boolean>>` 为给定上下文解析了所有标志。
-   `setFlag(flagName, config)` -如果提供程序支持写，则更新标志的配置。

### 标志配置形状

```js
{
  enabled: true,                   // simple boolean
  percentage: 25,                  // % rollout, 0-100
  rules: [                         // rule-based targeting
    { attribute: 'plan', value: 'pro', result: true }
  ]
}
```

### 供应商

-   `createMemoryProvider(options)` -内存提供程序。选项: `flags` - initial flag config map。
    -   `.getFlag(name)` -返回一个标志配置。
    -   `.getAllFlags()` —返回所有标志配置。
    -   `.setFlag(name, config)` -更新标志配置。
-   `createRemoteProvider(options)` -从HTTP端点获取标志。选项: `url`， `token`， `ttl` （缓存TTL以毫秒为单位）。

### `flagMiddleware(flagManager, options?)`

解析当前请求上下文和集合的所有标志 `ctx.state.flags`． 选项: `getContext(ctx)` -从请求上下文中提取评估上下文的函数。

## 许可证

apache - 2.0

## 常见问题

### @basenative/flags 是什么？

带有percentage rollouts和@feature template指令的特性标志

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

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

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

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

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

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

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

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

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

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