Components 元素参考

Components 元素用于指定构成一个版本的插件的组件。

多个 Components 元素可用于标识插件的组件；每个 Components 元素可以标识一个或多个组件。Components 元素的平台和产品信息由 RuntimeRequirements 元素定义。

如果要将所有在 Components 元素中定义的组件都应用到相同的平台，则无需将 RuntimeRequirements 元素添加到每个单独的 ComponentEntry 元素中。

除了 RuntimeRequirements 元素，Components 元素还可以包含一个或多个以下元素

注： Components 元素只能有一个 RegistryEntries、SystemVariables 和 EnvironmentVariables 元素，但可以包含多个 ComponentEntry 元素。

以下内容概述了 Components 元素及其可以包含的任何元素之间的基本关系。 

<Components>
  <RuntimeRequirements ... />

  <RegistryEntries>
    <RegistryEntry ... />
  </RegistryEntries>

  <SystemVariables>
    <SystemVariable ... />
  </SystemVariables>

  <EnvironmentVariables>
    <EnvironmentVariable ... />
  </EnvironmentVariables>

  <ComponentEntry ... >
    <RuntimeRequirements ... />

    <AssemblyMappings>
      <AssemblyMapping ... />
      <AssemblyMappingFolder ... />
    </AssemblyMappings>

    <Commands ...>
      <Command ... />
    </Commands>
  </ComponentEntry>

  <ComponentEntry ... />
</Components>

ComponentEntry 元素（基于 AutoCAD 2013 的产品及更高版本、AutoCAD LT 2024 及更高版本）

ComponentEntry 元素是必需的，用于指定 Components 元素中各个组件的相关详细信息。

可以根据需要指定任意多个 ComponentEntry 元素。组件类型可以是以下文件格式之一：

文件格式 Windows Mac OS
AutoCAD AutoCAD LT AutoCAD AutoCAD LT
AutoLISP 源代码 (LSP) ✓ ✓ ✓ --
快速加载 AutoLISP (FAS) ✓ ✓ ✓ --
编译的 Visual LISP 工程 (VLX) ✓ ✓ -- --
ObjectARX (ARX/CRX) ✓ -- ✓ --
ObjectDBX (DBX) ✓ -- ✓ --
可扩展应用程序标记语言 (XAML) ✓ ✓ -- --
JavaScript (JS) ✓ -- -- --
托管或混合模式 .NET 部件 (DLL) ✓ -- -- --
局部自定义 (CUI/CUIx) ✓ ✓ -- --
工具选项板 (ATC) ✓ ✓ -- --
VBA 工程 (DVB) ✓ -- -- --

如果 LoadReasons 属性设置为 LoadOnCommandInvocation，则 ComponentEntry 元素可能包含 Commands 元素。

注： ComponentEntry 元素按其列出的顺序加载，但自下而上。因此，其他组件所依赖的任何文件都必须位于列表的下方。例如，如果 ObjectARX 模块依赖 ObjectDBX 模块，则 ObjectARX 模块需要在列表中显示在 ObjectDBX 模块的上方。

ComponentEntry 元素可以有以下任一附着属性：

属性

说明

AppName

对于 AutoLISP 是可选的；对于 ObjectARX 和 .NET 是必需的 - 组件的名称；与 ObjectARX API AcadAppInfo 类中的 AppName 相同。

AppDescription

组件说明；与 ObjectARX API AcadAppInfo 类中的 AppDescription 相同。

AppType

组件类型；替代自 ModuleName 属性中提供的文件扩展名派生的类型。

组件类型可以是以下类型之一：

  • .Net - 托管或混合 .NET 部件
  • Arx - ObjectARX
    注： 需要将 ARX 文件从捆绑包加载到 AutoCAD for Mac。
  • Atc – 工具选项板
  • Bundle - 捆绑包
  • Cui 或 CuiX – 局部自定义
  • Dbx – ObjectDBX
  • Dependency – 资源 DLL（不会加载到基于 AutoCAD 的产品中）
  • JavaScript – JavaScript
  • Lisp 或 CompiledLisp – AutoLISP/Visual LISP
  • Mnu – 菜单自定义
  • VBA – VBA 工程
  • Xaml – 用于实现上下文功能区选项卡的 XAML 文件

