# @effected/schema-org 中文文档

规范地址：https://npmcn.com/package/%40effected/schema-org/

版本：0\.15\.0
npm 元数据更新时间：2026-11-10T15:07:58.030Z
中文译文更新时间：2026-11-14T04:54:07.712Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：215 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.0
- 首次发布：2026-08-26T18:36:45.805Z
- 最新版本发布：2026-11-10T15:07:57.684Z
- 近 30 天下载量：2330（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

schema.org 词汇作为 Effect Schema 类,带有脚本安全 JSON-LD 序列器

## 安装

```sh
npm install @effected/schema-org
```

也可以使用：`pnpm add @effected/schema-org`、`yarn add @effected/schema-org`、`bun add @effected/schema-org`

## README

# @ effect/schema-org (帮助)

[![npm](https://img.shields.io/npm/v/@effected%2Fschema-org?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/schema-org) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

schema.org作为 Effect Schema 类:构建一个 JSON-LD 图形,将其安全地序列化为 `<script>` 元素,并对照 schema.org 自己的词汇下线. `effect` 是唯一的对等依赖, 并且根本没有运行时间的依赖性 —— 词汇以生成的 TypeScript 来销售, 所以这里没有到达网络 .

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 为什么

结构化数据通常以对象字面形式组装,并投入模板 `JSON.stringify`,它得到两件事 错误同时。 第一个是安全错误: `JSON.stringify` 无法逃脱 `<`因此,有一个描述包含文字 `</script>` 提前关闭 JSON-LD 块, 并在页面中注入任何后续内容 。 第二个是更安静的——schema.org有一个词汇,你的对象字面上没有,词汇上没有定义的假象属性,只是被每个消费者忽略,在任何地方都没有出错.

这个包在源头都修好了. `toScriptBody()` 是唯一的文本序列器,它是被逃脱的,所以无法通过选择错误的函数来到达注射大小写。 词汇船卖出,所以一个建造步骤可以拒绝一个错误的地产离线,在CI,没有网络呼叫和爬行者往返.

## 安装

```bash
npm install @effected/schema-org effect
```

```bash
pnpm add @effected/schema-org effect
```

需要节点.js~~24.11.0.

全体 `@effected/*` 软件包仅为无害环境管理:只公布出口地图 `import` 条件,所以 `require()` 包括解析 CJS 模式的工具 —— 与节点失败 `ERR_PACKAGE_PATH_NOT_EXPORTED` 而不是装入不存在的 CJS 建筑。 从ES模块导入.

## 快开始

将节点组合成图表,然后序列化:

```ts
import { JsonLdDocument, NodeRef, SoftwareSourceCode, TechArticle } from "@effected/schema-org";
import { Result } from "effect";

const built = JsonLdDocument.buildResult([
  SoftwareSourceCode.make({ "@id": "https://example.com/pkg#source", name: "example", version: "1.2.3" }),
  TechArticle.make({
    "@id": "https://example.com/pkg/docs#intro",
    headline: "Getting started </script>",
    isPartOf: [NodeRef.to("https://example.com/pkg#source")],
  }),
]);

console.log(Result.getOrThrow(built).toScriptBody());
// {"@context":"https://schema.org","@graph":[{"@id":"https://example.com/pkg#source","@type":"SoftwareSourceCode","name":"example","version":"1.2.3"},{"@id":"https://example.com/pkg/docs#intro","@type":"TechArticle","isPartOf":[{"@id":"https://example.com/pkg#source"}],"headline":"Getting started </script>"}]}
```

然后逐字地将身体嵌入:

```html
<script type="application/ld+json">BODY</script>
```

`buildResult` 是切入点,而不是 `make`数字 : `Schema.Class` 储备金 `make` 它的原始结构构造器, 它没有进行身份检查. `JsonLdDocument.build` 这是 `Effect` 双 `buildResult`,从它衍生出来——同步形式是原始的,所以静态站点的建筑从不需要构造出跑时.

三件事都失败了 全部都是呼叫器错误 而不是要向用户报告的东西:一个畸形 `@id` (单位:千美元)`InvalidNodeIdError`),两个节点声称一个 `@id` (单位:千美元)`DuplicateNodeIdError`),以及一个囊括所有密钥与打字场相撞(`ConflictingTermError`A级 **轻而易举的引用是合法的** ——指向另一页描述的节点是正确的JSON-LD——所以读作 `danglingReferences` 自己决定你的图表是否应该关闭.

## 连载器才是重点

你图中的每个字符串都来自别人写的散文 包含文字的描述 `</script>` **提前关闭 JSON- LD 块并插入标记到您的页面**,以及 `JSON.stringify` 不能逃脱它.

`toScriptBody()` 逃脱 `<`, (中文(简体) ), `>` 财务报告和审定财务报表 `&` 字符串后。 所有三个都是有效的 JSON 字符串逃出,所以一个解析器可以看到原始字符;没有 `<` 在体内,也没有 `</script` 也没有 `<!--` ,元素不能从内部关闭。 这个 `&` 在文档作为 XHTML 服务时,另将输出保存良好。 出逃是"一能",所以第二次通过输出是安全的,而不是"双能".

**故意没有未脱逃的文本序列器 .** 所逃出的产出并不是一种受限制的形式——对于任何描述它的人来说,它是完全相同的,那就是每一个人——所以第二个切入点只能被错误地选择.

`toJsonLd()` 返回电线窗体为纯值,用于串行 JSON-LD 本身的框架. **如果您正在生成文本, 请不要使用** —— 说 `JSON.stringify(doc.toJsonLd())` 重新引入此软件包的准确错误来防止 .

## 校验离线

```ts
import { Conformance, Vocabulary } from "@effected/schema-org/validate";

console.log(Vocabulary.version);
// 30.0

for (const issue of Conformance.check(doc)) {
  console.error(issue._tag, issue.message);
}
// PropertyNotOnType https://example.com/pkg#source: schema.org does not define "softwareVersion" on SoftwareSourceCode
```

`Conformance.check` 完全——它从不失败,从不扔出,因为报告不是一个失败模式. `Conformance.validateResult` 是建在它的上方的大门, 返回图表或一个 `NonConformantGraphError` 携带每期 `Conformance.validate` 这是它的 `Effect` 双胞胎 默认只关闭大门的结构类型; `ConformanceOptions` 拓宽其范围,以贬低和忽略引用.

词汇被卖出,所以大门会断线运行,在CI中没有网络呼叫. 它抓住了实际发生的失败——不是JSON的畸形,但一个可信的地产schema.org没有定义该类型. `softwareVersion` 编号 `SoftwareSourceCode` 是犬科的例子: 它的读取正确,序列化精细,在下游被默默地忽略. (财产是: `version`. ) (中文(简体) )

合法性通过全面解决 `rdfs:subClassOf` 祖先封闭,所以继承的财产被接受—— `license` 仅公布于 `CreativeWork`,这是合法的 `SoftwareSourceCode` 因为那个链子.

**从中导入 `./validate` 子路径.** 词汇表是只使用图表的消费者所避免的全部:导入 `@effected/schema-org` 装入节点类和序列器. `./validate` 重新导出节点类 **只类型**,用于标注签字——通过签字达到某种价值,例如: `NodeRef.to`,以“只提及类型”失败。 从根导入值 .

**符合标准不是谷歌富收资格.** Google要求属性schema.org没有,并按自己的时间表改变其政策. 这告诉你schema.org定义了这个术语;它不会给你带来丰富的结果.

## 此软件包没有做什么

-   **薄荷 `@id`编号.** 它们是您命名空间中的IRI; 软件包无法了解您的基址, 也永远不会获得一个 .
-   **将您的域映射到节点上 .** 那幅地图是你的.
-   **解码 JSON-LD 回打出节点.** 编码方向是本出品中被支持的方向,而测试会把不对称的分出来,这样它就不能意外地开始半工半读.
-   **模拟所有 schema.org.** 6个节点类型,加一个开口 `additional` 涵盖任何术语——验证人随后检查.

## 特征

-   `SoftwareSourceCode`, (中文(简体) ), `TechArticle`, (中文(简体) ), `APIReference`, (中文(简体) ), `Person`, (中文(简体) ), `Organization`, (中文(简体) ), `CreativeWork` ——六个节点类. 每个节点都需要 `@id` 其它所有领域都是可选的,可以当作 `undefined`,在序列化时放弃.
-   `ThingFields`, (中文(简体) ), `CreativeWorkFields`, (中文(简体) ), `TechArticleFields` ——共享字段记录节点类组装自来,为消费楼出品,此套件不作型号的节点.
-   `NodeRef` - 指另一个节点,由 `@id`,与 `to` (未检查,在构建时验证),同步 `toCheckedResult` 联 合 国 `Effect` 双向 `toChecked`,则 `isValidId` 上观相. 节点价值的财产持有 `NodeRef`从来没有嵌入式节点.
-   `JsonLdDocument` ——图: `buildResult` 编号 : `build` 收集并检查身份, `nodeIds` 财务报告和审定财务报表 `danglingReferences` 检查, `toScriptBody()` 要序列化页面 `toJsonLd()` 一个将JSON-LD本身序列化的框架.
-   `Vocabulary` 阅读API `version`, (中文(简体) ), `hasType`, (中文(简体) ), `hasProperty`, (中文(简体) ), `ancestorsOf`, (中文(简体) ), `propertiesOf`, (中文(简体) ), `isPropertyOn` 财务报告和审定财务报表 `supersededBy`,可自行使用,用于从未构建图表的工具.
-   `Conformance` ——离线合规检查,报告 `UnknownTerm`, (中文(简体) ), `PropertyNotOnType`, (中文(简体) ), `DeprecatedType`, (中文(简体) ), `DeprecatedProperty` 财务报告和审定财务报表 `DanglingReference` 每个问题都有一行 `message`。 。 。 .
-   重复的属性总是一个数组, 即使是长度为一的- 包括 `license`,因为 `MIT AND Apache-2.0` 这是一种真正的双重许可证 并且崩溃 这将是沉默的数据损失.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40effected/schema-org/LICENSE)

## 常见问题

### @effected/schema-org 是什么？

schema\.org 词汇作为 Effect Schema 类,带有脚本安全 JSON-LD 序列器

### 如何安装 @effected/schema-org？

在项目目录运行 npm install @effected/schema-org，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effected/schema-org 支持 TypeScript 吗？

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

### @effected/schema-org 支持 ESM 还是 CommonJS？

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

### @effected/schema-org 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @effected/schema-org 可以商用吗？

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

### @effected/schema-org 的下载量有多少？

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

### @effected/schema-org 还在维护吗？

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