@ 习惯要素 - 显示/ 标记下
自定义元素. json是描述自定义元素的文件格式. 这种格式将允许工具化和IDEs在给定项目中提供丰富的自定义元素信息. 然而,它非常具有实验性,而且情况会发生变化。 继续讨论 这里。 。 。 .
这个库需要一个自定义元素表单, 并让它被标记下来 .
使用量
安装 :
npm i -S @custom-elements-manifest/to-markdown
在代码中导入和使用 :
import fs from 'fs';
import { customElementsManifestToMarkdown } from '@custom-elements-manifest/to-markdown';
const manifest = JSON.parse(fs.readFileSync('./custom-elements.json', 'utf-8'));
const markdown = customElementsManifestToMarkdown(manifest);
fs.writeFileSync('./custom-elements.md', markdown);
选项
| 选项 | 类型 | 默认 | 说明 |
|---|
| 标题 | 整数 | 0 个 | 用这个数字来抵消标题级别 |
| 私营 | 'all'|'details'|'hidden' | 'all' | 见 私人成员 |
| 省略声明 | OptionalDeclarations[] | [ | 见 奥林匹克宣言 |
| 省略节 | OptionalSections[] | [ | 见 关闭部分 |
| 分类Name | string | (() => string) | '.*' | 见 类名过滤器 |
私人成员
这个 private 选项控制个人成员如何出现在减记中.
'all':私人成员根据来源顺序与公共成员并列'hidden':私人成员根本不出现在减记中,但受保护成员确实如此'details': 私有和受保护的成员在表格下方的详细披露部件中出现
奥林匹克宣言
这个 omitDeclarations 选项是 string[] 控制最终减值产出中哪些实体。 这四种宣言类型是:
以下是可以过滤出所有四种声明类型的示例配置:
customElementsManifestToMarkdown(manifest, {
omitSections: ['mixins', 'variables', 'functions', 'exports' ]
})
** 注:**混合物既可作为声明提供,也可作为声明内的章节提供。 这个 omitDeclarations 选项 mixins 将仅过滤出顶层混合声明。 从 a 过滤出混音段 class 声明,使用 mixin 过滤从 omitSections。 。 。 .
关闭部分
这个 omitSections 选项是 string[] json)在最后减值输出中应提供。 本节名称为:
- 主标题
- 超级类
- 字段
- 方法
- 静态字段
- 静态方法
- 插槽
- 事件
- 属性
- css 财产
- css 组件
- 组合
以下是显示如何过滤出几节的示例配置 :
customElementsManifestToMarkdown(manifest, {
// static fields and static methods tables will not be present
// in the markdown result
omitSections: [ 'staticFields', 'staticMethods' ]
})
类名过滤器
根据你传给分析员的来源文件 custom-elements-manifest.json 可能包含的类文件声明数量超过您需要的最终减值输出。 这个 classNameFilter 选项接受一个 regex 作为字符串(或返回一个函数),用于在渲染前过滤类声明.
customElementsManifestToMarkdown(manifest, {
classNameFilter: () => {
// some logic
return `(${prefix}-*|SuperClassExact)`; // filters out every class name that doesnt match the regex provided
}
})
演示
customElementsManifestToMarkdown(manifest, {
headingOffset: 1,
private: 'details',
})
来源
{
"schemaVersion": "1.0.0",
"readme": "",
"modules": [
{
"kind": "javascript-module",
"path": "./fixtures/-TEST/package/my-element.js",
"declarations": [
{
"kind": "class",
"name": "SuperClass",
"events": [
{
"name": "custom-event",
"type": {
"text": "SuperCustomEvent"
},
"description": "this is custom"
}
],
"superclass": {
"name": "LitElement",
"package": "lit-element"
},
"members": [
{
"kind": "method",
"name": "superClassMethod",
"privacy": "public"
}
]
},
{
"kind": "class",
"name": "MyElement",
"cssProperties": [
{
"name": "--background-color",
"description": "Controls the color of bar"
}
],
"cssParts": [
{
"name": "bar",
"description": "Styles the color of bar"
}
],
"slots": [
{
"name": "container",
"description": "You can put some elements here"
}
],
"events": [
{
"name": "my-event",
"type": {
"text": "Event"
}
},
{
"name": "custom-event",
"type": {
"text": "SuperCustomEvent"
},
"description": "this is custom",
"inheritedFrom": {
"name": "SuperClass",
"module": "./fixtures/-TEST/package/my-element.js"
}
}
],
"mixins": [
{
"name": "LocalizeMixin",
"package": "lion"
},
{
"name": "Mixin",
"module": "./fixtures/-TEST/package/my-element.js"
}
],
"superclass": {
"name": "SuperClass",
"module": "./fixtures/-TEST/package/my-element.js"
},
"attributes": [
{
"name": "prop-1",
"fieldName": "prop1"
},
{
"name": "prop2",
"fieldName": "prop2"
}
],
"members": [
{
"kind": "field",
"name": "prop1",
"privacy": "public"
},
{
"kind": "field",
"name": "prop2",
"privacy": "public"
},
{
"kind": "field",
"name": "prop3",
"privacy": "public",
"type": {
"text": "boolean"
},
"default": "true"
},
{
"kind": "field",
"name": "foo",
"type": {
"text": "string"
},
"privacy": "private",
"description": "description goes here",
"default": "'bar'"
},
{
"kind": "method",
"name": "instanceMethod",
"privacy": "public",
"description": "Some description of the method here",
"return": {
"type": {
"text": ""
}
},
"parameters": [
{
"name": "e",
"type": {
"text": "Event"
}
},
{
"name": "a",
"type": {
"text": "string"
},
"description": "some description"
}
]
},
{
"kind": "field",
"name": "mixinProp",
"type": {
"text": "number"
},
"privacy": "protected",
"default": "1",
"inheritedFrom": {
"name": "Mixin",
"module": "./fixtures/-TEST/package/my-element.js"
}
},
{
"kind": "method",
"name": "superClassMethod",
"privacy": "public",
"inheritedFrom": {
"name": "SuperClass",
"module": "./fixtures/-TEST/package/my-element.js"
}
}
],
"tagName": "my-element"
},
{
"kind": "variable",
"name": "variableExport",
"description": "this is a var export",
"type": {
"text": "boolean"
}
},
{
"kind": "variable",
"name": "stringVariableExport",
"description": "this is a string var export",
"type": {
"text": "string"
}
},
{
"kind": "function",
"name": "functionExport",
"description": "This is a function export",
"return": {
"type": {
"text": "boolean"
}
},
"parameters": [
{
"name": "a",
"type": {
"text": "string"
}
},
{
"name": "b",
"type": {
"text": "boolean"
}
}
]
},
{
"kind": "mixin",
"name": "MyMixin4",
"parameters": [
{
"name": "klass",
"type": {
"text": "*"
},
"description": "This is the description"
},
{
"name": "foo",
"type": {
"text": "string"
},
"description": "Description goes here"
}
]
},
{
"kind": "mixin",
"name": "Mixin",
"parameters": [
{
"name": "klass",
"type": {
"text": "*"
},
"description": "This is the description"
}
],
"members": [
{
"kind": "field",
"name": "mixinProp",
"type": {
"text": "number"
},
"privacy": "protected",
"default": "1"
}
]
}
],
"exports": [
{
"kind": "js",
"name": "SuperClass",
"declaration": {
"name": "SuperClass",
"module": "./fixtures/-TEST/package/my-element.js"
}
},
{
"kind": "custom-element-definition",
"name": "my-element",
"declaration": {
"name": "MyElement",
"module": "./fixtures/-TEST/package/my-element.js"
}
},
{
"kind": "js",
"name": "variableExport",
"declaration": {
"name": "variableExport",
"module": "./fixtures/-TEST/package/my-element.js"
}
},
{
"kind": "js",
"name": "stringVariableExport",
"declaration": {
"name": "stringVariableExport",
"module": "./fixtures/-TEST/package/my-element.js"
}
},
{
"kind": "js",
"name": "functionExport",
"declaration": {
"name": "functionExport",
"module": "./fixtures/-TEST/package/my-element.js"
}
}
]
}
]
}
结果
./fixtures/-TEST/package/my-element.js数字 :
类 : SuperClass
超级级
方法
活动
| 名称 | 类型 | 说明 | 继承自 |
|---|
| 自定义事件 | SuperCustomEvent | 这是自定义 | |
类 : MyElement, (中文(简体) ), my-element
超级级
| 名称 | 模块 | 软件包 |
|---|
| 超级类 | ./固定/-TEST/包装/我的元素.js | |
混合
| 名称 | 模块 | 软件包 |
|---|
| 本地化Mixin | | 狮子 |
| 混音 | ./固定/-TEST/包装/我的元素.js | |
字段
| 名称 | 隐私 | 类型 | 默认 | 说明 | 继承自 |
|---|
| 道具1 | 公开 | | | | |
| 道具2 | 公开 | | | | |
| 道具3 | 公开 | boolean | true | | |
方法
| 名称 | 隐私 | 说明 | 参数 | 返回时 | 继承自 |
|---|
| 实例方法 | 公开 | 这里对方法的一些描述 | e: Event, a: string | | |
| 超级分类方法 | 公开 | | | | 超级类 |
活动
| 名称 | 类型 | 说明 | 继承自 |
|---|
| 我的活动 | Event | | |
| 自定义事件 | SuperCustomEvent | 这是自定义 | 超级类 |
属性
CSS 属性
槽数
私人 API
字段
| 名称 | 隐私 | 类型 | 默认 | 说明 | 继承自 |
|---|
| o | 私营 | string | 'bar' | 描述到这里 | |
| 混合配置 | 受保护 | number | 1 | | 混音 |
组合 : MyMixin4
参数
| 名称 | 类型 | 默认 | 说明 |
|---|
| 宽度 | * | | 这是描述 |
| o | string | | 说明在这里 |
组合 : Mixin
参数
私人 API
字段
| 名称 | 隐私 | 类型 | 默认 | 说明 | 继承自 |
|---|
| 混合配置 | 受保护 | number | 1 | | |
变量
| 名称 | 说明 | 类型 |
|---|
| 变量导出 | 这是 var 导出 | boolean |
| 字符串变量导出 | 这是一个字符串 var 导出 | string |
职能
| 名称 | 说明 | 参数 | 返回时 |
|---|
| 函数导出 | 这是函数导出 | a: string, b: boolean | boolean |
出口
| 仁爱 | 名称 | 声明 | 模块 | 软件包 |
|---|
| 编 | 超级类 | 超级类 | ./固定/-TEST/包装/我的元素.js | |
| 自定义 | 我的元素 | 元素 | ./固定/-TEST/包装/我的元素.js | |
| 编 | 变量导出 | 变量导出 | ./固定/-TEST/包装/我的元素.js | |
| 编 | 字符串变量导出 | 字符串变量导出 | ./固定/-TEST/包装/我的元素.js | |
| 编 | 函数导出 | 函数导出 | ./固定/-TEST/包装/我的元素.js | |