ModuleName

捆绑包中组件的相对路径；与 ObjectARX API AcadAppInfo 类中的 ModuleName 相同。

组件类型由文件的扩展名确定：

  • .atc – 工具选项板
  • .arx – ObjectARX
  • .cuix - 局部自定义
  • .dbx – ObjectDBX
  • .dll – Managed .NET 部件
  • .dvb – VBA 工程（基于 AutoCAD 2015 的产品及更高版本）
    注： DVB 文件要求先安装 VBA Enabler。加载后，用户需要先单击“启用宏”，才可以访问项目及其宏。
    重要： 当前，仅在启动时打开图形文件时才会加载 VBA 工程文件，这是通过将 STARTUP 系统变量设置为 0 或 1 来实现的。
  • .js – Javascript（基于 AutoCAD 2015 的产品及更高版本）
  • .lsp、.fas 或 .vlx – AutoLISP/Visual LISP
    注： 仅在 Windows 上支持 VLX 文件。
  • .xaml – 可扩展应用程序标记语言（基于 AutoCAD 2015 的产品及更高版本）
    注： 属性 XamlType 必须设置为“ContextualTabRule”

如果应用程序要处理多种语言，通过将 ModuleName 与区域设置代码组合在一起来指定特定组件的不同语言版本。请参见“支持的区域设置代码参考”，以获取支持的区域设置代码的完整列表。

注： 所有路径指定符皆为“/”和“\”，路径相对于根“.bundle”文件夹。

PerDocument

仅对于 AutoLISP - 当为“真”时，每个文档加载 AutoLISP 文件一次。默认值为“真”。

Loadreasons

可以指定多个值 - 使用 LoadReasons 定义组件的加载行为参数，除了 LoadOnCommandInvocation 参数。

默认情况下，如果 LoadReasons 未指定，则 LoadOnAutoCADStartup、LoadOnAppearance 和 LoadOnProxy 处于启用状态（设置为“True”）。如果需要禁用参数（设置为“False”），则 LoadReasons 元素必须与设置为“False”的参数一起指定。

默认情况下，LoadOnCommandInvocation 处于禁用状态，启用它时会禁用 LoadOnAutoCADStartup 和 LoadOnAppearance，除非明确启用。如果一个或多个命令定义为“Components”元素的一部分，则会隐式启用 LoadOnCommandInvocation。

有关“AcadAppInfo LoadReasons”的完整详细信息，请参见《ObjectARX 参考手册》。

有效参数值：

  • 真 - 参数已启用。
  • 假 - 参数已禁用。

可以使用下列参数：

  • LoadOnCommandInvocation。仅在调用自定义命令时加载。当使用此参数时，“Commands”元素必须包含在内。如果 LoadOnCommandInvocation 已启用，则 LoadOnAutoCADStartup 和 LoadOnAppearance 都假定为处于禁用状态，除非明确启用。仅适用于 AutoLISP、ObjectARX 和 .NET 文件。
    注： 出于启动性能的原因，请务必在组件定义命令时使用此选项。
  • LoadOnAutoCADStartup。在启动基于 AutoCAD 的产品时加载。如果已指定，则此参数优先于其他所有参数。建议仅当没有任何其他参数适用时才使用 LoadOnAutoCADStartup，尽可能将其禁用（将其设置为“False”）。如果 LoadOnAutoCADStartup 参数被省略，则其默认为处于启用状态（设置为“True”），除非 LoadOnCommandInvocation 已启用；在这种情况下，LoadOnAutoCADStartup 默认设置为“False”。仅适用于 VBA 工程、ObjectARX 和 .NET 文件。
  • LoadOnProxy。当检测到自定义图元的代理时加载。默认情况下，此参数处于启用状态，除非明确禁用（设置为“False”）。如果启用（设置为“True”），则 LoadOnAutoCADStartup 应处于禁用状态。仅适用于 ObjectDBX 文件。
  • LoadOnAppearance。当产品在其中一个“ApplicationPlugins”文件夹中检测到应用程序捆绑包时加载，从而支持在安装时即时加载而无需重新启动基于 AutoCAD 的产品。参数的行为方式与 LoadOnAutoCADStartup 相同，除了加载上下文与在产品运行的同时何时安装应用程序相关（例如，当通过 Autodesk App Store 网站安装时）。

XamlType

XAML 类型；当前唯一支持的值为“ContextualTabRule”，并且在将 XAML 文件指定给 ModuleName 属性时需要该值。使用 XAML 文件的应用程序文件应在包含 XAML 文件的 ComponentEntry 元素后列出。

“Commands”元素（基于 AutoCAD 2013 的产品及更高版本、AutoCAD LT 2024 及更高版本）

Commands 元素是可选的，除非已为e LoadReasons 属性启用 LoadOnCommandInvocation 参数。用于为 LoadOnCommandInvocation 指定注册哪些命令。

可以根据需要指定多个 Command 元素。

Commands 元素可以有以下附着属性：

属性

说明

GroupName

用于组织相关命令的名称。

“Command”元素（基于 AutoCAD 2013 的产品及更高版本、AutoCAD LT 2024 及更高版本）

指定每个命令的全局和本地名称。

Command 元素可以有以下任一附着属性：

属性

说明

Global

全局命令名。

Local

本地命令名。

通过将 Local 与区域设置代码组合在一起可以为多种语言定义命令。请参见“支持的区域设置代码参考”，以获取支持的区域设置代码的完整列表。

HelpTopic

在命令处于活动状态以及在按下 F1 键时打开的帮助主题。

注： 要显示帮助主题，必须将帮助文件指定给插件。使用 ApplicationPackage 元素下的 HelpFile 属性来指定插件的帮助文件位置。

StartupCommand

如果为“真”，则在启动时执行命令。

以下样例添加了在名为“ADSKCMDS”的组中定义的两个命令： 

<Commands GroupName="ADSKCMDS">
    <Command Global="HELLOWORLD" Local="ADSKHELLOWORLD"/>
    <Command Global="DRAWLINE" Local="ADSKDRAWLINE"/>
</Commands>

“AssemblyMappings”元素（基于 AutoCAD 2013 及更高版本的产品）

AssemblyMappings 元素是可选的，并可以包含一个或多个 AssemblyMapping 或 AssemblyMappingFolder 元素。AssemblyMapping 和 AssemblyMappingFolder 元素用于将部件文件和文件夹路径添加到内部列表，供 AutoCAD 用来解析在产品安装文件夹中未找到的部件。

“AssemblyMapping”元素（基于 AutoCAD 2013 及更高版本的产品）

属性

说明

Name

与部件关联且应加载的 ComponentEntry 的名称。

Path

捆绑包内部件的相对路径。

“AssemblyMappingFolder”元素（基于 AutoCAD 2022 的产品及更高版本）

属性

说明

Path

包内部件的相对路径。

以下样例添加了两个文件夹，其中包含组件所使用的部件： 

<AssemblyMappings>
    <AssemblyMappingFolder Path="./Content/Assemblies" />
    <AssemblyMappingFolder Path="./Content/MoreAssemblies" />
</AssemblyMappings>

“RegistryEntries”元素（基于 AutoCAD 2015 的产品及更高版本、AutoCAD LT 2024 及更高版本）

RegistryEntries 元素是可选的，并且可以包含一个或多个 RegistryEntry 元素。RegistryEntry 元素包含插件应该创建或修改的注册表项的定义。注册表项存储在 Windows 注册表中或 Mac 操作系统上的特性列表 (PLIST) 文件中。

注： 在 Windows 上，在“HKEY_CURRENT_USER\Software\Autodesk\AutoCAD\<版本>\ACAD-<产品>:<语言>”下创建注册表项。无法在其他位置中创建注册表项。可以在 Mac 操作系统上的 PLIST 文件中使用该等效位置。
RegistryEntry 元素

属性

说明

Name

要创建或修改的注册表项的名称。

Value

要指定给注册表项的值。

该值可以包括下列可选运算符前缀之一：+、-、& 和 |。

有关详细信息，请参见“变量值运算符前缀”部分。

注： 将值应用于注册表项后，不会保留运算符前缀。

Type

要分配给注册表项的数据类型。（可选）在修改现有的注册表项时。

有效值包括：

  • REG_SZ – 字符串；空终止
  • REG_EXPAND_SZ – 包含未展开环境变量的字符串，例如 %APPDATA%；空终止
  • REG_DWORD – 32 位无符号整数
  • REG_QWORD – 64 位有符号整数

如果运算符前缀用作注册表项值的一部分，则必须指定相应的数据类型。如果未使用相应的数据类型，则运算将被视作字符串运算。

Flags

可选，创建和修改标志。可以指定多个标志；使用管道符号分隔各个标志。

支持以下标志：

  • Create – 如果不存在，将创建注册表项。（默认行为）
  • Open – 每次加载插件时且仅当注册表项存在时，修改注册表项的值。
  • OpenOnce – 首次加载插件时且仅当注册表项存在时，修改注册表项的值。卸载并重新安装插件会导致注册表项的值再次发生更改。
注： 必须使用 Open 或 OpenOnce 标志来修改注册表项的值。

下面的样例将创建注册表项 MYREGKEY 并添加 STRING 和 NUMBER 值： 

<RegistryEntries>
    <RegistryEntry
        Key="MYREGKEY"
        Name="STRING"
        Value="Example"
        Type="REG_SZ"
    />

    <RegistryEntry
        Key="MYREGKEY"
        Name="NUMBER"
        Value="123"
        Type="REG_DWORD"
    />
</RegistryEntries>

“SystemVariables”元素（基于 AutoCAD 2015 的产品及更高版本、AutoCAD LT 2024 及更高版本）

SystemVariables 元素是可选的，并且可以包含一个或多个 SystemVariables 元素。SystemVariable 元素包含插件应创建或修改的系统变量的定义。

SystemVariable 元素

属性

说明

Name

要创建或修改的系统变量的名称。

Value

要指定给变量的值。

该值可以包括下列可选运算符前缀之一：+、-、& 和 |。

有关详细信息，请参见“变量值运算符前缀”部分。

注： 将值应用于变量后，不会保留运算符前缀。

PrimaryType

要分配给变量的数据类型。（可选）在修改现有系统变量时。

有效值包括：

  • Int16 – 16 位有符号整数
  • Int32 – 32 位整数
  • Real – 浮点或双精度数值
  • String – 单个或多个字符值

如果运算符前缀用作变量值的一部分，则必须指定相应的数据类型。如果未使用相应的数据类型，则运算将被视作字符串运算。

StorageType

变量值的存储位置；在保持不变时。（可选）在修改现有系统变量时。

有效值包括：

  • Database – 保留在创建变量的图形文件中
  • Profile – 保留为当前 AutoCAD 配置的一部分
  • Session – 不会在任务之间或在创建任务的图形中保留
  • User – 保留为 AutoCAD 的 FixedProfile 的一部分

Owner

可选，AcRX 服务名称。

用于使系统变量只读并且仅可通过使用 acrxRegisterService() 注册服务名称的应用程序进行修改。

Flags

可选，创建和修改标志。可以指定多个标志；使用管道符号分隔各个标志。

支持以下标志：

  • Create – 如果不存在，将创建变量。（默认行为）

  • Open – 每次加载插件时并且仅当变量存在时，修改变量的值。

  • OpenOnce – 首次加载插件时并且仅当变量存在时，修改变量的值。卸载并重新安装插件会导致变量的值再次发生更改。

  • SpacesAllowed – 允许在命令提示下按空格键。如果未指定，则按空格键与按 Enter 键的效果一样。

    注： 仅在 PrimaryType 属性设置为“String”时与“Create”标志结合使用。

  • DotIsEmpty - 允许通过为变量的值输入“.”（句点）来清除变量的值。

    注： 仅在 PrimaryType 属性设置为“String”时与“Create”标志结合使用。

  • NoUndo – 不会记录对变量的更改，并且无法使用 U 或 UNDO 命令放弃更改。

    注： 仅与“Create”标志结合使用。

  • Chatty – 触发反应器通知，即使在变量的值设置为当前值时也是如此。

    注： 仅与“Create”标志结合使用。
注： 必须使用 Open 或 OpenOnce 标志来修改变量的值。

以下样例创建了一个名为 MYVARIABLE 的系统变量： 

<SystemVariable
    Name="MYVARIABLE"
    PrimaryType="String"
    StorageType="User"
    Value="Example"
    Owner=""
    Flags="Create|DotIsEmpty|SpacesAllowed"
/>

以下样例在首次加载插件时，将 CURSORSIZE 系统变量的值更改为 100： 

<SystemVariable
    Name="CURSORSIZE"
    Value="100"
    Flags="OpenOnce"
/>

“EnvironmentVariables”元素（基于 AutoCAD 2015 的产品及更高版本、AutoCAD LT 2024 及更高版本）

EnvironmentVariables 元素是可选的，并且可以包含一个或多个 EnvironmentVariable 元素。EnvironmentVariable 元素包含插件应该创建或修改的环境变量的定义。环境变量存储在 Windows 注册表中或 Mac 操作系统上的特性列表 (PLIST) 文件中。

注： 环境变量的值始终存储为字符串，并且环境变量的名称区分大小写。
EnvironmentVariable 元素

属性

说明

Name

要创建或修改的环境变量的名称。

Value

要指定给变量的值。

该值可以包括下列可选运算符前缀之一：+、-、& 和 |。

有关详细信息，请参见“变量值运算符前缀”部分。

注： 将值应用于变量后，不会保留运算符前缀。

Type

可选，Value 表示的数据类型。

有效值包括：

  • Int16 – 16 位有符号整数
  • Int32 – 32 位有符号整数
  • Real – 浮点或双精度数值
  • String – 单个或多个字符值

如果运算符前缀用作变量值的一部分，则必须指定相应的数据类型。如果未使用相应的数据类型，则运算将被视作字符串运算。

Flags

可选，创建和修改标志。可以指定多个标志；使用管道符号分隔各个标志。

支持以下标志：

  • Create – 如果不存在，将创建变量。（默认行为）
  • Open – 每次加载插件时并且仅当变量存在时，修改变量的值。
  • OpenOnce – 首次加载插件时并且仅当变量存在时，修改变量的值。卸载并重新安装插件会导致变量的值再次发生更改。
注： 必须使用 Open 或 OpenOnce 标志来修改变量的值。

以下样例创建了两个名为 MYNUMVAR 和 MYSTRVAR 的环境变量： 

<EnvironmentVariables>
    <EnvironmentVariable
        Name="MYNUMVAR"
        Value="123"
    />

    <EnvironmentVariable
        Name="MYSTRVAR"
        Value="Example"
    />
</EnvironmentVariables>

变量值的运算符前缀

运算符前缀用于在加载插件后，修改变量的当前值。可以将下表中列出的运算符前缀之一添加到 RegistryEntry、SystemVariable 或 EnvironmentVariable 元素的“Value”属性。

前缀

说明

+（加号）

将值添加或附加到现有变量的值。

Int16、Int32、Real：将值添加到现有变量的值。

String：将值附加到现有变量的值。

-（连字符）

从现有变量的值减去或移除一个值。

Int16、Int32、Real：从现有变量的值减去值。

String：从现有变量的值移除值。

&（与符号）

变量现有值的按位“与”运算；仅支持数值。

|（管道符号）

变量现有值的按位“或”运算；仅支持数值。

注： 如果变量的值应以某个运算符前缀开头，则在运算符之前添加一个反斜杠。例如，如果变量的值为 +radius，则输入值 \+radius。

下面的对象将始终启用 END、MID、CEN、NOD、QUA 和 INT 运行对象捕捉，并使所有其他对象捕捉保持原样： 

<SystemVariable
    Name="OSMODE"
    Value="|63"
    Flags="Open"
/>
父主题： PackageContents.xml 格式参考

相关概念

相关参考